@jokerized/decksmith 0.1.3 → 0.2.0

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jokerized/decksmith",
-  "version": "0.1.3",
+  "version": "0.2.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",