@jokerized/decksmith 0.7.0 → 0.9.0

package/dist/types/index.d.ts

@@ -1,6 +1,6 @@
 import { type DeckNarration } from "./emit/composition.js";
 import type { Cut } from "./plan/select.js";
-import { type Format, type Source, type Storyboard } from "./types.js";
+import { type Design, type Format, type Source, type Storyboard } from "./types.js";
 /**
  * Markdown (and LaTeX-ish markdown) in, typed `Source` out. The one parser we
  * have; a consumer that already holds structured text can skip it and hand
@@ -103,10 +103,22 @@ export type { Deck, DeckNarration, DeckOptions } from "./emit/composition.js";
  * itself, exported so it can be run against a budget no `Format` states.
  */
 export { selectBeats } from "./plan/select.js";
+/**
+ * `--design v2`: the Director that picks each beat's look, the look vocabulary
+ * it picks from, and the sameness numbers it reports. Exported so an eval can
+ * measure a corpus of storyboards without building each one.
+ */
+export { direct, summarize } from "./plan/direct.js";
+export type { BeatLook, Direction, LookSummary } from "./plan/direct.js";
+export { candidates, classicLook, LOOK_FILE, signature, VARIANTS } from "./emit/look.js";
+export type { Look, Placement } from "./emit/look.js";
 export type { Cut, Dangling, Dropped, DropRule, SelectionBudget } from "./plan/select.js";
 /** Themes are a named, closed set; a consumer needs to enumerate and validate. */
 export { resolveTheme, THEME_NAMES, THEMES } from "./emit/themes/index.js";
 export type { DeckTheme } from "./emit/themes/index.js";
+export { PACKS } from "./emit/themes/packs.js";
+export { chooseLook, type Design, type LookChoice, pickTheme, rankPacks, } from "./emit/themes/pick.js";
+export { TYPES, type TypeSpec } from "./emit/type.js";
 /**
  * The gates. `verify` is ours plus HyperFrames'; `check` is HyperFrames' alone
  * and needs its CLI. A build that never opens a browser can still run `verify`
@@ -123,8 +135,11 @@ export { verify } from "./verify/index.js";
  * `scanBeatCount` also fold into `verify`; that one needs the preferences the
  * deck was asked for, which a built directory does not carry — and
  * `scanUnusedFigures` folds in only where the source was passed alongside.
+ * `scanMath` does not fold into `verify`: by then the build has already said
+ * the same thing through `onBeatWarning`, and saying it twice trains people to
+ * stop reading it.
  */
-export { scanBeatCount, scanNarrationDrift, scanPaperArc, scanHeadlines, scanNarrationLead, scanRepeatedObject, scanUnusedFigures, } from "./verify/index.js";
+export { scanBeatCount, scanMath, scanNarrationDrift, scanPaperArc, scanHeadlines, scanNarrationLead, scanRepeatedObject, scanUnusedFigures, } from "./verify/index.js";
 export { check, parseCheckReport, sampleTimes } from "./verify/check.js";
 export type { CheckOptions } from "./verify/check.js";
 /**
@@ -134,7 +149,25 @@ export type { CheckOptions } from "./verify/check.js";
  * verdict. `verify` runs it; nothing else has to.
  */
 export { gradeOverprint, MIN_OVERLAP, overprints } from "./verify/overprint.js";
+/**
+ * Motion variety measured off a built composition: modal-entrance share, seam
+ * kinds, ease shares. The M4 exit metrics; see experiments/019-motion.
+ */
+export { motionStats, topTwoEaseShare } from "./verify/motion.js";
+export type { MotionStats } from "./verify/motion.js";
 export type { Overprint, Overprinted, TextRun } from "./verify/overprint.js";
+/**
+ * The frame gate on its own, and the fill measure it carries: one browser over
+ * a built deck, every stop seeked and captured. `verify` runs it beside `check`;
+ * exported so an eval can read `fills` — main-axis fill at each scene's last
+ * hold, on a classic deck as on a v2 one — without running the slower half.
+ * `fillBand` and `FIT_FILE` are the definition and the manifest both sides use.
+ */
+export { fidelity } from "./verify/fidelity.js";
+export type { FidelityReport } from "./verify/fidelity.js";
+export { fillBand, FIT_FILE } from "./emit/fit.js";
+export type { Fit, FillBand, FitManifest } from "./emit/fit.js";
+export type { FillRow } from "./verify/fill.js";
 /**
  * The determinism gate: render the deck twice and compare. Separate from
  * `verify` because it costs two full renders — minutes, not milliseconds — so
@@ -218,6 +251,10 @@ export interface BuildDeckOptions {
     onBeatWarning?: (beatId: string, warning: string) => void;
     /** Any name in `THEME_NAMES`. Overrides `storyboard.theme`. */
     theme?: string;
