@jokerized/decksmith 0.3.1 → 0.4.0

package/README.md

@@ -51,7 +51,9 @@ decksmith unpack  talk.deck        -o reopened/
 ```
 
 - **ingest** — document to `Source`: sections, figures, equations and tables, each with a
-  stable id so a later stage can point back at it.
+  stable id so a later stage can point back at it. Give it an http(s) URL instead of a
+  path and it reads the page in a browser first — see "Ingesting a web page" below, which
+  also says what happens to a video.
 - **plan** — `Source` to `Storyboard`: an ordered list of beats. Each beat carries an
   `intent` (what the viewer should understand), an optional `claim` it is accountable to,
   `evidence` refs into the Source, a `weight`, and an archetype with its parameters.
@@ -108,6 +110,77 @@ decksmith unpack  talk.deck        -o reopened/
 - **pack** / **unpack** — the whole deck as one `.deck` file, and back again. See "The
   `.deck` container" below.
 
+### Ingesting a web page
+
+`ingest` takes a URL wherever it takes a file:
+
+```sh
+decksmith ingest https://example.com/the-paper -o source.json
+```
+
+It opens a headless Chrome, puts the page's own bytes into it, and **aborts every request
+the page then makes**. A browser pointed at a stranger's URL is otherwise an open proxy —
+the page says `<img src="http://169.254.169.254/latest/meta-data/">` and the browser
+fetches it from inside your network. So the HTML comes through the same address guard
+everything else here uses, and each figure is fetched afterwards, one at a time, through
+that guard again. That has a cost, and it is stated rather than discovered: a page that assembles its body
+from an external bundle harvests to almost nothing, because that bundle was one of the
+aborted requests. Save the page and ingest the file.
+
+Which part of the page becomes the document is scored the way Readability scores it: strip
+what the tag, the ARIA role or the class name says is chrome, score every paragraph by its
+length and its commas, propagate that up to five levels of ancestor, discount each
+candidate by its link density, then merge the winner with the siblings that score near it.
+That is what keeps a consent banner and a 142-comment thread out of a deck about the
+article. When it is not sure it declines, says so, and leaves the page to a blunter rule —
+believe `<main>`, believe `<article>`, else take the densest container. Either way the
+line after it is the one to read:
+
+```
+ingest: harvested "Sparse attention at scale" — 6 images, 1 clips
+ingest: 9 sections, 6 figures, 0 equations
+```
+
+Nine sections for a nine-section article is the extraction working. Ninety is the page.
+
+**A video has three cases, and they are three different decks.**
+
+- **A file the page serves** — `<video src="…mp4">`, or a link ending in one — is
+  downloaded, measured off its own container, and re-encoded to a VP9 webm no more than
+  1280px on its longest edge, with the audio dropped and the length capped at 60 seconds.
+  It **plays in the presented deck and in the rendered mp4**: the composition holds a real
+  `<video>` seeked on the deck's own clock. The encode is why the cap exists — `render`
+  pre-decodes a clip to one still per output frame before capture begins, at the source's
+  own resolution, so a 4K original writes 4K stills into an 860px plate. **If ffmpeg is
+  not installed the clip is still used**, exactly as the page served it, and the harvest
+  says so in a warning naming what to install. `--no-transcode` asks for that on purpose;
+  `--max-clip-seconds` moves the cap.
+- **A player-page link** — YouTube, Vimeo, Dailymotion, Loom — keeps its still and where
+  to watch it. The **mp4 gets the poster frame**, because that is all a captured document
+  can honestly hold. The **presented deck gets the real player**: `deck.html` carries the
+  embeddable form of that URL, and a `▶ Video` button (or `v`) opens it over the slide,
+  click to play, torn down when you leave the slide. Nothing is fetched until you press
+  it, and `index.html` never gains an iframe — a third-party frame in the captured
+  document would play at wall-clock speed while the deck is being seeked, and refetch
+  itself from the network on every render.
+
+  **The bytes are deliberately not downloaded.** They sit behind a manifest, DRM or terms,
+  and pulling down what a YouTube link stands for is usually against that site's terms.
+  It is the same `embed` policy the container uses — see "bake, link, embed" below — and
+  it is a property of the URL rather than a choice you can make. A host we have no
+  verified embed rule for keeps the poster and the link, and no frame: a URL we invented
+  would 404 inside the frame as a black rectangle with nothing to click.
+- **No video at all** is the ordinary case, and nothing changes. A `<video>` with a poster
+  and no source becomes an ordinary figure, warned; one with neither becomes a line of
+  prose carrying the link, also warned.
+
+The URL-only budgets, each named after the option it sets so that a refusal naming
+`maxAssets` names something findable in `--help`: `--max-assets` (40), `--max-clips` (4),
+`--max-bytes` (96 MB in total), `--max-seconds` (180, wall clock for the whole harvest),
+`--max-clip-seconds` (60, per clip), `--no-transcode`. Every figure, clip or whole video
+left out is printed verbatim before the plan is paid for, which is the only moment anyone
+can act on it.
+
 ### What `build` writes
 
 ```
