@cparkerwebm/webmonterey 1.0.0

package/src/includes/webmonterey/animations/animations.css

@@ -0,0 +1,347 @@
+/*
+ * Web animations — no dependencies, and no JavaScript beyond one small observer.
+ *
+ * Three things live here:
+ *
+ *   1. ONE-SHOT ANIMATIONS (.webm-animate) — play once on render, for things that APPEAR: a
+ *      banner, a dialog, a toast. Pure CSS. Works with JavaScript off.
+ *
+ *   2. SCROLL REVEAL (.webm-reveal) — a drop-in class that reveals content as it enters the
+ *      viewport. Needs observe.ts, imported once from base.astro. See that section for why it
+ *      is not the CSS-only `animation-timeline: view()` it used to be.
+ *
+ *   3. NAMED KEYFRAMES (webm-fade-in, webm-slide-in-up, …) that any component can reference
+ *      from its own @layer webm.components.core block. This is how the consent banner, a
+ *      mobile menu, a modal, or a toast animates — reuse these rather than writing new ones.
+ *
+ * BOTH systems respect prefers-reduced-motion, by opposite routes. Section 1 only ever
+ * applies inside `no-preference`, so there is nothing to undo. Section 2 must start from a
+ * hidden state, so it instead forces every element visible under `reduce` — in CSS here and
+ * in observe.ts, which is why both halves are required.
+ *
+ * IMPORTED BY src/styles/global.css, alongside the other stylesheets — nothing to wire up.
+ * It used to be opt-in, documented as an `@import` the client had to add to custom/_index.css,
+ * and the failure mode for forgetting was silent: no error, no warning, build still exits 0,
+ * every rule below simply absent from the output. That is not a choice worth offering.
+ *
+ * Section 2 needs the companion script (observe.ts, imported once from base.astro). Section 1
+ * and the keyframes are pure CSS and work with JavaScript off.
+ */
+
+@layer webm.utilities {
+  /* ======================================================================
+   * 1. ONE-SHOT ANIMATIONS
+   *
+   * Play once on render. For elements that appear — a banner, a dialog, a
+   * dropdown — rather than elements scrolled past.
+   *
+   *   <div class="webm-animate" data-animate="slide-in-up">…</div>
+   *   <div class="webm-animate" data-animate="fade-in" data-speed="slow">…</div>
+   * ==================================================================== */
+
+  @media (prefers-reduced-motion: no-preference) {
+    .webm-animate {
+      animation-duration: var(--webm-animate-duration, var(--webm-duration-normal));
+      animation-timing-function: var(--webm-animate-ease, var(--webm-ease-out));
+      animation-fill-mode: both;
+    }
+
+    .webm-animate:where([data-animate='fade-in']) {
+      animation-name: webm-fade-in;
+    }
+    .webm-animate:where([data-animate='fade-out']) {
+      animation-name: webm-fade-out;
+    }
+
+    .webm-animate:where([data-animate='slide-in-up']) {
+      animation-name: webm-fade-in, webm-slide-in-up;
+    }
+    .webm-animate:where([data-animate='slide-in-down']) {
+      animation-name: webm-fade-in, webm-slide-in-down;
+    }
+    .webm-animate:where([data-animate='slide-in-left']) {
+      animation-name: webm-fade-in, webm-slide-in-left;
+    }
+    .webm-animate:where([data-animate='slide-in-right']) {
+      animation-name: webm-fade-in, webm-slide-in-right;
+    }
+
+    .webm-animate:where([data-animate='slide-out-up']) {
+      animation-name: webm-fade-out, webm-slide-out-up;
+    }
+    .webm-animate:where([data-animate='slide-out-down']) {
+      animation-name: webm-fade-out, webm-slide-out-down;
+    }
+
+    .webm-animate:where([data-animate='scale-in']) {
+      animation-name: webm-fade-in, webm-scale-in;
+    }
+    .webm-animate:where([data-animate='scale-out']) {
+      animation-name: webm-fade-out, webm-scale-out;
+    }
+
+    /* Speed. Overrides the token default above. */
+    .webm-animate:where([data-speed='fast']) {
+      --webm-animate-duration: var(--webm-duration-fast);
+    }
+    .webm-animate:where([data-speed='slow']) {
+      --webm-animate-duration: var(--webm-duration-slow);
+    }
+    .webm-animate:where([data-speed='slower']) {
+      --webm-animate-duration: var(--webm-duration-slower);
+    }
+
+    /* A little overshoot, for things that should feel physical. */
+    .webm-animate:where([data-ease='spring']) {
+      --webm-animate-ease: var(--webm-ease-spring);
+    }
+  }
+
+  /* ======================================================================
+   * 2. SCROLL REVEAL
+   *
+   * Driven by IntersectionObserver (observe.ts), which does nothing but add
+   * `data-reveal-visible` once the element enters the viewport. Everything
+   * below — distance, duration, easing, the reduced-motion and print
+   * overrides — stays here in CSS.
+   *
+   * This replaced an `animation-timeline: view()` implementation. That version
+   * was Chromium-only: Firefox keeps scroll-driven animations behind a flag,
+   * so `.webm-reveal` was a silent no-op for a large share of visitors.
+   *
+   *   <div class="webm-reveal" data-reveal="up">…</div>
+   *   <div class="webm-reveal" data-reveal="blur" data-reveal-delay="150">…</div>
+   *   <ul data-reveal-stagger="80"> <li class="webm-reveal" data-reveal="up">…
+   *
+   * THE `html.js` GUARD IS LOAD-BEARING. Every hidden state is scoped to it,
+   * and the class is set by an inline script in base.astro's <head>. With
+   * JavaScript off — or if the bundle simply fails to load — nothing is ever
+   * hidden, so content and crawlers never face a permanent opacity: 0. That
+   * failure mode is the whole reason a JS reveal needs a guard and a pure-CSS
+   * one does not.
+   * ==================================================================== */
+
+  html.js .webm-reveal {
+    /*
+     * `translate` and `scale` as their own properties, not `transform` — the same choice the
+     * keyframes below make, and for the same reason: a direction and a scale can be driven
+     * independently without one clobbering the other.
+     */
+    transition-property: opacity, translate, scale, filter;
+    transition-duration: var(--webm-reveal-duration);
+    transition-timing-function: var(--webm-reveal-ease);
+    transition-delay: var(--webm-reveal-delay);
+  }
+
+  /* Hidden until the observer marks it visible. */
+  html.js .webm-reveal:not([data-reveal-visible]) {
+    opacity: 0;
+  }
+
+  html.js .webm-reveal:where([data-reveal='up']):not([data-reveal-visible]) {
+    translate: 0 var(--webm-reveal-distance);
+  }
+  html.js .webm-reveal:where([data-reveal='down']):not([data-reveal-visible]) {
+    translate: 0 calc(var(--webm-reveal-distance) * -1);
+  }
+
+  /* `left` enters travelling leftwards, so it starts out to the right. */
+  html.js .webm-reveal:where([data-reveal='left']):not([data-reveal-visible]) {
+    translate: calc(var(--webm-reveal-distance) * 2) 0;
+  }
+  html.js .webm-reveal:where([data-reveal='right']):not([data-reveal-visible]) {
+    translate: calc(var(--webm-reveal-distance) * -2) 0;
+  }
+
+  html.js .webm-reveal:where([data-reveal='scale']):not([data-reveal-visible]) {
+    scale: 0.94;
+  }
+  html.js .webm-reveal:where([data-reveal='zoom-out']):not([data-reveal-visible]) {
+    scale: 1.06;
+  }
+  html.js .webm-reveal:where([data-reveal='blur']):not([data-reveal-visible]) {
+    filter: blur(var(--webm-reveal-blur));
+  }
+
+  /*
+   * The visible state is written out rather than left to inherited defaults, so an element
+   * revealing inside an already-transformed parent lands where you expect.
+   */
+  html.js .webm-reveal[data-reveal-visible] {
+    opacity: 1;
+    translate: none;
+    scale: none;
+    filter: none;
+  }
+
+  /*
+   * Stagger. `--webm-reveal-index` is set per child by observe.ts; the step comes from
+   * `data-reveal-stagger` on the container, defaulting to --webm-reveal-stagger-step.
+   *
+   * This is the part the old scroll-driven version could not express. Its delays came from
+   * `animation-range-start`, which meant a fixed four-step ladder — `animation-delay` is
+   * time-based and has no effect on a scroll-driven animation at all. A transition has no
+   * such restriction, so the step is real milliseconds and the count is unbounded.
+   */
+  /*
+   * DESCENDANT, NOT `>`. This was `> .webm-reveal`, which paired with observe.ts numbering only
+   * direct children: markup that nests the revealing element one level deeper - <ul> <li>
+   * <button>, or a card wrapper that holds its border still - got no index and no delay, so the
+   * group arrived at once and looked like a stagger that had never been applied. Both halves had
+   * to change together; an index nothing reads is as useless as a rule with no index.
+   *
+   * Nesting still resolves without extra specificity, because neither value is inherited from
+   * this rule: --webm-reveal-stagger-step is an inline property on each container, so an inner
+   * one shadows an outer one for its subtree, and --webm-reveal-index is written per element by
+   * observe.ts, which numbers each element under its NEAREST container.
+   */
+  html.js [data-reveal-stagger] .webm-reveal {
+    --webm-reveal-delay: calc(var(--webm-reveal-stagger-step) * var(--webm-reveal-index, 0));
+  }
+
+  /* Convenience aliases, kept so the documented `data-delay` ladder still works. */
+  html.js .webm-reveal:where([data-delay='1']) {
+    --webm-reveal-delay: calc(var(--webm-reveal-stagger-step) * 1);
+  }
+  html.js .webm-reveal:where([data-delay='2']) {
+    --webm-reveal-delay: calc(var(--webm-reveal-stagger-step) * 2);
+  }
+  html.js .webm-reveal:where([data-delay='3']) {
+    --webm-reveal-delay: calc(var(--webm-reveal-stagger-step) * 3);
+  }
+  html.js .webm-reveal:where([data-delay='4']) {
+    --webm-reveal-delay: calc(var(--webm-reveal-stagger-step) * 4);
+  }
+
+  /*
+   * Reduced motion. Only half the fix — observe.ts also reveals every element immediately, so
+   * a motion-sensitive visitor never has to scroll to make content appear. Both halves are
+   * required; neutralising the CSS alone would leave content gated on scroll position.
+   */
+  @media (prefers-reduced-motion: reduce) {
+    html.js .webm-reveal,
+    html.js .webm-reveal:not([data-reveal-visible]) {
+      opacity: 1 !important;
+      translate: none !important;
+      scale: none !important;
+      filter: none !important;
+      transition: none !important;
+    }
+  }
+
+  /*
+   * Print. Only elements scrolled past carry `data-reveal-visible`, so printing a long page
+   * would otherwise emit blank space wherever the reader had not been. Same for save-as-PDF
+   * and full-page screenshots.
+   */
+  @media print {
+    html.js .webm-reveal,
+    html.js .webm-reveal:not([data-reveal-visible]) {
+      opacity: 1 !important;
+      translate: none !important;
+      scale: none !important;
+      filter: none !important;
+      transition: none !important;
+    }
+  }
+
+  /* ======================================================================
+   * 3. KEYFRAMES
+   *
+   * Deliberately outside the reduced-motion guard: they are inert until
+   * something references them, and components reference them directly.
+   * Movement uses `translate`/`scale` rather than `transform` so two
+   * animations can drive position and scale independently without one
+   * clobbering the other.
+   * ==================================================================== */
+
+  @keyframes webm-fade-in {
+    from {
+      opacity: 0;
+    }
+    to {
+      opacity: 1;
+    }
+  }
+
+  @keyframes webm-fade-out {
+    from {
+      opacity: 1;
+    }
+    to {
+      opacity: 0;
+    }
+  }
+
+  @keyframes webm-slide-in-up {
+    from {
+      translate: 0 var(--webm-slide-distance, var(--webm-space-lg));
+    }
+    to {
+      translate: 0 0;
+    }
+  }
+
+  @keyframes webm-slide-in-down {
+    from {
+      translate: 0 calc(var(--webm-slide-distance, var(--webm-space-lg)) * -1);
+    }
+    to {
+      translate: 0 0;
+    }
+  }
+
+  @keyframes webm-slide-in-left {
+    from {
+      translate: calc(var(--webm-slide-distance, var(--webm-space-lg)) * -1) 0;
+    }
+    to {
+      translate: 0 0;
+    }
+  }
+
+  @keyframes webm-slide-in-right {
+    from {
+      translate: var(--webm-slide-distance, var(--webm-space-lg)) 0;
+    }
+    to {
+      translate: 0 0;
+    }
+  }
+
+  @keyframes webm-slide-out-up {
+    from {
+      translate: 0 0;
+    }
+    to {
+      translate: 0 calc(var(--webm-slide-distance, var(--webm-space-lg)) * -1);
+    }
+  }
+
+  @keyframes webm-slide-out-down {
+    from {
+      translate: 0 0;
+    }
+    to {
+      translate: 0 var(--webm-slide-distance, var(--webm-space-lg));
+    }
+  }
+
+  @keyframes webm-scale-in {
+    from {
+      scale: 0.94;
+    }
+    to {
+      scale: 1;
+    }
+  }
+
+  @keyframes webm-scale-out {
+    from {
+      scale: 1;
+    }
+    to {
+      scale: 0.94;
+    }
+  }
+}

