explico 0.5.0 → 0.7.0

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/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>

package/src/components/starlight/HeadingAnchorEnhancer.astro

@@ -37,6 +37,7 @@
 
 <script>
   import { HEADINGS, sectionParts } from './section-parts';
+  import { animatedScrollIntoView } from '../scroll-animation';
 
   (() => {
     const root = document.querySelector('.sl-markdown-content');
@@ -78,10 +79,7 @@
       if (!heading) return;
       const parts = sectionParts(heading);
       if (doScroll) {
-        parts[0].scrollIntoView({
-          behavior: reduce.matches ? 'auto' : 'smooth',
-          block: 'start',
-        });
+        animatedScrollIntoView(parts[0], { block: 'start' });
       }
       for (const part of parts) flash(part);
       heading.setAttribute('tabindex', '-1');

package/src/components/starlight/KeyedFloatEnhancer.astro

@@ -40,6 +40,8 @@
 ---
 
 <script>
+  import { animatedScrollIntoView } from '../scroll-animation';
+
   (() => {
     const root = document.querySelector('.sl-markdown-content');
     if (!root) return;
@@ -97,10 +99,7 @@
         target.style.removeProperty('animation');
       }
       if (doScroll) {
-        target.scrollIntoView({
-          behavior: reduce.matches ? 'auto' : 'smooth',
-          block: 'start',
-        });
+        animatedScrollIntoView(target, { block: 'start' });
       }
       target.setAttribute('tabindex', '-1');
       try {
@@ -132,13 +131,15 @@
 
     // "Copy LaTeX" for an equation, two ways: its own button (only a numbered
     // display equation has one — `data-eq-copy`, `remark-notation.mjs`'s
-    // `equationNode`), or a click anywhere else in the equation that isn't a
-    // symbol with its own notation card (an operator, a bare number, a
-    // parenthesis, …) — the same gesture works on an inline equation too
-    // (`inlineEquationNode`), which has no room for a persistent button of
-    // its own without breaking the reading line. A notation-registry symbol
-    // keeps its existing click-to-pin behavior either way
-    // (`NotationLayer.astro`), so this skips anything under `[data-notation-key]`.
+    // `equationNode`), or a click anywhere else in the box — including the
+    // reserved gutter between the equation and its number/button, not just
+    // the rendered `.katex-html` — that isn't the number link or a symbol
+    // with its own notation card. The same gesture works on an inline
+    // equation too (`inlineEquationNode`), which has no room for a
+    // persistent button of its own without breaking the reading line. A
+    // notation-registry symbol keeps its existing click-to-pin behavior
+    // either way (`NotationLayer.astro`), so this skips anything under
+    // `[data-notation-key]`.
     root.addEventListener('click', (event) => {
       const origin = event.target instanceof Element ? event.target : null;
       if (!origin) return;
@@ -150,9 +151,7 @@
       const container = ownButton
         ? null
         : origin.closest<HTMLElement>('.keyed-equation, .inline-equation');
-      if (!ownButton && (!container || !origin.closest('.katex-html'))) {
-        return;
-      }
+      if (!ownButton && !container) return;
 
       const feedbackTarget =
         ownButton ??
@@ -185,12 +184,14 @@
     root.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-eq-copy]')) return;
       if (
-        !origin.closest('.keyed-equation .katex-html, .inline-equation .katex-html')
+        origin.closest(
+          '[data-notation-key], [data-eq-copy], a.keyed-equation__number',
+        )
       ) {
         return;
       }
+      if (!origin.closest('.keyed-equation, .inline-equation')) return;
       origin.setAttribute('title', 'Copy LaTeX');
     });
 

package/src/components/starlight/LessonFooter.astro

@@ -23,6 +23,7 @@ import AbbreviationLayer from '../abbreviation/AbbreviationLayer.astro';
 import KeyedFloatEnhancer from './KeyedFloatEnhancer.astro';
 import FloatRefLayer from '../reference/FloatRefLayer.astro';
 import HeadingAnchorEnhancer from './HeadingAnchorEnhancer.astro';
+import AnchorScrollEnhancer from './AnchorScrollEnhancer.astro';
 import CollapsibleSections from './CollapsibleSections.astro';
 import TableOverflowExpander from '../table/TableOverflowExpander.astro';
 import DiagramEnhancer from './DiagramEnhancer.astro';
@@ -40,8 +41,10 @@ const lessonId = isLessonSlug(routeSlug)
 const glossaryBase = `${import.meta.env.BASE_URL.replace(/\/$/, '')}/glossary/`;
 
 const definitions: NotationLayerDefinition[] = [];
+let notationDefaultOpen = false;
 if (lessonId) {
   const manifest = await loadManifest();
+  notationDefaultOpen = manifest.disclosureDefaults.notation;
   const lesson = manifest.lessons.find((entry) => entry.id === lessonId);
   const routeData = Astro.locals.starlightRoute.entry.data as {
     notation?: { local?: readonly { key?: unknown }[] };
@@ -80,7 +83,8 @@ if (lessonId) {
 }
 ---
 
-<NotationLayer definitions={definitions} />
+<NotationLayer definitions={definitions} defaultOpen={notationDefaultOpen} />
+<AnchorScrollEnhancer />
 {lessonId && <CitationLayer />}
 {lessonId && <AbbreviationLayer />}
 {lessonId && <KeyedFloatEnhancer />}

package/src/content-config.ts

@@ -196,6 +196,21 @@ const assessmentItemBase = z.object({
   explanation: z.string().min(1),
 });
 
+/**
+ * `AssessmentSet.astro` renders the numbered heading itself — `<h2>Knowledge
+ * check {number} — {title}</h2>` — so `title` must be just the topic. A title
+ * that repeats the "Knowledge check" label duplicates it on every page that
+ * uses `AssessmentSet` (the standalone `AssessmentRunner` heading fallback
+ * reads fine either way, so this only bites the common path).
+ */
+const assessmentTitle = z
+  .string()
+  .min(1)
+  .refine((value) => !/^knowledge check\b/i.test(value), {
+    message:
+      'Assessment title must not start with "Knowledge check" — AssessmentSet already renders "Knowledge check {number} — {title}", so a title with the same prefix duplicates it. Use just the topic, e.g. "AIC and KL risk".',
+  });
+
 const assessments = defineCollection({
   loader: glob({
     pattern: '**/*.json',
@@ -203,7 +218,7 @@ const assessments = defineCollection({
   }),
   schema: z.object({
     id,
-    title: z.string().min(1),
+    title: assessmentTitle,
     editorialStatus,
     items: z
       .array(

package/src/reference/base-abbreviations.mjs

@@ -20,12 +20,18 @@ export const BASE_ABBREVIATIONS = Object.freeze(
     'e.g.',
     'i.e.',
     'etc.',
+    'e.t.c.',
     'cf.',
     'vs.',
-    'a.m.',
-    'p.m.',
     'a.k.a.',
     'et al.',
+    // time of day, in each casing/punctuation style a lesson might use
+    'a.m.',
+    'p.m.',
+    'A.M.',
+    'P.M.',
+    'AM',
+    'PM',
     // generic acronyms with no domain-specific meaning in this engine
     'AI',
     'ID',

package/src/reference/consistency.ts

@@ -2,11 +2,11 @@
  * Corpus consistency checks (Step D6) — the Tier 1–2 checks from the cleanup
  * plan's "Enforced checks" section that no earlier step covers.
  *
- * Every check here enters as a **Tier-3 warning**: `pnpm validate:content`
- * surfaces the counts, `manifest.diagnostics.consistency` records the detail,
- * and `resolution/consistency-report.json` is the committed, diff-checkable
- * snapshot. Nothing here changes content — each finding is an open item for a
- * separate human-quantitative-reviewed pass. A finding is silenced only by a
+ * Every check here is non-blocking Tier 3: repairable violations are warnings
+ * and optional restructuring advice is info. `pnpm validate:content` surfaces
+ * warning counts, `manifest.diagnostics.consistency` records every detail, and
+ * `resolution/consistency-report.json` is the committed, diff-checkable
+ * snapshot. Nothing here changes content. A finding is silenced only by a
  * reviewed line in `lint-ignore.yml` (see `./lint-ignore`).
  *
  *   (a) glyph-unique-in-corpus       one rendered glyph → one meaning corpus-wide
@@ -14,8 +14,6 @@
  *                                     unit strings drawn from a controlled vocab
  *   (c) convention-single-definition  a sign / cash-flow-perspective convention a
  *                                     lesson uses resolves to one declaration
- *   (e) numerals-tagged              numerals in `$…$` / result tables are tagged
- *                                     to a `src/domain/` call or a source locator
  *   (f) weak-local                   a `notation.local` symbol used only in its
  *                                     own defining equation and prose
  *   (g) notation-source-locator      every notation `sources` entry has a locator
@@ -54,7 +52,6 @@ export type ConsistencyCode =
   | 'notation-units'
   | 'units-vocab'
   | 'convention-single-definition'
-  | 'numerals-tagged'
   | 'weak-local'
   | 'notation-source-locator'
   | 'gloss-wants-promoting'
@@ -65,8 +62,8 @@ export type ConsistencyCode =
 
 export interface ConsistencyDiagnostic {
   readonly code: ConsistencyCode;
-  /** Tier 3 — every finding here is a warning until content is brought clean. */
-  readonly severity: 'warning';
+  /** Tier 3 — repairable violations are warnings; optional advice is info. */
+  readonly severity: 'warning' | 'info';
   readonly message: string;
   readonly file?: string;
   readonly lessonId?: string;
@@ -119,28 +116,6 @@ function mathSpans(body: string): MathSpan[] {
   return spans;
 }
 
-function tableRows(body: string): string[] {
-  const rows: string[] = [];
-  for (const line of stripCode(body).split('\n')) {
-    const trimmed = line.trim();
-    if (!trimmed.startsWith('|') || !trimmed.slice(1).includes('|')) continue;
-    if (/^\s*\|[\s:|-]+\|\s*$/.test(line)) continue;
-    rows.push(line);
-  }
-  return rows;
-}
-
-const NUMERAL_RE = /(?<![\w.])-?\d+(?:\.\d+)?/g;
-
-function numeralCount(text: string): number {
-  return (text.replace(/\\[a-zA-Z]+/g, ' ').match(NUMERAL_RE) ?? []).length;
-}
-
-/** A math span / table row is "tagged" when it carries a citation or a domain marker. */
-function isTagged(text: string): boolean {
-  return /\[@[a-z0-9]/i.test(text) || /<!--\s*domain:/i.test(text);
-}
-
 // --- glyph regex for weak-local --------------------------------------
 
 function glyphMatcher(latex: string): RegExp | undefined {
@@ -274,35 +249,6 @@ function checkConventionSingleDefinition(
   }
 }
 
-function checkNumeralsTagged(
-  input: ConsistencyInput,
-  out: ConsistencyDiagnostic[],
-): void {
-  for (const lesson of input.notationInput.lessons) {
-    if (input.lintIgnore.matches('numerals-tagged', lesson.lessonId)) continue;
-    let math = 0;
-    for (const span of mathSpans(lesson.body)) {
-      if (isTagged(span.latex)) continue;
-      math += numeralCount(span.latex);
-    }
-    let table = 0;
-    for (const row of tableRows(lesson.body)) {
-      if (isTagged(row)) continue;
-      table += numeralCount(row.replace(/\$[^$\n]*\$/g, ' '));
-    }
-    const count = math + table;
-    if (count === 0) continue;
-    out.push({
-      code: 'numerals-tagged',
-      severity: 'warning',
-      lessonId: lesson.lessonId,
-      file: lesson.source.file,
-      count,
-      message: `${lesson.lessonId}: ${count} numeral(s) in $…$ / result tables (${math} in math, ${table} in tables) are not tagged to a src/domain/ call or a source locator`,
-    });
-  }
-}
-
 function checkWeakLocal(
   input: ConsistencyInput,
   out: ConsistencyDiagnostic[],
@@ -317,7 +263,7 @@ function checkWeakLocal(
       if (uses > 1) continue;
       out.push({
         code: 'weak-local',
-        severity: 'warning',
+        severity: 'info',
         lessonId: lesson.lessonId,
         file: lesson.source.file,
         key: definition.key,
@@ -390,7 +336,7 @@ function checkGlossWantsPromoting(
     if (input.lintIgnore.matches('gloss-wants-promoting', glyph)) continue;
     out.push({
       code: 'gloss-wants-promoting',
-      severity: 'warning',
+      severity: 'info',
       glyph,
       message: `gloss ${JSON.stringify(glyph)} (${label}) is declared on ${keys.size} entries (${[...keys].sort().join(', ')}); a meaning reused this widely wants promoting to a card`,
     });
@@ -425,7 +371,7 @@ function checkCardWantsDemoting(
     }
     out.push({
       code: 'card-wants-demoting',
-      severity: 'warning',
+      severity: 'info',
       key: definition.key,
       file: definition.source.file,
       count: words,
@@ -627,7 +573,6 @@ const CHECKS: ((
   checkGlyphUniqueness,
   checkNotationUnits,
   checkConventionSingleDefinition,
-  checkNumeralsTagged,
   checkWeakLocal,
   checkNotationSourceLocator,
   checkGlossWantsPromoting,
@@ -666,7 +611,6 @@ export function consistencyCounts(
     'notation-units': 0,
     'units-vocab': 0,
     'convention-single-definition': 0,
-    'numerals-tagged': 0,
     'weak-local': 0,
     'notation-source-locator': 0,
     'gloss-wants-promoting': 0,