diff --git a/GRAPHICS.md b/GRAPHICS.md
new file mode 100644
index 000000000..19b2134b8
--- /dev/null
+++ b/GRAPHICS.md
@@ -0,0 +1,84 @@
+# Graphics — an inline-rendering guide for GitHub
+
+companion to `HAND.md` and `papers/VOICE.md`. HAND governs how the code reads, VOICE how the papers sound; this governs how a **PR, issue, or repo `.md` draws** — pictures that render on github.com from text alone.
+
+it exists because the reflex is to drag in a screenshot. a screenshot drifts the moment the code moves and can't be reviewed as a diff. a diagram written *in text*, beside the change, can't drift — it versions with the thing it explains. so: prefer the mark you can type.
+
+## the one rule
+
+**if it isn't a fence or `$math$`, it doesn't render.** github runs every markdown surface through a sanitizer. know the line and you stop guessing.
+
+## what renders inline — verified on github.com
+
+- **`​```mermaid`** — diagrams *and* charts. flow, sequence, state, er, class — and `pie`, `xychart-beta`, `sankey-beta`, `quadrantChart` for data. `classDef` colors nodes (the ac chartreuse-on-black look stays in text).
+- **`$…$` / `​```math`** — equations. `\color{…}{…}` and `\bbox[bg]{…}` tint *real content*. that's the whole of what math draws — see the dead end below.
+- **`​```geojson` / `​```topojson`** — an interactive leaflet map.
+- **braille / block art in a plain `​```` ` fence** — the only way to draw *arbitrary* art inline. low-res, but anything.
+- **prose primitives** — tables, task lists, `<details>`, `> [!NOTE]` alerts, footnotes.
+
+## what does not render — and why
+
+| you reach for | what happens | because |
+|---|---|---|
+| inline `<svg>…</svg>` | stripped | sanitizer |
+| `data:` uri in `<img>` | stripped | sanitizer |
+| `<script>` / `<style>` / iframe / raw css | stripped | sanitizer |
+| math `\rule{w}{h}` pixel art | **"unable to render"** | `\rule` is a *text-mode* tex command; mathjax implements only math-mode macros |
+| math `\colorbox{…}{…}` grid | broken | broken on github since may 2023, not restored |
+| `\begin{array}{@{}c@{}…}` + `\\[-Npt]` | **"unable to render"** | the `@{}` column spec and negative row gaps aren't supported |
+
+**the trap:** every `\textcolor{red}{\rule{…}}` "colored square" example on the web is a *native-latex → png* tool (readme2tex and kin). those commit an image. they do not work in github's mathjax. don't chase them — i did, it's a dead end.
+
+## draw anything inline: braille
+
+`\rule` is gone, so arbitrary art comes down to **unicode braille** (U+2800–28FF). each glyph is a 2×4 dot grid, so a generated field of glyphs is a 1-bit raster that renders anywhere monospace. `toolchain/art-to-braille.mjs` does it from a shape or from any png:
+
+```
+node toolchain/art-to-braille.mjs smiley
+node toolchain/art-to-braille.mjs flower
+node toolchain/art-to-braille.mjs image pic.png 50 [--invert]
+```
+
+it shells out to `sips` to normalize/resize, decodes the png with node's built-in `zlib` (no image library), thresholds luminance, packs the dots. a smiley:
+
+```
+⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢀⣀⣀⣀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀
+⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⣀⣤⣴⣶⣾⣿⣿⠿⠿⠿⠿⢿⣿⣿⣶⣶⣤⣄⡀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀
+⠀⠀⠀⠀⠀⠀⠀⢀⣠⣶⣿⡿⠟⠋⠉⠁⠀⠀⠀⠀⠀⠀⠀⠀⠀⠉⠉⠛⠿⣿⣷⣦⣀⠀⠀⠀⠀⠀⠀⠀
+⠀⠀⠀⠀⠀⢀⣴⣿⡿⠛⠁⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠙⠻⣿⣷⣄⠀⠀⠀⠀⠀
+⠀⠀⠀⠀⣰⣿⡿⠋⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠈⠻⣿⣷⡀⠀⠀⠀
+⠀⠀⠀⣼⣿⡟⠁⠀⠀⠀⠀⢰⣿⣿⣷⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢰⣿⣿⣷⠀⠀⠀⠀⠀⠙⣿⣿⡄⠀⠀
+⠀⠀⢰⣿⣿⠁⠀⠀⠀⠀⠀⠈⠛⠛⠋⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠈⠛⠛⠋⠀⠀⠀⠀⠀⠀⢹⣿⣷⠀⠀
+⠀⠀⣿⣿⡇⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⣿⣿⡇⠀
+⠀⠀⣿⣿⡇⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⣿⣿⡇⠀
+⠀⠀⢹⣿⣷⠀⠀⠀⠀⠀⢿⣿⣇⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢀⣿⣿⠇⠀⠀⠀⠀⢰⣿⣿⠁⠀
+⠀⠀⠀⢿⣿⣇⠀⠀⠀⠀⠘⢿⣿⣆⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢀⣾⣿⠟⠀⠀⠀⠀⢀⣿⣿⠇⠀⠀
+⠀⠀⠀⠈⢻⣿⣧⡀⠀⠀⠀⠈⠻⣿⣷⣦⣄⡀⠀⠀⠀⠀⠀⣀⣤⣶⣿⡿⠋⠀⠀⠀⠀⣠⣿⣿⠋⠀⠀⠀
+⠀⠀⠀⠀⠀⠙⢿⣿⣦⣀⠀⠀⠀⠀⠉⠛⠿⢿⣿⣿⣿⣿⣿⠿⠟⠋⠁⠀⠀⠀⢀⣠⣾⣿⠟⠁⠀⠀⠀⠀
+⠀⠀⠀⠀⠀⠀⠀⠙⠻⣿⣷⣦⣄⡀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⣀⣤⣶⣿⡿⠛⠁⠀⠀⠀⠀⠀⠀
+⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠉⠛⠿⢿⣿⣷⣶⣶⣤⣤⣤⣤⣴⣶⣶⣿⣿⠿⠟⠋⠁⠀⠀⠀⠀⠀⠀⠀⠀⠀
+⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠈⠉⠉⠙⠛⠛⠛⠉⠉⠉⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀
+```
+
+limits: low resolution, 1-bit (no grayscale or color), and it wants a monospace font with braille coverage. right for icons, logos, mascots, diagram-art — wrong for photos. for a photo, you've left inline-only: commit a code-generated svg/png and reference it by path.
+
+## picking a method
+
+```mermaid
+flowchart TD
+  q{show what?} --> d{flow / state?}
+  d -->|yes| mer[mermaid diagram]
+  d -->|no| c{quantities?}
+  c -->|yes| chart[mermaid chart]
+  c -->|no| f{formula?}
+  f -->|yes| math[math block]
+  f -->|no| g{geographic?}
+  g -->|yes| geo[geojson]
+  g -->|no| br[braille — shape or png]
+```
+
+label nodes with the real names — `disk.mjs`, `session-server`, not "service a". a diagram that names the code is navigable; boxes of abstractions are decoration. (same instinct as HAND: knowability first.)
+
+## the papers caveat
+
+none of this reaches the `papers/` xelatex pdfs — mermaid and mathjax are a github.com feature. in a paper the equivalents are native and better: tikz for diagrams, real latex math, `pgfplots` for charts, `\includegraphics` for raster. this guide is for the github surface — prs, rfcs, issues, readmes.
diff --git a/HAND.md b/HAND.md
index 10fd4c895..9d78757c0 100644
--- a/HAND.md
+++ b/HAND.md
@@ -1,6 +1,6 @@
 # The Hand — a code style guide for Aesthetic Computer
 
-companion to `papers/VOICE.md`. VOICE.md governs how papers *sound*; this governs how the code *reads*.
+companion to `papers/VOICE.md` and `GRAPHICS.md`. VOICE.md governs how papers *sound*, GRAPHICS.md how a PR or doc *draws*; this governs how the code *reads*.
 
 it exists because of what *The Hand and the Loop* (`papers/arxiv-hand-and-loop`) found: across three eras the codebase gained velocity and breadth and lost the instrument — the terse, single-mind discipline of the hand-written years. this guide is how the hand gets handed back to the loop. an agent that reads this should write code that knows it's part of an instrument, not just code that runs.
 
diff --git a/toolchain/art-to-braille.mjs b/toolchain/art-to-braille.mjs
new file mode 100644
index 000000000..b7eb98ab2
--- /dev/null
+++ b/toolchain/art-to-braille.mjs
@@ -0,0 +1,122 @@
+// art-to-braille.mjs — draw ANYTHING inline as Unicode braille (no deps, no files).
+//
+// The only route that actually renders arbitrary art inline on GitHub: pack a
+// boolean dot-field into braille glyphs (U+2800, 2 wide x 4 tall dots per char)
+// and drop the text in a ``` code fence. No MathJax (\rule is unsupported), no
+// committed image.
+//
+//   node art-to-braille.mjs smiley
+//   node art-to-braille.mjs flower
+//   node art-to-braille.mjs image path/to/pic.png [cols] [--invert]
+//
+// image mode shells out to macOS `sips` to normalize+resize any input to an
+// 8-bit PNG, then decodes it with Node's built-in zlib (no image library).
+
+import { execFileSync } from "node:child_process";
+import { inflateSync } from "node:zlib";
+import { readFileSync } from "node:fs";
+
+// (col 0..1, row 0..3) -> braille dot bit
+const DOTBIT = { "0,0": 0x01, "0,1": 0x02, "0,2": 0x04, "1,0": 0x08, "1,1": 0x10, "1,2": 0x20, "0,3": 0x40, "1,3": 0x80 };
+
+function render(cols, rows, on) {
+  let out = "";
+  for (let cy = 0; cy < rows; cy++) {
+    for (let cx = 0; cx < cols; cx++) {
+      let code = 0;
+      for (let r = 0; r < 4; r++)
+        for (let c = 0; c < 2; c++)
+          if (on(cx * 2 + c, cy * 4 + r)) code |= DOTBIT[`${c},${r}`];
+      out += String.fromCharCode(0x2800 + code);
+    }
+    out += "\n";
+  }
+  return out;
+}
+
+// ---- parametric shapes (normalized -1..1 field) ----
+function shapeField(name, W, H) {
+  return (px, py) => {
+    const dx = (px / W - 0.5) * 2, dy = (py / H - 0.5) * 2;
+    if (name === "smiley") {
+      const ring = Math.abs(Math.hypot(dx, dy) - 0.85) < 0.06;
+      const eyeL = Math.hypot(dx + 0.35, dy + 0.3) < 0.1;
+      const eyeR = Math.hypot(dx - 0.35, dy + 0.3) < 0.1;
+      const smile = dy > 0.1 && Math.abs(Math.hypot(dx, dy - 0.1) - 0.45) < 0.06;
+      return ring || eyeL || eyeR || smile;
+    }
+    if (name === "flower") {
+      const a = Math.atan2(dy, dx), r = Math.hypot(dx, dy);
+      const petal = r < 0.78 * Math.abs(Math.cos(3 * a)) + 0.18; // rose curve
+      const core = r < 0.16;
+      return petal || core;
+    }
+    return Math.hypot(dx, dy) < 0.85; // circle
+  };
+}
+
+// ---- minimal PNG decode (8-bit, color types 0/2/4/6, no interlace) ----
+function decodePng(buf) {
+  let p = 8; // skip signature
+  let w, h, ct, idat = [];
+  while (p < buf.length) {
+    const len = buf.readUInt32BE(p); const type = buf.toString("ascii", p + 4, p + 8);
+    const data = buf.subarray(p + 8, p + 8 + len);
+    if (type === "IHDR") { w = data.readUInt32BE(0); h = data.readUInt32BE(4); ct = data[9]; }
+    else if (type === "IDAT") idat.push(data);
+    else if (type === "IEND") break;
+    p += 12 + len;
+  }
+  const ch = { 0: 1, 2: 3, 4: 2, 6: 4 }[ct];
+  if (!ch) throw new Error("unsupported PNG color type " + ct);
+  const raw = inflateSync(Buffer.concat(idat));
+  const stride = w * ch;
+  const out = Buffer.alloc(h * stride);
+  const pae = (a, b, c) => { const pp = a + b - c, da = Math.abs(pp - a), db = Math.abs(pp - b), dc = Math.abs(pp - c); return da <= db && da <= dc ? a : db <= dc ? b : c; };
+  let q = 0;
+  for (let y = 0; y < h; y++) {
+    const f = raw[q++];
+    for (let i = 0; i < stride; i++) {
+      const x = raw[q++];
+      const a = i >= ch ? out[y * stride + i - ch] : 0;
+      const b = y > 0 ? out[(y - 1) * stride + i] : 0;
+      const c = i >= ch && y > 0 ? out[(y - 1) * stride + i - ch] : 0;
+      let v = x;
+      if (f === 1) v = x + a; else if (f === 2) v = x + b; else if (f === 3) v = x + ((a + b) >> 1); else if (f === 4) v = x + pae(a, b, c);
+      out[y * stride + i] = v & 0xff;
+    }
+  }
+  return { w, h, ch, px: out };
+}
+
+function imageField(path, dotW, invert) {
+  const tmp = "/tmp/braille-norm.png";
+  execFileSync("sips", ["-s", "format", "png", "--resampleWidth", String(dotW), path, "-o", tmp], { stdio: "ignore" });
+  const { w, h, ch, px } = decodePng(readFileSync(tmp));
+  return {
+    W: w, H: h,
+    on: (x, y) => {
+      if (x >= w || y >= h) return false;
+      const o = (y * w + x) * ch;
+      const lum = ch >= 3 ? 0.299 * px[o] + 0.587 * px[o + 1] + 0.114 * px[o + 2] : px[o];
+      const dark = lum < 128;
+      return invert ? !dark : dark;
+    },
+  };
+}
+
+// ---- main ----
+const mode = process.argv[2] || "smiley";
+let cols, rows, on;
+if (mode === "image") {
+  const path = process.argv[3];
+  cols = parseInt(process.argv[4] || "50", 10);
+  const invert = process.argv.includes("--invert");
+  const f = imageField(path, cols * 2, invert);
+  cols = Math.ceil(f.W / 2); rows = Math.ceil(f.H / 4); on = f.on;
+} else {
+  cols = 40; rows = 16;
+  const W = cols * 2, H = rows * 4;
+  on = shapeField(mode, W, H);
+}
+process.stdout.write(render(cols, rows, on));
-- 
2.51.2


From 36311a209a20c6eac7724b6e77c3092cc89cea4e Mon Sep 17 00:00:00 2001
From: "prompt.ac/@jeffrey" <mail@aesthetic.computer>
Date: Wed, 17 Jun 2026 12:07:08 -0700
Subject: [PATCH 02/13] pop/RELEASES: momabobasheep listener video PUBLIC on
 YouTube (GCOhg5J-brw)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

10:00 1920x1080 listener cut — 15 felt Seedance clips (9 movements + 6
added vignettes incl. the day-reliving sketchbook closer) cycling with no
back-to-back repeats, fresh crop drift each pass, xfade between scenes,
trim/slo-mo/stop-motion shots, wavy+grain+unsharp post, staggered pals
badges. Storyboarded in ShotWizard (video/board.json + build.mjs driver),
built via bin/assemble-listener.mjs + bin/chrome-listener.mjs.
---
 pop/RELEASES.md | 17 +++++++++++++++++
 1 file changed, 17 insertions(+)

