Bento, the office suite that fits in a file
TypeScript mit-licenseofficeoffice-365office-suiteoffice-toolsoffice365open-sourcepowerpointself-hostedsingle-page-appslidesslideshareslideshowslideshow-galleryslideshow-makerslideshows
docs: settle how document search gets built, and make DECISIONS greppable again
nyblneta61b211a0d25
diff --git a/docs/DECISIONS.md b/docs/DECISIONS.mdindex 90731f33..127bd742 100644--- a/docs/DECISIONS.md+++ b/docs/DECISIONS.md@@ -14,6 +14,80 @@ Decision. Why. Pointers.---+## 2026-08-16 — Document search: the list stays native, the indexer is shared by FIXTURE++**Decision.** When the native hosts grow a document library, each keeps its own+**native list UI** and ports the text extraction itself; the three+implementations are held together by **one shared fixture corpus**, not by a+shared runtime. Specifically NOT by moving `tray/webext`'s `home.html` /+`library.js` into a WebView on the native hosts.++**The gap this is about.** The three surfaces are at three different levels, and+only one of them can search:++| | what "search" means there |+|---|---|+| `tray/webext` | scans every granted folder; matches title, file name, folder, **and the document's own prose** (`library.js extractText`) |+| `tray/ios` | the system document browser's search field — **the app contributes nothing to it** (no CoreSpotlight, no `NSUserActivity`) |+| `tray/android` | **none**; a recents list sorted by last-opened |++`extractText` is the valuable part: up to 40KB of prose per document, pulled out+of the `#bento-doc` block as string VALUES (`:"…"`, never keys), data URIs+stripped first. Deliberately not a JSON parse, so it is format-agnostic across+slides/spaces/dash and degrades to "finds less" rather than throwing. It is free+in I/O because the same read already produced the thumbnail. That is what lets+someone find a deck by a phrase on a slide rather than by what they named the+file.++Both platforms CAN support this — it is a "not built" gap, not a "can't" one.+Android has `ACTION_OPEN_DOCUMENT_TREE` (a persistable whole-directory grant,+near-exactly `showDirectoryPicker`); iOS has the document picker in folder mode+(a security-scoped directory URL).++**Why the shared-WebView-library option was rejected.** Three costs, in+descending order of severity:++1. **iOS would throw away `UIDocumentBrowserViewController`,** which is not a+ list but a surface: Browse into iCloud Drive, Dropbox and every File Provider+ on the device, drag-and-drop, in-place rename, favourites and tags, the+ system's own sort and view controls. An HTML grid replaces all of that with+ less, and contradicts the property `tray/README.md` claims — *on iOS the app+ is a lens onto the filesystem; on Android it is a keyring*. **Android has+ nothing to lose here**, which is the asymmetry that makes a single shared+ answer wrong.+2. **Cold start costs ~0.5s,** on the first screen of every launch. MEASURED+ 2026-08-16, Pixel 7 / Android 16 emulator, both cold: native list root+ **1171ms** (1241ms on a repeat) against WebView root **1728ms**. That is an+ emulator on Apple silicon, so treat it as a FLOOR — WebView provider load is+ I/O and CPU bound and a mid-range phone widens the gap. iOS was not measured.+3. **Accessibility stops being free.** Native lists get VoiceOver/TalkBack,+ Dynamic Type and system font scaling correctly with no effort; in a WebView+ Android's font-size setting does nothing unless `WebSettings.textZoom` is+ wired, and Dynamic Type does not reach web content without explicit work.+ Predictive back and interactive dismiss are native on a native screen and+ reimplemented in a WebView. `home.html` is also a desktop-first grid with a+ sidebar and would need a real mobile design pass, not a media query.++**The reasoning that settles it: the UX cost sits entirely in the part that does+not need sharing.** What is worth sharing is the INDEXER — pure data work, no UI.+The chrome is what costs cold start, accessibility and the iOS browser, and the+chrome is exactly what should stay native.++**Why this differs from `tray/bridge.js`, which IS shared.** That file is shared+because its semantics are subtle and a divergence is catastrophic and silent —+its comments record a bug that wrote users' documents out as zero bytes. Text+extraction is string scanning with a documented budget: a divergence makes search+find less, which is visible and recoverable. So the right guarantee is weaker and+cheaper. Trading "cannot diverge" for "cannot diverge SILENTLY" is the correct+trade at this level of consequence, and it is already this repo's idiom for+exactly this problem — the splice contract has a conformance gate in+`release.mjs`, the save-purpose ids have `scripts/test-savepurpose.ts`.++**Status: not built.** Nothing here has been implemented. The cheap intermediate+step, if it is wanted before the full library, is a name filter over the existing+Android recents list — that brings Android level with iOS and touches no+extraction. Parity table and the standing gap: `tray/README.md` § Android.+## 2026-08-16 — bento/tray gets an Android host (PR #87, rearchitected)**Decision.** `tray/android/` is a document host, written against the same two@@ -2526,7 +2600,16 @@ prompting, nothing reporting a fault.*Found in passing:* the rig carried a LITERAL NUL byte in a test case, whichmade `grep` treat the whole file as binary and hid it from ordinary tooling. It-is now written as a ` ` escape.+is now written as a `\x00` escape.++*Amended 2026-08-16:* and then **this file caught it** — the sentence above+shipped with a literal NUL where it says `` `\x00` ``, so `grep` treated+DECISIONS.md as binary and returned nothing, silently, for every query. That is+the worst possible file to lose to this: `CLAUDE.md` tells every agent to read it+before non-trivial work, so a silent no-match reads as "no prior decision" and+invites the contradiction the log exists to prevent. Found by a `grep` for a+heading that was demonstrably present. If you are describing a control character,+escape it.*Amended 2026-08-14, later.* Two corrections to the entry above, both fromlooking rather than reasoning.diff --git a/tray/README.md b/tray/README.mdindex e78c3b4f..884cd987 100644--- a/tray/README.md+++ b/tray/README.md@@ -476,12 +476,28 @@ here rather than discovered later.| `<a download>` lands | app's Documents folder, silently | wherever the author picks | platform-forced || write access to an opened document | always | **may be read-only** | platform-forced || status bar while editing | hidden on iPad | always shown | **known gap** |--The last row is the only real gap. iOS hides the status bar on iPad because-nothing else keeps the page off the whole screen there; the Android equivalent-would be to hide it on tablets (`smallestScreenWidthDp >= 600`). Not done,-because it cannot be tested without a tablet target, and shipping an untested-behaviour is worse than naming an untested one.+| finding a document by its contents | — | — | **gap on both**, see below |++Two gaps, both named rather than quietly left out.++**The status bar.** iOS hides it on iPad because nothing else keeps the page off+the whole screen there; the Android equivalent would be to hide it on tablets+(`smallestScreenWidthDp >= 600`). Not done, because it cannot be tested without a+tablet target, and shipping an untested behaviour is worse than naming an+untested one.++**Search — and note this table compares the two NATIVE hosts to each other,+which flatters both.** Against `tray/webext` there is a third axis neither has:+the extension scans every granted folder and searches **the document's own+prose**, so a deck is findable by a phrase on a slide. iOS gets only the system+document browser's search field, and the app contributes nothing to it (no+CoreSpotlight, no `NSUserActivity`); Android has no search at all. Both platforms+*could* support it — `ACTION_OPEN_DOCUMENT_TREE` on Android, the folder-mode+document picker on iOS — so this is "not built", not "can't". The direction is+settled in `docs/DECISIONS.md` (2026-08-16): native list UI on each host, the+extraction ported per platform and pinned against one shared fixture, rather than+a shared HTML library screen in a WebView — which was measured at ~0.5s of extra+cold start and would cost iOS its system document browser.### What is genuinely different