Skip to content

armgit / bento

Public Imported from GitHub
0

Bento, the office suite that fits in a file

Merge main into tray

nyblnet4315b8a78ea5
diff --cc docs/DECISIONS.md
index a2e1341b,7e4e51a7..cf6600ab
--- a/docs/DECISIONS.md
+++ b/docs/DECISIONS.md
@@@ -233,39 -434,81 +434,118 @@@ Human review is a practice, not a GitHu
one person. Restore a real approval count the moment a second reviewer exists;
the future-action exclusion list in the amended entry still applies.
+ ## RTL is two separable problems; only one of them is the document's
+
+ **Decided:** 2026-07-26. Supersedes nothing; establishes the split.
+
+ Content bidi and chrome mirroring get confused constantly, and treating them
+ as one feature produces the wrong answer to both.
+
+ *Content* direction is a correctness bug and belongs to the document: an
+ Arabic sentence puts its full stop in the wrong place without `dir="auto"`,
+ and it is wrong for everyone who opens the file. Cheap, uncontroversial, do it.
+
+ *Chrome* mirroring is a UI convention. Nothing is incorrect without it; the
+ editor merely feels foreign to an RTL reader. It was deliberately sequenced
+ AFTER an RTL language pack existed, because mirroring a UI whose every label
+ is still English is worse than not mirroring — and because the point of
+ shipping a pack first is to learn whether RTL users actually turn up.
+
+ The invariant that falls out of the split — **the document never mirrors** —
+ is recorded in `PLATFORM.md` §8 and binds every Bento app. A document that
+ looks different depending on the viewer's locale is a format-level bug.
+
+ Cost, measured rather than guessed: ~430 bytes in the shipped shell for the
+ whole chrome conversion, and **zero** for the languages themselves, because
+ every RTL language is a pack. Size was never the constraint here. The real
+ constraint is that 32 of the editor's ~36 direction-adjacent coordinate sites
+ live in `canvas.ts` (Moveable/Selecto), which cannot be verified by an agent —
+ synthetic drags on Moveable handles do not register at all. Pinning the
+ document surfaces LTR was sufficient to leave that math untouched, and that is
+ the outcome to preserve: if a future change makes chrome direction reach
+ `canvas.ts`, stop and reconsider rather than refactoring the coordinate code.
+
+ **No plural system.** Hebrew (and later Arabic) ship without one. Of 15
+ count-bearing strings only 6 take a real count; the rest are index labels
+ (`Axis {n}`, `slide {n}`) or abbreviated times. Six strings do not justify
+ changing the catalog format, the build script, the CI gate and every catalog.
+ Translators phrase them count-agnostically instead (`מחוברים: {n}`), which is
+ standard practice when a framework lacks plurals and costs nothing at runtime.
+ Revisit only if a language arrives where the workaround genuinely fails.
+
+ ## One English word, two meanings = two keys
+
+ **Decided:** 2026-07-26. Consequence of English-string-as-key; binds every
+ Bento app that uses `kernel/src/i18n.ts`.
+
+ Gettext-style catalogs key on the English source string, which quietly assumes
+ that one English word means one thing. It often doesn't. `Loop` was the
+ animation loop AND the media playback toggle; `solid` was a fill style AND a
+ line style. Every language had to pick one word and be wrong in the other
+ place — Swedish wants *enfärgad* for a solid colour and *heldragen* for a
+ solid line, and no amount of translator care fixes that from inside the
+ catalog. Both were found independently by pack authors, which is the signal:
+ if a translator has to ask "which one is this?", the key is broken, not them.
+
+ **The rule.** When one English string reaches `t()` from two call sites that
+ mean different things, the more specific site takes a QUALIFIED key
+ (`Loop animation`, `solid colour`) and the plainer one keeps the bare word.
+ Do not add a context-prefix convention — the key is also what English users
+ read, so it has to be a sentence, not `fill.solid`.
+
+ **Model words never move.** Values like `solid`/`gradient` are format words
+ stored in the document. Disambiguate the LABEL only: `labeledSelect()` takes
+ `[value, label]` pairs precisely so the displayed string and the stored string
+ can diverge. A "fix" that changes what is written to `doc` is a format change
+ wearing an i18n costume.
+
+ **The cost, so it is paid deliberately.** Re-keying invalidates that entry in
+ every bundled catalog AND in every pack, silently — the string simply falls
+ back to English. So it happens BEFORE packs are published, in one PR, with
+ the affected keys listed for pack authors to pick up. After packs ship,
+ re-keying is a coordinated break across every language and should be weighed
+ against living with a slightly wrong word.
+
+ **Interpolated values are strings too.** `t('This {kind} is…', { kind })` with
+ a model word for `kind` puts an English noun inside a translated sentence.
+ Localise at the call site (`{ kind: t(kind) }`) — and check the sentence still
+ agrees grammatically, since a substituted noun carries gender in half the
+ languages we ship (French needed "Ce fichier {kind}" once `vidéo` could land
+ in it).
++
+## 2026-07-26 — bento/tray: the iOS host is a suite member, and it is generic
+
+The native iOS app is named **bento/tray** — "Bento Tray" on the App Store,
+bundle id `page.bento.tray`, source in `tray/` beside `slides/` and `spaces/`.
+
+**It runs ANY self-contained HTML document, not only Bento's.** That is not
+scope creep bolted on; the Swift never parses the document and never did — it
+is a courier that serves bytes into a WKWebView and polyfills the one File
+System Access call the page needs to save itself. Bento decks are simply the
+first documents it carries. Any single-file HTML app that saves itself works
+identically, which on iOS is otherwise impossible: every browser there is
+WebKit and none ship that API.
+
+Naming notes, so this is not relitigated:
+
+- **`bento/host` was rejected.** It names the mechanism, not the thing, and the
+ suite convention is `bento/<what you get>`. "tray" keeps the food metaphor and
+ says what it does — a tray carries any bento, whoever made it.
+- **Plain "Bento" is unavailable** on the App Store: an unrelated Food & Drink
+ app holds the exact name, and App Store names are globally unique. "Bento
+ Tray" and "BentoTray" were both free at time of checking. That check reads
+ published listings only — reservations in App Store Connect are invisible to
+ it, so confirm there before submitting.
+- The App Store name carries no slash. Per the 2026-07-24 naming entry, `/` is
+ a mark, never a stored name.
+
+**One app, not two.** A separate "generic HTML runner" listing would risk
+guideline 4.3 (duplicate apps from one developer) and doubles the listing
+overhead — screenshots, privacy labels, review cycles — for no gain. The
+Developer Program is $99/yr per ACCOUNT, so a second app costs nothing in fees;
+the cost is entirely in maintenance.
+
+Consequence already implemented: each document gets its OWN origin
+(`bento-tray://<sha256 of path>`), because a shared origin would let one
+document read another's localStorage and IndexedDB — tolerable when every file
+is yours, a real leak between unrelated third-party apps.