@arach/lattices 0.2.0 → 0.6.1

package/docs/hyperspace-grid-snappiness.md

@@ -0,0 +1,210 @@
+# Hyper+G in-place grid — snappiness & satisfaction brief
+
+Context: `relayoutGroup()` already switched from sequential `RealWindowAnimator.setFrameRobust`
+to `WindowTiler.batchMoveAndRaiseWindows` (SLS freeze + one AX pass/app), with UI refresh
+deferred and a tap on commit. This is the "make it even better" pass.
+
+Code anchors:
+- Grid path: `WindowMotionMode.swift:1100 relayoutGroup()` → `:1138 distributeGroup()` (G = keycode 5, `:833`)
+- Batch move: `WindowTiler.swift:1753 batchMoveAndRaiseWindows` (freeze `:1767`, AX enum `:1776`, activate `:1818`, unfreeze `:1825`)
+- Sound: `DiagnosticLog.swift:162 AppFeedback.playTap`
+- Optional anim: `RealWindowAnimator.swift` (Timer 60fps, 0.28s — NOT on the batch path)
+- Chrome flash: `WindowTiler.swift:54 WindowHighlight.flash` (single-window only)
+- No haptics anywhere in the codebase yet → green field.
+
+---
+
+## The governing principle
+
+Perceived latency is bound to the **earliest** feedback the brain receives, not the moment
+pixels finish moving. The AX move is 40–120ms of work we can't fully erase. So the play is:
+**acknowledge on key-down (haptic + sound + overlay), move under cover, let the windows catch
+up.** Every quick win below is a variant of "fire feedback before the slow thing finishes."
+
+---
+
+## Quick wins (ship this week, low risk)
+
+### Q1 — Haptic on key-down (biggest bang, ~10 lines)
+There is zero haptic feedback today. `NSHapticFeedbackManager.defaultPerformer.perform(.alignment, performanceTime: .now)`
+is *exactly* the Loop/Magnet "snap" feel on trackpad/Force Touch. Fire it the instant `G` is
+matched in `keyDown` (`:833`), **before** `distributeGroup()` runs. Costs nothing, lands on the
+keypress, and the windows snapping ~80ms later reads as "instant + tactile."
+
+### Q2 — Decouple + pre-warm the tap sound
+`playTap` does `DispatchQueue.main.async { stop(); play() }`. Three problems:
+- the async hop delays the sound ~1 runloop turn past the keypress,
+- `stop()` then `play()` adds a tiny dead gap,
+- NSSound's *first* play in a session stutters (codec spin-up).
+
+Fixes: (a) prime the sound once on motion-mode entry by playing `tap.wav` at volume 0; (b) fire
+it synchronously on key-down (same site as the haptic), not after the move; (c) consider a
+prepared `AVAudioPlayer` (`prepareToPlay()`) or `AudioServicesPlaySystemSound` for sub-frame
+latency. Net: the *thunk* and the *tap* (haptic) coincide with the keypress, not the landing.
+
+### Q3 — Shrink the SLS freeze window
+`batchMoveAndRaiseWindows` does the slow `kAXWindowsAttribute` enumeration **inside** the
+`SLSDisableUpdate` freeze (`:1776`). The screen is frozen while we do AX queries. Resolve the
+AX elements *before* the freeze, freeze only around the set-frame writes, unfreeze immediately.
+Bonus: `relayoutGroup` already resolves each element via `recordOriginal`'s `ax(for: m)` (`:1113`)
+and then the batch path re-resolves the whole window list — pass the resolved elements in and
+skip the second AX pass entirely. Shorter freeze = less black-flash, snappier reveal.
+
+### Q4 — Stop activating every app
+`batchMoveAndRaiseWindows` calls `app.activate()` once per pid (`:1818`). With windows from N
+apps that's N activations → focus churn, Space flicker, and the overlay can lose key. AX
+`kAXRaiseAction` (already issued at `:1806`) reorders without activating. Activate **only** the
+app that should end up frontmost (the last-picked / aimed window), once. Raise the rest.
+
+### Q5 — Overlay "snap-pop" on the selection chrome
+The real move is a teleport, so add the *sense* of motion in the cheap overlay layer (no AX
+cost). When the grid lands, give each selection border a tiny scale overshoot (1.0→1.04→1.0,
+~120ms, Core Animation) + a one-shot green edge flash converging on the slot. This is the
+Arc/Raycast "it clicked into place" pop. Overlay-only, runs off the AX path, can't add input
+latency.
+
+---
+
+## Bigger bets (more design, higher ceiling)
+
+### B1 — Ghost-slot anticipation (kills perceived latency outright)
+On `G`, **instantly** paint the target grid as outlined ghost slots (you already compute
+`balancedGrid` rects → `tileFrame`). Animate the slots filling (or the picked windows' chrome
+sliding toward their slots) over ~140ms while the real `batchMove` runs underneath. The user
+sees motion begin on the same frame as the keypress; the real windows arrive under the
+animation. This fully decouples felt-speed from AX latency and is the single highest-ceiling
+change. The ghost overlay is also the natural home for Q5's pop.
+
+### B2 — Precompute on selection, commit = pure writes
+Every pluck/unpluck currently recomputes `balancedGrid` + `tileFrame` and re-resolves AX. Cache
+(a) the AX element per picked wid and (b) the target frame map, updated incrementally as the
+selection changes. By the time `G` fires, commit is nothing but the frozen set-frame loop —
+nothing to compute, nothing to resolve, minimal freeze.
+
+### B3 — Staggered cascade fill (the "deliberate fast" feel)
+Real windows must move simultaneously (per-window AX animation = jank — see "avoid"). But the
+*overlay* tiles/borders can land on a micro-stagger in reading order (~10–14ms/cell). The eye
+reads a fast left-to-right cascade as more intentional and premium than a flat simultaneous
+snap, while the actual work stays a single batch. Pure overlay timing.
+
+---
+
+## What to avoid (these ADD latency or jank)
+
+- **Don't animate many real windows via per-tick AX writes.** `RealWindowAnimator`'s 0.28s
+  Timer loop is fine for one window; across a group it's 60fps × N AX position+size writes —
+  AX is slow and serializes, so it stutters and feels *slower* than a clean teleport. Keep the
+  batch teleport; animate the overlay, not the windows.
+- **Don't do AX enumeration / `DesktopModel.poll()` inside the freeze or on the commit path.**
+  Poll/rebuild are already deferred (`refreshAfterGridMove`, `:1125`) — keep it that way; don't
+  let new chrome work creep back onto the hot path.
+- **Don't async-dispatch or `stop()`-then-`play()` the commit sound** (see Q2) — both push the
+  thunk past the keypress.
+- **Don't `app.activate()` per app** (Q4) — multi-app activation is the main source of flicker
+  and overlay focus loss.
+- **Avoid Timer-driven overlay animation.** Use Core Animation / `CADisplayLink`; `Timer` at
+  1/60 drifts and can hitch under load.
+- **Don't add dwell.** `WindowHighlight.flash` defaults to a 0.9s dwell + 0.3s fade — fine for a
+  one-shot locate, wrong for a snap pop. Snap feedback wants ~120–180ms total. Long fades read
+  as lag, not polish.
+
+---
+
+## Recommended ship order
+
+1. **Q1 + Q2** together — one small change at the `G` key site: haptic + synchronous pre-warmed
+   sound on key-down. Instant tactile upgrade, ~20 lines, no risk.
+2. **Q3 + Q4** — tighten `batchMoveAndRaiseWindows` (pre-resolve AX, shorter freeze, single
+   activate). Real latency reduction.
+3. **Q5** — overlay snap-pop on the chrome. First "ooh" moment.
+4. **B1** — ghost-slot anticipation once Q5's overlay exists to build on. This is the headliner.
+
+---
+
+## Implementation sketches
+
+### Sketch 1 — Haptic + tactile commit on key-down (Q1+Q2)
+At `WindowMotionMode.swift:833`, before dispatching the grid:
+```swift
+case 5: // G
+    if exposed { gatherInPlace() }
+    else {
+        AppFeedback.shared.commitTactile()   // haptic + sound, synchronous, NOW
+        distributeGroup()                     // remove the playTapSound() from relayoutGroup
+    }
+    return
+```
+New in `AppFeedback`:
+```swift
+func warmUp() {                       // call on motion-mode entry
+    tapSound?.volume = 0; tapSound?.play(); tapSound?.stop(); tapSound?.volume = 1
+}
+func commitTactile() {                // called on the keypress, on main
+    NSHapticFeedbackManager.defaultPerformer.perform(.alignment, performanceTime: .now)
+    tapSound?.currentTime = 0
+    tapSound?.play()                  // no async hop, no stop() gap
+}
+```
+Remove `AppFeedback.shared.playTapSound()` from `relayoutGroup()` (`:1120`) so the feedback is
+owned by the keypress, not the move completion.
+
+### Sketch 2 — Pre-resolved, minimal-freeze batch (Q3+Q4)
+New overload that trusts caller-resolved elements and freezes only the writes:
+```swift
+static func batchSetFrames(_ moves: [(el: AXUIElement, pid: Int32, frame: CGRect, raise: Bool)],
+                           frontmostPid: Int32?) {
+    // app -> enhanced-UI off, BEFORE freeze
+    let pids = Set(moves.map(\.pid))
+    let appRefs = Dictionary(uniqueKeysWithValues: pids.map { ($0, AXUIElementCreateApplication($0)) })
+    appRefs.values.forEach { AXUIElementSetAttributeValue($0, "AXEnhancedUserInterface" as CFString, false as CFTypeRef) }
+
+    let cid = _SLSMainConnectionID?()
+    if let cid { _ = _SLSDisableUpdate?(cid) }          // freeze ONLY the writes
+    for m in moves {
+        setFrameTriplet(m.el, m.frame)                  // size→pos→size
+        if m.raise { AXUIElementPerformAction(m.el, kAXRaiseAction as CFString) }
+    }
+    if let cid { _ = _SLSReenableUpdate?(cid) }         // unfreeze immediately
+
+    appRefs.values.forEach { AXUIElementSetAttributeValue($0, "AXEnhancedUserInterface" as CFString, true as CFTypeRef) }
+    if let frontmostPid { NSRunningApplication(processIdentifier: frontmostPid)?.activate() }  // ONE activate
+}
+```
+`relayoutGroup` already has `el` in hand from `recordOriginal` — collect it into `moves` and
+call this; no second `kAXWindows` enumeration, freeze shrinks to just the set-frame loop.
+
+### Sketch 3 — Overlay snap-pop on selection chrome (Q5)
+On grid landing, per slot, run a layer animation on the existing selection border view (overlay,
+not the window):
+```swift
+let pop = CAKeyframeAnimation(keyPath: "transform.scale")
+pop.values = [1.0, 1.045, 1.0]; pop.keyTimes = [0, 0.45, 1]
+pop.duration = 0.13; pop.timingFunction = CAMediaTimingFunction(name: .easeOut)
+borderLayer.add(pop, forKey: "snapPop")
+// + a one-shot edge tint that fades over the same 0.13s
+```
+No dwell, no AX. Fire it from `refreshAfterGridMove` (`:1125`) so it rides the deferred turn.
+
+### Sketch 4 — Ghost-slot anticipation (B1)
+On `G`, before the move, draw target slots in the motion overlay and animate the picked windows'
+*chrome* (or ghost rects) from current → slot, while `batchSetFrames` runs underneath:
+```swift
+func previewGrid(_ rects: [CGRect]) {     // rects already from balancedGrid → tileFrame
+    for (i, r) in rects.enumerated() {
+        let slot = ghostLayer(at: currentChromeFrame(i))
+        slot.frame = currentChromeFrame(i)
+        CATransaction.begin()
+        CATransaction.setAnimationDuration(0.14)
+        slot.frame = r                      // slides to target as the real window teleports under it
+        CATransaction.commit()
+    }
+}
+```
+Sequence: keypress → `commitTactile()` (Sketch 1) + `previewGrid()` same frame → `batchSetFrames()`
+→ ghosts fade as real windows land → `refreshAfterGridMove`. Felt latency ≈ 0; the move hides
+under 140ms of overlay motion.
+
+### Sketch 5 — Staggered cascade (B3, optional flourish)
+In `previewGrid`/snap-pop, offset each cell's animation `beginTime` by `index * 0.012` in
+row-major order. Overlay-only; the real batch stays simultaneous. Toggle behind a setting if you
+want a "calm" vs "playful" feel.

