@hraness/slopcamera 3.2.7 → 3.3.1

package/apps/desktop/cli/args.ts

@@ -1,6 +1,10 @@
 import { CliError } from "./errors";
 import { MAX_EVENT_QUERY_LIMIT } from "./query-limits";
 import { STUDIO_TEMPLATES, type StudioTemplate } from "./studio-template-names";
+import {
+  slopcameraGalleryKinds,
+  slopcameraGalleryLimits,
+} from "../../../src/image-gallery";
 
 export type OverlayKind = "image" | "svg" | "gif" | "video" | "emoji";
 export type ZoomTargetKind = "rect" | "point" | "cursor" | "window" | "focused-input";
@@ -58,6 +62,12 @@ export type SpatialWorldCommand = JsonOption & {
   readonly kind: "spatial-world"; readonly action: "import";
   readonly input: string; readonly sourceRoot: string; readonly outputRoot: string;
 };
+export type SpatialAssetCommand = JsonOption & {
+  readonly kind: "spatial-asset"; readonly action: "admit";
+  readonly file: string; readonly output: string;
+  readonly sourceRoot?: string; readonly assetId?: string;
+  readonly metersPerUnit: number; readonly sourceUp: "x" | "y" | "z";
+};
 export type DirectingCommand = JsonOption & { readonly kind: "directing" } & (
   | { readonly action: "init"; readonly path: string }
   | { readonly action: "anchor"; readonly input: string }
@@ -69,12 +79,37 @@ export type DirectingCommand = JsonOption & { readonly kind: "directing" } & (
   | { readonly action: "resume" | "cleanup"; readonly id: string; readonly attempt: string }
   | { readonly action: "review"; readonly id: string; readonly attempt: string; readonly decision: "accepted" | "rejected"; readonly note: string }
 );
-export type SpatialSceneCommand = JsonOption & { readonly kind: "spatial-scene"; readonly path: string } & (
-  | { readonly action: "init" | "inspect" }
-  | { readonly action: "patch"; readonly patch: string; readonly output: string }
-  | { readonly action: "evaluate"; readonly camera: string; readonly timeUs: number }
-  | { readonly action: "camera-track"; readonly request: string; readonly output: string }
-  | { readonly action: "plan" | "render"; readonly request: string; readonly assets?: string; readonly executionProfile?: SpatialCliExecutionProfile }
+export type SpatialSceneCommand = JsonOption & { readonly kind: "spatial-scene" } & (
+  | { readonly action: "init" | "inspect"; readonly path: string }
+  | { readonly action: "diff"; readonly path: string; readonly other: string }
+  | { readonly action: "patch"; readonly path: string; readonly patch: string; readonly output: string }
+  | { readonly action: "evaluate"; readonly path: string; readonly camera: string; readonly timeUs: number }
+  | { readonly action: "audit"; readonly path: string; readonly camera: string; readonly timesUs?: readonly number[]; readonly assetBounds?: string }
+  | { readonly action: "render-audit"; readonly path: string; readonly camera: string; readonly timesUs?: readonly number[] }
+  | { readonly action: "solve"; readonly path: string; readonly goals: string; readonly output?: string; readonly assetBounds?: string }
+  | { readonly action: "review"; readonly path: string; readonly camera: string; readonly timesUs?: readonly number[]; readonly allowCloudUpload: boolean }
+  | { readonly action: "camera-track"; readonly path: string; readonly request: string; readonly output: string }
+  | { readonly action: "plan" | "render"; readonly path: string; readonly request: string; readonly assets?: string; readonly executionProfile?: SpatialCliExecutionProfile }
+  | { readonly action: "generate"; readonly module: string; readonly generatorId: string; readonly parameters?: string; readonly seed?: number; readonly into?: string; readonly output: string }
+  | { readonly action: "direction-check"; readonly direction: string; readonly scene: string }
+  | { readonly action: "direction-plan"; readonly direction: string; readonly scene: string; readonly camera?: string; readonly output?: string }
+  | { readonly action: "direction-gallery"; readonly direction: string; readonly scene: string; readonly axis: string; readonly camera?: string; readonly output?: string }
+  | { readonly action: "effects-check"; readonly effects: string; readonly scene: string }
+  | { readonly action: "effects-plan"; readonly draft: string; readonly scene: string; readonly output?: string }
+  | { readonly action: "effects-bake"; readonly simulation: string; readonly scene: string; readonly output: string }
+  | { readonly action: "behavior-check"; readonly behavior: string; readonly scene: string }
+  | { readonly action: "behavior-bake"; readonly behavior: string; readonly scene: string; readonly channelMap?: string; readonly output: string }
+  | { readonly action: "behavior-gallery"; readonly behavior: string; readonly scene: string; readonly channelMap?: string; readonly output?: string }
+  | { readonly action: "behavior-audit"; readonly bake: string; readonly output?: string }
+  | { readonly action: "temporal-audit"; readonly path: string; readonly camera: string; readonly timesUs?: readonly number[]; readonly contacts?: string; readonly cutBeforeUs?: readonly number[] }
+);
+export type SpatialDesignCommand = JsonOption & { readonly kind: "spatial-design" } & (
+  | { readonly action: "catalog" }
+  | { readonly action: "init"; readonly directory: string; readonly template: string }
+  | { readonly action: "inspect"; readonly path: string }
+  | { readonly action: "set"; readonly path: string; readonly parameters: string; readonly output: string }
+  | { readonly action: "compile"; readonly path: string; readonly scene?: string; readonly outputDir: string }
+  | { readonly action: "gallery"; readonly path: string; readonly scene?: string; readonly variants: string; readonly outputDir: string }
 );
 export type SpatialProjectCommand = JsonOption & {
   readonly kind: "spatial-project"; readonly project: string;
@@ -89,10 +124,13 @@ export type CliCommand =
   | StudioCommand
   | DirectingCommand
   | SpatialWorldCommand
+  | SpatialAssetCommand
   | SpatialSceneCommand
+  | SpatialDesignCommand
   | SpatialProjectCommand
   | { readonly kind: "help"; readonly topic: readonly string[] }
   | { readonly kind: "version" }
+  | ({ readonly kind: "capabilities" } & JsonOption)
   | ({ readonly kind: "operations-list" } & JsonOption)
   | ({ readonly kind: "operations-show"; readonly operation: string } & JsonOption)
   | ({ readonly kind: "diagram-check"; readonly path: string } & JsonOption)
@@ -194,6 +232,29 @@ export type CliCommand =
       readonly temperature: number | undefined;
       readonly timeout: string;
     } & JsonOption)
+  | ({
+      readonly candidatesFile: string | undefined;
+      readonly cell: number | undefined;
+      readonly count: number | undefined;
+      readonly galleryKind: string | undefined;
+      readonly kind: "ai-image-gallery";
+      readonly model: string;
+      readonly outputDir: string;
+      readonly preview: "probe" | undefined;
+      readonly subject: string;
+      readonly tiled: boolean | undefined;
+      readonly timeout: string;
+      readonly vary: string | undefined;
+    } & JsonOption)
+  | ({
+      readonly camera: string | undefined;
+      readonly cell: number | undefined;
+      readonly kind: "ai-scene-gallery";
+      readonly outputDir: string;
+      readonly scene: string;
+      readonly timeUs: number | undefined;
+      readonly variants: string;
+    } & JsonOption)
   | ({
       readonly allowCloudUpload: boolean;
       readonly aspectRatio: string | undefined;
@@ -271,6 +332,8 @@ export type CliCommand =
       readonly tint: number | undefined;
       readonly videoStreamIndex: number;
     } & JsonOption)
+  | ({ readonly kind: "menubar"; readonly action: "run" | "install" | "uninstall" | "status"; readonly mode: "foreground" | "background" } & JsonOption)
+  | ({ readonly kind: "outputs" } & JsonOption)
   | ({ readonly kind: "recordings-list"; readonly limit: number } & JsonOption)
   | ({ readonly kind: "projects-list"; readonly limit: number } & JsonOption)
   | ({
@@ -385,6 +448,16 @@ export type CliCommand =
       readonly project: string;
       readonly width: number;
     } & JsonOption)
+  | ({
+      readonly action: "init" | "check" | "plan" | "animatic" | "run" | "audit" | "gallery";
+      readonly allowPlaceholders: boolean;
+      readonly axis: string | undefined;
+      readonly dryRun: boolean;
+      readonly force: boolean;
+      readonly kind: "project-cinema";
+      readonly output: string | undefined;
+      readonly project: string;
+    } & JsonOption)
   | ({
       readonly apply: boolean;
       readonly candidate: string | undefined;
@@ -490,20 +563,6 @@ export type CliCommand =
       readonly recording: string;
       readonly to: string | undefined;
     })
-  | ({
-      readonly action: "start";
-      readonly cameraDeviceId: string | undefined;
-      readonly displays: readonly string[];
-      readonly microphone: boolean;
-      readonly microphoneDeviceId: string | undefined;
-      readonly strictInputs: boolean;
-      readonly systemAudio: boolean;
-      readonly typedText: boolean;
-      readonly webcam: boolean;
-    } & JsonOption & { readonly kind: "record" })
-  | ({ readonly action: "pause" | "resume" | "stop" | "status" } & JsonOption & {
-      readonly kind: "record";
-    })
   | ({
       readonly edit: EditCommand;
       readonly fps: number | undefined;
@@ -799,22 +858,6 @@ function strictBoolean(value: string | undefined, name: string, defaults: boolea
   fail(`${name} must be true or false.`);
 }
 
-function captureSourceId(
-  value: string | undefined,
-  name: string,
-  maximumUTF8Bytes: number,
-): string | undefined {
-  if (value === undefined) return undefined;
-  if (
-    value.length === 0
-    || value.includes("\0")
-    || new TextEncoder().encode(value).byteLength > maximumUTF8Bytes
-  ) {
-    fail(`${name} must be a non-empty, non-NUL source ID of at most ${maximumUTF8Bytes} UTF-8 bytes.`);
-  }
-  return value;
-}
-
 function oneOf<T extends string>(
   value: string | undefined,
   name: string,
@@ -837,6 +880,12 @@ function exactPositionals(parsed: ParsedOptions, count: number, usage: string):
 
 const JSON_SPEC = { "--json": "flag" } as const;
 
+function parseCapabilities(argv: readonly string[]): CliCommand {
+  const parsed = parseOptions(argv, JSON_SPEC);
+  exactPositionals(parsed, 0, "slopcamera capabilities [--json]");
+  return { json: optionFlag(parsed, "--json"), kind: "capabilities" };
+}
+
 function parseDoctor(argv: readonly string[]): CliCommand {
   const parsed = parseOptions(argv, JSON_SPEC);
   exactPositionals(parsed, 0, "slopcamera doctor [--json]");
@@ -939,7 +988,10 @@ function parseAiProviderOptions(argv: readonly string[]): CliCommand {
 }
 
 function parseAiImage(argv: readonly string[]): CliCommand {
-  if (argv[0] !== "generate") fail("Usage: slopcamera ai image generate --model <id> [options]");
+  if (argv[0] === "gallery") return parseAiImageGallery(argv.slice(1));
+  if (argv[0] !== "generate") {
+    fail("Usage: slopcamera ai image <generate|gallery> --model <id> [options]");
+  }
   const parsed = parseOptions(argv.slice(1), {
     ...JSON_SPEC,
     "--allow-cloud-upload": "flag",
@@ -997,6 +1049,145 @@ function parseAiImage(argv: readonly string[]): CliCommand {
   };
 }
 
+function parseAiImageGallery(argv: readonly string[]): CliCommand {
+  const parsed = parseOptions(argv, {
+    ...JSON_SPEC,
+    "--candidates": "value",
+    "--cell": "value",
+    "--count": "value",
+    "--kind": "value",
+    "--model": "value",
+    "--no-tile": "flag",
+    "--output-dir": "value",
+    "--preview": "value",
+    "--tile": "flag",
+    "--timeout": "value",
+    "--vary": "value",
+  });
+  const [subject] = exactPositionals(
+    parsed,
+    1,
+    "slopcamera ai image gallery <subject> --model <id> --output-dir <directory> [options]",
+  );
+  const model = optionString(parsed, "--model");
+  if (model === undefined) fail("--model is required.");
+  const outputDir = optionString(parsed, "--output-dir");
+  if (outputDir === undefined || outputDir.trim() === "") {
+    fail("--output-dir is required.");
+  }
+  const galleryKind = optionString(parsed, "--kind");
+  if (
+    galleryKind !== undefined
+    && !(slopcameraGalleryKinds as readonly string[]).includes(galleryKind)
+  ) {
+    fail(`--kind must be one of: ${slopcameraGalleryKinds.join(", ")}.`);
+  }
+  const count = optionalStrictInteger(optionString(parsed, "--count"), "--count");
+  if (count !== undefined && count > slopcameraGalleryLimits.candidates) {
+    fail(`--count must be at most ${slopcameraGalleryLimits.candidates}.`);
+  }
+  const cell = optionalStrictInteger(optionString(parsed, "--cell"), "--cell");
+  if (
+    cell !== undefined
+    && (
+      cell < slopcameraGalleryLimits.cellEdgeMin
+      || cell > slopcameraGalleryLimits.cellEdgeMax
+    )
+  ) {
+    fail(
+      `--cell must be between ${slopcameraGalleryLimits.cellEdgeMin} and ${slopcameraGalleryLimits.cellEdgeMax}.`,
+    );
+  }
+  const candidatesFile = optionString(parsed, "--candidates");
+  const vary = optionString(parsed, "--vary");
+  if (candidatesFile !== undefined && (vary !== undefined || count !== undefined)) {
+    fail("--candidates is mutually exclusive with --vary and --count.");
+  }
+  const tile = optionFlag(parsed, "--tile");
+  const noTile = optionFlag(parsed, "--no-tile");
+  if (tile && noTile) fail("--tile and --no-tile are mutually exclusive.");
+  const preview = optionString(parsed, "--preview");
+  if (preview !== undefined && preview !== "probe") {
+    fail("--preview must be probe.");
+  }
+  if (
+    preview === "probe"
+    && !["texture", "skybox", "backdrop"].includes(galleryKind ?? "image")
+  ) {
+    fail("--preview probe requires --kind texture, skybox, or backdrop.");
+  }
+  return {
+    candidatesFile,
+    cell,
+    count,
+    galleryKind,
+    json: optionFlag(parsed, "--json"),
+    kind: "ai-image-gallery",
+    model,
+    outputDir,
+    preview: preview as "probe" | undefined,
+    subject: subject!,
+    tiled: tile ? true : noTile ? false : undefined,
+    timeout: optionString(parsed, "--timeout") ?? "10m",
+    vary,
+  };
+}
+
+function parseAiScene(argv: readonly string[]): CliCommand {
+  if (argv[0] !== "gallery") {
+    fail("Usage: slopcamera ai scene gallery <scene.json> --variants <file.json> --output-dir <directory> [options]");
+  }
+  const parsed = parseOptions(argv.slice(1), {
+    ...JSON_SPEC,
+    "--camera": "value",
+    "--cell": "value",
+    "--output-dir": "value",
+    "--time-us": "value",
+    "--variants": "value",
+  });
+  const [scene] = exactPositionals(
+    parsed,
+    1,
+    "slopcamera ai scene gallery <scene.json> --variants <file.json> --output-dir <directory> [options]",
+  );
+  const variants = optionString(parsed, "--variants");
+  if (variants === undefined) fail("--variants is required.");
+  const outputDir = optionString(parsed, "--output-dir");
+  if (outputDir === undefined || outputDir.trim() === "") {
+    fail("--output-dir is required.");
+  }
+  const timeUsText = optionString(parsed, "--time-us");
+  let timeUs: number | undefined;
+  if (timeUsText !== undefined) {
+    if (!/^\d+$/u.test(timeUsText) || !Number.isSafeInteger(Number(timeUsText))) {
+      fail("--time-us must be a nonnegative integer microsecond time.");
+    }
+    timeUs = Number(timeUsText);
+  }
+  const cell = optionalStrictInteger(optionString(parsed, "--cell"), "--cell");
+  if (
+    cell !== undefined
+    && (
+      cell < slopcameraGalleryLimits.cellEdgeMin
+      || cell > slopcameraGalleryLimits.cellEdgeMax
+    )
+  ) {
+    fail(
+      `--cell must be between ${slopcameraGalleryLimits.cellEdgeMin} and ${slopcameraGalleryLimits.cellEdgeMax}.`,
+    );
+  }
+  return {
+    camera: optionString(parsed, "--camera"),
+    cell,
+    json: optionFlag(parsed, "--json"),
+    kind: "ai-scene-gallery",
+    outputDir,
+    scene: scene!,
+    timeUs,
+    variants,
+  };
+}
+
 function parseAiVideo(argv: readonly string[]): CliCommand {
   if (argv[0] !== "generate") fail("Usage: slopcamera ai video generate --model <id> [options]");
   const parsed = parseOptions(argv.slice(1), {
@@ -1159,11 +1350,12 @@ function parseAi(argv: readonly string[]): CliCommand {
     case "models": return parseAiModels(argv.slice(1));
     case "provider-options": return parseAiProviderOptions(argv.slice(1));
     case "image": return parseAiImage(argv.slice(1));
+    case "scene": return parseAiScene(argv.slice(1));
     case "video": return parseAiVideo(argv.slice(1));
     case "speech": return parseAiSpeech(argv.slice(1));
     case "transcribe": return parseAiTranscribe(argv.slice(1));
     case undefined:
-    default: fail("Usage: slopcamera ai <models|provider-options|image|video|speech|transcribe> [options]");
+    default: fail("Usage: slopcamera ai <models|provider-options|image|scene|video|speech|transcribe> [options]");
   }
 }
 
@@ -1770,7 +1962,65 @@ function parseProject(argv: readonly string[]): CliCommand {
       width: strictEvenPositiveInteger(optionString(parsed, "--width"), "--width", 1_920),
     };
   }
-  fail("Usage: slopcamera project <inspect|add|edit|render> ...");
+  if (action === "cinema") {
+    const cinemaAction = argv[1];
+    if (
+      cinemaAction !== "init"
+      && cinemaAction !== "check"
+      && cinemaAction !== "plan"
+      && cinemaAction !== "animatic"
+      && cinemaAction !== "run"
+      && cinemaAction !== "audit"
+      && cinemaAction !== "gallery"
+    ) {
+      fail("Usage: slopcamera project cinema <init|check|plan|animatic|run|audit|gallery> <project> [options]");
+    }
+    const parsed = parseOptions(argv.slice(2), {
+      ...JSON_SPEC,
+      "--allow-placeholders": "flag",
+      "--axis": "value",
+      "--dry-run": "flag",
+      "--force": "flag",
+      "--output": "value",
+    });
+    const [project] = exactPositionals(
+      parsed,
+      1,
+      `slopcamera project cinema ${cinemaAction} <project> [options]`,
+    );
+    if (optionFlag(parsed, "--dry-run") && cinemaAction !== "animatic" && cinemaAction !== "run") {
+      fail("--dry-run is valid only for project cinema animatic or run.");
+    }
+    if (optionFlag(parsed, "--force") && cinemaAction !== "init") {
+      fail("--force is valid only for project cinema init.");
+    }
+    const output = optionString(parsed, "--output");
+    if (output !== undefined && (cinemaAction === "init" || cinemaAction === "check" || cinemaAction === "audit")) {
+      fail("--output is valid only for project cinema plan, animatic, run, or gallery.");
+    }
+    const axis = optionString(parsed, "--axis");
+    if (cinemaAction === "gallery" && axis === undefined) {
+      fail("project cinema gallery requires --axis <pacing|transitions|looks|audio|structure|mixed>.");
+    }
+    if (axis !== undefined && cinemaAction !== "gallery") {
+      fail("--axis is valid only for project cinema gallery.");
+    }
+    if (optionFlag(parsed, "--allow-placeholders") && (cinemaAction === "init" || cinemaAction === "check" || cinemaAction === "audit" || cinemaAction === "gallery")) {
+      fail("--allow-placeholders is valid only for project cinema plan, animatic, or run.");
+    }
+    return {
+      action: cinemaAction,
+      allowPlaceholders: optionFlag(parsed, "--allow-placeholders"),
+      axis,
+      dryRun: optionFlag(parsed, "--dry-run"),
+      force: optionFlag(parsed, "--force"),
+      json: optionFlag(parsed, "--json"),
+      kind: "project-cinema",
+      output,
+      project: project!,
+    };
+  }
+  fail("Usage: slopcamera project <inspect|add|edit|render|cinema> ...");
 }
 
 function parseInspect(argv: readonly string[]): CliCommand {
@@ -1825,61 +2075,6 @@ function parseEvents(argv: readonly string[]): CliCommand {
   };
 }
 
-function parseRecord(argv: readonly string[]): CliCommand {
-  const action = argv[0];
-  if (action === "start") {
-    const parsed = parseOptions(argv.slice(1), {
-      ...JSON_SPEC,
-      "--camera-device": "value",
-      "--display": "repeat",
-      "--microphone": "value",
-      "--microphone-device": "value",
-      "--strict-inputs": "flag",
-      "--system-audio": "value",
-      "--typed-text": "value",
-      "--webcam": "value",
-    });
-    exactPositionals(parsed, 0, "slopcamera record start [options]");
-    const displays = optionStrings(parsed, "--display").map((displayId) =>
-      captureSourceId(displayId, "--display", 64)!
-    );
-    if (displays.length > 16) fail("--display may be specified at most 16 times.");
-    if (new Set(displays).size !== displays.length) fail("--display IDs must be unique.");
-    const microphone = strictBoolean(optionString(parsed, "--microphone"), "--microphone", true);
-    const webcam = strictBoolean(optionString(parsed, "--webcam"), "--webcam", true);
-    const cameraDeviceId = captureSourceId(optionString(parsed, "--camera-device"), "--camera-device", 256);
-    const microphoneDeviceId = captureSourceId(
-      optionString(parsed, "--microphone-device"),
-      "--microphone-device",
-      256,
-    );
-    if (!webcam && cameraDeviceId !== undefined) {
-      fail("--camera-device cannot be combined with --webcam false.");
-    }
-    if (!microphone && microphoneDeviceId !== undefined) {
-      fail("--microphone-device cannot be combined with --microphone false.");
-    }
-    return {
-      action,
-      cameraDeviceId,
-      displays,
-      json: optionFlag(parsed, "--json"),
-      kind: "record",
-      microphone,
-      microphoneDeviceId,
-      strictInputs: optionFlag(parsed, "--strict-inputs"),
-      systemAudio: strictBoolean(optionString(parsed, "--system-audio"), "--system-audio", true),
-      typedText: strictBoolean(optionString(parsed, "--typed-text"), "--typed-text", false),
-      webcam,
-    };
-  }
-  if (action === "pause" || action === "resume" || action === "stop" || action === "status") {
-    const parsed = parseOptions(argv.slice(1), JSON_SPEC);
-    exactPositionals(parsed, 0, `slopcamera record ${action} [--json]`);
-    return { action, json: optionFlag(parsed, "--json"), kind: "record" };
-  }
-  fail("Usage: slopcamera record <start|pause|resume|stop|status> [options]");
-}
 
 const TIME_RANGE_SPEC = {
   "--end": "value",
@@ -3073,9 +3268,77 @@ function parseSpatialWorldArgs(argv: readonly string[]): SpatialWorldCommand {
   return fail("Usage: slopcamera scene world import --input <request.json> --source-root <directory> --output-root <artifact-directory>");
 }
 
-function parseSpatialSceneArgs(argv: readonly string[]): SpatialSceneCommand | SpatialProjectCommand | SpatialWorldCommand {
+const SPATIAL_ASSET_ADMIT_USAGE = "slopcamera scene asset admit <model.glb> --output <manifest.json> [--source-root <directory>] [--asset-id <id>] [--meters-per-unit <n>] [--source-up x|y|z] [--json]";
+
+function parseSpatialAssetArgs(argv: readonly string[]): SpatialAssetCommand {
+  const action = argv[0];
+  if (action !== "admit") return fail(`Usage: ${SPATIAL_ASSET_ADMIT_USAGE}`);
+  const parsed = parseOptions(argv.slice(1), {
+    ...JSON_SPEC, "--source-root": "value", "--asset-id": "value",
+    "--meters-per-unit": "value", "--source-up": "value", "--output": "value",
+  });
+  const [file] = exactPositionals(parsed, 1, SPATIAL_ASSET_ADMIT_USAGE);
+  const output = optionString(parsed, "--output");
+  if (output === undefined) fail("scene asset admit requires --output.");
+  const assetId = optionString(parsed, "--asset-id");
+  if (assetId !== undefined && (assetId.length > 128 || !/^asset_[a-zA-Z0-9][a-zA-Z0-9_-]*$/u.test(assetId))) {
+    fail("--asset-id must be an asset_-prefixed identifier of at most 128 characters.");
+  }
+  return {
+    kind: "spatial-asset", action, file: file!, output,
+    ...(optionString(parsed, "--source-root") === undefined ? {} : { sourceRoot: optionString(parsed, "--source-root")! }),
+    ...(assetId === undefined ? {} : { assetId }),
+    metersPerUnit: boundedNumber(optionString(parsed, "--meters-per-unit"), "--meters-per-unit", 0.000001, 1_000_000, 1),
+    sourceUp: oneOf(optionString(parsed, "--source-up"), "--source-up", ["x", "y", "z"], "y"),
+    json: optionFlag(parsed, "--json"),
+  };
+}
+
+function parseSpatialDesignArgs(argv: readonly string[]): SpatialDesignCommand {
+  const action = argv[0];
+  if (action === "catalog") {
+    const parsed = parseOptions(argv.slice(1), JSON_SPEC);
+    exactPositionals(parsed, 0, "slopcamera scene design catalog [--json]");
+    return { kind: "spatial-design", action, json: optionFlag(parsed, "--json") };
+  }
+  if (action === "init") {
+    const parsed = parseOptions(argv.slice(1), { ...JSON_SPEC, "--template": "value" });
+    const [directory] = exactPositionals(parsed, 1, "slopcamera scene design init <directory> --template <id> [--json]");
+    const template = optionString(parsed, "--template");
+    if (template === undefined) return fail("scene design init requires --template; use scene design catalog.");
+    return { kind: "spatial-design", action, directory: directory!, template, json: optionFlag(parsed, "--json") };
+  }
+  if (action === "inspect" || action === "check") {
+    const parsed = parseOptions(argv.slice(1), JSON_SPEC);
+    const [path] = exactPositionals(parsed, 1, "slopcamera scene design inspect <design.json> [--json]");
+    return { kind: "spatial-design", action: "inspect", path: path!, json: optionFlag(parsed, "--json") };
+  }
+  if (action === "set") {
+    const parsed = parseOptions(argv.slice(1), { ...JSON_SPEC, "--parameters": "value", "--output": "value" });
+    const [path] = exactPositionals(parsed, 1, "slopcamera scene design set <design.json> --parameters <values.json> --output <new-design.json> [--json]");
+    const parameters = optionString(parsed, "--parameters"), output = optionString(parsed, "--output");
+    if (parameters === undefined || output === undefined) return fail("scene design set requires --parameters and --output.");
+    return { kind: "spatial-design", action, path: path!, parameters, output, json: optionFlag(parsed, "--json") };
+  }
+  if (action === "compile" || action === "gallery") {
+    const parsed = parseOptions(argv.slice(1), { ...JSON_SPEC, "--scene": "value", "--output-dir": "value", ...(action === "gallery" ? { "--variants": "value" as const } : {}) });
+    const [path] = exactPositionals(parsed, 1, `slopcamera scene design ${action} <design.json> [--scene <scene.json>] --output-dir <new-directory> [--json]`);
+    const scene = optionString(parsed, "--scene"), outputDir = optionString(parsed, "--output-dir");
+    if (outputDir === undefined) return fail(`scene design ${action} requires --output-dir.`);
+    const shared = { kind: "spatial-design" as const, path: path!, ...(scene === undefined ? {} : { scene }), outputDir, json: optionFlag(parsed, "--json") };
+    if (action === "compile") return { ...shared, action };
+    const variants = optionString(parsed, "--variants");
+    if (variants === undefined) return fail("scene design gallery requires --variants.");
+    return { ...shared, action, variants };
+  }
+  return fail("Usage: slopcamera scene design <catalog|init|inspect|set|compile|gallery> ...");
+}
+
+function parseSpatialSceneArgs(argv: readonly string[]): SpatialSceneCommand | SpatialDesignCommand | SpatialProjectCommand | SpatialWorldCommand | SpatialAssetCommand {
   const action = argv[0];
+  if (action === "design") return parseSpatialDesignArgs(argv.slice(1));
   if (action === "world") return parseSpatialWorldArgs(argv.slice(1));
+  if (action === "asset") return parseSpatialAssetArgs(argv.slice(1));
   if (action === "project") {
     const projectAction = argv[1];
     if (projectAction === "snapshot") {
@@ -3105,6 +3368,11 @@ function parseSpatialSceneArgs(argv: readonly string[]): SpatialSceneCommand | S
     const [path] = exactPositionals(parsed, 1, `slopcamera scene ${action} <scene.json> [--json]`);
     return { kind: "spatial-scene", action: action === "check" ? "inspect" : action, path: path!, json: optionFlag(parsed, "--json") };
   }
+  if (action === "diff") {
+    const parsed = parseOptions(argv.slice(1), JSON_SPEC);
+    const [path, other] = exactPositionals(parsed, 2, "slopcamera scene diff <scene-a.json> <scene-b.json> [--json]");
+    return { kind: "spatial-scene", action, path: path!, other: other!, json: optionFlag(parsed, "--json") };
+  }
   if (action === "patch") {
     const parsed = parseOptions(argv.slice(1), { ...JSON_SPEC, "--patch": "value", "--output": "value" });
     const [path] = exactPositionals(parsed, 1, "slopcamera scene patch <scene.json> --patch <patch.json> --output <new-scene.json>");
@@ -3126,6 +3394,54 @@ function parseSpatialSceneArgs(argv: readonly string[]): SpatialSceneCommand | S
     if (camera === undefined || time === undefined || !/^\d+$/u.test(time) || !Number.isSafeInteger(Number(time))) fail("scene evaluate requires --camera and integer --time-us.");
     return { kind: "spatial-scene", action, path: path!, camera, timeUs: Number(time), json: optionFlag(parsed, "--json") };
   }
+  if (action === "audit") {
+    const parsed = parseOptions(argv.slice(1), { ...JSON_SPEC, "--camera": "value", "--times-us": "value", "--asset-bounds": "value" });
+    const [path] = exactPositionals(parsed, 1, "slopcamera scene audit <scene.json> --camera <camera-id> [--times-us <csv>] [--asset-bounds <bounds-or-admission.json>] [--json]");
+    const camera = optionString(parsed, "--camera"), times = optionString(parsed, "--times-us"), assetBounds = optionString(parsed, "--asset-bounds");
+    if (camera === undefined) fail("scene audit requires --camera.");
+    let timesUs: number[] | undefined;
+    if (times !== undefined) {
+      if (!/^\d+(,\d+)*$/u.test(times)) return fail("scene audit --times-us must be a comma-separated list of nonnegative integers.");
+      timesUs = times.split(",").map(Number);
+      if (timesUs.length > 64) return fail("scene audit --times-us is bounded to 64 samples.");
+    }
+    return { kind: "spatial-scene", action, path: path!, camera, ...(timesUs === undefined ? {} : { timesUs }), ...(assetBounds === undefined ? {} : { assetBounds }), json: optionFlag(parsed, "--json") };
+  }
+  if (action === "render-audit") {
+    const parsed = parseOptions(argv.slice(1), { ...JSON_SPEC, "--camera": "value", "--times-us": "value" });
+    const [path] = exactPositionals(parsed, 1, "slopcamera scene render-audit <scene.json> --camera <camera-id> [--times-us <csv>] [--json]");
+    const camera = optionString(parsed, "--camera"), times = optionString(parsed, "--times-us");
+    if (camera === undefined) fail("scene render-audit requires --camera.");
+    let timesUs: number[] | undefined;
+    if (times !== undefined) {
+      if (!/^\d+(,\d+)*$/u.test(times)) return fail("scene render-audit --times-us must be a comma-separated list of nonnegative integers.");
+      timesUs = times.split(",").map(Number);
+      if (timesUs.length > 64) return fail("scene render-audit --times-us is bounded to 64 samples.");
+    }
+    return { kind: "spatial-scene", action, path: path!, camera, ...(timesUs === undefined ? {} : { timesUs }), json: optionFlag(parsed, "--json") };
+  }
+  if (action === "solve") {
+    const parsed = parseOptions(argv.slice(1), { ...JSON_SPEC, "--goals": "value", "--output": "value", "--asset-bounds": "value" });
+    const [path] = exactPositionals(parsed, 1, "slopcamera scene solve <scene.json> --goals <goals.json> [--output <patch.json>] [--asset-bounds <bounds-or-admission.json>] [--json]");
+    const goals = optionString(parsed, "--goals"), output = optionString(parsed, "--output"), assetBounds = optionString(parsed, "--asset-bounds");
+    if (goals === undefined) fail("scene solve requires --goals.");
+    return { kind: "spatial-scene", action, path: path!, goals, ...(output === undefined ? {} : { output }), ...(assetBounds === undefined ? {} : { assetBounds }), json: optionFlag(parsed, "--json") };
+  }
+  if (action === "review") {
+    const parsed = parseOptions(argv.slice(1), { ...JSON_SPEC, "--camera": "value", "--times-us": "value", "--allow-cloud-upload": "flag" });
+    const [path] = exactPositionals(parsed, 1, "slopcamera scene review <scene.json> --camera <camera-id> [--times-us <csv>] --allow-cloud-upload [--json]");
+    const camera = optionString(parsed, "--camera"), times = optionString(parsed, "--times-us");
+    if (camera === undefined) fail("scene review requires --camera.");
+    let timesUs: number[] | undefined;
+    if (times !== undefined) {
+      if (!/^\d+(,\d+)*$/u.test(times)) return fail("scene review --times-us must be a comma-separated list of nonnegative integers.");
+      timesUs = times.split(",").map(Number);
+      if (timesUs.length > 4) return fail("scene review --times-us is bounded to 4 samples.");
+      if (timesUs.some(value => !Number.isSafeInteger(value))) return fail("scene review --times-us values must be safe integers.");
+      if (new Set(timesUs).size !== timesUs.length) return fail("scene review --times-us values must be unique.");
+    }
+    return { kind: "spatial-scene", action, path: path!, camera, ...(timesUs === undefined ? {} : { timesUs }), allowCloudUpload: optionFlag(parsed, "--allow-cloud-upload"), json: optionFlag(parsed, "--json") };
+  }
   if (action === "plan" || action === "render") {
     const parsed = parseOptions(argv.slice(1), { ...JSON_SPEC, "--request": "value", "--assets": "value", "--profile": "value" });
     const [path] = exactPositionals(parsed, 1, `slopcamera scene ${action} <scene.json> --request <request.json> [--assets <bindings.json>]`);
@@ -3134,7 +3450,110 @@ function parseSpatialSceneArgs(argv: readonly string[]): SpatialSceneCommand | S
     const executionProfile = spatialCliExecutionProfile(optionString(parsed, "--profile"));
     return { kind: "spatial-scene", action, path: path!, request, ...(assets === undefined ? {} : { assets }), ...(executionProfile === undefined ? {} : { executionProfile }), json: optionFlag(parsed, "--json") };
   }
-  fail("Usage: slopcamera scene <init|check|inspect|patch|evaluate|camera-track|plan|render> ...");
+  if (action === "generate") {
+    const parsed = parseOptions(argv.slice(1), { ...JSON_SPEC, "--module": "value", "--generator-id": "value", "--parameters": "value", "--seed": "value", "--into": "value", "--output": "value" });
+    exactPositionals(parsed, 0, "slopcamera scene generate --module <generator.ts> --generator-id <id> [--parameters <params.json>] [--seed <n>] [--into <scene.json>] --output <new-scene.json> [--json]");
+    const modulePath = optionString(parsed, "--module"), generatorId = optionString(parsed, "--generator-id"), output = optionString(parsed, "--output");
+    if (modulePath === undefined || generatorId === undefined || output === undefined) fail("scene generate requires --module, --generator-id, and --output.");
+    const seed = optionalNonNegativeInteger(optionString(parsed, "--seed"), "--seed");
+    if (seed !== undefined && seed > 0xffff_ffff) fail("--seed must be between 0 and 4294967295.");
+    const parameters = optionString(parsed, "--parameters"), into = optionString(parsed, "--into");
+    return { kind: "spatial-scene", action, module: modulePath, generatorId, output, ...(parameters === undefined ? {} : { parameters }), ...(seed === undefined ? {} : { seed }), ...(into === undefined ? {} : { into }), json: optionFlag(parsed, "--json") };
+  }
+  if (action === "direction") {
+    const directionAction = argv[1];
+    if (directionAction === "check") {
+      const parsed = parseOptions(argv.slice(2), { ...JSON_SPEC, "--scene": "value" });
+      const [direction] = exactPositionals(parsed, 1, "slopcamera scene direction check <direction.json> --scene <scene.json> [--json]");
+      const scene = optionString(parsed, "--scene");
+      if (scene === undefined) fail("scene direction check requires --scene.");
+      return { kind: "spatial-scene", action: "direction-check", direction: direction!, scene, json: optionFlag(parsed, "--json") };
+    }
+    if (directionAction === "plan" || directionAction === "gallery") {
+      const parsed = parseOptions(argv.slice(2), { ...JSON_SPEC, "--axis": "value", "--camera": "value", "--output": "value", "--scene": "value" });
+      const [direction] = exactPositionals(parsed, 1, `slopcamera scene direction ${directionAction} <direction.json> --scene <scene.json>${directionAction === "gallery" ? " --axis <axis>" : ""} [--camera <camera-id>] [--output <out.json>] [--json]`);
+      const scene = optionString(parsed, "--scene"), camera = optionString(parsed, "--camera"), output = optionString(parsed, "--output"), axis = optionString(parsed, "--axis");
+      if (scene === undefined) fail(`scene direction ${directionAction} requires --scene.`);
+      if (directionAction === "gallery" && axis === undefined) fail("scene direction gallery requires --axis.");
+      return directionAction === "gallery"
+        ? { kind: "spatial-scene", action: "direction-gallery", direction: direction!, scene, axis: axis!, ...(camera === undefined ? {} : { camera }), ...(output === undefined ? {} : { output }), json: optionFlag(parsed, "--json") }
+        : { kind: "spatial-scene", action: "direction-plan", direction: direction!, scene, ...(camera === undefined ? {} : { camera }), ...(output === undefined ? {} : { output }), json: optionFlag(parsed, "--json") };
+    }
+    fail("Usage: slopcamera scene direction <check|plan|gallery> ...");
+  }
+  if (action === "effects") {
+    const effectsAction = argv[1];
+    if (effectsAction === "check") {
+      const parsed = parseOptions(argv.slice(2), { ...JSON_SPEC, "--scene": "value" });
+      const [effects] = exactPositionals(parsed, 1, "slopcamera scene effects check <effects.json> --scene <scene.json> [--json]");
+      const scene = optionString(parsed, "--scene");
+      if (scene === undefined) fail("scene effects check requires --scene.");
+      return { kind: "spatial-scene", action: "effects-check", effects: effects!, scene, json: optionFlag(parsed, "--json") };
+    }
+    if (effectsAction === "plan") {
+      const parsed = parseOptions(argv.slice(2), { ...JSON_SPEC, "--output": "value", "--scene": "value" });
+      const [draft] = exactPositionals(parsed, 1, "slopcamera scene effects plan <draft.json> --scene <scene.json> [--output <effects.json>] [--json]");
+      const scene = optionString(parsed, "--scene"), output = optionString(parsed, "--output");
+      if (scene === undefined) fail("scene effects plan requires --scene.");
+      return { kind: "spatial-scene", action: "effects-plan", draft: draft!, scene, ...(output === undefined ? {} : { output }), json: optionFlag(parsed, "--json") };
+    }
+    if (effectsAction === "bake") {
+      const parsed = parseOptions(argv.slice(2), { ...JSON_SPEC, "--output": "value", "--scene": "value" });
+      const [simulation] = exactPositionals(parsed, 1, "slopcamera scene effects bake <simulation.json> --scene <scene.json> --output <receipt.json> [--json]");
+      const scene = optionString(parsed, "--scene"), output = optionString(parsed, "--output");
+      if (scene === undefined || output === undefined) fail("scene effects bake requires --scene and --output.");
+      return { kind: "spatial-scene", action: "effects-bake", simulation: simulation!, scene, output, json: optionFlag(parsed, "--json") };
+    }
+    fail("Usage: slopcamera scene effects <check|plan|bake> ...");
+  }
+  if (action === "behavior") {
+    const behaviorAction = argv[1];
+    if (behaviorAction === "check") {
+      const parsed = parseOptions(argv.slice(2), { ...JSON_SPEC, "--scene": "value" });
+      const [behavior] = exactPositionals(parsed, 1, "slopcamera scene behavior check <behavior.json> --scene <scene.json> [--json]");
+      const scene = optionString(parsed, "--scene");
+      if (scene === undefined) fail("scene behavior check requires --scene.");
+      return { kind: "spatial-scene", action: "behavior-check", behavior: behavior!, scene, json: optionFlag(parsed, "--json") };
+    }
+    if (behaviorAction === "bake" || behaviorAction === "gallery") {
+      const parsed = parseOptions(argv.slice(2), { ...JSON_SPEC, "--channel-map": "value", "--output": "value", "--scene": "value" });
+      const [behavior] = exactPositionals(parsed, 1, `slopcamera scene behavior ${behaviorAction} <behavior.json> --scene <scene.json> [--channel-map <map.json>]${behaviorAction === "bake" ? " --output <bake.json>" : " [--output <gallery.json>]"} [--json]`);
+      const scene = optionString(parsed, "--scene"), channelMap = optionString(parsed, "--channel-map"), output = optionString(parsed, "--output");
+      if (scene === undefined) fail(`scene behavior ${behaviorAction} requires --scene.`);
+      if (behaviorAction === "bake" && output === undefined) fail("scene behavior bake requires --output.");
+      const shared = { kind: "spatial-scene" as const, behavior: behavior!, scene, ...(channelMap === undefined ? {} : { channelMap }), json: optionFlag(parsed, "--json") };
+      return behaviorAction === "bake"
+        ? { ...shared, action: "behavior-bake", output: output! }
+        : { ...shared, action: "behavior-gallery", ...(output === undefined ? {} : { output }) };
+    }
+    if (behaviorAction === "audit") {
+      const parsed = parseOptions(argv.slice(2), { ...JSON_SPEC, "--output": "value" });
+      const [bake] = exactPositionals(parsed, 1, "slopcamera scene behavior audit <bake.json> [--output <audit.json>] [--json]");
+      const output = optionString(parsed, "--output");
+      return { kind: "spatial-scene", action: "behavior-audit", bake: bake!, ...(output === undefined ? {} : { output }), json: optionFlag(parsed, "--json") };
+    }
+    fail("Usage: slopcamera scene behavior <check|bake|gallery|audit> ...");
+  }
+  if (action === "temporal-audit") {
+    const parsed = parseOptions(argv.slice(1), { ...JSON_SPEC, "--camera": "value", "--contacts": "value", "--cut-before-us": "value", "--times-us": "value" });
+    const [path] = exactPositionals(parsed, 1, "slopcamera scene temporal-audit <scene.json> --camera <camera-id> [--times-us <csv>] [--contacts <contacts.json>] [--cut-before-us <csv>] [--json]");
+    const camera = optionString(parsed, "--camera"), times = optionString(parsed, "--times-us"), contacts = optionString(parsed, "--contacts"), cutBefore = optionString(parsed, "--cut-before-us");
+    if (camera === undefined) fail("scene temporal-audit requires --camera.");
+    let timesUs: number[] | undefined;
+    if (times !== undefined) {
+      if (!/^\d+(,\d+)*$/u.test(times)) return fail("scene temporal-audit --times-us must be a comma-separated list of nonnegative integers.");
+      timesUs = times.split(",").map(Number);
+      if (timesUs.length > 64) return fail("scene temporal-audit --times-us is bounded to 64 samples.");
+    }
+    let cutBeforeUs: number[] | undefined;
+    if (cutBefore !== undefined) {
+      if (!/^\d+(,\d+)*$/u.test(cutBefore)) return fail("scene temporal-audit --cut-before-us must be a comma-separated list of nonnegative integers.");
+      cutBeforeUs = cutBefore.split(",").map(Number);
+      if (cutBeforeUs.length > 64) return fail("scene temporal-audit --cut-before-us is bounded to 64 values.");
+    }
+    return { kind: "spatial-scene", action, path: path!, camera, ...(timesUs === undefined ? {} : { timesUs }), ...(contacts === undefined ? {} : { contacts }), ...(cutBeforeUs === undefined ? {} : { cutBeforeUs }), json: optionFlag(parsed, "--json") };
+  }
+  fail("Usage: slopcamera scene <init|check|inspect|diff|patch|evaluate|audit|render-audit|solve|review|camera-track|generate|plan|render|direction|effects|behavior|temporal-audit|asset|project|world> ...");
 }
 
 export function parseCliArgs(argv: readonly string[]): CliCommand {
@@ -3162,6 +3581,7 @@ export function parseCliArgs(argv: readonly string[]): CliCommand {
     case "direct": return parseDirectingArgs(argv.slice(1));
     case "scene": return parseSpatialSceneArgs(argv.slice(1));
     case "operations": return parseOperations(argv.slice(1));
+    case "capabilities": return parseCapabilities(argv.slice(1));
     case "diagram": return parseDiagram(argv.slice(1));
     case "image": return parseImage(argv.slice(1));
     case "workflows": return parseWorkflows(argv.slice(1));
@@ -3175,7 +3595,18 @@ export function parseCliArgs(argv: readonly string[]): CliCommand {
     case "project": return parseProject(argv.slice(1));
     case "inspect": return parseInspect(argv.slice(1));
     case "events": return parseEvents(argv.slice(1));
-    case "record": return parseRecord(argv.slice(1));
+    case "menubar": {
+      const parsed = parseOptions(argv.slice(1), { ...JSON_SPEC, "--foreground": "flag", "--background": "flag" });
+      const positionals = parsed.positionals;
+      if (positionals.length > 1 || (positionals[0] !== undefined && !["install", "uninstall", "status"].includes(positionals[0]))) throw new CliError("usage", "Use slopcamera menubar [--foreground|--background] | install|uninstall|status");
+      if (positionals[0] !== undefined && (optionFlag(parsed, "--foreground") || optionFlag(parsed, "--background"))) throw new CliError("usage", "Choose a menu-bar action or a run mode, not both.");
+      return { kind: "menubar", action: (positionals[0] as "install" | "uninstall" | "status" | undefined) ?? "run", mode: optionFlag(parsed, "--background") ? "background" : "foreground", json: optionFlag(parsed, "--json") };
+    }
+    case "outputs": {
+      const parsed = parseOptions(argv.slice(1), JSON_SPEC);
+      exactPositionals(parsed, 0, "slopcamera outputs [--json]");
+      return { kind: "outputs", json: optionFlag(parsed, "--json") };
+    }
     case "edit": return parseEdit(argv.slice(1));
     case "analyze": return parseAnalyze(argv.slice(1));
     case "faces": return parseFaces(argv.slice(1));