explico 0.12.0 → 0.13.0

package/src/components/citation/CitationLayer.astro

@@ -6,8 +6,8 @@
  * quick look at the source without leaving the reader's place.
  *
  * It reads everything it shows from the page's own static markup — the
- * marker's `data-*` and the matching `#cite-n` reference-list item — so no
- * page serializes a second copy of the source database. Opening, pinning,
+ * marker's `data-*` and the reference-list item it links to (`#cite-n`) —
+ * so no page serializes a second copy of the source database. Opening, pinning,
  * Escape and placement come from the card manager (`../card-manager.ts`); a
  * card per source, several at once.
  */
@@ -21,12 +21,11 @@ import HoverPanel from '../HoverPanel.astro';
   </p>
   <div class="citation-panel-body">
     <p class="citation-panel-locator" data-panel-locator hidden></p>
-    <p class="citation-panel-status" data-panel-status hidden></p>
     <p class="citation-panel-links">
-      <a class="citation-panel-link" data-panel-link hidden
+      <a class="citation-panel-link hover-panel-action" data-panel-link hidden
         >Go to the source<span aria-hidden="true" data-jump-arrow> ↗</span></a
       >
-      <a class="citation-panel-jump" data-panel-jump
+      <a class="citation-panel-jump hover-panel-action" data-panel-jump
         >Go to the reference list<span aria-hidden="true" data-jump-arrow> ↓</span></a
       >
     </p>
@@ -35,6 +34,7 @@ import HoverPanel from '../HoverPanel.astro';
 
 <script>
   import { cloneCardShell, registerCardSource } from '../card-manager';
+  import { fetchDoc, hrefFrom } from '../card-fetch';
   import { wireJumpArrow } from '../card-jump';
   import { referenceLabelFromText } from '../../reference/citation-format.mjs';
 
@@ -49,10 +49,11 @@ import HoverPanel from '../HoverPanel.astro';
 
   function setup() {
     const template = document.getElementById('citation-panel');
+    // Every page registers, with markers or none: a citation's card carried
+    // in from another page is built here (rule K5).
     if (
       !(template instanceof HTMLTemplateElement) ||
-      template.dataset.cardSourceReady === 'true' ||
-      !document.querySelector('a.citation-ref[data-citation-id]')
+      template.dataset.cardSourceReady === 'true'
     ) {
       return;
     }
@@ -66,27 +67,34 @@ import HoverPanel from '../HoverPanel.astro';
       return candidate && !candidate.closest('[data-card-foreign]') ? candidate : null;
     };
 
