gmp/Pad
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
d3d11b5d20
Pad/doc/README.md
Greg Pomerantz d3d11b5d20 Doc: reorganize — delete over-detailed docs, rewrite spec + architecture to match code 
- Deleted (drift-prone point-in-time plans / dead specs):
  browser_implementation_plan.md, editor_implementation_plan.md,
  virtual_scroll_render_optimization.md, conflict_resolution.md,
  touch.md, element_model.md, layout_rendering.md, bugs.txt
- Rewrote architecture.md: single-owner/no-lock model, channel topology,
  Frame handoff contract, ownership rules, editor/browser/render internals,
  active vs dead task types, testing hooks.
- Rewrote spec.md: actual behavior (browser, editor, IME, autosave, 50 MB
  limit with measured numbers), actual code layout, invariants to preserve,
  explicit deferred-features table (undo, restoration, sync awareness).
- Added doc/README.md: doc index, documentation policy, build/install
  recipe, on-device observation loop.
- Updated development_plan.md: Phase 5 mostly done; §7 spec deltas written
  with two corrections (no undo at all; no external-change detection).
2026-08-16 13:22:21 -04:00

3.4 KiB
Raw Blame History

Pad documentation

Three documents, kept at the level of what, why, and invariants — not line-by-line code — so they stay true as the implementation evolves.

Doc What it is
spec.md What the app actually does, measured performance, the code layout, and an explicit list of deferred features.
architecture.md How it works: single-owner concurrency model, channel topology, Frame handoff contract, ownership rules, editor/browser/render internals.
development_plan.md The active plan: completed phases, remaining work, and the on-device observation loop.

Documentation policy

  1. Docs describe invariants and contracts, not code lines. If a document has to change on every refactor, it is too detailed — delete it or raise its level of abstraction. Point-in-time implementation plans are deleted once implemented (the previous *_implementation_plan.md, touch.md, element_model.md, layout_rendering.md, virtual_scroll_render_optimization.md, and conflict_resolution.md were removed in the 2026-08 doc reorganization for this reason).
  2. Unbuilt behavior is not spec'd. Requirements that are not in the code live in spec.md §7 (deferred), never as if they worked.
  3. Code wins. When doc and code disagree, fix the doc.

Build & install (Android, this workstation)

Prereqs on this box (already installed): JDK 17, Go, Android SDK at ~/android-sdk (platform-tools, build-tools 35.0.0, emulator, NDK), gogio@v0.10.0 in ~/go/bin, apktool at /tmp/apktool.jar, debug keystore at ~/.android/debug.keystore. Env vars are set in ~/.bashrc.

The full recipe is /tmp/build_pad.sh (machine-local). Steps:

  1. gogio -target android -targetsdk 35 -arch amd64 -o /tmp/pad-raw.apk . (from cmd/pad/)
  2. apktool d /tmp/pad-raw.apk -o /tmp/pad_decoded -f
  3. Inject <uses-permission android:name="android.permission.MANAGE_EXTERNAL_STORAGE"/> into the decoded AndroidManifest.xml (Android 15 needs it for /storage/emulated/0).
  4. apktool b /tmp/pad_decoded -o /tmp/pad-unsigned.apk
  5. apksigner sign --ks ~/.android/debug.keystore --ks-pass pass:android --key-pass pass:android --ks-key-alias androiddebugkey --out cmd/pad/pad-emu.apk /tmp/pad-unsigned.apk
  6. adb install -r cmd/pad/pad-emu.apk

Run the emulator (headless, AVD pad_avd, API 35):

nohup emulator -avd pad_avd -no-window -no-audio -no-boot-anim \
  -gpu swiftshader_indirect >/tmp/emulator.log 2>&1 &

App package/activity: pad.pad / org.gioui.GioActivity. Default root directory: /storage/emulated/0/Notes (push test files there with adb push file /storage/emulated/0/Notes/).

On-device observation loop (quick reference)

Gio renders into one GL surface, so the authoritative debug signals are data, not pixels:

  • adb logcat -s pad.pad — app log (IME commits, open-file timing, errors).
  • adb shell input tap|swipe|text — drive the UI (see development_plan.md for the tap coordinates and IME-tap cadence that works).
  • Autosave debounce is 1 s: wait ~1.6 s before reading a file back from disk after typing.
  • Memory: adb shell dumpsys meminfo pad.pad (watch PSS/RSS; the 3.8 GB emulator OOMs the app above ~2.5 GB RSS).
  • Screenshots (adb exec-out screencap -p > /tmp/x.png) are an auxiliary check only — state, logcat, and file diffs are authoritative.