@jokerized/decksmith 0.2.0 → 0.3.0

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

@@ -285,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.

package/dist/types/emit/morph-runtime.d.ts

@@ -0,0 +1,178 @@
+/**
+ * The keyed equation morph — TransformMatchingTex, for the DOM.
+ *
+ * Two KaTeX renderings in, one seek-evaluable plan out. `build()` runs once in
+ * the browser, inside the ready gate (Seam B), and bakes every number; the
+ * plan is then driven by a GSAP PLUGIN — `render(ratio)` is part of being
+ * seeked, so it fires under `suppressEvents` where an `onUpdate` would not
+ * (invariant 11). Nothing here runs on a callback.
+ *
+ * Four phases, kept separate on purpose:
+ *   1. LIFT   — pull every ink-bearing leaf out of KaTeX's nested boxes into a
+ *               flat absolutely-positioned overlay. Removes clipping, vlist
+ *               stacking and transform-on-inline entirely.
+ *   2. GROUP  — collect leaves into the units that move as one body. An author
+ *               key makes a group; an unkeyed leaf is its own group.
+ *   3. MATCH  — decide which group of A becomes which group of B.
+ *   4. PLAN   — a similarity transform per group, as per-leaf segments.
+ *
+ * `evaluate()` turns a plan and a progress into styles. It is a pure function
+ * of its arguments — two seeks to one time write the same strings — which is
+ * what makes the render byte-identical across browser processes, measured on
+ * the spike this is ported from (`experiments/013-vocabulary/morph/`).
+ *
+ * Bundled to an IIFE by `scripts/build.mjs`, vendored beside GSAP by the CLI,
+ * and loaded only by a deck that has a morph in it. The pure halves — `group`,
+ * `match`, `plan`, `evaluate` — are exported for the tests, which is why the
+ * window registration at the bottom is guarded.
+ */
+/** The class prefix an author key is carried on: `\htmlClass{ds-k-<key>}{...}`. */
+export declare const KEY_PREFIX = "ds-k-";
+export interface Leaf {
+    el: HTMLElement;
+    key: string;
+    sig: string;
+    text: string;
+    /** Font size in layout px. */
+    fs: number;
+    /** Centre and box, in the host's own layout px. */
+    cx: number;
+    cy: number;
+    w: number;
+    h: number;
+}
+export interface Group {
+    ident: string;
+    key: string;
+    leaves: Leaf[];
+    cx: number;
+    cy: number;
+    w: number;
+    h: number;
+    fs: number;
+    text: string;
+}
+/**
+ * The unit that moves as one body.
+ *
+ * This is the whole quality argument of the file. Matching GLYPH BY GLYPH is
+ * what a naive reading of TransformMatchingTex suggests and it is visibly
+ * wrong: in `a^2+b^2=c^2 -> c^2-b^2=a^2` the three `2`s are interchangeable
+ * under any text-plus-class identity, so they pair left-to-right and stay put
+ * while their bases cross over. The audience sees the letters swap and the
+ * exponents refuse to follow, which asserts something false about the algebra.
+ *
+ * Manim does not avoid this by being cleverer — `MathTex("a^2", "+", "b^2",
+ * ...)` is the AUTHOR splitting the expression into the parts meant to
+ * survive. `\htmlClass{ds-k-<key>}{...}` is the same act, and it is the only
+ * mechanism here that produces a correct morph on an ambiguous pair.
+ *
+ * A group's identity is its key alone, not its contents, so `ds-k-exp` can
+ * carry `x^2` onto `x^3`: the body moves and its contents dissolve.
+ */
+export declare function group(items: Leaf[]): Group[];
+export interface Match {
+    pairs: [number, number][];
+    dropA: number[];
+    addB: number[];
+}
+/**
+ * Bucket by identity, then pair NEAREST FIRST within a bucket.
+ *
+ * Document order — the spike's rule — sends the wrong twin across the slide:
+ * `F = E(I), X = W(F)` has two `=` and its successor one, and pairing the
+ * first `=` with it flew a glyph 800px over the equation while the `=` sitting
+ * 40px from its destination faded out. Nearest-first is what a viewer expects
+ * of a symbol that did not move. Ties fall to document order, so it is still a
+ * pure function of the two layouts.
+ */
+export declare function match(A: Group[], B: Group[]): Match;
+export type Prop = "x" | "y" | "s" | "o";
+export type Ease = "none" | "power1.in" | "power1.out" | "power2.in" | "power2.out" | "power2.inOut";
+/**
+ * One property of one leaf, over one slice of the morph.
+ *
+ * Times are FRACTIONS of the morph, not seconds: the plan is evaluated against
+ * the plugin tween's ratio, so `pace()` scaling the tween's `duration` scales
+ * all of this with it, and the plan never has to know how long it takes.
+ */
+export interface Step {
+    el: HTMLElement;
+    prop: Prop;
+    from: number;
+    to: number;
+    at: number;
+    dur: number;
+    ease: Ease;
+}
+/**
+ * One similarity transform per matched group, expressed per leaf.
+ *
+ * A group's leaves move RIGIDLY: every leaf gets the same scale and the
+ * translation that the group's own centre-to-centre move implies for its
+ * position within the body. `a^2` therefore arrives with its exponent still
+ * attached, which is the whole reason groups exist.
+ *
+ * The B side is placed by the INVERSE transform — B's leaves start where they
+ * would sit inside A's box — so when the contents differ the two renderings
+ * dissolve into each other while sharing one trajectory.
+ *
+ * `arc` bows the path. Two glyphs swapping ends of an equation travel the same
+ * straight line in opposite directions and pile up in the middle, which reads
+ * as a collision rather than an exchange. The bow is two segments on `y` — out
+ * over the first half, back over the second — against one on `x` that runs
+ * the whole way.
+ */
+export declare function plan(A: Group[], B: Group[], m: Match, opt: {
+    arc?: boolean;
+}): Step[];
+export interface MorphPlan {
+    leaves: {
+        el: HTMLElement;
+        side: "a" | "b";
+    }[];
+    steps: Step[];
+}
+/**
+ * Write the morph at progress `v` in [0, 1] into every leaf's style.
+ *
+ * Every leaf is written every time, from its resting state forward — A drawn,
+ * B hidden, nothing moved — so a cold seek to any progress produces the same
+ * strings as a walk to it. That is the property the capture depends on.
+ */
+export declare function evaluate(p: MorphPlan, v: number): void;
+export interface Stats {
+    groupsA: number;
+    groupsB: number;
+    leavesA: number;
+    leavesB: number;
+    matched: number;
+    dropped: number;
+    added: number;
+}
+/**
+ * Build the morph inside `host`, which must already contain two rendered KaTeX
+ * roots marked `data-morph="a"` and `data-morph="b"`. Runs in `measure`, after
+ * fonts; the plan is kept for the plugin tween on the same host to find.
+ */
+export declare function build(host: HTMLElement, opt?: {
+    arc?: boolean;
+}): Stats;
+interface PluginState {
+    plan: MorphPlan;
+    end: number;
+}
+/**
+ * `dsMorph` as a GSAP property: `tl.fromTo(host, { dsMorph: 0 }, { dsMorph: 1 })`.
+ *
+ * A plugin's `render` is called by the timeline as part of being seeked, so
+ * this runs under `suppressEvents` — the capture path — where an `onUpdate`
+ * does not. The tween's own ease must be "none": the plan carries its eases
+ * per segment, and a second ease on top would warp every one of them.
+ */
+export declare const DSMorphPlugin: {
+    name: string;
+    init(this: PluginState, target: Element, value: unknown): void;
+    render(ratio: number, d: PluginState): void;
+};
+export {};

