Skip to content

PROGRESS.md

Latest commit

 

History

History
119 lines (105 loc) · 14.3 KB

PROGRESS.md

File metadata and controls

119 lines (105 loc) · 14.3 KB
Raw

CrystalSpace Progress

Last updated: 2026-07-27

Completed

  • Read and adopted AGENTS.md, SPEC.md, and WALLSPACE_API.md.
  • Created a Swift 6.2 native macOS package targeting macOS 15.
  • Added CrystalSpace domain models with provider isolation and forward-compatible qualities.
  • Added transactional SQLite durable state for local wallpapers, favorites, playlists, playback preferences, and per-display configuration.
  • Added local MP4/MOV/M4V import with AVFoundation metadata validation and security-scoped bookmarks.
  • Added an AppKit wallpaper window and looping, muted AVFoundation renderer.
  • Added persistent display identity, independent display sessions, display hotplug refresh, apply-to-one, and apply-to-all.
  • Added startup restoration for local wallpapers.
  • Added a native SwiftUI local library, drag and drop, file picker, favorites, per-display apply actions, empty states, privacy messaging, and menu bar pause/resume.
  • Verified and implemented the public read-only Wallspace gallery endpoint with page-based pagination.
  • Added isolated Wallspace DTO, mapper, endpoint registry, public URL parser, request deduplication, bounded retry, and sanitized fixture tests.
  • Added a native Explore grid with lazy pagination, public thumbnails, 300 ms silent hover previews, Pro labeling, and deterministic local metadata filtering.
  • Added sleep/wake, display sleep/wake, Low Power Mode, battery-policy, and critical thermal pause handling.
  • Added deterministic local wallpaper IDs and bounded on-disk video thumbnail generation.
  • Added durable local playlists with create/delete/item management, sequential/shuffle modes, apply actions, duplicate prevention, and sequence tests.
  • Added persisted playback preference controls for performance mode, battery, Low Power Mode, and display sleep.
  • Added tolerant versioned state decoding so older state files migrate with safe defaults.
  • Added ordered SQLite migrations with WAL, foreign keys, the specified durable tables, and a one-time legacy JSON import that preserves the original backup.
  • Added per-display playlist assignment, manual next/previous, cancellation-safe intervals, On Wake, and On Login scheduling.
  • Added Apple ServiceManagement launch-at-login support with approval-state handling.
  • Added a signed sandboxed .app packaging workflow, crystalspace:// registration, and bundle verification.
  • Added CrystalSpace and public Wallspace deep-link parsing with navigation handling.
  • Added an isolated Lock Screen provider that accurately reports the absence of a supported public macOS setter API.
  • Replaced SwiftUI VideoPlayer previews after release smoke testing exposed an optimized-build runtime failure; previews now use a native AVPlayerLayer.
  • Reworked the application shell to match the supplied cinematic Wallspace reference: full-bleed poster hero, floating brand/navigation controls, featured metadata/actions, selectable wallpaper strip, curated card rows, and a compact Library hub.
  • Added native macOS 26 Liquid Glass effects to the floating controls with an accessible material fallback on macOS 15.
  • Added a muted, looping AVPlayer hero preview that switches with the selected wallpaper and respects Reduce Motion.
  • Extended content beneath a transparent full-size title bar, removing the blank title-bar band while preserving native traffic-light controls.
  • Reserved layout space below the floating controls on Explore and Library so interactive content is never obscured.
  • Made Home provider-neutral: Wallspace is labeled as a source, local and Wallspace items share the Featured row, and app-branded editorial wording was removed.
  • Added dynamic provider identities and a persisted multi-source manager.
  • Added a native source-management UI for adding, enabling, checking, and removing multiple Wallspace-compatible catalogues using complete user-supplied HTTPS URLs.
  • Combined enabled sources in Home and Explore with independent pagination, health, and provider-safe identity.
  • Reimplemented macOS 26 controls with native .glass and .glassProminent button styles inside GlassEffectContainer, retaining the macOS 15 material fallback.
  • Fixed tall/fullscreen Home geometry by independently anchoring hero copy and the preview rail, and capping the cinematic hero height so the Featured catalogue remains visible.
  • Reverse-engineered and documented the official Wallspace 1.6 read-only catalogue, home, category, ID-lookup, and exact public media path behavior without committing its client credential.
  • Implemented verified free master.mp4 downloads with progress, cancellation, duplicate-task coalescing, atomic finalization, AVFoundation media validation, managed offline storage, and immediate wallpaper apply.
  • Made catalogue actions state-aware: completed managed downloads switch to Apply-only, while an actively applied wallpaper gains a checkmark and disables the action; both states survive relaunch.
  • Added an always-visible Explore search field and deterministic filter menu for access, downloaded state, resolution, source, category, and sorting.
  • Raised persistent wallpaper windows one public AppKit level above the system desktop picture, made them non-hideable, and refresh their ordering on active-Space changes to prevent native-wallpaper flashes during rapid desktop/Space switching.
  • Added an isolated experimental macOS 26 Lock Screen provider based on Wallpaper-Sync’s MIT-licensed aerial-slot technique: current-schema aerial selection, AVFoundation HEVC conversion, validated backups, atomic replacement, Desktop-to-Idle index mirroring, wallpaper-process reload, rollback, and explicit restoration.
  • Added a direct unsandboxed distribution mode required for user-level Apple wallpaper-store access while retaining an optional sandboxed package mode with Lock Screen integration disabled.
  • Added guarded Lock Screen actions for both downloaded catalogue wallpapers and imported local videos, with explicit replacement confirmation and applied-state feedback.
  • Rebuilt the Playlists tab without nested AppKit split-view/toolbars: it now has a bounded sidebar workspace, first-playlist auto-selection, responsive detail controls, and a full-page creation empty state.
  • Home now selects the primary display’s active wallpaper as the default hero and first thumbnail. Managed downloads resolve back to current provider metadata when available and fall back to their durable local video/thumbnail when the item is outside the loaded catalogue page, so offline and paginated catalogues cannot desynchronize the hero and selection.
  • Added a native Icon Composer application icon built from the project-owned SVG version of CrystalSpace’s in-app sparkle mark. Release builds compile the layered Liquid Glass icon into Assets.car and include an .icns fallback.
  • Added a dependency-free DMG release stage using Apple tooling. It rebuilds and verifies the signed app, creates a styled drag-to-Applications image, compresses and optionally signs it, verifies the final disk image, and emits its SHA-256 checksum.
  • Prepared the repository for public GitHub hosting with comprehensive ignore and text-attribute rules, project/security/contribution documentation, structured issue and pull-request templates, macOS 26 pull-request CI, Dependabot coverage for Actions, and a tag-driven Developer ID notarized DMG release workflow.
  • Fixed the Home hero in fullscreen and ultra-wide windows by constraining its media and overlay coordinate space to the responsive hero bounds; featured copy and the thumbnail strip now remain fully inside the hero instead of being clipped by the content shelf.
  • Added launcher/overlay compatibility through macOS's real per-display wallpaper state: every applied video now produces a durable high-resolution still in Application Support and installs it with NSWorkspace.setDesktopImageURL; the animated AVPlayerLayer remains read-only capture-visible so standard screen recordings include motion while system-wallpaper consumers retain the still fallback.
  • Replaced separate display and Lock Screen actions with a unified destination picker that supports multiple persistent display selections plus the animated Lock Screen behind one confirmation flow.
  • Increased grid, card, control, list-row, and section spacing throughout Explore and every Library tab.
  • Completed native SMAppService Launch at Login UX in Settings and the menu bar, including a signed bundled LoginItem helper, main-app fallback, approval/install guidance, and status refresh when CrystalSpace becomes active.
  • Added a persistent, reversible checkbox to skip the animated Lock Screen replacement warning while keeping the warning enabled by default.
  • Eliminated black desktop/overlay frames by keeping a decoded still fallback beneath each AVPlayer layer, revealing video only after isReadyForDisplay, delaying new wallpaper windows until content is ready, and avoiding redundant WindowServer reordering on every Space change.
  • Preserved the selected Apple aerial slot before installing native desktop stills so the optional animated Lock Screen workflow remains available across applies and relaunches.
  • Fixed Lock Screen replacement after launcher-compatible native wallpaper installation: the index editor recognizes an interim Desktop-image/Idle-aerial state, then relinks both native providers to the remembered aerial because macOS requires that relationship for animated lock/login playback.
  • Made Lock Screen activation the final destination transaction, refreshes matching Idle timestamps, and added launch-time reconciliation after desktop restoration so Apple’s wallpaper agent reloads the animated aerial instead of leaving a static Lock Screen.
  • Added provider-specific Lock Screen configuration mapping: legacy Sonoma choices use selectedID plus showAsScreenSaver, while Tahoe’s com.apple.wallpaper.choice.aerials choices retain the observed assetID-only schema so System Settings does not reject them as MissingImage.
  • Enforced Wallspace access metadata at both mapping and download boundaries: Pro and unknown-access records never receive a downloadable master URL.
  • Added the verified Wallspace category mapping to deterministic metadata search.