+    /** `classic` (default) or `v2`. Overrides `storyboard.design`. See `designSchema`. */
+    design?: Design;
+    /** v2: the seed the style pack is ranked by. Default `storyboard.sourceId`. */
+    packSeed?: string;
     /** Multiplies every duration and hold. 1 leaves the bytes untouched. */
     speed?: number;
     /** Default `FORMATS["deck-16x9"]`. */

package/dist/types/plan/direct.d.ts

@@ -0,0 +1,66 @@
+import type { EmitContext, Scene, Theme } from "../emit/kit.js";
+import { type Look } from "../emit/look.js";
+import type { Archetype, Beat, Design, Format, Source } from "../types.js";
+export interface DirectOptions {
+    source: Source;
+    format: Format;
+    theme: Theme;
+    /** Normally `storyboard.sourceId`. */
+    seed: string;
+    /**
+     * The design every candidate is emitted under. `v2` from `emitDeck`, so each
+     * look is measured as the fit engine will actually draw it; absent in tests
+     * that exercise the Director on its own.
+     */
+    design?: Design;
+    /** The emitter. `emitScene` unless a test substitutes one that misbehaves. */
+    emit?: (beat: Beat, ctx: EmitContext) => Scene;
+}
+/** One beat's decision, as `out/look.json` records it. */
+export interface BeatLook {
+    beat: string;
+    archetype: Archetype;
+    variant: string;
+    placement: Look["placement"];
+    signature: string;
+    /** The chosen look's `Scene.fill`, when its emitter reports one. */
+    fill?: number;
+    /** Candidates that drew and kept the classic timing. Always ≥ 1. */
+    viable: number;
+    /** Candidates that were refused, and why — the emitter's own sentence. */
+    refused: {
+        signature: string;
+        reason: string;
+    }[];
+}
+export interface Direction {
+    /** One per beat, in order: what `EmitContext.look` is set to. */
+    looks: Look[];
+    beats: BeatLook[];
+    summary: LookSummary;
+}
+export interface LookSummary {
+    beats: number;
+    distinct: number;
+    /** Share of beats whose chrome sits on top of the slide (title excluded from the numerator). */
+    modalChrome: number;
+    /** Adjacent pairs with the same signature. */
+    adjacentRepeats: number;
+    /** The four most-used signatures' share of beats. */
+    top4: number;
+}
+export declare function direct(beats: readonly Beat[], opts: DirectOptions): Direction;
+/**
+ * The least share of the classic look's figure area another look may draw the
+ * figure at. The review (2026-10-08) measured v2's rail and foot looks shrinking
+ * the paper's own figure to 43-61% of its classic area (ja s4, ko s6, en s5) to
+ * make room for a headline: fill went up because white plate and bigger text
+ * count as ink, and the most informative thing on the slide got smaller. A
+ * look that keeps 80% or more is still a different slide; one below it is not
+ * worth the variety.
+ */
+export declare const FIGURE_FLOOR = 0.8;
+/** The sameness numbers for one deck. Also used by the corpus measurement. */
+export declare function summarize(beats: readonly Pick<BeatLook, "archetype" | "signature" | "placement">[]): LookSummary;
+/** 32-bit FNV-1a. Deterministic, dependency-free, and enough to spread ties. */
+export declare function fnv1a(s: string): number;

package/dist/types/plan/prompt.d.ts

@@ -1,15 +1,3 @@
-/**
- * What the model is told, and what it is told about.
- *
- * Planning quality is the product, and this file is where it is won or lost —
- * the schema only guarantees the storyboard is well-formed, never that it is a
- * good explanation of this particular document.
- *
- * `renderSource` deliberately puts every citable id next to its caption. The
- * model cannot cite an id it was never shown, so the inventory is the cheapest
- * defence against the failure mode that actually happens: a plausible-looking
- * `figureId` that exists in no source.
- */
 import type { Prefs } from "../prefs.js";
 import { type Source } from "../types.js";
 /**

package/dist/types/prefs.d.ts

@@ -1,5 +1,5 @@
 import type { z } from "zod";
-import { prefsSchema, type Source } from "./types.js";
+import { type Design, prefsSchema, type Source } from "./types.js";
 export type Prefs = z.infer<typeof prefsSchema>;
 /**
  * A partial Prefs. `narration` and `images` are the two nested objects, so they
@@ -33,6 +33,16 @@ export declare function loadPrefs(overrides?: PrefsPatch, cwd?: string, source?:
  * schema, so there is exactly one place that decides what a legal tone is.
  */
 export declare function prefsFromFlags(flags: PrefFlags): PrefsPatch;
