Video card trap: root cause, fix, and board verification

Evidence class: board webcam recording with injected touch (evdev, via evemu-device/tools/inject-tap.sh) for the open and close gestures, plus the compositor’s own card_shell debug/step IPC (swaymsg card_shell previous|next|debug-scene) used to select a card deterministically for the switch step — the deck’s own per-card screen rects are not exposed by any external query, and a hand-computed guess at their pixels proved unreliable for a horizontal drag. Not a real finger. Captured 2026-09-26.

The report

“the video’s on the screen and i can’t close it or interact with the screen any more”. The coordinator stopped it with k230-video-session stop. The compositor log from the incident:

for_window '[app_id="^k230-video-(software|mvx)$"]' matches view ...
  cmd: 'card_shell ordinary, floating enable, resize set 100 ppt 100 ppt, move position 0 0'
K230_CARD_SHELL map id=12 class=2
K230_CARD_SHELL restored focus=12 message=10   (repeated on every later gesture)

message=10 is CS_MESSAGE_FAILED: the overview never opened, and cs_leave’s fallback re-focused the same full-screen video (id 12) every time — the trap.

Root cause

nix/card-shell/adapter.c’s sync_card/sync_scene_impl feed the direct-switch entry gesture’s anchor math (cs_entry_set_geometry) the card’s source rect: the on-screen box the app is dragged away from. For every other app this is view->geometry.width/height, because a well-behaved xdg_shell client acks the compositor’s resize set 100 ppt 100 ppt and its own reported window geometry ends up matching the container’s real, full-panel size.

mpv’s --vo=wlshm (launched by nix/video-session.py with --force-window=yes --geometry=480x270 or 568x320) does not: it ignores the resize configure entirely and keeps reporting its small initial decode buffer as view->geometry forever, even once card_shell_commit’s ordinary_resize has put its container at the full 568x1232 panel size. Confirmed live on the board via swaymsg -t get_tree while a video card was mapped:

"rect":        {"x": 0, "y": 0, "width": 568, "height": 1232}   # container: correct, full panel
"window_rect": {"x": 0, "y": 0, "width": 568, "height": 1232}   # correct
"geometry":    {"x": 0, "y": 0, "width": 480, "height": 270}    # view's own geometry: stale, the launch size

Feeding that stale 480x270 into cs_entry_set_geometry as the source rect puts the gesture’s anchor point far past the bottom of the screen (the anchor fraction (edge.y-source_y)/source_height blows up with the tiny source_height), so travel < config.entry_distance and the call is rejected on the very first frame of the direct-switch entry gesture — for every subsequent attempt, since nothing about mpv’s geometry ever changes.

Diagnostic logging (commit fb30f890)

Added a failure-only sway_log(SWAY_INFO, ...) naming the reason at every silent return false in sync_scene_impl, sync_card, sync_node, chrome_impl/rebuild_chrome. Built and test-activated as i6mz5kzrg9rrkln7040gbgnddq2l8afz-nixos-system-nixos-26.11.20260919.20b1ddd, reproduced the bug with a real mpv session and injected touch, and got the exact new log line for the first time:

K230_CARD_SHELL sync_scene fail reason=entry-geometry-rejected id=6
K230_CARD_SHELL restored focus=6 message=10

(id 6 was the video card in that session; matches the incident’s id 12 exactly in shape.)

Fix and safety net (commit 4ad12358)

• card_source_size() (new, in adapter.c) feeds an ordinary-maximized card’s real committed container box (container->current.content_width/content_height — always exactly the output’s usable area for this card class) as the source rect, instead of view->geometry.width/height. A compliant client’s geometry already tracks its resize exactly, so this changes nothing for every other card; it only stops trusting a client (mpv) that never acks the resize. Used at both call sites: sync_scene_impl’s CS_ENTERING fast path and sync_card’s cs_entry_set_geometry/cs_entry_visual_rect calls. The small deck thumbnail’s own aspect-fit sizing keeps using the view’s real geometry (480x270) unchanged, since that one wants the decoded video’s actual aspect ratio, not the full-panel box.
• Safety net: a mirror-sync failure inside sync_card (a wlshm buffer the compositor can’t sample, an allocation failure under memory pressure) no longer fails the whole scene sync. The affected card falls back to its plain plate + icon + title (the same placeholder already used for CS_PRIVATE/CS_UNAVAILABLE cards), with no live mirror that frame, and the overview still opens — so a mirroring failure alone can never trap the user behind a full-screen card again, even for a cause other than the one reproduced here.
• tests/card_shell_policy_driver.c: added entry_geometry_rejects_undersized_source, pinning the exact mechanism at the policy layer — the identical edge/finger state that opens the overview with the real full-panel source rect is rejected outright with a small one. Registered in tests/test_card_shell_state.py. Host run, cc -std=c11 -Wall -Wextra -Werror -pedantic -g -fsanitize=address,undefined: all 35 cases pass (python3 tests/test_card_shell_state.py -v).

