WorkbenchPREVIEW

PRODUCT HANDBOOK · WORKING SPECIFICATION

A desktop to enjoy.
A scene to present.

Choose a picture for your day, or prepare a scene for a call. Reuse what you like. Each experience should be complete on its own.

What exists today

The signed and notarized public Preview 4 includes scene preparation, still-desktop apply/restore and optional gentle motion with a separate app-owned desktop layer. A direct wallpaper picker and independent wallpaper settings remain proposed. The capability records below retain their specific evidence and hardware limits.

THE EXPERIENCE

Two starting points. An optional connection.

01 / EVERYDAY DESKTOP

Make the Mac feel yours.

Open Wallpaper directly, choose a picture and see its fit on the display you name. Apply it and return to work. No phone, branding or scene setup required.

  1. Choose. A useful still picture is the complete first experience.
  2. Settle in. Keep typing and switching windows normally. The wallpaper stays behind your work.
  3. Add motion, if wanted. Offer a quiet local loop with a still fallback, clear Pause and measured energy behavior.

Proposed journey · current still apply starts in the scene editor

02 / PRESENTATION

Prepare once. Show it simply.

Compose the backdrop, device and optional branding or persona in one direct visual editor. Start the saved scene with one action once the device is connected and ready.

  1. Prepare. See the composition while changing its parts; keep advanced layout controls nearby.
  2. Present. Pick a window or full screen. Use the small phone tile for session controls.
  3. End. Close the presentation and release its resources. Keep the saved scene and independent desktop choice.

Implemented baseline · audience and hardware checks remain explicit

The bridge is a picture. “Use this picture” can save repeated searching. It should create an independent choice for the other job, with its own crop and playback settings. No automatic wallpaper changes when starting a scene.

Concept study with independent desktop and presentation journeys, optional reuse, and a normal desktop after ending the scene.
Design exploration. The desktop picker and motion controls are proposals. The illustration explains the journeys; its editor layout is not an instruction to replace the working composition editor.
What changed between the image experiments?

The first image put scenery inside the phone and dropped the persona during presentation. We rejected both: the phone displays a real device app, and the composition retains its foreground. The refined study fixes those points and removes invented poetic document text. Its three-column preparation layout is still illustrative; the actual editor below is the implementation reference.

Open the first experiment · Open the refinement

CRAFT IS BEHAVIOR

A simple first action. Depth when it helps.

First use

Choose and apply a still picture. Or open a prepared scene and present. Explain missing access or a disconnected device exactly where it blocks the task.

Everyday use

Remember each job’s choices. Keep Cancel dependable, recovery visible and labels literal. Offer reuse when there is something useful to reuse.

Power use

Reveal crop, display targeting, shortcuts and motion controls in context. A familiar shortcut accelerates the same operation; it does not introduce another state owner.

Voice remains a direct starting point in Workbench. This visual-experience specification does not move recording controls into presentation or change how dictation is delivered. A person who came for one excellent feature should be able to stay there.

Actual native backdrop replacement sheet, showing the retained phone, logo and persona and explicit Cancel and Use backdrop controls.
Actual native editor. Captured with disposable synthetic scenes. This is the implemented backdrop workflow: a meaningful preview, local choices, labelled crop controls and explicit application. See missing-image repair.

WHAT STAYS. WHAT ENDS.

“End” should mean one clear thing.

A presentation window, the desktop underneath it and keyboard focus are separate concerns. Explore the contract below. These buttons change this explanation only; they do not control your Mac.

End presentation

Implemented

Stops or changes

The presentation window, its device capture, controls and keep-awake activity.

Keeps

Saved scenes, original assets, any independently applied desktop picture and a separately started desktop-motion session.

Do not restore wallpaper, close a meeting, move unrelated windows or change system Stage Manager settings. Check focus returns sensibly; do not promise an exact previous app is always restored.

Read every lifecycle rule without interacting
EventStops or changesKeeps and checks
End presentation
Implemented		The presentation window, its device capture, controls and keep-awake activity.Saved scenes, original assets, any independently applied desktop picture and a separately started desktop-motion session.

Do not restore wallpaper, close a meeting, move unrelated windows or change system Stage Manager settings. Check focus returns sensibly; do not promise an exact previous app is always restored.
Restore desktop
Implemented		The app-owned desktop-motion layer immediately, then use of Workbench’s still output on eligible matched displays after macOS confirms restoration.A later manual picture choice, unmatched recovery records and any active presentation.

