@jokerized/decksmith 0.7.0 → 0.8.0

package/dist/types/emit/archetypes/equation-morph.d.ts

@@ -1,2 +1,42 @@
+/**
+ * An equation becoming the next one.
+ *
+ * The keyed morph — the 3Blue1Brown move — and the one thing in the vocabulary
+ * that shows a DERIVATION rather than a statement: the terms the author keys
+ * travel from where they sit in the first line to where they sit in the second,
+ * as rigid bodies, and everything else dissolves. Which terms are keyed is the
+ * animation: `a^2+b^2=c^2` to `c^2-b^2=a^2` is a glyph riot unkeyed and a
+ * three-body exchange keyed, on the same two strings.
+ *
+ * The keying reuses `equation-walk`'s: a term is located in the TeX by normal
+ * form and wrapped in `\htmlClass{term t-<tone> ds-k-<tone>}{...}`, so KaTeX
+ * emits a real element the runtime can find. It must be found in BOTH lines
+ * to be a key at all — a term on one side only is dropped, with its legend
+ * row, exactly as the walk drops a term it cannot place.
+ *
+ * Geometry is measured in the browser, after fonts (Seam B), and the morph
+ * reaches the timeline as ONE typed `fromTo` on the host driving a GSAP plugin.
+ * See `src/emit/morph-runtime.ts` for why that, and not a callback.
+ */
+import type { BeatOf, Source, Term } from "../../types.js";
 import type { Emitter } from "../kit.js";
+/**
+ * Both lines and their keys, decided in Node — the morph's half of what
+ * `prepareWalk` is to the walk, so `plan` can report what `build` will do.
+ * Throws where the emitter would: a line KaTeX refuses even repaired, or no key.
+ */
+export declare function prepareMorph(beat: BeatOf<"equation-morph">, source: Source): {
+    a: {
+        id: string;
+        tex: string;
+    };
+    b: {
+        id: string;
+        tex: string;
+    };
+    wa: string;
+    wb: string;
+    both: Term[];
+    notes: string[];
+};
 export declare const equationMorph: Emitter<"equation-morph">;

package/dist/types/emit/archetypes/equation-walk.d.ts

@@ -10,7 +10,14 @@ import type { Term } from "../../types.js";
 import type { Emitter, Theme } from "../kit.js";
 export declare const OPTS = "{ displayMode: true, trust: function (c) { return c.command === \"\\\\htmlClass\"; }, strict: false, output: \"html\" }";
 export declare const INLINE_OPTS = "{ displayMode: false, trust: function (c) { return c.command === \"\\\\htmlClass\"; }, strict: false, output: \"html\" }";
-/** Where `term` sits in `tex`, comparing normal forms. Null when it is absent. */
+/**
+ * Where `term` sits in `tex`, comparing normal forms. Null when it is absent.
+ *
+ * The span starts at the first matched character's token — with the `\left`
+ * that sizes it, when the term opens on a sized delimiter — and ends where the
+ * last matched character's token ends. Never further: whatever follows the term
+ * in the equation, a `\right` included, is not the term's.
+ */
 export declare function locate(tex: string, term: string): {
     start: number;
     end: number;
@@ -36,7 +43,47 @@ cls?: (t: Term) => string): {
     tex: string;
     used: Term[];
     missing: Term[];
+    broken: Term[];
 };