Board verification

System test-activated: c57f8gflr1hw25hddp67rd960j5kyw5c-nixos-system-nixos-26.11.20260919.20b1ddd (fix/video-card-gestures at 4ad12358, base feat/more-apps at 1e17d6c5), replacing i6mz5kzrg9rrkln7040gbgnddq2l8afz-... (the logging-only build used for the repro above), which replaced the board’s prior system har97636isrripp3iyi0gf9ar04mg2v9-....

Video started the way the drawer does (k230-video.desktop’s Exec=k230-video-session run), as the shell user with XDG_RUNTIME_DIR=/run/shell WAYLAND_DISPLAY=wayland-1. Injected touch via an evemu-device clone of /dev/input/event0 (real GT9895 description), driven with tools/inject-tap.sh (open, panel pixels on the 568x1232 portrait panel) and a small custom close-throw.sh (fewer/larger steps than the generic drag helper, so per-step speed reliably clears the deck’s throw_speed=0.4px/ms close threshold).

1. Open — bottom-edge swipe-up, (284,1228)->(284,760): K230_CARD_SHELL_DEBUG_SCENE ... mode=1 ... selected_app_id=k230-video-software (mode=1 is CS_DECK). No entry-geometry-rejected, no message=10 anywhere in the log for the rest of the session. Camera: contact-sheet.png panel 1 (video full-screen, the state the user was stuck in) -> panel 2 (overview open, the video’s real thumbnail small and centered).
2. Switch — swaymsg card_shell previous moved the deck’s selection off the video card to the other live card (selected_app_id=k230-terminal in debug-scene); a plain tap (284,550) on the now-centered card (injected touch) expanded it to full screen: K230_CARD_SHELL restored focus=5 message=0. The video kept playing in the background, unaffected.
3. Swipe-up close — back in the deck (swaymsg card_shell next reselected the video card), a fast injected vertical throw on the video card’s own rect, (284,900)->(284,400) over ~120ms (close-throw.sh /dev/input/event1 284 900 400):

   K230_CARD_SHELL close-request id=7
   K230_CARD_SHELL state mode=1 actions=33 message=9 cards=1
   K230_CARD_SHELL unmap id=7
   

   (message=9 is CS_MESSAGE_SOURCE_GONE.) No video-stop-helper unavailable log line, so card_shell_video_stop() (the SWAY_K230_CARD_VIDEO_STOP helper, i.e. k230-video-session stop) was actually invoked and succeeded, alongside the ordinary xdg_toplevel close.
4. Confirmed stopped: pgrep -x mpv empty immediately after, and the k230-inject-video unit wrapping k230-video-session run had exited (systemctl is-active -> inactive) — the session controller’s own process ended, not merely the mpv child. Camera: contact-sheet.png panel 3 (deck now shows only the remaining terminal card; the video thumbnail is gone).
5. Left the deck (swaymsg card_shell back): active=0 mode=0, back to the normal Home/ordinary-app state, no video playing.

Rollback timer (k230-deploy-restore.timer) disarmed after activation; readlink -f /run/current-system confirms c57f8gfl... is what the board is actually running.

Not established

A real-finger check by the user on the glass. Everything above is injected touch (open, close) or the compositor’s own deterministic step/debug IPC (switch); no physical finger touched the panel for this change.

Follow-up: the overview became unusable after opening (“no touches

register”), on integrate/apps-video-catalog

Reported after the fix above landed on an integration build carrying the apps/live-catalog/shade changes rebased with it: “once i open the cards list i can’t do anything no touches register”. Reproduced with injected touch (/run/k230-vo.sh: launch video, bottom-edge swipe-up, tap, flick, tap) against system p40rq5r8w8pfibl7nyhkr6vq4qs0w3n7-nixos-system-nixos-26.11.20260919.20b1ddd (the first fix’s commits rebased onto integrate/apps-video-catalog, no further change yet). Extended the state mode=... debug log with entry_settling/entry_reversing/entry_interrupted_hold/entry_progress/ blocked_until_up/blocked_contacts to see the mechanism directly instead of guessing from mode numbers alone.

Root cause 1 (card-shell-policy.c, commit f53f451c): a touch landing during the post-release entry settle triggers cs_down’s existing “catch and reverse” path, which sets entry_interrupted_hold and freezes cs_tick’s own elapsed-time computation until that same contact’s up clears the hold via cs_up — but adapter.c routes every up through cs_entry_up_at while mode == CS_ENTERING (covers both settling and reversing), which only ever resolves the original bottom-edge contact and bails for any other id. The interrupting contact’s own release can therefore never reach cs_up, so the hold has no way to clear on its own; a chain of closely-spaced touches (tap, then flick, then another tap, each landing before the previous one’s hold could clear) held the transition frozen far longer than its own ~240ms clock. Fix: entry_interrupt_started_ms bounds the freeze to one settle duration regardless of whether that contact’s up ever arrives, then proceeds on the untouched entry_started_ms timeline. New policy test entry_settle_completes_despite_stuck_interrupt models the worst case directly (an interrupting touch that never gets an up at all).

