@jokerized/decksmith 0.1.0

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

@@ -0,0 +1,41 @@
+import { type Beat, type Finding, type Format, type Storyboard } from "../types.js";
+/** What the composition root records about itself. */
+export interface Canvas {
+    width: number;
+    height: number;
+    /** `data-duration` on the root: the whole deck, narration included. */
+    seconds: number;
+}
+/**
+ * Read the root element's own attributes.
+ *
+ * Only the root carries `data-width`/`data-height` (`emitComposition`); scenes
+ * carry an id, a start and a duration and nothing else, which is exactly the
+ * attribute set EXPERIMENT-003 pinned. So "the div with all three" is an
+ * unambiguous handle, and a sub-composition file — should one ever exist — reads
+ * as `undefined` rather than as a deck of its own.
+ */
+export declare function readCanvas(html: string): Canvas | undefined;
+/**
+ * Which profiles could have produced this canvas.
+ *
+ * The composition records pixels, never a profile id, and `deck-16x9` and
+ * `video-16x9` share 1920x1080 — they differ only in navigability. Rather than
+ * guess between them, hold the deck to the most permissive budget any profile
+ * with this canvas allows: a gate that fails a deck for a limit that might not
+ * 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.
+ */
+export declare function profilesFor(width: number, height: number): Format[];
+/**
+ * The budget finding for one built composition, if there is one.
+ *
+ * `storyboard` is optional because `decksmith verify <dir>` has only the
+ * directory. With it, the message can name the beats to drop; without it, the
+ * overrun alone still says the useful half. `kept` is the list `build` actually
+ * emitted — scenes are beats in order, so a scene's window is the narrated
+ * length of the beat at the same index, and getting that pairing wrong would
+ * attribute one beat's seconds to another. Absent, it is re-derived with the
+ * flat threshold, which is the same list only while the budget cut nothing.
+ */
+export declare function scanBudget(html: string, storyboard?: Storyboard, kept?: readonly Beat[]): Finding[];

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