@@ -116,6 +189,11 @@ out/
   deck.html                     open this: the navigable deck
   hyperframes-player.global.js  copied from the hyperframes package, so nothing needs a CDN
   hyperframes.json
+  vendor/                       the scripts the head loads, and only those: GSAP and
+                                DrawSVG on every deck, MorphSVG (21,195 B) only on one
+                                that reshapes, ds-morph.js only on one that morphs an
+                                equation
+  katex/                        katex.min.css rewritten to its woff2 faces, and those fonts
   assets/                       every figure a beat cites — generated ones included, under
                                 the same name source.json records
   audio/                        only when the deck is narrated
@@ -126,9 +204,9 @@ not `file://`: the wrapper drives the composition through its iframe, and a file
 iframe cannot be reached. The deck says so in the console rather than rendering blank.
 
 Arrow keys, Space and PageUp/PageDown step; clicking the left or right third does too;
-`Home`/`End` jump; `n` toggles presenter notes; `f` is fullscreen; `m` mutes the voice and
-`s` hides the subtitles. Every step is deep-linkable (`#3` is slide 3, `#3.2` its second
-reveal).
+`Home`/`End` jump; `p` plays the deck by itself and pauses it again; `n` toggles presenter
+notes; `f` is fullscreen; `m` mutes the voice and `s` hides the subtitles. Every step is
+deep-linkable (`#3` is slide 3, `#3.2` its second reveal).
 
 Stepping forward *plays* the reveal rather than cutting to it — the step layer sweeps the
 composition's timelines across frames instead of seeking once. Backward steps, `Home`/`End`
@@ -279,6 +357,8 @@ for pictures still finishes, on the tool's own SVG if it has to.
 | `GET /api/jobs/:id/events` | the same payload as SSE on every change |
 | `GET /api/formats` | the presets, themes, tones, densities and canvas bounds the picker draws from |
 | `GET /d/:id/...` | the built deck, served statically; `/d/:id/deck.html` is the player |
+| `GET /player.js` | the `<decksmith-player>` element, as an ES module — see below |
+| `GET /examples/embed.html` | a page that embeds two decks with it, and the file you copy |
 
 Options on `POST`, all optional, all defaulted server-side: `format`, `width`+`height`,
 `theme`, `slides`, `lang`, `tone`, `density`, `speed`, `narrate`, `voice`, `images`,
@@ -488,6 +568,8 @@ const { out, files, navigable } = await buildDeck(storyboard, source, "./deck",
   format: FORMATS["deck-16x9"],
   theme: "ink",
   assetsFrom: ".",            // the directory whose assets/ holds the figures
+  onBeatError: (id, err) => {},    // the beat is not in the deck
+  onBeatWarning: (id, why) => {},  // the beat IS, minus an ornament it could not fit
   onStep: console.log,        // silent otherwise: a library that prints is one you
 });                           // cannot run inside a request handler
 
@@ -499,6 +581,11 @@ demo deck built this way is byte-identical to `decksmith build`'s. It does **not
 gates, because `verify` wants a browser and a caller may have neither one nor the patience
 for it; call `verify` yourself when you want it.
 
+`onBeatWarning` is the only signal that a slide is finished-looking but not what was
+planned — a `line-chart` drawn without its comparison, say. `build` prints it and the
+server puts it in the job's warnings; a library caller that ignores it ships the same
+silence this project keeps finding by eye.
+
 ### The surface
 
 | Stage | Exports |
