Reveal an element the first time it enters the viewport

A reveal that waits for the reader is a visibility question, and the platform now answers visibility questions with IntersectionObserver instead of with arithmetic inside a scroll handler. The effect itself belongs to CSS; the script only has to say when a block has earned its visible state, and to stop asking about it afterwards.

<section class="panel" data-reveal>
  <h2>Fetch and error handling</h2>
  <p>A failed request and a failed status need different answers.</p>
</section>

<section class="panel" data-reveal>
  <h2>Deployment</h2>
  <p>The same artifact serves preview and production.</p>
</section>

.js-reveal [data-reveal] {
  opacity: 0;
  transform: translate3d(0, 1.5rem, 0);
  transition: opacity 400ms ease-out, transform 400ms ease-out;
}

.js-reveal [data-reveal].is-revealed {
  opacity: 1;
  transform: none;
}

@media (prefers-reduced-motion: reduce) {
  .js-reveal [data-reveal],
  .js-reveal [data-reveal].is-revealed {
    opacity: 1;
    transform: none;
    transition: none;
  }
}

// Everything that hides content sits behind this class, so a page whose script
// never runs simply shows its sections.
document.documentElement.classList.add('js-reveal');

const revealTargets = document.querySelectorAll('[data-reveal]');

function reveal(target, obs) {
  target.classList.add('is-revealed');
  if (obs) {
    obs.unobserve(target);   // first entry only: nothing left to report
  }
}

if (typeof IntersectionObserver !== 'function') {
  for (const target of revealTargets) {
    reveal(target, null);    // no observer means no waiting, not no content
  }
} else {
  const observer = new IntersectionObserver((entries, obs) => {
    for (const entry of entries) {
      if (!entry.isIntersecting) {
        continue;            // this entry is an exit, not an arrival
      }
      reveal(entry.target, obs);
    }
  }, { threshold: 0.25 });

  for (const target of revealTargets) {
    observer.observe(target);
  }
}

Explanation

The transition lives in CSS and the decision lives in the observer, which is the division that makes this cheap. threshold: 0.25 asks for a quarter of each section’s own area to be inside the viewport before the callback delivers anything, so the reveal lands while the block is genuinely being read rather than the moment its first row of pixels appears. Entries arrive in batches, and a batch can contain both arrivals and departures, because the observer reports transitions in both directions; that is why the loop tests entry.isIntersecting before doing anything, and why a reveal written directly against “the callback fired” animates at the wrong time on the way up. unobserve then removes just that element from the observer’s list, so the visible state is written once and the remaining sections keep being watched.

translate3d is used instead of a plain translateY because a reveal is a movement that happens while the page is already scrolling, and the third argument pushes the animated element onto its own compositing layer where the browser can move it without repainting its neighbours. The duration is short and the distance is small for the same reason: a long slide reads as lag when the reader is in motion. The reduced-motion block resolves the whole mechanism to a static state by overriding both the hidden and revealed rules, so the content is simply there, with no transition for the preference to shorten.

The interesting boundary is what happens when this script does not run, and the class gate is the answer to it. Hiding content in the stylesheet alone is the single worst failure mode of scroll reveals: blocked script, disabled JavaScript, a throwing earlier module, or a race between the stylesheet and the bundle all leave the reader with blank space where the page’s body should be. Gating the hidden rule behind a class that the reveal script itself adds means the failure state is a plain, fully visible page; the cost is that those sections can paint for one frame before the class lands, which is a far better outcome than content that never arrives. If that flash matters, the same class can be added by an earlier declaration in the document head, at the price of a blocking script, and that trade is worth making deliberately rather than by accident. The second boundary is geometry: a threshold is a fraction of the element, so a section taller than the viewport can never reach a quarter visible on a phone, and the fix is a smaller threshold or a sentinel element, not more script.

Next steps

A reveal answers when a block becomes decorative-visible. The same observer shape solves a heavier problem when the answer decides a network request, which is what the image example does with a margin band in place of a threshold, and the pairing of one observer plus one delegated listener is what keeps both patterns working after content is added to the page.