[teamleaderleo]

Fixes #27075

Leo asked: “can you have it sync up with the desktop wallpapers? And, you know, like if you have different displays, that might have different kinds of situations that you can run into.” He also asked for wallpapers that “swap” “on whatever cadence.”

This adds opt-in per-display background and cadence overrides while preserving the global defaults from #22577. A stable NSScreenNumber binds a window to its display; screen changes rebind immediately, workspace and pane pins keep precedence, and stop() cancels the cadence timer and removes the observer. The display map accepts daily, folder:<absolute path>, fixed selections, and explicit none.

Coverage first reproduces independent display folder/hourly cadence, moves between screens, global fallback, workspace opt-outs, and observer cleanup in DisplayBackdropBindingTests. The binding is wired into each WindowController and follows settings snapshots.

Fleet focused check: cmux-ci run --class light --script scripts/ci/package-test-lane.sh --ref d40d897f009d4bc480982b17f02fe2b68de0cb59 --key wallpaper-rotation-d40d897f --arg=suite --arg=Packages/macOS/CmuxNext --arg=CmuxNextSettingsTests.DisplayBackdropBindingTests --env CMUX_CI_XCODE_APP=/Applications/Xcode_26.6.app --timeout 3000 (step pending).

Reference inspected: cmux-design-references/apps/t3-code/live/settings-appearance-themes.png and its NOTES; this behavior adds no motion or visual redesign. The supported capture-host two-display primitive is ready for the fleet capture owner; no synthetic/private image is included.

Exact-head fleet capture at 45379eb17c4483ffbf94641a0b5a23c157c388f3: six two-display states passed (global painting, UUID-keyed folder override, 0→1→0 restoration, explicit none, and global daily/hourly cadence inheritance). Build bf802bf611ed2adff6a4d83f, artifact sha256:a1252018c78d07071961bb0b6a81f0edb2ef62f1e7bc0be4c8d57c1ffb09c9f7.

Agent session: agent session

[github-actions]

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

Review 178a449: 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=pr27092 -f ref=wallpaper-rotation -f platform=macos -f backend_mode=local

red: cmux-next checks (god files, concurrency, crash safety, l10n); no finished base run on 4f5bcd1 to compare; do not merge until green; see lane-rules

Default changes

This pull request changes 3 defaults at 178a4493a9c7 (what everyone gets without configuring anything):

• setting.appearance.displayBackgroundRotations: (none) -> (none) (a new setting, off by default: passes on its own)
• setting.appearance.displayBackgrounds: (none) -> (none) (a new setting, off by default: passes on its own)
• tunable-source.CmuxNextSettings/Schema/SettingsSchema+Appearance.swift:descriptors: "ed23bc071d2ce9f7c7bc845e7f16084873ec9698643244f60d8b9334813217a4" -> "9969f2ccf81980538030608447f6d45d525ac95435298dc973b15d9bdb2865e7"

Signed off on this commit by review (codex, router-review).

Merge receipt: merged as e77c232e0b0c with these defaults changed, signed off by review (codex, router-review).

Regenerate the snapshot with python3 scripts/ci/defaults_guard.py snapshot.

Shipped in:

• cmux NEXT nightly 1.0.0-nightly.4143038272801 (912566a91a)
• cmux NEXT nightly 1.0.0-nightly.4143282790301 (50298238a3)
• cmux NEXT nightly 1.0.0-nightly.4143649268801 (d887a9ec1b)

[teamleaderleo]

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

[teamleaderleo]

Owned by an agent session · session

[teamleaderleo]

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

• Packages/macOS/CmuxNext/Sources/CmuxNextSettings/DisplayBackdropBinding.swift:41: Explicit "none" is converted to nil and passed to ThemeScope.setBackdropSelection(nil), which means “inherit the parent,” not “pin no backdrop.” A display configured with none therefore still shows the global wallpaper; the added test at line 71 fails.

[cmux-bot]

cmux-bot approves 1a78fb8: an independent review passed this exact head (next-review receipt by teamleaderleo). A push needs a new review; a later BLOCK at this head dismisses this approval.

[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, router-review): SHIP at 1d1b97c

Follow-ups: 1. Each lands as an issue in this repo that links this receipt; the lane that opened the PR fixes it forward.

SHIP at 1d1b97c

Visual verdict: no images; Leo tries the build

1. [P1][follow-up] Packages/macOS/CmuxNext/Sources/CmuxNextSettings/DisplayBackdropBinding.swift:162 maps a per-display "desktop" value to the process-wide .desktop selection. That selection resolves through NSScreen.main (BackdropSelection.swift:179) and is cached under one global key, so a secondary display with its own macOS wallpaper still shows the primary display’s wallpaper.

Follow-ups:

• [P1][follow-up] Make desktop wallpaper resolution/cache screen-specific for per-display "desktop" entries.

[teamleaderleo]

Review (independent Codex gpt-6.1-sol, high, via the review router; full diff from merge base ea29e41 to this head): SHIP at 0fd6b9f.

No P1/P2 findings.

[teamleaderleo]

For awareness: this PR has a SHIP review at its head, but GitHub reports it as conflicting with feat-cmux-next (plans/cmux-next/arch-ratchet.json and web/data/next-docs/settings-reference.generated.json conflict in a test merge), so it can't land as is. Its claimed owner session looks alive but couldn't be messaged directly. Please merge feat-cmux-next in and resolve the conflicts. If this PR has been abandoned, the conflict sweep will adopt it. (No push was made.)

[teamleaderleo]

Review (codex gpt-6.1-sol xhigh, next-review): SHIP at 5fb0364

SHIP at 5fb0364
Visual verdict: no images; Leo tries the build

