simframe 0.1.0

package/src/daemon.js

@@ -0,0 +1,170 @@
+// The capture loop. Runs detached, one process per simulator, and keeps the
+// newest frame permanently warm on disk so a reader never waits on simctl.
+import fs from 'node:fs';
+import path from 'node:path';
+import { decodePng } from './png.js';
+import { frameHash, regionSignature, signatureDiff, regionDeltas } from './analyze.js';
+import * as store from './store.js';
+import { isBootedSync, resize, screenshot } from './simctl.js';
+
+// Bump whenever the shape of state.json changes, so an upgraded client retires
+// a capture loop left running by an older install instead of misreading it.
+export const STATE_VERSION = 2;
+
+export const DEFAULTS = {
+  fps: 4,
+  idleFps: 1.5,
+  idleAfterMs: 2500,
+  maxDim: 700,
+  ringSize: 24,
+  fullKeep: 3,
+  changeThreshold: 0.004,
+  idleExitMs: 15 * 60_000,
+};
+
+const BOOT_CHECK_MS = 5000;
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+export async function runDaemon(device, options = {}) {
+  const opts = { ...DEFAULTS, ...options };
+  const udid = device.udid;
+  const p = store.ensureDirs(udid);
+
+  // Exactly one loop may own a device: two loops would both write ring/1.png
+  // and prune each other's frames. meta.json is the ownership record.
+  const incumbent = store.readJson(p.meta);
+  if (
+    incumbent?.pid &&
+    incumbent.pid !== process.pid &&
+    incumbent.version === STATE_VERSION &&
+    store.isProcessAlive(incumbent.pid)
+  ) {
+    return { started: false, reason: `already captured by pid ${incumbent.pid}` };
+  }
+
+  store.writeAtomic(
+    p.meta,
+    JSON.stringify(
+      { pid: process.pid, device, options: opts, startedAt: Date.now(), version: STATE_VERSION },
+      null,
+      2,
+    ),
+  );
+
+  let seq = 0;
+  let prevSignature = null;
+  let lastChangeAt = Date.now();
+  let consecutiveErrors = 0;
+  let lastBootCheck = Date.now();
+  let running = true;
+  const stop = () => {
+    running = false;
+  };
+  process.on('SIGTERM', stop);
+  process.on('SIGINT', stop);
+
+  const log = (msg) => {
+    try {
+      fs.appendFileSync(p.log, `${new Date().toISOString()} ${msg}\n`);
+    } catch {
+      /* logging is best effort */
+    }
+  };
+  log(`start pid=${process.pid} device=${device.name} udid=${udid}`);
+
+  while (running) {
+    const tickStart = Date.now();
+
+    if (store.heartbeatAge(udid) > opts.idleExitMs) {
+      log('exit: no client heartbeat');
+      break;
+    }
+    // Checking the boot state means shelling out to simctl, which costs more
+    // than a capture does; every few seconds is soon enough to notice a shutdown.
+    if (tickStart - lastBootCheck > BOOT_CHECK_MS) {
+      lastBootCheck = tickStart;
+      if (store.readJson(p.meta)?.pid !== process.pid) {
+      log('exit: superseded by another capture loop');
+      break;
+    }
+    if (!isBootedSync(udid)) {
+        log('exit: device is no longer booted');
+        break;
+      }
+    }
+
+    try {
+      const nextSeq = seq + 1;
+      const fullFile = path.join(p.full, `${nextSeq}.png`);
+      const ringFile = path.join(p.ring, `${nextSeq}.png`);
+      await screenshot(udid, fullFile, { mask: 'ignored' });
+      await resize(fullFile, ringFile, opts.maxDim);
+
+      const bmp = decodePng(fs.readFileSync(ringFile));
+      const signature = regionSignature(bmp);
+      const diff = signatureDiff(signature, prevSignature);
+      const deltas = regionDeltas(signature, prevSignature);
+      const changed = diff > opts.changeThreshold;
+      const now = Date.now();
+      if (changed || prevSignature === null) lastChangeAt = now;
+
+      seq = nextSeq;
+      prevSignature = signature;
+      consecutiveErrors = 0;
+
+      fs.copyFileSync(ringFile, path.join(p.dir, 'latest.png.tmp'));
+      fs.renameSync(path.join(p.dir, 'latest.png.tmp'), path.join(p.dir, 'latest.png'));
+
+      store.writeAtomic(
+        p.state,
+        JSON.stringify({
+          seq,
+          capturedAt: now,
+          captureMs: now - tickStart,
+          width: bmp.width,
+          height: bmp.height,
+          hash: frameHash(bmp),
+          diff: Number(diff.toFixed(5)),
+          changed,
+          stableForMs: now - lastChangeAt,
+          regions: deltas.map((d) => Number(d.toFixed(4))),
+          fullFile,
+          ringFile,
+          device,
+        }),
+      );
+
+      store.pruneDir(p.ring, opts.ringSize);
+      store.pruneDir(p.full, opts.fullKeep);
+    } catch (err) {
+      consecutiveErrors++;
+      log(`capture error (${consecutiveErrors}): ${err.message}`);
+      if (consecutiveErrors >= 10) {
+        log('exit: too many consecutive capture errors');
+        break;
+      }
+      await sleep(Math.min(5000, 250 * consecutiveErrors));
+      continue;
+    }
+
+    // Back off while the screen sits still, and snap back the moment it moves.
+    const idle = Date.now() - lastChangeAt > opts.idleAfterMs;
+    const interval = 1000 / (idle ? opts.idleFps : opts.fps);
+    const wait = interval - (Date.now() - tickStart);
+    if (wait > 0) await sleep(wait);
+  }
+
+  log('stopped');
+  const outcome = { started: true };
+  try {
+    // A replacement loop may already have registered itself while this one was
+    // winding down; only deregister if meta.json still points at us.
+    const meta = store.readJson(p.meta);
+    if (meta?.pid === process.pid) {
+      store.writeAtomic(p.meta, JSON.stringify({ ...meta, pid: null, stoppedAt: Date.now() }, null, 2));
+    }
+  } catch {
+    /* nothing useful to do on the way out */
+  }
+  return outcome;
+}

