explico 0.4.0 → 0.5.0

package/src/reference/page-notation.ts

@@ -0,0 +1,252 @@
+import type { Manifest, ManifestLessonNotation } from '../compiler/manifest';
+import {
+  formulaExplainKeys,
+  formulaGlyphScope,
+  type GlyphScopeEntry,
+} from './gloss';
+import { resolveReferenceId } from './references';
+import type { NotationDefinitionRecord } from './types';
+
+export interface PageNotationDependency {
+  readonly key: string;
+  readonly context: string;
+}
+
+interface StarlightLocals {
+  readonly starlightRoute?: {
+    readonly entry?: { readonly id?: unknown };
+  };
+}
+
+const dependenciesByLocals = new WeakMap<object, Map<string, Set<string>>>();
+
+/**
+ * Record notation keys emitted by a nested server component for this request.
+ * The request-local collector is deliberately keyed by `Astro.locals`: static
+ * builds render pages concurrently, so a process-global set would leak symbols
+ * between lessons and defeat page-local notation scope.
+ */
+export function registerPageNotationDependencies(
+  locals: object,
+  keys: Iterable<string>,
+  context: string,
+): void {
+  let byKey = dependenciesByLocals.get(locals);
+  if (!byKey) {
+    byKey = new Map();
+    dependenciesByLocals.set(locals, byKey);
+  }
+
+  for (const key of keys) {
+    let contexts = byKey.get(key);
+    if (!contexts) {
+      contexts = new Set();
+      byKey.set(key, contexts);
+    }
+    contexts.add(context);
+  }
+}
+
+export function pageNotationDependencies(
+  locals: object,
+): PageNotationDependency[] {
+  const byKey = dependenciesByLocals.get(locals);
+  if (!byKey) return [];
+  return [...byKey]
+    .flatMap(([key, contexts]) =>
+      [...contexts].map((context) => ({ key, context })),
+    )
+    .sort(
+      (left, right) =>
+        left.key.localeCompare(right.key) ||
+        left.context.localeCompare(right.context),
+    );
+}
+
+/** Starlight's route id as exposed to nested Astro components. */
+export function routeIdFromLocals(locals: object): string | undefined {
+  const id = (locals as StarlightLocals).starlightRoute?.entry?.id;
+  return typeof id === 'string' ? id : undefined;
+}
+
+/** Collect the notation keys that survived into a sanitized KaTeX tree. */
+export function notationKeysInMathNodes(
+  nodes: readonly {
+    readonly type: string;
+    readonly properties?: Readonly<Record<string, string>>;
+    readonly children?: readonly unknown[];
+  }[],
+): string[] {
+  const keys = new Set<string>();
+  const visit = (node: unknown): void => {
+    if (!node || typeof node !== 'object') return;
+    const candidate = node as {
+      properties?: Readonly<Record<string, string>>;
+      children?: readonly unknown[];
+    };
+    const key = candidate.properties?.['data-notation-key'];
+    if (key) keys.add(key);
+    for (const child of candidate.children ?? []) visit(child);
+  };
+  for (const node of nodes) visit(node);
+  return [...keys].sort();
+}
+
+function manifestDefinition(
+  definition: NotationDefinitionRecord,
+  cardsByKey: ReadonlyMap<string, GlyphScopeEntry>,
+): ManifestLessonNotation {
+  return {
+    id: definition.id,
+    key: definition.key,
+    scope: definition.kind === 'shared' ? 'shared' : 'local',
+    notation: definition.notation,
+    label: definition.label,
+    summary: definition.summary,
+    editorialStatus: definition.status,
+    seeAlso: [...definition.seeAlso],
+    glosses: [...definition.glosses],
+    formulaScope: formulaGlyphScope({
+      key: definition.key,
+      notation: definition.notation,
+      glosses: definition.glosses,
+      cardsByKey,
+      ...(definition.formula === undefined
+        ? {}
+        : { formula: definition.formula }),
+    }),
+    ...(definition.units === undefined ? {} : { units: definition.units }),
+    ...(definition.formula === undefined
+      ? {}
+      : { formula: definition.formula }),
+  };
+}
+
+/**
+ * Extend one compiled lesson bundle with only the definitions requested by
+ * components rendered on that page (plus those definitions' normal closure).
+ */
+export function notationDefinitionsForRenderedPage(
+  manifest: Manifest,
+  lessonId: string,
+  dependencies: readonly PageNotationDependency[],
+): ManifestLessonNotation[] {
+  const lesson = manifest.lessons.find((entry) => entry.id === lessonId);
+  if (!lesson) return [];
+
+  const definitionsById = new Map(
+    manifest.notation.definitions.map((definition) => [definition.id, definition]),
+  );
+  const availableIds = new Set(definitionsById.keys());
+  const ids = new Set(lesson.notation.definitionIds);
+  const contextsByKey = new Map<string, Set<string>>();
+
+  for (const dependency of dependencies) {
+    let contexts = contextsByKey.get(dependency.key);
+    if (!contexts) {
+      contexts = new Set();
+      contextsByKey.set(dependency.key, contexts);
+    }
+    contexts.add(dependency.context);
+
+    const definitionId = resolveReferenceId(
+      dependency.key,
+      { kind: 'page', lessonId },
+      availableIds,
+    );
+    if (!definitionId) {
+      throw new Error(
+        `Notation payload error in lesson "${lessonId}": ${dependency.context} ` +
+          `emitted data-notation-key="${dependency.key}", but that key is not ` +
+          `defined in this lesson or the shared notation registry.`,
+      );
+    }
+    ids.add(definitionId);
+  }
+
+  const pending = [...ids];
+  while (pending.length > 0) {
+    const id = pending.pop();
+    if (!id) continue;
+    const definition = definitionsById.get(id);
+    for (const reference of definition?.resolvedReferences ?? []) {
+      if (ids.has(reference.definitionId)) continue;
+      ids.add(reference.definitionId);
+      pending.push(reference.definitionId);
+    }
+    // A card formula's explicit symbols are intentionally not curriculum
+    // reference edges, but they are UI dependencies: NotationFormula emits
+    // triggers for them, so their cards must travel with the parent card.
+    for (const key of formulaExplainKeys(definition?.formula ?? '')) {
+      if (!definition) continue;
+      const formulaDependencyId = resolveReferenceId(
+        key,
+        definition.scope,
+        availableIds,
+      );
+      // A gloss has no card record; NotationLayer emits its hidden source from
+      // the owning definition's `glosses` collection instead.
+      if (!formulaDependencyId || ids.has(formulaDependencyId)) continue;
+      ids.add(formulaDependencyId);
+      pending.push(formulaDependencyId);
+    }
+  }
+
+  // A local definition shadows the shared card with the same key. A shared
+  // dependency closure must never reintroduce that second meaning on the page.
+  const definitionIdByKey = new Map<string, string>();
+  for (const id of ids) {
+    const definition = definitionsById.get(id);
+    if (!definition) continue;
+    const previous = definitionIdByKey.get(definition.key);
+    if (previous && previous !== id) {
+      const context = [...(contextsByKey.get(definition.key) ?? [])].join(', ');
+      throw new Error(
+        `Notation payload error in lesson "${lessonId}": key "${definition.key}" ` +
+          `would have two meanings (${previous} and ${id})` +
+          (context ? ` after ${context} emitted it.` : '.'),
+      );
+    }
+    definitionIdByKey.set(definition.key, id);
+  }
+
+  const cardsByKey = new Map<string, GlyphScopeEntry>();
+  for (const definition of manifest.notation.definitions) {
+    if (definition.kind !== 'shared') continue;
+    cardsByKey.set(definition.key, {
+      key: definition.key,
+      notation: definition.notation,
+    });
+  }
+
+  const existingById = new Map(
+    lesson.notation.definitions.map((definition) => [definition.id, definition]),
+  );
+  return [...ids]
+    .sort()
+    .flatMap((id) => {
+      const existing = existingById.get(id);
+      if (existing) return [existing];
+      const definition = definitionsById.get(id);
+      return definition ? [manifestDefinition(definition, cardsByKey)] : [];
+    });
+}
+
+/**
+ * Structural backstop over final HTML: every trigger must have a source entry
+ * from which the popup enhancer can populate a card.
+ */
+export function missingNotationPayloadKeys(html: string): string[] {
+  const attributeValues = (name: string): Set<string> => {
+    const values = new Set<string>();
+    const pattern = new RegExp(`${name}=(?:"([^"]+)"|'([^']+)')`, 'g');
+    for (const match of html.matchAll(pattern)) {
+      const value = match[1] ?? match[2];
+      if (value) values.add(value);
+    }
+    return values;
+  };
+  const triggers = attributeValues('data-notation-key');
+  const entries = attributeValues('data-notation-entry');
+  return [...triggers].filter((key) => !entries.has(key)).sort();
+}

