explico 0.1.1 → 0.3.0

package/src/content-config.ts

@@ -3,6 +3,7 @@ import { glob } from 'astro/loaders';
 import { z } from 'astro/zod';
 import { docsSchema } from '@astrojs/starlight/schema';
 import { isSubstantiveMeaning } from './reference/prose';
+import { glossKeySegment } from './reference/gloss';
 
 // Phase F: content lives in the top-level `content/` folder, not `src/content/`.
 // `docsLoader()` is hard-wired to `<srcDir>/content/docs`, so the `docs`
@@ -71,6 +72,42 @@ const notationSource = z.union([
  * `label` is authored only where that reads wrong. The `notationProse`
  * refinement rejects an under-specified `meaning`.
  */
+/**
+ * A **gloss** on a notation card: a symbol the card's own `formula` needs in
+ * order to be written down, carrying a name and nothing else (D15).
+ *
+ * A gloss is deliberately cheaper than a card. It has no description, no
+ * sources, no curriculum alignment, no review state, and no glossary card of
+ * its own; it is not a node in the curriculum graph and never creates a
+ * reference edge. Its key is derived, not authored — `<card key>.<slug(name)>`
+ * — so a gloss is scoped to the card that declares it and two cards may each
+ * gloss `T`. Because a formula spells LaTeX and never a key, **promoting** a
+ * gloss is exactly: delete this line, add `content/notation/<key>.md`.
+ *
+ * `units` is optional and stays a bare unit string: "T — time" is ambiguous in
+ * a corpus with several `T`s, "T — time, years from valuation" is not, and it
+ * is still one line. Prose belongs on a card.
+ */
+const notationGloss = z.object({
+  latex: z.string().min(1),
+  name: z
+    .string()
+    .min(1)
+    .refine((value) => glossKeySegment(value) !== undefined, {
+      message:
+        'A gloss name must contain letters or digits so a key can be derived from it.',
+    })
+    // The symbol goes in `latex`, the name names it. A name carrying LaTeX is
+    // the one unambiguous way to get this field wrong, so it blocks; a name
+    // that is merely long is a Tier-3 `gloss-name-shape` warning instead,
+    // because a complicated quantity may honestly need several words.
+    .refine((value) => !/[\\$`\n]/.test(value), {
+      message:
+        'A gloss name is a plain noun phrase; put the symbol in `latex`, not in the name.',
+    }),
+  units: z.string().min(1).optional(),
+});
+
 const notationEntryShape = z.object({
   key: id,
   latex: z.string().min(1),
@@ -82,6 +119,7 @@ const notationEntryShape = z.object({
   sources: z.array(notationSource).default([]),
   alignment: notationAlignmentDefault,
   label: z.string().min(1).optional(),
+  glosses: z.array(notationGloss).default([]),
 });
 
 const localNotationDefinition = notationEntryShape;

package/src/reference/base-operators.mjs

@@ -0,0 +1,103 @@
+/**
+ * The base operator library: the named mathematical operators every reader is
+ * assumed to know, so a lesson never has to introduce them with a notation
+ * entry.
+ *
+ * Rationale (parallel to `base-library.mjs`): the completeness gate has no
+ * opinion about operators — KaTeX parses `\exp`, `\int`, `\sin`, … as operator
+ * nodes, and `\operatorname{Var}` as an `operatorname` node, none of which the
+ * glyph resolver treats as a bindable symbol. The `operator-explained`
+ * consistency check (rule N8) fills that gap: an operator a lesson uses is
+ * either on this list (or the course's additions to it) or it carries a
+ * notation entry the reader can hover. This set is the "everyone knows these"
+ * baseline — trig, the exponential and logarithms, limits, extrema, and the
+ * big operators — kept greppable and small like the base library.
+ *
+ * A domain operator (`Var`, `Cov`, `Corr`, `sgn`, `erf`, `Tr`, `argmax`, …) is
+ * written `\operatorname{…}` and is NOT here: it earns a card, a
+ * `notation.local` entry, or an explicit line in `course.config.ts`
+ * (`operators.allow`).
+ *
+ * Entries are the KaTeX command without its backslash (`exp`, not `\exp`) for
+ * `op` nodes, and the verbatim body for `\operatorname{…}` nodes (`Var`).
+ * Matching is case-sensitive.
+ */
+export const BASE_OPERATORS = Object.freeze(
+  new Set([
+    // exponential / logarithms
+    'exp',
+    'log',
+    'ln',
+    'lg',
+    // trigonometric
+    'sin',
+    'cos',
+    'tan',
+    'cot',
+    'sec',
+    'csc',
+    // inverse trigonometric
+    'arcsin',
+    'arccos',
+    'arctan',
+    // hyperbolic
+    'sinh',
+    'cosh',
+    'tanh',
+    'coth',
+    // limits
+    'lim',
+    'limsup',
+    'liminf',
+    'injlim',
+    'projlim',
+    'varlimsup',
+    'varliminf',
+    'varinjlim',
+    'varprojlim',
+    // extrema
+    'max',
+    'min',
+    'sup',
+    'inf',
+    // linear algebra / number theory / misc
+    'arg',
+    'deg',
+    'det',
+    'dim',
+    'gcd',
+    'hom',
+    'ker',
+    'Pr',
+    'mod',
+    // big operators
+    'sum',
+    'prod',
+    'coprod',
+    'int',
+    'iint',
+    'iiint',
+    'oint',
+  ]),
+);
+
+/**
+ * The operators a course treats as common, given its `course.config.ts`
+ * `operators` block: the shipped baseline, plus `allow`, minus `deny`.
+ *
+ * @param {{ allow?: readonly string[], deny?: readonly string[] } | undefined} operators
+ * @returns {Set<string>}
+ */
+export function effectiveOperatorAllowlist(operators) {
+  const allow = operators?.allow ?? [];
+  const deny = new Set(operators?.deny ?? []);
+  const effective = new Set(BASE_OPERATORS);
+  for (const name of allow) effective.add(name);
+  for (const name of deny) effective.delete(name);
+  return effective;
+}
+
+/** True when `name` needs no notation entry for this course. */
+export function isBaseOperator(name, operators) {
+  return effectiveOperatorAllowlist(operators).has(name);
+}

package/src/reference/consistency.ts

@@ -19,15 +19,23 @@
  *   (f) weak-local                   a `notation.local` symbol used only in its
  *                                     own defining equation and prose
  *   (g) notation-source-locator      every notation `sources` entry has a locator
+ *   (h) operator-explained           a named operator a lesson uses is on the
+ *                                     shipped/course operator allowlist or
+ *                                     carries a notation entry (rule N8)
  *
  * Check (d) — the committed per-lesson resolution report — lives in
  * `src/content/resolution-report.ts`.
  */
 
-import type { CourseConventions } from '../compiler/course-config';
+import type {
+  CourseConventions,
+  CourseOperators,
+} from '../compiler/course-config';
 import type { CurriculumCatalog } from '../curriculum/validation';
 import type { NotationSpec } from '../compiler/collections';
 import type { LintIgnore } from './lint-ignore';
+import { effectiveOperatorAllowlist } from './base-operators.mjs';
+import { collectOperators } from './math-glyphs.mjs';
 import { offVocabularyTokens } from './units-vocab';
 import type {
   NotationDefinitionRecord,
@@ -42,7 +50,11 @@ export type ConsistencyCode =
   | 'convention-single-definition'
   | 'numerals-tagged'
   | 'weak-local'
-  | 'notation-source-locator';
+  | 'notation-source-locator'
+  | 'gloss-wants-promoting'
+  | 'card-wants-demoting'
+  | 'gloss-name-shape'
+  | 'operator-explained';
 
 export interface ConsistencyDiagnostic {
   readonly code: ConsistencyCode;
@@ -65,6 +77,8 @@ export interface ConsistencyInput {
   readonly lintIgnore: LintIgnore;
   /** Convention keys this course anchors on (from `content/course.config.ts`). */
   readonly conventions: CourseConventions;
+  /** This course's edits to the named-operator baseline (rule N8). */
+  readonly operators?: CourseOperators;
 }
 
 const CONVENTION_RE =
@@ -325,6 +339,218 @@ function checkNotationSourceLocator(
   }
 }
 
+/**
+ * The two-tier vocabulary needs both directions kept honest (D15).
+ *
+ * A gloss is cheap on purpose, and cheapness invites copying: the same symbol
+ * and name glossed on three cards is a shared meaning that should be a card,
+ * reviewed once, with sources and a curriculum home. `GLOSS_PROMOTION_LIMIT`
+ * is where "a letter this formula needs" stops being a plausible reading.
+ */
+const GLOSS_PROMOTION_LIMIT = 3;
+
+function checkGlossWantsPromoting(
+  input: ConsistencyInput,
+  out: ConsistencyDiagnostic[],
+): void {
+  const owners = new Map<string, { label: string; keys: Set<string> }>();
+  const record = (
+    ownerKey: string,
+    gloss: { notation: string; label: string },
+  ) => {
+    const id = `${gloss.notation}\u0000${gloss.label.toLowerCase()}`;
+    const current = owners.get(id) ?? { label: gloss.label, keys: new Set() };
+    current.keys.add(ownerKey);
+    owners.set(id, current);
+  };
+
+  for (const definition of input.notationInput.sharedDefinitions) {
+    for (const gloss of definition.glosses) record(definition.key, gloss);
+  }
+  for (const lesson of input.notationInput.lessons) {
+    for (const definition of lesson.localDefinitions) {
+      for (const gloss of definition.glosses) record(definition.key, gloss);
+    }
+  }
+
+  for (const [id, { label, keys }] of [...owners].sort(([a], [b]) =>
+    a.localeCompare(b),
+  )) {
+    if (keys.size < GLOSS_PROMOTION_LIMIT) continue;
+    const glyph = id.split('\u0000')[0] ?? '';
+    if (input.lintIgnore.matches('gloss-wants-promoting', glyph)) continue;
+    out.push({
+      code: 'gloss-wants-promoting',
+      severity: 'warning',
+      glyph,
+      message: `gloss ${JSON.stringify(glyph)} (${label}) is declared on ${keys.size} entries (${[...keys].sort().join(', ')}); a meaning reused this widely wants promoting to a card`,
+    });
+  }
+}
+
+/**
+ * The other direction: a card that never grew past its name is carrying the
+ * full weight of the card tier — a glossary entry, a curriculum node, a review
+ * obligation — for something a gloss would say as well.
+ */
+const CARD_BODY_MINIMUM_WORDS = 25;
+
+function checkCardWantsDemoting(
+  input: ConsistencyInput,
+  out: ConsistencyDiagnostic[],
+): void {
+  const used = new Set(
+    input.registry.backlinks.map((backlink) => backlink.key),
+  );
+
+  for (const definition of input.notationInput.sharedDefinitions) {
+    if (definition.formula !== undefined) continue;
+    if (definition.sources.length > 0) continue;
+    if (used.has(definition.key)) continue;
+    const words = stripCode(definition.body)
+      .split(/\s+/)
+      .filter((word) => word.length > 0).length;
+    if (words >= CARD_BODY_MINIMUM_WORDS) continue;
+    if (input.lintIgnore.matches('card-wants-demoting', definition.key)) {
+      continue;
+    }
+    out.push({
+      code: 'card-wants-demoting',
+      severity: 'warning',
+      key: definition.key,
+      file: definition.source.file,
+      count: words,
+      message: `notation card ${definition.key} has no formula, no sources, a ${words}-word body, and no lesson uses it; it carries no more than a name — a gloss on the entry that needs it may be the right home`,
+    });
+  }
+}
+
+/**
+ * A gloss `name` is the name of a symbol, not a description of it — the
+ * description tier is the card. The schema already blocks the unambiguous
+ * failure (LaTeX in the name); this catches the softer drift toward prose.
+ *
+ * The word limit is measured, not guessed: across the 62 shared cards the
+ * longest name is six words (`cds protection buyer net present value`), and
+ * that is the most complicated quantity in the course. A gloss names a *letter*
+ * inside one formula, so it should be shorter still. Seven or more words means
+ * the author is describing rather than naming — a warning, never a block,
+ * because a genuinely complicated quantity may earn the exception through
+ * `lint-ignore.yml`.
+ */
+const GLOSS_NAME_WORD_LIMIT = 6;
+const GLOSS_NAME_PROSE = /[.;]|\b(?:which|whose|that is|such that)\b/i;
+
+function checkGlossNameShape(
+  input: ConsistencyInput,
+  out: ConsistencyDiagnostic[],
+): void {
+  const check = (
+    gloss: { key: string; label: string },
+    file: string,
+    lessonId?: string,
+  ) => {
+    const words = gloss.label.trim().split(/\s+/).filter(Boolean);
+    const reason =
+      words.length > GLOSS_NAME_WORD_LIMIT
+        ? `${words.length} words`
+        : GLOSS_NAME_PROSE.test(gloss.label)
+          ? 'sentence punctuation or a relative clause'
+          : undefined;
+    if (reason === undefined) return;
+    if (input.lintIgnore.matches('gloss-name-shape', gloss.key)) return;
+    out.push({
+      code: 'gloss-name-shape',
+      severity: 'warning',
+      key: gloss.key,
+      file,
+      ...(lessonId ? { lessonId } : {}),
+      message: `gloss ${gloss.key} is named ${JSON.stringify(gloss.label)} (${reason}); a gloss name is a short noun phrase naming the symbol, not a description of it`,
+    });
+  };
+
+  for (const definition of input.notationInput.sharedDefinitions) {
+    for (const gloss of definition.glosses) {
+      check(gloss, definition.source.file);
+    }
+  }
+  for (const lesson of input.notationInput.lessons) {
+    for (const definition of lesson.localDefinitions) {
+      for (const gloss of definition.glosses) {
+        check(gloss, definition.source.file, lesson.lessonId);
+      }
+    }
+  }
+}
+
+/**
+ * A named operator a lesson uses is either universal — on the shipped
+ * `BASE_OPERATORS` baseline plus this course's `operators.allow`, minus its
+ * `operators.deny` — or it is explained: a notation card or `notation.local`
+ * entry the lesson binds with `[[key]]` whose `latex` is that operator, so the
+ * reader can hover it. Anything else (`\operatorname{Var}` with no entry, or a
+ * baseline operator the course chose to `deny`) is a finding. Rule N8.
+ *
+ * The glyph resolver skips operator bodies whole, so this is the only check
+ * that looks at them; it reads `collectOperators`, which parses with the same
+ * pinned KaTeX as the completeness gate.
+ */
+function checkOperatorExplained(
+  input: ConsistencyInput,
+  out: ConsistencyDiagnostic[],
+): void {
+  const allowlist = effectiveOperatorAllowlist(input.operators);
+  const byId = new Map<string, NotationDefinitionRecord>(
+    input.registry.definitions.map((definition) => [definition.id, definition]),
+  );
+  const bindingsByLesson = new Map(
+    input.registry.bundles.map((bundle) => [bundle.lessonId, bundle.bindings]),
+  );
+
+  for (const lesson of input.notationInput.lessons) {
+    // Operators the reader is shown on this page: the lesson's own
+    // `notation.local` entries, plus every shared card it binds with `[[key]]`.
+    const explained = new Set<string>();
+    const noteEntryOperators = (latex: string): void => {
+      for (const operator of collectOperators(latex)) {
+        explained.add(operator.name);
+      }
+    };
+    for (const definition of lesson.localDefinitions) {
+      noteEntryOperators(definition.notation);
+    }
+    for (const binding of bindingsByLesson.get(lesson.lessonId) ?? []) {
+      const definition = byId.get(binding.definitionId);
+      if (definition) noteEntryOperators(definition.notation);
+    }
+
+    const reported = new Set<string>();
+    for (const span of mathSpans(lesson.body)) {
+      for (const operator of collectOperators(span.latex)) {
+        if (allowlist.has(operator.name)) continue;
+        if (explained.has(operator.name)) continue;
+        if (reported.has(operator.name)) continue;
+        reported.add(operator.name);
+        if (input.lintIgnore.matches('operator-explained', operator.name)) {
+          continue;
+        }
+        const display =
+          operator.source === 'operatorname'
+            ? `\\operatorname{${operator.name}}`
+            : `\\${operator.name}`;
+        out.push({
+          code: 'operator-explained',
+          severity: 'warning',
+          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`,
+        });
+      }
+    }
+  }
+}
+
 const CHECKS: ((
   input: ConsistencyInput,
   out: ConsistencyDiagnostic[],
@@ -335,6 +561,10 @@ const CHECKS: ((
   checkNumeralsTagged,
   checkWeakLocal,
   checkNotationSourceLocator,
+  checkGlossWantsPromoting,
+  checkCardWantsDemoting,
+  checkGlossNameShape,
+  checkOperatorExplained,
 ];
 
 /**
@@ -369,6 +599,10 @@ export function consistencyCounts(
     'numerals-tagged': 0,
     'weak-local': 0,
     'notation-source-locator': 0,
+    'gloss-wants-promoting': 0,
+    'card-wants-demoting': 0,
+    'gloss-name-shape': 0,
+    'operator-explained': 0,
   } satisfies Record<ConsistencyCode, number>;
   for (const diagnostic of diagnostics) counts[diagnostic.code] += 1;
   return counts;

package/src/reference/diagram-layout.ts

@@ -0,0 +1,246 @@
+/**
+ * Build-time graph layout for the `Diagram` component.
+ *
+ * Wraps `@dagrejs/dagre` — a pure layout algorithm, no DOM — so node
+ * positions and edge routes are computed once at build time, the same way
+ * `renderLabMath` and the notation formulas are: static output, no runtime
+ * layout library shipped to the reader. `Diagram.astro` turns the result into
+ * SVG; this module only computes geometry and is deliberately framework-free
+ * so it is unit-testable without KaTeX, Astro, or a browser.
+ *
+ * Box sizes are not measured from a real render (there is no DOM at build
+ * time) — `estimateBoxSize` is a deliberately generous character-count
+ * heuristic. It is meant to avoid overlap and clipping in the common case,
+ * not to be pixel-accurate; a diagram author can always pass an explicit
+ * `width`/`height` on a node for a wide equation.
+ */
+import dagre from '@dagrejs/dagre';
+import type {
+  EdgeLabel as DagreEdgeLabel,
+  GraphLabel as DagreGraphLabel,
+  NodeLabel as DagreNodeLabel,
+} from '@dagrejs/dagre';
+
+export interface DiagramNodeInput {
+  readonly id: string;
+  readonly width: number;
+  readonly height: number;
+}
+
+export interface DiagramEdgeInput {
+  readonly from: string;
+  readonly to: string;
+}
+
+export interface DiagramLayoutOptions {
+  /** Top-to-bottom (default) or left-to-right. */
+  readonly direction?: 'TB' | 'LR';
+  readonly nodeSeparation?: number;
+  readonly rankSeparation?: number;
+  /** Uniform padding added around the computed bounding box. */
+  readonly padding?: number;
+}
+
+export interface Point {
+  readonly x: number;
+  readonly y: number;
+}
+
+export interface LaidOutNode {
+  readonly id: string;
+  /** Top-left corner, not the center dagre itself works in. */
+  readonly x: number;
+  readonly y: number;
+  readonly width: number;
+  readonly height: number;
+}
+
+export interface LaidOutEdge {
+  readonly from: string;
+  readonly to: string;
+  readonly points: readonly Point[];
+}
+
+export interface DiagramLayout {
+  readonly nodes: readonly LaidOutNode[];
+  readonly edges: readonly LaidOutEdge[];
+  /** The SVG canvas size a caller should use as the `viewBox`. */
+  readonly width: number;
+  readonly height: number;
+}
+
+/**
+ * Lay out a small directed graph. Node ids must be unique; an edge naming an
+ * undeclared node fails loudly rather than silently dropping it (dagre itself
+ * would otherwise create a phantom zero-size node).
+ */
+export function layoutDiagram(
+  nodes: readonly DiagramNodeInput[],
+  edges: readonly DiagramEdgeInput[],
+  options: DiagramLayoutOptions = {},
+): DiagramLayout {
+  const ids = new Set<string>();
+  for (const node of nodes) {
+    if (ids.has(node.id)) {
+      throw new Error(`Diagram declares node "${node.id}" more than once.`);
+    }
+    if (!(node.width > 0) || !(node.height > 0)) {
+      throw new Error(
+        `Diagram node "${node.id}" must have a positive width and height.`,
+      );
+    }
+    ids.add(node.id);
+  }
+  for (const edge of edges) {
+    if (!ids.has(edge.from)) {
+      throw new Error(`Diagram edge references unknown node "${edge.from}".`);
+    }
+    if (!ids.has(edge.to)) {
+      throw new Error(`Diagram edge references unknown node "${edge.to}".`);
+    }
+  }
+
+  const graph = new dagre.graphlib.Graph<
+    DagreGraphLabel,
+    DagreNodeLabel,
+    DagreEdgeLabel
+  >();
+  graph.setGraph({
+    rankdir: options.direction ?? 'TB',
+    nodesep: options.nodeSeparation ?? 24,
+    ranksep: options.rankSeparation ?? 48,
+    marginx: 0,
+    marginy: 0,
+  });
+  graph.setDefaultEdgeLabel(() => ({}));
+
+  for (const node of nodes) {
+    graph.setNode(node.id, { width: node.width, height: node.height });
+  }
+  for (const edge of edges) {
+    graph.setEdge(edge.from, edge.to);
+  }
+
+  dagre.layout(graph);
+
+  const centeredNodes = nodes.map((node) => {
+    const label = graph.node(node.id);
+    const cx = label.x ?? 0;
+    const cy = label.y ?? 0;
+    return {
+      id: node.id,
+      x: cx - node.width / 2,
+      y: cy - node.height / 2,
+      width: node.width,
+      height: node.height,
+    };
+  });
+
+  const rawEdges = edges.map((edge) => {
+    const label = graph.edge(edge.from, edge.to) ?? {};
+    return {
+      from: edge.from,
+      to: edge.to,
+      points: (label.points ?? []).map((point) => ({
+        x: point.x,
+        y: point.y,
+      })),
+    };
+  });
+
+  // dagre does not guarantee the layout starts at (0, 0); compute the real
+  // bounding box from node boxes and edge routing points, then shift
+  // everything so the canvas starts at `padding`.
+  const padding = options.padding ?? 12;
+  const xs = [
+    ...centeredNodes.flatMap((node) => [node.x, node.x + node.width]),
+    ...rawEdges.flatMap((edge) => edge.points.map((point) => point.x)),
+  ];
+  const ys = [
+    ...centeredNodes.flatMap((node) => [node.y, node.y + node.height]),
+    ...rawEdges.flatMap((edge) => edge.points.map((point) => point.y)),
+  ];
+  const minX = xs.length > 0 ? Math.min(...xs) : 0;
+  const minY = ys.length > 0 ? Math.min(...ys) : 0;
+  const maxX = xs.length > 0 ? Math.max(...xs) : 0;
+  const maxY = ys.length > 0 ? Math.max(...ys) : 0;
+  const shiftX = padding - minX;
+  const shiftY = padding - minY;
+
+  return {
+    nodes: centeredNodes.map((node) => ({
+      ...node,
+      x: node.x + shiftX,
+      y: node.y + shiftY,
+    })),
+    edges: rawEdges.map((edge) => ({
+      ...edge,
+      points: edge.points.map((point) => ({
+        x: point.x + shiftX,
+        y: point.y + shiftY,
+      })),
+    })),
+    width: maxX - minX + padding * 2,
+    height: maxY - minY + padding * 2,
+  };
+}
+
+// --- box-size estimation (no DOM at build time) --------------------------
+
+export interface BoxSizeEstimate {
+  readonly width: number;
+  readonly height: number;
+}
+
+const DEFAULT_MAX_WIDTH = 220;
+const MIN_WIDTH = 90;
+const PADDING_X = 20;
+const PADDING_Y = 16;
+const LINE_HEIGHT = 22;
+/** Generous per-visible-character width estimates, in px, at diagram scale. */
+const CHAR_WIDTH: Record<'text' | 'formula', number> = {
+  text: 7.2,
+  formula: 11,
+};
+
+/**
+ * A LaTeX command name (`\theta`, `\cdot`, …) renders as roughly one glyph,
+ * not one character per letter of its name; braces are structural, not
+ * visible. Collapsing both keeps the estimate from reading a formula as far
+ * wider than it will actually render.
+ */
+function formulaVisibleLength(latex: string): number {
+  const collapsed = latex
+    .replace(/\\[a-zA-Z]+/g, 'x')
+    .replace(/[{}$]/g, '')
+    .trim();
+  return Math.max(1, collapsed.length);
+}
+
+/**
+ * Estimate a diagram node's box from its label text (or raw, pre-resolution
+ * LaTeX for a formula node). Deliberately generous: it is meant to avoid
+ * clipping, not to match a real render pixel-for-pixel. Pass an explicit
+ * `width`/`height` on the node to override for a label this estimate gets
+ * badly wrong.
+ */
+export function estimateBoxSize(
+  content: string,
+  kind: 'text' | 'formula',
+  options: { readonly maxWidth?: number } = {},
+): BoxSizeEstimate {
+  const maxWidth = options.maxWidth ?? DEFAULT_MAX_WIDTH;
+  const visibleLength =
+    kind === 'formula' ? formulaVisibleLength(content) : content.trim().length || 1;
+  const charWidth = CHAR_WIDTH[kind];
+
+  const naturalWidth = visibleLength * charWidth + PADDING_X * 2;
+  const width = Math.min(maxWidth, Math.max(MIN_WIDTH, naturalWidth));
+
+  const usableWidth = width - PADDING_X * 2;
+  const charsPerLine = Math.max(1, Math.floor(usableWidth / charWidth));
+  const lines = Math.max(1, Math.ceil(visibleLength / charsPerLine));
+  const height = lines * LINE_HEIGHT + PADDING_Y * 2;
+
+  return { width: Math.round(width), height: Math.round(height) };
+}