Bento, the office suite that fits in a file
TypeScript mit-licenseofficeoffice-365office-suiteoffice-toolsoffice365open-sourcepowerpointself-hostedsingle-page-appslidesslideshareslideshowslideshow-galleryslideshow-makerslideshows
Docs: coordination layer for multi-app, multi-agent development
nyblnet9ba96db2c62f
diff --git a/AGENTS.md b/AGENTS.mdnew file mode 100644index 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.mdindex 47ac06c4..8017c033 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -1,7 +1,21 @@# Bento — self-contained office documentsOne 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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