explico 0.11.1 → 0.13.0

package/dist/reference/figure-pictures.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Every figure has its picture in the built page (rule V3). A lab draws its
+ * plot in the browser, after the page loads, so without a copy drawn at
+ * build time the page holds an empty box until then: a reference card made
+ * from the page (from another page, or before the figure scrolls into view)
+ * has only the caption, and so do print without JavaScript and the
+ * standalone HTML export. A lab draws its default picture at build time and
+ * hands it to its island as children (`still-plot.ts` in the playground).
+ *
+ * `undrawnFigurePictures` reads rendered HTML: a `figure.keyed-figure` whose
+ * picture (`.keyed-figure__body`) holds an `<astro-island>` but nothing drawn
+ * (`svg`, `img`, `picture`, `canvas`, `video` or `table`) is reported.
+ * `compiler/astro.ts` runs it on every built page and warns; it is a
+ * warning, not an error, since the figure still works once hydrated.
+ */
+/** The diagnostic a built page with an undrawn picture gets. */
+interface UndrawnFigurePicture {
+    readonly code: 'lab-picture-undrawn';
+    /** The figure's anchor id, e.g. `fig-launch-angle-explorer`. */
+    readonly figure: string;
+}
+/** The figures in `html` whose picture is an island with nothing drawn. */
+declare function undrawnFigurePictures(html: string): UndrawnFigurePicture[];
+/** The build's warning for one page, naming each figure and what to do. */
+declare function undrawnFigureWarning(page: string, figures: readonly UndrawnFigurePicture[]): string;
+
+export { type UndrawnFigurePicture, undrawnFigurePictures, undrawnFigureWarning };

package/dist/reference/figure-pictures.js

@@ -0,0 +1,49 @@
+import { parse } from "parse5";
+const DRAWN = /* @__PURE__ */ new Set(["svg", "img", "picture", "canvas", "video", "table"]);
+function isElement(node) {
+  return "tagName" in node;
+}
+function attribute(node, name) {
+  return node.attrs.find((attr) => attr.name === name)?.value;
+}
+function hasClass(node, name) {
+  return (attribute(node, "class") ?? "").split(/\s+/u).includes(name);
+}
+function childrenOf(node) {
+  if (isElement(node) && node.tagName === "template") return [];
+  return "childNodes" in node ? node.childNodes : [];
+}
+function find(node, test) {
+  for (const child of childrenOf(node)) {
+    if (!isElement(child)) continue;
+    if (test(child)) return child;
+    const inner = find(child, test);
+    if (inner) return inner;
+  }
+  return void 0;
+}
+function undrawnFigurePictures(html) {
+  if (!html.includes("keyed-figure") || !html.includes("astro-island")) return [];
+  const found = [];
+  const visit = (node) => {
+    for (const child of childrenOf(node)) {
+      if (!isElement(child)) continue;
+      if (child.tagName === "figure" && hasClass(child, "keyed-figure")) {
+        const body = find(child, (el) => hasClass(el, "keyed-figure__body"));
+        if (body && find(body, (el) => el.tagName === "astro-island") && !find(body, (el) => DRAWN.has(el.tagName))) {
+          found.push({ code: "lab-picture-undrawn", figure: attribute(child, "id") ?? "" });
+        }
+      }
+      visit(child);
+    }
+  };
+  visit(parse(html));
+  return found;
+}
+function undrawnFigureWarning(page, figures) {
+  return `lab-picture-undrawn (rule V3): on rendered page "${page}", ` + figures.map(({ figure }) => `#${figure}`).join(", ") + " draw nothing until the browser runs the island, so a preview card, print without JavaScript and the HTML export show no picture. Draw the default picture at build time and pass it to the island as its children.";
+}
+export {
+  undrawnFigurePictures,
+  undrawnFigureWarning
+};

