[teamleaderleo]

Summary

A capture of a translucent window could not show its translucency: debug.window_snapshot composites only the app's own windows, and a capture slot shares its Mac's desktop with other slots, so glass and window opacity showed nothing behind them (a uniform dark backdrop).

debug.capture_backdrop (DEBUG and bench-hook builds only) shows a patterned window of the app itself just behind one of its windows, covering that window's screen:

• pattern: checker, stripes, image:/absolute/path (read off the main thread), or none (closes it).
• window / kind: as for debug.window_snapshot (default the key window, else the active main window).
• Returns pattern, window_number, backdrop_number.

The window it is behind keeps it (an associated object), and floating-overlay discovery skips every capture backdrop, so a snapshot of one window never takes another window's screen-sized backdrop as an overlay over it.

Lifecycle: replacing a backdrop, taking it away (none) or closing its window closes the panel (CaptureBackdropPanel.remove()), so no window-server window outlives it and a screen-sized backdrop never stays on screen after its window is gone.

New observer: each backdrop observes NSWindow.willCloseNotification for its one target window (MainActorObservation, object: target; at most one backdrop per window). It holds the panel weakly, so the window keeping the panel makes no cycle. Stop condition and cleanup: it is dropped in remove() (the backdrop is replaced, set to none, or its window closes) and its token is removed when the panel is released. The arch-ratchet observer_sites +1 carries that reason in plans/cmux-next/arch-ratchet.json.

compositedSnapshotWithOverlays() now composites a window's capture backdrop behind everything else (always last in the window list, whatever the on-screen order), so the window server blurs it under glass as on screen. With no backdrop the snapshot is unchanged. The backdrop is an app window, never the desktop picture, so it goes with the app; nothing outside the app changes.

