Pad/doc/spec.md

Pad — Text Editor Specification

This is the specification of what Pad actually is (v1, current code). Behavior that was once spec'd but never built is listed as deferred in §7, not described as a requirement. If code and this document disagree, the code wins — and this document should be fixed.

1. Overview

Pad is a minimal plain-text editor for Android, written in Go with the Gio UI framework. It presents a single root directory of text files (a browser) and a full-screen editor with the Android soft keyboard. The design goal is a fast, honest editor for a directory that is synced across devices — instant open, autosave on every edit, and large files that stay smooth.

Design philosophy:

• Plain text only — no formatting, no syntax highlighting.
• Automatic everything — autosave with a 1 s debounce; there is no save button.
• Minimal surface area — a browser and an editor, nothing else.
• Bounded memory — a measured file-size limit with an explicit "too large" state, instead of silently degrading or OOMing.

Platform: Android-first. Window 390×844 dp. Default root directory is /storage/emulated/0/Notes on Android (overridable with -root); . elsewhere.

2. Implemented behavior

2.1 File browser

• Lists files and directories under the current directory.
• Sort: four modes — name asc/desc, date asc/desc — cycled by the sort button. Default: date descending (newest first).
• Search: incremental, case-insensitive filter over entry names via the search bar (a Gio widget.Editor).
• Pagination: directory entries are loaded asynchronously in pages through the worker pool; the first paint does not wait for a full directory read.
• Navigation: tap a directory to enter it, back to return. Single tap opens a file — no long-press menus, no file management actions.

2.2 Editor

