@jokerized/decksmith 0.9.3 → 0.9.5

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

@@ -139,6 +139,11 @@ export declare function judge(m: {
         db: number;
     };
     motion: Motion;
+    /**
+     * The worker count of each render, so the passing note says what was
+     * compared: `--workers 1` pins both, and must not be reported as two counts.
+     */
+    workers?: readonly [number | "auto" | undefined, number | "auto" | undefined];
 }): DriftReport;
 /**
  * `frame_000001.png` → `frame_%06d.png`, for ffmpeg's image2 demuxer.

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

@@ -139,6 +139,7 @@
  * demo moves 5.81s to 6.32s, and that is a cold cache. A gate too slow to run is
  * a gate nobody runs; this one costs nothing, so it runs by default.
  */
+import type { BrokenFrame } from "../emit/animate-runtime.js";
 import type { Finding } from "../types.js";
 import { type FillRow } from "./fill.js";
 /**
@@ -257,7 +258,7 @@ export declare function decodePng(png: Uint8Array): Promise<Frame>;
  * bounding box, and it does not ask the DOM whether an element is visible; both
  * of those have been wrong in this project inside the last week.
  */
-export declare function inkBelow(frame: Frame, bandTopPx: number): number;
+export declare function inkBelow(frame: Frame, bandTopPx: number, plate?: Frame | null): number;
 /**
  * Where a scene's BODY is, in device px: the part of the frame that is not its
  * chrome. Classic chrome is a block across the top, so the body is everything
@@ -344,6 +345,19 @@ export declare function collectUnfit(attr: string): Unfit[];
  * shorten.
  */
 export declare function gradeUnfit(rows: readonly Unfit[]): Finding[];
+/**
+ * Run IN THE PAGE: every mounted animate piece drawn at each of its own frames
+ * (`sweep`, src/emit/animate-runtime.ts). Empty on a deck with no piece, whose
+ * page never loads the runtime.
+ */
+export declare function collectBrokenPieces(): BrokenFrame[];
+/**
+ * An error per piece that throws at ANY of its frames. A drawing error is a
+ * page error only where `hyperframes check` happens to seek, and on a long deck
+ * it samples coarsely enough to miss a throw confined to a short window — which
+ * `render` then draws half-painted and exits 0 over.
+ */
+export declare function gradePieces(rows: readonly BrokenFrame[]): Finding[];
 /**
  * Seek every declared stop and count the ink below its caption.
  *

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

@@ -427,3 +427,20 @@ export declare function scanNarrationLead(beats: readonly Beat[], timing: {
 }): Finding[];
 /** Flag render-time nondeterminism in one composition file (invariant 7). */
 export declare function scanDeterminism(html: string, file: string): Finding[];
+/**
+ * Every script under the deck's `assets/` — which is where an animate piece's
+ * assembled script lives (src/build/piece.ts), and the only file holding code
+ * an AUTHOR wrote. It runs at render time like the composition does, so the
+ * determinism scan reads it; the type and budget gates, which read markup, do
+ * not.
+ */
+export declare function readAssetScripts(dir: string): Promise<Array<[string, string]>>;
+/**
+ * ROUND 5, the deck's variety: the camera grammars its illustrated scenes are
+ * staged in (`data-ds-grammar`, stamped by the shell) and the builds of its
+ * data scenes (`data-ds-build`), in scene order. Two consecutive illustrated
+ * scenes in one grammar, or two data scenes that build alike, is the "same
+ * animation every card" one level up; fewer distinct grammars than
+ * `diversityWanted` is reported.
+ */
+export declare function scanStagingVariety(compositions: readonly string[]): Finding[];

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

