Skip to content

armgit / bento

Public Imported from GitHub
0

Bento, the office suite that fits in a file

Docs: coordination layer for multi-app, multi-agent development

nyblnet9ba96db2c62f
diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 00000000..5a935fb7
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,77 @@
+# 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 (Bento Slides). Two more are starting: **Bento Spaces**
+(Notion/notes-like) and **Bento Dash** (data/spreadsheet) — names provisional,
+see `docs/DECISIONS.md`.
+
+## 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. **New UI strings go into ALL i18n catalogs** (ja, zh-Hans, zh-Hant, es, fr,
+ de, it). English-string-as-key; never call `t()` in module-level consts.
+6. **Never edit `site/`** — it's generated. Sources are `site-src/` and the
+ `scripts/build-*.mjs` tooling. Same for `dist-single/`.
+7. **No AI co-author trailers on commits** (no `Co-Authored-By: Claude` or
+ similar), and no bot identities in git history.
+8. **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.
+9. **External PRs get provenance checks** before merge (`gh api users/<login>`)
+ — AI-agent/bot contributions are not merged.
+10. **Verify before claiming done**: typecheck, build, and exercise the change
+ in a browser when it's user-visible. Report failures honestly.
+
+## Commands
+
+```sh
+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)
+```
+
+## 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`.
diff --git a/CLAUDE.md b/CLAUDE.md
index 47ac06c4..8017c033 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -1,7 +1,21 @@
# Bento — self-contained office documents
One HTML file = the document + viewer + editor. See `README.md` for the vision.
-`slides/` is the first app (PowerPoint replacement); docs and sheets come later.
+`slides/` is the first app (PowerPoint replacement); **Bento Spaces**
+(Notion/notes-like) and **Bento Dash** (data/spreadsheet) are starting —
+names provisional.
+
+## Multi-app coordination (read first when working beyond slides/)
+
+- `docs/PLATFORM.md` — invariants EVERY Bento app must honor (splice contract,
+ docId, format additivity, collab, signed updates). Breaking these bricks
+ shipped files.
+- `docs/PARALLEL-WORK.md` — ownership zones + branch/merge discipline for the
+ many parallel agents/tools working on this repo. Kernel-zone changes are
+ serialized, never parallelized.
+- `docs/DECISIONS.md` — append-only decision log. Read before non-trivial
+ work; append when you settle something other agents could contradict.
+- `AGENTS.md` — the tool-agnostic contract (Codex/Antigravity read this).
## Architecture (slides/)
diff --git a/docs/DECISIONS.md b/docs/DECISIONS.md
new file mode 100644
index 00000000..eab1e092
--- /dev/null
+++ b/docs/DECISIONS.md
@@ -0,0 +1,75 @@
+# Decision log
+
+Append-only. Newest first. One entry per settled decision that a parallel
+agent (or future session) might otherwise re-open or contradict. Keep entries
+to a few lines: **what** was decided, **why**, and where the details live.
+Reversing a decision = a new entry that supersedes the old one, not an edit.
+
+Format:
+
+```
+## YYYY-MM-DD — Title
+Decision. Why. Pointers.
+```
+
+---
+
+## 2026-07-24 — Suite expansion: Bento Spaces and Bento Dash
+Two new apps begin: **Bento Spaces** (Notion/notes-like) and **Bento Dash**
+(data/spreadsheet). Names provisional. Development fans out across parallel
+agents and multiple tools (Claude Code, Codex, Antigravity) — coordination
+rules in `docs/PARALLEL-WORK.md`, platform contract in `docs/PLATFORM.md`.
+Planned pre-fan-out groundwork: extract the shared kernel (monorepo layout,
+apps beside `slides/`), add per-PR CI validation gates (typecheck +
+build:single + splice conformance + test-sync). Releases stay local/signed
+regardless of CI.
+
+## 2026-07-24 — Hold marketing-surface i18n
+Don't localize the bento.page landing page or README yet: the landing page
+will be rebuilt around the multi-app suite, so translations now would only
+drift. App UI i18n (7 locales) is the localization that matters and already
+ships. Revisit once the new landing page is stable.
+
+## 2026-07-24 — No bot/AI-agent identities in git history
+External PRs get provenance review before merge (`gh api users/<login>`);
+scatter-bot/AI-agent contributions are declined. A bot's merged PR was
+scrubbed from history via filter-repo + force-push, and `main` is now
+branch-protected (1 required review, no force-pushes). Human contributors'
+authorship is preserved normally.
+
+## 2026-07-22 — v1.0.7 launch (Show HN) and post-launch fixes
+Launched publicly (#1 on HN, ~1000 pts). Post-launch priorities were driven
+by thread feedback: collab focus-steal fix, chart zero-baseline for negative
+values, mobile-Safari pinch, reduce-motion mode — all shipped in v1.0.8
+alongside panel UI for community format features (text gradient, text-stroke,
+blur/blend, backdrop-filter). Community format features are accepted when
+additive + composable (unknown fields preserved; effects compose).
+
+## v1.0.7 — Morph identity decoupled from element id
+Elements carry optional `morphId` overriding the morph pairing;
+`data-flip-id = morphId || id`. `id` stays the stable identity (selection,
+anchors, CRDT). Chosen over mutating ids, which would have broken comment
+anchors and collab node identity. Details: CLAUDE.md (render.ts section).
+
+## v0.9.x — Charts are in-house (ECharts removed)
+ECharts was 630KB (~47% of the shell); replaced with charts-lite interpreting
+the same option SHAPE (pure JSON, no functions). Exotic configs degrade
+gracefully rather than crash. Don't re-add a chart dependency; extend
+charts-lite instead. Details: CLAUDE.md (charts section).
+
+## v0.9.x — Collab credentials mint-at-creation, dormant until shared
+Decks are born collab-capable but never auto-connect unless the doc arrived
+carrying collab or the user opted in — fresh templates/demos must never phone
+home. Read-only and writer roles are enforced cryptographically at the blind
+relay, not honour-system. Spec: docs/collab-design.md.
+
+## v0.x — Releases are cut locally, never in CI
+The signing key never leaves the maintainer's machine; the signed bytes are
+the served bytes. CI may validate (typecheck/build/gates) but never signs,
+publishes, or deploys. Runbook: docs/RELEASING.md.
+
+## v0.x — Single-file architecture is the product
+One HTML file = document + viewer + editor, working offline from file://.
+The splice contract on `#bento-doc` is frozen forever (shipped updaters
+depend on it). Everything else is negotiable; this isn't. See
+docs/PLATFORM.md §1–2.
diff --git a/docs/PARALLEL-WORK.md b/docs/PARALLEL-WORK.md
new file mode 100644
index 00000000..93d19356
--- /dev/null
+++ b/docs/PARALLEL-WORK.md
@@ -0,0 +1,87 @@
+# Parallel work — discipline for many agents, many tools
+
+Bento development runs many parallel agents (Claude Code, Codex, Antigravity,
+…) across multiple apps. These tools share **nothing but this repository** —
+no memory, no chat context. So the repo is the coordination surface, and these
+rules exist to keep N parallel workstreams from dissolving into merge hell.
+(Empirically: 11 parallel PRs once produced cascading conflicts on `render.ts`,
+`i18n/*`, and `CHANGELOG.md` — every rule here traces back to that.)
+
+## 1. Ownership zones
+
+- **App zones** — `slides/`, and (as they land) `spaces/`, `dash/`: parallel
+ work is safe *within different apps*. Agents working on different apps must
+ not touch each other's app directories.
+- **Kernel zone** — shared machinery (save/splice, sync engine + relay,
+ update, i18n runtime, build tooling; see `docs/PLATFORM.md` §9):
+ **serialize, don't parallelize.** One coordinated change at a time, reviewed
+ against the platform invariants. If your app task needs a kernel change,
+ stop, make (or request) the kernel change as its own small PR, land it,
+ then continue.
+- **Ops zone** — `server/`, `scripts/`, `site-src/`: maintainer-coordinated;
+ relay changes have deploy-order constraints (`docs/PLATFORM.md` §5).
+
+## 2. Branch & PR discipline
+
+- One branch = one agent = one concern. Never share a branch between agents
+ or tools.
+- Small, single-purpose PRs. A PR that "also fixes" something unrelated will
+ conflict with the agent that was assigned that something.
+- **Integrate frequently.** Long-lived branches are where conflicts breed;
+ rebase/merge from `main` at least daily while a branch is open.
+- `main` is branch-protected (1 review, no force-push). Merge order for a
+ batch: independent zones first, then known-overlapping PRs one at a time,
+ re-checking mergeability between each.
+- Every PR body states: what changed, how it was verified (commands run,
+ browser-tested or not), and any platform invariant it touches.
+
+## 3. Known conflict magnets (pre-empt them)
+
+- **`CHANGELOG.md`** — every feature branch appends to `[Unreleased]`. Keep
+ entries as one self-contained block; when apps multiply, each app gets its
+ own changelog (`slides/CHANGELOG.md`, …).
+- **i18n catalogs** — append-only additions at the TOP of each catalog map;
+ never reorder or reformat existing entries. All 7 catalogs in the same PR
+ as the source string.
+- **`render.ts` / shared modules** — additive features must COMPOSE (blur +
+ blend + backdrop all coexist; gradient + stroke coexist). When resolving a
+ conflict between two features, the answer is almost always "keep both".
+- **Version/release files** (`package.json` version, manifests) — maintainer
+ only, at release time.
+
+## 4. Tool assignment
+
+Assign tools per app, not per file: mixing three tools' edits inside one
+module means reconciling three styles and three context gaps. A reasonable
+split is one tool as the primary for each app + one doing cross-cutting
+review. Whatever the split, record it in `docs/DECISIONS.md` so every session
+of every tool can see it.
+
+## 5. Verification bar (before any PR is opened)
+
+- `node_modules/.bin/tsc -b` clean in the affected app
+- `npm run build:single` succeeds (the single-file build IS the product)
+- `node scripts/test-sync.ts` if anything under `sync/` changed
+- user-visible changes exercised in a real browser (dev server), not assumed
+- i18n: new strings present in all catalogs (`x-pseudo` audit catches strays)
+- no edits under generated dirs (`site/`, `dist-single/`)
+
+## 6. Coordination artifacts (the shared brain)
+
+- `docs/DECISIONS.md` — append-only decision log. Before starting non-trivial
+ work: read it. After settling anything another agent could contradict:
+ append to it (date, decision, why, owner). Decisions live here, not in any
+ one tool's chat history.
+- `docs/PLATFORM.md` — the invariants; change only with maintainer sign-off.
+- `AGENTS.md` / `CLAUDE.md` — behavioral contract + deep architecture.
+- Work assignment lives with the maintainer (issues/task list); an agent that
+ finds adjacent-but-out-of-scope work files it as a note or issue instead of
+ expanding its own PR.
+
+## 7. What agents never do
+
+- Release, publish, deploy, or touch signing keys (maintainer-only, local).
+- Rewrite history or force-push shared branches.
+- Merge external contributors' PRs without provenance review.
+- "Fix" another in-flight branch's code from their own branch.
+- Add AI co-author trailers or bot identities to commits.
diff --git a/docs/PLATFORM.md b/docs/PLATFORM.md
new file mode 100644
index 00000000..047e6ec2
--- /dev/null
+++ b/docs/PLATFORM.md
@@ -0,0 +1,145 @@
+# The Bento platform — invariants every app must honor
+
+Bento is growing from one app (Slides) into a suite (Spaces, Dash, …). This
+document is the contract that makes them all *Bento*: the properties a file
+must keep so that shipped documents — including ones saved years ago —
+continue to open, save, update, and sync. **Breaking an invariant here doesn't
+break the build; it bricks files that are already on users' disks.**
+
+`slides/` is the reference implementation for everything below. When this doc
+and the code disagree, the code that *shipped* wins — fix the doc.
+
+## 1. One file is the product
+
+A Bento document is a single self-contained HTML file carrying the document
+data, the viewer, and the editor. It must work from `file://`, from a static
+host, and from an email attachment — no backend, no CDN, no network required
+to open, edit, present, or save. Anything that adds a runtime network
+dependency to the core document lifecycle is off-platform.
+
+Byte order of a shipped shell (postbuild-compress):
+`chrome → NOTICE → tooling comment → plaintext #bento-doc → splash → compressed payloads`.
+Runtime JS/CSS ship deflated in `bento/deflate-b64` script blocks with a ~1KB
+loader (DecompressionStream → blob import).
+
+## 2. The splice contract (FROZEN)
+
+Self-save and self-update work by re-splicing the document block into a shell.
+Updaters embedded in already-shipped files are frozen code, so every future
+build of every app must keep:
+
+- a `<script type="application/bento+json" id="bento-doc">` block that is
+ **plaintext** (never inside the compressed payloads), same id, forever;
+- block content that is JSON with `<` escaped as `<` — it can never
+ contain `</script>`;
+- a file that survives `DOMParser → splice → outerHTML` round-trips, with
+ balanced script tags and a v0.1.0-style *text* splice still producing a
+ well-formed document.
+
+`scripts/release.mjs` runs a conformance gate on all of this before signing.
+New apps must run the same gate (or an app-specific equivalent with identical
+checks) before any release.
+
+## 3. Document identity & format
+
+- `doc.type` names the format (`bento/slides`; provisionally `bento/spaces`,
+ `bento/dash`) with an integer format version.
+- **Formats are additive.** Every version opens files from every earlier
+ version; unknown fields are preserved, not stripped. Breaking reads of old
+ files is not an option — there is no server to migrate them.
+- `docId` (uuid) is minted once at creation/load and never regenerated. It
+ keys autosave recovery, collab identity, and future sync/merge. "Duplicate
+ as new deck"-style flows mint a fresh `docId` + fresh collab creds — that is
+ the *only* sanctioned way an id changes.
+- Locale/language never enters the document format; i18n follows the viewer.
+
+## 4. Save, autosave, encryption
+
+- Self-save: capture the pristine shell at boot, swap the `#bento-doc` block,
+ re-serialize. File System Access API first, download fallback.
+- Autosave (IndexedDB) keeps a latest-recovery snapshot + a capped version
+ timeline, keyed by `docId`. Read-only players skip autosave.
+- Password-protected docs use the `bento/enc` envelope (PBKDF2-SHA-256 300k →
+ AES-GCM-256 over the doc JSON) *inside* the plaintext block — the splice
+ contract still holds. **Encrypted docs are never snapshotted to IndexedDB in
+ plaintext**, and every write-back path stays encrypted while the password is
+ held in memory.
+
+## 5. Collaboration (E2EE, blind relay)
+
+Authoritative spec: `docs/collab-design.md`. The non-negotiables:
+
+- The relay stores/relays **ciphertext only** (AES-GCM; key in `doc.collab.key`,
+ never sent to the server). Room ids are random or key-committed — never the
+ `docId`, never derived from content.
+- **The saved file is the capability**: opening a copy joins the session.
+ Reader copies strip private keys (`writerPriv`, `ownerPriv`, invites);
+ read-only is enforced cryptographically by the relay, not honour-system.
+- Credentials are minted at creation but a never-saved/never-shared doc stays
+ **dormant** — a fresh template or demo must never phone home.
+- Engine changes (`sync/crdt.ts`) require the convergence rig
+ (`node scripts/test-sync.ts`) before merge. No exceptions.
+- Relay changes require `wrangler deploy` and must stay backward-compatible
+ with already-shipped clients (deploy relay before client when a handshake
+ changes).
+
+## 6. Signed self-update
+
+- Shipped files check `https://bento.page/releases/<app>/manifest.json`
+ (user-initiated or launch check) and verify: ECDSA P-256 signature over the
+ manifest payload against the `PUBLIC_KEY_JWK` embedded in the shell, sha256
+ of the fetched shell, and **version monotonicity**.
+- Manifest shape: `{ payload: "<json string>", sig: "<b64>" }` where payload
+ carries `{ app, version, sha256, url, at }`.
+- The signing key lives offline (`~/.bento/release-key.json`), never in the
+ repo or CI. Releases are cut locally so the signed bytes are the served
+ bytes (`docs/RELEASING.md`). Updates write a NEW file or keep an explicit
+ FSA handle — the original stays as rollback.
+- All apps share the release channel pattern; each app gets its own manifest
+ path under `releases/`.
+
+## 7. AI round-trip
+
+The **document JSON** is the interchange unit for AI tooling — chat models
+can't emit multi-MB files. Every app exposes: copy document JSON / replace
+document from JSON (undoable), plus a scripting surface on `window.bento`
+(`doc`, `serialize()`, `loadDoc(json)`, …). The shell carries a tooling
+comment pointing agents at `#bento-doc` and this API. Keep model JSON pure
+data — template strings over functions (see charts: formatters are `{b}/{c}`
+templates, never code).
+
+## 8. i18n
+
+~1KB `t()` with English-string-as-key (missing key = English). Catalogs are
+compiled in; new UI strings must land in **all** catalogs in the same PR.
+Never call `t()` at module scope (frozen at import). `select()` localizes
+display labels only — model values stay English words. Audit with
+`setLocale('x-pseudo')`.
+
+## 9. What is kernel vs what is app
+
+Shared (extract once, evolve carefully, serialize changes — see
+`docs/PARALLEL-WORK.md`):
+save/splice, autosave, encryption, collab engine + relay protocol, signed
+update, i18n runtime, compressed-shell build + conformance gate, and (for
+Slides+Dash) the charts engine and table rendering.
+
+Per-app (own it, don't prematurely abstract):
+the document model, the renderer, the editor UX, starter documents, panels.
+
+## 10. New-app checklist
+
+A new Bento app is on-platform when it:
+
+- [ ] builds to ONE self-contained HTML file passing the §2 conformance gate
+- [ ] declares `doc.type` + format version; opens its own older files
+- [ ] mints and preserves `docId` per §3
+- [ ] self-saves (FSA + download) and autosaves per §4
+- [ ] supports the `bento/enc` envelope per §4 (or explicitly documents why not yet)
+- [ ] ships collab dormant-by-default per §5, or ships without collab wired
+ rather than with a half-secure version
+- [ ] verifies signed updates per §6 with its own manifest path
+- [ ] exposes the AI round-trip surface per §7
+- [ ] uses the shared i18n runtime per §8
+- [ ] has a starter document that demos the app honestly
+- [ ] documents its model in its own CLAUDE/README section