@jokerized/decksmith 0.1.4 → 0.3.0

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/index.d.ts

@@ -1,4 +1,5 @@
-import { type Beat, type Finding, type Storyboard, type Verdict } from "../types.js";
+import type { Prefs } from "../prefs.js";
+import { type Beat, type Finding, type Source, type Storyboard, type Verdict } from "../types.js";
 import { type CheckOptions } from "./check.js";
 /**
  * The duration budget reads the built composition, so it needs no argument the
@@ -52,9 +53,10 @@ export interface VerifyOptions extends CheckOptions {
  * the beat-level gates as well. `kept` — the cut `build` emitted — is optional
  * for the same reason, and for a second one: without it the budget gate falls
  * back to the flat threshold, which is the right list only while the budget has
- * cut nothing.
+ * cut nothing. `source` is optional on the same terms: it is what makes the
+ * unused-figure advisory possible, and a built directory does not carry it.
  */
-export declare function verify(dir: string, opts?: VerifyOptions, storyboard?: Storyboard, kept?: readonly Beat[]): Promise<Verdict>;
+export declare function verify(dir: string, opts?: VerifyOptions, storyboard?: Storyboard, kept?: readonly Beat[], source?: Source): Promise<Verdict>;
 /**
  * Every mp3 the narration island promises is actually in the deck.
  *
@@ -144,6 +146,102 @@ export declare function scanHeadlines(storyboard: Storyboard): Finding[];
  * into two holds of one beat is a rewrite only the author can perform.
  */
 export declare function scanRepeatedObject(storyboard: Storyboard): Finding[];