@@ -0,0 +1,78 @@
+import type { Verdict } from "../types.js";
+/**
+ * No `strict` option on purpose. Upstream's `--strict` fails on warnings, and
+ * every real deck emits `composition_file_too_large` — its limit is 300
+ * structural lines, which a seven-beat deck already passes. Its remedy is to
+ * split into sub-compositions, which is exactly the structure that makes a deck
+ * non-navigable (EXPERIMENT-003). So the flag could never pass, and a switch
+ * that cannot succeed is worse than no switch.
+ */
+export interface CheckOptions {
+    /** Also write the five contrast-pass PNGs to `<dir>/snapshots`. */
+    snapshots?: boolean;
+    /**
+     * Extra moments to sample, in absolute deck seconds — the deck's own stops.
+     *
+     * WHY THE DEFAULT GRID IS NOT ENOUGH. Upstream samples nine midpoints across
+     * the whole duration, and a stop is a POINT: a twelve-beat deck is ~92s, so
+     * the grid lands on 5.1, 15.4, 25.6 … and the odds that any of them coincides
+     * with a hold are nil. Measured on a deliberately reverted `claim-figure` fix:
+     * the default grid reported 0 findings, and the same deck sampled at its own
+     * stops reported `canvas_overflow` on `#s11-c` and `#s11-e` at t=91.4. The
+     * overflow was there the whole time; nothing ever looked at the frame the
+     * audience actually sees.
+     *
+     * `regrade` still excuses anything inside a camera transit window, so widening
+     * the sampling cannot resurrect the mid-flight false positives that exemption
+     * exists for.
+     */
+    at?: readonly number[];
+    timeoutMs?: number;
+}
+/** Run the HyperFrames gates over a built project directory. */
+export declare function check(dir: string, opts?: CheckOptions): Promise<Verdict>;
+/**
+ * The times to hand `--at`: the caller's stops UNION the grid they displace.
+ *
+ * THE UNION IS THE WHOLE POINT. `--at` is a replacement, not an addition
+ * (`buildLayoutSampleTimes` returns early on a non-empty `at`), so handing over
+ * a list of stops silently deletes nine samples that were doing real work —
+ * `data-table` at 7 rows is caught by a midpoint and by no stop of its own. A
+ * gate change that trades one class of defect for another is not a
+ * strengthening, and this is the line that stops it being one.
+ *
+ * Times past the end are dropped by upstream anyway; dropping them here keeps
+ * the argument honest about what was asked for. Rounded to 3dp because that is
+ * upstream's own `roundTime`, so a stop and its midpoint neighbour dedupe
+ * instead of running the same frame twice.
+ */
+export declare function sampleTimes(stops: readonly number[], duration: number): number[];
+/**
+ * Turn one `hyperframes check --json` run into a verdict.
+ *
+ * Findings carry no `beatId`: the gates report DOM selectors, and mapping a
+ * selector back to a beat needs the scene→beat table that `emit` owns. The scene
+ * id survives inside the message (`[#s3 .term t=12.5s]`), which is enough to aim
+ * a repair round by hand until T2 makes it mechanical.
+ *
+ * `transit` defaults to none, which is the STRICT grading — a caller who does
+ * not supply the deck's camera windows gets every off-canvas finding as an
+ * error, exactly as before the camera existed.
+ */
+export declare function parseCheckReport(stdout: string, stderr?: string, transit?: Window[]): Verdict;
+/** One camera transit, `[t0, t1]` in absolute deck seconds. */
+/**
+ * A camera's transit window, and WHOSE it is.
+ *
+ * The sid matters because the guarantee is not symmetric. `assertStopsOutsideMove`
+ * promises that no stop of the DIPPING scene lands inside its own move; it
+ * promises nothing about the INCOMING scene, whose first stop can fall inside the
+ * tail (a review built exactly that deck to check). So an exemption granted on
+ * time alone excuses a finding about a scene the emitter never vouched for.
+ */
+type Window = {
+    sid: string;
+    t0: number;
+    t1: number;
+};
+export {};

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

