Architecture

IdleScreen ships one companion app with an embedded screen-saver extension, camera agent, renderer framework and local command tool. The active Xcode project is generated from project.yml. This page follows docs/ARCHITECTURE.md.

Repository layoutCopy Anchor Link

• Products/ has the app, screen saver, helper and command-line entry points that ship inside IdleScreen.app.
• Sources/ has the shared production frameworks and modules.
• Tests/ has the unit-test targets and test-only support executables.
• Support/ has the performance and synthetic-gate executables that don't ship in the app.

Product boundaryCopy Anchor Link

IdleScreen.app
├── Contents/MacOS/IdleScreen
├── Contents/Frameworks/IdleScreenRenderer.framework
├── Contents/PlugIns/IdleScreenScreenSaver.appex
├── Contents/Helpers/IdleScreenCameraAgent.app
├── Contents/Helpers/idlescreenctl
└── Contents/Library/LaunchAgents/

• IdleScreenApp owns Studio, onboarding, diagnostics and user actions.
• IdleScreenScreenSaver hosts the shared renderer in ScreenSaverEngine.
• IdleScreenCameraAgent is the only process allowed to open AVFoundation.
• IdleScreenRenderer owns Metal resources and all glyph presentation.
• IdleScreenDisplay publishes display topology and deterministic scene plans.
• IdleScreenCore owns versioned configuration and cross-process data models.
• IdleScreenSystem owns app-only registration and System Settings integration.
• IdleScreenAgent and idlescreenctl implement the optional local agent signals.

The IdleScreenSyntheticGate targets are test apparatus and are never embedded in the distributed app.

Camera lifecycleCopy Anchor Link

The camera agent is a signed per-user LaunchAgent registered with SMAppService. Clients authenticate the XPC peer, acquire connection-bound leases and read generation-fenced frames from a fixed-size App Group mailbox. Raw frames don't queue through XPC.

Capture starts when the first valid consumer lease arrives and stops after the last lease expires or its XPC connection closes. Stream generations stop a frame produced before a restart or device change from being shown as current. The renderer falls back to a procedural source when a camera frame is unavailable or stale.

Display scenesCopy Anchor Link

One coordinator per process converts the current display topology into an immutable, generation-fenced plan:

• Panorama shares one scene and normalized viewport across displays.
• Per Display assigns an independent deterministic scene to each display.
• Focus Display gives one display the active scene and applies the configured quiet treatment elsewhere.

The companion preview and the screen saver consume the same planner output. Pixel Materials uses the same topology boundary so shared terrain and world edges stay stable across view recreation and display changes.

Procedural modes generate their glyph instances through a bounded Metal compute pass. The CPU implementation remains the deterministic reference and fallback, and parity tests cover every pattern, viewport, seed, brightness, contrast and glyph choice.

Local agent signalsCopy Anchor Link

Codex and Claude integrations are opt-in. Their hook adapters accept bounded JSON, reduce it to a provider-neutral AgentSignal and pass it to the bundled idlescreenctl over standard input. The command writes an atomic, private App Group snapshot with a bounded TTL.

There is no network listener. Prompt text, transcripts, commands, tool payloads, assistant responses, credentials and raw hook payloads are outside the signal schema. See Agent signals for using it.

Built withCopy Anchor Link

Swift 6, SwiftUI and AppKit. Metal and Metal compute shaders. ScreenSaver, ServiceManagement, AVFoundation and XPC. XcodeGen 2.46.0.