@jokerized/decksmith 0.1.0

package/dist/types/emit/camera.d.ts

@@ -0,0 +1,397 @@
+/**
+ * One camera move, between two beats the SOURCE says are nested.
+ *
+ * This is the whole of "keep the stop, lose the cut" (ARCHITECTURE-CANVAS §1).
+ * It is deliberately not a canvas and not a general camera: a beat may declare
+ * that it happens `inside` one named part of the beat immediately before it, and
+ * when it does, the containing beat's window is extended by a dive that lands
+ * with that part filling the frame, so the incoming beat opens on the rect the
+ * outgoing one left on. Where the source supplies no such relation there is no
+ * move, because a smooth pan between unrelated diagrams is a fancier cut and
+ * measurably worse than the cut it replaces (Prezi's motion-sickness complaint
+ * is the market's own version of this finding).
+ *
+ * Three things here are load-bearing and each of them cost a render to learn:
+ *
+ * 1. THE MOVE IS TWO `fromTo`s AND NOTHING ELSE. `seek()` passes
+ *    `suppressEvents`, so a GSAP `onUpdate` never fires under capture. The first
+ *    camera in experiment 008 drove `viewBox` from an `onUpdate`, played
+ *    perfectly in a browser, and rendered 900 frames of a frozen `0 0 1920 1080`
+ *    with every gate green (invariant 11). State must be applied by the thing
+ *    being seeked.
+ *
+ * 2. THE EASES ARE CLOSED FORM AND THEY ARE NOT DECORATION. `zoomEase` travels
+ *    scale in log space — a linear scale tween reads as a lurch, and every
+ *    smooth-zoom implementation since Van Wijk 2004 fixes it the same way.
+ *    `panEase` is the normalised integral of 1/k over the same path, which is
+ *    exactly the condition "the target moves at constant SCREEN speed"; without
+ *    it a pan at 5x whips. Both are pure functions of the tween's own progress:
+ *    nothing reads a clock, a frame delta, or an element's current value, so
+ *    `seek(x)` gives the same transform for a given x on every run and in any
+ *    order.
+ *
+ * 3. THE CONTAINING DIAGRAM IS AT FULL OPACITY FOR THE WHOLE FLIGHT. The spike
+ *    faded its world out DURING the move by accident and made the mid-flight
+ *    frame an empty world — a camera over nothing is not continuity, it is a
+ *    slow wipe. So the fade here starts only once the camera has stopped, and
+ *    lasts `FADE_SECONDS`: the deck dives into the region, comes to rest on it,
+ *    and dips through its own background into the beat that lives there.
+ *
+ *    WHAT THE DIP COSTS, MEASURED, so nobody has to find it twice. Luma sampled
+ *    every 1/30s across the handoff of a `pipeline`→`grid` deck: the dive lands
+ *    at 10.4s, the dip runs to the scene's window end at 10.8s and hands off at
+ *    max luma 63 over a background of 13 — and then the frame is FLAT BACKGROUND
+ *    FOR FIVE FRAMES, 10.8s through 10.933s, before the incoming scene reaches
+ *    23 at 10.967s. Those five frames are not the camera's. They are the
+ *    incoming scene's own opening: `chromeIn` (`title.ts`) puts its first tween
+ *    at 0.15s, so every scene in the deck opens on 150ms of nothing, and a plain
+ *    cut in the demo measures the same four-to-five dark frames at 10.233s.
+ *    Nothing this file can do reaches them: `paint()` and the engine both swap
+ *    scene visibility on one instant, so retiming the dip only moves the hole —
+ *    verified over dip lengths of 0, 0.25 and 0.4, all five frames.
+ *
+ *    THAT HOLE IS NOW CLOSED, and it was closed the way this note predicted:
+ *    extend the OUTGOING scene's clip past the incoming scene's start and run
+ *    the dip on into it. `composition.ts` no longer derives the scene div's
+ *    window, the island's window and the next scene's start from one number —
+ *    the div's `data-duration` is `duration + HANDOFF_SECONDS` while the island
+ *    and the deck's running clock still see `duration`. Doing it on the island
+ *    as well still fails the gate — `slideshow_unresolved_ref: main-line slides
+ *    "s1" and "s2" overlap`, still true on 0.7.71 — which is the same §4
+ *    `planTransition`/`paint()` work described below, and is why the overlap
+ *    lives on the clip and nowhere else. The 150ms proposed here turned out to
+ *    be short by half; `HANDOFF_SECONDS` carries the luma trace that fixes it.
+ *
+ *    That dip is a compromise and it is worth naming. The spike's version keeps
+ *    the container lit while the contained scene arrives inside it, which needs
+ *    both scenes on screen at once — and `hyperframes lint` rejects that
+ *    outright: `slideshow_unresolved_ref — main-line slides "s1" and "s2"
+ *    overlap`. Overlapping windows need the island to place one of them off the
+ *    main line and `paint()` to stop owning `display`, which is exactly the
+ *    `planTransition`/`paint()` work ARCHITECTURE-CANVAS §4 scoped and deferred.
+ *    So what is here is a dive that lands on the incoming beat's frame and dips
+ *    to background across the seam — items 1 and 4 of §2, "do first" and "the
+ *    cheap half of lose the cut" — and not item 5. Called by its right name it
+ *    is a match cut with a camera in front of it, not a continuous world.
+ *
+ * The geometry is measured in the browser rather than computed here, because the
+ * region's page rect depends on how much room the headline above it took, which
+ * depends on font metrics. Measuring during parse frames the deck on fallback
+ * metrics and lands the camera in the wrong place, silently, in a deck that still
+ * renders twice to the same bytes because both renders take the same wrong path.
+ * So the measurement is DEFERRED into the ready gate's barrier and taken exactly
+ * once — see `cameraMeasure`, which carries the render that made it necessary.
+ */
+import type { Format } from "../types.js";
+import { type Tween } from "./kit.js";
+/** How long the dive takes. The spike's MOVE1; long enough to read, short
+ * enough that deck mode's `MAX_SPAN` still sweeps the step around it. */
+export declare const MOVE_SECONDS = 1.4;
+/** How long the landed framing takes to dip to the deck's background, after
+ * which the incoming scene's window begins. Below ~0.25 it reads as a pop; much
+ * above and the seam becomes a noticeable hole in the deck. */
+export declare const FADE_SECONDS = 0.4;
+/**
+ * How far a scene's CLIP outlasts its own slide, so the next scene opens
+ * underneath it instead of on an empty plate. Zero on the last scene.
+ *
+ * This is the number that closes the hole described at the top of this file,
+ * and 0.4 is measured rather than chosen. Every archetype opens through
+ * `chromeIn`, which puts the eyebrow at 0.15s and the headline at 0.3s, so a
+ * scene's first frames carry no ink at all. Luma sampled every 1/30s across the
+ * first handoff of the vertical demo, as mean frame luma above the deck's
+ * background of 27:
+ *
+ *   +0.163s 0.007   +0.263s 0.053   +0.363s 0.809   +0.463s 1.801
+ *
+ * — against 7.73 for the outgoing scene's last lit frame. So the incoming
+ * scene is, measurably, EMPTY for its first tenth of a second and near-empty
+ * for a third of one, and an overlap that ends before ~0.36s only MOVES the
+ * hole rather than closing it: at 0.15 the floor across the seam was 0.007,
+ * indistinguishable from background. At 0.4 the floor is 1.40 and the frames
+ * either side of it are a legible dissolve.
+ *
+ * Do not raise it much further. The two scenes are absolutely positioned on
+ * top of each other, so a long dissolve is two headlines superimposed — at
+ * 0.45 the outgoing eyebrow is still at 58% while the incoming's is up, and
+ * the two lines of type collide legibly.
+ */
+export declare const HANDOFF_SECONDS = 0.4;
+/**
+ * The dissolve that carries a scene across the seam, for a scene with no camera
+ * on it. Starts where the slide ends and runs into the next slide's window, so
+ * it is only ever seen against the incoming scene rather than against nothing.
+ *
+ * `power2.in` for the same reason the dip uses it: the outgoing scene holds
+ * most of its brightness through the first half of the overlap, which is
+ * exactly the half in which the incoming scene has nothing to give.
+ *
+ * The target is the scene div itself. There is no wrapper to fade instead, and
+ * adding one would put a second copy of the scene box in the tree — the camera
+ * rig already carries that cost and only earns it because it needs the
+ * transforms.
+ */
+export declare function handoffStatement(sid: string, at: number, over: number): Tween;
+/** A dive, in the containing scene's own time base. All three already scaled by `speed`. */
+export interface Dive {
+    /** Seconds from the scene's start at which the camera leaves the wide shot. */
+    t0: number;
+    /** Travel time. */
+    dur: number;
+    /** The dip that follows the landing, and ends this scene's window. */
+    fade: number;
+}
+/** How much longer a scene's window is because a camera leaves from it. */
+export declare function diveTail(d: Dive): number;
+/** The DOM id an archetype gives one of its parts: `s2` + `stage1` -> `s2-stage1`. */
+export declare function elementId(sid: string, element: string): string;
+/**
+ * The parts of a scene a camera could enter, read back out of the emitted HTML.
+ *
+ * Only used to write a useful error. There is no registry of enterable regions —
+ * `src/emit/svg.ts`'s `id(sid, part, i)` is the whole convention, and an
+ * archetype that draws a thing with an id can be entered at it.
+ */
+export declare function enterableIds(sid: string, html: string): string[];
+/**
+ * The camera rig, wrapped around one scene's content.
+ *
+ * Two nested transforms and a plate, in that order, because the order is what
+ * makes the neutral framing the IDENTITY transform: scaling about the frame's
+ * centre and then translating the plate by `centre - target` frames the target
+ * for any scale, and both tweens start at 0/1 — the values an element has before
+ * a `fromTo` with `immediateRender: false` has ever run. A rig whose rest state
+ * needed setting would show the wrong framing for every frame before the move.
+ *
+ * The plate carries `class="scene"` so it lays out through the one rule in
+ * `theme.ts` rather than a copy of the padding kept in step by hand.
+ */
+export declare function rigHtml(inner: string): string;
+/**
+ * THE TRANSIT WINDOW, in absolute composition seconds — `[t0, t0+dur+fade+over]`
+ * measured from the deck's start — written onto the cameraed scene's own div as
+ * `data-ds-transit`. Nothing in the browser reads it, and there is exactly one
+ * of them per camera.
+ *
+ * `over` IS PART OF THE WINDOW, and leaving it out was a live bug. `diveTail` is
+ * how much the camera lengthens the scene's SLIDE — `dur + fade`, deliberately
+ * ignorant of the handoff — but the dip `diveStatements` writes lasts
+ * `fade + over`, so the rig is displaced and still visible for `over` seconds
+ * after that. Publishing `dur + fade` therefore describes less than the move:
+ * `menu-10` of `experiments/015-decision` dives at 10s and clips at 12.2s, the
+ * gate sampled 11.978s, and the window said `10,11.8` — thirteen
+ * `canvas_overflow` errors on one legitimate mid-move frame, which was one of
+ * the two failures in that experiment's arm MENU
+ * (`out/f-menu10-11.978.png`; deleting the beat's `inside` made the same plan
+ * PASS). The window must be the move: everything the rig is displaced for.
+ *
+ * It is here because a camera is the first thing in this project that puts
+ * MOTION between two stops, and the layout gate samples a uniform grid that
+ * knows nothing about stops. `hyperframes check` on
+ * `demo/fixtures/camera.storyboard.json` samples 1.1, 3.3, … 18.7 across a 19.8s
+ * deck; exactly one of those, 9.9, lands inside the dive, and at 9.9 the frame
+ * is a legitimate mid-flight crop — headline sliced, outer stages gone past the
+ * edge. Upstream calls all eight of those findings `info` and returns `ok:true`,
+ * because a single-sample dynamic issue is a transient to it. `regrade` in
+ * `src/verify/check.ts` promotes every `canvas_overflow` to `error` on the
+ * stated premise that "every DeckSmith frame the audience sees is a static plate
+ * at a hold" — which is true, and which this window is the exception to. So a
+ * legal storyboard builds a deck that fails our own gate on seven errors, none
+ * of which is a frame anybody sees.
+ *
+ * WHY NOT `data-layout-allow-overflow`, which is the vocabulary upstream's own
+ * fixHint offers. Because it hides real overflow, measured rather than argued.
+ * The audit exempts a text node when `element.closest("[data-layout-allow-
+ * overflow]")` matches — an ancestor test with no notion of time. Every glyph a
+ * camera moves is inside the rig, so the flag can only go on the rig, and there
+ * it exempts the scene at every sample instead of only the ones inside the move.
+ * Three builds of this fixture with the containing beat's `note` replaced by a
+ * 130-character unbreakable word, which overflows the canvas at scale 1, at
+ * every stop, forever:
+ *
+ *   no `inside`, no flag   FAIL 1 error   #s1-note t=5s
+ *   `inside`,    no flag   FAIL 8 errors  #s1-note t=5.5s and t=9.9s, + 6 transit
+ *   `inside`,    flag      PASS
+ *
+ * (Those three were measured before this exemption existed; see the re-measured
+ * pair below, which is the same experiment through today's grading.)
+ *
+ * The third line is a deck shipping with its own copy sliced through and every
+ * gate green — the failure shape this project has now found by hand eleven
+ * times. So the flag is not written. The exemption is published as DATA the
+ * caller can compare a finding's `time` against, and the teeth stay in because
+ * the SECOND line is what a real defect looks like through this window: the note
+ * is reported at 5.5s as well as at 9.9s, and 5.5 is outside the window.
+ * Anything genuinely wrong with the plate is wrong at rest, and at rest the gate
+ * is sampling it. The emitter's half of the same guarantee is
+ * `assertStopsOutsideMove`: no stop is ever inside the window to begin with.
+ *
+ * WIDENING A WINDOW IS THE CHANGE THAT COULD EXCUSE A REAL DEFECT, so the `over`
+ * term was checked both ways rather than argued.
+ *
+ * The teeth, RE-MEASURED with `over` in the window — the same three builds, now
+ * against `9,11.2`. Line two is the one that matters, and it is the number that
+ * did NOT move:
+ *
+ *   no `inside`, no flag   FAIL 1 error              #s1-note t=5s
+ *   `inside`,    no flag   FAIL 1 error + 7 info     #s1-note t=5.5s, 7 at 9.9s
+ *
+ * (The middle column reads 1+7 rather than the 8 errors recorded above only
+ * because this exemption now exists; the ERROR at 5.5s is unchanged, and 5.5 is
+ * outside the widened window as it was outside the narrow one.)
+ *
+ * THE ADVERSARIAL DECK, which `.planning/DECISION.md` §5.1 named as the control
+ * this change must survive: `regrade` exempts by TIME ALONE, with no scene scope,
+ * so the extra `over` seconds exempt the whole deck — including the INCOMING
+ * scene, whose first stop can land inside them. Constructed rather than argued
+ * about: the incoming beat is 0.5s long, so `holdsWithin` clamps its stop to
+ * 0.35s (inside the 0.4s tail), its eyebrow AND headline are 130-character
+ * unbreakable words, and a third 0.3s beat tunes the deck's total so that one of
+ * the layout gate's nine uniform samples lands at 10.956s — inside the tail. That
+ * deck's stop really is inside the published window: `[9, 11.2]` against a
+ * fragment at 11.15.
+ *
+ * One render of it, graded twice, which is the only way to attribute a change to
+ * the change:
+ *
+ *   window [9, 10.8] (the bug)   FAIL 7 errors, all `#s1-*` at t=10.956s
+ *   window [9, 11.2] (fixed)     PASS
+ *   findings naming `#s2`        ZERO, at any severity, in both gradings
+ *
+ * So everything the wider window forgave was the dipping rig's own displacement,
+ * and nothing about the incoming scene was forgiven — because during the handoff
+ * the incoming scene has nothing to forgive. `chromeIn` starts its eyebrow at
+ * 0.15s over 0.5s and its headline at 0.3s over 0.6s, so at 0.156s into a scene
+ * there is no text at a measurable opacity yet. That is the same 150ms of nothing
+ * the handoff exists to cover, seen from the other side.
+ *
+ * The corpus agrees: across the 36 built decks of
+ * `experiments/015-decision/out/decks` (36 windows, one per deck), widening every
+ * published window by 0.4s AND by 0.8s swallows ZERO stops, and the earliest stop
+ * any of their 60 scenes has is 1.55s into itself.
+ *
+ * WHAT IS STILL NOT GUARANTEED, said out loud because the exemption's own message
+ * overstates it. `regrade` prints "no hold is inside this window"; what the
+ * emitter guarantees is that no hold of the DIPPING scene is
+ * (`assertStopsOutsideMove`), and an incoming scene's hold inside the `over` tail
+ * is reachable — the deck above has one. It is harmless only because nothing of
+ * that scene is visible yet. Closing it for good means scoping the exemption to
+ * the dipping rig's own subtree, which is `regrade`'s job in
+ * `src/verify/check.ts`: the sid is right there in the selector it already has.
+ *
+ * `over` is a required argument, not one defaulting to 0. A default is what let
+ * the sole call site drift out of step with `diveStatements` in the first place;
+ * making it required means the compiler asks.
+ */
+export declare function transitWindow(start: number, d: Dive, over: number): string;
+export declare function cameraCss(): string;
+/**
+ * THE MEASUREMENT, taken ONCE, inside the ready gate's barrier — after
+ * `document.fonts.ready` and before this scene's timeline exists. Emitted as
+ * `Scene.measure` (see `sceneHtml`), so these statements run in the scene's own
+ * builder closure and the tweens below read `dsFramed` as a plain number.
+ *
+ * WHY NOT LAZILY, which is what this did until the twelfth case of a green gate
+ * over wrong output. `hyperframes render` shards frames CONTIGUOUSLY, one span
+ * per worker, so worker k's first seek lands MID-DECK — and a value first read on
+ * a tween's first render is therefore read under different conditions in every
+ * worker. `experiments/014-seam-b` measured that standalone: `lazy` moved 286 of
+ * 360 frames when only `--workers` changed, `defer` 0 of 360.
+ *
+ * WHAT THE NUMBER ATTRIBUTED TO THIS FILE ACTUALLY WAS, because the first reading
+ * of it was wrong and the correction is the useful part. The twelfth case reported
+ * `demo/fixtures/camera.storyboard.json` differing in 201 of 594 frames at 1 vs 3
+ * workers, worst 51.52 dB, and blamed the lazy read here. It is not the lazy read.
+ * Three controls, each varying one thing:
+ *
+ *   defer vs lazy, same worker count   594 of 594 frames BYTE-IDENTICAL
+ *   lazy, 1 vs 3 workers               201 of 594, worst 51.52 dB — the same
+ *                                      frames and the same dB as `defer`
+ *   the same two beats, camera REMOVED  180 of 540, worst 51.52 dB, and the
+ *                                      differing frames are exactly worker 3's
+ *                                      contiguous shard
+ *
+ * So the fixture's 201 is 198 frames of the `grid` scene's cell fill landing one
+ * LSB apart in a worker whose first seek is inside that scene, plus 3 frames of 3
+ * pixels at 113 dB. It has nothing to do with the camera and this change does not
+ * move it.
+ *
+ * AND WHY THAT FIXTURE CANNOT WITNESS THE CLASS AT ALL, which is worth knowing
+ * before anyone points it at this again. The dive tweens carry
+ * `immediateRender: false`, so under a lazy read GSAP never touches them before
+ * `t0`; the read therefore happens on each worker's first frame at or after `t0`,
+ * and by then everything it measures — `#s1-stage1`, revealed at 2.4s over 0.5s —
+ * has stopped moving. Every worker that reaches the dive measures the same rects.
+ * Point a camera at something that is STILL MOVING at `t0` and the class appears
+ * at once. Measured, target given a 4s `y` tween running through `t0` and the
+ * shard boundary forced inside the dive at 2 workers:
+ *
+ *   lazy    39 of 594 frames differ, worst 14.96 dB — the camera lands 18px off
+ *   defer    7 of 594 frames differ, worst 62.64 dB — antialiasing on a scaled edge
+ *
+ * 14.96 dB is a visibly different frame. That is the defect this file no longer
+ * has, and the 51.52 dB one belongs to somebody else.
+ *
+ * Deferring is not merely earlier. It is the difference between a value GSAP
+ * evaluates when it feels like it and a NUMBER in the vars payload — which is why
+ * the eases below are now closed-form functions built once from a fixed ratio
+ * rather than wrappers that re-read a memo on every call.
+ *
+ * `dsFramed` measures the target RELATIVE TO THE PLATE and divides out the
+ * plate's scale, so the answer is a property of the LAYOUT and not of the moment
+ * it was taken. Nothing has moved the rig when this runs, but a non-1920 canvas
+ * carries a scale on `.scene` regardless (`zoomOf`), so the division is load-
+ * bearing in portrait and it is also what keeps a second reading — if anything
+ * ever takes one — equal to the first.
+ *
+ * A missing target degrades to the neutral framing rather than to `NaN`: a
+ * camera that does not move is a cut, and a cut is what we had. The emitter
+ * refuses to write a camera at a target that is not in the HTML, so this branch
+ * only fires if something removed the element after emit.
+ */
+export declare function cameraMeasure(sid: string, element: string, format: Format): string[];
+/**
+ * The move itself. Two `fromTo`s on the rig, plus the container's fade.
+ *
+ * Every value that depends on the measurement is an EXPRESSION over `dsFramed`,
+ * which `cameraMeasure` has already assigned by the time these statements run.
+ * So GSAP is handed numbers, and the timeline is as seekable as one written here
+ * at emit time — no function value evaluated on a first render whose position in
+ * the deck depends on how many workers the renderer happened to start.
+ *
+ * `immediateRender: false` is not optional: with it, the rig has no transform at
+ * all before `t0` — which is the neutral framing — and GSAP holds the landing
+ * transform after the move ends, which is the framing the incoming scene opens
+ * on.
+ */
+export declare function diveStatements(sid: string, format: Format, d: Dive, over?: number): Tween[];
+/**
+ * THE TYPE FLOOR UNDER A CAMERA.
+ *
+ * The 40px rule is about what the audience can READ, so under a camera it has to
+ * be stated in final rendered pixels rather than in the emitter's font-size:
+ *
+ *   At every stop time t_s, for every text node n intersecting the viewport,
+ *     effOpacity(n, t_s) == 0  OR  finalPx(n, t_s) >= 40
+ *   where finalPx = computedFontSize x screenScale and effOpacity is the product
+ *   of computed opacity to the root. TRANSIT IS EXEMPT, and is exempt only
+ *   because the deck never rests between stops.
+ *
+ * That reading is what lets a cropping camera reach 1.55-1.75x where a camera
+ * that had to keep everything inside a safe box was stuck at 1.127x: text that
+ * leaves the frame is not small, it is absent, and nobody is asked to read it.
+ *
+ * This function is the part of that rule an emitter can enforce WITHOUT a
+ * browser, and it enforces it by making the general case unnecessary: if no stop
+ * falls inside the move, then at every stop of a cameraed scene the rig is at
+ * scale 1 (before `t0`, because `immediateRender: false` leaves no transform) or
+ * at the landing scale with the region filling the frame (after the landing,
+ * where every surviving glyph is LARGER than it was authored). Either way the
+ * static 40px floor the archetypes already satisfy is still the true floor, and
+ * the browser-measured rule above is only needed once a stop lands mid-camera.
+ *
+ * Throws rather than warns: a stop inside a camera move is a frame where the
+ * audience is asked to read text at an arbitrary scale, and that is exactly the
+ * class of defect that ships green.
+ */
+export declare function assertStopsOutsideMove(sid: string, holds: readonly number[], d: Dive): void;

