explico 0.1.0 → 0.2.0

package/src/reference/registry.ts

@@ -58,6 +58,8 @@ export function buildNotationRegistry(
   );
   const availableDefinitionIds = new Set(definitions.keys());
 
+  validateGlossKeys(definitions, diagnostics);
+
   // `notation.uses` is retired (D1 decision): a lesson pulls a shared key into
   // scope by referencing it (`[[key]]`/`\explain`), and every reference resolves
   // directly against page-local then shared definitions.
@@ -411,6 +413,43 @@ function normalizeLocalDefinition(
   };
 }
 
+/**
+ * A gloss key is derived as `<card key>.<slug(name)>`, so it is entry-scoped
+ * and cannot clash with another card's glosses. It can still collide with a
+ * **card** whose own key happens to take that shape — and a colliding key
+ * would make the same string mean two things in the flat glyph table, which
+ * is exactly what the semantic-key design exists to prevent. Tier 1.
+ *
+ * This is also the promotion boundary: promoting a gloss means deleting the
+ * gloss line *and* adding the card. Leaving both in place fails here rather
+ * than resolving to whichever the table saw first.
+ */
+function validateGlossKeys(
+  definitions: ReadonlyMap<string, DefinitionCandidate>,
+  diagnostics: NotationDiagnostic[],
+): void {
+  const cardKeys = new Set(
+    [...definitions.values()].map((candidate) => candidate.input.key),
+  );
+
+  for (const candidate of definitions.values()) {
+    for (const gloss of candidate.input.glosses) {
+      if (!cardKeys.has(gloss.key)) continue;
+      diagnostics.push(
+        diagnostic({
+          code: 'gloss-collides-with-card',
+          message: `${candidate.id} glosses ${JSON.stringify(gloss.label)} as ${gloss.key}, which is also a notation card; delete the gloss or rename it`,
+          key: gloss.key,
+          lessonId:
+            candidate.kind === 'local' ? candidate.lesson.lessonId : undefined,
+          definitionId: candidate.id,
+          source: candidate.input.source,
+        }),
+      );
+    }
+  }
+}
+
 function validateReferenceKey(
   reference: NotationReferenceInput,
   owner: DefinitionCandidate,
@@ -503,6 +542,7 @@ function toDefinitionRecord(
       status: input.status,
       aiAssisted: input.aiAssisted,
       body: input.body,
+      glosses: input.glosses,
       source: input.source,
       resolvedReferences: candidate.resolvedReferences,
       ...(input.formula === undefined ? {} : { formula: input.formula }),
@@ -525,6 +565,7 @@ function toDefinitionRecord(
     seeAlso: input.seeAlso,
     alignment: input.alignment,
     status: candidate.lesson.status,
+    glosses: input.glosses,
     source: input.source,
     resolvedReferences: candidate.resolvedReferences,
     ...(input.formula === undefined ? {} : { formula: input.formula }),
@@ -570,6 +611,7 @@ function definitionFingerprint(candidate: DefinitionCandidate): string {
       status: input.status,
       aiAssisted: input.aiAssisted,
       body: normalizeText(input.body),
+      glosses: input.glosses,
       references,
     });
   }
@@ -586,6 +628,7 @@ function definitionFingerprint(candidate: DefinitionCandidate): string {
     sources: [...input.sources].sort(),
     seeAlso: [...input.seeAlso].sort(),
     alignment,
+    glosses: input.glosses,
     references,
   });
 }

package/src/reference/rehype-heading-anchors.mjs

