Bento, the office suite that fits in a file
TypeScript mit-licenseofficeoffice-365office-suiteoffice-toolsoffice365open-sourcepowerpointself-hostedsingle-page-appslidesslideshareslideshowslideshow-galleryslideshow-makerslideshows
Docs: record what language packs actually became
nyblnete3faca61f894
diff --git a/docs/DECISIONS.md b/docs/DECISIONS.mdindex 1c7b816d..d3e9ceed 100644--- a/docs/DECISIONS.md+++ b/docs/DECISIONS.md@@ -14,6 +14,54 @@ Decision. Why. Pointers.---+## 2026-07-26 — A language pack lives in the FILE and nowhere else++No browser-local install. A "keep it on this computer" option (localStorage)+was **built and then removed**, because `localStorage` is scoped per ORIGIN+and that is fatally misaligned with how Bento is used: the download comes from+`bento.page` (an https origin) and the file is then opened from disk (a+`file://` origin). A language added on the website was therefore GONE the+moment the user saved the deck and reopened it locally — the exact journey the+product encourages, and "I added Korean and it vanished" is not a bug a user+can diagnose.++One home also matches the platform: the file *is* the software, so a language+belongs to the deck. The trade — adding a language requires saving the file —+is stated plainly in the UI ("Added when you next save") rather than hidden.+Adding is staged on click and written on the next save because on browsers+without File System Access, writing on click means silently downloading a+second copy of the user's deck.++Corollary: anything that remembers pack *content* outside the file+reintroduces this. Viewer *preferences* (locale, reduce-motion) stay+browser-local on purpose; that asymmetry is deliberate. Details:+`docs/i18n-packs.md`, `slides/src/packs.ts`.++## 2026-07-26 — The pack carrier is generic; pack POLICY is not. This is not a plugin system.++The kernel mechanism is already extension-agnostic and should stay that way:+`registerShellBlocks` / `readShellBlocks` (`kernel/src/save.ts`) carry+arbitrary typed blocks in the shell and know nothing about languages, and+`registerUpdatePrepare` (`kernel/src/update.ts`) is a generic "refresh+version-bound extras" hook. Signature verification and hash pinning are being+made generic in the kernel too (branch `claude/i18n-pack-verify`). Reuse all+of that freely.++**Do not generalize the policy.** Language packs are DATA and their worst case+is bounded — a tampered or stale pack shows wrong or English words. That bound+is why degrade-per-string, keep-on-refresh-failure, and auto-refresh on update+are the right rules *for packs*.++Anything carrying CODE is categorically different: unbounded failure (it would+hold the document, the file handle, and the collab keys), and it breaks the+property that makes self-update trustworthy — that the shell only ever runs+bytes from a signed release. Such a thing would need its own policy (pinned at+install, never auto-refreshed) and must not inherit the pack rules by reusing+the pack machinery.++So: reuse the carrier and the crypto; do not treat "we have packs" as evidence+that a plugin system is designed or wanted. It is not.+## 2026-07-25 — i18n: a bundled core of 9 languages, everything else a signed packThe 7 non-English catalogs cost **115,572 B** of the shell even after key-oncediff --git a/docs/PLATFORM.md b/docs/PLATFORM.mdindex 9292eee4..12a94950 100644--- a/docs/PLATFORM.md+++ b/docs/PLATFORM.md@@ -30,8 +30,13 @@ 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+- block content that is JSON with `<` escaped as `\u003c` — it can nevercontain `</script>`;+- the SAME escaping on every other plaintext data block the shell carries+ (`application/bento+*`, written by `registerShellBlocks` — language packs+ today): their bodies are not authored by us, so an unescaped one could+ close its own block or forge a second `#bento-doc` opening tag for an old+ updater to splice into;- a file that survives `DOMParser → splice → outerHTML` round-trips, withbalanced script tags and a v0.1.0-style *text* splice still producing awell-formed document.@@ -123,6 +128,27 @@ see `i18n-packs.md`. Packs are additive — a file that never fetches one behaveexactly as before — and both tiers fall back per string to the English key,which is what lets a stale or partial pack degrade instead of break.+Four pack rules are platform-level, not app choices:++- **A pack lives in the FILE and nowhere else.** No browser-local copy: the+ download comes from an https origin and the file is then opened from+ `file://`, so anything stored per-origin vanishes on the journey the product+ encourages. A pack rides in an `application/bento+lang` block written by+ `registerShellBlocks` (kernel `save.ts`), under the same `\u003c`-escaping+ and the same §2 splice contract as `#bento-doc` — `scripts/shell-gate.mjs`+ proves a pack-carrying shell conformant, with an adversarial pack, on every+ build.+- **Adding is staged, and written on the next save.** Writing on click means a+ silent second download of the user's deck on every browser without File+ System Access.+- **Self-update carries packs forward** and refreshes them for the incoming+ version (`registerUpdatePrepare` in kernel `update.ts`), best effort — a pack+ that cannot be re-fetched is kept, never dropped.+- **Fetched packs are verified against the signed release channel; embedded+ packs are not re-verified** — they carry the same trust as the document+ around them, and opening a file must never require the network. (Design+ settled; the client-side check lands on `claude/i18n-pack-verify`.)+## 9. What is kernel vs what is appShared — **`kernel/src/`**, extracted and in use (evolve carefully, serializediff --git a/docs/i18n-packs.md b/docs/i18n-packs.mdindex 40a2b0f2..2b80ab1d 100644--- a/docs/i18n-packs.md+++ b/docs/i18n-packs.md@@ -1,8 +1,10 @@# Language packs — design-*Design document, July 2026. Status: **agreed, not built**. Companion to-`PLATFORM.md` §6 (signed self-update) and §8 (i18n). The bundled-core half is-settled; the pack half is specified here and implemented incrementally.*+*Design document, July 2026. Companion to `PLATFORM.md` §6 (signed+self-update) and §8 (i18n). The bundled core, the pack format and the in-app+"Add language…" flow are **built**; release-side publishing and client-side+signature verification are landing on their own branches — see+[Status](#status), which says per item what is shipped and what is not.*## The problem@@ -109,6 +111,37 @@ sha256, verified against the `PUBLIC_KEY_JWK` already embedded in every shellsigns packs beside the shell, and the manifest gains a `packs` array listing`{lang, version, sha256, url}`. No new trust root, no second key.+### Verification: what is checked, and what deliberately is not++> **Landing separately.** The design below is settled; the client-side+> implementation is on branch `claude/i18n-pack-verify`. Until that merges,+> `fetchPack` validates *shape* only (`lang`, `strings`, matching `app`) — do+> not read this section as describing shipped behaviour.++Two rules, and the asymmetry between them is the point.++- **A pack fetched from the network is verified.** The pack *index* is signed+ with the release key; each entry pins its pack by sha256. So a client+ verifies the index signature once, then checks the bytes it downloaded+ against the signed hash — the same two-step the shell itself goes through on+ self-update. You cannot substitute a pack without breaking its hash, and you+ cannot fix the hash without breaking the signature. A pack that fails is+ refused, not degraded: a *wrong* pack is worse than no pack, and there is a+ working English fallback right there.+- **A pack already embedded in a file is NOT re-verified.** It carries exactly+ the same trust as the document it travels with: someone who can rewrite a+ block in your `.bento.html` can rewrite the document, the CRDT state and the+ collab keys in the same file, so re-checking one block buys nothing.+ Re-verification would also mean a *network round trip to open a deck*, which+ breaks the property the whole format exists for — a file that works offline,+ forever, from `file://`. The blast radius is bounded in a way that makes+ this an easy trade: a pack is DATA, and its worst case is wrong words on+ screen.++That bound is load-bearing and does not transfer. See `docs/DECISIONS.md` —+the carrier is generic, the policy is not, and nothing carrying **code** may+inherit these rules.+### Loading`registerI18n` already accepts a packed table (kernel). Pack loading adds a@@ -119,11 +152,89 @@ partial or stale pack degrade gracefully rather than break.### Incorporation into the fileA pack is fetched **only on explicit user action** ("Add language…"), verified,-then spliced into the shell as an additional payload block and written out as-a new file — the same fetch → verify → re-splice flow `update.ts` already-performs. Nothing phones home by default; a file that never adds a language-never talks to the network. Once spliced, the pack travels with the file and-works offline forever, like everything else.+then written into the shell as an additional plaintext data block. Nothing+phones home by default; a file that never adds a language never talks to the+network. Once written, the pack travels with the file and works offline+forever, like everything else.++Mechanically the block is a `<script type="application/bento+lang"+id="bento-lang-<lang>">` in `<head>`, holding the pack JSON with `<` escaped as+`\u003c` — exactly the treatment `#bento-doc` gets. The kernel side is+deliberately ignorant: `registerShellBlocks` / `readShellBlocks`+(`kernel/src/save.ts`) carry *typed blocks*, and know nothing about languages.+The app registers `shellBlocksForPacks()` once, at boot, and every serialize+re-declares the whole set.++## Where a pack lives++### A pack lives in the FILE and nowhere else++This was decided the hard way: a second home — "install for this browser",+backed by `localStorage` — was **built and then removed**. The reasoning must+survive, because the idea looks obviously good and will otherwise be proposed+again.++`localStorage` is scoped per **origin**. Bento's actual journey crosses+origins: the download comes from `bento.page` (an `https` origin), and the+file is then opened from disk (a `file://` origin, where every file is+effectively its own storage bucket anyway). So a language added on the website+was **gone** the moment the user saved the deck and reopened it locally — the+exact journey the product encourages. "I added Korean and it vanished" is not+something a user can diagnose, and no wording fixes it.++It also matches everything else here: the file *is* the software, so a+language belongs to the deck. The trade is that adding a language requires+saving the file, which the UI states plainly instead of hiding.++Corollary for future work: anything that "remembers" a pack outside the file+reintroduces this bug. Viewer *preferences* (chosen locale, reduce-motion) are+browser-local on purpose; pack *content* never is.++### Adding is staged on click, written on the next save++Clicking Add registers the pack immediately — the editor switches language+right away — and marks it pending. The row says **"Added when you next save"**,+and the file gains it on the next save (`markFileSaved()` clears the pending+flags once the bytes are out).++It is staged rather than written-on-click because on every browser without the+File System Access API, "write" means **silently downloading a second copy of+the user's deck**. Handing someone an unexpected `deck (1).bento.html` because+they asked for Korean is a worse surprise than asking them to save.++Removal is meant to be symmetric and to need no deletion path: `serializeBody`+drops every block of a managed type and rewrites the current set, so "remove+from this file" is just *stop listing it*.++> **Known gap (kernel, unfixed at time of writing).** `serializeBody` derives+> the managed types from the blocks it is *about* to write, so when the set is+> EMPTY it removes nothing. Removing the file's **last** pack therefore leaves+> the old block in the saved file — every other removal works. The fix is for+> the provider to declare its managed types rather than have them inferred.+> Kernel zone, so it wants its own small PR (`docs/PARALLEL-WORK.md` §1).++### Staying current++Two mechanisms, because a pack is frozen at the version it was built for while+the app around it keeps gaining strings — so a translated deck otherwise+drifts back toward English one release at a time, silently, per string.++- **Update refreshes packs.** `registerUpdatePrepare` (`kernel/src/update.ts`)+ gives the app a moment after a release is verified and before the document+ is serialized into the new shell; slides uses it to run+ `refreshPacksForVersion(version)`, re-fetching each carried language at the+ incoming version. It is **best effort and never fatal**: any pack that+ cannot be re-fetched — offline, not published yet, anything — is kept as it+ is. Degraded beats absent; losing a language the author baked in is far+ worse than one that is a release out of date.+- **The Languages dialog says when a pack is stale.** `packCoverage(pack)`+ counts how many of the *running app's* strings the pack does not cover+ (`PACKED`'s keys are exactly the strings the app asks for), and the row+ reads "Built for v1.0.11 — 23 phrases still show in English. Updating Bento+ refreshes it." Measured, not inferred from the version number: a pack built+ against an older release may still cover everything, and a same-version pack+ can be incomplete. Naming the number turns "why is some of this English?"+ into a fact, and saying it fixes itself stops anyone hunting for a button.## Risks@@ -132,17 +243,34 @@ if it isn't designed in.** `update.ts` fetches a *new shell* and re-splices thecurrent *document* into it. Packs live in the shell, not the document, so thenaive path hands a Korean user back an English file after an update, silentlyand with no error to describe. Pack migration is part of the update path, not-a follow-up.+a follow-up. *Handled:* the registered block provider is consulted on every+serialize, including the update one, so packs ride across by construction —+and `registerUpdatePrepare` refreshes them to the incoming version first (see+[Staying current](#staying-current)).**Pack/app version coupling.** Every release adds strings. A 1.0.10 pack in a1.1.0 shell must degrade per string to English, never fail to load. Themanifest is versioned per pack; the policy for "pack older than app" isload-and-degrade.-**Splice contract.** Packs are additional payload blocks. `#bento-doc` stays-plaintext and the file must still survive `DOMParser → outerHTML`-(`PLATFORM.md` §2). `shell-gate.mjs` must cover a shell carrying packs — the-gate is what protects updaters already frozen in the wild.+**Splice contract.** Packs are additional plaintext blocks beside `#bento-doc`,+and a pack body is arbitrary translated text — it can contain `<`, quotes, and+the literal sequence that closes a script tag. Unescaped, a single pack string+could terminate its own block, or forge a second `#bento-doc` opening tag that+an old updater (which splices into the FIRST regex match) would write into+instead of the real one. Both would brick files already in the wild.++*Handled:* `serializeBody` applies the same `<`→`\u003c` escape to registered+blocks as to the document, and `scripts/shell-gate.mjs` now proves it. Because+a fresh build carries no packs, the gate synthesises an adversarial one — a+script-close sequence, a forged `#bento-doc` opening tag, an HTML comment+opener, CJK/RTL/emoji, U+2028/U+2029 — inserts it both above and below the doc+block, and re-runs the whole contract plus a lossless JSON round-trip and a+v0.1.0-style text splice. A negative control (the same pack written unescaped)+must fail, so the check cannot quietly become vacuous, and one source+assertion keeps `kernel/src/save.ts` applying the escape on both write paths.+The gate covers the splice contract only; it says nothing about whether a+pack's *contents* are right.**RTL is not a pack.** Arabic, Urdu, Persian and Hebrew are among the largestgaps by population, but they need bidi and mirroring work in the CSS. Ranking@@ -163,15 +291,34 @@ turns native review into a continuous process instead of a release blocker.self-contained? Slides, Spaces and Dash have overlapping but distinct stringsets.- Should a saved deck record which packs it carries, for the People/About UI?+ (Partly answered: the Languages dialog reads them straight out of the shell,+ so nothing needs recording in the *document*.)+- Should a spliced pack be compressed? It is written as plaintext JSON today,+ which is simple and keeps the splice contract trivially checkable; the shell+ already has deflate+base64 payload blocks that would roughly halve it, at+ the cost of a second block shape for the gate to reason about.## Status-- [ ] Key-once packing of the bundled catalogs — **PR #75, in flight**. A- prerequisite: it shrinks the core and its kernel change (`registerI18n`- accepting a packed table) is the loading path packs will reuse.-- [ ] Portuguese catalog, bundled-- [ ] Pack format + `release.mjs` emitting and signing packs-- [ ] Manifest `packs` array-- [ ] In-app "Add language…" (fetch → verify → splice)-- [ ] **Update carries packs forward**-- [ ] `shell-gate.mjs` covers a pack-carrying shell+Answered: **is this shipped?** Anything marked *branch* is designed and+written but not merged — do not describe it as shipped.++- [x] Key-once packing of the bundled catalogs (PR #75) — the prerequisite:+ it shrank the core, and its kernel change (`registerI18n` accepting a+ packed table) is the loading path packs reuse.+- [x] Portuguese catalog, bundled (PR #79)+- [x] Pack format + `build-i18n.mjs --packs` emission, Korean first (PR #81)+- [x] Runtime loading: `addPack`/`removePack`, per-string fallback+ (`kernel/src/i18n.ts`)+- [x] In-app "Add language…" / "Remove", staged and written on the next save+ — *branch `claude/i18n-pack-ui`, PR #86*+- [x] **Update carries packs forward** + `refreshPacksForVersion` — same branch+- [x] Per-pack staleness note from `packCoverage` — same branch+- [x] `shell-gate.mjs` covers a pack-carrying shell — *branch+ `claude/i18n-pack-gate`, stacked on #86*+- [ ] `release.mjs` publishing packs + the signed manifest `packs` array —+ *branch `claude/i18n-pack-release`*+- [ ] Client-side signature/hash verification of fetched packs —+ *branch `claude/i18n-pack-verify`*+- [ ] A published pack index at the release channel (`packs.json`), so+ "Available to add" is non-empty in the wild