Windowed GUI: wm module, input routing, and the paint app

- Add the wm window-manager facility per ADR 0004: overlapping
  pixel-surface windows, damage-rectangle compositing, WM-drawn title
  bar, focus/minimize/close, and F1-F4 keybindings
- Add gop shadow compositing primitives and vt::repaint_region so the
  console stays layer 0 beneath windows
- Route mouse (absolute coords, press/release edges) and keyboard
  (focus-aware input pump) to the focused window
- Add the rspaint drawing-program crate (pen, 8 colors, clear) and shell
  draw/windows/restore commands
- Extend TaskMsg with AppMouse/Focus/Close and document the design in
  CONTEXT.md + ADR 0004

1 files changed, 78 insertions, 0 deletions

diff --git a/docs/adr/0004-windowed-gui-and-compositor.md b/docs/adr/0004-windowed-gui-and-compositor.md
new file mode 100644
index 0000000..86e8b30
--- /dev/null
+++ b/docs/adr/0004-windowed-gui-and-compositor.md
@@ -0,0 +1,78 @@
+# ADR 0004 — Overlapping-window GUI with damage-rectangle compositing and a shared-facility window manager
+
+## Status
+
+Accepted.
+
+## Context
+
+The kernel's only display surface was a single global text terminal (`vt`),
+shared by the shell, klog, and fault dumps.  We want a "proper GUI" with
+programs (a terminal, a drawing program, …).  The kernel is
+TempleOS-inspired: one identity-mapped address space, no userspace
+separation, preemptive round-robin tasks.  The display must stay viable on
+real hardware (uncached GOP framebuffers), not just fast on QEMU.  The
+existing cursor task already routed mouse events to a single "forward
+target" in anticipation of a window manager.
+
+## Decision
+
+Introduce an overlapping-window GUI:
+
+- **Window** is the fundamental unit: a rectangular, task-owned **pixel
+  surface** composited onto the fixed 800×600 canvas, with z-order.
+- **Every window is a raster surface.**  A terminal window renders its text
+  grid into its own pixels; a drawing program draws pixels directly.  One
+  content model.
+- **Damage-rectangle compositing** (not full-frame redraw) to stay
+  real-hardware-viable.  Damage granularity is **window-level first**
+  (repaint a dirty window's whole bounds) — revisit sub-window rectangles
+  if the console proves slow.
+- **Repaint** = blit the dirty window, then re-overlay any occluders above
+  it (rectangle intersection, not subtraction).
+- **The window manager is a shared facility, not a task** — in a single
+  address space there is no isolation to enforce, so a dedicated task only
+  adds round-trips.
+- **App = a task owning one window** (no separate process concept).  The
+  console is app 0.
+- **Focus = click-to-focus + raise**; keyboard and mouse go to the focused
+  window.
+- **The console is the launcher**; no taskbar/menu in the first pass.
+- **Chrome** (background, per-window title bars, later a menu) is
+  window-manager-drawn, not windows.  A title bar is a strip above a
+  **content-only** app buffer, with title, minimize, and close.
+- **Restore** of minimized windows is via a console command
+  (`windows`/`restore`) plus global **keybindings** F1–F4 (spawn terminal,
+  focus next, minimize, close); F1–F4 are reserved and invisible to apps.
+- **Window buffers** are dedicated `w×h×4` buffers allocated from the page
+  allocator (the same mechanism as the shadow backbuffer); full-screen
+  (800×600) content is allowed.
+- **Drawing is explicit** — the app writes into its buffer and calls
+  `flush()` to request a composite; there is no automatic per-tick
+  compositing.
+- **App event contract** — an app's queue delivers `Key`, `Mouse { x, y,
+  buttons, kind }` (absolute window-relative; `kind` = Move/Press/Release),
+  `Focus(bool)`, `Close`, `Timer`, and `User(u64)`.  Mouse events outside
+  the focused window's content bounds are suppressed.
+- **Minimum window size** is 64×64 content.
+- **Window lifecycle** — a window is created by and bound to its task: it
+  is freed (buffer returned) when the task exits, via a reap hook.  Close
+  is cooperative: `Close` is delivered and the app exits; three F4 presses
+  in quick succession force-teardown (free the window, kill the task).  The
+  console (app 0) never closes.
+- **Placement** — new windows cascade (+24px each, wrapping) and are
+  focused and raised on creation; the console is full-canvas at (0,0).
+  Windows are fixed-position and fixed-size in v1: move is the first
+  post-v1 feature and resize is deferred.
+
+## Consequences
+
+- Positive: one content model, one compositing path, minimal concepts.
+- Negative: window-level damage means a full-screen console repaints its
+  whole rectangle per keystroke — accepted for now, revisitable.
+- Negative: windows are fixed-size initially (no resize).
+- The existing `vt` dirty-cell path is demoted to a per-terminal-window
+  trigger; the window manager becomes the only writer of the framebuffer
+  (plus the cursor overlay).
+- Open (not yet decided): the terminal-app design (per-instance vt + shell),
+  and the save/image-format + image-viewer design (both deferred).