package/src/includes/webmonterey/animations/observe.test.ts

@@ -0,0 +1,88 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { ownedReveals } from './observe.ts';
+
+/*
+ * A tree of plain objects standing in for elements, and a lookup that models what the real code
+ * does: `element.parentElement?.closest('[data-reveal-stagger]')` — walk up from the PARENT and
+ * take the first stagger container found.
+ *
+ * These test the ownership rule, which is the logic that was wrong. They do not exercise
+ * querySelectorAll or closest themselves; those are the browser's, and there is no DOM here.
+ */
+interface Node {
+  id: string;
+  parent?: Node;
+  stagger?: true;
+}
+
+const ownerOf = (element: Node): Node | null => {
+  for (let p = element.parent; p; p = p.parent) if (p.stagger) return p;
+  return null;
+};
+
+/** Everything below `root`, in document order, as querySelectorAll would return it. */
+const descendants = (root: Node, all: Node[]): Node[] =>
+  all.filter((n) => {
+    for (let p = n.parent; p; p = p.parent) if (p === root) return true;
+    return false;
+  });
+
+const owned = (container: Node, all: Node[]) =>
+  ownedReveals(container, descendants(container, all), ownerOf).map((n) => n.id);
+
+test('direct children are numbered in order - the case that already worked', () => {
+  const ul: Node = { id: 'ul', stagger: true };
+  const all = [ul, { id: 'a', parent: ul }, { id: 'b', parent: ul }, { id: 'c', parent: ul }];
+  assert.deepEqual(owned(ul, all), ['a', 'b', 'c']);
+});
+
+/*
+ * THE REGRESSION. <ul> -> <li> -> <button class="webm-reveal">: the reveal is a grandchild, the
+ * old `container.children` walk found nothing, every item took a delay of zero, and the group
+ * arrived at once looking exactly like a stagger nobody applied. Hit on three client sites.
+ */
+test('a reveal nested a level deeper is owned, not skipped', () => {
+  const ul: Node = { id: 'ul', stagger: true };
+  const li1: Node = { id: 'li1', parent: ul };
+  const li2: Node = { id: 'li2', parent: ul };
+  const all = [ul, li1, li2, { id: 'btn1', parent: li1 }, { id: 'btn2', parent: li2 }];
+  assert.deepEqual(
+    owned(ul, all),
+    ['li1', 'li2', 'btn1', 'btn2'].filter((id) => id.length > 0),
+  );
+});
+
+test('an element belongs to its NEAREST container, so a nested grid is not numbered twice', () => {
+  const section: Node = { id: 'section', stagger: true };
+  const grid: Node = { id: 'grid', parent: section, stagger: true };
+  const all = [
+    section,
+    grid,
+    { id: 'intro', parent: section },
+    { id: 'card1', parent: grid },
+    { id: 'card2', parent: grid },
+  ];
+  // The outer owns the intro and the grid itself - not the grid's cards.
+  assert.deepEqual(owned(section, all), ['grid', 'intro']);
+  // And the inner numbers its own from zero.
+  assert.deepEqual(owned(grid, all), ['card1', 'card2']);
+});
+
+/*
+ * Why the lookup starts at the PARENT rather than the element. With `closest()` from the element,
+ * a node that is both a reveal and a nested container resolves to ITSELF, matches no outer
+ * container, and is numbered by nothing at all.
+ */
+test('a container that is also a reveal is owned by the container above it', () => {
+  const section: Node = { id: 'section', stagger: true };
+  const grid: Node = { id: 'grid', parent: section, stagger: true };
+  const all = [section, grid, { id: 'card', parent: grid }];
+  assert.deepEqual(owned(section, all), ['grid']);
+  assert.deepEqual(owned(grid, all), ['card']);
+});
+
+test('a container that owns nothing yields nothing rather than throwing', () => {
+  const empty: Node = { id: 'empty', stagger: true };
+  assert.deepEqual(owned(empty, [empty]), []);
+});

