@jokerized/decksmith 0.8.0 → 0.9.1

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

@@ -0,0 +1,205 @@
+/**
+ * THE FILL GATE — at each scene's last hold, how much of its region did the
+ * body actually paint, and did the build predict that?
+ *
+ * WHY THIS EXISTS. The founder's complaint was "the content doesn't fill the
+ * screen", and v0.8.0 passes every gate while doing exactly that: the solvers
+ * could only shrink, so a two-bar comparison drew two 96px bars in a ~700px
+ * region and `.scene` centred the rest into air. The v2 archetypes grow into
+ * their region and PREDICT the result (`Scene.fit`, `src/emit/fit.ts`); a
+ * prediction nobody checks is the green-gate-over-wrong-output shape this
+ * project keeps producing, so the browser measures the same ratio here, on the
+ * frame `fidelity` has already seeked and captured.
+ *
+ * WHAT IS MEASURED: MAIN-AXIS FILL, IN PIXELS. The region is the room the body
+ * was given: `.scene`'s content box less the height of its `.headline` and
+ * `.eyebrow` (see `FillRegion` for why that is not "everything under the
+ * headline"). The body's extent is the first to the last pixel ROW, from the
+ * chrome's bottom edge down to the frame's bottom edge, that holds at least
+ * `MIN_ROW_INK` pixels off the frame's modal background (the same
+ * background-relative test `fidelity` uses, so it is theme-independent). Fill is
+ * that extent over the region's height. Scanning past the content box is
+ * deliberate: a body that spills into the padding reads above 1, which is the
+ * SPILLAGE band rather than a silently clipped 1.0.
+ *
+ * PIXELS, NOT DOM BOXES, for the reason `fidelity.ts` gives at length: a
+ * wrapper's box is the size of its slot, not of what it shows — `.titleslide` is
+ * `height:100%`, `.panels` is `flex:1` — and visibility read off the DOM has been
+ * wrong in this project before. A panel wash too close to the background to
+ * clear `INK_DELTA` does not count; its border and its text do.
+ *
+ * ALSO REPORTED, for the eval and never graded: `cross`, the same ratio across
+ * the region's width, and `canvas`, the union box of ALL ink on the frame
+ * (chrome included) over the frame's area — the "bbox" share the 2026-10-07
+ * density audit quoted for bar-compare and pipeline (51%).
+ *
+ * AND TWO AREA MEASURES, because `fill` is an EXTENT and cannot see area: two
+ * thin bars spanning a 1700px axis, a white figure plate, or cards with empty
+ * bottom halves all read full (review, 2026-10-08). `occupancy` cuts the whole
+ * frame (less a 3% border) into 40px cells, at 1080p scale, and reports the
+ * share holding ink (`cells`) and the share whose pixels VARY (`detail`): a
+ * flat run of colour — a plate's empty white, a panel's wash, a bar's inside —
+ * is ink but not detail. Both are placement-independent: they do not move when
+ * a look redefines where its body region is.
+ *
+ * GRADED ONLY ON A V2 DECK, i.e. one whose build wrote `fit.json`. A classic deck
+ * is measured (so the eval can compare the two designs on the same storyboard)
+ * but never gets a finding: v0.8.0's verdicts do not move. Both findings are
+ * WARNINGS, as the plan's M1 sets them — a new gate starts by reporting:
+ *
+ *   hollow_at_hold        measured fill under 0.70, the EMPTY band
+ *   fill_model_disagrees  |predicted − measured| over 0.20 — the build-time
+ *                         arithmetic and the browser disagree, which is a bug
+ *                         in the model, not a matter of taste
+ */
+import { type FitManifest } from "../emit/fit.js";
+import type { Finding } from "../types.js";
+/** A row counts as painted from this many off-background pixels: one is a stray fringe. */
+export declare const MIN_ROW_INK = 2;
+/** Predicted and measured fill may differ by this much before the model is called wrong. */
+export declare const FILL_TOLERANCE = 0.2;
+/** Device px, in the frame's own coordinates. */
+export interface Box {
+    left: number;
+    right: number;
+    top: number;
+    bottom: number;
+}
+/** The pixel test `fidelity` uses: what counts as ink, and against what. */
+export interface InkTest {
+    bg: readonly [number, number, number];
+    delta: number;
+    /**
+     * The page's background as a FRAME — every scene hidden, the body's own paint
+     * left — compared pixel for pixel instead of against `bg`. A v2 style pack
+     * paints its ground with gradients, a grid or dots (src/emit/themes/packs.ts),
+     * so no single colour is the background: a 7% cyan grid line on blueprint is
+     * 12 levels off its navy, and atlas's vignette darkens the corners by far more.
+     * Against one colour those read as ink and a sparse slide measured full. When
+     * its size differs from the frame's it is ignored and `bg` is used.
+     */
+    plate?: FrameLike;
+}
+interface FrameLike {
+    width: number;
+    height: number;
+    channels: number;
+    pixels: Uint8Array;
+}
+/**
+ * The extent of ink inside `box`, or null when there is none. Pure, so what the
+ * gate counts can be tested without a browser.
+ *
+ * A row is painted when it holds `MIN_ROW_INK` ink pixels between `box.left` and
+ * `box.right`; the vertical extent is the first and last such row. The
+ * horizontal extent is then read over those rows only, by the same rule turned
+ * ninety degrees.
+ */
+export declare function inkExtent(frame: FrameLike, test: InkTest, box: Box): Box | null;
+/**
+ * A scene's body region, as the page reports it: where to LOOK for the body's
+ * ink (`top` is the chrome's bottom edge, `bottom` the content box's), and how
+ * tall the region IS (`height`).
+ *
+ * THE TWO DIFFER ON PURPOSE, and the difference is the defect being measured.
+ * `.scene` centres its column, so a short body pushes the headline DOWN by half
+ * the slack — and a region drawn from the headline's bottom edge to the content
+ * bottom silently drops the other half, the band of nothing ABOVE the headline.
+ * The first version did exactly that and called a two-bar chart with 250px of
+ * empty canvas over its eyebrow 70% full. So the height is the content box less
+ * the chrome's own height, wherever the centring put it: the room the body was
+ * given, which is the same number `bodyBudget` hands the emitter.
+ */
+export interface FillRegion extends Box {
+    height: number;
+    /**
+     * How far down body ink is looked for. Absent: the frame's bottom edge, so a
+     * body that spills past its region is measured, not clipped. A `foot` slide
+     * sets it to the region's bottom, because what lies under that region is the
+     * slide's own headline, not spill.
+     */
+    scanBottom?: number;
+    /**
+     * The page's own background, `[r, g, b]`, or null when it is not an opaque
+     * colour. What "ink" is measured against — see `fillInk`.
+     */
+    bg: [number, number, number] | null;
+}
+/**
+ * Run IN THE PAGE: the scene's body region, in device px. Null when the scene
+ * is not in the document.
+ *
+ * The content box is `.scene`'s padding box, read off computed style rather
+ * than restated from `kit.ts`, so a deck built with a caption reserve (bottom
+ * padding grows) is measured against the box it actually laid out in.
+ */
+export declare function collectFillRegion(sid: string): FillRegion | null;
+/**
+ * The ink test for a fill measurement: the page's declared background when the
+ * region reported one, else the frame's modal colour, at `delta`.
+ *
+ * NOT the modal colour by default, and the reason is this gate's own success.
+ * `fidelity` takes the background to be the frame's most common colour, which
+ * holds while a slide is mostly air — "80–98% of every frame measured". A v2
+ * callout whose panels grew into their region covers MORE of the frame with
+ * panel wash than with background; the modal colour is then the panel's, the
+ * real background reads as ink, and a 0.95 hold measured 1.107 with a canvas
+ * share of 1.0 (HypePaper ko deck 894a874a, s18, 2026-10-07). The body
+ * stylesheet says what the background is, so that is what is asked.
+ */
+export declare function fillInk(region: FillRegion | null, modal: readonly [number, number, number], delta: number, plate?: FrameLike | null): InkTest;
+/**
+ * Run IN THE PAGE: hide (`true`) or restore (`false`) every scene, so one
+ * screenshot between the two is the deck's bare background — `InkTest.plate`.
+ * Opacity on the scene roots rather than visibility, because GSAP's `autoAlpha`
+ * writes `visibility:visible` on descendants and would show through.
+ */
+export declare function hideScenes(on: boolean): void;
+/** One scene's last hold, measured. */
+export interface FillRow {
+    sid: string;
+    t: number;
+    /** Main-axis (vertical) fill: body ink extent over region height. Above 1 spills. */
+    fill: number;
+    /** The same across the region's width. Reported, not graded. */
+    cross: number;
+    /** Union box of every ink pixel on the frame, chrome included, over the frame's area. */
+    canvas: number;
+    /** Region height in device px — 0 when the scene had no region to measure. */
+    region: number;
+    /** Share of the frame's cells holding ink, and of cells whose pixels vary. See `occupancy`. */
+    cells: number;
+    detail: number;
+}
+/**
+ * How much of the frame carries content, by area. Pure.
+ *
+ * `cells`: share of cells with at least `CELL_MIN_INK` of their pixels off the
+ * ground (the ink test `fidelity` uses — the bare-background plate when there is
+ * one). `detail`: share of cells that hold ink AND whose pixels span more than
+ * the ink threshold in luma — an edge, a glyph, a picture — so a flat slab of
+ * one colour counts as ink and not as detail.
+ */
+export declare function occupancy(frame: FrameLike, test: InkTest): {
+    cells: number;
+    detail: number;
+};
+/**
+ * Fill at one stop, from a decoded frame and the region the page reported.
+ * Pure. A scene with no region (not found) or no ink reads 0, which grades as
+ * hollow — "nothing painted below the headline" is exactly what that is.
+ */
+export declare function measureFill(frame: FrameLike, test: InkTest, region: FillRegion | null, stop: {
+    sid: string;
+    t: number;
+}): FillRow;
+/** The last declared stop of each scene: the final hold the fill is judged at. */
+export declare function finalStops<S extends {
+    sid: string;
+    t: number;
+}>(stops: readonly S[]): S[];
+/** Parse `fit.json`. Null when the deck has none — a classic build — or it does not parse. */
+export declare function readFitManifest(text: string | null): FitManifest | null;
+/** Findings for a v2 deck's measured fills. Nothing at all for a classic deck. */
+export declare function gradeFill(rows: readonly FillRow[], manifest: FitManifest | null): Finding[];
+export {};

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

