astroshot 0.2.1

package/node_modules/@archastro/movie-harness/native/macos/WindowTools.swift

@@ -0,0 +1,164 @@
+/**
+ * Window inventory + Screen Recording TCC helpers for desktop.window.
+ *
+ * Usage:
+ *   swift WindowTools.swift list
+ *   swift WindowTools.swift screen-access          # preflight only (JSON)
+ *   swift WindowTools.swift screen-access --request  # may show system prompt
+ */
+import AppKit
+import CoreGraphics
+import Foundation
+
+struct WindowRow: Encodable {
+  let id: Int
+  let pid: Int
+  let owner: String
+  let title: String
+  let bundleId: String?
+  let width: Int
+  let height: Int
+  let x: Int
+  let y: Int
+  let onScreen: Bool
+  /// CGWindow layer (0 = normal). Popovers / floating chrome often use > 0.
+  let layer: Int
+}
+
+struct ScreenAccessReport: Encodable {
+  let granted: Bool
+  /// True when we invoked CGRequestScreenCaptureAccess (may have shown a prompt).
+  let requested: Bool
+  let hostApp: String
+  let hostBundleId: String?
+  let settingsHint: String
+}
+
+func listWindows() -> [WindowRow] {
+  // Include off-screen windows so agents can still target them.
+  let opts = CGWindowListOption(arrayLiteral: .excludeDesktopElements)
+  guard let info = CGWindowListCopyWindowInfo(opts, kCGNullWindowID) as? [[String: Any]]
+  else {
+    return []
+  }
+
+  var bundleByPid: [Int32: String] = [:]
+  for app in NSWorkspace.shared.runningApplications {
+    if let bid = app.bundleIdentifier {
+      bundleByPid[app.processIdentifier] = bid
+    }
+  }
+
+  var rows: [WindowRow] = []
+  for w in info {
+    let layer = w[kCGWindowLayer as String] as? Int ?? -1
+    // Layer 0 = normal windows. Menu-bar trays / NSPopover often sit above 0
+    // (floating ~3, modal panel ~8). Skip Dock / main menu / status chrome
+    // (typically ≥20) which are huge, blank under screencapture, or unusable.
+    guard layer >= 0, layer <= 15 else { continue }
+
+    let id = w[kCGWindowNumber as String] as? Int ?? 0
+    let pid = w[kCGWindowOwnerPID as String] as? Int ?? 0
+    let owner = w[kCGWindowOwnerName as String] as? String ?? ""
+    let title = w[kCGWindowName as String] as? String ?? ""
+    let onScreen = w[kCGWindowIsOnscreen as String] as? Bool ?? false
+    let bounds = w[kCGWindowBounds as String] as? [String: Any]
+    let width = (bounds?["Width"] as? NSNumber)?.intValue ?? 0
+    let height = (bounds?["Height"] as? NSNumber)?.intValue ?? 0
+    let x = (bounds?["X"] as? NSNumber)?.intValue ?? 0
+    let y = (bounds?["Y"] as? NSNumber)?.intValue ?? 0
+    // Popovers can be small; keep a low floor but drop 1×1 placeholders.
+    if width < 2 || height < 2 { continue }
+
+    rows.append(
+      WindowRow(
+        id: id,
+        pid: pid,
+        owner: owner,
+        title: title,
+        bundleId: bundleByPid[Int32(pid)],
+        width: width,
+        height: height,
+        x: x,
+        y: y,
+        onScreen: onScreen,
+        layer: layer
+      )
+    )
+  }
+
+  // Prefer larger + on-screen + lower layer so normal windows win over
+  // tiny floating helpers when multiple match a bundle id.
+  return rows.sorted {
+    let area0 = $0.width * $0.height
+    let area1 = $1.width * $1.height
+    if area0 != area1 { return area0 > area1 }
+    if $0.onScreen != $1.onScreen { return $0.onScreen && !$1.onScreen }
+    return $0.layer < $1.layer
+  }
+}
+
+func hostIdentity() -> (name: String, bundleId: String?) {
+  let app = NSRunningApplication.current
+  let name =
+    app.localizedName
+    ?? ProcessInfo.processInfo.processName
+  return (name, app.bundleIdentifier)
+}
+
+func screenAccess(request: Bool) -> ScreenAccessReport {
+  let host = hostIdentity()
+  var granted = CGPreflightScreenCaptureAccess()
+  var didRequest = false
+  if request && !granted {
+    // May show the system consent dialog (not always; Settings may still be required).
+    granted = CGRequestScreenCaptureAccess()
+    didRequest = true
+  }
+  return ScreenAccessReport(
+    granted: granted,
+    requested: didRequest,
+    hostApp: host.name,
+    hostBundleId: host.bundleId,
+    settingsHint:
+      "System Settings → Privacy & Security → Screen Recording → enable \(host.name), then quit & reopen it"
+  )
+}
+
+func emitJSON<T: Encodable>(_ value: T) {
+  let encoder = JSONEncoder()
+  encoder.outputFormatting = [.prettyPrinted, .sortedKeys]
+  let data = try! encoder.encode(value)
+  FileHandle.standardOutput.write(data)
+  fputs("\n", stdout)
+}
+
+let args = Array(CommandLine.arguments.dropFirst())
+let command = args.first ?? "list"
+
+if command == "list" || command == "--json" {
+  emitJSON(listWindows())
+  exit(0)
+}
+
+if command == "screen-access" {
+  let request = args.contains("--request") || args.contains("-r")
+  let report = screenAccess(request: request)
+  emitJSON(report)
+  // Exit 0 when granted, 2 when denied (easy for shells).
+  exit(report.granted ? 0 : 2)
+}
+
+fputs(
+  """
+  usage:
+    WindowTools.swift list
+    WindowTools.swift screen-access [--request]
+
+  list          JSON windows for desktop.window matching
+  screen-access Screen Recording TCC preflight (optional --request prompt)
+
+  """,
+  stderr
+)
+exit(2)

