@jokerized/decksmith 0.1.4 → 0.3.0

package/dist/types/emit/archetypes/annotated-figure.d.ts

@@ -24,6 +24,7 @@
 import type { Format } from "../../types.js";
 import type { Emitter } from "../kit.js";
 import type { Box, Pt } from "../svg.js";
+import { type Face } from "../svg.js";
 export interface FigureNote {
     x: number;
     y: number;
@@ -78,7 +79,7 @@ export interface FigureLayout {
 export declare function planFigure(stageW: number, notes: FigureNote[], fig: {
     width: number;
     height: number;
-}, stageH: number, tall?: boolean): FigureLayout;
+}, stageH: number, tall?: boolean, face?: Face): FigureLayout;
 /**
  * Height the stage may spend, once the chrome and the caption have taken theirs.
  * A budget, not a size — `planFigure` gives back only what it used.
@@ -99,5 +100,5 @@ export declare function planFigure(stageW: number, notes: FigureNote[], fig: {
  * that reports more room than exists does not create room; it only moves which
  * gate notices.
  */
-export declare function stageBudget(format: Format, eyebrow: string | undefined, headline: string, caption: string): number;
+export declare function stageBudget(format: Format, eyebrow: string | undefined, headline: string, caption: string, face?: Face): number;
 export declare const annotatedFigure: Emitter<"annotated-figure">;

package/dist/types/emit/archetypes/data-table.d.ts

@@ -1,21 +1,2 @@
-/**
- * A table from the source, revealed row by row, then read for the viewer: the
- * highlighted rows light up in the order the argument needs them.
- *
- * Nothing here invents numbers, and nothing here drops them either: every row of
- * the named table is drawn, at 40px or above, or the beat is refused. The type
- * is solved from the WIDTH — upwards from the 40px floor, capped — and the height
- * rule then asks whether those rows, drawn at that size, fit on the canvas. The
- * one lever the height rule owns is the row padding, and it is already shut to
- * `PAD_Y_MIN` whenever this refuses, so "will not fit" is a measurement of this
- * slide rather than a preference about it.
- *
- * WHAT IT DELIBERATELY DOES NOT DO: buy rows by taking the type back down toward
- * 40. That would be legal — invariant 5 is a floor, not a fixed size, and a table
- * declined here at 52px would often fit at 40 — but it makes `cell` solve two
- * constraints at once, and the width solve is the one that has been measured. So
- * the refusal names the size it refused AT, and the choice stays visible to
- * whoever reads the error instead of being buried in this file.
- */
 import type { Emitter } from "../kit.js";
 export declare const dataTable: Emitter<"data-table">;

package/dist/types/emit/archetypes/equation-morph.d.ts

@@ -0,0 +1,2 @@
+import type { Emitter } from "../kit.js";
+export declare const equationMorph: Emitter<"equation-morph">;

package/dist/types/emit/archetypes/equation-walk.d.ts