package/dist/reference/figure-symbols.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Every symbol a figure shows opens its notation card (rule N4). Lesson
+ * math, lab math (`renderLabMath`), a diagram's formulas and a caption
+ * clause's `{ math }` run all go through the glyph resolver, which binds
+ * each symbol to its key: KaTeX then wraps it in a `[data-notation-key]`
+ * span. KaTeX that a course renders itself — `katex.renderToString` in a
+ * lab's legend, axis title or slider label — skips the resolver, so its
+ * symbols have no card and nothing else would report them.
+ *
+ * `unboundFigureSymbols` reads rendered HTML: inside each
+ * `figure.keyed-figure` (a lab's tools included), every letter KaTeX draws
+ * must sit in a `[data-notation-key]`. Upright text is not a symbol:
+ * `\text{…}`, `\mathrm{…}` (the resolver skips its body, rule N10) and a
+ * named operator (`\sin`, `\max`). `compiler/astro.ts` runs it on every
+ * built page, and a course's browser test can run it on a hydrated figure's
+ * `outerHTML`, which also holds what an island draws only in the browser.
+ */
+interface UnboundFigureSymbols {
+    /** The figure's anchor id, e.g. `fig-latent-factor-model`. */
+    readonly figure: string;
+    /** Each unbound symbol's text, in document order, once. */
+    readonly symbols: readonly string[];
+}
+/** The figures in `html` that draw a symbol with no card, and those symbols. */
+declare function unboundFigureSymbols(html: string): UnboundFigureSymbols[];
+/**
+ * Fail a build whose rendered page shows a symbol in a figure that opens no
+ * card, naming the figure, the symbols, and the way to bind them.
+ */
+declare function assertFigureSymbolsBound(page: string, html: string): void;
+
+export { type UnboundFigureSymbols, assertFigureSymbolsBound, unboundFigureSymbols };

package/dist/reference/figure-symbols.js

@@ -0,0 +1,55 @@
+import { parse } from "parse5";
+const UPRIGHT = /* @__PURE__ */ new Set(["text", "mathrm", "textrm", "mop"]);
+const LETTER = new RegExp("\\p{L}", "u");
+function isElement(node) {
+  return "tagName" in node;
+}
+function attribute(node, name) {
+  return node.attrs.find((attr) => attr.name === name)?.value;
+}
+function classes(node) {
+  return (attribute(node, "class") ?? "").split(/\s+/u).filter(Boolean);
+}
+function childrenOf(node) {
+  if (isElement(node) && node.tagName === "template") {
+    return node.content.childNodes;
+  }
+  return "childNodes" in node ? node.childNodes : [];
+}
+function unboundFigureSymbols(html) {
+  if (!html.includes("keyed-figure") || !html.includes("katex-html")) return [];
+  const found = /* @__PURE__ */ new Map();
+  const visit = (node, figure, inKatex, covered) => {
+    if (isElement(node)) {
+      const names = classes(node);
+      if (node.tagName === "figure" && names.includes("keyed-figure")) {
+        figure = attribute(node, "id") ?? "(a figure with no id)";
+      }
+      if (names.includes("katex-html")) inKatex = true;
+      if (attribute(node, "data-notation-key") !== void 0 || inKatex && names.some((name) => UPRIGHT.has(name))) {
+        covered = true;
+      }
+    } else if (node.nodeName === "#text" && figure !== void 0 && inKatex && !covered) {
+      const text = node.value.trim();
+      if (LETTER.test(text)) {
+        const symbols = found.get(figure) ?? [];
+        if (!symbols.includes(text)) symbols.push(text);
+        found.set(figure, symbols);
+      }
+    }
+    for (const child of childrenOf(node)) visit(child, figure, inKatex, covered);
+  };
+  visit(parse(html), void 0, false, false);
+  return [...found].map(([figure, symbols]) => ({ figure, symbols }));
+}
+function assertFigureSymbolsBound(page, html) {
+  const unbound = unboundFigureSymbols(html);
+  if (unbound.length === 0) return;
+  throw new Error(
+    `Explico figure symbols without a notation card on rendered page "${page}": ` + unbound.map(({ figure, symbols }) => `#${figure} shows ${symbols.map((s) => `"${s}"`).join(", ")}`).join("; ") + ". Every symbol a figure shows opens its card (rule N4): render its math with renderLabMath (`{ display: false }` for a legend, an axis title or a label; a `{ math }` run for the caption clause), never with katex directly. Write a unit as `\\text{\u2026}`."
+  );
+}
+export {
+  assertFigureSymbolsBound,
+  unboundFigureSymbols
+};

package/dist/reference/figures-validate.d.ts

@@ -2,7 +2,7 @@ import { KeyedFloatLabelRecord, KeyedFloatLessonInput, KeyedFloatValidation } fr
 
 /** `validateKeyedFloats` for `<Figure>` — see `keyed-float-validate.ts`. */
 
-type FigureDiagnosticCode = 'fig-invalid-key' | 'fig-duplicate-key' | 'fig-ref-resolves' | 'fig-key-unused' | 'fig-removed-prop';
+type FigureDiagnosticCode = 'fig-invalid-key' | 'fig-duplicate-key' | 'fig-ref-resolves' | 'fig-key-unused' | 'fig-removed-prop' | 'fig-unread-prop';
 interface FigureDiagnostic {
     readonly code: FigureDiagnosticCode;
     readonly severity: 'error' | 'warning' | 'info';

package/dist/reference/gate-abbreviations.d.ts

@@ -1,6 +1,6 @@
 import { MathGateDiagnostic } from './gate-math.js';
 import { NotationRegistryInput, AbbreviationDefinitionInput } from './types.js';
-import { a as CourseAbbreviations } from '../course-config-Dsnri9Tk.js';
+import { h as CourseAbbreviations } from '../course-config-rRtME5UV.js';
 import '../rules/catalog.js';
 import '../rules/course-rules.js';
 

package/dist/reference/gate-abbreviations.js

@@ -14,7 +14,7 @@ function findAbbreviationLikeTokens(text) {
   }
   return out.sort((a, b) => a.index - b.index);
 }
-const FIX = "Add it to an abbreviations-table entry (content/abbreviations/*.md), allowlist it in abbreviations.allow in course.config.ts if it is common, non-technical usage, or \u2014 if it names a math quantity \u2014 introduce it as \\mathrm{\u2026} (or \\operatorname{\u2026}) bound to a notation entry the reader can hover. See docs/authoring/notation.md#n14.";
+const FIX = "Add it to an abbreviations-table entry (content/abbreviations/*.md), allowlist it in rules.N14.allow in the course config (course.config.ts, or the course.settings.json it reads) if it is common, non-technical usage, or \u2014 if it names a math quantity \u2014 introduce it as \\mathrm{\u2026} (or \\operatorname{\u2026}) bound to a notation entry the reader can hover. See docs/authoring/notation.md#n14.";
 function gateAbbreviations(input) {
   const { notationInput, abbreviations, courseAbbreviations } = input;
   const tableTokens = /* @__PURE__ */ new Set();

package/dist/reference/gate-course-rules.d.ts

@@ -9,9 +9,10 @@ import '../rules/catalog.js';
  *
  * One loop over every enabled course rule's `forbid` patterns, matched against
  * the same "is this really prose" surface rule N9 uses — `proseOnly` blanks
- * code fences, inline code, `$…$` / `$$…$$`, `[[key]]` references, `import`
- * lines, JSX tags and MDX comments to spaces, so offsets still point at the
- * source. A match becomes a `MathGateDiagnostic` with the rule's own ID as its
+ * code fences, inline code, `$…$` / `$$…$$`, `[[key]]` references, link
+ * addresses, `import` lines, JSX tags and MDX comments to spaces, so offsets
+ * still point at the source — plus the text of each visible prop (`caption`,
+ * `short`, `title`, `label`) as a paragraph of its own. A match becomes a `MathGateDiagnostic` with the rule's own ID as its
  * code and a lesson `file` + `line`, which is what lets `{/* explico-allow X1:
  * reason *\/}` waive one place.
  *

package/dist/reference/gate-course-rules.js

@@ -1,4 +1,5 @@
 import { lessonLine, proseOnly } from "./gate-prose-notation.js";
+import { propStrings } from "./gate-prop-text.js";
 const HEADING = /^[ \t]{0,3}(#{1,6})[ \t]+(.*)$/;
 function paragraphs(text) {
   const units = [];
@@ -32,14 +33,18 @@ function headings(text) {
   }
   return units;
 }
-function unitsFor(scope, prose) {
+const VISIBLE_PROPS = /* @__PURE__ */ new Set(["caption", "short", "title", "label"]);
+function visibleProps(body) {
+  return propStrings(body).filter((prop) => VISIBLE_PROPS.has(prop.name) && prop.value.trim() !== "").map((prop) => ({ text: prop.value, index: prop.offset }));
+}
+function unitsFor(scope, prose, body) {
   switch (scope) {
     case "prose":
-      return [{ text: prose, index: 0 }];
+      return [{ text: prose, index: 0 }, ...visibleProps(body)];
     case "heading":
       return headings(prose);
     case "paragraph":
-      return paragraphs(prose);
+      return [...paragraphs(prose), ...visibleProps(body)];
   }
 }
 function* matches(pattern, unit) {
@@ -59,7 +64,7 @@ function gateCourseRules(lessons, rules) {
     const cache = /* @__PURE__ */ new Map();
     for (const rule of active) {
       for (const pattern of rule.forbid) {
-        if (!cache.has(pattern.scope)) cache.set(pattern.scope, unitsFor(pattern.scope, prose));
+        if (!cache.has(pattern.scope)) cache.set(pattern.scope, unitsFor(pattern.scope, prose, lesson.body));
         for (const unit of cache.get(pattern.scope)) {
           for (const [index, token] of matches(pattern, unit)) {
             diagnostics.push({

package/dist/reference/gate-heading-length.d.ts

@@ -10,6 +10,8 @@ declare const HEADING_LENGTH_LIMIT = 65;
  */
 declare function gateHeadingLength(lessons: readonly NotationLessonInput[], options?: {
     readonly maxLength?: number;
+    /** A `[[key]]` term's label on a lesson's page, as a heading shows it. */
+    readonly labelFor?: (lessonId: string, key: string) => string | undefined;
 }): MathGateDiagnostic[];
 
 export { HEADING_LENGTH_LIMIT, gateHeadingLength };

package/dist/reference/gate-heading-length.js

@@ -1,5 +1,6 @@
 import { EQ_CAPTION_PATTERN, stripFencedCode } from "./equations.mjs";
 import { stripHeadingMarker } from "./rehype-heading-anchors.mjs";
+import { headingDisplayText } from "./sections.mjs";
 import { lessonLine } from "./gate-prose-notation.js";
 const HEADING_LENGTH_LIMIT = 65;
 const HEADING_LINE = /^[ \t]{0,3}(#{1,6})[ \t]+(.+?)[ \t]*#*[ \t]*$/gm;
@@ -20,13 +21,13 @@ function readAttribute(attributesSource, name) {
 function overLimitMessage(kind, text, limit) {
   return `${kind} ${JSON.stringify(text)} is ${text.length} characters, over the ${limit}-character limit (rule S1, rules.S1.maxLength in the course settings). Shorten it and move the rest into the paragraph or caption that follows.`;
 }
-function headingFindings(text, limit) {
+function headingFindings(text, limit, labelFor) {
   const out = [];
   const re = new RegExp(HEADING_LINE.source, HEADING_LINE.flags);
   let match;
   while (match = re.exec(text)) {
     const level = match[1]?.length ?? 1;
-    const title = stripHeadingMarker(match[2] ?? "").trim();
+    const title = headingDisplayText(stripHeadingMarker(match[2] ?? ""), { labelFor });
     if (title.length > limit) {
       out.push({
         index: match.index,
@@ -71,9 +72,9 @@ function equationCaptionFindings(text, limit) {
   }
   return out;
 }
-function findingsIn(text, limit) {
+function findingsIn(text, limit, labelFor) {
   return [
-    ...headingFindings(text, limit),
+    ...headingFindings(text, limit, labelFor),
     ...floatTitleFindings(text, limit),
     ...equationCaptionFindings(text, limit)
   ].sort((a, b) => a.index - b.index);
@@ -83,7 +84,8 @@ function gateHeadingLength(lessons, options = {}) {
   const limit = options.maxLength ?? HEADING_LENGTH_LIMIT;
   for (const lesson of lessons) {
     const text = stripFencedCode(lesson.body);
-    for (const finding of findingsIn(text, limit)) {
+    const labelFor = options.labelFor ? (key) => options.labelFor?.(lesson.lessonId, key) : void 0;
+    for (const finding of findingsIn(text, limit, labelFor)) {
       diagnostics.push({
         context: "structure",
         code: "title-length",

package/dist/reference/gate-heading-structure.js

@@ -67,6 +67,31 @@ function skipFindings(blocks) {
   }
   return out;
 }
+const HOSTS = ["Memo", "ShortNote"];
+function nestedFindings(body) {
+  const blank = (match) => match.replace(/[^\n]/g, " ");
+  const text = body.replace(/```[\s\S]*?```/g, blank).replace(/\{\/\*[\s\S]*?\*\/\}/g, blank);
+  const out = [];
+  for (const host of HOSTS) {
+    const opening = new RegExp(`<${host}\\b(?:[^>"']|"[^"]*"|'[^']*')*(?<!/)>`, "g");
+    for (const open of text.matchAll(opening)) {
+      const start = (open.index ?? 0) + open[0].length;
+      const end = text.indexOf(`</${host}>`, start);
+      if (end === -1) continue;
+      for (const inner of text.slice(start, end).matchAll(/<(AssessmentSet|CompactExamples)\b/g)) {
+        const name = inner[1];
+        const what = name === "CompactExamples" ? "set of worked examples" : "knowledge check";
+        out.push({
+          code: "heading-nested",
+          index: start + (inner.index ?? 0),
+          token: `<${name}>`,
+          message: `\`<${name}>\` sits inside a \`<${host}>\`, ${TITLED_COMPONENTS[name].what}, ${host === "Memo" ? "under the memo\u2019s own `<h6>`" : "in the middle of the note"}: the heading order jumps, and "On this page" never lists it (rule S6). A ${what} is a section of the lesson: put it at the top level, after the ${host === "Memo" ? "memo" : "paragraph"}.`
+        });
+      }
+    }
+  }
+  return out;
+}
 function adjacentFindings(blocks, lesson) {
   const out = [];
   blocks.forEach((block, position) => {
@@ -92,6 +117,7 @@ function gateHeadingStructure(lessons, options = {}) {
     const blocks = blocksOf(lesson.body);
     const findings = [
       ...levels ? skipFindings(blocks) : [],
+      ...levels ? nestedFindings(lesson.body) : [],
       ...adjacency ? adjacentFindings(blocks, lesson) : []
     ].sort((a, b) => a.index - b.index);
     for (const finding of findings) {

package/dist/reference/gate-indices.d.ts

@@ -0,0 +1,35 @@
+import { ScopeEntry, AssessmentLike, LessonAssessmentLink, MathGateDiagnostic } from './gate-math.js';
+import { ResolvedGloss } from './gloss.js';
+import { NotationLessonInput, DerivedUse, IndexedSymbol } from './types.js';
+
+/** What the check needs of an entry besides its glyph-table row. */
+interface IndexEntryFacts extends ScopeEntry {
+    readonly range?: string;
+    readonly formula?: string;
+    readonly glosses?: readonly ResolvedGloss[];
+    readonly source?: {
+        readonly file: string;
+    };
+}
+/**
+ * Run rule N23 over every lesson (and non-chapter page) body, every notation
+ * formula and every assessment, and collect the derived cards each body
+ * uses. `entries` holds every shared entry by key; a lesson's own come from
+ * its `localDefinitions`. The index-set check (`index-range`) reads lesson
+ * bodies only: a letter's set is stated on its card or on the page.
+ */
+declare function gateIndices(lessons: readonly NotationLessonInput[], entries: ReadonlyMap<string, IndexEntryFacts>, extras?: {
+    readonly assessments?: readonly AssessmentLike[];
+    readonly lessonAssessments?: readonly LessonAssessmentLink[];
+}): {
+    diagnostics: MathGateDiagnostic[];
+    derivedByLesson: Map<string, DerivedUse[]>;
+};
+/**
+ * Rule N23's findings in one math source rendered outside a lesson body — a
+ * lab's or a diagram's, which fail the build as they render — as one line
+ * each: the form, what explains none of it, and the fix.
+ */
+declare function indexFindings(indices: readonly IndexedSymbol[]): string[];
+
+export { DerivedUse, type IndexEntryFacts, gateIndices, indexFindings };