@archastro/movie-harness 0.1.0 → 0.2.1

package/dist/cli.js

@@ -30,7 +30,7 @@ run --source …
   pty             --fixture path.yaml|json   # truecolor TUI — preferred for terminals
   pty-demo        [--color 7c5cff]           # truecolor smoke, no program
   desktop.window  --bundle-id ID | --window-id N | --title-regex RE | --owner NAME | --pid N
-                  [--duration-ms 3000] [--fps 10] [--cursor]
+                  [--duration-ms 3000] [--fps 10] [--cursor] [--allow-blank]
   frames          [--demo-frames N]          # or use start/push-frame/stop
 
 Common options
@@ -362,6 +362,7 @@ async function cmdRun(args) {
             match,
             durationMs,
             cursor: Boolean(args.cursor),
+            allowBlank: Boolean(args["allow-blank"]),
             fps: common.fps ?? 10,
         });
         process.stdout.write(`${JSON.stringify(artifact, null, 2)}\n`);

package/dist/index.d.ts

@@ -6,7 +6,7 @@ export { finalizeManifest, sinkMovie } from "./sink.js";
 export { formatSourceCatalog, recommendSource, SOURCE_CATALOG, SOURCE_DECISION_TABLE, sourceHintForError, } from "./source-help.js";
 export type { SourceAdvice, SourceKindHelp } from "./source-help.js";
 export { recordBrowserMovie } from "./sources/browser.js";
-export { assertDesktopToolchain, checkScreenRecordingAccess, desktopMatchFromFlags, ensureScreenRecordingAccess, formatScreenRecordingDeniedHelp, listDesktopWindows, matchDesktopWindow, openScreenRecordingSettings, recordDesktopWindowMovie, } from "./sources/desktop-macos.js";
+export { assertDesktopToolchain, checkScreenRecordingAccess, describeDesktopWindow, desktopMatchFromFlags, ensureScreenRecordingAccess, formatScreenRecordingDeniedHelp, isNearlyBlankPng, listDesktopWindows, matchDesktopWindow, openScreenRecordingSettings, recordDesktopWindowMovie, } from "./sources/desktop-macos.js";
 export type { DesktopWindowInfo, DesktopWindowMatch, DesktopWindowMovieOptions, ScreenAccessReport, } from "./sources/desktop-macos.js";
 export { loadFrameSession, markFrameSession, pushFrameToSession, startFrameSession, stopFrameSession, } from "./sources/frames-store.js";
 export { loadPtyMovieFixture, recordPtyMovie, recordTruecolorDemoMovie, } from "./sources/pty.js";

package/dist/index.js

@@ -5,7 +5,7 @@ export { MovieSession } from "./session.js";
 export { finalizeManifest, sinkMovie } from "./sink.js";
 export { formatSourceCatalog, recommendSource, SOURCE_CATALOG, SOURCE_DECISION_TABLE, sourceHintForError, } from "./source-help.js";
 export { recordBrowserMovie } from "./sources/browser.js";
-export { assertDesktopToolchain, checkScreenRecordingAccess, desktopMatchFromFlags, ensureScreenRecordingAccess, formatScreenRecordingDeniedHelp, listDesktopWindows, matchDesktopWindow, openScreenRecordingSettings, recordDesktopWindowMovie, } from "./sources/desktop-macos.js";
+export { assertDesktopToolchain, checkScreenRecordingAccess, describeDesktopWindow, desktopMatchFromFlags, ensureScreenRecordingAccess, formatScreenRecordingDeniedHelp, isNearlyBlankPng, listDesktopWindows, matchDesktopWindow, openScreenRecordingSettings, recordDesktopWindowMovie, } from "./sources/desktop-macos.js";
 export { loadFrameSession, markFrameSession, pushFrameToSession, startFrameSession, stopFrameSession, } from "./sources/frames-store.js";
 export { loadPtyMovieFixture, recordPtyMovie, recordTruecolorDemoMovie, } from "./sources/pty.js";
 export { createHeadlessTerminal, terminalPlainText, terminalToHtml, writeTerminal, } from "./terminal-paint.js";