@@ -1,2 +1,64 @@
-import type { Emitter } from "../kit.js";
+/**
+ * An equation, walked one symbol at a time.
+ *
+ * This is the most valuable thing the vocabulary does: the reader is never shown
+ * a wall of TeX and left to find the symbol being discussed. Each term is wrapped
+ * in `\htmlClass{term t-<tone>}{...}` so KaTeX emits a real element for it, which
+ * GSAP then tints and swells in step with its legend row.
+ */
+import type { Term } from "../../types.js";
+import type { Emitter, Theme } from "../kit.js";
+export declare const OPTS = "{ displayMode: true, trust: function (c) { return c.command === \"\\\\htmlClass\"; }, strict: false, output: \"html\" }";
+export declare const INLINE_OPTS = "{ displayMode: false, trust: function (c) { return c.command === \"\\\\htmlClass\"; }, strict: false, output: \"html\" }";
+/** Where `term` sits in `tex`, comparing normal forms. Null when it is absent. */
+export declare function locate(tex: string, term: string): {
+    start: number;
+    end: number;
+} | null;
+/**
+ * Wrap each term where it first occurs, and report which ones were wrapped.
+ *
+ * Segments are tracked as raw/wrapped so a later term cannot match inside an
+ * earlier term's `\htmlClass{...}` and produce nested markup that highlights the
+ * wrong span.
+ *
+ * A term that cannot be found is DROPPED rather than thrown on, and the caller
+ * drops its legend row with it — the two go together, which is what keeps this
+ * honest. Silently highlighting nothing is the failure this archetype exists to
+ * avoid, and a legend line pointing at an unhighlighted symbol is that failure;
+ * a shorter legend is not. Losing an entire deck to one mis-spelled term is a
+ * worse answer than either. If NOTHING matches, the beat has no work to do and
+ * that is still an error.
+ */
+export declare function wrapTerms(tex: string, terms: Term[], beatId: string, 
+/** The class the wrapper carries; the morph adds its key to the walk's tint. */
+cls?: (t: Term) => string): {
+    tex: string;
+    used: Term[];
+    missing: Term[];
+};
+/**
+ * Display equations want to live between 68px and 108px.
+ *
+ * The equation is the whole argument of this archetype and it was the smallest
+ * thing on the slide — 72px of TeX centred in a 1700px box, measured at 46% fill
+ * with a 1920x316 band under it. It is sized off the source length rather than
+ * off `textWidth` because TeX is not the string that gets set: `\mathcal{W}(F)`
+ * is fourteen characters and three glyphs.
+ *
+ * This is the *wanted* size, not the final one. The old comment here claimed
+ * "KaTeX's own `\displaystyle` box will shrink to the container if the estimate
+ * runs wide". It does not — it overflows, silently, because the composition is
+ * the size it says it is and no gate reads past the canvas edge. At 9:16 that
+ * truncated `X = \mathcal{W}(F)` to "X =" and then left the legend explaining a
+ * symbol the viewer could not see, which is worse than a clip: the slide
+ * asserted something false. `statements` and the `size` cap below are what make
+ * the claim true.
+ */
+export declare function equationSize(tex: string): number;
+/** Estimated rendered width of a display, in ems. */
+export declare function texUnits(tex: string): number;
+/** One row per term: a chip KaTeX fills in `setup`, and the label. Shared with the morph. */
+export declare function legendRows(sid: string, terms: Term[], theme: Theme): string;
+export declare function legendCss(theme: Theme): string;
 export declare const equationWalk: Emitter<"equation-walk">;

package/dist/types/emit/archetypes/index.d.ts

@@ -12,7 +12,7 @@ export declare const emitters: {
 };
 /**
  * Dispatch a beat to its emitter. The cast is the one place the pairing is taken
- * on trust: `emitters[beat.archetype]` is a union of twelve emitters and TypeScript
+ * on trust: `emitters[beat.archetype]` is a union of thirteen emitters and TypeScript
  * will not narrow the key and the beat together. The table above already proves
  * every archetype has exactly one emitter of the right shape.
  */

package/dist/types/emit/archetypes/pipeline.d.ts

@@ -33,7 +33,7 @@
  */
 import type { BeatOf } from "../../types.js";
 import type { Emitter } from "../kit.js";