@@ -511,6 +598,7 @@ for it; call `verify` yourself when you want it.
 | verify | `verify`, `check`, `parseCheckReport` |
 | pack | `writePack`, `readPack`, `openPack`, `planMedia`, `mediaSummary` |
 | prefs | `loadPrefs`, `CONFIG_FILE` |
+| process | `guardTmpdir` |
 | contract | everything in `src/types.ts` — every schema, `Source`, `Storyboard`, `Beat`, `Format`, `FORMATS`, `Verdict` |
 
 Two of those are worth pointing at. `Runner` is exported so you can drive planning through
@@ -522,6 +610,13 @@ body rather than a filesystem: it is pure, taking strings in and returning strin
 so a server's tests draw with a fake instead of spawning Codex, and a deployment can add a
 backend this package does not ship.
 
+`guardTmpdir` is the odd one out: it is not part of building a deck, it is what an
+executable that is about to `mkdtemp` calls first. It deletes a `TMPDIR` that resolves
+inside the package root and says so on stderr, and it is a no-op in an installed package.
+Importing this module does not run it, deliberately — an absent `TMPDIR` is inherited by
+every child process a host spawns, which is not a decision a library import gets to make
+for its host. Our own three executables call it; nothing else does.
+
 Anything not listed is deliberately absent, and adding to the list is a promise we cannot
 quietly take back. `prefsFromFlags` is the clearest example: it translates commander's flag
 object, which is the CLI's problem and nobody else's.
@@ -642,7 +737,19 @@ right up until the first stall, and a stall is exactly when a viewer looks at th
 to find out what they missed. `m` mutes (captions keep tracking, and a muted element is
 exempt from the autoplay policy, so it doubles as the escape hatch); `s` hides subtitles.
 If the browser refuses to autoplay, the deck says `press any key for sound` once and
-navigation carries on regardless.
+navigation carries on regardless. A segment that will not *play* — a missing file, a
+dropped connection — reads `narration unavailable` instead, because telling that viewer to
+press a key names the wrong culprit and goes on naming it every time they try. A gesture
+retries either failure; nothing retries the unplayable one unasked.
+
+`p` plays the deck by itself, and that is a mode rather than a change to what stepping
+means — the ordinary case is a presenter talking over it. A narrated stop is timed by its
+own audio and waits for it to finish. A stop that is not being *heard* — no segment, or
+one that would not play — gets the clock instead, at the gap the author left before the
+next stop, floored at 1.5s and capped at 8s. Whether a stop is heard is asked twice, on
+arrival and again when `play()` settles, because until it settles a missing file and a
+working one are indistinguishable; without the second ask, autoplay waits forever for an
+`ended` that a source which never loaded cannot fire.
 
 Audio is content-addressed on the text, voice, rate and pitch, so re-narrating an edited
 deck re-speaks only the sentences that moved — and two beats saying the same sentence
@@ -799,7 +906,7 @@ The explanatory vocabulary. These came out of hand-building a real deck
 | `equation-walk` | an equation explained symbol by symbol | `equationId`, `terms` (1–4) |
 | `equation-morph` | one equation becoming the next, the shared terms carried across | `fromId`, `toId`, `terms` (1–4) |
 | `data-table` | a results table with rows revealed in argument order | `tableId`, `highlight` |
-| `line-chart` | a trend, with per-step deltas | `points`, `deltas?`, `readout?` |
+| `line-chart` | a trend, with per-step deltas, optionally against a baseline | `points`, `deltas?`, `readout?`, `compare?` |
 | `callout` | 1–3 panels of prose: definitions, contrasts, takeaways | `panels`, `note?` |
 | `pipeline` | stages in a flow, arrowed, with an optional feedback loop | `stages` (2–6), `loop?` |
 | `annotated-figure` | a figure cropped to the panel under discussion, with leader lines | `figureId`, `crop?`, `notes` |
@@ -812,6 +919,33 @@ The last six draw the mechanism rather than describe it, and `verify` warns when
 leans on the others: a deck of headlines and bullet panels is what every other slide
 generator already makes.
 