+/** What `prepareWalk` decided about one equation and its terms. */
+export interface PreparedWalk {
+    /** The TeX to render, repaired and term-wrapped. Absent when `plain`. */
+    tex?: string;
+    /** The repaired TeX without wrappers, for measuring. The source TeX when `plain`. */
+    raw: string;
+    /** Set when KaTeX refuses the equation even after repair. */
+    plain?: {
+        error: string;
+    };
+    used: Term[];
+    missing: Term[];
+    notes: string[];
+}
+/**
+ * Everything the walk needs to draw one equation, decided in Node — so `plan`
+ * can report it and `build` cannot ship a `katex.render` call that throws.
+ *
+ * The equation is parsed and, if KaTeX refuses it, repaired (`repairTex`). Each
+ * term is repaired the same way, so a term spelled with the paper's own macro
+ * still finds it once both are drawn as names. Then the terms are wrapped, each
+ * wrapping parsed before it is kept.
+ *
+ * An equation no repair makes parseable is DEGRADED, not dropped and not
+ * shipped: `plain` is set and the slide shows the TeX source as text, with the
+ * terms still marked so the walk still walks. `notes` says, in words, every
+ * repair, degradation and dropped term — `plan` prints them and `build` reports
+ * them as the beat's warnings.
+ */
+export declare function prepareWalk(eq: {
+    id: string;
+    tex: string;
+}, terms: readonly Term[], beatId: string): PreparedWalk;
+/**
+ * A legend chip's contents: the term's TeX for KaTeX when it parses inline
+ * (repaired if it had to be), and its source as plain text when it does not —
+ * a chip is where a viewer reads WHICH symbol, so it is never left empty.
+ */
+export declare function chipSetup(sid: string, term: Term): string;
 /**
  * Display equations want to live between 68px and 108px.
  *
@@ -58,6 +105,18 @@ cls?: (t: Term) => string): {
 export declare function equationSize(tex: string): number;
 /** Estimated rendered width of a display, in ems. */
 export declare function texUnits(tex: string): number;
+/**
+ * Grow each legend chip to hold the glyphs KaTeX set in it.
+ *
+ * A chip is a painted box with 2px of vertical padding, and the layout gate
+ * measures text against the nearest painted box. `x^{\text{gt}}_{<i}` or a
+ * `\frac` sets glyph boxes above and below the line box, so the chip failed
+ * `text_box_overflow` on its own superscript — measured on HypePaper deck
+ * 0ef77cae: the `gt` sat 10px above the chip's top edge. Padding is added only
+ * where a glyph box actually crosses an edge, so a chip that already held its
+ * term is untouched.
+ */
+export declare function chipFit(sid: string, terms: Term[]): string[];
 /** One row per term: a chip KaTeX fills in `setup`, and the label. Shared with the morph. */
 export declare function legendRows(sid: string, terms: Term[], theme: Theme): string;
 export declare function legendCss(theme: Theme): string;

package/dist/types/emit/tex.d.ts

@@ -0,0 +1,39 @@
+/**
+ * The attribute `equation-walk`'s fit leaves on a display it could not fit,
+ * holding the formula. `fidelity` reads it and fails the deck naming that
+ * formula — the one statement the layout gate's `span.mord` cannot make.
+ */
+export declare const UNFIT_ATTR = "data-ds-unfit";
+/** KaTeX's message for `tex`, or null when it parses. Same options the deck uses. */
+export declare function texError(tex: string, display: boolean): string | null;
+export interface Repaired {
+    /** The TeX to render: the input when it parsed, otherwise the repaired form. */
+    tex: string;
+    /** One sentence per repair made, in the order made. Empty when none was needed. */
+    repairs: string[];
+    /** KaTeX's message when even the repaired form does not parse; null otherwise. */
+    error: string | null;
+}
+/**
+ * Parse `tex`; if KaTeX refuses it, apply the repairs that cannot change its
+ * meaning, one at a time, until it parses or none is left to try.
+ *
+ * THE REPAIRS, and why each is safe:
+ *
+ * - An UNBALANCED `\left`/`\right` is closed with the null delimiter `\right.`
+ *   (or opened with `\left.`). The delimiter the author wrote is still drawn,
+ *   at the size it was asked for; only the missing invisible partner is added.
+ * - An UNBALANCED brace group is closed at the end, or opened at the start.
+ * - `\label`, `\nonumber`, `\notag` are removed (see `NO_INK`).
+ * - An UNDEFINED macro — a paper's own `\newcommand`, which the source never
+ *   carries — is drawn as its NAME in upright type: `\raydir` becomes
+ *   `\operatorname{raydir}`, an operator rather than `\mathrm` so that two in a
+ *   row keep a space between them (`\camerarot \cameraint` set as `\mathrm`
+ *   read "camerarotcameraint"). A degradation, not a restoration, and the sentence
+ *   it returns says so; but it keeps the symbol on the slide under the name the
+ *   paper gave it, where the alternatives are to drop the symbol or the slide.
+ *
+ * Deterministic: the same input always produces the same output and sentences,
+ * which is what lets `plan` report a repair that `build` will then make.
+ */
+export declare function repairTex(input: string, display: boolean): Repaired;

package/dist/types/index.d.ts

