Bento Slides

Authoring Bento decks

A Bento deck is one self-contained .bento.html file: a compressed app runtime plus the document as plain JSON in one block:

<script type="application/bento+json" id="bento-doc"> { "format":"bento/slides", ... } </script>

• Edit that block only, in place. Leave the runtime untouched.
• render_check.mjs --write writes the block for you. A hand-written splice must escape every < in the JSON as its unicode escape (a backslash followed by u003c), so the block never contains a literal </script> and a build script can find the block's end at the first </script> after the opening tag.
• Chat context (no filesystem): the user copies the JSON out (Save > Copy compact JSON) and pastes your replacement back (Save > Replace from JSON). window.bento.loadDoc(json) does the same from the console.

Before touching an existing deck

• Ask the user to close the deck in their browser. A save from the open tab overwrites your edit. Autosave keeps a recovery snapshot in IndexedDB keyed by docId, so a stale tab offers to "restore" the old version on the next open; tell the user to pick Discard.
• If the #bento-doc block contains "format":"bento/enc", the deck is password-encrypted. Stop and tell the user; plain JSON written over it destroys the ciphertext.
• Leave collab as found. Keys mint at creation and every save writes them, so nearly every saved deck carries ownerPriv: anyone with the file can join its live session.
  • Deleting collab severs the owner from their own room while sent copies keep the old one.
  • Tell the user once that the file contains session keys. Hand-outs: Share > View-only copy. Leaked file: Share > Reset access.
  • Every save also stamps CRDT state into collab.sync; the next open merges it with the room, so elements a script deleted come back. render_check.mjs --write drops collab.sync. If edits still reappear, the owner's other tabs are in the room: set collab.on to false and have the user Share > Reset access.
  • Otherwise set collab.on to false only when the user asks to stop sharing. Change that one field and keep the keys.

Starting from nothing

The user does not need Bento installed; the app ships inside every deck. Fetch the latest release 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"

Verify the download contains id="bento-doc". The block is empty on disk (a browser mints a demo deck on first open), so there is nothing to discard. Omit docId and collab. render_check.mjs --write saves freshly minted keys with sharing off (collab.on:false); the user turns sharing on with Share. Never author a collab object: one without keys never gets any, so Share silently connects nothing.

Starting from a theme

When the user asks for a themed deck or names a theme from bento-themes, use the local clone at ~/git/sammcj/bento-themes if it exists (it may hold unreleased work). Otherwise clone it there: git clone https://github.com/sammcj/bento-themes ~/git/sammcj/bento-themes.

• Pick a theme from the repo README (one section per theme) and themes/<name>/preview/*.png.
• Shell: copy themes/<name>/<Name>.bento.html to <Topic>.bento.html.
• Document: start doc.json from themes/<name>/<Name>.doc.json (full form). Keep theme, fonts, assets, present, meta and layouts. Delete collab, docId and template so the deck is not a template and --write saves it with sharing off.
• Slides: copy the demo slide for each layout you need (its element ids match the layout), give it a unique slide id, and replace its text, data and notes. A layout with a detail state needs its state slide copied too, with stateOf and link updated. Theme layouts carry no role, so compact role placement does not apply.

Workflow

Create a task per step below, each with its completion criterion, then work them to completion.

1. Read the references. references/agents-1.2.3.md (element shapes, chart/state/hidden-slide rules, column arithmetic) and references/format-reference.md (compact form, fields since 1.0.18, runtime rules). Every key, generated from the runtime: https://bento.page/schema/slides.json.
2. Find the document (existing deck). Parse the #bento-doc JSON. Note doc.size, doc.theme, element ids, docId, and whether template or readonly is set. Keep docId unchanged.
3. Classify the source material. For each piece: a stat, a table, a process, a definition to expand, a photo, code?
4. Map each piece to a feature. This step makes it a Bento deck:
   • numbers to compare (trend, magnitude, share) -> a chart element
   • a comparison, spec, pricing or feature grid -> a table element (columns weights + rows of cells + a style object)
   • a point to drill into -> a state slide (stateOf + element link)
   • a hero or full-slide image -> full-bleed image + scrim rect + text
   • a sequence, flow or timeline -> connectors (from/to) or a path
   • a headline number -> big text, one plain number per box
   • source code -> a code element
   • a build across slides -> one slide per step with unnumbered:true on the continuations
   • repeated chrome or logo -> keep its id stable across slides
   • a demo clip, recording or soundbite -> a media element
5. Author doc.json in compact form ("compact": true), per format-reference "Compact form". Its typography and role-placement rules fail silently: read both before writing text. Compact fills size (1280x720) and theme when omitted.
   • Keep one accent colour, at most two typefaces, and 96px side margins (right-most x <= 1184).
   • Write speaker notes on each slide.
   • Size text with compact h:"auto"; otherwise window.bento.measure({html, w, fontSize, fontFamily}) via render_check.mjs --eval, always passing fontFamily.
   • When fanning slides out to several agents, the shared spec lists the type scale (title/body/caption px) and the band tier per slide, as well as colours and columns.
6. Render and write back: render_check.mjs "<Topic>.bento.html" --doc doc.json --write "<Topic>.bento.html" (add --motion if the user asked for animation). In a chat context, return the replacement JSON instead.
7. Fix and re-run until there are no dropped entries or errors, and no warnings on content you authored, then read every PNG. On an existing deck, report warnings about the user's own content (motion, notes, fonts) instead of rewriting it. Overflow, crowding and a dropped chart key are invisible in the JSON and obvious on screen.
8. Self-audit before finishing:
   • any numbers rendered as text that should be a chart?
   • a drill-down that would work better as a state slide?
   • one accent colour?
   • captions baked into raster images flagged to the user?
   • on content slides, does the content reach the bottom of the band, with slack spread between blocks rather than pooled underneath?