Changelog

First-launch welcome window

Scene now greets new users on first launch with a friendly welcome window — confirming the app is running in the menu bar and pointing them at the icon with a native SwiftUI illustration. Long-overdue fix for the silent "did anything happen?" launch experience.

What's new

• One-time welcome window. On first install (after Accessibility permission is granted), a welcome window appears with:
  • Title: "Welcome to Scene"
  • Body explaining Scene is running and how to access it
  • A SwiftUI-drawn mock menu bar with the Scene icon highlighted by a pulsing accent ring and a bouncing "↑ Scene is here" caption
  • Two buttons: Got it (dismiss) and Open Settings (primary — opens Workspaces tab)
• One-shot. Tracked via a UserDefaults flag (hasShownFirstLaunchWelcomeV1). Survives reinstalls, never re-shows after dismissal. Flag is set at show-time (not on dismiss) so ⌘Q mid-welcome doesn't cause it to re-appear.
• Re-openable. Settings → About → "Show welcome screen again" triggers the welcome on demand without resetting the one-shot flag.
• Coordinated with AX onboarding. If Accessibility permission isn't granted yet at launch, the existing AX onboarding appears first. After the user grants permission, the welcome appears in its place. The two windows never overlap.
• Localized. English, 繁體中文 (香港) 粵語, 繁體中文 (台灣).
• Dynamic version string. The About tab now reads CFBundleShortVersionString directly from the app bundle instead of a stale localized "V0.4" constant. Future MARKETING_VERSION bumps no longer require a String Catalog edit.

Why this matters

New users often downloaded Scene, launched it, and saw nothing happen — the menu bar icon is easy to miss in the sea of other status items. The welcome window is an industry-standard pattern for menu bar utilities (Rectangle, Magnet, Raycast all do it), and it finally closes that "where did it go?" gap.

Under the hood

• No SceneCore changes. 177/177 unit tests still pass.
• Three new SwiftUI files under SceneApp/SceneApp/FirstLaunch/ (illustration / view / window controller) — mirrors the existing OnboardingWindowController pattern for consistency.
• Swift 6 strict-concurrency correct — applicationDidFinishLaunching now carries @MainActor to match the @MainActor-isolated method it calls.
• Hardened runtime, Developer ID signed, Apple notarized. No Gatekeeper warning.

Install

Homebrew (recommended):

``` brew upgrade --cask scene # existing users brew install --cask chifunghillmanchan/tap/scene # new users ```

DMG: download `Scene-0.5.2.dmg` below, double-click, drag into Applications. First-launch welcome will appear automatically once you grant Accessibility.

Upgrade notes

• If you're on v0.5.0 or v0.5.1, your Accessibility grant carries forward automatically — same Developer ID signature lineage, same cdhash binding policy. Just open v0.5.2 and the welcome will greet you.
• If you're on v0.4.3 or earlier (ad-hoc signed), the one-time Accessibility re-authorization from the v0.5.0 upgrade still applies. After that, v0.5.x → v0.5.y updates preserve the grant.

Continuous update detection

Until now, Scene only checked for new releases at launch. For a menu bar app people keep running for weeks, that passive-update-nudge never fired — you had to quit and relaunch to discover a new version.

v0.5.1 adds two recurring triggers on top of the launch-time check:

• Hourly timer — ambient background check, still rate-limited to one GitHub API call per 24 hours per device (no new network traffic pattern).
• Wake-from-sleep observer — when your Mac wakes up, Scene runs one check.

Practical effect: if you leave Scene running continuously, you'll see the "Update available: vX.Y.Z" menu item within about an hour of a new release, without touching the app.

Under the hood

• UpdateChecker.startPeriodicChecks() replaces the single checkIfDue() call at launch.
• 24-hour UserDefaults debounce is unchanged — the timer just unblocks it; it doesn't bypass it.
• No new permissions, no new endpoints, no new data.

Upgrade

• Homebrew: brew upgrade --cask scene
• DMG: download Scene-0.5.1.dmg below, drag into Applications.

