Rewrite CatNotch as a native macOS app (2.0.0)

Start with docs/adr/0001-rewrite-as-native-macos-app.md and the numbered phase specs, beginning at 0015; the issue says the first phase is a throwaway prototype of the NSPanel and click-through behavior. Read the existing app entry points and the macos/ Xcode project as each phase identifies them. Done means the native Swift app reaches current feature parity, passes the specified CatNotchCore tests, and the cutover removes Electron.

Problem Statement

CatNotch is an Electron and Next.js app that already depends on a Swift helper, a MediaRemote adapter and a native glass module. As a user, I pay for a whole Chromium runtime to run a bar that is always on: memory and CPU at idle, a larger download, and an animation and glass feel that falls short of a real macOS app. As a maintainer, I carry the Electron, helper and IPC stack, a 20-second dev start and a patched nextron.

Solution

Rewrite CatNotch as one native Swift app for Apple Silicon (macOS 14 and up), with every current feature and no cuts. The Notch is SwiftUI drawn inside an NSPanel per display. The app keeps its name, ships as 2.0.0, and reaches installed 1.0.x apps through a Bridge release that uses the old update file names. Existing tasks and settings carry over once. After that the app updates itself only when the user presses the button in Settings. See ADR 0001.

User Stories

1. As a user, I want the Notch to open when I hover it and fold away when I leave, so that it stays out of my way.
2. As a user, I want clicks outside the Notch to reach the apps beneath it, so that the bar never blocks my work.
3. As a user with a hardware notch, I want the Notch sized to it, so that it looks like part of the Mac.
4. As a user with several displays, I want to choose all, one or the primary display, so that the Notch appears where I work.
5. As a user, I want the Notch hidden over fullscreen apps, so that it never covers a video or game.
6. As a user, I want the closed Notch to show the clock when nothing else needs the space, so that it is useful at a glance.
7. As a user, I want transparent and glass styles with Catppuccin flavours, so that the Notch matches my setup.
8. As a user, I want a focus timer with a ring on the closed Notch, so that I see time left without opening it.
9. As a user, I want a focus log, so that I can see what I worked on.
10. As a user, I want quick-add tasks and a done view, so that I can capture and finish work from the Notch.
11. As a user, I want now playing with album art, a pulse while audio plays and playback controls, so that I control music from the Notch.
12. As a user, I want my calendar agenda, day details, tasks and special days, so that I see my day.
13. As a user, I want my reminders, so that I can see what is due.
14. As a user, I want a shelf where I drop files and drag them back out, so that I can move files between apps.
15. As a user, I want shelf items to survive a moved file, so that the shelf does not break.
16. As a user, I want my chosen photo and my recent screenshots on the Notch, so that I can reach them fast.
17. As a user, I want battery, headphones, mic and camera indicators, wifi, bluetooth and my most used apps, so that I see system state at a glance.
18. As a user, I want my Claude and Codex plan limits as rings, so that I know how much I have left.
19. As a user running Claude Code, I want its prompts to appear on the Notch and to answer them there, so that I do not switch windows.
20. As a user, I want Claude sessions listed and a chat on the Notch, so that I can follow and continue them.
21. As a user, I want prompts skipped when a terminal is in front but not when VS Code is, so that I am not asked twice.
22. As a user, I want Claude hooks to keep working after every launch, so that no prompt is silently lost.
23. As a user, I want a companion (cat, ghost, blob and the others, or my own photo) that reacts to the timer, tasks, music and the clock, so that the Notch has character.
24. As a user, I want switches to turn the companion's looking, sleeping and reacting off, so that it costs less.
25. As a user, I want a Settings window opened by a global shortcut, so that I can change anything quickly.
26. As a user, I want to choose whether CatNotch opens at login, so that it starts when I want.
27. As a user, I want to quit from Settings, so that I can close an app with no Dock icon.
28. As a user, I want an Update button in Settings that replaces the app only when I press it, so that updates never surprise me.
29. As an installed 1.0.x user, I want to update to the native app with the button I already have, so that I do not reinstall by hand.
30. As an upgrading user, I want my tasks, focus log, shelf and settings imported on first launch, so that I lose nothing.
31. As a maintainer, I want Electron deleted in one cutover PR after parity, so that the repo has a single app.
32. As a maintainer, I want logic tested without the UI, so that changes stay safe.

