@jokerized/decksmith 0.3.1 → 0.3.2

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
 
 ```
@@ -279,6 +352,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`,
@@ -850,6 +925,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