@jokerized/decksmith 0.1.0

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

@@ -0,0 +1,207 @@
+import { type Beat, type Finding, 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
+ * `verify <dir>` entry point does not already have. Exported for the same reason
+ * the other scans are: it is testable without a browser.
+ */
+export { type Canvas, profilesFor, readCanvas, scanBudget } from "./budget.js";
+/**
+ * The drift gate is deliberately not part of `verify()`. Everything above reads
+ * one built artifact and costs seconds; drift renders the deck twice and costs
+ * minutes, so folding it in would make every build pay for it. It is its own
+ * entry point, called on demand.
+ */
+export { type DriftMode, type DriftOptions, type DriftReport, drift, FLOOR_DB, type Motion, type SceneWindow, } from "./drift.js";
+/**
+ * The fidelity gate. Unlike `drift` it IS part of `verify()`: it costs one
+ * browser and one screenshot per declared stop — 4.3s for the twelve-beat demo's
+ * 37 stops against `check`'s ~60s — so folding it in is a 7% tax, and it is the
+ * only gate here that can see a slide that draws nothing.
+ */
+export { type FidelityOptions, type FidelityReport, type Frame, fidelity, gradeFidelity, INK_FLOOR, inkBelow, type Measured, readStops, type Stop, } from "./fidelity.js";
+/**
+ * The chart-collision rule, folded into `fidelity`'s report because it shares
+ * that gate's browser. Exported here so the pure half is testable and so a
+ * caller can see what the rule considers a collision.
+ */
+export { collectSvgTextRuns, gradeOverprint, MIN_OVERLAP, type Overprint, type Overprinted, overprints, type TextRun, } from "./overprint.js";
+/**
+ * Invariant 5. Emit enforces the floor while laying a beat out, and this checks
+ * that the artifact came out the way emit believed — the two are not the same
+ * claim while any of that enforcement is a character count rather than a width.
+ */
+export { scanTypeFloor, TYPE_FLOOR_PX } from "./typefloor.js";
+/**
+ * What `verify` runs on top of the HyperFrames gates.
+ *
+ * `fidelity` is opt-OUT rather than opt-in: it is the only gate that can see a
+ * slide the audience gets nothing from, and a gate that has to be asked for is a
+ * gate that is not on when it matters. The switch exists for the one honest
+ * case — a machine with no browser, where it would only emit its own warning.
+ */
+export interface VerifyOptions extends CheckOptions {
+    /** Default true. `false` skips the frame measurement entirely. */
+    fidelity?: boolean;
+}
+/**
+ * Run every gate DeckSmith owns over a built project directory.
+ *
+ * The storyboard is optional because `decksmith verify <dir>` is handed a built
+ * directory and nothing else; pass it from `build`, where one is in hand, to get
+ * 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.
+ */
+export declare function verify(dir: string, opts?: VerifyOptions, storyboard?: Storyboard, kept?: readonly Beat[]): Promise<Verdict>;
+/**
+ * Every mp3 the narration island promises is actually in the deck.
+ *
+ * Nothing else notices this. `hyperframes check` never opens `deck.html`, and
+ * the runtime treats a missing file exactly like a browser that refused to
+ * autoplay — it clears the subtitles and moves on. So a deck that lost its audio
+ * on the way to a web host presents in silence and says nothing about why, which
+ * is the failure mode a gate exists for.
+ */
+export declare function scanNarration(page: string, files: ReadonlySet<string>): Finding[];
+/**
+ * Warn when a deck mostly talks. A deck of headlines and bullet panels is what
+ * every other slide generator already makes, and passes every other gate here
+ * with room to spare — nothing else in the pipeline notices it at all.
+ *
+ * A warning rather than an error: a genuinely shapeless source can honestly
+ * yield such a deck, and this is a judgement about explanation, not a broken
+ * build.
+ */
+export declare function scanDiagrammatic(storyboard: Storyboard): Finding[];
+/**
+ * Warn when a headline reads the visual's own labels back as a list.
+ *
+ * FOUND BY WATCHING A RENDER, not by a gate. "ThinkSR links encoding, windows,
+ * thought ticks, and decoding" sat over a pipeline whose four stages are Encoder,
+ * Windows, Shared DQ-CTM ticks and Decoder. Cover the four names and the sentence
+ * asserts nothing the arrows had not already drawn — it is RULE 8's label with
+ * commas where the Title Case used to be. It passes RULE 8 as written, because it
+ * IS a complete sentence in sentence case with a verb in it.
+ *
+ * WHY THIS IS A DETECTOR AND NOT A PROMPT RULE. It was tried as a prompt rule
+ * first — an example-led sharpening of RULE 8 carrying that exact bad headline and
+ * its good twin — and a real Codex run answered "ThinkSR runs through encoder,
+ * windows, ticks, and decoder". Same beat, same four labels, verb swapped. Whether
+ * a sentence "asserts nothing" is a judgement the writer makes about their own
+ * output, so it can always be met cosmetically. The label strings are not a
+ * judgement, so a check on them has teeth the instruction did not.
+ *
+ * TWO CONDITIONS, and it needs both. Naming your own parts is not the defect —
+ * "A dense carrier is read and updated by compact thought" names all three of its
+ * stages and is the good headline on the same archetype, because the names sit in
+ * different grammatical positions with a relation asserted between them. And
+ * coordination is not the defect either: "One pass in, one pass out, and a loop in
+ * the middle" is three coordinated fragments and the sharpest line in the shipped
+ * demo, because it names no stage at all — it says what the shape DOES. The defect
+ * is the two together, which is why this counts labels landing in SEPARATE
+ * coordinated fragments rather than counting either alone.
+ *
+ * A warning, never an error. Incidence is about one beat in twelve, the judgement
+ * is editorial, and `plan` already tells the author to read the storyboard before
+ * building — which is the moment this is for.
+ */
+export declare function scanHeadlines(storyboard: Storyboard): Finding[];
+/**
+ * Warn when two beats draw the SAME PICTURE from the same object (RULE 9).
+ *
+ * FOUND IN A REAL PLAN, not by a gate. `b10-params` and `b11-average` both cite
+ * `tbl-bench` and both emit a bar-compare over the same five methods — one
+ * picture, drawn twice, with a different number on the bars. RULE 9 already
+ * forbids it in prose ("One object, one beat... Repeating a visual to say one
+ * more small thing is padding, and reads as padding") and the planner did it
+ * anyway, which is the same shape of failure `scanHeadlines` documents: a rule
+ * about whether something is padding is a judgement the writer makes about their
+ * own output, so it can always be met cosmetically.
+ *
+ * THREE CONDITIONS, and it needs all of them, because the loose version condemns
+ * the shipped demo. Measured over the 134 plans in `experiments/` and `demo/`:
+ *
+ *   same evidence id alone                  fires on 10 plans, INCLUDING demo/storyboard.json
+ *   + same archetype + identical labels     fires on 4, demo clear, every hit the same five bars
+ *
+ * What the two extra conditions buy is the difference between padding and
+ * progressive disclosure. `demo/storyboard.json` cites `tbl-bench` from a
+ * bar-compare and then a data-table — the shape, then the numbers — and that is a
+ * deck teaching, not repeating. So is a pipeline followed by the paper's own
+ * annotated figure. Two bar-compares over the identical five bars is neither;
+ * there is no reading of it in which the second picture shows something the first
+ * did not. A0-05 draws three bar-compares off one table with DIFFERENT bars in
+ * each and is deliberately left alone — different bars are a different picture,
+ * and whether three of them is too many is editorial.
+ *
+ * A camera dive is exempt: `inside` says this beat is what happens within a part
+ * of the one before it, so sharing the object is the entire point of the relation
+ * (RULE 11) rather than a repeat of it.
+ *
+ * A warning, never an error — same reason as `scanHeadlines`. Merging two beats
+ * into two holds of one beat is a rewrite only the author can perform.
+ */
+export declare function scanRepeatedObject(storyboard: Storyboard): Finding[];
+/**
+ * How far a name may precede the thing it names before a viewer notices.
+ *
+ * A second, which is generous on purpose. The word position inside a cue is
+ * estimated proportionally by character offset — the same model `splitCue`
+ * already uses — so it carries a few hundred milliseconds of error, and a
+ * threshold tighter than that would be reporting its own arithmetic.
+ */
+export declare const LEAD_SECONDS = 1;
+/**
+ * Warn when the narration names a part before that part is on screen.
+ *
+ * `scanHeadlines` one level down, and the reason it did not exist until now is
+ * worth keeping: THE DEFECT WAS NOT REACHABLE. Measured across all 136 plans in
+ * `experiments/` and `demo/` — 1103 named parts over 337 containers, every word
+ * placed on the scene clock at the speed a 60-second target derives — the lead
+ * came out at median −6.87s, p90 −2.47s, maximum +0.87s, and **zero** parts were
+ * named more than a second early. Transplanting §9's own defect sentence onto a
+ * real pipeline produced zero early names too. The build ran roughly four times
+ * faster than the voice, so the narration simply could not outrun the picture.
+ *
+ * `fillFactor` is what makes it reachable. Slowing each scene's build to fill its
+ * sentence takes that same measurement from 0 of 1103 to 222 of 1103 — the words
+ * stay put and the pictures they describe move later. So this ships in the same
+ * change as the stretch, not after it: the detector is not a smoke alarm for a
+ * fire already burning, it is the one fitted before the gas is turned on.
+ *
+ * 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.
+ *   - 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`.
+ *   - the word's time inside its cue is estimated proportionally, and the
+ *     threshold is a whole second.
+ *
+ * A warning, never an error. Which sentence describes which reveal is editorial,
+ * and `place` already guarantees the containment that matters — no sentence ends
+ * before the reveal it speaks over appears (`assertFits`).
+ */
+export declare function scanNarrationLead(beats: readonly Beat[], timing: {
+    scenes: readonly {
+        id: string;
+        start: number;
+        holds: readonly number[];
+    }[];
+    segments: readonly {
+        scene: string;
+        start: number;
+        cues: readonly {
+            start: number;
+            end: number;
+            text: string;
+        }[];
+    }[];
+}): Finding[];
+/** Flag render-time nondeterminism in one composition file (invariant 7). */
+export declare function scanDeterminism(html: string, file: string): Finding[];

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

@@ -0,0 +1,133 @@
+/**
+ * THE COLLISION GATE — inside a chart, did two labels land on top of each other?
+ *
+ * WHY THIS EXISTS AND WHY IT IS OURS. `hyperframes check` has a rule for exactly
+ * this, `content_overlap`, and it is STRUCTURALLY BLIND to a chart. Two reasons,
+ * either of which alone is fatal:
+ *
+ *   - `isManagedFlowOverlap` (layoutAudit) exempts any pair of boxes that are
+ *     both in normal flow under a shared flex/grid ancestor, on the sound
+ *     grounds that a flex container is entitled to lay its children out however
+ *     it likes. An SVG child computes `position: static`, so `isInFlow` is true
+ *     of every `<text>` in the chart, and `.chartwrap` is the flex ancestor they
+ *     all share. Every label pair in every chart is exempt, permanently.
+ *   - `content_overlap` is not in `OFF_CANVAS`, so even if it fired it would
+ *     arrive as upstream's severity and could never fail a DeckSmith build.
+ *
+ * MEASURED, not reasoned: `line-chart` with the three 2026-07-31 fixes reverted,
+ * built as a one-beat deck and sampled at every stop inside the scene, comes
+ * back `layout.findings: []` with `truncated: false`. The deck it passed is a
+ * line chart whose value labels, delta labels and category labels print through
+ * each other 69 times over. Neither of those two facts is reachable from here
+ * without an upstream change, so the rule is ours.
+ *
+ * WHY SVG AND NOTHING ELSE. Scoping it wider would be re-implementing
+ * `content_overlap` badly: outside SVG, elements overlap on purpose all the time
+ * (a badge on a card, a caption over a plate), the flex exemption upstream
+ * applies is CORRECT there, and a second opinion that disagrees with the shipped
+ * gate is how two definitions of "broken" start drifting apart. Inside an `<svg>`
+ * every glyph was placed by our own arithmetic at an absolute coordinate: two
+ * text runs on the same pixels is never a layout engine's decision, it is always
+ * our emitter getting the spacing wrong. Two archetypes emit `<text>` —
+ * `line-chart` and `bar-compare` — so that is the whole blast radius.
+ *
+ * WHERE IT RUNS. Inside `fidelity`'s existing per-stop loop, on the page it has
+ * already opened and seeked. No second browser, no second page, no second
+ * `renderSeek`: the marginal cost is one `page.evaluate` per stop. It therefore
+ * rides with `--fidelity`, which is right rather than merely convenient — the
+ * one honest reason to pass `--no-fidelity` is a machine with no browser, and a
+ * machine with no browser cannot run this either.
+ *
+ * AT A STOP, NOT AT A MIDPOINT. A chart builds: at t=0 the value labels have not
+ * arrived and at the first hold the deltas have not. Measuring anywhere but a
+ * declared stop would report a collision between a label that is on screen and
+ * one that is fading in at opacity 0.3, which is motion, not a defect. The walk
+ * drops anything hidden or fully transparent for the same reason.
+ */
+import type { Finding } from "../types.js";
+/**
+ * How much two runs must share, in BOTH axes, before it is a collision.
+ *
+ * 8px, carried across from the calibration this was fitted in (the
+ * research-env perturbation sweep, 2026-07-31). Abutting boxes are the reason it
+ * is not zero: a `<text>` run's client rect includes the font's leading, so two
+ * lines of a stacked label overlap by a pixel or three while being perfectly
+ * legible, and at 0 the sweep called every multi-line label a defect. 8px is
+ * about a fifth of the 40px audience floor of invariant 5 — an overlap that
+ * large is a fifth of a glyph body and is visible.
+ */
+export declare const MIN_OVERLAP = 8;
+/** One painted run of text, in device pixels. */
+export interface TextRun {
+    /**
+     * Which text node this rect came from, numbered in document order.
+     *
+     * IDENTITY, NOT THE STRING. Chrome hands back one client rect per line box, so
+     * a wrapped `<text>` yields several runs that necessarily overlap; those are
+     * one label, not a collision. The first version told them apart by comparing
+     * `text`, which also exempted two GENUINELY different labels that happened to
+     * agree — on the first 40 characters, since that is all `text` keeps — and
+     * exempted a real collision between two elements showing the same rounded
+     * value, which is exactly what a chart with repeated y-labels produces.
+     */
+    node: number;
+    /** The run's string, truncated — for the message only, never for comparison. */
+    text: string;
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}
+/** Two runs that share pixels, and how many. */
+export interface Overprint {
+    a: string;
+    b: string;
+    /** Overlap extent, `[x, y]`, rounded. */
+    overlap: [number, number];
+}
+/**
+ * Serialised into the page: every visible text run inside this scene's SVGs.
+ *
+ * TEXT RANGES, NOT ELEMENT BOXES. `<g class="ptlab">` wraps every value label in
+ * the chart, so its own box spans the entire plot and overlaps everything;
+ * measuring elements would report the chart colliding with itself on every deck
+ * ever built. A `Range` over the text node measures the glyphs, which is what
+ * the audience sees overlapping.
+ *
+ * The walk starts at the SCENE and only begins collecting once it is inside an
+ * `<svg>`, so the visibility test is applied to every ancestor on the way down —
+ * a chart hidden inside a collapsed wrapper contributes nothing, rather than
+ * contributing runs measured at a stale position.
+ */
+export declare function collectSvgTextRuns(sid: string): TextRun[];
+/**
+ * Every pair of runs that shares more than `minOverlap` pixels in both axes.
+ *
+ * Pure and exported so the predicate can be tested without a browser — the same
+ * reason `inkBelow` is. Quadratic on purpose: a chart has tens of labels, not
+ * thousands, and a spatial index here would be code nobody can check by reading.
+ *
+ * ONE NODE'S OWN RECTS ARE SKIPPED. A `<text>` that Chrome breaks into two line
+ * boxes yields two runs which necessarily overlap; that is one label, and without
+ * this the sweep's very first run reported hundreds of them. The test is
+ * `TextRun.node`, not the string — see there for why comparing the string
+ * exempted real collisions too.
+ */
+export declare function overprints(runs: readonly TextRun[], minOverlap?: number): Overprint[];
+/** One scene's collisions at one stop. */
+export interface Overprinted {
+    sid: string;
+    t: number;
+    pairs: Overprint[];
+}
+/**
+ * Findings for the scenes whose chart labels print through each other.
+ *
+ * One finding per SCENE, not per pair and not per stop — the same shape, and the
+ * same reason, as `gradeFidelity`. `line-chart` at sixteen points collides 69
+ * times at one stop; sixty-nine lines saying "two labels overlap" is a report
+ * nobody reads, and the defect is one defect: the chart does not have room for
+ * its labels. The worst stop is named because that is the frame to open, and
+ * three example pairs because a repair needs to know WHICH labels.
+ */
+export declare function gradeOverprint(rows: readonly Overprinted[]): Finding[];

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

@@ -0,0 +1,50 @@
+/**
+ * Invariant 5, measured on the artifact instead of guessed from the input.
+ *
+ * WHY THIS EXISTS AT ALL. The floor is enforced at emit time — seven archetypes
+ * refuse a beat they cannot lay out above it — but the enforcement is a mixture
+ * of measurement and PROXY, and the proxies are where it leaks. The clearest one
+ * is `src/emit/archetypes/equation-walk.ts:187`, which picks a font size from
+ * `tex.length`: 68px past 120 characters, 80 past 90, 92 past 55. A character
+ * count is not a width. `\alpha` is six characters and one glyph; `\!` is two
+ * characters and negative width. The review of `.planning/VOCABULARY.md` found
+ * the same substitution being used as a DEFECT TEST — `coherence.mjs:92` scored a
+ * headline as broken at "73 chars > 60" — built the deck, and found the
+ * 73-character headline wrapping to two lines at full size, looking correct
+ * (VOCABULARY-REVIEW §3.3). A rule that fires on text that renders fine is a rule
+ * people learn to ignore, and a rule that passes text that renders too small is
+ * worse. So nothing here counts characters. It reads the size the deck declares.
+ *
+ * REFERENCE SPACE, NOT CANVAS PIXELS. An archetype lays out in a unit system
+ * `refWidth` wide and `baseCss` zooms the finished scene onto the real canvas
+ * exactly once (`src/emit/kit.ts`, `REF_PULL`). Every absolute measurement in the
+ * vocabulary — including the floor — is therefore written in reference space and
+ * left untouched by the format: MEASURED on the demo, both `deck-16x9` and
+ * `short-9x16` declare the same smallest size, 40. At 1920 the zoom is exactly 1
+ * and reference px are canvas px; in portrait the same 40 deliberately lands at
+ * 30 canvas px, which is the whole argument of `REF_PULL` and not a violation. So
+ * the declared number is the number the floor is about, and the scan compares it
+ * to 40 as written, with no per-format normalisation to get wrong.
+ *
+ * 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
+ * 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.
+ */
+import type { Finding } from "../types.js";
+/**
+ * Audience text never below this, in reference-space px (invariant 5).
+ *
+ * Inclusive: the demo declares exactly 40 in ten places, and a floor that failed
+ * its own reference deck would be a floor nobody could build against.
+ */
+export declare const TYPE_FLOOR_PX = 40;
+/**
+ * Every text size the composition declares, against the floor.
+ *
+ * `file` names the composition in the finding, the way `scanDeterminism` does —
+ * a deck can hold more than one and "some size is 28px" is not a repair.
+ */
+export declare function scanTypeFloor(html: string, file: string, floorPx?: number): Finding[];

package/package.json

@@ -0,0 +1,84 @@
+{
+  "name": "@jokerized/decksmith",
+  "version": "0.1.0",
+  "description": "Turn a source document into an animated explanation deck.",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ca1773130n/DeckSmith.git"
+  },
+  "homepage": "https://github.com/ca1773130n/DeckSmith#readme",
+  "bugs": {
+    "url": "https://github.com/ca1773130n/DeckSmith/issues"
+  },
+  "keywords": [
+    "slides",
+    "presentation",
+    "deck",
+    "animation",
+    "gsap",
+    "video",
+    "paper",
+    "explainer",
+    "mcp"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "bin": {
+    "decksmith": "./dist/cli.js",
+    "decksmith-mcp": "./dist/mcp.js"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/types/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "node scripts/build.mjs",
+    "prepare": "npm run build",
+    "typecheck": "tsc --noEmit",
+    "lint": "biome check .",
+    "format": "biome check --write .",
+    "test": "vitest run",
+    "check": "npm run typecheck && npm run lint && npm run test",
+    "score": "npm run build && node scripts/score.mjs",
+    "sweep": "npm run build && node scripts/sweep.mjs",
+    "build:server": "esbuild src/server/*.ts --outdir=dist/server --platform=node --target=node22 --format=esm --log-level=warning",
+    "build:mcp": "esbuild src/mcp/main.ts --bundle --outfile=dist/mcp.js --platform=node --target=node22 --format=esm --packages=external --log-level=warning",
+    "serve": "npm run build && npm run build:server && node dist/server/main.js",
+    "demo": "node demo/build.mjs && node dist/cli.js build demo/storyboard.json --source demo/source.json -o demo/deck && python3 -m http.server 8080 --directory demo/deck --bind 127.0.0.1"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.30.0",
+    "@puppeteer/browsers": "^3.0.6",
+    "commander": "^14.0.1",
+    "fflate": "^0.8.3",
+    "gsap": "^3.14.2",
+    "hyperframes": "0.7.71",
+    "katex": "^0.16.11",
+    "puppeteer-core": "^25.3.0",
+    "remark-gfm": "^4.0.1",
+    "remark-math": "^6.0.0",
+    "remark-parse": "^11.0.0",
+    "unified": "^11.0.5",
+    "zod": "^4.1.12"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.3.14",
+    "@types/mdast": "^4.0.4",
+    "@types/node": "^22.19.0",
+    "esbuild": "^0.25.12",
+    "typescript": "^5.9.3",
+    "vitest": "^3.2.4"
+  }
+}