@digithings-ai/ui 0.0.0-stage → 0.1.0

package/src/components/diagrams/ArchitectureTour.tsx

@@ -0,0 +1,912 @@
+"use client";
+/**
+ * Architecture tour — the same container diagram, walked, and then swapped.
+ *
+ * The owner, after seeing the first cut: "i still want to have that slide where
+ * i do the guided box rings or actually the element that's selected or talked
+ * about should just glow and then i still want that that swipe to the digi
+ * things so we start with the diagram for the off-the-shelf solution and then we
+ * swipe over to the digi things solution the guided camera while it'd be much
+ * cooler just to guide the camera and make the elements glow it's currently
+ * broken if you could make it work".
+ *
+ * So the tour takes PAIRS of sides — `[{ rented spec + steps }, { owned spec +
+ * steps }]` — and runs them as ONE scroll timeline:
+ *
+ *   - the first side's steps hold the frame still and light its boxes (a glow,
+ *     not a ring, with a spotlight that drops everything outside the box back
+ *     into the page);
+ *   - the last fraction of the final step runs the SWAP. Each side is ONE group
+ *     — its diagram and its own step list — and the groups swap by sliding, not
+ *     by fading: the rented group (diagram left, list right) leaves to the LEFT
+ *     as a unit, then the owned group arrives from the RIGHT (list left and
+ *     bottom-aligned, diagram right). The rail does not cross the page on its
+ *     own; it travels with its diagram. The owner asked for exactly this: "the
+ *     diagram slides to the left, the rented text also goes left with it. And
+ *     then from the right side of the screen appears the owned text with its
+ *     diagram … they don't continue one another. One replaces the other so that
+ *     you should see them slide on and off the screen." So neither group is ever
+ *     faded — no opacity anywhere on the swap — and the two never share the
+ *     frame: the exit runs over the first half of the window and the entrance
+ *     over the second;
+ *   - the second side's steps then drive the camera as well as the glow.
+ *
+ * The camera follows whichever side is active and can only ever zoom IN on
+ * a step's lit boxes (a step lighting the whole diagram computes ~1 and
+ * switches off), so a walk never zooms in and then has to pull back out —
+ * which is what made the earlier version read as empty space and clipping.
+ *
+ * HOW IT KNOWS WHERE ANYTHING IS. It does not. mermaid's layout is its own, so
+ * the tour measures the rendered SVG after the fact: each service is emitted as
+ * `<g id="arch-…-service-<id>">` and each boundary as `<g id="arch-…-group-<id>">`,
+ * which makes every box addressable by id without touching mermaid internals or
+ * hard-coding coordinates. Measurements are taken once each SVG appears (a
+ * MutationObserver on the stage) and again on resize, always while that pane's
+ * camera is untransformed so the numbers are in unscaled pane space.
+ *
+ * MOTION BUDGET. One rAF-throttled passive scroll listener writing custom
+ * properties (`--arch-out` / `--arch-in` on the grid; `--arch-p` on the pin);
+ * React state changes only when the coarse step index changes. The wheel is
+ * never captured: a flick skips through with the page, and once scroll rests
+ * the camera eases onto the narrated boxes (`scroll-glide`). Reduced motion
+ * gets the static treatment, and so does anything narrower than the breakpoint
+ * at which the pinned layout fits.
+ */
+
+import { useEffect, useMemo, useRef, useState, type ReactNode } from "react";
+
+import {
+  REST_GLIDE_MS,
+  REST_QUIET_MS,
+  applyRestBlend,
+  restBlendAmount,
+  shouldStartRestGlide,
+} from "../../motion/scroll-glide";
+import { ArchitectureDiagram, type ArchSpec } from "./ArchitectureDiagram";
+import {
+  CAM_IDENTITY,
+  camTransform,
+  fitCamera,
+  glideAmount,
+  lerpCam,
+  mixSpot,
+  unionSpot,
+  walkCursor,
+  type CamFrame,
+} from "./tour-camera";
+
+export interface TourStep {
+  id: string;
+  label: string;
+  line: string;
+  /** Box ids this step is about. Empty means "the whole diagram". */
+  ids: string[];
+}
+
+export interface TourSide {
+  spec: ArchSpec;
+  /**
+   * Per-step specs for a side that redraws as it is walked (the morph: the
+   * same topology with labels swapped step by step). Entry i renders at that
+   * side's local step i; missing entries and the static fallback use `spec`,
+   * which should be the side's end state. Box ids must be stable across
+   * entries so measurement, glow and camera keep working.
+   */
+  specs?: ArchSpec[];
+  steps: TourStep[];
+  /** Short marker for the rail, e.g. "rented" / "owned". */
+  tag?: string;
+  caption?: string;
+  /**
+   * Which edge this side's step column shows its progress rule on, and with it
+   * the step text alignment: "start" (default, rule left) or "end" (rule right,
+   * text right-aligned to it). Per side, so the rented column can sit right
+   * while the owned one keeps the left.
+   */
+  rail?: "start" | "end";
+  /** Extra content under the step column, bottom-aligned with the frame. */
+  aside?: ReactNode;
+}
+
+export type TourVariant = "static" | "highlight" | "camera";
+
+export interface ArchitectureTourProps {
+  /** One side is a plain walk; two add the swipe between them. */
+  sides: TourSide[];
+  variant?: TourVariant;
+  /** Scroll spent per step, in viewport heights. The track is this times the step count. */
+  vhPerStep?: number;
+  /**
+   * Controlled step index into the flattened walk. When omitted the tour
+   * owns its step internally. Either way every step change is reported
+   * through `onStepChange`, so a parent can key side content (an invoice,
+   * a caption) off the walk without reaching into the tour.
+   */
+  step?: number;
+  onStepChange?: (index: number) => void;
+  /** Reports the resolved treatment ("static" under reduced motion or narrow
+      viewports); a parent uses it to pick the matching fallback content. */
+  onModeChange?: (mode: TourVariant) => void;
+  /**
+   * Held inside the pin, above the diagram, so a title/lede stays on screen for
+   * the whole walk instead of scrolling away when the walk begins.
+   */
+  header?: ReactNode;
+  className?: string;
+  /**
+   * How much of the stage a step's boxes should fill, and the zoom cap.
+   * Defaults keep a whole-graph beat at identity. A denser drawing needs a
+   * higher fill before the camera will travel between clusters.
+   */
+  cameraFill?: number;
+  cameraMaxScale?: number;
+  /** Zoom a wide short row into view. Default fits the whole cluster. */
+  cameraCover?: boolean;
+  /**
+   * Stretch each drawing's gutters to its frame's shape in the pinned view, so
+   * a graph fills the box instead of letterboxing. Static mode sizes the frame
+   * from the drawing, so it is left alone there.
+   */
+  fitFrame?: boolean;
+}
+
+interface Box {
+  x: number;
+  y: number;
+  w: number;
+  h: number;
+}
+
+interface SideMeasure {
+  boxes: Record<string, Box>;
+  w: number;
+  h: number;
+}
+
+const NO_MOTION = "(prefers-reduced-motion: reduce)";
+// The pinned treatment runs at every width. Narrow viewports keep the same
+// single-stage scroll walk but collapse it to one column (diagrams.css), so the
+// two stacks share one pane and the scroll swaps them.
+const PIN_MEDIA = "(min-width: 1px)";
+
+const clamp01 = (n: number): number => Math.max(0, Math.min(1, n));
+const smooth = (n: number): number => {
+  const t = clamp01(n);
+  return t * t * (3 - 2 * t);
+};
+
+function sameMeasure(prev: SideMeasure[], next: SideMeasure[]): boolean {
+  if (prev.length !== next.length) return false;
+  return next.every((side, si) => {
+    const before = prev[si];
+    if (!before || Math.abs(before.w - side.w) > 0.5 || Math.abs(before.h - side.h) > 0.5) {
+      return false;
+    }
+    const ids = Object.keys(side.boxes);
+    if (ids.length !== Object.keys(before.boxes).length) return false;
+    return ids.every((id) => {
+      const a = before.boxes[id];
+      const b = side.boxes[id];
+      return (
+        a !== undefined &&
+        b !== undefined &&
+        Math.abs(a.x - b.x) < 0.5 &&
+        Math.abs(a.y - b.y) < 0.5 &&
+        Math.abs(a.w - b.w) < 0.5 &&
+        Math.abs(a.h - b.h) < 0.5
+      );
+    });
+  });
+}
+
+/** Where the pin parks: its own sticky `top`, so a consumer that moves the pin
+    in CSS moves the scroll math with it. */
+function pinOffset(pin: HTMLElement): number {
+  const top = Number.parseFloat(getComputedStyle(pin).top);
+  return Number.isFinite(top) ? top : 88;
+}
+
+function usePrefersReducedMotion(): boolean {
+  const [reduced, setReduced] = useState(false);
+  useEffect(() => {
+    if (typeof matchMedia !== "function") return;
+    const mq = matchMedia(NO_MOTION);
+    const sync = () => setReduced(mq.matches);
+    sync();
+    mq.addEventListener("change", sync);
+    return () => mq.removeEventListener("change", sync);
+  }, []);
+  return reduced;
+}
+
+/** True while the viewport is wide enough for the pinned two-column layout. */
+function usePinned(): boolean {
+  const [pinned, setPinned] = useState(false);
+  useEffect(() => {
+    if (typeof matchMedia !== "function") return;
+    const mq = matchMedia(PIN_MEDIA);
+    const sync = () => setPinned(mq.matches);
+    sync();
+    mq.addEventListener("change", sync);
+    return () => mq.removeEventListener("change", sync);
+  }, []);
+  return pinned;
+}
+
+export function ArchitectureTour({
+  sides,
+  variant = "static",
+  vhPerStep = 0.62,
+  header,
+  className,
+  step: controlledStep,
+  onStepChange,
+  onModeChange,
+  cameraFill = 0.34,
+  cameraMaxScale = 1.45,
+  cameraCover = false,
+  fitFrame = false,
+}: ArchitectureTourProps) {
+  const reduced = usePrefersReducedMotion();
+  const wide = usePinned();
+  // The animated treatments need a pin to exist; without one they read as the
+  // static treatment rather than pinning to nothing.
+  const mode: TourVariant = reduced || !wide ? "static" : variant;
+
+  const rootRef = useRef<HTMLDivElement | null>(null);
+  const trackRef = useRef<HTMLDivElement | null>(null);
+  const pinRef = useRef<HTMLDivElement | null>(null);
+  const gridRef = useRef<HTMLDivElement | null>(null);
+  const paneRefs = useRef<Array<HTMLDivElement | null>>([]);
+  const cameraRefs = useRef<Array<HTMLDivElement | null>>([]);
+  const spotRefs = useRef<Array<HTMLSpanElement | null>>([]);
+  const onStepChangeRef = useRef(onStepChange);
+  onStepChangeRef.current = onStepChange;
+  const controlledRef = useRef(controlledStep);
+  controlledRef.current = controlledStep;
+  /** Last index reported to the parent. -1 so the opening beat still fires. */
+  const reportedStep = useRef(-1);
+  /** Set by the scroll effect so a late-arriving SVG can resize the track. */
+  const remeasureRef = useRef<() => void>(() => {});
+
+  const [measures, setMeasures] = useState<SideMeasure[]>([]);
+  const [internalStep, setInternalStep] = useState(0);
+  const step = controlledStep ?? internalStep;
+
+  /* Report the walk outward: the flattened step (fires on mount too, so a
+     parent keying content off the walk starts in sync) and the resolved
+     treatment (so the parent can match the static fallback). Both are
+     parent-owned setters or undefined — no feedback loop either way. */
+  useEffect(() => {
+    onStepChange?.(step);
+  }, [step, onStepChange]);
+  useEffect(() => {
+    onModeChange?.(mode);
+  }, [mode, onModeChange]);
+
+  const flat = useMemo(
+    () => sides.flatMap((side, si) => side.steps.map((entry) => ({ ...entry, side: si }))),
+    [sides],
+  );
+  const count = flat.length;
+  const flatRef = useRef(flat);
+  flatRef.current = flat;
+  const measuresRef = useRef(measures);
+  measuresRef.current = measures;
+  /** The flat index at which the swipe has finished and the last side is live. */
+  const swapAt = sides.length > 1 ? sides[0].steps.length : count;
+
+  /* ── measure each rendered diagram ─────────────────────────────────── */
+
+  useEffect(() => {
+    // The media queries resolve after mount, so the FIRST render is always the
+    // static branch — there is no stage to measure yet. Depending on `mode` is
+    // what re-runs this once the pinned layout exists; without it the effect
+    // returned early forever and nothing was ever measured.
+    if (mode === "static") return;
+    const pin = pinRef.current;
+    if (!pin) return;
+
+    /** Returns true once every side has at least one measured box. */
+    const measure = (): boolean => {
+      // Snapshots are in unscaled pane space. Clear the camera for the read,
+      // then put it back in the same turn so a ResizeObserver does not see a
+      // size change and re-enter.
+      // The camera eases its transform, so clearing it alone leaves the zoom
+      // on screen and every box reads scaled. Drop the transition for the read.
+      const saved = cameraRefs.current.map((camera) => camera?.style.transform ?? "");
+      cameraRefs.current.forEach((camera) => {
+        if (!camera) return;
+        camera.style.transition = "none";
+        camera.style.transform = "";
+      });
+      let done = true;
+      const next = sides.map((side, si) => {
+        const empty: SideMeasure = { boxes: {}, w: 0, h: 0 };
+        const pane = paneRefs.current[si];
+        if (!pane) {
+          done = false;
+          return empty;
+        }
+        const svg = pane.querySelector("svg");
+        if (!svg) {
+          done = false;
+          return empty;
+        }
+        const origin = svg.getBoundingClientRect();
+        if (origin.width === 0) {
+          done = false;
+          return empty;
+        }
+        const ids = [
+          ...side.spec.services.map((s) => s.id),
+          ...(side.spec.groups ?? []).map((g) => g.id),
+        ];
+        const boxes: Record<string, Box> = {};
+        for (const id of ids) {
+          const el = svg.querySelector(`[id$="-service-${id}"], [id$="-group-${id}"]`);
+          if (!el) continue;
+          const r = el.getBoundingClientRect();
+          if (r.width === 0) continue;
+          boxes[id] = {
+            x: r.left - origin.left,
+            y: r.top - origin.top,
+            w: r.width,
+            h: r.height,
+          };
+        }
+        if (Object.keys(boxes).length === 0) done = false;
+        return { boxes, w: origin.width, h: origin.height };
+      });
+      cameraRefs.current.forEach((camera, si) => {
+        if (!camera) return;
+        camera.style.transform = saved[si] ?? "";
+        void camera.offsetWidth;
+        camera.style.transition = "";
+      });
+      setMeasures((prev) => (sameMeasure(prev, next) ? prev : next));
+      return done;
+    };
+
+    // mermaid is a lazy ~2.9MB chunk that draws after this mounts, and there is
+    // no event to await — the figure only flips to `data-state="diagram"` when
+    // it is done. So rather than trust a MutationObserver to catch the draw, poll
+    // until every pane has measurable boxes and then stop, with a hard ceiling so
+    // a diagram that never renders cannot spin forever.
+    let timer = 0;
+    const tick = (): void => {
+      if (measure() && timer) {
+        window.clearInterval(timer);
+        timer = 0;
+      }
+    };
+    const frame = requestAnimationFrame(tick);
+    timer = window.setInterval(tick, 250);
+    const ceiling = window.setTimeout(() => {
+      if (timer) window.clearInterval(timer);
+      timer = 0;
+    }, 12000);
+
+    const onResize = (): void => {
+      measure();
+    };
+    window.addEventListener("resize", onResize);
+
+    // A browser/page ZOOM (ctrl +/-, pinch, or a devicePixelRatio change) scales
+    // every CSS-pixel measurement but does NOT reliably raise a `resize` event, so
+    // the box coordinates kept describing the pre-zoom layout while the camera read
+    // `stage.clientWidth` live — the two frames no longer agreed and the focus
+    // drifted or clipped. A ResizeObserver on each pane's SVG fires whenever that
+    // element's own box changes, which is exactly what a zoom does, so the snapshot
+    // is retaken and the camera recomputes against matching geometry.
+    const panes = paneRefs.current.filter(Boolean) as HTMLDivElement[];
+    let observer: ResizeObserver | null = null;
+    if (typeof ResizeObserver !== "undefined") {
+      observer = new ResizeObserver(() => {
+        measure();
+        // The SVG resizing also means the pin/track geometry moved, so anchor the
+        // scroll to the same step as well as retaking the box snapshot.
+        remeasureRef.current?.();
+      });
+      for (const pane of panes) {
+        const svg = pane.querySelector("svg");
+        if (svg) observer.observe(svg);
+      }
+    }
+
+    // A fitted drawing (`fitFrame`) re-lays its gutters once the frame is
+    // measured: every box moves but the SVG element keeps its size, so the
+    // ResizeObserver above never fires. The viewBox is what changes.
+    const relayout = new MutationObserver(() => {
+      measure();
+      remeasureRef.current?.();
+    });
+    for (const pane of panes) {
+      relayout.observe(pane, { subtree: true, attributes: true, attributeFilter: ["viewBox"] });
+    }
+
+    // devicePixelRatio is the other half: a zoom can change it (and a bare
+    // resolution change can change it without moving any element), and there is
+    // no event for it, so watch the media query that describes it.
+    const dpr = window.devicePixelRatio || 1;
+    const dprQuery =
+      typeof window.matchMedia === "function"
+        ? window.matchMedia(`(resolution: ${dpr}dppx)`)
+        : null;
+    const onDpr = (): void => {
+      measure();
+      remeasureRef.current?.();
+    };
+    dprQuery?.addEventListener("change", onDpr);
+
+    return () => {
+      cancelAnimationFrame(frame);
+      if (timer) window.clearInterval(timer);
+      window.clearTimeout(ceiling);
+      window.removeEventListener("resize", onResize);
+      observer?.disconnect();
+      relayout.disconnect();
+      dprQuery?.removeEventListener("change", onDpr);
+    };
+  }, [sides, mode]);
+
+  /* ── the scroll binding ────────────────────────────────────────────── */
+
+  useEffect(() => {
+    if (mode === "static") return;
+    const track = trackRef.current;
+    const pin = pinRef.current;
+    if (!track || !pin) return;
+
+    let distance = 0;
+    let frame = 0;
+
+    const measureTrack = () => {
+      /* Cap the scroll budget: at extreme zoom-out a viewport-relative track
+         grows without bound and the stack section reads as an endless page. */
+      distance = Math.min(Math.round(window.innerHeight * vhPerStep * Math.max(1, count)), 3000);
+      /* Cap the whole section too: the pin's own content grows with the
+         viewport, so capping only the scroll distance still leaves an
+         unbounded section at extreme zoom-out. */
+      track.style.height = `${Math.max(pin.offsetHeight, Math.min(pin.offsetHeight + distance, 4800))}px`;
+    };
+
+    const boxesFor = (entry: { side: number; ids: string[] } | undefined, si: number): Box[] => {
+      if (!entry || entry.side !== si || entry.ids.length === 0) return [];
+      const m = measuresRef.current[si];
+      if (!m) return [];
+      return entry.ids.map((id) => m.boxes[id]).filter((box): box is Box => Boolean(box));
+    };
+
+    const frameFor = (entry: { side: number; ids: string[] } | undefined, si: number): CamFrame => {
+      const camera = cameraRefs.current[si];
+      const m = measuresRef.current[si];
+      if (!camera || !m?.w || !m.h) return CAM_IDENTITY;
+      if (!entry || entry.side !== si || entry.ids.length === 0) return CAM_IDENTITY;
+      const stage = camera.closest(".arch-tour__stage") as HTMLElement | null;
+      const stageW = stage?.clientWidth ?? 0;
+      const stageH = stage?.clientHeight ?? 0;
+      if (!stageW || !stageH) return CAM_IDENTITY;
+      const svg = paneRefs.current[si]?.querySelector("svg");
+      const liveW = svg?.clientWidth ?? 0;
+      let scale = 1;
+      let contentW = m.w;
+      let contentH = m.h;
+      if (svg && liveW > 0 && Math.abs(liveW - m.w) > 0.5) {
+        scale = liveW / m.w;
+        contentW = m.w * scale;
+        contentH = m.h * scale;
+      }
+      const picked = boxesFor(entry, si).map((b) => ({
+        x: b.x * scale,
+        y: b.y * scale,
+        w: b.w * scale,
+        h: b.h * scale,
+      }));
+      return fitCamera({
+        boxes: picked,
+        stageW,
+        stageH,
+        contentW,
+        contentH,
+        fill: cameraFill,
+        maxScale: cameraMaxScale,
+        cover: cameraCover,
+      });
+    };
+
+    /* The camera follows scroll, not the integer step. It rests on the
+       narrated boxes, then glides to the next ones across the tail of the
+       beat so the move and the text rail arrive together. `restBlend` eases
+       that glide back to the parked boxes after the page stops; it stays 0
+       while the reader is skipping, so the picture never lags the wheel.
+       A controlled parent (the why band) only hears the integer index —
+       without this report the rail and the glow stay on the opening beat
+       forever. */
+    let restBlend = 0;
+    const pose = (progress: number) => {
+      const cursor = walkCursor(progress, count);
+      const glide = applyRestBlend(glideAmount(cursor.frac), restBlend);
+      const steps = flatRef.current;
+      const current = steps[cursor.index];
+      const upcoming = steps[Math.min(count - 1, cursor.index + 1)];
+      cameraRefs.current.forEach((camera, si) => {
+        if (!camera) return;
+        const frame = lerpCam(frameFor(current, si), frameFor(upcoming, si), glide);
+        camera.style.transform = camTransform(frame);
+        const spot = spotRefs.current[si];
+        if (!spot) return;
+        const mixed = mixSpot(
+          unionSpot(
+            boxesFor(current, si),
+            measuresRef.current[si]?.w ?? 0,
+            measuresRef.current[si]?.h ?? 0,
+          ),
+          unionSpot(
+            boxesFor(upcoming, si),
+            measuresRef.current[si]?.w ?? 0,
+            measuresRef.current[si]?.h ?? 0,
+          ),
+          glide,
+        );
+        if (!mixed || mixed.opacity < 0.02) {
+          spot.style.opacity = "0";
+          return;
+        }
+        spot.style.opacity = mixed.opacity.toFixed(3);
+        spot.style.transform = `translate(${mixed.rect.left}px, ${mixed.rect.top}px)`;
+        spot.style.width = `${mixed.rect.width}px`;
+        spot.style.height = `${mixed.rect.height}px`;
+      });
+    };
+
+    const report = (index: number) => {
+      if (reportedStep.current === index) return;
+      reportedStep.current = index;
+      if (controlledRef.current === undefined) setInternalStep(index);
+      onStepChangeRef.current?.(index);
+    };
+
+    /**
+     * Re-measure the track WITHOUT moving the reader.
+     *
+     * The track's height depends on `window.innerHeight`, so a viewport or zoom
+     * change resizes it — and because the track sits at a fixed document offset,
+     * its top edge and every step's scroll position move with it. Left alone that
+     * lands the reader on a different step of the walk, which is what "it moves
+     * around as I zoom" was. So read the current step first, resize, then put the
+     * scroll position back on the same step.
+     */
+    const remeasure = () => {
+      const pinEl = pinRef.current;
+      const trackEl = trackRef.current;
+      if (!pinEl || !trackEl) {
+        measureTrack();
+        update();
+        return;
+      }
+      // The fraction of the walk the reader is currently on, before the
+      // resize — UNCLAMPED. At or past either edge the walk does not hold
+      // the pin, so the reader is just scrolling the page and must not be
+      // moved at all. That bail is what stops the scroll-jump-on-load: on a
+      // fresh load the pin sits far below the viewport (fraction 0) while
+      // late layout (fonts, mermaid draw, the chat iframe) fires the pane
+      // observers, and without it every one of those callbacks scrollTo'd
+      // the tour start.
+      const beforeAvail = Math.max(1, trackEl.offsetHeight - pinEl.offsetHeight);
+      const beforeTop = trackEl.getBoundingClientRect().top + window.scrollY;
+      const beforeRaw = (pinOffset(pin) - beforeTop) / beforeAvail;
+
+      measureTrack();
+
+      if (!(beforeRaw > 0 && beforeRaw < 1)) {
+        update();
+        return;
+      }
+      const beforeP = clamp01(beforeRaw);
+
+      // After the resize, put the scroll back so the same fraction sits under the
+      // pin. Only do it while the walk actually holds the pin — outside it the
+      // reader is just scrolling the page and must not be moved at all.
+      const afterAvail = Math.max(1, trackEl.offsetHeight - pinEl.offsetHeight);
+      const afterTop = trackEl.getBoundingClientRect().top + window.scrollY;
+      const target = afterTop - pinOffset(pin) + beforeP * afterAvail;
+      // A zoom keeps the anchor scrollY ratio, so the browser may already be at
+      // the right place; only nudge when the step would actually change.
+      if (Math.abs(window.scrollY - target) > 2) {
+        window.scrollTo({ top: Math.max(0, Math.round(target)), behavior: "auto" });
+      }
+      update();
+    };
+
+    const update = () => {
+      // The pinned scroll IS the track minus the pin, so progress is measured
+      // against that rather than against the requested budget — otherwise the
+      // pin releases with the walk only partly finished and the last steps are
+      // crammed into the tail.
+      const avail = Math.max(1, track.offsetHeight - pin.offsetHeight);
+      const p = clamp01((pinOffset(pin) - track.getBoundingClientRect().top) / avail);
+      pin.style.setProperty("--arch-p", p.toFixed(4));
+
+      // Each rail's own progress bar would otherwise read the whole-walk value:
+      // on the rented rail that fills only its share then the side slides away,
+      // and on the owned rail it is already full before that side starts. So
+      // each side gets a local 0→1 across its own steps.
+      let seen = 0;
+      for (let si = 0; si < sides.length; si += 1) {
+        const total = sides[si].steps.length;
+        const local = clamp01((p * count - seen) / Math.max(1, total));
+        pin.style.setProperty(`--arch-r${si}`, local.toFixed(4));
+        seen += total;
+      }
+
+      // The swipe lives in the tail of the last step of the earlier side, so the
+      // reader finishes that walk before the page changes diagram under them.
+      const v = p * count;
+      const index = Math.min(count - 1, Math.floor(v));
+      const frac = clamp01(v - index);
+      let swap = 0;
+      if (sides.length > 1) {
+        if (index >= swapAt) swap = 1;
+        else if (index === swapAt - 1) swap = smooth((frac - 0.35) / 0.65);
+      }
+      const grid = gridRef.current;
+      if (grid) {
+        // "get rid of the old, in with the new": on a wide two-column stage the
+        // rented group leaves over the first half of the window and the owned
+        // group arrives over the second, so the two are never in the frame
+        // together. On a narrow single-pane stage that hand-off would leave a
+        // blank frame at p=0.5, so the same swap value drives a crossfade.
+        const narrow = window.innerWidth < 1024;
+        grid.style.setProperty("--arch-out", clamp01(narrow ? swap : swap * 2).toFixed(4));
+        grid.style.setProperty("--arch-in", clamp01(narrow ? swap : swap * 2 - 1).toFixed(4));
+      }
+
+      pose(p);
+      report(index);
+    };
+
+    /* Skip-through / rest. Scroll position is never rewritten and the wheel
+       is never captured, so a flick crosses the walk with the page. While
+       scrollY is changing, `data-skipping` drops the time-based CSS follows
+       (they lag a fast skip). After the page has been still, the camera
+       eases onto the narrated boxes — unless that glide is already committed,
+       in which case the frame stays where the reader left it. */
+    let restRaf = 0;
+    let restTimer = 0;
+    let resting = false;
+    let lastScrollY = window.scrollY;
+    let lastMoveAt = performance.now();
+
+    const setSkipping = (on: boolean) => {
+      const root = rootRef.current;
+      if (!root) return;
+      if (on) root.setAttribute("data-skipping", "");
+      else root.removeAttribute("data-skipping");
+    };
+
+    const cancelRest = () => {
+      resting = false;
+      restBlend = 0;
+      if (restRaf) cancelAnimationFrame(restRaf);
+      restRaf = 0;
+    };
+
+    const beginRest = () => {
+      if (resting) return;
+      /* Nothing to glide while the pin is off screen: update() reads
+         getBoundingClientRect twice and writes transforms every frame, and a
+         reader who stopped at the top of the page is nowhere near the tour. */
+      const pinBox = pin.getBoundingClientRect();
+      if (pinBox.bottom < 0 || pinBox.top > window.innerHeight) {
+        setSkipping(false);
+        return;
+      }
+      const availNow = Math.max(1, track.offsetHeight - pin.offsetHeight);
+      const progress = clamp01((pinOffset(pin) - track.getBoundingClientRect().top) / availNow);
+      const live = glideAmount(walkCursor(progress, count).frac);
+      if (!shouldStartRestGlide({ quietMs: performance.now() - lastMoveAt, liveGlide: live })) {
+        setSkipping(false);
+        return;
+      }
+      const start = performance.now();
+      resting = true;
+      const step = (now: number) => {
+        if (!resting) return;
+        restBlend = restBlendAmount(now - start, REST_GLIDE_MS);
+        update();
+        if (restBlend < 1) {
+          restRaf = requestAnimationFrame(step);
+          return;
+        }
+        resting = false;
+        restRaf = 0;
+        setSkipping(false);
+      };
+      restRaf = requestAnimationFrame(step);
+    };
+
+    const noteMove = () => {
+      const y = window.scrollY;
+      if (Math.abs(y - lastScrollY) < 0.5) return;
+      lastScrollY = y;
+      lastMoveAt = performance.now();
+      if (resting || restBlend !== 0) cancelRest();
+      setSkipping(true);
+      window.clearTimeout(restTimer);
+      restTimer = window.setTimeout(beginRest, REST_QUIET_MS);
+    };
+
+    const onScroll = () => {
+      noteMove();
+      cancelAnimationFrame(frame);
+      frame = requestAnimationFrame(update);
+    };
+    const onResize = () => {
+      remeasure();
+    };
+
+    remeasureRef.current = remeasure;
+    measureTrack();
+    update();
+    /* The sides and camera ease their transforms, so a fresh mount would
+       otherwise tween from the CSS defaults to the first pose — a remount
+       (a parent swapping content by `key`) slid the old side across the new
+       one. Motion switches on only once that pose has painted. */
+    let settle = requestAnimationFrame(() => {
+      settle = requestAnimationFrame(() => rootRef.current?.setAttribute("data-settled", ""));
+    });
+    window.addEventListener("scroll", onScroll, { passive: true });
+    window.addEventListener("resize", onResize);
+
+    return () => {
+      resting = false;
+      cancelAnimationFrame(frame);
+      cancelAnimationFrame(settle);
+      cancelAnimationFrame(restRaf);
+      window.clearTimeout(restTimer);
+      window.removeEventListener("scroll", onScroll);
+      window.removeEventListener("resize", onResize);
+      rootRef.current?.removeAttribute("data-skipping");
+      track.style.height = "";
+    };
+  }, [mode, count, swapAt, sides.length, vhPerStep, cameraFill, cameraMaxScale, cameraCover]);
+
+  // The diagrams arrive after mermaid draws, so the pin is taller than it was
+  // when the track was first measured — remeasure once the boxes land.
+  useEffect(() => {
+    if (measures.length === 0) return;
+    remeasureRef.current();
+  }, [measures]);
+
+  /* ── the camera ────────────────────────────────────────────────────── */
+
+  const active = flat[Math.min(step, count - 1)];
+  const activeSide = active?.side ?? 0;
+  const activeIds = mode === "static" ? [] : (active?.ids ?? []);
+
+  /* ── render ────────────────────────────────────────────────────────── */
+
+  if (mode === "static") {
+    return (
+      <div className={`arch-tour${className ? ` ${className}` : ""}`} data-variant="static">
+        {header ? <div className="arch-tour__head">{header}</div> : null}
+        {sides.map((side, si) => (
+          <div className="arch-tour__static" key={si}>
+            {side.tag ? (
+              <span className="arch-tour__tag" data-tag={side.tag}>
+                {side.tag}
+              </span>
+            ) : null}
+            <ArchitectureDiagram spec={side.spec} caption={side.caption} />
+            <ol className="arch-tour__rail">
+              {side.steps.map((entry, index) => (
+                <li className="arch-tour__step" key={entry.id}>
+                  <span className="arch-tour__index">{String(index + 1).padStart(2, "0")}</span>
+                  <span className="arch-tour__label">{entry.label}</span>
+                  <span className="arch-tour__line">{entry.line}</span>
+                </li>
+              ))}
+            </ol>
+            {side.aside ? <div className="arch-tour__aside">{side.aside}</div> : null}
+          </div>
+        ))}
+      </div>
+    );
+  }
+
+  return (
+    <div
+      ref={rootRef}
+      className={`arch-tour${className ? ` ${className}` : ""}`}
+      data-variant={mode}
+      /* The walked side, so CSS can light it bright white and subdue the
+         other (static fallback omits it — both sides read full bright). */
+      data-active-side={activeSide}
+    >
+      <div className="arch-tour__track" ref={trackRef}>
+        <div className="arch-tour__pin" ref={pinRef}>
+          {header ? <div className="arch-tour__head">{header}</div> : null}
+          <div className="arch-tour__grid" ref={gridRef}>
+            {sides.map((side, si) => {
+              const base = sides.slice(0, si).reduce((n, s) => n + s.steps.length, 0);
+              /* The side's local step, clamped: ahead of its range it rests on
+                 its first frame (the morph waits as the provider copy), past
+                 it on its last (the provider rests full-lit for comparison). */
+              const local = Math.max(0, Math.min(side.steps.length - 1, step - base));
+              const effSpec = side.specs?.[local] ?? side.spec;
+              const mod =
+                sides.length > 1
+                  ? si === 0
+                    ? " arch-tour__side--leaving"
+                    : " arch-tour__side--entering"
+                  : "";
+              return (
+                <div
+                  className={`arch-tour__side${mod}`}
+                  key={si}
+                  data-rail={side.rail ?? "start"}
+                  data-active={si === activeSide}
+                >
+                  <div className="arch-tour__frame">
+                    <div className="arch-tour__stage">
+                      <div
+                        className="arch-tour__pane"
+                        ref={(el) => {
+                          paneRefs.current[si] = el;
+                        }}
+                      >
+                        <div
+                          className="arch-tour__camera"
+                          ref={(el) => {
+                            cameraRefs.current[si] = el;
+                          }}
+                        >
+                          <ArchitectureDiagram
+                            spec={effSpec}
+                            lit={si === activeSide ? activeIds : undefined}
+                            fit={fitFrame}
+                          />
+                          {/* One spotlight, positioned from the scroll pose. A second
+                              spot would stack the 9999px dim and black out the frame. */}
+                          <span
+                            className="arch-tour__spot"
+                            aria-hidden="true"
+                            ref={(el) => {
+                              spotRefs.current[si] = el;
+                            }}
+                          />
+                        </div>
+                      </div>
+                    </div>
+                  </div>
+
+                  {side.tag ? (
+                    <span className="arch-tour__side-tag" data-tag={side.tag}>
+                      {side.tag}
+                    </span>
+                  ) : null}
+                  <ol className="arch-tour__rail">
+                    {side.steps.map((entry, index) => {
+                      const on = base + index === step;
+                      return (
+                        <li className={`arch-tour__step${on ? " on" : ""}`} key={entry.id}>
+                          <span className="arch-tour__index">
+                            {String(index + 1).padStart(2, "0")}
+                          </span>
+                          <span className="arch-tour__label">{entry.label}</span>
+                          <span className="arch-tour__line">{entry.line}</span>
+                        </li>
+                      );
+                    })}
+                  </ol>
+                  {side.aside ? <div className="arch-tour__aside">{side.aside}</div> : null}
+                </div>
+              );
+            })}
+          </div>
+        </div>
+      </div>
+    </div>
+  );
+}