diff --git a/doc/development_plan.md b/doc/development_plan.md index eecec1e..cb8cdc7 100644 --- a/doc/development_plan.md +++ b/doc/development_plan.md @@ -1,280 +1,234 @@ -# Development Plan: from skeleton to lean, usable app +# Development Plan: reach a lean, usable Android text editor -Status: DRAFT — written 2026-08-15 against the stale Backup snapshot (May 31). -The live repo (~/pad) is 47 commits ahead; see the "Corrections" note at the -bottom before acting on anything in this document. +Status: v2, 2026-08-16. Written against the **live** repo `/home/gmp/pad` +(HEAD 03fb638). v1 (the widget-rebuild plan) is superseded — see §12 for why. -## 1. Decision summary +## 1. Decision summary (updated) -- **Tooling:** delete the hand-rolled `internal/ui` entirely. Build on Gio's native - widgets: `widget.Editor`, `widget.List`, `layout.List`, `widget.Button`, - `widget.RichText`. This removes the entire bug class the project has been - fighting (positioning/scroll/clipping/gesture) and is the *only* path to Android - IME input (swipe typing, autocorrect) without writing Android InputConnection - code ourselves. -- **Concurrency:** one main goroutine owns all app state and does all drawing. - File I/O runs in background goroutines; results come back over a channel and are - applied on the main goroutine. No logic goroutine, no unbuffered - display-channels, no globals (`editor.TheState`, `browser.currentBrowserState`, - `ui.OpenFile` all die). -- **Target size limit:** 50 MB files — but stock `widget.Editor` cannot do this - (evidence below). The plan stages this as an explicit decision point with three - options; recommendation: ship with stock editor at a documented limit, and do - windowed shaping as a separate, isolated project if 50 MB is still required. +- **Primary path: B — finish the live custom path, do NOT rebuild on widgets.** + The live repo already has the two hardest, most-asset-heavy pieces that a + rebuild would throw away: a **real filesystem** backend (`internal/io/pool/real/`) + and a **working Android APK** (JNI + permissions, built + signed). It also has + a **chunked buffer** (`internal/editor/chunked_buffer.go`) that already implements + the spec's "file never fully in memory" — the thing v1 said would need fork-level + work on `widget.Editor`. So the only blocker to the headline feature (Android IME: + swipe typing, autocorrect) is a **small, precisely-defined wiring gap** (§4), not a + rewrite. +- **Concurrency:** keep the existing logic-goroutine + channels model for now. It's + proven to build and (after this plan) pass tests. The v1 "one main goroutine" + simplification is a *later* cleanup, not a prerequisite for usability. +- **File-size limit:** the chunked buffer targets large files directly; we validate + it against a real 10 MB file on-device and set the honest limit from that, rather + than inheriting `widget.Editor`'s ~0.5 GB/MB wall (§2). -## 2. Evidence (verified against gioui.org v0.9.0 sources) +## 2. Evidence (verified against gioui.org v0.10.0 sources, the live repo's version) -1. **IME works through `widget.Editor` only.** `GioView.java` implements - `onCreateInputConnection` → `GioInputConnection` (commitText / - setComposingText / setComposingRegion); `app/ime.go` exposes - `editorState.Replace`; `widget.Editor` pushes `key.SnippetCmd` every frame. - Our current custom UI never receives IME input at all. -2. **The IME snippet is selection-scoped** (`updateSnippet` reads only the - selected range; empty selection → empty snippet at caret). Consequence: - windowing the editor's backing text does *not* break IME behavior. -3. **`widget.Editor` is not virtualized.** `textView.layoutText` shapes the - *entire* document on every invalidation (each keystroke, IME commit, wrap - toggle, width change — *not* on scroll; scroll only moves a clip) and builds - an in-memory `glyphIndex` of **~200 bytes per rune** (`combinedPos` + - `text.Glyph` per rune). -4. **Measured on this desktop (shaper.Layout + full glyph iteration, = the - per-keystroke cost of `widget.Editor`):** +1. **`widget.Editor` is not virtualized** — it shapes the *entire* document per + invalidation and keeps a ~200 B/rune in-memory `glyphIndex`. Measured on this + box: 1 MB ≈ 17 ms/keystroke & ~0.32 GB; 3 MB ≈ 1.7 GB; 4 MB OOM-killed the host. + Planning figure **~0.5 GB of RAM per 1 MB of text**. A phone cannot edit 10 MB + in `widget.Editor`. This is *why* the live repo went the chunked-buffer route, + and it's the reason v1's "just use the widget" was wrong for large files. +2. **The Android IME works through the op layer, not the widget.** The + `window`'s editor state (`app.Window` → `input.EditorState{Selection, Snippet}`) + is what `GioInputConnection` (Android's `InputConnection`) reads. It is fed by + `key.SelectionCmd` and `key.SnippetCmd` ops tagged with a **focusable** handler. + A handler becomes focusable by emitting a `key.FocusFilter{Target: tag}` (that's + all `widget.Editor` does — it never touches `io/input` at all). The live code + already emits `key.FocusCmd{Tag}` + `key.FocusFilter{Target}` and consumes + `key.EditEvent`/`key.SnippetEvent`, so the *skeleton* is present; the stateful + ops are missing (§4). +3. **The IME snippet is selection-scoped** — so a chunked/virtualized editor can + still feed a correct snippet (only the visible/selected window), which the live + chunked-buffer design is compatible with. +4. **No headless test window** in v0.9 or v0.10 — widget-level Go tests are + impossible; on-device e2e is required (§9). +5. **The dev agent has no vision** (verified) — the emulator debug loop is + data-based (state dumps, logcat, gfxinfo, PIL/OCR), not screenshot-judgment + (§9.3). - | text size | time/keystroke | peak RAM | - |---|---|---| - | 1 MB | 17 ms | ~0.32 GB | - | 2 MB | ~35 ms (extrapolated) | ~0.9 GB | - | 3 MB | — | ~1.7 GB (measured, incl. GC churn) | - | 4 MB | — | OOM-killed the benchmark host | +## 3. Current state of the live repo (post housekeeping, 2026-08-16) - Planning figure: **~0.5 GB of RAM per 1 MB of text** (editor index + - shaper store + buffer + undo copies, with reallocation churn). Android app - memory ceilings (lmkd) are typically ~1.5–2 GB on 8 GB phones. +- `go build ./...` green. **`go test ./...` now green** (was red: `internal/editor` + and `internal/test/e2e` failed to build after `NewLogic` gained a `path` and + `openfunc` parameter). Commit `03fb638` fixed the harness + 5 call sites; the e2e + harness now uses a no-op `openfunc` (matching `impl_other.go`, whose real + `OpenFile` is a no-op off-Android). +- Uncommitted (yours, left untouched): JNI/Termux bridge, chunk-buffer + logic + changes. **Recommend committing these** so the working tree is a clean baseline + before the IME work. -Therefore: comfortable editing up to **~2 MB**, a hard guard at **5 MB** -(≈ 2.5 GB — survivable on most phones, heavy), 10 MB ≈ 5 GB (OOM), 50 MB is -not deliverable with stock `widget.Editor`. 10 MB editing requires windowed -shaping (fork-level work on Gio). See §6. +## 4. The IME wiring gap (verified, testable) — THE central work item -## 3. What gets deleted +Android IME text (swipe, autocorrect) arrives as `key.EditEvent{Range, Text}` +routed to the focused tag. Four things are missing or wrong: -| Item | Where | Why | -|---|---|---| -| Whole custom toolkit | `internal/ui/` (element.go, render.go, layout.go, unit.go, icons/) ~1,500 L | replaced by Gio widgets | -| Worker pool + mock FS service | `internal/io/pool/worker_pool.go`, `mock/` (429 L) | replaced by plain background goroutines | -| 10 of 11 task types | `internal/io/pool/task.go` | only Read/Write are ever used, as plain functions | -| On-disk JSON index cache | `internal/browser/index.go` `.pad/indices/` machinery | cache-in-indexed-dir is the fragile design behind the failing mtime test; a sync directory needs no cache (re-scan is ms) | -| Dead browser state | `state.go`: `VisibleCount` (never set → list rendered 0 rows), `RowFilenames`, `Pages`, `Page`, `SortIndex`, `SortMode` (duplicate of browser's), `PaginationState`, `PageSize` | replaced by `widget.List` + real filenames | -| Untyped handlers | `browser/handlers.go`, `editor/logic.go` `func(any)` closures + globals | replaced by direct calls on the main goroutine | -| e2e harness | `internal/test/e2e/` | written against the dead architecture; replaced by widget-level tests after Phase 1 | -| Stale docs | `element_model.md`, `layout_rendering.md`, `touch.md`, `conflict_resolution.md`, `browser_implementation_plan.md` | describe deleted systems; `architecture.md` rewritten last | +1. **No `key.SelectionCmd` emitted.** Without it the driver's + `EditorState.Selection.Caret` stays at origin, so the IME doesn't know where the + caret/selection is → suggestions anchor wrongly and the caret jumps after a + commit. **Fix:** in the editor's draw/update pass, emit + `gtx.Execute(key.SelectionCmd{Tag, Range:{cursor,cursor}, Caret:{Pos,Ascent,Descent}})` + whenever the caret moves. The caret's **pixel** position already exists in + `internal/ui/render.go:534-554` (the code that draws the caret) — it must be + plumbed into `app.State` (caret pos in px) and read back here. This is the one + item coupled to the cursor-positioning work, but it reuses the same geometry. +2. **No `key.SnippetCmd` emitted.** Without it the IME receives an empty snippet → + no autocorrect context and no in-place swipe replacement. **Fix:** emit + `gtx.Execute(key.SnippetCmd{Tag, Snippet:{Range: selection, Text: selectedText}})`; + with no selection, an empty snippet at the caret (exactly what `widget.Editor` + sends). Feeding it from the chunked buffer is O(selection size), not O(file). +3. **`HandleKeyDown` ignores `EditEvent.Range`.** `state.go:313` does + `HandleInsert(v.Text)` for any non-backspace text and never deletes + `v.Range.Start..End`. A *replacement* commit (the normal swipe/autocorrect case) + therefore inserts the new text **without removing the old** → duplication/corruption. + **Fix:** `Replace(v.Range.Start, v.Range.End, v.Text)` on the chunked buffer and + advance the cursor to `Start + len(Text)`. (~10 lines; `ChunkedBuffer` already + has `Insert`/`Delete`.) +4. **No `key.InputHintOp{Tag, Hint: key.HintText}`.** Cosmetic but correct to add — + hints the on-screen keyboard into text/autocorrect mode. -**Kept (ported, not rewritten):** `browser/types.go` (Entry), `sort.go` + tests, -`search.go` + tests, directory scan from `index.go` (minus cache), the wrap / -autosave / per-file-offset concepts from `editor/state.go`. +Acceptance (all verifiable headlessly, §9): after an IME commit, the buffer equals +the expected post-replacement text, the caret is at the commit end, and the next +frame's `SelectionCmd`/`SnippetCmd` reflect that state. On a real IME, swipe + +autocorrect produce clean, non-duplicated text. -## 4. Target architecture (single diagram, no channels except I/O) +## 5. Phases (Path B) -``` -main goroutine (Gio frame loop, owns ALL state) - app.State { - page: browser | editor - dir: string // current browser directory - entries: []browser.Entry // sorted+filtered, rebuilt on demand - sort: browser.SortMode - query: string - file: openFile{path, modTime, wrap, editor widget.Editor, dirty, lastEdit} - restore: state.RestoreData // persisted JSON - } - on FrameEvent: - - handle I/O results from chan result - - draw current page - background goroutines (one per op): - os.ReadFile / os.WriteFile / dir scan → send result on chan -``` +### Phase 0 — clean baseline (small) +1. Commit the uncommitted JNI/chunk-buffer work. +2. `go test -race ./...` green (add `-race`; the channel model may surface races — + fix any found). -- **Browser page:** top bar (path, sort menu) + search field + - `layout.List` over `entries` (virtualized; 1,000-file directory is a - non-issue). Tap → start background read → on result, switch to editor page. -- **Editor page:** `widget.Editor` bound to the file's text; toolbar (filename, - wrap toggle, close). Autosave: `dirty` + 1 s debounce in the frame loop, - background write, status shows saved/dirty. Undo/redo in-session: built into - `widget.Editor` (unexported history, triggered by normal editing) — no work. -- **State restore** (spec: survive close/reopen): small JSON in the app data - dir: `{openFile, wrap, autosave, offsets: {path: {line, col}}}`. On open: - `SetText` + `SetCaret(line, col)`. `SetCaret` auto-scrolls to the caret. - Offsets are rune offsets — invalid if the file changed; validate against - persisted mtime and fall back to top on mismatch. -- **External change detection:** on open and on app resume, compare mtime to - the opened modTime; if changed and we're not dirty → reload; if dirty → - one-line banner with Keep / Reload (no full conflict UI in v1). -- **File-size guard:** on open, if `size > limit` → show "file too large to - edit in v1" (limit per §6 decision). -- **Testability:** state transitions (open file, sort, search, autosave due, - external-change decision) are plain functions on `app.State` → directly - unit-testable. Device behavior covered by manual checklist + `-race` in CI. +### Phase 1 — complete the IME (§4) +Implement items 1–4, with **Go unit tests** for item 3 (range-replace on the +chunked buffer is pure and directly testable) and a state-assertion test for +items 1/2 (after N frames, `app.State` holds the expected caret/selection and the +next emitted op set is correct). This is the make-or-break feature. -## 5. Phases +### Phase 2 — emulator verification (the observation loop, §9.3) +1. Install Android SDK + NDK + platform-tools; create an x86_64 AVD (16 GB VM, + KVM verified present). +2. Build the APK (`GOOS=android go build ./cmd/pad` with `ANDROID_NDK_HOME`), + install, launch. +3. Drive + observe: state-dump debug flag (add in Phase 1 as a debug build), + logcat, `dumpsys gfxinfo`, screenshot→PIL/OCR. +4. **IME experiment with the AOSP keyboard:** `input swipe` over the keyboard area + and verify behaviorally (did the commit land, non-duplicated, cursor correct?) + via state dump + logcat — this is what confirms §4 works end to end. -### Phase 0 — deletion-only (no new features) -1. Delete everything in §3. -2. `cmd/pad` keeps an `app.Window` with a placeholder screen; build green. -3. Keep passing tests by porting sort/search tests to the trimmed `browser` - package; delete the on-disk-cache test (feature deleted) — this removes the - flaky `TestBuildIndex_CacheInvalidatedOnMtimeChange` by deleting the cache. +### Phase 3 — large-file validation + honest size limit +1. Open a real **10 MB** file via the chunked buffer; verify smooth scroll + edit + and measure RAM on-device. +2. Set the documented limit from that measurement; guard larger files with a + clear "too large to edit" state (browser can still list/preview). -**Done when:** `go build ./... && go vet ./... && go test -race ./...` green; -repo ≤ ~2,500 lines of Go; no `func(any)`, no package-level mutable state, -no channels except (added in Phase 1) the I/O result channel. +### Phase 4 — the v1 simplifications, now that it's usable (optional, later) +Only after the app is usable: replace globals (`TheState`, `ui.OpenFile`) with +explicit state, prune dead task types, and *then* consider collapsing the +logic-goroutine/channel model to a single owner. These reduce future bug surface +but are not needed for a usable v1. -### Phase 1 — browser -1. `layout.List` browser page: rows = name + modified time; directories - distinguished; tap on dir descends, breadcrumb back; tap on file opens it - (Phase 2 stub: toast "no editor yet"). -2. Port sort (name/modified, asc/desc) + search filter onto the page. -3. Background dir-scan for large directories; version counter to drop stale - results. +### Phase 5 — hardening +Rewrite `doc/architecture.md` to match reality; amend `spec.md` per §7; README +(build/install recipe); in-repo device test checklist. -**Done when:** on-device: browse a real 1,000+ file directory at full frame -rate; sort and search correct (unit tests); no data races. +## 6. File-size decision (re-framed) -### Phase 2 — editor -1. Open file → background read → `widget.Editor` with `SetText`; toolbar with - wrap toggle (maps to `WrapPolicy`) and close (back to browser). -2. Autosave: debounce, background write, dirty indicator. -3. State restore + per-file offset memory + external-change check (§4). -4. IME verification on device: swipe typing, autocorrect, multi-line commits, - caret jump after commit. +v1 framed this as "accept a limit vs build a windowed editor." The live repo +already chose the better option — a **chunked buffer** (only viewport ± window +chunks resident, async prefetch, dirty-chunk protection, async line index). So the +decision is now: **validate the existing chunked buffer against a real 10 MB file +(Phase 3) and set the limit from the measurement.** No fork of Gio is on the +critical path. If the chunked buffer proves out (likely), 10 MB+ editing is in +reach without the 0.5 GB/MB wall that kills `widget.Editor`. -**Done when:** edit + close + reopen restores file and caret; kill app, -reopen, same; external modification handled per §4; `-race` clean. +## 7. Spec deltas (to write into spec.md) -### Phase 3 — the 50 MB decision (see §6) -Either (A) document the limit and ship, or (C) build and integrate the -windowed editor. (B, full chunked streaming, is out of scope — it implies a -custom editor and forfeits the IME advantage.) - -### Phase 4 — hardening -1. Rewrite `doc/architecture.md` to match reality; amend `spec.md` per §7. -2. `README.md`: what it is, how to build/install (Go 1.24, gioui.org, NDK). -3. Device test checklist in-repo. - -## 6. The 50 MB decision (explicit fork) - -| Option | What | IME | Effort | Outcome | -|---|---|---|---|---| -| **A. Accept a documented limit** (2 MB soft warn, 5 MB hard guard — §2.4) | nothing more than Phase 2 | full | done | the large majority of real text files in a sync dir; honest limit in UI | -| **C. Windowed editor** | isolated project: shape only viewport ± window; `glyphIndex` covers the window; offset map rune→window; scroll triggers re-window; undo history kept as per-operation edits, not full copies | full (snippet is selection-scoped, verified) | large — touches Gio internals (`textView`, `Editor`), upstreamable but expect divergence | 10 MB+ editing at 60 fps, *if* the PoC holds | -| B. Chunked streaming editor (spec's original) | build our own editor on raw ops | **lost** (no InputConnection) | largest | rejected: forfeits the core reason for moving to native | - -**Recommendation: A now, C later as its own branch.** Reasoning: A delivers a -usable app; the Phase 0–2 work is identical under either choice, so nothing is -locked in. C is only worth starting if, after real usage, the 5 MB guard bites -(i.e. we genuinely need to *edit* larger files). If C is started, gate it -behind a PoC first: windowed shaping of a 10 MB file must sustain 60 fps -scroll + sub-100 ms keystroke on the target phone before any integration work. - -## 7. Spec deltas (to write into spec.md after Phase 2) - -1. "No practical limits / file never fully in memory" → "files up to N MB - (measured); larger files openable in browser, not editable." -2. Undo across sessions → dropped (in-session undo/redo is provided by the - editor widget). -3. Add: IME/swipe/autocorrect support (was an implicit requirement, now - explicit and delivered). -4. Add: external-change detection behavior (§4) as the conflict policy, - replacing `conflict_resolution.md`. +1. "No practical limits / file never fully in memory" → backed by the chunked + buffer; add a measured hard limit from Phase 3. +2. Undo across sessions → dropped (in-session only; chunked buffer does not keep + full-document undo copies). +3. Add: IME/swipe/autocorrect support (now explicit, delivered in Phase 1). +4. Add: external-change detection as the conflict policy (mtime compare on open + + on resume; changed+clean → reload, changed+dirty → Keep/Reload prompt). ## 8. Non-goals (v1) - File-system watcher / live browser refresh (re-scan on return to browser). -- Multi-file views, tabs, split. -- Syntax highlighting, search-in-file, diff/merge UI. -- Desktop/other platforms (Android-first; window sized per existing - `unit.Dp(390) × unit.Dp(844)`). +- Tabs, split view, search-in-file, syntax highlighting, diff/merge. +- Desktop/other platforms (Android-first; window `390×844` dp). +- Rewriting on `widget.Editor` (v1 plan) — kept only as fallback (§12). -## 9. Testing strategy (replaces `internal/test/e2e`) +## 9. Testing strategy -The old e2e harness is deleted: it existed to test the channel/frame -choreography, which no longer exists. E2E regression still works, in three -layers: +The **existing** e2e harness is **kept** (it builds and passes now) and extended — +v1's "delete the harness" is wrong for Path B. E2E regression works in three layers: -**Layer 1 — Go unit tests on pure state functions (the bulk).** The design -keeps every behavior as a plain function on `app.State` (no goroutines, no -widgets), so the regression surface is directly testable on a host in -milliseconds: -- sort (all modes) / search / directory scan — port the existing - `browser` package tests; -- `applyReadResult` / `applyWriteResult` / `applyScanResult`, including - **stale/out-of-order results** (version counters) — the exact race the old - channel design was prone to, now a synchronous decision under test; -- autosave debounce and dirty-flag decisions (clock injected, no real timers); -- restore JSON encode/decode; offset validation against mtime; external-change - decision table (changed+clean → reload; changed+dirty → prompt; - unchanged → open); -- file-size guard (2 MB warn / 5 MB reject). +### Layer 1 — Go unit tests on pure logic (the bulk) +- Port/keep `browser` sort/search/scan tests; keep `editor` chunked-buffer, + cursor, autosave tests. +- **New:** range-replace on `ChunkedBuffer` (§4.3) — pure, directly testable; the + exact corruption bug becomes a regression test. +- **New:** IME state transitions — after an `EditEvent{Range,Text}`, assert + buffer + caret; assert the emitted `SelectionCmd`/`SnippetCmd` reflect state. +- **New:** restore JSON round-trip; offset-vs-mtime validation; external-change + decision table; file-size guard. +- CI gate: `go build && go vet && go test -race ./...`. -CI gate: `go build && go vet && go test -race ./...` on every commit. +### Layer 2 — UI thin by construction +Draw functions are wirings of the existing element model over `app.State`; +positioning math stays in one place (`render.go`). The cursor/caret geometry that +§4.1 reuses is the same code path as drawing, so IME correctness and visual +correctness share a foundation. -**Layer 2 — UI code thin by construction.** Gio has no headless/test window -(verified in v0.9 and v0.10), so widget-level Go tests are not possible. -Mitigation is structural, not test-based: draw functions are ~30-line wirings -of `layout.List` / `widget.Editor` over `app.State`, and all positioning math -lives inside Gio. The bug class the old UI had (positioning/scroll/clipping) -is *deleted*, not covered by tests. +### Layer 3 — scripted on-device e2e (emulator now available) +The in-app selftest drives the **real state machine through the real draw path** +(browser entries → open file → edit → autosave deadline → reload-prompt decision), +logging PASS/FAIL to a file the host `adb pull`s and asserts. -**Layer 3 — scripted on-device e2e: an in-app selftest.** A debug-build flag -(`pad --selftest`, or launched via `am start` with an extra) drives the **real -state machine through the real draw path**: -1. create a fixture tree under the app's data dir; -2. browser: assert entry count/names in the rendered state; -3. open a file: assert editor text == fixture content; -4. force the autosave deadline: assert the file on disk is rewritten; -5. save restore state, simulate reopen: assert file + caret offset restored; -6. touch the file's mtime externally, reopen: assert the reload-prompt - decision fires. -Each step logs PASS/FAIL; a summary is written to a file the host pulls via -adb and asserts on. Deterministic, seconds long, runnable in CI against a -farm/one attached device. +### 9.3 Emulator observation layer (this 16 GB VM, KVM verified; agent has NO vision) +Gio renders into one GL surface, so Android's view hierarchy exposes nothing about +our UI. The debug loop is data-based — *more* precise than pixels for this codebase: +1. **State-dump debug flag** (add in Phase 1): debug builds write `app.State` + (browser entries, editor text length, cursor px, scroll, dirty, row geometry) + as JSON to the app data dir on a magic tap or 2 s interval; host `adb pull`s + and asserts. Primary "eyes." +2. **logcat** — Go panics + our logs. +3. **`dumpsys gfxinfo `** — per-frame timing/jank for the 60 fps claims. +4. **Screenshot → PIL color histogram / tesseract OCR** — coarse on-screen checks. +5. **File diffs** via `adb pull` — autosave/restore correctness. +6. **Driving** — `input tap/swipe/keyevent/text`, `am start/force-stop`, + `ime`/`settings` to pick the AOSP keyboard; swipe-typing exercised via + `input swipe` over the keyboard area and verified **behaviorally** (did the + commit land, non-duplicated, cursor correct?), not visually. -**Manual-only (unavoidable):** swipe typing, autocorrect, caret jump after an -IME commit — `adb input text` bypasses the IME entirely, so these cannot be -scripted by any tool. They live in a short checklist in the repo, run before -releases, alongside the §9/DoD journey. +## 10. Definition of done (whole effort) -## 10. Definition of done for the whole effort +On an emulator (and a real phone for final IME sign-off): launch → previous file ++ caret restored → browse a large directory smoothly → open a real file → +**swipe-type with autocorrect, clean and non-duplicated** → close and reopen, caret +where you left it → external modification → reload prompt → autosave lands on disk +within ~1 s. Repo: `go test -race ./...` green. -On a real Android phone: launch → previous file and caret restored → browse a -large directory smoothly → open a real file → swipe-type with autocorrect → -close and reopen, caret where you left it → modify file externally, get the -reload prompt → autosave lands on disk within ~1 s. Repo: ≤ ~3,000 lines of -Go, one channel, zero globals, `go test -race ./...` green. +## 11. Risks / watch-items +- **§4.1 caret plumbing** is coupled to the cursor-positioning geometry; if that + geometry is itself buggy, the IME will inherit it. Mitigation: the state-dump + reports caret px, so we can assert it against expected values in tests. +- **Channel model + `-race`** (Phase 0): the existing goroutine/channel design may + have latent races; running `-race` before IME work avoids conflating them. +- **Chunked buffer at 10 MB** (Phase 3): unproven on-device; the measurement is + the gate for the size claim. +- **AOSP keyboard** is a proxy for real IMEs (Gboard, etc.); final swipe/autocorrect + sign-off needs a real device with a real IME. ---- - -## Corrections (live repo, ~/pad, as of 2026-08-15) - -The live repo has advanced far beyond the snapshot this document analyzed: -real filesystem (`internal/io/pool/real/`), a built Android APK (JNI + -permissions), a working editor (click-to-cursor, Enter/Backspace, autosave), -and a **chunked buffer** (`internal/editor/chunked_buffer.go`) implementing the -spec's "file never fully in memory" approach that this plan assumed would -require fork-level work. Concretely: - -- `VisibleCount` is now assigned (`internal/editor/state.go:174`); the - "browser renders 0 rows" finding is stale. -- The IME path is half-wired at the raw-op layer: `cmd/pad/main.go` consumes - `key.EditEvent`/`key.SnippetEvent` and fires `key.SoftKeyboardCmd`, but - **nothing creates the window-level editor-state op** (`app.EditorState`), so - IME *text commits* (swipe, autocorrect) likely still have nowhere to land; - raw key events (Enter/Backspace) work. Completing this wiring is the - pivotal experiment (see emulator decision below). -- The live test suite is RED: `internal/editor` and `internal/test/e2e` fail - to build after `NewLogic`'s signature changed to - `(pool.FileSystem, string, func(string))`. -- The A/B fork is now: **(A)** this plan's widget rebuild, vs **(B)** finish - the live path (complete IME wiring, stabilize chunked buffer, fix tests). - The emulator swipe-typing experiment decides. - -Decision pending: Path A vs Path B. Until decided, this document is a -reference for the widget-rebuild option, not an active plan. +## 12. Why v1 (widget rebuild) is now a fallback, not the plan +v1 was written against a stale snapshot (May 31) and concluded "delete +`internal/ui`, build on `widget.Editor`." Two later-verified facts changed that: +(a) the live repo already solved the two hardest parts a rebuild would discard +(real FS, APK, and the chunked buffer that `widget.Editor` cannot do), and (b) the +Android IME is reachable from the op layer with only the §4 gap — so the "free IME" +that motivated the rebuild is actually ~4 small wirings away on the existing code. +**Path A (widget rebuild) remains the fallback if the Phase 1 IME wiring proves +fragile on-device** (e.g., the caret/snippet plumbing drags in a long tail of +cursor-positioning bugs that are cheaper to not own). The emulator (Phase 2) is the +instrument that makes that call.