1. [P2] [follow-up] DisplayBackdropBinding.swift:162: desktop still resolves through the shared main-screen wallpaper cache. With different desktop wallpapers and both displays configured as desktop, both windows show the main screen’s picture. Resolve and cache desktop wallpapers per display.

2. [P2] [follow-up] DisplayBackdropBinding.swift:146: A cadence override alone is ignored. For global background: "daily" and displayBackgroundRotations[display]: "hourly", this guard returns before reading the override. Apply the display cadence to the inherited global background.

3. [P2] [follow-up] SettingsSchema+Appearance.swift:116: Both new palette rows open empty value pages: .stringMap supplies neither options nor custom input. Add an editing path so these settings work from the palette.

Native tests could not run because Swift/Xcode are unavailable.

Follow-ups:

• Fix per-display desktop resolution and caching (1).
• Honor cadence-only overrides (2).
• Provide palette editing for both maps (3).
• [P2] [follow-up] Add exact-head two-display captures for WindowController.swift:118.

[cmux-bot]

cmux-bot approves 5fb0364: an independent review passed this exact head (next-review receipt by teamleaderleo). A push needs a new review; a later BLOCK at this head dismisses this approval.

[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 (next-review patch-id; carried): SHIP at 22aac0c

The independent SHIP at 5fb0364 carries to this head: the PR's own change (git diff $(git merge-base feat-cmux-next HEAD) HEAD) has the same git patch-id --verbatim (91a4cc26870bdc72) at both heads, and no merge between them was resolved by hand. Nothing new to review. A newer BLOCK, or any change to the PR's own diff, ends the carry.

[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, router-review): SHIP at 178a449

Reviewer: codex gpt-6.1-sol xhigh, fast tier.

Follow-ups: 3. Each lands as an issue in this repo that links this receipt; the lane that opened the PR fixes it forward.

SHIP at 178a449
Visual verdict: no images; Leo tries the build

1. [P2] [follow-up] DisplayBackdropBinding.swift:162: Display-specific desktop entries resolve to the shared .desktop selection. Its cache reads NSScreen.main, so windows on displays with different desktop wallpapers show the same picture. Resolve and cache the wallpaper by the bound display.

2. [P2] [follow-up] DisplayBackdropBinding.swift:146: A cadence override silently does nothing without a matching displayBackgrounds entry. With global background: daily and a display rotation of hourly, this guard returns before reading the override. Apply the display cadence to the inherited global shuffle.

3. [P2] [follow-up] SettingsSchema+Appearance.swift:113: Supply exact-head images covering the new settings rows and two-display behavior; none were available for visual review.

Follow-ups:

• Resolve desktop wallpapers per display.
• Honor cadence overrides with an inherited global shuffle.
• Capture the new settings and two-display states.

[cmux-bot]

cmux-bot approves 178a449: an independent review passed this exact head (router-review receipt by teamleaderleo). A push needs a new review; a later BLOCK at this head dismisses this approval.

[lawrencecchen]

Swift-logic note (REWRITE R-SWIFT-MIRRORS): this PR added DisplayBackdropBinding to CmuxNextSettings (+153 counted lines). It reads a copy of the settings document and decides the per-display background, rotation and daily turn. Those rules belong with the effective settings in cmux-config (rust-migration D2, wave W7, target 11-20); the theme scope pin stays Swift.

Why this matters: the tip's swift_logic_lines report (scripts/cmux-next/swift-logic-lines.py) has been red since 2026-11-02, and this PR is one of the rises. The project rule is that Rust owns state, lists and rules, and Swift is the platform shell (plans/cmux-next/layer-ownership.md; the cmux-next-feature skill: "Move as much as possible into Rust"). For new code of this kind, please put the rule in Rust (a crate the app links through cmux-app-ffi, or the daemon) and keep only the platform call in Swift. If a part truly must stay in Swift, add its row to plans/cmux-next/swift-logic-classes.tsv in the same PR, with the reason.

Nothing to change in this merged PR. REWRITE R-SWIFT-MIRRORS tracks the move (design: https://cmux-orchestrator-1.tail137216.ts.net/resize-videos/rewrites/R-SWIFT-MIRRORS/DESIGN.md, section 11).

[lawrencecchen]

Swift logic follow-up (tip watcher swift-logic row, STATUS 13027 "SWIFT LOGIC CULPRITS"; lead order).

This PR raised swift_logic_lines by +168 at its merge commit e77c232: scripts/cmux-next/swift-logic-lines.py before and after the merge, with the same table (the tip's, c6be943). The largest declarations of the rise:

• class DisplayBackdropBinding in Packages/macOS/CmuxNext/Sources/CmuxNextSettings/DisplayBackdropBinding.swift: +153 lines counted as Swift logic (no row in plans/cmux-next/swift-logic-classes.tsv)
• enum AppearanceSettingsSchema in Packages/macOS/CmuxNext/Sources/CmuxNextSettings/Schema/SettingsSchema+Appearance.swift: +14 lines counted as Swift logic (its row counts it as logic)
• extension SettingsSchema in Packages/macOS/CmuxNext/Sources/CmuxNextSettings/Schema/SettingsSchema+AgentPolicy.swift: +1 lines counted as Swift logic (its row counts it as logic)

plans/cmux-next/layer-ownership.md says Rust owns every state, list and rule and Swift is the platform shell. Please move the new logic of this PR in a follow-up: to Rust (the crate that owns the area; the owner lists in STATUS 12147-12165 name the target per area), or at least out of the app into its package. If a declaration above is platform code (AppKit, Core Animation, OS calls, strings, tokens, DEBUG tooling), reply here and the table gets a PLATFORM row with your reason instead.

The swift-logic row is a report, not a gate: nothing blocks on this comment.