[Improvement] OmacaseNotify — themed, fully-owned notification system

[splaice]

Goal

Replace the system-rendered notification path with an Omacase-owned notification experience: complete control of look, feel, and interaction, fully integrated with the theme system — themed colors and typography, per-theme notification sounds, actionable banners, and a replayable history — while keeping the current system backend as a fallback and a user choice.

Why the current system can't get there

omacase notify (lib/notify.sh) renders through macOS's notification center via terminal-notifier (osascript fallback). That ceiling is hard:

• Look/feel: banner appearance is Apple's — no theme colors, no fonts, no shape; the app icon is pinned to the sender. Omacase themes stop at the notification.
• Sounds: limited to /System/Library/Sounds names; per-theme sound identity is impossible.
• Interaction: no custom actions, no hover behavior, no history/replay we control.
• Reliability: banners are suppressed by Focus and gated by per-app Notification permission; the osascript path is documented in our own source as "FLAKY on modern macOS".

Alternatives evaluated

1. Stay on UNUserNotificationCenter (status quo) — zero customization headroom. Rejected as the primary path; retained as fallback.
2. Hammerspoon (hs.canvas) — could draw anything, but imports a Lua runtime + large third-party app for one feature; against the trim-third-party direction (Ice/Zed/yabai precedent). Rejected.
3. SketchyBar popups — SketchyBar was deliberately removed from the stack; re-adding it for notifications regresses that decision. Rejected.
4. OmacaseNotify: a small native daemon we build — ✅ chosen. Precedent already in-repo: OmacaseLauncher.app is built at install time; Xcode CLT (hence swiftc) is a boot.sh prerequisite, and the compile-at-install + ad-hoc codesign pattern is proven. Omarchy Quattro just validated the direction upstream by making its notification daemon a first-class shell plugin (replayable 10-notification history, DND, dedup) — this is the macOS analog.

Product shape (what the user gets)

• Banners rendered by Omacase: theme background/foreground/accent, Omacase typography, rounded panel matching OmniWM's aesthetic, stacked top-right, notch- and multi-display-aware, never steal focus.
• Theme integration: switching themes restyles notifications instantly (same generated-fragment pipeline as ghostty/btop/nvim), and each theme can define its own sound identity — logical events (info/success/warn/error) mapped per theme, with themes able to ship sound files.
• Interaction: click-to-run action, hover pauses the timeout, close affordance; later: multiple action buttons, omacase notify --history replay, a quiet toggle.
• omacase notify stays the single API — every existing call site (theme switch, keybinds, scripts) upgrades for free; system backend remains as fallback and as a style=system opt-out. No Notification permission prompts at all on the Omacase path.

Implementation plan follows in a comment.

[splaice]

Implementation plan

Self-contained; needs only this comment and the repo. Build in the four phases below — each ships alone. Read lib/notify.sh first: it is the single client API today (terminal-notifier → osascript fallback) and stays the API throughout.

Architecture

assets/notify/OmacaseNotify.swift     one-file Swift daemon+client (compiled at install)
assets/notify/Info.plist              bundle id org.omacase.notify, LSUIElement
lib/notifyd.sh                        build/install/agent lifecycle (mirrors lib/launcher.sh)
lib/notify.sh                         routing: daemon first, system fallback
config/omacase/notify.conf            seed-once user config (style, position, duration, quiet)
$OMACASE_DATA/generated/themes/<t>/notify   generated per-theme style fragment
~/.config/omacase/theme-notify        theme-linked fragment (via _theme_links)
$OMACASE_STATE/notify.sock            unix socket, daemon ⇄ client