package/docs/layers.md

@@ -28,13 +28,13 @@ Add `groups` to `~/.lattices/workspace.json`:
   "name": "my-setup",
   "groups": [
     {
-      "id": "talkie",
-      "label": "Talkie",
+      "id": "vox",
+      "label": "Vox",
       "tabs": [
-        { "path": "/Users/you/dev/talkie-ios", "label": "iOS" },
-        { "path": "/Users/you/dev/talkie-macos", "label": "macOS" },
-        { "path": "/Users/you/dev/talkie-web", "label": "Website" },
-        { "path": "/Users/you/dev/talkie-api", "label": "API" }
+        { "path": "/Users/you/dev/vox-ios", "label": "iOS" },
+        { "path": "/Users/you/dev/vox-macos", "label": "macOS" },
+        { "path": "/Users/you/dev/vox-web", "label": "Website" },
+        { "path": "/Users/you/dev/vox-api", "label": "API" }
       ]
     }
   ]
@@ -46,10 +46,10 @@ to per-project configs.
 
 ### How it works
 
-- Session name follows the pattern `lattices-group-<id>` (e.g. `lattices-group-talkie`)
+- Session name follows the pattern `lattices-group-<id>` (e.g. `lattices-group-vox`)
 - 1 group = 1 tmux session. Each tab is a tmux window, and each window
   gets its own panes from that project's `.lattices.json`