• Input via the Android IME: soft-keyboard typing, composition, backspace, and autocorrect replacements all arrive through one IME replace-range path and are converted from rune indices to byte offsets. (Swipe-typing support follows from the same IME path; final sign-off on a physical device is the one open validation item.)
• Word wrap: on by default; wrapped lines are virtual — the buffer stores only real newlines.
• Virtualized viewport: only the visible byte range is shaped and drawn each frame (typically ~4 KB of a large file), keeping frame cost and shaper memory constant regardless of file size.
• Cursor + scroll: tap to place the cursor, drag/scroll to pan; with a hardware keyboard, arrow keys, Home/End, and Page Up/Down move the cursor (verified on the Android emulator; Gio's mobile focus-navigation default for arrow keys is overridden — see architecture.md §2.1).
• Text selection: shift+arrow (hardware keyboard) extends a selection; insert, backspace, and delete replace the selected text; the IME replaces a selection when the user types over it. The selection is highlighted in the editor and pushed to the IME. (Shift state is tracked by the app, since Gio's Android bridge drops modifier keys — architecture.md §2.1.)
• Autosave: every edit restarts a 1 s debounce; on expiry the full content is written to disk by a worker. Failed writes are retried. This is the only persistence mechanism.

2.3 Large files (measured)

• Editable limit: 50 MB (MaxEditableFileSize), measured on-device: a 10 MB file (130,954 lines) opens in ~120 ms (stat ~76 ms, read ~27 ms, line-index ~18 ms) and idles at ~150 MB PSS / ~230 MB RSS, flat under scroll. 50 MB extrapolates to a few hundred MB — acceptable on a modern phone.
• Files above the limit open into a "too large to edit" state: a notice is shown, edit operations are no-ops, and the browser still lists the file.
• The buffer is chunked (64 KB chunks, prefix-sum offsets, full load for in-range files); edits splice only affected chunks. Details: architecture.md §6.

3. Code organization (actual)

cmd/pad/                  # Gio entry point, main loop, frameReceiver,
                          # Android defaults (impl_android.go)
internal/
  browser/                # BrowserState, BrowserManager, sort, search,
                          # pagination, layout, handlers
  editor/                 # Logic goroutine, State, ChunkedBuffer, LineIndex,
                          # IME handling, autosave, Frame handoff (frame.go)
  io/pool/                # Worker pool (priority lanes), task types,
                          #   real/  — real filesystem (rooted at /)
                          #   mock/  — in-memory FS for tests
                          #   types/ — shared types (LineIndex, ...)
  ui/                     # Element model, Renderer, units (Dp/Px), theme
  ui/icons/               # Vector icons
  test/e2e/               # Logic-level e2e harness + tests
doc/                      # spec.md (this file), architecture.md,
                          # development_plan.md

4. Architecture (summary)

The logic goroutine is the sole owner of mutable state; the main (Gio) goroutine reads only a Frame snapshot and writes only via channels; a frame-receiver goroutine stores frames and invalidates the window; a priority-aware worker pool does all file I/O. No mutex guards application state. The IME snippet, search box, and gesture state live on the main-goroutine side because Gio mutates them during draw.

Full details, channel topology, and ownership rules: architecture.md.

5. Invariants to preserve (future development must not break these)

1. Single owner, no locks on state (architecture.md §1). Any new feature adds a channel or an owner-executed callback — never a direct state touch from another goroutine.
2. Main never reads logic State — only the Frame snapshot.
3. Never shape the whole file. The text shaper's internal line storage retains the largest layout ever performed; one whole-file layout permanently inflates memory (this caused a 1 GB leak, fixed in Phase 3).
4. The IME snippet is the visible window, and rune↔byte conversion happens in one place (HandleReplaceRange / RuneIndexToByte).
5. Autosave is the only persistence. If state persistence (last file, cursor, scroll) is added later, it must go through the same owner-dispatches-a-task pattern.
6. Logic work stays < 16 ms. Anything that can block or scan more than the viewport goes to the worker pool.
7. Scroll offset is always clamped to [0, maxScroll], where maxScroll = contentHeight − viewportHeight floored at 0. A file whose content fits the viewport has maxScroll = 0 and cannot scroll. Verified on-device across 2→130,955 lines (development_plan.md Phase 6).

6. Performance expectations (validated on-device)

Operation	Target	Measured (10 MB file, Android 35 emulator)
Open file	instant feel	~120 ms (stat + read + line index)
Scroll	60 fps	logic-frame cadence flat across offsets 0.02→1.0 — no large-offset degradation; present fps is emulator-limited (~14–27 on the software-rendered emulator, not a Pad quality metric)
Type	responsive	single IME path; rapid commits land cleanly
Memory	bounded	PSS plateaus ~250 MB at a 10 MB file (bounded high-water mark, no growth under sustained scroll; no OOM)

7. Deferred / not implemented (explicit non-goals for v1)

These were in the original v1 spec but are not in the code. They are recorded here so future rounds don't mistake doc text for behavior:

Feature	Status	Notes
Undo (any)	not implemented	No undo stack exists; the old SaveUndoTask is dead code.
State restoration on relaunch	not implemented	Last file / cursor / scroll are not persisted.
External change detection	not implemented	No mtime compare on open/resume, no watcher, no Keep/Reload prompt.
Syncthing conflict handling	not implemented	No .sync-conflict-* file detection or merging.
File-system watcher	not implemented	Browser does not live-refresh; it re-scans on navigation.
Alphabetical index sidebar	not implemented	AlphaIndex element exists but is unused.
In-file search, tabs, split view	not implemented	—
Touch selection (long-press, drag handles)	not implemented	Selection is reachable only via hardware-keyboard shift+arrow; touch users can position the caret by tap.
Files > 50 MB	not supported	TooLarge state instead.
Desktop / other platforms	not supported	Android-first.

8. Product requirements (standing)

Requirement	Detail
Instant open	Files open without visible lag; content and line index load async.
Auto-save	Every edit persisted with a 1 s debounce; no save button.
External change awareness	Deferred (§7) — the sync-awareness story is explicitly out of v1.
Plain text only	No formatting, no highlighting, no file management UI.
Bounded memory	50 MB editable limit with an explicit "too large" state.