SouveraineOS/docs/tasks/60-the-multitasking-view.md

TASK 60 — multitasking is a place, not a transition

Status: 2026-08-07 (latest) — both halves are built and the strand repro passes on hardware. The compositor owns the transition geometry; the shell drives it through four verbs and names the card rect once. Read "One owner" for why, then "Shell half: DONE" for what landed.

One owner — the rebuild, 2026-08-07

The fault, stated once

Two writers own one geometry. The rail scales the real windows through pose; ZoneOverview scales its cards through scale. Both read zonePullProgress, and a session was spent trying to make the two numbers agree — the card ran 0.6 → 1.0 while the pose ran 1.0 → 0.6, so at the handoff the window was at 0.6 of the glass and the card arrived near full bleed.

That is DEVICE-STATE-MACHINE.md §1's blind actors in the render path, and TASK-52 names the same rule for exactly this reason: one attention model, one clock, effects as strategies over it. Every symptom is the one fault — the size pop, the doubled frame (viewtop's 3 px #9EC7FF under the card's radius: 18), and the strand.

The strand is the proof. Casey, 2026-08-07: open btop, swipe to multitasking, tap Home, reopen multitasking, tap btop — btop comes back as a small card in the middle of the screen. Every clear-the-pose path built that day hangs off the rail's drag edge (endPull → clearPose). Those taps are ZoneOverview's and never touch the rail, so nothing ever runs. A transform that one surface applies and a different surface must remember to undo will always have a path that forgets. Note also that pose is TASK-52 #10, gravity wells — an atmosphere primitive that navigation borrowed.

What the prior art does — quickstep, on this machine

~/Downloads/lineage-trebuchet/quickstep/src/com/android/quickstep/.

• One float. SwipeUpAnimationLogic.mCurrentShift ∈ [0,1] — its own comment: 0 = preview snapshot completely visible, 1 = "preview snapshot completely aligned with the recents view". TaskViewSimulator transforms the live window onto the real card rect. The card never has to be made to match the window, because the window is placed on the card. There is no second geometry.
• The drag length is derived from the destination. getSwipeUpDestinationAndLength(dp, ctx, TEMP_RECT, …) returns the rect and the length together, and mDragLengthFactor = dp.heightPx / mTransitionDragLength. Our missionAt is 18% of the panel, a number with no relationship to where the card actually is.
• End targets are an enum, not a set of booleans: HOME, RECENTS, NEW_TASK, LAST_TASK, ALL_APPS (GestureState.java:77). Every gesture resolves to exactly one, and LAST_TASK is a first-class destination — "went back to the app" is a real endpoint that animates, not an abandon branch.
• The controller owns the transform and hands it back at the endpoint. Nothing hopefully-undoes anything, which is structurally why Android cannot strand a window and we can.
• Dwell is first-class. isFling = mGestureStarted && !mIsMotionPaused && |endVelocity| > threshold, and in gestural mode mIsMotionPaused → RECENTS (AbsSwipeUpHandler:1121,1322). A pause is never a fling. MIN_PROGRESS_FOR_OVERVIEW = 0.7.

Sailfish/Glacier (~/phone-qml-research/glacier-home) is the QML-side reference for the same shape and is worth reading before the shell half.

The plan

1. One owner of the geometry. The compositor owns the transition: one verb carrying shift 0→1, where 1 means the window sits exactly on its card rect. The destination rect is named once at gesture start, not re-derived per frame. The shell stops calling poseActiveZone for navigation and stops scaling cards; ZoneOverview draws chrome — label, close control, neighbours — and never a competing transform.
2. End targets as an enum. One end-target state replaces missionControlOpen / overviewOpen / zonePullProgress. Entering and leaving become the same machinery whether the gesture came from the pill or from a card tap — which is precisely what the strand repro broke. LastTask is a destination, so the transform is released by arriving, not by remembering to clear.
3. Detents from the destination rect, not 18%. Keep the dwell; make "paused is never a fling" explicit rather than emergent.
4. One frame. A window inside the transition is furniture in the overview's composition, so focus_border suppresses itself while a window is owned by the transition and the card carries the chrome.