-- You can still launch projects independently: `cd talkie-ios && lattices`
+- You can still launch projects independently: `cd vox-ios && lattices start`
   creates its own standalone session as before
 
 ### Tab group fields
@@ -73,9 +73,9 @@ lattices tab <group> [tab]  # Switch tab by label or index
 Examples:
 
 ```bash
-lattices group talkie       # Launch all Talkie tabs
-lattices tab talkie iOS     # Switch to the iOS tab
-lattices tab talkie 0       # Switch to first tab (by index)
+lattices group vox       # Launch all Vox tabs
+lattices tab vox iOS     # Switch to the iOS tab
+lattices tab vox 0       # Switch to first tab (by index)
 ```
 
 ### Menu bar app
@@ -136,6 +136,42 @@ Add `layers` to `~/.lattices/workspace.json`:
 }
 ```
 
+### App windows in layers
+
+Layers aren't limited to terminal sessions. You can include any
+application window by using the `app`, `title`, `url`, and `launch`
+fields instead of `path`:
+
+```json
+{
+  "name": "hudson",
+  "layers": [
+    {
+      "id": "main",
+      "label": "Main",
+      "projects": [
+        { "app": "Google Chrome", "title": "GitHub", "tile": "left" },
+        { "app": "Vox", "tile": "top-right", "launch": "open -a Vox" },
+        { "path": "/Users/you/dev/frontend", "tile": "bottom-right" }
+      ]
+    },
+    {
+      "id": "docs",
+      "label": "Docs",
+      "projects": [
+        { "app": "Google Chrome", "url": "https://docs.example.com", "tile": "left" },
+        { "app": "Notes", "title": "Sprint Notes", "tile": "right" }
+      ]
+    }
+  ]
+}
+```
+
+When switching to a layer, lattices matches windows by `app` name and
+optionally filters by `title` substring or `url` prefix. If `launch`
+is provided and no matching window is found, the command is executed
+to open the app.
+
 ### Using groups in layers
 
 Layer projects can reference a tab group instead of a single path.
@@ -146,11 +182,11 @@ This lets you tile a whole group into a screen position:
   "name": "my-setup",
   "groups": [
     {
-      "id": "talkie",
-      "label": "Talkie",
+      "id": "vox",
+      "label": "Vox",
       "tabs": [
-        { "path": "/Users/you/dev/talkie-ios", "label": "iOS" },
-        { "path": "/Users/you/dev/talkie-web", "label": "Website" }
+        { "path": "/Users/you/dev/vox-ios", "label": "iOS" },
+        { "path": "/Users/you/dev/vox-web", "label": "Website" }
       ]
     }
   ],
@@ -159,7 +195,7 @@ This lets you tile a whole group into a screen position:
       "id": "main",
       "label": "Main",
       "projects": [
-        { "group": "talkie", "tile": "top-left" },
+        { "group": "vox", "tile": "top-left" },
         { "path": "/Users/you/dev/design-system", "tile": "right" }
       ]
     }
@@ -168,7 +204,7 @@ This lets you tile a whole group into a screen position:
 ```
 
 When switching to this layer, lattices launches (or focuses) the