Read the current desktop before restoring. A recorded old URL is not authority to overwrite a later user choice.
Change a picture in System Settings
Implemented		The desktop-motion layer at its next ownership check if the native picture no longer matches the applied output. macOS owns the new choice.A running presentation and saved compositions. Restoration subsequently skips pictures it no longer owns.

The renderer never reapplies a picture. A five-second timer with tolerance and wake checks verify ownership; unknown state stops the session. Restore still respects later manual choices.
Pause wallpaper motion
Implemented		The desktop layer’s animation and visibility; the underlying native still shows.The applied still, independent saved scene and any presentation. Resume checks that Workbench still owns the desktop picture.

Explicit Pause survives sleep/wake. Reduce Motion, Low Power Mode, high thermal state and occlusion separately suppress animation. No automatic login restart.
Quit Workbench
Implemented		App-owned recording, playback, presentation, drawing, timers and monitors.Saved work, retained desktop output files and recovery records. A still picture set through macOS remains set.

App-rendered desktop motion stops on Quit; the native still remains. Do not restart in the background or restore wallpaper silently.
Hide all overlays temporarily
Implemented		Visibility of all current session artwork. The small tile remains available.Prepared sets, frozen artwork and each copy's visibility choice. Changing sets while paused stays hidden.

Show again restores the selected set without reviving copies individually hidden earlier.
End overlays
Implemented		Every window and the control tile belonging to the overlay session.Saved groups, layouts, original images, unrelated apps and the desktop picture.

Live changes are temporary unless explicitly saved. Quit also ends the session; launch never restarts it.
End preview and open an Apple app
Implemented		This Workbench device presentation, its capture session, observers, controls and keep-awake activity before launching the requested app.Saved scenes, independently applied wallpaper and other apps. The selected Apple app owns its own device session and meeting sharing remains separate.

Both capture cleanup and native window closure must finish, in either order, before one app-launch attempt. A visible launch error never silently reacquires capture.

WHAT THE MAC PROVIDES

Use the OS well. Name the gaps honestly.

ConcernmacOS baselineWorkbench implication
Still wallpaperPictures, colors and image-positioning controls.The public desktop-image API is the starting point for stills. Confirm the selected display and read back the result.
Dynamic and aerialTime-of-day Dynamic Wallpapers and aerial lock/unlock/screen-saver behavior are distinct.A still-image setter does not prove continuous-video, native aerial or schedule support. Test each type separately.
Displays and SpacesWallpaper settings include “Show on all Spaces.” Displays and Spaces are different scopes.Current code targets the editor’s display or main display. A named display chooser and arbitrary Space control are not established.
Windows and attentionMission Control and Stage Manager organize windows. The frontmost app receives keyboard input.Wallpaper should stay behind work. A presentation can take focus deliberately; ending it must not rearrange unrelated windows or change system settings.
SharingThe capturing app selects a window or display and may filter other windows.Rendering the scene inside its own window is different from an overlay or desktop picture. Verify the recipient’s view in Teams and Zoom.
Primary sources and evidence limits

Apple documentation was reviewed on 13 September 2026. Earlier native inspection covered Apple Wallpaper and Plash settings. No wallpaper was changed in this documentation increment; dynamic playback, energy and receiver behavior have not been benchmarked.

THE IMPLEMENTATION CONTRACT

One record, with evidence attached.

The records below are generated from the same JSON contract available to contributors and agents. “Implemented” describes source and stated checks, not publication of the newest binary. “Proposed” means work still needs to be scoped and verified.

Change a scene backdropImplemented

Entry: Present a device → Change backdrop…

Preview a file, starter or saved scene image with the retained foreground; apply only the background and crop.

Boundary: Changes the saved scene and later outputs, not a running presentation or an already-applied desktop image.

Evidence: Six focused tests with 126 assertions; native picker Cancel, Escape, Return Apply and missing-image repair checked with disposable scenes.

scene-backdrop · Source owner

Present a prepared sceneImplemented

Entry: Present full screen / Present in window

Show a saved composition in a Mac window, optionally with device video. The compact controls use a phone icon when the device is enabled and a picture icon otherwise.

Boundary: A meeting app chooses what to share. An audience view, USB recovery and a second display need their own checks.

Evidence: At da4f0f4, saved name/backdrop/persona edits left a running windowed still unchanged; End/restart adopted them. At 7e45213, the unchanged isolated native host verified all eight expanded positions, a compact-tile drag to Left centre, keyboard reveal and Escape collapse/End through a full-screen transition. Device capture and cloud were off; this is not receiver-view or installed signed-shell verification.

scene-session · Source owner

Choose a phone connection and audio routeImplemented

