[teamleaderleo]

Phase 3 of the backgrounds plan (briefs/next-backgrounds-plan.md): an easier way to add your own background.

What changes

Settings > Background:

• Add from a Link tile: paste an https link to an image or video.
  • It downloads into the backgrounds folder and becomes the background, the same way a picked file does.
  • A refused link says why:
    • not https
    • not an image or a video this Mac can play
    • too big: 50 MB for an image, 500 MB for a video
    • could not be downloaded
• Your images gets:
  • what the images take on disk
  • Show in Finder
  • a remove (×) button on each image, shown on hover or focus. It's disabled on the background in use, so the window never goes blank.
• Drop is no longer gated. Dropping an image or movie on Settings used to work only with experimentalAppearance on, even though the picker already said "Or drop an image anywhere on this page."

Checks before a file is copied in. This covers picked, dropped and linked files, through BackdropUserImages.adoptChecked:

• a picture must decode (ImageIO)
• a movie must be playable and have a video track (AVFoundation)

Before this, a broken file was copied in, listed, and then showed nothing.

Links:

• BackdropUserImages.download takes https only.
• A download delegate stops it once it passes the cap. The size is checked again on disk.
• The file is named for its bytes: ImageIO's type for a picture, the server's movie MIME type, or the link's movie extension. Anything else is refused.

Where the code lives.

• BackdropImagesPageProvider (CmuxNextPages) serves the new ops on the longest prefix, cmux.settings.backdrop.image.: link, remove, reveal and usage.
• For a link, it downloads to a temp file and then calls the App's existing useBackdropImage, so the check and the settings write are shared with the picker.
• SettingsBackdropImages moved to CmuxNextPages with it.
• CmuxNextApp source lines go down by 3.

Strings

10 new settingsWindow.backdropPicker.* keys, all 21 locales, in CmuxNextSettingsWindow/Localizable.xcstrings. generated/strings.json is regenerated with gen-strings.mjs.

Tests

• CmuxNextDesignTests/BackdropImportTests:
  • a broken .png is refused and never listed
  • adopt, usage and remove
  • only the folder's own images can be removed
  • http, file and ftp links are refused
  • a stubbed URLSession checks that PNG bytes behind an extensionless link are named .png, HTML behind .png is refused, and a 404 fails
• CmuxNextPagesTests/BackdropImagesPageProviderTests: the ops, refusal codes, own-images-only remove and reveal, and folder reveal.
• webviews/.../hostCards.test.tsx: the link form's refusals, adding sets and lists the image, the in-use image can't be removed and another can, and Show in Finder.

Verification

• bun test src/pages/settings: 128 pass.
• vp lint and vp fmt on the changed files: clean.
• tsc: no errors in settings. The only 2 errors are files outside my sparse checkout.
• lint-ios-package-conventions.sh: clean.
• check-text-focus-rings.py: only the known base red (DaemonRecoveryControls.swift:98).
• Swift: not built locally (no Mac in this lane), so CI is the first compile.
• Not dogfooded.

Not in this PR

• Hover-to-play video thumbnails in the picker. They need a video resource route in the App's SettingsBackdropThumbnails, and the App can't grow, so that waits for a slot.
• The 4K / over-60 fps "uses more power" note. It needs async video probing in the catalog listing.
• Built-in videos in art/manifest.json belong to phase 5, since they change the schema's accepted samples.

WINDOW

None. No settings schema, catalog or Package.swift change. The ops are page ops, not settings keys.

Changelog

Added: Add a background from a web link, and remove your own background images or show them in Finder.

🤖 Generated with Claude Code

---

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

---

Summary by cubic

Adds Settings > Background the ability to add your own background from an https link, and management for your own images: remove (not the one in use), size on disk, and Show in Finder. Picked, dropped, and linked files are checked to decode or play before they are copied in, and dropping no longer requires the experimental appearance flag.

• Link downloads stream under a cap (50 MB images, 500 MB videos) checked against both the declared length and the running count, stay https-only (redirects off https are refused), and are refused with a reason when not playable or too large. A body that starts like a picture gets the picture cap regardless of the declared type.
• Link names are sanitized (folders, colons, and leading dots stripped; the extension drops at the last dot) and kept in the download's folder; idle and total timeouts are covered, and the temporary folder is removed on every failure.
• The new ops (link, remove, reveal, usage) are served by a new BackdropImagesPageProvider in CmuxNextPages, shrinking CmuxNextApp and importing every type it uses so the fleet compile passes. Removing the background in use is refused natively, and both folder size and Finder reveal run off the main thread.
• Adds 10 new localized strings, a settings gallery entry for the link form, and tests covering import checks, page ops, and the link form.

^{Written for commit 7d675dd. Summary will update on new commits.}

[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.

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

• Configuration used: Repository: manaflow-ai/cmux/.coderabbit.yaml
• Review profile: ASSERTIVE
• Plan: Advanced
• Run ID: 1bbbb574-f551-43c7-bbb8-fa8872420614

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

Receipt for 7d675dd (this PR's head; a new push replaces it)

• Visual review: HQ feed card · gallery before/after runs
• Checks: this head
• 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=pr21731 -f ref=leo/next-own-backgrounds -f platform=macos -f backend_mode=local

[github-actions]

all web/size checks green

[teamleaderleo]

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

[github-actions]

Not verified: macOS jobs did not run: compile and app tests were skipped on 7d675dddf9; ci-status is green without them.

CI passes on 7d675dddf9 (run 39190235382 attempt 1).
macOS jobs did not run: compile and app tests were skipped: Fast static checks skipped (the macos job needs both to succeed). Re-run CI once they pass, before merging.

Written by scripts/ci/classify_failures.py (ci-failure-attribution.yml); signatures are its SIGNATURES table. A machine verdict is the runner's fault, not this PR's; yours means the failing file is one this PR changes, also red on main that main's latest full suite fails the same way, seen on other PRs that it failed on another pull request's run lately.

[github-actions]

CI fast guards passes on 7d675dddf9 (https://github.com/manaflow-ai/cmux/actions/runs/39190235382). This covers only the fast guards, not CI: CI's result is the ci-status check, and the CI failure attribution comment names any failing test.

[blacksmith-sh]

Found 2 test failures on Blacksmith runners:

Failures

Test	View Logs
/tmp/tmpbhsz0g21/summary-missing.json (live):/summary-missing.json (live):	View Logs
/tmp/tmpggv757ku/summary-fail.json (live):/summary-fail.json (live):	View Logs

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

[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.