trykeyline 0.0.0-stage → 0.1.1

package/plugins/keyline/skills/keyline/glass/motion/assets/motion-presets.ts

@@ -0,0 +1,210 @@
+/**
+ * Motion presets — every spring and tween in the system, with the
+ * reduced-motion substitutes.
+ *
+ * Two vocabularies appear here on purpose:
+ *   bounce + duration          — a designer's controls; predictable arrival
+ *   stiffness + damping + mass — needed when the RELATIONSHIP between two
+ *                                springs is the effect (see GROW / CROSS)
+ *
+ * The one rule that applies to all of them: opacity never springs. Position
+ * wants physics, opacity wants a curve. A spring on opacity overshoots past
+ * its clamp and hitches on the way back — a visible flicker at the tail of
+ * every fade.
+ */
+
+/* ── Shared element re-targeting ─────────────────────────────────────────
+   A highlight or tooltip sliding to a new item. bounce is near the floor of
+   "perceptibly springy" on purpose: this is a thing MOVING, not a thing
+   ARRIVING. Bounce implies a moment of settling, and a highlight that
+   settles at every stop draws attention to itself instead of to the item
+   it's marking. */
+export const SLIDE = {
+  type: "spring",
+  bounce: 0.2,
+  duration: 0.4,
+  opacity: { duration: 0.16, ease: "easeOut" },
+} as const;
+
+/* ── The one playful moment ──────────────────────────────────────────────
+   Cards rising out of a folder on hover. 40% more bounce and 25% more
+   duration than anything else in the system. That it's the ONLY such moment
+   is why it works: against a baseline of restraint, one exuberant
+   interaction reads as craft. Three of them read as a template. */
+export const LIFT = { type: "spring", bounce: 0.28, duration: 0.5 } as const;
+
+/* ── Squash and stretch, out of physics ──────────────────────────────────
+   Two springs of deliberately different character, applied to the two axes
+   of one panel. Every difference pushes the same direction — GROW is fast
+   and loose, CROSS is slow and controlled:
+
+     stiffness  620 vs 380   GROW pulls harder, moves sooner
+     damping     19 vs  30   GROW resists less, overshoots
+     mass      0.85 vs   1   GROW is lighter, accelerates faster
+
+   Through the overshoot the panel is briefly TALLER and NARROWER than it
+   ends up, then settles. Squash and stretch emerging from physics rather
+   than a hand-authored timeline — interruptible and velocity-aware for free.
+
+   Generalises: when two axes of one element move together, giving them
+   different springs creates deformation, and deformation reads as mass. */
+export const GROW = { type: "spring", stiffness: 620, damping: 19, mass: 0.85 } as const;
+export const CROSS = { type: "spring", stiffness: 380, damping: 30 } as const;
+
+/* ── Closing ─────────────────────────────────────────────────────────────
+   A tween, not a spring. easeIn, so it accelerates away rather than
+   decelerating in. 130ms, well under the state tier.
+
+   A bounce on the way out reads as the interface being reluctant, and it
+   stands between the user and whatever they're reaching for next.
+   Entrances can have character; exits should get out of the way. */
+export const CLOSE = { duration: 0.13, ease: "easeIn" } as const;
+
+/* ── Reduced motion ──────────────────────────────────────────────────────
+   Substitute, don't subtract. The preference exists because large-area or
+   accelerating motion is physically unpleasant for some users — it is not a
+   preference for a static interface. A user who sets it still needs to know
+   that a menu opened.
+
+   Flat, state-tier, no overshoot. The state change stays legible; the
+   physics goes away. */
+export const FLAT = { duration: 0.15 } as const;
+
+/** Pick the spring or its flat substitute. `reduce` from useReducedMotion(). */
+export function motionOr<T>(reduce: boolean | null, animated: T) {
+  return reduce ? FLAT : animated;
+}
+
+/* ── Duration ladder, for inline JS use ──────────────────────────────────
+   Mirrors motion-tokens.css. Seconds, because that's what Motion takes. */
+export const DURATION = {
+  micro: 0.1,
+  state: 0.15,
+  popover: 0.2,
+  route: 0.26,
+  overlay: 0.3,
+  theme: 0.4,
+} as const;
+
+/* ── Off the ladder, deliberately ────────────────────────────────────────
+   The ladder is for STATE: something changed and the user has to follow it.
+   Two categories aren't state, and squeezing them onto the ladder makes
+   them worse rather than tighter.
+
+   THE SUBJECT OF THE MOMENT. When the thing animating IS the content, the
+   user is looking directly at it and the motion has to read in its own
+   right. Note the discipline in the pair below: same component, two
+   durations, decided by whether the motion is the subject or the report. */
+export const SUBJECT = {
+  /** Stepping between images — a noise-thresholded dissolve, not a cut. */
+  dissolve: 0.62,
+  /** The same image moving between two layouts. On screen at both ends, so
+      it only has to be followable — back inside the overlay tier. */
+  flight: 0.42,
+} as const;
+
+/* A SET PIECE gets its own budget by never appearing again: once per tab,
+   never blocking a deep link, never played under reduced motion. See §14 of
+   glass/motion/guide.md for the gating. */
+export const SET_PIECE = {
+  /** The first open of a disclosure, per line. */
+  theatreLine: 0.34,
+  /** Every subsequent open of the same thing. */
+  quietLine: 0.16,
+  /** Between staggered children on the first open only. */
+  stagger: 0.09,
+} as const;
+
+/* ── The curve for a track that also drives a filter ─────────────────────
+   NOT --ease-geist. The house curve overshoots past 1, and a blur animating
+   to 0px would have to pass through a NEGATIVE radius to settle back.
+   Browsers clamp rather than crash, so the symptom isn't an error — it's a
+   value stuck at zero for the tail while everything else is still moving,
+   which reads as the animation stalling right at the end.
+
+   Applies to any property with a hard floor: blur, brightness, a radius
+   going to 0, a scale you've promised won't invert. Expo-out has the same
+   "arrives decisively" character without ever leaving [0, 1]. */
+export const EASE_FILTER = [0.16, 1, 0.3, 1] as const;
+
+/* ── Blur crossfade ──────────────────────────────────────────────────────
+   Text swapping in place — a wordmark revealing its tagline on hover, say.
+   Note the asymmetry (280 in / 180 out): same principle as the springs.
+
+   Blur is the vestibular trigger; the fade isn't. So reduced motion swaps
+   only the blur amount to 0px and keeps the crossfade. Animating
+   blur(0px) → blur(0px) is a no-op the browser optimises away, so this needs
+   no second code path. */
+export function blurCrossfade(reduce: boolean | null) {
+  const blur = reduce ? "blur(0px)" : "blur(4px)";
+  return {
+    initial: { opacity: 0, filter: blur },
+    animate: { opacity: 1, filter: "blur(0px)", transition: { duration: 0.28, ease: "easeOut" } },
+    exit: { opacity: 0, filter: blur, transition: { duration: 0.18, ease: "easeIn" } },
+  } as const;
+}
+
+/* ── First-open theatre ──────────────────────────────────────────────────
+   Staggered lines behind a blur, on the FIRST open only; every subsequent
+   open is a quick fade. `theatre` comes from sessionStorage, so it is false
+   on the server for everyone and true on the client for most.
+
+   Which is why the shut state below is a CONSTANT. Branch a rendered style
+   on a client-only flag and React hands you two different first paints and
+   says so in the console. Only the transition reads the flags — a transition
+   isn't a style, so there's nothing for hydration to disagree about, and a
+   reader who asked for less motion gets a zero-length transition to the same
+   end state rather than a different starting position.
+
+   Record "seen" on animation COMPLETE, not on start: setting it earlier
+   lands in the same render batch as the open and cancels the very animation
+   it's recording. */
+export function theatreLine(reduce: boolean | null, theatre: boolean) {
+  return {
+    shut: { opacity: 0, y: 6, filter: "blur(4px)" },
+    open: {
+      opacity: 1,
+      y: 0,
+      filter: "blur(0px)",
+      transition: {
+        duration: reduce ? 0 : theatre ? SET_PIECE.theatreLine : SET_PIECE.quietLine,
+        // A blur is on this track — see EASE_FILTER above.
+        ease: EASE_FILTER,
+      },
+    },
+  } as const;
+}
+
+/** The parent's stagger. Zero after the first open, so a re-open is instant. */
+export function theatreList(theatre: boolean) {
+  return {
+    open: {
+      transition: {
+        staggerChildren: theatre ? SET_PIECE.stagger : 0,
+        delayChildren: theatre ? 0.06 : 0,
+      },
+    },
+  } as const;
+}
+
+/* ── Icon fill ───────────────────────────────────────────────────────────
+   Fill means CHOSEN — the page you're on, or the one you're pointing at.
+   Nothing is filled because it looks better.
+
+   The filled variant is not a second drawing: it's the same outline with its
+   interior painted in, layered OVER the stroke at the same coordinates. The
+   silhouette never moves, so the two crossfade in place — no pop, no reflow.
+
+   ease-out, not the house curve: the overshoot is right for travel and wrong
+   for a fade. Same split the springs make between position and opacity. */
+export const fillFade = (on: boolean) =>
+  `transition-opacity duration-200 ease-out motion-reduce:transition-none ${
+    on ? "opacity-100" : "opacity-0"
+  }`;
+
+/** The inverse — interior lines a solid shape swallows (a briefcase's
+    divider, a document's rules) have to leave as the fill arrives. */
+export const detailFade = (on: boolean) =>
+  `transition-opacity duration-200 ease-out motion-reduce:transition-none ${
+    on ? "opacity-0" : "opacity-100"
+  }`;