-import { type Track } from "../svg.js";
+import { type Face, type Track } from "../svg.js";
 type Stage = BeatOf<"pipeline">["params"]["stages"][number];
 type Loop = {
     from: number;
@@ -76,6 +76,6 @@ export interface PipeLayout {
  * archetype must never get wrong, and asserting it against numbers beats
  * asserting it against a rendered string.
  */
-export declare function pipeLayout(stageW: number, stages: readonly Stage[], loop?: Loop): PipeLayout;
+export declare function pipeLayout(stageW: number, stages: readonly Stage[], loop?: Loop, face?: Face): PipeLayout;
 export declare const pipeline: Emitter<"pipeline">;
 export {};

package/dist/types/emit/archetypes/stack.d.ts

@@ -23,8 +23,16 @@
  */
 import type { BeatOf, Format } from "../../types.js";
 import type { Emitter } from "../kit.js";
+import { type Face } from "../svg.js";
 type Params = BeatOf<"stack">["params"];
 export interface StackLayout {
+    /**
+     * The type floor this layout solved against, which is `MIN_FONT` for a flat
+     * beat and larger for a tilted one. The emitter reads it back so the notes it
+     * draws are set at the same floor the solver reserved room for — they were
+     * pinned to `MIN_FONT` directly, which under a tilt drew them below it.
+     */
+    floor: number;
     /**
      * False when the rise the canvas allows is shorter than the tallest label
      * block — i.e. adjacent labels would overlap. `stackLayout` re-composes rather
@@ -32,6 +40,17 @@ export interface StackLayout {
      * fitted and the caller is looking at the least-bad one.
      */
     fits: boolean;
+    /**
+     * Whether the label column is as wide as its content needs.
+     *
+     * `fits` is a HEIGHT test and was the only test: `colW` is clamped to
+     * `colCap`, so a column whose content wants more simply overflows, and an
+     * inline note is drawn with no `maxWidth` at all — one unwrapped line that
+     * runs off the slide. A Korean note did exactly that ("크기·대비·선택·자막·번역
+     * 검사" at the 40px floor), and the only thing that noticed was
+     * `container_overflow` at a hold, after a browser had laid the deck out.
+     */
+    wide: boolean;
     /** Notes set beside their label rather than beneath it. See `stackLayout`. */
     inline: boolean;
     /** The svg's own box. `width` is the full content column. */
@@ -88,6 +107,6 @@ export interface StackLayout {
  * composition changes rather than the type: the note moves beside its label, on
  * the same line, right-aligned against the spine.
  */
-export declare function stackLayout(p: Params, format: Format): StackLayout;
+export declare function stackLayout(p: Params, format: Format, face?: Face): StackLayout;
 export declare const stack: Emitter<"stack">;
 export {};

package/dist/types/emit/archetypes/title.d.ts

@@ -8,6 +8,7 @@
  */
 import type { Format } from "../../types.js";
 import type { Emitter, Theme, Tween, Vars } from "../kit.js";
+import { type Face } from "../svg.js";
 /**
  * Whether this format's content box is taller than it is wide.
  *
@@ -27,14 +28,30 @@ export declare function isPortrait(format: Format): boolean;
  *
  * These are exported because every archetype that draws a diagram has to know
  * how much room the chrome took before it can decide how big the diagram is. A
- * duplicated `const HEADLINE_H = 76` in five files is a type scale that can only
+ * duplicated `const HEADLINE_H = 64` in five files is a type scale that can only
  * ever be changed in one of them, and the other four then overflow or leave a
  * band — both silent.
  *
- * 76/42, not 66/40. The floor is 40 and most of the deck was sitting on it, so
- * the whole slide read as body text with one slightly larger line. Growing type
- * is the safe direction (invariant 5 is a minimum), and the budget arithmetic
- * below is what keeps the extra height from pushing a scene off both edges.
+ * 64/42/40, down from 76/42/44. The density pass that set 76 was answering a
+ * real complaint — at 66/40 the whole slide read as body text with one slightly
+ * larger line — but it overshot the measure. MEASURED at contentW 1700: a 76px
+ * headline line holds 45 characters, and the planner is asked for headlines
+ * longer than that, so TEN of `demo/storyboard.json`'s twelve wrapped to two
+ * lines and each spent 174px of a 912px box saying one sentence. At 64 the same
+ * line holds 53: three still wrap, seven stop, and a headline that stops hands
+ * 100px back to the body (174 -> 74) while one that still wraps hands back 26
+ * (174 -> 148). Across the demo that is 804px, 67 a beat — which is the space
+ * the owner said the deck was wasting.
+ *
+ * EYEBROW_SIZE STAYS AT 42. It is the one line that is already short by
+ * contract, so shrinking it buys ~10px and costs the only contrast the chrome
+ * has between its two lines.
+ *
+ * BODY_SIZE goes to 40, which IS the floor. That is deliberate and it is legal:
+ * `scanTypeFloor` compares `px < floorPx` (src/verify/typefloor.ts), so 40
+ * passes, and the demo already declares 40 in ten places. There is no room under
+ * this one — the next archetype that wants a body notch smaller has to take less
+ * text instead.
  */
 export declare const EYEBROW_SIZE = 42;
 export declare const EYEBROW_LH = 1.2;
@@ -52,11 +69,11 @@ export declare const EYEBROW_H: number;
  */
 export declare const EYEBROW_TRACKING = 0.14;
 export declare const HEADLINE_TRACKING = -0.015;
-export declare const HEADLINE_SIZE = 76;
+export declare const HEADLINE_SIZE = 64;
 export declare const HEADLINE_LH = 1.15;
 export declare const HEADLINE_H: number;
-/** Body copy — notes, captions, claims. One notch off the floor, deliberately. */
-export declare const BODY_SIZE = 44;
+/** Body copy — notes, captions, claims. ON the floor, deliberately: see above. */
+export declare const BODY_SIZE = 40;
 export declare const BODY_LH = 1.45;
 /**
  * Bind the tail of a headline so it cannot break to a one- or two-word last line.
@@ -87,7 +104,7 @@ export declare const BODY_LH = 1.45;
  * (nothing to borrow from), and one where every candidate is wider than the
  * measure — the browser would break that anyway, and then in mid-word.
  */
-export declare function unwidow(text: string, width: number, size: number, weight?: number): string;
+export declare function unwidow(text: string, width: number, size: number, weight?: number, face?: Face): string;
 /**
  * Height the chrome will actually occupy, headline wrapping included.
  *
@@ -95,7 +112,7 @@ export declare function unwidow(text: string, width: number, size: number, weigh
  * That is the safe direction: an under-count overflows the canvas, and `.scene`
  * is centred so it overflows off *both* edges at once.
  */
-export declare function chromeHeight(eyebrow: string | undefined, headline: string, width: number): number;
+export declare function chromeHeight(eyebrow: string | undefined, headline: string, width: number, face?: Face): number;
 /**
  * What is left for the body once the chrome, the body's own top margin, and
  * anything below it (a note, a caption band) have been paid for.
@@ -108,7 +125,7 @@ export declare function chromeHeight(eyebrow: string | undefined, headline: stri
  * is LAST in the queue for space has to be able to hear "there is almost none",
  * so it can pass its own floor and act on the answer.
  */
-export declare function bodyBudget(format: Format, eyebrow: string | undefined, headline: string, below?: number, top?: number, floor?: number): number;
+export declare function bodyBudget(format: Format, eyebrow: string | undefined, headline: string, below?: number, top?: number, floor?: number, face?: Face): number;
 /**
  * The largest size at which `text` sets in `width` lines of `maxLines`, capped
  * both ends. Used where a headline should grow to meet its box instead of
@@ -126,7 +143,7 @@ export declare function bodyBudget(format: Format, eyebrow: string | undefined,
  * a bisection's midpoint happened to skip. `lo` is a floor, not a target — a
  * string that will not set in `maxLines` at `lo` simply lands there, as before.
  */
-export declare function fitText(text: string, width: number, maxLines: number, lo: number, hi: number, weight?: number): number;
+export declare function fitText(text: string, width: number, maxLines: number, lo: number, hi: number, weight?: number, face?: Face): number;
 /**
  * The vocabulary's own constructor: a `fromTo` at a rounded position.
  *
@@ -164,7 +181,7 @@ export declare function holdsWithin(times: number[], seconds: number): number[];
  * site from a deliberate one, so the next archetype would inherit the same
  * silent opt-out; requiring it makes the omission a type error instead.
  */
-export declare function chrome(sid: string, eyebrow: string | undefined, headline: string, width: number): string;
+export declare function chrome(sid: string, eyebrow: string | undefined, headline: string, width: number, face?: Face): string;
 /** Reveals the chrome. Finishes at 0.9s, which is where archetype bodies pick up. */
 export declare function chromeIn(sid: string, eyebrow: boolean): Tween[];
 export declare function chromeCss(t: Theme): string;
@@ -184,5 +201,5 @@ export declare function noteWidth(format: Format): number;
  * measuring against the bare 1600 cap at 9:16 under-counts the lines by half and
  * hands the body a budget the note then overruns.
  */
-export declare function noteHeight(note: string | undefined, width: number, top?: number): number;
+export declare function noteHeight(note: string | undefined, width: number, top?: number, face?: Face): number;
 export declare const title: Emitter<"title">;

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

@@ -153,6 +153,31 @@ export declare function elementId(sid: string, element: string): string;
  * archetype that draws a thing with an id can be entered at it.
  */
 export declare function enterableIds(sid: string, html: string): string[];
+/**
+ * THE CAMERA HAZARD, checked. `inside.element` is an index, so naming the right
+ * kind of part and the wrong number is not a build error — `stage2` exists, it
+ * has a rect, and the deck dives smoothly into whatever happens to be third.
+ * That is this project's signature failure shape: correct-looking output that no
+ * gate can see is wrong. `inside.label` is what the plan says it is entering,
+ * `Scene.parts` is what the archetype drew, and this is the one place they meet.
+ *
+ * Returns the PREDICATE of a sentence whose subject is the containing beat, so
+ * that both callers can keep their own framing — the emitter says "this beat",
+ * `assertInsideResolves` names the beat and its archetype — over one comparison.
+ * Undefined means nothing to report.
+ *
+ * A plan that omits `label` is not checked: the field has to stay optional or
+ * the 130 committed references stop validating and every stored plan's sha256
+ * moves. A plan that SUPPLIES one for a part carrying no label is refused rather
+ * than skipped, because a check that silently does nothing is how the six
+ * green-gate failures in this repo all began — and by RULE 11 only a pipeline
+ * stage, a grid region and a stack layer are enterable anyway.
+ *
+ * The comparison is deliberately not exact and deliberately not fuzzy. Exact,
+ * and a re-typed or re-cased label fails a build over nothing; fuzzy — substring
+ * — and "Window" matches "window group", which occurs in this corpus.
+ */
+export declare function partLabelProblem(part: string, expected: string | undefined, parts: Readonly<Record<string, string>> | undefined): string | undefined;
 /**
  * The camera rig, wrapped around one scene's content.
  *

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

@@ -67,6 +67,24 @@ export interface DeckOptions {
      * failure shape.
      */
     onBeatError?: (beatId: string, err: Error) => void;
+    /**
+     * The subsetted bundle's `@font-face` CSS, INLINED rather than linked.
+     *
+     * The composition sets `font-family: "Noto Sans KR", …` for a CJK deck and
+     * used to declare the face in a `<link rel=stylesheet>`. Two things read the
+     * composition and neither follows that link: hyperframes' static guard, which
+     * reported "Font family used without @font-face declaration … text will fall
+     * back to a generic font, producing incorrect typography in the video" on
+     * every Korean deck this project has built; and the compiler, which inlines
+     * `<script src>` and not stylesheets — the same asymmetry the KaTeX note above
+     * records. A face the renderer cannot see is invariant 9 exactly: a font stack
+     * naming a family the bundle does not declare falls back silently.
+     *
+     * Passed in rather than read here because this function does no I/O. Absent,
+     * the link is emitted as before, so a caller that has no bundle is unchanged
+     * and every non-CJK deck is byte-identical either way.
+     */
+    fontCss?: string;
 }
 /**
  * Both artifacts from one layout pass.
@@ -75,8 +93,8 @@ export interface DeckOptions {
  * `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.
+ * and because HyperFrames' own navigation is dead at 0.7.71/0.7.72 and still
+ * dead at 0.8.27 as at 0.7.90 (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;
 /**

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

@@ -0,0 +1,95 @@
+/**
+ * Tilting a plane, and paying for it in type size.
+ *
+ * Gap 2 wants depth as exposition — a diagram tilting to reveal a layer. The
+ * expensive half is not the transform. It is that perspective shrinks the type on
+ * the far half of the plane, and invariant 5 is about what the AUDIENCE sees, so
+ * a tilt that leaves a 40px label drawing 31px has broken the floor whatever the
+ * source says. `src/verify/apparent.ts` is the gate that catches it; this module
+ * is how an archetype avoids tripping it, by declaring bigger type up front.
+ *
+ * WHAT IS AND IS NOT SUPPORTED HERE. One transform on one plane — the whole
+ * scene's content tilts as a unit. NOT per-element depth: measured in Chrome,
+ * `translateZ` on an SVG `<g>` under a `preserve-3d` ancestor is ignored
+ * completely (z=0, z=+200 and z=-200 paint the identical rect, while an HTML
+ * sibling in the same test moves and scales correctly). An exploding stack needs
+ * sibling HTML planes and is a later slice; a tilting plate is this one.
+ *
+ * THE MODEL. For a plane rotated by `t` about its horizontal centre line under
+ * CSS `perspective: d`, a point `dy` below the plane's centre is drawn at
+ *
+ *     scale(dy) = cos(t) * (d / (d - dy * sin(t)))^2
+ *
+ * — `cos(t)` for the foreshortening and the square for the perspective divide
+ * applying to both the glyph's height and its distance from the eye. Fitted
+ * against Chrome at `rotateX(30deg)`, `perspective: 1400px`:
+ *
+ *     dy = -340 (near the top)     model 0.6886   Chrome 0.6820   +0.97%
+ *     dy = +360 (near the bottom)  model 1.1404   Chrome 1.1260   +1.28%
+ *
+ * The model runs about 1% OPTIMISTIC, so `worstScale` rounds its answer down by
+ * 2% before anyone divides by it. Erring large costs a couple of type px; erring
+ * small ships a slide under the floor, which is the whole failure this exists to
+ * prevent.
+ */
+/** How a scene's plane is tilted. Degrees, and CSS `perspective` in px. */
+export interface Pose {
+    /** Rotation about the horizontal centre line. Positive tips the top away. */
+    rotateX: number;
+    /** CSS `perspective`, in reference px. Smaller is a stronger effect. */
+    perspective: number;
+}
+/**
+ * The default a depth archetype gets when it asks for one.
+ *
+ * 12 degrees, not the 30 the spike reached for. The table in `worstScale`'s note
+ * is why: at 30 degrees a 40px audience floor needs 67px declared, which is more
+ * than a headline can spend and still fit its own line. At 12 it needs 48.7px,
+ * which archetypes can and do pay. Depth here is a lean, not a dive.
+ */
+export declare const DEFAULT_POSE: Pose;
+/** Apparent scale at `dy` reference px below the plane's centre. */
+export declare function scaleAt(pose: Pose, dy: number): number;
+/**
+ * The smallest scale anywhere on a `height`-tall plane, already discounted.
+ *
+ * The smallest scale is at the TOP edge, furthest from the eye. The BOTTOM edge
+ * is the one that can swing through the eye entirely, and when it does the plane
+ * is not being tilted any more — it is being turned inside out — so the pose is
+ * refused rather than priced. Checking only the top would have returned a
+ * perfectly reasonable-looking floor for a pose that cannot be drawn.
+ *
+ * What it buys, at `perspective: 1400` on a 1080 canvas, AFTER the 2% discount:
+ *
+ *   rotateX(6)   0.901  ->  a 40px floor needs 44.4px declared
+ *   rotateX(12)  0.821  ->  48.7px
+ *   rotateX(18)  0.744  ->  53.8px
+ *   rotateX(24)  0.669  ->  59.8px
+ *   rotateX(30)  0.597  ->  67.0px
+ *
+ * That table is the tilt budget. Depth in this project is bounded by the type
+ * floor rather than by taste, and the bound is tighter than it looks.
+ */
+export declare function worstScale(pose: Pose, height: number): number;
+/**
+ * The type floor an archetype must solve against to LAND on `floor` once tilted.
+ *
+ * Archetypes already solve against a floor — `stack` passes `MIN_FONT` into its
+ * own fit — so depth costs them one substitution rather than a second solver.
+ */
+export declare function tiltedFloor(pose: Pose, height: number, floor: number): number;
+/**
+ * The CSS a tilted scene needs, scoped to its own id (invariant 3).
+ *
+ * `perspective` sits on the scene and the rotation on ONE part of it, named by
+ * `part`, because tilting a whole scene tilts its chrome too. Built that way
+ * first and it was obviously wrong the moment a frame was opened: the headline
+ * came out sheared, leaning like a mistake rather than a design, and the stack's
+ * probe marker — a straight rule with a dot under it — bent into a hook. The
+ * diagram is what gains by leaning; the words are what the audience reads.
+ *
+ * Nothing here animates: a pose is a static property of the beat, and a tilt that
+ * moved would put every label at a different apparent size on every frame while
+ * `apparent` only measures at the declared stops.
+ */
+export declare function depthCss(sid: string, pose: Pose, part: string): string;

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

@@ -185,6 +185,17 @@ export interface Tween {
     readonly at: number;
 }
 export declare function fromTo(target: string, from: Vars, to: Vars, at: number): Tween;
+/**
+ * Invariant 10 at the vocabulary's two places.
+ *
+ * Positions are sums of authored beat times and accumulate float tails —
+ * `7.199999999999999` — and a position that prints differently between two
+ * builds of one storyboard moves a byte in the composition. `title.ts`'s
+ * `tween()` rounds an archetype's positions this way; the verbs at the end of
+ * this file need the same rounding and cannot reach it, because `title.ts`
+ * imports this file and not the other way round.
+ */
+export declare function sec(n: number): number;
 /**
  * THE ONE PLACE A TWEEN BECOMES GSAP TEXT.
  *
@@ -198,6 +209,42 @@ export declare function tweenText(t: Tween): string;
 export interface Scene {
     /** The scene's inner HTML. The wrapper `<div class="scene clip">` is added by the shell. */
     html: string;
+    /**
+     * For each id suffix this scene drew that CARRIES A LABEL, the label it drew
+     * there: `{ stage0: "Encode", stage1: "Window" }`. Only the archetypes with
+     * enterable interiors populate it, and only for the parts a camera can be
+     * aimed at.
+     *
+     * WHY IT EXISTS. `inside.element` is an INDEX — `stage2` is the third thing in
+     * `params.stages` — so a reference that names the right kind of part and the
+     * wrong number resolves to a real id, measures a real rect and hands GSAP
+     * valid numbers. The deck renders a smooth, convincing dive into the wrong
+     * box, and `lint`, `check`, the type floor and `drift` are all green over it.
+     * `insideSchema.label` is what the plan thought it was entering; this is what
+     * the archetype actually drew, and the two are compared before the camera is
+     * built. `experiments/015-decision/runs-n32/menu-20/plan.json` is a committed
+     * plan where they disagree.
+     *
+     * WHY NOT AN ATTRIBUTE IN THE HTML, and why not a table in `withCamera`. A
+     * `data-` attribute would move the bytes of every built deck, which is the one
+     * thing the camera is not allowed to do (`renders byte-identical output when
+     * nothing is annotated`). A table in the shell is what `assertInsideResolves`
+     * already rejected in its own words — it would drift from the emitter. `Scene`
+     * is in-memory and never serialised, so this is archetype-sourced and costs
+     * zero emitted bytes.
+     *
+     * IF YOU ARE WRITING AN ARCHETYPE WITH AN ENTERABLE INTERIOR, RETURN THIS.
+     * Omitting it does not merely leave the new archetype unchecked — a supplied
+     * `label` over a part reporting none is a build ERROR, not a skip
+     * (`partLabelProblem` says why), so an archetype that populates the map and
+     * forgets it in the return object REFUSES ITS OWN CORRECT REFERENCES with
+     * "does not label ... It labels: nothing". `stack` shipped that way for the
+     * length of one review: the map was filled in the layer loop and dropped at
+     * the return, and because every test for this was written against `pipeline`,
+     * `tsc` and `biome` both saw a merely-unused local. Test the archetype you
+     * added, not the one that already worked.
+     */
+    parts?: Readonly<Record<string, string>>;
     /**
      * Tweens appended to this scene's own paused timeline, with times RELATIVE to
      * the scene's start. `Tween` is a `fromTo` by construction — `from()` records
@@ -238,6 +285,13 @@ export interface Scene {
      * values.
      */
     measure?: string[];
+    /**
+     * Vendored runtimes this scene's tweens need registered before its script
+     * runs — `"dsMorph"` for the equation morph. The shell loads a runtime only
+     * when some scene names it, so a deck that names none is byte-for-byte what
+     * it was.
+     */
+    plugins?: readonly string[];
     /**
      * Hold points in seconds from the scene's start — where a presenter should
      * pause. The shell converts these to absolute island fragment times.
@@ -254,3 +308,102 @@ export declare function mathy(raw: string): string;
 export declare const TEX_MARK = "ds-tex";
 /** Escape a string for embedding inside a single-quoted JS literal. */
 export declare function js(s: string): string;
+/**
+ * Where a dimmed element rests. Exactly this and never lower: the contrast
+ * gate and the type floor were both cleared with text at this opacity, and
+ * nothing here can express a darker one. The headline and the eyebrow are
+ * never dimmed at all — that is the archetype's promise, kept by never naming
+ * `-h` or `-e` to a spotlight.
+ */
+export declare const DIM = 0.62;
+/**
+ * How much bigger the part under discussion stands than its neighbours.
+ *
+ * UP, AND ONLY UP. The obvious way to say "this one matters" is to shrink the
+ * others, and it is the one way this project may not: `verify/typefloor.ts`
+ * reads DECLARED type sizes and says so in its own header — "text shrunk by a
+ * `scale` below 1 at a hold reads as its unscaled size" — so a 0.94 on a panel
+ * of 40px text draws 37.6px that the audience floor scores as 40. That is the
+ * exact shape of the failure this project keeps writing experiments about: a
+ * gate green over output that is wrong. Growing the focus has no such blind
+ * spot, and against neighbours already at `DIM` it reads the same.
+ *
+ * 3%, not 8%: the parts stand in gaps of their own — a pipeline's 120px, a
+ * callout's 44 — and a lift big enough to close one would be caught by
+ * `content_overlap`, which is not exempted here and should not be.
+ */
+export declare const LIFT = 1.03;
+/**
+ * A spotlight over one scene's parts. Built by `spotlighter`, which is the
+ * only constructor, because the thing being enforced is a HISTORY: which parts
+ * are at `DIM` right now, and which are lit.
+ *
+ * WHY STATEFUL. Two rules govern every dim: at most one immediate-render
+ * `fromTo` per (element, property), and a later tween's `from` equals the
+ * earlier tween's `to`. Break the first and a part shows at full opacity
+ * before its own reveal; break the second and a part already at 0.62 snaps to
+ * 1 and eases back down — a blink, at every gate green. Both are facts about
+ * what was emitted BEFORE, so a helper that takes a `first: false` flag from
+ * the caller is a helper that trusts the caller to remember. This one
+ * remembers.
+ *
+ * Every tween it emits carries `immediateRender: false`. The elements a
+ * spotlight touches enter through their own `opacity: 0 → 1` reveal, and that
+ * reveal is the one immediate render opacity gets; a second one would apply
+ * `opacity: 1` at build time, on top of the reveal's 0, and the part would be
+ * on screen from frame one. An element with no reveal is at 1 already, so
+ * withholding the immediate render costs it nothing.
+ *
+ * Two idioms, and one spotlighter is one or the other (mixing throws):
+ *
+ * - `lit(keep, at)` — the whole scope is on screen. The first call dims
+ *   everything in scope but `keep` (`#sid .term:not(#sid-t0)`); later calls
+ *   move the light: what was kept dims, what is newly kept comes back. For
+ *   terms, bars, rows, cells.
+ * - `dim(target, at)` — parts arrive one at a time and the light stays on the
+ *   newest, so only the part it just left dims. For stages, layers, panels,
+ *   notes. `target` is a part suffix or an exact `#sid…` selector.
+ *
+ * `restore(at)` brings everything dimmed back to 1 in one tween, at a scene's
+ * last hold. In `lit` mode that is the scope minus what is lit, so it assumes
+ * the whole scope is on screen by then — true at a last hold by construction.
+ */
+export interface Spotlight {
+    lit(keep: string | readonly string[], at: number): Tween[];
+    dim(target: string, at: number): Tween[];
+    restore(at: number): Tween[];
+}
+/**
+ * `scope` is a selector fragment inside the scene — `.term`, `.stage` — and is
+ * required by `lit()` only; `dim()` names its targets outright. Every selector
+ * this emits begins with `#sid` (`unscoped_gsap_selector`, invariant 3).
+ */
+export declare function spotlighter(sid: string, scope?: string): Spotlight;
+/**
+ * The part under discussion stands a little closer.
+ *
+ * A pair, always used as a pair: `lift` when the part arrives, `settle` when the
+ * next one takes over, so nothing is left standing proud at the beat's end. Both
+ * carry `immediateRender: false` and start from where the other left off,
+ * because an archetype's entrance usually owns this element's first `scale`
+ * render already (`pipeline` pops its boxes in) and a second immediate one would
+ * apply the end value at build time, over the entrance's start value.
+ *
+ * `svgOrigin` for an SVG part, named in BOTH halves or GSAP treats the second
+ * mention as an origin CHANGE and compensates it with a translate that never
+ * unwinds — the defect `grid` and `annotated-figure` each record in their own
+ * words.
+ */
+export declare function lift(target: string, at: number, seconds?: number, origin?: string): Tween;
+export declare function settle(target: string, at: number, seconds?: number, origin?: string): Tween;
+/**
+ * One `<span class="w">` per word, for a headline that rises word by word
+ * (`#sid-t .w`, staggered). Words are `esc()`ed one at a time and rejoined
+ * with single spaces, so the line sets exactly as the plain string did and
+ * the type floor sees the same size. No ids: the stagger addresses the class.
+ *
+ * The archetype's CSS must give the class `display: inline-block` — a
+ * transform on an inline box is a no-op, and the rise would render as a plain
+ * fade with every gate green.
+ */
+export declare function words(text: string, cls?: string): string;