package/src/reference/raw-floats-validate.ts

@@ -0,0 +1,103 @@
+/** Diagnostics for raw/unwrapped floats — see `raw-floats.mjs`. */
+
+import { scanRawFloats } from './raw-floats.mjs';
+
+export type RawFloatDiagnosticCode =
+  | 'raw-table-markdown'
+  | 'raw-table-html'
+  | 'diagram-unkeyed'
+  | 'diagram-nested';
+
+export interface RawFloatDiagnostic {
+  readonly code: RawFloatDiagnosticCode;
+  readonly severity: 'warning';
+  readonly message: string;
+  readonly file?: string;
+  readonly lessonId?: string;
+}
+
+export interface RawFloatLessonInput {
+  readonly lessonId: string;
+  readonly slug: string;
+  readonly file: string;
+  readonly body: string;
+}
+
+function plural(count: number, noun: string): string {
+  return count === 1 ? noun : `${noun}s`;
+}
+
+export function validateRawFloats(
+  lessons: readonly RawFloatLessonInput[],
+): readonly RawFloatDiagnostic[] {
+  const diagnostics: RawFloatDiagnostic[] = [];
+
+  const push = (
+    lesson: RawFloatLessonInput,
+    code: RawFloatDiagnosticCode,
+    count: number,
+    message: (count: number) => string,
+  ) => {
+    if (count === 0) return;
+    diagnostics.push({
+      code,
+      severity: 'warning',
+      message: message(count),
+      file: lesson.file,
+      lessonId: lesson.lessonId,
+    });
+  };
+
+  for (const lesson of [...lessons].sort((a, b) =>
+    a.lessonId.localeCompare(b.lessonId),
+  )) {
+    const found = scanRawFloats(lesson.body);
+
+    push(
+      lesson,
+      'raw-table-markdown',
+      found.markdownTableCount,
+      (count) =>
+        `${lesson.lessonId} has ${count} raw Markdown ${plural(count, 'table')} ` +
+        `not wrapped in <Table>; ${count === 1 ? 'it has' : 'they have'} no ` +
+        `stable number and cannot be referenced with [[tab-…]]. Wrap it in ` +
+        `<Table id="…">…</Table> to give it one.`,
+    );
+    push(
+      lesson,
+      'raw-table-html',
+      found.htmlTableCount,
+      (count) =>
+        `${lesson.lessonId} has ${count} raw HTML <table> ${plural(count, 'element')} ` +
+        `not wrapped in <Table>; ${count === 1 ? 'it has' : 'they have'} no ` +
+        `stable number and cannot be referenced with [[tab-…]]. Wrap it in ` +
+        `<Table id="…">…</Table> to give it one.`,
+    );
+    push(
+      lesson,
+      'diagram-unkeyed',
+      found.unkeyedDiagramCount,
+      (count) =>
+        `${lesson.lessonId} has ${count} <Diagram> ${plural(count, 'component')} ` +
+        `with no id; ${count === 1 ? 'it' : 'they'} cannot be referenced with ` +
+        `[[dia-…]]. Add an id to give it a stable reference.`,
+    );
+    push(
+      lesson,
+      'diagram-nested',
+      found.nestedDiagramCount,
+      (count) =>
+        `${lesson.lessonId} has ${count} <Diagram> ${plural(count, 'component')} ` +
+        `nested inside another component; ${count === 1 ? 'it is' : 'they are'} ` +
+        `invisible to diagram numbering. Move it to the top level (or inside ` +
+        `<Memo>/<ShortNote>), or wrap it in <Figure> to give it identity.`,
+    );
+  }
+
+  diagnostics.sort(
+    (a, b) =>
+      a.code.localeCompare(b.code) ||
+      (a.lessonId ?? '').localeCompare(b.lessonId ?? ''),
+  );
+  return diagnostics;
+}

