@archastro/astroshot 0.2.0 → 0.2.1

package/README.md

@@ -3,20 +3,35 @@
 One command for deterministic React, Ink, and arbitrary terminal screenshots —
 plus **journey movies** into `.astroshot/`.
 
+## Start here (no prerequisites)
+
+```bash
+# Write a real .astroshot/ set: stills + movie poster/video + manifest.json.
+# No Chromium download, no assets of your own; works with the app closed.
+npx astroshot demo
+
+# Check Node, watched folders, app install/run state, Chromium, and macOS
+# Screen Recording. Each failure prints the exact fix command. Read-only.
+npx astroshot doctor
+```
+
+`demo` accepts `--feature <name>`, `--root <dir>`, and `--json`. `doctor`
+accepts `--root <dir>`, `--json`, and `--skip-screen`, and exits non-zero when a
+required check fails. Watched-folder coverage comes from the Astroshots app's
+own live configuration, so an "empty tray" resolves to one of: first-launch
+setup never completed, this project is outside every watched folder, or the
+project is watched and the problem is elsewhere.
+
+## Capture
+
 ```bash
-npx --@archastro:registry=https://registry.npmjs.org \
-  @archastro/astroshot init react
-npx --@archastro:registry=https://registry.npmjs.org \
-  @archastro/astroshot init ink
-npx --@archastro:registry=https://registry.npmjs.org \
-  @archastro/astroshot init pty
-
-npx --@archastro:registry=https://registry.npmjs.org \
-  @archastro/astroshot react ./react.shot.tsx -o ./react.png
-npx --@archastro:registry=https://registry.npmjs.org \
-  @archastro/astroshot ink ./ink.shot.tsx -o ./ink.png
-npx --@archastro:registry=https://registry.npmjs.org \
-  @archastro/astroshot pty ./pty.shot.yaml -o ./terminal.png
+npx astroshot init react
+npx astroshot init ink
+npx astroshot init pty
+
+npx astroshot react ./react.shot.tsx -o ./react.png
+npx astroshot ink ./ink.shot.tsx -o ./ink.png
+npx astroshot pty ./pty.shot.yaml -o ./terminal.png
 ```
 
 ## Movies (`astroshot movie`)
@@ -57,8 +72,7 @@ npm install --save-dev ink@^7.1 react@^19
 Install the shared Chromium runtime once:
 
 ```bash
-npx --@archastro:registry=https://registry.npmjs.org \
-  @archastro/astroshot install-browser
+npx astroshot install-browser
 ```
 
 Use `react batch <manifest>` or `ink batch <manifest>` for maintained fixture

package/bin/astroshot.mjs

@@ -6,11 +6,15 @@ import { fileURLToPath } from "node:url";
 import path from "node:path";
 
 import { writeFixtureTemplate } from "./templates.mjs";