@@ -0,0 +1,144 @@
+/**
+ * Deep-linkable content headings (Step F3).
+ *
+ * The lesson pipeline uses a custom Markdown `processor` (see `astro.config.mjs`),
+ * which bypasses Starlight's own heading-link rehype pass. This plugin restores
+ * it with the *same* markup Starlight emits, so its bundled `anchor-links.css`
+ * (shipped globally because `markdown.headingLinks` defaults on) styles it for
+ * free — including the hover/focus reveal of an otherwise invisible anchor:
+ *
+ *   <div class="sl-heading-wrapper level-h2">
+ *     <h2 id="slug">Heading</h2>
+ *     <a class="sl-anchor-link" href="#slug"> <icon> <sr-only label> </a>
+ *   </div>
+ *
+ * The `:target` flash, sticky-header scroll offset, and the JS niceties
+ * (re-trigger on repeat activation, smooth scroll, `history.pushState`, brief
+ * section highlight) live in `global.css` + `HeadingAnchorEnhancer.astro`, the
+ * same split the keyed-equation feature uses.
+ *
+ * `rehypeHeadingIds` from `@astrojs/markdown-remark` normally runs *after* the
+ * user rehype plugins, so heading `id`s do not exist yet when this runs. It is
+ * idempotent (only assigns a missing `id`, and rebuilds `file.data.astro.headings`
+ * from an unchanged document order), so this plugin runs it first and Astro's
+ * later pass becomes a no-op for these headings.
+ */
+
+import { rehypeHeadingIds } from '@astrojs/markdown-remark';
+
+const HEADING_TAG = /^h([1-6])$/;
+
+// Starlight's `link-alt` icon (`components-internals/Icons.ts`), the same glyph
+// its own `rehypeAutolinkHeadings` uses.
+const LINK_ICON_PATH =
+  'm12.11 15.39-3.88 3.88a2.52 2.52 0 0 1-3.5 0 2.47 2.47 0 0 1 0-3.5l3.88-3.88a1 1 0 1 0-1.42-1.42l-3.88 3.89a4.48 4.48 0 0 0 6.33 6.33l3.89-3.88a1 1 0 0 0-1.42-1.42m8.58-12.08a4.49 4.49 0 0 0-6.33 0l-3.89 3.88a1 1 0 1 0 1.42 1.42l3.88-3.88a2.52 2.52 0 0 1 3.5 0 2.47 2.47 0 0 1 0 3.5l-3.88 3.88a1 1 0 0 0 0 1.42 1 1 0 0 0 1.42 0l3.88-3.89a4.49 4.49 0 0 0 0-6.33M8.83 15.17a1 1 0 0 0 .71.29 1 1 0 0 0 .71-.29l4.92-4.92a1 1 0 1 0-1.42-1.42l-4.92 4.92a1 1 0 0 0 0 1.42';
+
+function headingText(node) {
+  let text = '';
+  const walk = (current) => {
+    if (!current || typeof current !== 'object') return;
+    if (current.type === 'text' || current.type === 'raw') {
+      text += String(current.value ?? '');
+      return;
+    }
+    if (Array.isArray(current.children)) current.children.forEach(walk);
+  };
+  walk(node);
+  return text.replace(/\s+/g, ' ').trim();
+}
+
+function isHeadingWrapper(node) {
+  const className = node?.properties?.className;
+  return (
+    node?.type === 'element' &&
+    Array.isArray(className) &&
+    className.includes('sl-heading-wrapper')
+  );
+}
+
+function anchorLink(id, label) {
+  return {
+    type: 'element',
+    tagName: 'a',
+    properties: { className: ['sl-anchor-link'], href: `#${id}` },
+    children: [
+      {
+        type: 'element',
+        tagName: 'span',
+        properties: { ariaHidden: 'true', className: ['sl-anchor-icon'] },
+        children: [
+          {
+            type: 'element',
+            tagName: 'svg',
+            properties: {
+              width: 16,
+              height: 16,
+              viewBox: '0 0 24 24',
+              fill: 'currentColor',
+            },
+            children: [
+              {
+                type: 'element',
+                tagName: 'path',
+                properties: { d: LINK_ICON_PATH },
+                children: [],
+              },
+            ],
+          },
+        ],
+      },
+      {
+        type: 'element',
+        tagName: 'span',
+        properties: { className: ['sr-only'], 'data-pagefind-ignore': 'true' },
+        children: [{ type: 'text', value: label }],
+      },
+    ],
+  };
+}
+
+export default function rehypeHeadingAnchors() {
+  const assignHeadingIds = rehypeHeadingIds();
+
+  return function transform(tree, file) {
+    assignHeadingIds(tree, file);
+
+    const walk = (node) => {
+      if (!node || typeof node !== 'object' || !Array.isArray(node.children)) {
+        return;
+      }
+      if (isHeadingWrapper(node)) return; // already processed
+
+      for (let index = 0; index < node.children.length; index++) {
+        const child = node.children[index];
+        const tag =
+          child?.type === 'element' && typeof child.tagName === 'string'
+            ? HEADING_TAG.exec(child.tagName)
+            : null;
+
+        if (
+          tag &&
+          tag[1] !== '1' &&
+          typeof child.properties?.id === 'string' &&
+          child.properties.id.length > 0
+        ) {
+          const id = child.properties.id;
+          const label = `Section titled “${headingText(child)}”`;
+          node.children[index] = {
+            type: 'element',
+            tagName: 'div',
+            properties: {
+              className: ['sl-heading-wrapper', `level-${child.tagName}`],
+            },
+            children: [child, anchorLink(id, label)],
+          };
+          continue; // the heading is a leaf for our purposes
+        }
+
+        walk(child);
+      }
+    };
+
+    walk(tree);
+  };
+}

package/src/reference/remark-notation.mjs