package/src/reference/raw-floats.mjs

@@ -0,0 +1,129 @@
+/**
+ * Detection for content invisible to keyed-float validation:
+ *
+ * - a raw Markdown pipe table or raw HTML `<table>` that was never wrapped in
+ *   `<Table>`/`<Figure>`, so it can never get a stable number or be
+ *   referenced with `[[tab-…]]`;
+ * - an Explico `<Diagram>` with no `id` (can't be referenced with
+ *   `[[dia-…]]` even though it participates in diagram numbering);
+ * - an Explico `<Diagram>` nested inside some other, non-transparent
+ *   component (anything but `<Memo>`/`<ShortNote>`, or `<Table>`/`<Figure>`
+ *   which legitimately gives it identity) — invisible to
+ *   `keyed-jsx-floats.mjs`'s top-level-only scan entirely, so it never even
+ *   reaches diagram numbering.
+ *
+ * A raw table nested in `<Table>`/`<Figure>` is the intended, wrapped case
+ * and is not flagged; nesting inside anything else (`<CompactExample>`,
+ * `<Aside>`, `<Memo>`, …) still is, because a raw table has no numbering
+ * scheme of its own to opt into the way a `<Diagram>`'s top-level/`<Memo>`-
+ * transparent scan does.
+ *
+ * `scanRawFloats` (raw Markdown, for the manifest builder) and
+ * `collectRawFloats` (mdast, for `remark-notation.mjs`) MUST agree on counts
+ * — `tests/notation/raw-floats.test.ts` checks that, the same contract
+ * `keyed-jsx-floats.mjs` holds `scanKeyedJsxFloats`/`collectKeyedJsxFloats` to.
+ */
+
+import { stripFencedCode } from './equations.mjs';
+import { collectKeyedJsxFloats, scanKeyedJsxFloats } from './keyed-jsx-floats.mjs';
+
+/** Blank `<Table>…</Table>` and `<Figure>…</Figure>` bodies — legitimately wrapped, not raw. */
+function blankFloatWrappers(text) {
+  return text.replace(
+    /<(Table|Figure)\b(?:\s[^>]*)?>[\s\S]*?<\/\1\s*>/g,
+    (block) => block.replace(/[^\n]/g, ' '),
+  );
+}
+
+/** Line index of every GFM pipe-table header + delimiter-row pair. */
+function findMarkdownTableStarts(text) {
+  const lines = text.split('\n');
+  const delimiterRow =
+    /^[ \t]{0,3}\|?[ \t]*:?-+:?[ \t]*(\|[ \t]*:?-+:?[ \t]*)*\|?[ \t]*$/;
+  const hits = [];
+  for (let index = 0; index < lines.length - 1; index++) {
+    const header = lines[index];
+    const delimiter = lines[index + 1];
+    if (!header.includes('|')) continue;
+    if (!delimiter.includes('-') || !delimiterRow.test(delimiter)) continue;
+    hits.push(index);
+  }
+  return hits;
+}
+
+function findHtmlTableTags(text) {
+  return [...text.matchAll(/<table\b/gi)];
+}
+
+function findDiagramTags(text) {
+  return [...text.matchAll(/<Diagram\b/g)];
+}
+
+/**
+ * Counts of raw/unwrapped content in one lesson body. See the module doc for
+ * what each count means and why `<Diagram>` needs the extra visible/nested
+ * split that raw tables don't.
+ */
+export function scanRawFloats(markdown) {
+  const codeStripped = stripFencedCode(String(markdown));
+  const withoutWrappedFloats = blankFloatWrappers(codeStripped);
+
+  const markdownTableCount = findMarkdownTableStarts(withoutWrappedFloats).length;
+  const htmlTableCount = findHtmlTableTags(withoutWrappedFloats).length;
+
+  const diagramsOutsideWrappers = findDiagramTags(withoutWrappedFloats).length;
+  const visibleDiagrams = scanKeyedJsxFloats(markdown, { tagName: 'Diagram' });
+  const nestedDiagramCount = Math.max(
+    0,
+    diagramsOutsideWrappers - visibleDiagrams.length,
+  );
+  const unkeyedDiagramCount = visibleDiagrams.filter(
+    (diagram) => diagram.key == null,
+  ).length;
+
+  return {
+    markdownTableCount,
+    htmlTableCount,
+    nestedDiagramCount,
+    unkeyedDiagramCount,
+  };
+}
+
+/** The mdast equivalent of `scanRawFloats` — same counts, plus the nodes. */
+export function collectRawFloats(tree) {
+  const markdownTableNodes = [];
+  const htmlTableNodes = [];
+  const allDiagramNodes = [];
+
+  const walk = (node) => {
+    if (!node || typeof node !== 'object') return;
+    if (
+      node.type === 'mdxJsxFlowElement' &&
+      (node.name === 'Table' || node.name === 'Figure')
+    ) {
+      return; // legitimately wrapped — don't descend
+    }
+    if (node.type === 'table') markdownTableNodes.push(node);
+    if (node.type === 'html' && /<table\b/i.test(String(node.value ?? ''))) {
+      htmlTableNodes.push(node);
+    }
+    if (node.type === 'mdxJsxFlowElement' && node.name === 'Diagram') {
+      allDiagramNodes.push(node);
+    }
+    if (Array.isArray(node.children)) {
+      for (const child of node.children) walk(child);
+    }
+  };
+  walk(tree);
+
+  const visibleDiagrams = collectKeyedJsxFloats(tree, { tagName: 'Diagram' });
+  const visibleNodes = new Set(visibleDiagrams.map((diagram) => diagram.node));
+  const nestedDiagramNodes = allDiagramNodes.filter(
+    (node) => !visibleNodes.has(node),
+  );
+  const unkeyedDiagramNodes = visibleDiagrams
+    .filter((diagram) => diagram.key == null)
+    .map((diagram) => diagram.node);
+
+  return { markdownTableNodes, htmlTableNodes, nestedDiagramNodes, unkeyedDiagramNodes };
+}

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