package/dist/source-help.d.ts

@@ -19,6 +19,9 @@ export declare function formatSourceCatalog(): string;
 /**
  * Lightweight advisor for agents: pass free-text intent, get a recommended source.
  * This is heuristic — the decision table is authoritative.
+ *
+ * Order matters: TUI beats native (don't desktop Terminal.app); native/menu-bar
+ * beats browser so "record the Astroshots tray" never defaults to Chromium.
  */
 export declare function recommendSource(intent: string): {
     source: SourceKindHelp;

package/dist/source-help.js

@@ -15,6 +15,7 @@ Pick the FIRST row that matches the thing you need to record:
 | A TUI / CLI / Ink / Ratatui / truecolor terminal | pty                 | SGR→xterm truecolor path; NEVER screenshot Terminal.app |
 | Color-critical terminal (brand purple, etc.)     | pty                 | Host terminal themes remapping 16 colors would lie |
 | A native macOS app window (SwiftUI, Electron…)   | desktop.window      | Real window pixels via screencapture; needs Screen Recording |
+| Menu-bar / tray / status-item / LSUIElement app  | desktop.window      | Real app chrome; list-windows may include popover layers |
 | The whole monitor / multi-window desktop         | desktop.display     | (not implemented yet — use desktop.window or frames) |
 | Frames from any other tool (Unity, remote, custom)| frames              | You push PNG/JPEG; harness only encodes + sinks |
 | You already have PNG frames on disk              | frames              | Multi-process start/push-frame/stop |
@@ -104,6 +105,7 @@ export const SOURCE_CATALOG = {
         summary: "macOS native window pixels via CGWindowList + screencapture -l sampling.",
         useWhen: [
             "SwiftUI / AppKit / Electron / any real Mac window",
+            "Menu-bar / tray / status-item / LSUIElement apps (e.g. Astroshots)",
             "You need the actual app chrome and OS rendering",
         ],
         neverWhen: [
@@ -177,6 +179,9 @@ export function formatSourceCatalog() {
 /**
  * Lightweight advisor for agents: pass free-text intent, get a recommended source.
  * This is heuristic — the decision table is authoritative.
+ *
+ * Order matters: TUI beats native (don't desktop Terminal.app); native/menu-bar
+ * beats browser so "record the Astroshots tray" never defaults to Chromium.
  */
 export function recommendSource(intent) {
     const text = intent.toLowerCase();
@@ -186,9 +191,13 @@ export function recommendSource(intent) {
             reason: "Terminal/TUI intent detected — use pty for truecolor SGR fidelity (not desktop of a terminal app).",
         };
     }
-    if (/\b(swiftui|appkit|electron|native app|macos app|mac app|native mac|menu ?bar|desktop window|bundle[- ]?id|window id)\b/.test(text) ||
-        /\b(swiftui|appkit|electron)\b/.test(text) ||
-        (/\bnative\b/.test(text) && /\b(window|app|desktop|macos|mac)\b/.test(text))) {
+    if (/\b(swiftui|appkit|electron|native app|macos app|mac app|native mac|menu[- ]?bar|menubar|status[- ]?item|lsuielement|popover|desktop window|bundle[- ]?id|window id|window[- ]?id)\b/.test(text) ||
+        // "tray" alone is ambiguous (web trays exist); with an app name / menu-bar
+        // product context, treat as native desktop capture.
+        /\b(tray|menu bar tray)\b/.test(text) ||
+        /\bastroshots?\b/.test(text) ||
+        (/\bnative\b/.test(text) &&
+            /\b(window|app|desktop|macos|mac|chrome|ui)\b/.test(text))) {
         return {
             source: "desktop.window",
             reason: "Native desktop window intent detected — use desktop.window with --bundle-id or --window-id.",

package/dist/sources/desktop-macos.d.ts

@@ -10,6 +10,8 @@ export interface DesktopWindowInfo {
     x: number;
     y: number;
     onScreen: boolean;
+    /** CGWindow layer; 0 = normal, >0 = floating/popover chrome. */
+    layer?: number;
 }
 export interface DesktopWindowMatch {
     windowId?: number;
@@ -19,6 +21,11 @@ export interface DesktopWindowMatch {
     pid?: number;
     /** When multiple match, pick largest (default) or first. */
     pick?: "largest" | "first";
+    /**
+     * Prefer on-screen windows when several match (default true).
+     * Off-screen / empty host windows often produce black frames.
+     */
+    preferOnScreen?: boolean;
 }
 export type DesktopWindowMovieOptions = Omit<MovieSessionOptions, "source"> & {
     match: DesktopWindowMatch;
@@ -26,6 +33,11 @@ export type DesktopWindowMovieOptions = Omit<MovieSessionOptions, "source"> & {
     durationMs?: number;
     /** Include cursor in frames (screencapture -C). Default false. */
     cursor?: boolean;
+    /**
+     * Allow mostly-blank / black posters to encode (default false).
+     * Off-screen windows and denied Screen Recording often produce black frames.
+     */
+    allowBlank?: boolean;
 };
 export interface ScreenAccessReport {
     granted: boolean;
@@ -70,6 +82,16 @@ export declare function ensureScreenRecordingAccess(options?: {
 /** List layer-0 windows as JSON via shipped Swift tool (interpreted by `swift`). */
 export declare function listDesktopWindows(): DesktopWindowInfo[];
 export declare function matchDesktopWindow(windows: DesktopWindowInfo[], match: DesktopWindowMatch): DesktopWindowInfo;
+/** Human-readable manifest description for a captured window. */
+export declare function describeDesktopWindow(target: DesktopWindowInfo): string;
+/**
+ * True when a PNG is almost entirely very dark (typical failed/off-screen capture).
+ * Samples up to ~4k pixels across a simple grid; supports 8-bit RGB/RGBA.
+ */
+export declare function isNearlyBlankPng(filePath: string, options?: {
+    maxMeanLuma?: number;
+    minDarkFraction?: number;
+}): boolean;
 /**
  * Sample a macOS window at `fps` for `durationMs`, encode to movie + poster.
  * Uses OS `screencapture` (already on every Mac) — no separate download.

package/dist/sources/desktop-macos.js

@@ -3,6 +3,7 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
+import zlib from "node:zlib";
 import { MovieSession } from "../session.js";
 const SCREENCAPTURE = "/usr/sbin/screencapture";
 /** Known deep-links to the Screen Recording privacy pane (varies by macOS). */
@@ -200,16 +201,126 @@ export function matchDesktopWindow(windows, match) {
     if (candidates.length === 0) {
         const sample = windows
             .slice(0, 8)
-            .map((w) => `  id=${w.id} pid=${w.pid} bundle=${w.bundleId ?? "?"} owner=${JSON.stringify(w.owner)} title=${JSON.stringify(w.title)} ${w.width}x${w.height}`)
+            .map((w) => `  id=${w.id} pid=${w.pid} layer=${w.layer ?? "?"} bundle=${w.bundleId ?? "?"} owner=${JSON.stringify(w.owner)} title=${JSON.stringify(w.title)} ${w.width}x${w.height} onScreen=${w.onScreen}`)
             .join("\n");
         throw new Error(`No desktop window matched ${JSON.stringify(match)}.\n` +
             `Run: astroshot movie list-windows\n` +
             `Sample windows:\n${sample || "  (none)"}`);
     }
+    const preferOnScreen = match.preferOnScreen !== false;
+    if (preferOnScreen && match.windowId === undefined) {
+        const onScreen = candidates.filter((w) => w.onScreen);
+        if (onScreen.length > 0)
+            candidates = onScreen;
+    }
     if (match.pick === "first")
         return candidates[0];
-    // Default largest (list is already size-sorted, but re-sort for safety).
-    return [...candidates].sort((a, b) => b.width * b.height - a.width * a.height)[0];
+    // Default: largest area, then lower layer (normal windows over floaters).
+    return [...candidates].sort((a, b) => {
+        const area = b.width * b.height - a.width * a.height;
+        if (area !== 0)
+            return area;
+        return (a.layer ?? 0) - (b.layer ?? 0);
+    })[0];
+}
+/** Human-readable manifest description for a captured window. */
+export function describeDesktopWindow(target) {
+    const name = target.bundleId?.split(".").pop() || target.owner || "window";
+    const title = target.title.trim();
+    const size = `${target.width}×${target.height}`;
+    const where = target.onScreen ? "on-screen" : "off-screen";
+    const layer = target.layer !== undefined && target.layer > 0
+        ? `, layer ${target.layer}`
+        : "";
+    if (title) {
+        return `${name}: “${title}” (${size}, ${where}${layer})`;
+    }
+    return `${name} window (${size}, ${where}${layer})`;
+}
+/**
+ * True when a PNG is almost entirely very dark (typical failed/off-screen capture).
+ * Samples up to ~4k pixels across a simple grid; supports 8-bit RGB/RGBA.
+ */
+export function isNearlyBlankPng(filePath, options) {
+    const maxMeanLuma = options?.maxMeanLuma ?? 12;
+    const minDarkFraction = options?.minDarkFraction ?? 0.97;
+    let data;
+    try {
+        data = fs.readFileSync(filePath);
+    }
+    catch {
+        return true;
+    }
+    if (data.length < 33 || data.toString("ascii", 1, 4) !== "PNG")
+        return true;
+    // Minimal PNG scan: find IDAT chunks, inflate, average luma on a grid.
+    const width = data.readUInt32BE(16);
+    const height = data.readUInt32BE(20);
+    const bitDepth = data[24];
+    const colorType = data[25];
+    if (!width || !height || bitDepth !== 8)
+        return false;
+    // 2 = RGB, 6 = RGBA
+    if (colorType !== 2 && colorType !== 6)
+        return false;
+    const channels = colorType === 6 ? 4 : 3;
+    const idatParts = [];
+    let offset = 8;
+    while (offset + 8 <= data.length) {
+        const len = data.readUInt32BE(offset);
+        const type = data.toString("ascii", offset + 4, offset + 8);
+        const start = offset + 8;
+        const end = start + len;
+        if (end + 4 > data.length)
+            break;
+        if (type === "IDAT")
+            idatParts.push(data.subarray(start, end));
+        if (type === "IEND")
+            break;
+        offset = end + 4;
+    }
+    if (idatParts.length === 0)
+        return true;
+    let inflated;
+    try {
+        inflated = zlib.inflateSync(Buffer.concat(idatParts));
+    }
+    catch {
+        return false; // can't decode — don't claim blank
+    }
+    const stride = 1 + width * channels; // filter byte + row
+    const expected = stride * height;
+    if (inflated.length < expected)
+        return false;
+    // Only sample rows that use filter type 0 (None) for correct RGB bytes.
+    // For filtered rows, still sample raw bytes as a coarse darkness heuristic.
+    let samples = 0;
+    let dark = 0;
+    let lumaSum = 0;
+    const stepY = Math.max(1, Math.floor(height / 32));
+    const stepX = Math.max(1, Math.floor(width / 32));
+    for (let y = 0; y < height; y += stepY) {
+        const rowStart = y * stride;
+        const filter = inflated[rowStart] ?? 0;
+        for (let x = 0; x < width; x += stepX) {
+            const i = rowStart + 1 + x * channels;
+            const r = inflated[i] ?? 0;
+            const g = inflated[i + 1] ?? 0;
+            const b = inflated[i + 2] ?? 0;
+            // filter≠0 means bytes aren't raw RGB; still treat very low triples as dark.
+            const luma = 0.2126 * r + 0.7152 * g + 0.0722 * b;
+            lumaSum += luma;
+            if (luma <= maxMeanLuma)
+                dark += 1;
+            samples += 1;
+            void filter;
+        }
+    }
+    if (samples === 0)
+        return true;
+    const mean = lumaSum / samples;
+    const darkFraction = dark / samples;
+    return mean <= maxMeanLuma && darkFraction >= minDarkFraction;
 }
 function captureWindowPng(windowId, outPath, cursor) {
     const finalArgs = cursor
@@ -279,6 +390,13 @@ export async function recordDesktopWindowMovie(options) {
     ensureScreenRecordingAccess({ request: true, openSettings: true });
     const windows = listDesktopWindows();
     const target = matchDesktopWindow(windows, options.match);
+    if (!target.onScreen && !options.allowBlank) {
+        throw new Error(`Matched window id=${target.id} (${target.bundleId ?? target.owner}) is off-screen ` +
+            `(${target.width}×${target.height} at ${target.x},${target.y}). ` +
+            "Off-screen windows usually produce black movies. Bring the window on-screen " +
+            "(open the tray/popover) or pass --allow-blank to record anyway.\n" +
+            `Hint: ${describeDesktopWindow(target)}`);
+    }
     const tmp = fs.mkdtempSync(path.join(os.tmpdir(), "astroshot-desktop-"));
     const probe = path.join(tmp, "probe.png");
     try {
@@ -288,6 +406,14 @@ export async function recordDesktopWindowMovie(options) {
         fs.rmSync(tmp, { recursive: true, force: true });
         throw error;
     }
+    if (!options.allowBlank && isNearlyBlankPng(probe)) {
+        fs.rmSync(tmp, { recursive: true, force: true });
+        throw new Error(`Probe frame for window id=${target.id} is nearly blank/black. ` +
+            "Screen Recording may be denied for this host app, the window may be empty, " +
+            "or the popover may not be visible. Fix visibility/TCC, or pass --allow-blank.\n" +
+            `Window: ${describeDesktopWindow(target)}\n` +
+            "Run: astroshot movie check-screen-access");
+    }
     const probed = readPngSize(probe);
     const size = options.size ??
         probed ?? {
@@ -299,8 +425,7 @@ export async function recordDesktopWindowMovie(options) {
         size,
         fps,
         source: "desktop.window",
-        description: options.description ??
-            `desktop.window id=${target.id} ${target.bundleId ?? target.owner} ${JSON.stringify(target.title)}`,
+        description: options.description ?? describeDesktopWindow(target),
     });
     // Seed with probe frame so we never end empty if duration is tiny.
     session.pushFrame(fs.readFileSync(probe));

package/native/macos/WindowTools.swift

@@ -21,6 +21,8 @@ struct WindowRow: Encodable {
   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 {
@@ -50,7 +52,10 @@ func listWindows() -> [WindowRow] {
   var rows: [WindowRow] = []
   for w in info {
     let layer = w[kCGWindowLayer as String] as? Int ?? -1
-    guard layer == 0 else { continue }
+    // 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
@@ -62,6 +67,7 @@ func listWindows() -> [WindowRow] {
     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(
@@ -75,13 +81,21 @@ func listWindows() -> [WindowRow] {
         height: height,
         x: x,
         y: y,
-        onScreen: onScreen
+        onScreen: onScreen,
+        layer: layer
       )
     )
   }
 
-  // Largest first — better default when multiple windows share a bundle id.
-  return rows.sorted { ($0.width * $0.height) > ($1.width * $1.height) }
+  // 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?) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@archastro/movie-harness",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "Universal movie capture harness for browser, PTY, desktop, and raw frames into .astroshot/",
   "keywords": [
     "astroshots",