@arach/lattices 0.2.1 → 0.6.1

package/docs/proposals/LAT-002-shared-overlay-canvas.md

@@ -0,0 +1,353 @@
+# LAT-002: Shared Per-Screen Overlay Canvas
+
+## Status
+
+Partially implemented.
+
+The shared canvas primitive exists in `ScreenOverlayCanvasController`, and drag-snap zones now publish `snapZones` layers into it. Mouse gesture visuals, passive hotkey hints, and broader overlay consolidation are still pending.
+
+This document proposes a shared, click-through, per-screen overlay canvas for Lattices. The canvas would provide one persistent visual layer per display that features can draw into without each feature creating its own overlay window stack.
+
+## Summary
+
+Lattices already has several overlay-like systems:
+
+- `HUDController` prebuilds HUD panels, keeps them ordered, and toggles visibility with alpha.
+- `WindowDragSnapController` creates full-screen snap-zone panels per screen as needed.
+- `MouseGestureController` creates transient gesture overlay panels for gesture trails and results.
+- `MouseFinder`, `WindowTiler`, and Screen Map have their own small overlay and highlight mechanisms.
+
+These are useful, but they are still separate surfaces. Each one owns its own window lifecycle, z-order behavior, coordinate mapping, visibility rules, and cleanup. That makes every new ambient visual feature slightly more expensive than it should be.
+
+The proposed primitive is a `ScreenOverlayCanvas`: one transparent, click-through, always-on-top window per screen, owned by a central controller. Features publish lightweight visual layers into that canvas. The canvas stays passive by default and never becomes the place where input semantics or actions are decided.
+
+## Why Now
+
+Recent exploration of Clicky's macOS overlay approach highlighted a simpler mental model: create one full-screen transparent window per display, make it click-through, and draw small dynamic UI elements inside it. The visible object can be tiny and contextual, but the rendering surface is stable and screen-sized.
+
+That model maps well to several Lattices ideas:
+
+- snap drag target areas
+- passive hotkey information
+- layer and workspace hints
+- mouse gesture trails
+- focus and target highlights
+- command-mode affordances
+- window-map annotations
+
+Lattices already has the hard parts in pieces. The value is in unifying the canvas primitive so features stop reinventing overlay windows.
+
+## Current State
+
+### HUD
+
+`apps/mac/Sources/Core/Overlays/HUD/HUDController.swift` already uses a warm, persistent model:
+
+1. Panels are prebuilt.
+2. Panels stay ordered in the window server.
+3. Hidden state is mostly `alphaValue = 0`.
+4. Showing the HUD is an immediate alpha flip plus focus handling.
+5. Data refresh happens after first paint.
+
+This makes the HUD feel fast. But the HUD is a set of segmented panels: top, bottom, left, right, preview, and minimap panels. It is interactive and cockpit-like, not a general screen canvas.
+
+### Drag Snap
+
+`apps/mac/Sources/Core/Desktop/WindowDragSnapController.swift` creates `WindowSnapOverlayPanel` instances keyed by screen. Each panel covers a whole screen, ignores mouse events, joins all Spaces, and draws snap zones into an `NSView`.
+
+This is very close to the proposed canvas, but it is owned by drag snap and only exists for that feature's model.
+
+### Mouse Gestures
+
+`apps/mac/Sources/Core/Input/MouseGestureController.swift` creates a `MouseGestureOverlay` for a gesture session. It draws path feedback, recognition feedback, and completion labels. It is intentionally close to the input/action fast path, but its rendering should remain decorative.
+
+### Overlay Shells
+
+`apps/mac/Sources/Core/Overlays/OverlayPanelShell.swift` helps normal panel-based surfaces, but it is optimized for discrete overlay panels, not full-screen passive visual layers.
+
+## Proposal
+
+Create a shared `ScreenOverlayCanvasController` responsible for one click-through overlay window per `NSScreen`.
+
+The controller should provide:
+
+- stable full-screen transparent windows, one per display
+- local coordinate mapping for each screen
+- feature-scoped visual layer registration
+- cheap show/hide/update calls
+- deterministic z-order within the canvas
+- automatic screen-change reconciliation
+- explicit cleanup when features end
+
+The overlay windows should be:
+
+- borderless
+- transparent
+- non-activating
+- click-through
+- not key or main windows
+- able to join all Spaces
+- available in fullscreen auxiliary contexts where practical
+- high enough level for passive visual feedback, but configurable if a surface needs a lower level
+
+Conceptually:
+
+```swift
+@MainActor
+final class ScreenOverlayCanvasController {
+    static let shared = ScreenOverlayCanvasController()
+
+    func warmUp()
+    func reconcileScreens()
+    func publishLayer(_ layer: ScreenOverlayLayerSnapshot)
+    func removeLayer(id: ScreenOverlayLayerID)
+    func removeLayers(owner: ScreenOverlayOwner)
+}
+```
+
+The first implementation can be AppKit-first: an `NSPanel` or `NSWindow` per screen hosting a custom `NSView` that draws layer snapshots. SwiftUI hosting can come later for feature surfaces that benefit from it, but the lowest-level canvas should stay simple.
+
+## Non-Goals
+
+This proposal does not make the shared canvas interactive.
+
+Clickable UI should remain in separate panels or app windows. The shared canvas is for passive visual information and transient affordances. This keeps it safe: it should never steal clicks, focus, keyboard input, or app activation.
+
+This proposal also does not move action dispatch into the canvas. Features decide behavior elsewhere and publish visual state into the canvas.
+
+## Layer Model
+
+Layers should be declarative snapshots, not live feature-owned views by default.
+
+Good examples:
+
+- `snapZones`: trigger rects, hovered zone, preview rect
+- `gestureTrail`: path points, recognized shape, result label
+- `focusHighlight`: screen rect, color, pulse style, timeout
+- `hotkeyHints`: compact labels and positions
+- `layerStatus`: current layer, running sessions, stale sessions
+
+Each snapshot should include:
+
+- stable layer id
+- owner
+- target screen id, or all screens
+- z-index within the canvas
+- visibility/opacity
+- payload enum
+- optional expiry
+
+Example shape:
+
+```swift
+struct ScreenOverlayLayerSnapshot: Equatable {
+    let id: ScreenOverlayLayerID
+    let owner: ScreenOverlayOwner
+    let screen: ScreenOverlayScreenTarget
+    let zIndex: Int
+    let opacity: CGFloat
+    let payload: ScreenOverlayPayload
+    let expiresAt: Date?
+}
+
+enum ScreenOverlayPayload: Equatable {
+    case snapZones(SnapZoneOverlayPayload)
+    case gestureTrail(GestureTrailOverlayPayload)
+    case highlight(HighlightOverlayPayload)
+    case hotkeyHints(HotkeyHintOverlayPayload)
+}
+```
+
+This is intentionally plain. The canvas can render it synchronously without asking feature controllers for more state.
+
+## Coordinate Rules
+
+The canvas should make coordinate handling boring:
+
+- external feature APIs accept global AppKit screen coordinates unless explicitly documented otherwise
+- each screen view receives local coordinates derived from its `NSScreen.frame`
+- Y-axis conversion is centralized
+- screen identity uses `NSScreenNumber` when available
+- all features use the same screen id helper
+
+This matters because Lattices currently touches AppKit, CoreGraphics, AX, and ScreenCaptureKit coordinate systems. A shared canvas should reduce the number of local conversions.
+
+## Snap Drag Migration
+
+Snap drag is the best first adopter.
+
+Today, `WindowDragSnapController` already computes:
+
+- trigger rects
+- visible label rects
+- preview rects
+- hovered zone
+- screen grouping
+
+Instead of owning `WindowSnapOverlayPanel`, it can publish a `snapZones` layer:
+
+1. Drag begins and modifier mode is active.
+2. Controller resolves zones as it does today.
+3. Controller publishes `snapZones` snapshots grouped by screen.
+4. Mouse movement updates the hovered zone and preview rect.
+5. Mouse up removes the layer and dispatches tiling as today.
+
+The drag-snap action path should not change.
+
+## HUD Relationship
+
+The HUD should not be moved wholesale onto the shared canvas.
+
+The HUD is interactive: search, selection, keyboard focus, previews, sidebars. It should remain panel-based. But the shared canvas can support HUD-adjacent passive information:
+
+- pre-HUD hotkey hints
+- layer status while a modifier is held
+- ambient screen map outlines
+- tile target previews before full HUD activation
+- “what will happen if I drop here” hints
+
+Think of the canvas as the quiet always-ready visual substrate. The HUD remains the cockpit.
+
+## Mouse Gesture Relationship
+
+Mouse gesture recognition and event suppression must remain outside the canvas.
+
+The gesture controller can publish trail snapshots and completion markers to the canvas, but:
+
+- event tap callbacks still decide pass-through vs swallow
+- shape recognition stays in the gesture pipeline
+- action dispatch stays native and immediate
+- visual renderer failure cannot affect action behavior
+
+This dovetails with `LAT-001`: gesture visuals become consumers of semantic snapshots, not owners of recognition state.
+
+## Hotkey Overlay Mode
+
+A high-value use case is a passive hotkey layer.
+
+When the user holds a configured modifier chord, Lattices could fade in lightweight context:
+
+- current layer
+- active project/session names
+- snap zones
+- mouse gesture affordances
+- focused window identity
+- available drop targets
+- voice or command-mode status
+
+This would feel different from opening the HUD. It is not a modal command surface. It is a heads-up layer that answers, “what can I do right now?”
+
+If the user releases the chord, the layer fades away. If the user continues into an action, the relevant feature can take over and update its layer.
+
+## Window Level
+
+The canvas should probably start at a high but conservative level.
+
+Existing snap overlays use `CGWindowLevelForKey(.maximumWindow)`. Clicky uses `.screenSaver`. Both work, but they should not become an accidental default for every future surface.
+
+The canvas controller should centralize this decision and document it. A first version can use the level already proven by snap overlays, then adjust after testing with:
+
+- Terminal.app
+- iTerm2
+- browser fullscreen
+- Stage Manager
+- fullscreen Spaces
+- mission control edge cases
+
+## Performance Rules
+
+The canvas should be safe to keep warm:
+
+- no polling when no layers are visible
+- no timers inside the canvas unless a visible layer requires animation
+- no filesystem reads during drawing
+- no network access
+- no feature callbacks during draw
+- coalesce rapid updates per run loop
+- keep payloads small and value-like
+
+Animations should be bounded and cancelable. Expiring layers should clean themselves up even if a feature forgets to remove them.
+
+## Failure Model
+
+Overlay failure should be boring.
+
+If the canvas cannot create a window, the feature should still run without visuals.
+
+If one screen fails, other screens should continue.
+
+If a payload cannot be rendered, the canvas should skip that layer and log a diagnostic.
+
+If screen topology changes, the controller should reconcile windows and drop or remap stale screen-targeted layers.
+
+The shared canvas must not:
+
+- block input
+- steal focus
+- leave opaque windows stuck on screen
+- make actions depend on rendering
+- crash if a feature publishes malformed or stale visual state
+
+## Implementation Plan
+
+### Phase 1: Canvas Primitive
+
+- Add `ScreenOverlayCanvasController`.
+- Add a simple `ScreenOverlayWindow` or `ScreenOverlayPanel`.
+- Add screen identity and coordinate helpers.
+- Add a minimal `ScreenOverlayView` that can render `highlight` and `snapZones` payloads.
+- Warm up windows at app launch, hidden and click-through.
+
+### Phase 2: Drag Snap Adoption
+
+- Replace `WindowSnapOverlayPanel` ownership with canvas snapshots.
+- Keep existing snap-zone geometry and tiling behavior.
+- Verify multi-monitor drag, fullscreen Spaces, and modifier toggling.
+- Remove old snap overlay panel code after parity.
+
+### Phase 3: Gesture Visual Adoption
+
+- Publish gesture path snapshots from `MouseGestureController`.
+- Move native gesture trail drawing into the canvas renderer.
+- Keep recognition/action dispatch untouched.
+- Align with `LAT-001` renderer hooks.
+
+### Phase 4: Passive Hotkey Layer
+
+- Add a read-only modifier watcher for a passive “show context” chord.
+- Publish layer/session/window hints into the canvas.
+- Fade in/out quickly without activating Lattices.
+- Keep interactive HUD activation separate.
+
+### Phase 5: Consolidation
+
+- Identify duplicate overlay/highlight windows that can become canvas payloads.
+- Keep interactive panels on `OverlayPanelShell`.
+- Document which surfaces should use the canvas and which should remain separate.
+
+## Acceptance Criteria
+
+- One shared controller owns screen-sized click-through overlay windows.
+- Snap zones render through the shared canvas with no behavior regression.
+- Canvas rendering survives multiple monitors and screen changes.
+- Visual layers can be added/removed by owner id.
+- Hidden canvas windows do not intercept clicks or focus.
+- Drag snap still tiles correctly when visual rendering is disabled.
+- Mouse gestures can publish visual feedback without action dispatch depending on it.
+- Diagnostics make canvas creation, screen reconciliation, and render failures understandable.
+
+## Open Questions
+
+- Should the base window level match current snap overlays or use a lower default?
+- Should the canvas use one `NSView` renderer first, or host SwiftUI layers from the start?
+- How should expiry be modeled: controller-owned timers, per-layer deadlines, or both?
+- Should passive hotkey overlays live in the app config or user workspace config?
+- How much of `MouseFinder` and window highlight feedback should migrate to the canvas?
+
+## References
+
+- `apps/mac/Sources/Core/Overlays/HUD/HUDController.swift`
+- `apps/mac/Sources/Core/Desktop/WindowDragSnapController.swift`
+- `apps/mac/Sources/Core/Input/MouseGestureController.swift`
+- `apps/mac/Sources/Core/Overlays/OverlayPanelShell.swift`
+- `docs/proposals/LAT-001-gesture-visual-customization.md`