-"talkie" group session and tiles it to the top-left quarter, alongside
+"vox" group session and tiles it to the top-left quarter, alongside
 the design-system project on the right.
 
 ### Layer fields
@@ -182,9 +218,13 @@ the design-system project on the right.
 | `layers[].projects` | array  | Projects in this layer                   |
 | `projects[].path` | string?  | Absolute path to project directory       |
 | `projects[].group`| string?  | Group ID (alternative to `path`)         |
+| `projects[].app`  | string?  | Application name (for non-terminal windows) |
+| `projects[].title`| string?  | Window title substring to match          |
+| `projects[].url`  | string?  | URL prefix to match (browser windows)    |
+| `projects[].launch`| string? | Shell command to launch the app if not found |
 | `projects[].tile` | string?  | Tile position (optional, see below)      |
 
-Each project entry must have either `path` or `group`, not both.
+Each project entry must have either `path`, `group`, or `app` — pick one.
 
 ### Tile values
 
@@ -195,29 +235,68 @@ works: `left`, `right`, `top`, `bottom`, `top-left`, `top-right`,
 
 ### Switching layers
 
-Three ways to switch:
+Four ways to switch:
 
 | Method               | How                                      |
 |----------------------|------------------------------------------|
 | **Hotkey**           | Cmd+Option+1, Cmd+Option+2, Cmd+Option+3... |
 | **Layer bar**        | Click a layer pill in the menu bar panel |
 | **Command palette**  | Search "Switch to Layer" in Cmd+Shift+M  |
