Skip to content

armgit / bento

Public Imported from GitHub
0

Bento, the office suite that fits in a file

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.md
index 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 can
author 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 document
lives 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
```json
diff --git a/scripts/postbuild-compress.mjs b/scripts/postbuild-compress.mjs
index 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.mjs
index 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.md
new file mode 100644
index 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.json
index 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",