-    // Fill a card from the marker plus its `#cite-n` reference-list item —
-    // never from a serialized source table.
-    const render = (number: string, marker: HTMLElement) => {
-      const item = document.getElementById(`cite-${number}`);
+    // The reference-list item a marker links to (`#cite-n`). Followed, not
+    // built from the number: a downloaded part or course holds one list per
+    // chapter, each numbered from 1, with the chapter in its items' ids.
+    const itemIdOf = (marker: HTMLElement) => {
+      const href = marker.getAttribute('href') ?? '';
+      return href.startsWith('#') && href.length > 1 ? decodeURIComponent(href.slice(1)) : null;
+    };
+
+    // Fill a card from the marker plus its reference-list item — never from
+    // a serialized source table. On another page (K5), both come from the
+    // page the card was opened on, and its links go there.
+    const render = (itemId: string, marker: HTMLElement, from?: Document, page?: string) => {
+      const item = (from ?? document).getElementById(itemId);
+      const number = marker.dataset.citationNumber ?? '';
       const el = cloneCardShell(template);
       if (!item || !el) return null;
       const field = (name: string) => el.querySelector<HTMLElement>(`[data-panel-${name}]`);
       const markerEl = field('marker');
       const label = field('label');
       const locator = field('locator');
-      const status = field('status');
       const link = el.querySelector<HTMLAnchorElement>('[data-panel-link]');
       const jump = el.querySelector<HTMLAnchorElement>('[data-panel-jump]');
-      if (!markerEl || !label || !locator || !status || !link || !jump) return null;
+      if (!markerEl || !label || !locator || !link || !jump) return null;
 
       // The reference list is a tight list, so the `<li>` has no `<p>`
-      // wrapper: clone it and drop the trailing link/status chrome.
-      const line = item.cloneNode(true) as HTMLElement;
-      for (const extra of line.querySelectorAll(
-        '.citation-url, .citation-status, .citation-backref',
-      )) {
+      // wrapper: clone it and drop the trailing link chrome.
+      const line = document.importNode(item, true);
+      for (const extra of line.querySelectorAll('.citation-url, .citation-backref')) {
         extra.remove();
       }
       const referenceText = line.textContent ?? '';
@@ -97,11 +105,6 @@ import HoverPanel from '../HoverPanel.astro';
       setText(locator, loc);
       el.setAttribute('aria-label', `Source citation ${number}`);
 
-      const sourceStatus = item
-        .querySelector('.citation-status')
-        ?.textContent?.trim();
-      setText(status, sourceStatus ? `Source record: ${sourceStatus}` : '');
-
       const sourceUrl = item.querySelector<HTMLAnchorElement>('a.citation-url');
       if (sourceUrl) {
         link.href = sourceUrl.href;
@@ -109,19 +112,34 @@ import HoverPanel from '../HoverPanel.astro';
         link.hidden = false;
       }
 
-      jump.href = marker.getAttribute('href') ?? '#references';
+      const jumpTo = marker.getAttribute('href') ?? '#references';
+      jump.href = page ? hrefFrom(jumpTo, page) : jumpTo;
       wireJumpArrow(jump);
       return el;
     };
 
+    /** A reference-list item names its source only on its own page. */
+    const idOf = (item: string) => item.split('@')[0] ?? item;
+
     registerCardSource({
       layer: 'citation',
       triggerFrom: markerFrom,
       itemFor: (marker) => {
-        const number = marker.dataset.citationNumber;
-        return number && document.getElementById(`cite-${number}`) ? number : null;
+        const id = itemIdOf(marker);
+        return id && marker.dataset.citationNumber && document.getElementById(id) ? id : null;
       },
-      render,
+      render: (id, marker) => render(id, marker),
+      // K5: on another page, `[3]` is that page's third source.
+      awayItem: (id, page) => `${idOf(id)}@${page}`,
+      build: (id, page) =>
+        fetchDoc(page).then((doc) => {
+          const marker = [
+            ...doc.querySelectorAll<HTMLElement>('a.citation-ref[data-citation-number]'),
+          ].find((candidate) => itemIdOf(candidate) === idOf(id));
+          const el = marker ? render(idOf(id), marker, doc, page) : null;
+          el?.setAttribute('data-card-foreign', '');
+          return el;
+        }),
     });
   }
 
@@ -155,21 +173,8 @@ import HoverPanel from '../HoverPanel.astro';
       color: var(--sl-color-gray-2);
     }
 
-    .citation-panel-status {
-      color: var(--sl-color-gray-3);
-      font-size: var(--sl-text-xs);
-      text-transform: lowercase;
-    }
-
     .citation-panel-body .citation-panel-links {
       margin: 0;
     }
-
-    .citation-panel-link,
-    .citation-panel-jump {
-      display: inline-block;
-      margin-inline-end: 0.9rem;
-      font-size: var(--sl-text-xs);
-    }
   }
 </style>

package/src/components/diagram/Diagram.astro

@@ -17,9 +17,20 @@
  * client script**: `NotationLayer`'s trigger scan already queries the whole
  * document, not just its own subtree.
  *