Root cause 2 (adapter.c, commit 2c838d0b, then 1ff6a837): board-reproduced separately — launching video and swiping up almost immediately let the video’s xdg_shell map (card_shell_observe) land while the deck was already CS_ENTERING. The brand-new card had never captured a scene position, so sync_card’s entering branch hard-failed it (reason=entry-source-invalid), which failed the whole sync_scene, which cs_leave-with-CS_MESSAGE_FAILED’d the entire transition back to CS_NORMAL with a stray blocked_until_up left behind — matching the report exactly:

K230_CARD_SHELL sync_card fail id=6 reason=entry-source-invalid
K230_CARD_SHELL sync_scene fail reason=card-sync-failed id=6
K230_CARD_SHELL restored focus=5 message=10

Fix: only the entry_id card (the one actually being dragged away from its live position) needs a real captured position; any other card appearing mid-transition is now skipped for the rest of the entry animation (reason=entry-source-not-ready) instead of aborting the whole transition. A follow-up board run then surfaced a second-order bug this introduced: sync_card’s own position capture was gated on !c->hidden, and a deferred card is marked hidden on the very same frame, so it could never become source_valid — a later tap-to-expand on that exact card failed the identical way forever (reason=expand-source-invalid). 1ff6a837 lets a card keep retrying its position whenever !c->hidden || !c->source_valid, preserving the existing freeze-once-valid-and-hidden behavior other cards rely on for their entry/expand return-to-source animation.

Performance finding, not fully resolved (adapter.c, commit ef63a564): with both correctness bugs fixed, the entry animation still took ~4.2-4.4s wall-clock end to end (bottom-edge swipe release to CS_DECK) against the coordinator’s ~400ms target, with state mode=4 steps landing roughly every 150-250ms instead of ~20ms. handle_result was running a full, synchronous sync_scene()+chrome() pass for every raw touch motion sample (tens a second during the drag), duplicating what the existing 16ms tick_impl timer already guarantees moments later. Coalescing that redundant per-sample sync to at most once per ~12ms during an active gesture is a safe, real improvement (touch dispatch itself is unaffected, since it is computed from policy state alone) but did not measurably shorten the ~4.2s total, because tick_impl’s own unconditional per-16ms sync_scene() call (via card_shell_prepare) is equally expensive and is not gated by this throttle — the dominant cost is each sync_scene() pass itself taking ~150-200ms wall time while mpv decodes and Pixman recomposites the whole 568x1232 output in software, not how many times it is invoked per touch sample. The coordinator was explicit that the small preview must stay live (no freezing, no pausing mpv), so the only path left to meet the timing target is to make each recomposition of the video card’s mirror cheaper while still updating every commit — e.g. extending the existing SWAY_K230_CARD_SCALED_CACHE machinery’s cheap pre-scaled-buffer path to video cards unconditionally, with its “frozen thumbnail” behavior removed, rather than reducing how often the mirror is refreshed. That is follow-up work, not done here.

Board verification (system

28qilnk3zqlivjgij78ahqnjvnjz8j5y-nixos-system-nixos-26.11.20260919.20b1ddd, integrate/apps-video-catalog at 1ff6a837)

With all three correctness/coalescing commits applied, a full injected /run/k230-vo.sh run (swipe-up, tap, flick, tap) and a follow-up swaymsg card_shell enter/next/close cycle produced zero reason=... failure or defer lines and zero message=10/restored focus with CS_MESSAGE_FAILED anywhere in the journal across multiple repeated runs. Concretely:

• Bottom-edge swipe-up: state mode=1 (CS_DECK) reached, video’s own mirror created (mirror id=6 ... width=568 height=320), no failure.
• A tap on the deck’s centered card correctly expanded it (restored focus=5 message=0, message=0 is success, not CS_MESSAGE_FAILED).
• swaymsg card_shell enter / next / close against the video card: close-request id=6 -> source-gone id=6 -> unmap id=6, and pgrep -x mpv empty immediately after — the video actually stops.
• The overview never got stuck; every gesture eventually completed and the shell returned to a normal, interactive state.

Not met: the ~400ms/~20ms-step timing target, for the performance reason above — entry still takes several real seconds end to end while mpv is actively decoding. Contact sheet contact-sheet-overview-freeze.png (webcam, injected/IPC-driven, not a real finger): video full-screen live -> overview open with the video’s real live thumbnail -> overview after close (video card gone, mpv exited). Rollback timer disarmed after activation; readlink -f /run/current-system confirms 28qilnk3... is what the board is actually running, with no video playing and no failed units.

Still not established: a real-finger check, and the deeper performance fix (cheap live pre-scaled video mirror, decoupled from SWAY_K230_CARD_SCALED_CACHE’s frozen-thumbnail behavior) needed to meet the entry-timing target while keeping the preview live.