+`line-chart`'s `compare` is the one parameter that changes what its archetype *is*. Given
+`{ label, points }` the chart draws the baseline first, holds it, then reshapes the curve
+into `points` and leaves the baseline behind as a labelled ghost — so the slide asserts a
+change in the curve's *shape*, not two numbers. Reach for it on that tell: one quantity
+measured under two conditions.
+
+The two series must be over the same x values in the same order, or `storyboardSchema`
+refuses the beat before any of it is drawn. Series over different categories would reshape
+point *i* of one condition onto point *i* of another, which is a smooth and convincing lie
+that nothing downstream can catch: both curves fit the plot, both clear the type floor, and
+`drift` renders the same wrong thing twice.
+
+It costs time — the baseline draws, is held, then reshapes — so give a compare beat
+`seconds` of 7, or 8 with a `readout`. Given fewer than it needs, the emitter draws the
+chart *without* the comparison rather than stopping on a half-drawn one: the same beat, one
+series, byte-for-byte the plain chart, down to MorphSVG's 21,195 bytes staying off the deck.
+It says so on the way past, as a `build: kept <beat> — …` line, and that line is the only
+place anyone learns the comparison is gone. Refusing instead would reach `onBeatError` and
+drop the whole slide, which is the worse trade.
+
+Keep `label` short. It is set at the end of the baseline and refused outright if it is
+wider than the plot, and *that* refusal does cost the slide. Where it fits, it is placed by
+trying four positions and rejecting any that would print through the axis names, the tick
+labels, the category names, a value, a drawn delta or either curve; if all four are
+rejected the label is dropped rather than overprinted, and dropped silently, because an
+unnamed ghost is still legibly the fainter, earlier curve.
+
 Each maps to exactly one emitter. Adding a domain means adding archetypes — the core never
 learns what a camera frustum or an orderbook is.
 
@@ -824,7 +958,13 @@ learns what a camera frustum or an orderbook is.
    inner HTML, GSAP statements, hold points, and its own CSS. It owns one scene's insides
    and nothing else. If it draws labelled parts a camera could fly into, fill `Scene.parts`
    in the same loop that gives them their ids — `inside.element` is an index, and that map
-   is the only thing that can tell the plan's third stage from the picture's.
+   is the only thing that can tell the plan's third stage from the picture's. If its tweens
+   need a vendored GSAP plugin, name it in `Scene.plugins`: `PLUGINS` in
+   `src/emit/composition.ts` is the one place a name resolves, and a name that table does
+   not know is refused at emit time rather than emitted as a tween that animates nothing.
+   And if it has to drop an ornament to fit the beat's length, draw the rest and say so in
+   `Scene.warnings` rather than throwing — a throw reaches `onBeatError`, which costs the
+   whole slide.
 3. Register it in `src/emit/archetypes/index.ts`.
 
 Nothing else changes. The document shell, the deck runtime, the format profiles and the
@@ -850,6 +990,42 @@ The corollary is worth internalising before you trust a green gate: `check` has
 twice on artifacts that were broken. The gates verify the mechanics of what the structure
 exposes, and a structurally wrong deck exposes nothing to check.
 