@@ -1,3 +1,44 @@
+/**
+ * Three gates on a scene's MOTION, which no other gate here looks at, run in
+ * the renderer's own browser at the narration's cue boundaries.
+ *
+ *  1. `static_hold` — the picture must change during every narration cue. A
+ *     v2 archetype finishes building in about five seconds and then holds still
+ *     for fifteen to twenty seconds of speech (spike, 2026-10-07: 0 px changed
+ *     between cue ends on two of four beats). A bespoke scene exists to keep
+ *     explaining while the voice does, so for one this is an error.
+ *  2. `graphic_crosses_text` (with `text_overlap`, `bespoke_type_floor`,
+ *     `off_canvas`) — a drawn stroke must not run through a label, and a filled
+ *     shape painted later must not cover one. The spike's worst defect was a
+ *     giant stray arc across a whole diagram that every gate passed, including a
+ *     text-on-text overlap check; strokes were simply not text. Strokes are
+ *     sampled along their geometry and their dash pattern, so a line drawn by
+ *     DrawSVG is checked only where it is visible at that instant.
+ *     Round 2 adds what round 1's frames showed a person and no gate: the
+ *     settled drawing must span `STAGE_FILL` of its box (`stage_fill`) and carry
+ *     one label of `KEY_TYPE_PX` or more (`type_hierarchy`), none over
+ *     `MAX_TYPE_PX` (`type_ceiling`, 2026-10-10); an arrowhead must
+ *     not show where its line is not drawn (`stray_marker`); and a group the
+ *     scene tags `data-cue="N"` must not show before cue N starts
+ *     (`early_reveal`, with `cue_groups` failing a scene that tags nothing).
+ *     Round 6, after the founder's "animated UI elements are old-fashioned, and
+ *     the fonts are too large": no word in a bespoke scene renders above the
+ *     deck's headline size (`type_scale`, TYPE_SCALE in src/emit/type.ts —
+ *     round 2's 64px floor for a key label is gone), and no label, plate,
+ *     chip, card or bar is animated into place (`ui_motion`, read off the
+ *     scene's own GSAP timeline).
+ *  3. `seek_order` — the frame at time t must not depend on which times were
+ *     seeked before it. Capture shards a render across workers and the deck
+ *     player jumps around, so a frame that depends on history is a frame that
+ *     differs between two renders of one input. Ascending, descending (after
+ *     jumping past the scene), a fixed scramble, and a cold page are compared.
+ *     This is what found v2's equation-walk bug: a `fromTo` authored with
+ *     `immediateRender` set its from-state at BUILD time, so a cold seek showed
+ *     a swollen term that a warm seek did not.
+ *
+ * The graders are pure and take what the browser measured, so each is tested
+ * without one; `probeScenes` is the one place a browser is opened.
+ */
 import type { DeckPage } from "../render/capture.js";
 import type { Timing } from "../render/timing.js";
 import type { Finding } from "../types.js";
@@ -15,7 +56,7 @@ export declare const PIXEL_DELTA = 24;
  */
 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";
+export declare const GATES_VERSION = "gates-7";
 /**
  * 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,
@@ -60,10 +101,42 @@ export declare function gradeStillCues(rows: readonly CueChange[], min?: number)
  * 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;
+/**
+ * The settled frame's largest label, px at 1080p: one label reaches the body
+ * size (`TYPE_SCALE`), so something is read first…
+ */
+export declare const KEY_TYPE_PX: 44;
+/**
+ * …and nothing passes the headline's size. The founder's verdict on the 88-120px
+ * focal numbers this gate used to ASK for was "the fonts are too large"
+ * (2026-10-10): the picture is the focus, the subtitles carry the words.
+ */
+export declare const MAX_TYPE_PX: 56;
+/**
+ * The largest a bespoke scene's own words may RENDER, px at 1080p, at any graded
+ * frame, camera zoom included (`type_scale`, round 6): `type_ceiling` reads the
+ * size a word declares, this one what the audience sees.
+ */
+export declare const TYPE_MAX_PX: number;
 /** A cue group may appear this long before its cue starts (the prompt's own sync window). */
 export declare const EARLY_SLACK = 0.5;
