@hraness/slopcamera 3.5.0 → 3.7.0

package/apps/desktop/cli/html-overlay-renderer.ts

@@ -1844,6 +1844,30 @@ async function fulfillPreparedRoute(
   });
 }
 
+/**
+ * Validates a still/preview frame selection: distinct, ascending, in range.
+ * Ascending order keeps the runtime's virtual clock monotonic.
+ */
+export function selectedHtmlOverlayFrames(
+  frames: readonly number[],
+  frameCount: number,
+): readonly number[] {
+  if (frames.length === 0) {
+    throw new ApplicationError("invalid-data", "A frame selection must name at least one frame.");
+  }
+  let previous = -1;
+  for (const frame of frames) {
+    if (!Number.isSafeInteger(frame) || frame < 0 || frame >= frameCount) {
+      throw new ApplicationError("invalid-data", `Frame ${String(frame)} is outside the render range of ${String(frameCount)} frames.`);
+    }
+    if (frame <= previous) {
+      throw new ApplicationError("invalid-data", "A frame selection must be strictly ascending.");
+    }
+    previous = frame;
+  }
+  return [...frames];
+}
+
 export class PlaywrightHtmlOverlayRenderer implements HtmlOverlayRenderer {
   readonly #browserStepTimeoutMs: number;
   readonly #cacheRoot: string;
@@ -1963,6 +1987,9 @@ export class PlaywrightHtmlOverlayRenderer implements HtmlOverlayRenderer {
       join(request.outputDirectory, ".html-overlay-frames-"),
     );
     const frameCount = htmlOverlayFrameCount(request.authoring.timing);
+    const frameIndexes = request.frames === undefined
+      ? this.orderedFrameIndexes(frameCount)
+      : selectedHtmlOverlayFrames(request.frames, frameCount);
     const diagnostics: string[] = [];
     const pageErrors: string[] = [];
     let browserRuntimeSnapshot: PreparedBrowserRuntimeSnapshot | undefined;
@@ -2306,7 +2333,7 @@ export class PlaywrightHtmlOverlayRenderer implements HtmlOverlayRenderer {
               "document load",
             );
             await assertNoDeniedBrowserActivity(host);
-            for (const frameIndex of this.orderedFrameIndexes(frameCount)) {
+            for (const frameIndex of frameIndexes) {
               if (signal.aborted) throw cancellationReason(signal);
               const frame = createHtmlOverlayRuntimeFrame(
                 frameIndex,
@@ -2445,7 +2472,7 @@ export class PlaywrightHtmlOverlayRenderer implements HtmlOverlayRenderer {
       renderResult = {
         ...(gpuEvidence === undefined ? {} : { gpuEvidence }),
         executionIntegrity: execution.integrity,
-        frameCount,
+        frameCount: frameIndexes.length,
         framePattern: join(finalFrameDirectory, "frame-%08d.png"),
         libraryLocks: locks,
       };

package/apps/desktop/cli/html-scene.ts

@@ -67,7 +67,7 @@ async function readPngHeader(path: string, expectedBytes: number) {
   } finally { await handle.close(); }
 }
 
-async function readSource(application: ApplicationContext, input: unknown, signal: AbortSignal) {
+export async function readHtmlSceneSource(application: ApplicationContext, input: unknown, signal: AbortSignal) {
   const request = HtmlSceneInputSchema.parse(input);
   assertHtmlOverlayExecutionProfileLibraries(request.libraries, request.executionProfile);
   const loadedDocument = "path" in request.document
@@ -100,7 +100,7 @@ async function readSource(application: ApplicationContext, input: unknown, signa
 }
 
 export async function planHtmlScene(application: ApplicationContext, input: unknown, signal: AbortSignal) {
-  const source = await readSource(application, input, signal);
+  const source = await readHtmlSceneSource(application, input, signal);
   return {
     kind: "slopcamera.html-scene-plan" as const, schemaVersion: 1 as const,
     executed: false, name: source.request.name, frameCount: source.frameCount,
@@ -221,7 +221,7 @@ export async function renderHtmlScene(
   };
   await active();
   dependencies.progress?.("source");
-  const source = await readSource(application, input, signal);
+  const source = await readHtmlSceneSource(application, input, signal);
   if (application.htmlOverlayRenderer === undefined) throw new CliError("unavailable", "HTML scene renderer is unavailable.");
   const tools = await (dependencies.bindTools ?? bindExactCapabilities)(application, ["ffmpeg", "ffprobe", "html-browser"]);
   const tool = (name: string): ExactCapabilityBinding => {

package/apps/desktop/cli/main.ts

@@ -55,6 +55,7 @@ export async function main(
   }
   const paths = await resolveRepositoryPaths(processIo.cwd(), processIo.env);
   if (earlyCommand.kind === "html-render" || earlyCommand.kind === "spatial-world" || earlyCommand.kind === "spatial-asset" || earlyCommand.kind === "spatial-design" || earlyCommand.kind === "directing" || earlyCommand.kind === "studio"
+    || earlyCommand.kind === "html-film"
     || earlyCommand.kind === "spatial-scene" && (earlyCommand.action === "render" || earlyCommand.action === "camera-track" || earlyCommand.action === "render-audit" || earlyCommand.action === "review")) {
     const controller = new AbortController();
     const cancel = () => controller.abort(new CliError("cancelled", "Command interrupted."));

package/apps/desktop/cli/menubar-status.ts

@@ -0,0 +1,156 @@
+import { chmodSync, lstatSync, openSync, closeSync, readFileSync, renameSync, rmSync, writeSync, constants } from "node:fs";
+import { randomUUID } from "node:crypto";
+import { join } from "node:path";
+
+import type { CliCommand } from "./args";
+
+/**
+ * The small status file the menu bar reads: what Slopcamera is doing now,
+ * how the last render ended, and the last credits balance a command saw.
+ * It holds plain labels, times and fixed error codes only — never paths,
+ * prompts, tokens or account identifiers. Writes are best effort: a status
+ * that can't be saved never fails the command.
+ */
+export const MENUBAR_STATUS_FILE = "menubar-status.json";
+const MAX_STATUS_BYTES = 16 * 1024;
+
+export type ActivityState = "running" | "done" | "failed";
+
+export interface MenubarActivity {
+  readonly state: ActivityState;
+  readonly label: string;
+  readonly startedAt: number;
+  readonly finishedAt?: number;
+  readonly error?: string;
+}
+
+export interface MenubarCredits {
+  readonly usd: string;
+  readonly low: boolean;
+  readonly checkedAt: number;
+}
+
+export interface MenubarStatus {
+  readonly schemaVersion: 1;
+  readonly activity?: MenubarActivity;
+  readonly credits?: MenubarCredits;
+}
+
+/** Plain labels for the commands that make media. Everything else leaves the status alone. */
+export function activityLabel(command: CliCommand): string | undefined {
+  switch (command.kind) {
+    case "render-run": return command.dryRun ? undefined : "Rendering a recording";
+    case "project-render": return command.action === "run" && !command.dryRun ? "Rendering a project" : undefined;
+    case "project-cinema": return "Rendering a project";
+    case "html-render": return "Rendering an HTML scene";
+    case "html-film": return command.action === "deliver" ? "Encoding a film" : "Rendering film stills";
+    case "diagram-render": return "Rendering a diagram";
+    case "image-vectorize": return "Vectorizing an image";
+    case "ai-image-generate": return "Generating an image";
+    case "ai-video-generate": return "Generating a video";
+    case "ai-speech-generate": return "Generating speech";
+    case "directing": return "Directing a clip";
+    case "studio": return "Running a studio job";
+    case "spatial-scene": return command.action === "render" ? "Rendering a 3D scene" : undefined;
+    case "workflows-run": return "Running a workflow";
+    case "code-run": return "Running a workflow";
+    default: return undefined;
+  }
+}
+
+function parse(text: string): MenubarStatus {
+  try {
+    const value: unknown = JSON.parse(text);
+    if (typeof value !== "object" || value === null || (value as { schemaVersion?: unknown }).schemaVersion !== 1) return { schemaVersion: 1 };
+    const record = value as Record<string, unknown>;
+    const activity = record.activity as MenubarActivity | undefined;
+    const credits = record.credits as MenubarCredits | undefined;
+    return {
+      schemaVersion: 1,
+      ...(activity !== undefined && typeof activity === "object" && typeof activity.label === "string" ? { activity } : {}),
+      ...(credits !== undefined && typeof credits === "object" && typeof credits.usd === "string" ? { credits } : {}),
+    };
+  } catch {
+    return { schemaVersion: 1 };
+  }
+}
+
+export function readMenubarStatus(stateRoot: string): MenubarStatus {
+  const path = join(stateRoot, MENUBAR_STATUS_FILE);
+  try {
+    const info = lstatSync(path);
+    if (!info.isFile() || info.size > MAX_STATUS_BYTES) return { schemaVersion: 1 };
+    return parse(readFileSync(path, "utf8"));
+  } catch {
+    return { schemaVersion: 1 };
+  }
+}
+
+const LOCK_FILE = `.${MENUBAR_STATUS_FILE}.lock`;
+/** A held lock blocks a write for this long before it is skipped. */
+const LOCK_BUDGET_MS = 250;
+/** A lock older than this is a crashed writer's and is reclaimed. */
+const LOCK_STALE_MS = 10_000;
+
+function sleepSync(ms: number): void {
+  Bun.sleepSync(ms);
+}
+
+/**
+ * Runs `update` holding a small exclusive lock file, so a render finishing
+ * while `credits status` runs cannot overwrite the other slot. Returns
+ * undefined when the lock never comes free; the write is then skipped
+ * rather than lost-halfway.
+ */
+function withStatusLock<T>(stateRoot: string, update: () => T): T | undefined {
+  const lock = join(stateRoot, LOCK_FILE);
+  const deadline = Date.now() + LOCK_BUDGET_MS;
+  for (;;) {
+    let fd: number;
+    try {
+      fd = openSync(lock, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600);
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== "EEXIST") return undefined;
+      try {
+        if (Date.now() - lstatSync(lock).mtimeMs > LOCK_STALE_MS) rmSync(lock, { force: true });
+      } catch { /* races with the lock holder */ }
+      if (Date.now() >= deadline) return undefined;
+      sleepSync(5);
+      continue;
+    }
+    closeSync(fd);
+    try {
+      return update();
+    } finally {
+      try { rmSync(lock, { force: true }); } catch { /* best effort */ }
+    }
+  }
+}
+
+/** Replaces the status file atomically with an owner-only file. Never throws. */
+export function writeMenubarStatus(stateRoot: string, update: (current: MenubarStatus) => MenubarStatus): void {
+  withStatusLock(stateRoot, () => {
+    const path = join(stateRoot, MENUBAR_STATUS_FILE);
+    const staged = join(stateRoot, `.${MENUBAR_STATUS_FILE}.${randomUUID()}.tmp`);
+    try {
+      const root = lstatSync(stateRoot);
+      if (!root.isDirectory()) return;
+      const text = `${JSON.stringify(update(readMenubarStatus(stateRoot)))}\n`;
+      if (Buffer.byteLength(text) > MAX_STATUS_BYTES) return;
+      const fd = openSync(staged, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600);
+      try { writeSync(fd, text); } finally { closeSync(fd); }
+      chmodSync(staged, 0o600);
+      renameSync(staged, path);
+    } catch {
+      try { rmSync(staged, { force: true }); } catch { /* best effort */ }
+    }
+  });
+}
+
+export function recordActivity(stateRoot: string, activity: MenubarActivity): void {
+  writeMenubarStatus(stateRoot, (current) => ({ ...current, activity }));
+}
+
+export function recordCredits(stateRoot: string, credits: MenubarCredits): void {
+  writeMenubarStatus(stateRoot, (current) => ({ ...current, credits }));
+}

package/apps/desktop/cli/menubar.ts

@@ -7,6 +7,7 @@ import { writeJson, writeLine } from "./io";
 import { ensurePrivateDirectory } from "./paths";
 
 const SETTLE_MS = 400;
+/** The label earlier releases used; the menu bar now manages its own login item. */
 const LABEL = "com.hraness.slopcamera.menubar";
 
 function xml(value: string): string { return value.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll('"', "&quot;").replaceAll("'", "&apos;"); }
@@ -109,109 +110,86 @@ function readAgent(path: string, environment: Environment): string | null {
   return readRegular(path, 16 * 1024).toString("utf8");
 }
 
-/** Configuration state only; it does not claim the launchd service is running. */
-export type LaunchAgentState = "absent" | "installed" | "conflict";
-export type LaunchctlRunner = (args: readonly string[], allowMissing?: boolean) => string | null;
-function launchctl(args: readonly string[], allowMissing = false): string | null {
-  const uid = process.getuid?.();
-  if (uid === undefined) throw new CliError("unavailable", "The current user has no launchd GUI domain.");
-  const result = Bun.spawnSync(["/bin/launchctl", ...args.map((arg) => arg.replaceAll("{uid}", String(uid)))], { stdin: "ignore", stdout: "pipe", stderr: "pipe", timeout: 10_000, maxBuffer: 64 * 1024 });
-  return interpretLaunchctlResult(result, uid, allowMissing);
-}
-export function interpretLaunchctlResult(result: { success: boolean; exitCode: number; stdout: Uint8Array; stderr: Uint8Array }, uid: number, allowMissing: boolean): string | null {
-  if (result.stdout.byteLength + result.stderr.byteLength > 64 * 1024) throw new CliError("unavailable", "launchctl exceeded the bounded response size.");
-  if (result.success && result.exitCode === 0) return Buffer.from(result.stdout).toString();
-  if (allowMissing && result.exitCode === 113 && result.stdout.length === 0 && Buffer.from(result.stderr).toString() === `Bad request.\nCould not find service "${LABEL}" in domain for user gui: ${uid}\n`) return null;
-  throw new CliError("unavailable", "launchctl could not reconcile the Slopcamera menu-bar LaunchAgent. Run menubar install again to retry.");
-}
-
-function loadedOwned(path: string, binary: string, current: string | null, run: LaunchctlRunner): boolean {
-  const output = run(["print", `gui/{uid}/${LABEL}`], true);
-  if (output === null) return false;
-  const uid = process.getuid?.();
-  if (current === null || Buffer.byteLength(output) > 64 * 1024 || !output.startsWith(`gui/${uid}/${LABEL} = {\n`)) {
-    throw new CliError("conflict", "The loaded menu-bar service has an unverified identity.");
-  }
-  const lines = output.split("\n").map(line => line.trim());
-  const field = (key: string): string | null => {
-    const values = lines.filter(line => line.startsWith(`${key} = `));
-    return values.length === 1 ? values[0]!.slice(key.length + 3) : null;
-  };
-  const argumentsStart = lines.indexOf("arguments = {");
-  const argumentsEnd = lines.indexOf("}", argumentsStart + 1);
-  if (field("path") !== path || field("program") !== binary || argumentsStart < 0 || argumentsEnd !== argumentsStart + 2 || lines[argumentsStart + 1] !== binary) {
-    throw new CliError("conflict", "The loaded menu-bar service does not match this install; it was left untouched.");
-  }
-  return true;
-}
-export function launchAgentState(binary: string, environment: Environment = process.env): LaunchAgentState {
-  const content = readAgent(launchAgentPath(environment), environment);
-  if (content === null) return "absent";
-  checkParents(binary, environment);
-  assertOwnedFile(binary);
-  return content === launchAgentPlist(binary) && exists(binary) ? "installed" : "conflict";
-}
-function assertMac(platform: NodeJS.Platform): void {
-  if (platform !== "darwin") throw new CliError("unsupported-plan", "Slopcamera menu-bar LaunchAgents are supported only on macOS.");
-}
-export function installLaunchAgent(binary: string, environment: Environment = process.env, platform: NodeJS.Platform = process.platform, runLaunchctl: LaunchctlRunner = launchctl): LaunchAgentState {
-  assertMac(platform);
-  if (!isAbsolute(binary)) throw new CliError("unsafe-path", "LaunchAgent binary must be an absolute path.");
+/**
+ * Copies the built menu bar into its installed location, replacing an
+ * earlier copy. Existing shared directory permissions are preserved;
+ * symbolic links and files other users can write are refused.
+ */
+export function installBinary(binary: string, environment: Environment = process.env): string {
+  if (!isAbsolute(binary)) throw new CliError("unsafe-path", "The menu-bar build must be an absolute path.");
   const stable = installedBinaryPath(environment);
-  const path = launchAgentPath(environment);
-  const current = readAgent(path, environment);
-  const expected = launchAgentPlist(stable);
   checkParents(stable, environment);
   assertOwnedFile(stable);
-  if (current !== null && current !== expected || current === null && infoAt(stable) !== null) {
-    throw new CliError("conflict", "The existing Slopcamera menu-bar install is not owned by this command.");
-  }
   const bytes = readRegular(binary, MAX_BINARY_BYTES, true);
-  loadedOwned(path, stable, current, runLaunchctl);
-  checkParents(path, environment, true);
   checkParents(stable, environment, true);
-  // Unique private staging directories prevent predictable temporary-file clobbering.
-  const binaryStage = mkdtempSync(join(dirname(stable), ".install-"));
-  let agentStage: string | undefined;
+  const stage = mkdtempSync(join(dirname(stable), ".install-"));
   try {
-    agentStage = mkdtempSync(join(dirname(path), ".slopcamera-install-"));
-    const stagedBinary = join(binaryStage, "binary");
-    const stagedAgent = join(agentStage, "agent.plist");
-    writeFileSync(stagedBinary, bytes, { mode: 0o700, flag: "wx" });
-    writeFileSync(stagedAgent, expected, { mode: 0o600, flag: "wx" });
-    if (readAgent(path, environment) !== current) throw new CliError("conflict", "The menu-bar install changed concurrently.");
+    const staged = join(stage, "binary");
+    writeFileSync(staged, bytes, { mode: 0o700, flag: "wx" });
     assertOwnedFile(stable);
-    // Retry bootstrap even when the plist matches: a previous bootstrap may have failed.
-    if (loadedOwned(path, stable, current, runLaunchctl)) runLaunchctl(["bootout", `gui/{uid}/${LABEL}`], true);
-    renameSync(stagedBinary, stable);
-    renameSync(stagedAgent, path);
-    runLaunchctl(["bootstrap", "gui/{uid}", path]);
-    return "installed";
+    renameSync(staged, stable);
+    return stable;
   } finally {
-    rmSync(binaryStage, { recursive: true });
-    if (agentStage !== undefined) rmSync(agentStage, { recursive: true });
+    rmSync(stage, { recursive: true });
   }
 }
-export function uninstallLaunchAgent(_binary: string, environment: Environment = process.env, platform: NodeJS.Platform = process.platform, runLaunchctl: LaunchctlRunner = launchctl): LaunchAgentState {
-  assertMac(platform);
-  const stable = installedBinaryPath(environment);
+
+/**
+ * Removes the login item earlier releases wrote under the old label, but
+ * only when it is exactly the file they wrote. It never calls launchctl: a
+ * copy that is already running keeps running until you quit it or log out.
+ */
+export function removeLegacyAgent(environment: Environment = process.env): "absent" | "removed" | "foreign" {
   const path = launchAgentPath(environment);
   const current = readAgent(path, environment);
   if (current === null) return "absent";
-  if (current !== launchAgentPlist(stable)) throw new CliError("conflict", "The existing Slopcamera menu-bar LaunchAgent is not owned by this command.");
-  checkParents(stable, environment);
-  assertOwnedFile(stable);
-  if (loadedOwned(path, stable, current, runLaunchctl)) runLaunchctl(["bootout", `gui/{uid}/${LABEL}`], true);
-  if (readAgent(path, environment) !== current) throw new CliError("conflict", "The menu-bar install changed concurrently.");
-  assertOwnedFile(stable);
+  if (current !== launchAgentPlist(installedBinaryPath(environment))) return "foreign";
   rmSync(path);
-  if (infoAt(stable) !== null) rmSync(stable);
-  return "absent";
+  return "removed";
+}
+
+function assertMac(platform: NodeJS.Platform): void {
+  if (platform !== "darwin") throw new CliError("unsupported-plan", "The Slopcamera menu bar runs only on macOS.");
+}
+
+export interface HelperResult { readonly code: number; readonly stdout: string; readonly stderr: string }
+/** Runs the installed menu bar's own install, uninstall or status command. */
+export type HelperRunner = (binary: string, args: readonly string[], env: Environment) => Promise<HelperResult>;
+
+async function runHelper(binary: string, args: readonly string[], env: Environment): Promise<HelperResult> {
+  const child = Bun.spawn([binary, ...args], { stdin: "ignore", stdout: "pipe", stderr: "pipe", env: { ...env } as Record<string, string> });
+  const [stdout, stderr, code] = await Promise.all([new Response(child.stdout).text(), new Response(child.stderr).text(), child.exited]);
+  return { code, stdout: stdout.slice(0, 64 * 1024), stderr: stderr.slice(0, 64 * 1024) };
 }
+
+const AGENT_MARKERS = ["AI_AGENT", "CLAUDECODE", "CODEX_SANDBOX", "CODEX_SANDBOX_NETWORK_DISABLED", "CURSOR_AGENT", "GEMINI_CLI"];
+
+/**
+ * The helper decides between human and agent output from its environment.
+ * Its output is captured here, so a person's terminal is passed on as
+ * `HRANESS_AUDIENCE=human`; agents and explicit settings pass through.
+ */
+export function helperEnvironment(env: Environment): Environment {
+  const agent = AGENT_MARKERS.some((name) => (env[name] ?? "") !== "");
+  return env.HRANESS_AUDIENCE !== undefined || agent ? env : { ...env, HRANESS_AUDIENCE: "human" };
+}
+
+function helperFailure(result: HelperResult): CliError {
+  // The helper prints the login-item notice on stderr before the error;
+  // the failure is the last ✗ line plus the → hint that follows it.
+  const lines = result.stderr.split("\n");
+  let start = -1;
+  for (const [index, line] of lines.entries()) {
+    const trimmed = line.trimStart();
+    if (trimmed.startsWith("✗") || trimmed.startsWith("FAIL")) start = index;
+  }
+  const text = (start === -1 ? result.stderr : lines.slice(start).join("\n")).trim().replace(/^(✗|FAIL)\s+/u, "");
+  return new CliError(result.code === 2 ? "usage" : "unavailable", text === "" ? "The Slopcamera menu bar couldn't change its login item." : text);
+}
+
 /** `slopcamera-menubar` exits with this code when another copy already holds the menu bar. */
 export const ALREADY_RUNNING_EXIT = 3;
 const NOT_BUILT = "The Slopcamera menu bar isn't in this release yet. Build it with cargo build --release --manifest-path desktop/Cargo.toml in a Slopcamera checkout; slopcamera finds it there, or set SLOPCAMERA_MENUBAR to the built file.";
-const LOGIN_ITEMS = "System Settings › General › Login Items & Extensions";
 
 export type Launched = "running" | "already-running" | "exited";
 export type BinaryRunner = (binary: string, foreground: boolean) => Promise<number | null>;
@@ -240,11 +218,6 @@ export function marks(env: Readonly<Record<string, string | undefined>>): Marks
   return ascii ? { ok: "OK", warn: "WARN", note: "NOTE", next: "->" } : { ok: "✓", warn: "⚠", note: "🔐", next: "→" };
 }
 
-/** The LOGIN_ITEM notice (notifies, so there is no confirm line). The requester is the bare companion until Slopcamera ships as an app. */
-export function loginItemNotice(env: Readonly<Record<string, string | undefined>>): string {
-  return `${marks(env).note} macOS will show a notice that slopcamera-menubar can open at login. That's Slopcamera's menu bar.\n   It lists your outputs and opens when you log in. Nothing else runs in the background. Turn it off any time in ${LOGIN_ITEMS}.\n`;
-}
-
 export function launchMessage(outcome: Launched, env: Readonly<Record<string, string | undefined>>): string {
   const mark = marks(env);
   if (outcome === "already-running") return `${mark.ok} Slopcamera is already in your menu bar. Look for 📷.`;
@@ -252,42 +225,6 @@ export function launchMessage(outcome: Launched, env: Readonly<Record<string, st
   return "The Slopcamera menu bar closed.";
 }
 
-export function stateMessage(action: "install" | "uninstall" | "status", state: LaunchAgentState, running: boolean, env: Readonly<Record<string, string | undefined>>): string {
-  const mark = marks(env);
-  if (state === "conflict") return `${mark.warn} Another menu-bar setup that this command didn't create is in the way. It was left untouched.\n  Remove ~/Library/LaunchAgents/${LABEL}.plist yourself if you don't need it.`;
-  if (state === "absent") return action === "uninstall" ? `${mark.ok} Slopcamera no longer opens in your menu bar at login.` : `Slopcamera doesn't open at login.\n${mark.next} slopcamera menubar install`;
-  if (action === "install") return `${mark.ok} Slopcamera opens in your menu bar now and at every login. Look for 📷.\n  Remove it any time: slopcamera menubar uninstall`;
-  return running
-    ? `${mark.ok} Slopcamera opens at login and is in your menu bar now.`
-    : `${mark.warn} Slopcamera is set to open at login but isn't running. It may be turned off in ${LOGIN_ITEMS}.\n${mark.next} slopcamera menubar install`;
-}
-
-/** Whether launchd reports the loaded companion as running. Reads state only. */
-export function serviceRunning(runLaunchctl: LaunchctlRunner): boolean {
-  const output = runLaunchctl(["print", `gui/{uid}/${LABEL}`], true);
-  return output !== null && output.split("\n").some((line) => line.trim() === "state = running");
-}
-
-export type ProcessProbe = () => boolean;
-/** Whether any copy of the companion runs for this user, including one started by hand. */
-function companionProcessRunning(): boolean {
-  const uid = process.getuid?.();
-  if (uid === undefined) return false;
-  try {
-    return Bun.spawnSync(["/usr/bin/pgrep", "-x", "-U", String(uid), "slopcamera-menubar"], { stdin: "ignore", stdout: "ignore", stderr: "ignore", timeout: 5_000 }).exitCode === 0;
-  } catch { return false; }
-}
-
-/** The menu bar is showing when launchd runs the login item or another copy holds it. */
-async function menubarShowing(runLaunchctl: LaunchctlRunner, probe: ProcessProbe, waitMs: number): Promise<boolean> {
-  const deadline = Date.now() + waitMs;
-  for (;;) {
-    if (serviceRunning(runLaunchctl) || probe()) return true;
-    if (Date.now() >= deadline) return false;
-    await Bun.sleep(200);
-  }
-}
-
 export async function launchMenubar(io: CliIo, repositoryRoot: string, asJson: boolean, mode: "foreground" | "background" = "foreground", runBinary: BinaryRunner = spawnBinary): Promise<void> {
   const binary = resolveMenubarBinary(repositoryRoot, io.env);
   if (binary === null) throw new CliError("unavailable", NOT_BUILT);
@@ -295,23 +232,38 @@ export async function launchMenubar(io: CliIo, repositoryRoot: string, asJson: b
   if (asJson) writeJson(io, { running: outcome !== "exited", foreground: mode === "foreground", alreadyRunning: outcome === "already-running" });
   else writeLine(io, launchMessage(outcome, io.env));
 }
-export async function manageMenubar(io: CliIo, repositoryRoot: string, action: "install" | "uninstall" | "status", asJson: boolean, runLaunchctl: LaunchctlRunner = launchctl, probe: ProcessProbe = companionProcessRunning): Promise<void> {
+export async function manageMenubar(io: CliIo, repositoryRoot: string, action: "install" | "uninstall" | "status", asJson: boolean, run: HelperRunner = runHelper): Promise<void> {
   assertMac(io.platform);
   const stable = installedBinaryPath(io.env);
-  let state: LaunchAgentState;
+  const args = asJson ? [action, "--json"] : [action];
+  const env = helperEnvironment(io.env);
+  const forward = (result: HelperResult): void => {
+    if (result.stdout !== "") io.stdout(result.stdout);
+    if (result.code !== 0) throw helperFailure(result);
+    if (result.stderr !== "") io.stderr(result.stderr);
+  };
   if (action === "install") {
     const binary = resolveMenubarBinary(repositoryRoot, io.env);
     if (binary === null) throw new CliError("unavailable", NOT_BUILT);
-    if (!asJson) io.stderr(loginItemNotice(io.env));
-    state = installLaunchAgent(binary, io.env, io.platform, runLaunchctl);
-  } else {
-    state = action === "uninstall" ? uninstallLaunchAgent(stable, io.env, io.platform, runLaunchctl) : launchAgentState(stable, io.env);
+    const installed = binary === stable ? stable : installBinary(binary, io.env);
+    forward(await run(installed, args, env));
+    // The old login item goes only after the new one is in place, so a
+    // failed install never leaves nothing to start at login.
+    removeLegacyAgent(io.env);
+    return;
   }
-  // A fresh login item may take a moment to start, so install waits briefly.
-  const running = state === "installed" && await menubarShowing(runLaunchctl, probe, action === "install" ? 1_000 : 0);
-  if (asJson) writeJson(io, { launchAgent: state, running });
-  else writeLine(io, stateMessage(action, state, running, io.env));
+  if (action === "uninstall") removeLegacyAgent(io.env);
+  if (!exists(stable)) {
+    if (asJson) writeJson(io, { login: "off", running: false, installed: false });
+    else if (action === "uninstall") writeLine(io, `${marks(io.env).ok} Slopcamera won't open at login.`);
+    else writeLine(io, `Slopcamera's menu bar isn't installed.\n${marks(io.env).next} slopcamera menubar install`);
+    return;
+  }
+  const result = await run(stable, args, env);
+  forward(result);
+  if (action === "uninstall") rmSync(stable);
 }
+
 export async function reportOutputsRoot(io: CliIo, stateRoot: string, asJson: boolean): Promise<void> {
   const directory = outputsRoot(stateRoot);
   await ensurePrivateDirectory(directory);

package/apps/desktop/cli/portable-surface.ts

@@ -15,6 +15,10 @@ import {
   type HtmlOverlayScaffoldKind,
 } from "../html-overlay";
 import { CliError } from "./errors";
+import {
+  createHtmlFilmProject, HTML_FILM_ASPECTS, HTML_FILM_TEMPLATES,
+  type HtmlFilmAspect, type HtmlFilmInitResult, type HtmlFilmTemplate,
+} from "./html-film-init";
 
 const HEADLESS_SLOPCAMERA_CLI_MODULE = "@hraness/slopcamera/cli";
 
@@ -42,6 +46,7 @@ export interface PortableSurfaceDependencies {
   readonly log?: (value: string) => void;
   readonly runHeadless?: (argv: readonly string[], options?: Readonly<{ onUsefulResult?: UsefulResultObserver }>) => Promise<void>;
   readonly writeScaffold?: (path: string, html: string) => Promise<void>;
+  readonly createFilm?: typeof createHtmlFilmProject;
 }
 function optionValue(argv: readonly string[], name: string): string | undefined {
   const indexes = argv.flatMap((value, index) => value === name ? [index] : []);
@@ -215,6 +220,53 @@ function runHtmlCatalog(
   return 0;
 }
 
+const HTML_INIT_USAGE = "Use slopcamera html init <dir> --template launch-film [--aspect 16:9|1:1|9:16] [--json].";
+
+async function runHtmlInit(
+  argv: readonly string[],
+  dependencies: PortableSurfaceDependencies,
+): Promise<number> {
+  let directory: string | undefined;
+  let template: string | undefined;
+  let aspect: string | undefined;
+  let json = false;
+  for (let index = 2; index < argv.length; index += 1) {
+    const value = argv[index]!;
+    if (value === "--json") {
+      if (json) throw new CliError("usage", "--json may be supplied at most once.");
+      json = true;
+    } else if (value === "--template" || value === "--aspect") {
+      const next = argv[index + 1];
+      if (next === undefined || next.startsWith("--")) throw new CliError("usage", `${value} requires a value.`);
+      if ((value === "--template" ? template : aspect) !== undefined) throw new CliError("usage", `${value} may be supplied at most once.`);
+      if (value === "--template") template = next;
+      else aspect = next;
+      index += 1;
+    } else if (value.startsWith("-") || directory !== undefined) {
+      throw new CliError("usage", HTML_INIT_USAGE);
+    } else {
+      directory = value;
+    }
+  }
+  if (directory === undefined || template === undefined) throw new CliError("usage", HTML_INIT_USAGE);
+  if (!(HTML_FILM_TEMPLATES as readonly string[]).includes(template)) {
+    throw new CliError("usage", `Unknown film template ${template}. Use one of: ${HTML_FILM_TEMPLATES.join(", ")}.`);
+  }
+  const selectedAspect = aspect ?? "16:9";
+  if (!(HTML_FILM_ASPECTS as readonly string[]).includes(selectedAspect)) {
+    throw new CliError("usage", `--aspect must be one of ${HTML_FILM_ASPECTS.join(", ")}.`);
+  }
+  const result: HtmlFilmInitResult = await (dependencies.createFilm ?? createHtmlFilmProject)(
+    resolve((dependencies.cwd ?? process.cwd)(), directory),
+    { template: template as HtmlFilmTemplate, aspect: selectedAspect as HtmlFilmAspect },
+  );
+  (dependencies.log ?? console.log)(json
+    ? JSON.stringify(result)
+    : [`Created ${result.directory} from ${result.template} (${result.aspect})`, ...result.next.map(line => `next ${line}`)].join("\n"));
+  reportUsefulResult(dependencies.onUsefulResult);
+  return 0;
+}
+
 export async function runPortableSurface(
   argvInput: readonly string[],
   dependencies: PortableSurfaceDependencies = {},
@@ -222,8 +274,10 @@ export async function runPortableSurface(
   const argv = canonicalizeUnifiedCliArgs(argvInput);
   if (argv[0] === "style" && (argv.includes("--help") || argv.includes("-h"))) return undefined;
   if (argv[0] === "html") {
-    if (argv[1] === "render" || argv.includes("--help") || argv.includes("-h")) return undefined;
+    if (argv[1] === "render" || argv[1] === "still" || argv[1] === "preview" || argv[1] === "deliver"
+      || argv.includes("--help") || argv.includes("-h")) return undefined;
     if (argv[1] === "catalog") return runHtmlCatalog(argv, dependencies);
+    if (argv[1] === "init") return await runHtmlInit(argv, dependencies);
     return await runHtmlScaffold(argv, dependencies);
   }
   const delegatesToHeadless = argv[0] === "diagram"