@@ -123,8 +123,11 @@ export { verify } from "./verify/index.js";
  * `scanBeatCount` also fold into `verify`; that one needs the preferences the
  * deck was asked for, which a built directory does not carry — and
  * `scanUnusedFigures` folds in only where the source was passed alongside.
+ * `scanMath` does not fold into `verify`: by then the build has already said
+ * the same thing through `onBeatWarning`, and saying it twice trains people to
+ * stop reading it.
  */
-export { scanBeatCount, scanNarrationDrift, scanPaperArc, scanHeadlines, scanNarrationLead, scanRepeatedObject, scanUnusedFigures, } from "./verify/index.js";
+export { scanBeatCount, scanMath, scanNarrationDrift, scanPaperArc, scanHeadlines, scanNarrationLead, scanRepeatedObject, scanUnusedFigures, } from "./verify/index.js";
 export { check, parseCheckReport, sampleTimes } from "./verify/check.js";
 export type { CheckOptions } from "./verify/check.js";
 /**

package/dist/types/plan/prompt.d.ts

@@ -1,15 +1,3 @@
-/**
- * What the model is told, and what it is told about.
- *
- * Planning quality is the product, and this file is where it is won or lost —
- * the schema only guarantees the storyboard is well-formed, never that it is a
- * good explanation of this particular document.
- *
- * `renderSource` deliberately puts every citable id next to its caption. The
- * model cannot cite an id it was never shown, so the inventory is the cheapest
- * defence against the failure mode that actually happens: a plausible-looking
- * `figureId` that exists in no source.
- */
 import type { Prefs } from "../prefs.js";
 import { type Source } from "../types.js";
 /**

package/dist/types/render/capture.d.ts

@@ -66,6 +66,30 @@ export interface ResolvedChrome {
 export declare function resolveChrome(need?: string): Promise<ResolvedChrome>;
 /** The path alone, for the callers that only ever wanted that. */
 export declare function chromePath(need?: string): Promise<string>;
+/**
+ * Whether Chrome died for want of a sandbox. Stock Ubuntu 24.04, GitHub's
+ * `ubuntu-latest` included, sets `kernel.apparmor_restrict_unprivileged_userns=1`.
+ * Chrome's sandbox needs exactly those namespaces, so it exits at launch with
+ * `FATAL:zygote_host_impl_linux.cc(…)] No usable sandbox!`, which puppeteer
+ * quotes in the error it throws.
+ */
+export declare function sandboxMissing(err: unknown): boolean;
+/** How a person gets the sandbox back. */
+export declare const SANDBOX_FIX = "`sudo sysctl -w kernel.apparmor_restrict_unprivileged_userns=0`, or give Chrome an AppArmor profile";
+/**
+ * Launch Chrome for a page DeckSmith wrote itself: a built deck, a caption band.
+ *
+ * On a host with no usable sandbox (`sandboxMissing`) every gate that opens the
+ * deck reported `not_measured`, a warning, so `build` PASSED having measured
+ * nothing (.planning/2026-09-18-linux-determinism.md §4). The sandbox stays on
+ * wherever Chrome can have one. Only when Chrome refuses to start without it is
+ * the launch retried with `--no-sandbox`, and stderr says so. That is no wider
+ * than the render already is: hyperframes launches its own capture with
+ * `--no-sandbox` every time, on this same deck.
+ *
+ * Pages from the web never come here: `harvest` refuses instead.
+ */
+export declare function launchOwnPage<T>(launch: (args: string[]) => Promise<T>, args: string[], what: string): Promise<T>;
 type Browser = Awaited<ReturnType<typeof import("puppeteer-core").launch>>;
 type Page = Awaited<ReturnType<Browser["newPage"]>>;
 /** An open deck, seekable and photographable. Close it. */

package/dist/types/render/timing.d.ts

@@ -111,6 +111,22 @@ export interface Timing {
      * written without it, and those decks did reserve nothing.
      */
     captionReserve?: number;
+    /**
+     * The format the deck was built for: its id and its duration budget.
+     *
+     * The composition records only pixels, and `verify` used to find the budget
+     * by looking those up among the presets. A custom canvas matches none, so
+     * every custom build read "no duration budget applies" — true of the pixels
+     * and false of the deck, which inherits the budget of the profile it was
+     * resized from (`resizeFormat`). Optional, and absent falls back to the pixel
+     * lookup: every `timing.json` written before this lacks it.
+     */
+    format?: {
+        id: string;
+        minWeight: number;
+        maxSeconds?: number;
+        warnSeconds?: number;
+    };
     scenes: TimedScene[];
     segments: TimedSegment[];
 }

