Bento, the office suite that fits in a file
Working in this repo — agents & tools
Guidance for AI coding agents (Claude Code, Codex, Antigravity, …) and human
contributors. This file is the tool-agnostic contract; Claude Code also
reads CLAUDE.md (the deep architecture guide for slides/). If your tool
only reads one file, read this one, then follow the pointers.
What this project is
bento — office documents as single self-contained HTML files. One file = the
document + viewer + editor; it saves itself, updates itself over a signed
channel, and optionally syncs E2EE through a blind relay. slides/ is the
shipped app. Starting now: bento/spaces (Notion/notes-like),
bento/dash (spreadsheet + tables), bento/vault (document library).
Naming and casing — lowercase everywhere. The platform is bento, the
wordmark is bento/., and apps are bento/slides, bento/spaces,
bento/dash, bento/vault. This applies to UI strings and prose as well as
format constants — do not write "Bento Slides" in new copy. The / in the
wordmark is decorative: anywhere a name is stored or typed (filenames, URLs,
package names) it is plain bento. Full reasoning and the rejected candidates
are in docs/DECISIONS.md — don't reopen them.
Read before writing code
docs/PLATFORM.md— invariants every Bento app must honor. Breaking these bricks files already shipped to users.docs/PARALLEL-WORK.md— branch/merge discipline when many agents work at once (you are probably one of them).docs/DECISIONS.md— settled decisions. Don't relitigate them in code; append new ones.CLAUDE.md— deep architecture + hard-won gotchas, authoritative forslides/internals.docs/collab-design.md— the sync/collab spec + threat model.
Hard rules (each one has broken something before)
- Never let a literal
</script>into a bundle or document block. JSON in the doc block escapes<as<; builders concatenate around it. - The
#bento-docblock stays plaintext, same id, regex-extractable. That's the splice contract (docs/PLATFORM.md) — updaters already shipped in old files are frozen code that depends on it. - Never regenerate a document's
docId. It's the document's identity for recovery, sync, and future merge. - After any change to
slides/src/sync/crdt.ts, runnode scripts/test-sync.ts. The convergence rig has caught 15+ ordering bugs; a green typecheck means nothing for CRDT correctness. - A password-protected deck never carries a plaintext preview of page one.
Saves write a static first-page render into the shell for file-manager
thumbnails (
kernel/src/save.ts,slides/src/preview.ts);bento/encdecks are vetoed and any existing preview is stripped. Runnode scripts/test-preview.tsafter touching that path. - New UI strings go into ALL i18n catalogs. English-string-as-key; never
call
t()in module-level consts. Never take the locale list from prose — including this file. It isLOCALESin that app'sscripts/build-*-i18n.mjs, andls <app>/src/i18n/is the check. This rule said seven for a month after Portuguese made it eight, and bento/dash ships without Portuguese today because a fourth copy of the list still says seven.- Adding a locale touches three places, not one: the catalogue file, the
app's
LOCALES, and any rig with its own copy of the list. Onlybuild-i18n.mjs(slides) errors on a catalogue missing fromLOCALES; the others exit 0 and silently never pack it. dashis the app that is short, and its rig cannot see it. Its rig IS its generator —dash/src/i18n/packed.tssays "GENERATED by scripts/test-dash-i18n.ts" — and that file's ownLOCALES(line 48) has nopt. It reports "every core catalog is complete", truthfully, about seven locales. A generator that grades its own output cannot report a gap in the set it was given.- A rig must derive the list, never restate it.
scripts/test-i18n-coverage.mjsreadsPACKED_LOCALESout of the generatedpacked.ts— copy that, and a fourth copy can never go stale. It covers slides ONLY (coreDiris hardcoded toslides/src/i18n), so spaces and type have no coverage rig at all. Do not assume your app's catalogues are checked by anything. - A locale code is not always a language.
ptis Brazilian inslides/and drifted European inspaces/; no check can see this, because both files are correctly namedpt.ts. See docs/DECISIONS.md, 2026-08-29, before writing or reusing a catalogue for a language with regional variants.
- Adding a locale touches three places, not one: the catalogue file, the
app's
- Never edit
site/— it's generated. Sources aresite-src/and thescripts/build-*.mjstooling. Same fordist-single/. - No AI co-author trailers on commits (no
Co-Authored-By: Claudeor similar), and no bot identities in git history. - Releases are cut locally by the maintainer only. Never touch signing
keys (
~/.bento/release-key.json), never attempt to release, publish, or deploy from an agent session unless the maintainer explicitly asks. - External PRs get provenance checks before merge (
gh api users/<login>) — AI-agent/bot contributions are not merged. - Verify before claiming done: typecheck, build, and exercise the change in a browser when it's user-visible. Report failures honestly.
Authoring a deck as an agent: the compact form
The JSON in #bento-doc is the full document: every element carries every
field, including a dozen defaults no author chose. Write the compact form
instead — "compact": true at the top level, and leave out every field that
equals what the editor would insert (rotation 0, opacity 1, the font stack,
weight 400, centre/middle, line height 1.25, a shape's transparent stroke, a
slide's theme background, transition: "fade" …). x y w h and the type's
content (html, shape, src, option, content, columns/rows) are
always written. Two conveniences: elements may nest arrays (a helper that
returns a card as [bg, title, body] needs no spread), and id may be
omitted — it is minted deterministically as <slideId>-<type>-<index>, so a
re-run yields the same ids.
{ "compact": true, "title": "Q3 review",
"slides": [ { "id": "s1", "elements": [
{ "type": "text", "x": 96, "y": 80, "w": 1088, "h": 100, "html": "Q3 review", "fontSize": 48 },
[ { "type": "shape", "shape": "rect", "x": 96, "y": 220, "w": 500, "h": 300, "fill": "#F3F0EA" },
{ "type": "text", "x": 120, "y": 240, "w": 452, "h": 60, "html": "Revenue" } ] ] } ] }
Two more things a compact text element may do. Leave h out (or write
"h": "auto") and the box is sized to its text on load, measured on the
deck's real fonts — the same number Fit height to text would set; you
cannot know how tall three lines of 24 pt are, the runtime can. Write md
instead of html and it converts exactly as pasted markdown does: **bold**,
*italic*, `code`, ~~strike~~, - bullets (indent two spaces for a
sub-bullet), [caption](https://…); when both are present html wins.
You need not place anything. Give a slide a layout and its elements a
role, leave out geometry and typography, and the layout's frames and type
are used — the same matching the editor's Apply layout does, and slides born
from the same layout share element ids, so their titles morph. An element that
DOES carry x y w h is placed as given, on top. More body elements than the
layout has body slots stack into the slot top-to-bottom, each sized to its
text. A role the layout lacks falls back to the body slot and the load report
says so (dropped carries a note with the path). An image role takes an
image element and puts the picture in the slot.
{ "compact": true, "slides": [
{ "layout": "title-body", "elements": [
{ "role": "title", "md": "Three things went right" },
{ "role": "body", "md": "**Latency** fell 40%." },
{ "role": "body", "md": "**Uptime** held at 99.97%." } ] },
{ "layout": "image-right", "elements": [
{ "role": "title", "md": "The tile" },
{ "role": "body", "md": "It stays put." },
{ "type": "image", "role": "image", "src": "data:image/png;base64,…" } ] } ] }
The built-in layouts and their roles (this list is generated from the code by
scripts/test-slides-compact-layouts.ts, so it cannot drift):
title— title, subtitletitle-content— title, body (also answers totitle-body)two-col— title, body, left, right (alsotwo-column;left/rightare the two body slots)section— title, kickerthree-cards— title, card1, card2, card3 (alsocards)quote— quote, attributionimage-left— image, title, bodyimage-right— title, body, image
A deck's own layouts (full Slide objects, the shape Save slide as layout
writes) may be named the same way.
Load it with window.bento.loadDoc(json) or Save ▾ Replace from JSON…;
window.bento.compact() (or Save ▾ Copy compact JSON) gives a deck back in
this shape. A compact document passes the untrusted shape gate on the way in,
and loadDoc RETURNS what happened:
const r = window.bento.loadDoc(json)
// r === false → not a document at all (nothing changed)
// r.dropped → [{ path: '/slides/0/elements/2/fontSze', reason: 'unknown key for a text element' }, …]
// r.expanded → fields filled from the editor's defaults
// r.fitted → text boxes sized to their text
// r.laidOut → slides placed by layout + role
// r.findings → window.bento.validate() on the loaded deck (overflow, off-canvas, dead links …)
The loop is: load → read dropped and findings → fix the JSON → load
again. A dropped key is one the format does not have (a typo, or a field that
does not exist for that element type); an invalid value is the right key with
the wrong type or range. The FILE is always saved full — the on-disk format is
unchanged and every shipped shell reads it as before. slides/src/compact.ts
and compactload.ts are the whole mechanism; scripts/test-slides-compact.ts
proves the round-trip on the starter deck and the gallery decks, and
scripts/fixtures/agent-decks/ holds decks written this way that must load
clean in CI — add yours there if you find a shape that does not.
Commands
cd slides
npm install
npm run dev # dev server (see .claude/launch.json for ports)
npm run build:single # → dist-single/Bento_Slides.bento.html (the product)
node_modules/.bin/tsc -b # typecheck
node ../scripts/test-sync.ts # CRDT convergence rig (SEEDS/STEPS/ACTORS env)
node ../scripts/test-preview.ts # first-page preview rig (encryption veto, output safety)
node ../scripts/shell-gate.mjs dist-single/Bento_Slides.bento.html # splice conformance
Check your deck
You wrote a deck; now look at it. bento check loads it in headless Chrome —
the real shell, the real fonts — and tells you what the runtime would otherwise
swallow, then hands you pictures:
node scripts/bento-check.mjs deck.bento.html # findings, by slide, with element ids
node scripts/bento-check.mjs doc.json --png out/ # a document JSON in the built shell, + one PNG per slide
node scripts/bento-check.mjs doc.json --json --fail-on warning # machine-readable, strict exit code
The loop: write the document JSON (compact where the shell accepts it) → bento check --png → read findings (text-overflow and table-overflow say how
many px the box is short and on which element; out-of-canvas, dead links, effects that can
never run, unknown keys the gate dropped) → look at contact.png, one image of
every slide, or a single page-NN.png when a finding points at it → fix →
run again. Exit 0 means no finding at or above --fail-on (default error).
Needs Chrome (BENTO_CHROME to point at a binary) and the built shell
(cd slides && npm run build:single, or --shell path).
The document schema
The bento/slides format has a machine-readable schema, generated from the
runtime's own validation tables (slides/src/schema.ts reads what
untrusted.ts accepts; scripts/build-schema.mjs prints it; CI fails if
schema/slides.json is stale). One source, reachable four ways:
- URL —
https://bento.page/schema/slides.json, with a version-pinned twin atschema/slides-<version>.json. Put"$schema": "https://bento.page/schema/slides.json"at the top of a deck you write and any JSON-Schema-aware editor validates it; the runtime strips the key on load and writes it back on save, so every saved deck carries it. - In the file — the Tooling comment at the top of every
.bento.htmlnames the URL, and the saved JSON's first key is$schema. window.bento.schema()— the same JSON, built at runtime, for an agent driving the browser (the shell is compressed, so a text reader cannot see the code; use the URL).https://bento.page/llms.txt— the index: this guide, the schema, the platform invariants, the app.
Which door for which reader: a model that READS the file gets the Tooling
comment, $schema and the URL; a model that DRIVES the app gets schema(),
validate(), measure() and loadDoc().
Repo layout
slides/ Bento Slides app (src/, single-file build)
server/ Cloudflare workers: sync relay, guestbook daemon
scripts/ build, release, signing, guestbook, site tooling
site-src/ authored landing/guestbook/404 pages (site/ is generated)
docs/ architecture, platform spec, releasing, collab design
New apps will live beside slides/ (working names spaces/, dash/); the
shared kernel extraction is tracked in docs/DECISIONS.md.