Entry: Present a device → Connection & audio…; also available in live Source

Separate phone picture, voice conversation and Mac control; guide six native routes. Explicit End preview & open releases capture and closes the presentation before launching an installed Apple app.

Boundary: Workbench USB remains video only. The guide does not detect policy, forward a microphone, configure a meeting or establish a working duplex voice route.

Evidence: Six phone regressions passed with 45 assertions. Integrated StageKit passed 121 tests / 2,601 assertions. Actual native guide inspection covered all jobs/routes, scroll reset, Escape/Done and dismissal before a fake fallback launch. Physical device and receiver checks remain separate.

phone-routes · Source owner

Apply a scene as a desktop pictureImplemented

Entry: Present a device → More → Use as desktop (Preview build)

Render the whole scene to a retained PNG, record recovery information and request the desktop change through macOS.

Boundary: Includes foreground artwork; it is not a background-photo-only picker. Uses the editor window's display or the main display. No dedicated display chooser. Excluded from APP_STORE builds.

Evidence: Source verifies journal-before-write and URL readback; this documentation change did not alter the user's desktop.

desktop-still · Source owner

Restore a previous desktop pictureImplemented

Entry: Restore desktop when recovery information exists

Restore recorded image/options only where the current picture still matches a Workbench-owned output.

Boundary: Retains unmatched recovery records. It is not a complete snapshot of Apple's dynamic, aerial, rotation, screen-saver or arbitrary Space configuration.

Evidence: Recovery planning has deterministic tests; multi-display and multi-Space behavior requires native validation.

desktop-restore · Source owner

Choose a wallpaper without preparing a sceneProposed

Entry: A direct Wallpaper entry; final placement to be tested

Choose a picture, preview its fit on a named display and apply it. Keep a separate wallpaper preference and previous-picture recovery.

Boundary: No dedicated wallpaper manager exists yet. Do not introduce login launch, scheduling, a sidebar category or an asset migration merely to ship this first job.

Evidence: Next proof: a first-time user sets and restores a picture without opening a scene editor; another can use only Dictate without seeing wallpaper setup.

wallpaper-entry · Source owner

Reuse a picture between the two jobsProposed

Entry: An explicit Use this picture action in the relevant picker

Reference the same original through two independent saved configurations. A still frame may accompany future motion assets.

Boundary: No live synchronization of crop or playback. Existing scene-image reuse is implemented; cross-job wallpaper reuse is not.

Evidence: Proof: edit, remove and export each configuration independently; preserve originals referenced by the other job or recovery.

asset-reuse · Source owner

Gentle desktop motion, while Workbench is openImplemented

Entry: Present a device → More beside the presentation buttons → Use as animated desktop (non-App-Store build)

Apply and verify a rendered native still, then show an independent click-through desktop layer. Authored starters move clouds or foliage; ordinary photos use gentle zoom. Foreground artwork stays still. Pause/Resume/Stop controls appear in the scene window.

Boundary: App-owned, one display and the current Space only. Stops on Quit or Space change; checks native wallpaper ownership periodically. A direct photo-only wallpaper picker is still proposed. No video import, Lock Screen installation, automatic login restart or energy claim.

Evidence: Native isolated Mac host checked desktop-layer Start/Pause/Resume/Stop and presentation-End independence without changing the user’s wallpaper. Ownership, nested sleep and removal policies passed unit checks. Actual native still apply is separately implemented; physical multi-display/Spaces and energy remain unverified. The signed Mac Preview at source 9fe7959 was installed and opened with existing scenes present; the new toggle and desktop menu action were confirmed. It is not notarized or in the public download. The authored starter increment at 48c00dc is installed as signed local Preview build 20260914180524; exact archive/resource identity and new gallery verified. Not notarized or in the public download.

wallpaper-motion · Source owner

Gentle motion in a prepared sceneImplemented

Entry: Choose a starter → Window light, Campus breeze or Coastal sky. Gentle motion in scene settings; Pause/Play in presentation controls or the iOS editor preview.

For ordinary photos, an optional 3.5% zoom. Three authored starters instead move clouds or branches while the architecture and foreground remain still. Complete posters, clean plates and details travel in version 2 packages; the prior library manifest is preserved before upgrade.

Boundary: Mac editor and galleries remain still. iOS animates only the active visible scene preview. PNG/Photos exports stay still; no Live Photo export or continuous iOS Home Screen animation. Reduce Motion, disabled animated-image autoplay, low power and high thermal state suppress animation. Device video and meeting receivers need separate validation.