package/node_modules/@archastro/movie-harness/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "@archastro/movie-harness",
+  "version": "0.2.1",
+  "description": "Universal movie capture harness for browser, PTY, desktop, and raw frames into .astroshot/",
+  "keywords": [
+    "astroshots",
+    "movie",
+    "screencast",
+    "playwright",
+    "pty",
+    "harness"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ArchAstro/astroshots.git",
+    "directory": "packages/movie-harness"
+  },
+  "homepage": "https://github.com/ArchAstro/astroshots#readme",
+  "bugs": "https://github.com/ArchAstro/astroshots/issues",
+  "type": "module",
+  "main": "./dist/index.js",
+  "bin": {
+    "astroshot-movie": "bin/astroshot-movie.mjs"
+  },
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "bin",
+    "dist",
+    "native",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "clean": "rm -rf dist",
+    "test": "npm run build && vitest run",
+    "typecheck": "tsc --noEmit",
+    "prepack": "npm run clean && npm run build"
+  },
+  "engines": {
+    "node": ">=22.14.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true,
+    "registry": "https://registry.npmjs.org/"
+  },
+  "dependencies": {
+    "@xterm/headless": "^5.5.0",
+    "playwright": "1.61.1",
+    "yaml": "^2.8.0"
+  },
+  "optionalDependencies": {
+    "node-pty": "1.2.0-beta.14"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.9.0",
+    "vitest": "^4.1.0"
+  }
+}

package/node_modules/@archastro/react-shot/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ArchAstro
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/node_modules/@archastro/react-shot/README.md