+### Embedding a deck in your own page
+
+The same step layer is reachable from outside as a custom element. A consumer learns one
+thing — where the deck is:
+
+```html
+<script type="module" src="/player.js"></script>
+<decksmith-player deck="/d/<id>/"></decksmith-player>
+```
+
+`next()`, `prev()`, `go(i)` and `play(on)` are methods; `ds-ready`, `ds-stop` and
+`ds-error` are events. `ds-ready` carries every stop the deck can land on, which is what
+a jump list is built from. Setting `deck` again swaps the deck in place.
+
+**The iframe stays, and is the module boundary.** It is tempting to mount the deck
+inline instead, and three facts in this tree rule it out. `frameOf` reads
+`contentDocument` and returns null cross-origin while the runtime only warns, so an
+inlined deck served from a CDN would navigate perfectly and paint nothing, silently.
+`customElements.define` is one registry per document, so two decks would be two vendored
+hyperframes bundles and the second `define` throws. And the deck's own chrome is written
+against `100vh` being the box, which is true inside a frame and quietly wrong outside it.
+Keeping the frame leaves the same-origin pair as `deck.html`↔`index.html`, one directory,
+always true — and makes the host link `postMessage`, which does not care about origin.
+
+**Silence is a supported state.** A deck is a static artifact that outlives the tool that
+built it, and every deck built before this change has no bridge in it. The element waits,
+gives up, emits `ds-error` with reason `no-bridge`, and leaves the deck exactly as usable
+as it was — still a deck in a frame, its own keyboard still working. It does not blank and
+it does not throw.
+
+`examples/embed.html` is both the demo the dev server serves at `/examples/embed.html`
+and the file you copy next to a built deck. Nothing in `lint`, `check`, `verify`, `drift`
+or `render` opens a deck page, so a browser pass is the only instrument that can tell you
+any of this works. The design note is
+[`.planning/2026-09-07-player-as-a-module.md`](.planning/2026-09-07-player-as-a-module.md).
+
 ## Invariants the generator enforces
 
 These were all learned by breaking them, and they are why build output is generated
@@ -888,19 +1064,36 @@ mechanically rather than free-hand.
   correctly only because one wrapper happened to already be its box's width. No gate reads
   CSS, so this is pinned by a test instead — `archetypes.test.ts` fails when two
   archetypes say different things about the same class name.
-- **Nothing is driven by a GSAP callback.** Capture seeks rather than plays, and `seek()`
-  passes `suppressEvents` — so `onUpdate`, `onStart` and `onComplete` never fire while a
-  frame is being taken. Motion applied from a callback therefore looks right in a browser
-  and renders a **frozen video**, with every gate green: lint, check, the type floor, and
-  even `drift`, which passes twice over because both renders freeze identically. State
-  must be applied by the thing being seeked — tween the property. This is the most
-  dangerous failure shape in the project, and no automated gate can see it.
+- **Nothing is driven by a GSAP callback.** Not because the video renders frozen: that was
+  the stated reason for a long time, it was measured on 2026-09-04, and it did not hold.
+  `hyperframes render` drives capture through Chrome's `beginFrame` rather than through a
+  seek, and `suppressEvents` is a property of a seek — so under the renderer a callback
+  fires and its motion ramps, in both constructions that were tried. What the callback
+  actually costs is **reproducibility**. Measured against a control on the same deck: the
+  demo differs on 11 frames of 3,120 as built and on 260 with one `onUpdate` tween added,
+  so one callback multiplies the non-reproducible frames by 24 without moving the
+  worst-case PSNR. And nothing in this stack agrees about what a callback did: `decksmith
+  frames` *does* seek, so it passes `suppressEvents` and shows nothing; `hyperframes
+  snapshot` shows a browser's playback; the render shows a third thing. So tween the
+  property, and where a value is not directly tweenable, tween a proxy object and bind the
+  property to it. `AGENTS.md` invariant 11 carries the measurement and the table.
+- **A vendored runtime costs bytes only on the decks that use it.** GSAP and DrawSVG are
+  unconditional, because every drawing archetype draws something on. Everything else goes
+  through `PLUGINS` in `src/emit/composition.ts`: a scene names what its tweens need in
+  `Scene.plugins`, the head emits a `<script src>` and a `registerPlugin` per name **in the
+  table's order** — not the scene's, or two storyboards differing only in beat order would
+  emit the same tags in a different order and cost someone a day in `drift` — and
+  `vendorScripts` copies only the files the emitted head actually references. So MorphSVG's
+  21,195 bytes are on a deck that reshapes and on no other, and a name the table does not
+  know is refused at emit time rather than shipped as a tween that silently animates
+  nothing. Registration goes before the first scene script, because a scene builds its
+  timeline inline and late registration is not late, it is nothing.
 
 ## Repo layout
 
 ```
 src/index.ts          the library surface — the only file consumers import
-src/cli.ts            the ten verbs, argv and stderr
+src/cli.ts            the eleven verbs, argv and stderr
 src/types.ts          the contract: Source, Storyboard, Beat, Format, Verdict
 src/prefs.ts          the three-layer preference resolver
 src/emit/kit.ts       the seam between the deck shell and the archetype emitters