package/plugins/keyline/skills/keyline/glass/motion/assets/motion-tokens.css

@@ -0,0 +1,176 @@
+/* ─────────────────────────────────────────────────────────────────────────
+   Interface motion — tokens and CSS-driven effects
+   Drop-in for Tailwind v4 (@theme) or plain CSS (the :root fallback below).
+   ───────────────────────────────────────────────────────────────────────── */
+
+@theme {
+  /* ── One curve for the whole system ─────────────────────────────────────
+     The 1.1 end control point overshoots ~10% and settles back — enough to
+     feel physical, not enough to read as bounce. A single shared curve is
+     why unrelated elements moving at once still feel like one mechanism.
+
+     Do NOT add a second bezier "because this needs a different feel." If an
+     element needs distinct character it needs a spring — that's the axis
+     where character belongs without fragmenting the system. */
+  --ease-geist: cubic-bezier(0.175, 0.885, 0.32, 1.1);
+
+  /* ── Duration ladder ────────────────────────────────────────────────────
+     Set by how much of the screen changes, not by how important the element
+     feels. Three numbers carry almost everything: 150 / 200 / 300. */
+  --duration-micro: 100ms;    /* one property, no position — link opacity  */
+  --duration-state: 150ms;    /* colour, background, small transform, icon */
+  --duration-popover: 200ms;  /* chevron, hover card, compound glyph       */
+  --duration-route: 260ms;    /* whole viewport, on the critical path      */
+  --duration-overlay: 300ms;  /* large region entering or collapsing       */
+  --duration-theme: 400ms;    /* literally everything, at once            */
+
+  /* ── Off the ladder, deliberately ───────────────────────────────────────
+     The ladder is for STATE. Two things aren't state, and squeezing them
+     onto it makes them worse rather than tighter.
+
+     THE SUBJECT OF THE MOMENT — the thing animating IS the content, so the
+     user is looking directly at it and the motion has to read in its own
+     right. Note the pair: the dissolve is the subject, the flight is a
+     report about it, so the flight stays inside the overlay tier. */
+  --duration-dissolve: 620ms; /* stepping between images                   */
+  --duration-flight: 420ms;   /* one image moving between two layouts      */
+
+  /* A SET PIECE earns its budget by never appearing again — once per tab,
+     never blocking a deep link, never played under reduced motion. */
+  --duration-setpiece-in: 560ms;
+  --duration-setpiece-out: 320ms;
+
+  /* ── The curve for a track that also drives a filter ────────────────────
+     NOT --ease-geist. The house curve overshoots past 1, and a blur
+     animating to 0px would have to pass through a NEGATIVE radius to settle
+     back. Browsers clamp rather than crash, so the symptom is a value stuck
+     at zero for the tail of the transition — which reads as the animation
+     stalling right at the end, and is very hard to attribute.
+
+     Applies to any property with a hard floor: blur, brightness, a radius
+     going to 0, a scale you've promised won't invert. Expo-out has the same
+     "arrives decisively" character without ever leaving [0, 1]. */
+  --ease-filter: cubic-bezier(0.16, 1, 0.3, 1);
+}
+
+/* Plain-CSS fallback if you're not on Tailwind v4. */
+:root {
+  --ease-geist: cubic-bezier(0.175, 0.885, 0.32, 1.1);
+}
+
+@layer components {
+  /* ── Reveal on scroll ────────────────────────────────────────────────────
+     CSS animates; JS only sets `data-in` (see useReveal.ts). 8px of travel —
+     enough to register, small enough that a page of revealing paragraphs
+     doesn't feel like it's sliding around. */
+  .reveal {
+    opacity: 0;
+    transform: translateY(8px);
+    transition: opacity var(--duration-overlay) var(--ease-geist),
+                transform var(--duration-overlay) var(--ease-geist);
+  }
+  /* An attribute, not a class — see useReveal.ts for why a class can't survive. */
+  .reveal[data-in] {
+    opacity: 1;
+    transform: translateY(0);
+  }
+
+  /* Off entirely — the animation IS the effect, so there's nothing to
+     degrade to. Note it resolves to opacity: 1; the danger with any
+     reveal-on-scroll is leaving content stuck at opacity: 0. */
+  @media (prefers-reduced-motion: reduce) {
+    .reveal {
+      opacity: 1;
+      transform: none;
+      transition: none;
+    }
+  }
+
+  /* Print is a real presentation, and scroll-triggered content prints blank
+     without this. The most-forgotten line in the file. */
+  @media print {
+    .reveal {
+      opacity: 1;
+      transform: none;
+    }
+  }
+
+  /* THE THIRD GUARD IS NOT CSS. A feature check can't catch "JavaScript
+     never ran at all": the rules above ship, `.reveal` applies, and nothing
+     arrives to add `.in`. The reader gets a correct document they cannot
+     see — a blank page rather than a plain one. Put this in the head:
+
+       <noscript>
+         <style>.reveal { opacity: 1 !important; transform: none !important; }</style>
+       </noscript>
+
+     The general rule: any CSS that hides content pending JavaScript needs a
+     <noscript> reset. */
+
+  /* ── Route transition ───────────────────────────────────────────────────
+     Opacity only — no slide, no scale. Directional motion implies a spatial
+     relationship between routes; in a flat site map there isn't one.
+
+     260ms rather than 300: a page transition sits directly between "I
+     clicked" and "I can read," and that latency reads as the site being
+     slow. 260 is the shortest crossfade that isn't mistaken for a flicker.
+
+     `both` holds the from-state before the animation starts, preventing a
+     one-frame flash of opaque content. Key the wrapper on the pathname to
+     replay it on each navigation. */
+  .route-fade {
+    animation: routeFade var(--duration-route) var(--ease-geist) both;
+  }
+  @keyframes routeFade {
+    from { opacity: 0; }
+    to   { opacity: 1; }
+  }
+  @media (prefers-reduced-motion: reduce) {
+    .route-fade { animation: none; }
+  }
+
+  /* ── Theme crossfade ────────────────────────────────────────────────────
+     Added by the theme setter for ~440ms on an explicit toggle only, then
+     removed. Left in permanently it would make EVERY hover state on the site
+     400ms and sluggish — the !important is what lets it beat each
+     component's own duration-150 for those 440ms, and the removal is what
+     stops it poisoning everything else.
+
+     400ms because this is the largest possible change: every surface, text
+     colour, border, icon fill and shadow simultaneously.
+
+     Plain `ease`, not the house curve — overshoot on a position is momentum;
+     overshoot on a colour interpolation means the background travels past
+     its target and comes back, which reads as a wobble in the light.
+
+     The whole rule sits inside no-preference, so it's opt-in. Reduced-motion
+     users still get the theme change, just instantly. */
+  @media (prefers-reduced-motion: no-preference) {
+    :root.theme-transition,
+    :root.theme-transition *,
+    :root.theme-transition *::before,
+    :root.theme-transition *::after {
+      transition: background-color var(--duration-theme) ease,
+                  color var(--duration-theme) ease,
+                  border-color var(--duration-theme) ease,
+                  fill var(--duration-theme) ease,
+                  stroke var(--duration-theme) ease,
+                  box-shadow var(--duration-theme) ease !important;
+    }
+  }
+
+  /* ── Skip link ──────────────────────────────────────────────────────────
+     Parked off-screen with a transform (not display:none, which would take
+     it out of the tab order) and slid in on focus at the state tier. */
+  .skip {
+    position: absolute;
+    left: 16px;
+    top: 16px;
+    z-index: 100;
+    transform: translateY(-200%);
+    transition: transform var(--duration-state) var(--ease-geist);
+  }
+  .skip:focus {
+    transform: translateY(0);
+  }
+}

