Pad/doc/architecture.md

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:

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).
  • Relaunch snapshot (spec §2.4): the counts are process-local (rebuilt from the all-ones estimate on relaunch; only the visible window is ever shaped), so a persisted pixel scroll offset cannot be restored by re-mapping — with every count above the restored viewport at the estimate, LineForVisual maps the offset 1:1 to a logical line deeper by all the wrapped continuations above it, with no self-correction (those lines never enter the window). The snapshot therefore persists the wrap-independent coordinates: the logical line at the viewport top (derived with the same scrollDecompose + LineForVisual mapping the layout uses, against the CURRENT index) plus the sub-line remainder; the restore re-derives the offset as line·lh + sub. The raw offset is kept as the fallback for pre-line-coordinate session files.
• 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 Regions, 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.Filters + 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.FrameEvents 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).