Compositor half: DONE 2026-08-07 (souveraine-viewtop 3c85397)

Gates green on archdev — 239 tests, cargo fmt, workspace clippy and --features kms clippy, all -D warnings. Not yet on the phone: needs a CI package and a session restart.

• crates/compositor/src/transition.rs — the state. begin(&[TransitionTarget]) / shift_to(0..=1) / commit(EndTarget) / cancel() / forget(id), seven unit tests. Empty begin refused; forget on the last leg ends the flight; forget is wired to surface destruction beside navigation.forget.
• Wire: OverviewBegin { to } / OverviewProgress { progress } / OverviewCommit { target } / OverviewCancel, plus TransitionTarget and EndTarget (home | overview | last_zone | zone{zone}), all four in the verb table.
• Geometry: Viewtop::carried(window) returns the lerped origin and scale, and window_origin and window_extent both consult it, so the render and the hit test inherit the carry with no call-site changes. Anchor is (0,0) on purpose so pose_origin's pivot term vanishes.
• focus_border returns empty while a window is carried — the card owns the frame.

Shell half: DONE 2026-08-07 (souveraine)

services/ZoneTransition.qml is the one owner: the card rect, the four verbs, the end-target table, and the clock. ZoneOverview and the rail both read it and neither derives a geometry.

Deleted, not adapted — ViewtopControl.poseActiveZone / clearPose / _posed, zoneCard.scale, and GlobalStates.zonePullProgress. The card's inner ColumnLayout went too: its 8 px margin was a second opinion about where a window sits inside its zone. Panes are now the compositor's own tiling scaled, so a split zone draws as what it is.

One clock, two strategies. The rail reports travel and interprets nothing. ZoneTransition derives shift (what the compositor carries on, clamped) and presence (how present the destination is, rising to the detent then receding past it, so a home-bound pull never previews somewhere the release will not go). Two curves is correct; two places was the bug, and putting the second one on the rail was the first thing tried here and reverted. TASK-52's rule — one clock, effects as strategies over it — is the same rule as "one owner", a level up, and pose is a gravity well borrowed from those primitives, so this is her felt environment, not merely navigation chrome.

What actually made the swipe feel wrong

Not the dwell gate. The release committed where the thumb left it. Lift at 60% of the climb and the carry was released at 60%, so the window jumped to its final state with no travel — two motions with a cut between them. Every attempt to fix this by tuning fades was treating the symptom.

quickstep does not do that (AbsSwipeUpHandler.handleNormalGestureEnd):

float endShift = endTarget.isLauncher ? 1 : 0;
long expectedDuration = Math.abs(Math.round((endShift - currentShift)
        * MAX_SWIPE_DURATION * SWIPE_DURATION_MULTIPLIER));
duration = Math.min(MAX_SWIPE_DURATION, expectedDuration);
startShift = currentShift;

ZoneTransition.settleTo() is that, with the same numbers — 350 ms cap, multiplier min(1/0.7, 1/0.3) from MIN_PROGRESS_FOR_OVERVIEW. Every release travels to its destination and commits on arrival, including the abandoned half-swipe (last_zone, end shift 0), which is the commonest gesture of all and used to snap.

Correcting a claim made earlier in this session: the dwell gate was restored after reading the source. quickstep gates the same way and the "ever" is a latch, not a level:

recentsAttachedToAppWindow = mHasMotionEverBeenPaused || mIsLikelyToStartNewTask;

Removing it went against prior art. A fast unpaused flick showing no destination on its way past is correct.

Measured on hardware (10.10.30.213, viewtop r97.g3c853972)

• The carry lands where it is told: target (135,280) 270×520 logical → (271,561) 539×1035 physical at scale 2.0. focus_border correctly absent.
• Shell-driven: card (73.9, 12.0) 392.2×784.4, scale 0.7263; carried window measured (148,89)–(931,1590) against predicted (147.8,82.1)–(932.2,1592.7).
• The strand repro passes, three times across three shell builds.

The geometry is measured now, not assumed