@@ -36,7 +36,9 @@ export const NOTATION_KEY_PATTERN = /^[a-z0-9]+(?:[.-][a-z0-9]+)*$/;
 import { GlyphResolutionError, resolveMathGlyphs } from './math-glyphs.mjs';
 import {
   EQ_LABEL_PATTERN,
+  collectDisplayEquations,
   collectEquationLabels,
+  equationAnchorId,
   parseEquationRef,
   stripEquationLabels,
 } from './equations.mjs';
@@ -307,28 +309,31 @@ function defaultHref(definition, key, base = '') {
 }
 
 /**
- * Wrap a keyed `$$…$$` `math` node so the container survives `rehype-katex`
- * (which splices the inner `math-display` element out). The visible number is
- * a focusable `<a>` sibling — never authored, never inside KaTeX — so it
- * survives print and screen readers name it "Equation 2.4".
+ * Wrap a display `$$…$$` `math` node so the container survives `rehype-katex`
+ * (which splices the inner `math-display` element out). Every display equation
+ * in a lesson is numbered; a keyed one anchors at `#eq-<key>`, an unkeyed one
+ * at its positional `#eq-<section>-<index>`. The visible number is a focusable
+ * `<a>` sibling — never authored, never inside KaTeX — so it survives print and
+ * screen readers name it "Equation 2.4".
  */
