Skip to content

armgit / bento

Public Imported from GitHub
0

Bento, the office suite that fits in a file

13.6 KB
Raw Blame

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 for slides/ internals.
  • docs/collab-design.md — the sync/collab spec + threat model.

Hard rules (each one has broken something before)

  1. Never let a literal </script> into a bundle or document block. JSON in the doc block escapes < as <; builders concatenate around it.
  2. The #bento-doc block 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.
  3. Never regenerate a document's docId. It's the document's identity for recovery, sync, and future merge.
  4. After any change to slides/src/sync/crdt.ts, run node scripts/test-sync.ts. The convergence rig has caught 15+ ordering bugs; a green typecheck means nothing for CRDT correctness.
  5. 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/enc decks are vetoed and any existing preview is stripped. Run node scripts/test-preview.ts after touching that path.
  6. 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 is LOCALES in that app's scripts/build-*-i18n.mjs, and ls <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. Only build-i18n.mjs (slides) errors on a catalogue missing from LOCALES; the others exit 0 and silently never pack it.
    • dash is the app that is short, and its rig cannot see it. Its rig IS its generator — dash/src/i18n/packed.ts says "GENERATED by scripts/test-dash-i18n.ts" — and that file's own LOCALES (line 48) has no pt. 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.mjs reads PACKED_LOCALES out of the generated packed.ts — copy that, and a fourth copy can never go stale. It covers slides ONLY (coreDir is hardcoded to slides/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. pt is Brazilian in slides/ and drifted European in spaces/; no check can see this, because both files are correctly named pt.ts. See docs/DECISIONS.md, 2026-08-29, before writing or reusing a catalogue for a language with regional variants.
  7. Never edit site/ — it's generated. Sources are site-src/ and the scripts/build-*.mjs tooling. Same for dist-single/.
  8. No AI co-author trailers on commits (no Co-Authored-By: Claude or similar), and no bot identities in git history.
  9. 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.
  10. External PRs get provenance checks before merge (gh api users/<login>) — AI-agent/bot contributions are not merged.
  11. 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, subtitle
  • title-content — title, body (also answers to title-body)
  • two-col — title, body, left, right (also two-column; left/right are the two body slots)
  • section — title, kicker
  • three-cards — title, card1, card2, card3 (also cards)
  • quote — quote, attribution
  • image-left — image, title, body
  • image-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 at schema/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.html names 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.