+import { demoHelp, runDemo } from "./demo.mjs";
+import { doctorHelp, runDoctor } from "./doctor.mjs";
 
 function help() {
   console.log(`astroshot — one CLI for React, Ink, PTY stills, and movies
 
 Usage:
+  astroshot demo [--feature <name>] [--root <dir>]
+  astroshot doctor [--root <dir>] [--json]
   astroshot init react [fixture.tsx] [--force]
   astroshot init ink [fixture.tsx] [--force]
   astroshot init pty [fixture.yaml] [--force]
@@ -23,6 +27,10 @@ Usage:
   astroshot movie <command> [options]
   astroshot install-browser [--with-deps]
 
+Start here:
+  demo               Write a complete .astroshot/ example set (no prerequisites)
+  doctor             Check Node, watched folders, app, Chromium, permissions
+
 Commands:
   react              Capture an isolated React component (still PNG)
   ink                Capture an Ink component fixture (still PNG)
@@ -196,6 +204,28 @@ if (!command || command === "help" || command === "-h" || command === "--help")
   process.exit(command ? 0 : 1);
 }
 
+if (command === "demo") {
+  try {
+    process.exit(runDemo(arguments_));
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : error);
+    console.error("");
+    console.error(demoHelp());
+    process.exit(1);
+  }
+}
+
+if (command === "doctor") {
+  try {
+    process.exit(runDoctor(arguments_));
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : error);
+    console.error("");
+    console.error(doctorHelp());
+    process.exit(1);
+  }
+}
+
 if (command === "install-browser") {
   runEngine("react", ["install-browser", ...arguments_]);
 }

package/bin/demo.mjs

@@ -0,0 +1,275 @@
+/**
+ * `astroshot demo` — seed a real .astroshot/<feature>/ set with zero
+ * prerequisites.
+ *
+ * The payload is bundled PNG/WebM bytes under fixtures/demo/, so this command
+ * needs no managed Chromium, no ffmpeg, and no user-supplied assets. It only
+ * writes files, so it also works while the macOS app is closed; the caller is
+ * told where to look.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { execFileSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+
+import {
+  evaluateWatchCoverage,
+  readWatchConfiguration,
+} from "./mac-preferences.mjs";
+
+const FIXTURES_DIR = fileURLToPath(new URL("../fixtures/demo/", import.meta.url));
+export const DEFAULT_DEMO_FEATURE = "astroshot-demo";
+
+export function demoHelp() {
+  return `astroshot demo — write a complete .astroshot/ example set (no prerequisites)
+
+Usage:
+  astroshot demo [options]
+
+Options:
+  --feature <name>   Feature directory under .astroshot/ (default: ${DEFAULT_DEMO_FEATURE})
+  --root <dir>       Worktree root (default: git root, else cwd)
+  --json             Print the written paths as JSON
+  -h, --help         Show this help
+
+Writes two stills, one movie poster + video pair, and manifest.json using
+bundled fixtures. No Chromium download, no ffmpeg, no assets of your own.
+Re-running starts a fresh run and appends new numbered frames.
+
+After it runs, open the Astroshots menu-bar icon → Shots. If nothing appears,
+run "astroshot doctor".`;
+}
+
+function resolveRoot(explicitRoot) {
+  if (explicitRoot) return path.resolve(explicitRoot);
+  try {
+    return execFileSync("git", ["rev-parse", "--show-toplevel"], {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+    }).trim();
+  } catch {
+    return process.cwd();
+  }
+}
+
+function assertKebabCase(value, label) {
+  if (!/^[a-z0-9][a-z0-9-]*$/.test(value)) {
+    throw new Error(
+      `${label} must be kebab-case [a-z0-9-]+, got ${JSON.stringify(value)}`,
+    );
+  }
+}
+
+function nextSequence(featureDirectory) {
+  let max = 0;
+  const entries = fs.existsSync(featureDirectory)
+    ? fs.readdirSync(featureDirectory)
+    : [];
+  for (const name of entries) {
+    const match = /^(\d{4})-/.exec(name);
+    if (match) max = Math.max(max, Number(match[1]));
+  }
+  return max + 1;
+}
+
+function writeAtomic(filePath, contents) {
+  const temporary = path.join(
+    path.dirname(filePath),
+    `.${path.basename(filePath)}.tmp.${process.pid}.${Date.now()}`,
+  );
+  fs.writeFileSync(temporary, contents);
+  fs.renameSync(temporary, filePath);
+}
+
+function copyAtomic(source, destination) {
+  const temporary = path.join(
+    path.dirname(destination),
+    `.${path.basename(destination)}.tmp.${process.pid}.${Date.now()}`,
+  );
+  fs.copyFileSync(source, temporary);
+  fs.renameSync(temporary, destination);
+}
+
+export function loadDemoFixtures(fixturesDirectory = FIXTURES_DIR) {
+  const indexPath = path.join(fixturesDirectory, "fixtures.json");
+  if (!fs.existsSync(indexPath)) {
+    throw new Error(
+      `bundled demo fixtures are missing at ${fixturesDirectory}. Reinstall @archastro/astroshot.`,
+    );
+  }
+  const index = JSON.parse(fs.readFileSync(indexPath, "utf8"));
+  if (!Array.isArray(index.shots) || index.shots.length === 0) {
+    throw new Error(`bundled demo fixtures are empty: ${indexPath}`);
+  }
+  for (const shot of index.shots) {
+    for (const asset of [shot.asset, shot.video].filter(Boolean)) {
+      const assetPath = path.join(fixturesDirectory, asset);
+      if (!fs.existsSync(assetPath)) {
+        throw new Error(`bundled demo asset is missing: ${assetPath}`);
+      }
+    }
+  }
+  return index;
+}
+
+/**
+ * Write the demo set and return the paths, without printing anything.
+ *
+ * Each invocation is its own run: a new `run_id` with a fresh shot list, while
+ * earlier numbered frames stay on disk as prior-run evidence. That matches the
+ * documented lifecycle used by astroshot-capture and the movie harness.
+ */
+export function writeDemo({
+  root,
+  feature = DEFAULT_DEMO_FEATURE,
+  fixturesDirectory = FIXTURES_DIR,
+  now = new Date(),
+} = {}) {
+  assertKebabCase(feature, "feature");
+  const resolvedRoot = resolveRoot(root);
+  const featureDirectory = path.join(resolvedRoot, ".astroshot", feature);
+  const index = loadDemoFixtures(fixturesDirectory);
+
+  fs.mkdirSync(featureDirectory, { recursive: true });
+  const startSequence = nextSequence(featureDirectory);
+  const stamp = now.toISOString().replace(/[-:]/g, "").replace(/\.\d+Z$/, "Z");
+  // The first sequence of this run keeps the id unique when two runs land in
+  // the same second from the same process.
+  const runId = `${feature}-${stamp}-${process.pid}-${String(startSequence).padStart(4, "0")}`;
+  const capturedAt = now.toISOString();
+
+  const shots = [];
+  const files = [];
+  index.shots.forEach((fixture, offset) => {
+    const sequence = String(startSequence + offset).padStart(4, "0");
+    const posterName = `${sequence}-${fixture.slug}.png`;
+    copyAtomic(path.join(fixturesDirectory, fixture.asset), path.join(featureDirectory, posterName));
+    files.push(path.join(featureDirectory, posterName));
+
+    const shot = {
+      id: sequence,
+      file: posterName,
+      slug: fixture.slug,
+      title: fixture.title,
+      description: fixture.description,
+      captured_at: capturedAt,
+      viewport: index.viewport,
+    };
+
+    if (fixture.video) {
+      const videoExtension = path.extname(fixture.video) || ".webm";
+      const videoName = `${sequence}-${fixture.slug}${videoExtension}`;
+      copyAtomic(path.join(fixturesDirectory, fixture.video), path.join(featureDirectory, videoName));
+      files.push(path.join(featureDirectory, videoName));
+      shot.kind = "movie";
+      shot.video = videoName;
+      shot.duration_ms = fixture.duration_ms;
+      shot.source = fixture.source ?? "frames";
+      if (Array.isArray(fixture.chapters)) shot.chapters = fixture.chapters;
+    }
+
+    shots.push(shot);
+  });
+
+  const manifestPath = path.join(featureDirectory, "manifest.json");
+  const manifest = {
+    version: 1,
+    feature,
+    run_id: runId,
+    status: "pass",
+    description:
+      "Synthetic proof set written by `astroshot demo` — stills plus one journey movie.",
+    shots,
+  };
+  writeAtomic(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`);
+  files.push(manifestPath);
+
+  return {
+    root: resolvedRoot,
+    feature,
+    featureDirectory,
+    manifestPath,
+    runId,
+    shots,
+    files,
+  };
+}
+
+function coverageAdvice(root) {
+  const configuration = readWatchConfiguration();
+  const coverage = evaluateWatchCoverage(root, configuration);
+  switch (coverage.state) {
+    case "inside-root":
+      return [
+        `Watched by Astroshots via ${coverage.matchedRoot}.`,
+        "Open the Astroshots menu-bar icon → Shots to see these frames.",
+      ];
+    case "setup-incomplete":
+      return [
+        "Astroshots has no watched folders yet, so it will not pick these up.",
+        "Fix: open Astroshots and choose a folder, or menu-bar icon → gear → Add folders…",
+        "Then re-check with: astroshot doctor",
+      ];
+    case "outside-roots":
+      return [
+        `This project is outside every watched folder (${coverage.roots.join(", ")}).`,
+        "Fix: Astroshots menu-bar icon → gear → Add folders… and add a parent of this project.",
+        "Then re-check with: astroshot doctor",
+      ];
+    case "unsupported":
+      return [
+        "The Astroshots app is macOS-only; the files above still follow the .astroshot contract.",
+      ];
+    default:
+      // Unknown — do not claim the user has no watched folders.
+      return [
+        "Could not read Astroshots' watched folders, so whether this project is",
+        "watched is unknown (the files above were still written correctly).",
+        "Check with: astroshot doctor",
+      ];
+  }
+}
+
+export function runDemo(argv, { log = console.log } = {}) {
+  const options = { feature: DEFAULT_DEMO_FEATURE, root: undefined, json: false };
+  for (let index = 0; index < argv.length; index += 1) {
+    const token = argv[index];
+    if (token === "-h" || token === "--help" || token === "help") {
+      log(demoHelp());
+      return 0;
+    }
+    if (token === "--json") {
+      options.json = true;
+      continue;
+    }
+    if (token === "--feature" || token === "--root") {
+      const value = argv[index + 1];
+      if (!value || value.startsWith("-")) {
+        throw new Error(`${token} requires a value`);
+      }
+      options[token === "--feature" ? "feature" : "root"] = value;
+      index += 1;
+      continue;
+    }
+    throw new Error(`Unknown demo argument: ${token}`);
+  }
+
+  const result = writeDemo(options);
+  if (options.json) {
+    log(JSON.stringify({ ...result, advice: coverageAdvice(result.root) }, null, 2));
+    return 0;
+  }
+
+  const movies = result.shots.filter((shot) => shot.kind === "movie").length;
+  const stills = result.shots.length - movies;
+  log(`astroshot demo → ${result.featureDirectory}`);
+  for (const file of result.files) {
+    log(`  ${path.relative(result.root, file)}`);
+  }
+  log("");
+  log(
+    `Wrote ${stills} still${stills === 1 ? "" : "s"}, ${movies} movie${movies === 1 ? "" : "s"} (poster + video), and manifest.json.`,
+  );
+  for (const line of coverageAdvice(result.root)) log(line);
+  return 0;
+}