package/dist/types/verify/budget.d.ts

@@ -26,6 +26,13 @@ export declare function readCanvas(html: string): Canvas | undefined;
  * be its own is a gate people learn to ignore. Today the two 16:9 profiles have
  * the same (absent) budget, so the reading is exact as well as safe.
  */
+/** What the budget gate reads off a format, whether a preset or the one `build` recorded. */
+export type BudgetFormat = Pick<Format, "id" | "minWeight" | "maxSeconds" | "warnSeconds">;
+/** `timing.json`'s record of the format, with the canvas it was recorded for. */
+export interface RecordedFormat extends BudgetFormat {
+    width: number;
+    height: number;
+}
 export declare function profilesFor(width: number, height: number, formats?: Readonly<Record<string, Format>>): Format[];
 /**
  * The budget finding for one built composition, if there is one.
@@ -46,4 +53,4 @@ export declare function profilesFor(width: number, height: number, formats?: Rea
  * a table that disagrees, rather than the rule being deleted and silently absent
  * the next time a real destination is tighter than the rest.
  */
-export declare function scanBudget(html: string, storyboard?: Storyboard, kept?: readonly Beat[], formats?: Readonly<Record<string, Format>>): Finding[];
+export declare function scanBudget(html: string, storyboard?: Storyboard, kept?: readonly Beat[], formats?: Readonly<Record<string, Format>>, recorded?: RecordedFormat): Finding[];

package/dist/types/verify/fidelity.d.ts

@@ -291,6 +291,25 @@ export declare function gradeFidelity(rows: readonly Measured[], floor?: number)
  * thing it was told to deliver, not a note about taste.
  */
 export declare function gradeReserve(rows: readonly Measured[], tolerance?: number): Finding[];
+/** An equation the deck's own fit gave up on: the scene, and the formula. */
+export interface Unfit {
+    sid: string;
+    tex: string;
+}
+/**
+ * Run IN THE PAGE: every display `equation-walk`'s fit marked as not fitting.
+ *
+ * Read once, after the ready gate — the fit runs inside it, before any frame,
+ * so the marks are the same at every time the deck could be seeked to.
+ */
+export declare function collectUnfit(attr: string): Unfit[];
+/**
+ * An error per equation that does not fit its box at the type floor even broken
+ * across lines, NAMING THE FORMULA. The layout gate sees the same overflow and
+ * can only say `span.mord`, which tells nobody which of a deck's equations to
+ * shorten.
+ */
+export declare function gradeUnfit(rows: readonly Unfit[]): Finding[];
 /**
  * Seek every declared stop and count the ink below its caption.
  *

package/dist/types/verify/index.d.ts

@@ -171,6 +171,23 @@ export declare function scanRepeatedObject(storyboard: Storyboard): Finding[];
  * citing it in evidence is a different defect, and not this scan's to report.
  */
 export declare function scanUnusedFigures(storyboard: Storyboard, source: Source): Finding[];
+/**
+ * Every equation a walk or a morph will draw, parsed now by the KaTeX the deck
+ * vendors, with what `build` will do about each one said in words.
+ *
+ * Run at `plan` because that is when the storyboard is in front of the author
+ * and the cheapest moment to change a beat. Before this, a bad formula was first
+ * parsed by a browser at `verify`, after a deck had been built and narrated
+ * around it: 26 of 92 HypePaper build failures in the week to 2026-10-07.
+ *
+ * It calls the SAME preparation the emitters call (`prepareWalk`,
+ * `prepareMorph`), so what it reports is what `build` will do, not a second
+ * opinion that can drift from it. A WARNING throughout: a repaired formula, a
+ * formula shown as plain source and a dropped term are all drawn without
+ * throwing — and a beat that will be left out is reported again, by name, when
+ * `build` leaves it out.
+ */
+export declare function scanMath(storyboard: Storyboard, source: Source): Finding[];
 /**
  * Warn when the plan came back with fewer beats than were asked for.
  *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jokerized/decksmith",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "Turn a source document into an animated explanation deck.",
   "type": "module",
   "license": "MIT",