ZoneTransition took the card's box from screen.height * 0.78. The overview PanelWindow respects exclusive zones, so its height changes underneath: read once as 1040 (something reserving 40 px) and once as 1080. The assumption was right today and would have drifted silently the moment the dock reserved. The surface reports its own rect through measuredAt(), and carryState prints surface beside panelWindow so a card in the wrong place is read, not theorised — the same reason state exists at all.

Two findings that are not this task's

1. A synthesized touch cannot reach the pill. furniture_at() returns None unconditionally and deliberately (wayland.rs:4490: "until the engine publishes a region layout, nothing is furniture and every touch is session content"), so an agent's touch_down on the rail lands on the client window behind it. This is the structural argument for "it has to be a verb" below — the touch path cannot drive the pill today. A drawn hand (Casey, 2026-08-07, art in progress) rides on the verbs and does not wait on this.
2. Origin is two-valued, so on-device Ani and a remote caller over the socket are indistinguishable, and an agent touch leaves no trail at all — is_evidence() is false by design. Evidence ("does the machine think a human is here") and audit ("who did what") are different questions and only the first is answered. TASK-41's attested producers is where the second lives.

Still unseen on glass: a split zone's card, which is right by construction (each pane is the compositor's reported rect scaled) but has not been exercised.

Shell half: the plan as written (kept for the argument)

Rewrite the pill and ZoneOverview to drive the four verbs instead of posing windows and scaling cards independently.

1. ZoneOverview computes each zone card's rect in panel coordinates. That rect — not 0.6, not an inset — is the TransitionTarget for the windows on that zone.
2. SystemGestureRail.onPressed → overview_begin with those rects. onPositionChanged → overview_progress. Release → overview_commit with the end target chosen from projected travel and dwell, or overview_cancel.
3. Delete ViewtopControl.poseActiveZone / clearPose / _posed and GlobalStates.zonePullProgress's pose duties, and drop zoneCard.scale entirely — the compositor is now carrying the real window onto that rect, so a card that also scales is the second writer all over again. The card becomes chrome: label, close control, and the neighbours either side.
4. Tapping a card is overview_commit { target: zone } — which is what makes the strand repro pass, because that path now releases like every other.

Today's four shell commits (57208c8, f699f57, 452acea, 72171ac) are the two-writer design and step 3 deletes most of them. Kept on the phone meanwhile because the sizes at least agree.

It has to be a verb, because she gives the tour

Casey, 2026-08-07: there is a point where an agent is asked for a tour or a demo of the phone, "and that does mean even these little gesture steps will be possible." So the transition is a verb with a caller, not a side effect of a touch handler — shift and the end target are both reachable from the verb table, or a tour is impossible and TASK-30's third capability enumeration grows a fourth.

The principles that already govern her hand govern this too, and they are built (input.rs):

• Origin::{Physical, Agent}, carried from the source, never a caller-set field.
• AGENT_SLOT_BASE = 1 << 16, so a synthesized contact cannot land on a slot a thumb owns.
• Origin::is_evidence() — an agent-driven tour must not be evidence. A demo that raises observed_confidence or feeds the idle budget is the machine believing a human is present because she moved a window.
• Step-up stays human-only, and already is: input.rs:432 routes Origin::Physical => Route::LockSurface and Origin::Agent => Route::Withheld("the lock surface takes fingers, not the agent"). The navigation verb must not become a way around that.

Connects to TASK-50 (the same origin machinery, and the inverse mapping pose owes the hit test) and doctrine §13 (the 60 is hers; the credential is the 40).

2026-08-07 — the cards were zero pixels wide

Reported as "it goes to a blur screen but nothing else", and every signal read healthy: zones 2, windows 1, subscribed true, loader active, item present, opacity 1, progress 1. The blur was the backdrop; the cards were there and 540 px shorter than nothing — item.w: 0, h: 842.