+| **CLI**              | `lattices layer <name\|index>`           |
 
 When you switch to a layer:
 
-1. Each project's terminal window is **raised and focused**
-2. If a project isn't running yet, it gets **launched** automatically
-3. Windows with a `tile` value are **tiled** to that position
-4. The previous layer's windows stay open behind the new ones
+1. Each project's window is **raised and focused**
+2. App windows are matched by `app` / `title` / `url`
+3. If a project isn't running yet, it gets **launched** automatically
+4. Windows with a `tile` value are **tiled** to that position
+5. The previous layer's windows stay open behind the new ones
 
 The app remembers which layer was last active across restarts.
 
+### Named layer switching
+
+You can switch layers by name from the CLI:
+
+```bash
+lattices layer hudson     # Switch to the layer named "hudson"
+lattices layer 0          # Switch to the first layer (by index)
+```
+
+This is useful for scripting — you don't need to know the index,
+just the layer's `id` or `label`.
+
+### Window tagging
+
+You can manually assign any window to a layer, even if it's not
+declared in `workspace.json`. This is useful for ad-hoc windows
+that you want to move with a layer:
+
+```bash
+lattices window assign <wid> <layer>   # Tag a window to a layer
+lattices window map                    # Show all window→layer assignments
+```
+
+Tagged windows behave like declared ones — they're raised and tiled
+when their layer activates. Remove a tag by reassigning or with:
+
+```bash
+# Via the agent API
+await daemonCall('window.removeLayer', { wid: 1234 })
+```
+
+### Layer bezel
+
+When you switch layers via hotkey, a translucent HUD pill appears
+briefly at the top of the screen showing the new layer's name.
+This provides instant visual feedback without interrupting your flow.
+
 ### Programmatic switching
 