Implementation Decisions

• Apple Silicon only, macOS 14 and up, using Liquid Glass where available (macOS 26).
• SwiftUI inside an NSPanel per target display; AppKit only for window behaviour.
• Window model: no full-width strip and no cursor polling. One transparent panel sized to the largest open state sits at the top centre, with mouse events toggled by NSEvent monitors and tracking areas. A throwaway prototype of the panel and click-through comes first.
• Plain Xcode project in macos/ while Electron lives at the root; moved to the repo root at cutover. No path may assume macos/.
• One UI-free CatNotchCore module holds all testable logic (hook server, store and import, updater, usage limits, parsers).
• Identity: bundle ID com.devezio.catnotch, support folder CatNotch, store catnotch-store.json. First launch imports once from the old DeskNotch folder and leaves it untouched. Permissions are asked for again once.
• Unsandboxed, ad hoc signed, not notarized; GitHub Releases and Homebrew only (cask gets depends_on arch: :arm64).
• Version 2.0.0, in the Xcode project. The tag must equal the version, no v prefix.
• Bridge release: published under the legacy -universal-mac.zip name with a generated latest-mac.yml, so installed 1.0.x apps update to it; the zip is arm64 only despite the name. latest-mac.yml is still generated while 1.0.x installs exist.
• Updater: user-triggered only. Check the GitHub release, verify the checksum, swap the app in place with rollback, relaunch. No Sparkle.
• Claude hook server: the same HTTP protocol and port range (47821 and up) on Network.framework, re-syncing ~/.claude/settings.json hook entries to the live port on every launch.
• Now playing: the vendored mediaremote-adapter is kept unchanged and run as it is today; Swift only consumes its JSON stream.
• Shelf and photo use security-scoped bookmarks. Screenshots keep the folder watch.
• Companion: a native engine ported from the bot-avatars approach (SVG-path parser, layered shaded Canvas drawing with yaw, pitch and roll, and a three-state pose simulation: default, working, sleeping). All seven characters, the cat and the photo. Orbs and the ambient video are redrawn natively with a close, not pixel-exact, look.
• Shell behaviour kept: no Dock icon, no menu bar item, a global shortcut for Settings, open-at-login, display selector, Quit in Settings.
• Cutover: one PR deletes Electron, moves macos/ to the root, rewrites CLAUDE.md, the README and the Supported platform and Release glossary entries; then the 2.0.0 tag. Until it merges, Electron keeps shipping from main and new work only adds to macos/.
• One short numbered spec per phase, written just before the phase starts, from 0015 on.

Testing Decisions

• A good test checks external behaviour through the public interface of CatNotchCore, against temp folders and a loopback client, never internals.
• One seam: CatNotchCore, tested with Swift Testing and run by xcodebuild test on a macOS arm64 runner.
• Covered: hook server and settings.json sync, store and the DeskNotch import, updater checksum, swap and rollback, usage limits (fixture JSON per provider, last-good fallback) and parsers (pmset, fullscreen, helper events).
• Tests never touch the real ~/.claude: CLAUDE_CONFIG_DIR points at a temp folder.
• No automated UI tests. Panels, views, glass and companion drawing are checked by hand and through the prototype.
• Prior art: the existing vitest files for the hook server, battery, fullscreen and update install are the spec to port.

Out of Scope

• Intel Macs, Windows and Linux.
• The Mac App Store, the sandbox and notarization.
• Sparkle and automatic updates.
• A menu bar item.
• Any new feature beyond current parity.
• A pixel-exact match with the Electron UI.
• Automated UI tests, and tests for the companion engine (a second seam, added only if needed).

Further Notes

• Decisions and reasons are in docs/adr/0001-rewrite-as-native-macos-app.md; the term Bridge release is in GLOSSARY.md.
• The in-app updater only recognises a zip named -universal-mac.zip; that name must be kept for the Bridge release.
• Issues filed in thecharydev/catnotch only, never upstream.