[adefreitas]

Summary

Adds the companion: a small animated Stacky that floats on the desktop, takes the pill widget's place, and reacts to what stack-nudge knows (a waiting prompt, a busy agent, a finished turn, mute, quiet). It is on for new installs, offered once to existing installs after an update, and can be switched in Settings → Appearance → Floating widget. Builds on #227 (Settings… in the menu bar menu) and #228 (the widget no longer squeezes the panel into a pill).

Screen.Recording.2026-10-29.at.18.36.12.mov

Screen.Recording.2026-10-29.at.18.39.55.mov

Changes

• Skin engine (panel/Companion/): a skin is Core Animation layers built from baked PNG parts and a manifest, so the render server runs the animation and the app does no per-frame work. CompanionSkins is the registry, so more skins slot in beside Stacky. Only regular Stacky ships (assets/skins/stacky, 3.7 MB), copied into the bundle by build.sh.
• Floating window: borderless, never takes focus. Click opens the panel beside it, drag moves it, and its spot is saved as its bottom-right corner so a size change doesn't make it jump. A spot on a display that went away is pulled to the nearest screen. Animation pauses while covered, on display sleep and when locked; Reduce Motion holds it still.
• Poses, highest first: muted, quota past the alert threshold (alert), a queued event or permission prompt (pending, the wave), a busy agent (thinking), asleep after five quiet minutes, else idle. Open sessions that are not working leave it idle (not polling) and only keep it from napping; only a busy session changes the pose. A permission prompt is a waiting pose like any queued event, not an alert. The wave means something wants you to act, so a finished agent turn still waves.
• Count badge at the character's corner for events waiting on you (grey while muted), switched off with STACKNUDGE_COMPANION_BADGE.
• Info nod: a new finished agent turn plays one small nod when the character is otherwise calm (idle or asleep), notifications aren't muted, the session isn't muted and Reduce Motion is off; a burst earns one. Only live arrivals nod, not events restored at launch.
• CompanionInputs is where a later source of reactions publishes a value that CompanionController reads into CompanionSignals; it holds only the nod request today, and nothing here depends on feeds, GitHub, calendar or AI.
• The pill gives way while the companion is on and returns with its settings when it is off (widgetPreferred remembers the user's choice).
• Settings → Appearance → Floating widget: one picker row (Pill, Companion, Off) replacing the Widget toggle and the Companion on/off row. The pill's rows (snap, corner, opacity, type, mascot) apply only to Pill. STACKNUDGE_FLOATING_WIDGET holds it; a config without it is migrated on load (STACKNUDGE_COMPANION=true gives companion, else STACKNUDGE_COMPACT_MODE on unless false gives pill, else off) and the result is written back. Both old keys are still read, never written. The post-update Turn on card sets it too.
• Settings → Companion: Count badge, Size, Preview pose (forces any pose, never saved) and Reset position. While Floating widget isn't Companion the tab shows a note, a Turn on companion row that switches it, and the settings dimmed. They follow the fix(panel): make the keys mean the same thing on every page #224 key rules: toggles and actions act on Space/⏎, Floating widget, Size and Preview pose are value rows that pick, arrows alone never change anything. All are in selectedRowIsPicker and SettingsRowTests.
• Right-click menu: the menu-bar menu at the pointer, including feat(panel): Settings… in the menu bar menu and ⌘, to open Settings #227's Settings… (⌘,, the same showSettings), with a Companion submenu (Size, Reset position). Holding ⌥ while it is open reveals Debug: Pose preview and Info (nod). A 50 ms timer in the event-tracking run loop mode reads the key live, only while the menu is open.
• Post-update "Meet Stacky" card with a Turn on button, shown once (STACKNUDGE_COMPANION_OFFERED). It is keyboard-reachable: Tab / ⇧Tab move focus between Turn on and Got it (accent ring, the Settings selection style), ⏎ presses the focused one, and focus starts on Got it so ⏎ still dismisses. The decision is the pure PanelController.postUpdateKeyAction; the Tab hint shows only while the card does. Esc still hides the panel, via the global handler. Following fix(panel): swallow a held key after recording a shortcut #226, pressing ⏎ on the card arms the global key router to swallow that key's repeats, so a held ⏎ does not carry on into the Events page (GlobalKeyRouter.swallowRepeats).
• Layout race: turning the companion on or off flips compactMode and compactExpanded together. fix(widget): turning the widget on no longer squeezes the panel into a pill #228 now defers applyCompactLayout in both sinks, and setFloatingWidget (which drives them for Pill, Companion and Off) relies on that. The core adds no sink of its own, so each change lays out once.
• Config: STACKNUDGE_COMPANION (on in notify.conf.example, so new installs start with it), _SIZE, _BADGE, _POS, _OFFERED. README, CONTRIBUTING and notify.conf.example updated. Nothing is read or sent over the network, so PRIVACY.md needs no change.

Testing

With SDKROOT=/Library/Developer/CommandLineTools/SDKs/MacOSX26.5.sdk:

• ./build.sh: builds, only the existing ImplicitStrongCapture warnings.
• make test-without-xcode: 1510 tests, 0 failures.
• make typecheck-tests: OK.

Manual (the window and animation can't run in CI; I did not run the app):

1. Fresh config: the companion appears bottom right. Click it: the panel opens beside it. Click again or press the hotkey: it hides.
2. Drag it, relaunch: it comes back where you dropped it. Settings → Companion → Reset position (Space): it returns bottom right.
3. Right-click: menu-bar menu appears at the pointer. Companion → Size changes it live. Hold ⌥ with the menu open: Debug appears and disappears with the key. Pose preview shows each pose; the first menu item says a pose is previewed and stops it. Info (nod) plays one nod.
4. Settings → Appearance → Floating widget: Space then → steps Pill, Companion, Off; Pill returns at full panel size (not squeezed) and the pill's rows are dimmed otherwise. In the Companion tab → on Size does nothing; Space then ←/→ steps it. With the companion off the tab shows the note and Turn on companion.
5. Mute notifications: muted pose and a grey badge. Trigger a permission prompt: the waiting wave with a count badge, not alert.
6. Idle, then finish an agent turn: one nod, then the wave while it waits to be read.
7. Remove STACKNUDGE_FLOATING_WIDGET, STACKNUDGE_COMPANION and STACKNUDGE_COMPANION_OFFERED from the config, update from an older build: the post-update screen shows the card once.
8. On the update screen with the "Meet Stacky" card: Tab rings Turn on, ⇧Tab goes back to Got it, ⏎ on Turn on turns the companion on and the card goes, ⏎ on Got it leaves. Hold ⏎ on Turn on: nothing happens on the next page. Without the card, Tab does nothing and no Tab hint shows.
9. Right-click the companion: Settings… (and ⌘,) opens Settings.
10. Migration: with STACKNUDGE_COMPANION=true and no STACKNUDGE_FLOATING_WIDGET in the config, launch: the key is written as companion.

Related issues

None.

🤖 Generated with Claude Code