• Bundle build: copy lib/launcher.sh's pattern exactly (stage → run installs → ad-hoc codesign), but the executable is compiled: swiftc -O assets/notify/OmacaseNotify.swift -o …/MacOS/OmacaseNotify. swiftc comes with the Xcode CLT, which boot.sh requires; guard with have swiftc || { warn …; return 0; } so absence degrades to the system backend, never breaks install.
• Process model: LaunchAgent org.omacase.notify (use the shared helper from [Improvement] Shared LaunchAgent helper for generated plists #15 if it has landed; else copy the launcher.sh dance), RunAtLoad, KeepAlive. One binary, two modes: no args = daemon (bind socket, run NSApplication); --post = client (connect, write one JSON line, exit). lib/notify.sh never needs nc/python.

Phase 1 — MVP daemon (banners, theme colors, click-dismiss)

Swift essentials (all AppKit, no external deps):

• Windows: NSPanel per banner — .nonactivatingPanel, level = .statusBar, collectionBehavior = [.canJoinAllSpaces, .stationary, .fullScreenAuxiliary] (OmniWM and Spaces ignore it; never steals focus), hasShadow, corner-radius layer. Stack from top-right of the screen with the menu bar, below the notch-safe area (NSScreen.main.safeAreaInsets on notched Macs); re-anchor on NSApplication.didChangeScreenParametersNotification.
• Content: title/subtitle/message labels + optional left image (the caller's --image), auto-dismiss timer (default 5s), click anywhere = dismiss (Phase 3 adds actions), NSTrackingArea hover pauses the timer.
• Protocol: one JSON object per line on the socket: {"title","subtitle","message","image","sound","event","onclick","timeout"}. Unknown keys ignored (forward compatibility).
• Style: read ~/.config/omacase/theme-notify (simple key=value: bg=#RRGGBB fg=… accent=… font=… radius=…); watch it with a DispatchSource.makeFileSystemObjectSource and re-style live — theme switches restyle without restart.
• Theme fragment generation: in lib/theme.sh, the renderer already emits per-app fragments into _theme_generated_dir; add a notify fragment derived from the same palette values the ghostty render uses (bg, fg, accent), and add ~/.config/omacase/theme-notify to _theme_links so switching relinks it. _is_omacase_link already whitelists $OMACASE_DATA/generated/themes/* — backup/restore semantics come free.
• Routing in lib/notify.sh: if style=omacase in ~/.config/omacase/notify.conf (seed-once; copy the config/omacase/login-items seeding pattern in lib/launcher.sh::_launcher_seed_login_items) AND the socket accepts the write → done; otherwise fall through to today's terminal-notifier/osascript path unchanged. Ship Phase 1 with style=system as the seeded default; flip to omacase in Phase 4 after soak.

Phase 2 — per-theme sounds

• Logical events: notify --event info|success|warn|error (existing --sound keeps working and wins when set explicitly).
• Resolution order in the daemon: theme fragment sound.<event>=<path-or-system-name> → theme dir themes/<name>/sounds/<event>.(aiff|wav|m4a) → built-in default map to system sounds. Play via NSSound (handles both files and system names).
• themes/manifest gains nothing structural — sounds are discovered by path, and the fragment generator writes sound.* lines only when the theme ships them. Update the theme docs section (README.md Themes and ownership) with the sounds contract.
• Convert the one hardcoded call site: lib/theme.sh line ~60 notify --subtitle "Theme" --sound Glass … → --event success.

Phase 3 — interaction depth

• --on-click "<cmd>": daemon runs it via /bin/bash -c as the user's argv, never string-interpolated into anything on click, then dismisses.
• Action buttons: "actions":[{"label","cmd"}] renders up to 3 buttons; keyboard: banner is nonactivating, so no key handling — document that.
• History: daemon keeps a 20-entry ring; omacase notify --history (client mode --history) prints it; omacase menu gets a "Notification history" entry that replays the last 10 (Quattro parity).
• Quiet: omacase notify --quiet on|off|status — daemon drops banners (still records to history) while quiet. Respecting macOS Focus automatically is explicitly out of scope (no supported API; document in the conf header).
• Dedup: identical title+message within 2s collapses into one banner with a ×N badge.

Phase 4 — integration polish

• Flip the seeded default to style=omacase; existing installs keep their conf (seed-once).
• omacase doctor: "Notifications" line — daemon running (socket connect), agent bootstrapped, style, theme fragment present.
• omacase uninstall: bootout + remove app bundle + agent (add to the same block as launcher/usage agents).
• Completion (completions/_omacase): notify options --event, --history, --quiet.

Tests (tests/run.sh + CI)

• Build test: swiftc -parse (syntax-check without full compile is fast) on assets/notify/OmacaseNotify.swift — macOS CI runner has CLT.
• Routing tests with a fake socket: start nc -lU "$tmp/notify.sock" (or a tiny python socket sink), point OMACASE_STATE=$tmp, style=omacase conf → assert omacase_notify writes valid JSON (parse the captured line) and does NOT invoke terminal-notifier (PATH-shim a failing terminal-notifier to prove it). Then remove the socket → assert fallback path is taken (shim records the call).
• Theme fragment: after a theme render in a temp DATA dir, assert notify fragment exists and contains bg=/fg=/accent=; assert _theme_links includes theme-notify.
• Conf seeding: temp HOME → seed creates the file; a pre-existing file is not overwritten.
• JSON injection: message containing " and newlines round-trips intact (client must JSON-encode properly — use python3 or hand-escape in notify.sh; do NOT printf raw into JSON).

Risks called out for the implementer

• Never activate: any makeKeyAndOrderFront on a non-panel steals focus from the tiling workflow — use orderFrontRegardless on the nonactivating panel and test while typing in another app.
• Multi-display: anchor to NSScreen.screens with the menu bar, not main (which follows key window).
• Daemon death mid-write: client gets EPIPE — catch and fall back to the system path silently (best-effort contract in notify.sh's header must survive).
• swiftc at install adds ~seconds — build only when source hash changes (store a hash marker beside the bundle, same idea as theme .live staging).

Verification / done criteria

Per phase: full suite green + shellcheck clean; manual: omacase notify --event success "hello" themed banner appears over a fullscreen OmniWM tile without focus change; switch themes → next banner restyled; kill the daemon → same command still produces a system banner. Phase 4 done = default flipped + doctor green.

Branch + PR per phase or one PR with phase commits; PR body says Closes #28 on the final phase (earlier phases reference the issue).