+/**
+ * Warn when the source carries a figure the deck never cites.
+ *
+ * NOTHING ELSE LOOKS IN THIS DIRECTION. `assertRefsResolve` checks the other one
+ * — that every id a beat writes exists in the source — so a plan that ignores
+ * the figures entirely satisfies it perfectly. Measured on the shipped demo: two
+ * of four figures cited, one of the two left out being the paper's own
+ * architecture figure, while a beat redrew that architecture as a synthetic
+ * pipeline. Every gate was green, and the owner found it by watching the video.
+ *
+ * A WARNING, NEVER AN ERROR. A source may honestly hold a figure this deck does
+ * not need — a decorative header, a figure about related work, a plot the deck
+ * replaces with bars of its own. What is wrong is not using none of them; it is
+ * not having decided.
+ *
+ * Cited counts BOTH ways a beat can be accountable to a figure: `evidence`, and
+ * the params that actually put it on screen. A beat that shows a figure without
+ * citing it in evidence is a different defect, and not this scan's to report.
+ */
+export declare function scanUnusedFigures(storyboard: Storyboard, source: Source): Finding[];
+/**
+ * Warn when the plan came back with fewer beats than were asked for.
+ *
+ * `--slides` IS A FLOOR ON THE REQUEST, NOT ON THE ARTIFACT, and this is the half
+ * that MEASURES it. It has no teeth, and none are available — the door is closed
+ * three ways, so do not reopen it. Truncating to the count that came back throws
+ * away slides the author asked for. Padding to reach the number is what RULE 9
+ * forbids, and `scanRepeatedObject` above only fires on the same object drawn
+ * twice with the SAME archetype over identical part labels, so padding induced by
+ * a gate would mostly be invisible to the one scan that looks for it. Re-asking is
+ * a fresh multi-minute `codex exec` whose only possible second instruction is
+ * "return more" — a padding request with extra steps — and whose answer could only
+ * be preferred over the first by counting it.
+ *
+ * THE COUNT IS NOT DETERMINISTIC — which is a weaker argument than it first looks,
+ * and is written out here so the next reader does not have to re-derive that.
+ * Under ONE fixed configuration, the same command over the same source returned
+ * 9, 10 and 8 beats on three independent runs (the "rate + prompt floor" row of
+ * the table in .planning/HANDOFF-DURATION-CONTROL.md). So the number a gate would
+ * test is partly a draw rather than a property of the source. But all three of
+ * those are short of twelve, and NO configuration on record has produced both a
+ * twelve and a short count: the 12-beat run in the same table is a different
+ * prompt and a different character budget. So this is not evidence that a gate
+ * would flap between pass and fail on identical input — it would have failed all
+ * three of those runs alike. It is a reason to distrust the number, not a fourth
+ * reason the door is closed. The three above are that, and they stand on their
+ * own.
+ *
+ * The other half is the prompt's LENGTH block, which now says so in words — and
+ * words are not enough here for the reason `scanHeadlines` records two functions
+ * up: a real Codex run answered a sharpened RULE 8 by swapping one verb. Four of
+ * the last five plans came back short of their target (8, 9, 9 and 10 against 12)
+ * against a prompt that already asked for the number. Whether a source "genuinely
+ * will not carry twelve points" is a judgement the writer makes about their own
+ * output, so it can always be met cosmetically. A COUNT is not a judgement, which
+ * is what makes it worth MEASURING here — and measuring is the whole of what this
+ * is.
+ *
+ * THE FLOOR THE OWNER ASKED FOR IS ALREADY HELD, and it is a different floor: he
+ * asked that a short duration not be paid for in slides — a 12-slide deck under a
+ * minute, "keeping all twelve". That one holds structurally now. `slidesFor` is a
+ * DEFAULT that an explicit `--slides` overrides rather than the reverse (see
+ * `loadPrefs`), `durationPlan` raises the speaking rate before it says less, and
+ * the advisory that used to answer sixty seconds with "use nine slides" no longer
+ * fires there at all — under `FF_BEAT_SECONDS` the rate is what moves, and where
+ * it still fires it names keeping every slide beside the smaller count. A floor
+ * against the PLANNER'S judgement is a different object, and it is the one that
+ * cannot be built. What is held in its place is honesty about it: the budget is
+ * struck at the count that came back, the gap is priced in the numbers that moved,
+ * and `pack` writes `prefs.slides` and the storyboard into the same file — so a
+ * caller that really does want "N or nothing" compares those two numbers itself.
+ *
+ * REPORTED, NEVER REPAIRED, which is the same shape as `cut.dangling`. None of the
+ * three repairs above is available, so the deck is built at the count it has —
+ * `durationPlan` restrikes the whole budget there, which is what stops the
+ * shortfall becoming a video that quietly misses its duration — and the author
+ * is told what it cost, at `plan`, before a minute of TTS is spent on it.
+ *
+ * NAMING THE NUMBERS IS THE WHOLE VALUE, same argument as `INSTEAD` above: "the
+ * plan is short" changes nothing, "each surviving slide now runs 7.5s instead of
+ * 5.0s and has to carry 102 characters where the prompt budgeted 66" is a fact
+ * the author can act on — by adding the missing beat, or by accepting the deck
+ * they have.
+ *
+ * A WARNING, NEVER AN ERROR, and that is a contract rather than an oversight. A
+ * source that honestly carries eight points is a real thing, and only the author
+ * can tell that from a planner that stopped early. `build` prints every content
+ * loss and fails on none of them: a beat the emitter refused (`onBeatError`), a
+ * beat the budget cut (`reportCut`), a beat the planner never wrote (this one).
+ * A beat written and then thrown away is a bigger loss than one never written, so
+ * making the smallest of the three fatal while the larger two stay advisory would
+ * be incoherent — promoting this to `severity: "error"` is a decision about all
+ * three, not about this scan. test/verify.test.ts asserts the severity so that
+ * decision cannot be made by accident.
+ */
+export declare function scanBeatCount(storyboard: Storyboard, prefs: Prefs): Finding[];
 /**
  * How far a name may precede the thing it names before a viewer notices.
  *
@@ -174,9 +272,19 @@ export declare const LEAD_SECONDS = 1;
  * CONSERVATIVE BY CONSTRUCTION, in three ways, because a warning that cries wolf
  * is a warning people learn to scroll past:
  *   - a part is assumed to appear at the EARLIEST hold that could be its own,
- *     `holds[min(j, last)]`. Where an archetype spends its first hold on a
- *     landing rather than a part, the real appearance is later than this and the
- *     finding is missed rather than invented.
+ *     `holds[j]`. Where an archetype spends its first hold on a landing rather
+ *     than a part, the real appearance is later than this and the finding is
+ *     missed rather than invented.
+ *
+ *     THIS PARAGRAPH USED TO SAY `holds[min(j, last)]`, AND IT WAS WRONG IN THE
+ *     ONE DIRECTION A DOCSTRING MUST NOT BE WRONG IN. Clamping to the last hold
+ *     does not under-report, it OVER-reports: an archetype that draws five bars
+ *     on two holds charges bars three through five to the final hold, so a word
+ *     spoken over a bar that is already on screen is read as a word spoken 1.05
+ *     to 2.25s early, against a 1.0s threshold. 86 of `bar-compare`'s 90 flagged
+ *     parts were that arithmetic and not a defect — 43% of every flagged part in
+ *     the committed corpus. The promise of under-reporting is exactly why nobody
+ *     checked. The scene is now skipped instead of clamped, see below.
  *   - only labels the narration actually names are considered, by the same
  *     five-character prefix match `scanHeadlines` uses — tuned on exactly this
  *     problem, where the headline said "encoding" and the stage was `Encoder`.

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.1.4",
+  "version": "0.3.0",
   "description": "Turn a source document into an animated explanation deck.",
   "type": "module",
   "license": "MIT",
@@ -63,7 +63,7 @@
     "commander": "^14.0.1",
     "fflate": "^0.8.3",
     "gsap": "^3.14.2",
-    "hyperframes": "0.7.71",
+    "hyperframes": "0.8.27",
     "katex": "^0.16.11",
     "puppeteer-core": "^25.3.0",
     "remark-gfm": "^4.0.1",