bento-slides

# Authoring Bento decks A Bento deck is one self-contained `.bento.html` file. The document is plain JSON in a single block: ```html <script type="application/bento+json" id="bento-doc"> { "format":"bento/slides", ... } </script> ``` You edit **that block only**, in place. Escape every `<` in the JSON as `\u003c` so it can never contain a literal `</script>`. Leave the rest of the file (the compressed runtime) untouched. In a chat context instead, the user copies the JSON out (*Save ▾ → Copy document JSON*) and pastes your replacement back (*Save ▾ → Replace from JSON…*); `window.bento.loadDoc(json)` does it from the console. ## Starting from nothing The user does NOT need Bento installed — the app ships inside every deck. When there is no `.bento.html` to edit, fetch the latest signed release yourself and author into it: ```bash # name the file after the deck's topic, e.g. Q4_Review.bento.html curl -fsSL https://bento.page/releases/slides/Bento_Slides.bento.html -o "<Topic>.bento.html" ``` (Windows without curl: `iwr https://bento.page/releases/slides/Bento_Slides.bento.html -OutFile <Topic>.bento.html`.) Then verify the download contains `id="bento-doc"`, and write your document into that block. **The block is empty in the downloaded file** — a browser mints a showcase deck on first open, but on disk there is nothing to discard and nothing to copy from, so do not go looking for it. Rules for a fresh document: - **Fetch https://bento.page/agents.md BEFORE authoring** and start from its "Minimal valid document" skeleton. `size` and `theme` (including `theme.fontFamily`) are **required** — the app will not boot without them. - **Fully specify element fields** as the skeleton shows (shapes need `stroke`/`strokeWidth`; text needs `fontFamily`/`align`/`valign`) — missing fields render wrong or not at all. - **Omit `docId` and `collab` entirely**: the app mints a fresh identity and dormant collaboration credentials on first open. When done, open it (`open` / `xdg-open` / `start`) — the file boots straight into the editor with the finished deck — and **look at every slide before you report done**. Text overflow, elements crowding each other, a heading that wrapped to three lines and a chart key the renderer dropped are all invisible in the JSON and obvious on screen. Author, render, check, fix; a deck nobody looked at is not finished. ## Workflow 1. **Find the document.** Locate the `#bento-doc` block; parse its JSON. Note `doc.size` (canonical 1280×720), `doc.theme`, existing element `id`s, and whether `doc.template`/`doc.readonly` are set. **Check `doc.collab` first.** If it carries `ownerPriv`, `writerPriv` or `invite`, this deck's live-session keys are in the file you are about to read — and anything that receives the file or its JSON can join that session and write to it. That is by design: the file is the invitation. **Tell the user before you continue**, because only they can decide, and they may not know the deck is shared. Offer the alternative: a read-only copy, or *Share → Stop sharing* on a duplicate. If it has already gone somewhere, the remedy is *Share → Rotate keys* — removing the keys afterwards does not retract them. 2. **Read the source material the user gave you** and classify each piece — is it a stat? a table? a process? a definition to expand? a photo? 3. **Map material → feature (do NOT default to bullet text).** This is the step that makes it a Bento deck rather than a slideshow of paragraphs: - numbers to compare visually (trend, magnitude, share) → a **chart** element - a comparison / spec / pricing / feature grid → a **table** element (`columns` weights + `rows` of `cells` + a `style` object) - consecutive slides about the **same thing changing** → **morph**: give shared elements the same `id` on both slides + `transition:"morph"` on the later one (Bento's signature move — reach for it liberally) - a point to **drill into** → a **state slide** (`stateOf` + element `link`) - a **hero / full-slide image** → full-bleed image + scrim rect + text, with **ken-burns** drift - a **sequence / flow / timeline** → a line/`path` with a `dash-march` loop, or morph a highlight through the steps - a **headline number** → big text + `fx:{countUp:true}` - **every cover / divider** → at least one ambient motion - **repeated chrome / logo** → keep its `id` stable across slides so it morphs in place - a **demo clip / recording / soundbite** → a **media** element (`kind: video|audio`); embed short clips as a data URI, link big ones by URL to keep the file small 4. **Author** using the schema. Keep the full schema and copy-paste recipes open: **fetch https://bento.page/agents.md** (it has the element shapes, the morph/chart/state/ken-burns snippets, and the gotchas). Respect one accent colour, ≤2 typefaces, 96px side margins (right-most x ≤ 1184), and write **speaker notes** on each slide. 5. **Self-audit before finishing:** - [ ] any numbers rendered as text that should be a **chart**? - [ ] do consecutive slides on one subject share **ids + `transition:"morph"`**? - [ ] at least one **motion moment** (ken-burns / loop / count-up), esp. the cover? - [ ] a drill-down that would work better as a **state slide**? - [ ] one accent colour, ≤2 typefaces, 96px margins? - [ ] speaker notes on every slide? 6. **Write back** the edited `#bento-doc` block (escaping `<`), or return the replacement JSON. Never regenerate the whole HTML file. ## Critical gotchas - **Charts:** bar/line series `data` must be **plain numbers** (`{value,…}` item objects coerce to 0 — only pie takes `{name,value}`); colour by series, not per bar; `option` is pure JSON, template formatters only (`{b}`/`{c}`/`{d}`), never functions. - **Morph needs deterministic, stable ids** shared across the slides that should animate together. Different ids = no morph (elements just cut). - **Images/fonts must be embedded** as data URIs in `doc.assets` and referenced by `"asset:<key>"` — the file stays self-contained. - **Media:** a `media` element (`kind: video|audio`) embeds short clips as a data URI in `src` (self-contained) or references a URL for big files (keeps the deck small). `autoplay` runs only in present mode and needs `muted:true` for video. Don't embed large videos — they bloat the file. - **Never regenerate `docId`** when editing an existing deck; it is the document's identity. (Fresh decks omit it — the app mints one.) - `template:true` → every open mints a fresh deck; `readonly:true` → the file boots straight into the show with no editor. Working examples of every technique: open any template at https://bento.page and read its `#bento-doc` block.