@jokerized/decksmith 0.1.3 → 0.2.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/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,6 +23,7 @@
  */
 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 {
     /**
@@ -32,6 +33,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 +100,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/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
@@ -254,3 +301,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;

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

@@ -13,7 +13,7 @@
  * that composes these primitives, and putting it here is how a primitive layer
  * turns into six hand-rolled one-offs wearing a shared import.
  */
-import { type Vars } from "./kit.js";
+import { type Tween, type Vars } from "./kit.js";
 export interface Pt {
     x: number;
     y: number;
@@ -47,18 +47,54 @@ export declare function n(v: number): string;
  */
 export declare function nv(v: number): number;
 /**
- * The `from` vars of a stroke draw-on, with the path fully hidden.
+ * The `from` and `to` vars of a stroke draw-on, measured by the browser.
  *
- * The length is rounded UP rather than to two decimals, and then given a pixel
- * of slack, because GSAP writes `strokeDashoffset` back as an integer px: a
- * leader of length 720.21 came to rest at an offset of 720 and left 0.21px of
- * the dash exposed at the path start, which `stroke-linecap: round` paints as a
- * full-width dot. A yellow dot therefore sat on the grid one reveal before its
- * own region was drawn — inside the frame, above the type floor, and invisible
- * to every gate. Any offset between the length and twice it is still inside the
- * pattern's gap, so the slack costs nothing.
+ * The `drawFrom` this replaced needed the emitter to know the path's length at
+ * BUILD time —
+ * `Math.hypot(knee.x - start.x, knee.y - start.y) + b.w` in annotated-figure,
+ * `perimeter(b)` in grid — which is arithmetic about a shape the browser is
+ * going to measure anyway, kept in step by hand. DrawSVG asks the path.
+ *
+ * It also retires a bug the hand-computed version had. GSAP writes
+ * `strokeDashoffset` back as an integer px, so a leader of length 720.21 came to
+ * rest at an offset of 720 and left 0.21px of dash exposed at the path start,
+ * which `stroke-linecap: round` paints as a full-width dot: a yellow dot sat on
+ * the grid one reveal before its own region was drawn, inside the frame, above
+ * the type floor, and invisible to every gate. That is why the old `drawFrom`
+ * rounded up and added a pixel of slack. A percentage has no remainder to leave.
+ *
+ * Safe under capture because a plugin's `render()` is part of being seeked,
+ * unlike a callback — see `DRAWSVG_SRC` in composition.ts for the measurement.
+ * Anything drawn this way still obeys invariant 2: it is a `fromTo`, always.
+ */
+export declare const DRAW_FROM: Vars;
+export declare const DRAW_TO: Vars;
+/**
+ * Something travels a polyline — a pulse along an arrow, a marker ring along a
+ * curve, a highlight down a divider: one `x`/`y` `fromTo` per leg, each leg's
+ * share of `seconds` proportional to its length, `ease: "none"` until the last
+ * leg, which settles with `power2.out`. Only the first leg renders
+ * immediately; every later one is `immediateRender: false` and starts exactly
+ * where the leg before it ended, so the route reads as one motion under any
+ * seek. `x`/`y` are TRANSLATIONS, so author the traveller at the origin —
+ * `<circle r="6">` — and give the route in the same user space as the parts it
+ * passes. A transform rather than `attr: { cx, cy }` so one verb moves an SVG
+ * dot and an HTML rule alike; not MotionPath, which is not loaded.
+ *
+ * ONE CALL PER ELEMENT. The first leg's immediate render is the one that
+ * (element, x/y) gets; a second route on the same element would need
+ * `immediateRender: false` and a `from` equal to the first route's end, which
+ * is not where a second route starts. A pulse per arrow, not one pulse reused.
+ *
+ * Every leg starts where the last one ended, printed at two places, and lint
+ * reads `at + duration` back in floating point: 0.1 + 0.2 is 0.30000000000000004,
+ * which `overlapping_gsap_tweens` reports as a 4e-17s overlap with the leg at
+ * 0.3 (measured on 0.7.90). So a leg whose float sum overshoots its successor
+ * is shortened by a hundredth — a rest at the corner under one frame long —
+ * and the corner itself, and the arrival at `at + seconds`, stay where they
+ * were scheduled.
  */
-export declare function drawFrom(length: number): Vars;
+export declare function travel(target: string, route: readonly Pt[], at: number, seconds: number): Tween[];
 /** Scene-scoped element id. Every timeline selector is built from one of these. */
 export declare function id(sid: string, part: string, i?: number): string;
 /**
@@ -68,13 +104,36 @@ export declare function id(sid: string, part: string, i?: number): string;
  * Every archetype sizes its boxes and padding through this function. When two of
  * them disagree about how wide "Reconstruction" is, one of them clips.
  */
-export declare function textWidth(text: string, fontSize: number, weight?: number, tracking?: number, tabular?: boolean): number;
+/**
+ * Which face actually draws a run.
+ *
+ * A deck that bundles a CJK family sets EVERY run in it, ASCII included, because
+ * `fontStack` puts that family ahead of Inter and it covers Latin. So the face is
+ * a property of the DECK, not of the characters in one run — and a run of pure
+ * ASCII inside a Korean deck is drawn by the Korean face even though nothing in
+ * it is Korean.
+ *
+ * `"latin"` is not "no CJK in this string"; it is "this deck bundles no CJK
+ * family". Passing it for a run that does contain CJK would be a lie, which is
+ * why the auto-detection below still runs underneath: the parameter can only
+ * widen what a run is charged, never narrow it.
+ */
+export type Face = "latin" | "cjk" | "hangul";
+/**
+ * The face a theme's stack will use, from the family `familyFor` put in front.
+ *
+ * Korean is split out because it is the one character the four bundled families
+ * disagree about: KR draws the middle dot at 0.561em where JP, SC and TC draw it
+ * on the em grid at 1.0.
+ */
+export declare function faceOf(fontStack: string): Face;
+export declare function textWidth(text: string, fontSize: number, weight?: number, tracking?: number, tabular?: boolean, face?: Face): number;
 /**
  * Greedy word wrap to `maxWidth`. A word wider than the line is broken by
  * character — which is also how Korean and Chinese wrap, since they arrive as
  * one unbroken "word".
  */
-export declare function wrap(text: string, fontSize: number, maxWidth: number, weight?: number, tracking?: number): string[];
+export declare function wrap(text: string, fontSize: number, maxWidth: number, weight?: number, tracking?: number, face?: Face): string[];
 /** The SVG root. Width and height match the viewBox so px and user units agree. */
 export declare function svg(elementId: string, w: number, h: number, body: string): string;
 export declare function rect(b: Box, a?: Attrs): string;
@@ -100,6 +159,11 @@ export interface TextOptions {
     vAlign?: "baseline" | "middle";
     class?: string;
     id?: string;
+    /**
+     * The face the deck's stack will draw this in. Only consulted when `maxWidth`
+     * makes this text wrap — an unwrapped run is measured by nothing here.
+     */
+    face?: Face;
 }
 export declare function text(content: string, at: Pt, o: TextOptions): string;
 export interface ArrowOptions {

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

@@ -16,6 +16,7 @@ import { type Scene } from "./kit.js";
 import type { DeckTheme } from "./themes/index.js";
 export { type DeckTheme, ink, mono, paper, resolveTheme, THEME_NAMES, THEMES, } from "./themes/index.js";
 /** Where `ingest` writes the subsetted font bundle, relative to the deck. */
+export declare const FONT_BUNDLE_DIR = "assets/fonts";
 export declare const FONT_BUNDLE_HREF = "assets/fonts/fonts.css";
 /** A luminance breath. Safe on an element an entrance tween already moves. */
 export declare const BREATHE = "ds-breathe 6s ease-in-out infinite alternate";

package/dist/types/images/illustrate.d.ts

@@ -0,0 +1,34 @@
+import type { Prefs } from "../prefs.js";
+import { type Source, type Storyboard } from "../types.js";
+import { type ImageProvider } from "./providers.js";
+export interface IllustrateOpts {
+    prefs: Prefs;
+    /** `<dir of source.json>/assets`. Created if missing. */
+    assetsDir: string;
+    /** Tests inject; the default is `imageChain(prefs.images, resolveImageBackend())`. */
+    chain?: ImageProvider[];
+    /** Progress lines. Silent by default, for the reason `buildDeck` gives. */
+    onStep?: (message: string) => void;
+}
+export interface Illustrated {
+    beatId: string;
+    figureId: string;
+    /** Which rung drew it. */
+    provider: string;
+    /** The figure's `src`: a file name under `assetsDir`. */
+    src: string;
+    /** Found on disk from an earlier run; no provider was asked. */
+    cached: boolean;
+}
+/**
+ * Draw every pending brief. Always finishes: the tool rung is last and pure.
+ *
+ * Returns fresh objects parsed through the schemas; the ones passed in are not
+ * touched, so a caller that keeps the old storyboard around still holds the
+ * pending one.
+ */
+export declare function illustrate(storyboard: Storyboard, source: Source, opts: IllustrateOpts): Promise<{
+    storyboard: Storyboard;
+    source: Source;
+    illustrated: Illustrated[];
+}>;