package/docs/proposals/LAT-003-menu-bar-controller-architecture.md

@@ -0,0 +1,291 @@
+# LAT-003: Menu Bar Controller Architecture
+
+## Status
+
+Mostly implemented.
+
+The menu bar, hotkey registration, daemon/service startup, workspace-inspector presentation, and activation-policy ownership have been extracted from `AppDelegate`. The optional `MenuBarPanelShell` remains deferred until a concrete menu-bar-adjacent panel needs it.
+
+This document records a narrow architecture proposal for the Lattices menu bar surface. The product direction is deliberately conservative: keep the existing menu bar UX, which is already strong, and extract the architectural lessons that make future menu-adjacent surfaces easier to build.
+
+## Summary
+
+Lattices currently uses `NSStatusItem` directly from `AppDelegate`, with a cached `NSPopover`, a right-click context menu, prewarmed SwiftUI content, global hotkey setup, service startup, daemon boot, and onboarding checks all coordinated from the same launch object.
+
+That works, and the visible menu bar experience should remain intact.
+
+The improvement proposed here is structural:
+
+- split menu bar ownership out of `AppDelegate`
+- keep the current `NSPopover` for the main projects surface
+- use custom `NSPanel` only for menu-bar-adjacent surfaces that need exact focus, positioning, or dismissal behavior
+- keep activation policy updates centralized
+- make app startup easier to reason about by moving hotkeys and services into small bootstrap components
+
+The result should be less launch-time sprawl, not a new visual design.
+
+## Why Now
+
+Recent review of Clicky's menu bar implementation highlighted a useful pattern:
+
+- `NSStatusItem` owns the menu bar icon
+- a custom borderless `NSPanel` owns the transient control panel
+- click-outside dismissal is explicit
+- panel focus behavior is explicitly defined
+- the app avoids standard popover chrome when it needs full control
+
+Lattices does not need to copy that wholesale. Our `NSPopover` is a good fit for the main menu bar projects view, and it already gives us useful system behavior.
+
+The lesson is more about ownership. Clicky's menu bar controller has one job. Lattices' `AppDelegate` currently has many.
+
+## Current State
+
+The relevant code is in `apps/mac/Sources/AppShell/AppDelegate.swift`.
+
+Today, `AppDelegate` owns:
+
+- app activation policy decisions
+- status item creation
+- menu bar icon drawing
+- left-click popover toggling
+- right-click context menu construction
+- popover prewarming
+- global hotkey registration
+- command palette configuration
+- drag snap, mouse gesture, keyboard remap startup
+- layer hotkey registration
+- tiling hotkey registration
+- onboarding and permission checks
+- daemon/model service startup
+- updater checks
+- debug launch flags
+
+This is not a correctness problem by itself, but it makes the app entry point harder to change. Any new launch-time surface adds one more responsibility to a file that already coordinates too much.
+
+## Non-Goals
+
+This proposal does not redesign the menu bar UI.
+
+This proposal does not replace the main menu bar `NSPopover` with a custom `NSPanel` by default.
+
+This proposal does not change command palette, HUD, Screen Map, or daemon behavior.
+
+This proposal does not alter the app's existing visual identity.
+
+## Proposed Components
+
+### 1. `MenuBarController`
+
+Owns only menu bar behavior:
+
+- create and retain `NSStatusItem`
+- draw or load the status item icon
+- route left-click and right-click behavior
+- own the cached projects popover
+- own the context menu
+- expose `dismissPopover()`
+- publish menu bar visibility state needed for activation policy
+
+The existing popover behavior should move here almost unchanged:
+
+- lazy `NSPopover` creation
+- SwiftUI content prewarm
+- `.transient` behavior
+- dark appearance
+- `latticesPopoverWillShow` notification
+
+This keeps the UX stable while making ownership clearer.
+
+### 2. `AppActivationCoordinator`
+
+Owns activation policy decisions.
+
+Today `AppDelegate.updateActivationPolicy()` checks a list of surfaces directly. That should become an explicit coordinator that asks registered surfaces whether they are visible.
+
+Conceptually:
+
+```swift
+protocol AppVisibleSurface {
+    var isVisibleForActivationPolicy: Bool { get }
+}
+
+final class AppActivationCoordinator {
+    static let shared = AppActivationCoordinator()
+
+    func register(_ surface: AppVisibleSurface)
+    func refresh()
+}
+```
+
+This avoids long hard-coded conditionals in `AppDelegate` as new windows are added.
+
+### 3. `HotkeyBootstrap`
+
+Owns global hotkey registration.
+
+This includes:
+
+- command palette
+- unified window or Screen Map
+- HUD
+- voice command
+- Hands Off
+- mouse finder
+- session layers
+- tiling commands
+- organize mode
+- OmniSearch
+
+The point is not to abstract the hotkeys away. The point is to isolate the big registration block into a component whose only job is binding actions to the existing controllers.
+
+### 4. `AppServicesBootstrap`
+
+Owns daemon and model startup:
+
+- `OcrStore`
+- `DesktopModel`
+- `OcrModel`
+- `TmuxModel`
+- `ProcessModel`
+- `LatticesApi`
+- `DaemonServer`
+- companion bridge
+- agent pool
+
+This keeps service startup grouped and timed without mixing it into menu bar construction.
+
+### 5. Optional `MenuBarPanelShell`
+
+Keep `NSPopover` for the current project list.
+
+Add a small helper only if we introduce menu-bar-adjacent panels that need custom behavior:
+
+- borderless `NSPanel`
+- explicit click-outside dismissal
+- non-activating or keyable variants
+- manual positioning below the status item
+- exact sizing around SwiftUI content
+
+This helper should not replace `OverlayPanelShell`. It is specific to status-item anchored panels.
+
+## Popover vs Panel Rule
+
+Use the cached `NSPopover` when the surface is:
+
+- anchored to the menu bar icon
+- mostly standard transient menu behavior
+- comfortable with popover sizing and dismissal semantics
+- part of the existing projects/menu surface
+
+Use a custom `NSPanel` when the surface needs:
+
+- non-standard chrome
+- unusual animation
+- explicit click-outside rules
+- custom focus behavior
+- independent window level
+- tighter control over multi-Space behavior
+
+This is the main lesson from Clicky: use `NSPanel` where control matters. Do not replace a good `NSPopover` just to be clever.
+
+## Suggested File Shape
+
+```text
+apps/mac/Sources/AppShell/
+  AppDelegate.swift
+  MenuBarController.swift
+  AppActivationCoordinator.swift
+  HotkeyBootstrap.swift
+  AppServicesBootstrap.swift
+  MenuBarPanelShell.swift      # optional, only when needed
+```
+
+`AppDelegate` should become a launch conductor:
+
+1. set activation policy and appearance
+2. create `MenuBarController`
+3. register hotkeys
+4. start input controllers
+5. run onboarding or permission checks
+6. start daemon services
+7. process debug flags
+
+It should not own the details of each of those systems.
+
+## Migration Plan
+
+### Phase 1: Extract `MenuBarController`
+
+- Move status item creation.
+- Move menu icon creation.
+- Move context menu construction.
+- Move cached popover creation.
+- Keep existing public behavior and notifications.
+- Route `MainView` dismissal through `MenuBarController` instead of reaching into `AppDelegate` if practical.
+
+### Phase 2: Extract Hotkey Registration
+
+- Move the global hotkey registration block into `HotkeyBootstrap`.
+- Keep action closures identical.
+- Keep controller singletons unchanged.
+- Add small helper methods only where they improve readability.
+
+### Phase 3: Extract Service Startup
+
+- Move daemon/model startup into `AppServicesBootstrap`.
+- Preserve existing startup order.
+- Preserve diagnostic timing.
+- Keep companion bridge preference behavior unchanged.
+
+### Phase 4: Activation Policy Cleanup
+
+- Introduce `AppActivationCoordinator`.
+- Register visible surfaces.
+- Remove the long hard-coded visibility conditional from `AppDelegate`.
+- Keep the current `.accessory` to `.regular` behavior.
+
+### Phase 5: Add `MenuBarPanelShell` Only If Needed
+
+- Do not add this during initial extraction unless a concrete menu-bar panel needs it.
+- If added, keep it separate from the main popover.
+- Document why that surface needs panel behavior.
+
+## Acceptance Criteria
+
+- Main menu bar popover looks and behaves the same.
+- Right-click menu behaves the same.
+- First popover open remains prewarmed and fast.
+- App activation policy behavior is unchanged.
+- Hotkeys continue to register and fire as before.
+- Daemon and model startup order is unchanged.
+- `AppDelegate` is materially smaller and easier to scan.
+- No new custom panel replaces the existing popover without a concrete need.
+
+## Risks
+
+The main risk is accidental behavior drift around activation policy and popover focus. The migration should be done in small steps and tested manually after each extraction.
+
+The second risk is over-abstraction. These components should be plain controllers, not a framework. The goal is named ownership, not ceremony.
+
+## Testing Notes
+
+Manual testing should cover:
+
+- left-click menu bar toggle
+- right-click context menu
+- popover dismiss by outside click
+- popover dismiss from project actions
+- command palette hotkey
+- HUD hotkey
+- Screen Map hotkey
+- voice command hotkey
+- app activation policy returning to accessory mode when surfaces close
+- launch with `--diagnostics`
+- launch with `--screen-map`
+
+## References
+
+- `apps/mac/Sources/AppShell/AppDelegate.swift`
+- `apps/mac/Sources/AppShell/MainView.swift`
+- `apps/mac/Sources/Core/Overlays/OverlayPanelShell.swift`
+- `/Users/art/dev/ext/clicky/leanring-buddy/MenuBarPanelManager.swift`