@jokerized/decksmith 0.9.4 → 0.9.6

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

@@ -153,6 +153,10 @@ import { type FillRow } from "./fill.js";
  */
 export declare const INK_FLOOR = 0.0015;
 /** One declared stop: which scene, and where on the deck timeline. */
+/** The scene's final state is measured this long before it ends: settled, before the handoff. */
+export declare const FINAL_LEAD = 1;
+/** A final state is measured only this long after the last hold; nearer, the hold is it. */
+export declare const FINAL_GAP = 2;
 export interface Stop {
     /** Composition id — `s1`, `s2`. */
     sid: string;
@@ -216,8 +220,9 @@ export declare function readReserve(timingText: string | null): number;
 export interface FidelityReport {
     stops: Measured[];
     /**
-     * Main-axis fill at each scene's last hold — measured on every deck, graded
-     * only on a v2 one (`fit.json` present). See `./fill.ts`.
+     * Fill at each hold: every hold on a v2 deck (`fit.json` present), each with
+     * its content `area`, which is graded; each scene's last hold on a classic
+     * deck, measured and never graded. See `./fill.ts`.
      */
     fills: FillRow[];
     /**

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

@@ -42,22 +42,49 @@
  * is ink but not detail. Both are placement-independent: they do not move when
  * a look redefines where its body region is.
  *
+ * AND THE GRADED MEASURE, `area`: the bounding box of the body's REAL CONTENT
+ * over the region's area, at EVERY hold. Real content is what is left once the
+ * page's containers are made transparent (`stripContainers`): a card's wash and
+ * border, a figure's plate, a plot's panel. A row of three thin cards in a 170px
+ * band read as a full region on a wash that spanned it, and a column of bullets
+ * in a full-height panel read full by the panel (founder, 2026-10-12: "content
+ * sits small in the top-left with two thirds of the frame empty"). An extent is
+ * one axis; content in the top-left third is a third of BOTH axes, a ninth of
+ * the area, and only an area can say so.
+ *
  * 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:
+ * but never gets a finding: v0.8.0's verdicts do not move.
  *
- *   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
+ *   hollow_at_hold        ERROR: at a hold, the content's box covers under 70%
+ *                         of the region's area. Every scene with a body, every
+ *                         hold — the title, kinetic and hero-number slides
+ *                         have no body under a title band (their words or
+ *                         number are the slide) and are not graded
+ *   fill_model_disagrees  WARNING: |predicted − measured| main-axis fill over
+ *                         0.20 at the last hold — the build-time arithmetic and
+ *                         the browser disagree, which is a bug in the model
  */
-import { type FitManifest } from "../emit/fit.js";
+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;
+/** A hold's content box must cover at least this share of its region's area. */
+export declare const CONTENT_AREA_MIN = 0.7;
+/**
+ * How far (max channel, times alpha) a fill must stand from the page's ground
+ * to be a tile rather than a wash. The deck themes' panel colours sit 10–25
+ * from their ground; a tone at a quarter strength sits past 40.
+ */
+export declare const TILE_DELTA = 36;
+/**
+ * Archetypes with no body under a title band: their words are the slide (a
+ * title, a kinetic statement, a hero number set at 200px or more), so there is
+ * no region to fill.
+ */
+export declare const NO_BODY: Set<string>;
 /** Device px, in the frame's own coordinates. */
 export interface Box {
     left: number;
@@ -155,7 +182,24 @@ export declare function fillInk(region: FillRegion | null, modal: readonly [numb
  * writes `visibility:visible` on descendants and would show through.
  */
 export declare function hideScenes(on: boolean): void;
-/** One scene's last hold, measured. */
+/**
+ * Run IN THE PAGE: make every CONTAINER in a scene transparent (`on`), or put
+ * it back. What is left is the content `area` measures.
+ *
+ * A container is an element whose box encloses the centre of a piece of
+ * content (a run of text, a picture, an SVG mark): an HTML one loses its
+ * background, border and shadow (what it holds stays), and an SVG `rect` is
+ * hidden. That is a card's wash, a figure's plate, a plot's panel, and a
+ * full-frame backdrop behind a lone number. What encloses nothing is content: a
+ * filled shape (a dot, a tile, a bar), a picture, a glyph — except an HTML leaf
+ * with a border and no fill, an empty box, which draws nothing. A container
+ * whose fill stands out from the ground (`TILE_DELTA`: a coloured cell, a chip)
+ * is a tile and stays. Classes
+ * and one style element, removed on `false`, so GSAP's inline styles are never
+ * touched.
+ */
+export declare function stripContainers(sid: string, on: boolean): void;
+/** One scene's hold, measured. */
 export interface FillRow {
     sid: string;
     t: number;
@@ -170,6 +214,11 @@ export interface FillRow {
     /** Share of the frame's cells holding ink, and of cells whose pixels vary. See `occupancy`. */
     cells: number;
     detail: number;
+    /**
+     * The content box's share of the region's AREA, measured on the frame with its
+     * containers stripped (`stripContainers`). Absent when that frame was not taken.
+     */
+    area?: number;
 }
 /**
  * How much of the frame carries content, by area. Pure.
@@ -193,6 +242,12 @@ export declare function measureFill(frame: FrameLike, test: InkTest, region: Fil
     sid: string;
     t: number;
 }): FillRow;
+/**
+ * The content box's share of the region's area: the extent of ink in the region
+ * (down to `scanBottom` or the frame's edge) on a frame whose containers were
+ * stripped, each side capped at the region's. Pure. 0 with no region or no ink.
+ */
+export declare function contentArea(frame: FrameLike, test: InkTest, region: FillRegion | null): number;
 /** The last declared stop of each scene: the final hold the fill is judged at. */
 export declare function finalStops<S extends {
     sid: string;
@@ -200,6 +255,12 @@ export declare function finalStops<S extends {
 }>(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. */
+/**
+ * Findings for a v2 deck's measured fills. Nothing at all for a classic deck.
+ *
+ * `rows` is every hold: `hollow_at_hold` is judged at each one that carries an
+ * `area`, one finding per scene naming its emptiest hold, and the model check at
+ * each scene's last hold (`finalStops`).
+ */
 export declare function gradeFill(rows: readonly FillRow[], manifest: FitManifest | null): Finding[];
 export {};

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

@@ -131,3 +131,49 @@ export interface Overprinted {
  * three example pairs because a repair needs to know WHICH labels.
  */
 export declare function gradeOverprint(rows: readonly Overprinted[]): Finding[];
+/**
+ * The marks a word may not lie on, in device px: points (an SVG circle, by its
+ * centre and radius) and lines (an SVG line, polyline or open path, sampled
+ * every ~6px along its length). Visible ones only: a mark under a clip — a
+ * wipe that has not reached it, the camera's frame — is cut to the clip's box,
+ * so a series not yet drawn is not a series a label lies on.
+ */
+export interface Marks {
+    points: Array<{
+        x: number;
+        y: number;
+        r: number;
+    }>;
+    lines: Array<{
+        x: number;
+        y: number;
+    }>;
+}
+/**
+ * Serialised into the page: every visible point and line inside this scene's
+ * SVGs. Closed shapes (rects, polygons) are not marks: a word on a panel or a
+ * chip is meant to be there.
+ */
+export declare function collectSvgMarks(sid: string): Marks;
+/** A word lying on a mark. */
+export interface WordOnMark {
+    word: string;
+    on: "point" | "line";
+    /** Where the mark meets the word, device px, rounded: the place to look. */
+    at: [number, number];
+}
+/**
+ * Every run of text that lies on a point or a line: a line sample inside the
+ * run's box shrunk by `MIN_OVERLAP / 2` a side (a fifth of its height top and
+ * bottom, the leading), or a point whose disc reaches that far into it. A word INSIDE its own dot (a key's number) is not on it:
+ * the dot holds the whole run. Pure, for the same reason `overprints` is.
+ */
+export declare function wordsOnMarks(runs: readonly TextRun[], marks: Marks): WordOnMark[];
+/** One scene's words on marks at one stop. */
+export interface MarkedStop {
+    sid: string;
+    t: number;
+    hits: WordOnMark[];
+}
+/** Findings for the scenes that print a word on a point or a line: one per scene, its worst stop. */
+export declare function gradeWordsOnMarks(rows: readonly MarkedStop[]): Finding[];

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

@@ -56,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-7";
+export declare const GATES_VERSION = "gates-8";
 /**
  * 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,
@@ -84,6 +84,8 @@ export interface SceneWindow {
     start: number;
     duration: number;
     cues: SceneCue[];
+    /** Scene-relative holds, from timing.json: where the scene's reveals settle. */
+    holds?: number[];
 }
 export interface CueChange {
     sid: string;
@@ -93,6 +95,63 @@ export interface CueChange {
     changed: number;
     total: number;
 }
+/**
+ * The longest a scene may show one unchanged picture, in seconds. The brief's
+ * rule is "no 6-9s stretches where nothing moves"; r1 of the literal verbs run
+ * had runs of up to 18.9s, all of them archetype scenes that passed every gate,
+ * because `static_hold` only ever probed generated scenes.
+ */
+export declare const DEAD_SECONDS = 6;
+export interface DeadSpan {
+    sid: string;
+    t0: number;
+    t1: number;
+    changed: number;
+    total: number;
+}
+/**
+ * The stretches of a scene that no reveal can be moving in: hold to the next
+ * reveal (which runs in the second before its hold), and the last hold to the
+ * settled end. Only those at least `DEAD_SECONDS` long, which are the only ones
+ * worth photographing.
+ *
+ * And each run of TWO such stretches, across the hold between them: a hold
+ * with nothing to reveal joins its neighbours into one still run that neither
+ * half shows. r2's OneVL deck had a lengths scene still for 12s over its last
+ * two holds, each window under 6s, and the gate passed it. The three frames
+ * of a two-stretch window still see a reveal at the hold between.
+ */
+export declare function deadCandidates(w: SceneWindow, min?: number): Array<[number, number]>;
+/**
+ * A step of a long stretch moved when this share of its pixels changed across
+ * `DEAD_STEP` seconds, compared at 480×270 (`pooled`). Not `MIN_CHANGE`'s "anything at all": a literal scene's
+ * lean — a 1.5% scale breathing over a still slide — changes edge pixels on
+ * every frame and passed r2's runs of 6–10s that a viewer saw as stills.
+ */
+export declare const DEAD_MIN_CHANGE = 0.01;
+/** The side `pooled` averages a frame down by: 1920×1080 to 480×270. */
+export declare const DEAD_POOL = 4;
+/** A frame averaged down `k`×`k` per pixel: what a viewer sees move, not antialiasing. */
+export declare function pooled(f: Frame, k?: number): Frame;
+/** Seconds between the two frames a step of motion is judged across. */
+export declare const DEAD_STEP = 2;
+/**
+ * The longest still run across frames at `times` (a second apart), given the
+ * changed pixels between each frame and the one `DEAD_STEP` seconds before it
+ * (`changed[k]` for frame k against frame k − DEAD_STEP; undefined for the
+ * first). A second of the stretch moved when a two-second step that spans it
+ * changed `min` of the pixels or more; the run is the longest stretch of
+ * seconds none of which moved. A slow lean — a slide breathing 1.5% across 8s —
+ * accumulates past 1% of the stretch's first frame and so read as motion to a
+ * comparison against the run's start; r3 had a line chart under 1% between every
+ * pair of frames two seconds apart for 14s, and the gate passed it.
+ */
+export declare function stillRun(times: readonly number[], changed: ReadonlyArray<number | undefined>, total: number, min?: number): {
+    a: number;
+    b: number;
+    peak: number;
+};
+export declare function gradeDeadSpans(rows: readonly DeadSpan[], min?: number): Finding[];
 export declare function gradeStillCues(rows: readonly CueChange[], min?: number): Finding[];
 /**
  * The settled frame's drawing must span this share of the body box (the
@@ -473,7 +532,7 @@ export interface Probe {
 }
 export interface ProbeOptions {
     /** Which gates. Default all three. `seek` alone is what `verify` runs on plain v2 scenes. */
-    gates?: ReadonlyArray<"motion" | "layout" | "seek">;
+    gates?: ReadonlyArray<"motion" | "layout" | "seek" | "dead" | "clip">;
     /** `seek_order` severity; `verify` passes `warning` for scenes nobody generated. */
     seekSeverity?: Finding["severity"];
     /** Keep the PNGs (the critique round needs them). */

package/package.json

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