Evidence: 79 native Mac scene tests / 2251 assertions and 72 shared-module tests passed. Actual isolated Mac office captures changed only the window sky; fixed room/desk pixels were identical. Native compositor and UIKit poster parity checked for all three rigs. See /scenes/ambient/ for the current source and delivery evidence.

scene-motion · Source owner

Present several native overlaysImplemented

Entry: Personas and overlays → Prepare presentation → Demo groups → Start overlays

Show several independently placed cards, switch among explicitly prepared sets, and Hide/Show/End through one click-based native tile. Live images, labels and allowed choices are frozen; layout saving is explicit.

Boundary: Mac screen-positioned windows, not browser-tab attachments or captured-app composition. Up to 8 sets / 8 copies each / 32 prepared personas / 256 MB rendered imagery. Three editable single-persona shortcuts default on; the five multi-overlay session actions remain opt-in. No new cloud service or scene schema. Whole-display receiver checks remain separate.

Evidence: 88 integrated native Mac scene tests /2367 assertions and 114 StageKit CI-mode tests /2533 assertions passed (live menu-bar popover check excluded). Native keyboard focus and click menu, per-card hide, paused set switching, return and restoration checked with disposable artwork. Signed local Preview 20260914204356 installed; signature, preparation entry and disabled optional shortcuts verified. Source and delivery limits are in /personas/.

persona-session · Source owner

Remember the separate break timer positionImplemented

Entry: Break timer → drag or Position

Snap on drag release; persist a free normalized position or one of eight anchors and recover on an available display after hiding, closing or restarting.

Boundary: Countdown and presentation remain independent. Corrupt, future or concurrently changed placement files are preserved. Physical display removal, VoiceOver and meeting receivers remain acceptance checks.

Evidence: Focused synthetic persistence checks: 19 assertions. Native AppKit timer hide/reopen and release-time snapping: 11 assertions. See docs/verification/2026-09-20-contribution-integration.md for combined-candidate results.

break-timer-placement · Source owner

Keep the state owners small

Original imageReusable local media; retain while any saved output or recovery record needs it.
Wallpaper preference proposed separate recordPicture + fit + explicit display scope. Future playback belongs here.
Saved scene implementedBackdrop + device + logo/persona layout. No live capture in this record.
Desktop output and recovery implemented for scenesRendered still + previous image/options + ownership check. Survives Quit.
Presentation session implementedCapture + scene window + controls + keep-awake activity. Ends with the session.

Separate responsibility does not require another service or a plugin framework. Add a wallpaper preference only when the independent workflow needs it. Reuse pure image rendering and selection components where their contracts match.