package/src/index.js

@@ -0,0 +1,271 @@
+// Client API shared by the CLI and the MCP server.
+import { spawn } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { DEFAULTS, STATE_VERSION } from './daemon.js';
+import { decodePng, encodePng, scaleBitmap } from './png.js';
+import { REGION_COLS, regionMap } from './analyze.js';
+import { resolveDevice, resize } from './simctl.js';
+import * as store from './store.js';
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const CLI = path.join(HERE, 'cli.js');
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+export const DETAIL_LEVELS = { low: 420, normal: 700, high: 1100, full: 0 };
+
+export function resolveMaxDim(detail) {
+  if (typeof detail === 'number') return detail;
+  if (detail && detail in DETAIL_LEVELS) return DETAIL_LEVELS[detail];
+  return DETAIL_LEVELS.normal;
+}
+
+export function daemonStatus(udid) {
+  const meta = store.readJson(store.paths(udid).meta);
+  const pid = meta?.pid ?? null;
+  const running = store.isProcessAlive(pid);
+  const stale = running && meta?.version !== STATE_VERSION;
+  // A loop from an older install is treated as not usable, so callers replace it.
+  return { meta, pid, running, stale, alive: running && !stale };
+}
+
+/**
+ * Make sure a capture loop is running for `deviceQuery`, then return once a
+ * frame is actually available. Safe to call on every request: it is a stat
+ * when the daemon is already up.
+ */
+export async function ensureDaemon(deviceQuery, options = {}) {
+  const device = await resolveDevice(deviceQuery);
+  const p = store.ensureDirs(device.udid);
+  store.touchHeartbeat(device.udid);
+
+  const existing = daemonStatus(device.udid);
+  if (existing.stale) stopDaemon(device.udid);
+  // A dead daemon leaves its last state.json behind. Anything captured before
+  // we (re)started the loop is not evidence of a live screen, so ignore it.
+  const minCapturedAt = existing.alive ? 0 : Date.now();
+  if (!existing.alive) {
+    if (acquireSpawnLock(p.lock)) {
+      try {
+        spawnDaemon(device.udid, options);
+      } finally {
+        // Hold the lock briefly so a burst of callers does not double-spawn.
+        setTimeout(() => releaseSpawnLock(p.lock), 1500).unref?.();
+      }
+    }
+  }
+
+  const deadline = Date.now() + (options.readyTimeoutMs ?? 8000);
+  while (Date.now() < deadline) {
+    const state = store.readJson(p.state);
+    if (state && state.capturedAt >= minCapturedAt && Date.now() - state.capturedAt < 30_000) {
+      return { device, state, started: !existing.alive };
+    }
+    await sleep(80);
+  }
+  const tail = readLogTail(p.log);
+  throw new Error(`simframe daemon did not produce a frame for ${device.name}${tail ? `\n${tail}` : ''}`);
+}
+
+function spawnDaemon(udid, options) {
+  const args = [CLI, 'daemon', udid];
+  for (const key of ['fps', 'maxDim', 'ringSize', 'idleExitMs']) {
+    if (options[key] != null) args.push(`--${key}=${options[key]}`);
+  }
+  const child = spawn(process.execPath, args, {
+    detached: true,
+    stdio: 'ignore',
+    env: process.env,
+  });
+  child.unref();
+}
+
+function acquireSpawnLock(lockFile) {
+  try {
+    fs.writeFileSync(lockFile, String(process.pid), { flag: 'wx' });
+    return true;
+  } catch {
+    const holder = Number(safeRead(lockFile));
+    if (holder && !store.isProcessAlive(holder)) {
+      try {
+        fs.unlinkSync(lockFile);
+        fs.writeFileSync(lockFile, String(process.pid), { flag: 'wx' });
+        return true;
+      } catch {
+        return false;
+      }
+    }
+    return false;
+  }
+}
+
+function releaseSpawnLock(lockFile) {
+  try {
+    if (safeRead(lockFile) === String(process.pid)) fs.unlinkSync(lockFile);
+  } catch {
+    /* a stale lock is reclaimed by the next caller */
+  }
+}
+
+function safeRead(file) {
+  try {
+    return fs.readFileSync(file, 'utf8');
+  } catch {
+    return '';
+  }
+}
+
+function readLogTail(file, lines = 6) {
+  return safeRead(file).trim().split('\n').slice(-lines).join('\n');
+}
+
+export function stopDaemon(udid) {
+  const { pid, running } = daemonStatus(udid);
+  if (!running) return false;
+  try {
+    process.kill(pid, 'SIGTERM');
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** The warm read: newest frame as PNG bytes, with no capture in the request path. */
+export async function getFrame(deviceQuery, { detail = 'normal', options } = {}) {
+  const { device, state } = await ensureDaemon(deviceQuery, options);
+  const p = store.paths(device.udid);
+  const maxDim = resolveMaxDim(detail);
+  const nativeMax = Math.max(state.width, state.height);
+
+  let file = path.join(p.dir, 'latest.png');
+  let scaledOnRead = false;
+  if (maxDim === 0) {
+    file = state.fullFile;
+  } else if (maxDim > nativeMax + 8 && fs.existsSync(state.fullFile)) {
+    const out = path.join(p.dir, `read-${maxDim}.png`);
+    await resize(state.fullFile, out, maxDim);
+    file = out;
+    scaledOnRead = true;
+  } else if (maxDim < nativeMax - 8) {
+    const out = path.join(p.dir, `read-${maxDim}.png`);
+    await resize(path.join(p.dir, 'latest.png'), out, maxDim);
+    file = out;
+    scaledOnRead = true;
+  }
+
+  const png = fs.readFileSync(file);
+  const bmp = pngSize(png);
+  return {
+    device,
+    state,
+    png,
+    width: bmp.width,
+    height: bmp.height,
+    ageMs: Date.now() - state.capturedAt,
+    scaledOnRead,
+  };
+}
+
+function pngSize(png) {
+  return { width: png.readUInt32BE(16), height: png.readUInt32BE(20) };
+}
+
+export async function getState(deviceQuery, { options } = {}) {
+  const { device, state } = await ensureDaemon(deviceQuery, options);
+  return {
+    device,
+    state,
+    ageMs: Date.now() - state.capturedAt,
+    map: regionMap(state.regions || [], REGION_COLS),
+  };
+}
+
+/**
+ * Wait for the screen to settle (`mode: 'stable'`) or to move away from what it
+ * shows right now (`mode: 'change'`). Removes the screenshot-retry loop.
+ */
+export async function waitFor(
+  deviceQuery,
+  { mode = 'stable', stableMs = 600, timeoutMs = 8000, baselineHash, options } = {},
+) {
+  const { device, state: first } = await ensureDaemon(deviceQuery, options);
+  const p = store.paths(device.udid);
+  const baseline = baselineHash || first.hash;
+  const deadline = Date.now() + timeoutMs;
+  let last = first;
+
+  while (Date.now() < deadline) {
+    const state = store.readJson(p.state);
+    if (state) {
+      last = state;
+      if (mode === 'change') {
+        if (state.hash !== baseline) return { device, state, satisfied: true, mode, waitedMs: timeoutMs - (deadline - Date.now()) };
+      } else if (state.stableForMs >= stableMs) {
+        return { device, state, satisfied: true, mode, waitedMs: timeoutMs - (deadline - Date.now()) };
+      }
+    }
+    await sleep(60);
+  }
+  return { device, state: last, satisfied: false, mode, waitedMs: timeoutMs };
+}
+
+/**
+ * Tile the most recent frames into one image. A transition or animation becomes
+ * legible in a single tool call instead of a sequence of them.
+ */
+export async function getStrip(deviceQuery, { count = 5, spanMs, thumbMaxDim = 240, options } = {}) {
+  const { device } = await ensureDaemon(deviceQuery, options);
+  const p = store.paths(device.udid);
+  let entries = fs
+    .readdirSync(p.ring)
+    .filter((n) => n.endsWith('.png'))
+    .map((n) => ({ seq: parseInt(n, 10), file: path.join(p.ring, n) }))
+    .filter((e) => Number.isFinite(e.seq))
+    .sort((a, b) => a.seq - b.seq);
+
+  entries = entries.map((e) => ({ ...e, mtimeMs: safeMtime(e.file) })).filter((e) => e.mtimeMs);
+  if (spanMs) {
+    const cutoff = Date.now() - spanMs;
+    const within = entries.filter((e) => e.mtimeMs >= cutoff);
+    if (within.length) entries = within;
+  }
+  entries = entries.slice(-Math.max(1, count));
+  if (!entries.length) throw new Error('no frames buffered yet');
+
+  const frames = entries.map((e) => decodePng(fs.readFileSync(e.file)));
+  const ratio = frames[0].height / frames[0].width;
+  const tw = Math.max(40, Math.round(thumbMaxDim / Math.max(1, ratio)));
+  const th = Math.round(tw * ratio);
+  const gap = 6;
+  const width = frames.length * tw + gap * (frames.length - 1);
+  const sheet = { width, height: th, data: Buffer.alloc(width * th * 4, 0) };
+
+  frames.forEach((frame, i) => {
+    const thumb = scaleBitmap(frame, tw, th);
+    const x0 = i * (tw + gap);
+    for (let y = 0; y < th; y++) {
+      thumb.data.copy(sheet.data, (y * width + x0) * 4, y * tw * 4, (y + 1) * tw * 4);
+    }
+  });
+
+  const t0 = entries[0].mtimeMs;
+  return {
+    device,
+    png: encodePng(sheet),
+    width,
+    height: th,
+    frames: entries.map((e) => ({ seq: e.seq, offsetMs: Math.round(e.mtimeMs - t0) })),
+    spanMs: Math.round(entries[entries.length - 1].mtimeMs - t0),
+  };
+}
+
+function safeMtime(file) {
+  try {
+    return fs.statSync(file).mtimeMs;
+  } catch {
+    return 0;
+  }
+}
+
+export { DEFAULTS, store };

package/src/mcp.js

@@ -0,0 +1,258 @@
+// MCP server. The point of every tool here is that the expensive part
+// (capturing) already happened in the background, so a call is a file read.
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+} from '@modelcontextprotocol/sdk/types.js';
+import fs from 'node:fs';
+import { REGION_COLS, REGION_ROWS, regionMap } from './analyze.js';
+import * as api from './index.js';
+import { bootedDevices } from './simctl.js';
+import * as store from './store.js';
+
+const deviceProp = {
+  device: {
+    type: 'string',
+    description: 'Simulator UDID or name substring. Defaults to the booted simulator.',
+  },
+};
+
+const TOOLS = [
+  {
+    name: 'sim_look',
+    description:
+      'Look at the iOS Simulator screen right now. Returns the newest buffered frame immediately — a background capture loop keeps it warm, so there is no screenshot wait. Use this instead of taking a screenshot. Prefer detail "low" for layout checks and "high" only when you must read small text.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        ...deviceProp,
+        detail: {
+          type: 'string',
+          enum: ['low', 'normal', 'high', 'full'],
+          description:
+            'Image size: low (~420px, cheapest), normal (~700px, default), high (~1100px, readable small text), full (native resolution).',
+        },
+        maxAgeMs: {
+          type: 'number',
+          description:
+            'If the buffered frame is older than this, wait for a fresher one (default 900).',
+        },
+      },
+    },
+  },
+  {
+    name: 'sim_state',
+    description:
+      'Cheap TEXT-ONLY check of what the simulator screen is doing: a stable screen hash, how long it has been still, how much changed since the last frame, and an ASCII map of which regions moved. Costs a tiny fraction of an image. Use this to poll ("has it finished loading?", "did my tap do anything?") and only call sim_look when you actually need to see pixels.',
+    inputSchema: { type: 'object', properties: { ...deviceProp } },
+  },
+  {
+    name: 'sim_wait',
+    description:
+      'Block until the simulator screen settles (mode "stable") or until it changes away from what it shows now (mode "change"), then return the frame. Use this after a tap, launch or navigation instead of screenshotting repeatedly and hoping the animation finished.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        ...deviceProp,
+        mode: {
+          type: 'string',
+          enum: ['stable', 'change'],
+          description: 'stable: wait for the screen to stop moving. change: wait for it to differ from now.',
+        },
+        stableMs: { type: 'number', description: 'How long the screen must hold still for mode "stable" (default 600).' },
+        timeoutMs: { type: 'number', description: 'Give up after this long (default 8000).' },
+        includeImage: { type: 'boolean', description: 'Attach the resulting frame as an image (default true).' },
+        detail: { type: 'string', enum: ['low', 'normal', 'high', 'full'] },
+      },
+    },
+  },
+  {
+    name: 'sim_strip',
+    description:
+      'Return the last few buffered frames tiled into ONE image, left to right, oldest first. Lets you understand a transition, animation or flicker in a single call instead of a burst of screenshots. Frames are already buffered, so this looks backwards in time — it does not wait.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        ...deviceProp,
+        count: { type: 'number', description: 'How many frames to tile (default 5, max 12).' },
+        spanMs: { type: 'number', description: 'Only include frames from the last N milliseconds.' },
+        thumbMaxDim: { type: 'number', description: 'Height budget per frame in pixels (default 240).' },
+      },
+    },
+  },
+  {
+    name: 'sim_capture',
+    description:
+      'Inspect or control the background capture loops: action "status" (what is running and how fresh), "start", "stop". Capture starts automatically on first use, so you rarely need this.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        action: { type: 'string', enum: ['status', 'start', 'stop'] },
+        ...deviceProp,
+        fps: { type: 'number', description: 'Capture rate while the screen is moving (default 4).' },
+      },
+      required: ['action'],
+    },
+  },
+  {
+    name: 'sim_devices',
+    description: 'List booted iOS simulators that simframe can capture.',
+    inputSchema: { type: 'object', properties: {} },
+  },
+];
+
+const text = (s) => ({ type: 'text', text: s });
+const image = (png) => ({ type: 'image', data: png.toString('base64'), mimeType: 'image/png' });
+
+function header(device, state, ageMs, extra = '') {
+  return (
+    `${device.name} · ${device.runtime} · frame #${state.seq} · ${ageMs}ms old · ` +
+    `${state.width}x${state.height} · still for ${state.stableForMs}ms${extra ? ` · ${extra}` : ''}`
+  );
+}
+
+export async function serve({ device: defaultDevice, options = {} } = {}) {
+  const server = new Server(
+    { name: 'simframe', version: '0.1.0' },
+    { capabilities: { tools: {} } },
+  );
+
+  server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOLS }));
+
+  server.setRequestHandler(CallToolRequestSchema, async (req) => {
+    const args = req.params.arguments || {};
+    const target = args.device || defaultDevice;
+    try {
+      switch (req.params.name) {
+        case 'sim_look':
+          return await look(target, args, options);
+        case 'sim_state':
+          return await state(target, options);
+        case 'sim_wait':
+          return await wait(target, args, options);
+        case 'sim_strip':
+          return await strip(target, args, options);
+        case 'sim_capture':
+          return await capture(target, args, options);
+        case 'sim_devices':
+          return await devices();
+        default:
+          throw new Error(`unknown tool ${req.params.name}`);
+      }
+    } catch (err) {
+      return { isError: true, content: [text(`simframe: ${err.message}`)] };
+    }
+  });
+
+  await server.connect(new StdioServerTransport());
+}
+
+async function look(target, args, options) {
+  const maxAge = args.maxAgeMs ?? 900;
+  let res = await api.getFrame(target, { detail: args.detail ?? 'normal', options });
+  if (res.ageMs > maxAge) {
+    // Freshness was requested; the loop is already running, so just let it tick.
+    const deadline = Date.now() + Math.min(2000, maxAge * 3);
+    const p = store.paths(res.device.udid);
+    while (Date.now() < deadline) {
+      const next = store.readJson(p.state);
+      if (next && Date.now() - next.capturedAt <= maxAge) break;
+      await new Promise((r) => setTimeout(r, 50));
+    }
+    res = await api.getFrame(target, { detail: args.detail ?? 'normal', options });
+  }
+  return {
+    content: [text(header(res.device, res.state, res.ageMs)), image(res.png)],
+  };
+}
+
+async function state(target, options) {
+  const res = await api.getState(target, { options });
+  const s = res.state;
+  const body = [
+    header(res.device, s, res.ageMs),
+    `screen hash: ${s.hash}   change since previous frame: ${(s.diff * 100).toFixed(1)}%`,
+    s.stableForMs > 1200 ? 'screen is idle' : 'screen is currently changing',
+    `region change map (${REGION_COLS}x${REGION_ROWS}, top-left to bottom-right; "." to "#" = more movement):`,
+    regionMap(s.regions || []),
+  ].join('\n');
+  return { content: [text(body)] };
+}
+
+async function wait(target, args, options) {
+  const res = await api.waitFor(target, {
+    mode: args.mode ?? 'stable',
+    stableMs: args.stableMs ?? 600,
+    timeoutMs: args.timeoutMs ?? 8000,
+    options,
+  });
+  const note = res.satisfied
+    ? `${res.mode === 'change' ? 'screen changed' : 'screen settled'} after ${res.waitedMs}ms`
+    : `TIMED OUT after ${res.waitedMs}ms — screen never ${res.mode === 'change' ? 'changed' : 'settled'}`;
+  const content = [text(`${note}\n${header(res.device, res.state, Date.now() - res.state.capturedAt)}`)];
+  if (args.includeImage !== false) {
+    const frame = await api.getFrame(target, { detail: args.detail ?? 'normal', options });
+    content.push(image(frame.png));
+  }
+  return { content };
+}
+
+async function strip(target, args, options) {
+  const res = await api.getStrip(target, {
+    count: Math.min(12, args.count ?? 5),
+    spanMs: args.spanMs,
+    thumbMaxDim: args.thumbMaxDim ?? 240,
+    options,
+  });
+  const offsets = res.frames.map((f) => `+${f.offsetMs}ms`).join('  ');
+  return {
+    content: [
+      text(
+        `${res.device.name} · ${res.frames.length} frames spanning ${res.spanMs}ms, oldest first\n${offsets}`,
+      ),
+      image(res.png),
+    ],
+  };
+}
+
+async function capture(target, args, options) {
+  if (args.action === 'start') {
+    const res = await api.ensureDaemon(target, { ...options, fps: args.fps ?? options.fps });
+    return {
+      content: [
+        text(
+          `${res.started ? 'started' : 'already running'} — ${res.device.name}, frame #${res.state.seq}`,
+        ),
+      ],
+    };
+  }
+  if (args.action === 'stop') {
+    const udids = target ? [(await api.ensureDaemon(target, options)).device.udid] : listStateDirs();
+    const stopped = udids.filter((u) => api.stopDaemon(u));
+    return { content: [text(`stopped ${stopped.length} capture loop(s)`)] };
+  }
+  const rows = listStateDirs().map((udid) => {
+    const { meta, pid, alive } = api.daemonStatus(udid);
+    const s = store.readJson(store.paths(udid).state);
+    return `${alive ? '●' : '○'} ${meta?.device?.name ?? udid} pid=${pid ?? '-'} frame=#${s?.seq ?? '-'} age=${s ? Date.now() - s.capturedAt : '-'}ms`;
+  });
+  return { content: [text(rows.join('\n') || 'no capture loops running')] };
+}
+
+function listStateDirs() {
+  try {
+    return fs.readdirSync(store.ROOT);
+  } catch {
+    return [];
+  }
+}
+
+async function devices() {
+  const booted = await bootedDevices();
+  if (!booted.length) return { content: [text('no booted simulators')] };
+  return {
+    content: [text(booted.map((d) => `${d.name} · ${d.runtime} · ${d.udid}`).join('\n'))],
+  };
+}