package/plugins/keyline/skills/keyline/glass/motion/assets/useReveal.ts

@@ -0,0 +1,65 @@
+import { useEffect } from "react";
+
+/**
+ * Marks any `.reveal` element as arrived, with `data-in`, when it scrolls into
+ * view. The CSS does all the animating (see motion-tokens.css); this only sets
+ * an attribute.
+ *
+ * An attribute rather than a class, and that is not a style choice. `class` is a
+ * prop React owns: the moment any `.reveal` element gets a className that depends
+ * on state, React rewrites the whole attribute from its own value and a class
+ * added out here is gone. The element then has `.reveal` with nothing to say it
+ * arrived, so it fades to `opacity: 0` — and the observer has already unobserved
+ * it, so it never comes back. React doesn't render `data-in`, so it leaves it be.
+ *
+ * Pass a value that changes on navigation (e.g. the pathname) so the observer
+ * re-attaches to the new page's `.reveal` elements after a route change —
+ * without it, a client-side navigation leaves the incoming page's content
+ * permanently at opacity: 0.
+ *
+ * THE THIRD GUARD IS NOT IN THIS FILE, and it's the one people miss. A feature
+ * check can't catch "JavaScript never ran at all": the CSS ships, `.reveal`
+ * applies, and nothing arrives to set `data-in`. The reader gets a correct document
+ * they cannot see. Put this in the document head, beside where you load the app:
+ *
+ *   <noscript>
+ *     <style>.reveal { opacity: 1 !important; transform: none !important; }</style>
+ *   </noscript>
+ *
+ * The general rule: any CSS that hides content pending JavaScript needs a
+ * <noscript> reset. This is a correctness bug, not a nicety — the failure mode
+ * is a blank page rather than a plain one.
+ */
+export function useReveal(dep?: unknown) {
+  useEffect(() => {
+    // No IntersectionObserver → show everything immediately. Never leave
+    // content invisible behind a feature check.
+    if (typeof IntersectionObserver === "undefined") {
+      document.querySelectorAll(".reveal").forEach((el) => el.setAttribute("data-in", ""));
+      return;
+    }
+
+    const io = new IntersectionObserver(
+      (entries) => {
+        for (const entry of entries) {
+          if (entry.isIntersecting) {
+            entry.target.setAttribute("data-in", "");
+            // A reveal is one-shot. Re-animating on scroll-back is nauseating,
+            // and unobserving keeps the observer's element list shrinking.
+            io.unobserve(entry.target);
+          }
+        }
+      },
+      // No fractional threshold, deliberately. An element's intersection ratio
+      // can never exceed the viewport's height divided by its own, so anything
+      // more than ten screens tall can't reach 0.1 however far you scroll, and
+      // it sits at opacity 0 for the whole page. The bottom margin does the job
+      // the threshold was doing: reveal once the element is 40px inside the
+      // viewport, at any height.
+      { threshold: 0, rootMargin: "0px 0px -40px 0px" }
+    );
+
+    document.querySelectorAll(".reveal").forEach((el) => io.observe(el));
+    return () => io.disconnect();
+  }, [dep]);
+}