-function keyedEquationNode(mathNode, key, number) {
+function equationNode(mathNode, { key, number }) {
+  const id = equationAnchorId({ key, number });
+  const hProperties = {
+    id,
+    className: ['keyed-equation'],
+    'data-eq-number': number,
+  };
+  if (key) hProperties['data-eq-key'] = key;
+  else hProperties['data-eq-auto'] = '';
+
   return {
     type: 'paragraph',
-    data: {
-      hName: 'div',
-      hProperties: {
-        id: `eq-${key}`,
-        className: ['keyed-equation'],
-        'data-eq-key': key,
-        'data-eq-number': number,
-      },
-    },
+    data: { hName: 'div', hProperties },
     children: [
       mathNode,
       {
         type: 'link',
-        url: `#eq-${key}`,
+        url: `#${id}`,
         children: [{ type: 'text', value: `(${number})` }],
         data: {
           hProperties: {
@@ -598,6 +603,14 @@ export default function remarkNotation(options = {}) {
       crossPage: options.equations ?? {},
     };
 
+    // 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 equationByNode = new Map(
+      displayEquations.map((equation) => [equation.node, equation]),
+    );
+
     const resolve = (key, kind, node) => {
       const context = {
         file,
@@ -647,7 +660,6 @@ export default function remarkNotation(options = {}) {
               node,
             );
           }
-          node.__eqKey = labelMatch[1];
           value = stripEquationLabels(value);
           replaceMathSource(node, value);
         }
@@ -725,14 +737,8 @@ export default function remarkNotation(options = {}) {
           continue;
         }
         visit(child, false);
-        if (child && child.__eqKey) {
-          const key = child.__eqKey;
-          delete child.__eqKey;
-          node.children[index] = keyedEquationNode(
-            child,
-            key,
-            pageLabels.get(key),
-          );
+        if (child && child.type === 'math' && equationByNode.has(child)) {
+          node.children[index] = equationNode(child, equationByNode.get(child));
         }
       }
     };

package/src/reference/types.ts

@@ -21,6 +21,20 @@ export type NotationAlignment =
 
 export type NotationReferenceKind = 'prose' | 'math' | 'definition';
 
+/**
+ * A gloss resolved by the loader (D15). Declared on a card, keyed
+ * `<card key>.<slug(name)>`, and deliberately absent from the registry: a
+ * gloss is never a definition record, never a reference target, and never a
+ * curriculum node. See `reference/gloss.ts`.
+ */
+export interface NotationGlossEntry {
+  readonly key: string;
+  readonly notation: string;
+  readonly label: string;
+  readonly units?: string;
+  readonly ownerKey: string;
+}
+
 export interface NotationReferenceInput {
   readonly key: string;
   readonly kind: NotationReferenceKind;
@@ -44,6 +58,8 @@ export interface SharedNotationDefinitionInput {
   readonly body: string;
   /** References harvested from the Markdown body. */
   readonly references: readonly NotationReferenceInput[];
+  /** Symbols this entry's `formula` names but does not make cards of. */
+  readonly glosses: readonly NotationGlossEntry[];
   readonly source: SourceSpan;
 }
 
@@ -59,6 +75,8 @@ export interface LocalNotationDefinitionInput {
   readonly alignment: NotationAlignment;
   /** References harvested from summary content. */
   readonly references: readonly NotationReferenceInput[];
+  /** Symbols this entry's `formula` names but does not make cards of. */
+  readonly glosses: readonly NotationGlossEntry[];
   readonly source: SourceSpan;
 }
 
@@ -90,7 +108,8 @@ export type NotationDiagnosticCode =
   | 'alignment-unknown-lesson'
   | 'alignment-introduction'
   | 'alignment-unavailable'
-  | 'alignment-review-state';
+  | 'alignment-review-state'
+  | 'gloss-collides-with-card';
 
 export type DiagnosticSeverity = 'error' | 'warning';
 
@@ -120,6 +139,12 @@ export interface ResolvedNotationReference {
 interface NotationDefinitionRecordBase {
   readonly id: string;
   readonly key: string;
+  /**
+   * Symbols this entry's `formula` names but does not make cards of (D15).
+   * Carried on the record so the manifest can build the entry-scoped formula
+   * table; deliberately **not** a definition, a reference target, or an edge.
+   */
+  readonly glosses: readonly NotationGlossEntry[];
   readonly scope: NotationDefinitionScope;
   readonly notation: string;
   readonly label: string;

package/src/styles/global.css

@@ -690,13 +690,42 @@
   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;
+  transition: opacity 120ms ease-out;
 }
 
-.sl-markdown-content a.keyed-equation__number:hover,
+@media (hover: none) {
+  /* No hover to reveal it on touch, so keep the number legible there. */
+  .sl-markdown-content a.keyed-equation__number {
+    opacity: 1;
+  }
+}
+
+.sl-markdown-content .keyed-equation:hover a.keyed-equation__number,
+.sl-markdown-content .keyed-equation:focus-within a.keyed-equation__number,
+.sl-markdown-content .keyed-equation:target a.keyed-equation__number,
 .sl-markdown-content a.keyed-equation__number:focus-visible {
+  opacity: 1;
   text-decoration: underline;
 }
 
+@media (prefers-reduced-motion: reduce) {
+  .sl-markdown-content a.keyed-equation__number {
+    transition: none;
+  }
+}
+
+@media (forced-colors: active) {
+  .sl-markdown-content a.keyed-equation__number {
+    opacity: 1;
+  }
+}
+
 .sl-markdown-content a.equation-ref {
   font-variant-numeric: tabular-nums;
   font-weight: 600;
@@ -725,7 +754,7 @@
 }
 
 .sl-markdown-content .keyed-equation:target {
-  animation: eq-flash 3s ease-out both;
+  animation: eq-flash 5s ease-out both;
 }
 
 @media (prefers-reduced-motion: reduce) {
@@ -761,3 +790,56 @@
     padding-inline-end: 0;
   }
 }
+
+/* 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
+   the keyed-equation deep-link treatment. `HeadingAnchorEnhancer.astro` adds
+   the JS-only niceties (smooth scroll, repeat-activation re-trigger, and a
+   brief highlight of the section body). */
+.sl-markdown-content :is(h1, h2, h3, h4, h5, h6),
+.sl-markdown-content .sl-heading-wrapper {
+  scroll-margin-block-start: 5rem;
+}
+
+@keyframes heading-flash {
+  from {
+    background: var(--sl-color-accent-low);
+    box-shadow: 0 0 0 0.3rem var(--sl-color-accent-low);
+  }
+  to {
+    background: transparent;
+    box-shadow: 0 0 0 0.3rem transparent;
+  }
+}
+
+.sl-markdown-content :is(h1, h2, h3, h4, h5, h6):target,
+.sl-markdown-content .sl-heading-wrapper:has(> :target),
+.sl-markdown-content .deep-link-section-flash {
+  border-radius: 0.3rem;
+  /* `HeadingAnchorEnhancer.astro`'s `FLASH_MS` cleanup timeout must stay
+     comfortably longer than this so it never clips the fade-out. */
+  animation: heading-flash 5s ease-out both;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .sl-markdown-content :is(h1, h2, h3, h4, h5, h6):target,
+  .sl-markdown-content .sl-heading-wrapper:has(> :target) {
+    animation: none;
+    background: var(--sl-color-accent-low);
+    outline: 2px solid var(--sl-color-accent);
+    outline-offset: 0.2rem;
+  }
+  .sl-markdown-content .deep-link-section-flash {
+    animation: none;
+  }
+}
+
+@media (forced-colors: active) {
+  .sl-markdown-content :is(h1, h2, h3, h4, h5, h6):target,
+  .sl-markdown-content .sl-heading-wrapper:has(> :target) {
+    animation: none;
+    outline: 2px solid Highlight;
+    outline-offset: 0.2rem;
+  }
+}