Skip to content

armgit / bento

Public Imported from GitHub
0

Bento, the office suite that fits in a file

Document the direction split and the never-mirror invariant

nyblnetfebf2d0ccffe
diff --git a/docs/DECISIONS.md b/docs/DECISIONS.md
index 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 is
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.
diff --git a/docs/PLATFORM.md b/docs/PLATFORM.md
index 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 behave
exactly 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 app
Shared — **`kernel/src/`**, extracted and in use (evolve carefully, serialize