Bento, the office suite that fits in a file
TypeScript mit-licenseofficeoffice-365office-suiteoffice-toolsoffice365open-sourcepowerpointself-hostedsingle-page-appslidesslideshareslideshowslideshow-galleryslideshow-makerslideshows
Document the direction split and the never-mirror invariant
nyblnetfebf2d0ccffe
diff --git a/docs/DECISIONS.md b/docs/DECISIONS.mdindex 1c7b816d..9f31737b 100644--- a/docs/DECISIONS.md+++ b/docs/DECISIONS.md@@ -264,3 +264,42 @@ something is actually failing.Human review is a practice, not a GitHub setting, for as long as the team isone 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.diff --git a/docs/PLATFORM.md b/docs/PLATFORM.mdindex 9292eee4..442b6581 100644--- a/docs/PLATFORM.md+++ b/docs/PLATFORM.md@@ -123,6 +123,35 @@ 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.+### Direction (RTL) — two halves, never confuse them++**Content direction belongs to the DOCUMENT and is per element.** Text+resolves its own base direction from what the author typed (`dir="auto"` in+the renderer), so an Arabic paragraph reads RTL beside an English one in the+same file. This is data: it renders identically for every viewer, and it is+the half that fixes real bugs (misplaced sentence-final punctuation).++**Chrome direction belongs to the VIEWER and never enters the format.** The+editor flips to RTL when the viewer's locale is RTL — the same viewer-scoped+pattern as `bento-lang` and reduce-motion. `applyDirection()` runs AFTER+`capturePristine()`, so a saved file can never carry a `dir` attribute. Lay+chrome out with logical properties (`inset-inline-start`, `margin-inline-end`,+`text-align: start`) and it mirrors itself; only glyphs that encode a+direction in their SHAPE need flipping by hand.++> **INVARIANT — the document never mirrors.** Elements carry absolute x/y+> model coordinates, so a document MUST render identically regardless of who+> opens it. A document whose appearance depends on the viewer's locale is a+> format-level bug, and a worse outcome than an unmirrored UI. Every surface+> that renders document content is therefore pinned `direction: ltr`: the+> document root, thumbnails, the scroller, the present overlay, print, and any+> body-mounted overlay that reads coordinates (e.g. Moveable's control box,+> which mounts outside the document subtree and needs its own pin).+>+> An app adding a new document-rendering surface MUST pin it. The pin is also+> what keeps direction away from `scrollLeft` — the one layout API whose+> meaning genuinely changes under RTL — so coordinate math stays untouched.+## 9. What is kernel vs what is appShared — **`kernel/src/`**, extracted and in use (evolve carefully, serialize