+/**
+ * The longest a seam may leave the stage empty (round 6): r1's final review
+ * found 12 of 15 seams showing nothing but the headline for ~0.6s — the
+ * outgoing scene gone, the incoming one's first group not yet in.
+ */
+export declare const SEAM_BLANK_MAX = 0.15;
+/**
+ * The height share of its box a bespoke scene's drawing spans while a later
+ * cue holds (`hollow_hold`): the fill module's EMPTY band. r1's final s8 held
+ * three calipers across the top 58% for seconds; its settled end frame filled.
+ */
+export declare const HOLD_SPAN_MIN = 0.7;
+/**
+ * Below this share of the frame painted (headlines aside), the stage is empty:
+ * about one 64px mark. r1's blank seams read exactly 0.
+ */
+export declare const SEAM_PAINT_MIN = 0.002;
 /**
  * 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
@@ -92,6 +165,8 @@ export interface GeoLabel {
 export interface Geo {
     w: number;
     h: number;
+    /** The shell camera's scale at this frame (1 when it has none). */
+    cs?: number;
     labels: GeoLabel[];
     /** Filled shapes and pictures: address, owning label unit, paint order, box. */
     boxes: Array<{
@@ -102,7 +177,7 @@ export interface Geo {
     }>;
     /** 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). */
+    /** Each visible part's opacity and what dims it (`tag:index`, `#id` appended when it has one, then `@` its own opacity). */
     parts: Array<{
         a: string;
         al: number;
@@ -125,8 +200,15 @@ export interface Layout {
     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. */
+    /** The largest visible label in the body box, px as drawn (a camera push-in scales it). */
     maxType?: number;
+    /**
+     * The largest font-size a visible label in the body box DECLARES, KaTeX
+     * excluded (it sets itself at 1.21em of its box): what `type_ceiling` holds
+     * to `MAX_TYPE_PX`. Not `maxType`, which a camera push-in or a viewBox zoom
+     * grows past the size the scene asked for.
+     */
+    maxDeclared?: 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. */
@@ -161,6 +243,14 @@ export interface Layout {
     }>;
     /** Labels with digits in them sitting on the illustration. */
     onPicture?: number;
+    /** Visible text in the body box under `TEXT_CONTRAST` against its backdrop, as `id [box] ratio`. */
+    faint?: string[];
+    /** End row: the scene's own tweens that animate a label, plate, chip, card or bar into place (`ui_motion`). */
+    uiMotion?: string[];
+    /** Height share of the body box the drawing spans (bespoke scenes), for \`hollow_hold\`. */
+    span?: number;
+    /** Pairs of alike filled dots drawn into each other (\`marks_overlap\`). */
+    marksOverlap?: string[];
 }
 /**
  * A label that names a subject sits within this many box px of that
@@ -185,6 +275,12 @@ export interface CamSample {
     shot: [number, number, number, number, number];
     /** How many subjects the scene's illustration has. */
     subjects: number;
+    /** The camera grammar the shell stamped on the scene (src/bespoke/grammar.ts). */
+    grammar?: string;
+    /** The backdrop's scale, x, y (round 5's second layer), when it has one. */
+    plate?: [number, number, number];
+    /** How much of the box's width a wiped-on picture shows, 0..1, when it is wiped. */
+    wipe?: number;
 }
 /**
  * The distinct shots a scene's camera HOLDS: a push-in counts when two
@@ -197,6 +293,12 @@ export declare function shotsOf(samples: readonly CamSample[]): {
     wide: boolean;
     close: Array<[number, number]>;
 };
+/**
+ * Whether the camera did what its grammar says (src/bespoke/grammar.ts), read
+ * off the samples alone — so a shell that compiled every grammar to round 4's
+ * tour would fail here, not pass on the stamp.
+ */
+export declare function grammarBroken(grammar: string, list: readonly CamSample[], t0?: number): string[];
 /**
  * `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
@@ -205,6 +307,67 @@ export declare function shotsOf(samples: readonly CamSample[]): {
  * first cue start.
  */
 export declare function gradeShots(samples: readonly CamSample[], opens?: ReadonlyMap<string, number>): Finding[];
+/**
+ * `text_clipped`: a word the frame cuts in two while it is HELD there. A
+ * camera push or a clipped viewBox crops what lies at its edge, and a shape cut
+ * off reads as framing — a label cut mid-word does not (r1, 2026-10-10: '…인된
+ * 결과' held for 2.5s at s12's left edge, '구조 맵' cropped by s7's push-ins).
+ * Sampled every `CAM_STEP`; a text counts when it is partly inside the frame
+ * (more than `CUT_MIN` of it) and has lost more than a sliver across (under
+ * `CUT_MAX` of its width) or more than its leading down (under `CUT_DEEP` of
+ * its height), at `CUT_HOLD` consecutive samples — so a label sliding out
+ * during a 1.1s move is not one.
+ */
+export declare const CUT_MIN = 0.05;
+/** Under this share of its width inside the frame, a word has lost a glyph. */
+export declare const CUT_MAX = 0.96;
+/** Under this share of its line box's height, a word has lost ink (the rest is leading). */
+export declare const CUT_DEEP = 0.75;
+export declare const CUT_HOLD = 3;
+/** One dense sample of one scene: the texts the frame cuts, as `id (share%)`. */
+export interface CutSample {
+    sid: string;
+    t: number;
+    cut: Array<{
+        id: string;
+        share: number;
+    }>;
+}
+export declare function gradeCuts(samples: readonly CutSample[]): Finding[];
+/**
+ * `morph_glitch`: a path tween that throws its shape across the stage on the
+ * way. An `attr: { d }` tween pairs the two paths' numbers in order, so between
+ * paths of different commands (`V455 L1090 320` against `L1090 405 L1240 495`)
+ * an x is tweened into a y and back (r1 s4 at 61.75s: a green wedge over half
+ * the frame, between two shapes on its right); a morphSVG between mismatched
+ * shapes can do the same. Between matched paths every in-between point lies
+ * between its two ends, so the shape stays inside their union. A tween counts
+ * when, at any in-between sample of one iteration, the shape is visible and
+ * reaches more than `MORPH_REACH` of the larger side of its two ends' union
+ * (and 60px at least) past that union.
+ */
+export declare const MORPH_REACH = 0.35;
+/** One morph tween's shape box at shares of its duration: [x, y, w, h] in page px, and its opacity. */
+export interface MorphSample {
+    sid: string;
+    id: string;
+    start: number;
+    dur: number;
+    boxes: Array<{
+        f: number;
+        b: [number, number, number, number];
+        o: number;
+    }>;
+}
+export declare function gradeMorphs(samples: readonly MorphSample[]): Finding[];
+/**
+ * `dim_text`: a word left under 3:1 contrast with what is behind it, at a held
+ * frame (a cue's end, the settled end). Every bespoke label is 40px or more —
+ * large text — so 3:1 is the WCAG floor; focus dimming had taken key numbers to
+ * 1.6:1 (r1 s13 "75.1 %") and named subjects to 1.5:1 (s8) while the voice was
+ * on them.
+ */
+export declare const TEXT_CONTRAST = 3;
 export declare function gradeLayout(rows: readonly Layout[]): Finding[];
 /**
  * What the page did that a scene must not, pinned to the scenes it implicates.
@@ -281,6 +444,17 @@ export interface ProbedFrame {
     t: number;
     png: Buffer;
 }
+/** How long the stage stood empty across the seam into one scene (`seam_blank`). */
+export interface SeamSample {
+    sid: string;
+    /** The longest run, seconds, with under `SEAM_PAINT_MIN` of the frame painted. */
+    blank: number;
+    /** Scene seconds (negative: before the seam) where that run starts. */
+    at: number;
+    /** Whether the incoming scene is a generated (bespoke) one. */
+    bespoke: boolean;
+}
+export declare function gradeSeams(rows: readonly SeamSample[]): Finding[];
 export interface Probe {
     findings: Finding[];
     /** Ascending-pass frames, for a contact sheet. */
@@ -290,6 +464,12 @@ export interface Probe {
     seek: SeekDiff[];
     /** The shell's camera every `CAM_STEP` through each illustrated scene (`shot_variety`). */
     cams: CamSample[];
+    /** The words the frame cuts, every `CAM_STEP` through each bespoke scene (`text_clipped`). */
+    cuts: CutSample[];
+    /** Each morphSVG tween's shape through its run (`morph_glitch`). */
+    morphs: MorphSample[];
+    /** The stage across each seam into a probed scene (`seam_blank`). */
+    seams: SeamSample[];
 }
 export interface ProbeOptions {
     /** Which gates. Default all three. `seek` alone is what `verify` runs on plain v2 scenes. */

package/package.json

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

package/dist/types/bespoke/callouts.d.ts

@@ -1,76 +0,0 @@
-/**
- * The labels of an illustrated scene, drawn by the shell ON their subjects.
- *
- * WHY THE SHELL AND NOT THE SCENE. Round 3's labels were plates in a row along
- * the top of the box. Round 4's first run (2026-10-09, en deck) asked the scene
- * to put each label on its subject itself: the labels went on their subjects
- * (3-4 of 3-4 within 96px in every draft), and four of five scenes then failed
- * on their own plates and leader lines running through their own text — the
- * model guesses a label's width, and at 56px a guess is wrong by more than the
- * plate's margin. The shell knows the width (the same estimator the archetypes
- * lay out with), so the scene says WHAT each subject is called (`labels`) and
- * the shell says WHERE: a plate in a zone just above the subject (or across
- * its top when there is no room above), a leader line to a dot on it, entering
- * when the camera first arrives on that subject. One grammar for every deck.
- *
- * Zones are fixed from the subjects alone, before the scene is written, so the
- * prompt can tell the scene where they are and to keep its own drawing out.
- */
-import type { Theme } from "../emit/kit.js";
-import type { Box, CamMove } from "./shots.js";
-/** One subject's label, as the scene names it. */
-export interface Label {
-    subject: number;
-    text: string;
-}
-/** Where a subject's label goes: its zone (box px), and the dot its leader ends on. */
-export interface Zone extends Box {
-    subject: number;
-    /** "above" the subject, or across its "top" inside it. */
-    side: "above" | "top";
-    dot: {
-        x: number;
-        y: number;
-    };
-}
-/** The label's size, and the floor it may shrink to to fit its zone. */
-export declare const LABEL_PX = 56;
-export declare const LABEL_MIN_PX = 44;
-/**
- * Each subject's label zone: centred over the subject, as wide as half the
- * distance to each neighbour allows (so neighbours' zones never meet), above
- * the subject when there is room, else across its top.
- */
-export declare function calloutZones(subjects: readonly Box[], W: number): Zone[];
-/** How a label is set: its size and its line(s). */
-export interface Fit {
-    fs: number;
-    lines: string[];
-}
-/**
- * How a label fits its zone: one line from `LABEL_PX` down to `LABEL_MIN_PX`,
- * else two lines (the plate grows away from the subject, as far as the box
- * allows), else not at all.
- */
-export declare function fitLabel(text: string, zone: Zone, theme: Theme, boxH?: number): Fit | undefined;
-/**
- * Roughly how many characters fit a zone at the floor size, for the prompt
- * ("at most N characters"): Latin lowercase if the deck is Latin, else the
- * deck's script, at `LABEL_MIN_PX`. The fit itself is `fitLabel`'s.
- */
-export declare function longestFit(zone: Zone, theme: Theme): number;
-/** What the camera frames for a subject: the subject and its label zone together. */
-export declare function withZone(s: Box, z: Zone | undefined): Box;
-/** When each subject's label enters: as the camera arrives on it, else at the reveal. */
-export declare function entrances(moves: readonly CamMove[], subjects: number): Map<number, number>;
-/**
- * The labels as markup and GSAP for the shell to put in the scene: a layer of
- * `<g data-subject="K">` groups (so `label_anchor` measures them like any
- * label), each hidden until its entrance, then the plate rises in, the leader
- * draws to the dot. Labels that do not fit their zone are left out (the
- * static check refuses a scene that has one, so this is belt and braces).
- */
-export declare function calloutLayer(sid: string, labels: readonly Label[], zones: readonly Zone[], moves: readonly CamMove[], theme: Theme, W: number, H: number): {
-    markup: string;
-    script: string;
-};