-Agents and scripts can switch layers via the daemon API:
+Agents and scripts can switch layers via the agent API:
 
 ```js
-import { daemonCall } from '@arach/lattices/daemon-client'
+import { daemonCall } from '@lattices/cli'
 
 // List available layers
 const { layers, active } = await daemonCall('layers.list')
@@ -225,13 +304,69 @@ console.log(`Active: ${layers[active].label}`)
 
 // Switch to a layer by index
 await daemonCall('layer.switch', { index: 0 })
+
+// Switch to a layer by name
+await daemonCall('layer.switch', { name: 'hudson' })
 ```
 
 The `layer.switch` call focuses and tiles all windows in the target
 layer, just like the hotkey or command palette. A `layer.switched`
 event is broadcast to all connected clients.
 
-More methods in the [Daemon API reference](/docs/api).
+More methods in the [Agent API reference](/docs/api).
+
+## Rule-backed Studio layers
+
+Studio layers are live window rules stored in `~/.lattices/layers.json`.
+They are separate from `workspace.json` launch-and-tile layers: Studio
+layers do not launch projects. They resolve matching desktop windows,
+then recall or scope those windows in Studio and Screen Map.
+
+Each layer has a `match` array. A window joins the layer when it matches
+any clause in that array. Inside one clause, every present positive field
+must match, and every clause in `not` must fail.
+
+```json
+[
+  {
+    "id": "review",
+    "name": "Review",
+    "match": [
+      {
+        "appEquals": "Google Chrome",
+        "titleRegex": "(GitHub|Pull Request)",
+        "not": [
+          { "titleContains": "Actions" }
+        ]
+      },
+      {
+        "sessionContains": "lattices",
+        "isOnScreen": true
+      }
+    ]
+  }
+]
+```
+
+Supported clause fields:
+
+| Field | Match |
+|-------|-------|
+| `app` | App name contains this string |
+| `appEquals` | App name exactly equals this string |
+| `appRegex` | App name matches this regular expression |
+| `titleContains` | Window title contains this string |
+| `titleEquals` | Window title exactly equals this string |
+| `titleRegex` | Window title matches this regular expression |
+| `session` | Parsed lattices tmux session exactly equals this string |
+| `sessionContains` | Parsed lattices tmux session contains this string |
+| `isOnScreen` | Window is, or is not, visible on the current Space |
+| `spaceId` | Window belongs to this macOS Space id |
+| `not` | Exclusion clauses; any match rejects the window |
+
+`app` and `titleContains` are the original substring fields, so older
+`layers.json` files continue to work. New layers created from plucked
+windows use `appEquals` by default to avoid accidental substring matches.
 
 ### Layer bar
 
@@ -258,7 +393,7 @@ header and search field in the menu bar panel:
 ```json
 {
   "projects": [
-    { "path": "/Users/you/dev/talkie" }
+    { "path": "/Users/you/dev/vox" }
   ]
 }
 ```
@@ -276,12 +411,23 @@ No `tile` — just focuses the window wherever it is.
 }
 ```
 
+### Mixed: apps + terminals
+
+```json
+{
+  "projects": [
+    { "app": "Google Chrome", "title": "GitHub", "tile": "left" },
+    { "path": "/Users/you/dev/api", "tile": "right" }
+  ]
+}
+```
+
 ### Group + project
 
 ```json
 {
   "projects": [
-    { "group": "talkie", "tile": "left" },
+    { "group": "vox", "tile": "left" },
     { "path": "/Users/you/dev/api", "tile": "right" }
   ]
 }
@@ -305,6 +451,8 @@ No `tile` — just focuses the window wherever it is.
 - Projects don't need a `.lattices.json` config to be in a layer — any
   directory path works. If the project has a config, lattices uses it; if
   not, it opens a plain terminal in that directory.
+- App windows don't need any config at all — just specify `app` and
+  optionally `title` or `url` to match the right window.
 - You can have up to 9 layers (Cmd+Option+1 through Cmd+Option+9).
 - Edit `workspace.json` by hand — the app re-reads it on launch. Use
   the Refresh Projects button or restart the app to pick up changes.