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.