@@ -44,6 +44,20 @@ export { scanTypeFloor, TYPE_FLOOR_PX } from "./typefloor.js";
 export interface VerifyOptions extends CheckOptions {
     /** Default true. `false` skips the frame measurement entirely. */
     fidelity?: boolean;
+    /**
+     * Default true. The motion gates in ./scenes.ts: all three, as errors, on the
+     * scenes `bespoke.json` says were generated; `seek_order` alone, as a
+     * warning, on every other scene of a v2 deck. A classic deck runs none.
+     * The bespoke pass turns this off on its probe decks, which it gates itself.
+     */
+    scenes?: boolean;
+    /**
+     * Generated scenes whose motion gates the bespoke pass already ran on these
+     * exact bytes at this same scene id (`bespoke.json`'s `gatedAt`): `build`
+     * seeks them like any other scene instead of repeating the full probe (~16s
+     * a scene). `decksmith verify <dir>` never passes it.
+     */
+    probed?: ReadonlySet<string>;
 }
 /**
  * Run every gate DeckSmith owns over a built project directory.

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

@@ -0,0 +1,33 @@
+/**
+ * Motion variety, measured off a built composition — the M4 exit metrics.
+ *
+ * Read from the emitted `index.html` rather than from the in-memory plan, so the
+ * number is about what ships: a plan that said "push" and an emitter that wrote
+ * a dissolve would read as a dissolve here. The three numbers are the ones the
+ * redesign plan set against v0.8.0's audit of 124 HypePaper scenes:
+ *
+ * | metric                         | v0.8.0 | v2 target |
+ * |--------------------------------|--------|-----------|
+ * | modal entrance (share)         | 92%    | ≤ 40%     |
+ * | seam kinds (deck of 10+ beats) | 1      | ≥ 3       |
+ * | top-2 ease share of tweens     | 85%    | ≤ 60%     |
+ *
+ * MODAL is deliberately generous to the old look: a scene "opens modal" when its
+ * headline enters as a bare opacity + y fade-up, whatever the ease. v2's `rise`
+ * verb therefore counts as modal, which is why `planMotion` caps it.
+ */
+export interface MotionStats {
+    scenes: number;
+    /** Scenes whose headline (`#sN-h`, or the title's `#sN-t`) enters as opacity + y only. */
+    modalScenes: number;
+    /** Scenes with at least one emphasis (glow, underline, or a sine-eased pulse) after the build. */
+    emphasisScenes: number;
+    /** Seam kind per handoff, in scene order. */
+    seams: string[];
+    /** Tween count per ease name; a tween naming none is `"default"`. */
+    eases: Record<string, number>;
+    tweens: number;
+}
+export declare function motionStats(composition: string): MotionStats;
+/** The share of tweens carried by the two most common eases. */
+export declare function topTwoEaseShare(stats: MotionStats): number;

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

