@jokerized/decksmith 0.9.0 → 0.9.2

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.9.0",
+  "version": "0.9.2",
   "description": "Turn a source document into an animated explanation deck.",
   "type": "module",
   "license": "MIT",
@@ -64,6 +64,7 @@
     "@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",