In Progress

  • Durable download status/history records and interrupted-transfer resume data.

Blocked

Wallspace Pro entitlement

  • What: Authorized Wallspace Pro downloads and account entitlement.
  • Why: No entitlement/authentication contract has been verified.
  • Evidence: The official client constructs a deterministic master-media CDN path, but CDN reachability does not prove permission. Catalogue is_pro metadata is therefore enforced locally.
  • Attempted: Public site assets and the signed official client were inspected; only read-only, client-visible catalogue behavior was tested.
  • Missing: A user-authorized Pro request/response flow and entitlement contract.
  • Authentication research: The signed client exposes StoreKit purchase and license-key/device entitlement, not conventional account sign-in. The mutation body and validation contract remain unknown; “authorize all” is intentionally forbidden.
  • Work continuing: Explicitly free media now downloads, validates, persists locally, and applies; Pro/unknown items remain locked.

Experimental Lock Screen limitations

  • Apple still exposes no public animated Lock Screen setter API.
  • CrystalSpace’s direct distribution uses the reversible, undocumented user-level aerial-slot mechanism demonstrated by Wallpaper-Sync; sandboxed builds keep it disabled.
  • The user must first select and download an Apple animated aerial in System Settings.
  • CrystalSpace relinks the native Desktop and Idle providers to the chosen aerial and writes the configuration schema observed for that macOS wallpaper provider.
  • CrystalSpace never modifies the original imported wallpaper. It converts a managed HEVC copy, validates the current aerial, preserves a validated original backup, and asks for confirmation before replacement.
  • If Apple changes the wallpaper index schema, the provider fails without changing the desktop engine. If a later System Settings change alters the index, restoration preserves that newer index instead of overwriting it.