diff --git a/pop/RELEASES.md b/pop/RELEASES.md
index 09ca87a32..c5ab4d2c8 100644
--- a/pop/RELEASES.md
+++ b/pop/RELEASES.md
@@ -19,6 +19,7 @@ All AC YouTube cuts are **1920×1080 landscape only** (vertical = Short, metadat
 | Helpabeach (v3) | [KVynj0RAwg8](https://youtu.be/KVynj0RAwg8) | `preview-score-helpabeach-yt.mjs` — multiply vignette half of `drawBacklight` dropped (warm sunset screen-glow kept); replaces v2 `WKdMYawwDPY` (deleted 2026-05-29 for the same side-darkening complaint) |
 | Amaythingra | [2FwOYCXS4UA](https://youtu.be/2FwOYCXS4UA) | `preview-score-yt.mjs` (big-pictures fork) — 32 cinematic beats, 3 render modes (photoreal office / glossy-grey metaverse / psychedelic AC-glitch degradation); chrome: per-slide tint, stained-glass colour-sep backlight, radial chromatic+blur edge-warp, glowy lanes, slide-blink bar, shimmer labels, kick beat-bump. Replaces `-at3b-chBbE`/`F-RhEL9OQ1g`/`KpK_MV8-178` (all deleted) |
 | Hellsine (v2) | [IjMGmPDvO4I](https://youtu.be/IjMGmPDvO4I) | `preview-score-hellsine-yt.mjs` — `drawVignette(c, v_i)` call removed from `paintSectionPanel` (function kept as dead code, mirrors marimbaba v3 / trancepenta-yt fix); replaces v1 `9KPUr6mA5e8` (deleted 2026-05-29, side-darkening crushed the felt-puppet panel edges); promoted to public 2026-05-29 |
+| Momabobasheep | [GCOhg5J-brw](https://youtu.be/GCOhg5J-brw) | **listener video** (not a preview-score cut) — 15 felt Seedance clips (`pop/momboba/video/board.json` + `build.mjs` driver, auditioned in ShotWizard) cycling so no clip repeats back-to-back, each under a fresh crop drift, smooth xfade dissolves between scenes, trimmed jumpy tails + slo-mo + stop-motion fps, gentle wavy displacement + film grain + unsharp, staggered pals badges (left low / right high, pals leading each rotated title column). `bin/assemble-listener.mjs` (cycling/crossfade plate) + `bin/chrome-listener.mjs`. Public 2026-06-17 |
 
 YouTube API quota: **6 video_insert / day / project** (`defaultVideoInsertPerDayPerProject`); deletes count toward the same window. On 2026-05-29 the de-vignette pass burned 5 of 6 (hellsine v1 upload at 02:04Z + delete hellsine v1 + delete helpabeach v2 + upload hellsine v2 + upload helpabeach v3) — next YT churn must wait for the 24h rolling window to clear.
 
@@ -714,6 +715,22 @@ DistroKid has a "request Spotify for Artists" shortcut for new artists.
   --reel split for the Reels UI). Canvas: `bin/build-canvas.mjs` —
   8 s silent ping-pong of the dream take. Audio bed = the track from
   5:20, swelling into THE DREAM's golden-section climax.
+- **YouTube (2026-06-17):** listener video PUBLIC →
+  <https://youtu.be/GCOhg5J-brw> (1920×1080, 10:00, ~1.07 GB). NOT a
+  preview-score cut — a new **listener** pipeline: 15 felt Seedance clips
+  (the 9 movement scenes + 6 added vignettes: boba-macro, sheep-sky,
+  pond-koi, color-field, night-moon, and a closing **sketchbook** shot that
+  feeds the day's prior stills forward as gpt-image-2 refs so the pages
+  relive the day) **cycled** so no clip repeats back-to-back, each under a
+  fresh crop drift, **xfade dissolves** between every scene, trimmed jumpy
+  tails + slo-mo + stop-motion fps, gentle wavy displacement + film grain +
+  unsharp, staggered pals side-badges (left low / right high, pals leading
+  each rotated title column). Storyboarded/auditioned in **ShotWizard**
+  (`pop/momboba/video/board.json` + `build.mjs` driver: `--shot <id>` gens
+  still+clip, `--assemble` cuts the full video). Built by
+  `bin/assemble-listener.mjs` (cycling/crossfade plate) →
+  `bin/chrome-listener.mjs` (chrome + post). Title "Momabobasheep",
+  hashtag-only description. Thumbnail = the lily-pad dream frame.
 - **Engine:** `pop/momboba/bin/render-momabobasheep.mjs` — a **generative**
   renderer (deterministic per `--seed`; the default seed string remains
   `mombobasleep`, the PRNG key for this exact walk). **C ENGINE
-- 
2.51.2


From 2b4b561542ad1a7809221177fdd4ae24dca60c15 Mon Sep 17 00:00:00 2001
From: "prompt.ac/@jeffrey" <mail@aesthetic.computer>
Date: Wed, 17 Jun 2026 12:27:38 -0700
Subject: [PATCH 03/13] =?UTF-8?q?pop/momboba:=20momabobasheep.youtube.txt?=
 =?UTF-8?q?=20=E2=80=94=20add=20Spotify=20+=20Apple=20Music=20links=20to?=
 =?UTF-8?q?=20the=20YouTube=20description=20(live=20on=20GCOhg5J-brw),=20m?=
 =?UTF-8?q?atching=20the=20marimbaba=20pattern?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 pop/momboba/momabobasheep.youtube.txt | 4 ++++
 1 file changed, 4 insertions(+)
 create mode 100644 pop/momboba/momabobasheep.youtube.txt

diff --git a/pop/momboba/momabobasheep.youtube.txt b/pop/momboba/momabobasheep.youtube.txt
new file mode 100644
index 000000000..2d7a3a312
--- /dev/null
+++ b/pop/momboba/momabobasheep.youtube.txt
@@ -0,0 +1,4 @@
+🎧 Spotify · https://open.spotify.com/album/1Hi0BG97U3aD4zW0Rmcabv
+ Apple Music · https://music.apple.com/us/album/momabobasheep-single-ep/6779669836
+
+#lullaby #sleep #ambient #marimba #felt #stopmotion #visualizer #aestheticcomputer #pixsies
-- 
2.51.2


From ce7e16913c251c1682e04c2bafbb1d7cdcaffc03 Mon Sep 17 00:00:00 2001
From: "prompt.ac/@jeffrey" <mail@aesthetic.computer>
Date: Wed, 17 Jun 2026 14:41:48 -0700
Subject: [PATCH 04/13] =?UTF-8?q?slab:=20frame=20=E2=80=94=20fleet=20scree?=
 =?UTF-8?q?n-capture=20primitive=20(pixels=20+=20OCR=20+=20AX=20+=20meta)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Native-capture complement to puppet (which only sees the browser via CDP):
frame observes the whole screen of any fleet Mac, puppet acts. Folded into the
menubar app (FrameCapture.swift) so it reuses the app's Accessibility trust and
GUI-session WindowServer access; captures in-process via ScreenCaptureKit (no
screencapture subprocess, no launchd throttle), runs Vision OCR with click
coords, walks the AX tree, downscales a thumbnail. Permissions are lazy: the
app never prompts at launch; the first frame request triggers Screen Recording.

bin/frame + frame.mjs: frame <machine> [--no-ocr] / doctor / setup / list,
config-driven from the shared ~/.config/slab/puppet.json.

install.sh: stable self-signed identity in a dedicated keychain, cert created
once and reused, signing done in the Aqua session — so TCC grants (Screen
Recording + Accessibility) survive rebuilds instead of resetting under ad-hoc.
---
 slab/bin/frame                                |  35 +++
 slab/bin/frame.mjs                            | 215 ++++++++++++++++++
 .../Sources/SlabMenubar/AppDelegate.swift     |   6 +
 .../Sources/SlabMenubar/FrameCapture.swift    | 212 +++++++++++++++++
 .../Sources/SlabMenubar/Paths.swift           |   7 +
 slab/menubar-swift/install.sh                 | 151 +++++++-----
 6 files changed, 563 insertions(+), 63 deletions(-)
 create mode 100755 slab/bin/frame
 create mode 100755 slab/bin/frame.mjs
 create mode 100644 slab/menubar-swift/Sources/SlabMenubar/FrameCapture.swift

diff --git a/slab/bin/frame b/slab/bin/frame
new file mode 100755
index 000000000..5d2bee184
--- /dev/null
+++ b/slab/bin/frame
@@ -0,0 +1,35 @@
+#!/bin/bash
+# frame — node-resolving wrapper around frame.mjs (mirrors the asana wrapper).
+#
+# Symlinked into ~/.local/bin like the other slab bins; resolves through the
+# symlink so SCRIPT points at frame.mjs next to this wrapper, then finds a
+# usable node even under launchd's minimal PATH.
+set -u
+SRC="${BASH_SOURCE[0]}"
+while [ -L "$SRC" ]; do
+  DIR="$(cd -P "$(dirname "$SRC")" && pwd)"
+  SRC="$(readlink "$SRC")"
+  [[ "$SRC" != /* ]] && SRC="$DIR/$SRC"
+done
+HERE="$(cd -P "$(dirname "$SRC")" && pwd)"
+SCRIPT="$HERE/frame.mjs"
+
+find_node() {
+  if command -v node >/dev/null 2>&1; then command -v node; return; fi
+  local c
+  for c in \
+    "$HOME/.local/share/fnm/aliases/default/bin/node" \
+    "$HOME/.fnm/aliases/default/bin/node" \
+    /opt/homebrew/bin/node \
+    /usr/local/bin/node \
+    "$HOME/.volta/bin/node"; do
+    [ -x "$c" ] && { echo "$c"; return; }
+  done
+  c=$(ls -td "$HOME"/.local/share/fnm/node-versions/*/installation/bin/node \
+        2>/dev/null | head -1)
+  [ -n "$c" ] && [ -x "$c" ] && { echo "$c"; return; }
+  return 1
+}
+
+NODE="$(find_node)" || { echo "frame: no node found" >&2; exit 1; }
+exec "$NODE" "$SCRIPT" "$@"
diff --git a/slab/bin/frame.mjs b/slab/bin/frame.mjs
new file mode 100755
index 000000000..4901b84bd
--- /dev/null
+++ b/slab/bin/frame.mjs
@@ -0,0 +1,215 @@
+#!/usr/bin/env node
+// frame.mjs — capture a rich "frame" of a remote Mac for fleet automation.
+//
+// A frame = pixels (a downscaled JPEG thumbnail) + OCR'd text with click
+// coordinates + the Accessibility element tree (roles/titles/AXPress targets)
+// + window/cursor/frontmost state, packed into one JSON envelope. It is the
+// native-capture complement to `puppet`: `frame` OBSERVES the whole screen
+// (any native app, no DOM needed), `puppet` ACTS (trusted stroke/gesture/key).
+// Together they close an observe→act loop across the fleet.
+//
+// The capture is produced ON the target by the SlabMenubar app (see
+// FrameCapture.swift) — it already holds Accessibility trust and lives in the
+// GUI session, so it can reach the WindowServer that a plain ssh session
+// cannot. This CLI just drops a request file over SSH and reads the result.
+//
+// PERMISSIONS ARE LAZY: the app never prompts at launch. The first real frame
+// request is what triggers the Screen Recording grant on the target; until
+// granted, the envelope reports `capture: "permission_needed"` and `frame
+// setup <machine>` walks you through the one-time toggle.
+//
+// This file ships in the PUBLIC aesthetic.computer repo, so it carries NO
+// machine names: the registry lives in the UNTRACKED config shared with
+// puppet at ~/.config/slab/puppet.json. A machine's name doubles as its ssh
+// host (the minis are ssh aliases); set "sshHost" per machine to override.
+
+import { execFileSync } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+const HOME = process.env.HOME;
+const CONFIG_PATH =
+  process.env.SLAB_PUPPET_CONFIG || join(HOME, ".config", "slab", "puppet.json");
+const FRAMES_DIR = join(HOME, ".local", "share", "slab", "frames");
+const APP_BUNDLE = "computer.slab.menubar";
+const REMOTE_STATE = "~/.local/share/slab/state"; // expanded by the remote shell
+
+function loadMachines() {
+  if (!existsSync(CONFIG_PATH)) {
+    console.error(`no config at ${CONFIG_PATH} — register machines (puppet config)`);
+    process.exit(1);
+  }
+  const cfg = JSON.parse(readFileSync(CONFIG_PATH, "utf8"));
+  return cfg.machines || {};
+}
+
+function sshHostFor(name, machines) {
+  return machines[name]?.sshHost || name;
+}
+
+// One ssh invocation with a warm multiplexed master so repeated frames are fast.
+function ssh(host, remoteCmd, { timeoutMs = 15000 } = {}) {
+  const cp = join(HOME, ".ssh", `cm-${host}`);
+  return execFileSync(
+    "ssh",
+    [
+      "-o", "ControlMaster=auto",
+      "-o", `ControlPath=${cp}`,
+      "-o", "ControlPersist=300",
+      "-o", "BatchMode=yes",
+      host,
+      remoteCmd,
+    ],
+    { encoding: "utf8", timeout: timeoutMs, maxBuffer: 64 * 1024 * 1024 },
+  );
+}
+
+function captureFrame(name, { noOCR = false, out, json = false } = {}) {
+  const machines = loadMachines();
+  if (!machines[name]) {
+    console.error(`unknown machine "${name}" — known: ${Object.keys(machines).join(", ") || "(none)"}`);
+    process.exit(1);
+  }
+  const host = sshHostFor(name, machines);
+  const mode = noOCR ? "noocr" : "full";
+  // Drop the request, wait for the daemon's done marker (≤4s), emit the envelope.
+  const remote =
+    `d=${REMOTE_STATE}; mkdir -p "$d"; rm -f "$d/frame.done"; ` +
+    `printf '%s' '${mode}' > "$d/frame.req"; ` +
+    `for i in $(seq 1 200); do [ -f "$d/frame.done" ] && break; sleep 0.02; done; ` +
+    `cat "$d/frame.out.json" 2>/dev/null`;
+  let raw;
+  try {
+    raw = ssh(host, remote);
+  } catch (e) {
+    console.error(`ssh ${host} failed: ${e.message.split("\n")[0]}`);
+    process.exit(1);
+  }
+  let env;
+  try {
+    env = JSON.parse(raw);
+  } catch {
+    console.error(`no frame from ${name} — is SlabMenubar running there? (frame doctor ${name})`);
+    process.exit(1);
+  }
+  if (env.capture === "permission_needed") {
+    console.error(
+      `${name}: Screen Recording not granted to SlabMenubar yet.\n` +
+        `  run:  frame setup ${name}\n` +
+        `  (AX + window/meta still captured; pixels + OCR are blocked until granted)`,
+    );
+  }
+  // Write the thumbnail out; keep the base64 out of stdout unless --json.
+  const outPath = out || join(FRAMES_DIR, `${name}.jpg`);
+  if (env.thumb_jpg_b64) {
+    mkdirSync(dirname(outPath), { recursive: true });
+    writeFileSync(outPath, Buffer.from(env.thumb_jpg_b64, "base64"));
+  }
+  if (json) {
+    process.stdout.write(JSON.stringify(env));
+    return;
+  }
+  const { thumb_jpg_b64, ...rest } = env;
+  rest.thumb = env.thumb_jpg_b64 ? outPath : null;
+  rest.ocr_count = (env.ocr || []).length;
+  rest.ax_count = (env.ax?.elements || []).length;
+  delete rest.ocr;
+  delete rest.ax;
+  console.log(JSON.stringify(rest, null, 2));
+}
+
+// Read a TCC grant state over ssh (system DB is world-readable here).
+function srGrant(host) {
+  try {
+    const q =
+      `sqlite3 "/Library/Application Support/com.apple.TCC/TCC.db" ` +
+      `"select auth_value from access where service='kTCCServiceScreenCapture' ` +
+      `and client='${APP_BUNDLE}';" 2>/dev/null`;
+    return ssh(host, q).trim();
+  } catch {
+    return "";
+  }
+}
+
+function doctor(name) {
+  const machines = loadMachines();
+  const names = name ? [name] : Object.keys(machines);
+  if (!names.length) {
+    console.error(`no machines registered (${CONFIG_PATH})`);
+    process.exit(1);
+  }
+  for (const n of names) {
+    const host = sshHostFor(n, machines);
+    let running = "?";
+    try {
+      running = ssh(host, "pgrep -x slab-menubar >/dev/null && echo yes || echo no").trim();
+    } catch (e) {
+      console.log(`${n}: UNREACHABLE (${e.message.split("\n")[0]})`);
+      continue;
+    }
+    const sr = srGrant(host);
+    const srLabel = sr === "2" ? "granted" : sr === "" ? "not listed (capture once to register)" : `denied (auth=${sr})`;
+    console.log(
+      `${n}: SlabMenubar ${running === "yes" ? "running" : "NOT running"} | ` +
+        `Screen Recording ${srLabel} | Accessibility inherited from app trust`,
+    );
+  }
+}
+
+function setup(name) {
+  const machines = loadMachines();
+  if (!machines[name]) {
+    console.error(`unknown machine "${name}"`);
+    process.exit(1);
+  }
+  const host = sshHostFor(name, machines);
+  console.log(`Triggering a capture on ${name} to surface the Screen Recording prompt…`);
+  captureFrame(name, { noOCR: true });
+  const sr = srGrant(host);
+  if (sr === "2") {
+    console.log(`✓ ${name}: Screen Recording already granted — frames will include pixels + OCR.`);
+    return;
+  }
+  console.log(
+    `\nOn ${name}'s screen, grant Screen Recording to SlabMenubar:\n` +
+      `  1. A system prompt may already be showing — click "Allow".\n` +
+      `  2. Otherwise: System Settings → Privacy & Security → Screen & System\n` +
+      `     Audio Recording → enable "SlabMenubar".\n` +
+      `  3. Re-run:  frame ${name}   (the app picks up the grant; no restart needed)\n` +
+      `(Accessibility is already granted to the app, so the AX tree needs no toggle.)`,
+  );
+}
+
+function list() {
+  const machines = loadMachines();
+  const names = Object.keys(machines);
+  if (!names.length) {
+    console.log(`(no machines in ${CONFIG_PATH})`);
+    return;
+  }
+  for (const n of names) console.log(`${n}\t-> ssh ${sshHostFor(n, machines)}`);
+}
+
+// ---- arg parse ----
+const argv = process.argv.slice(2);
+const cmd = argv[0];
+const flag = (f) => argv.includes(f);
+const opt = (f) => {
+  const i = argv.indexOf(f);
+  return i >= 0 ? argv[i + 1] : undefined;
+};
+
+if (!cmd || cmd === "-h" || cmd === "--help") {
+  console.log(
+    "frame — capture a rich frame (pixels + OCR + AX + state) of a remote Mac\n\n" +
+      "  frame <machine> [--no-ocr] [--out file.jpg] [--json]\n" +
+      "  frame doctor [machine]      per-machine daemon + permission status\n" +
+      "  frame setup <machine>       trigger + guide the one-time Screen Recording grant\n" +
+      "  frame list                  registered machines\n",
+  );
+  process.exit(0);
+}
+if (cmd === "doctor") doctor(argv[1]);
+else if (cmd === "setup") setup(argv[1]);
+else if (cmd === "list") list();
+else captureFrame(cmd, { noOCR: flag("--no-ocr"), out: opt("--out"), json: flag("--json") });
diff --git a/slab/menubar-swift/Sources/SlabMenubar/AppDelegate.swift b/slab/menubar-swift/Sources/SlabMenubar/AppDelegate.swift
index f36ce8589..52b0123ca 100644
--- a/slab/menubar-swift/Sources/SlabMenubar/AppDelegate.swift
+++ b/slab/menubar-swift/Sources/SlabMenubar/AppDelegate.swift
@@ -148,6 +148,12 @@ final class AppDelegate: NSObject, NSApplicationDelegate, NSMenuDelegate {
             selector: #selector(activeSpaceDidChange),
             name: NSWorkspace.activeSpaceDidChangeNotification,
             object: nil)
+
+        // Fleet "frame" capture: watch for an SSH-dropped request file and
+        // answer with pixels + OCR + AX + window state. Only spins a file
+        // watcher — never touches ScreenCaptureKit until a frame is actually
+        // requested, so no Screen Recording prompt at launch (lazy grant).
+        FrameCapture.shared.start()
     }
 
     func applicationWillTerminate(_ notification: Notification) {
diff --git a/slab/menubar-swift/Sources/SlabMenubar/FrameCapture.swift b/slab/menubar-swift/Sources/SlabMenubar/FrameCapture.swift
new file mode 100644
index 000000000..e728340a3
--- /dev/null
+++ b/slab/menubar-swift/Sources/SlabMenubar/FrameCapture.swift
@@ -0,0 +1,212 @@
+import AppKit
+import ApplicationServices
+import CoreGraphics
+import ScreenCaptureKit
+import Vision
+
+/// A "frame" of this machine for fleet automation: pixels (a downscaled
+/// thumbnail) + OCR'd text with click coordinates + the Accessibility element
+/// tree + window/cursor/frontmost state, packed into one JSON envelope. The
+/// `frame` CLI on the controlling Mac pokes a request file over SSH; this
+/// watcher (running inside the menubar app, which already holds Accessibility
+/// trust and lives in the GUI session) produces the envelope. It is the
+/// native-capture complement to `puppet` (which only sees the browser via CDP):
+/// `frame` observes, `puppet` acts.
+///
+/// PERMISSIONS ARE LAZY. `start()` only spins a file-watch timer — it never
+/// touches ScreenCaptureKit, so no Screen Recording prompt appears at launch.
+/// The first *actual* frame request is what calls ScreenCaptureKit, which is
+/// when macOS surfaces the grant (auto-approves on some hosts, prompts on
+/// others). If capture fails for lack of permission we say so in the envelope
+/// (`capture: "permission_needed"`) so the CLI can guide the one-time grant.
+/// Accessibility is already granted to the app, so the AX tree is free.
+final class FrameCapture {
+    static let shared = FrameCapture()
+    private let queue = DispatchQueue(label: "computer.slab.frame", qos: .userInitiated)
+    private var timer: DispatchSourceTimer?
+    private let fm = FileManager.default
+
+    func start() {
+        let dir = (Paths.frameReq as NSString).deletingLastPathComponent
+        try? fm.createDirectory(atPath: dir, withIntermediateDirectories: true)
+        let t = DispatchSource.makeTimerSource(queue: queue)
+        t.schedule(deadline: .now() + .milliseconds(50), repeating: .milliseconds(30))
+        t.setEventHandler { [weak self] in self?.tick() }
+        t.resume()
+        timer = t
+        // No ScreenCaptureKit call here — see the type doc: permissions are lazy.
+    }
+
+    private func tick() {
+        guard fm.fileExists(atPath: Paths.frameReq) else { return }
+        let mode = (try? String(contentsOfFile: Paths.frameReq, encoding: .utf8)) ?? ""
+        try? fm.removeItem(atPath: Paths.frameReq)
+        try? fm.removeItem(atPath: Paths.frameDone)
+        produce(noOCR: mode.contains("noocr"))
+        fm.createFile(atPath: Paths.frameDone, contents: nil)
+    }
+
+    // MARK: - capture (in-process; no screencapture subprocess → no launchd throttle)
+
+    private func captureDisplay() -> CGImage? {
+        guard #available(macOS 14.0, *) else { return nil }
+        let sem = DispatchSemaphore(value: 0)
+        var img: CGImage?
+        Task {
+            defer { sem.signal() }
+            guard let content = try? await SCShareableContent.excludingDesktopWindows(
+                    false, onScreenWindowsOnly: true),
+                  let display = content.displays.first else { return }
+            let filter = SCContentFilter(display: display, excludingWindows: [])
+            let cfg = SCStreamConfiguration()
+            cfg.width = display.width
+            cfg.height = display.height
+            cfg.showsCursor = true
+            img = try? await SCScreenshotManager.captureImage(contentFilter: filter, configuration: cfg)
+        }
+        sem.wait()
+        return img
+    }
+
+    // MARK: - OCR (text + click-center coords, in logical points)
+
+    private func ocr(_ cg: CGImage, scale: Double) -> [[String: Any]] {
+        let req = VNRecognizeTextRequest()
+        req.recognitionLevel = .accurate
+        req.usesLanguageCorrection = false
+        try? VNImageRequestHandler(cgImage: cg, options: [:]).perform([req])
+        let W = Double(cg.width), H = Double(cg.height)
+        var out: [[String: Any]] = []
+        for obs in (req.results ?? []) {
+            guard let c = obs.topCandidates(1).first else { continue }
+            let bb = obs.boundingBox
+            let x = bb.minX * W / scale, y = (1 - bb.maxY) * H / scale
+            let w = bb.width * W / scale, h = bb.height * H / scale
+            out.append(["t": c.string, "cx": Int(x + w / 2), "cy": Int(y + h / 2),
+                        "r": [Int(x), Int(y), Int(w), Int(h)]])
+        }
+        return out
+    }
+
+    // MARK: - Accessibility element tree of the frontmost app (trust already held)
+
+    private func axAttr(_ el: AXUIElement, _ k: String) -> AnyObject? {
+        var v: AnyObject?
+        return AXUIElementCopyAttributeValue(el, k as CFString, &v) == .success ? v : nil
+    }
+    private func axPoint(_ el: AXUIElement) -> (CGFloat, CGFloat)? {
+        guard let v = axAttr(el, "AXPosition") else { return nil }
+        var p = CGPoint.zero; AXValueGetValue(v as! AXValue, .cgPoint, &p); return (p.x, p.y)
+    }
+    private func axSize(_ el: AXUIElement) -> (CGFloat, CGFloat)? {
+        guard let v = axAttr(el, "AXSize") else { return nil }
+        var s = CGSize.zero; AXValueGetValue(v as! AXValue, .cgSize, &s); return (s.width, s.height)
+    }
+    private func axTree() -> [String: Any] {
+        guard AXIsProcessTrusted() else { return ["trusted": false, "elements": []] }
+        guard let front = NSWorkspace.shared.frontmostApplication else {
+            return ["trusted": true, "elements": []]
+        }
+        let app = AXUIElementCreateApplication(front.processIdentifier)
+        let want: Set<String> = ["AXButton", "AXMenuItem", "AXTextField", "AXTextArea",
+            "AXCheckBox", "AXRadioButton", "AXLink", "AXPopUpButton", "AXMenuButton",
+            "AXSlider", "AXComboBox", "AXToggle"]
+        var out: [[String: Any]] = []
+        var count = 0
+        func walk(_ el: AXUIElement, _ depth: Int) {
+            if count > 2000 || depth > 28 { return }
+            count += 1
+            let role = (axAttr(el, "AXRole") as? String) ?? ""
+            if want.contains(role), let (x, y) = axPoint(el), let (w, h) = axSize(el), w > 0, h > 0 {
+                let title = (axAttr(el, "AXTitle") as? String)
+                    ?? (axAttr(el, "AXValue") as? String)
+                    ?? (axAttr(el, "AXDescription") as? String) ?? ""
+                var acts: CFArray?
+                AXUIElementCopyActionNames(el, &acts)
+                out.append(["role": role, "title": String(title.prefix(80)),
+                    "cx": Int(x + w / 2), "cy": Int(y + h / 2),
+                    "r": [Int(x), Int(y), Int(w), Int(h)],
+                    "actions": (acts as? [String]) ?? []])
+            }
+            if let kids = axAttr(el, "AXChildren") as? [AXUIElement] {
+                for k in kids { walk(k, depth + 1) }
+            }
+        }
+        walk(app, 0)
+        return ["trusted": true, "app": front.localizedName ?? "?", "elements": out]
+    }
+
+    // MARK: - meta (screen geometry/scale, cursor, frontmost, windows)
+
+    private func meta() -> [String: Any] {
+        var r: [String: Any] = [:]
+        let scale = NSScreen.main?.backingScaleFactor ?? 1
+        if let s = NSScreen.main {
+            r["screen"] = ["w": Int(s.frame.width), "h": Int(s.frame.height), "scale": scale]
+        }
+        let m = NSEvent.mouseLocation
+        let sh = NSScreen.main?.frame.height ?? 0
+        r["cursor"] = ["x": Int(m.x), "y": Int(sh - m.y)]   // flip to top-left origin
+        if let f = NSWorkspace.shared.frontmostApplication {
+            r["frontmost"] = ["app": f.localizedName ?? "?",
+                              "bundle": f.bundleIdentifier ?? "?", "pid": f.processIdentifier]
+        }
+        var wins: [[String: Any]] = []
+        if let info = CGWindowListCopyWindowInfo(
+                [.optionOnScreenOnly, .excludeDesktopElements], kCGNullWindowID) as? [[String: Any]] {
+            for w in info {
+                guard let layer = w[kCGWindowLayer as String] as? Int, layer == 0 else { continue }
+                let b = w[kCGWindowBounds as String] as? [String: Any] ?? [:]
+                wins.append(["app": w[kCGWindowOwnerName as String] as? String ?? "?",
+                             "title": w[kCGWindowName as String] as? String ?? "",
+                             "x": b["X"] ?? 0, "y": b["Y"] ?? 0,
+                             "w": b["Width"] ?? 0, "h": b["Height"] ?? 0])
+            }
+        }
+        r["windows"] = wins
+        return r
+    }
+
+    // MARK: - thumbnail (downscale to 1568px — what a vision model downsamples to anyway)
+
+    private func thumbJPEG(_ cg: CGImage, maxWidth: Int) -> Data? {
+        let s = Double(maxWidth) / Double(cg.width)
+        let w = maxWidth, h = max(1, Int(Double(cg.height) * s))
+        guard let rep = NSBitmapImageRep(bitmapDataPlanes: nil, pixelsWide: w, pixelsHigh: h,
+            bitsPerSample: 8, samplesPerPixel: 4, hasAlpha: true, isPlanar: false,
+            colorSpaceName: .deviceRGB, bytesPerRow: 0, bitsPerPixel: 0),
+            let ctx = NSGraphicsContext(bitmapImageRep: rep) else { return nil }
+        NSGraphicsContext.saveGraphicsState()
+        NSGraphicsContext.current = ctx
+        ctx.cgContext.interpolationQuality = .high
+        ctx.cgContext.draw(cg, in: CGRect(x: 0, y: 0, width: w, height: h))
+        ctx.flushGraphics()
+        NSGraphicsContext.restoreGraphicsState()
+        return rep.representation(using: .jpeg, properties: [.compressionFactor: 0.6])
+    }
+
+    // MARK: - assemble + write the envelope
+
+    private func produce(noOCR: Bool) {
+        var env: [String: Any] = [:]
+        let mt = meta()
+        env["meta"] = mt
+        env["ax"] = axTree()
+        let scale = ((mt["screen"] as? [String: Any])?["scale"] as? CGFloat).map(Double.init) ?? 1.0
+        if let cg = captureDisplay() {
+            env["ocr"] = noOCR ? [] : ocr(cg, scale: scale)
+            if let jpg = thumbJPEG(cg, maxWidth: 1568) {
+                env["thumb_jpg_b64"] = jpg.base64EncodedString()
+            }
+            env["capture"] = "ok"
+        } else {
+            env["ocr"] = []
+            // Either Screen Recording isn't granted yet, or this is < macOS 14.
+            env["capture"] = "permission_needed"
+            env["permission"] = "screen_recording"
+        }
+        if let d = try? JSONSerialization.data(withJSONObject: env, options: []) {
+            try? d.write(to: URL(fileURLWithPath: Paths.frameOut))
+        }
+    }
+}
diff --git a/slab/menubar-swift/Sources/SlabMenubar/Paths.swift b/slab/menubar-swift/Sources/SlabMenubar/Paths.swift
index 9f061ab0f..a00a38e79 100644
--- a/slab/menubar-swift/Sources/SlabMenubar/Paths.swift
+++ b/slab/menubar-swift/Sources/SlabMenubar/Paths.swift
@@ -75,6 +75,13 @@ enum Paths {
     static var soundsDir: String { "\(slabHome)/sounds" }
     static var lidLog: String { "\(slabHome)/logs/lidalive.log" }
 
+    /// `frame` capture handshake (see FrameCapture.swift). The CLI on the
+    /// controlling Mac drops `frame.req` over SSH; the menubar app produces
+    /// `frame.out.json` (pixels + OCR + AX + meta) and touches `frame.done`.
+    static var frameReq: String { "\(slabHome)/state/frame.req" }
+    static var frameOut: String { "\(slabHome)/state/frame.out.json" }
+    static var frameDone: String { "\(slabHome)/state/frame.done" }
+
     static var mailDir: String {
         ProcessInfo.processInfo.environment["AC_MAIL_MAILDIR"] ?? "\(home)/.mail-all"
     }
diff --git a/slab/menubar-swift/install.sh b/slab/menubar-swift/install.sh
index add0b704e..02545be49 100755
--- a/slab/menubar-swift/install.sh
+++ b/slab/menubar-swift/install.sh
@@ -41,65 +41,94 @@ command -v swift >/dev/null 2>&1 || {
 }
 
 SIGN_CN="Slab Menubar Self-Signed"
-SIGN_KEYCHAIN="${HOME}/Library/Keychains/login.keychain-db"
+# A DEDICATED keychain, not login.keychain. Over SSH the login keychain is
+# locked and can't be unlocked without user interaction ("User interaction is
+# not allowed"), so identity import there fails on the headless minis. A
+# dedicated keychain with a known passphrase unlocks non-interactively. The
+# passphrase guards only a local self-signed code-signing cert (no real
+# secret), so a constant default is fine; override with SLAB_SIGN_KC_PASS.
+SIGN_KEYCHAIN="${HOME}/Library/Keychains/slab-signing.keychain-db"
+SIGN_KC_PASS="${SLAB_SIGN_KC_PASS:-slab-signing}"
 
-ensure_signing_identity() {
-    # find-certificate works for self-signed certs even if untrusted, unlike
-    # `find-identity -p codesigning` which filters by trust.
-    if security find-certificate -c "${SIGN_CN}" "${SIGN_KEYCHAIN}" >/dev/null 2>&1; then
+# Sign an app bundle with the stable identity. codesign needs a real Security
+# session to reach the private key; over SSH (notty) it returns
+# errSecInternalComponent, so a direct sign only works when install.sh runs in
+# a GUI Terminal. When it fails we run the exact same sign INSIDE the logged-in
+# Aqua session via a one-shot launchd job — the same gui-bootstrap trick the
+# frame capture uses to reach the WindowServer. Returns 1 if neither path
+# produces a "${SIGN_CN}" signature (caller then falls back to ad-hoc).
+codesign_app() {
+    local app="$1"
+    # Only try a direct sign when we're already in an Aqua session (install.sh
+    # run from a GUI Terminal). Over SSH a direct sign fails with
+    # errSecInternalComponent AND can pop a keychain dialog on the machine's
+    # screen, so skip straight to the gui-bootstrap path below.
+    if [ -n "${SECURITYSESSIONID:-}" ] && \
+       codesign --force --deep --sign "${SIGN_CN}" \
+        --identifier computer.slab.menubar "${app}" >/dev/null 2>&1; then
         return 0
     fi
-    say "creating self-signed code signing identity '${SIGN_CN}' (one-time)"
-    local tmpdir
-    tmpdir="$(mktemp -d)"
-    cat > "${tmpdir}/openssl.cnf" <<EOF
-[req]
-distinguished_name = dn
-prompt = no
-[dn]
-CN = ${SIGN_CN}
-[v3_ext]
-keyUsage = critical,digitalSignature
-extendedKeyUsage = critical,codeSigning
-basicConstraints = critical,CA:FALSE
-EOF
-    if ! openssl req -x509 -newkey rsa:2048 -nodes -days 36500 \
-        -keyout "${tmpdir}/key.pem" \
-        -out "${tmpdir}/cert.pem" \
-        -config "${tmpdir}/openssl.cnf" \
-        -extensions v3_ext >/dev/null 2>&1; then
-        warn "openssl req failed; will fall back to ad-hoc signing"
-        rm -rf "${tmpdir}"
-        return 1
-    fi
-    # Apple's Security framework PKCS12 importer needs SHA1-MAC + 3DES PBE,
-    # AND a non-empty password (empty pass triggers MAC verification quirks
-    # with OpenSSL 3 even with the legacy MAC algorithm).
-    local p12pass="slab-import-$$"
-    if ! openssl pkcs12 -export \
-        -macalg sha1 -keypbe PBE-SHA1-3DES -certpbe PBE-SHA1-3DES \
-        -out "${tmpdir}/bundle.p12" \
-        -inkey "${tmpdir}/key.pem" \
-        -in "${tmpdir}/cert.pem" \
-        -name "${SIGN_CN}" \
-        -passout "pass:${p12pass}" >/dev/null 2>&1; then
-        warn "pkcs12 export failed; will fall back to ad-hoc signing"
-        rm -rf "${tmpdir}"
-        return 1
+    local uid label script plist log i
+    uid="$(id -u)"; label="ac.slabsign.$$"
+    # Use shared /tmp, NOT mktemp: over SSH mktemp lands in the ssh session's
+    # private $TMPDIR (/var/folders/…), which the GUI-session launchd job can't
+    # read — so the helper would never run. /tmp is visible to both sessions.
+    script="/tmp/slab-sign.$$.sh"; plist="/tmp/slab-sign.$$.plist"; log="/tmp/slab-sign.$$.log"
+    # Self-contained recipe run IN the Aqua session: create the dedicated
+    # keychain if missing, create the identity ONCE (find-certificate guard →
+    # the cert is reused on every later rebuild, so grants stay bound), set the
+    # partition list (no GUI prompt), keep it on the search list, then sign.
+    cat > "${script}" <<EOS
+#!/bin/bash
+KC='${SIGN_KEYCHAIN}'; PASS='${SIGN_KC_PASS}'; CN='${SIGN_CN}'; APP='${app}'
+exec > '${log}' 2>&1
+[ -f "\$KC" ] || security create-keychain -p "\$PASS" "\$KC"
+security set-keychain-settings "\$KC"
+security unlock-keychain -p "\$PASS" "\$KC"
+if ! security find-certificate -c "\$CN" "\$KC" >/dev/null 2>&1; then
+  T="\$(mktemp -d)"
+  printf '%s\n' '[req]' 'distinguished_name=dn' 'prompt=no' '[dn]' "CN=\$CN" \
+    '[v3]' 'keyUsage=critical,digitalSignature' 'extendedKeyUsage=critical,codeSigning' \
+    'basicConstraints=critical,CA:FALSE' > "\$T/o.cnf"
+  openssl req -x509 -newkey rsa:2048 -nodes -days 36500 -keyout "\$T/k.pem" -out "\$T/c.pem" -config "\$T/o.cnf" -extensions v3 >/dev/null 2>&1
+  openssl pkcs12 -export -macalg sha1 -keypbe PBE-SHA1-3DES -certpbe PBE-SHA1-3DES -out "\$T/b.p12" -inkey "\$T/k.pem" -in "\$T/c.pem" -name "\$CN" -passout pass:p12 >/dev/null 2>&1
+  security import "\$T/b.p12" -k "\$KC" -P p12 -T /usr/bin/codesign -T /usr/bin/security >/dev/null 2>&1
+  rm -rf "\$T"
+fi
+security set-key-partition-list -S apple-tool:,apple: -s -k "\$PASS" "\$KC" >/dev/null 2>&1 || true
+CUR="\$(security list-keychains -d user | sed -e 's/\"//g' -e 's/^ *//')"
+case "\$CUR" in *slab-signing*) : ;; *) security list-keychains -d user -s \$CUR "\$KC" ;; esac
+codesign --force --deep --sign "\$CN" --identifier computer.slab.menubar "\$APP"
+echo "rc=\$?"
+EOS
+    cat > "${plist}" <<EOP
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0"><dict><key>Label</key><string>${label}</string>
+<key>ProgramArguments</key><array><string>/bin/bash</string><string>${script}</string></array>
+<key>RunAtLoad</key><true/></dict></plist>
+EOP
+    launchctl bootout "gui/${uid}/${label}" 2>/dev/null || true
+    if launchctl bootstrap "gui/${uid}" "${plist}" 2>/dev/null; then
+        # Gate on the helper's own completion marker (the rc= line it echoes
+        # last) rather than a fixed clock, so a job whose *start* launchd
+        # throttles still gets waited out instead of us racing it to an ad-hoc
+        # fallback. ~60s ceiling.
+        for i in $(seq 1 240); do
+            grep -q '^rc=' "${log}" 2>/dev/null && break
+            sleep 0.25
+        done
+        launchctl bootout "gui/${uid}/${label}" 2>/dev/null || true
     fi
-    if ! security import "${tmpdir}/bundle.p12" \
-        -k "${SIGN_KEYCHAIN}" \
-        -P "${p12pass}" \
-        -T /usr/bin/codesign \
-        -T /usr/bin/security >/dev/null 2>&1; then
-        warn "keychain import failed; will fall back to ad-hoc signing"
-        rm -rf "${tmpdir}"
-        return 1
+    rm -f "${script}" "${plist}"
+    if codesign -dvv "${app}" 2>&1 | grep -q "Authority=${SIGN_CN}"; then
+        rm -f "${log}"
+        return 0
     fi
-    rm -rf "${tmpdir}"
-    ok "code signing identity created"
-    warn "first signing may prompt for keychain access — click 'Always Allow'"
-    return 0
+    warn "stable-sign helper did not produce a '${SIGN_CN}' signature; last output:"
+    tail -4 "${log}" 2>/dev/null | sed 's/^/    /' >&2 || true
+    rm -f "${log}"
+    return 1
 }
 
 # Provision iTerm2 profiles for the per-session tiled topic wallpapers: every
@@ -197,15 +226,11 @@ fi
 # Accessibility grant survives rebuilds (ad-hoc embeds the cdhash in the
 # designated requirement, which changes every build).
 SIGN_OK=0
-if ensure_signing_identity; then
-    if codesign --force --deep --sign "${SIGN_CN}" \
-        --identifier computer.slab.menubar \
-        "${APP_DIR}" >/dev/null 2>&1; then
-        SIGN_OK=1
-        ok "signed with '${SIGN_CN}' (stable identity — TCC grant should persist)"
-    else
-        warn "codesign with '${SIGN_CN}' failed; falling back to ad-hoc"
-    fi
+if codesign_app "${APP_DIR}"; then
+    SIGN_OK=1
+    ok "signed with '${SIGN_CN}' (stable identity — TCC grants persist across rebuilds)"
+else
+    warn "stable signing unavailable; using ad-hoc (TCC grants reset each rebuild)"
 fi
 if [[ "${SIGN_OK}" -eq 0 ]]; then
     codesign --force --deep --sign - \
-- 
2.51.2


From f64511ed249f1601a0e24c96ef03d61b586d0d82 Mon Sep 17 00:00:00 2001
From: "prompt.ac/@jeffrey" <mail@aesthetic.computer>
Date: Wed, 17 Jun 2026 15:12:02 -0700
Subject: [PATCH 05/13] slab menubar install.sh: harden stable code-signing
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The stable-sign path was failing on machines with a legacy same-CN cert in
login.keychain (blueberry) and falling back to ad-hoc — which resets the TCC
Screen-Recording/Accessibility grants on every rebuild. Three root causes:

1. Ambiguous identity. codesign --sign "<CN>" errors 'ambiguous (matches … in
   login.keychain and … in slab-signing.keychain)' when a dup exists. Now sign
   by the cert's SHA-1 HASH read from the dedicated slab-signing keychain
   specifically (new slab_sign_hash helper + hash lookup in the gui-bootstrap
   helper), so the right cert is always picked. find-certificate -c keeps
   guarding existence.

2. Spurious ad-hoc fallback from a SIGPIPE/pipefail interaction. The post-sign
   verify piped 'codesign -dvv' into 'grep -q'; under set -o pipefail grep -q
   closes the pipe on first match, codesign takes SIGPIPE and exits non-zero, so
   the pipeline reported failure even when the signature matched. Capture to a
   var and pattern-match instead.

3. Removed a kickstart -k I briefly added — it double-ran the gui job and the
   two runs raced the same bundle. RunAtLoad starts it once; the completion-
   marker wait is sufficient. Pre-create the log so the marker gate polls from
   t=0; make set-keychain-settings best-effort.

Verified on blueberry: adhoc -> Authority=Slab Menubar Self-Signed across three
consecutive install.sh runs, same cert SHA-1 each time (idempotent), with the
login.keychain dup still present.
---
 slab/menubar-swift/install.sh | 54 +++++++++++++++++++++++++++++------
 1 file changed, 46 insertions(+), 8 deletions(-)

diff --git a/slab/menubar-swift/install.sh b/slab/menubar-swift/install.sh
index 02545be49..1573bd1ff 100755
--- a/slab/menubar-swift/install.sh
+++ b/slab/menubar-swift/install.sh
@@ -50,6 +50,17 @@ SIGN_CN="Slab Menubar Self-Signed"
 SIGN_KEYCHAIN="${HOME}/Library/Keychains/slab-signing.keychain-db"
 SIGN_KC_PASS="${SLAB_SIGN_KC_PASS:-slab-signing}"
 
+# SHA-1 hash of the stable cert in the DEDICATED keychain, or "" if it doesn't
+# exist yet. We sign by this hash, not by CN, because a same-CN cert may also
+# exist in login.keychain (legacy installs) — signing by CN is then "ambiguous"
+# and fails. Reading from "${SIGN_KEYCHAIN}" explicitly guarantees we get the
+# right cert even when a duplicate lives elsewhere.
+slab_sign_hash() {
+    [ -f "${SIGN_KEYCHAIN}" ] || return 0
+    security find-certificate -Z -c "${SIGN_CN}" "${SIGN_KEYCHAIN}" 2>/dev/null \
+        | awk '/SHA-1 hash:/{print $3; exit}'
+}
+
 # Sign an app bundle with the stable identity. codesign needs a real Security
 # session to reach the private key; over SSH (notty) it returns
 # errSecInternalComponent, so a direct sign only works when install.sh runs in
@@ -59,12 +70,22 @@ SIGN_KC_PASS="${SLAB_SIGN_KC_PASS:-slab-signing}"
 # produces a "${SIGN_CN}" signature (caller then falls back to ad-hoc).
 codesign_app() {
     local app="$1"
+    # Sign by the cert's SHA-1 HASH, never by CN. If a same-CN cert also lives in
+    # login.keychain (an older install.sh left one there on some machines),
+    # codesign --sign "<CN>" errors out "ambiguous (matches … in login.keychain
+    # and … in slab-signing.keychain)". The hash is unique to the cert in the
+    # dedicated keychain, so it always picks the right one. We can only compute
+    # the hash once the keychain+cert exist; the direct-sign shortcut below is
+    # therefore best-effort and silently no-ops on the first run (no cert yet),
+    # falling through to the gui-bootstrap path which creates it.
+    local hash=""
+    hash="$(slab_sign_hash)"
     # Only try a direct sign when we're already in an Aqua session (install.sh
-    # run from a GUI Terminal). Over SSH a direct sign fails with
-    # errSecInternalComponent AND can pop a keychain dialog on the machine's
+    # run from a GUI Terminal) AND we have a hash. Over SSH a direct sign fails
+    # with errSecInternalComponent AND can pop a keychain dialog on the machine's
     # screen, so skip straight to the gui-bootstrap path below.
-    if [ -n "${SECURITYSESSIONID:-}" ] && \
-       codesign --force --deep --sign "${SIGN_CN}" \
+    if [ -n "${SECURITYSESSIONID:-}" ] && [ -n "${hash}" ] && \
+       codesign --force --deep --sign "${hash}" \
         --identifier computer.slab.menubar "${app}" >/dev/null 2>&1; then
         return 0
     fi
@@ -83,7 +104,7 @@ codesign_app() {
 KC='${SIGN_KEYCHAIN}'; PASS='${SIGN_KC_PASS}'; CN='${SIGN_CN}'; APP='${app}'
 exec > '${log}' 2>&1
 [ -f "\$KC" ] || security create-keychain -p "\$PASS" "\$KC"
-security set-keychain-settings "\$KC"
+security set-keychain-settings "\$KC" 2>/dev/null || true  # best-effort: drop lock-timeout
 security unlock-keychain -p "\$PASS" "\$KC"
 if ! security find-certificate -c "\$CN" "\$KC" >/dev/null 2>&1; then
   T="\$(mktemp -d)"
@@ -98,7 +119,10 @@ fi
 security set-key-partition-list -S apple-tool:,apple: -s -k "\$PASS" "\$KC" >/dev/null 2>&1 || true
 CUR="\$(security list-keychains -d user | sed -e 's/\"//g' -e 's/^ *//')"
 case "\$CUR" in *slab-signing*) : ;; *) security list-keychains -d user -s \$CUR "\$KC" ;; esac
-codesign --force --deep --sign "\$CN" --identifier computer.slab.menubar "\$APP"
+# Sign by the cert's SHA-1 hash from THIS keychain, never by CN — a legacy
+# same-CN cert in login.keychain would make a sign-by-CN "ambiguous" and fail.
+HASH="\$(security find-certificate -Z -c "\$CN" "\$KC" 2>/dev/null | awk '/SHA-1 hash:/{print \$3; exit}')"
+codesign --force --deep --sign "\$HASH" --identifier computer.slab.menubar "\$APP"
 echo "rc=\$?"
 EOS
     cat > "${plist}" <<EOP
@@ -108,12 +132,19 @@ EOS
 <key>ProgramArguments</key><array><string>/bin/bash</string><string>${script}</string></array>
 <key>RunAtLoad</key><true/></dict></plist>
 EOP
+    : > "${log}"  # pre-create so the marker gate has a file to poll from t=0
     launchctl bootout "gui/${uid}/${label}" 2>/dev/null || true
     if launchctl bootstrap "gui/${uid}" "${plist}" 2>/dev/null; then
+        # RunAtLoad starts the job exactly once. Do NOT kickstart -k it: that
+        # forces a SECOND run that races the first (both re-sign the same
+        # bundle), and our verify can land while the second run has the
+        # signature half-written → a spurious ad-hoc fallback. Just wait.
+        #
         # Gate on the helper's own completion marker (the rc= line it echoes
         # last) rather than a fixed clock, so a job whose *start* launchd
         # throttles still gets waited out instead of us racing it to an ad-hoc
-        # fallback. ~60s ceiling.
+        # fallback. The helper script stays on disk until the marker appears (we
+        # never delete it mid-run). ~60s ceiling.
         for i in $(seq 1 240); do
             grep -q '^rc=' "${log}" 2>/dev/null && break
             sleep 0.25
@@ -121,7 +152,14 @@ EOP
         launchctl bootout "gui/${uid}/${label}" 2>/dev/null || true
     fi
     rm -f "${script}" "${plist}"
-    if codesign -dvv "${app}" 2>&1 | grep -q "Authority=${SIGN_CN}"; then
+    # Verify the bundle now carries the stable authority. Capture first, then
+    # grep a string — do NOT pipe `codesign -dvv` into `grep -q`: under
+    # `set -o pipefail`, grep -q closes the pipe on first match, codesign takes
+    # SIGPIPE and exits non-zero, and the whole pipeline reports failure even
+    # though the signature matched (this caused a spurious ad-hoc fallback).
+    local sig
+    sig="$(codesign -dvv "${app}" 2>&1)"
+    if [[ "${sig}" == *"Authority=${SIGN_CN}"* ]]; then
         rm -f "${log}"
         return 0
     fi
-- 
2.51.2


From ac10ccc0bf3d5bdb8a50a6376e9d8b5e6265d284 Mon Sep 17 00:00:00 2001
From: "prompt.ac/@jeffrey" <mail@aesthetic.computer>
Date: Wed, 17 Jun 2026 15:37:00 -0700
Subject: [PATCH 06/13] slab/frame: local-machine support (controller captures
 itself, no ssh) + run remote cmds via 'bash -s' so fish-login machines
 (blueberry) work

---
 slab/bin/frame.mjs | 57 +++++++++++++++++++++++++++++++---------------
 1 file changed, 39 insertions(+), 18 deletions(-)

diff --git a/slab/bin/frame.mjs b/slab/bin/frame.mjs
index 4901b84bd..94f899eef 100755
--- a/slab/bin/frame.mjs
+++ b/slab/bin/frame.mjs
@@ -35,12 +35,20 @@ const APP_BUNDLE = "computer.slab.menubar";
 const REMOTE_STATE = "~/.local/share/slab/state"; // expanded by the remote shell
 
 function loadMachines() {
-  if (!existsSync(CONFIG_PATH)) {
-    console.error(`no config at ${CONFIG_PATH} — register machines (puppet config)`);
-    process.exit(1);
+  let machines = {};
+  if (existsSync(CONFIG_PATH)) {
+    machines = JSON.parse(readFileSync(CONFIG_PATH, "utf8")).machines || {};
   }
-  const cfg = JSON.parse(readFileSync(CONFIG_PATH, "utf8"));
-  return cfg.machines || {};
+  // The controller captures itself with no ssh (ssh-to-self is host-key
+  // fragile). Expose it under its LocalHostName as a `local: true` machine —
+  // synthetic, so it never has to live in puppet.json (which puppet's daemon
+  // also reads and would try to CDP-connect).
+  let self = "local";
+  try {
+    self = execFileSync("scutil", ["--get", "LocalHostName"], { encoding: "utf8" }).trim() || "local";
+  } catch {}
+  if (!machines[self]) machines[self] = { local: true };
+  return machines;
 }
 
 function sshHostFor(name, machines) {
@@ -48,6 +56,10 @@ function sshHostFor(name, machines) {
 }
 
 // One ssh invocation with a warm multiplexed master so repeated frames are fast.
+// The command is fed to `bash -s` over stdin, NOT passed as an argument: the
+// remote runs the login shell, and some machines use fish (blueberry) which
+// can't parse the bash `for/$()/done` syntax. `bash -s` + stdin is shell-
+// agnostic and sidesteps all quoting.
 function ssh(host, remoteCmd, { timeoutMs = 15000 } = {}) {
   const cp = join(HOME, ".ssh", `cm-${host}`);
   return execFileSync(
@@ -58,19 +70,30 @@ function ssh(host, remoteCmd, { timeoutMs = 15000 } = {}) {
       "-o", "ControlPersist=300",
       "-o", "BatchMode=yes",
       host,
-      remoteCmd,
+      "bash -s",
     ],
-    { encoding: "utf8", timeout: timeoutMs, maxBuffer: 64 * 1024 * 1024 },
+    { input: remoteCmd, encoding: "utf8", timeout: timeoutMs, maxBuffer: 64 * 1024 * 1024 },
   );
 }
 
+// Run a shell command on a machine — locally (no ssh) when it's flagged
+// "local" in the registry (e.g. neo, the controller, capturing its own screen;
+// `ssh localhost` is awkward/host-key-fragile), otherwise over the warm master.
+function runOn(name, machines, cmd, { timeoutMs = 15000 } = {}) {
+  if (machines[name]?.local) {
+    return execFileSync("bash", ["-c", cmd], {
+      encoding: "utf8", timeout: timeoutMs, maxBuffer: 64 * 1024 * 1024,
+    });
+  }
+  return ssh(sshHostFor(name, machines), cmd, { timeoutMs });
+}
+
 function captureFrame(name, { noOCR = false, out, json = false } = {}) {
   const machines = loadMachines();
   if (!machines[name]) {
     console.error(`unknown machine "${name}" — known: ${Object.keys(machines).join(", ") || "(none)"}`);
     process.exit(1);
   }
-  const host = sshHostFor(name, machines);
   const mode = noOCR ? "noocr" : "full";
   // Drop the request, wait for the daemon's done marker (≤4s), emit the envelope.
   const remote =
@@ -80,9 +103,9 @@ function captureFrame(name, { noOCR = false, out, json = false } = {}) {
     `cat "$d/frame.out.json" 2>/dev/null`;
   let raw;
   try {
-    raw = ssh(host, remote);
+    raw = runOn(name, machines, remote);
   } catch (e) {
-    console.error(`ssh ${host} failed: ${e.message.split("\n")[0]}`);
+    console.error(`${name} unreachable: ${e.message.split("\n")[0]}`);
     process.exit(1);
   }
   let env;
@@ -118,14 +141,14 @@ function captureFrame(name, { noOCR = false, out, json = false } = {}) {
   console.log(JSON.stringify(rest, null, 2));
 }
 
-// Read a TCC grant state over ssh (system DB is world-readable here).
-function srGrant(host) {
+// Read a TCC grant state (system DB is world-readable here).
+function srGrant(name, machines) {
   try {
     const q =
       `sqlite3 "/Library/Application Support/com.apple.TCC/TCC.db" ` +
       `"select auth_value from access where service='kTCCServiceScreenCapture' ` +
       `and client='${APP_BUNDLE}';" 2>/dev/null`;
-    return ssh(host, q).trim();
+    return runOn(name, machines, q).trim();
   } catch {
     return "";
   }
@@ -139,15 +162,14 @@ function doctor(name) {
     process.exit(1);
   }
   for (const n of names) {
-    const host = sshHostFor(n, machines);
     let running = "?";
     try {
-      running = ssh(host, "pgrep -x slab-menubar >/dev/null && echo yes || echo no").trim();
+      running = runOn(n, machines, "pgrep -x slab-menubar >/dev/null && echo yes || echo no").trim();
     } catch (e) {
       console.log(`${n}: UNREACHABLE (${e.message.split("\n")[0]})`);
       continue;
     }
-    const sr = srGrant(host);
+    const sr = srGrant(n, machines);
     const srLabel = sr === "2" ? "granted" : sr === "" ? "not listed (capture once to register)" : `denied (auth=${sr})`;
     console.log(
       `${n}: SlabMenubar ${running === "yes" ? "running" : "NOT running"} | ` +
@@ -162,10 +184,9 @@ function setup(name) {
     console.error(`unknown machine "${name}"`);
     process.exit(1);
   }
-  const host = sshHostFor(name, machines);
   console.log(`Triggering a capture on ${name} to surface the Screen Recording prompt…`);
   captureFrame(name, { noOCR: true });
-  const sr = srGrant(host);
+  const sr = srGrant(name, machines);
   if (sr === "2") {
     console.log(`✓ ${name}: Screen Recording already granted — frames will include pixels + OCR.`);
     return;
-- 
2.51.2


From 7424ee22b4c6b6ae0ba733d745101f4ca435df67 Mon Sep 17 00:00:00 2001
From: "prompt.ac/@jeffrey" <mail@aesthetic.computer>
Date: Wed, 17 Jun 2026 15:44:10 -0700
Subject: [PATCH 07/13] slab/frame: report per-stage timings_ms
 (capture/ocr/ax/meta/thumb) in the envelope for latency auditing

---
 .../Sources/SlabMenubar/FrameCapture.swift    | 19 +++++++++++++++----
 1 file changed, 15 insertions(+), 4 deletions(-)

diff --git a/slab/menubar-swift/Sources/SlabMenubar/FrameCapture.swift b/slab/menubar-swift/Sources/SlabMenubar/FrameCapture.swift
index e728340a3..93512150f 100644
--- a/slab/menubar-swift/Sources/SlabMenubar/FrameCapture.swift
+++ b/slab/menubar-swift/Sources/SlabMenubar/FrameCapture.swift
@@ -188,16 +188,26 @@ final class FrameCapture {
     // MARK: - assemble + write the envelope
 
     private func produce(noOCR: Bool) {
+        func nowNs() -> UInt64 { DispatchTime.now().uptimeNanoseconds }
+        func msSince(_ t: UInt64) -> Double { (Double(nowNs() - t) / 1e6 * 10).rounded() / 10 }
         var env: [String: Any] = [:]
-        let mt = meta()
+        var tm: [String: Double] = [:]
+        var t = nowNs(); let mt = meta(); tm["meta"] = msSince(t)
         env["meta"] = mt
-        env["ax"] = axTree()
+        t = nowNs(); env["ax"] = axTree(); tm["ax"] = msSince(t)
         let scale = ((mt["screen"] as? [String: Any])?["scale"] as? CGFloat).map(Double.init) ?? 1.0
-        if let cg = captureDisplay() {
-            env["ocr"] = noOCR ? [] : ocr(cg, scale: scale)
+        t = nowNs(); let cg = captureDisplay(); tm["capture"] = msSince(t)
+        if let cg = cg {
+            if noOCR {
+                env["ocr"] = []
+            } else {
+                t = nowNs(); env["ocr"] = ocr(cg, scale: scale); tm["ocr"] = msSince(t)
+            }
+            t = nowNs()
             if let jpg = thumbJPEG(cg, maxWidth: 1568) {
                 env["thumb_jpg_b64"] = jpg.base64EncodedString()
             }
+            tm["thumb"] = msSince(t)
             env["capture"] = "ok"
         } else {
             env["ocr"] = []
@@ -205,6 +215,7 @@ final class FrameCapture {
             env["capture"] = "permission_needed"
             env["permission"] = "screen_recording"
         }
+        env["timings_ms"] = tm
         if let d = try? JSONSerialization.data(withJSONObject: env, options: []) {
             try? d.write(to: URL(fileURLWithPath: Paths.frameOut))
         }
-- 
2.51.2


From 59ab36a14ce1296ba893d3d30934bb656942544c Mon Sep 17 00:00:00 2001
From: "prompt.ac/@jeffrey" <mail@aesthetic.computer>
Date: Wed, 17 Jun 2026 16:10:11 -0700
Subject: [PATCH 08/13] =?UTF-8?q?slab/frame:=20parallelize=20AX=20walk=20w?=
 =?UTF-8?q?ith=20capture+OCR=20(hides=20~150ms)=20+=20--fast=20OCR=20optio?=
 =?UTF-8?q?n=20(.fast=20level,=20~260ms=E2=86=9255ms)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

AX is independent of the screenshot, so run it on a concurrent queue and join
after capture+OCR — wall-clock becomes max(ax, capture+ocr) instead of the sum.
--fast switches Vision to .fast recognition for ~5x quicker OCR at some accuracy
cost on small text. timings_ms now also reports 'wall' (serial part).
---
 slab/bin/frame.mjs                            |  9 +++---
 .../Sources/SlabMenubar/FrameCapture.swift    | 32 +++++++++++++++----
 2 files changed, 31 insertions(+), 10 deletions(-)

diff --git a/slab/bin/frame.mjs b/slab/bin/frame.mjs
index 94f899eef..17c45d9c5 100755
--- a/slab/bin/frame.mjs
+++ b/slab/bin/frame.mjs
@@ -88,13 +88,13 @@ function runOn(name, machines, cmd, { timeoutMs = 15000 } = {}) {
   return ssh(sshHostFor(name, machines), cmd, { timeoutMs });
 }
 
-function captureFrame(name, { noOCR = false, out, json = false } = {}) {
+function captureFrame(name, { noOCR = false, fast = false, out, json = false } = {}) {
   const machines = loadMachines();
   if (!machines[name]) {
     console.error(`unknown machine "${name}" — known: ${Object.keys(machines).join(", ") || "(none)"}`);
     process.exit(1);
   }
-  const mode = noOCR ? "noocr" : "full";
+  const mode = noOCR ? "noocr" : fast ? "fast" : "full";
   // Drop the request, wait for the daemon's done marker (≤4s), emit the envelope.
   const remote =
     `d=${REMOTE_STATE}; mkdir -p "$d"; rm -f "$d/frame.done"; ` +
@@ -223,7 +223,8 @@ const opt = (f) => {
 if (!cmd || cmd === "-h" || cmd === "--help") {
   console.log(
     "frame — capture a rich frame (pixels + OCR + AX + state) of a remote Mac\n\n" +
-      "  frame <machine> [--no-ocr] [--out file.jpg] [--json]\n" +
+      "  frame <machine> [--no-ocr] [--fast] [--out file.jpg] [--json]\n" +
+      "      --fast: Vision .fast OCR (lower latency, less accurate on small text)\n" +
       "  frame doctor [machine]      per-machine daemon + permission status\n" +
       "  frame setup <machine>       trigger + guide the one-time Screen Recording grant\n" +
       "  frame list                  registered machines\n",
@@ -233,4 +234,4 @@ if (!cmd || cmd === "-h" || cmd === "--help") {
 if (cmd === "doctor") doctor(argv[1]);
 else if (cmd === "setup") setup(argv[1]);
 else if (cmd === "list") list();
-else captureFrame(cmd, { noOCR: flag("--no-ocr"), out: opt("--out"), json: flag("--json") });
+else captureFrame(cmd, { noOCR: flag("--no-ocr"), fast: flag("--fast"), out: opt("--out"), json: flag("--json") });
diff --git a/slab/menubar-swift/Sources/SlabMenubar/FrameCapture.swift b/slab/menubar-swift/Sources/SlabMenubar/FrameCapture.swift
index 93512150f..8c7cccf76 100644
--- a/slab/menubar-swift/Sources/SlabMenubar/FrameCapture.swift
+++ b/slab/menubar-swift/Sources/SlabMenubar/FrameCapture.swift
@@ -42,7 +42,7 @@ final class FrameCapture {
         let mode = (try? String(contentsOfFile: Paths.frameReq, encoding: .utf8)) ?? ""
         try? fm.removeItem(atPath: Paths.frameReq)
         try? fm.removeItem(atPath: Paths.frameDone)
-        produce(noOCR: mode.contains("noocr"))
+        produce(noOCR: mode.contains("noocr"), fast: mode.contains("fast"))
         fm.createFile(atPath: Paths.frameDone, contents: nil)
     }
 
@@ -70,10 +70,11 @@ final class FrameCapture {
 
     // MARK: - OCR (text + click-center coords, in logical points)
 
-    private func ocr(_ cg: CGImage, scale: Double) -> [[String: Any]] {
+    private func ocr(_ cg: CGImage, scale: Double, fast: Bool = false) -> [[String: Any]] {
         let req = VNRecognizeTextRequest()
-        req.recognitionLevel = .accurate
+        req.recognitionLevel = fast ? .fast : .accurate
         req.usesLanguageCorrection = false
+        req.recognitionLanguages = ["en-US"]
         try? VNImageRequestHandler(cgImage: cg, options: [:]).perform([req])
         let W = Double(cg.width), H = Double(cg.height)
         var out: [[String: Any]] = []
@@ -187,21 +188,36 @@ final class FrameCapture {
 
     // MARK: - assemble + write the envelope
 
-    private func produce(noOCR: Bool) {
+    private func produce(noOCR: Bool, fast: Bool = false) {
         func nowNs() -> UInt64 { DispatchTime.now().uptimeNanoseconds }
         func msSince(_ t: UInt64) -> Double { (Double(nowNs() - t) / 1e6 * 10).rounded() / 10 }
         var env: [String: Any] = [:]
         var tm: [String: Double] = [:]
+
+        // The AX walk is independent of the screenshot, so run it CONCURRENTLY
+        // with capture+OCR: wall-clock becomes max(ax, capture+ocr) instead of
+        // the sum. AX is ~150ms and capture+OCR ~280ms, so this hides the AX
+        // cost entirely. (AXUIElement calls are fine off the main thread.)
+        var axResult: [String: Any] = [:]
+        var axMs: Double = 0
+        let grp = DispatchGroup()
+        grp.enter()
+        let axStart = nowNs()
+        DispatchQueue.global(qos: .userInitiated).async {
+            axResult = self.axTree()
+            axMs = msSince(axStart)
+            grp.leave()
+        }
+
         var t = nowNs(); let mt = meta(); tm["meta"] = msSince(t)
         env["meta"] = mt
-        t = nowNs(); env["ax"] = axTree(); tm["ax"] = msSince(t)
         let scale = ((mt["screen"] as? [String: Any])?["scale"] as? CGFloat).map(Double.init) ?? 1.0
         t = nowNs(); let cg = captureDisplay(); tm["capture"] = msSince(t)
         if let cg = cg {
             if noOCR {
                 env["ocr"] = []
             } else {
-                t = nowNs(); env["ocr"] = ocr(cg, scale: scale); tm["ocr"] = msSince(t)
+                t = nowNs(); env["ocr"] = ocr(cg, scale: scale, fast: fast); tm["ocr"] = msSince(t)
             }
             t = nowNs()
             if let jpg = thumbJPEG(cg, maxWidth: 1568) {
@@ -215,6 +231,10 @@ final class FrameCapture {
             env["capture"] = "permission_needed"
             env["permission"] = "screen_recording"
         }
+        grp.wait()                 // join the concurrent AX walk
+        env["ax"] = axResult
+        tm["ax"] = axMs
+        tm["wall"] = (tm["meta"]! + tm["capture"]! + (tm["ocr"] ?? 0) + tm["thumb"]!)  // serial part; ax overlapped
         env["timings_ms"] = tm
         if let d = try? JSONSerialization.data(withJSONObject: env, options: []) {
             try? d.write(to: URL(fileURLWithPath: Paths.frameOut))
-- 
2.51.2


From 01069f5ed078c5011f416b0f28af73943838847e Mon Sep 17 00:00:00 2001
From: "prompt.ac/@jeffrey" <mail@aesthetic.computer>
Date: Wed, 17 Jun 2026 16:23:26 -0700
Subject: [PATCH 09/13] slab/frame: opt-in persistent server (held per-machine
 ssh agents over a unix socket)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

A long-lived consumer that holds the socket open avoids per-call node cold-start
and connection setup: steady-state --fast frames drop ~440ms→~280ms (~35%), full
~650→530ms. Started explicitly with 'frame server' (the CLI uses it only if
running — for one-shot calls it's no faster than direct, since ControlMaster
already amortizes ssh, so we don't auto-spawn a daemon). 'frame stop' to halt;
'--direct' forces a one-shot ssh. Remaining held-socket cost is the AX walk
(~150ms, now the daemon limiter) + the 248KB envelope transfer.
---
 slab/bin/frame.mjs | 198 +++++++++++++++++++++++++++++++++++++++++----
 1 file changed, 182 insertions(+), 16 deletions(-)

diff --git a/slab/bin/frame.mjs b/slab/bin/frame.mjs
index 17c45d9c5..94869d498 100755
--- a/slab/bin/frame.mjs
+++ b/slab/bin/frame.mjs
@@ -23,17 +23,36 @@
 // puppet at ~/.config/slab/puppet.json. A machine's name doubles as its ssh
 // host (the minis are ssh aliases); set "sshHost" per machine to override.
 
-import { execFileSync } from "node:child_process";
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { execFileSync, spawn } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
+import net from "node:net";
 import { dirname, join } from "node:path";
 
 const HOME = process.env.HOME;
 const CONFIG_PATH =
   process.env.SLAB_PUPPET_CONFIG || join(HOME, ".config", "slab", "puppet.json");
 const FRAMES_DIR = join(HOME, ".local", "share", "slab", "frames");
+const SOCK_PATH = process.env.SLAB_FRAME_SOCK || join(HOME, ".local", "share", "slab", "frame.sock");
 const APP_BUNDLE = "computer.slab.menubar";
 const REMOTE_STATE = "~/.local/share/slab/state"; // expanded by the remote shell
 
+// The remote read-loop agent: ONE per machine, held open by the server so each
+// frame is a stdin-write + stdout-read on an already-open ssh channel — no
+// channel setup (~100ms) and no node restart per call. `bash -s` reads its
+// SCRIPT from stdin, so the agent can't also read modes from stdin — instead we
+// drop this script on the target once and feed modes to `bash <file>` over the
+// persistent channel. Emits exactly one JSON line per mode (terminator-framed).
+const AGENT_SCRIPT = String.raw`#!/bin/bash
+d="$HOME/.local/share/slab/state"; mkdir -p "$d"
+while IFS= read -r mode; do
+  [ -z "$mode" ] && mode=full
+  rm -f "$d/frame.done"; printf '%s' "$mode" > "$d/frame.req"
+  for i in $(seq 1 400); do [ -f "$d/frame.done" ] && break; sleep 0.01; done
+  out="$(cat "$d/frame.out.json" 2>/dev/null)"
+  if [ -n "$out" ]; then printf '%s\n' "$out"; else printf '%s\n' '{"capture":"error","reason":"no-out"}'; fi
+done`;
+const AGENT_REMOTE_PATH = "~/.local/share/slab/frame-agent.sh";
+
 function loadMachines() {
   let machines = {};
   if (existsSync(CONFIG_PATH)) {
@@ -88,7 +107,132 @@ function runOn(name, machines, cmd, { timeoutMs = 15000 } = {}) {
   return ssh(sshHostFor(name, machines), cmd, { timeoutMs });
 }
 
-function captureFrame(name, { noOCR = false, fast = false, out, json = false } = {}) {
+function sshOpts(host) {
+  return [
+    "-o", "ControlMaster=auto",
+    "-o", `ControlPath=${join(HOME, ".ssh", `cm-${host}`)}`,
+    "-o", "ControlPersist=300",
+    "-o", "BatchMode=yes",
+  ];
+}
+
+// ─── persistent server: one held-open agent per machine ───────────────────
+// Removes the two per-call costs the transport audit found: node cold-start
+// (the server stays warm) and ssh channel setup (each agent is a single ssh
+// process kept open, fed modes on stdin). A frame then costs ~daemon work + one
+// RTT on the open channel instead of +~170ms of process/connection spin-up.
+const agents = new Map(); // name -> { proc, pending: [resolve], buf }
+
+function ensureAgentScript(name, machines) {
+  if (machines[name]?.local) {
+    const p = join(HOME, ".local", "share", "slab", "frame-agent.sh");
+    mkdirSync(dirname(p), { recursive: true });
+    writeFileSync(p, AGENT_SCRIPT);
+    return p;
+  }
+  const host = sshHostFor(name, machines);
+  execFileSync(
+    "ssh",
+    [...sshOpts(host), host, `mkdir -p ~/.local/share/slab && cat > ${AGENT_REMOTE_PATH}`],
+    { input: AGENT_SCRIPT, encoding: "utf8", timeout: 15000 },
+  );
+  return AGENT_REMOTE_PATH;
+}
+
+function spawnAgent(name, machines) {
+  const scriptPath = ensureAgentScript(name, machines);
+  let proc;
+  if (machines[name]?.local) {
+    proc = spawn("bash", [scriptPath], { stdio: ["pipe", "pipe", "ignore"] });
+  } else {
+    const host = sshHostFor(name, machines);
+    proc = spawn("ssh", [...sshOpts(host), host, `bash ${AGENT_REMOTE_PATH}`], {
+      stdio: ["pipe", "pipe", "ignore"],
+    });
+  }
+  const ag = { proc, pending: [], buf: "" };
+  proc.stdout.setEncoding("utf8");
+  proc.stdout.on("data", (chunk) => {
+    ag.buf += chunk;
+    let nl;
+    while ((nl = ag.buf.indexOf("\n")) >= 0) {
+      const line = ag.buf.slice(0, nl);
+      ag.buf = ag.buf.slice(nl + 1);
+      if (!line.startsWith("{")) continue; // skip ssh banners / blank lines
+      const resolve = ag.pending.shift();
+      if (resolve) resolve(line);
+    }
+  });
+  proc.on("exit", () => {
+    agents.delete(name);
+    ag.pending.forEach((r) => r('{"capture":"error","reason":"agent-exit"}'));
+  });
+  agents.set(name, ag);
+  return ag;
+}
+
+function agentRequest(name, machines, mode, timeoutMs = 15000) {
+  return new Promise((resolve, reject) => {
+    let ag;
+    try {
+      ag = agents.get(name) || spawnAgent(name, machines);
+    } catch (e) {
+      reject(e);
+      return;
+    }
+    const timer = setTimeout(() => reject(new Error("agent timeout")), timeoutMs);
+    ag.pending.push((line) => { clearTimeout(timer); resolve(line); });
+    ag.proc.stdin.write(mode + "\n");
+  });
+}
+
+function runServer() {
+  mkdirSync(dirname(SOCK_PATH), { recursive: true });
+  try { unlinkSync(SOCK_PATH); } catch {}
+  const server = net.createServer((sock) => {
+    let buf = "";
+    sock.on("data", async (chunk) => {
+      buf += chunk;
+      let nl;
+      while ((nl = buf.indexOf("\n")) >= 0) {
+        const line = buf.slice(0, nl);
+        buf = buf.slice(nl + 1);
+        if (!line.trim()) continue;
+        let req;
+        try { req = JSON.parse(line); } catch { sock.write('{"error":"bad json"}\n'); continue; }
+        try {
+          const env = await agentRequest(req.machine, loadMachines(), req.mode || "full");
+          sock.write(env + "\n");
+        } catch (e) {
+          sock.write(JSON.stringify({ error: String(e.message || e) }) + "\n");
+        }
+      }
+    });
+    sock.on("error", () => {});
+  });
+  server.on("error", (e) => {
+    if (e.code === "EADDRINUSE") process.exit(0); // another server won the race
+    throw e;
+  });
+  server.listen(SOCK_PATH, () => console.log(`frame server listening on ${SOCK_PATH}`));
+}
+
+function requestViaServer(machine, mode, timeoutMs = 15000) {
+  return new Promise((resolve, reject) => {
+    const sock = net.createConnection(SOCK_PATH);
+    let buf = "";
+    const timer = setTimeout(() => { sock.destroy(); reject(new Error("server rpc timeout")); }, timeoutMs);
+    sock.on("error", (e) => { clearTimeout(timer); reject(e); });
+    sock.on("connect", () => sock.write(JSON.stringify({ machine, mode }) + "\n"));
+    sock.on("data", (chunk) => {
+      buf += chunk;
+      const nl = buf.indexOf("\n");
+      if (nl >= 0) { clearTimeout(timer); sock.end(); resolve(buf.slice(0, nl)); }
+    });
+  });
+}
+
+async function captureFrame(name, { noOCR = false, fast = false, out, json = false, direct = false } = {}) {
   const machines = loadMachines();
   if (!machines[name]) {
     console.error(`unknown machine "${name}" — known: ${Object.keys(machines).join(", ") || "(none)"}`);
@@ -101,12 +245,25 @@ function captureFrame(name, { noOCR = false, fast = false, out, json = false } =
     `printf '%s' '${mode}' > "$d/frame.req"; ` +
     `for i in $(seq 1 200); do [ -f "$d/frame.done" ] && break; sleep 0.02; done; ` +
     `cat "$d/frame.out.json" 2>/dev/null`;
-  let raw;
-  try {
-    raw = runOn(name, machines, remote);
-  } catch (e) {
-    console.error(`${name} unreachable: ${e.message.split("\n")[0]}`);
-    process.exit(1);
+  let raw = null;
+  // Use the resident server ONLY if it's already running (started explicitly
+  // with `frame server`). Measured: for one-shot CLI calls it's no faster than
+  // direct — ControlMaster already amortizes ssh, and the client's own node
+  // cold-start + OCR + payload dominate. The server pays off for a LONG-LIVED
+  // consumer that holds the socket open (no per-call node-start); we don't
+  // auto-spawn a daemon for a single call.
+  if (!direct && existsSync(SOCK_PATH)) {
+    try {
+      raw = await requestViaServer(name, mode);
+    } catch { raw = null; } // stale socket / dead server → one-shot direct ssh
+  }
+  if (raw == null) {
+    try {
+      raw = runOn(name, machines, remote);
+    } catch (e) {
+      console.error(`${name} unreachable: ${e.message.split("\n")[0]}`);
+      process.exit(1);
+    }
   }
   let env;
   try {
@@ -178,14 +335,14 @@ function doctor(name) {
   }
 }
 
-function setup(name) {
+async function setup(name) {
   const machines = loadMachines();
   if (!machines[name]) {
     console.error(`unknown machine "${name}"`);
     process.exit(1);
   }
   console.log(`Triggering a capture on ${name} to surface the Screen Recording prompt…`);
-  captureFrame(name, { noOCR: true });
+  await captureFrame(name, { noOCR: true });
   const sr = srGrant(name, machines);
   if (sr === "2") {
     console.log(`✓ ${name}: Screen Recording already granted — frames will include pixels + OCR.`);
@@ -223,15 +380,24 @@ const opt = (f) => {
 if (!cmd || cmd === "-h" || cmd === "--help") {
   console.log(
     "frame — capture a rich frame (pixels + OCR + AX + state) of a remote Mac\n\n" +
-      "  frame <machine> [--no-ocr] [--fast] [--out file.jpg] [--json]\n" +
+      "  frame <machine> [--no-ocr] [--fast] [--direct] [--out file.jpg] [--json]\n" +
       "      --fast: Vision .fast OCR (lower latency, less accurate on small text)\n" +
+      "      --direct: bypass the resident server, do a one-shot ssh\n" +
       "  frame doctor [machine]      per-machine daemon + permission status\n" +
       "  frame setup <machine>       trigger + guide the one-time Screen Recording grant\n" +
-      "  frame list                  registered machines\n",
+      "  frame list                  registered machines\n" +
+      "  frame server                run the resident server (holds a warm agent per\n" +
+      "                              machine; auto-started on demand otherwise)\n" +
+      "  frame stop                  stop the resident server\n",
   );
   process.exit(0);
 }
-if (cmd === "doctor") doctor(argv[1]);
-else if (cmd === "setup") setup(argv[1]);
+if (cmd === "server") runServer();
+else if (cmd === "stop") {
+  try { unlinkSync(SOCK_PATH); } catch {}
+  try { execFileSync("pkill", ["-f", "frame.mjs server"]); } catch {}
+  console.log("frame server stopped");
+} else if (cmd === "doctor") doctor(argv[1]);
+else if (cmd === "setup") await setup(argv[1]);
 else if (cmd === "list") list();
-else captureFrame(cmd, { noOCR: flag("--no-ocr"), fast: flag("--fast"), out: opt("--out"), json: flag("--json") });
+else await captureFrame(cmd, { noOCR: flag("--no-ocr"), fast: flag("--fast"), direct: flag("--direct"), out: opt("--out"), json: flag("--json") });
-- 
2.51.2


From 5a168fa2fc475d6e7c9d1f6fd5210412006924d7 Mon Sep 17 00:00:00 2001
From: "prompt.ac/@jeffrey" <mail@aesthetic.computer>
Date: Wed, 17 Jun 2026 16:36:24 -0700
Subject: [PATCH 10/13] slab/frame: transfer the JPEG as raw bytes, not base64
 (ACF1 length-prefixed frame)

Daemon writes the thumbnail to a sidecar frame.out.jpg (no thumb_jpg_b64 in the
envelope). Transport frames it as 'ACF1 <jsonLen> <jpgLen>\n<json><jpg>' across
all paths (held agent, server->consumer socket, one-shot direct). Kills the
base64 +33% inflation (225KB->148KB on the wire) and the encode/decode CPU;
verified the JPEG survives the agent->server->consumer double-hop intact.
---
 slab/bin/frame.mjs                            | 176 ++++++++++++------
 .../Sources/SlabMenubar/FrameCapture.swift    |  13 +-
 .../Sources/SlabMenubar/Paths.swift           |   1 +
 3 files changed, 132 insertions(+), 58 deletions(-)

diff --git a/slab/bin/frame.mjs b/slab/bin/frame.mjs
index 94869d498..158df5c7a 100755
--- a/slab/bin/frame.mjs
+++ b/slab/bin/frame.mjs
@@ -34,7 +34,6 @@ const CONFIG_PATH =
 const FRAMES_DIR = join(HOME, ".local", "share", "slab", "frames");
 const SOCK_PATH = process.env.SLAB_FRAME_SOCK || join(HOME, ".local", "share", "slab", "frame.sock");
 const APP_BUNDLE = "computer.slab.menubar";
-const REMOTE_STATE = "~/.local/share/slab/state"; // expanded by the remote shell
 
 // The remote read-loop agent: ONE per machine, held open by the server so each
 // frame is a stdin-write + stdout-read on an already-open ssh channel — no
@@ -42,14 +41,29 @@ const REMOTE_STATE = "~/.local/share/slab/state"; // expanded by the remote shel
 // SCRIPT from stdin, so the agent can't also read modes from stdin — instead we
 // drop this script on the target once and feed modes to `bash <file>` over the
 // persistent channel. Emits exactly one JSON line per mode (terminator-framed).
+// Emits a length-prefixed binary frame per request: `ACF1 <jsonLen> <jpgLen>\n`
+// then the JSON bytes then the raw JPEG bytes — no base64. One frame per mode
+// line read on stdin.
+// NOTE: this is a JS template literal — bash `${...}` would be interpreted as JS
+// interpolation, so the script uses only `$var` and `$(...)` (both literal here).
 const AGENT_SCRIPT = String.raw`#!/bin/bash
 d="$HOME/.local/share/slab/state"; mkdir -p "$d"
+emit() {
+  local j="$d/frame.out.json" p="$d/frame.out.jpg" jl pl e el
+  jl=$(wc -c < "$j" 2>/dev/null | tr -d ' '); [ -z "$jl" ] && jl=0
+  pl=$(wc -c < "$p" 2>/dev/null | tr -d ' '); [ -z "$pl" ] && pl=0
+  if [ "$jl" = 0 ]; then
+    e='{"capture":"error","reason":"no-out"}'
+    el=$(printf '%s' "$e" | wc -c | tr -d ' ')
+    printf 'ACF1 %s 0\n%s' "$el" "$e"; return
+  fi
+  printf 'ACF1 %s %s\n' "$jl" "$pl"; cat "$j"; [ "$pl" != 0 ] && cat "$p"
+}
 while IFS= read -r mode; do
   [ -z "$mode" ] && mode=full
   rm -f "$d/frame.done"; printf '%s' "$mode" > "$d/frame.req"
   for i in $(seq 1 400); do [ -f "$d/frame.done" ] && break; sleep 0.01; done
-  out="$(cat "$d/frame.out.json" 2>/dev/null)"
-  if [ -n "$out" ]; then printf '%s\n' "$out"; else printf '%s\n' '{"capture":"error","reason":"no-out"}'; fi
+  emit
 done`;
 const AGENT_REMOTE_PATH = "~/.local/share/slab/frame-agent.sh";
 
@@ -116,6 +130,30 @@ function sshOpts(host) {
   ];
 }
 
+// ─── ACF1 binary frame codec ──────────────────────────────────────────────
+// Wire format: `ACF1 <jsonLen> <jpgLen>\n` + <jsonLen bytes JSON> + <jpgLen
+// bytes raw JPEG>. No base64. Parses one frame off the front of a Buffer.
+// Returns {frame:{json,jpg}, rest} when complete, {skip, rest} for a non-ACF1
+// line (ssh banner), or null when more bytes are needed.
+function parseFrame(buf) {
+  const nl = buf.indexOf(0x0a);
+  if (nl < 0) return null;
+  const header = buf.subarray(0, nl).toString("ascii");
+  const m = header.match(/^ACF1 (\d+) (\d+)$/);
+  if (!m) return { skip: true, rest: buf.subarray(nl + 1) };
+  const jl = +m[1], pl = +m[2];
+  const start = nl + 1, end = start + jl + pl;
+  if (buf.length < end) return null;
+  return {
+    frame: { json: buf.subarray(start, start + jl).toString("utf8"), jpg: buf.subarray(start + jl, end) },
+    rest: buf.subarray(end),
+  };
+}
+function frameBytes(json, jpg) {
+  const jb = Buffer.from(json, "utf8");
+  return Buffer.concat([Buffer.from(`ACF1 ${jb.length} ${jpg.length}\n`, "ascii"), jb, jpg]);
+}
+
 // ─── persistent server: one held-open agent per machine ───────────────────
 // Removes the two per-call costs the transport audit found: node cold-start
 // (the server stays warm) and ssh channel setup (each agent is a single ssh
@@ -150,22 +188,22 @@ function spawnAgent(name, machines) {
       stdio: ["pipe", "pipe", "ignore"],
     });
   }
-  const ag = { proc, pending: [], buf: "" };
-  proc.stdout.setEncoding("utf8");
+  const ag = { proc, pending: [], buf: Buffer.alloc(0) }; // buf is binary
   proc.stdout.on("data", (chunk) => {
-    ag.buf += chunk;
-    let nl;
-    while ((nl = ag.buf.indexOf("\n")) >= 0) {
-      const line = ag.buf.slice(0, nl);
-      ag.buf = ag.buf.slice(nl + 1);
-      if (!line.startsWith("{")) continue; // skip ssh banners / blank lines
+    ag.buf = Buffer.concat([ag.buf, chunk]);
+    for (;;) {
+      const r = parseFrame(ag.buf);
+      if (!r) break;
+      ag.buf = r.rest;
+      if (r.skip) continue; // ssh banner line
       const resolve = ag.pending.shift();
-      if (resolve) resolve(line);
+      if (resolve) resolve(r.frame);
     }
   });
   proc.on("exit", () => {
     agents.delete(name);
-    ag.pending.forEach((r) => r('{"capture":"error","reason":"agent-exit"}'));
+    const dead = { json: '{"capture":"error","reason":"agent-exit"}', jpg: Buffer.alloc(0) };
+    ag.pending.forEach((r) => r(dead));
   });
   agents.set(name, ag);
   return ag;
@@ -181,7 +219,7 @@ function agentRequest(name, machines, mode, timeoutMs = 15000) {
       return;
     }
     const timer = setTimeout(() => reject(new Error("agent timeout")), timeoutMs);
-    ag.pending.push((line) => { clearTimeout(timer); resolve(line); });
+    ag.pending.push((frame) => { clearTimeout(timer); resolve(frame); });
     ag.proc.stdin.write(mode + "\n");
   });
 }
@@ -190,21 +228,23 @@ function runServer() {
   mkdirSync(dirname(SOCK_PATH), { recursive: true });
   try { unlinkSync(SOCK_PATH); } catch {}
   const server = net.createServer((sock) => {
-    let buf = "";
+    // Request is a JSON line; response is an ACF1 binary frame (forwarded from
+    // the held agent), so we frame the request side on '\n' but write binary.
+    let buf = Buffer.alloc(0);
     sock.on("data", async (chunk) => {
-      buf += chunk;
+      buf = Buffer.concat([buf, chunk]);
       let nl;
-      while ((nl = buf.indexOf("\n")) >= 0) {
-        const line = buf.slice(0, nl);
-        buf = buf.slice(nl + 1);
+      while ((nl = buf.indexOf(0x0a)) >= 0) {
+        const line = buf.subarray(0, nl).toString("utf8");
+        buf = buf.subarray(nl + 1);
         if (!line.trim()) continue;
         let req;
-        try { req = JSON.parse(line); } catch { sock.write('{"error":"bad json"}\n'); continue; }
+        try { req = JSON.parse(line); } catch { sock.write(frameBytes('{"error":"bad json"}', Buffer.alloc(0))); continue; }
         try {
-          const env = await agentRequest(req.machine, loadMachines(), req.mode || "full");
-          sock.write(env + "\n");
+          const frame = await agentRequest(req.machine, loadMachines(), req.mode || "full");
+          sock.write(frameBytes(frame.json, frame.jpg));
         } catch (e) {
-          sock.write(JSON.stringify({ error: String(e.message || e) }) + "\n");
+          sock.write(frameBytes(JSON.stringify({ error: String(e.message || e) }), Buffer.alloc(0)));
         }
       }
     });
@@ -220,14 +260,52 @@ function runServer() {
 function requestViaServer(machine, mode, timeoutMs = 15000) {
   return new Promise((resolve, reject) => {
     const sock = net.createConnection(SOCK_PATH);
-    let buf = "";
+    let buf = Buffer.alloc(0);
     const timer = setTimeout(() => { sock.destroy(); reject(new Error("server rpc timeout")); }, timeoutMs);
     sock.on("error", (e) => { clearTimeout(timer); reject(e); });
     sock.on("connect", () => sock.write(JSON.stringify({ machine, mode }) + "\n"));
     sock.on("data", (chunk) => {
-      buf += chunk;
-      const nl = buf.indexOf("\n");
-      if (nl >= 0) { clearTimeout(timer); sock.end(); resolve(buf.slice(0, nl)); }
+      buf = Buffer.concat([buf, chunk]);
+      const r = parseFrame(buf);
+      if (r && r.frame) { clearTimeout(timer); sock.end(); resolve(r.frame); }
+    });
+  });
+}
+
+// One-shot direct path (no server): spawn ssh/local, feed the request, read one
+// ACF1 frame off stdout. Returns {json, jpg}.
+function directFrame(name, machines, mode, timeoutMs = 15000) {
+  return new Promise((resolve, reject) => {
+    const remote =
+      `d="$HOME/.local/share/slab/state"; mkdir -p "$d"; rm -f "$d/frame.done"; ` +
+      `printf '%s' '${mode}' > "$d/frame.req"; ` +
+      `for i in $(seq 1 400); do [ -f "$d/frame.done" ] && break; sleep 0.01; done; ` +
+      `j="$d/frame.out.json"; p="$d/frame.out.jpg"; ` +
+      `jl=$(wc -c < "$j" 2>/dev/null | tr -d ' '); pl=$(wc -c < "$p" 2>/dev/null | tr -d ' '); ` +
+      `[ -z "$jl" ] && jl=0; [ -z "$pl" ] && pl=0; ` +
+      `printf 'ACF1 %s %s\\n' "$jl" "$pl"; cat "$j" 2>/dev/null; [ "$pl" != 0 ] && cat "$p" 2>/dev/null`;
+    let proc;
+    if (machines[name]?.local) {
+      proc = spawn("bash", ["-c", remote], { stdio: ["ignore", "pipe", "ignore"] });
+    } else {
+      const host = sshHostFor(name, machines);
+      proc = spawn("ssh", [...sshOpts(host), host, "bash -s"], { stdio: ["pipe", "pipe", "ignore"] });
+      proc.stdin.end(remote);
+    }
+    let buf = Buffer.alloc(0), settled = false;
+    const finish = (fn, arg) => { if (!settled) { settled = true; clearTimeout(timer); fn(arg); } };
+    const timer = setTimeout(() => { proc.kill(); finish(reject, new Error("direct timeout")); }, timeoutMs);
+    proc.stdout.on("data", (chunk) => {
+      buf = Buffer.concat([buf, chunk]);
+      let r = parseFrame(buf);
+      while (r && r.skip) { buf = r.rest; r = parseFrame(buf); }
+      if (r && r.frame) { finish(resolve, r.frame); proc.kill(); }
+    });
+    proc.on("error", (e) => finish(reject, e));
+    proc.on("exit", () => {
+      const r = parseFrame(buf);
+      if (r && r.frame) finish(resolve, r.frame);
+      else finish(reject, new Error("no frame"));
     });
   });
 }
@@ -239,35 +317,22 @@ async function captureFrame(name, { noOCR = false, fast = false, out, json = fal
     process.exit(1);
   }
   const mode = noOCR ? "noocr" : fast ? "fast" : "full";
-  // Drop the request, wait for the daemon's done marker (≤4s), emit the envelope.
-  const remote =
-    `d=${REMOTE_STATE}; mkdir -p "$d"; rm -f "$d/frame.done"; ` +
-    `printf '%s' '${mode}' > "$d/frame.req"; ` +
-    `for i in $(seq 1 200); do [ -f "$d/frame.done" ] && break; sleep 0.02; done; ` +
-    `cat "$d/frame.out.json" 2>/dev/null`;
-  let raw = null;
-  // Use the resident server ONLY if it's already running (started explicitly
-  // with `frame server`). Measured: for one-shot CLI calls it's no faster than
-  // direct — ControlMaster already amortizes ssh, and the client's own node
-  // cold-start + OCR + payload dominate. The server pays off for a LONG-LIVED
-  // consumer that holds the socket open (no per-call node-start); we don't
-  // auto-spawn a daemon for a single call.
+  // Use the resident server only if already running (opt-in; see runServer);
+  // otherwise a one-shot direct ssh. Both return an ACF1 {json, jpg} frame —
+  // the JPEG is raw bytes, never base64.
+  let frame = null;
   if (!direct && existsSync(SOCK_PATH)) {
-    try {
-      raw = await requestViaServer(name, mode);
-    } catch { raw = null; } // stale socket / dead server → one-shot direct ssh
+    try { frame = await requestViaServer(name, mode); } catch { frame = null; }
   }
-  if (raw == null) {
-    try {
-      raw = runOn(name, machines, remote);
-    } catch (e) {
-      console.error(`${name} unreachable: ${e.message.split("\n")[0]}`);
+  if (!frame) {
+    try { frame = await directFrame(name, machines, mode); } catch (e) {
+      console.error(`${name} unreachable: ${String(e.message || e).split("\n")[0]}`);
       process.exit(1);
     }
   }
   let env;
   try {
-    env = JSON.parse(raw);
+    env = JSON.parse(frame.json);
   } catch {
     console.error(`no frame from ${name} — is SlabMenubar running there? (frame doctor ${name})`);
     process.exit(1);
@@ -279,18 +344,19 @@ async function captureFrame(name, { noOCR = false, fast = false, out, json = fal
         `  (AX + window/meta still captured; pixels + OCR are blocked until granted)`,
     );
   }
-  // Write the thumbnail out; keep the base64 out of stdout unless --json.
+  // Write the raw JPEG to disk (no base64 anywhere on the path).
   const outPath = out || join(FRAMES_DIR, `${name}.jpg`);
-  if (env.thumb_jpg_b64) {
+  const hasJpg = frame.jpg && frame.jpg.length > 0;
+  if (hasJpg) {
     mkdirSync(dirname(outPath), { recursive: true });
-    writeFileSync(outPath, Buffer.from(env.thumb_jpg_b64, "base64"));
+    writeFileSync(outPath, frame.jpg);
   }
   if (json) {
-    process.stdout.write(JSON.stringify(env));
+    process.stdout.write(frame.json);
     return;
   }
-  const { thumb_jpg_b64, ...rest } = env;
-  rest.thumb = env.thumb_jpg_b64 ? outPath : null;
+  const rest = { ...env };
+  rest.thumb = hasJpg ? outPath : null;
   rest.ocr_count = (env.ocr || []).length;
   rest.ax_count = (env.ax?.elements || []).length;
   delete rest.ocr;
diff --git a/slab/menubar-swift/Sources/SlabMenubar/FrameCapture.swift b/slab/menubar-swift/Sources/SlabMenubar/FrameCapture.swift
index 8c7cccf76..9884ca232 100644
--- a/slab/menubar-swift/Sources/SlabMenubar/FrameCapture.swift
+++ b/slab/menubar-swift/Sources/SlabMenubar/FrameCapture.swift
@@ -213,6 +213,11 @@ final class FrameCapture {
         env["meta"] = mt
         let scale = ((mt["screen"] as? [String: Any])?["scale"] as? CGFloat).map(Double.init) ?? 1.0
         t = nowNs(); let cg = captureDisplay(); tm["capture"] = msSince(t)
+        // The JPEG ships as RAW BYTES in a sidecar file (frame.out.jpg), not
+        // base64 in the JSON — base64 inflates the payload +33% and burns
+        // encode/decode CPU. The transport length-prefixes the two. Written
+        // BEFORE the JSON + done marker so a reader that sees `done` has both.
+        var jpgBytes = 0
         if let cg = cg {
             if noOCR {
                 env["ocr"] = []
@@ -220,17 +225,19 @@ final class FrameCapture {
                 t = nowNs(); env["ocr"] = ocr(cg, scale: scale, fast: fast); tm["ocr"] = msSince(t)
             }
             t = nowNs()
-            if let jpg = thumbJPEG(cg, maxWidth: 1568) {
-                env["thumb_jpg_b64"] = jpg.base64EncodedString()
-            }
+            let jpg = thumbJPEG(cg, maxWidth: 1568) ?? Data()
+            try? jpg.write(to: URL(fileURLWithPath: Paths.frameOutJpg))
+            jpgBytes = jpg.count
             tm["thumb"] = msSince(t)
             env["capture"] = "ok"
         } else {
             env["ocr"] = []
+            try? Data().write(to: URL(fileURLWithPath: Paths.frameOutJpg)) // truncate stale jpg
             // Either Screen Recording isn't granted yet, or this is < macOS 14.
             env["capture"] = "permission_needed"
             env["permission"] = "screen_recording"
         }
+        env["thumb_bytes"] = jpgBytes
         grp.wait()                 // join the concurrent AX walk
         env["ax"] = axResult
         tm["ax"] = axMs
diff --git a/slab/menubar-swift/Sources/SlabMenubar/Paths.swift b/slab/menubar-swift/Sources/SlabMenubar/Paths.swift
index a00a38e79..a0f4a5508 100644
--- a/slab/menubar-swift/Sources/SlabMenubar/Paths.swift
+++ b/slab/menubar-swift/Sources/SlabMenubar/Paths.swift
@@ -80,6 +80,7 @@ enum Paths {
     /// `frame.out.json` (pixels + OCR + AX + meta) and touches `frame.done`.
     static var frameReq: String { "\(slabHome)/state/frame.req" }
     static var frameOut: String { "\(slabHome)/state/frame.out.json" }
+    static var frameOutJpg: String { "\(slabHome)/state/frame.out.jpg" }
     static var frameDone: String { "\(slabHome)/state/frame.done" }
 
     static var mailDir: String {
-- 
2.51.2


From 43d369ab638f2d591b889385b0e8800231968949 Mon Sep 17 00:00:00 2001
From: "prompt.ac/@jeffrey" <mail@aesthetic.computer>
Date: Wed, 17 Jun 2026 16:42:41 -0700
Subject: [PATCH 11/13] slab/frame: batch AX attribute fetches
 (AXUIElementCopyMultipleAttributeValues)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The walk did ~6 separate AX IPC round-trips per node (role/children/title/value/
desc/position/size), each a sync Mach call into the target app — ~2000 IPCs for
a 300-element tree. Batch all seven into ONE call per node; AXActionNames stays
separate but only for matched elements. AX walk on Chrome's ~320-element tree:
~200ms -> ~120ms (~40%). Since AX runs parallel to capture+OCR it's the --fast
daemon limiter, so this is the wall.
---
 .../Sources/SlabMenubar/FrameCapture.swift    | 45 +++++++++++++------
 1 file changed, 31 insertions(+), 14 deletions(-)

diff --git a/slab/menubar-swift/Sources/SlabMenubar/FrameCapture.swift b/slab/menubar-swift/Sources/SlabMenubar/FrameCapture.swift
index 9884ca232..034d00610 100644
--- a/slab/menubar-swift/Sources/SlabMenubar/FrameCapture.swift
+++ b/slab/menubar-swift/Sources/SlabMenubar/FrameCapture.swift
@@ -91,16 +91,33 @@ final class FrameCapture {
 
     // MARK: - Accessibility element tree of the frontmost app (trust already held)
 
-    private func axAttr(_ el: AXUIElement, _ k: String) -> AnyObject? {
-        var v: AnyObject?
-        return AXUIElementCopyAttributeValue(el, k as CFString, &v) == .success ? v : nil
+    // Fetch several attributes in ONE IPC round-trip instead of one call each.
+    // The old walk did ~6 `AXUIElementCopyAttributeValue` calls per node (role,
+    // children, title, value, desc, position, size) — each a synchronous Mach
+    // round-trip into the target app's main thread, so a 300-element tree cost
+    // ~2000 IPCs. `AXUIElementCopyMultipleAttributeValues` collapses that to one
+    // call per node. Returns values parallel to `attrs`; a failed slot comes
+    // back as an AXValue of type .axError, mapped to nil here.
+    private let AX_ATTRS = ["AXRole", "AXChildren", "AXTitle", "AXValue", "AXDescription", "AXPosition", "AXSize"]
+    private func axBatch(_ el: AXUIElement) -> [AnyObject?] {
+        var raw: CFArray?
+        let err = AXUIElementCopyMultipleAttributeValues(
+            el, AX_ATTRS as CFArray, AXCopyMultipleAttributeOptions(rawValue: 0), &raw)
+        guard err == .success, let arr = raw as? [AnyObject] else {
+            return Array(repeating: nil, count: AX_ATTRS.count)
+        }
+        return arr.map { v -> AnyObject? in
+            if CFGetTypeID(v) == AXValueGetTypeID(), AXValueGetType((v as! AXValue)) == .axError { return nil }
+            if v is NSNull { return nil }
+            return v
+        }
     }
-    private func axPoint(_ el: AXUIElement) -> (CGFloat, CGFloat)? {
-        guard let v = axAttr(el, "AXPosition") else { return nil }
+    private func axCGPoint(_ v: AnyObject?) -> (CGFloat, CGFloat)? {
+        guard let v = v, CFGetTypeID(v) == AXValueGetTypeID() else { return nil }
         var p = CGPoint.zero; AXValueGetValue(v as! AXValue, .cgPoint, &p); return (p.x, p.y)
     }
-    private func axSize(_ el: AXUIElement) -> (CGFloat, CGFloat)? {
-        guard let v = axAttr(el, "AXSize") else { return nil }
+    private func axCGSize(_ v: AnyObject?) -> (CGFloat, CGFloat)? {
+        guard let v = v, CFGetTypeID(v) == AXValueGetTypeID() else { return nil }
         var s = CGSize.zero; AXValueGetValue(v as! AXValue, .cgSize, &s); return (s.width, s.height)
     }
     private func axTree() -> [String: Any] {
@@ -117,19 +134,19 @@ final class FrameCapture {
         func walk(_ el: AXUIElement, _ depth: Int) {
             if count > 2000 || depth > 28 { return }
             count += 1
-            let role = (axAttr(el, "AXRole") as? String) ?? ""
-            if want.contains(role), let (x, y) = axPoint(el), let (w, h) = axSize(el), w > 0, h > 0 {
-                let title = (axAttr(el, "AXTitle") as? String)
-                    ?? (axAttr(el, "AXValue") as? String)
-                    ?? (axAttr(el, "AXDescription") as? String) ?? ""
+            let v = axBatch(el) // role, children, title, value, desc, position, size
+            let role = (v[0] as? String) ?? ""
+            if want.contains(role),
+               let (x, y) = axCGPoint(v[5]), let (w, h) = axCGSize(v[6]), w > 0, h > 0 {
+                let title = (v[2] as? String) ?? (v[3] as? String) ?? (v[4] as? String) ?? ""
                 var acts: CFArray?
-                AXUIElementCopyActionNames(el, &acts)
+                AXUIElementCopyActionNames(el, &acts) // only for matched elements
                 out.append(["role": role, "title": String(title.prefix(80)),
                     "cx": Int(x + w / 2), "cy": Int(y + h / 2),
                     "r": [Int(x), Int(y), Int(w), Int(h)],
                     "actions": (acts as? [String]) ?? []])
             }
-            if let kids = axAttr(el, "AXChildren") as? [AXUIElement] {
+            if let kids = v[1] as? [AXUIElement] {
                 for k in kids { walk(k, depth + 1) }
             }
         }
-- 
2.51.2


From 902986b999489c46ab2ae56aa2da823c25e4c2ce Mon Sep 17 00:00:00 2001
From: "prompt.ac/@jeffrey" <mail@aesthetic.computer>
Date: Wed, 17 Jun 2026 19:33:41 -0700
Subject: [PATCH 12/13] =?UTF-8?q?frame:=20preview=20window=20=E2=80=94=20p?=
 =?UTF-8?q?ulled=20screenshot=20with=20machine-name=20badge?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

FramePreview.swift mirrors VideoViewer/PdfViewer: watches state/open-frame
(path\tmachine lines), opens a chromeless glass panel per machine showing the
captured JPEG, live-reloads on rewrite, and draws the source machine name in a
top-left HUD chip (same material/radius/mono style as the other viewers, but
the machine — not a session emoji — leads, since a frame answers "whose screen
is this"). Wired into AppDelegate.refresh()'s consume pass next to pdf/video.

frame.mjs gains an opt-in --preview flag (and a 'frame view <machine>' verb):
after writing the JPEG it appends path\tmachine to state/open-frame so the
local menubar raises/reloads the badged window. Bare 'frame' calls never pop a
window. Skips when capture was permission-blocked (no pixels to show).
---
 slab/bin/frame.mjs                            |  38 ++-
 .../Sources/SlabMenubar/AppDelegate.swift     |   4 +
 .../Sources/SlabMenubar/FramePreview.swift    | 275 ++++++++++++++++++
 3 files changed, 313 insertions(+), 4 deletions(-)
 create mode 100644 slab/menubar-swift/Sources/SlabMenubar/FramePreview.swift

diff --git a/slab/bin/frame.mjs b/slab/bin/frame.mjs
index 158df5c7a..3bb4e1ef6 100755
--- a/slab/bin/frame.mjs
+++ b/slab/bin/frame.mjs
@@ -24,7 +24,7 @@
 // host (the minis are ssh aliases); set "sshHost" per machine to override.
 
 import { execFileSync, spawn } from "node:child_process";
-import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
+import { appendFileSync, existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
 import net from "node:net";
 import { dirname, join } from "node:path";
 
@@ -33,6 +33,12 @@ const CONFIG_PATH =
   process.env.SLAB_PUPPET_CONFIG || join(HOME, ".config", "slab", "puppet.json");
 const FRAMES_DIR = join(HOME, ".local", "share", "slab", "frames");
 const SOCK_PATH = process.env.SLAB_FRAME_SOCK || join(HOME, ".local", "share", "slab", "frame.sock");
+// The menubar app on THIS (controller) Mac watches `state/open-frame` and
+// raises a preview window per machine, badged with the machine name (see
+// FramePreview.swift). Opt-in via `--preview` / `frame view <machine>` so a
+// plain `frame` call never pops a window. SLAB_HOME mirrors the Swift side.
+const SLAB_HOME = process.env.SLAB_HOME || join(HOME, ".local", "share", "slab");
+const FRAME_REQUEST_FILE = join(SLAB_HOME, "state", "open-frame");
 const APP_BUNDLE = "computer.slab.menubar";
 
 // The remote read-loop agent: ONE per machine, held open by the server so each
@@ -154,6 +160,16 @@ function frameBytes(json, jpg) {
   return Buffer.concat([Buffer.from(`ACF1 ${jb.length} ${jpg.length}\n`, "ascii"), jb, jpg]);
 }
 
+// Ask the local menubar app to open (or live-reload) a preview window for a
+// pulled frame. One `path\tmachine` line appended to `state/open-frame`; the
+// app's 2 s tick consumes it (FramePreview.consumeRequests). Re-asking the
+// same machine raises + reloads its window. Best-effort: a missing menubar
+// just leaves an unconsumed line, which is harmless.
+function requestPreview(machine, jpgPath) {
+  mkdirSync(dirname(FRAME_REQUEST_FILE), { recursive: true });
+  appendFileSync(FRAME_REQUEST_FILE, `${jpgPath}\t${machine}\n`);
+}
+
 // ─── persistent server: one held-open agent per machine ───────────────────
 // Removes the two per-call costs the transport audit found: node cold-start
 // (the server stays warm) and ssh channel setup (each agent is a single ssh
@@ -310,7 +326,7 @@ function directFrame(name, machines, mode, timeoutMs = 15000) {
   });
 }
 
-async function captureFrame(name, { noOCR = false, fast = false, out, json = false, direct = false } = {}) {
+async function captureFrame(name, { noOCR = false, fast = false, out, json = false, direct = false, preview = false } = {}) {
   const machines = loadMachines();
   if (!machines[name]) {
     console.error(`unknown machine "${name}" — known: ${Object.keys(machines).join(", ") || "(none)"}`);
@@ -351,6 +367,12 @@ async function captureFrame(name, { noOCR = false, fast = false, out, json = fal
     mkdirSync(dirname(outPath), { recursive: true });
     writeFileSync(outPath, frame.jpg);
   }
+  // Opt-in: pop (or live-reload) the local preview window, badged `name`.
+  // Only with pixels in hand — a permission-blocked frame has nothing to show.
+  if (preview && hasJpg) requestPreview(name, outPath);
+  else if (preview && !hasJpg) {
+    console.error(`(no pixels to preview for ${name} — capture blocked; run: frame setup ${name})`);
+  }
   if (json) {
     process.stdout.write(frame.json);
     return;
@@ -446,9 +468,11 @@ const opt = (f) => {
 if (!cmd || cmd === "-h" || cmd === "--help") {
   console.log(
     "frame — capture a rich frame (pixels + OCR + AX + state) of a remote Mac\n\n" +
-      "  frame <machine> [--no-ocr] [--fast] [--direct] [--out file.jpg] [--json]\n" +
+      "  frame <machine> [--no-ocr] [--fast] [--direct] [--preview] [--out file.jpg] [--json]\n" +
       "      --fast: Vision .fast OCR (lower latency, less accurate on small text)\n" +
       "      --direct: bypass the resident server, do a one-shot ssh\n" +
+      "      --preview: pop a labeled preview window of the pulled frame on THIS Mac\n" +
+      "  frame view <machine>        capture + open the badged preview window (= --preview)\n" +
       "  frame doctor [machine]      per-machine daemon + permission status\n" +
       "  frame setup <machine>       trigger + guide the one-time Screen Recording grant\n" +
       "  frame list                  registered machines\n" +
@@ -466,4 +490,10 @@ else if (cmd === "stop") {
 } else if (cmd === "doctor") doctor(argv[1]);
 else if (cmd === "setup") await setup(argv[1]);
 else if (cmd === "list") list();
-else await captureFrame(cmd, { noOCR: flag("--no-ocr"), fast: flag("--fast"), direct: flag("--direct"), out: opt("--out"), json: flag("--json") });
+else if (cmd === "view") {
+  // `frame view <machine>` — capture + open the badged preview window.
+  // Sugar for `frame <machine> --preview` so it reads like the slab-video /
+  // slab-pdf "show me this" verbs.
+  if (!argv[1]) { console.error("usage: frame view <machine>"); process.exit(1); }
+  await captureFrame(argv[1], { noOCR: flag("--no-ocr"), fast: flag("--fast"), direct: flag("--direct"), out: opt("--out"), preview: true });
+} else await captureFrame(cmd, { noOCR: flag("--no-ocr"), fast: flag("--fast"), direct: flag("--direct"), out: opt("--out"), json: flag("--json"), preview: flag("--preview") });
diff --git a/slab/menubar-swift/Sources/SlabMenubar/AppDelegate.swift b/slab/menubar-swift/Sources/SlabMenubar/AppDelegate.swift
index 52b0123ca..df33d5bf0 100644
--- a/slab/menubar-swift/Sources/SlabMenubar/AppDelegate.swift
+++ b/slab/menubar-swift/Sources/SlabMenubar/AppDelegate.swift
@@ -253,6 +253,10 @@ final class AppDelegate: NSObject, NSApplicationDelegate, NSMenuDelegate {
                 }
                 PdfViewer.shared.consumeRequests(emojiFor: emojiFor)
                 VideoViewer.shared.consumeRequests(emojiFor: emojiFor)
+                // Pulled `frame` screenshots open in FramePreview, badged with
+                // the source machine name (see FramePreview.swift / `frame
+                // --preview`). Machine identity leads, so no session emoji here.
+                FramePreview.shared.consumeRequests()
                 self.applyTerminalDecor()
                 self.applyDesktopTint()
             }
diff --git a/slab/menubar-swift/Sources/SlabMenubar/FramePreview.swift b/slab/menubar-swift/Sources/SlabMenubar/FramePreview.swift
new file mode 100644
index 000000000..b0c857c2e
--- /dev/null
+++ b/slab/menubar-swift/Sources/SlabMenubar/FramePreview.swift
@@ -0,0 +1,275 @@
+// FramePreview — slab's window for a pulled `frame` screenshot, so "see what
+// panda's screen looks like right now" is a glance, not a Finder dig into
+// ~/.local/share/slab/frames. The PdfViewer/VideoViewer contract, but for a
+// captured desktop JPEG: a chromeless glass panel showing the image, with a
+// corner BADGE naming the source machine ("panda", "chicken") in the same
+// HUD-chip style as the other viewers. Esc or ⌘W dismisses.
+//
+// How it gets asked: `frame <machine> --preview` (or `frame view <machine>`)
+// pulls the frame, writes the JPEG to ~/.local/share/slab/frames/<machine>.jpg
+// like always, then appends "path\tmachine" to $SLAB_HOME/state/open-frame.
+// The menubar's 2 s tick consumes that file on the main thread (tiny stat —
+// no shell-outs, per slab-menubar-perf) and raises one panel per machine.
+// Re-pulling the same machine brings its window forward and reloads the image
+// in place, so a `frame chicken --preview` loop feels live (the controller
+// keeps overwriting the same <machine>.jpg path).
+//
+// Unlike video/pdf, the badge is the MACHINE name, not a Claude session emoji:
+// a `frame` is fundamentally "which Mac am I looking at", so the fleet identity
+// leads. (A session emoji could ride alongside later, but the machine is the
+// load-bearing label here.)
+import AppKit
+
+extension Paths {
+    /// One "path\tmachine" line per pulled frame; consumed each tick.
+    static var frameRequestFile: String { "\(slabHome)/state/open-frame" }
+}
+
+final class FramePreview {
+    static let shared = FramePreview()
+    /// Keyed by MACHINE name (not path): one window per fleet Mac, re-pulled
+    /// in place. The path may even stay constant across pulls (the controller
+    /// overwrites <machine>.jpg), so the machine is the stable identity.
+    private var controllers: [String: FrameWindowController] = [:]
+
+    var openMachines: [String] { controllers.keys.sorted() }
+
+    /// Called from the main-thread side of AppDelegate.refresh() every tick.
+    /// Request lines are "path\tmachine"; an empty machine falls back to the
+    /// file's basename so a bare path still labels something sensible.
+    func consumeRequests() {
+        let file = Paths.frameRequestFile
+        guard FileManager.default.fileExists(atPath: file) else { return }
+        let text = (try? String(contentsOfFile: file, encoding: .utf8)) ?? ""
+        try? FileManager.default.removeItem(atPath: file)
+        for line in text.split(separator: "\n") {
+            let parts = line.split(separator: "\t", maxSplits: 1, omittingEmptySubsequences: false)
+            let path = parts[0].trimmingCharacters(in: .whitespaces)
+            var machine = parts.count > 1 ? parts[1].trimmingCharacters(in: .whitespaces) : ""
+            if machine.isEmpty {
+                machine = ((path as NSString).lastPathComponent as NSString).deletingPathExtension
+            }
+            if !path.isEmpty { open(path, machine: machine) }
+        }
+    }
+
+    func open(_ rawPath: String, machine: String) {
+        let path = (rawPath as NSString).expandingTildeInPath
+        if let existing = controllers[machine] { existing.focusAndReload(path: path); return }
+        guard FileManager.default.fileExists(atPath: path),
+              let controller = FrameWindowController(path: path, machine: machine, onClose: { [weak self] in
+                  self?.controllers.removeValue(forKey: machine)
+              })
+        else { return }
+        controllers[machine] = controller
+        controller.focus()
+    }
+
+    func focus(_ machine: String) { controllers[machine]?.focus() }
+
+    func closeAll() {
+        // close() triggers onClose which mutates the dictionary — iterate a copy.
+        for controller in Array(controllers.values) { controller.close() }
+    }
+}
+
+/// One panel per machine. Owns the NSImageView, the machine badge, and a file
+/// monitor that reloads the image when the JPEG is rewritten on disk (the
+/// controller overwrites <machine>.jpg on each pull).
+private final class FrameWindowController: NSObject, NSWindowDelegate {
+    private var path: String
+    private let machine: String
+    private let panel: FramePanel
+    private let imageView = DraggableFrameImageView()
+    private let onClose: () -> Void
+    private var monitor: DispatchSourceFileSystemObject?
+    private var reloadPending = false
+
+    init?(path: String, machine: String, onClose: @escaping () -> Void) {
+        guard let image = NSImage(contentsOfFile: path) else { return nil }
+        self.path = path
+        self.machine = machine
+        self.onClose = onClose
+
+        panel = FramePanel(
+            contentRect: FrameWindowController.idealFrame(for: image),
+            styleMask: [.titled, .closable, .resizable, .fullSizeContentView],
+            backing: .buffered, defer: false)
+        super.init()
+
+        panel.titleVisibility = .hidden
+        panel.titlebarAppearsTransparent = true
+        panel.isMovableByWindowBackground = true
+        panel.standardWindowButton(.miniaturizeButton)?.isHidden = true
+        panel.standardWindowButton(.zoomButton)?.isHidden = true
+        panel.isFloatingPanel = false
+        panel.hidesOnDeactivate = false
+        panel.isReleasedWhenClosed = false
+        panel.delegate = self
+        panel.title = machine // for Mission Control, not chrome
+        panel.isOpaque = false
+        panel.backgroundColor = .black
+
+        let content = panel.contentView!
+        imageView.image = image
+        imageView.imageScaling = .scaleProportionallyUpOrDown
+        imageView.imageAlignment = .alignCenter
+        // A glance pane, not an editor: any drag moves the window (matches
+        // DraggablePdfView's "click-drag relocates" feel).
+        imageView.translatesAutoresizingMaskIntoConstraints = false
+        content.addSubview(imageView)
+
+        NSLayoutConstraint.activate([
+            imageView.topAnchor.constraint(equalTo: content.topAnchor),
+            imageView.bottomAnchor.constraint(equalTo: content.bottomAnchor),
+            imageView.leadingAnchor.constraint(equalTo: content.leadingAnchor),
+            imageView.trailingAnchor.constraint(equalTo: content.trailingAnchor),
+        ])
+        installBadge()
+        watchFile()
+    }
+
+    // MARK: badge — the source machine name, leading the corner
+
+    /// A HUD chip in the top-left (the other viewers chip top-right with a
+    /// filename; the machine is the headline here so it leads at the corner
+    /// the eye lands on first). Style — hudWindow material, 8pt radius,
+    /// monospaced — matches PdfViewer/VideoViewer so a wall of slab panels
+    /// reads as one family.
+    private func installBadge() {
+        let chip = NSVisualEffectView()
+        chip.material = .hudWindow
+        chip.blendingMode = .withinWindow
+        chip.state = .active
+        chip.wantsLayer = true
+        chip.layer?.cornerRadius = 8
+        chip.translatesAutoresizingMaskIntoConstraints = false
+
+        // The machine name in bold so it carries as a label from across the
+        // room — this IS the answer to "whose screen is this".
+        let name = NSTextField(labelWithString: machine)
+        name.font = .monospacedSystemFont(ofSize: 12, weight: .semibold)
+        name.textColor = .labelColor
+        name.lineBreakMode = .byTruncatingMiddle
+        name.translatesAutoresizingMaskIntoConstraints = false
+        name.toolTip = path
+
+        chip.addSubview(name)
+        // The chip must be IN the hierarchy before any chip↔content
+        // constraint activates, or AppKit throws (no common ancestor).
+        let content = panel.contentView!
+        content.addSubview(chip)
+        NSLayoutConstraint.activate([
+            chip.leadingAnchor.constraint(equalTo: content.leadingAnchor, constant: 12),
+            chip.topAnchor.constraint(equalTo: content.topAnchor, constant: 10),
+            name.leadingAnchor.constraint(equalTo: chip.leadingAnchor, constant: 10),
+            name.trailingAnchor.constraint(equalTo: chip.trailingAnchor, constant: -10),
+            name.centerYAnchor.constraint(equalTo: chip.centerYAnchor),
+            name.widthAnchor.constraint(lessThanOrEqualToConstant: 280),
+            chip.heightAnchor.constraint(equalToConstant: 24),
+        ])
+    }
+
+    // MARK: live reload — re-pulls rewrite the JPEG in place
+
+    private func watchFile() {
+        let fd = Darwin.open(path, O_EVTONLY)
+        guard fd >= 0 else { return }
+        let source = DispatchSource.makeFileSystemObjectSource(
+            fileDescriptor: fd, eventMask: [.write, .rename, .delete, .extend],
+            queue: .main)
+        source.setEventHandler { [weak self] in self?.scheduleReload() }
+        source.setCancelHandler { Darwin.close(fd) }
+        source.resume()
+        monitor = source
+    }
+
+    /// `frame.mjs` writes the JPEG with a single writeFileSync (not atomic
+    /// rename), so a write can land mid-flight — debounce briefly, then reload
+    /// from disk. Re-arm the watcher after (a rename invalidates the fd).
+    private func scheduleReload() {
+        if reloadPending { return }
+        reloadPending = true
+        monitor?.cancel()
+        monitor = nil
+        DispatchQueue.main.asyncAfter(deadline: .now() + 0.3) { [weak self] in
+            guard let self = self else { return }
+            self.reloadPending = false
+            guard FileManager.default.fileExists(atPath: self.path) else { return }
+            if let fresh = NSImage(contentsOfFile: self.path) {
+                self.imageView.image = fresh
+            }
+            self.watchFile()
+        }
+    }
+
+    // MARK: window plumbing
+
+    func focus() {
+        NSApp.activate(ignoringOtherApps: true)
+        panel.makeKeyAndOrderFront(nil)
+    }
+
+    /// Re-pull of an already-open machine: swap to the new path (usually the
+    /// same <machine>.jpg), reload the image, re-arm the watcher, and raise.
+    func focusAndReload(path newPath: String) {
+        if newPath != path {
+            monitor?.cancel()
+            monitor = nil
+            path = newPath
+            watchFile()
+        }
+        if let fresh = NSImage(contentsOfFile: path) { imageView.image = fresh }
+        focus()
+    }
+
+    func close() { panel.close() }
+
+    func windowWillClose(_ notification: Notification) {
+        monitor?.cancel()
+        monitor = nil
+        onClose()
+    }
+
+    /// Size the window to the image's aspect, ~3/4 of the screen tall (matches
+    /// the pdf/video viewers' framing).
+    private static func idealFrame(for image: NSImage) -> NSRect {
+        let screen = NSScreen.main?.visibleFrame
+            ?? NSRect(x: 0, y: 0, width: 1440, height: 900)
+        let size = image.size.width > 0 && image.size.height > 0
+            ? image.size : NSSize(width: 1568, height: 980)
+        let aspect = size.width / max(size.height, 1)
+        var height = min(screen.height * 0.78, 980)
+        var width = height * aspect
+        if width > screen.width * 0.85 {
+            width = screen.width * 0.85
+            height = width / max(aspect, 0.001)
+        }
+        return NSRect(x: screen.midX - width / 2, y: screen.midY - height / 2,
+                      width: width, height: height)
+    }
+}
+
+/// A glance pane: any click-drag on the image moves the WINDOW (no selection),
+/// matching DraggablePdfView. Esc/⌘W dismiss.
+private final class DraggableFrameImageView: NSImageView {
+    override func mouseDown(with event: NSEvent) { window?.performDrag(with: event) }
+}
+
+/// Titled-but-chromeless panel: key-able so Esc works, and Esc
+/// (cancelOperation) closes — the "just glance and dismiss" contract.
+private final class FramePanel: NSPanel {
+    override var canBecomeKey: Bool { true }
+    override var canBecomeMain: Bool { true }
+    override func cancelOperation(_ sender: Any?) { close() }
+}
+
+// MARK: - menu management (slab manages the viewers)
+
+extension AppDelegate {
+    @objc func focusFrame(_ sender: NSMenuItem) {
+        if let machine = sender.representedObject as? String { FramePreview.shared.focus(machine) }
+    }
+
+    @objc func closeAllFrames() { FramePreview.shared.closeAll() }
+}
-- 
2.51.2


From 5b42c1ee4b787c41d3298208b1fda9b806be0e8c Mon Sep 17 00:00:00 2001
From: "prompt.ac/@jeffrey" <mail@aesthetic.computer>
Date: Wed, 17 Jun 2026 19:45:12 -0700
Subject: [PATCH 13/13] FramePreview: open small + resizable, image
 aspect-fits, badge pinned

The frame panel was sizing by screen height like the portrait pdf/video
viewers, but a frame is a LANDSCAPE desktop (~1568x882) so it spanned the
display. Worse, NSImageView's intrinsicContentSize is the image's pixel
size, which (with the edge-pinned constraints) dragged the window out to
the native frame size regardless of the contentRect.

- idealFrame: target a small default WIDTH (~38% screen, 640pt floor,
  60% cap), derive height from the frame aspect, clamp height to 60% of
  screen, and corner-anchor top-right with a 24pt inset (no full-bleed).
- Drop the imageView's content hugging + compression resistance to
  .defaultLow so it no longer forces the window to the native pixel size;
  the image just scales to fit (.scaleProportionallyUpOrDown).
- panel.minSize + contentAspectRatio so drag-resize scales the image and
  keeps the frame's proportions.
- isRestorable = false so a stale saved frame (e.g. from a since-
  disconnected display) can't override the small default.

Badge stays corner-pinned (fixed-height leading/top constraints) and all
existing behavior (live reload, per-machine keying, Esc/Cmd-W, glass) is
unchanged. Verified on neo against chicken: opens 640x360, resizes with
aspect held, 'chicken' badge stays top-left.
---
 .../Sources/SlabMenubar/FramePreview.swift    | 55 +++++++++++++++----
 1 file changed, 45 insertions(+), 10 deletions(-)

diff --git a/slab/menubar-swift/Sources/SlabMenubar/FramePreview.swift b/slab/menubar-swift/Sources/SlabMenubar/FramePreview.swift
index b0c857c2e..dad651175 100644
--- a/slab/menubar-swift/Sources/SlabMenubar/FramePreview.swift
+++ b/slab/menubar-swift/Sources/SlabMenubar/FramePreview.swift
@@ -105,10 +105,19 @@ private final class FrameWindowController: NSObject, NSWindowDelegate {
         panel.isFloatingPanel = false
         panel.hidesOnDeactivate = false
         panel.isReleasedWhenClosed = false
+        // Always open at our computed small size — never let AppKit restore a
+        // stale saved frame (e.g. a size from a since-disconnected display).
+        panel.isRestorable = false
         panel.delegate = self
         panel.title = machine // for Mission Control, not chrome
         panel.isOpaque = false
         panel.backgroundColor = .black
+        // Resizable, but with a sane floor and aspect locked to the frame so a
+        // drag-resize scales the image rather than letterboxing it.
+        panel.minSize = NSSize(width: 280, height: 160)
+        if image.size.width > 0 && image.size.height > 0 {
+            panel.contentAspectRatio = image.size
+        }
 
         let content = panel.contentView!
         imageView.image = image
@@ -117,6 +126,15 @@ private final class FrameWindowController: NSObject, NSWindowDelegate {
         // A glance pane, not an editor: any drag moves the window (matches
         // DraggablePdfView's "click-drag relocates" feel).
         imageView.translatesAutoresizingMaskIntoConstraints = false
+        // NSImageView's intrinsicContentSize is the IMAGE's pixel size; with the
+        // edge-pinned constraints below that would drag the window out to the
+        // native ~1568px frame, overriding our small contentRect. Drop hugging
+        // and compression resistance so the window keeps the size we ask for and
+        // the image just scales to fit (aspect via .scaleProportionallyUpOrDown).
+        imageView.setContentHuggingPriority(.defaultLow, for: .horizontal)
+        imageView.setContentHuggingPriority(.defaultLow, for: .vertical)
+        imageView.setContentCompressionResistancePriority(.defaultLow, for: .horizontal)
+        imageView.setContentCompressionResistancePriority(.defaultLow, for: .vertical)
         content.addSubview(imageView)
 
         NSLayoutConstraint.activate([
@@ -231,22 +249,39 @@ private final class FrameWindowController: NSObject, NSWindowDelegate {
         onClose()
     }
 
-    /// Size the window to the image's aspect, ~3/4 of the screen tall (matches
-    /// the pdf/video viewers' framing).
+    /// Open SMALL: a glance pane, not a takeover. A frame is usually a
+    /// LANDSCAPE desktop (~1568×882), so sizing by height like the portrait
+    /// pdf/video viewers would make it span the screen. Instead start from a
+    /// modest target WIDTH (~38% of the screen, ~640pt floor) and derive height
+    /// from the image aspect, then clamp both axes so it never dominates the
+    /// display. The window is `.resizable`, the imageView aspect-fits
+    /// (`.scaleProportionallyUpOrDown`), and the badge is corner-pinned — so
+    /// the user can drag it to any size and the image scales while the chip
+    /// stays put. Anchored to the top-right corner (not centered/full-bleed).
     private static func idealFrame(for image: NSImage) -> NSRect {
         let screen = NSScreen.main?.visibleFrame
             ?? NSRect(x: 0, y: 0, width: 1440, height: 900)
         let size = image.size.width > 0 && image.size.height > 0
-            ? image.size : NSSize(width: 1568, height: 980)
+            ? image.size : NSSize(width: 1568, height: 882)
         let aspect = size.width / max(size.height, 1)
-        var height = min(screen.height * 0.78, 980)
-        var width = height * aspect
-        if width > screen.width * 0.85 {
-            width = screen.width * 0.85
-            height = width / max(aspect, 0.001)
+
+        // Target a small default width, with a sensible floor and a cap that
+        // keeps the whole window comfortably inside the screen.
+        var width = min(max(screen.width * 0.38, 640), screen.width * 0.6)
+        var height = width / max(aspect, 0.001)
+        // Don't let a tall/square frame run off the bottom either.
+        let maxHeight = screen.height * 0.6
+        if height > maxHeight {
+            height = maxHeight
+            width = height * aspect
         }
-        return NSRect(x: screen.midX - width / 2, y: screen.midY - height / 2,
-                      width: width, height: height)
+
+        // Corner-anchor (top-right) with a small inset — visible but not
+        // full-bleed, and out from under the menubar piano.
+        let inset: CGFloat = 24
+        let x = screen.maxX - width - inset
+        let y = screen.maxY - height - inset
+        return NSRect(x: x, y: y, width: width, height: height)
     }
 }