- * Box sizes are a generous estimate (`reference/diagram-layout.ts`) unless a
- * node gives an explicit `width`/`height` — there is no DOM at build time to
- * measure a real render against.
+ * Each box is sized from what it holds (`nodeBoxSize` in
+ * `reference/diagram-layout.ts`): the label measured in DejaVu Sans, the
+ * widest common system font, and wrapped to a line count that sets the
+ * height, and the formula measured from KaTeX's own layout tree
+ * (`reference/katex-measure.ts`). A node's `width` or `height` overrides
+ * either; with only a `width`, the label wraps inside it and the height
+ * follows. A diagram wider than the lesson column first wraps its labels
+ * narrower until it fits (`fitDiagramLayout`).
+ *
+ * One that still does not fit (rule V8, `rules.V8.columnWidth`, or the
+ * diagram's own `warnAboveWidth`) is marked `data-diagram-too-wide`; the
+ * build reports it as a `dia-too-wide` warning with the lesson file and this
+ * id (`reference/diagram-fit.ts`), and `astro dev` prints the same warning as
+ * it renders.
  *
  * Named like every float (docs/plans/titles-and-containers.md Part 3): the
  * long `caption` sits below the graph with its number, in the same caption
@@ -31,7 +42,10 @@
  * reader fold a diagram away, wrap it in a `<Fold>` or put it in a
  * collapsible section.
  */
-import { estimateBoxSize, layoutDiagram } from '../../reference/diagram-layout';
+import { fitDiagramLayout, FORMULA_FONT_PX } from '../../reference/diagram-layout';
+import { measureFormula } from '../../reference/katex-measure';
+import { diagramTooWideMessage, diagramWidthLimit } from '../../reference/diagram-fit';
+import { loadManifest } from '../../compiler/manifest';
 import { renderNotationFormula } from '../notation/render-notation-math';
 import type { SafeMathNode as SafeMathNodeType } from '../notation/render-notation-math';
 import SafeMathNode from '../notation/SafeMathNode.astro';
@@ -40,8 +54,11 @@ import { DIAGRAM_NO_LONGER_FOLDS } from '../../reference/diagrams-validate';
 import type { GlyphScopeEntry } from '../../reference/gloss';
 import {
   notationKeysInMathNodes,
+  registerPageDerivedNotation,
   registerPageNotationDependencies,
 } from '../../reference/page-notation';
+import { indexFindings } from '../../reference/gate-indices';
+import type { DerivedUse } from '../../reference/types';
 
 export interface DiagramNode {
   readonly id: string;
@@ -49,8 +66,9 @@ export interface DiagramNode {
   readonly text?: string;
   /** Raw LaTeX, resolved against `scope` before rendering. */
   readonly formula?: string;
-  /** Overrides the size estimate — use for a label the heuristic gets wrong. */
+  /** The box's width in px; the label wraps inside it and the height follows. */
   readonly width?: number;
+  /** The box's height in px. */
   readonly height?: number;
 }
 
@@ -76,8 +94,9 @@ export interface Props {
   /** Computed by `remark-notation.mjs` for a top-level lesson diagram. */
   anchorId?: string;
   /**
-   * Emit a build warning when the laid-out SVG is wider than this many pixels.
-   * Set `false` only when horizontal overflow is deliberate. Default: `800`.
+   * The widest this diagram may lay out, in px, before the build warns
+   * (`dia-too-wide`, rule V8). Default: the course's `rules.V8.columnWidth`,
+   * the lesson column. Set `false` only when horizontal overflow is deliberate.
    */
   warnAboveWidth?: number | false;
 }
@@ -92,7 +111,7 @@ const {
   direction = 'TB',
   number,
   anchorId,
-  warnAboveWidth = 800,
+  warnAboveWidth,
 } = Astro.props;
 
 const idPattern = /^[A-Za-z][A-Za-z0-9_-]*$/;
@@ -128,6 +147,7 @@ if ((number && !anchorId) || (!number && anchorId)) {
   );
 }
 if (
+  warnAboveWidth !== undefined &&
   warnAboveWidth !== false &&
   (!Number.isFinite(warnAboveWidth) || warnAboveWidth <= 0)
 ) {
@@ -136,26 +156,47 @@ if (
 
 interface RenderedNode extends DiagramNode {
   readonly mathNodes?: readonly SafeMathNodeType[];
+  /** The LaTeX `mathNodes` were rendered from, glyphs bound. */
+  readonly boundFormula?: string;
 }
 
+// The course's rule settings; a page rendered without a manifest (a
+// component test) checks against the defaults.
+const rules = await loadManifest().then(
+  (manifest) => manifest.rules,
+  () => undefined,
+);
+
+// Rule N23: a diagram's formula is page math, so its indexed symbols take
+// derived cards like the lesson's, and are held to the rule.
+const derivedUses: DerivedUse[] = [];
 const rendered: RenderedNode[] = nodes.map((node) => {
   if (!node.text && !node.formula) {
     throw new Error(`Diagram "${id}" node "${node.id}" has neither text nor formula.`);
   }
   if (!node.formula) return { ...node };
 
-  const { nodes: mathNodes, unresolved, degraded } = renderNotationFormula(
-    node.formula,
-    scope,
-  );
+  const {
+    nodes: mathNodes,
+    latex,
+    unresolved,
+    degraded,
+    reason,
+    derived,
+    indices,
+  } = renderNotationFormula(node.formula, scope, { derive: true });
   if (degraded) {
+    // The resolver says what went wrong; an empty `scope` is the usual cause
+    // when the diagram is written straight into MDX, where nothing passes it.
+    const emptyScope =
+      scope.length === 0
+        ? ' The diagram has no `scope`, so no symbol can resolve: pass the page\'s ' +
+          'notation scope (`labMathScope`), as a wrapper component does.'
+        : '';
     throw new Error(
       `Diagram "${id}" node "${node.id}" formula "${node.formula}" could not be ` +
-        `bound to the notation scope: the LaTeX did not parse, or a bare glyph is ` +
-        `the base of more than one page symbol. Wrap each symbol in ` +
-        `\\explain{key}{latex}, or brace a subscripted base (write {v_0}^{2}, not ` +
-        `v_0^{2}), so every glyph resolves — a diagram formula is never allowed to ` +
-        `render as silent, unexplained math.`,
+        `bound to the notation scope: ${(reason ?? 'the LaTeX did not parse').replace(/\.$/, '')}.${emptyScope} ` +
+        `A diagram formula is never allowed to render as silent, unexplained math.`,
     );
   }
   if (unresolved.length > 0) {
@@ -166,33 +207,55 @@ const rendered: RenderedNode[] = nodes.map((node) => {
         `or pass it in the diagram's scope.`,
     );
   }
-  return { ...node, mathNodes };
+  const findings = rules?.disabled.includes('N23') ? [] : indexFindings(indices);
+  if (findings.length > 0) {
+    throw new Error(
+      `Diagram "${id}" node "${node.id}" formula "${node.formula}" has an index no card ` +
+        `explains (rule N23): ${findings.join('; ')}.`,
+    );
+  }
+  derivedUses.push(...derived);
+  return { ...node, mathNodes, boundFormula: latex };
 });
 
+const derivedKeys = new Set(derivedUses.map((use) => use.key));
+registerPageDerivedNotation(Astro.locals, derivedUses, `Diagram "${id}"`);
 for (const node of rendered) {
   if (!node.mathNodes) continue;
   registerPageNotationDependencies(
     Astro.locals,
-    notationKeysInMathNodes(node.mathNodes),
+    // A derived card is no definition: it ships through its own registry.
+    notationKeysInMathNodes(node.mathNodes).filter((key) => !derivedKeys.has(key)),
     `Diagram "${id}" node "${node.id}" formula "${node.formula}"`,
   );
 }
 
-const sized = rendered.map((node) => ({
-  node,
-  box:
-    node.width && node.height
-      ? { width: node.width, height: node.height }
-      : estimateBoxSize(
-          node.formula ?? node.text ?? node.id,
-          node.formula ? 'formula' : 'text',
-        ),
-}));
-
-const layout = layoutDiagram(
-  sized.map(({ node, box }) => ({ id: node.id, width: box.width, height: box.height })),
+for (const node of rendered) {
+  for (const side of ['width', 'height'] as const) {
+    const value = node[side];
+    if (value !== undefined && !(Number.isFinite(value) && value > 0)) {
+      throw new Error(`Diagram "${id}" node "${node.id}" needs a positive \`${side}\`.`);
+    }
+  }
+}
+
+// Rule V8's settings, from the course's rules above.
+const widthLimit = diagramWidthLimit(warnAboveWidth, rules);
+
+const { layout } = fitDiagramLayout(
+  rendered.map((node) => ({
+    id: node.id,
+    content: {
+      ...(node.text ? { text: node.text } : {}),
+      ...(node.boundFormula
+        ? { formula: measureFormula(node.boundFormula, FORMULA_FONT_PX) }
+        : {}),
+    },
+    ...(node.width !== undefined ? { width: node.width } : {}),
+    ...(node.height !== undefined ? { height: node.height } : {}),
+  })),
   edges.map((edge) => ({ from: edge.from, to: edge.to })),
-  { direction },
+  { direction, ...(widthLimit !== undefined ? { fitWidth: widthLimit } : {}) },
 );
 
 const nodeById = new Map(rendered.map((node) => [node.id, node]));
@@ -203,13 +266,13 @@ const renderedAnchorId = anchorId ?? legacyAnchorId;
 const viewportId = `${legacyAnchorId}-viewport`;
 const captionTextId = `${legacyAnchorId}-caption`;
 
-if (warnAboveWidth !== false && layout.width > warnAboveWidth) {
+const tooWide = widthLimit !== undefined && layout.width > widthLimit;
+if (tooWide && import.meta.env.DEV) {
+  const entry = (Astro.locals as { starlightRoute?: { entry?: { filePath?: string; id?: string } } })
+    .starlightRoute?.entry;
   console.warn(
-    `[explico/Diagram] "${id}" lays out at ${layout.width}px wide, above the ` +
-      `${warnAboveWidth}px authoring threshold. It will scroll and can be expanded ` +
-      `by readers, but consider recreating the graph with direction="TB", shorter ` +
-      `labels, or explicit node sizes. Set warnAboveWidth={false} only when the ` +
-      `horizontal overflow is intentional.`,
+    `[dia-too-wide] ${entry?.filePath ?? entry?.id ?? Astro.url.pathname}: ` +
+      diagramTooWideMessage(id, layout.width, widthLimit),
   );
 }
 
@@ -227,6 +290,7 @@ function pathFrom(points: readonly { x: number; y: number }[]): string {
   data-dia-key={number ? id : undefined}
   data-dia-short={short}
   data-diagram-width={layout.width}
+  data-diagram-too-wide={tooWide ? widthLimit : undefined}
   data-diagram-expandable
 >
   <div class="diagram__body">
@@ -426,23 +490,38 @@ function pathFrom(points: readonly { x: number; y: number }[]): string {
       stroke-width: 1;
     }
 
+    /* `NODE_FONT_PX` and the insets in `reference/diagram-layout.ts` size each
+       box from these values; change them together. The size is in px, not
+       rem: the boxes are measured at build time for 13.6px text, so text that
+       followed a reader's larger default font size (20px, Chrome's "Large")
+       outgrew its box and was cut off. Scaling the whole drawing instead is no
+       way out — WebKit on iOS scales the SVG but not the HTML in a
+       `foreignObject`. Browser zoom still enlarges it with everything else. */
     .diagram-node-content {
       display: flex;
       height: 100%;
       flex-direction: column;
       align-items: center;
       justify-content: center;
-      gap: 0.15rem;
-      padding: 0.2rem 0.5rem;
+      gap: 2.4px;
+      padding: 3.2px 8px;
       color: var(--sl-color-text);
       font-family: var(--sl-font);
-      font-size: 0.85rem;
+      font-size: 13.6px;
       line-height: 1.25;
       text-align: center;
     }
 
-    .diagram-node-formula :global(.katex) {
-      font-size: 1em;
+    /* The box was sized for its label wrapped evenly; a narrower font
+       balances it the same way rather than leaving one word alone. */
+    .diagram-node-text {
+      text-wrap: balance;
+    }
+
+    /* The box is as wide as the formula on one line (`nodeBoxSize`); KaTeX's
+       inline math would otherwise break after a `+` or `=` and outgrow it. */
+    .diagram-node-formula {
+      white-space: nowrap;
     }
 
     .diagram-edge {

package/src/components/figure/Figure.astro

@@ -263,6 +263,17 @@ const name = `Figure ${number}`;
     .keyed-figure__tools-stub {
       display: none !important;
     }
+
+    /* A lab the reader never scrolled to has not drawn yet. The Print button
+       and Ctrl+P load it first; the browser's own File → Print cannot wait,
+       so the empty box says how to print the figure. */
+    .keyed-figure__body:has(astro-island[ssr])::after {
+      content: 'Interactive figure not loaded: print with the page’s Print button or Ctrl+P to include it.';
+      display: block;
+      font-size: 0.85em;
+      font-style: italic;
+      padding: 0.5rem 0;
+    }
   }
 </style>
 

package/src/components/figure/FloatCaption.astro

@@ -4,11 +4,11 @@
  * (docs/plans/figures-and-short-captions.md, decisions 1 and 4). One
  * anatomy, below the picture, the LaTeX figure convention:
  *
- *   Figure 2.2.1  [chain]  **‹short›.** ‹caption› ‹live end›   [buttons]
+ *   Figure 2.2.1  **‹short›.** ‹caption› ‹live end›   [buttons]
  *
- * The number links to the float, the chain icon copies that link
- * (`HeadingAnchorEnhancer.astro` reads `data-copy-link`) and then navigates
- * the same way, and the caption is the float's one long caption. A float
+ * The number links to the float; hovering or focusing it shows its toolbar,
+ * whose Copy link copies that link (`float-toolbar.ts`). The caption is the
+ * float's one long caption. A float
  * with a short caption opens the caption with it as a bold title,
  * `b.float-caption__title` (decision 9.1), outside `.float-caption__text`, so
  * a reader of the long caption (a preview card, a fold's bar) still reads
@@ -65,19 +65,6 @@ const tools = Astro.slots.has('default') ? (await Astro.slots.render('default'))
       </a>
     )
   }
-  <a
-    class="float-caption__anchor"
-    href={`#${anchorId}`}
-    aria-label={`Copy the link to ${name}`}
-    title="Copy link"
-    data-copy-link={name}
-  >
-    <svg aria-hidden="true" width="16" height="16" viewBox="0 0 24 24" fill="currentColor"
-      ><path
-        d="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"
-      ></path></svg
-    >
-  </a>
   {short && <b class="float-caption__title">{captionTitle(short)}</b>}{short && ' '}<span
     class:list={['float-caption__text', `${prefix}__caption-text`]}
     id={textId}