v0.5.0 users: Accessibility grant is preserved automatically — same Developer ID lineage. v0.4.3 or earlier users: the one-time re-authorization described in v0.5.0's release notes still applies for the jump to the notarized lineage.

Notarized by Apple — no more Gatekeeper warnings

Scene v0.5.0 is signed with a Developer ID certificate and notarized by Apple. Install it like any other trusted Mac app — no right-click, no xattr, no "cannot be verified" prompt.

What this changes for you

• Fresh install. Double-click the DMG, drag Scene.app into /Applications, open it. That's it.
• Homebrew upgrade. brew upgrade --cask scene — the cask dropped its postflight quarantine strip because notarized DMGs are trusted by default.
• Future updates. Same Developer ID signature lineage means the cdhash stays stable across versions. macOS will preserve your Accessibility grant automatically on v0.5.0 → v0.5.1 → v0.6.0 and so on.

One-time upgrade step

If you're upgrading from v0.4.3 or earlier (ad-hoc signed), macOS treats v0.5.0 as a different app because the signature format changed. You need to re-authorize Accessibility once:

1. Quit Scene.
2. System Settings → Privacy & Security → Accessibility → remove Scene (select, press −).
3. Install v0.5.0 and relaunch.
4. Grant Accessibility again on the onboarding screen.

If toggling off/on doesn't work, run:

tccutil reset Accessibility com.hillman.SceneApp

The onboarding window has a Copy Command button. This is the last time the grant will reset — v0.5.x → v0.5.y updates preserve it automatically.

Under the hood

