Greg Pomerantz
e3690d6b98
Persist a tiny JSON snapshot (SessionState) written by the cmd layer ($HOME/.pad/session.json off-Android, /storage/emulated/0/Pad/ on Android) and call the logic-owned snapshot rate-limited (<=1/s, on change) from emitFrame plus unconditionally at Shutdown. On launch the cmd layer hands the snapshot to Logic.BeginRestore before Run; the file re-opens through the normal openFile path and lands straight on the editor page. - Cursor/selection land with the content, clamped to a shrunk file (path-guarded so a late result for a replaced file cannot apply the snapshot to the wrong buffer); a missing file falls back to the browser. - Scroll is applied only after the first ScaleEvent has been laid out: the size ConfigEvent precedes it and the one-way MaxScroll clamp in a wrong-unit layout would corrupt the offset (found by e2e). - Find: query + open/closed + current match are persisted; results are regenerated by re-scanning and the saved current match is re-selected by byte offset (Find.Restoring/RestoreMatch) without re-scrolling the restored viewport. A closed-bar query re-scans on the next bar open instead (an eager scan would be dropped and leave Scanning stuck). - The main-owned find_bar widget is seeded with the restored query so its first frame matches the logic-side query. Docs: spec.md gains §2.4 and drops the §7 row; invariant 5 updated; architecture.md gains §6.7. Tests: 7 e2e tests covering cursor/scroll/ selection restore, clamping, missing-file fallback, find-bar restore (open/closed), and the saver/shutdown persist paths.
639 lines
39 KiB
Markdown
639 lines
39 KiB
Markdown
# Runtime Architecture
|
||
|
||
This document describes how Pad actually works: the concurrency model, goroutine
|
||
responsibilities, the frame handoff contract, ownership rules, and the internal
|
||
design of the editor and browser. It is written at the level of *invariants and
|
||
contracts*, not line-by-line code, so it stays true as implementation details
|
||
evolve. If a detail below conflicts with the code, the code wins — and this
|
||
document should be fixed.
|
||
|
||
## 1. Concurrency model: single owner, no locks on state
|
||
|
||
The **logic goroutine is the sole owner (reader and writer) of mutable
|
||
`State`**. There is no `sync.Mutex`/`sync.RWMutex` on application state. Every
|
||
other goroutine talks to the owner through channels.
|
||
|
||
```
|
||
┌────────────────────────────────────────────────────────────────────┐
|
||
│ Main goroutine (Gio event loop) │
|
||
│ - w.Event() loop: Config / Frame / Destroy │
|
||
│ - On FrameEvent: lock(handoff) → read Frame snapshot → │
|
||
│ Renderer.Draw → collect gestures + key events → │
|
||
│ e.Frame → unlock(handoff) → send inputs/config/query/layout │
|
||
│ to logic channels (sends happen OUTSIDE the lock) │
|
||
└───────────────▲──────────────────────────────┬─────────────────────┘
|
||
│ handoff lock (frame storage) │ inputChan, configChan,
|
||
│ + w.Invalidate() │ layoutChan, searchQueryChan
|
||
┌───────────────┴───────────┐ ▼
|
||
│ frameReceiver goroutine │ ┌──────────────────────────────────────┐
|
||
│ tight loop: │ │ Logic goroutine (SOLE OWNER of State)│
|
||
│ f := <-frameChan │ │ - select over all input channels │
|
||
│ lock; *frame = f; │ │ - mutates State, builds []Element │
|
||
│ w.Invalidate(); unlock │ │ - sends Frame on frameChan │
|
||
└───────────────────────────┘ │ - dispatches tasks to worker pool │
|
||
└───────────────┬──────────────────────┘
|
||
│ task dispatch / results
|
||
┌───────────────▼──────────────────────┐
|
||
│ Worker pool (8 goroutines) │
|
||
│ - priority: high > medium > low │
|
||
│ - file I/O, directory index, line │
|
||
│ index build, autosave writes │
|
||
│ - results posted on ResultChan │
|
||
└──────────────────────────────────────┘
|
||
```
|
||
|
||
Key invariants:
|
||
|
||
1. **No locks on `State`.** The only mutex is the *handoff* mutex in
|
||
`cmd/pad/main.go`, which guards the one-frame storage slot between
|
||
frameReceiver and the main goroutine. It is a message-passing handoff, not
|
||
a state lock; it is never held while touching a channel.
|
||
2. **The main goroutine never reads logic `State` directly.** It reads only
|
||
the latest `Frame` snapshot (see §4) and writes only via channels.
|
||
3. **Non-owner goroutines never mutate `State`.** They send a request
|
||
(channel) or run a callback on the owner (`Inspect`, test-only).
|
||
4. **The autosave timer goroutine reads nothing.** `time.AfterFunc` only sends
|
||
a token on `autosaveChan`; the owner does all state reads and dispatches
|
||
the write.
|
||
5. **Gio-mutable widget state lives in the main-goroutine-owned `Renderer`**,
|
||
never in logic-owned `State` (see §5).
|
||
6. **Logic work is synchronous and fast.** Processing input, mutating state,
|
||
building the element tree, and sending a frame must stay well under one
|
||
display refresh (~16 ms). File I/O and index building always go to the
|
||
worker pool.
|
||
|
||
## 2. Goroutine responsibilities
|
||
|
||
### 2.1 Main goroutine (`cmd/pad/main.go`)
|
||
|
||
- Runs the Gio event loop.
|
||
- On `app.ConfigEvent`: sends `ConfigEvent{PixelWidth, PixelHeight}` to
|
||
`logic.ConfigChan()`.
|
||
- On `app.FrameEvent`:
|
||
1. Reads `newScale = gtx.Metric.PxPerDp`; if it differs from
|
||
`frame.Scale`, sends `ScaleEvent` (after the draw).
|
||
2. Under the handoff lock: reads the `Frame` snapshot, calls
|
||
`renderer.Draw(gtx, frame.Elems, scale)`, then `renderer.CheckGestures`
|
||
and the focused element's key/edit events, then `e.Frame(&ops)`.
|
||
Key events are queried with a catch-all `key.Filter{Focus: id}` **plus
|
||
one named filter per arrow key**. This is required on Android: the
|
||
window layer wraps plain arrow-key *presses* in `input.SystemEvent`
|
||
(it wants them for focus navigation), and system events match only
|
||
filters that name the key explicitly. Matching a named filter both makes
|
||
the press deliverable and suppresses the focus-move side effect (a
|
||
matched event makes `WakeupTime` report handled, skipping the window's
|
||
`moveFocus`). The **shift key is tracked here** (`shiftDown`): Gio's
|
||
Android JNI bridge never reads `KeyEvent.getMetaState`, so
|
||
`key.Event.Modifiers` is always 0 and shift+arrow is otherwise
|
||
indistinguishable from a plain arrow. `NameShift` press/release do
|
||
arrive as plain events; the tracked state is attached to the
|
||
`ui.KeyEvent{Shift: ...}` forwarded to the logic (OR-ed with the
|
||
Modifiers field so desktop behavior is unchanged). Shift state is
|
||
reset when no element is focused.
|
||
3. Outside the lock: sends `[]ui.InputEvent` (if any) to `InputChan`,
|
||
the search text (if it differs from `frame.Query`) to `SearchQueryChan`,
|
||
and `renderer.GlyphLayout()` to `LayoutChan`.
|
||
- Owns `frameReceiver` (started in `run`).
|
||
|
||
### 2.2 Frame receiver
|
||
|
||
Tight loop: read `logic.FrameChan()`, store into the shared `Frame` under the
|
||
handoff lock, call `w.Invalidate()`. The logic goroutine's send on `frameChan`
|
||
(bufsize 1) never blocks for more than one frame cycle.
|
||
|
||
### 2.3 Logic goroutine (`internal/editor/logic.go`)
|
||
|
||
Sole owner of `*State`. `Run()` selects on:
|
||
|
||
| Channel | From | Payload | Action |
|
||
|---|---|---|---|
|
||
| `configChan` | main | `ConfigUpdate` (pixels or scale) | store scale/pixels; recompute layout |
|
||
| `inputChan` | main | `[]ui.InputEvent` | run each `Handler(evt.Data)` on the owner |
|
||
| `searchQueryChan` | main | `string` | store `Browser.Query`, re-filter, new frame |
|
||
| `findQueryChan` | main | `string` | in-file search: store `Editor.Find.Query`, dispatch `Search` task, new frame |
|
||
| `openFileChan` | main (tap) | `string` path | open file in editor (chunked buffer + async index) |
|
||
| `layoutChan` | main | `ui.GlyphLayout` | store on editor state; derive `LastLineY` for scroll clamping |
|
||
| `retryChan` | logic | `string` filename | autosave retry |
|
||
| `autosaveChan` | timer | `struct{}` token | reconstruct content, dispatch `WriteFile` task |
|
||
| `workerPool.ResultChan()` | pool | task `Result` | apply async results (stat, read, index, write ack) |
|
||
| `inspectChan` | tests | `inspectReq` | run `fn(*State)` **on the owner** and reply (test-only) |
|
||
| `resultChan` | legacy | `ResultEvent` | drained (legacy channel; the live result path is the pool's) |
|
||
| `done` | main | — | drain pool, stop timer, exit |
|
||
|
||
After every state change the logic goroutine rebuilds the element tree and
|
||
sends a `Frame` on `frameChan`.
|
||
|
||
### 2.4 Worker pool (`internal/io/pool`)
|
||
|
||
Fixed 8 workers, two priority lanes (high > low; dispatch routes
|
||
`HighPriority` tasks to the high lane, everything else to low). Tasks are small
|
||
structs with `Execute() Result`; the `FileSystem` interface (`pool.FileSystem`)
|
||
has a real implementation (`io/pool/real`, rooted at `/`) and a mock
|
||
(`io/pool/mock`) for tests.
|
||
|
||
Task types in active use: `StatFile`, `ReadFile`, `BuildLineIndex`,
|
||
`WriteFile`, `Search` (editor); `BuildIndex`, `LoadPages` (browser). The
|
||
`Search` task runs a case-insensitive substring scan over a full-content
|
||
snapshot (`FindSubstring`) and returns the match byte ranges plus the query
|
||
generation that dispatched it; the logic drops results whose generation no
|
||
longer matches (`EditorState.applySearchResult`), so a superseded scan can
|
||
never clobber newer results. Dormant/dead task
|
||
types — `ReadChunk` (no-op for fully-loaded in-range files), `ReadDir`,
|
||
`StatDir`, `ReadCache`, `WriteCache`, `Invalidate`, `SaveState`, `SaveUndo` —
|
||
are candidates for removal in a cleanup round.
|
||
|
||
## 3. Channel topology summary
|
||
|
||
- **main → logic:** `InputChan`, `ConfigChan`, `LayoutChan`, `SearchQueryChan`,
|
||
`FindQueryChan`, `OpenFileChan`.
|
||
- **timer → logic:** `autosaveChan` (token only).
|
||
- **logic → logic:** `retryChan` (self-piped).
|
||
- **logic → frameReceiver:** `FrameChan` (the only outbound state carrier).
|
||
- **pool → logic:** `WorkerPool.ResultChan()`.
|
||
- **tests → logic:** `Inspect` (owner-executed callback; the production
|
||
equivalent is "send a request channel message").
|
||
|
||
## 4. The Frame handoff contract
|
||
|
||
`editor.Frame` is the **only** data that crosses from the logic side to the
|
||
main side:
|
||
|
||
```go
|
||
type Frame struct {
|
||
Elems []ui.Element // element tree for the next draw
|
||
Scale float32 // current px-per-Dp
|
||
FocusedElementID string // which registered element gets key/edit events
|
||
Query string // search text logic is filtering with
|
||
}
|
||
```
|
||
|
||
- `Elems` is the computed tree; the renderer draws it (it is a snapshot, safe
|
||
to read from main).
|
||
- `Scale` lets main detect a density change and pass scale to `Renderer.Draw`.
|
||
- `FocusedElementID` drives which registered `key.Filter`/`key.FocusFilter`
|
||
main uses to harvest keyboard/IME events.
|
||
- `Query` lets main compare against the (main-owned) search `widget.Editor`
|
||
text and forward changes — the browser search box is a Gio widget, so its
|
||
text lives on the main side, not in `State`.
|
||
|
||
## 5. Ownership rules
|
||
|
||
| Owned by | What |
|
||
|---|---|
|
||
| **Logic goroutine** | `State` (browser + editor + chunked buffers + line indexes), worker pool, autosave timer handle |
|
||
| **Main goroutine** | `*app.Window`, `op.Ops`, text shaper, `ui.Renderer` (gesture state, IME dedup state, glyph layout cache), the search-bar `widget.Editor` |
|
||
|
||
Rules:
|
||
|
||
1. **Gio mutates widgets during draw, so anything Gio mutates must be
|
||
main-owned.** The search bar is a `widget.Editor` registered with the
|
||
renderer by ID (`"search_bar"`); its text reaches logic only through
|
||
`SearchQueryChan`.
|
||
2. **The editor content is NOT a `widget.Editor`.** It is the custom
|
||
`ui.TextField` element; all editor state (buffer, cursor, scroll) is
|
||
logic-owned. This is why the editor does not hit `widget.Editor`'s
|
||
O(n²)-ish cost on large files.
|
||
3. **Per-frame element values are rebuilt by logic** (`[]ui.Element` in the
|
||
`Frame`); any cross-frame persistent draw-side state (IME dedup, gesture
|
||
tracking) belongs in the persistent, main-owned `Renderer`.
|
||
|
||
## 6. Editor internals (`internal/editor`)
|
||
|
||
### 6.1 Chunked buffer
|
||
|
||
`ChunkedBuffer` (`chunked_buffer.go`) is the edit buffer for open files.
|
||
|
||
- **Full load on open** for in-range files: the whole file is read into an
|
||
ordered slice of chunks (64 KB) plus **prefix-sum byte offsets** over actual
|
||
chunk lengths. There is no lazy loading and no eviction (both existed as
|
||
plans and were removed).
|
||
- **Byte-indexed** throughout: `CursorPosition`, chunk offsets, and glyph
|
||
`ByteOffsets` are byte offsets. All edit primitives are **rune-granular**:
|
||
`HandleBackspace`/`HandleDelete` compute the UTF-8 rune width at the cursor
|
||
(a byte-granular delete corrupts multi-byte characters, e.g. a two-byte
|
||
character straddling a chunk boundary); IME edits arrive as rune ranges;
|
||
tap-to-position lands on rune starts.
|
||
- Edits splice the affected chunk(s) only; chunks are not rebalanced.
|
||
- `LineIndex` (per-line byte offsets, `int32`) is built asynchronously by
|
||
`BuildLineIndexTask` and stored on `cb.LineIndex` — the single source of
|
||
truth (the old parallel `EditorState.LineIndex` field was removed). A file
|
||
ending in `'\n'` has a trailing empty line (one offset past the last `\n`,
|
||
equal to the file length).
|
||
- **Incremental line-index maintenance.** Every buffer edit updates the index
|
||
in place instead of rebuilding it: `UpdateLineIndexAfterInsert(pos, text)`
|
||
(shifts starts above `pos` right, keeps a start at `pos`, adds one start per
|
||
inserted `\n`) and `UpdateLineIndexAfterDelete(start, end)` (drops starts in
|
||
`[start, end)`, shifts the rest left, re-inserts `start` iff it is a line
|
||
start in the new content). A start exactly at `end` always drops: it was
|
||
created by the `'\n'` at `end-1`, which the deletion removes (line merge).
|
||
These must be called in the same order as the buffer splice, and an IME
|
||
replace is `Delete` then `Insert` at the same position.
|
||
- **Size guard:** files larger than `MaxEditableFileSize` (**50 MB**,
|
||
measured on-device) open into a `TooLarge` state: the editor shows a notice
|
||
and edit handlers are no-ops; the browser still lists the file.
|
||
|
||
### 6.2 Virtualized viewport
|
||
|
||
Only the visible byte range is shaped and drawn each frame:
|
||
|
||
- `VisibleByteRange` maps scroll offset + viewport height → `[startLine,
|
||
endLine]` via the `LineIndex`, then to a byte range. The range is always
|
||
bounded by real lines of the document.
|
||
- **Scroll decomposition invariant.** The scroll offset s is split into a
|
||
content line k and sub-line remainder r by a single float64 floor
|
||
decomposition, and all consumers of that split MUST stay in lockstep: the
|
||
window start line (VisibleByteRange), the renderer's sub-line shift (the
|
||
windowed layout is drawn shifted up by r), the tap mapping (`tapLocalY`
|
||
adds r), the selection menu/handle positions (`bytePosToScreenXY`), and the
|
||
max-scroll clamp. With them consistent, a tap a dp below the region top
|
||
always maps to the line actually under the finger for every s ≥ 0. The
|
||
decomposition must be computed in float64: a raw `int(s/lh)` in the Dp
|
||
float32 domain can round the quotient UP across an integer boundary while
|
||
a float64 mod still reflects the line below, so the window start and the
|
||
remainder disagree by one line in a sub-pixel-wide band of offsets and the
|
||
whole rendered window (hence every tapped line) shifts by one.
|
||
- **Word wrap: the visual-line space (WrapIndex).** A wrapped logical line
|
||
occupies several visual lines, so the scroll offset lives in VISUAL-line
|
||
space, not logical-line space. Every scroll↔content mapping site
|
||
(window start, sub-line shift, tap-to-line, max scroll) MUST go through
|
||
the same conversion, or the content jumps: when the viewport top crosses
|
||
the bottom of a wrapped line, a 1:1 logical↔visual mapping skips the
|
||
wrapped remainder (jump magnitude (count-1)·lh) instead of moving
|
||
pixel-by-pixel. The conversion is backed by the `WrapIndex`, a Fenwick
|
||
tree of per-logical-line visual-line counts (built parallel to the
|
||
LineIndex, same line set, updated by the same edit hooks):
|
||
- **Invariant:** with k the logical line at the viewport top and r the
|
||
sub-line shift, the viewport top is ALWAYS exactly s into the document's
|
||
visual space: `V(k)·lh + r = s`, where V(k) is the prefix sum of counts
|
||
before line k. Equivalently k = LineForVisual(⌊s/lh⌋) and r = s − V(k)·lh
|
||
(0 ≤ r < count(k)·lh: a wrapped line's top may sit several visual lines
|
||
above the viewport). Any mapping that breaks the identity silently skips
|
||
or re-shows content — the scroll jump. An all-ones WrapIndex (the state
|
||
before any shaping correction lands) makes V(k)=k and the mapping
|
||
reduces to the legacy 1:1 behavior, so pre-shaping and non-wrapped files
|
||
are unchanged by construction.
|
||
- **Correction pipeline:** the renderer's per-frame `VisualLineStarts`
|
||
(one entry per visual line, window-relative) are grouped per logical
|
||
line and written back into the WrapIndex (the layout feedback carries
|
||
the exact window text it was shaped for, the window's first logical
|
||
line, and the content-edit counter; the correction is applied only if
|
||
the edit counter matches, so a layout shaped before an edit never
|
||
stamps shifted lines). Counts are content- and width-dependent, not
|
||
window-dependent: once known they are globally valid until an edit or a
|
||
wrap-width change.
|
||
- **Edit staleness:** the UpdateLineIndexAfter{Insert,Delete} hooks
|
||
bookkeep the WrapIndex in the same pass as the LineIndex (line inserts/
|
||
deletes shift counts; touched lines reset to the estimate 1). The rule
|
||
is never under-stale: every line whose content changed is reset, and
|
||
extra resets (over-stale) are always safe — the next frame that shapes
|
||
the line re-corrects it. A stale estimate is an under-count (count 1),
|
||
which only shortens maxScroll and compresses the mapping until the
|
||
correction lands (a self-heating warm-up, never corruption).
|
||
- Max scroll is `TotalVisuals()·lh − regionH + lh/2` with the
|
||
font-scale-effective line height; it grows incrementally as shaped
|
||
counts arrive (pre-shaping it equals the no-wrap estimate).
|
||
- **Font-scale axis.** The shaper draws baselines in sp, so on Android the
|
||
rendered line pitch in density-dp is `EditorLineHeight()*fontScale`
|
||
(`fontScale = Metric.PxPerSp/PxPerDp`, the user font-size setting).
|
||
Every consumer of `lh` above therefore uses `EffectiveLineHeight()` (the
|
||
font-scale-applied value, tracked in `State` via `ScaleEvent.FontScale`),
|
||
and the renderer's `GlyphLayout.LineHeight`, caret, handles, and selection
|
||
highlight use the same scaled pitch. With the raw line height, a
|
||
non-default font setting would misplace taps by up to (fontScale-1)
|
||
viewportfuls of lines and make scroll clamping stop short of (or run past)
|
||
the file ends. Density itself (pure hi-DPI) is a separate axis: all
|
||
geometry bookkeeping is in density-dp and scale enters only at the px↔dp
|
||
conversion (single `r.scale`/`State.scale`), so the invariant above is
|
||
scale-free and holds at any display density.
|
||
- **Never shape the whole file.** Lesson learned (Phase 3): the shaper's
|
||
internal `document` retains the backing array of its largest layout forever
|
||
(`reset()` keeps the cap), so one whole-file layout permanently inflated
|
||
memory to ~1 GB for a 10 MB file. Shaping ~50 lines keeps it small and flat.
|
||
- The renderer reports `GlyphLayout` back via `LayoutChan`; logic derives
|
||
`LastLineY` for scroll clamping and the max scroll offset.
|
||
- **`GlyphLayout` offsets are window-relative.** The shaper only sees the
|
||
visible window, so `GlyphLayout.ByteOffsets` (and `VisualLineStarts`, `Y`)
|
||
are relative to `IMEWindowStartByte`, not the file start. Any logic-goroutine
|
||
code that maps a glyph offset to the absolute `CursorPosition` (tap-to-position,
|
||
Home/End, vertical cursor move) must add the window base
|
||
(`IMEWindowStartByte`) before storing the cursor and subtract it before
|
||
searching the offsets. For a whole-file window the base is 0 (a no-op).
|
||
Getting this wrong snaps the cursor to the window top on scrolled large files.
|
||
|
||
### 6.3 Selection and caret
|
||
|
||
- Key presses arrive as `ui.KeyEvent{Name, Shift}` (main.go), not bare
|
||
`key.Name`, so handlers can distinguish shift+arrow from plain arrow.
|
||
On Android the `Shift` bit comes from main.go's own shift tracking, not
|
||
from Gio's Modifiers (see §2.1); arrow-key presses reach the handler only
|
||
because main.go registers the explicit named key filters.
|
||
- **Shift+arrow extends a selection**, plain arrow moves the caret and clears
|
||
it. `SelectionAnchor` is the fixed end, `CursorPosition` the active end; both
|
||
are **absolute file byte offsets**. No selection ⇔ `SelectionAnchor == -1`.
|
||
A zero-length shift selection keeps the anchor (`SelectionStart/End == -1`)
|
||
so the next shift-move extends from the original spot.
|
||
- Insert / backspace / delete with a live selection delete the whole selection
|
||
first (`deleteRange`), then insert; the selection is cleared afterwards.
|
||
- IME: with an active selection, `HandleReplaceRange` unions the IME-reported
|
||
range with the selection before splicing, so replacement is deterministic
|
||
whether the IME reports the caret (empty range) or the full range.
|
||
- Rendering: the `TextField` element carries **window-relative** selection
|
||
start/end into the visible `Value` (−1 = none) for the highlight, drawn
|
||
before the glyphs; the IME `SelectionCmd` push dedups on the
|
||
(selectionStart, caret) pair.
|
||
|
||
### 6.3a Touch selection (v1)
|
||
|
||
- **Division of labor: the renderer reports finger positions, the logic owns
|
||
all geometry.** Touch input is delivered to the logic goroutine as
|
||
`ui.Point` (tap), `ui.DoubleTapPoint`, `ui.LongPressPoint`, and selection
|
||
drag events (which handle + app-local Dp position). The logic converts them
|
||
to text coordinates using the `EditorRegion` stored on `State` (set each
|
||
layout frame) plus the scroll offset, hit-tests the floating-menu items
|
||
itself, and owns the menu rect, highlight range, and handle positions.
|
||
The renderer only draws what the `Frame` snapshot says (menu, handles,
|
||
highlight) and registers the input regions.
|
||
- **Menu taps are logic-decided.** The menu panel is one `Tap` interaction
|
||
over its whole rect; the editor's tap handler ignores any tap inside a
|
||
visible menu (`pointInMenu` guard) so both handlers can coexist regardless
|
||
of dispatch order. Item identity comes from the tap's X within the panel.
|
||
- **Long press needs frames to elapse.** Gio renders on demand; a stationary
|
||
finger produces no pointer events and therefore no frames, so the 400 ms
|
||
threshold could never be checked. The main loop polls
|
||
`Renderer.PendingLongPress()` and keeps invalidating the window while a
|
||
press is held still on the editor. A non-grabbing raw pointer probe
|
||
(plain `event.Op` tag on the editor region) observes the press's motion and
|
||
cancels the pending long press on movement; a scroll or handle drag grabs
|
||
the pointer (`pointer.GrabCmd`), which cancels it via `pointer.Cancel`.
|
||
- **A pointer filter with zero `Kinds` matches nothing.**
|
||
`pointer.Filter.Matches` tests `e.Kind & f.Kinds == e.Kind`, so a query
|
||
without `Kinds` silently receives no pointer events — probe queries must
|
||
name the kinds they want.
|
||
- **One event per Update is a trap on Android.** A tap's down+up routinely
|
||
arrive in a *single* frame, and `gesture.Click`/`gesture.Drag` return at
|
||
most one event per `Update` call. If the renderer processed only one event
|
||
per gesture per frame, the release would sit in the queue until the next
|
||
redraw — which on an idle window may never come — and the tap is swallowed
|
||
(this is why menu taps initially required a second tap to "rescue" the
|
||
first). The renderer therefore drains each click/drag gesture's queue to
|
||
exhaustion every frame; `gesture.Scroll` already drains internally.
|
||
- **Per-frame gesture bookkeeping must survive the frame.** Click-registry
|
||
state (press time/position, long-press-fired flag) is kept in structs held
|
||
**by pointer** in a map; `range` over a value-type map yields copies and
|
||
silently discards the mutations.
|
||
- **Clipboard crosses the goroutine boundary via channels; the ops run on
|
||
the main/Gio frame path.** Logic→main: `clipboardSetChan` (string to write)
|
||
and `pasteReqChan` (token). Main→logic: `pasteChan` (string). All three are
|
||
buffered (16) so a harness with no main loop can never block the logic
|
||
goroutine. Main executes `clipboard.WriteCmd` / `clipboard.ReadCmd` during
|
||
a frame and forwards read results back on `pasteChan` from the
|
||
`transfer.DataEvent`.
|
||
- **Android clipboard reads need an explicit invalidation.** Gio v0.10 on
|
||
Android answers `ReadCmd` synchronously during the op flush by queueing a
|
||
`transfer.DataEvent`; a queued DataEvent schedules **no** frame wakeup of
|
||
its own. Main therefore invalidates the window after each read so a
|
||
follow-up frame exists in which the DataEvent is consumed.
|
||
- **The menu closes on any item tap.** Copy keeps the selection (only the
|
||
menu disappears); cut removes it (via `ClearSelection`, which also hides
|
||
the menu and cancels drag bookkeeping); paste closes the menu immediately
|
||
even though the actual insert happens on a later frame when the clipboard
|
||
content arrives.
|
||
|
||
### 6.4 IME (Android soft keyboard)
|
||
|
||
- The editor exposes to the IME a **windowed snippet**: `IMEWindowText` is the
|
||
visible viewport text, `IMEWindowStartByte` its absolute start. While the
|
||
`TextField` is focused, `drawElement` emits `key.SnippetCmd` (the window)
|
||
and `key.SelectionCmd` (caret as a rune index into the window).
|
||
- **Dedup in the Renderer** (main-owned state): the snippet/selection are
|
||
re-emitted only when they actually change, and a fresh push is forced when
|
||
the field (re)gains focus. This mirrors `widget.Editor`'s behavior and
|
||
prevents per-frame re-push from resetting IME composition on rapid commits.
|
||
- Incoming `key.EditEvent{Range, Text}` has **window-relative rune
|
||
indices**; `HandleReplaceRange` converts them to absolute byte offsets
|
||
(`RuneIndexToByte`) and splices the chunked buffer. Insertion,
|
||
`deleteSurroundingText` (backspace/autocorrect replacement), and composition
|
||
all arrive through this one path.
|
||
|
||
### 6.5 Autosave and the per-file write protocol
|
||
|
||
- Any edit calls `markDirty()`: a 1 s debounce timer; each keystroke restarts
|
||
it. On expiry the timer goroutine sends a token on `autosaveChan`; the owner
|
||
snapshots the full content from the chunked buffer and requests a save.
|
||
- **Per-file write protocol (corruption guard).** The worker pool is shared
|
||
and the on-disk staging path is per-file, so two concurrent writes of the
|
||
same file would race on the staging file. The owner therefore guarantees:
|
||
- at most **one write in flight per file** (`writeInFlight`, keyed by
|
||
filename, recording the file version whose content the write carries);
|
||
- a save requested while one is in flight is **deferred** (`savePending`)
|
||
and re-issued by the write's result handler — so the rename that lands
|
||
last always carries the **newest** content ("latest state wins");
|
||
- on success the recorded written version is the **snapshot's** version,
|
||
so any edit that arrived during the write leaves the file dirty and
|
||
triggers the re-issue.
|
||
- `FlushAll` (page switch, shutdown) obeys the same protocol: if a write is
|
||
in flight it defers instead of writing concurrently.
|
||
- **Shutdown drain:** on the `done` signal the owner waits (bounded, 5 s) for
|
||
in-flight writes and armed retries to settle before exiting, so the
|
||
post-exit `FlushAll` and `workerPool.Stop` cannot race a straggling worker
|
||
write.
|
||
- **Staging file:** `WriteFileAtomic` uses a **unique per-call temp name**
|
||
("`.<name>.tmp.<pid>.<seq>`") in the target directory and renames it into
|
||
place, so readers and crash recovery only ever see a complete file. Each
|
||
successful write also best-effort removes stale temps of the same file
|
||
(crash leftovers, plus the legacy deterministic "`.<name>.tmp`" name).
|
||
Unique temp names make same-file interleaving structurally impossible even
|
||
if the serialization regressed.
|
||
- Write failures are tracked per file (`writeFailed`, `retryAttempts`) and
|
||
retried via `retryChan` (exponential backoff 1 s … 30 s; the timer sends a
|
||
non-blocking token and the owner re-snapshots at fire time). There is no
|
||
save button; autosave is the only persistence.
|
||
- Known residual (out of scope): no `fsync` before the rename — a **power
|
||
loss** inside the rename window can lose the last save (process death
|
||
cannot: the page cache survives).
|
||
|
||
### 6.6 Opening a file
|
||
|
||
- A browser tap sends the path on `OpenFileChan`. The logic goroutine creates
|
||
the `ChunkedBuffer`, dispatches `StatFile` (size guard) and the read +
|
||
`BuildLineIndex` tasks, switches `page` to the editor, and sets
|
||
`justOpenedAt`. The relaunch restore (below) reuses the same `openFile`
|
||
path.
|
||
- **Opening-tap swallow:** the tap that opens the file is also delivered as an
|
||
editor tap in the same frame. A short time window (`justOpenedAt`) swallows
|
||
it so the viewport does not jump to the tapped (often EOF) position.
|
||
|
||
### 6.7 State restoration on relaunch (`session.go`)
|
||
|
||
- The restorable state is a plain comparable value, `SessionState` (last
|
||
file, cursor byte, scroll Dp, selection range, find query/visibility/
|
||
current-match byte). The search results themselves are not stored; they are
|
||
re-scanned on restore.
|
||
- **Ownership:** the logic goroutine owns snapshot content. The cmd layer
|
||
(`cmd/pad/main.go`) owns the JSON file and registers the writer via
|
||
`Logic.SetSessionSaver`; the owner invokes it rate-limited (≤ 1/s, only on
|
||
change) from `emitFrame` and unconditionally at `Shutdown` (post-exit,
|
||
single-threaded, next to `FlushAll`). Satisfies the single-owner rule:
|
||
the callback receives a value copy, and the file I/O is a tiny synchronous
|
||
write in the cmd layer's closure.
|
||
- **Restore:** the cmd layer reads the file at startup and calls
|
||
`Logic.BeginRestore(s)` BEFORE `Run()` (single-threaded window, like
|
||
`NewLogic` itself): it sets `Filename`, shows the editor page, and arms the
|
||
scroll. `Run()` then re-opens the file through the normal `openFile` path.
|
||
- **Stat success:** the find state lands (query, visibility, current-match
|
||
byte via `Find.Restoring`/`Find.RestoreMatch`, so the re-scan's first
|
||
result re-selects the saved match WITHOUT re-scrolling the restored
|
||
viewport).
|
||
- **Content arrival:** cursor/selection land, clamped to the file length
|
||
(path-guarded, so a late result for a replaced file cannot apply the
|
||
snapshot to the wrong buffer); the query re-scans only if the find bar
|
||
was open (a closed-bar scan would be dropped and leave `Scanning` stuck).
|
||
- **Scroll offset:** applied only after the first `ScaleEvent` has been
|
||
laid out: the size `ConfigEvent` precedes it, and a layout in between
|
||
computes the viewport in the wrong unit, whose one-way `MaxScroll` clamp
|
||
would corrupt the offset.
|
||
- **File gone** (stat failure): the restore is abandoned and the app lands
|
||
on the browser page with a clean editor. Any user open of another file
|
||
cancels an in-flight restore for the same reason as the path-guard.
|
||
|
||
## 7. Browser internals (`internal/browser`)
|
||
|
||
- `BrowserState` is **embedded by value** in `State` (single owner; no
|
||
pointer indirection).
|
||
- `BrowserManager` drives async directory loading through the worker pool:
|
||
`ReadDir` + `BuildIndex` on navigation, `LoadPages` for pagination.
|
||
- Features: 4 sort modes (name/date × asc/desc; default newest-first),
|
||
incremental case-insensitive search over names, directory navigation with
|
||
back, single-tap file open.
|
||
- The browser renders via `ListView`/`ListItem` elements; rows carry
|
||
`Interaction` handlers that send channel requests (tap) or mutate state
|
||
directly when the handler runs on the owner (scroll).
|
||
|
||
## 8. Render pipeline (`internal/ui`)
|
||
|
||
- **Logic** builds a `[]ui.Element` tree. Elements are value types; interactive
|
||
ones carry `Interaction{Gesture, Handler}` entries. `Handler` is a static
|
||
function that mutates `TheState` — handlers run on the logic goroutine only.
|
||
- **Main** draws via `Renderer.Draw(gtx, elems, scale)`:
|
||
1. `drawElement` recursively walks the tree, applying transforms/clips.
|
||
2. Interactive elements register hit regions in the *current clip context*
|
||
(`gesture.Click.Add` / `pointer.InputOp`), so hit-testing always matches
|
||
the drawn geometry.
|
||
3. Text elements shape through the shared shaper — **only the visible
|
||
window**, never the whole buffer.
|
||
4. `e.Frame(&ops)` flushes ops.
|
||
- After draw, `CheckGestures` turns raw pointer/gesture state into
|
||
`[]ui.InputEvent` (each carrying its own handler) for the logic channel.
|
||
Tap/double-tap/long-press/selection-drag event positions are **app-local
|
||
Dp** (window px ÷ `PxPerDp` — the same space as element `Region`s, and
|
||
`MenuRect`); the logic side converts them to text coordinates with the
|
||
stored `EditorRegion` + scroll (README.md §Screen coordinates, pipeline
|
||
hop 2).
|
||
- **Units:** `ui.Dp`/`ui.Px` convert via the current `PxPerDp` scale
|
||
(`ToDp`/`ToPx`). The window is 390×844 dp; the real pixel size arrives via
|
||
`ConfigEvent`.
|
||
- **Live element catalog:** `Container`, `Label`, `Icon`, `TextField` (editor
|
||
window), `ListView`/`Line`/`ListItem` (browser rows), `GioEditor` (search
|
||
bar), `Cursor`. Types `Button`, `Toast`, `Spacer`, `AlphaIndex`,
|
||
`Selection`, `MergeHunk` exist in `element.go` but are not used by any page
|
||
— future work, not current behavior.
|
||
- **Theme:** `ui.Theme{FontSize: 14}` + palette in `element.go`.
|
||
|
||
## 9. Testing hooks
|
||
|
||
- `Logic.Inspect(fn)` (test-only): runs `fn(*State)` **on the owner** and
|
||
returns its result — the sanctioned way for tests to read state without
|
||
breaking single ownership. It must never be called from production code.
|
||
- The e2e harness (`internal/test/e2e`) drives the **real** `Logic` + worker
|
||
pool + mock filesystem through the real channels, and asserts via
|
||
`Inspect`. It is logic-only: it does not exercise `Renderer.Draw`, so
|
||
draw-path behavior (IME dedup, gesture routing) is validated on-device with
|
||
adb (see `development_plan.md` §Phase 2/3 observation loop).
|
||
- CI gate: `go build ./... && go vet ./... && go test -race ./...`.
|
||
|
||
## 10. Known loose ends (code, not spec)
|
||
|
||
- Globals `TheState` / `TheLogic` / `ui.OpenFile` still exist (handlers are
|
||
static funcs); replacing them with explicit state is a planned cleanup
|
||
(`development_plan.md` Phase 4).
|
||
- Dead task types (`ReadChunk`, `SaveState`, `SaveUndo`, …) and unused element
|
||
types are candidates for removal in the same round.
|
||
- The Android arrow-key/shift workaround in main.go (named `key.Filter`s +
|
||
app-side shift tracking, §2.1) compensates for two Gio v0.10 behaviors: the
|
||
JNI bridge dropping modifier state, and mobile arrow presses being wrapped
|
||
in `input.SystemEvent` for focus navigation. If Gio changes either
|
||
behavior (e.g. starts passing meta state), the shift tracking and the named
|
||
filters must be re-examined — the workaround would become redundant or
|
||
wrong. Re-verify on-device with `adb shell input keyevent 22` (cursor must
|
||
move) and `input keycombination 59 22` (selection must extend).
|
||
|
||
## 11. Performance profiler (default-off, `internal/perf`)
|
||
|
||
Pad ships a built-in profiler that is **off by default** and costs nothing when
|
||
off. It is the in-app frame-timing tool (see `development_plan.md` §9: `gfxinfo`
|
||
cannot measure this app because it renders into a `SurfaceView`).
|
||
|
||
- **Enable** by creating the marker file
|
||
`/storage/emulated/0/PadPerf/enable` before launch. `main.go` then creates a
|
||
`perf.Profiler` that writes `logic_frames.csv` (one row per logic frame: seq,
|
||
ms-since-start, frame delta, page, scroll Dp, max-scroll Dp, total lines,
|
||
visible byte range, gap flag) and logs a rolling ~1 s `PERF` summary.
|
||
`DestroyEvent` stops it (final flush + `PERF stopped` summary with
|
||
p50/p90/p99/max).
|
||
- **Gap handling**: a row whose previous frame is ≥ 100 ms away is an idle
|
||
gap, not a slow frame (the first frame of a burst would otherwise carry the
|
||
whole idle period in its delta). Gap rows are flagged in the CSV, kept out
|
||
of the summary's latency percentiles, and reported separately
|
||
(`gaps=N maxGap=…ms`). A frame that arrives ≥ 2 s after the previous one
|
||
also flushes the CSV immediately: the frame that opens a new burst is the
|
||
moment the previous burst's rows become final, so an idle tail (or a
|
||
force-stopped app) does not lose the last burst.
|
||
- **Main-side presents**: `main.go` separately counts `app.FrameEvent`s and
|
||
logs a rolling `PERF-PRESENT frames=N fps=F` line; fps ≫ 1 while idle means
|
||
something is invalidating the window continuously.
|
||
- **Hook**: `internal/editor.PerfRecord` is a package-level func, set by
|
||
`main.go` only when enabled. `Logic.emitFrame` calls it on the owner
|
||
goroutine with a `ProbeRecord` **before** sending the frame. When disabled it
|
||
is `nil` and the per-frame cost is a single nil check.
|
||
- **Debug commands** (for testing, off by default): with the profiler on,
|
||
`main.go` also polls `/storage/emulated/0/PadPerf/cmd` (a one-shot file
|
||
consumed on read; `Logic.applyDebugCmd`). `top`, `bottom`, `frac <0..1>`,
|
||
and `dp <int>` jump the editor's `ScrollOffset` (clamped to
|
||
`[0, MaxScroll]`) and emit a frame; `open <path>` opens a file from any
|
||
page (same `OpenFile` path as a browser tap) and emits. This lets a test
|
||
drive scrolls and file opens deterministically without pixel taps.
|
||
- **Frame-regression guard**: frame emission is event-driven, so a healthy
|
||
app emits small per-action bursts and nothing while idle. The guard has
|
||
two RELEASE-GATE tiers and one diagnostic use:
|
||
1. `TestNoFramesWhileIdle` (internal/test/e2e, in the regular go-test
|
||
suite) asserts the logic emits ZERO frames across an idle window
|
||
after the browser and the editor (load + scroll + find cycle) settle.
|
||
2. `scripts/profile_emulator.sh`, run on the **emulator** (auto-selected;
|
||
physical devices are never auto-picked), as the pre-release checklist
|
||
item: it drives 8 s idle, open, 16 s idle, three scrolls via the debug
|
||
commands above, seeds a known 4000-line file for the open, and FAILs
|
||
if any idle-split phase of the CSV exceeds its frame budget (a ≥ 1/s
|
||
spinner exceeds a 16 s idle budget; a faster one balloons a phase or
|
||
shows up in PERF-PRESENT).
|
||
The same script on a **physical device is diagnostic only, never a gate**
|
||
(pass `-s <serial>` explicitly; a banner says so): the run force-stops the
|
||
app and seeds/removes a file in its storage, and the developer may be using
|
||
the phone while a release runs. It exists to investigate a suspected
|
||
frame/battery problem, not to certify a release.
|
||
|
||
The full release flow (gates → build → install to all connected devices,
|
||
and the policy that a phone is install-only during a release) is
|
||
`doc/release.md` + `scripts/release.sh`.
|
||
- The profiler is owned by the goroutine that creates it and is single-goroutine
|
||
(no locks). It does **not** `Sync()` the CSV per flush (only per row batch) to
|
||
avoid periodic fsync hitches in the logic path.
|
||
- **Measured** (emulator, 10 MB file, 2026-08): logic-frame cadence is flat
|
||
across scroll offsets 0.02→1.0 (no large-offset degradation); the visible byte
|
||
range stays ≤ ~4.3 KB (0.04% of the file); PSS plateaus ~250 MB (bounded
|
||
high-water mark, no leak). See `development_plan.md` Phase 6.
|
||
- **Measured** (emulator, 4000-line file, 2026-08): the pre-release profile
|
||
passes with 5 phases — browser startup 5–6 frames, open 5–6, and 1–2 per
|
||
scroll — and ZERO frames across all idle windows (PERF-PRESENT fps < 1
|
||
throughout); an injected 500 ms frame spinner makes the script FAIL
|
||
(phase 1 = 69 frames vs budget 10, PERF-PRESENT fps ≈ 2.4).
|