@@ -22,6 +22,27 @@
  * 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.
+ *
+ * Collapsibility (docs/plans/collapsible-disclosure.md Part 3) has a
+ * site-wide default — `defaultCollapsible: { sections, subsections }`, an
+ * option to this plugin (see `astro.config.mjs`), each of `{ collapsible,
+ * defaultOpen }` — plus a per-heading marker an author can append to
+ * override it for one heading:
+ *
+ *   - `[collapsible]` — collapsible, starts open, regardless of the default.
+ *   - `[collapsed]` — collapsible, starts *closed*, regardless of the default.
+ *   - `[no-collapsible]` — never collapsible, regardless of the default.
+ *   - no marker — falls back to the site default for this heading's rank:
+ *     `sections` governs `h2`, `subsections` governs `h3`-`h6`. `collapsible`
+ *     decides whether it's wrapped at all; `defaultOpen` decides its initial
+ *     state when it is (ignored, like the rest of the category, when
+ *     `collapsible` is `false`).
+ *
+ * The marker is stripped from the rendered text and the *resolved* decision
+ * (not the raw marker) becomes `data-collapsible="true"` +
+ * `data-default-open="true"|"false"` on the wrapper — `CollapsibleSections.astro`
+ * only wraps headings carrying `data-collapsible` and never needs to know
+ * about the config or the marker syntax itself.
  */
 
 import { rehypeHeadingIds } from '@astrojs/markdown-remark';