@@ -0,0 +1,158 @@
+import type { Verdict } from "../types.js";
+/** Below this, two renders of the same deck differ in a way a viewer would see. */
+export declare const FLOOR_DB = 40;
+/**
+ * The archetypes a byte-identical fixture may use.
+ *
+ * Everything left out tweens `scale` on something that carries text, or draws a
+ * raster: `equation-walk` scales the term it is explaining, `grid` scales whole
+ * labelled cells, `line-chart` pops its dots from zero, and the two figure
+ * archetypes place a decoded bitmap. Scaling an outline hands Skia a glyph-cache
+ * decision that comes out differently between runs (EXPERIMENT-006), which is
+ * exactly the noise `identical` mode must not contain — so a fixture that grew
+ * one of these would start failing for a reason that is not a defect.
+ *
+ * Enforced by `test/drift.test.ts` against the committed fixture, because the
+ * pressure on a fixture is always to make it more interesting.
+ */
+export declare const FIXTURE_SAFE_ARCHETYPES: ReadonlySet<string>;
+export type DriftMode = "identical" | "psnr";
+export interface DriftOptions {
+    /** Default `psnr`. Use `identical` only on a deck that can actually hold it. */
+    mode?: DriftMode;
+    /** Per-frame PSNR floor in dB. Ignored in `identical` mode. */
+    floorDb?: number;
+    /**
+     * Passed to `hyperframes render -w`. Worker sharding was tested and refuted as
+     * a source of drift (EXPERIMENT-006, hypothesis 2), so this defaults to `auto`
+     * and exists to re-test that, not to work around it.
+     */
+    workers?: number | "auto";
+    /** Where the two frame directories go. A fresh temp directory by default. */
+    workDir?: string;
+    /** Keep the frames even when the gate passes. They are kept on failure regardless. */
+    keep?: boolean;
+    /** Per render, not for the pair. */
+    timeoutMs?: number;
+}
+export interface DriftReport extends Verdict {
+    mode: DriftMode;
+    frames: number;
+    /** Frames whose two PNGs are byte for byte the same. */
+    identical: number;
+    /** The lowest per-frame PSNR and the 1-based frame it fell on. Absent when nothing differed. */
+    worst?: {
+        frame: number;
+        db: number;
+    };
+    /** The two frame directories, when they were kept. */
+    kept?: {
+        a: string;
+        b: string;
+    };
+    /** What moved inside the first render. */
+    motion: Motion;
+}
+/** One scene's window as the composition declares it, in seconds. */
+export interface SceneWindow {
+    id: string;
+    start: number;
+    duration: number;
+}
+/** What changed inside a single render. */
+export interface Motion {
+    /** Scenes that had frames of their own to compare, and did change. */
+    live: readonly string[];
+    /** Scenes that had frames of their own to compare, and did not. */
+    frozen: readonly string[];
+    /**
+     * Scenes with fewer than two frames the scene does not share with a
+     * neighbour. Reported rather than counted as a pass: "no rule applied" and
+     * "the rule passed" have to stay distinguishable.
+     */
+    unmeasured: readonly string[];
+    /** Distinct frames across the whole render — the only measure when no scene could be read. */
+    distinct: number;
+}
+/**
+ * `<div data-composition-id="s3" data-start="…" data-duration="…">` for every
+ * scene, in document order.
+ *
+ * The attribute triple is EXPERIMENT-003's, and `emitComposition` puts it on
+ * scenes and nothing else — `scanBudget` reads the same three. Anchored on the
+ * opening tag rather than swept with one greedy pattern because a `[\s\S]{0,200}`
+ * bridge between two attributes reads across the boundary into the next element
+ * on a scene whose attribute order ever changes.
+ */
+export declare function readScenes(html: string): SceneWindow[];
+/**
+ * Did anything move, and where not?
+ *
+ * PER SCENE, not per deck, because the deck-level question has no threshold that
+ * survives contact. MEASURED on the frozen fixture: 210 frames, 3 distinct
+ * images, 2 frame-to-frame changes — one per scene switch, which HyperFrames
+ * performs itself and which happens whether or not the deck's own timeline ever
+ * ran. A twelve-scene frozen deck would show about twelve. So "more than N
+ * distinct frames" is a bar that rises with the scene count and can be cleared by
+ * a deck in which nothing the emitter wrote has any effect at all. Per scene the
+ * bar is fixed and needs no calibration: a scene either changed during its own
+ * window or it did not.
+ *
+ * A RATIO does not work either, and the two decks say why: the fixture's live
+ * render is 138 distinct frames in 210 (65.7%) and the shipped demo's is 1198 in
+ * 7395 (16.2%), because narration stretches every beat and a hold is one image
+ * for as long as it lasts. A threshold set from the fixture fails the demo; one
+ * set from the demo passes a deck where ten of twelve scenes are dead.
+ *
+ * ITS OWN WINDOW means the frames it does not share with a neighbour. Scenes
+ * overlap by a crossfade — the fixture's s1 is [0, 3.4) and s2 is [3, 7) — and
+ * those shared frames carry the switch, which is exactly the change that is not
+ * evidence of the scene animating. Dropping them takes the frozen fixture's
+ * per-scene count from 1 change to 0, against 55 and 92 in the live render, so
+ * the rule is "at least one change", with no constant to argue about.
+ *
+ * That leaves the partial freeze visible too: one archetype whose reveal is
+ * driven by a callback fails its own scene while the other eleven pass.
+ */
+export declare function measureMotion(hashes: readonly string[], scenes: readonly SceneWindow[], seconds: number): Motion;
+/**
+ * Render `dir` twice and compare.
+ *
+ * `dir` is a built deck directory — the thing `decksmith build -o` writes, with
+ * `index.html` and `hyperframes.json` in it.
+ */
+export declare function drift(dir: string, opts?: DriftOptions): Promise<DriftReport>;
+/**
+ * Turn the measurement into a verdict. Pure, and separated from the plumbing
+ * because this is the part with an opinion in it — everything above just shells
+ * out and hashes.
+ */
+export declare function judge(m: {
+    mode: DriftMode;
+    floorDb: number;
+    frames: number;
+    /** 1-based indices of the frames whose two PNGs differ. */
+    differing: readonly number[];
+    /** Required whenever `differing` is non-empty. */
+    worst?: {
+        frame: number;
+        db: number;
+    };
+    motion: Motion;
+}): DriftReport;
+/**
+ * `frame_000001.png` → `frame_%06d.png`, for ffmpeg's image2 demuxer.
+ *
+ * Derived from what the renderer actually wrote rather than hardcoded, because
+ * the naming is HyperFrames' business: a version that renames its frames should
+ * make this say so, not silently compare nothing.
+ */
+export declare function framePattern(name: string): {
+    pattern: string;
+    start: number;
+} | undefined;
+/** The lowest `psnr_avg` in an ffmpeg stats stream, and the frame it fell on. */
+export declare function worstFrame(stats: string): {
+    frame: number;
+    db: number;
+} | undefined;

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

