SouveraineOS/HANDOFF-2026-08-05-navigation.md

# Handoff — 2026-08-05, navigation & the window sheet

**Your job first: audit what this session did against the docs, then judge
whether it actually delivered Casey's ask.** Do not start new work until you
have. Several things were built fast and one was built wrong and rewritten.

## Read these FULLY. Do not grep them.

Grepping these produces confident, wrong architecture — it is the single most
reliable failure in this project, and it is written down in three places.

1. `SouveraineOS/START-HERE.md`
2. `SouveraineOS/docs/tasks/55-hand-verbs-on-the-glass.md` — the sheet; most of
   this session is its "what landed" section
3. `SouveraineOS/docs/tasks/60-the-multitasking-view.md` — written after the
   multitasking view was built wrong and Casey said so. **Uncommitted.**
4. `SouveraineOS/docs/SESSION-AUTHORITY-DOCTRINE.md` — §13 first, then §4, §9-11
5. `SouveraineOS/docs/DEVICE-STATE-MACHINE.md` — §1, §4, §12
6. `SouveraineOS/docs/LOCK-DPMS-LESSONS.md` — §1 is the lock-then-blank invariant
7. `souveraine-viewtop/docs/SHELL-BOUNDARY.md` — the engine runs in-process
8. `souveraine-viewtop/crates/compositor/src/workspace.rs` — header only; the
   zone model, and why a zone exists because something is on it
9. `souveraine-viewtop/crates/compositor/src/gesture.rs` — header only; the
   compositor recognises, the shell draws
10. `SouveraineOS/docs/tasks/59-her-face-on-the-glass.md` — TASK-59 phase 1
    passed on hardware; phase 2 is unstarted

## State of the tree — READ THIS BEFORE TOUCHING ANYTHING

- **`souveraine` has UNCOMMITTED work.** `ZoneOverview.qml` (new), the rail's
  gesture rewrite, `Overview.qml` rewired to zone cards, `deploy.sh` manifest,
  `ViewtopControl.qml`. It is **deployed to the phone** and **not committed**.
  Commit or discard deliberately; do not deploy over it without looking.
- **`souveraine-viewtop` is pushed** at `8e6700b` and **not yet on the phone**.
  The device runs `r84.g2d0ffdc`. So the compositor there does not yet report
  `focused`, `app_id` or `title` — which `ZoneOverview` needs to group and
  label cards. **Until `r85+` installs, the new overview will draw zones but
  its cards cannot match pictures to windows.** That is expected, not a bug.
- CI publishes automatically now: green `main` on viewtop dispatches
  Pixel3Arch's `packages.yml`. Verified end-to-end (run 1176 → 1177).

## What was asked, and what happened

Casey's asks, in order given:

1. **Remove three-finger tap from everything binding it** — done. It opened the
   overview; `Action::Overview` is gone.
2. **Three-finger tap opens an overlay on the app: resize, split, close** —
   built (`WindowSheet.qml`), deployed. Now four buttons: Move, Resize, Split,
   Close. Close is polite on tap, `kill` on a 1 s hold.
3. **Zones/states, not workspaces; drop Hyprland verbiage** — done in new code
   and in the shell. **The wire op is still spelled `workspace`** and the
   compositor's `workspace.rs` still uses the old noun throughout. A rename
   sweep is owed and was deliberately not started.
4. **Long-press power → context overlay** — built (`PowerMenu.qml`), shows real
   USB-C data role + charger state. Not lock-gated.
5. **Short swipe → multitasking, long swipe → home; dock always on zone one** —
   built. Home is 18% of panel height.
6. **Multitasking must show all backgrounded zones including splits** —
   **this is the one that was built wrong twice.** First as a live scale of the
   active zone (a transition mistaken for a destination), then rewritten as
   `ZoneOverview.qml`. **The rewrite is deployed but UNVERIFIED on glass.**
   TASK-60 holds the design questions that were answered by fiat, not by Casey:
   card = zone, `ScreencopyView` per window inside it, focus reported by the
   compositor, refresh on open, scale-on-drag deleted. **Check those against
   what he actually wanted.**

## Bugs found and fixed, worth verifying rather than trusting

- **`pose` never worked.** It was applied by passing a smaller scale to
  `render_elements_from_surface_tree`, which positions but does not resize; the
  size comes from `Element::geometry(scale)`, called later with the *output*
  scale. Windows moved and never shrank. Fixed with `RescaleRenderElement`.
  Casey diagnosed it precisely: *"the content slid to meet the upper left
  corner instead of shrinking."* **Verify on glass — it was confirmed broken by
  eye, and the fix has not been confirmed the same way.**
- **Firefox drew off-centre** because the main render path never subtracted
  `window.geometry().loc` (CSD shadow inset). The popup and capture paths both
  did. Fixed. Not folded into `window_origin` on purpose — that feeds the hit
  test, and correcting it there would move touch targets instead.
- **Every window got two zone-membership entries** — `new_toplevel` had a
  pre-existing `on_workspace.push` plus the new explicit claim. Duplicates keep
  empty zones alive forever, which is what `prune_workspaces` exists to prevent.
- **Three-finger drag deleted outright**, not retuned: it beat the tap to nearly
  every gesture. The window carry came back as `grab`/`drop`, entered from the
  sheet. While grabbed, `Route::Client` becomes `Withheld` so the app underneath
  stops receiving the finger.
- **CI never published viewtop.** Its own workflow only ran fmt/clippy/test/
  cross-build. Fixed by dispatching Pixel3Arch's job on green `main`; the 403
  was `LOCAL_GITEA_TOKEN` existing only as a Pixel3Arch repo secret.

## Known-not-done — say so rather than discovering it later

- **The dock when an app opens.** Casey asked twice; never resolved. The dock is
  a *global* layer surface whose visibility is now *per-zone* (pinned on home).
  Its exclusive zone may still reserve space on every zone. Needs eyes on glass.
- **A real resize handle.** Resize cycles half → two-thirds → full. No corner
  drag.
- **Widgets on zone one.** It is kept clear and never pruned; nothing fills it.
- **The runtime-lock paint gap.** Power → black → lockscreen paints → blank.
  Decisions are correctly ordered (`lock-before-blank` → `lock-directive` →
  `panel-off`); the black is `frame_elements` compositing lock surfaces *and
  nothing else* while the shell's lock surface has not painted. Casey's rule:
  lock, confirm the lockscreen is up, *then* blank — which is viewtop's to
  attest, since only it knows a lock surface is presented on every output.
- **Casey's OSK bug from the morning handoff** (search bar "jerked", keyboard
  did not open) — never investigated. Untouched by this session.
- **`app_id`+`title` as a join key is approximate.** Two terminals with the same
  title collide. The sound fix is a shared id in foreign-toplevel.

## The trap that cost this session the most time

Reaching for the phone's control socket earlier would have saved an hour:
`$XDG_RUNTIME_DIR/souveraine/viewtop.sock`, one JSON object per line.
`{"op":"describe"}` is the authoritative verb table, `{"op":"workspaces"}` lists
zones and windows, and `{"op":"scene","intent":"close","id":N}` closed two apps
Casey could not close — no rebuild, no deploy. The phone has no socat/nc but has
python3.

Also: `qs -c souveraine ipc …` needs `WAYLAND_DISPLAY` set or it reports "no
running instances" while the shell is plainly running. sessiond has it; an ssh
session does not.