explico 0.13.0 → 0.14.0

package/dist/reference/remark-notation.mjs

@@ -37,6 +37,8 @@ import {
   GlyphResolutionError,
   baseSymbolLatex,
   derivedNotationLatex,
+  fixedLenderMessage,
+  mathExcerpt,
   resolveMathGlyphs,
   stripNotationMarkers,
 } from './math-glyphs.mjs';
@@ -62,7 +64,23 @@ import {
   parseKnowledgeCheckRef,
 } from './knowledge-checks.mjs';
 import { injectMdxStringAttributes } from './mdx-attributes.mjs';
+import {
+  collectDeckFloats,
+  deckOfFile,
+  deckScopeChapters,
+  deckTeaches,
+  expandRecalls,
+  insertLegends,
+  manifestDeckOf,
+  markDeckChecks,
+  outcomesFrameNode,
+  readChapter,
+  stampDeckHeadings,
+  titleFrameNode,
+} from './deck-remark.mjs';
 import { collectSectionHeadings, parseSectionRef } from './sections.mjs';
+import { REGISTRY_BODY_FIX, registryGlyphScope } from './registry-scope.mjs';
+import { sourceLineOffset, shiftedPlace } from './source-lines.mjs';
 
 const PROSE_SKIP_TYPES = new Set([
   'code',
@@ -340,7 +358,7 @@ function readBracedGroup(value, start) {
 }
 
 function fail(file, message, node) {
-  if (typeof file?.fail === 'function') file.fail(message, node);
+  if (typeof file?.fail === 'function') file.fail(message, shiftedPlace(file, node));
 
   const location = file?.path ? `${file.path}: ` : '';
   throw new Error(`${location}${message}`);
@@ -348,7 +366,7 @@ function fail(file, message, node) {
 
 function warn(file, message, node) {
   if (typeof file?.message === 'function') {
-    file.message(message, node);
+    file.message(message, shiftedPlace(file, node));
     return;
   }
   console.warn(message);
@@ -365,7 +383,7 @@ function tokenLocation(file, node, value, offset) {
   if (!start || typeof start.line !== 'number') return path;
   const before = String(value).slice(0, offset);
   const newlines = before.split('\n').length - 1;
-  const line = start.line + newlines;
+  const line = start.line + sourceLineOffset(file) + newlines;
   const column =
     newlines === 0
       ? (start.column ?? 1) + offset
@@ -442,13 +460,16 @@ function inlineEquationNode(mathNode) {
  * author-written one; either way the reader copies plain LaTeX, never this
  * system's own notation-key plumbing (`math-glyphs.mjs:stripNotationMarkers`).
  */
-function equationNode(mathNode, { key, number, short }) {
+function equationNode(mathNode, { key, number, short, href }) {
   const id = equationAnchorId({ key, number });
   const hProperties = {
     id,
     className: ['keyed-equation'],
     'data-eq-number': number,
   };
+  // A deck's recall of its chapter's equation: the chapter's number, which
+  // links to the chapter (`deck-remark.mjs`).
+  if (href) hProperties['data-eq-recall'] = href;
   if (key) hProperties['data-eq-key'] = key;
   else hProperties['data-eq-auto'] = '';
   // The `\caption{}` short caption names the equation wherever it is shown
@@ -465,7 +486,7 @@ function equationNode(mathNode, { key, number, short }) {
       el('div', { className: ['keyed-equation__controls'] }, [
         {
           type: 'link',
-          url: `#${id}`,
+          url: href ?? `#${id}`,
           children: [{ type: 'text', value: `(${number})` }],
           data: {
             hProperties: {
@@ -515,6 +536,20 @@ function injectFloatNumberAttributes(node, float, prefix) {
   });
 }
 
+/**
+ * A float on a deck page: a recalled one shows the chapter's number, which
+ * links to the chapter; the deck's own is unnumbered (rule D8) and anchors at
+ * its key, or at its place among the deck's floats of its kind.
+ */
+function injectDeckFloatAttributes(node, float) {
+  // The component sees it is on a deck (`components/deck/deck-context.ts`):
+  // it takes no number of its own, and a recalled one links to its chapter.
+  injectMdxStringAttributes(node, {
+    ...(float.number === undefined ? {} : { number: float.number }),
+    anchorId: float.key ? `${float.prefix}-${float.key}` : `${float.prefix}-deck-${float.position}`,
+  });
+}
+
 /**
  * The URL path Starlight serves a docs page at: `motion/index.mdx` is
  * `/motion/`, `motion/speed.mdx` is `/motion/speed/`, `index.mdx` is `/`.
@@ -646,6 +681,29 @@ function unnumberedFloatMessage(tagName, component) {
   );
 }
 
+/**
+ * The chapter a deck's unqualified `[[eq-…]]`, `[[fig-…]]` or `[[sec-…]]`
+ * names when the deck shows no such float or frame itself: its chapter's,
+ * or on a part's deck the one covered chapter whose table (`crossPage`, by
+ * lesson slug) has `key`. Two that do leave it open: the author writes
+ * `[[<chapter>#…]]`.
+ */
+function fallbackLessonFor(ctx, key, written, file, node) {
+  const lessons = ctx.fallbackLessons;
+  if (lessons.length === 1) return lessons[0];
+  const having = lessons.filter((lesson) => ctx.crossPage?.[lesson]?.[key] !== undefined);
+  if (having.length !== 1) {
+    fail(
+      file,
+      having.length === 0
+        ? `Unknown reference ${written}: neither this deck nor a chapter it covers (${lessons.join(', ')}) has it.`
+        : `Reference ${written} on a part's deck: ${having.join(' and ')} each have one. Name the chapter: [[<chapter>#…]].`,
+      node,
+    );
+  }
+  return having[0];
+}
+
 /** Resolve a `[[eq-key]]` / `[[slug#eq-key]]` reference to `{ number, href }`. */
 function resolveEquationRef(eqRef, eqCtx, file, node) {
   if (eqRef.lesson) {
@@ -663,6 +721,11 @@ function resolveEquationRef(eqRef, eqCtx, file, node) {
     };
   }
   const number = eqCtx.pageLabels.get(eqRef.key);
+  // On a deck, an equation the deck neither labels nor recalls is its chapter's.
+  if (number === undefined && eqCtx.fallbackLessons) {
+    const lesson = fallbackLessonFor(eqCtx, eqRef.key, `[[eq-${eqRef.key}]]`, file, node);
+    return resolveEquationRef({ lesson, key: eqRef.key }, eqCtx, file, node);
+  }
   if (number === undefined) {
     fail(
       file,
@@ -694,6 +757,16 @@ function resolveKeyedFloatRef(floatRef, ctx, { prefix, tagName }, file, node) {
     };
   }
   const number = ctx.pageLabels.get(floatRef.key);
+  // On a deck, a float the deck does not recall is its chapter's.
+  if (number === undefined && ctx.fallbackLessons) {
+    return resolveKeyedFloatRef(
+      { lesson: fallbackLessonFor(ctx, floatRef.key, `[[${prefix}-${floatRef.key}]]`, file, node), key: floatRef.key },
+      ctx,
+      { prefix, tagName },
+      file,
+      node,
+    );
+  }
   if (number === undefined) {
     fail(
       file,
@@ -711,6 +784,10 @@ function resolveKeyedFloatRef(floatRef, ctx, { prefix, tagName }, file, node) {
  * reference never prints a number the reader cannot find on the page.
  */
 function resolveSectionRef(secRef, ctx, file, node) {
+  if (!secRef.lesson && ctx.fallbackLessons && !ctx.pageHeadings.has(secRef.key)) {
+    const lesson = fallbackLessonFor(ctx, secRef.key, `[[sec-${secRef.key}]]`, file, node);
+    return resolveSectionRef({ ...secRef, lesson }, ctx, file, node);
+  }
   const heading = secRef.lesson
     ? ctx.crossPage?.[secRef.lesson]?.[secRef.key]
     : ctx.pageHeadings.get(secRef.key);
@@ -1471,6 +1548,9 @@ function assertStrictNumbering({ file, slug, noun, count, placement, crossPage }
  * covers every catalogued lesson.
  */
 export default function remarkNotation(options = {}) {
+  // The processor this plugin runs in: a deck's `<Recall>` parses its chapter
+  // with the page's own parser (`deck-remark.mjs`).
+  const processor = this;
   const unknown = options.unknown ?? 'error';
   const strict = options.strict ?? false;
   // The manifest supplies every numbering input at once; an explicit option
@@ -1495,13 +1575,44 @@ export default function remarkNotation(options = {}) {
         ? options.definitions()
         : options.definitions;
     const sharedDefinitions = definitionsMap(suppliedDefinitions);
-    const registryMathDefinitions = [...sharedDefinitions.values()].map(
-      (definition) => ({ key: definition.key, notation: definition.notation }),
-    );
-    const localDefinitions = localDefinitionsFromFile(file);
-    const suspendedOperators = suspendedOperatorsFromFile(file);
-    const lessonId = lessonIdFrom(file);
+    // The same table `validate:content` checks an entry's body against.
+    const registryMathDefinitions = registryGlyphScope(sharedDefinitions.values());
+    // A deck (`<lesson>.deck.mdx`) is a page of its lesson: its symbols bind
+    // in the chapter's scope, and its numbers are the chapter's for what it
+    // recalls and its own for what it labels (`deck-remark.mjs`). A part's
+    // deck (`<part>/index.deck.mdx`) binds in its chapters' scopes, the
+    // first to define a key binding it, and recalls from the chapters its
+    // sections cover.
+    const deck = deckOfFile(file);
+    const deckEntry = deck ? manifestDeckOf(options.manifest, deck) : undefined;
+    const scopeChapters = deck ? deckScopeChapters(deck, options.manifest).map((path) => readChapter(path)) : [];
+    const localDefinitions = deck?.scope === 'part' || scopeChapters.length > 0
+      ? new Map(
+          scopeChapters
+            .flatMap((chapter) => [...definitionsMap(chapter.data.notation?.local)])
+            .filter(([key], index, all) => all.findIndex(([other]) => other === key) === index),
+        )
+      : localDefinitionsFromFile(file);
+    const suspendedOperators = deck?.scope === 'part' || scopeChapters.length > 0
+      ? [...new Set(scopeChapters.flatMap((chapter) => suspendedOperatorsFromFile({ data: chapter.data })))]
+      : suspendedOperatorsFromFile(file);
+    const lessonId = deck ? (deck.scope === 'part' ? deck.pageId : deck.lessonId) : lessonIdFrom(file);
     const lessonSlug = lessonId ? lessonId.replace(/\./g, '/') : undefined;
+    const failHere = (message, node) => fail(file, message, node);
+    if (deck) {
+      expandRecalls(tree, {
+        processor,
+        deck,
+        deckEntry,
+        manifest: options.manifest,
+        base: options.base,
+        fail: failHere,
+      });
+      if (deckEntry) stampDeckHeadings(tree, deckEntry, failHere);
+      // A question frame on a part's deck asks its section's chapter's checks.
+      if (deckEntry?.part !== undefined) markDeckChecks(tree, deckEntry, failHere);
+    }
+    const deckFloats = deck ? collectDeckFloats(tree, deckEntry) : undefined;
     // The landing page, a part's overview page (rule S10): its math binds
     // like a chapter's, but it numbers nothing.
     const nonChapterPage = !lessonId && isDocsPageFile(file);
@@ -1509,11 +1620,15 @@ export default function remarkNotation(options = {}) {
     // Missing ⇒ the legacy `##`-section numbering.
     const equationNumbering = pageNumbering(numbering, lessonSlug, 'equations');
     const registryFile = isNotationRegistryFile(file);
-    const mathScope = pageGlyphScope(
-      localDefinitions,
-      sharedDefinitions,
-      collectPageSharedKeys(tree),
-    );
+    // A deck shows its lessons' symbols: those its chapters name count as
+    // named here, as the manifest's gates count them.
+    const pageSharedKeys = collectPageSharedKeys(tree);
+    for (const chapter of scopeChapters) {
+      for (const key of collectPageSharedKeys({ type: 'root', children: [{ type: 'text', value: chapter.body }] })) {
+        pageSharedKeys.add(key);
+      }
+    }
+    const mathScope = pageGlyphScope(localDefinitions, sharedDefinitions, pageSharedKeys);
     const references = [];
     const resolved = new Map();
 
@@ -1521,7 +1636,9 @@ export default function remarkNotation(options = {}) {
     // math node is rewritten, so a `[[eq-key]]` earlier in the page still
     // resolves. `equationNumbering` picks the `‹part›.‹n›` vs `##`-section
     // scheme.
-    const equationLabels = collectEquationLabels(tree, equationNumbering);
+    const equationLabels = deckFloats
+      ? [...deckFloats.equations.values()].filter((equation) => !equation.href)
+      : collectEquationLabels(tree, equationNumbering);
     const pageLabels = new Map();
     for (const label of equationLabels) {
       if (nonChapterPage) {
@@ -1540,33 +1657,65 @@ export default function remarkNotation(options = {}) {
       }
       pageLabels.set(label.key, label.number);
     }
+    // A deck's recalled equations answer to their chapter's key on the page;
+    // a reference to anything else of the chapter's goes to the chapter.
+    if (deckFloats) {
+      for (const equation of deckFloats.equations.values()) {
+        if (equation.href && !pageLabels.has(equation.key)) pageLabels.set(equation.key, equation.number);
+      }
+    }
+    // What a deck's `[[eq-…]]`, `[[fig-…]]`, `[[sec-…]]` name when the deck
+    // shows no such float itself: its chapter's, or the one chapter of those a
+    // part's deck covers that has it.
+    const fallbackLessons = deck?.scope === 'part'
+      ? (deckEntry?.covers ?? []).map((cover) => cover.chapter)
+      : deck?.chapterPath
+        ? [lessonSlug]
+        : [];
+    const fallback = fallbackLessons.length > 0 ? { fallbackLessons } : {};
     const eqCtx = {
       base: options.base ?? '',
       pageLabels,
       crossPage: numbering.equations ?? {},
+      ...fallback,
     };
     // WERN guard: what this page prints next to the equation must be what a
-    // reference from another page prints for it.
-    assertManifestNumberParity({
-      file,
-      slug: lessonSlug,
-      pageLabels,
-      crossPage: eqCtx.crossPage,
-      placement: equationNumbering,
-      noun: 'equation',
-      syntax: (key) => `eq:${key}`,
-    });
+    // reference from another page prints for it. A deck's numbers are its
+    // own, checked against the manifest's deck instead.
+    if (!deck) {
+      assertManifestNumberParity({
+        file,
+        slug: lessonSlug,
+        pageLabels,
+        crossPage: eqCtx.crossPage,
+        placement: equationNumbering,
+        noun: 'equation',
+        syntax: (key) => `eq:${key}`,
+      });
+    } else {
+      for (const equation of deckFloats.equations.values()) {
+        if (equation.number === '?') {
+          fail(
+            file,
+            `Stale Explico manifest for the deck ${deckEntry?.slug ?? lessonSlug}: it lists no equation labelled eq:${equation.key}. Recompile the manifest.`,
+          );
+        }
+      }
+    }
 
     // Number and anchor every display equation on a lesson page, keyed or
     // not (F3). Non-lesson pages (notation registry, stray docs) keep the
-    // keyed-only behaviour so their body math is left untouched.
-    const displayEquations = lessonId
-      ? collectDisplayEquations(tree, equationNumbering)
-      : [];
+    // keyed-only behaviour so their body math is left untouched. A deck
+    // numbers only what it labels or recalls.
+    const displayEquations = deckFloats
+      ? [...deckFloats.equations].map(([node, equation]) => ({ ...equation, node }))
+      : lessonId
+        ? collectDisplayEquations(tree, equationNumbering)
+        : [];
     const equationByNode = new Map(
       displayEquations.map((equation) => [equation.node, equation]),
     );
-    if (strict) {
+    if (strict && !deck) {
       assertStrictNumbering({
         file,
         slug: lessonSlug,
@@ -1581,6 +1730,25 @@ export default function remarkNotation(options = {}) {
     // page is numbered and anchored, keyed or not — same rule as equations,
     // via the shared engine in `keyed-jsx-floats.mjs`.
     const makeFloatCtx = (tagName, crossPage, kind) => {
+      // A deck's floats: recalled ones keep the chapter's number, the deck's
+      // own are unnumbered (rule D8).
+      if (deckFloats) {
+        const prefix = { Table: 'tab', Figure: 'fig', Diagram: 'dia' }[tagName];
+        const entries = [...deckFloats.floats].filter(([, float]) => float.prefix === prefix);
+        return {
+          ctx: {
+            base: options.base ?? '',
+            pageLabels: new Map(
+              entries
+                .filter(([, float]) => float.number !== undefined)
+                .map(([, float]) => [float.key, float.number]),
+            ),
+            crossPage: crossPage ?? {},
+            ...fallback,
+          },
+          byNode: new Map(entries),
+        };
+      }
       const floatNumbering = pageNumbering(numbering, lessonSlug, kind);
       const floats = lessonId
         ? collectKeyedJsxFloats(tree, { tagName, numbering: floatNumbering })
@@ -1670,7 +1838,7 @@ export default function remarkNotation(options = {}) {
     // Outline numbering: the lesson's top-level headings take the manifest's
     // anchors and numbers before anything else reads them, and `[[sec-…]]`
     // resolves against that same table.
-    const publishedHeadings = lessonSlug
+    const publishedHeadings = lessonSlug && !deck
       ? numbering.sections?.[lessonSlug]
       : undefined;
     if (lessonId && publishedHeadings) {
@@ -1686,8 +1854,12 @@ export default function remarkNotation(options = {}) {
     const sectionCtx = {
       base: options.base ?? '',
       show: sectionSettings.show,
-      pageHeadings: new Map(Object.entries(headingsBySlug[lessonSlug] ?? {})),
+      // Beside a chapter, a deck's `[[sec-…]]` names a section of the
+      // chapter (`fallbackLessons`), on a part's deck one of a chapter it
+      // covers; a slides-first deck's names its own frame.
+      pageHeadings: new Map(fallbackLessons.length > 0 ? [] : Object.entries(headingsBySlug[lessonSlug] ?? {})),
       crossPage: headingsBySlug,
+      ...fallback,
     };
 
     const resolve = (key, kind, node) => {
@@ -1806,23 +1978,29 @@ export default function remarkNotation(options = {}) {
           if (result.unresolved.length > 0) {
             const unresolved = result.unresolved
               .map(
-                ({ token, start, suspended, font, lenders }) =>
+                ({ token, start, suspended, font, lenders, fixedLenders, instance }) =>
                   `${tokenLocation(file, node, value, start)}: "${token}"${
                     suspended
                       ? ` (${suspended} is suspended on this page, so this form needs its own entry)`
                       : font
                         ? ' (a different symbol from the plain letter; it needs its own entry)'
-                        : lenders
-                          ? ` (${lenders.join(', ')} explains only its own instances with a subscript, never a bare "${token}", rule N4: give it its own entry, or \\explain{${lenders[0]}}{${token}} if it is that entry's shorthand)`
-                          : ''
+                        : fixedLenders?.length
+                          ? ` (${fixedLenders
+                              .map((lender) => fixedLenderMessage(lender, instance ?? token))
+                              .join(' ')})`
+                          : lenders
+                            ? ` (${lenders.join(', ')} explains only its own instances with a subscript, never a bare "${token}", rule N4: give it its own entry, or \\explain{${lenders[0]}}{${token}} if it is that entry's shorthand)`
+                            : ''
                   }`,
               )
               .join(', ');
             fail(
               file,
               nonChapterPage
-                ? `Unresolved notation in ${context}: ${unresolved}. Introduce the symbol with [[key]], or wrap it in \\explain{key}{latex}: a page that is not a chapter recalls shared notation and defines none (rule S10).`
-                : `Unresolved notation in ${context}: ${unresolved}. Introduce the symbol with [[key]], define it in notation.local, or wrap it in \\explain{key}{latex}.`,
+                ? `Unresolved notation in ${context}: ${unresolved}, in ${mathExcerpt(value)}. Introduce the symbol with [[key]], or wrap it in \\explain{key}{latex}: a page that is not a chapter recalls shared notation and defines none (rule S10).`
+                : lessonId
+                  ? `Unresolved notation in ${context}: ${unresolved}, in ${mathExcerpt(value)}. Introduce the symbol with [[key]], define it in notation.local, or wrap it in \\explain{key}{latex}.`
+                  : `Unresolved notation in ${context}: ${unresolved}, in ${mathExcerpt(value)}. ${REGISTRY_BODY_FIX}`,
               node,
             );
           }
@@ -1888,6 +2066,11 @@ export default function remarkNotation(options = {}) {
           // Scoped to lesson pages, same as `displayEquations` above — a
           // registry/glossary page's inline math is left exactly as before.
           node.children[index] = inlineEquationNode(child);
+        } else if (deck && child?.type === 'mdxJsxFlowElement' && (tableByNode.has(child) || figureByNode.has(child) || diagramByNode.has(child))) {
+          injectDeckFloatAttributes(
+            child,
+            tableByNode.get(child) ?? figureByNode.get(child) ?? diagramByNode.get(child),
+          );
         } else if (child?.type === 'mdxJsxFlowElement' && tableByNode.has(child)) {
           injectFloatNumberAttributes(child, tableByNode.get(child), 'tab');
         } else if (child?.type === 'mdxJsxFlowElement' && figureByNode.has(child)) {
@@ -1981,6 +2164,32 @@ export default function remarkNotation(options = {}) {
     titleChapterLinks(tree, file, chapterTitleBySlug, options.base);
     visit(tree);
 
+    if (deck && deckEntry) {
+      // The legend lines first: they read the frames between the headings.
+      insertLegends(tree, {
+        resolved: Object.fromEntries(resolved),
+        mode: options.manifest?.deck?.legend ?? 'first-use',
+      });
+      const firstContent = tree.children.findIndex((node) => node?.type !== 'mdxjsEsm');
+      tree.children.splice(firstContent === -1 ? tree.children.length : firstContent, 0, titleFrameNode(options.manifest, deckEntry));
+      const outcomes = outcomesFrameNode(options.manifest, deckEntry, { teaches: deckTeaches(options.manifest, deckEntry) });
+      if (outcomes) tree.children.push(outcomes);
+      file.data.explicoDeck = {
+        slug: deckEntry.slug,
+        frames: deckEntry.frames.length,
+        // Each frame's id, by its number less one: `rehype-deck.mjs` stamps
+        // every frame with it, the references frame too, whose heading the
+        // citations pass writes after this one.
+        frameIds: deckEntry.frames.map((frame) => frame.id),
+        // On a part's deck, the chapter each frame's section covers, by its
+        // lesson slug (`data-chapter`), which the sidebar lights.
+        frameChapters: deckEntry.frames.map((frame) => frame.chapter ?? null),
+        aspectRatio: options.manifest?.deck?.aspectRatio ?? '16:9',
+        canvas: options.manifest?.deck?.canvas ?? { width: 1280, height: 720 },
+        notes: options.manifest?.deck?.notes ?? 'reader',
+      };
+    }
+
     file.data.notationReferences = references;
     file.data.notationResolved = Object.fromEntries(resolved);
     file.data.equationLabels = equationLabels.map(

package/dist/reference/source-lines.d.mts

@@ -0,0 +1,12 @@
+/**
+ * Lines to add to a position in `file.value` to get the line in `file.path`:
+ * 0 when the text is the whole file (or the file cannot be read), the height
+ * of the frontmatter when it is the body alone.
+ */
+export function sourceLineOffset(file: any): any;
+/**
+ * `node` with its `position` moved to the file's own lines, for
+ * `file.fail` / `file.message`, which print it. The node itself is left alone:
+ * the tree keeps the positions the parser gave it.
+ */
+export function shiftedPlace(file: any, node: any): any;

package/dist/reference/source-lines.mjs

@@ -0,0 +1,65 @@
+/**
+ * Where a vfile's text sits in the file on disk.
+ *
+ * Astro's glob loader renders a content-collection entry (a notation entry)
+ * from its body alone: the frontmatter is gone, so every `position` the remark
+ * pass reads counts lines from the first line after it, and an error naming
+ * `entry.md:1:43` points at the wrong line. A page Astro compiles whole (a
+ * lesson, through MDX) carries its full text, and its positions are already the
+ * file's own. This finds which of the two a file is, so a location can be
+ * reported the way an editor opens it.
+ *
+ * It reads the file, and only when a location is being reported (a failure or
+ * a warning), never on the happy path.
+ */
+import { readFileSync } from 'node:fs';
+
+const offsets = new WeakMap();
+
+/**
+ * Lines to add to a position in `file.value` to get the line in `file.path`:
+ * 0 when the text is the whole file (or the file cannot be read), the height
+ * of the frontmatter when it is the body alone.
+ */
+export function sourceLineOffset(file) {
+  if (!file || typeof file !== 'object') return 0;
+  if (offsets.has(file)) return offsets.get(file);
+
+  let offset = 0;
+  try {
+    const text = typeof file.value === 'string' ? file.value : undefined;
+    if (text && typeof file.path === 'string') {
+      const raw = readFileSync(file.path, 'utf8');
+      const at = raw.endsWith(text) ? raw.length - text.length : raw.indexOf(text);
+      if (at > 0) {
+        for (let index = 0; index < at; index += 1) {
+          if (raw.charCodeAt(index) === 10) offset += 1;
+        }
+      }
+    }
+  } catch {
+    // A hand-built tree has no file on disk: its positions are all there is.
+    offset = 0;
+  }
+  offsets.set(file, offset);
+  return offset;
+}
+
+/**
+ * `node` with its `position` moved to the file's own lines, for
+ * `file.fail` / `file.message`, which print it. The node itself is left alone:
+ * the tree keeps the positions the parser gave it.
+ */
+export function shiftedPlace(file, node) {
+  const position = node?.position;
+  if (!position?.start || typeof position.start.line !== 'number') return node;
+  const offset = sourceLineOffset(file);
+  if (offset === 0) return node;
+  const move = (point) =>
+    point && typeof point.line === 'number' ? { ...point, line: point.line + offset } : point;
+  // vfile-message reads a place from a node only when it has a `type`.
+  return {
+    type: node.type ?? 'unknown',
+    position: { start: move(position.start), end: move(position.end) },
+  };
+}

package/dist/reference/types.d.ts

@@ -60,6 +60,12 @@ interface SharedNotationDefinitionInput {
     readonly alignment: NotationAlignment;
     readonly aiAssisted: boolean;
     readonly body: string;
+    /**
+     * 1-based line in `source.file` where `body` starts, as on a lesson: the
+     * gate's body-relative findings are shifted by it. Optional for a
+     * hand-built input, which then behaves as 1.
+     */
+    readonly bodyLine?: number;
     /** References harvested from the Markdown body. */
     readonly references: readonly NotationReferenceInput[];
     /** Symbols this entry's `formula` names but does not make cards of. */
@@ -109,6 +115,28 @@ interface NotationLessonInput {
      * so a hand-built input (a test, an adapter) stays valid.
      */
     readonly suspended?: readonly NotationSuspension[];
+    /**
+     * A deck is a page of its own whose symbols resolve in other lessons'
+     * scopes: the ids of the lessons whose `notation.local` entries are in
+     * scope on this page, the first that defines a key binding it. A deck
+     * beside its chapter (`<lesson>.deck.mdx`, page `<lessonId>.slides`) has
+     * its chapter's; a part's deck (`<part>/index.deck.mdx`, page
+     * `<part>.slides`) every chapter of its part, in reading order. Absent:
+     * the page's own `lessonId`, and the page is no deck.
+     */
+    readonly scopeLessonIds?: readonly string[];
+    /**
+     * Those lessons' `notation.local` entries, for the gates that build a
+     * page's glyph table, the first of a key kept. They stay the chapters'
+     * definitions: the registry defines each once, under its chapter.
+     */
+    readonly inheritedLocalDefinitions?: readonly LocalNotationDefinitionInput[];
+    /**
+     * The shared keys those lessons' chapters name (`[[key]]`, `\explain{key}`):
+     * a deck may show any symbol of its lessons — what it recalls, and what its
+     * legend line introduces at its first use (`docs/authoring/deck.md`).
+     */
+    readonly inheritedKeys?: readonly string[];
     /** References harvested from lesson prose and equations, excluding definitions. */
     readonly references: readonly NotationReferenceInput[];
     /** Original lesson body, retained for lossless loader adapters. */

package/dist/rules/catalog.d.ts

@@ -26,14 +26,23 @@
  * `unchecked` by {@link enforcementOf}.
  */
 /** The part of a page a rule is about. The first tag on an entry is primary. */
-type Element = 'prose' | 'math' | 'equation' | 'notation' | 'heading' | 'part-page' | 'plot' | 'diagram' | 'table' | 'assessment' | 'source' | 'changelog';
+type Element = 'slide' | 'prose' | 'math' | 'equation' | 'notation' | 'heading' | 'part-page' | 'plot' | 'diagram' | 'table' | 'assessment' | 'source' | 'changelog';
 /** Every element, in the order the rules-in-effect page lists them. */
 declare const ELEMENTS: readonly Element[];
 /**
- * The five areas the engine ships, plus `X` — reserved for a course's own rules
+ * The six areas the engine ships, plus `X` — reserved for a course's own rules
  * and never used by an engine rule (see {@link CourseRuleId}).
  */
-type RuleArea = 'N' | 'V' | 'C' | 'S' | 'P' | 'X';
+type RuleArea = 'N' | 'V' | 'C' | 'S' | 'P' | 'D' | 'X';
+/**
+ * Which edition of a lesson a rule is about (`docs/authoring/deck.md`): its
+ * chapter, its deck (`<lesson>.deck.mdx`), or `both`. A rule without one is
+ * `both`. The rules-in-effect page is written per edition, so an author of
+ * either reads one list: a chapter-only rule is off on a deck, where a `D`
+ * rule says the same thing about a frame.
+ */
+type Edition = 'chapter' | 'deck';
+type Editions = Edition | 'both';
 type RuleId = `${RuleArea}${number}`;
 /**
  * A course's own rule, defined in `courseRules` in the course settings rather
@@ -113,6 +122,8 @@ interface RuleEntry {
      * absent means "shipped with the engine".
      */
     readonly source?: 'course';
+    /** The edition the rule is about; absent is `both` ({@link Editions}). */
+    readonly editions?: Editions;
 }
 interface InvariantEntry {
     readonly kind: 'invariant';
@@ -123,8 +134,14 @@ interface InvariantEntry {
     readonly doc: string;
     readonly summary: string;
     readonly checks: readonly [RuleCheck, ...RuleCheck[]];
+    /** The edition the invariant is about; absent is `both` ({@link Editions}). */
+    readonly editions?: Editions;
 }
 type CatalogEntry = RuleEntry | InvariantEntry;
+/** True when `entry` is in force for `edition` ({@link Editions}). */
+declare function appliesTo(entry: {
+    readonly editions?: Editions;
+}, edition: Edition): boolean;
 type Enforcement = 'script' | 'partial' | 'guide';
 /**
  * A rule that is no longer in force. It keeps its ID forever — an old commit
@@ -173,4 +190,4 @@ declare function enforcementOf(entry: CatalogEntry): Enforcement;
 /** Every code the catalog owns, sorted. */
 declare function ownedCodes(): readonly string[];
 
-export { CATALOG, type CatalogEntry, type CourseRuleId, ELEMENTS, type Element, type Emitter, type Enforcement, type InvariantEntry, type RetiredRule, type RuleArea, type RuleCheck, type RuleEntry, type RuleId, type SettingSchema, type SettingSpec, type Severity, enforcementOf, entryById, invariants, isCourseRuleId, ownedCodes, ownerOf, retiredRule, retiredRules, ruleById, ruleIdOf, rules };
+export { CATALOG, type CatalogEntry, type CourseRuleId, ELEMENTS, type Edition, type Editions, type Element, type Emitter, type Enforcement, type InvariantEntry, type RetiredRule, type RuleArea, type RuleCheck, type RuleEntry, type RuleId, type SettingSchema, type SettingSpec, type Severity, appliesTo, enforcementOf, entryById, invariants, isCourseRuleId, ownedCodes, ownerOf, retiredRule, retiredRules, ruleById, ruleIdOf, rules };