• Hardened runtime enabled.
• Explicit entitlements file (app-sandbox = false — AX API requires no sandbox).
• ITSAppUsesNonExemptEncryption = false in Info.plist (only standard HTTPS/TLS, qualifies for Apple's export compliance exemption).
• Build script (scripts/build-dmg.sh) signs with Developer ID, submits to Apple notary, and staples the ticket end-to-end. Set SKIP_NOTARY=1 for local ad-hoc test builds.
• 177/177 SceneCore unit tests pass; no regressions.

Install

Homebrew (recommended):

brew upgrade --cask scene                         # existing users
brew install --cask chifunghillmanchan/tap/scene  # new users

DMG: download Scene-0.5.0.dmg below, double-click, drag into Applications. No Gatekeeper bypass needed.

What's new

• Passive update nudge. Scene now checks GitHub once every 24 hours and shows a tinted "Update available: vX.Y.Z — click to download" item at the top of the menu when a newer release is out. Click it and the release page opens in your browser. No silent auto-install — because Scene is ad-hoc signed, every new build has a different cdhash that would invalidate your Accessibility grant. Keeping you in the DMG install path preserves the Homebrew tap's quarantine-strip postflight.

• Icon bytes down 77%. The 9 AppIcon PNGs had regressed from their V0.4.1 pngquant-compressed sizes (~672 KB total) back to uncompressed (~2.0 MB DMG). Re-ran pngquant, back to 156 KB for the icons and 1.4 MB for the DMG.

• +19 new unit tests. The semver comparison driving the update nudge moved into SceneCore as isVersionTag(_:newerThan:) — fully testable without Bundle / URLSession / Xcode. Patch / minor / major bumps, v prefix handling, zero-padding equivalence, pre-release suffix fail-safe, and malformed / empty input are all covered. Total SceneCore tests: 158 → 177.

Upgrade path

• If you're on v0.3, v0.4.0, v0.4.1, or v0.4.2: none of those builds have the update checker — you need to upgrade manually one more time. After that, future versions will notify you in-app automatically.
  • Homebrew: brew upgrade --cask scene
  • DMG: download Scene-0.4.3.dmg below, drag Scene.app into Applications, then re-grant Accessibility (the cdhash changes with every build, so macOS treats the new binary as a distinct app).
• If you're already on v0.4.3+: future release nudges will appear in your menu bar automatically. No action needed.

Why you should upgrade

Beyond the new nudge, v0.4.3 also carries v0.4.2's fixes:

• ProMotion (120Hz) animation lag eliminated for Cursor / Chrome / VS Code swaps.
• Workspace checkmark no longer "preselected" on launch.
• Workspace clicks fire instantly (no more 5s / 1.5s waits on empty app lists).
• Re-firing the same layout after opening a new window now catches the new window.

Details: Roadmap wiki.

Accessibility permission note

If the menu bar icon stays greyed out after install, run:

tccutil reset Accessibility com.hillman.SceneApp

...and grant Accessibility again in System Settings → Privacy & Security → Accessibility. The onboarding window has a Copy button for the command. This is expected behaviour for ad-hoc signed builds until the app moves onto a Developer ID (planned for a future release).

Tests

177 SceneCore unit tests pass; no regressions.

Fixes

• Animation lag on ProMotion (120Hz) displays. Cursor ↔ Chrome swaps now complete in the configured 250ms instead of dragging out to a second-plus. AX writes are throttled to 30Hz and deduped per window (0.5pt tolerance).
• Workspace "preselected on launch." The active-workspace checkmark is now session-only state. Earlier builds restored it from disk, so the menu bar showed a checkmark against a workspace the user did not pick in the current session. Legacy on-disk state is silently ignored and dropped on next write.
• Instant workspace click. AppLauncher.quit early-returns on an empty bundleIDs list (was waiting 5s for nothing); WorkspaceActivator skips the 1.5s settle when appsToLaunch is empty. Default seeded workspaces fire within ~50ms instead of ~6.5s.
• Layout re-fire after opening a new window. Pressing the same layout hotkey twice now adds a 200ms settle before re-enumerating, giving CGWindowListCopyWindowInfo time to register a window opened right before the hotkey. First fire of any layout is unchanged.

Install

Homebrew (recommended)

``` brew upgrade --cask scene ```

(New installs: `brew install --cask chifunghillmanchan/tap/scene`.)

DMG

Download `Scene-0.4.2.dmg` below, drag Scene.app into Applications, then follow `docs/INSTALL.md` for the one-time Gatekeeper + Accessibility steps.

Existing DMG users: Scene is ad-hoc signed, so macOS binds the Accessibility grant to the binary's `cdhash`. A fresh install invalidates the v0.4.1 grant. If the menu bar icon greys out after install, run `tccutil reset Accessibility com.hillman.SceneApp` (the onboarding window has a one-click Copy button) and re-grant Accessibility in System Settings.

Tests

158 SceneCore unit tests pass; no regressions.

Highlights

Under-1.5 MB DMG. Previous 2.8 MB → 1.4 MB via -Osize + thin LTO + full stripping, pngquant-compressed icons, and LZFSE DMG format.

Polished installer window. Custom light gradient background with a directional chevron, pinned icon positions (Scene on the left, Applications on the right), hidden toolbar/sidebar, 660×420 window — no more random Finder defaults.

Changes

Size & polish

• Release build with -Osize, thin LTO, full stripping (binary 1.9 MB → 840 KB)
• App icon PNGs pngquant+oxipng compressed; 1024×1024 variant dropped (Assets.car 2.1 MB → 232 KB)
• DMG format UDZO → ULFO (LZFSE)
• Custom installer background image (committed at dmg/background.tiff)

Workspace reliability

• WorkspaceActivator no longer shows "Activated" banner or sets activeWorkspaceID when the layout apply fails — surfaces a specific workspace.apply_failed notification instead
• CalendarTriggerWatcher skips empty-keyword triggers (previously matched every calendar event in the next 5 minutes)
• TriggerSupervisor single-flight guard prevents concurrent activations from racing
• WorkspaceStore.insert guards against duplicate IDs (new WorkspaceStoreError.duplicateID)
• +1 unit test (158 total, all pass)

Onboarding UX (after-update grant issue)

Re-installing Scene previously left users stuck with an "Accessibility toggle looks ON but Scene says denied" state, because macOS ties ad-hoc-signed grants to the binary's cdhash. The "Still not detected?" hint now:

• Explains the cdhash-binding reality
• Shows the exact tccutil reset Accessibility com.hillman.SceneApp command
• Provides a one-click Copy Command button for non-Terminal users

Localization

• Japanese removed; bundled locales are en / zh-HK / zh-TW

Docs

• README.md + README.zh-HK.md updated with V0.4.1 polish section
• INSTALL.md has a new troubleshooting row for the grant-denied-after-update scenario
• TESTING.md points at the 0.4.1 DMG

---

Scene-0.4.1.dmg · Apple Silicon · macOS 14+ · ~1.4 MB

First public release of Scene. Bundles V0.2 (customization + smooth animation), V0.3 (drag-to-swap), and V0.4 (Workspaces — the headline differentiator) into a single tag.

Requires macOS 14 (Sonoma) or later. Apple Silicon binary, ad-hoc signed.

Headline — Workspaces (情境)

A Workspace bundles layout + apps to launch + apps to quit + Focus mode + auto-triggers into a one-click productivity context switcher.

4 seed Workspaces ship with ⌘⌥1-4: Coding / Meeting / Reading / Streaming.

5 trigger types:

• Manual (hotkey or menu click)
• Monitor connect / disconnect (auto-activate when an external display plugs in)
• Time of day (weekday mask + HH:MM)
• Calendar event (EventKit keyword match, lazy permission)

Activation runs a safe 7-step flow: previous Focus Off → gentle quit (5s grace + notify; never force-quit — protects unsaved work) → launch → settle 1.5s → apply layout → Focus On → persist active + banner.

Other new features

• 3 vertical preset layouts (⌘⌃8 / ⌘⌃9 / ⌘⌃0): Main + Side Vertical, Halves Vertical, Thirds Vertical
• Layout thumbnails — Canvas-rendered accent rects in menu bar, Settings list, and Workspace editor
• Multilingual UI — full English + 繁體中文 (香港, 粵語 house style); stretch 繁體中文 (台灣) + 日本語
• Cross-store hotkey conflict — Workspaces and Layouts share a single chord namespace with block-save enforcement

Breaking changes

• Layout hotkeys moved: ⌘⇧1-7 → ⌘⌃1-9,0. The old ⌘⇧3 / ⌘⇧4 / ⌘⇧5 were being eaten by macOS screenshot / screen recording shortcuts. ⌘⌃ is uniform, collision-free, and keeps the number-keyed pattern.

Installation

1. Download Scene-0.4.0.dmg from this release
2. Drag Scene.app into /Applications
3. First launch will ask for Accessibility permission — grant in System Settings → Privacy & Security → Accessibility
4. If you previously had Scene installed: toggle Scene OFF then ON in the Accessibility list. Ad-hoc signed apps rebuild their code signature every release, invalidating the prior grant even though the toggle looks ON. If that fails, run:

   tccutil reset Accessibility com.hillman.SceneApp
   

   then relaunch.

Full install walkthrough: docs/INSTALL.md

Credits

• 157 XCTest cases (up from 116 in V0.3) covering layout math, window-to-slot mapping, animation state machine, JSON persistence, hotkey conflicts, drag-to-swap, Workspace store + triggers
• Full 粵語 zh-HK translation house-styled with 撳 / 嘅 / 係 / 咁 / 喺
• Zero external dependencies — pure Foundation + AppKit + SwiftUI + Carbon + EventKit

See README.md (English) or README.zh-HK.md (繁體中文 粵語) for the full feature list. Wiki: Home.

Scene V0.1 — a macOS menu bar app for instant window layouts.

Install

Download Scene-0.1.0.dmg, drag Scene.app to /Applications. First launch: right-click the app → Open to bypass Gatekeeper (the build is ad-hoc signed, not Apple-notarized). Full walkthrough in docs/INSTALL.md.

Requirements

• macOS 14 (Sonoma) or later
• Apple Silicon or Intel (universal binary)

Features

• 7 preset layouts: Full, Halves, Thirds, Quads, Main+Side, LeftSplit+Right, Left+RightSplit
• Global hotkeys ⌘⇧1–7
• Accessibility onboarding + degraded-state handling
• Electron tolerance (±5 px retry)
• Multi-display active-screen selection
• visibleFrame-aware placement (no overlap with menu bar or Dock)
• Zero external dependencies

Deferred to V0.2

• Drag-to-swap app wiring (core already implemented)
• Window move animation
• Per-display independent layouts
• Settings / preferences window