@@ -0,0 +1,181 @@
+# @archastro/react-shot
+
+Capture deterministic PNG screenshots from small React or TSX fixtures. The
+CLI starts an isolated Vite page, renders the fixture in Chromium with
+Playwright, and captures either a CSS selector or the full page.
+
+This package is the React rendering engine. Use the unified
+`@archastro/astroshot` package for command-line capture.
+
+Use this for component documentation, release assets, and repeatable visual
+fixtures. Use browser automation against your application when the screenshot
+needs real authentication, routing, server data, or a complete product flow.
+
+## Quick start
+
+Node.js 22.14 or newer is required. Install the package's compatible Chromium
+build once:
+
+```bash
+npx astroshot install-browser
+```
+
+On a Linux machine that also needs Chromium's operating-system libraries, run
+`npx astroshot install-browser --with-deps`.
+
+Then create `example.shot.tsx`:
+
+```tsx
+import type { ReactShotFixture } from "@archastro/astroshot/react";
+
+function WelcomeCard() {
+  return (
+    <main
+      data-card
+      style={{ width: 480, padding: 32, background: "#f8fafc" }}
+    >
+      <h1>Hello from React</h1>
+    </main>
+  );
+}
+
+export default {
+  width: 800,
+  height: 600,
+  selector: "[data-card]",
+  component: <WelcomeCard />,
+} satisfies ReactShotFixture;
+```
+
+Capture it without a permanent install:
+
+```bash
+npx astroshot react example.shot.tsx --out welcome.png
+```
+
+Or install the unified package and use `astroshot` in project scripts:
+
+```bash
+npm install --save-dev @archastro/astroshot
+npx astroshot react example.shot.tsx -o welcome.png
+```
+
+## Fixture API
+
+The fixture's default export accepts:
+
+| Field | Purpose |
+| --- | --- |
+| `component` | React tree to render; required |
+| `width`, `height` | Viewport in CSS pixels; defaults to 1280 by 800 |
+| `background` | Page background; defaults to transparent |
+| `selector` | Element to capture; defaults to the fixture root |
+| `waitFor` | CSS selector or `text=...` gate to await |
+| `settleMs` | Extra layout settling time; defaults to 150 ms |
+| `fullPage` | Capture the full page instead of one element |
+| `stripOverlay` | Isolate the target from a full-screen parent overlay |
+| `omitBackground` | Preserve transparent PNG pixels |
+
+Selectors containing `[role=dialog]` automatically enable `stripOverlay` and
+`omitBackground`. This avoids including a modal's full-screen dimmer and keeps
+rounded corners transparent. Set either option explicitly to override it.
+
+CLI `--width` and `--height` values override fixture dimensions. Values must be
+whole CSS pixels between 1 and 10,000, and output paths must end in `.png`.
+
+## Project configuration
+
+Place `react-shot.config.ts` beside your application package. It is discovered
+by walking upward from the fixture, or can be selected with `--config`.
+Filesystem paths are resolved relative to the config file.
+
+Without a config or `--root`, react-shot uses the closest directory containing
+a `package.json`, so fixtures can import sibling application source files.
+
+```ts
+export default {
+  root: ".",
+  alias: {
+    "@": "./src",
+  },
+  styles: ["./src/global.css"],
+  postcssConfig: "./postcss.config.mjs",
+  dedupe: ["some-react-library"],
+  stubModules: ["server-only"],
+};
+```
+
+Common imports from `next/navigation`, `next/link`, `next/image`,
+`next/dynamic`, and `server-only` receive lightweight browser stubs. These
+stubs are conveniences for presentation fixtures, not substitutes for testing
+Next.js behavior.
+
+If `@tailwindcss/vite` is installed in the target project, react-shot loads it
+automatically. Otherwise Vite uses the configured PostCSS pipeline.
+
+## Batch captures
+
+Create a YAML or JSON manifest:
+
+```yaml
+root: .
+shots:
+  - fixture: fixtures/welcome.shot.tsx
+    out: screenshots/welcome.png
+    width: 900
+    height: 700
+  - fixture: fixtures/settings.shot.tsx
+    out: screenshots/settings.png
+```
+
+Paths in a manifest, including per-shot `root` and `config`, are relative to
+the manifest file. Destinations are normalized and checked as a complete batch
+before capture; duplicate and case-only colliding output paths are rejected:
+
+```bash
+npx astroshot react batch shots.yaml
+```
+
+## Programmatic API
+
+```ts
+import { closeSharedBrowser, takeShot } from "@archastro/react-shot";
+
+try {
+  await takeShot({
+    fixturePath: "fixtures/welcome.shot.tsx",
+    outPath: "screenshots/welcome.png",
+  });
+} finally {
+  await closeSharedBrowser();
+}
+```
+
+Batch CLI runs reuse one browser process. Programmatic callers should close
+the shared browser during shutdown.
+
+## Security
+
+Fixtures and config files are executable code. Vite loads application modules
+and `react-shot.config.*`; they run with the permissions of the current user.
+Only capture trusted repositories and fixtures. Do not run the CLI on an
+untrusted pull request, package, or downloaded manifest without reviewing it.
+
+The Vite server binds only to `127.0.0.1` and restricts file serving to the
+package, fixture, configured alias/style paths, and this tool's runtime files.
+It does not provide a sandbox for fixture code.
+
+## Troubleshooting
+
+- `Executable doesn't exist`: run
+  `npx astroshot install-browser`.
+- Import failures: pass `--root` or define `root` and `alias` in the config.
+- Missing styles: add their entry files to `styles`; CSS is not inferred.
+- A modal includes a dimmer: target `[role=dialog]` or set
+  `stripOverlay: true`.
+- A fixture depends on application providers or network state: wrap it with
+  deterministic providers, or capture the running application instead.
+
+Run
+`npx astroshot react --help`
+for all CLI options.

package/node_modules/@archastro/react-shot/bin/react-shot.mjs

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import "../dist/cli.js";

package/node_modules/@archastro/react-shot/dist/batch-paths.d.ts