package/bin/doctor.mjs

@@ -0,0 +1,492 @@
+/**
+ * `astroshot doctor` — report every way Astroshots setup silently fails.
+ *
+ * Read-only by contract: it never installs, launches, or writes preferences.
+ * Each check prints pass/fail plus the exact remediation command, and required
+ * failures make the process exit non-zero.
+ */
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { createRequire } from "node:module";
+import { execFileSync, spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+
+import { loadDemoFixtures } from "./demo.mjs";
+import {
+  ASTROSHOTS_DOMAIN,
+  evaluateWatchCoverage,
+  preferenceToolsAvailable,
+  readWatchConfiguration,
+} from "./mac-preferences.mjs";
+
+const APP_PROCESS_NAME = "Astroshots";
+
+export function doctorHelp() {
+  return `astroshot doctor — diagnose Astroshots capture setup (read-only)
+
+Usage:
+  astroshot doctor [options]
+
+Options:
+  --root <dir>     Project directory to test for watch coverage (default: cwd)
+  --json           Machine-readable report
+  --skip-screen    Skip the macOS Screen Recording probe (avoids a Swift run)
+  -h, --help       Show this help
+
+Reports Node version, watched-folder coverage, whether the Astroshots app is
+installed and running, the managed Chromium runtime, and macOS Screen Recording
+state for desktop.window. Exits non-zero when a required check fails.
+doctor never installs anything and never changes app state.`;
+}
+
+function readEngines() {
+  const packageJSON = JSON.parse(
+    fs.readFileSync(new URL("../package.json", import.meta.url), "utf8"),
+  );
+  return packageJSON.engines?.node ?? ">=22.14.0";
+}
+
+function parseVersion(value) {
+  const match = /(\d+)\.(\d+)\.(\d+)/.exec(value);
+  if (!match) return null;
+  return [Number(match[1]), Number(match[2]), Number(match[3])];
+}
+
+function compareVersions(a, b) {
+  for (let index = 0; index < 3; index += 1) {
+    if (a[index] !== b[index]) return a[index] < b[index] ? -1 : 1;
+  }
+  return 0;
+}
+
+function checkNode(range) {
+  const minimum = parseVersion(range);
+  const current = parseVersion(process.versions.node);
+  if (!minimum || !current) {
+    return {
+      id: "node",
+      title: "Node.js version",
+      required: true,
+      status: "warn",
+      detail: `could not compare ${process.versions.node} with "${range}"`,
+      remediation: "Install Node.js 22.14.0 or newer: https://nodejs.org/en/download",
+    };
+  }
+  const ok = compareVersions(current, minimum) >= 0;
+  return {
+    id: "node",
+    title: "Node.js version",
+    required: true,
+    status: ok ? "pass" : "fail",
+    detail: ok
+      ? `${process.versions.node} satisfies ${range}`
+      : `${process.versions.node} is older than required ${range}`,
+    remediation: "nvm install 22.14.0 && nvm use 22.14.0",
+  };
+}
+
+function checkDemoFixtures() {
+  try {
+    const index = loadDemoFixtures();
+    const movies = index.shots.filter((shot) => shot.video).length;
+    return {
+      id: "demo-fixtures",
+      title: "Bundled demo payload",
+      required: true,
+      status: "pass",
+      detail: `${index.shots.length} fixtures (${movies} movie) ready for "astroshot demo"`,
+      remediation: "npm install --global @archastro/astroshot",
+    };
+  } catch (error) {
+    return {
+      id: "demo-fixtures",
+      title: "Bundled demo payload",
+      required: true,
+      status: "fail",
+      detail: error instanceof Error ? error.message : String(error),
+      remediation: "npm install --global @archastro/astroshot",
+    };
+  }
+}
+
+export function checkWatchCoverage(
+  projectPath,
+  platform,
+  // Seam for tests: the tool-failure path is otherwise only reachable by
+  // breaking the host's /usr/bin.
+  { readConfiguration = readWatchConfiguration } = {},
+) {
+  const base = { id: "watch-roots", title: "Watched folder covers this project" };
+  if (platform !== "darwin") {
+    return {
+      ...base,
+      required: false,
+      status: "skip",
+      detail: "the Astroshots app is macOS-only; .astroshot files are still written",
+      remediation: "Run captures on macOS to review them in the Astroshots tray",
+    };
+  }
+
+  const configuration = readConfiguration();
+  const coverage = evaluateWatchCoverage(projectPath, configuration);
+  const source =
+    configuration.source === "plist-file"
+      ? ` (read from ${configuration.plistPath}; cfprefsd unavailable)`
+      : "";
+  const legacy = configuration.usedLegacyKey ? " via legacy watchRoot key" : "";
+
+  switch (coverage.state) {
+    case "inside-root":
+      return {
+        ...base,
+        required: true,
+        status: "pass",
+        detail: `${coverage.projectPath} is inside ${coverage.matchedRoot}${legacy}${source}`,
+        remediation: "Astroshots menu-bar icon → gear → Add folders…",
+        data: coverage,
+      };
+    case "setup-incomplete":
+      return {
+        ...base,
+        required: true,
+        status: "fail",
+        detail:
+          "first-launch folder setup has not completed, so Astroshots watches nothing yet",
+        remediation:
+          "open -a Astroshots   # then choose the folder that holds your projects",
+        data: coverage,
+      };
+    case "outside-roots":
+      return {
+        ...base,
+        required: true,
+        status: "fail",
+        detail: `${coverage.projectPath} is outside every watched folder (${coverage.roots.join(", ")})`,
+        remediation:
+          "Astroshots menu-bar icon → gear → Add folders… → add a parent folder of this project",
+        data: coverage,
+      };
+    default: {
+      // The configuration could not be read. Say exactly that: claiming
+      // "setup incomplete" here would tell a correctly configured user to redo
+      // work they already did.
+      const tools = preferenceToolsAvailable({ platform });
+      const toolProblem =
+        coverage.reason === "tool-unavailable" || !tools.available;
+      const missing = tools.missing.length
+        ? ` (missing ${tools.missing.join(", ")})`
+        : "";
+      return {
+        ...base,
+        required: true,
+        status: "warn",
+        detail: toolProblem
+          ? `watch coverage is UNKNOWN, not unconfigured: could not read ${ASTROSHOTS_DOMAIN} because the macOS preference tools are unavailable${missing}`
+          : `watch coverage is UNKNOWN: could not read ${ASTROSHOTS_DOMAIN} preferences (${coverage.reason ?? "unknown"})`,
+        remediation: toolProblem
+          ? "Re-run with /usr/bin on PATH — doctor needs /usr/bin/defaults and /usr/bin/plutil"
+          : "Install and launch Astroshots once: https://github.com/ArchAstro/astroshots/releases",
+        data: coverage,
+      };
+    }
+  }
+}
+
+function findInstalledApp({ home = os.homedir() } = {}) {
+  const candidates = [
+    "/Applications/Astroshots.app",
+    path.join(home, "Applications", "Astroshots.app"),
+  ];
+  for (const candidate of candidates) {
+    if (fs.existsSync(candidate)) return candidate;
+  }
+  const found = spawnSync(
+    "/usr/bin/mdfind",
+    ["-0", `kMDItemCFBundleIdentifier == '${ASTROSHOTS_DOMAIN}'`],
+    { encoding: "utf8" },
+  );
+  if (found.status === 0 && found.stdout) {
+    const hit = found.stdout
+      .split("\0")
+      .map((entry) => entry.trim())
+      .find((entry) => entry.endsWith(".app") && fs.existsSync(entry));
+    if (hit) return hit;
+  }
+  return null;
+}
+
+function appVersion(appPath) {
+  const plist = path.join(appPath, "Contents", "Info.plist");
+  if (!fs.existsSync(plist)) return null;
+  const result = spawnSync(
+    "/usr/bin/plutil",
+    ["-extract", "CFBundleShortVersionString", "raw", "-o", "-", plist],
+    { encoding: "utf8" },
+  );
+  if (result.status !== 0) return null;
+  return result.stdout.trim() || null;
+}
+
+function checkApp(platform) {
+  const base = { id: "app", title: "Astroshots app installed" };
+  if (platform !== "darwin") {
+    return {
+      ...base,
+      required: false,
+      status: "skip",
+      detail: "macOS-only review app",
+      remediation: "Review captured files directly on this platform",
+    };
+  }
+  const appPath = findInstalledApp();
+  if (!appPath) {
+    return {
+      ...base,
+      required: true,
+      status: "fail",
+      detail: "no Astroshots.app found in /Applications or ~/Applications",
+      remediation:
+        "Download the latest DMG: https://github.com/ArchAstro/astroshots/releases",
+    };
+  }
+  const version = appVersion(appPath);
+  return {
+    ...base,
+    required: true,
+    status: "pass",
+    detail: `${appPath}${version ? ` (${version})` : ""}`,
+    remediation: "open -a Astroshots",
+  };
+}
+
+function checkAppRunning(platform) {
+  const base = { id: "app-running", title: "Astroshots app running" };
+  if (platform !== "darwin") {
+    return {
+      ...base,
+      required: false,
+      status: "skip",
+      detail: "macOS-only review app",
+      remediation: "Review captured files directly on this platform",
+    };
+  }
+  const result = spawnSync("/usr/bin/pgrep", ["-x", APP_PROCESS_NAME], {
+    encoding: "utf8",
+  });
+  const running = result.status === 0 && Boolean(result.stdout.trim());
+  return {
+    ...base,
+    required: false,
+    status: running ? "pass" : "warn",
+    detail: running
+      ? `pid ${result.stdout.trim().split(/\s+/).join(", ")} (menu-bar only, no Dock icon)`
+      : "not running, so new captures will not stream or flash an overlay",
+    remediation: "open -a Astroshots",
+  };
+}
+
+function resolvePlaywright() {
+  // playwright belongs to the engine packages, so resolve it from the engine
+  // rather than assuming a hoisted install next to this CLI. It is CommonJS,
+  // so require it: ESM interop does not expose the `chromium` named export.
+  const engineEntry = fileURLToPath(
+    import.meta.resolve("@archastro/react-shot"),
+  );
+  return createRequire(engineEntry)("playwright");
+}
+
+function checkChromium() {
+  const base = {
+    id: "chromium",
+    title: "Managed Chromium runtime",
+    required: false,
+    remediation: "astroshot install-browser   # add --with-deps on Linux CI",
+  };
+  let executablePath;
+  try {
+    executablePath = resolvePlaywright().chromium.executablePath();
+  } catch (error) {
+    return {
+      ...base,
+      status: "warn",
+      detail: `could not resolve Playwright (${error instanceof Error ? error.message.split("\n")[0] : error}); react/ink/pty and browser movies need it`,
+    };
+  }
+  const present = Boolean(executablePath) && fs.existsSync(executablePath);
+  return {
+    ...base,
+    status: present ? "pass" : "warn",
+    detail: present
+      ? executablePath
+      : `not installed at ${executablePath} — needed for react/ink/pty stills and browser movies (not for "astroshot demo")`,
+  };
+}
+
+function checkScreenRecording(platform, { skip = false } = {}) {
+  const base = {
+    id: "screen-recording",
+    title: "Screen Recording permission (movie --source desktop.window)",
+    required: false,
+  };
+  if (platform !== "darwin") {
+    return {
+      ...base,
+      status: "skip",
+      detail: "desktop.window is macOS-only; use --source browser, pty, or frames",
+      remediation: "astroshot movie which-source \"<intent>\"",
+    };
+  }
+  if (skip) {
+    return {
+      ...base,
+      status: "skip",
+      detail: "skipped with --skip-screen",
+      remediation: "astroshot movie check-screen-access",
+    };
+  }
+
+  const engineEntry = fileURLToPath(
+    import.meta.resolve("@archastro/movie-harness"),
+  );
+  const harnessBin = path.join(
+    path.dirname(path.dirname(engineEntry)),
+    "bin",
+    "astroshot-movie.mjs",
+  );
+  const result = spawnSync(
+    process.execPath,
+    [harnessBin, "check-screen-access"],
+    { encoding: "utf8" },
+  );
+  let report = null;
+  try {
+    report = JSON.parse(result.stdout ?? "");
+  } catch {
+    report = null;
+  }
+  if (!report) {
+    return {
+      ...base,
+      status: "warn",
+      detail: `could not probe Screen Recording (${(result.stderr ?? "").trim().split("\n")[0] || `status ${result.status}`})`,
+      remediation: "xcode-select --install && astroshot movie check-screen-access",
+    };
+  }
+  return {
+    ...base,
+    status: report.granted ? "pass" : "warn",
+    detail: report.granted
+      ? `granted for ${report.enableApp}`
+      : `denied — enable "${report.enableApp}" then quit and reopen it`,
+    remediation: report.granted
+      ? "astroshot movie check-screen-access"
+      : "astroshot movie open-screen-settings",
+  };
+}
+
+const SYMBOLS = { pass: "PASS", fail: "FAIL", warn: "WARN", skip: "SKIP" };
+
+export function collectDoctorChecks({
+  projectPath = process.cwd(),
+  platform = process.platform,
+  skipScreen = false,
+} = {}) {
+  return [
+    checkNode(readEngines()),
+    checkDemoFixtures(),
+    checkApp(platform),
+    checkAppRunning(platform),
+    checkWatchCoverage(projectPath, platform),
+    checkChromium(),
+    checkScreenRecording(platform, { skip: skipScreen }),
+  ];
+}
+
+export function summarizeDoctor(checks) {
+  const failures = checks.filter(
+    (check) => check.required && check.status === "fail",
+  );
+  const warnings = checks.filter((check) => check.status === "warn");
+  return {
+    ok: failures.length === 0,
+    failures: failures.map((check) => check.id),
+    warnings: warnings.map((check) => check.id),
+  };
+}
+
+export function runDoctor(argv, { log = console.log } = {}) {
+  const options = { root: undefined, json: false, skipScreen: false };
+  for (let index = 0; index < argv.length; index += 1) {
+    const token = argv[index];
+    if (token === "-h" || token === "--help" || token === "help") {
+      log(doctorHelp());
+      return 0;
+    }
+    if (token === "--json") {
+      options.json = true;
+      continue;
+    }
+    if (token === "--skip-screen") {
+      options.skipScreen = true;
+      continue;
+    }
+    if (token === "--root") {
+      const value = argv[index + 1];
+      if (!value || value.startsWith("-")) throw new Error("--root requires a value");
+      options.root = value;
+      index += 1;
+      continue;
+    }
+    throw new Error(`Unknown doctor argument: ${token}`);
+  }
+
+  const projectPath = resolveProjectPath(options.root);
+  const checks = collectDoctorChecks({
+    projectPath,
+    skipScreen: options.skipScreen,
+  });
+  const summary = summarizeDoctor(checks);
+
+  if (options.json) {
+    log(JSON.stringify({ project: projectPath, ...summary, checks }, null, 2));
+    return summary.ok ? 0 : 1;
+  }
+
+  log(`astroshot doctor — ${projectPath}`);
+  log("");
+  for (const check of checks) {
+    const scope = check.required ? "required" : "optional";
+    log(`${SYMBOLS[check.status]}  ${check.title} [${scope}]`);
+    log(`      ${check.detail}`);
+    if (check.status === "fail" || check.status === "warn") {
+      log(`      fix: ${check.remediation}`);
+    }
+  }
+  log("");
+  if (summary.ok) {
+    log(
+      summary.warnings.length
+        ? `All required checks pass (${summary.warnings.length} optional warning${summary.warnings.length === 1 ? "" : "s"} above).`
+        : "All checks pass. Try: astroshot demo",
+    );
+    return 0;
+  }
+  log(
+    `${summary.failures.length} required check${summary.failures.length === 1 ? "" : "s"} failed: ${summary.failures.join(", ")}`,
+  );
+  log("Run the fix line under each failure, then re-run: astroshot doctor");
+  return 1;
+}
+
+function resolveProjectPath(explicitRoot) {
+  if (explicitRoot) return path.resolve(explicitRoot);
+  try {
+    return execFileSync("git", ["rev-parse", "--show-toplevel"], {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+    }).trim();
+  } catch {
+    return process.cwd();
+  }
+}

package/bin/mac-preferences.mjs

@@ -0,0 +1,346 @@
+/**
+ * Read-only access to the Astroshots macOS app's real preferences.
+ *
+ * Two traps make the obvious implementations wrong:
+ *
+ * 1. Whole-domain plist → JSON conversion can never work. The domain contains
+ *    AppKit's `NSOSPLastRootDirectory` open-panel bookmark (CFData), and JSON
+ *    has no representation for it, so `plutil -convert json` aborts with
+ *    "Invalid object in plist for JSON format" on effectively every real user's
+ *    machine. Extract one key at a time instead.
+ * 2. `~/Library/Preferences/<domain>.plist` is a lazily flushed cache of
+ *    cfprefsd state, so reading the file can report yesterday's configuration.
+ *    Go through cfprefsd (`defaults export`) first and treat the file as a
+ *    fallback only.
+ *
+ * Nothing here writes: `astroshot doctor` must not mutate app state.
+ */
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+
+export const ASTROSHOTS_DOMAIN = "ai.archastro.Astroshots";
+
+const MISSING_KEY_PATTERN =
+  /No value at that key path|invalid key path|Invalid object in plist/i;
+
+// Resolve Apple's tools by absolute path. They always live in /usr/bin, and a
+// minimal or empty PATH must never be mistaken for "this user has no watch
+// roots" — that is the exact false negative doctor exists to eliminate.
+const DEFAULTS_BIN = "/usr/bin/defaults";
+const PLUTIL_BIN = "/usr/bin/plutil";
+
+/** Whether the tools this module shells out to are actually present. */
+export function preferenceToolsAvailable({ platform = process.platform } = {}) {
+  if (platform !== "darwin") return { available: false, missing: [] };
+  const missing = [DEFAULTS_BIN, PLUTIL_BIN].filter(
+    (binary) => !fs.existsSync(binary),
+  );
+  return { available: missing.length === 0, missing };
+}
+
+/**
+ * Snapshot the preference domain as an XML plist.
+ *
+ * `defaults export` goes through cfprefsd, so it observes what the app itself
+ * sees. The on-disk plist is only used when cfprefsd is unavailable.
+ */
+export function readPreferenceDomain(
+  domain = ASTROSHOTS_DOMAIN,
+  { home = os.homedir(), platform = process.platform } = {},
+) {
+  if (platform !== "darwin") {
+    return { available: false, source: null, reason: "not-macos" };
+  }
+
+  const exported = spawnSync(DEFAULTS_BIN, ["export", domain, "-"], {
+    maxBuffer: 16 * 1024 * 1024,
+  });
+  if (!exported.error && exported.status === 0 && exported.stdout?.length) {
+    return { available: true, source: "cfprefsd", plist: exported.stdout };
+  }
+
+  const plistPath = path.join(
+    home,
+    "Library",
+    "Preferences",
+    `${domain}.plist`,
+  );
+  try {
+    const bytes = fs.readFileSync(plistPath);
+    return {
+      available: true,
+      source: "plist-file",
+      plist: bytes,
+      plistPath,
+      staleRisk: true,
+    };
+  } catch {
+    // `defaults` failing to launch is a tool failure, not evidence that the
+    // domain is absent.
+    if (exported.error) {
+      return {
+        available: false,
+        source: null,
+        reason: "tool-unavailable",
+        error: exported.error.message,
+      };
+    }
+    return {
+      available: false,
+      source: null,
+      reason:
+        exported.status === 1 && !exported.stdout?.length
+          ? "domain-not-found"
+          : "unreadable",
+    };
+  }
+}
+
+/**
+ * Extract a single preference key from a plist snapshot.
+ *
+ * Three outcomes, deliberately distinct:
+ *   - `{ present: true, raw }`            the key exists
+ *   - `{ present: false }`                the key is genuinely absent
+ *   - `{ present: false, failed: true }`  the tool could not answer
+ *
+ * A missing key exits non-zero with the same "Invalid object" wording as a real
+ * failure, so absence is matched explicitly. Everything else — `plutil`
+ * missing, a spawn error, or an unrecognized non-zero exit — is a tool failure.
+ * Collapsing the third case into absence would make a correctly configured user
+ * read as "setup never completed".
+ */
+export function extractPreferenceKey(plist, key, format = "raw") {
+  const result = spawnSync(
+    PLUTIL_BIN,
+    ["-extract", key, format, "-o", "-", "-"],
+    { input: plist, encoding: "utf8", maxBuffer: 16 * 1024 * 1024 },
+  );
+  if (result.error) {
+    return { present: false, failed: true, error: result.error.message };
+  }
+  if (result.status !== 0) {
+    if (MISSING_KEY_PATTERN.test(result.stderr ?? "")) {
+      return { present: false };
+    }
+    return {
+      present: false,
+      failed: true,
+      error: (result.stderr ?? "").trim() || `plutil exited ${result.status}`,
+    };
+  }
+  return { present: true, raw: result.stdout };
+}
+
+function extractStringArray(plist, key) {
+  const extracted = extractPreferenceKey(plist, key, "json");
+  if (!extracted.present) {
+    return { present: false, failed: extracted.failed, error: extracted.error };
+  }
+  try {
+    const parsed = JSON.parse(extracted.raw);
+    if (!Array.isArray(parsed)) return { present: false };
+    return {
+      present: true,
+      value: parsed.filter((entry) => typeof entry === "string"),
+    };
+  } catch (error) {
+    // The key exists but did not decode: unreadable, not absent.
+    return {
+      present: false,
+      failed: true,
+      error: error instanceof Error ? error.message : String(error),
+    };
+  }
+}
+
+function extractString(plist, key) {
+  const extracted = extractPreferenceKey(plist, key, "raw");
+  if (!extracted.present) {
+    return { present: false, failed: extracted.failed, error: extracted.error };
+  }
+  const value = extracted.raw.replace(/\n$/, "");
+  return { present: true, value };
+}
+
+function extractBoolean(plist, key) {
+  const extracted = extractString(plist, key);
+  if (!extracted.present) {
+    return { present: false, failed: extracted.failed };
+  }
+  return { present: true, value: /^(true|1|yes)$/i.test(extracted.value) };
+}
+
+/**
+ * Mirror of `Preferences.normalizeWatchRootPaths` in the Swift app: expand
+ * tildes, standardize, resolve symlinks, drop duplicates, and drop roots
+ * already covered recursively by an earlier root.
+ */
+export function normalizeWatchRootPaths(paths, { home = os.homedir() } = {}) {
+  const result = [];
+  for (const rawPath of paths) {
+    if (typeof rawPath !== "string" || rawPath.length === 0) continue;
+    const candidate = normalizePath(rawPath, { home });
+    if (result.some((root) => pathIsInside(root, candidate))) continue;
+    for (let index = result.length - 1; index >= 0; index -= 1) {
+      if (pathIsInside(candidate, result[index])) result.splice(index, 1);
+    }
+    result.push(candidate);
+  }
+  return result;
+}
+
+/** Expand `~`, make absolute, and resolve symlinks as far as the path exists. */
+export function normalizePath(rawPath, { home = os.homedir() } = {}) {
+  let expanded = rawPath;
+  if (expanded === "~") expanded = home;
+  else if (expanded.startsWith("~/")) expanded = path.join(home, expanded.slice(2));
+  const absolute = path.resolve(expanded);
+  try {
+    return fs.realpathSync.native(absolute);
+  } catch {
+    // Resolve the deepest existing ancestor so a missing leaf still normalizes.
+    const parts = absolute.split(path.sep);
+    for (let depth = parts.length - 1; depth > 1; depth -= 1) {
+      const ancestor = parts.slice(0, depth).join(path.sep);
+      try {
+        const real = fs.realpathSync.native(ancestor);
+        return path.join(real, ...parts.slice(depth));
+      } catch {
+        continue;
+      }
+    }
+    return absolute;
+  }
+}
+
+/**
+ * Containment on path-component boundaries, so `/Users/x/proj-two` is not
+ * treated as living inside `/Users/x/proj`.
+ */
+export function pathIsInside(root, candidate) {
+  if (root === candidate) return true;
+  const prefix = root.endsWith(path.sep) ? root : `${root}${path.sep}`;
+  return candidate.startsWith(prefix);
+}
+
+/**
+ * The app's live watch configuration.
+ *
+ * `watchRoots` (string array) is authoritative; the legacy singular
+ * `watchRoot` is still honored when `watchRoots` was never written so upgrades
+ * keep the folder the user already chose.
+ */
+export function readWatchConfiguration({
+  domain = ASTROSHOTS_DOMAIN,
+  home = os.homedir(),
+  platform = process.platform,
+  // Seam for tests: lets a suite supply a plist snapshot (including a corrupt
+  // one) without breaking the host's /usr/bin.
+  readDomain = readPreferenceDomain,
+} = {}) {
+  const snapshot = readDomain(domain, { home, platform });
+  if (!snapshot.available) {
+    return {
+      available: false,
+      reason: snapshot.reason,
+      source: null,
+      roots: [],
+      hasCompletedFirstRunSetup: false,
+      usedLegacyKey: false,
+    };
+  }
+
+  const modern = extractStringArray(snapshot.plist, "watchRoots");
+  const legacy = modern.present
+    ? { present: false }
+    : extractString(snapshot.plist, "watchRoot");
+  const firstRun = extractBoolean(snapshot.plist, "hasCompletedFirstRunSetup");
+
+  // If the extraction tool could not answer, we know nothing about this user's
+  // setup. Reporting "no watch roots" here would tell a correctly configured
+  // user to redo first-run setup, so surface the unreadable state instead.
+  const failure = [modern, legacy, firstRun].find((result) => result.failed);
+  if (failure) {
+    return {
+      available: false,
+      reason: "tool-unavailable",
+      error: failure.error,
+      source: snapshot.source,
+      roots: [],
+      hasCompletedFirstRunSetup: false,
+      usedLegacyKey: false,
+    };
+  }
+
+  const stored = modern.present
+    ? modern.value
+    : legacy.present && legacy.value
+      ? [legacy.value]
+      : [];
+
+  return {
+    available: true,
+    source: snapshot.source,
+    staleRisk: Boolean(snapshot.staleRisk),
+    plistPath: snapshot.plistPath,
+    roots: normalizeWatchRootPaths(stored, { home }),
+    storedRoots: stored,
+    usedLegacyKey: !modern.present && legacy.present,
+    hasCompletedFirstRunSetup: firstRun.present ? firstRun.value : false,
+    hasConfiguredWatchRoots: modern.present || legacy.present,
+  };
+}
+
+/**
+ * Classify a project directory against the app's watch roots.
+ *
+ * Each outcome needs a different remediation, so they stay distinct instead of
+ * collapsing into "not watched":
+ *   - `setup-incomplete`  first-run folder setup never finished
+ *   - `outside-roots`     setup finished, but this project is not covered
+ *   - `inside-root`       covered by `matchedRoot`
+ *   - `unknown`           the configuration could not be read at all — never
+ *                         claim anything about the user's setup here
+ *   - `unsupported`       not macOS
+ */
+export function evaluateWatchCoverage(
+  projectPath,
+  configuration,
+  { home = os.homedir() } = {},
+) {
+  if (!configuration.available) {
+    return {
+      state: configuration.reason === "not-macos" ? "unsupported" : "unknown",
+      reason: configuration.reason,
+      error: configuration.error,
+      roots: [],
+    };
+  }
+  const normalizedProject = normalizePath(projectPath, { home });
+  const matchedRoot =
+    configuration.roots.find((root) => pathIsInside(root, normalizedProject)) ??
+    null;
+  if (matchedRoot) {
+    return {
+      state: "inside-root",
+      matchedRoot,
+      projectPath: normalizedProject,
+      roots: configuration.roots,
+    };
+  }
+  if (!configuration.hasCompletedFirstRunSetup || configuration.roots.length === 0) {
+    return {
+      state: "setup-incomplete",
+      projectPath: normalizedProject,
+      roots: configuration.roots,
+    };
+  }
+  return {
+    state: "outside-roots",
+    projectPath: normalizedProject,
+    roots: configuration.roots,
+  };
+}

package/fixtures/demo/fixtures.json

@@ -0,0 +1,42 @@
+{
+  "version": 1,
+  "generated_by": "npm run build:demo-fixtures --workspace @archastro/astroshot",
+  "viewport": "720x450",
+  "shots": [
+    {
+      "asset": "welcome.png",
+      "slug": "welcome",
+      "title": "Watch path works",
+      "description": "astroshot demo wrote this still into .astroshot/ with zero prerequisites."
+    },
+    {
+      "asset": "next-steps.png",
+      "slug": "next-steps",
+      "title": "Next steps",
+      "description": "The commands that capture real React, Ink, PTY, and movie states."
+    },
+    {
+      "asset": "journey.png",
+      "video": "journey.webm",
+      "slug": "journey",
+      "title": "Journey movie",
+      "description": "A poster PNG plus sibling WebM proves movie playback, duration, and chapters.",
+      "duration_ms": 4240,
+      "source": "frames",
+      "chapters": [
+        {
+          "slug": "recording",
+          "t_ms": 0
+        },
+        {
+          "slug": "poster",
+          "t_ms": 2685
+        },
+        {
+          "slug": "streaming",
+          "t_ms": 3180
+        }
+      ]
+    }
+  ]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@archastro/astroshot",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "One CLI for deterministic React, terminal, and movie UI captures",
   "keywords": [
     "react",
@@ -47,6 +47,7 @@
   },
   "files": [
     "bin",
+    "fixtures",
     "react.d.ts",
     "react.js",
     "ink.d.ts",
@@ -59,7 +60,8 @@
   ],
   "scripts": {
     "pretest": "npm run build --workspace @archastro/react-shot && npm run build --workspace @archastro/tui-shot && npm run build --workspace @archastro/movie-harness",
-    "test": "node --test test/*.test.mjs"
+    "test": "node --test test/*.test.mjs",
+    "build:demo-fixtures": "node scripts/build-demo-fixtures.mjs"
   },
   "engines": {
     "node": ">=22.14.0"
@@ -70,8 +72,8 @@
     "registry": "https://registry.npmjs.org/"
   },
   "dependencies": {
-    "@archastro/movie-harness": "0.2.0",
-    "@archastro/react-shot": "0.2.0",
-    "@archastro/tui-shot": "0.2.0"
+    "@archastro/movie-harness": "0.2.1",
+    "@archastro/react-shot": "0.2.1",
+    "@archastro/tui-shot": "0.2.1"
   }
 }