Verification gates by capability
  • presentation-snapshot — At da4f0f4, start a windowed synthetic still in the native Mac host, change the saved name/backdrop and remove the placed persona, then revisit the running presentation. It stayed unchanged; End/restart adopted the saved changes. Device capture and cloud were off. Live video, incoming sync, fullscreen and receiving-participant behavior remain unverified. Status: passed windowed still.
    Applies to: scene-session, scene-backdrop.
  • presentation-controls — At 7e45213, select each of the eight named positions in an isolated native windowed still presentation; Position and End stayed reachable. Drag the compact tile from Bottom right to Left centre; release kept it collapsed with no guides remaining. Command Slash reopened it. A native full-screen transition retained controls; first Escape collapsed them, second Escape ended and returned to Scenes. Every drag target, guides during drag, multiple displays, VoiceOver, live capture and receiver views remain separate. Status: passed single display still.
    Applies to: scene-session.
  • independent-entry — Set a wallpaper from a fresh session without making a presentation. Complete first dictation without wallpaper setup. Status: not run.
    Applies to: wallpaper-entry.
  • independent-state — Use the same source in both jobs, crop each differently, end a scene and relaunch. Preserve each choice and referenced media. Status: not run.
    Applies to: asset-reuse.
  • ownership — Apply a still, manually change it in System Settings, then Restore. Preserve the manual choice and report any pending recovery accurately. Status: source and unit only.
    Applies to: wallpaper-entry, desktop-restore.
  • display-spaces — Two displays and two Spaces; Show on all Spaces on/off; disconnect and reconnect. Record affected surfaces rather than inferring them. Status: not run.
    Applies to: wallpaper-entry.
  • focus — Check typing destination, desktop clicks, Mission Control and Stage Manager during apply, start, end and future motion. Wallpaper must not take keyboard focus. Status: not run.
    Applies to: wallpaper-entry, wallpaper-motion, scene-session.
  • meeting-receiver — Observe a receiving participant in Teams and Zoom, desktop and browser versions, for window and whole-display sharing. Test separate overlays and control menus. Status: not run.
    Applies to: scene-session, wallpaper-motion.
  • motion-budget — Measure idle CPU/GPU/energy, battery, sleep/wake and Reduce Motion on named hardware before choosing defaults or advertising animation. Status: not run.
    Applies to: wallpaper-motion.
  • gentle-motion-local — Native Mac windowed motion, Pause, desktop-layer Pause/Resume/Stop and End independence checked using disposable scenes. iPhone Simulator created Coast, enabled motion, paused/resumed and opened still crop controls. The desktop host used the existing native wallpaper as its ownership token and did not replace it. Current source builds pass; full device-video, Lock Screen, multi-display and energy checks remain separate. Status: passed isolated native and simulator.
    Applies to: scene-motion, wallpaper-motion.
  • multiple-overlays — Start two independently placed copies; hide one, pause all, switch away and back, then resume. Preserve exact visibility and frozen audience labels/images. Failed start must retain the old view; conflicting Save must preserve preparation and show a safe notice. Test temporary edits, exact preupgrade backup and old/future files. Native capture and hardware shortcuts need their own receiving-device checks. Status: passed unit and focused native.
    Applies to: persona-session.
  • phone-source-and-handoff — Explicit first choice, exact-ID recovery, restricted versus denied permission guidance, both handoff callback orders, repeated end, native transition failure and capture callback retained beyond presenter release. Use synthetic devices and a stopped capture; no camera prompt. Status: passed source and unit.
    Applies to: scene-session, phone-routes.
  • phone-guide-native — Open guide before capture. Inspect all three jobs and route picker; scroll to rehearsal/workplace limits, change routes from the bottom, use Escape/Done and request an Apple fallback. Verify dismissal before the fake launch callback. Actual USB fallback release needs physical-device acceptance. Status: passed native isolated.
    Applies to: phone-routes.
  • phone-voice-duplex — On an approved Mac and phone, test actual agent microphone, reply monitoring, interruption, reconnect and receiver audibility in Teams and Zoom desktop and browser. Record route and app/OS versions. Ordinary media playback is insufficient. Status: not run.
    Applies to: phone-routes, scene-session.
  • single-persona-failure — A selected card in a group with unreadable other artwork returns a visible failure without ending existing output. Busy and oversized groups refuse before mutation. Native post-dismiss alert path is shared with prepared-session Start/Resume. Status: passed source and unit.
    Applies to: persona-session.
  • timer-position-recovery — Drag near an anchor and release; verify the visible frame matches the saved anchor before hide/reopen. Exercise free and named placement with changed synthetic display bounds and preserved corrupt/future/concurrent records. Physical displays and receiver view remain unverified. Status: passed native isolated.
    Applies to: break-timer-placement.

HUMANS, AGENTS AND DEVELOPERS

Different readers. The same source of truth.

Try a moment

Use the working guide. Tell us what you expected, what happened and which version you used. A screenshot of made-up content is enough to start; diagnosis is optional.

Prepare an observation →

Give an agent bounded work

Choose one capability ID from the contract, state the intended outcome and let the agent inspect current code. Require an actual result and evidence; a generated mockup is a hypothesis.

Read the agent brief →
Read the JSON contract →

NEXT BOUNDED APP INCREMENT

A direct still-wallpaper experience

Open Wallpaper, choose a local image, preview its fit on a named display, apply and return to work. Preserve a later manual desktop change during recovery. Prove this before adding motion or reorganizing the whole home screen.

Capability wallpaper-entry · proposed · no new daemon, account or automatic launch

What an agent should hand back
  1. Capability ID and observable before/after
  2. Changed files and state owners
  3. Tests actually run, including hardware/receiver limitations
  4. Actual screenshot and source revision
  5. Recovery behavior and remaining decisions

This is a readable product contract, not an automation API. Workbench does not currently expose wallpaper through a CLI, App Intent or MCP server. A contributor must inspect available interfaces and stay within the user’s authorization.

What the critical review accepted and rejected

Claude correctly challenged the absence of an independent wallpaper entry: sharing an editor should not force everyone through presentation setup. We retained its warning about burying voice and about duplicating specifications for different readers.

We rejected its advice that Quit should leave presentation running: app-owned capture and windows must end with the process. It also confused device video arriving at the Mac with output to a phone. Source review establishes the direction. Its “no reconciliation” suggestion does not replace the existing ownership check before restoring a desktop.

Image generation helped compare journeys and reveal misleading details. Source review, primary documentation and native evidence decide the contract. Agreement between models is not verification.