Authoring Bento decks
A Bento deck is one self-contained .bento.html file. The document is plain
JSON in a single block:
<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:
# 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
Find the document. Locate the #bento-doc block; parse its JSON. Note
doc.size (canonical 1280×720), doc.theme, existing element ids, 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.
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?
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
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.
Self-audit before finishing:
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.
1---2name: bento-slides3description: >-4 Create and edit Bento presentations — single-file .bento.html decks whose5 document is plain JSON in a "#bento-doc" script block. Use whenever the user6 wants a slide deck or presentation: starting from NOTHING (it downloads the7 latest Bento app from bento.page automatically), from source material, or by8 improving an existing .bento.html. Maps content to the right feature9 (charts, morph transitions, state slides, ken-burns, motion paths) instead10 of static text slides, then writes the document JSON in place. Full schema +11 recipes at https://bento.page/agents.md.12metadata:13 source: https://skillmd.com/skills/nyblnet/bento-slides14---1516# Authoring Bento decks1718A Bento deck is one self-contained `.bento.html` file. The document is plain19JSON in a single block:2021```html22<script type="application/bento+json" id="bento-doc"> { "format":"bento/slides", ... } </script>23```2425You edit **that block only**, in place. Escape every `<` in the JSON as26`\u003c` so it can never contain a literal `</script>`. Leave the rest of the27file (the compressed runtime) untouched. In a chat context instead, the user28copies the JSON out (*Save ▾ → Copy document JSON*) and pastes your29replacement back (*Save ▾ → Replace from JSON…*); `window.bento.loadDoc(json)`30does it from the console.3132## Starting from nothing3334The user does NOT need Bento installed — the app ships inside every deck.35When there is no `.bento.html` to edit, fetch the latest signed release36yourself and author into it:3738```bash39# name the file after the deck's topic, e.g. Q4_Review.bento.html40curl -fsSL https://bento.page/releases/slides/Bento_Slides.bento.html -o "<Topic>.bento.html"41```4243(Windows without curl: `iwr https://bento.page/releases/slides/Bento_Slides.bento.html -OutFile <Topic>.bento.html`.)4445Then verify the download contains `id="bento-doc"`, and write your document46into that block. **The block is empty in the downloaded file** — a browser47mints a showcase deck on first open, but on disk there is nothing to discard48and nothing to copy from, so do not go looking for it.49Rules for a fresh document:5051- **Fetch https://bento.page/agents.md BEFORE authoring** and start from its52 "Minimal valid document" skeleton. `size` and `theme` (including53 `theme.fontFamily`) are **required** — the app will not boot without them.54- **Fully specify element fields** as the skeleton shows (shapes need55 `stroke`/`strokeWidth`; text needs `fontFamily`/`align`/`valign`) — missing56 fields render wrong or not at all.57- **Omit `docId` and `collab` entirely**: the app mints a fresh identity and58 dormant collaboration credentials on first open.5960When done, open it (`open` / `xdg-open` / `start`) — the file boots straight61into the editor with the finished deck — and **look at every slide before you62report done**. Text overflow, elements crowding each other, a heading that63wrapped to three lines and a chart key the renderer dropped are all invisible64in the JSON and obvious on screen. Author, render, check, fix; a deck nobody65looked at is not finished.6667## Workflow68691. **Find the document.** Locate the `#bento-doc` block; parse its JSON. Note70 `doc.size` (canonical 1280×720), `doc.theme`, existing element `id`s, and71 whether `doc.template`/`doc.readonly` are set.7273 **Check `doc.collab` first.** If it carries `ownerPriv`, `writerPriv` or74 `invite`, this deck's live-session keys are in the file you are about to read75 — and anything that receives the file or its JSON can join that session and76 write to it. That is by design: the file is the invitation. **Tell the user77 before you continue**, because only they can decide, and they may not know78 the deck is shared. Offer the alternative: a read-only copy, or *Share → Stop79 sharing* on a duplicate. If it has already gone somewhere, the remedy is80 *Share → Rotate keys* — removing the keys afterwards does not retract them.812. **Read the source material the user gave you** and classify each piece —82 is it a stat? a table? a process? a definition to expand? a photo?833. **Map material → feature (do NOT default to bullet text).** This is the84 step that makes it a Bento deck rather than a slideshow of paragraphs:85 - numbers to compare visually (trend, magnitude, share) → a **chart** element86 - a comparison / spec / pricing / feature grid → a **table** element87 (`columns` weights + `rows` of `cells` + a `style` object)88 - consecutive slides about the **same thing changing** → **morph**: give89 shared elements the same `id` on both slides + `transition:"morph"` on90 the later one (Bento's signature move — reach for it liberally)91 - a point to **drill into** → a **state slide** (`stateOf` + element `link`)92 - a **hero / full-slide image** → full-bleed image + scrim rect + text,93 with **ken-burns** drift94 - a **sequence / flow / timeline** → a line/`path` with a `dash-march`95 loop, or morph a highlight through the steps96 - a **headline number** → big text + `fx:{countUp:true}`97 - **every cover / divider** → at least one ambient motion98 - **repeated chrome / logo** → keep its `id` stable across slides so it99 morphs in place100 - a **demo clip / recording / soundbite** → a **media** element101 (`kind: video|audio`); embed short clips as a data URI, link big ones by102 URL to keep the file small1034. **Author** using the schema. Keep the full schema and copy-paste recipes104 open: **fetch https://bento.page/agents.md** (it has the element shapes,105 the morph/chart/state/ken-burns snippets, and the gotchas). Respect one106 accent colour, ≤2 typefaces, 96px side margins (right-most x ≤ 1184),107 and write **speaker notes** on each slide.1085. **Self-audit before finishing:**109 - [ ] any numbers rendered as text that should be a **chart**?110 - [ ] do consecutive slides on one subject share **ids + `transition:"morph"`**?111 - [ ] at least one **motion moment** (ken-burns / loop / count-up), esp. the cover?112 - [ ] a drill-down that would work better as a **state slide**?113 - [ ] one accent colour, ≤2 typefaces, 96px margins?114 - [ ] speaker notes on every slide?1156. **Write back** the edited `#bento-doc` block (escaping `<`), or return the116 replacement JSON. Never regenerate the whole HTML file.117118## Critical gotchas119120- **Charts:** bar/line series `data` must be **plain numbers** (`{value,…}`121 item objects coerce to 0 — only pie takes `{name,value}`); colour by122 series, not per bar; `option` is pure JSON, template formatters only123 (`{b}`/`{c}`/`{d}`), never functions.124- **Morph needs deterministic, stable ids** shared across the slides that125 should animate together. Different ids = no morph (elements just cut).126- **Images/fonts must be embedded** as data URIs in `doc.assets` and127 referenced by `"asset:<key>"` — the file stays self-contained.128- **Media:** a `media` element (`kind: video|audio`) embeds short clips as a129 data URI in `src` (self-contained) or references a URL for big files (keeps130 the deck small). `autoplay` runs only in present mode and needs `muted:true`131 for video. Don't embed large videos — they bloat the file.132- **Never regenerate `docId`** when editing an existing deck; it is the133 document's identity. (Fresh decks omit it — the app mints one.)134- `template:true` → every open mints a fresh deck; `readonly:true` → the135 file boots straight into the show with no editor.136137Working examples of every technique: open any template at138https://bento.page and read its `#bento-doc` block.