package/src/includes/webmonterey/animations/observe.ts

@@ -0,0 +1,209 @@
+/*
+ * Scroll reveal — the JavaScript half of `.webm-reveal`.
+ *
+ * WHY THIS EXISTS RATHER THAN `animation-timeline: view()`. The CSS-only version of this
+ * feature is Chromium-only: Firefox keeps scroll-driven animations behind a flag and the
+ * `animation-trigger` syntax that would actually fit a reveal-on-enter API is Chromium-only
+ * too. In every other browser the `@supports` guard made the whole feature a silent no-op.
+ * IntersectionObserver is the mechanism, not a fallback for one.
+ *
+ * The split of duties is deliberate and worth keeping: this file ONLY toggles the
+ * `data-reveal-visible` attribute and copies two numbers into custom properties. Every
+ * distance, duration, easing and reduced-motion rule lives in animations.css, so a client can
+ * retheme the motion without reading a line of TypeScript.
+ *
+ * The one-shot `.webm-animate` system is untouched by any of this — it is pure CSS, plays on
+ * render rather than on scroll, and needs no JavaScript at all.
+ *
+ * Imported once from base.astro. Astro dedupes bundled <script> across component instances,
+ * so importing it elsewhere is harmless but pointless.
+ */
+
+const SELECTOR = '.webm-reveal';
+const STAGGER_SELECTOR = '[data-reveal-stagger]';
+
+/** Elements already wired, so re-running init never double-observes. */
+const registered = new WeakSet<Element>();
+
+let observer: IntersectionObserver | null = null;
+
+function prefersReducedMotion(): boolean {
+  return window.matchMedia('(prefers-reduced-motion: reduce)').matches;
+}
+
+function reveal(element: Element): void {
+  element.setAttribute('data-reveal-visible', '');
+}
+
+/**
+ * Reveal on a LATER frame, not this one.
+ *
+ * A transition only starts if the browser has already rendered the property's "before" value.
+ * A bundled module script runs before first paint, so revealing an element synchronously here
+ * means its `opacity: 0` is never painted — the element goes straight to its final state and
+ * nothing animates. The result is indistinguishable from an ordinary page load, which is
+ * exactly what an above-the-fold hero looked like before this existed.
+ *
+ * TWO frames, not one. A single requestAnimationFrame callback can still be folded into the
+ * same style recalculation, which reintroduces the bug intermittently — the kind that looks
+ * fixed on the machine you tested it on. The second frame guarantees a paint in between.
+ *
+ * Only the already-in-view path needs this. Anything revealed from the observer callback is
+ * long past first paint by definition.
+ */
+function revealAfterPaint(element: Element): void {
+  requestAnimationFrame(() => requestAnimationFrame(() => reveal(element)));
+}
+
+/**
+ * Copy `data-reveal-delay` / `-duration` onto the element as custom properties.
+ *
+ * Custom properties rather than an inline `transition` string: the CSS keeps ownership of
+ * easing and, more importantly, of the reduced-motion and print overrides. An inline
+ * shorthand would out-specify both.
+ */
+function applyTiming(element: HTMLElement): void {
+  const delay = element.dataset.revealDelay;
+  if (delay) element.style.setProperty('--webm-reveal-delay', `${parseInt(delay, 10) || 0}ms`);
+
+  const duration = element.dataset.revealDuration;
+  if (duration) {
+    element.style.setProperty('--webm-reveal-duration', `${parseInt(duration, 10) || 0}ms`);
+  }
+}
+
+/**
+ * The reveals a stagger container OWNS, in document order.
+ *
+ * Generic and taking its own lookup so it is a pure function of its arguments: the ownership
+ * rule is the whole logic here, and it is the part that can be reasoned about and tested
+ * without a DOM. `applyStagger` supplies the real elements.
+ *
+ * OWNERSHIP, NOT DESCENT. Every `.webm-reveal` below a container is a candidate; it belongs to
+ * the NEAREST stagger container above it. That is what lets a staggered grid sit inside a
+ * staggered section without the grid's cards being numbered twice — the section owns the grid,
+ * the grid owns its cards, and each numbering starts at zero.
+ */
+export function ownedReveals<T>(
+  container: T,
+  candidates: readonly T[],
+  ownerOf: (element: T) => T | null,
+): T[] {
+  return candidates.filter((element) => ownerOf(element) === container);
+}
+
+/**
+ * Index every reveal a stagger container owns, so the CSS can compute each delay.
+ *
+ * This is what the old `data-delay="1".."4"` ladder could not do: the step is a real
+ * millisecond value and the count is unbounded, so a grid of nine cards staggers as readily
+ * as a row of three.
+ *
+ * DESCENDANTS, NOT `children`. This walked `container.children` and so numbered only DIRECT
+ * children. Real markup nests the revealing element a level deeper more often than not — a
+ * `<ul>` whose `<li>` wraps the button that actually moves, or a card wrapper holding a border
+ * still while its inside animates. In those layouts the walk found nothing, set no index, and
+ * every item took a delay of zero: the group arrived in one piece, looking precisely like a
+ * stagger nobody had applied. Nothing threw, because nothing failed — there was simply nothing
+ * to do. Three client sites hit it and each worked around it by hand-writing delays off a map
+ * index. The CSS half of this had the same bug, as `> .webm-reveal`; changing either alone
+ * fixes nothing, because an index nothing reads is as useless as a rule with no index.
+ *
+ * `parentElement?.closest(...)` rather than `closest(...)` STARTS THE SEARCH ABOVE the element.
+ * An element that is both a reveal and a nested stagger container would otherwise resolve to
+ * itself, and so be numbered by nothing — the outer container would skip it as belonging to
+ * someone else. Starting a level up, it belongs to the outer container and still owns its own
+ * subtree, which is the behavior the markup implies.
+ */
+function applyStagger(root: ParentNode): void {
+  root.querySelectorAll<HTMLElement>(STAGGER_SELECTOR).forEach((container) => {
+    const step = container.dataset.revealStagger;
+    if (step) {
+      container.style.setProperty('--webm-reveal-stagger-step', `${parseInt(step, 10) || 0}ms`);
+    }
+
+    const candidates = Array.from(container.querySelectorAll<HTMLElement>(SELECTOR));
+    ownedReveals(
+      container,
+      candidates,
+      (element) => element.parentElement?.closest<HTMLElement>(STAGGER_SELECTOR) ?? null,
+    ).forEach((element, index) => {
+      element.style.setProperty('--webm-reveal-index', String(index));
+    });
+  });
+}
+
+function getObserver(): IntersectionObserver {
+  if (observer) return observer;
+
+  observer = new IntersectionObserver(
+    (entries) => {
+      for (const entry of entries) {
+        if (!entry.isIntersecting) continue;
+
+        reveal(entry.target);
+
+        // `data-reveal-once="false"` opts into re-animating on every entry.
+        const once = (entry.target as HTMLElement).dataset.revealOnce !== 'false';
+        if (once) observer?.unobserve(entry.target);
+      }
+    },
+    {
+      /*
+       * Fire slightly before the element is fully on screen, and require only a sliver of it
+       * to be visible — otherwise a section taller than the viewport waits for its bottom
+       * edge, which never arrives.
+       */
+      rootMargin: '0px 0px -10% 0px',
+      threshold: 0.05,
+    },
+  );
+
+  return observer;
+}
+
+/**
+ * Wire up every `.webm-reveal` in `root` that is not already wired.
+ *
+ * Safe to call repeatedly — on first load, after a view transition, and after injecting
+ * markup dynamically.
+ */
+export function initAnimations(root: ParentNode = document): void {
+  const elements = Array.from(root.querySelectorAll<HTMLElement>(SELECTOR));
+  if (elements.length === 0) return;
+
+  applyStagger(root);
+
+  /*
+   * Reduced motion: reveal everything at once and never observe. Neutralising the CSS is only
+   * half the fix — without this, a motion-sensitive visitor would still depend on scroll
+   * position for content to appear, because the CSS override only kills the movement.
+   */
+  if (prefersReducedMotion()) {
+    elements.forEach(reveal);
+    return;
+  }
+
+  const io = getObserver();
+
+  for (const element of elements) {
+    if (registered.has(element)) continue;
+    registered.add(element);
+    applyTiming(element);
+
+    // Anything already on screen at load must not wait for a scroll that may never come.
+    const rect = element.getBoundingClientRect();
+    if (rect.top < window.innerHeight && rect.bottom > 0) {
+      revealAfterPaint(element);
+      continue;
+    }
+
+    io.observe(element);
+  }
+}
+
+/** Tear down between view transitions so the observer never holds stale nodes. */
+export function destroyAnimations(): void {
+  observer?.disconnect();
+  observer = null;
+}