The capture tooling side (a state's "backdrop": "checker" | "stripes" | "image:<repo path>") is in the private capture tooling repo.

Testing

• CmuxNextDesignTests.CaptureBackdropPatternTests: pattern names, checker and stripe cells, composite order (backdrop always last, never in front).
• CmuxNextDesignTests.CaptureBackdropSnapshotTests (display suite, listed in scripts/ci/display-suites.txt): a translucent window's snapshot is uniform without a backdrop and shows the stripes with one; setCaptureBackdrop(nil) takes it away; aSnapshotShowsOnlyItsOwnWindowsBackdrop: two windows, each with its own backdrop, and each snapshot shows only its own.
• replacingOrRemovingABackdropClosesTheOldPanel: replacing a backdrop closes the old panel (its willClose fires once), none closes the current one, and the window lets go of it.
• closingTheTargetWindowRemovesAndClosesItsBackdrop: closing the target window removes and closes its backdrop.
• WindowSnapshotOverlaysTests rerun for the snapshot change.

Observed / Not run

• Observed: scripts/cmux-next/prepush-gate.py clean; scripts/cmux-next/check-objc-selectors.py 0 failures. Fleet package-test-lane.sh suite on a gui-session-v1 mini at 0b98b4e: CaptureBackdropPatternTests, CaptureBackdropSnapshotTests and WindowSnapshotOverlaysTests all passed. Red: the same suite with the overlay skip removed failed aSnapshotShowsOnlyItsOwnWindowsBackdrop (B's snapshot took A's backdrop as an overlay: floating == 1, an orange stripe pixel). The head after that only replaces the panel's self-retain and close() override with the target window keeping it.
• Not run: a full pr-capture of a glass surface with the backdrop (follows once this and the tooling side land).

No capture: a DEBUG-only control method and a snapshot path that is unchanged unless a backdrop is set; nothing visible changes in the app. The display tests above check the composite pixels.

Changelog

none

risk:low (DEBUG-only control method; the snapshot path changes only when a backdrop is set)

🤖 Generated with Claude Code

Agent session: agent session

[github-actions]

cmux status _{(one comment, edited in place; each line is updated by the job that owns it)}

Review f31f3aa: HQ feed card · gallery before/after runs · checks

App of this head (app.zip, kept 1 day)

gh workflow run reload-build.yml -R manaflow-ai/cmux --ref feat-cmux-next -f tag=pr27514 -f ref=dep-fleet--debug-capture-backdrop -f platform=macos -f backend_mode=local

red: cmux-next checks (god files, concurrency, crash safety, l10n); NEW: red check: Package dependency lists sorted is not red on the base 4756282; do not merge until green; see lane-rules

[teamleaderleo]

Owned by an agent session · session

[teamleaderleo]

Bead cx-qqmj05 created for this PR by the cmux coordinator.

[blacksmith-sh]

Found 9 test failures on Blacksmith runners:

Failures

Test	View Logs
/tmp/tmp3isv7qur/summary-fail.json (live):/summary-fail.json (live):	View Logs
/tmp/tmp_o_pr96q/summary-missing.json (live):/summary-missing.json (live):	View Logs
[new_workspaces] debug.new_workspace timed 0 of 50 new workspace rows/ [new_workspaces] debug.new_workspace timed 0 of 50 new workspace rows	View Logs
[new_workspaces] the window draws no frames/[new_workspaces] the window draws no frames	View Logs
[tabs] debug.tab_switch timed 0 of 40 switches/ [tabs] debug.tab_switch timed 0 of 40 switches	View Logs
[tabs] the window draws no frames/[tabs] the window draws no frames	View Logs
convention violations found (ERROR lines above)./ convention violations found (ERROR lines above).	View Logs
test_every_listed_hook_is_one_glaeda_released_with_the_check (main.SigningHooksInSt epWithGlaedaTests.test_every_listed_hook_is_one_glaeda_released_with_the_check)/ test_every_listed_hook_is_one_glaeda_released_with_the_check (main.SigningHooksInSt epWithGlaedaTests.test_every_listed_hook_is_one_glaeda_released_with_the_check)	View Logs
test_the_repository_highlights_validate (main.DigestTests.test_the_repository_highl ights_validate)/ test_the_repository_highlights_validate (main.DigestTests.test_the_repository_highl ights_validate)	View Logs

^{Need help on this PR? Tag @codesmith-bot with what you need.}

[teamleaderleo]

Review (codex gpt-6-astra high, next-review): BLOCK at af2187e

• P2 — CaptureBackdropPattern.swift:115: Backdrops corrupt other windows’ snapshots. With window A above B, A’s screen-sized backdrop sits above B. Because it is an unattached NSPanel, existing floating-overlay discovery includes it in B’s capture, covering B with the opaque pattern despite B having no backdrop. Exclude all capture backdrops from floating-overlay discovery, then explicitly composite only the target’s backdrop. This also prevents a reordered backdrop from becoming full-frame overlay coverage that overwrites captured Chromium content.

[cursor]

Bugbot needs on-demand usage enabled

Bugbot uses usage-based billing for this team and requires on-demand usage to be enabled.

A team admin can enable on-demand usage in the Cursor dashboard.

[cursor]

Bugbot needs on-demand usage enabled

Bugbot uses usage-based billing for this team and requires on-demand usage to be enabled.

A team admin can enable on-demand usage in the Cursor dashboard.

[teamleaderleo]

Review (codex gpt-6-astra high, router-review): BLOCK at 71131c8

BLOCK

1. Packages/macOS/CmuxNext/Sources/CmuxNextDesign/Windows/CaptureBackdropPattern.swift:107-110 — Replacing or removing a backdrop only calls orderOut and releases the association; it never closes/removes the independent NSPanel (which also sets isReleasedWhenClosed = false). Repeated pattern updates therefore accumulate stale window-server windows, and closing the target window has no teardown hook, so its full-screen backdrop can remain visible after the target is gone. Cleanly close/remove the old panel during replacement and target-window teardown.

[teamleaderleo]

Review (codex-review-box/gpt-6-astra high, lane-place): BLOCK at 71131c8

BLOCK

1. [P2] CaptureBackdropPattern.swift:114: Retaining the backdrop on its target does not synchronize visibility. Set a backdrop on the palette, then dismiss it: PaletteController.hide() retains and orders out the palette, leaving the screen-sized backdrop visible indefinitely. Minimizing a main window has the same problem. Tie backdrop visibility to the target’s hide/minimize/close lifecycle; the target == nil cleanup cannot handle retained targets.

[teamleaderleo]

Review (codex gpt-6-astra high, router-review): SHIP at f31f3aa

SHIP

No correctness, regression, crash, race, security, or test-blocking defects found.

(router-review gave this verdict for this head; its own --post hit the shared API quota, so the receipt is posted by the PR owner after checking the head has not moved.)

[github-actions]

Shipped in:

• cmux NEXT nightly 1.0.0-nightly.4102181555501 (9e836df436)

[github-actions]

Shipped in:

• cmux NEXT nightly 1.0.0-nightly.4102114976401 (91e41bb410)