explico 0.11.1 → 0.13.0

package/dist/reference/consistency.js

@@ -2,7 +2,8 @@ import { effectiveAccentAllowlist } from "./base-accents.mjs";
 import { effectiveOperatorAllowlist } from "./base-operators.mjs";
 import { effectiveRomanLabelAllowlist } from "./base-roman-labels.mjs";
 import { stripEquationLabels } from "./equations.mjs";
-import { pageScope } from "./gate-math.js";
+import { pageScope, scopeEntry } from "./gate-math.js";
+import { isIndexEntryLatex } from "../compiler/content-schemas.js";
 import {
   collectDecorations,
   collectOperators,
@@ -12,12 +13,12 @@ import {
   resolveMathGlyphs
 } from "./math-glyphs.mjs";
 import { offVocabularyTokens } from "./units-vocab.js";
-const CONVENTION_RE = /\bsign convention\b|\bcash-flow perspective\b|\bholder(?:'s)?(?:\s+\w+){0,2}\s+perspective\b|\bfrom (?:a|one|the|its)(?:\s+\w+){0,3}\s+perspective\b|\breverses? every sign\b|\bpositive (?:means|amounts?)\b/i;
+import { blankPropStrings } from "./gate-prop-text.js";
 function stripCode(text) {
   return text.replace(/```[\s\S]*?```/g, (block) => block.replace(/[^\n]/g, " ")).replace(/(^|[^`])`[^`\n]*`/g, (match) => match.replace(/[^\n]/g, " "));
 }
 function mathSpans(body) {
-  const searchable = stripCode(body);
+  const searchable = stripCode(blankPropStrings(body));
   const spans = [];
   for (const match of searchable.matchAll(/\$\$([\s\S]+?)\$\$/g)) {
     spans.push({ latex: stripEquationLabels(match[1] ?? "") });
@@ -79,6 +80,7 @@ function checkGlyphUniqueness(input, out) {
 }
 function checkNotationUnits(input, out) {
   for (const spec of input.specs) {
+    if (isIndexEntryLatex(spec.latex)) continue;
     if (spec.units === void 0 && !spec.dimensionless) {
       if (input.lintIgnore.matches("notation-units", spec.key)) continue;
       out.push({
@@ -105,35 +107,6 @@ function checkNotationUnits(input, out) {
     });
   }
 }
-function checkConventionSingleDefinition(input, out) {
-  const lessonById = new Map(
-    input.catalog.lessons.map((lesson) => [lesson.id, lesson])
-  );
-  for (const lesson of input.notationInput.lessons) {
-    const body = lesson.body;
-    if (!CONVENTION_RE.test(body)) continue;
-    const meta = lessonById.get(lesson.lessonId);
-    const { signConventionKey, cashFlowPerspectiveCompetency } = input.conventions;
-    const anchoredByCompetency = [
-      ...meta?.teaches ?? [],
-      ...meta?.requires ?? []
-    ].includes(cashFlowPerspectiveCompetency);
-    const anchoredByTerm = new RegExp(
-      `\\[\\[\\s*${signConventionKey}\\s*\\]\\]`
-    ).test(body);
-    if (anchoredByCompetency || anchoredByTerm) continue;
-    if (input.lintIgnore.matches("convention-single-definition", lesson.lessonId)) {
-      continue;
-    }
-    out.push({
-      code: "convention-single-definition",
-      severity: "warning",
-      lessonId: lesson.lessonId,
-      file: lesson.source.file,
-      message: `${lesson.lessonId} states a sign / cash-flow-perspective convention in prose but does not resolve it to a single declaration ([[${signConventionKey}]] or ${cashFlowPerspectiveCompetency})`
-    });
-  }
-}
 function checkWeakLocal(input, out) {
   for (const lesson of input.notationInput.lessons) {
     const spans = mathSpans(lesson.body).map((span) => span.latex);
@@ -295,7 +268,7 @@ function checkOperatorExplained(input, out) {
           lessonId: lesson.lessonId,
           file: lesson.source.file,
           glyph: operator.name,
-          message: `${lesson.lessonId}: operator ${JSON.stringify(display)} is neither on the course operator allowlist nor explained by a notation entry; give it a card or notation.local entry (latex ${JSON.stringify(display)}) introduced with [[key]], or add ${JSON.stringify(operator.name)} to operators.allow in course.config.ts`
+          message: `${lesson.lessonId}: operator ${JSON.stringify(display)} is neither on the course operator allowlist nor explained by a notation entry; give it a card or notation.local entry (latex ${JSON.stringify(display)}) introduced with [[key]], or add ${JSON.stringify(operator.name)} to rules.N8.allow in the course config (course.config.ts, or the course.settings.json it reads)`
         });
       }
     }
@@ -339,7 +312,7 @@ function checkRomanLabelExplained(input, out) {
           lessonId: lesson.lessonId,
           file: lesson.source.file,
           glyph: label.name,
-          message: `${lesson.lessonId}: roman label ${JSON.stringify(`\\mathrm{${label.name}}`)} is neither on the course roman-label allowlist nor explained by a notation entry; give it a card or notation.local entry (latex ${JSON.stringify(`\\mathrm{${label.name}}`)}) introduced with [[key]], or add ${JSON.stringify(label.name)} to romanLabels.allow in course.config.ts`
+          message: `${lesson.lessonId}: roman label ${JSON.stringify(`\\mathrm{${label.name}}`)} is neither on the course roman-label allowlist nor explained by a notation entry; give it a card or notation.local entry (latex ${JSON.stringify(`\\mathrm{${label.name}}`)}) introduced with [[key]], or add ${JSON.stringify(label.name)} to rules.N10.allow in the course config (course.config.ts, or the course.settings.json it reads)`
         });
       }
     }
@@ -349,7 +322,7 @@ function sharedScopeByKey(input) {
   return new Map(
     input.notationInput.sharedDefinitions.map((definition) => [
       definition.key,
-      { key: definition.key, notation: definition.notation }
+      scopeEntry(definition)
     ])
   );
 }
@@ -363,11 +336,35 @@ function checkAccentExplained(input, out) {
     for (const span of mathSpans(lesson.body)) {
       let decorations;
       try {
-        ({ decorations } = resolveMathGlyphs(span.latex, scope, { suspended }));
+        ({ decorations } = resolveMathGlyphs(span.latex, scope, {
+          suspended,
+          derive: true
+        }));
       } catch {
         continue;
       }
       for (const decoration of decorations) {
+        if (decoration.wholeForm !== null && decoration.wholeFormExplicit) {
+          const notation = scope.find((entry) => entry.key === decoration.wholeForm)?.notation ?? "";
+          const carries = collectDecorations(notation).some(
+            (item) => item.name === decoration.name
+          );
+          const id = `swallowed:${decoration.token}`;
+          if (!carries && !reported.has(id)) {
+            reported.add(id);
+            if (!input.lintIgnore.matches("accent-swallowed", decoration.name)) {
+              out.push({
+                code: "accent-swallowed",
+                severity: "warning",
+                lessonId: lesson.lessonId,
+                file: lesson.source.file,
+                glyph: decoration.name,
+                message: `${lesson.lessonId}: \\explain{${decoration.wholeForm}}{${decoration.token}} wraps the decoration ${JSON.stringify(decoration.name)} in ${decoration.wholeForm}, whose latex (${notation}) has none, so its card cannot explain it; wrap only the symbol under it and give the decoration an operator entry (latex ${JSON.stringify(operatorEntryLatex(decoration.name))}), or name an entry for the decorated form (latex ${JSON.stringify(decoration.token)})`
+              });
+            }
+          }
+          continue;
+        }
         if (decoration.wholeForm !== null || decoration.operator !== null) continue;
         if (suspended.includes(decoration.name)) continue;
         if (allowlist.has(decoration.name)) continue;
@@ -436,7 +433,6 @@ function checkOperatorSuspension(input, out) {
 const CHECKS = [
   checkGlyphUniqueness,
   checkNotationUnits,
-  checkConventionSingleDefinition,
   checkWeakLocal,
   checkNotationSourceLocator,
   checkGlossWantsPromoting,
@@ -459,7 +455,6 @@ function consistencyCounts(diagnostics) {
     "glyph-unique-in-corpus": 0,
     "notation-units": 0,
     "units-vocab": 0,
-    "convention-single-definition": 0,
     "weak-local": 0,
     "notation-source-locator": 0,
     "gloss-wants-promoting": 0,
@@ -468,6 +463,7 @@ function consistencyCounts(diagnostics) {
     "operator-explained": 0,
     "roman-label-explained": 0,
     "accent-explained": 0,
+    "accent-swallowed": 0,
     "operator-suspended": 0,
     "operator-suspension-reason": 0,
     "operator-shadowed": 0

package/dist/reference/curriculum-alignment.js

@@ -2,13 +2,10 @@ import { compareDiagnostics } from "./references.js";
 function validateNotationAlignment(registry, catalog) {
   const diagnostics = [];
   const competencies = new Map(
-    catalog.competencies.map((entry) => [
-      entry.id,
-      entry
-    ])
+    catalog.competencies.map((entry) => [entry.id, entry])
   );
   const lessons = new Map(catalog.lessons.map((entry) => [entry.id, entry]));
-  const sources = new Map(catalog.sources.map((entry) => [entry.id, entry]));
+  const sources = new Set(catalog.sources.map((entry) => entry.id));
   const trackPositions = buildTrackPositions(catalog, diagnostics);
   for (const definition of registry.definitions) {
     validateSources(definition, sources, diagnostics);
@@ -60,15 +57,6 @@ function validateNotationAlignment(registry, catalog) {
       trackPositions,
       diagnostics
     );
-    if (definition.status === "reviewed" && (lesson.status !== "reviewed" || competency?.editorialStatus !== "reviewed")) {
-      diagnostics.push(
-        error(
-          "alignment-review-state",
-          `${definition.id} is reviewed while its owning lesson or competency is not reviewed`,
-          definition
-        )
-      );
-    }
   }
   return diagnostics.sort(compareDiagnostics);
 }
@@ -129,8 +117,7 @@ function validateIntroductionOrder(definition, introductionLessonId, registry, t
 }
 function validateSources(definition, sources, diagnostics) {
   for (const sourceId of definition.sources) {
-    const source = sources.get(sourceId);
-    if (!source) {
+    if (!sources.has(sourceId)) {
       diagnostics.push(
         error(
           "alignment-unavailable",
@@ -138,14 +125,6 @@ function validateSources(definition, sources, diagnostics) {
           definition
         )
       );
-    } else if (definition.status === "reviewed" && source.editorialStatus !== "reviewed") {
-      diagnostics.push(
-        error(
-          "alignment-review-state",
-          `${definition.id} is reviewed while source ${sourceId} is ${source.editorialStatus}`,
-          definition
-        )
-      );
     }
   }
 }

package/dist/reference/derived-entries.d.ts

@@ -0,0 +1,45 @@
+import { ManifestDerivedNotation } from '../compiler/manifest.js';
+import { GlyphScopeEntry } from './gloss.js';
+import { DerivedUse, NotationDefinitionRecord } from './types.js';
+import '../curriculum/validation.js';
+import './consistency.js';
+import '../course-config-rRtME5UV.js';
+import '../rules/catalog.js';
+import '../rules/course-rules.js';
+import '../compiler/collections.js';
+import './gate-retired-keys.js';
+import './lint-ignore.js';
+import './equations-validate.js';
+import './tables-validate.js';
+import './keyed-float-validate.js';
+import './figures-validate.js';
+import './diagrams-validate.js';
+import './examples-validate.js';
+import './folds-validate.js';
+import './knowledge-checks-validate.js';
+import './raw-floats-validate.js';
+import './lab-katex-validate.js';
+import './gate-math.js';
+import './mixed-content.js';
+import '../rules/waivers.js';
+import '../compiler/knowledge-version.js';
+import '../compiler/lesson-derivation.js';
+
+/**
+ * Derived cards (rule N23) as the page payload carries them: each derived
+ * card a page's math uses, composed from its base and index entries by
+ * `derived-notation.mjs`, with the glyph table its formula resolves against.
+ * The manifest builds the ones lesson-body and assessment math use; the page
+ * payload (`page-notation.ts`) builds the ones a lab or a diagram registers
+ * while it renders, the same way.
+ */
+
+/**
+ * The derived cards for `uses`, sorted by key. `records` holds the page's
+ * entries by key, local ones winning; a use whose base or index entry is not
+ * there is skipped. A card's formula resolves against the derived symbol,
+ * the index entry's glosses, the base, and the cards the formula names.
+ */
+declare function derivedNotationEntries(uses: readonly DerivedUse[], records: ReadonlyMap<string, NotationDefinitionRecord>, cardsByKey: ReadonlyMap<string, GlyphScopeEntry>): ManifestDerivedNotation[];
+
+export { derivedNotationEntries };

package/dist/reference/derived-entries.js

@@ -0,0 +1,50 @@
+import { composeDerivedEntry } from "./derived-notation.mjs";
+import { scopeEntry } from "./gate-math.js";
+import { formulaExplainKeys } from "./gloss.js";
+import { baseSymbolLatex, derivedNotationLatex } from "./math-glyphs.mjs";
+function derivedNotationEntries(uses, records, cardsByKey) {
+  const derived = /* @__PURE__ */ new Map();
+  for (const use of uses) {
+    if (derived.has(use.key)) continue;
+    const base = records.get(use.base);
+    const index = records.get(use.index);
+    if (!base || !index) continue;
+    const notation = derivedNotationLatex(base.notation, index.notation);
+    const entry = composeDerivedEntry({
+      key: use.key,
+      notation,
+      baseLatex: baseSymbolLatex(base.notation),
+      base,
+      index: {
+        ...index,
+        ...index.formulaTemplate === void 0 ? {} : { formula: index.formulaTemplate }
+      }
+    });
+    const formulaScope = [
+      { key: use.key, notation },
+      ...index.glosses.map((gloss) => ({ key: gloss.key, notation: gloss.notation })),
+      scopeEntry(base)
+    ];
+    for (const key of formulaExplainKeys(entry.formula ?? "")) {
+      if (formulaScope.some((row) => row.key === key)) continue;
+      const card = records.get(key) ?? cardsByKey.get(key);
+      if (card) formulaScope.push(scopeEntry(card));
+    }
+    derived.set(use.key, {
+      key: entry.key,
+      base: entry.base,
+      index: entry.index,
+      notation: entry.notation,
+      label: entry.label,
+      summary: entry.summary,
+      glosses: [...index.glosses],
+      formulaScope,
+      ...entry.units === void 0 ? {} : { units: entry.units },
+      ...entry.formula === void 0 ? {} : { formula: entry.formula }
+    });
+  }
+  return [...derived.values()].sort((left, right) => left.key.localeCompare(right.key));
+}
+export {
+  derivedNotationEntries
+};

package/dist/reference/derived-notation.d.mts

@@ -0,0 +1,125 @@
+/**
+ * A label as it reads inside a sentence: its first letter lowercased unless
+ * the first word is an acronym (`OLS estimate`) — the same rule
+ * `composeHeaderLabel` applies to an operator's operand.
+ *
+ * @param {string} label
+ * @returns {string}
+ */
+export function inSentence(label: string): string;
+/**
+ * A derived card's title: the index entry's `reads` with `{base}` replaced by
+ * the base's label (lowercased in mid-sentence), or `"<index label> of
+ * <base label>"` when the index entry gives no `reads`.
+ *
+ * @param {{ label: string, reads?: string }} index
+ * @param {string} baseLabel
+ * @returns {string}
+ */
+export function derivedLabel(index: {
+    label: string;
+    reads?: string;
+}, baseLabel: string): string;
+/**
+ * An index entry's formula with `{base}` bound: to the base symbol under its
+ * own `\explain`, for a derived card, so the reader opens the base's card
+ * from it.
+ *
+ * @param {string} formula
+ * @param {string} baseKey
+ * @param {string} baseLatex
+ * @returns {string}
+ */
+export function derivedFormula(formula: string, baseKey: string, baseLatex: string): string;
+/**
+ * An index entry's own formula, shown on the index entry's card and checked
+ * by the formula gate: `{base}` becomes a placeholder square bound to the
+ * entry itself, as an operator entry is shown over a square.
+ *
+ * @param {string} formula
+ * @param {string} ownKey
+ * @returns {string}
+ */
+export function indexEntryFormula(formula: string, ownKey: string): string;
+/**
+ * @typedef {object} DerivedSource
+ * @property {string} key
+ * @property {string} notation
+ * @property {string} label
+ * @property {string} [summary]
+ * @property {string} [units]
+ * @property {string} [reads]
+ * @property {string} [formula]
+ * @property {readonly { key: string, notation: string, label: string, units?: string, ownerKey: string }[]} [glosses]
+ */
+/**
+ * The derived entry for one (base, index) pair. `notation` is the indexed
+ * symbol, from `derivedNotationLatex`.
+ *
+ * @param {{ key: string, notation: string, baseLatex: string, base: DerivedSource, index: DerivedSource }} input
+ */
+export function composeDerivedEntry({ key, notation, baseLatex, base, index }: {
+    key: string;
+    notation: string;
+    baseLatex: string;
+    base: DerivedSource;
+    index: DerivedSource;
+}): {
+    formula?: string | undefined;
+    units?: string | undefined;
+    key: string;
+    notation: string;
+    base: string;
+    index: string;
+    label: string;
+    summary: string;
+    glosses: {
+        key: string;
+        notation: string;
+        label: string;
+        units?: string;
+        ownerKey: string;
+    }[];
+};
+/**
+ * Derived notation entries (rule N23): the card for a symbol with a subscript
+ * that an **index entry** explains — `\mathbf{v}_0` from the base entry
+ * `velocity-vector` (`\mathbf{v}`) and the index entry `motion.initial`
+ * (`{}_0`, "Initial value").
+ *
+ * The resolver writes one `\explain` around the whole indexed symbol, with
+ * the key `derivedNotationKey(base, index)` (`math-glyphs.mjs`); the build
+ * materializes the entry from the two, here, so that everything downstream
+ * treats it as one more card. What the reader sees first is about the
+ * indexed symbol; the base's own card is one level deeper, through the base
+ * symbol on the card's formula line:
+ *
+ * | Field   | From                                        |
+ * | ------- | ------------------------------------------- |
+ * | symbol  | the base's symbol plus the index            |
+ * | title   | the index entry's `reads`, the base's label |
+ * | summary | the index entry's `meaning`, never the base's |
+ * | formula | the index entry's `formula`, `{base}` bound |
+ * | units   | the base entry                              |
+ *
+ * Plain JavaScript with no parser, so the remark pass and the manifest share
+ * it; `derivedNotationLatex` in `math-glyphs.mjs` builds the symbol.
+ */
+/** The indexed symbol, in an index entry's `reads` and `formula`. */
+export const BASE_PLACEHOLDER: "{base}";
+export type DerivedSource = {
+    key: string;
+    notation: string;
+    label: string;
+    summary?: string | undefined;
+    units?: string | undefined;
+    reads?: string | undefined;
+    formula?: string | undefined;
+    glosses?: readonly {
+        key: string;
+        notation: string;
+        label: string;
+        units?: string;
+        ownerKey: string;
+    }[] | undefined;
+};

package/dist/reference/derived-notation.mjs

@@ -0,0 +1,121 @@
+/**
+ * Derived notation entries (rule N23): the card for a symbol with a subscript
+ * that an **index entry** explains — `\mathbf{v}_0` from the base entry
+ * `velocity-vector` (`\mathbf{v}`) and the index entry `motion.initial`
+ * (`{}_0`, "Initial value").
+ *
+ * The resolver writes one `\explain` around the whole indexed symbol, with
+ * the key `derivedNotationKey(base, index)` (`math-glyphs.mjs`); the build
+ * materializes the entry from the two, here, so that everything downstream
+ * treats it as one more card. What the reader sees first is about the
+ * indexed symbol; the base's own card is one level deeper, through the base
+ * symbol on the card's formula line:
+ *
+ * | Field   | From                                        |
+ * | ------- | ------------------------------------------- |
+ * | symbol  | the base's symbol plus the index            |
+ * | title   | the index entry's `reads`, the base's label |
+ * | summary | the index entry's `meaning`, never the base's |
+ * | formula | the index entry's `formula`, `{base}` bound |
+ * | units   | the base entry                              |
+ *
+ * Plain JavaScript with no parser, so the remark pass and the manifest share
+ * it; `derivedNotationLatex` in `math-glyphs.mjs` builds the symbol.
+ */
+
+/** The indexed symbol, in an index entry's `reads` and `formula`. */
+export const BASE_PLACEHOLDER = '{base}';
+
+/**
+ * A label as it reads inside a sentence: its first letter lowercased unless
+ * the first word is an acronym (`OLS estimate`) — the same rule
+ * `composeHeaderLabel` applies to an operator's operand.
+ *
+ * @param {string} label
+ * @returns {string}
+ */
+export function inSentence(label) {
+  const [first = ''] = label.split(/\s+/u);
+  if (first.length > 1 && first === first.toUpperCase()) return label;
+  return label.charAt(0).toLowerCase() + label.slice(1);
+}
+
+/**
+ * A derived card's title: the index entry's `reads` with `{base}` replaced by
+ * the base's label (lowercased in mid-sentence), or `"<index label> of
+ * <base label>"` when the index entry gives no `reads`.
+ *
+ * @param {{ label: string, reads?: string }} index
+ * @param {string} baseLabel
+ * @returns {string}
+ */
+export function derivedLabel(index, baseLabel) {
+  const reads = index.reads ?? `${index.label} of ${BASE_PLACEHOLDER}`;
+  const at = reads.indexOf(BASE_PLACEHOLDER);
+  const filled = reads
+    .split(BASE_PLACEHOLDER)
+    .join(at === 0 ? baseLabel : inSentence(baseLabel));
+  // `{base}` first in a later position, or a `reads` that starts lowercase.
+  return filled.charAt(0).toUpperCase() + filled.slice(1);
+}
+
+/**
+ * An index entry's formula with `{base}` bound: to the base symbol under its
+ * own `\explain`, for a derived card, so the reader opens the base's card
+ * from it.
+ *
+ * @param {string} formula
+ * @param {string} baseKey
+ * @param {string} baseLatex
+ * @returns {string}
+ */
+export function derivedFormula(formula, baseKey, baseLatex) {
+  return formula.split(BASE_PLACEHOLDER).join(`\\explain{${baseKey}}{${baseLatex}}`);
+}
+
+/**
+ * An index entry's own formula, shown on the index entry's card and checked
+ * by the formula gate: `{base}` becomes a placeholder square bound to the
+ * entry itself, as an operator entry is shown over a square.
+ *
+ * @param {string} formula
+ * @param {string} ownKey
+ * @returns {string}
+ */
+export function indexEntryFormula(formula, ownKey) {
+  return formula.split(BASE_PLACEHOLDER).join(`\\explain{${ownKey}}{\\square}`);
+}
+
+/**
+ * @typedef {object} DerivedSource
+ * @property {string} key
+ * @property {string} notation
+ * @property {string} label
+ * @property {string} [summary]
+ * @property {string} [units]
+ * @property {string} [reads]
+ * @property {string} [formula]
+ * @property {readonly { key: string, notation: string, label: string, units?: string, ownerKey: string }[]} [glosses]
+ */
+
+/**
+ * The derived entry for one (base, index) pair. `notation` is the indexed
+ * symbol, from `derivedNotationLatex`.
+ *
+ * @param {{ key: string, notation: string, baseLatex: string, base: DerivedSource, index: DerivedSource }} input
+ */
+export function composeDerivedEntry({ key, notation, baseLatex, base, index }) {
+  return {
+    key,
+    notation,
+    base: base.key,
+    index: index.key,
+    label: derivedLabel(index, base.label),
+    summary: index.summary ?? '',
+    glosses: [...(index.glosses ?? [])],
+    ...(base.units === undefined ? {} : { units: base.units }),
+    ...(index.formula === undefined
+      ? {}
+      : { formula: derivedFormula(index.formula, base.key, baseLatex) }),
+  };
+}

package/dist/reference/diagram-fit.d.ts

@@ -0,0 +1,45 @@
+import { M as ManifestRules } from '../course-config-rRtME5UV.js';
+import '../rules/catalog.js';
+import '../rules/course-rules.js';
+
+/**
+ * Rule V8: a diagram is no wider than the lesson column.
+ *
+ * `Diagram.astro` lays a diagram out at build time and so knows its width, but
+ * not the page it is on or what the course allows, and a diagram drawn by a
+ * wrapper component (`<CourseDiagram kind="…">`) never shows its nodes to the
+ * manifest walk. So the check runs on what was rendered: the component marks
+ * a diagram wider than {@link diagramWidthLimit} with `data-diagram-too-wide`,
+ * `compiler/astro.ts` finds each mark with {@link oversizedDiagrams} on every
+ * built page and reports a `dia-too-wide` warning with the lesson file and the
+ * diagram id, and `content warnings` lists what the last build reported
+ * (`compiler/render-diagnostics.ts`). Under `astro dev` the component prints
+ * the same message as it renders.
+ */
+
+/**
+ * The lesson column at a 1366px-wide window, the most common laptop screen
+ * (632px at 1280, 832px at 1920), unless the course sets
+ * `rules.V8.columnWidth`.
+ */
+declare const DEFAULT_COLUMN_WIDTH = 707;
+/**
+ * The widest a diagram may lay out, or `undefined` when nothing checks it: rule
+ * V8 is off, or the diagram says `warnAboveWidth={false}`. A number in
+ * `warnAboveWidth` replaces the course's column width for that diagram.
+ */
+declare function diagramWidthLimit(warnAboveWidth: number | false | undefined, rules: Pick<ManifestRules, 'disabled' | 'settings'> | undefined): number | undefined;
+/** What to tell the author about one diagram wider than its limit. */
+declare function diagramTooWideMessage(id: string, width: number, limit: number): string;
+/** A diagram on a built page that is wider than its limit. */
+interface OversizedDiagram {
+    readonly code: 'dia-too-wide';
+    /** The diagram's `id`. */
+    readonly key: string;
+    readonly width: number;
+    readonly limit: number;
+}
+/** The diagrams `Diagram.astro` marked too wide in `html`. */
+declare function oversizedDiagrams(html: string): OversizedDiagram[];
+
+export { DEFAULT_COLUMN_WIDTH, type OversizedDiagram, diagramTooWideMessage, diagramWidthLimit, oversizedDiagrams };

package/dist/reference/diagram-fit.js

@@ -0,0 +1,54 @@
+import { parse } from "parse5";
+const DEFAULT_COLUMN_WIDTH = 707;
+function diagramWidthLimit(warnAboveWidth, rules) {
+  if (warnAboveWidth === false || rules?.disabled.includes("V8")) return void 0;
+  if (warnAboveWidth !== void 0) return warnAboveWidth;
+  const columnWidth = rules?.settings.V8?.columnWidth;
+  return typeof columnWidth === "number" ? columnWidth : DEFAULT_COLUMN_WIDTH;
+}
+function diagramTooWideMessage(id, width, limit) {
+  return `Diagram "${id}" lays out ${Math.round(width)}px wide, wider than the ${limit}px it may take (rule V8), so a reader has to scroll it or widen it to see it whole. Try direction="TB", a shorter label, or a narrower node \`width\` (its label wraps inside it); set warnAboveWidth={false} only when the diagram is meant to scroll.`;
+}
+function isElement(node) {
+  return "tagName" in node;
+}
+function attribute(node, name) {
+  return node.attrs.find((attr) => attr.name === name)?.value;
+}
+function viewportKey(node) {
+  for (const child of "childNodes" in node ? node.childNodes : []) {
+    if (!isElement(child)) continue;
+    const match = /^diagram-(.+)-viewport$/.exec(attribute(child, "id") ?? "");
+    if (match) return match[1];
+    const inner = viewportKey(child);
+    if (inner) return inner;
+  }
+  return void 0;
+}
+function oversizedDiagrams(html) {
+  if (!html.includes("data-diagram-too-wide")) return [];
+  const found = [];
+  const visit = (node) => {
+    for (const child of "childNodes" in node ? node.childNodes : []) {
+      if (!isElement(child)) continue;
+      const limit = attribute(child, "data-diagram-too-wide");
+      if (limit !== void 0) {
+        found.push({
+          code: "dia-too-wide",
+          key: viewportKey(child) ?? attribute(child, "id") ?? "",
+          width: Number(attribute(child, "data-diagram-width")),
+          limit: Number(limit)
+        });
+      }
+      visit(child);
+    }
+  };
+  visit(parse(html));
+  return found;
+}
+export {
+  DEFAULT_COLUMN_WIDTH,
+  diagramTooWideMessage,
+  diagramWidthLimit,
+  oversizedDiagrams
+};