@@ -47,6 +68,50 @@ function headingText(node) {
   return text.replace(/\s+/g, ' ').trim();
 }
 
+// A heading's marker, e.g. `## Some title [collapsed]`, stripped from the
+// rendered text. Square brackets, not curly braces (`{collapsed}`) — every
+// lesson here is authored as `.mdx`, where `{...}` is a JS expression
+// container (MDX tries to evaluate `collapsed` as a variable and the build
+// fails), not literal text the way it is in plain Markdown. An unmatched
+// `[collapsed]` with no link/reference definition of that name is just
+// literal text in both dialects. Deliberately not a general attribute syntax
+// (e.g. `{#id .class}`) — this codebase has no remark-attr-style plugin, and
+// three purpose-built tokens are enough for what an author needs to say
+// about a heading here.
+const COLLAPSIBLE_MARKER = /\s*\[(collapsible|collapsed|no-collapsible)\]\s*$/i;
+
+function stripCollapsibleMarker(headingNode) {
+  const children = headingNode.children;
+  for (let index = children.length - 1; index >= 0; index--) {
+    const node = children[index];
+    if (node.type !== 'text') return null; // trailing non-text node: no marker
+    const match = COLLAPSIBLE_MARKER.exec(node.value);
+    if (match) {
+      node.value = node.value.slice(0, match.index);
+      if (!node.value) children.splice(index, 1);
+      return match[1].toLowerCase();
+    }
+    if (node.value.trim()) return null; // real trailing text, no marker present
+    // trailing whitespace-only text node: keep looking further back
+  }
+  return null;
+}
+
+/**
+ * Resolve a heading's marker (or lack of one) plus the site-wide default for
+ * its rank into a final `{ collapsible, defaultOpen }` decision.
+ */
+function resolveCollapsible(marker, tagName, defaultCollapsible) {
+  if (marker === 'no-collapsible') return { collapsible: false };
+  if (marker === 'collapsed') return { collapsible: true, defaultOpen: false };
+  if (marker === 'collapsible') return { collapsible: true, defaultOpen: true };
+  const rankDefault =
+    tagName === 'h2' ? defaultCollapsible.sections : defaultCollapsible.subsections;
+  return rankDefault.collapsible
+    ? { collapsible: true, defaultOpen: rankDefault.defaultOpen }
+    : { collapsible: false };
+}
+
 function isHeadingWrapper(node) {
   const className = node?.properties?.className;
   return (
@@ -97,10 +162,44 @@ function anchorLink(id, label) {
   };
 }
 
-export default function rehypeHeadingAnchors() {
+const RANK_DEFAULT = { collapsible: false, defaultOpen: true };
+
+export default function rehypeHeadingAnchors(options = {}) {
+  const defaultCollapsible = {
+    sections: { ...RANK_DEFAULT, ...options.defaultCollapsible?.sections },
+    subsections: { ...RANK_DEFAULT, ...options.defaultCollapsible?.subsections },
+  };
   const assignHeadingIds = rehypeHeadingIds();
 
   return function transform(tree, file) {
+    // A marker must be stripped *before* `rehypeHeadingIds` runs — otherwise
+    // the generated slug is built from text that still contains it (e.g.
+    // `two-ways-to-name-the-same-point-collapsed` instead of the clean
+    // title). `collapsibleHeadings` records each heading node's *resolved*
+    // decision, since the marker text is gone by the time the main wrapping
+    // walk below runs.
+    const collapsibleHeadings = new WeakMap();
+    const stripMarkers = (node) => {
+      if (!node || typeof node !== 'object' || !Array.isArray(node.children)) {
+        return;
+      }
+      for (const child of node.children) {
+        if (
+          child?.type === 'element' &&
+          typeof child.tagName === 'string' &&
+          HEADING_TAG.test(child.tagName)
+        ) {
+          const marker = stripCollapsibleMarker(child);
+          collapsibleHeadings.set(
+            child,
+            resolveCollapsible(marker, child.tagName, defaultCollapsible),
+          );
+        }
+        stripMarkers(child);
+      }
+    };
+    stripMarkers(tree);
+
     assignHeadingIds(tree, file);
 
     const walk = (node) => {
@@ -123,12 +222,19 @@ export default function rehypeHeadingAnchors() {
           child.properties.id.length > 0
         ) {
           const id = child.properties.id;
+          const decision = collapsibleHeadings.get(child) ?? { collapsible: false };
           const label = `Section titled “${headingText(child)}”`;
           node.children[index] = {
             type: 'element',
             tagName: 'div',
             properties: {
               className: ['sl-heading-wrapper', `level-${child.tagName}`],
+              ...(decision.collapsible
+                ? {
+                    'data-collapsible': 'true',
+                    'data-default-open': String(decision.defaultOpen),
+                  }
+                : {}),
             },
             children: [child, anchorLink(id, label)],
           };