@@ -0,0 +1,325 @@
+import type { DeckPage } from "../render/capture.js";
+import type { Timing } from "../render/timing.js";
+import type { Finding } from "../types.js";
+import { type Frame } from "./fidelity.js";
+/** A pixel counts as changed when its RGB moved by more than this, summed. Same as the spike's. */
+export declare const PIXEL_DELTA = 24;
+/**
+ * Fewer changed pixels than this between two seeks of one instant is rasterising,
+ * not state. MEASURED: a never-seeked page against a warm one differs by up to
+ * 644px on a scene that looks identical — antialiasing along the headline's
+ * glyphs, which the shell's own entrance had moved — and a KaTeX glyph by 529px.
+ * The leaks this gate exists for are an order of magnitude past it: 13,958 and
+ * 22,037px for the equation-walk bug, a dimmed label in the test at several
+ * thousand.
+ */
+export declare const SEEK_TOLERANCE_PX = 1500;
+/** Bump whenever a gate's verdict can change: cached rejections from another version are retried. */
+export declare const GATES_VERSION = "gates-5";
+/**
+ * A cue whose picture changes by less than this share of the frame held still:
+ * about 310 px at 1080p. A frame that does not move renders to the same bytes,
+ * so the floor only has to clear antialiasing; a 14px dot crossing a wire
+ * changes ~1,200 px and passes, which is right — that dot IS the explanation.
+ * Whether the motion is worth watching is the critique round's question and a
+ * person's, not a pixel count's.
+ */
+export declare const MIN_CHANGE = 0.00015;
+/** Cues shorter than this are exempt from `static_hold`: there is no room to show anything. */
+export declare const MIN_CUE_SECONDS = 1.2;
+/** Below this the text is not text the audience can read (AGENTS.md invariant 5). */
+export declare const TYPE_FLOOR_PX = 39.5;
+/** One narration cue on a scene's own clock. */
+export interface SceneCue {
+    t0: number;
+    t1: number;
+    text: string;
+}
+/** A scene to probe, with the cues spoken over it. */
+export interface SceneWindow {
+    sid: string;
+    beatId?: string;
+    /** Absolute composition seconds. */
+    start: number;
+    duration: number;
+    cues: SceneCue[];
+}
+export interface CueChange {
+    sid: string;
+    cue: number;
+    t0: number;
+    t1: number;
+    changed: number;
+    total: number;
+}
+export declare function gradeStillCues(rows: readonly CueChange[], min?: number): Finding[];
+/**
+ * The settled frame's drawing must span this share of the body box (the
+ * bounding box of everything drawn, over the box's area). Round 1's scenes sat
+ * at 55-70%: a diagram in the top-left two thirds with the right third or the
+ * bottom band empty, at a size the founder called small.
+ */
+export declare const STAGE_FILL = 0.8;
+/** The settled frame's largest label, px at 1080p: one thing on the stage is read first. */
+export declare const KEY_TYPE_PX = 64;
+/** A cue group may appear this long before its cue starts (the prompt's own sync window). */
+export declare const EARLY_SLACK = 0.5;
+/**
+ * At the settled frame, at most this share of a scene's parts may be ones it
+ * showed lit (>= `LIT`) earlier and has left dimmed (< `DIM`). Round 2 kept
+ * three scenes that ended on a frame of ghosts; the founder's rule is that the
+ * last cue ends with the whole scene lit. A part that was never lit — a halo, a
+ * translucent cone — is not counted: it is drawn that way, not dimmed.
+ */
+export declare const END_DIMMED = 0.1;
+export declare const LIT = 0.85;
+export declare const DIM = 0.6;
+/** A label as the repair pass sees it: its address, the unit a nudge moves, its box in body px. */
+export interface GeoLabel {
+    /** `tag:index` among the body's elements, in document order. */
+    a: string;
+    /** The unit a nudge would wrap (the text, or its plate group); null when it cannot move. */
+    u: string | null;
+    /** Document order (paint order). */
+    o: number;
+    /** x, y, w, h in body px. */
+    b: [number, number, number, number];
+    /** Screen px per unit of the unit's parent (a camera zoom makes it > 1). */
+    s: number;
+    fs: number;
+}
+/** What one frame of a bespoke scene looks like to the repair pass. */
+export interface Geo {
+    w: number;
+    h: number;
+    labels: GeoLabel[];
+    /** Filled shapes and pictures: address, owning label unit, paint order, box. */
+    boxes: Array<{
+        a: string;
+        u: string | null;
+        o: number;
+        b: [number, number, number, number];
+    }>;
+    /** Visible stroke samples, body px, with the label unit they belong to. */
+    points: Array<[number, number, string | null]>;
+    /** Each visible part's opacity and what dims it (`tag:index`, `#id` appended when it has one). */
+    parts: Array<{
+        a: string;
+        al: number;
+        dim: string[];
+    }>;
+}
+/** What the page measured at one frame of one scene. */
+export interface Layout {
+    sid: string;
+    key: string;
+    t: number;
+    crossings: string[];
+    occlusions: string[];
+    overlaps: string[];
+    small: string[];
+    off: string[];
+    /** Markers painted where their line is not (an arrowhead on an undrawn path). */
+    strays?: string[];
+    /** Bounding box of what is drawn in the body box, over the box's area. Bespoke scenes only. */
+    fill?: number;
+    /** Share of a 6x4 grid over the body box that something is drawn in. Reported, not graded. */
+    cells?: number;
+    /** The largest visible label in the body box, px. */
+    maxType?: number;
+    /** Share of the body box the settled drawing paints (`paintedShare`). Reported; the rubric probe reads it. */
+    mass?: number;
+    /** Share of the drawn labels and shapes in the body box at under 0.6 opacity. */
+    dimmed?: number;
+    /** Distinct `data-cue` numbers the scene's groups declare. */
+    groups?: number[];
+    /** The cue groups showing at this instant. */
+    revealed?: Array<{
+        id: string;
+        cue: number;
+    }>;
+    /** Scene seconds each cue starts at, so `early_reveal` can be graded off this row alone. */
+    cueStarts?: number[];
+    /** Where the camera is when it is not home (bespoke scenes). Graded at the end only. */
+    camOff?: string;
+    /** Repair geometry, when the probe asked for it. */
+    geo?: Geo;
+    /** End row: the share of parts lit earlier and left dimmed (`END_DIMMED`). */
+    litDimmed?: number;
+    /** End row: the elements dimming those parts, as `tag:index[#id]`. */
+    relight?: string[];
+    /** The shell's camera at this instant: scale, x, y, and the box's width and height. */
+    shot?: [number, number, number, number, number];
+    /** How many subjects the scene's illustration has (0 or absent: not an illustrated scene). */
+    subjects?: number;
+    /** Each visible label that names a subject: its gap to that subject (box px) and how much of it another subject covers. */
+    anchors?: Array<{
+        id: string;
+        k: number;
+        d: number;
+        o: number;
+    }>;
+    /** Labels with digits in them sitting on the illustration. */
+    onPicture?: number;
+}
+/**
+ * A label that names a subject sits within this many box px of that
+ * subject's box (0 = on it). A leader line may bridge the gap; a row of plates
+ * along the top of the box, round 3's habit, is 150-400px away.
+ */
+export declare const ANCHOR_PX = 96;
+/** A label may cover at most this share of itself with ANOTHER subject's box. */
+export declare const ANCHOR_OVERLAP = 0.25;
+/** This many numbers on the picture is a table or a chart painted over it (ja s12, round 3: nine). */
+export declare const NUMBERS_ON_PICTURE = 5;
+/** A shot at this scale or closer is a push-in; under `WIDE` it is the whole picture. */
+export declare const CLOSE = 1.5;
+export declare const WIDE = 1.1;
+/** The camera is sampled this often (scene seconds) for `shot_variety`: no screenshot, a seek and a read. */
+export declare const CAM_STEP = 0.5;
+/** The shell's camera at one instant of one scene (`probeScenes` samples it every `CAM_STEP`). */
+export interface CamSample {
+    sid: string;
+    t: number;
+    /** scale, x, y, and the box's width and height. */
+    shot: [number, number, number, number, number];
+    /** How many subjects the scene's illustration has. */
+    subjects: number;
+}
+/**
+ * The distinct shots a scene's camera HOLDS: a push-in counts when two
+ * consecutive samples (one `CAM_STEP` apart) are both at `CLOSE` or closer and
+ * aimed within `SAME_SHOT` of each other — a camera passing through on its way
+ * somewhere is not a shot. Push-ins aimed within `SAME_SHOT` of one already
+ * counted are the same shot.
+ */
+export declare function shotsOf(samples: readonly CamSample[]): {
+    wide: boolean;
+    close: Array<[number, number]>;
+};
+/**
+ * `shot_variety`: an illustrated scene is staged — it OPENS on the whole
+ * picture (every sample in the first second of its first cue is wide), and the
+ * camera HOLDS push-ins on at least `min(2, subjects)` different subjects
+ * (`shotsOf`); that it comes back is `camera_end`'s. `opens` is each scene's
+ * first cue start.
+ */
+export declare function gradeShots(samples: readonly CamSample[], opens?: ReadonlyMap<string, number>): Finding[];
+export declare function gradeLayout(rows: readonly Layout[]): Finding[];
+/**
+ * What the page did that a scene must not, pinned to the scenes it implicates.
+ * A bespoke script that throws is caught by the shell and logged with its scene
+ * id (`bespokeCall`), so it lands on that scene alone. A request, a navigation
+ * or a CSP refusal names no scene, so it fails every scene probed with it —
+ * none of them can be shown to be innocent from inside one page.
+ */
+/**
+ * Console errors the MACHINE raises, not the page: no scene can cause or fix
+ * them. MEASURED 2026-10-09: "The AudioContext encountered an error from the
+ * audio device or the WebAudio renderer" appeared on one probe deck in three
+ * and failed all five of its scenes — five critique calls, two fallbacks.
+ * Round 1 saw the same line once on bytes that had passed an hour earlier.
+ */
+export declare const ENVIRONMENT_ERRORS: RegExp[];
+export declare function gradeErrors(errors: readonly string[], sids: readonly string[]): Finding[];
+export interface SeekDiff {
+    sid: string;
+    key: string;
+    t: number;
+    /** Which comparison: `descending`, `scrambled`, `cold`. */
+    order: string;
+    px: number;
+}
+export declare function gradeSeekOrder(rows: readonly SeekDiff[], severity?: Finding["severity"], tolerance?: number): Finding[];
+/**
+ * The share of a box's pixels that differ between two frames — with and without
+ * a scene's drawing — i.e. how much of its stage the drawing actually paints.
+ * `box` is in CSS px of a 1920-wide page; frames may be any scale of it.
+ */
+export declare function paintedShare(shown: Frame, hidden: Frame, box: {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}, delta?: number): number;
+/**
+ * Changed pixels that are not on an EDGE of the change: a pixel counts only
+ * when it and its 8 neighbours all changed. What `seek_order` compares with.
+ *
+ * WHY. A picture's first paint can be rasterised a hair differently from a
+ * later one (MEASURED 2026-10-09: 12,698px on one illustrated scene's first
+ * frame, 2 runs in 3, identical DOM, the difference a 1-2px outline round every
+ * subject of the picture). That is the raster, not the scene's state, and it
+ * is all edges. A state leak — a term left swollen, a part left lit — changes
+ * AREAS, which survive this nearly whole (a 20x20 patch keeps 324 of 400).
+ */
+export declare function changedArea(a: Frame, b: Frame, delta?: number): number;
+export declare function changedPixels(a: Frame, b: Frame, delta?: number): number;
+/**
+ * Each scene's cues, scene-relative, from the manifest `build` wrote. Segment
+ * cues are relative to their own audio; the segment's `start` is where that
+ * audio sits on the composition clock (which is the output clock — nothing is
+ * frozen, see `framePlan`).
+ */
+export declare function sceneWindows(timing: Timing, sids?: ReadonlySet<string>): SceneWindow[];
+/**
+ * The instants a scene is photographed at: just after each cue starts, 0.6s in,
+ * just before it ends, and the settled end. `sparse` keeps the first cue's start,
+ * the cue ends and the end — what `seek_order` on a deck's other scenes needs,
+ * at about a third of the screenshots.
+ */
+export declare function probeTimes(w: SceneWindow, sparse?: boolean): Array<{
+    key: string;
+    t: number;
+    cue?: number;
+    edge?: "a" | "s" | "z";
+}>;
+export interface ProbedFrame {
+    sid: string;
+    key: string;
+    /** Scene-relative seconds. */
+    t: number;
+    png: Buffer;
+}
+export interface Probe {
+    findings: Finding[];
+    /** Ascending-pass frames, for a contact sheet. */
+    frames: ProbedFrame[];
+    cueChanges: CueChange[];
+    layout: Layout[];
+    seek: SeekDiff[];
+    /** The shell's camera every `CAM_STEP` through each illustrated scene (`shot_variety`). */
+    cams: CamSample[];
+}
+export interface ProbeOptions {
+    /** Which gates. Default all three. `seek` alone is what `verify` runs on plain v2 scenes. */
+    gates?: ReadonlyArray<"motion" | "layout" | "seek">;
+    /** `seek_order` severity; `verify` passes `warning` for scenes nobody generated. */
+    seekSeverity?: Finding["severity"];
+    /** Keep the PNGs (the critique round needs them). */
+    keepFrames?: boolean;
+    /** Also compare a never-seeked page per scene. Default true; a fresh browser each. */
+    cold?: boolean;
+    /** Photograph cue ends only (see `probeTimes`). */
+    sparse?: boolean;
+    /** Measure the repair geometry at every graded frame (bespoke scenes). */
+    geometry?: boolean;
+    /** Opens a fresh page; injected so the graders' wiring is testable. */
+    open: () => Promise<DeckPage>;
+    /** The array `open` hands to `openDeck({ watch })`; read once the probe ends. */
+    errors?: readonly string[];
+}
+/**
+ * Photograph `windows` and grade them. One warm page for the ordered passes, one
+ * cold page per scene for the first-seek comparison.
+ */
+export declare function probeScenes(windows: readonly SceneWindow[], opts: ProbeOptions): Promise<Probe>;
+/**
+ * The end row's `litDimmed` and `relight`, from every graded frame of one
+ * scene: a part lit (>= `LIT`) at some earlier frame and dimmed (< `DIM`, but
+ * visible) at the end, and the elements above it that dim it. A part that was
+ * never lit is drawn translucent on purpose and is left alone.
+ */
+export declare function endState(rows: Layout[]): void;
+/** `timing.json`, or nothing. */
+export declare function readTimingFile(dir: string): Promise<Timing | undefined>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jokerized/decksmith",
-  "version": "0.8.0",
+  "version": "0.9.1",
   "description": "Turn a source document into an animated explanation deck.",
   "type": "module",
   "license": "MIT",
@@ -58,9 +58,13 @@
     "demo": "node demo/build.mjs && node dist/cli.js build demo/storyboard.json --source demo/source.json -o demo/deck && python3 -m http.server 8080 --directory demo/deck --bind 127.0.0.1"
   },
   "dependencies": {
+    "@fontsource-variable/ibm-plex-sans": "5.3.0",
     "@fontsource-variable/inter": "5.3.0",
+    "@fontsource-variable/source-serif-4": "5.3.0",
+    "@fontsource-variable/space-grotesk": "5.3.0",
     "@modelcontextprotocol/sdk": "^1.30.0",
     "@puppeteer/browsers": "^3.0.6",
+    "acorn": "^8.19.0",
     "commander": "^14.0.1",
     "fflate": "^0.8.3",
     "gsap": "^3.14.2",