@@ -0,0 +1,247 @@
+/**
+ * THE FIDELITY GATE — at each stop, did the thing this slide is about appear?
+ *
+ * WHY THIS EXISTS. Four of the twenty compositional decks in
+ * `experiments/015-decision/` are GATE-CLEAN and draw their main diagram as
+ * nothing at all: eight to fifteen drawables per deck, sized legally, placed
+ * legally, and multiplied to zero opacity by a group they were nested in.
+ * `out/f-vocab18.png` is a headline over three grey arrowheads. `lint`,
+ * `runtime`, `layout`, `motion`, `contrast`, the 40px floor and `drift` all pass
+ * on it — `drift` twice over, because both renders are identically empty. Every
+ * gate in this repo reads what the DOM CONTAINS. This one reads what the frame
+ * SHOWS, which is the only thing the audience gets.
+ *
+ * WHERE IT MEASURES, AND WHY NOT THE CHEAPER PLACE. Two prototypes exist.
+ * `invisible.mjs` does arithmetic over the plan — effective opacity as the
+ * product down the parent chain — and found 4 of 20. `ink.mjs` renders the deck
+ * and counts non-background pixels at every hold, and found 5 of 20. The
+ * arithmetic is ~1000x cheaper and it is NOT the gate, for a reason that is
+ * structural rather than aesthetic: the shipped path has no plan to do
+ * arithmetic over. A DeckSmith storyboard never mentions opacity — revealing
+ * what a beat draws is the archetype's job — so on the artifact this project
+ * actually produces there is nothing for `invisible.mjs` to read. It cannot be
+ * a pre-filter either, for the same reason. Pixels are the only instrument that
+ * works on both authoring paths, so pixels are the gate.
+ *
+ * WHICH PIXELS. Not `hyperframes snapshot`, which is the obvious cheap frame
+ * source and is unsound here: it calls `player.renderSeek(t)` with no options
+ * (`cli.js`, `seekCompositionTimeline`), so `suppressEvents` is falsy and a GSAP
+ * `onUpdate` FIRES. Invariant 11 says the capture path suppresses events, so
+ * callback-driven motion plays under snapshot and renders frozen — snapshot is
+ * permissive in exactly the direction that hides the failure this gate is for.
+ * So the gate drives the capture path's own two calls: inject the pinned
+ * hyperframes runtime, `renderSeek(t, { suppressEvents: true })`, then
+ * `Page.captureScreenshot` with the renderer's own clip parameters. Measured
+ * against `experiments/015-decision/out/vocab-18.mp4` — a real render — at all
+ * twelve of its holds, this agrees to a worst case of 0.11 and a mean of 0.03
+ * percentage points, the residual being H.264 quantisation (the video's
+ * background reads 11,13,15 where the screenshot reads 11,13,16).
+ *
+ * WHAT COUNTS AS INK. Pixels that differ from the frame's own modal colour by
+ * more than `INK_DELTA` on any channel. `ink.mjs` used absolute luma > 26, which
+ * is half of the `ink` theme's background and therefore counts 100% of a `mono`
+ * deck's white frame as ink; a shipped gate cannot be theme-specific. The modal
+ * colour IS the background — it holds 80–98% of every frame measured — and one
+ * line of 40px type comes out at 0.684% of the band on `ink`, 0.669% on `mono`
+ * and 0.668% on `paper`, so the measure is theme-independent to within 2.4%.
+ * This is also where `ink.mjs` and `invisible.mjs` disagreed: `ink.mjs` called
+ * `vocab-10` empty at 0.376%, under its 0.4% threshold, because luma > 26 misses
+ * a panel fill that is drawn but dim. Background-relative, `vocab-10`'s emptiest
+ * hold is 3.705% — nine times its own reported value and nowhere near any floor.
+ * The disagreement was the instrument, not the deck: the true count is 4 of 20.
+ *
+ * WHERE IT LOOKS. Below the slide's caption. Whole-frame ink does not
+ * discriminate — measured, MENU's median hold is 16.5% of the frame and VOCAB's
+ * is 3.4%, but the hand-written control is 3.6%, sitting among the failures
+ * rather than above them, because the headline alone is 1.5–2% and every deck
+ * has one. `ink.mjs` cut a fixed band at 0.22H. That band is wrong for this
+ * emitter: a two-line DeckSmith `.headline` reaches 0.309H at 16:9 and 0.382H on
+ * the twelve-beat demo's last scene, so a fixed 0.22H leaves most of the caption
+ * inside the measured region, where its ink would mask an empty body. So the
+ * band's top comes from the artifact — the bottom of the active scene's own
+ * caption — and 0.22H is only the fallback for a composition that names none.
+ * The control that had to be run: blank the archetype on four of the demo's
+ * scenes and measure what is left below the caption. It is 0.0000% on all four,
+ * so a DeckSmith slide whose beat drew nothing reads exactly zero. The gate is
+ * not being propped up by chrome.
+ *
+ * THE FLOOR IS NOT FITTED. 0.15% of the frame is the measured ink of ONE SHORT
+ * LABEL at the 40px audience floor of invariant 5 (0.213% of a 0.73H band =
+ * 0.155% of the frame, measured in Chrome, three themes). Below that the body
+ * holds less ink than the smallest legible thing this project permits. The
+ * corpus then CHECKS it rather than setting it: over 466 stops the worst
+ * positive reads 0.039% of the frame and the best negative 0.663%, so the floor
+ * derived from the type gate lands 3.8x above one and 4.4x below the other. Had
+ * it landed outside that gap, the floor would have been wrong and the gap would
+ * have said so. Fitting it would have looked exactly like this and meant
+ * nothing, which is why the number came from somewhere else first.
+ *
+ * ACCEPTANCE, from `fidelity()` itself and not a lookalike. 41 decks, 466 stops:
+ * TP 4, FP 0, TN 37, FN 0. It flags `vocab-11`, `-13`, `-16` and `-18` and names
+ * the scene (`s01-flow` in all four). It flags none of arm MENU's 20, none of the
+ * twelve other VOCAB decks, not the hand-written control, and not the twelve-beat
+ * demo in any of its four formats — whose tightest margin is 7.6x the floor
+ * (9:16, 1.138%; 16:9 and video 1.732%; 1x1 1.704%) — nor `demo/fixtures/`
+ * (plain 4.435%, camera 7.181%). Re-run three times, every number identical to
+ * four decimals: this gate does not flake, which matters more than its sensitivity
+ * because a false positive on a good slide is how `composition_file_too_large`
+ * became something everyone ignores.
+ *
+ * The number that did NOT move is the one worth the most. Arm MENU is 0 of 20
+ * under `invisible.mjs`, 0 of 20 under `ink.mjs` and 0 of 20 here — three
+ * different measures, three different thresholds, one answer — which is what
+ * makes 4 of 20 on the other arm a property of composition rather than of
+ * whoever wrote the checker.
+ *
+ * THE CONTROL THAT COULD HAVE REFUTED IT. Case thirteen is not expressible on the
+ * shipped path, so it was forced: a copy of the twelve-beat demo with one CSS
+ * rule holding every scene's content at opacity 0 while the captions reveal
+ * normally. Every other gate passes it with ZERO errors and ZERO warnings — it
+ * even loses `connector_detached`, because an invisible connector detaches from
+ * nothing — and this gate fails it with 12 errors, 37 of 37 stops at 0.0000%. The
+ * same deck unbroken reads 1.732% and passes. That is the fourteenth case, caught
+ * before it shipped rather than after.
+ *
+ * WHAT WAS TRIED AND REFUTED. "Ink INCREASED across the reveal" is the more
+ * appealing signal — it promises to excuse a sparse slide — and the corpus kills
+ * it. Per scene, last hold minus first: the hand-written control's scene 2 gains
+ * 0.71 points while every broken scene gains more (vocab-11 0.80, vocab-13 1.04,
+ * vocab-18 1.28, vocab-16 1.80), because a scene that starts at zero and ends
+ * faint still increases. Per-scene MAXIMUM ink fails too, and by a hair that is
+ * worse than a wide miss: vocab-16's broken third scene peaks at 2.51% against
+ * the control's honest 2.44%. Presence at a stop is the signal; nothing else in
+ * the corpus separates.
+ *
+ * WHAT IT STILL CANNOT SEE, written down here so it is not rediscovered as a
+ * surprise. It answers "something was drawn", never "something was legible": a
+ * panel wash 13 levels off the background clears the floor while being nearly
+ * invisible, and nothing in the stack measures contrast for a SHAPE — `contrast`
+ * only grades runs of text. It measures only at declared stops, so a scene with
+ * no holds is not looked at, on the grounds that the deck never claims the
+ * audience is stopped there. And it is per-scene, not per-element, which costs a
+ * real case: `vocab-16`'s third scene is a bar chart whose FIVE BARS are all
+ * invisible while its value labels, axis and category labels are not — opened, it
+ * is five numbers floating over an axis — and it reads 0.520% at its emptiest
+ * stop, 3.5x the floor, so this gate passes it. The deck is still caught, on its
+ * first scene, so the confusion matrix does not show the miss; the scene-level
+ * miss is real all the same. No threshold fixes it, because the labels genuinely
+ * appeared. What would fix it is knowing that a bar chart must have bars — the
+ * beat's intent, which is precisely what arm MENU's archetypes encode and a
+ * composed plan does not.
+ *
+ * COST, and this is why it is not behind a flag. Alone it is 3.8–4.7s for the
+ * twelve-beat demo's 37 stops — one browser, one page, one screenshot each. In
+ * `verify` it is FREE: it runs concurrently with `check`, which is a child
+ * process on its own Chrome, and finishes first. Measured, three runs each:
+ * `verify --no-fidelity` 5.66 / 5.77 / 5.75s, `verify` 5.61 / 5.64 / 5.66s. So
+ * the marginal wall cost is zero and the difference is noise, which was NOT the
+ * expected answer — the estimate before measuring was +7%. `npm run score` on the
+ * 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 { Finding } from "../types.js";
+/**
+ * Ink at a stop, as a fraction of the WHOLE frame — not of the measured band.
+ *
+ * The band's top moves with the caption, so a band-relative fraction would move
+ * the threshold every time a headline wrapped to another line. Normalising by
+ * the frame instead makes the number an amount of ink, and tightening the band
+ * can then only lower it. That is the safe direction: a stricter band cannot
+ * make a blank slide pass.
+ */
+export declare const INK_FLOOR = 0.0015;
+/** One declared stop: which scene, and where on the deck timeline. */
+export interface Stop {
+    /** Composition id — `s1`, `s2`. */
+    sid: string;
+    /** Absolute seconds on the composition timeline. */
+    t: number;
+}
+export interface Measured extends Stop {
+    /** Non-background pixels below the caption, over the whole frame's pixels. */
+    ink: number;
+    /** Where the band began, as a fraction of frame height. Reported for triage. */
+    bandTop: number;
+}
+export interface FidelityOptions {
+    floor?: number;
+    /**
+     * Stops to measure. Supplied by the 015 calibration harness, whose decks are
+     * not DeckSmith builds and carry neither `timing.json` nor an island; the
+     * shipped path reads them off the artifact.
+     */
+    stops?: readonly Stop[];
+    timeoutMs?: number;
+}
+export interface FidelityReport {
+    stops: Measured[];
+    /**
+     * Both gates' findings — this one's `blank_at_stop` and `overprint`'s
+     * `svg_text_overprint`.
+     *
+     * They share a report because they share a browser, a page and a seek: the
+     * collision rule is one `page.evaluate` inside the loop below. Keeping it in
+     * its own module and folding the findings in here is the split that costs
+     * nothing — see `verify/overprint.ts` for why the rule has to exist at all.
+     */
+    findings: Finding[];
+    elapsedMs: number;
+}
+export interface Frame {
+    width: number;
+    height: number;
+    /** 3 for RGB, 4 for RGBA. */
+    channels: number;
+    pixels: Uint8Array;
+}
+/**
+ * Chrome's screenshot PNG, unpacked.
+ *
+ * Written out rather than taken from a dependency because `fflate` already ships
+ * for the pack format and supplies the only hard part; what is left is one
+ * chunk walk and one unfilter. `ffmpeg` would also do it, but `verify` does not
+ * otherwise need ffmpeg and a gate that needs a second binary is a gate that
+ * gets skipped on the machine that lacks it.
+ */
+export declare function decodePng(png: Uint8Array): Promise<Frame>;
+/**
+ * Non-background pixels from `bandTopPx` down, over the whole frame's pixels.
+ *
+ * Pure and exported so the measurement can be tested without a browser — and so
+ * that "what this counts" is a thing someone can read in twenty lines rather
+ * than infer from a gate's verdict. It counts PIXELS. It does not read a
+ * 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;
+/**
+ * The stops a built deck declares, from `timing.json` if it is there and the
+ * slideshow island if it is not.
+ *
+ * `timing.json` is preferred because it exists for every format — `short-9x16`
+ * emits no navigable page and so no island — and because it names the scene each
+ * stop belongs to, which is what makes a finding aimable. Its `holds` are
+ * SCENE-RELATIVE and its `scenes[].start` absolute; the island's `fragments` are
+ * already absolute. (`TimedScene.holds`' doc comment in `src/render/timing.ts`
+ * says "absolute" and is stale — `framePlan` adds `scene.start` at line 265, and
+ * line 370 says so outright.)
+ */
+export declare function readStops(timing: string | null, deckPage: string | null): Stop[];
+/**
+ * Findings for the stops whose body drew nothing.
+ *
+ * One finding per SCENE rather than per stop. The failure is a scene whose
+ * content never arrives, and vocab-16 has five such stops in one scene — five
+ * lines saying the same thing is how a report becomes wallpaper. The worst stop
+ * is named because that is the frame to open.
+ */
+export declare function gradeFidelity(rows: readonly Measured[], floor?: number): Finding[];
+/**
+ * Seek every declared stop and count the ink below its caption.
+ *
+ * Never throws for an environmental reason: a machine that cannot open a browser
+ * gets a WARNING saying the gate did not run, because "the instrument is
+ * missing" and "the deck is blank" are different claims and only the second is
+ * the deck's fault. A stop that *was* measured and came up empty is an error.
+ */
+export declare function fidelity(dir: string, opts?: FidelityOptions): Promise<FidelityReport>;