+/**
+ * The design a build uses: a `--design` flag or a config file, else what the
+ * storyboard was planned under, else `classic`.
+ *
+ * NOT `stated()`, which treats a value at its default as unsaid. `design` has
+ * no default — it is optional in the schema — so an explicit `classic` is
+ * distinguishable from silence, and it IS the rollback: it has to win over a
+ * storyboard planned under v2.
+ */
+export declare function designFor(prefs: Pick<Prefs, "design">, recorded?: Design): Design;
 /** The flag surface the CLI exposes. Every one optional: absent means unstated. */
 export interface PrefFlags {
     slides?: string | number;
@@ -42,6 +52,10 @@ export interface PrefFlags {
     genre?: string;
     duration?: string | number;
     theme?: string;
+    /** `--design classic | v2`. */
+    design?: string;
+    /** `--pack-seed`: what v2 hashes to pick a pack. */
+    packSeed?: string;
     speed?: string | number;
     narrate?: boolean;
     voice?: string;

package/dist/types/render/capture.d.ts

@@ -66,6 +66,30 @@ export interface ResolvedChrome {
 export declare function resolveChrome(need?: string): Promise<ResolvedChrome>;
 /** The path alone, for the callers that only ever wanted that. */
 export declare function chromePath(need?: string): Promise<string>;
+/**
+ * Whether Chrome died for want of a sandbox. Stock Ubuntu 24.04, GitHub's
+ * `ubuntu-latest` included, sets `kernel.apparmor_restrict_unprivileged_userns=1`.
+ * Chrome's sandbox needs exactly those namespaces, so it exits at launch with
+ * `FATAL:zygote_host_impl_linux.cc(…)] No usable sandbox!`, which puppeteer
+ * quotes in the error it throws.
+ */
+export declare function sandboxMissing(err: unknown): boolean;
+/** How a person gets the sandbox back. */
+export declare const SANDBOX_FIX = "`sudo sysctl -w kernel.apparmor_restrict_unprivileged_userns=0`, or give Chrome an AppArmor profile";
+/**
+ * Launch Chrome for a page DeckSmith wrote itself: a built deck, a caption band.
+ *
+ * On a host with no usable sandbox (`sandboxMissing`) every gate that opens the
+ * deck reported `not_measured`, a warning, so `build` PASSED having measured
+ * nothing (.planning/2026-09-18-linux-determinism.md §4). The sandbox stays on
+ * wherever Chrome can have one. Only when Chrome refuses to start without it is
+ * the launch retried with `--no-sandbox`, and stderr says so. That is no wider
+ * than the render already is: hyperframes launches its own capture with
+ * `--no-sandbox` every time, on this same deck.
+ *
+ * Pages from the web never come here: `harvest` refuses instead.
+ */
+export declare function launchOwnPage<T>(launch: (args: string[]) => Promise<T>, args: string[], what: string): Promise<T>;
 type Browser = Awaited<ReturnType<typeof import("puppeteer-core").launch>>;
 type Page = Awaited<ReturnType<Browser["newPage"]>>;
 /** An open deck, seekable and photographable. Close it. */

package/dist/types/render/timing.d.ts

@@ -111,6 +111,22 @@ export interface Timing {
      * written without it, and those decks did reserve nothing.
      */
     captionReserve?: number;
+    /**
+     * The format the deck was built for: its id and its duration budget.
+     *
+     * The composition records only pixels, and `verify` used to find the budget
+     * by looking those up among the presets. A custom canvas matches none, so
+     * every custom build read "no duration budget applies" — true of the pixels
+     * and false of the deck, which inherits the budget of the profile it was
+     * resized from (`resizeFormat`). Optional, and absent falls back to the pixel
+     * lookup: every `timing.json` written before this lacks it.
+     */
+    format?: {
+        id: string;
+        minWeight: number;
+        maxSeconds?: number;
+        warnSeconds?: number;
+    };
     scenes: TimedScene[];
     segments: TimedSegment[];
 }

package/dist/types/source/fonts.d.ts

@@ -6,10 +6,20 @@ export interface FontBundle {
     /** The woff2 basenames written into `dir`, beside `fonts.css`. */
     files: string[];
 }
+/**
+ * The serif companion to `familyFor`: what a v2 pack whose type spec sets a role
+ * in a serif draws that role's CJK in. Without it every CJK deck set its
+ * headlines in Noto Sans whatever the pack said, so the font change that makes
+ * a serif pack a serif pack disappeared for three languages out of four
+ * (review, 2026-10-08).
+ */
+export declare function serifFamilyFor(lang: string): string | null;
 /** The CJK family a language needs subset, or null: the deck ships Inter (`vendorInter`). */
 export declare function familyFor(lang: string): string | null;
 /**
  * Write `dir/fonts.css` plus its woff2 for `lang`, covering `glyphs`. Returns
  * null for languages the renderer already resolves, which needs no bundle.
  */
-export declare function bundleFont(lang: string, glyphs: string, dir: string): Promise<FontBundle | null>;
+export declare function bundleFont(lang: string, glyphs: string, dir: string, opts?: {
+    serif?: boolean;
+}): Promise<FontBundle | null>;

package/dist/types/types.d.ts

@@ -1001,11 +1001,35 @@ export declare const DIAGRAMMATIC: ReadonlySet<string>;
  */
 export type ArchetypeFamily = "frame" | "structure" | "quantity" | "formal";
 export declare const ARCHETYPE_FAMILY: Readonly<Record<Archetype, ArchetypeFamily>>;
+/**
+ * Which generation of the look a deck is built in.
+ *
+ * `classic` is every deck built before 0.9 and stays byte-identical: it is what
+ * an unset design means, so an npm user and every ink golden see no change. `v2`
+ * opts into the redesign: the v2 player in deck.html (speed, CC, caption size,
+ * remembered preferences — src/deck/playback.ts), the fit engine
+ * (src/emit/fit.ts), a style pack per deck (src/emit/themes/pick.ts), varied
+ * layouts (src/plan/direct.ts) and the motion grammar (src/emit/motion.ts). One
+ * switch rather than one flag per feature, so a deck is always one coherent
+ * design and `--design classic` is a complete rollback.
+ *
+ * OPTIONAL rather than defaulted in both schemas, so a storyboard, a config or
+ * a pack that never mentions it serialises exactly as it did.
+ */
+export declare const designSchema: z.ZodEnum<{
+    classic: "classic";
+    v2: "v2";
+}>;
+export type Design = z.infer<typeof designSchema>;
 export declare const storyboardSchema: z.ZodObject<{
     sourceId: z.ZodString;
     title: z.ZodString;
     lang: z.ZodDefault<z.ZodString>;
     theme: z.ZodDefault<z.ZodString>;
+    design: z.ZodOptional<z.ZodEnum<{
+        classic: "classic";
+        v2: "v2";
+    }>>;
     beats: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
         narration: z.ZodOptional<z.ZodString>;
         archetype: z.ZodLiteral<"title">;
@@ -1600,6 +1624,11 @@ export declare const prefsSchema: z.ZodObject<{
     }>>;
     duration: z.ZodOptional<z.ZodNumber>;
     theme: z.ZodDefault<z.ZodString>;
+    design: z.ZodOptional<z.ZodEnum<{
+        classic: "classic";
+        v2: "v2";
+    }>>;
+    packSeed: z.ZodOptional<z.ZodString>;
     animationSpeed: z.ZodDefault<z.ZodNumber>;
     narration: z.ZodDefault<z.ZodObject<{
         enabled: z.ZodDefault<z.ZodBoolean>;
@@ -1739,6 +1768,11 @@ export declare const packSchema: z.ZodObject<{
         }>>;
         duration: z.ZodOptional<z.ZodNumber>;
         theme: z.ZodDefault<z.ZodString>;
+        design: z.ZodOptional<z.ZodEnum<{
+            classic: "classic";
+            v2: "v2";
+        }>>;
+        packSeed: z.ZodOptional<z.ZodString>;
         animationSpeed: z.ZodDefault<z.ZodNumber>;
         narration: z.ZodDefault<z.ZodObject<{
             enabled: z.ZodDefault<z.ZodBoolean>;
@@ -1807,6 +1841,10 @@ export declare const packSchema: z.ZodObject<{
         title: z.ZodString;
         lang: z.ZodDefault<z.ZodString>;
         theme: z.ZodDefault<z.ZodString>;
+        design: z.ZodOptional<z.ZodEnum<{
+            classic: "classic";
+            v2: "v2";
+        }>>;
         beats: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
             narration: z.ZodOptional<z.ZodString>;
             archetype: z.ZodLiteral<"title">;

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

@@ -26,6 +26,13 @@ export declare function readCanvas(html: string): Canvas | undefined;
  * 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.
  */
+/** What the budget gate reads off a format, whether a preset or the one `build` recorded. */
+export type BudgetFormat = Pick<Format, "id" | "minWeight" | "maxSeconds" | "warnSeconds">;
+/** `timing.json`'s record of the format, with the canvas it was recorded for. */
+export interface RecordedFormat extends BudgetFormat {
+    width: number;
+    height: number;
+}
 export declare function profilesFor(width: number, height: number, formats?: Readonly<Record<string, Format>>): Format[];
 /**
  * The budget finding for one built composition, if there is one.
@@ -46,4 +53,4 @@ export declare function profilesFor(width: number, height: number, formats?: Rea
  * a table that disagrees, rather than the rule being deleted and silently absent
  * the next time a real destination is tighter than the rest.
  */
-export declare function scanBudget(html: string, storyboard?: Storyboard, kept?: readonly Beat[], formats?: Readonly<Record<string, Format>>): Finding[];
+export declare function scanBudget(html: string, storyboard?: Storyboard, kept?: readonly Beat[], formats?: Readonly<Record<string, Format>>, recorded?: RecordedFormat): Finding[];

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

@@ -140,6 +140,7 @@
  * a gate nobody runs; this one costs nothing, so it runs by default.
  */
 import type { Finding } from "../types.js";
+import { type FillRow } from "./fill.js";
 /**
  * Ink at a stop, as a fraction of the WHOLE frame — not of the measured band.
  *
@@ -213,6 +214,11 @@ export interface FidelityOptions {
 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`.
+     */
+    fills: FillRow[];
     /**
      * Both gates' findings — this one's `blank_at_stop` and `overprint`'s
      * `svg_text_overprint`.
@@ -252,6 +258,34 @@ export declare function decodePng(png: Uint8Array): Promise<Frame>;
  * of those have been wrong in this project inside the last week.
  */
 export declare function inkBelow(frame: Frame, bandTopPx: number): 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
+ * below its bottom edge — exactly what `inkBelow` measured, and still is. The
+ * `--design v2` placements (src/emit/look.ts) move the chrome, and "below the
+ * headline" stops meaning "the body": under a `foot` headline there is nothing
+ * at all by design, and beside a `rail` the body is the column to its right.
+ * Measured where the body is, rather than below a headline that is no longer
+ * on top, the same floor means the same thing.
+ */
+export interface BodyRegion {
+    top: number;
+    left: number;
+    bottom: number;
+}
+/**
+ * Non-background pixels inside `region`, over the WHOLE frame's pixels.
+ *
+ * `plate` is the deck's bare background (every scene hidden), when the build
+ * captured one — a v2 deck does, for the fill gate. Against it each pixel is
+ * compared with the same pixel of the empty ground. Against the frame's modal
+ * colour alone a style pack's painted ground — signal's glow, blueprint's grid
+ * — read as ink: with every scene hidden, 4.42% of a signal frame and 2.40% of
+ * a blueprint one measured "inked", 29x and 16x `INK_FLOOR`, so a stop with
+ * nothing drawn on it passed this gate by a wide margin (review, 2026-10-08).
+ * A plate of another size is ignored.
+ */
+export declare function inkIn(frame: Frame, region: BodyRegion, plate?: Frame | null): number;
 /**
  * The stops a built deck declares, from `timing.json` if it is there and the
  * slideshow island if it is not.
@@ -291,6 +325,25 @@ export declare function gradeFidelity(rows: readonly Measured[], floor?: number)
  * thing it was told to deliver, not a note about taste.
  */
 export declare function gradeReserve(rows: readonly Measured[], tolerance?: number): Finding[];
+/** An equation the deck's own fit gave up on: the scene, and the formula. */
+export interface Unfit {
+    sid: string;
+    tex: string;
+}
+/**
+ * Run IN THE PAGE: every display `equation-walk`'s fit marked as not fitting.
+ *
+ * Read once, after the ready gate — the fit runs inside it, before any frame,
+ * so the marks are the same at every time the deck could be seeked to.
+ */
+export declare function collectUnfit(attr: string): Unfit[];
+/**
+ * An error per equation that does not fit its box at the type floor even broken
+ * across lines, NAMING THE FORMULA. The layout gate sees the same overflow and
+ * can only say `span.mord`, which tells nobody which of a deck's equations to
+ * shorten.
+ */
+export declare function gradeUnfit(rows: readonly Unfit[]): Finding[];
 /**
  * Seek every declared stop and count the ink below its caption.
  *

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 {};