explico 0.6.0 → 0.8.0

package/src/components/notation/NotationLayer.astro

@@ -263,14 +263,6 @@ for (const gloss of glossItems) {
             </header>
             <p data-slot-summary hidden />
             <div data-slot-formula hidden />
-            <button
-              class="notation-popup-copy"
-              type="button"
-              data-popup-copy
-              hidden
-            >
-              Copy LaTeX
-            </button>
             <p class="notation-units" data-slot-units hidden />
             <a data-slot-link hidden>
               Open the full definition
@@ -405,18 +397,7 @@ for (const gloss of glossItems) {
       const units = fragment.querySelector<HTMLElement>('[data-slot-units]');
       const link =
         fragment.querySelector<HTMLAnchorElement>('[data-slot-link]');
-      const copyButton = fragment.querySelector<HTMLButtonElement>(
-        '[data-popup-copy]',
-      );
-      if (
-        !el ||
-        !symbolHost ||
-        !title ||
-        !summary ||
-        !formulaHost ||
-        !units ||
-        !copyButton
-      ) {
+      if (!el || !symbolHost || !title || !summary || !formulaHost || !units) {
         return null;
       }
 
@@ -443,34 +424,6 @@ for (const gloss of glossItems) {
       );
       formulaHost.hidden = sourceFormula === null;
 
-      // The formula's own `data-latex` carries the plain, authored LaTeX —
-      // not the `\explain{key}{…}`-wrapped source KaTeX actually rendered —
-      // so what a reader copies is what they'd write themselves, not an
-      // internal marker macro. See `render-notation-math.ts:renderNotationFormula`.
-      const formulaLatex = sourceFormula?.dataset.latex ?? '';
-      copyButton.hidden = formulaLatex.length === 0;
-      if (formulaLatex.length > 0) {
-        copyButton.addEventListener('click', (event) => {
-          // Otherwise this bubbles to the document click handler in
-          // `popup-stack.ts`, which treats any click inside a popup that
-          // isn't a trigger or a link as "close it" — that would remove the
-          // card before the "Copied!" flash below ever paints.
-          event.stopPropagation();
-          if (!navigator.clipboard) return;
-          navigator.clipboard.writeText(formulaLatex).then(
-            () => {
-              copyButton.dataset.copied = 'true';
-              window.setTimeout(() => {
-                delete copyButton.dataset.copied;
-              }, 1200);
-            },
-            () => {
-              /* Clipboard blocked: nothing more we can do here. */
-            },
-          );
-        });
-      }
-
       setOptionalText(
         units,
         entry
@@ -547,6 +500,84 @@ for (const gloss of glossItems) {
     );
     if (details) setupNotationDisclosure(details);
   }
+
+  // "Copy LaTeX" for a notation formula (a glossary entry's own numbered
+  // formula, or one named inline via `\explain{}` inside a popup/`Diagram`),
+  // two ways: its own button (only a numbered formula has one —
+  // `data-notation-formula-copy`, `NotationFormula.astro`), or a click
+  // anywhere else in the box that isn't the number link or an explained
+  // symbol — the same region `.notation-formula-math:hover` highlights
+  // (`NotationFormula.astro`), which includes the reserved gutter between
+  // the equation and its number, not just the rendered `.katex-html`. This
+  // listener lives here, not in `NotationFormula.astro` or
+  // `KeyedFloatEnhancer.astro`, because this component loads on every page —
+  // it's the Starlight `Footer` override — while `KeyedFloatEnhancer` is
+  // lesson-only and a formula can appear inside a hover popup mounted
+  // outside `.sl-markdown-content`.
+  document.addEventListener('click', (event) => {
+    const origin = event.target instanceof Element ? event.target : null;
+    if (!origin) return;
+
+    const ownButton = origin.closest<HTMLButtonElement>(
+      '[data-notation-formula-copy]',
+    );
+    const container = ownButton
+      ? null
+      : origin.closest<HTMLElement>('[data-notation-formula]');
+    if (!ownButton) {
+      if (origin.closest('[data-notation-key], .notation-formula-number')) {
+        return;
+      }
+      if (!container) return;
+    }
+
+    const feedbackTarget =
+      ownButton ??
+      container?.querySelector<HTMLElement>('[data-notation-formula-copy]') ??
+      container;
+    const latex =
+      ownButton?.dataset.latex ?? feedbackTarget?.dataset.latex ?? '';
+    if (!feedbackTarget || latex.length === 0 || !navigator.clipboard) return;
+
+    navigator.clipboard.writeText(latex).then(
+      () => {
+        feedbackTarget.dataset.copied = 'true';
+        window.setTimeout(() => {
+          delete feedbackTarget.dataset.copied;
+        }, 1200);
+      },
+      () => {
+        /* Clipboard blocked: nothing more we can do here. */
+      },
+    );
+  });
+
+  // A tooltip for the click gesture above, and only for the part of the
+  // equation it actually applies to — an explained symbol has its own hover
+  // card (created above) and needs no tooltip layered on top of it, and the
+  // copy button already carries a static `title`. `mouseover`/`mouseout` (not
+  // `mouseenter`/`mouseleave`) because they bubble, which this document-level
+  // delegation needs.
+  document.addEventListener('mouseover', (event) => {
+    const origin = event.target instanceof Element ? event.target : null;
+    if (!origin || origin.getAttribute('title') === 'Copy LaTeX') return;
+    if (
+      origin.closest(
+        '[data-notation-key], [data-notation-formula-copy], .notation-formula-number',
+      )
+    ) {
+      return;
+    }
+    if (!origin.closest('[data-notation-formula]')) return;
+    origin.setAttribute('title', 'Copy LaTeX');
+  });
+
+  document.addEventListener('mouseout', (event) => {
+    const origin = event.target instanceof Element ? event.target : null;
+    if (origin?.getAttribute('title') === 'Copy LaTeX') {
+      origin.removeAttribute('title');
+    }
+  });
 </script>
 
 <style>
@@ -722,6 +753,10 @@ for (const gloss of glossItems) {
       font-size: var(--sl-text-sm);
     }
 
+    /* Cursor, hover highlight, and "Copied!" flash for this plain-span
+       formula fallback (a definition with no `formulaScope`) come from the
+       generic `[data-notation-formula]` rules in `global.css` — shared with
+       every other producer of that attribute, not reimplemented here. */
     .notation-formula {
       overflow-x: auto;
       /* `overflow-x: auto` alone makes the block axis compute to `auto` too
@@ -823,39 +858,6 @@ for (const gloss of glossItems) {
       line-height: 1.5;
     }
 
-    .notation-popup-copy {
-      position: relative;
-      margin-block: 0.4rem 0.6rem;
-      padding: 0.2rem 0.55rem;
-      border: 1px solid var(--sl-color-gray-5);
-      border-radius: 0.35rem;
-      color: var(--sl-color-text-accent);
-      background: var(--sl-color-bg);
-      font: inherit;
-      font-size: var(--sl-text-xs);
-      cursor: pointer;
-    }
-
-    .notation-popup-copy:hover {
-      border-color: var(--sl-color-accent);
-      background: var(--sl-color-accent-low);
-    }
-
-    .notation-popup-copy[data-copied]::after {
-      content: 'Copied!';
-      position: absolute;
-      inset-block-end: calc(100% + 0.35rem);
-      inset-inline-start: 50%;
-      translate: -50% 0;
-      padding: 0.15rem 0.45rem;
-      border-radius: 0.35rem;
-      background: var(--sl-color-accent-low);
-      color: var(--sl-color-text-accent);
-      font-size: var(--sl-text-xs);
-      white-space: nowrap;
-      pointer-events: none;
-    }
-
     .notation-panel-body [data-slot-formula] {
       overflow-x: auto;
       /* See `.notation-formula` above: pairs with `overflow-x` to stop the

package/src/components/notation/render-notation-math.ts

@@ -1,5 +1,8 @@
 import rehypeKatex from 'rehype-katex';
-import { createNotationKatexOptions } from '../../reference/katex-options.mjs';
+import {
+  createNotationKatexOptions,
+  trustNotationMarker,
+} from '../../reference/katex-options.mjs';
 import { NOTATION_KEY_PATTERN } from '../../reference/remark-notation.mjs';
 import {
   GlyphResolutionError,
@@ -81,32 +84,96 @@ const allowedTags = new Set([
   'line',
 ]);
 
+/**
+ * Every inert presentation attribute KaTeX's MathML builder can set, sorted.
+ *
+ * This list is deliberately KaTeX's whole surface rather than the attributes
+ * the corpus happens to have hit: anything missing here is a hard build error
+ * on valid, ordinary math, and the author has no way to work around it. `\Bigl`
+ * (`minsize`/`maxsize`), `\boxed` (`notation`), and `\colorbox`
+ * (`voffset`/`mathbackground`) each used to fail that way.
+ * `tests/notation/render-notation-math.test.ts` scans KaTeX's own
+ * `setAttribute` calls and fails when a release adds a name that is in neither
+ * this set nor {@link deniedAttributeNames}, so a KaTeX upgrade cannot quietly
+ * reintroduce the gap.
+ */
 const simpleAttributeNames = new Set([
   'accent',
   'accentunder',
   'columnalign',
+  'columnlines',
   'columnspacing',
+  'depth',
+  'display',
   'displaystyle',
   'fence',
   'height',
+  'largeop',
+  'linebreak',
+  'linethickness',
   'lspace',
+  'mathbackground',
+  'mathcolor',
+  'mathsize',
   'mathvariant',
+  'maxsize',
+  'minsize',
+  'notation',
   'preserveaspectratio',
+  'rowlines',
   'rowspacing',
   'rspace',
   'scriptlevel',
   'separator',
   'stretchy',
+  'valign',
   'viewbox',
+  'voffset',
   'width',
 ]);
 
-const safeAttributeValue = /^[ A-Za-z0-9+.,()\-/%]*$/;
+/**
+ * The attributes KaTeX can set that must never reach the page, each one a
+ * navigation or external-resource target: `href` (`\href`), `src`/`alt`
+ * (`\includegraphics`), and `title` (`\htmlTitle`). Every command that
+ * produces one already needs KaTeX's `trust` callback and is refused earlier by
+ * {@link unsafeExtensionCommand}, so this set is the second line — and the
+ * reason the completeness scan above can tell "KaTeX added an attribute nobody
+ * classified" apart from "we decided against this one".
+ */
+const deniedAttributeNames = new Set(['alt', 'href', 'src', 'title']);
+
+// `#` is here for `mathcolor` / `mathbackground` / a `background-color:` style,
+// which KaTeX writes as a hex literal. No attribute reaching this point can
+// carry a URL — `href` and `src` are denied above — so it opens no target.
+const safeAttributeValue = /^[ A-Za-z0-9+.,()\-/%#]*$/;
 const safeClassName = /^[A-Za-z0-9_-]+$/;
-const safeStyle = /^(?:[a-z-]+:[ A-Za-z0-9+.,()\-/%]*;)*$/;
+const safeDeclaration = /^\s*[a-z-]+:[ A-Za-z0-9+.,()\-/%#]*$/;
 const safePathData = /^[\sA-Za-z0-9+.,\-]*$/;
 const unsafeExtensionCommand =
   /\\(?:href|url|includegraphics|htmlClass|htmlData|htmlId|htmlStyle)\b/;
+// `\explain{key}{latex}` and `\slot{name}{latex}`, the two macros that expand
+// to a trusted `\htmlData` marker. Only the first argument is captured.
+const MARKER_MACRO = /\\(explain|slot)\{([^{}]*)\}/g;
+
+/**
+ * A declaration list KaTeX generated: inert properties only, and no
+ * `url(...)`/`expression(...)` to fetch or evaluate anything.
+ *
+ * Validated per declaration rather than with one regex over the whole string,
+ * because KaTeX does not always terminate the last one — `\vec` emits
+ * `style="width:0.471em"` with no trailing `;`, which a
+ * `(?:declaration;)*`-shaped pattern rejects outright.
+ */
+function isSafeStyle(value: string): boolean {
+  if (/(?:expression|url)\s*\(/i.test(value)) return false;
+  return value
+    .split(';')
+    .every(
+      (declaration) =>
+        declaration.trim().length === 0 || safeDeclaration.test(declaration),
+    );
+}
 
 function attributeValue(value: unknown, propertyName: string): string {
   if (typeof value === 'boolean') return String(value);
@@ -170,22 +237,27 @@ function safeProperties(
       continue;
     }
 
-    if (
-      name === 'style' &&
-      typeof value === 'string' &&
-      safeStyle.test(value) &&
-      !/(?:expression|url)\s*\(/i.test(value)
-    ) {
+    if (name === 'style') {
+      if (typeof value !== 'string' || !isSafeStyle(value)) {
+        throw new Error('Unsafe KaTeX style value.');
+      }
       properties.style = value;
       continue;
     }
 
-    if (name === 'd' && typeof value === 'string' && safePathData.test(value)) {
+    if (name === 'd') {
+      if (typeof value !== 'string' || !safePathData.test(value)) {
+        throw new Error('Unsafe KaTeX path data.');
+      }
       properties.d = value;
       continue;
     }
 
     const normalizedName = name.toLowerCase();
+    if (deniedAttributeNames.has(normalizedName)) {
+      throw new Error(`Disallowed KaTeX property: ${name}.`);
+    }
+
     if (simpleAttributeNames.has(normalizedName)) {
       const outputName =
         normalizedName === 'viewbox'
@@ -228,6 +300,34 @@ function sanitizeNode(node: HastNode): SafeMathNode {
 // this module already imports from `remark-notation.mjs`.
 export { stripNotationMarkers };
 
+/**
+ * Refuse a marker argument the trust callback would reject, before KaTeX sees
+ * it.
+ *
+ * KaTeX does not treat a denied `trust` as a parse error: it renders the
+ * command name in `errorColor` and carries on, so `\explain{Not A Key}{\Omega}`
+ * would otherwise reach a reader as red `\htmlData` text with the build still
+ * green. `\htmlData` itself is already refused by {@link
+ * unsafeExtensionCommand}, so the two marker macros are the only way into that
+ * callback and this check covers all of them. It asks
+ * {@link trustNotationMarker} rather than re-deriving the key patterns, so the
+ * answer here cannot drift from the answer KaTeX gets.
+ */
+function assertTrustedMarkers(latex: string): void {
+  for (const [, macro, argument] of latex.matchAll(MARKER_MACRO)) {
+    const attribute =
+      macro === 'explain' ? 'data-notation-key' : 'data-lab-slot';
+    if (
+      !trustNotationMarker({
+        command: '\\htmlData',
+        attributes: { [attribute]: argument },
+      })
+    ) {
+      throw new Error(`Notation LaTeX has an invalid \\${macro} key: ${argument}`);
+    }
+  }
+}
+
 /**
  * Render repository-authored LaTeX through the same build-time KaTeX adapter
  * as lesson math, then expose a constrained structured tree to Astro. No HTML
@@ -240,6 +340,7 @@ export function renderNotationMath(latex: string): readonly SafeMathNode[] {
   if (unsafeExtensionCommand.test(latex)) {
     throw new Error('Notation LaTeX cannot use a trust-requiring extension.');
   }
+  assertTrustedMarkers(latex);
 
   const root: HastRoot = {
     type: 'root',

package/src/components/scroll-animation.ts

@@ -0,0 +1,160 @@
+/**
+ * A single, site-wide motion profile for "jump to an in-page anchor":
+ * `DURATION_MS`, constant-magnitude acceleration — speeding up through the
+ * first half of the trip, slowing down through the second, symmetric about
+ * the midpoint (the standard `easeInOutQuad` curve, which is exactly a
+ * constant |acceleration| profile since position is piecewise quadratic in
+ * time).
+ *
+ * The browser's own fragment navigation (a plain `<a href="#id">` click, with
+ * no `scroll-behavior: smooth` set anywhere in this site's CSS) jumps
+ * instantly — and CSS's `scroll-behavior: smooth` can't be tuned to a given
+ * duration or easing anyway. Getting an exact, consistent curve everywhere
+ * means animating the scroll ourselves. `AnchorScrollEnhancer.astro` (the
+ * generic click case, covering every same-page link on every page) and the
+ * handful of enhancers with their own reasons to move the viewport
+ * (`HeadingAnchorEnhancer.astro`, `KeyedFloatEnhancer.astro`, footnote/memo
+ * expansion) all render through this module, so a click that touches two of
+ * them at once — e.g. a heading anchor click, animated here *and* re-scrolled
+ * by that enhancer's own `hashchange` listener — collapses to a single
+ * animation via `activeAnimation` below, rather than two fighting for the
+ * scroll position.
+ *
+ * An earlier version of `AnchorScrollEnhancer.astro` let the browser's own
+ * click-triggered jump run, then tried to catch it a frame later and replay
+ * it as an animation. The trouble: the HTML spec gives no guarantee about
+ * *when*, relative to our own script, that jump actually lands — under load
+ * it can take several frames — so a single-frame check could conclude
+ * "nothing moved, there's nothing to animate" and let the browser's own
+ * un-animated jump land moments later, unopposed (this was the original,
+ * confirmed bug reports came in about). Polling for more frames narrows that
+ * window but never closes it — there's always some delay past which it gives
+ * up. `animatedScrollIntoView` below removes the dependency on that timing
+ * entirely: it measures the destination itself, synchronously, before
+ * anything has had a chance to move, so there's nothing to race.
+ */
+
+const DURATION_MS = 200;
+function easeInOutQuad(t: number): number {
+  return t < 0.5 ? 2 * t * t : 1 - (-2 * t + 2) ** 2 / 2;
+}
+
+type SettleReason = 'complete' | 'interrupted';
+
+let activeAnimation: {
+  readonly target: Element;
+  readonly cancel: (reason: SettleReason) => void;
+} | null = null;
+
+function prefersReducedMotion(): boolean {
+  return window.matchMedia('(prefers-reduced-motion: reduce)').matches;
+}
+
+// Cancel on the reader's own scroll intent — a short ride is unlikely to
+// outlast one, but fighting the reader's wheel/touch/keyboard input, even
+// briefly, is exactly the kind of jank this exists to avoid.
+const CANCEL_EVENTS = ['wheel', 'touchstart', 'keydown'] as const;
+
+function runAnimation(
+  target: Element,
+  startX: number,
+  startY: number,
+  endX: number,
+  endY: number,
+  onSettle?: (reason: SettleReason) => void,
+): void {
+  if (activeAnimation?.target === target) return;
+  activeAnimation?.cancel('interrupted');
+
+  if (prefersReducedMotion() || (startX === endX && startY === endY)) {
+    window.scrollTo(endX, endY);
+    activeAnimation = null;
+    onSettle?.('complete');
+    return;
+  }
+
+  window.scrollTo(startX, startY);
+
+  let rafId = 0;
+  let cancelled = false;
+  const startTime = performance.now();
+
+  const onCancelEvent = () => cancel('interrupted');
+
+  const cleanup = () => {
+    for (const type of CANCEL_EVENTS) {
+      window.removeEventListener(type, onCancelEvent);
+    }
+  };
+
+  const finish = (reason: SettleReason) => {
+    cleanup();
+    if (activeAnimation?.target === target) activeAnimation = null;
+    onSettle?.(reason);
+  };
+
+  const cancel = (reason: SettleReason) => {
+    if (cancelled) return;
+    cancelled = true;
+    cancelAnimationFrame(rafId);
+    finish(reason);
+  };
+
+  const step = (now: number) => {
+    if (cancelled) return;
+    const t = Math.min(1, (now - startTime) / DURATION_MS);
+    const eased = easeInOutQuad(t);
+    window.scrollTo(
+      startX + (endX - startX) * eased,
+      startY + (endY - startY) * eased,
+    );
+    if (t < 1) {
+      rafId = requestAnimationFrame(step);
+    } else {
+      cancelled = true;
+      finish('complete');
+    }
+  };
+
+  for (const type of CANCEL_EVENTS) {
+    window.addEventListener(type, onCancelEvent, { passive: true });
+  }
+
+  activeAnimation = { target, cancel };
+  rafId = requestAnimationFrame(step);
+}
+
+/**
+ * Drop-in replacement for `target.scrollIntoView({ behavior: 'smooth', ... })`.
+ * Measures the destination itself — instantly, synchronously, before
+ * anything has had a chance to move — via `target.scrollIntoView({behavior:
+ * 'auto', ...})` (this respects `scroll-margin-*`, sticky headers, etc.
+ * exactly as the browser's own fragment navigation would), then jumps back
+ * and animates the trip.
+ *
+ * `onSettle`, when given, fires once: `'complete'` if the animation ran to
+ * the destination (or reduced motion meant an instant jump straight there),
+ * `'interrupted'` if the reader's own scroll/keyboard input cut it short, or
+ * — a rare, intentional no-op — never, if a newer call for the *same*
+ * target was already in flight (this one is simply dropped; the one already
+ * running owns the eventual settle).
+ */
+export function animatedScrollIntoView(
+  target: Element,
+  options: ScrollIntoViewOptions = { block: 'start' },
+  onSettle?: (reason: SettleReason) => void,
+): void {
+  if (prefersReducedMotion()) {
+    target.scrollIntoView({ ...options, behavior: 'auto' });
+    onSettle?.('complete');
+    return;
+  }
+
+  const startX = window.scrollX;
+  const startY = window.scrollY;
+  target.scrollIntoView({ ...options, behavior: 'auto' });
+  const endX = window.scrollX;
+  const endY = window.scrollY;
+
+  runAnimation(target, startX, startY, endX, endY, onSettle);
+}

package/src/components/starlight/AboutPanel.astro

@@ -12,6 +12,15 @@
  * It is a plain `<details>` disclosure: the browser gives keyboard toggle and
  * `aria-expanded` for free; the inline script only adds Escape-to-close and
  * outside-click-to-close.
+ *
+ * The panel also *publishes* the identity it displays: the `data-knowledge-*`
+ * and `data-engine-version` attributes carry the same values as the rendered
+ * text. A build check that wants to confirm the shipped page really carries the
+ * configured version would otherwise have to match the panel's prose and its
+ * `version · date` join, which pins a course's test to one version string and
+ * makes the check fail on every bump; a bare version substring is not even
+ * scoped to the panel, so the engine's own version elsewhere on the page can
+ * satisfy it. These attributes are exact, scoped, and stable across a bump.
  */
 import { loadManifest } from '../../compiler/manifest';
 
@@ -32,7 +41,13 @@ const knowledgeLine = knowledge.date
   : knowledge.version;
 ---
 
-<details class="about" data-about-panel>
+<details
+  class="about"
+  data-about-panel
+  data-knowledge-version={knowledge.version}
+  data-knowledge-date={knowledge.date}
+  data-engine-version={engine.version}
+>
   <summary
     class="about-toggle"
     aria-label={`About ${material.name}`}
@@ -47,7 +62,7 @@ const knowledgeLine = knowledge.date
     <dl class="about-facts">
       <div>
         <dt>Knowledge version</dt>
-        <dd>{knowledgeLine}</dd>
+        <dd data-knowledge-line>{knowledgeLine}</dd>
       </div>
       <div>
         <dt>Engine</dt>

package/src/components/starlight/AnchorScrollEnhancer.astro

@@ -0,0 +1,102 @@
+---
+/**
+ * Site-wide "jump to an in-page anchor" animation (Step F3 follow-up). Loads
+ * unconditionally, on every page — not just lessons — since it has to catch
+ * every same-page `<a href="#…">`: a heading, a keyed equation/table/figure
+ * number, a footnote/memo marker, and plain content links with no dedicated
+ * enhancer of their own at all (the notation glossary's term/anchor links,
+ * its "see also" list, a page's table of contents, …).
+ *
+ * This calls `preventDefault()` on a qualifying click — which looks like the
+ * one thing `HeadingAnchorEnhancer.astro` and `KeyedFloatEnhancer.astro` both
+ * carry a comment warning against, since `:target`-driven CSS (the
+ * heading/equation "flash") and the sticky-header `scroll-margin` offset only
+ * fire on a genuine same-document fragment navigation — never on a
+ * `history.pushState`. That warning is about *silently* replacing the
+ * navigation with `pushState` and never actually re-triggering it. This does
+ * something safer: it measures the destination and animates there itself
+ * (`animatedScrollIntoView`, `scroll-animation.ts` — the same call
+ * `HeadingAnchorEnhancer`/`KeyedFloatEnhancer` use for their own supplementary
+ * scrolls), and only once the viewport is actually *at* that destination does
+ * it assign `location.hash` — a real fragment navigation, not `pushState`,
+ * so `:target` matches and `hashchange` fires exactly as a plain click's
+ * default action would have. Because the assignment happens after arrival,
+ * the browser's own resulting "scroll to the fragment" pass finds nothing
+ * left to move and is an invisible no-op, whenever it happens to run.
+ *
+ * An earlier version instead let the native click run and tried to catch its
+ * jump a frame later — see the note atop `scroll-animation.ts` for why that
+ * was racy in a way no amount of polling fixed, and had to be replaced by
+ * this preventDefault-and-replay approach instead.
+ *
+ * If the reader scrolls away mid-animation (`'interrupted'` below), the URL
+ * still gets a plain `pushState` — reflecting the click without dragging
+ * them back to a destination they've already scrolled past, and without the
+ * `:target` flash firing for a section they're no longer looking at.
+ */
+---
+
+<script>
+  import { animatedScrollIntoView } from '../scroll-animation';
+
+  function sameDocumentFragmentId(link: HTMLAnchorElement): string | null {
+    if (link.target && link.target !== '_self') return null;
+    let url: URL;
+    try {
+      url = new URL(link.href, location.href);
+    } catch {
+      return null;
+    }
+    if (
+      url.origin !== location.origin ||
+      url.pathname !== location.pathname ||
+      url.search !== location.search ||
+      !url.hash
+    ) {
+      return null;
+    }
+    return url.hash.slice(1);
+  }
+
+  document.addEventListener('click', (event) => {
+    if (
+      event.defaultPrevented ||
+      event.button !== 0 ||
+      event.metaKey ||
+      event.ctrlKey ||
+      event.shiftKey ||
+      event.altKey
+    ) {
+      return;
+    }
+
+    const origin = event.target instanceof Element ? event.target : null;
+    const link = origin?.closest('a[href]');
+    if (!(link instanceof HTMLAnchorElement)) return;
+
+    const rawId = sameDocumentFragmentId(link);
+    if (!rawId) return;
+
+    let id = rawId;
+    try {
+      id = decodeURIComponent(rawId);
+    } catch {
+      /* keep the raw fragment */
+    }
+    const target = document.getElementById(id);
+    if (!target) return; // no matching element: let the browser's own no-op stand
+
+    if (window.matchMedia('(prefers-reduced-motion: reduce)').matches) return;
+
+    event.preventDefault();
+    animatedScrollIntoView(target, { block: 'start' }, (reason) => {
+      const hash = `#${id}`;
+      if (location.hash === hash) return;
+      if (reason === 'complete') {
+        location.hash = id;
+      } else {
+        history.pushState(null, '', hash);
+      }
+    });
+  });
+</script>