ZoneOverview took its width from the Column it sits in, and a Column is as wide as its widest child. In the drawer the search widget supplies that width; mission control is the cards alone and has no search, so the only child left was the loader — whose width came from the column, whose width came from the loader. The cycle resolves to zero. Bound to panelWindow.width instead, which is what this surface covers anyway (its mask is missionBackdrop, not the drawer's sheet).

Two things that made it findable, and are worth keeping:

• overview missionControl and overview state verbs. The one surface reported broken was the only one nothing but a pill swipe could raise, so it could not be inspected or tested. state reports what the cards are drawn from, and reading item.w: 0 beside column.w: 0 is what located this in one step after a long time spent on wrong theories.
• A false lead worth recording: the compositor was refusing every capture with "no client captures the screen behind a lock screen", and grim hung the same way the cards did. That is correct behaviour behind a lock — the session had been left locked by a test. Capture was never the problem. Check locked in state before concluding anything from a capture failure.

Cards are inset (26 px sides, 12 top) so neighbouring zones show through — full-bleed reads as "you are looking at that app" rather than "here are the places you can go", and leaves nothing on screen saying there ARE neighbours.

Still open: the swipe in

Casey, 2026-08-07: "the visual style from swiping up into this mode... we lost the consistency... the swipe to this swap is awkward."

The machinery exists and is where to look. ZoneOverview.progress follows GlobalStates.zonePullProgress while the rail is pulling and the state flag takes over on commit — this task's own acceptance is "no frame where a window is scaled by one and laid out by the other." Two concrete suspects:

1. Cards start at scale 0.6 + 0.4 * share, chosen to match the scale the rail's pose has reached at the multitasking detent. 0.6 is a written-down constant; if the rail's actual pose there is not 0.6, the card pops to a different size at handoff.
2. The inset above makes the card smaller than the full-bleed window it replaces at the handoff moment, which may have made that seam worse. Either the rail's pose should end at the inset card's rect, or the inset should animate in after the handoff rather than being there at share = 0.

Needs watching in motion. Screenshots cannot see it.

Original — design, 2026-08-05

Written after building the wrong thing and being told so. Casey, on device:

"Still major issues. We might need to take these concepts we've built back to the workshop. The scaling doesn't follow the selected app. meaning app#2 opened even if focused is not scalling down. Second, all we have is scaling; it's supposed to be showing me all sorta backgrounded zones; including split zones. You've seen macOS. That whole multitasking view is a function of it's own."

Repo: souveraine (shell surfaces), souveraine-viewtop (capture + zone facts).

What was built, and why it is not the thing

The rail's short swipe scales the live windows on the active zone from 1.0 to 0.6 as the thumb climbs (ViewtopControl.poseActiveZone), then opens GlobalStates.missionControlOpen. That is a transition — the animation of leaving an app — and it was mistaken for the destination.

Two failures follow from that mistake, and both were seen on hardware:

1. It scales the wrong windows. poseActiveZone poses everything whose workspace matches ViewtopControl.activeZone, and that list comes from a 2-second poll of {"op":"workspaces"}. Open a second app and the poll has not caught up, so the newly focused window is not in the set being scaled. There is no "focused window" fact in the shell at all — the compositor knows it (Surface::focused) and does not report it in the workspaces reply.
2. Scaling one zone is not a view of all of them. Even done perfectly, it shows the zone you are already on, smaller. It cannot show what is backgrounded, which is the entire question multitasking answers.

What exists

Piece	Where	State
WindowOverview.qml	modules/souveraine/navigation/	One column of equal cards, one per window, live ScreencopyView texture, flick-up to dismiss
Zone facts	{"op":"workspaces"}	count, active, offset (the float the strip is scrolled to), settled, and per window {id, workspace, at, size}
Per-window capture	viewtop, since 2026-08-03	A card can show a window rather than the screen covering it
pose / unpose	viewtop	Now genuinely scales content (fixed 2026-08-05 — it had only ever moved it)

WindowOverview.qml's own header states the gap: "viewtop has them [workspaces], and they are not Hyprland's: a continuous strip that grows when a window needs a room and shrinks when the last one leaves… That is a thing this overview could draw and does not yet." This task is that sentence.

What macOS actually does, since it is the named reference

Mission Control is two levels in one surface: a row of spaces across the top, and the windows of the current space spread below. Neither alone is the feature — the row answers "where else am I?" and the spread answers "what is here?". Dragging a window onto a space in the row moves it there, which is the same gesture doing placement.

Ours differs in one load-bearing way and it must not be papered over: macOS spaces are a fixed set the user creates; viewtop's zones are minted and destroyed by need (workspace.rs: "a workspace exists because something is on it"). A row of zones is therefore a row that grows and shrinks under you, and home is the one that is always there and always empty.

The questions

Q1. What is a card — a window, or a zone?

Today it is a window. macOS says both, at two levels. A phone has room for one level at a time. Options: zones-as-cards with their windows composited inside (split zones then read correctly, which is Casey's explicit ask); windows-as- cards grouped by zone; or a two-level surface where the zone row is a strip and tapping one spreads its windows. Q's real content: a split zone has two windows and must look like one thing you can switch to, not two.

Q2. Live textures, or posed real windows?

Two mechanisms now exist and they are not the same:

• ScreencopyView — a live picture. Cheap to lay out anywhere, but it is not the window; input goes to the card.
• pose — the real window, scaled, still touchable through unpose's inverse mapping.

The reference compositor composes client windows as external textures directly into the shell's scene, which is the third answer and the one the in-process Flutter shell would make natural (SHELL-BOUNDARY.md). Choosing here decides whether the overview is a gallery of pictures or the actual desktop, zoomed out — and whether the transition can be continuous into it.

Q3. Where does the focused window come from?

The shell has no such fact. Surface::focused exists in the compositor's registry and is not in the workspaces reply. Any answer to Q1 needs it, and it should be reported rather than inferred — inferring "the last window I saw open" is the kind of shadow copy §4 spends its whole argument against.

Q4. Is the poll acceptable?

ViewtopControl polls every 2 s. That is already the proximate cause of failure

1. A view built on it will be wrong every time something changes faster than two seconds — which is every gesture. Either the compositor pushes zone/window changes, or this surface asks synchronously when it opens and stops guessing in between. Design the push channel; it is owed anyway.

Q5. What does the transition become?

If the destination is a real view, the scale-on-drag is either (a) the first frames of it, continuous into the cards, or (b) noise that should be deleted. macOS and Phosh both do (a) — Phosh's home.c is a drag surface travelling between two states, not a button. (a) is better and harder: it means the transition and the view share one progress value, which is the reference overview's whole trick (WindowOverview.qml already cites it: "one progress driving everything").

Q6. What can you do to a card?

Switch to it, certainly. Close it — the close/kill verbs exist. Move a window between zones — {"op":"workspace","to":N,"surface":id} exists too, so drag-a-card-onto-a-zone is reachable today. Decide before building, because it changes whether cards need to be drag targets.

Acceptance (measured, on the phone)

• Every zone with something on it is represented, and a split zone reads as one destination containing two windows — not as two unrelated cards.
• The view reflects state at the moment it opened, not up to two seconds stale. Open an app, immediately open multitasking: the new app is there.
• Tapping a card goes to that zone. Home is reachable from it.
• Whatever drives the transition and whatever draws the view agree — no frame where a window is scaled by one and laid out by the other. Met by there being one geometry, not by two that were tuned to match.
• The scale-on-drag either continues into the view or is gone. Not both.
• The strand repro passes. btop → multitasking → Home → multitasking → tap btop, and btop is full size. No path leaves a window transformed, including the ones that never touch the rail.
• The gesture is reachable as a verb. An agent can drive shift and pick an end target well enough to demo multitasking, and the run leaves Origin::Agent throughout: no evidence, no idle-budget credit, no route to the lock surface.

Connects to

TASK-14 (the overview pane and its app grid; "a grid of workspace thumbnails is dead weight on a phone" is the constraint that made cards windows in the first place), TASK-55 (the sheet, and ViewtopControl as the one path to scene verbs), TASK-43 (the compositor's surface model and per-window capture), TASK-52 (atmosphere — pose is a gravity well and this is its first real user), VIEWTOP-AND-DENIAL.md (external textures into the shell's scene; Q2's third answer), SHELL-BOUNDARY.md (the in-process shell that would make it natural).