package/plugins/keyline/skills/keyline/glass/motion/assets/useScrollTick.ts

@@ -0,0 +1,183 @@
+import { useEffect, useRef, useState } from "react";
+
+/**
+ * The one scroll shape: a `ticking` flag, one requestAnimationFrame, and a
+ * passive listener. Every scroll-driven behaviour in the system uses it.
+ *
+ * `passive: true` tells the browser the handler will never preventDefault, so
+ * it can begin scrolling without waiting for your JS. Omitting it is the most
+ * common cause of scroll jank.
+ *
+ * The `ticking` flag collapses a burst of scroll events into one measurement
+ * per frame. Don't substitute a time-based throttle — it's either faster than
+ * the frame rate (wasted work) or slower (dropped frames). rAF is
+ * frame-aligned by construction.
+ *
+ * `resize` shares the handler because a viewport change invalidates the same
+ * measurements a scroll does.
+ */
+export function useScrollTick(update: () => void, deps: unknown[] = []) {
+  const fn = useRef(update);
+  fn.current = update;
+
+  useEffect(() => {
+    let ticking = false;
+
+    const onScroll = () => {
+      if (!ticking) {
+        ticking = true;
+        requestAnimationFrame(() => {
+          ticking = false;
+          fn.current();
+        });
+      }
+    };
+
+    // Measure once on mount, so a page loaded already scrolled (a deep link,
+    // a restored scroll position) starts in the right state.
+    fn.current();
+
+    window.addEventListener("scroll", onScroll, { passive: true });
+    window.addEventListener("resize", onScroll);
+    return () => {
+      window.removeEventListener("scroll", onScroll);
+      window.removeEventListener("resize", onScroll);
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, deps);
+}
+
+/**
+ * Collapse-on-scroll-down with hysteresis. Returns true while the element
+ * should be collapsed.
+ *
+ * Three things at once:
+ *
+ *   · THRESHOLD px of movement required before the state flips. Without a
+ *     dead zone, a 1px jitter — trackpad, rubber-band bounce, or your own
+ *     state change altering layout — oscillates forever.
+ *
+ *   · A zone at the top where it's always expanded. Landing at the top of a
+ *     page should look the same however you got there.
+ *
+ *   · A bottom zone, so a collapsed element never sits over the footer. The
+ *     `- 2` absorbs subpixel rounding in the height calculation; an exact
+ *     comparison intermittently fails at fractional device pixel ratios.
+ *
+ * The top/bottom overrides are checked FIRST so they beat the direction
+ * logic.
+ *
+ * `hoverOnly` (default true) bails out entirely on touch devices. This
+ * pattern is only safe where a cursor can bring the element back — on a
+ * touch screen there is no hover, so collapsing would strand whatever the
+ * element contains. The capability check belongs at the point where you
+ * decide to HIDE something, not where you reveal it.
+ */
+export function useCollapseOnScroll({
+  threshold = 6,
+  topZone = 24,
+  hoverOnly = true,
+}: { threshold?: number; topZone?: number; hoverOnly?: boolean } = {}) {
+  const [collapsed, setCollapsed] = useState(false);
+
+  useEffect(() => {
+    if (hoverOnly && !window.matchMedia("(hover: hover) and (pointer: fine)").matches) return;
+
+    let last = window.scrollY;
+    let ticking = false;
+
+    const update = () => {
+      ticking = false;
+      const y = window.scrollY;
+      const atBottom =
+        y + window.innerHeight >= document.documentElement.scrollHeight - 2;
+
+      if (y < topZone || atBottom) setCollapsed(false);
+      else if (y > last + threshold) setCollapsed(true);
+      else if (y < last - threshold) setCollapsed(false);
+      last = y;
+    };
+
+    const onScroll = () => {
+      if (!ticking) {
+        ticking = true;
+        requestAnimationFrame(update);
+      }
+    };
+
+    window.addEventListener("scroll", onScroll, { passive: true });
+    return () => window.removeEventListener("scroll", onScroll);
+  }, [threshold, topZone, hoverOnly]);
+
+  return collapsed;
+}
+
+/**
+ * Which of the given section ids the reader is currently in — for a table of
+ * contents that marks its place.
+ *
+ * A reading line, not an IntersectionObserver. An observer tells you WHETHER
+ * an element is visible, which is the wrong question: several sections are
+ * visible at once and the answer changes with element height. A single line
+ * answers the actual question — which heading did I most recently pass?
+ *
+ * Ids must be in document order; the loop breaks at the first section that
+ * hasn't crossed the line.
+ *
+ * IMPORTANT: give every heading a scroll-margin-top just under READING_LINE
+ * (scroll-mt-28 = 112px against 120px here). Without it, a jump scrolls the
+ * heading to y=0 — ABOVE the line — so the section you just jumped to isn't
+ * the active one and the TOC highlights the previous one.
+ */
+const READING_LINE = 120;
+
+export function useActiveSection(ids: string[]): string {
+  const [active, setActive] = useState(ids[0] ?? "");
+
+  // Ids arrive as a fresh array each render, so [ids] would tear down and
+  // rebuild the listener continuously. Key the effect on the contents.
+  const key = ids.join("|");
+
+  useEffect(() => {
+    const list = key ? key.split("|") : [];
+    if (list.length === 0) return;
+
+    let ticking = false;
+
+    const update = () => {
+      ticking = false;
+      let current = list[0];
+      for (const id of list) {
+        const el = document.getElementById(id);
+        if (!el) continue;
+        if (el.getBoundingClientRect().top > READING_LINE) break;
+        current = id;
+      }
+
+      // Without this clamp a short final section can never become active:
+      // you reach the end of the page before its heading crosses the line.
+      const atBottom =
+        window.scrollY + window.innerHeight >= document.documentElement.scrollHeight - 2;
+      if (atBottom) current = list[list.length - 1];
+
+      setActive((prev) => (prev === current ? prev : current));
+    };
+
+    const onScroll = () => {
+      if (!ticking) {
+        ticking = true;
+        requestAnimationFrame(update);
+      }
+    };
+
+    update();
+    window.addEventListener("scroll", onScroll, { passive: true });
+    window.addEventListener("resize", onScroll);
+    return () => {
+      window.removeEventListener("scroll", onScroll);
+      window.removeEventListener("resize", onScroll);
+    };
+  }, [key]);
+
+  return active;
+}