Remaining

  • Add interrupted-transfer resume data and durable download status/history records.
  • Add catalogue metadata disk caching.
  • Continue public Wallspace research without inventing or embedding credentialed endpoints.
  • Add a developer-team signing and notarization workflow for distributable releases.

Verification

  • Debug build: passed with Swift 6.2.3.
  • Release build: passed with Swift 6.2.3.
  • Test suite: 22 Swift Testing tests passed.
  • Signed sandboxed application bundle verification: passed.
  • Debug and optimized application launch smoke tests: passed.
  • Installed-app Home smoke test passed: the primary display’s applied Makoto P3 wallpaper was the animated hero and the visibly selected first thumbnail.
  • Installed-app Playlists smoke test passed: the empty state, in-content creation actions, and full-size layout render without the former split-view artifact or title-bar toolbar item.
  • Fullscreen Home layout smoke test at 1224×768: passed.
  • Explore search and complete filter-menu runtime smoke test: passed.
  • Persistent wallpaper window remained present at desktop level + 1 after application hiding and active-Space switching: passed.
  • Native desktop-image compatibility smoke test passed: after restoring the current CrystalSpace wallpaper, NSWorkspace.desktopImageURL(for:) resolved to the durable CrystalSpace-generated JPEG rather than the previous Apple wallpaper.
  • Standard macOS screen-recording smoke test passed: a 3420×2224, 2.98-second capture included the animated desktop, and wallpaper-region frames sampled two seconds apart contained distinct decoded pixels.
  • Live Lock Screen reconciliation validates that all active Desktop/Idle entries resolve to the remembered aerial ID using the Tahoe assetID schema, then relaunches both WallpaperAgent and WallpaperAerialsExtension.
  • Direct-build Lock Screen capability detection, downloaded-wallpaper action, and destructive-action confirmation UI smoke test: passed without modifying the Apple aerial.
  • Current Tahoe assetID wallpaper-index decoding and Desktop-to-Idle transformation regression test: passed.
  • Live free Wallspace master download, validation, managed import, SQLite persistence, and apply smoke test: passed.
  • Self-review: no TODO/fatal placeholders, debug printing, AI integration, telemetry, or committed secrets found.