@@ -0,0 +1,4 @@
+import type { BatchEntry } from "./types.js";
+/** Resolve every destination before capture and reject accidental overwrites. */
+export declare function resolveBatchOutputPaths(entries: BatchEntry[], manifestDirectory: string): string[];
+//# sourceMappingURL=batch-paths.d.ts.map

package/node_modules/@archastro/react-shot/dist/batch-paths.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"batch-paths.d.ts","sourceRoot":"","sources":["../src/batch-paths.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAmB7C,iFAAiF;AACjF,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,UAAU,EAAE,EACrB,iBAAiB,EAAE,MAAM,GACxB,MAAM,EAAE,CAgBV"}

package/node_modules/@archastro/react-shot/dist/batch-paths.js

@@ -0,0 +1,34 @@
+import fs from "node:fs";
+import path from "node:path";
+function collisionKey(filePath) {
+    // Keep manifests portable across case-sensitive and case-insensitive hosts.
+    let existingAncestor = path.resolve(filePath);
+    const missingSegments = [];
+    while (!fs.existsSync(existingAncestor)) {
+        const parent = path.dirname(existingAncestor);
+        if (parent === existingAncestor)
+            break;
+        missingSegments.unshift(path.basename(existingAncestor));
+        existingAncestor = parent;
+    }
+    const canonicalAncestor = fs.realpathSync.native(existingAncestor);
+    return path
+        .join(canonicalAncestor, ...missingSegments)
+        .normalize("NFC")
+        .toLowerCase();
+}
+/** Resolve every destination before capture and reject accidental overwrites. */
+export function resolveBatchOutputPaths(entries, manifestDirectory) {
+    const destinations = entries.map((entry) => path.resolve(manifestDirectory, entry.out));
+    const seen = new Map();
+    for (const destination of destinations) {
+        const key = collisionKey(destination);
+        const previous = seen.get(key);
+        if (previous) {
+            throw new Error(`Batch outputs resolve to the same destination: ${previous} and ${destination}`);
+        }
+        seen.set(key, destination);
+    }
+    return destinations;
+}
+//# sourceMappingURL=batch-paths.js.map

package/node_modules/@archastro/react-shot/dist/batch-paths.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"batch-paths.js","sourceRoot":"","sources":["../src/batch-paths.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,IAAI,MAAM,WAAW,CAAC;AAI7B,SAAS,YAAY,CAAC,QAAgB;IACpC,4EAA4E;IAC5E,IAAI,gBAAgB,GAAG,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;IAC9C,MAAM,eAAe,GAAa,EAAE,CAAC;IACrC,OAAO,CAAC,EAAE,CAAC,UAAU,CAAC,gBAAgB,CAAC,EAAE,CAAC;QACxC,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,gBAAgB,CAAC,CAAC;QAC9C,IAAI,MAAM,KAAK,gBAAgB;YAAE,MAAM;QACvC,eAAe,CAAC,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,gBAAgB,CAAC,CAAC,CAAC;QACzD,gBAAgB,GAAG,MAAM,CAAC;IAC5B,CAAC;IACD,MAAM,iBAAiB,GAAG,EAAE,CAAC,YAAY,CAAC,MAAM,CAAC,gBAAgB,CAAC,CAAC;IACnE,OAAO,IAAI;SACR,IAAI,CAAC,iBAAiB,EAAE,GAAG,eAAe,CAAC;SAC3C,SAAS,CAAC,KAAK,CAAC;SAChB,WAAW,EAAE,CAAC;AACnB,CAAC;AAED,iFAAiF;AACjF,MAAM,UAAU,uBAAuB,CACrC,OAAqB,EACrB,iBAAyB;IAEzB,MAAM,YAAY,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CACzC,IAAI,CAAC,OAAO,CAAC,iBAAiB,EAAE,KAAK,CAAC,GAAG,CAAC,CAC3C,CAAC;IACF,MAAM,IAAI,GAAG,IAAI,GAAG,EAAkB,CAAC;IACvC,KAAK,MAAM,WAAW,IAAI,YAAY,EAAE,CAAC;QACvC,MAAM,GAAG,GAAG,YAAY,CAAC,WAAW,CAAC,CAAC;QACtC,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAC/B,IAAI,QAAQ,EAAE,CAAC;YACb,MAAM,IAAI,KAAK,CACb,kDAAkD,QAAQ,QAAQ,WAAW,EAAE,CAChF,CAAC;QACJ,CAAC;QACD,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,WAAW,CAAC,CAAC;IAC7B,CAAC;IACD,OAAO,YAAY,CAAC;AACtB,CAAC"}

package/node_modules/@archastro/react-shot/dist/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/node_modules/@archastro/react-shot/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":""}