explico 0.2.0 → 0.3.0

package/src/reference/remark-notation.mjs

@@ -42,6 +42,11 @@ import {
   parseEquationRef,
   stripEquationLabels,
 } from './equations.mjs';
+import {
+  collectKeyedJsxFloats,
+  keyedFloatAnchorId,
+  parseKeyedFloatRef,
+} from './keyed-jsx-floats.mjs';
 
 const PROSE_SKIP_TYPES = new Set([
   'code',
@@ -340,6 +345,8 @@ function equationNode(mathNode, { key, number }) {
             className: ['keyed-equation__number'],
             'data-eq-number': number,
             'aria-label': `Equation ${number}`,
+            // Plain hover tooltip — the number is a permalink to this equation.
+            title: 'Anchor to this equation',
           },
         },
       },
@@ -347,6 +354,32 @@ function equationNode(mathNode, { key, number }) {
   };
 }
 
+/**
+ * Give a `<Table>`/`<Figure>` `mdxJsxFlowElement` its computed `number` and
+ * `anchorId` as real JSX attributes, so the actual Astro component (which
+ * renders the numbered anchor, unlike `equationNode`'s synthesized hast div)
+ * receives them as props. The compiler is the single source of truth for
+ * both — the component only renders what it's given.
+ */
+function injectFloatNumberAttributes(node, float, prefix) {
+  const anchorId = keyedFloatAnchorId({
+    key: float.key,
+    number: float.number,
+    prefix,
+  });
+  node.attributes = (node.attributes ?? []).filter(
+    (attribute) =>
+      !(
+        attribute?.type === 'mdxJsxAttribute' &&
+        (attribute.name === 'number' || attribute.name === 'anchorId')
+      ),
+  );
+  node.attributes.push(
+    { type: 'mdxJsxAttribute', name: 'number', value: float.number },
+    { type: 'mdxJsxAttribute', name: 'anchorId', value: anchorId },
+  );
+}
+
 /** Resolve a `[[eq-key]]` / `[[slug#eq-key]]` reference to `{ number, href }`. */
 function resolveEquationRef(eqRef, eqCtx, file, node) {
   if (eqRef.lesson) {
@@ -374,7 +407,47 @@ function resolveEquationRef(eqRef, eqCtx, file, node) {
   return { number, href: `#eq-${eqRef.key}` };
 }
 
-function proseNodes(value, resolve, file, node, references, eqCtx) {
+/**
+ * Resolve a `[[<prefix>-key]]` / `[[slug#<prefix>-key]]` reference (a
+ * `<Table>`/`<Figure>` float) to `{ number, href }` — the table/figure
+ * equivalent of `resolveEquationRef`.
+ */
+function resolveKeyedFloatRef(floatRef, ctx, { prefix, tagName }, file, node) {
+  if (floatRef.lesson) {
+    const number = ctx.crossPage?.[floatRef.lesson]?.[floatRef.key];
+    if (number === undefined) {
+      fail(
+        file,
+        `Unknown ${tagName} reference [[${floatRef.lesson}#${prefix}-${floatRef.key}]]: lesson ${floatRef.lesson} has no <${tagName}> with id="${floatRef.key}".`,
+        node,
+      );
+    }
+    return {
+      number,
+      href: `${ctx.base.replace(/\/$/, '')}/${floatRef.lesson}/#${prefix}-${floatRef.key}`,
+    };
+  }
+  const number = ctx.pageLabels.get(floatRef.key);
+  if (number === undefined) {
+    fail(
+      file,
+      `Unknown ${tagName} reference [[${prefix}-${floatRef.key}]]: no <${tagName}> on this page carries id="${floatRef.key}".`,
+      node,
+    );
+  }
+  return { number, href: `#${prefix}-${floatRef.key}` };
+}
+
+function proseNodes(
+  value,
+  resolve,
+  file,
+  node,
+  references,
+  eqCtx,
+  tableCtx,
+  figureCtx,
+) {
   const base = eqCtx?.base ?? '';
   const strayExplain = firstUnescaped(value, EXPLAIN);
   if (strayExplain !== -1) {
@@ -395,7 +468,18 @@ function proseNodes(value, resolve, file, node, references, eqCtx) {
 
     const key = match[1].trim();
     const eqRef = eqCtx ? parseEquationRef(key) : undefined;
-    if (!eqRef && !NOTATION_KEY_PATTERN.test(key)) {
+    const tableRef =
+      !eqRef && tableCtx ? parseKeyedFloatRef(key, { prefix: 'tab' }) : undefined;
+    const figureRef =
+      !eqRef && !tableRef && figureCtx
+        ? parseKeyedFloatRef(key, { prefix: 'fig' })
+        : undefined;
+    if (
+      !eqRef &&
+      !tableRef &&
+      !figureRef &&
+      !NOTATION_KEY_PATTERN.test(key)
+    ) {
       fail(file, `Invalid notation key "${key}" in [[...]].`, node);
     }
 
@@ -426,9 +510,46 @@ function proseNodes(value, resolve, file, node, references, eqCtx) {
       continue;
     }
 
+    const floatRef = tableRef ?? figureRef;
+    if (floatRef) {
+      const kind = tableRef ? 'table' : 'figure';
+      const prefix = tableRef ? 'tab' : 'fig';
+      const tagName = tableRef ? 'Table' : 'Figure';
+      const { number, href } = resolveKeyedFloatRef(
+        floatRef,
+        tableRef ? tableCtx : figureCtx,
+        { prefix, tagName },
+        file,
+        node,
+      );
+      output.push({
+        type: 'link',
+        url: href,
+        children: [{ type: 'text', value: `${tagName} ${number}` }],
+        data: {
+          hProperties: {
+            className: [`${kind}-ref`],
+            [`data-${prefix}-ref`]: floatRef.key,
+            ...(floatRef.lesson ? { [`data-${prefix}-lesson`]: floatRef.lesson } : {}),
+          },
+        },
+      });
+      references.push({
+        key: floatRef.key,
+        kind,
+        ...(floatRef.lesson ? { lesson: floatRef.lesson } : {}),
+      });
+      cursor = match.index + match[0].length;
+      continue;
+    }
+
     const definition = resolve(key, 'prose', node);
-    const title = definition?.title ?? key;
-    const summary = definition?.summary;
+    // `title`/`summary` are the pre-C1b field names, kept as the first
+    // fallback for a caller still supplying them; real content authors
+    // `label`/`meaning` (see `content-config.ts`), which raw frontmatter
+    // (`manifest.notation.raw`, a page's own `notation.local`) carries as-is.
+    const title = definition?.title ?? definition?.label ?? key;
+    const summary = definition?.summary ?? definition?.meaning;
     const href = defaultHref(definition, key, base);
 
     const properties = {
@@ -557,7 +678,16 @@ function inspectExplainCalls(value, resolve, file, node, references) {
  *   unknown?: 'error' | 'warn' | 'ignore',
  *   base?: string,
  *   equations?: Record<string, Record<string, string>>,
+ *   tables?: Record<string, Record<string, string>>,
+ *   figures?: Record<string, Record<string, string>>,
+ *   chapters?: Record<string, number>,
  * }} [options]
+ *
+ * `chapters` maps a lesson slug to its 1-based course ordinal. When the
+ * current page has one, every display equation / `<Table>` / `<Figure>` is
+ * numbered `‹chapter›.‹n›` (`##` headings ignored); with no entry the legacy
+ * `##`-section scheme applies. It must agree with `manifest.lessons[].chapter`,
+ * which is what feeds `equations`/`tables`/`figures` above.
  */
 export default function remarkNotation(options = {}) {
   const unknown = options.unknown ?? 'error';
@@ -573,6 +703,10 @@ export default function remarkNotation(options = {}) {
     );
     const localDefinitions = localDefinitionsFromFile(file);
     const lessonId = lessonIdFrom(file);
+    // The lesson's course ordinal (see the `chapters` option). Falsy / missing
+    // ⇒ the legacy `##`-section numbering, so `0` and `undefined` behave alike.
+    const chapter =
+      (lessonId && options.chapters?.[lessonId.replace(/\./g, '/')]) || undefined;
     const registryFile = isNotationRegistryFile(file);
     const mathScope = pageGlyphScope(
       localDefinitions,
@@ -582,10 +716,10 @@ export default function remarkNotation(options = {}) {
     const references = [];
     const resolved = new Map();
 
-    // Equation identity (D7): assign every `\label{eq:…}` its section-scoped
-    // number before any math node is rewritten, so a `[[eq-key]]` earlier in
-    // the page still resolves.
-    const equationLabels = collectEquationLabels(tree);
+    // Equation identity (D7): assign every `\label{eq:…}` its number before any
+    // math node is rewritten, so a `[[eq-key]]` earlier in the page still
+    // resolves. `chapter` picks the `‹chapter›.‹n›` vs `##`-section scheme.
+    const equationLabels = collectEquationLabels(tree, chapter);
     const pageLabels = new Map();
     for (const label of equationLabels) {
       if (pageLabels.has(label.key)) {
@@ -606,11 +740,50 @@ export default function remarkNotation(options = {}) {
     // Number and anchor every display equation on a lesson page, keyed or
     // not (F3). Non-lesson pages (notation registry, stray docs) keep the
     // keyed-only behaviour so their body math is left untouched.
-    const displayEquations = lessonId ? collectDisplayEquations(tree) : [];
+    const displayEquations = lessonId
+      ? collectDisplayEquations(tree, chapter)
+      : [];
     const equationByNode = new Map(
       displayEquations.map((equation) => [equation.node, equation]),
     );
 
+    // Keyed floats (F-tables-figures): every `<Table>`/`<Figure>` on a lesson
+    // page is numbered and anchored, keyed or not — same rule as equations,
+    // via the shared engine in `keyed-jsx-floats.mjs`.
+    const makeFloatCtx = (tagName, crossPage) => {
+      const floats = lessonId
+        ? collectKeyedJsxFloats(tree, { tagName, chapter })
+        : [];
+      const pageFloatLabels = new Map();
+      for (const float of floats) {
+        if (float.key == null) continue;
+        if (pageFloatLabels.has(float.key)) {
+          fail(
+            file,
+            `Duplicate <${tagName} id="${float.key}"> on this page; an id is unique per lesson.`,
+            float.node,
+          );
+        }
+        pageFloatLabels.set(float.key, float.number);
+      }
+      return {
+        ctx: {
+          base: options.base ?? '',
+          pageLabels: pageFloatLabels,
+          crossPage: crossPage ?? {},
+        },
+        byNode: new Map(floats.map((float) => [float.node, float])),
+      };
+    };
+    const { ctx: tableCtx, byNode: tableByNode } = makeFloatCtx(
+      'Table',
+      options.tables,
+    );
+    const { ctx: figureCtx, byNode: figureByNode } = makeFloatCtx(
+      'Figure',
+      options.figures,
+    );
+
     const resolve = (key, kind, node) => {
       const context = {
         file,
@@ -729,6 +902,8 @@ export default function remarkNotation(options = {}) {
             child,
             references,
             eqCtx,
+            tableCtx,
+            figureCtx,
           );
           if (replacement) {
             node.children.splice(index, 1, ...replacement);
@@ -739,6 +914,10 @@ export default function remarkNotation(options = {}) {
         visit(child, false);
         if (child && child.type === 'math' && equationByNode.has(child)) {
           node.children[index] = equationNode(child, equationByNode.get(child));
+        } else if (child?.type === 'mdxJsxFlowElement' && tableByNode.has(child)) {
+          injectFloatNumberAttributes(child, tableByNode.get(child), 'tab');
+        } else if (child?.type === 'mdxJsxFlowElement' && figureByNode.has(child)) {
+          injectFloatNumberAttributes(child, figureByNode.get(child), 'fig');
         }
       }
     };
@@ -755,5 +934,16 @@ export default function remarkNotation(options = {}) {
         indexInSection,
       }),
     );
+    const floatLabelData = (byNode) =>
+      [...byNode.values()]
+        .filter((float) => float.key != null)
+        .map(({ key, number, section, indexInSection }) => ({
+          key,
+          number,
+          section,
+          indexInSection,
+        }));
+    file.data.tableLabels = floatLabelData(tableByNode);
+    file.data.figureLabels = floatLabelData(figureByNode);
   };
 }

package/src/reference/tables-validate.ts

@@ -0,0 +1,40 @@
+/** `validateKeyedFloats` for `<Table>` — see `keyed-float-validate.ts`. */
+
+import {
+  validateKeyedFloats,
+  type KeyedFloatLabelRecord,
+  type KeyedFloatLessonInput,
+  type KeyedFloatValidation,
+} from './keyed-float-validate';
+
+export type TableDiagnosticCode =
+  | 'tab-invalid-key'
+  | 'tab-duplicate-key'
+  | 'tab-ref-resolves'
+  | 'tab-key-unused';
+
+export interface TableDiagnostic {
+  readonly code: TableDiagnosticCode;
+  readonly severity: 'error' | 'warning';
+  readonly message: string;
+  readonly file?: string;
+  readonly lessonId?: string;
+  readonly key?: string;
+}
+
+export type TableLabelRecord = KeyedFloatLabelRecord;
+export type TableLessonInput = KeyedFloatLessonInput;
+
+export interface TableValidation extends KeyedFloatValidation {
+  readonly diagnostics: readonly TableDiagnostic[];
+}
+
+export function validateTables(
+  lessons: readonly TableLessonInput[],
+): TableValidation {
+  return validateKeyedFloats(lessons, {
+    tagName: 'Table',
+    prefix: 'tab',
+    noun: 'table',
+  }) as TableValidation;
+}

package/src/reference/units-vocab.ts

@@ -118,6 +118,24 @@ export const UNITS_VOCAB: ReadonlySet<string> = new Set([
   'quoted',
   'explicitly',
   'calculations',
+  // motion / physical quantities (playground corpus)
+  'meter',
+  'meters',
+  'second',
+  'seconds',
+  'speed',
+  'velocity',
+  'acceleration',
+  'gravitational',
+  'launch',
+  'angle',
+  'degrees',
+  'horizontal',
+  'vertical',
+  'level',
+  'ground',
+  'squared',
+  'above',
 ]);
 
 /** Lowercase word tokens of a `units` string (split on whitespace and hyphens). */

package/src/styles/global.css

@@ -668,7 +668,7 @@
    `.keyed-equation` with an `id="eq-<key>"`, a `data-eq-number`, and a
    focusable number link. Prose refers to it with `[[eq:key]]` →
    `a.equation-ref`. The deep-link highlight is a pure-CSS `:target` animation
-   with a reduced-motion fallback; `EquationEnhancer.astro` only re-triggers it
+   with a reduced-motion fallback; `KeyedFloatEnhancer.astro` only re-triggers it
    on a repeated activation and moves focus. */
 .sl-markdown-content .keyed-equation {
   position: relative;
@@ -690,12 +690,11 @@
   font-size: var(--sl-text-sm);
   color: var(--sl-color-text-accent);
   text-decoration: none;
-  /* Hardly visible until you look for it (F3): transparent by default, so it
-     never competes with the equation, and — being `opacity:0`, not `hidden` —
-     still announced to assistive tech and revealed on hover/focus/deep-link.
-     A partial opacity would fail the WCAG contrast check, so it is all or
-     nothing, mirroring Starlight's own heading anchor links. */
-  opacity: 0;
+  /* Present but quiet by default (F4): partially visible so a reader
+     scanning the page can always find the number without hunting, but it
+     still doesn't compete with the equation itself. Hover, focus, and a
+     deep-link (`:target`) push it to full opacity, same as before. */
+  opacity: 0.45;
   transition: opacity 120ms ease-out;
 }
 
@@ -726,6 +725,41 @@
   }
 }
 
+/* Once a reader has actually arrived at (or clicked through to) an equation —
+   a deep-link on load, an in-page `[[eq:key]]` navigation, or pinning its
+   preview card (`FloatRefLayer.astro`) — its number stays fully visible
+   for the rest of the page's life, not just while `:target` or `:hover`
+   holds. `KeyedFloatEnhancer.astro` and `FloatRefLayer.astro` add this class
+   in JS; it is never present in the static markup. One extra class over the
+   base selector's specificity, so this always wins regardless of rule order. */
+.sl-markdown-content a.keyed-equation__number.eq-number-revealed {
+  opacity: 1;
+}
+
+/* A referencing `[[eq:key]]` link elsewhere in the prose was hovered/focused
+   and the equation it points to is already fully on screen: highlight it in
+   place instead of opening a preview card (`FloatRefLayer.astro` decides
+   which). Mirrors the reduced-motion `:target` treatment below — steady, no
+   keyframe — since this fires on every hover, not just a rare deep-link. */
+.sl-markdown-content .keyed-equation.eq-ref-highlight {
+  background: var(--sl-color-accent-low);
+  outline: 2px solid var(--sl-color-accent);
+  outline-offset: 0.2rem;
+  transition:
+    background 120ms ease-out,
+    outline-color 120ms ease-out;
+}
+
+.sl-markdown-content .keyed-equation.eq-ref-highlight a.keyed-equation__number {
+  opacity: 1;
+}
+
+@media (forced-colors: active) {
+  .sl-markdown-content .keyed-equation.eq-ref-highlight {
+    outline-color: Highlight;
+  }
+}
+
 .sl-markdown-content a.equation-ref {
   font-variant-numeric: tabular-nums;
   font-weight: 600;
@@ -785,12 +819,86 @@
     transform: none;
     text-align: end;
     color: inherit;
+    opacity: 1;
   }
   .sl-markdown-content .keyed-equation {
     padding-inline-end: 0;
   }
 }
 
+/* `<Table>`/`<Figure>` keyed floats (F-tables-figures) — the same deep-link
+   and hover-highlight treatment as equations above, via `KeyedFloatEnhancer`
+   and `FloatRefLayer.astro`. Unlike an equation's number (quiet until
+   hovered, F4), a table/figure number lives in its always-visible caption,
+   so there is no opacity dance to mirror here — only the `:target` flash
+   (reusing the `eq-flash` keyframe above) and the ref-highlight. */
+.sl-markdown-content a.table-ref,
+.sl-markdown-content a.figure-ref {
+  font-variant-numeric: tabular-nums;
+  font-weight: 600;
+  text-decoration: underline;
+  text-underline-offset: 0.15em;
+  padding-inline: 0.1em;
+  border-radius: 0.2em;
+  color: var(--sl-color-text-accent);
+  white-space: nowrap;
+}
+
+.sl-markdown-content a.table-ref:hover,
+.sl-markdown-content a.table-ref:focus-visible,
+.sl-markdown-content a.figure-ref:hover,
+.sl-markdown-content a.figure-ref:focus-visible {
+  background: var(--sl-color-accent-low);
+}
+
+.sl-markdown-content .keyed-table:target,
+.sl-markdown-content .keyed-figure:target {
+  animation: eq-flash 5s ease-out both;
+  border-radius: 0.3rem;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .sl-markdown-content .keyed-table:target,
+  .sl-markdown-content .keyed-figure:target {
+    animation: none;
+    background: var(--sl-color-accent-low);
+    outline: 2px solid var(--sl-color-accent);
+    outline-offset: 0.2rem;
+  }
+}
+
+/* A referencing `[[tab-key]]`/`[[fig-key]]` link elsewhere in the prose was
+   hovered/focused and the float it points to is already fully on screen:
+   highlight it in place instead of opening a preview card
+   (`FloatRefLayer.astro` decides which) — mirrors `.eq-ref-highlight`. */
+.sl-markdown-content .keyed-table.tab-ref-highlight,
+.sl-markdown-content .keyed-figure.fig-ref-highlight {
+  background: var(--sl-color-accent-low);
+  outline: 2px solid var(--sl-color-accent);
+  outline-offset: 0.2rem;
+  border-radius: 0.3rem;
+  transition:
+    background 120ms ease-out,
+    outline-color 120ms ease-out;
+}
+
+@media (forced-colors: active) {
+  .sl-markdown-content .keyed-table:target,
+  .sl-markdown-content .keyed-figure:target,
+  .sl-markdown-content .keyed-table.tab-ref-highlight,
+  .sl-markdown-content .keyed-figure.fig-ref-highlight {
+    animation: none;
+    outline: 2px solid Highlight;
+    outline-offset: 0.2rem;
+  }
+  .sl-markdown-content a.table-ref:hover,
+  .sl-markdown-content a.table-ref:focus-visible,
+  .sl-markdown-content a.figure-ref:hover,
+  .sl-markdown-content a.figure-ref:focus-visible {
+    outline: 2px solid Highlight;
+  }
+}
+
 /* Deep-linkable content headings (F3). The wrapper + anchor-link markup and its
    hover/focus reveal come from Starlight's bundled `anchor-links.css`; these
    rules add the sticky-header scroll offset and the `:target` flash, mirroring

package/src/components/starlight/EquationEnhancer.astro

@@ -1,87 +0,0 @@
----
-/**
- * Progressive enhancement for keyed equations (Step D7).
- *
- * The no-JS baseline is complete: `remark-notation` emits a real `id="eq-<key>"`
- * container, a focusable number `<a>`, and `[[eq:key]]` renders a plain anchor;
- * `global.css` does the `:target` deep-link highlight (with a
- * `prefers-reduced-motion` fallback) and the sticky-header scroll offset via
- * `scroll-margin`.
- *
- * This script only adds what CSS and anchors cannot:
- *  - a smooth, header-aware scroll on an in-page jump;
- *  - re-triggering the highlight when the same `#eq-…` is activated again —
- *    the one case a plain anchor click does nothing for, since the browser
- *    won't navigate to a fragment that's already current;
- *  - moving keyboard focus onto the equation so screen-reader users land on it.
- *
- * It deliberately does *not* intercept an ordinary click that changes the
- * hash. `:target` is set only by a genuine same-document fragment
- * navigation — never by `history.pushState` (a common trap: pushState
- * updates the URL but leaves `:target`, and thus `eq-flash`, dark). Letting
- * the click through and reacting to the `hashchange` it produces is what
- * actually plays the highlight.
- *
- * Everything here is gated on `prefers-reduced-motion` and degrades to the
- * native anchor behaviour if it throws.
- */
----
-
-<script>
-  (() => {
-    const root = document.querySelector('.sl-markdown-content');
-    if (!root) return;
-
-    const reduce = window.matchMedia('(prefers-reduced-motion: reduce)');
-
-    const activate = (target: HTMLElement | null, doScroll: boolean) => {
-      if (!target) return;
-      if (!reduce.matches) {
-        // Restart the CSS `:target` animation even when the hash is unchanged.
-        target.style.animation = 'none';
-        void target.offsetWidth;
-        target.style.removeProperty('animation');
-      }
-      if (doScroll) {
-        target.scrollIntoView({
-          behavior: reduce.matches ? 'auto' : 'smooth',
-          block: 'start',
-        });
-      }
-      target.setAttribute('tabindex', '-1');
-      try {
-        target.focus({ preventScroll: true });
-      } catch {
-        target.focus();
-      }
-    };
-
-    root.addEventListener('click', (event) => {
-      const origin = event.target instanceof Element ? event.target : null;
-      const link = origin?.closest('a.equation-ref, a.keyed-equation__number');
-      if (!link) return;
-      const href = link.getAttribute('href') || '';
-      if (!href.startsWith('#eq-')) return; // cross-page: let the browser navigate
-      const target = document.getElementById(href.slice(1));
-      if (!target) return;
-      // Only the already-on-this-anchor click needs handling here — the
-      // browser has nothing new to navigate to, so it won't fire `hashchange`
-      // and nothing else will re-trigger the flash. Every other click is left
-      // alone: its native navigation sets `:target` and fires `hashchange`,
-      // which the listener below turns into the same `activate()`.
-      if (location.hash === href) {
-        event.preventDefault();
-        activate(target, true);
-      }
-    });
-
-    window.addEventListener('hashchange', () => {
-      if (!location.hash.startsWith('#eq-')) return;
-      activate(document.getElementById(location.hash.slice(1)), true);
-    });
-
-    if (location.hash.startsWith('#eq-')) {
-      activate(document.getElementById(location.hash.slice(1)), true);
-    }
-  })();
-</script>