ImmichFrame

Native macOS 14+ desktop widgets for a self-hosted Immich server. This foundation contains a sample app and widget, shared core, and headless core tests. Connection setup and real photos are not implemented yet.

Build and test

Install full Xcode and select it with xcode-select. The project uses Swift 6 language mode and no third-party dependencies or project generator. Verified with Xcode 27.2 (27B52), Swift 6.4.2. Deployment target: macOS 14.0.

From a fresh checkout, run:

./Scripts/check.sh

This runs the core tests without launching the app UI, builds an unsigned universal Release app and embedded extension, and checks both executable architectures. It works on a macOS CI worker with full Xcode; no signing secrets or remote repository are required. Outputs are in .build/DerivedData. Unsigned builds verify compilation and packaging only.

Open ImmichFrame.xcodeproj in Xcode. Shared schemes are ImmichFrame (app, embedded widget and tests) and ImmichFrameCore (headless tests).

Signed installation and gallery check

1. Copy Config/Local.xcconfig.example to Config/Local.xcconfig (ignored by Git).
2. Set your development team, unique bundle identifier prefix, App Group and Keychain access group. Register/provision the identifiers and capabilities for both the app and its .Widgets extension under the same Apple Developer team. The app bundle identifier defaults to com.maroskucera.ImmichFrame; use your own unique prefix if building a separate copy.
3. In Xcode, select ImmichFrame, My Mac, and build with automatic signing. Both targets use the same configuration; do not independently change their sharing identifiers.
4. Copy the built ImmichFrame.app to /Applications or ~/Applications, launch it once, then quit it. Right-click the desktop → Edit Widgets → find ImmichFrame and add a small, medium or large sample widget.

The sample is an original, generated landscape with no private photo content. The widget is static and makes no network requests. It needs no resident app or helper. macOS controls widget registration and rendering; an unsigned build is insufficient evidence of gallery availability.

The engineer has successfully run the app and added its widget to the desktop using a Personal Team. Shared App Group/Keychain access and extension execution with the app closed remain unverified; MAR-31 covers that proof. See docs/verification.md for the evidence and remaining platform checks.

See architecture for shared contracts and verification for evidence and remaining checks.