package/dist/types/emit/composition.d.ts

@@ -0,0 +1,191 @@
+/**
+ * Storyboard + Source + Format -> one HyperFrames composition.
+ *
+ * This module owns the deck's structure, and structure is where deck mode fails
+ * silently: EXPERIMENT-002 produced a deck that passed `lint`, served, rendered,
+ * and had zero navigable slides. Nothing in the gate stack said so. So the
+ * renderer's structural rules live here as code rather than as prose an agent is
+ * asked to remember, and every one of them is annotated with what breaks.
+ *
+ * The shell never learns what an archetype means — it lays beats out on a
+ * timeline, wraps whatever the emitter returns, and closes the document.
+ */
+import type { z } from "zod";
+import { type Cut } from "../plan/select.js";
+import type { Format, Source, Storyboard, segmentSchema } from "../types.js";
+import { type Scene } from "./kit.js";
+/** A built deck. `page` is present only for navigable formats. */
+export interface Deck {
+    composition: string;
+    page?: string;
+    /**
+     * Which beats went in, which did not, and why each one did not.
+     *
+     * Returned rather than logged here because `emit` is a pure function and the
+     * caller owns the terminal — but it is not optional to LOOK at: a cut nobody
+     * prints is a third of the explanation missing from a deck that still says
+     * PASS. `build` prints every casualty's reason; see src/cli.ts.
+     */
+    cut: Cut;
+}
+type Segment = z.infer<typeof segmentSchema>;
+/**
+ * Narration as the deck page needs it: the segments, keyed by BEAT id because
+ * that is what `narrate` produced, plus where the audio sits relative to the
+ * page. The beat→scene mapping is `layout`'s to make — a scene id is a position
+ * over the beats a format kept, and no other layer knows which those are.
+ */
+export interface DeckNarration {
+    voice: string;
+    /** Directory holding the mp3s, relative to `deck.html`. */
+    dir: string;
+    beats: Record<string, Segment[]>;
+}
+/**
+ * The look-and-pace decisions `prefs` owns, handed down rather than read here:
+ * `emit` is a pure function of its arguments, and a module that loads a config
+ * file is a module you cannot render twice and compare.
+ */
+export interface DeckOptions {
+    /** Overrides `storyboard.theme`. Any name in the registry. */
+    theme?: string;
+    /** Multiplies every duration, hold, and beat length. 1 leaves bytes untouched. */
+    speed?: number;
+    narration?: DeckNarration;
+    /**
+     * What to do when one beat cannot be drawn.
+     *
+     * Absent, an emitter's error propagates and the build fails — right for a
+     * library caller and for every test, and what this did for months. It is the
+     * wrong answer for someone who uploaded a document: one beat the planner
+     * over-filled took a whole twelve-slide deck with it, at the last stage, after
+     * the planner had already been paid for.
+     *
+     * Dropped rather than repaired, deliberately. A missing slide is visibly
+     * missing; a slide silently shrunk to fit is a slide that lies about what the
+     * source said, and this project has spent a lot of its life on exactly that
+     * failure shape.
+     */
+    onBeatError?: (beatId: string, err: Error) => void;
+}
+/**
+ * Both artifacts from one layout pass.
+ *
+ * `composition` is the HyperFrames document — what `check`, `snapshot` and
+ * `render` consume. `page` is the navigable wrapper: it hosts the composition in
+ * a player, carries the same island, and inlines our step layer. Two files
+ * because they are genuinely two things — one is rendered, one is presented —
+ * and because HyperFrames' own navigation is dead at 0.7.71/0.7.72
+ * (EXPERIMENT-003), so the presented one has to be ours.
+ */
+export declare function emitDeck(storyboard: Storyboard, source: Source, format: Format, runtimeJs: string, opts?: DeckOptions): Deck;
+/**
+ * The beats this format actually draws, and why the rest are not there.
+ *
+ * TWO rules, and the second one is new here. The FLOOR — `format.minWeight`,
+ * raised for one invocation by `--min-weight` — is the author's own statement
+ * about what survives a shorter cut. The BUDGET is the format's: a `short-9x16`
+ * that runs four minutes is not a short, it is a tall video nobody can post
+ * (`DESTINATIONS` in src/types.ts). Until this call existed the budget could only
+ * be REPORTED, by `verify`, after the over-long deck had already been written, so
+ * one storyboard could not produce both a deck and a short without a human doing
+ * the arithmetic and feeding a threshold back in. `selectBeats` picks a better
+ * cut than a threshold can express — it protects the ends and one beat of every
+ * archetype family, and weighs length against weight — and every beat it drops
+ * arrives with a sentence saying why (src/plan/select.ts).
+ *
+ * WHY THIS MEASURES BEFORE IT SELECTS. A beat's real length is its NARRATED
+ * length, `beatSeconds` below, which is only known once the scene has been
+ * emitted and its holds are in hand. The measured scenes are then thrown away:
+ * a scene id is a position over the beats that SURVIVE (`s1`, `s2`, …) and every
+ * timeline selector is scoped by it (invariant 3), so a scene emitted before the
+ * cut is known carries ids for a deck that is not the one being built. Holds are
+ * times and do not depend on the id, which is what makes measuring with
+ * provisional ids exact rather than approximate.
+ *
+ * ONLY THE FLOOR'S SURVIVORS ARE MEASURED. Emitting a beat the floor has already
+ * dropped buys nothing and adds a way to fail: `emitScene` throws on a beat it
+ * cannot draw, and a beat nobody was ever going to draw must not be able to fail
+ * a build that never wanted it.
+ *
+ * AND THIS IS WHERE A BEAT THAT CANNOT BE DRAWN IS CAUGHT. It has to be: this is
+ * the FIRST place every surviving beat is emitted, so a `layout` that only caught
+ * the throw on its own second pass never saw one — `emitScene` is deterministic,
+ * so a beat that throws here throws identically there, and the deck died in the
+ * measuring pass with `onBeatError` never called. Dropping it here also keeps the
+ * returned `Cut` honest: a beat that is not in the deck is not in `kept`.
+ */
+export declare function planCut(storyboard: Storyboard, source: Source, format: Format, opts?: DeckOptions): Cut;
+/**
+ * How long the finished picture is held after the last word, before the cut.
+ *
+ * `HANDOFF_SECONDS`, deliberately: the outgoing scene's dissolve begins where its
+ * slide ends, so the settled frame gets exactly one handoff of stillness before
+ * it starts fading. Two scenes therefore have `SETTLE + open` between them — a
+ * breath, against the 1.86-3.44s of dead air measured on the deck this replaces.
+ */
+export declare const SETTLE_SECONDS = 0.4;
+/**
+ * When the voice may start inside a scene: as soon as the headline has landed.
+ *
+ * MEASURED off the scene rather than fixed, which is the whole point. The chrome
+ * is `#sid-e` at 0.15s over 0.5s and `#sid-h` at 0.3s over 0.6s, so it settles at
+ * 0.9s unpaced — but `pace` has already scaled the scene by the time this is
+ * asked, so at the 0.417 a 60-second target derives the same headline lands at
+ * 0.375s. A constant would have been right at one speed and wrong at every other,
+ * and starting the voice over a 46%-opacity headline is the failure it would have
+ * shipped.
+ *
+ * Falls back to the first hold when a scene draws no chrome, which is the same
+ * answer the deck gives today.
+ */
+export declare function openSeconds(scene: Scene): number;
+/**
+ * The scene as the deck actually contains it: paced, then filled.
+ *
+ * ONE function because three callers have to agree exactly — `planCut` measures
+ * with it, `layout` emits with it, and `holdsFor` in src/render/timing.ts builds
+ * the manifest with it. `assertHoldsAgree` cross-checks the last against the
+ * island the first two wrote, but ONLY on a navigable format; `video-16x9` and
+ * `short-9x16` carry no island, so on the artifact anybody actually watches a
+ * divergence between them is invisible. Sharing the code is the only thing that
+ * makes them the same answer.
+ */
+export declare function stageScene(scene: Scene, speed: number): {
+    scene: Scene;
+    open: number;
+};
+/**
+ * When each sentence of a beat is spoken, on one continuous clock.
+ *
+ * THE FIRST SENTENCE NEVER WAITS. It describes the beat arriving, the headline is
+ * already up by `open`, and making it wait for the first reveal is what put
+ * 0.65-1.52s of silence at the head of every scene — which ran straight into the
+ * tail of the one before it and became a 1.0-3.4s hole at every slide change.
+ *
+ * A LATER SENTENCE WAITS FOR THE REVEAL IT NAMES, and only when the clock has not
+ * already passed it. That is the whole synchronisation rule and it is one
+ * `Math.max`. When speech is dense — a short target, the case this was built for —
+ * the clock is always ahead, so the sentences run back to back with no gap at all.
+ * When the animation is deliberately slowed (`--speed 2`), the build outruns the
+ * voice and each sentence waits for its own reveal rather than describing a
+ * picture that is still seconds away. The gap that opens there is not dead air:
+ * it is the motion the author asked to be slow enough to watch.
+ *
+ * Shared by `beatSeconds` and `place` so the room RESERVED and the room USED are
+ * one piece of arithmetic rather than two statements of it that can drift apart.
+ */
+export declare function speechPlan(open: number, holds: readonly number[], segments: readonly Segment[]): {
+    starts: number[];
+    end: number;
+};
+export declare function emitComposition(storyboard: Storyboard, source: Source, format: Format, opts?: DeckOptions): string;
+/** Shipped beside the deck so a built artifact needs no network to navigate. */
+export declare const PLAYER_FILE = "hyperframes-player.global.js";
+/**
+ * The wrapper's filename, single-sourced because `verify` has to exclude it.
+ * It is a presented page, never a rendered one, so render-time rules — the
+ * determinism scan above all — do not apply to it.
+ */
+export declare const DECK_PAGE = "deck.html";
+export {};

package/dist/types/emit/island.d.ts

@@ -0,0 +1,19 @@
+/**
+ * The slideshow island — the deck's navigation map.
+ *
+ * Fragment times are ABSOLUTE positions on the deck timeline, not offsets into a
+ * slide, which is easy to get subtly wrong and produces a deck that lints clean
+ * and navigates to the wrong place. A fragment outside its slide's window fails
+ * `hyperframes lint`, so the conversion is checked here rather than at the gate.
+ */
+export interface SlideInput {
+    /** The scene's composition id, e.g. `"s3"`. */
+    sid: string;
+    start: number;
+    duration: number;
+    /** Presenter note, already plain text. */
+    notes: string;
+    /** Hold points in seconds from the scene's start. */
+    holds: number[];
+}
+export declare function emitIsland(slides: SlideInput[]): string;