@jokerized/decksmith 0.2.0 → 0.3.1

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

@@ -242,6 +242,70 @@ export declare function scanUnusedFigures(storyboard: Storyboard, source: Source
  * decision cannot be made by accident.
  */
 export declare function scanBeatCount(storyboard: Storyboard, prefs: Prefs): Finding[];
+/**
+ * Where a paper-shaped deck missed the shape it was asked for.
+ *
+ * SILENT UNLESS THE ARC WAS DECLARED. `prefs.genre` defaults to `general`, so
+ * every deck built before this existed, and every deck whose author did not say
+ * `--genre paper`, gets exactly nothing from this scan. That is not timidity: a
+ * ten-role heading lexicon over all 351 markdown files in this repository found
+ * 345 with zero hits, so there is no honest way to infer the genre, and a scan
+ * that guessed would mislabel the Korean fixture and every hypepaper analysis
+ * the tool actually ingests.
+ *
+ * REPORTED, NEVER REPAIRED, and a WARNING. It joins the four scans that already
+ * take that shape, and `scanBeatCount`'s header settles the class: `build`
+ * prints every content loss and fails on none of them, because the alternative
+ * is re-asking, and the only possible second instruction — "return more" — is a
+ * padding request with extra steps. Promoting this one is a decision about all
+ * of them.
+ *
+ * WHAT IT CANNOT DO. It cannot tell whether a beat labelled `limitations` really
+ * discusses one; `role` is the plan's own declaration, and a declaration can be
+ * false. What it checks instead is the part that is mechanical and that no
+ * committed plan has ever got right on its own: that the roles exist, that they
+ * are unique, that the ending is in the right ORDER, and that the closing pair
+ * does not collapse into two of the same picture. A rule about wording would be
+ * met cosmetically, exactly as `scanHeadlines` records a sharpened rule being
+ * answered by swapping one verb.
+ */
+export declare function scanPaperArc(storyboard: Storyboard, prefs: Prefs): Finding[];
+/**
+ * Narration that belongs to a different version of this storyboard.
+ *
+ * `narration.json` is keyed by BEAT ID and carries nothing that ties it to the
+ * plan it was made for, so an id that still exists is an id `build` will happily
+ * speak — even when the beat behind it has been replaced. Renumbering is the way
+ * in: inserting one beat and shifting the ids after it leaves every later id
+ * pointing at its neighbour's voice.
+ *
+ * FOUND IN THE SHIPPED DEMO, and it is the seventh green-gate case this project
+ * has recorded. A thirteenth beat was inserted at position six and the rest
+ * renumbered; the audio on disk predated it, so beats six through twelve each
+ * spoke the slide after them and the thirteenth spoke nothing. `build` reported
+ * `PASS — 0 error(s), 0 warning(s)`, because every id it looked for was present
+ * and nothing compared what was SAID against what the beat says it says.
+ *
+ * AN ERROR, NOT A WARNING, and it is the one member of this family that earns
+ * it. The other storyboard scans are editorial judgements only an author can
+ * settle; this is a string comparison between two authored fields that must
+ * agree, and the artifact it lets through is a video whose voice describes the
+ * wrong pictures. Missing narration audio is already an error here, and audio
+ * that is present and wrong is not the better failure.
+ *
+ * NARROW ON PURPOSE. It compares only beats that have BOTH a narration text and
+ * segments, so a deck narrated at a lower density — where some beats are
+ * deliberately silent — says nothing, and the existing missing-audio error keeps
+ * its own case. Whitespace is normalised because the splitter re-joins sentences
+ * at stop boundaries; on the demo's thirteen beats the concatenation reproduces
+ * the authored text exactly, which is what makes the comparison safe to make
+ * fatal.
+ */
+export declare function scanNarrationDrift(storyboard: Storyboard, narration: {
+    beats: Record<string, {
+        text: string;
+    }[]>;
+}): Finding[];
 /**
  * How far a name may precede the thing it names before a viewer notices.
  *

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.1",
   "description": "Turn a source document into an animated explanation deck.",
   "type": "module",
   "license": "MIT",