Bento, the office suite that fits in a file
TypeScript mit-licenseofficeoffice-365office-suiteoffice-toolsoffice365open-sourcepowerpointself-hostedsingle-page-appslidesslideshareslideshowslideshow-galleryslideshow-makerslideshows
v0.9.2: teach AI agents to use Bento's features (embedded briefing + cookbook + skill)
nyblnet1396d2f55d8b
diff --git a/docs/agents.md b/docs/agents.mdindex 9fbc07ce..a0602980 100644--- a/docs/agents.md+++ b/docs/agents.md@@ -2,7 +2,9 @@*Drop this file into your context (or point your harness at it) and you canauthor and edit Bento presentations directly. Also published at-[bento.page/agents.md](https://bento.page/agents.md).*+[bento.page/agents.md](https://bento.page/agents.md). For a harness+(Claude Code / Cowork), the packaged skill is at+[bento.page/skills/bento-deck/SKILL.md](https://bento.page/skills/bento-deck/SKILL.md).*A Bento deck (`*.bento.html`) is a self-contained HTML file. The documentlives in ONE plaintext block near the top:@@ -25,6 +27,77 @@ Two ways to work with it:In the browser console: `window.bento.doc` (read) /`window.bento.loadDoc(json)` (write, undoable).+---++## Make a GREAT deck, not just a correct one++**Read this section first — it is the difference between a wall of text and a+Bento deck.** The format's whole value is motion, morph, charts and+interactivity. A correct-but-static result (bullets on slides) wastes it and+is the #1 failure mode. The move is to look at the *source material* and map+each kind of content to the feature built for it:++| When the material is… | Reach for | Why |+|---|---|---|+| numbers, %, quantities, "A vs B", **any table** | a **chart** element | data as bars/lines reads instantly; as bullets it doesn't |+| consecutive slides about the **same thing changing** (before/after, process steps, a metric across stages) | **morph**: same element `id` on both slides + `transition:"morph"` on the later one | the shared elements glide; this is Bento's signature and is *almost always missed* |+| a point to **drill into** (a definition, "click to see how", a sub-topic) | a **state slide** (`stateOf` + element `link`) | keeps the linear story clean; the detail is one click away |+| a **hero / full-slide image** | full-bleed image + scrim rect + text, with **ken-burns** | static photos feel dead; a slow drift feels intentional |+| a **sequence / flow / timeline / connection** | a line or `path` with a **`dash-march` loop**, or morph a highlight through the steps | motion carries the eye along the sequence |+| a **headline number** | big text + `fx:{countUp:true}` | the count-up earns attention |+| **every cover / section divider** | at least **one ambient motion** (ken-burns, an orbiting accent) | a still cover is a missed first impression |+| **repeated chrome / a logo** | keep its `id` stable across slides | it morphs in place instead of popping on every slide |++### Copy-paste recipes++**Morph a title + accent bar between two slides** — identical ids, `transition:"morph"`:+```json+// slide 1+{ "id":"s1","transition":"none","elements":[+ { "id":"headline","type":"text","x":96,"y":140,"w":900,"h":200,"html":"Big claim.","fontSize":120,"fontWeight":900,"color":"#111","align":"left","valign":"top","lineHeight":1,"rotation":0,"opacity":1 },+ { "id":"bar","type":"shape","shape":"rect","x":96,"y":380,"w":320,"h":16,"fill":"#E8442E","stroke":"none","strokeWidth":0,"radius":0,"rotation":0,"opacity":1 } ] }+// slide 2 — same ids, new frames → they animate+{ "id":"s2","transition":"morph","elements":[+ { "id":"headline","type":"text","x":96,"y":84,"w":500,"h":80,"html":"Big claim.","fontSize":40,"fontWeight":900,"color":"#888","align":"left","valign":"top","lineHeight":1,"rotation":0,"opacity":1 },+ { "id":"bar","type":"shape","shape":"rect","x":96,"y":170,"w":16,"h":450,"fill":"#E8442E","stroke":"none","strokeWidth":0,"radius":0,"rotation":0,"opacity":1 } ] }+```++**A bar chart from a table** — bar/line data is PLAIN NUMBERS (see chart rules below):+```json+{ "id":"c1","type":"chart","x":96,"y":260,"w":1088,"h":380,"rotation":0,"opacity":1,"preset":"bar","option":{+ "xAxis":{"type":"category","data":["2022","2023","2024","2025"]},+ "yAxis":{"type":"value"},+ "series":[{"type":"bar","data":[420,780,1300,2450],"itemStyle":{"color":"#141310"},"barWidth":90}],+ "tooltip":{"trigger":"item","formatter":"{b}: {c}"} },+ "fx":{"enter":"fade-up"} }+```++**A state slide reached by clicking a node** — parent slide has the clickable element, the state lives adjacent:+```json+// on the parent slide, an element the viewer clicks:+{ "id":"node-ingest","type":"shape","shape":"ellipse","x":330,"y":180,"w":74,"h":74,"fill":"#0B0E1E","stroke":"#7A5CFF","strokeWidth":2,"radius":0,"rotation":0,"opacity":1,"link":"state-ingest" }+// a hidden state slide (arrow keys skip it; ← returns to parent):+{ "id":"state-ingest","stateOf":"parent-slide-id","transition":"morph","name":"INGEST","elements":[ /* … */+ { "id":"dismiss","type":"shape","shape":"rect","x":0,"y":0,"w":1280,"h":720,"fill":"rgba(0,0,0,0)","stroke":"none","strokeWidth":0,"radius":0,"rotation":0,"opacity":1,"link":"parent-slide-id" } ] }+```++**Full-bleed hero image with ken-burns + scrim + text:**+```json+{ "id":"photo","type":"image","x":0,"y":0,"w":1280,"h":720,"src":"asset:hero","fit":"cover","radius":0,"rotation":0,"opacity":1,"fx":{"ambient":"kenburns","ken":{"dir":"drift","scale":1.09,"duration":22}} },+{ "id":"scrim","type":"shape","shape":"rect","x":0,"y":0,"w":1280,"h":720,"fill":"rgba(10,14,26,0.55)","stroke":"none","strokeWidth":0,"radius":0,"rotation":0,"opacity":1 },+{ "id":"htitle","type":"text","x":96,"y":460,"w":1000,"h":180,"html":"On top of the photo.","fontSize":76,"fontWeight":800,"color":"#fff","align":"left","valign":"top","lineHeight":1.05,"rotation":0,"opacity":1,"fx":{"enter":"fade-up"} }+```+(Embed the image as a data URI in `doc.assets` under key `hero`, then reference `"asset:hero"` — the file must stay self-contained.)++### Before you finish — self-audit++- [ ] Any numbers rendered as text that should be a **chart**?+- [ ] Do consecutive slides on one subject share element **ids + `transition:"morph"`**?+- [ ] At least one **motion moment** (ken-burns / loop / count-up), especially the cover?+- [ ] A drill-down that would work better as a **state slide**?+- [ ] One accent colour, at most two typefaces, **96px** side margins (right-most x ≤ 1184)?+- [ ] **Speaker notes** written on each slide (they travel in the file and double as the talk track)?+## Minimal valid document```jsondiff --git a/scripts/postbuild-compress.mjs b/scripts/postbuild-compress.mjsindex 3e9aa392..7ad21483 100644--- a/scripts/postbuild-compress.mjs+++ b/scripts/postbuild-compress.mjs@@ -69,18 +69,51 @@ const splashCss = (() => {})()const TOOLING_COMMENT = `<!--- Tooling note (for AI assistants and scripts):- - The DOCUMENT lives in the script block of type "application/bento+json"- with id "bento-doc" below, as plain readable JSON. That block is the only part that changes- between saves; everything else is the fixed application shell.- - To modify this deck programmatically or with an AI: edit that JSON (or- replace the block's text), never regenerate the whole file. In the app:- About dialog → "Copy document JSON" / "Replace document from JSON".- - The base64 blocks near the end are the DEFLATE-compressed application- runtime (open source: https://bento.page) — no user content inside.- - In a running file, window.bento exposes { doc, serialize(), comments(),- loadDoc(json), updates, i18n } for automation.- -->`+ ════════════════════════════════════════════════════════════════════════+ AI AGENTS / TOOLING — READ THIS BEFORE EDITING THIS DECK+ ════════════════════════════════════════════════════════════════════════+ Full authoring guide (schema + copy-paste snippets): https://bento.page/agents.md++ THE MECHANICS+ · The document is the ONE script block of type "application/bento+json",+ id "bento-doc", below — plain readable JSON. Edit THAT block in place;+ never regenerate the whole file. Escape every "<" in the JSON as \\u003c.+ · The base64 blocks near the end are the DEFLATE-compressed app runtime+ (open source, https://bento.page) — no user content, leave them alone.+ · In a running file, window.bento exposes { doc, serialize(), loadDoc(json),+ comments(), updates, i18n }. In the app UI: About → Copy / Replace JSON.++ MAKE A GREAT DECK, NOT JUST A CORRECT ONE+ Bento's whole point is motion + interactivity. A wall of text slides wastes+ it. When the source material contains ↓, reach for the feature:+ · numbers / %, quantities, "A vs B", any table → a CHART element+ (preset bar|line|pie|scatter). Never list data as bullet text.+ · consecutive slides about the SAME thing changing (before/after, process+ steps, a metric across stages) → give the shared elements the SAME id+ on both slides and set the later slide's transition to "morph". This is+ Bento's signature move — use it liberally; it is almost always missed.+ · a point to drill into (a definition, "click to see how") → a STATE+ slide (stateOf: "<parent-id>" + an element link: "<state-id>").+ · a hero / full-slide image → full-bleed image (0,0,1280,720) + a scrim+ rect + text on top, with a slow ken-burns drift+ (fx:{ambient:"kenburns",ken:{dir:"drift",scale:1.08,duration:20}}).+ · a sequence / flow / timeline / connection → a line or path with a+ loop (fx:{loop:{type:"dash-march",...}}), or morph a highlight through it.+ · a headline number → big, with fx:{countUp:true}.+ · every cover / section divider → at least ONE ambient motion so it is+ not dead static.+ · repeated chrome or a logo → keep its id stable across slides so it+ morphs in place instead of popping.++ BEFORE YOU FINISH — self-audit:+ [ ] 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, at most two typefaces, 96px side margins?+ [ ] speaker notes written (they travel in the file)?+ ════════════════════════════════════════════════════════════════════════+-->`// --- loader (plain script, runs at end of body; no "</script>" literal) -----const loader = `diff --git a/scripts/release.mjs b/scripts/release.mjsindex 1c8aa1f0..daa29791 100644--- a/scripts/release.mjs+++ b/scripts/release.mjs@@ -89,6 +89,9 @@ execFileSync('node', [join(root, 'scripts/build-example-decks.mjs'), join(site,// The agent guide — the runnable version of the "designed for AI" claim.cpSync(join(root, 'docs/agents.md'), join(site, 'agents.md'))+// The harness skill (Cowork / Claude Code), fetchable + droppable.+mkdirSync(join(site, 'skills/bento-deck'), { recursive: true })+cpSync(join(root, 'skills/bento-deck/SKILL.md'), join(site, 'skills/bento-deck/SKILL.md'))// 404 — of course it's a deck (see build-404-deck.mjs + site-src/404.html).execFileSync('node', [join(root, 'scripts/build-404-deck.mjs'), join(site, '404.bento.html')], { stdio: 'inherit' })diff --git a/skills/bento-deck/SKILL.md b/skills/bento-deck/SKILL.mdnew file mode 100644index 00000000..c4af32f3--- /dev/null+++ b/skills/bento-deck/SKILL.md@@ -0,0 +1,80 @@+---+name: bento-deck+description: >-+ Author and edit Bento presentations — single-file .bento.html decks whose+ document is plain JSON in a "#bento-doc" script block. Use when creating or+ improving a Bento slide deck from source material: it maps content to the+ right feature (charts, morph transitions, state slides, ken-burns, motion+ paths) instead of producing static text slides, then writes the document+ JSON in place. Full schema + recipes at https://bento.page/agents.md.+---++# 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+`<` 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 (*About → Copy document JSON*) and pastes your replacement+back (*Replace document from JSON*); `window.bento.loadDoc(json)` does it from+the console.++## 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.+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 / %, quantities, "A vs B", **any table** → a **chart** element+ - 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+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.+- **Never regenerate `docId`** when editing; it is the document's identity.+- `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.diff --git a/slides/package.json b/slides/package.jsonindex 0aa2ea17..a35cb0ac 100644--- a/slides/package.json+++ b/slides/package.json@@ -1,7 +1,7 @@{"name": "bento-slides","private": true,- "version": "0.9.1",+ "version": "0.9.2","type": "module","scripts": {"dev": "vite",