package/dist/types/types.d.ts

@@ -140,6 +140,30 @@ export declare const equationWalkParamsSchema: z.ZodObject<{
         }>;
     }, z.core.$strip>>;
 }, z.core.$strip>;
+/**
+ * Two equations from the source, the first becoming the second.
+ *
+ * `terms` are the parts that TRAVEL: each must occur in both equations, and is
+ * carried from its place in the first to its place in the second as one rigid
+ * body. Everything else dissolves. Which terms are keyed IS the animation —
+ * the same two strings are a glyph riot unkeyed and an exchange keyed.
+ */
+export declare const equationMorphParamsSchema: z.ZodObject<{
+    eyebrow: z.ZodOptional<z.ZodString>;
+    headline: z.ZodString;
+    fromId: z.ZodString;
+    toId: z.ZodString;
+    terms: z.ZodArray<z.ZodObject<{
+        tex: z.ZodString;
+        label: z.ZodString;
+        tone: z.ZodEnum<{
+            a: "a";
+            b: "b";
+            c: "c";
+            d: "d";
+        }>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
 export declare const dataTableParamsSchema: z.ZodObject<{
     eyebrow: z.ZodOptional<z.ZodString>;
     headline: z.ZodString;
@@ -274,6 +298,7 @@ export declare const stackParamsSchema: z.ZodObject<{
         note: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>;
     note: z.ZodOptional<z.ZodString>;
+    tilt: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strip>;
 export declare const splitCompareParamsSchema: z.ZodObject<{
     eyebrow: z.ZodOptional<z.ZodString>;
@@ -423,6 +448,44 @@ export declare const beatSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     }, z.core.$strip>>>;
     weight: z.ZodDefault<z.ZodNumber>;
     seconds: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strip>, z.ZodObject<{
+    narration: z.ZodOptional<z.ZodString>;
+    archetype: z.ZodLiteral<"equation-morph">;
+    params: z.ZodObject<{
+        eyebrow: z.ZodOptional<z.ZodString>;
+        headline: z.ZodString;
+        fromId: z.ZodString;
+        toId: z.ZodString;
+        terms: z.ZodArray<z.ZodObject<{
+            tex: z.ZodString;
+            label: z.ZodString;
+            tone: z.ZodEnum<{
+                a: "a";
+                b: "b";
+                c: "c";
+                d: "d";
+            }>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>;
+    id: z.ZodString;
+    intent: z.ZodString;
+    inside: z.ZodOptional<z.ZodObject<{
+        beat: z.ZodString;
+        element: z.ZodString;
+        label: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    claim: z.ZodOptional<z.ZodString>;
+    evidence: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        kind: z.ZodEnum<{
+            figure: "figure";
+            equation: "equation";
+            table: "table";
+            section: "section";
+        }>;
+        id: z.ZodString;
+    }, z.core.$strip>>>;
+    weight: z.ZodDefault<z.ZodNumber>;
+    seconds: z.ZodDefault<z.ZodNumber>;
 }, z.core.$strip>, z.ZodObject<{
     narration: z.ZodOptional<z.ZodString>;
     archetype: z.ZodLiteral<"data-table">;
@@ -703,6 +766,7 @@ export declare const beatSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
             note: z.ZodOptional<z.ZodString>;
         }, z.core.$strip>>;
         note: z.ZodOptional<z.ZodString>;
+        tilt: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strip>;
     id: z.ZodString;
     intent: z.ZodString;
@@ -905,6 +969,44 @@ export declare const storyboardSchema: z.ZodObject<{
         }, z.core.$strip>>>;
         weight: z.ZodDefault<z.ZodNumber>;
         seconds: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strip>, z.ZodObject<{
+        narration: z.ZodOptional<z.ZodString>;
+        archetype: z.ZodLiteral<"equation-morph">;
+        params: z.ZodObject<{
+            eyebrow: z.ZodOptional<z.ZodString>;
+            headline: z.ZodString;
+            fromId: z.ZodString;
+            toId: z.ZodString;
+            terms: z.ZodArray<z.ZodObject<{
+                tex: z.ZodString;
+                label: z.ZodString;
+                tone: z.ZodEnum<{
+                    a: "a";
+                    b: "b";
+                    c: "c";
+                    d: "d";
+                }>;
+            }, z.core.$strip>>;
+        }, z.core.$strip>;
+        id: z.ZodString;
+        intent: z.ZodString;
+        inside: z.ZodOptional<z.ZodObject<{
+            beat: z.ZodString;
+            element: z.ZodString;
+            label: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+        claim: z.ZodOptional<z.ZodString>;
+        evidence: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            kind: z.ZodEnum<{
+                figure: "figure";
+                equation: "equation";
+                table: "table";
+                section: "section";
+            }>;
+            id: z.ZodString;
+        }, z.core.$strip>>>;
+        weight: z.ZodDefault<z.ZodNumber>;
+        seconds: z.ZodDefault<z.ZodNumber>;
     }, z.core.$strip>, z.ZodObject<{
         narration: z.ZodOptional<z.ZodString>;
         archetype: z.ZodLiteral<"data-table">;
@@ -1185,6 +1287,7 @@ export declare const storyboardSchema: z.ZodObject<{
                 note: z.ZodOptional<z.ZodString>;
             }, z.core.$strip>>;
             note: z.ZodOptional<z.ZodString>;
+            tilt: z.ZodOptional<z.ZodNumber>;
         }, z.core.$strip>;
         id: z.ZodString;
         intent: z.ZodString;
@@ -1546,6 +1649,44 @@ export declare const packSchema: z.ZodObject<{
             }, z.core.$strip>>>;
             weight: z.ZodDefault<z.ZodNumber>;
             seconds: z.ZodDefault<z.ZodNumber>;
+        }, z.core.$strip>, z.ZodObject<{
+            narration: z.ZodOptional<z.ZodString>;
+            archetype: z.ZodLiteral<"equation-morph">;
+            params: z.ZodObject<{
+                eyebrow: z.ZodOptional<z.ZodString>;
+                headline: z.ZodString;
+                fromId: z.ZodString;
+                toId: z.ZodString;
+                terms: z.ZodArray<z.ZodObject<{
+                    tex: z.ZodString;
+                    label: z.ZodString;
+                    tone: z.ZodEnum<{
+                        a: "a";
+                        b: "b";
+                        c: "c";
+                        d: "d";
+                    }>;
+                }, z.core.$strip>>;
+            }, z.core.$strip>;
+            id: z.ZodString;
+            intent: z.ZodString;
+            inside: z.ZodOptional<z.ZodObject<{
+                beat: z.ZodString;
+                element: z.ZodString;
+                label: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>>;
+            claim: z.ZodOptional<z.ZodString>;
+            evidence: z.ZodDefault<z.ZodArray<z.ZodObject<{
+                kind: z.ZodEnum<{
+                    figure: "figure";
+                    equation: "equation";
+                    table: "table";
+                    section: "section";
+                }>;
+                id: z.ZodString;
+            }, z.core.$strip>>>;
+            weight: z.ZodDefault<z.ZodNumber>;
+            seconds: z.ZodDefault<z.ZodNumber>;
         }, z.core.$strip>, z.ZodObject<{
             narration: z.ZodOptional<z.ZodString>;
             archetype: z.ZodLiteral<"data-table">;
@@ -1826,6 +1967,7 @@ export declare const packSchema: z.ZodObject<{
                     note: z.ZodOptional<z.ZodString>;
                 }, z.core.$strip>>;
                 note: z.ZodOptional<z.ZodString>;
+                tilt: z.ZodOptional<z.ZodNumber>;
             }, z.core.$strip>;
             id: z.ZodString;
             intent: z.ZodString;

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

@@ -0,0 +1,123 @@
+/**
+ * The type floor, measured on the rendered frame instead of read off the source.
+ *
+ * `typefloor.ts` scans declared sizes and says so plainly in its own header:
+ * "text shrunk by a `scale` below 1 at a hold reads as its unscaled size". That
+ * hole is not hypothetical and it is not only about `scale`. Measured in Chrome
+ * at `rotateX(30deg)` under `perspective: 1400px`, a run declaring 46px renders
+ * 31.4 apparent px near the top of the plane — invariant 5 broken by 8.6px, with
+ * `lint`, `check`, `drift` and the declared-size scan all green, because not one
+ * of them looks at how big the glyph actually came out.
+ *
+ * That matters now because Gap 2 wants depth, and every way of tilting a plane
+ * shrinks the type on the far half of it. A depth archetype built against a floor
+ * that cannot see projection would ship unreadable slides that pass. So the gate
+ * comes first and the archetype second.
+ *
+ * HOW APPARENT SIZE IS MEASURED. For an SVG text node, `getBBox()` is the
+ * untransformed box in user units and `getClientRects()` is the painted box in
+ * device px, so their ratio is the TOTAL scale between the two — the element's
+ * own transform, every ancestor transform, the 3D projection's per-point
+ * perspective divide, and the stage zoom, all of it, without having to know which
+ * of them applied. Measured against the three cases that matter:
+ *
+ *   flat, declared 46           ratio 1.000  ->  46.0 apparent px
+ *   tilted 30deg, near plane top  0.682  ->  31.4
+ *   tilted 30deg, near plane bottom 1.126  ->  51.8   (magnified, not a fault)
+ *   `scale(0.6)` at a hold        0.600  ->  27.6
+ *
+ * `getScreenCTM()` was tried first and rejected: it returns 0.673 for BOTH the
+ * top and bottom runs above, because it carries the affine part and drops the
+ * perspective divide that makes those two differ by 23 apparent px.
+ *
+ * WHY IT DIVIDES BY THE STAGE. A deck legitimately scales its whole stage —
+ * `zoomOf`/`REF_PULL` — and in portrait 40 reference px is SUPPOSED to land at 30
+ * canvas px, which `typefloor.ts` calls "the whole argument of REF_PULL and not a
+ * violation". Dividing the run's own ratio by the scene's gives apparent size
+ * back in REFERENCE px, so this gate agrees with the declared one on every deck
+ * that does nothing clever, and only diverges where something shrank one element
+ * relative to its own scene.
+ */
+import type { Finding } from "../types.js";
+/** One text run, as the frame actually drew it. */
+export interface ApparentRun {
+    /** First 40 characters, for the message. */
+    text: string;
+    /** `font-size` as declared, in px. */
+    declared: number;
+    /** Painted height over untransformed height, including the stage's own zoom. */
+    ratio: number;
+    /** Its own computed opacity, multiplied down the ancestors that carry one. */
+    opacity: number;
+}
+/** What `measureApparent` hands back for one instant. */
+export interface ApparentStop {
+    sid: string;
+    t: number;
+    runs: ApparentRun[];
+    /** The scene's own painted-over-declared scale, the baseline runs divide by. */
+    stage: number;
+    /**
+     * True at a declared stop, where the frame has arrived and everything drawn is
+     * being read. False at a sampled midpoint, where a run may be part-way through
+     * its own entrance — see `SETTLED_OPACITY`.
+     */
+    settled: boolean;
+}
+/**
+ * Serialised into the page: every visible SVG text run's apparent scale.
+ *
+ * Deliberately the same walk as `collectSvgTextRuns` in overprint.ts — same
+ * visibility rules, same "only inside an `<svg>`" restriction — because two gates
+ * that disagree about which text exists are two gates that cannot be reconciled
+ * when they disagree about a deck.
+ */
+export declare function collectApparent(sid: string): {
+    runs: ApparentRun[];
+    stage: number;
+};
+/**
+ * Apparent size in reference px: what the run declared, times how much the frame
+ * shrank or grew it relative to its own scene.
+ */
+export declare function apparentPx(run: ApparentRun, stage: number): number;
+/**
+ * How opaque a run must be, at a sampled midpoint, to count as text being read.
+ *
+ * At a declared stop the frame has arrived and everything drawn counts. Between
+ * stops it has not: `annotated-figure` enters its labels from `scale: 0.97`, so
+ * a run caught half way through its own entrance is BOTH under the floor and
+ * fading in, and failing a build for it would be crying wolf about a frame no
+ * one reads. A run at 0.95 opacity is not entering any more; it has arrived.
+ */
+export declare const SETTLED_OPACITY = 0.95;
+/**
+ * The times to sample BETWEEN the declared stops.
+ *
+ * `fidelity` measures at stops because that is where a frame has settled, and
+ * the apparent floor inherited that — which left exactly the hole it was built
+ * to close, one interval over: text scaled DOWN between two stops is invisible
+ * to a gate that only looks at the stops. A camera pulling back, or an exit that
+ * shrinks a label, would ship.
+ *
+ * Midway between consecutive stops of the SAME scene. Not across a scene
+ * boundary, where the midpoint lands in a cross-fade between two compositions
+ * and belongs to neither. Costs a seek and a DOM read each — no screenshot,
+ * which is what makes doubling the sample count affordable.
+ */
+export declare function midpoints(stops: readonly {
+    sid: string;
+    t: number;
+}[]): {
+    sid: string;
+    t: number;
+}[];
+/**
+ * Runs the frame drew below the floor, whatever shrank them.
+ *
+ * An ERROR, not a warning, and for the same reason `typefloor` is: text the
+ * audience cannot read is not a matter of degree. The tolerance is a tenth of a
+ * pixel, which is rasteriser noise rather than a grace margin — a deck that wants
+ * 40px declares 40px and measures 40.0, as the flat control does exactly.
+ */
+export declare function gradeApparent(stops: readonly ApparentStop[], floor?: number): Finding[];

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

@@ -28,7 +28,9 @@
  *
  * WHAT IT DOES NOT SEE, stated because a gate that overclaims is the thing this
  * file was written to stop. It reads declared sizes, so text shrunk by a
- * `scale` below 1 at a hold reads as its unscaled size; and it says nothing about
+ * `scale` below 1 at a hold reads as its unscaled size — `apparent.ts` is the
+ * gate that closes exactly that, by measuring the painted glyph instead, and it
+ * catches a 3D projection the same way; and it says nothing about
  * whether the text FITS — `container_overflow` and `text_occluded` in
  * `hyperframes check` are the gates for that, and `check.ts` already grades them
  * up to errors.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jokerized/decksmith",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Turn a source document into an animated explanation deck.",
   "type": "module",
   "license": "MIT",