Skip to content

armgit / bento

Public Imported from GitHub
0

Bento, the office suite that fits in a file

docs: settle how document search gets built, and make DECISIONS greppable again

nyblneta61b211a0d25
diff --git a/docs/DECISIONS.md b/docs/DECISIONS.md
index 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, which
made `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 from
looking rather than reasoning.
diff --git a/tray/README.md b/tray/README.md
index 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