switchboard-streamdeck CLAUDE.md

Switchboard — Stream Deck plugin (developer guide)

A macOS Stream Deck plugin (public name Switchboard, by Moving Average Labs). Built with the Elgato SDK v2 (TypeScript/Node). The plugin UUID is com.movingavg.switchboard (renamed from the legacy com.johnknox.safarijump). Don't change it casually — installed buttons reference it, so a change orphans configured keys unless migrated. scripts/rename.sh performs such a migration (it rewrites the UUIDs in the Stream Deck profile store so settings survive); see that script before ever renaming again. Sixteen actions today (the manifest is the source of truth — scripts/make-hero.py reads it).

Layout

src/
  plugin.ts                 # entry: registers every action, streamDeck.connect()
  actions/*.ts              # thin SDK glue per action (onKeyDown/onDialRotate/…)
  applescript/
    escape.ts               # escapeForAppleScript (shared)
    runner.ts               # runAppleScript via osascript; classifyError (TCC)
  mac/                      # PURE, tested logic (no SDK, no I/O)
    targets/safari ...      # see files below
  safari/                   # Safari tab logic (targets.ts, applescript.ts, runner re-export)
  mac/agent-*.ts            # AI Project (supersedes the three per-agent keys):
                            #   agent-project (one AgentKind/AgentState vocabulary,
                            #   per-kind approval-prompt matchers, decideAgentFace,
                            #   per-kind key face), agent-scan (ADAPTER over the three
                            #   existing scanners — never a fourth scanner)
  mac/deprecation.ts        # the badge on the three superseded key faces; DELETE
                            #   this whole file when those actions are retired
  mac/cursor-*.ts           # Cursor CLI detection: cursor-scan (pgrep -f the installed
                            #   versions path -> ps -o pid=,ppid=,tty=,args= -> lsof), cursor-project
                            #   (identity + turn_ended state + approval-prompt scrape + key face)
  mac/claude-*.ts           # Claude Code detection: claude-scan (ps→batched lsof +
                            #   shell-snapshot busy children = "N shells still running"; pgrep
                            #   misses ancestors), claude-state (title marker: braille=working,
                            #   ✳=waiting; tmux pane-tty map), claude-transcript (~/.claude/
                            #   projects freshness), claude-project (state decision + key face)
  mac/{coalesce,serialize,press-gate}.ts  # shared async plumbing (all unit-tested)
  mac/pasteboard-stash.ts    # Paste Snippet's clipboard save/restore: copies the
                            #   WHOLE pasteboard (every item, every type) into a
                            #   named stash pasteboard and back, so a gesture
                            #   borrows the clipboard instead of keeping it.
                            #   NEVER stashes a ConcealedType clipboard.
  mac/snippet.ts             # Paste Snippet pure logic: size cap, and the four key
                            #   faces — preview (the default, whatever the text's
                            #   provenance), masked (opt-in per key), blank
                            #   (whitespace-only) and over-cap. Key-face SVG.
  mac/clipboard-snippet.ts   # Paste Snippet's ⌘C/⌘V route: the capture poll, the
                            #   snippet write (build the item, THEN clear), the
                            #   per-write ownership token, and the gesture
                            #   orchestration that saves/restores the clipboard
  mac/ax-text.ts             # Paste Snippet's no-clipboard route, CAPTURE ONLY:
                            #   captureViaAx reads AXSelectedText on the frontmost
                            #   app's focused element via System Events. Framed
                            #   `ok\n<text>` / nosel / unsupported / err|<n> — status
                            #   on the first line, payload after the first newline, so
                            #   selection text can't corrupt the framing. insertViaAx
                            #   exists but is NOT on the live path: the AX write was
                            #   measured reporting success while inserting nothing
tests/*.test.ts             # vitest; one file per pure module
com.movingavg.switchboard.sdPlugin/
  manifest.json             # actions, layouts, icons, CodePath -> bin/plugin.js
  ui/*.html                 # property inspectors (sdpi-components from CDN)
  ui/lib/permissions.js     # shared PI Accessibility-warning banner (see below)
  layouts/*.json            # custom encoder (touchscreen) layouts
  imgs/actions/<a>/*.png    # icon.png/@2x + key.png/@2x per action
  bin/plugin.js             # rollup output — COMMITTED (self-contained bundle)
  bin/macos/{scroll,tile,axcheck}  # compiled Swift helpers — committed, UNIVERSAL
                            #   (arm64+x86_64), Developer ID signed + notarized
helper/{scroll,tile,axcheck}.swift # native helpers (scroll wheel / window tiling / AX probe)
scripts/
  build-helpers.sh          # build the 3 helpers universal; auto-sign if a Developer ID cert is present
  notarize-helpers.sh       # no-Fastlane notarize fallback
  make-hero.py              # regenerate docs/switchboard-hero.png from the manifest
  rename.sh                 # UUID migration tool (see Rename section)
fastlane/                   # Developer ID signing + notarization (see Releasing)