@hraness/slopcamera 3.2.7 → 3.3.1

package/apps/desktop/cli/commands.ts

@@ -1,12 +1,49 @@
+import { reportUsefulResult, type UsefulResultObserver } from "../../../src/support-completion";
+import { SlopcameraCloudError } from "../../../src/cloud-errors";
+import {
+  composeSlopcameraImageGallery,
+  parseSlopcameraGalleryVary,
+  planSlopcameraGallery,
+  slopcameraGalleryLimits,
+  type SlopcameraGalleryCandidate,
+  type SlopcameraGalleryKind,
+  type SlopcameraGalleryPlan,
+  type SlopcameraGalleryResolvedCandidate,
+} from "../../../src/image-gallery";
+import {
+  galleryProbeRenderRequest,
+  galleryProbeScene,
+  type SlopcameraGalleryProbeMode,
+} from "../../../src/spatial-scene/probe";
+import {
+  planSlopcameraSceneGallery,
+  slopcameraSceneGalleryLimits,
+  type SlopcameraSceneGalleryVariant,
+} from "../../../src/scene-gallery";
+import {
+  parseSpatialScene,
+  spatialSceneSha256,
+} from "../../../src/spatial-scene/identity";
+import {
+  SPATIAL_SCENE_LIMITS,
+  type SpatialSceneV1,
+} from "../../../src/spatial-scene/contracts";
 import { createDirectingBlobSession } from "./directing-blob";
 import { assembleDirectingClips, extractDirectingEndpoint, importDirectingAnchor } from "./directing-media";
 import { executeDirectingCommand } from "./directing-service";
 import { createHash, randomUUID } from "node:crypto";
-import { executeSpatialSceneCommand } from "./spatial-scene-service";
+import sharp from "sharp";
+import { executeSpatialAssetCommand } from "./spatial-asset-service";
+import { executeSpatialDesignCommand } from "./spatial-design-service";
+import {
+  executeSpatialSceneCommand,
+  publishSpatialSource,
+  readSpatialJson,
+} from "./spatial-scene-service";
 import { executeSpatialProjectCommand } from "./spatial-project-service";
 import { executeSpatialWorldCommand } from "./spatial-world-service";
 import { constants } from "node:fs";
-import { link, lstat, open, realpath, rm } from "node:fs/promises";
+import { link, lstat, mkdir, open, realpath, rm } from "node:fs/promises";
 import { basename, dirname, extname, isAbsolute, join, relative, resolve } from "node:path";
 import {
   createDefaultHostResourceCoordinator,
@@ -20,6 +57,9 @@ import {
   AnalyzerEvidenceV1Schema,
   AlignmentCandidateIdSchema,
   AudioAlignmentAnalysisV1Schema,
+  CinemaContinuityReportSchema,
+  CinemaPlanIdSchema,
+  CinemaRenderReceiptV1Schema,
   EventKindSchema,
   MusicAnalysisV1Schema,
   OverlayOperationSchema,
@@ -49,12 +89,18 @@ import {
   applyProjectInactivityPlan,
   analyzeAudioAlignment,
   applyAudioAlignmentCandidate,
+  analyzeCinemaPlan,
   addZoom,
+  assertCinemaPlanComposition,
+  auditCinemaContinuity,
+  auditCinemaTemporal,
   buildProjectOutputTimeMap,
   buildSourceTimeMap,
   canonicalSlopcameraPersistenceDocument,
   canonicalJson,
+  compileCinemaSequence,
   compileProjectRenderPlan,
+  createCinemaPlanScaffold,
   compileRenderPlan,
   createNodeBundleFileSystem,
   createDefaultEditPlan,
@@ -69,11 +115,17 @@ import {
   normalizeProjectEditPlan,
   planAutomaticInactivityCuts,
   planAutomaticZooms,
+  planCinemaGallery,
   projectFillerCut,
   removeOverlay,
   removeZoom,
   saveEditPlan,
   saveAnalysisArtifact,
+  saveImmutableText,
+  loadProjectCinemaPlan,
+  projectCinemaRenderPlanPath,
+  saveProjectCinemaPlan,
+  saveProjectCinemaRevision,
   saveProjectEditPlan,
   setSpeed,
   rebaseProjectEditPlan,
@@ -132,9 +184,11 @@ import {
 import { resolveEmojiAsset, searchEmojiAssets, inspectEmojiAssets } from "./emoji-assets";
 import { asCliError, CliError, EXIT_CODE } from "./errors";
 import { commandHelp, completions } from "./help";
+import { createLocalSlopcameraCapabilityManifest } from "./capability-manifest";
 import { PlaywrightHtmlOverlayRenderer } from "./html-overlay-renderer";
 import { executeHtmlSceneCommand } from "./html-scene";
 import { BunProcessRunner, processIo, writeJson, writeLine, type CliIo, type ProcessRunner } from "./io";
+import { launchMenubar, manageMenubar, reportOutputsRoot } from "./menubar";
 import {
   codePreparationHostResourceClaims,
   combineHostResourceClaims,
@@ -175,13 +229,8 @@ import {
   type OpenProject,
 } from "./project-service";
 import { resolveVerifiedProjectMedia } from "./project-media-integrity";
-import {
-  executeRecordingAction,
-  type RecordingController,
-  type RecordingSnapshot,
-  type RecordingStartOptions,
-} from "./recording-controller";
 import { buildFfmpegInvocation, prepareOverlaySources } from "./renderer";
+import { buildCinemaFfmpegInvocation } from "./cinema-renderer";
 import { buildProjectFfmpegInvocation } from "./project-renderer";
 import {
   DEFAULT_PROJECT_INACTIVITY_CONFIG,
@@ -190,6 +239,7 @@ import {
 import { resolveAnimatedPlaybackWindow } from "./overlay-playback";
 import { analyzeProjectScenes } from "./scene-analysis-service";
 import type { SceneDescriptionProvider } from "@hraness/slopcamera/scene";
+import type { SpatialReviewProvider } from "../../../src/spatial-scene/review";
 import { parseCliTime } from "./time";
 import {
   DEFAULT_FACE_ANALYSIS_CONFIG,
@@ -218,6 +268,10 @@ import {
   createGatewaySceneProvider,
   type GatewaySceneProviderOptions,
 } from "./gateway-scene-provider";
+import {
+  createGatewaySpatialReviewProvider,
+  type GatewaySpatialReviewProviderOptions,
+} from "./gateway-review-provider";
 import {
   GatewayMediaCatalogError,
   createFileGatewayMediaCatalogSnapshotStore,
@@ -301,7 +355,7 @@ import {
   workflowRunStore,
 } from "./workflow-runs";
 
-export const SLOPCAMERA_VERSION = "3.2.7";
+export const SLOPCAMERA_VERSION = "3.3.1";
 
 // Legacy direct renders predate per-target output contracts. Keep them
 // bounded generously enough for long-form production while preventing one
@@ -310,6 +364,7 @@ const MAXIMUM_LEGACY_RECORDING_RENDER_OUTPUT_BYTES = 32 * 1024 * 1024 * 1024;
 const MAXIMUM_LEGACY_PROJECT_RENDER_OUTPUT_BYTES = 32 * 1024 * 1024 * 1024;
 
 export interface CliDependencies {
+  readonly onUsefulResult?: UsefulResultObserver;
   readonly abortSignal?: AbortSignal;
   readonly stateRoot?: string;
   readonly clock?: () => number;
@@ -320,11 +375,38 @@ export interface CliDependencies {
   readonly hostResourceCoordinator?: HostResourceCoordinator;
   readonly io?: CliIo;
   readonly paths?: RepositoryPaths;
-  readonly recordingController?: RecordingController;
   readonly runner?: ProcessRunner;
   readonly sceneProviderFactory?: (options: GatewaySceneProviderOptions) => SceneDescriptionProvider;
+  readonly spatialReviewProviderFactory?: (options: GatewaySpatialReviewProviderOptions) => SpatialReviewProvider;
   readonly sleep?: (milliseconds: number) => Promise<void>;
   readonly version?: string;
+  /**
+   * Test/review seam for gallery scene renders (`ai image gallery
+   * --preview probe` and `ai scene gallery`): renders one bounded scene
+   * source into a still. The production default runs the real
+   * `scene.render` operation.
+   */
+  readonly renderGalleryScene?: (input: {
+    readonly application: ApplicationContext;
+    readonly assets?: readonly {
+      readonly assetId: string;
+      readonly artifact: {
+        readonly bytes: number;
+        readonly path: string;
+        readonly sha256: string;
+      };
+    }[];
+    readonly request?: unknown;
+    readonly sceneSha256?: string;
+    readonly source: { readonly path: string };
+  }) => Promise<{
+    readonly artifact: {
+      readonly bytes: number;
+      readonly path: string;
+      readonly sha256: string;
+    };
+    readonly receipt?: { readonly path: string };
+  }>;
 }
 
 interface CommandContext {
@@ -347,11 +429,12 @@ interface CommandContext {
   readonly hostResourceCoordinator: HostResourceCoordinator;
   readonly io: CliIo;
   readonly paths: RepositoryPaths;
-  readonly recordingController: RecordingController | undefined;
   readonly runner: ProcessRunner;
   readonly sceneProviderFactory: (options: GatewaySceneProviderOptions) => SceneDescriptionProvider;
+  readonly spatialReviewProviderFactory: (options: GatewaySpatialReviewProviderOptions) => SpatialReviewProvider;
   readonly sleep: (milliseconds: number) => Promise<void>;
   readonly version: string;
+  readonly renderGalleryScene?: CliDependencies["renderGalleryScene"];
 }
 
 function contextWithHostResourceLease(
@@ -541,7 +624,6 @@ function applicationContext(
   context: CommandContext,
   providerOptions?: GatewayProviderOptions,
 ): ApplicationContext {
-  const recordingController = context.recordingController;
   const toApplicationCapability = (capability: Capability) => ({
     available: capability.available,
     ...(capability.command === undefined ? {} : { command: capability.command }),
@@ -572,22 +654,14 @@ function applicationContext(
       : { hostResourceLease: context.hostResourceLease }),
     machineStateRoot: context.stateRoot,
     paths: context.paths,
-    ...(recordingController === undefined
-      ? {}
-      : {
-          recordingController: {
-            execute: async (
-              action: "pause" | "resume" | "start" | "stop",
-              options?: unknown,
-            ) => await executeRecordingAction(
-              recordingController,
-              action,
-              options as RecordingStartOptions | undefined,
-            ),
-            status: async () => await recordingController.status(),
-          },
-        }),
     runner: context.runner,
+    // The review provider is inert until scene.review reaches its consent gate;
+    // the credential loader runs only inside the single paid dispatch.
+    spatialReviewProvider: context.spatialReviewProviderFactory({
+      credential: () => loadGatewayCredential(context.io.env),
+      fetch: context.fetch,
+      transport: context.gatewayCatalogTransport,
+    }),
   };
   return {
     ...application,
@@ -692,6 +766,16 @@ function writeValue(io: CliIo, json: boolean, value: unknown, human: () => strin
   else writeLine(io, human());
 }
 
+function writeCapabilityManifest(io: CliIo, json: boolean, toolVersion: string): void {
+  const manifest = createLocalSlopcameraCapabilityManifest(
+    createApplicationOperationRegistry({ toolVersion }),
+    toolVersion,
+  );
+  writeValue(io, json, manifest, () => manifest.modules.map(module => (
+    `${module.moduleId}@${module.version}\t${module.trust}\toperations=${module.operations.length} workflows=${module.workflows.length} tools=${module.tools.length}\t${module.title}`
+  )).join("\n"));
+}
+
 function isWithin(root: string, candidate: string): boolean {
   const pathRelative = relative(root, candidate);
   return pathRelative === "" || (!pathRelative.startsWith("..") && !isAbsolute(pathRelative));
@@ -1715,11 +1799,6 @@ async function handleRender(
   writeValue(context.io, command.json, completed, () => `rendered ${output.outputPath}; plan=${artifactPath}`);
 }
 
-function snapshotHuman(snapshot: RecordingSnapshot): string {
-  if (snapshot.state === "idle") return "idle";
-  return `${snapshot.state} ${snapshot.recordingId ?? "unknown"} ${humanTime(snapshot.logicalTimeUs)} segments=${snapshot.completedSegmentCount}`;
-}
-
 async function handleProjectEdit(
   context: CommandContext,
   command: Extract<CliCommand, { readonly kind: "project-edit" }>,
@@ -2436,6 +2515,227 @@ async function handleProjectRender(
   writeValue(context.io, command.json, completed, () => `rendered ${outputRelative}; plan=${planArtifactPath}`);
 }
 
+async function handleProjectCinema(
+  context: CommandContext,
+  command: Extract<CliCommand, { readonly kind: "project-cinema" }>,
+): Promise<void> {
+  const project = await openProject(context.paths.projectRoot, command.project);
+  const edit = await loadCurrentProjectPlan(project);
+  const timestamp = context.io.now().toISOString();
+
+  if (command.action === "init") {
+    const existing = await loadProjectCinemaPlan(project.fileSystem);
+    if (existing !== null && !command.force) {
+      throw new CliError(
+        "conflict",
+        "Project already has a cinema sidecar. Pass --force to replace it.",
+      );
+    }
+    let plan;
+    try {
+      plan = createCinemaPlanScaffold(
+        project.project,
+        edit,
+        CinemaPlanIdSchema.parse(`cinema_${randomUUID().replaceAll("-", "").slice(0, 16)}`),
+        timestamp,
+      );
+    } catch (error) {
+      if (error instanceof TypeError) throw new CliError("conflict", error.message);
+      throw error;
+    }
+    const contents = `${canonicalJson(plan)}\n`;
+    await saveProjectCinemaPlan(project.fileSystem, plan);
+    const revisionPath = await saveProjectCinemaRevision(
+      project.fileSystem,
+      contents,
+      sha256Hex(contents),
+    );
+    writeValue(context.io, command.json, {
+      cinemaPlanSha256: plan.cinemaPlanSha256,
+      plan,
+      planPath: "cinema/current.json",
+      revisionPath,
+      shots: plan.shots.length,
+    }, () => `cinema sidecar ${plan.cinemaPlanSha256} with ${plan.shots.length} shots; revision=${revisionPath}`);
+    return;
+  }
+
+  const cinema = await loadProjectCinemaPlan(project.fileSystem);
+  if (cinema === null) {
+    throw new CliError(
+      "not-found",
+      "Project has no cinema sidecar. Run slopcamera project cinema init first.",
+    );
+  }
+  try {
+    assertCinemaPlanComposition(cinema);
+  } catch (error) {
+    if (error instanceof TypeError) throw new CliError("conflict", error.message);
+    throw error;
+  }
+
+  if (command.action === "check") {
+    const analysis = analyzeCinemaPlan(cinema, project.project, edit);
+    const audit = auditCinemaContinuity(cinema);
+    const findings = [...analysis.findings, ...audit.findings].sort((left, right) => (
+      left.timeUs - right.timeUs
+      || left.code.localeCompare(right.code)
+      || left.shotIds.join("").localeCompare(right.shotIds.join(""))
+    ));
+    const report = CinemaContinuityReportSchema.parse({
+      cinemaPlanSha256: cinema.cinemaPlanSha256,
+      findings,
+      kind: "slopcamera.cinema-continuity-report",
+      schemaVersion: 1,
+    });
+    const contents = `${canonicalJson(report)}\n`;
+    const auditPath = `cinema/audits/${sha256Hex(contents)}.json`;
+    await saveImmutableText(project.fileSystem, auditPath, contents, sha256Hex(contents));
+    const errors = findings.filter(finding => finding.severity === "error").length;
+    writeValue(context.io, command.json, {
+      auditPath,
+      findings,
+      ok: errors === 0,
+      stale: findings.some(finding => finding.code === "stale-sidecar"),
+    }, () => `${findings.length} findings (${errors} errors); audit=${auditPath}`);
+    if (errors > 0) {
+      throw new CliError(
+        "conflict",
+        `Cinema sidecar has ${errors} blocking findings; see ${auditPath}.`,
+      );
+    }
+    return;
+  }
+
+  if (command.action === "audit") {
+    const report = auditCinemaTemporal(cinema, project.project, edit);
+    const contents = `${canonicalJson(report)}\n`;
+    const auditPath = `cinema/audits/${sha256Hex(contents)}.json`;
+    await saveImmutableText(project.fileSystem, auditPath, contents, sha256Hex(contents));
+    const warnings = report.findings.filter(finding => finding.severity !== "advisory").length;
+    writeValue(context.io, command.json, {
+      auditPath,
+      findings: report.findings,
+      metrics: report.metrics,
+    }, () => `${report.findings.length} temporal findings (${warnings} warnings); audit=${auditPath}`);
+    return;
+  }
+
+  if (command.action === "gallery") {
+    const gallery = planCinemaGallery(cinema, command.axis);
+    const contents = `${canonicalJson(gallery)}\n`;
+    const galleryAbsolute = await resolveSafePath(project.directory.path, command.output ?? `cinema/galleries/${sha256Hex(contents)}.json`);
+    const galleryRelative = relative(project.directory.path, galleryAbsolute);
+    if (!galleryRelative.startsWith("cinema/") || isAbsolute(galleryRelative)) {
+      throw new CliError("unsafe-path", "Cinema gallery output must remain under the project's cinema/ directory.");
+    }
+    await saveImmutableText(project.fileSystem, galleryRelative, contents, sha256Hex(contents));
+    writeValue(context.io, command.json, {
+      axis: gallery.axis,
+      candidates: gallery.candidates.map(candidate => ({
+        candidateId: candidate.candidateId,
+        cinemaPlanSha256: candidate.cinemaPlanSha256,
+        label: candidate.label,
+      })),
+      galleryPath: galleryRelative,
+      selection: gallery.selection,
+    }, () => `${gallery.candidates.length} candidates on ${gallery.axis}; gallery=${galleryRelative}`);
+    return;
+  }
+
+  const placeholders = command.action === "animatic" || command.allowPlaceholders
+    ? "allow" as const
+    : "reject" as const;
+  let renderPlan;
+  try {
+    renderPlan = compileCinemaSequence(cinema, project.project, edit, { placeholders });
+  } catch (error) {
+    if (error instanceof TypeError) throw new CliError("conflict", error.message);
+    throw error;
+  }
+  const planContents = `${canonicalJson(renderPlan)}\n`;
+  const planPath = projectCinemaRenderPlanPath(renderPlan.planSha256);
+  await saveImmutableText(
+    project.fileSystem,
+    planPath,
+    planContents,
+    sha256Hex(planContents),
+  );
+  const planDocumentSha256 = sha256Hex(planContents);
+
+  if (command.action === "plan") {
+    writeValue(context.io, command.json, {
+      advisories: renderPlan.advisories,
+      plan: renderPlan,
+      planPath,
+    }, () => (
+      `cinema render plan ${renderPlan.planSha256}; shots=${renderPlan.shots.length} cues=${renderPlan.audioCues.length} advisories=${renderPlan.advisories.length}`
+    ));
+    return;
+  }
+
+  const tier = command.action === "animatic" ? "preview" as const : "final" as const;
+  const requested = command.output
+    ?? `renders/cinema/${command.action}-${renderPlan.planSha256.slice(0, 16)}.mp4`;
+  const renderLeaf = await resolveProjectRenderLeaf(project.directory.path, requested, { videoOutput: true });
+  const receiptRelative = `${renderLeaf.relative}.cinema-receipt.json`;
+  const receiptLeaf = await resolveProjectRenderLeaf(project.directory.path, receiptRelative);
+  const ffmpeg = await requireRequestedCapability(context, "ffmpeg");
+  const built = await buildCinemaFfmpegInvocation(renderPlan, {
+    dryRun: command.dryRun,
+    ffmpeg,
+    outputPath: renderLeaf.absolute,
+    projectDirectory: project.directory.path,
+    repositoryRoot: context.paths.repositoryRoot,
+    tier,
+  });
+  const output = {
+    invocation: built.invocation,
+    planPath,
+    projectId: project.project.projectId,
+    receiptPath: command.dryRun ? null : receiptRelative,
+    tier,
+  };
+  if (command.dryRun) {
+    writeValue(context.io, command.json, output, () => `dry-run ${built.argv.join(" ")}`);
+    return;
+  }
+  const placeholderShotIds = renderPlan.shots
+    .filter(shot => shot.placeholder !== undefined)
+    .map(shot => shot.shotId);
+  const outputIntegrity = await executeAtomicRender({
+    argv: built.argv,
+    companion: {
+      finalPath: receiptLeaf.absolute,
+      publish: async integrity => await project.fileSystem.writeTextAtomic(
+        receiptRelative,
+        `${canonicalJson(CinemaRenderReceiptV1Schema.parse({
+          cinemaPlanSha256: cinema.cinemaPlanSha256,
+          createdAt: context.io.now().toISOString(),
+          kind: "slopcamera.cinema-render-receipt",
+          output: { ...integrity, path: renderLeaf.relative },
+          placeholders: placeholderShotIds,
+          plan: { path: planPath, sha256: planDocumentSha256 },
+          projectId: project.project.projectId,
+          schemaVersion: 1,
+          tier,
+        }))}\n`,
+      ),
+    },
+    failureLabel: "FFmpeg cinema render failed",
+    finalOutputPath: renderLeaf.absolute,
+    maximumOutputBytes: MAXIMUM_LEGACY_PROJECT_RENDER_OUTPUT_BYTES,
+    runner: context.runner,
+  });
+  const completed = { ...output, output: outputIntegrity };
+  writeValue(
+    context.io,
+    command.json,
+    completed,
+    () => `rendered ${renderLeaf.relative}; plan=${planPath}`,
+  );
+}
+
 function projectPlacement(
   project: Awaited<ReturnType<typeof openProject>>,
   assetId: string,
@@ -4483,6 +4783,20 @@ function gatewayCliError(error: unknown): CliError {
   if (error instanceof GatewayProviderOptionsError) {
     return new CliError("usage", error.message);
   }
+  if (error instanceof SlopcameraCloudError) {
+    return new CliError(
+      error.code === "INVALID_ARGUMENT"
+        ? "usage"
+        : error.code === "OUTPUT_WRITE_FAILED"
+          ? "conflict"
+          : error.code === "AUTHENTICATION_REQUIRED"
+            ? "authorization-required"
+            : error.code === "GENERATION_INVALID_RESPONSE"
+              ? "invalid-data"
+              : "unavailable",
+      error.message,
+    );
+  }
   return asCliError(error);
 }
 
@@ -5138,6 +5452,819 @@ async function handleAiImageGenerate(
   });
 }
 
+async function dispatchGalleryCandidate(
+  context: CommandContext,
+  command: Extract<CliCommand, { readonly kind: "ai-image-gallery" }>,
+  plan: SlopcameraGalleryPlan,
+  candidate: SlopcameraGalleryCandidate,
+  timeoutMs: number,
+): Promise<SlopcameraGalleryResolvedCandidate> {
+  const tracker = await createGatewayJobTracker(context, {
+    model: command.model,
+    operation: "image.generate",
+    request: {
+      candidate: {
+        id: candidate.id,
+        index: candidate.index,
+        label: candidate.label,
+      },
+      count: 1,
+      galleryKind: plan.kind,
+      promptCharacters: candidate.prompt.length,
+      promptSha256: sha256Hex(candidate.prompt),
+      subjectSha256: sha256Hex(plan.subject),
+    },
+  });
+  const settled = (
+    partial: Omit<SlopcameraGalleryResolvedCandidate, "id" | "index" | "job" | "label" | "prompt">,
+  ): SlopcameraGalleryResolvedCandidate => ({
+    id: candidate.id,
+    index: candidate.index,
+    job: tracker.path,
+    label: candidate.label,
+    prompt: candidate.prompt,
+    ...partial,
+  });
+  try {
+    const bundle = await executeTrackedGatewayOperation(
+      context,
+      tracker,
+      async service => await service.generateImage(
+        {
+          consent: gatewayConsent(context),
+          model: command.model,
+          prompt: candidate.prompt,
+        },
+        {
+          ...(context.abortSignal === undefined
+            ? {}
+            : { signal: context.abortSignal }),
+          timeoutMs,
+        },
+      ),
+      result => result,
+    );
+    const output = bundle.outputs[0];
+    if (output === undefined) {
+      return settled({
+        error: "The Gateway image job completed without an image output.",
+        status: "failed",
+      });
+    }
+    const bytes = await readBoundedPhysicalBytes(
+      output.path,
+      CLI_GATEWAY_IMAGE_INPUT_BYTES,
+    );
+    const generated = settled({
+      bytes,
+      mediaType: output.mediaType,
+      path: output.path,
+      ...(bundle.receipt.routing.generationId === undefined
+        ? {}
+        : { requestId: bundle.receipt.routing.generationId }),
+      sha256: output.sha256,
+      status: "generated",
+      ...(bundle.receipt.warnings.length === 0
+        ? {}
+        : { warnings: bundle.receipt.warnings }),
+    });
+    if (command.preview === "probe") {
+      return await attachGalleryProbePreview(context, plan, generated);
+    }
+    return generated;
+  } catch (error) {
+    // A settled paid job stays a gallery row: the receipt keeps the failure
+    // and the durable job path so review never depends on provider success.
+    return settled({
+      error: gatewayCliError(error).message,
+      status: "failed",
+    });
+  }
+}
+
+const GALLERY_PROBE_MIME_TYPES = new Set(["image/png", "image/jpeg", "image/svg+xml"]);
+
+/**
+ * Renders one settled candidate inside the fixed probe scene and returns the
+ * candidate row with a distinct `cellImage` render artifact. A render failure
+ * keeps the flat candidate cell and records the failure as a warning — the
+ * paid candidate bytes stay reviewable and promotable.
+ */
+async function attachGalleryProbePreview(
+  context: CommandContext,
+  plan: SlopcameraGalleryPlan,
+  resolved: SlopcameraGalleryResolvedCandidate,
+): Promise<SlopcameraGalleryResolvedCandidate> {
+  const probeFailed = (message: string): SlopcameraGalleryResolvedCandidate => ({
+    ...resolved,
+    warnings: [...(resolved.warnings ?? []), `Probe preview failed: ${message}`],
+  });
+  try {
+    if (
+      resolved.bytes === undefined
+      || resolved.mediaType === undefined
+      || resolved.path === undefined
+      || resolved.sha256 === undefined
+    ) {
+      return probeFailed("the candidate artifact lacks published bytes.");
+    }
+    if (!GALLERY_PROBE_MIME_TYPES.has(resolved.mediaType)) {
+      return probeFailed(`candidate media type ${resolved.mediaType} cannot be a scene asset.`);
+    }
+    const [repositoryRoot, candidatePath] = await Promise.all([
+      realpath(context.paths.repositoryRoot),
+      realpath(resolved.path),
+    ]);
+    if (!isWithin(repositoryRoot, candidatePath)) {
+      return probeFailed("the candidate artifact escapes the repository root.");
+    }
+    if (
+      createHash("sha256").update(resolved.bytes).digest("hex")
+      !== resolved.sha256
+    ) {
+      return probeFailed("the candidate bytes do not match their published artifact digest.");
+    }
+    const metadata = await sharp(resolved.bytes, {
+      failOn: "warning",
+      limitInputPixels: slopcameraGalleryLimits.candidatePixels,
+    }).metadata();
+    if (metadata.width === undefined || metadata.height === undefined) {
+      return probeFailed("the candidate image did not expose its dimensions.");
+    }
+    const mode = plan.kind as SlopcameraGalleryProbeMode;
+    const scene = galleryProbeScene(mode, {
+      assetId: "asset_candidate",
+      dependencies: [],
+      interpretation: {
+        alpha: metadata.hasAlpha === true ? "straight" : "opaque",
+        colorSpace: "srgb",
+        height: metadata.height,
+        kind: "image",
+        mimeType: resolved.mediaType as "image/png" | "image/jpeg" | "image/svg+xml",
+        width: metadata.width,
+      },
+      payload: {
+        bytes: resolved.bytes.byteLength,
+        path: basename(candidatePath),
+        sha256: resolved.sha256,
+      },
+      provenance: {
+        description: `Gallery candidate ${resolved.id} probe preview.`,
+        source: "generated",
+      },
+    });
+    const scenePath = join(dirname(candidatePath), "probe-scene.json");
+    const handle = await open(
+      scenePath,
+      constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY | constants.O_NOFOLLOW,
+      0o600,
+    );
+    try {
+      await handle.writeFile(`${canonicalJson(scene)}\n`);
+    } finally {
+      await handle.close();
+    }
+    const source = { path: relative(repositoryRoot, scenePath) };
+    // The render phase admits its own local/browser vector per settled
+    // candidate; paid provider waits never hold render capacity.
+    const renderClaims = physicalHostResourceClaims(
+      [
+        { amount: 1, resource: "cpu" },
+        { amount: 1, resource: "local-io" },
+        { amount: 1, resource: "browser" },
+        { amount: 1, resource: "output-publication" },
+      ],
+      context.hostResourceCoordinator,
+    );
+    const rendered = await withHostResourceClaims(
+      context,
+      missingHostResourceClaims(
+        context.hostResourceLease?.claims ?? [],
+        renderClaims,
+      ),
+      async admitted => {
+        const input = {
+          request: galleryProbeRenderRequest(),
+          sceneSha256: spatialSceneSha256(scene),
+          source,
+        };
+        if (context.renderGalleryScene !== undefined) {
+          return await context.renderGalleryScene({
+            ...input,
+            application: applicationContext(admitted),
+          });
+        }
+        const registry = createApplicationOperationRegistry({
+          toolVersion: context.version,
+        });
+        const result = await registry.execute(
+          {
+            abortSignal: context.abortSignal ?? new AbortController().signal,
+            application: applicationContext(admitted),
+          },
+          {
+            input,
+            kind: "scene.render",
+            version: 1,
+          },
+        );
+        const output = result.output as {
+          readonly artifact: {
+            readonly bytes: number;
+            readonly path: string;
+            readonly sha256: string;
+          };
+        };
+        return { artifact: output.artifact };
+      },
+      context.abortSignal,
+    );
+    const stillPath = resolve(context.paths.repositoryRoot, rendered.artifact.path);
+    if (!isWithin(context.paths.repositoryRoot, stillPath)) {
+      return probeFailed("the rendered still escapes the repository root.");
+    }
+    const stillBytes = await readBoundedPhysicalBytes(
+      stillPath,
+      CLI_GATEWAY_IMAGE_INPUT_BYTES,
+    );
+    if (
+      stillBytes.byteLength !== rendered.artifact.bytes
+      || createHash("sha256").update(stillBytes).digest("hex") !== rendered.artifact.sha256
+    ) {
+      return probeFailed("the rendered still does not match its published artifact digest.");
+    }
+    return {
+      ...resolved,
+      cellImage: {
+        bytes: stillBytes,
+        mediaType: "image/png",
+        path: stillPath,
+        sha256: rendered.artifact.sha256,
+      },
+    };
+  } catch (error) {
+    return probeFailed(error instanceof Error ? error.message : String(error));
+  }
+}
+
+/**
+ * Renders one derived variant scene into a beauty still through the qualified
+ * `scene.render` operation (or the test seam) and returns the resolved gallery
+ * candidate. A render or write failure stays in the sheet as a failed row
+ * carrying the variant's patch provenance.
+ */
+async function dispatchSceneVariant(
+  context: CommandContext,
+  baseScene: SpatialSceneV1,
+  variant: SlopcameraSceneGalleryVariant,
+  request: {
+    readonly cameraId: string;
+    readonly mode: { readonly kind: "beauty" };
+    readonly selection: { readonly kind: "frame"; readonly timeUs: number };
+  },
+  derivedPath: string,
+  bases: {
+    readonly repositoryRoot: string;
+    readonly scene: string;
+    readonly variants: string;
+  },
+): Promise<SlopcameraGalleryResolvedCandidate> {
+  const base = {
+    id: variant.id,
+    index: variant.index,
+    label: variant.label,
+    prompt: variant.prompt,
+    scene: {
+      diff: variant.diff,
+      patchSha256: variant.patchSha256,
+      sceneSha256: variant.sceneSha256,
+    },
+  };
+  let derivedArtifact: {
+    readonly bytes: Uint8Array;
+    readonly mediaType: "application/json";
+    readonly path: string;
+    readonly sha256: string;
+  } | undefined;
+  let renderReceiptPath: string | undefined;
+  try {
+    const variantDirectory = dirname(derivedPath);
+    await mkdir(variantDirectory, { mode: 0o700, recursive: true });
+    // Stage every declared payload beneath the variant directory so the
+    // derived manifest's contained relative paths resolve for this render
+    // and for a standalone re-render after promotion. Inherited payloads
+    // resolve beside the authored scene; variant-authored payloads resolve
+    // beside the variants file.
+    const baseAssets = new Map(
+      baseScene.assets.map(asset => [asset.assetId, asset]),
+    );
+    const staged = new Map<string, string>();
+    const assets: {
+      readonly assetId: string;
+      readonly artifact: {
+        readonly bytes: number;
+        readonly path: string;
+        readonly sha256: string;
+      };
+    }[] = [];
+    for (const asset of variant.scene.assets) {
+      const inherited = baseAssets.get(asset.assetId);
+      const unchanged = inherited !== undefined
+        && inherited.payload.sha256 === asset.payload.sha256
+        && inherited.payload.bytes === asset.payload.bytes
+        && inherited.payload.path === asset.payload.path;
+      const sourcePath = resolve(
+        unchanged ? bases.scene : bases.variants,
+        asset.payload.path,
+      );
+      const target = join(variantDirectory, asset.payload.path);
+      const binding = [
+        sourcePath,
+        String(asset.payload.bytes),
+        asset.payload.sha256,
+      ].join("\u0000");
+      const assetBinding = {
+        assetId: asset.assetId,
+        artifact: {
+          bytes: asset.payload.bytes,
+          path: relative(context.paths.repositoryRoot, target),
+          sha256: asset.payload.sha256,
+        },
+      };
+      const previous = staged.get(target);
+      if (previous !== undefined) {
+        if (previous !== binding) {
+          throw new CliError(
+            "conflict",
+            `Variant ${variant.id} binds two payloads at ${asset.payload.path}.`,
+          );
+        }
+        assets.push(assetBinding);
+        continue;
+      }
+      const physicalSourcePath = await realpath(sourcePath);
+      if (
+        physicalSourcePath !== sourcePath
+        || !isWithin(bases.repositoryRoot, physicalSourcePath)
+      ) {
+        throw new CliError(
+          "unsafe-path",
+          `Asset payload ${asset.payload.path} must be a physical file inside the repository.`,
+        );
+      }
+      const payload = await readBoundedPhysicalBytes(
+        sourcePath,
+        asset.payload.bytes,
+      );
+      if (
+        payload.byteLength !== asset.payload.bytes
+        || createHash("sha256").update(payload).digest("hex")
+          !== asset.payload.sha256
+      ) {
+        throw new CliError(
+          "invalid-data",
+          `Asset ${asset.assetId} payload does not match its manifest.`,
+        );
+      }
+      await mkdir(dirname(target), { mode: 0o700, recursive: true });
+      const handle = await open(
+        target,
+        constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY
+          | (constants.O_NOFOLLOW ?? 0),
+        0o600,
+      );
+      try {
+        await handle.writeFile(payload);
+        await handle.sync();
+      } finally {
+        await handle.close();
+      }
+      staged.set(target, binding);
+      assets.push(assetBinding);
+    }
+    // The derived scene is a new no-replace document beside the sheet; the
+    // authored source scene is never touched.
+    await publishSpatialSource(derivedPath, variant.scene);
+    const sceneBytes = await readBoundedPhysicalBytes(
+      derivedPath,
+      SPATIAL_SCENE_LIMITS.sourceBytes,
+    );
+    derivedArtifact = {
+      bytes: sceneBytes,
+      mediaType: "application/json",
+      path: derivedPath,
+      sha256: createHash("sha256").update(sceneBytes).digest("hex"),
+    };
+    const source = {
+      path: relative(context.paths.repositoryRoot, derivedPath),
+    };
+    const rendered = context.renderGalleryScene === undefined
+      ? await (async () => {
+        const registry = createApplicationOperationRegistry({
+          toolVersion: context.version,
+        });
+        const result = await registry.execute(
+          {
+            abortSignal: context.abortSignal ?? new AbortController().signal,
+            application: applicationContext(context),
+          },
+          {
+            input: {
+              assets,
+              request,
+              sceneSha256: variant.sceneSha256,
+              source,
+            },
+            kind: "scene.render",
+            version: 1,
+          },
+        );
+        return result.output as {
+          readonly artifact: {
+            readonly bytes: number;
+            readonly path: string;
+            readonly sha256: string;
+          };
+          readonly receipt: { readonly path: string };
+        };
+      })()
+      : await context.renderGalleryScene({
+        application: applicationContext(context),
+        assets,
+        request,
+        sceneSha256: variant.sceneSha256,
+        source,
+      });
+    if (rendered.receipt !== undefined) {
+      const receiptPath = resolve(
+        context.paths.repositoryRoot,
+        rendered.receipt.path,
+      );
+      if (!isWithin(context.paths.repositoryRoot, receiptPath)) {
+        throw new CliError(
+          "unsafe-path",
+          "A render receipt escapes the repository root.",
+        );
+      }
+      renderReceiptPath = receiptPath;
+    }
+    const stillPath = resolve(
+      context.paths.repositoryRoot,
+      rendered.artifact.path,
+    );
+    if (!isWithin(context.paths.repositoryRoot, stillPath)) {
+      throw new CliError(
+        "unsafe-path",
+        "A rendered variant still escapes the repository root.",
+      );
+    }
+    const stillBytes = await readBoundedPhysicalBytes(
+      stillPath,
+      CLI_GATEWAY_IMAGE_INPUT_BYTES,
+    );
+    if (
+      stillBytes.byteLength !== rendered.artifact.bytes
+      || createHash("sha256").update(stillBytes).digest("hex")
+        !== rendered.artifact.sha256
+    ) {
+      throw new CliError(
+        "conflict",
+        "A rendered variant still does not match its published artifact digest.",
+      );
+    }
+    return {
+      ...base,
+      ...derivedArtifact,
+      cellImage: {
+        bytes: stillBytes,
+        mediaType: "image/png",
+        path: stillPath,
+        sha256: rendered.artifact.sha256,
+      },
+      ...(renderReceiptPath === undefined ? {} : { job: renderReceiptPath }),
+      status: "generated",
+    };
+  } catch (error) {
+    return {
+      ...base,
+      ...derivedArtifact,
+      ...(renderReceiptPath === undefined ? {} : { job: renderReceiptPath }),
+      error: error instanceof Error ? error.message : String(error),
+      status: "failed",
+    };
+  }
+}
+
+async function handleAiSceneGallery(
+  context: CommandContext,
+  command: Extract<CliCommand, { readonly kind: "ai-scene-gallery" }>,
+): Promise<void> {
+  const scenePath = resolve(context.paths.repositoryRoot, command.scene);
+  const variantsPath = resolve(context.paths.repositoryRoot, command.variants);
+  const [repositoryRoot, physicalScenePath, physicalVariantsPath] = await Promise.all([
+    realpath(context.paths.repositoryRoot),
+    realpath(scenePath),
+    realpath(variantsPath),
+  ]);
+  if (
+    physicalScenePath !== resolve(
+      repositoryRoot,
+      relative(context.paths.repositoryRoot, scenePath),
+    )
+    || physicalVariantsPath !== resolve(
+      repositoryRoot,
+      relative(context.paths.repositoryRoot, variantsPath),
+    )
+    || !isWithin(repositoryRoot, physicalScenePath)
+    || !isWithin(repositoryRoot, physicalVariantsPath)
+  ) {
+    throw new CliError(
+      "unsafe-path",
+      "Scene gallery inputs must be physical files inside the repository.",
+    );
+  }
+  const scene = parseSpatialScene(await readSpatialJson(scenePath));
+  const variantsValue = await readSpatialJson(
+    variantsPath,
+    slopcameraSceneGalleryLimits.variantsBytes,
+  );
+  // Every variant patch is validated and applied before the first render.
+  const gallery = planSlopcameraSceneGallery({
+    scene,
+    variants: variantsValue,
+  });
+  const cameraId = command.camera ?? gallery.scene.cameras[0]?.cameraId;
+  if (cameraId === undefined) {
+    throw new CliError(
+      "invalid-data",
+      "The scene declares no camera to render from.",
+    );
+  }
+  if (
+    !gallery.scene.cameras.some(camera => camera.cameraId === cameraId)
+  ) {
+    throw new CliError(
+      "invalid-data",
+      `--camera ${cameraId} is not a scene camera.`,
+    );
+  }
+  const timeUs = command.timeUs ?? 0;
+  const outputDir = await resolveSafePath(
+    context.paths.repositoryRoot,
+    command.outputDir,
+  );
+  await mkdir(outputDir, { mode: 0o700, recursive: true });
+  for (const name of ["gallery.png", "receipt.json", "variants"] as const) {
+    const existing = await lstat(join(outputDir, name)).then(
+      () => true,
+      () => false,
+    );
+    if (existing) {
+      throw new CliError(
+        "conflict",
+        `Gallery outputs are never replaced; ${name} already exists in ${command.outputDir}.`,
+      );
+    }
+  }
+  const renderRequest = {
+    cameraId,
+    mode: { kind: "beauty" as const },
+    selection: { kind: "frame" as const, timeUs },
+  };
+  const bases = {
+    repositoryRoot,
+    scene: dirname(physicalScenePath),
+    variants: dirname(physicalVariantsPath),
+  };
+  const resolved = await mapBounded(
+    gallery.variants,
+    slopcameraGalleryLimits.concurrency,
+    async variant =>
+      await dispatchSceneVariant(
+        context,
+        gallery.scene,
+        variant,
+        renderRequest,
+        join(outputDir, "variants", variant.id, "scene.json"),
+        bases,
+      ),
+  );
+  const plan: SlopcameraGalleryPlan = {
+    aspect: [16, 9],
+    axes: [],
+    candidates: gallery.variants.map(variant => ({
+      id: variant.id,
+      index: variant.index,
+      label: variant.label,
+      prompt: variant.prompt,
+    })),
+    kind: "image",
+    subject: gallery.scene.sceneId,
+    tiled: false,
+  };
+  const receipt = await composeSlopcameraImageGallery({
+    candidates: resolved,
+    ...(command.cell === undefined ? {} : { cellEdge: command.cell }),
+    model: "local/scene-render",
+    outputDir,
+    plan,
+    receipt: {
+      baseSceneSha256: gallery.baseSceneSha256,
+      kind: "slopcamera.scene-gallery",
+    },
+  });
+  const summary = {
+    baseSceneSha256: gallery.baseSceneSha256,
+    gallery: displayPath(context.paths.repositoryRoot, receipt.gallery.path),
+    kind: receipt.kind,
+    receipt: displayPath(context.paths.repositoryRoot, receipt.receiptPath),
+    variants: receipt.candidates.map(candidate => ({
+      id: candidate.id,
+      index: candidate.index,
+      ...(candidate.cellImage === undefined
+        ? {}
+        : {
+          cellImage: {
+            ...(candidate.cellImage.path === undefined
+              ? {}
+              : {
+                path: displayPath(
+                  context.paths.repositoryRoot,
+                  candidate.cellImage.path,
+                ),
+              }),
+            sha256: candidate.cellImage.sha256,
+          },
+        }),
+      ...(candidate.job === undefined
+        ? {}
+        : { job: displayPath(context.paths.repositoryRoot, candidate.job) }),
+      ...(candidate.path === undefined
+        ? {}
+        : { path: displayPath(context.paths.repositoryRoot, candidate.path) }),
+      ...(candidate.scene === undefined ? {} : { scene: candidate.scene }),
+      status: candidate.status,
+    })),
+  };
+  writeValue(
+    context.io,
+    command.json,
+    summary,
+    () =>
+      [
+        `scene.gallery ${receipt.counts.generated}/${receipt.counts.requested} variants rendered`,
+        ...receipt.candidates.map(candidate => (
+          `#${String(candidate.index)} ${candidate.id}\t${candidate.status}`
+          + (candidate.cellImage?.path === undefined
+            ? ""
+            : `\tstill ${displayPath(context.paths.repositoryRoot, candidate.cellImage.path)}`)
+        )),
+      ].join("\n"),
+  );
+}
+
+async function handleAiImageGallery(
+  context: CommandContext,
+  command: Extract<CliCommand, { readonly kind: "ai-image-gallery" }>,
+): Promise<void> {
+  await withGatewayErrors(async () => {
+    const timeoutMs = gatewayTimeoutMs(command.timeout);
+    const vary = command.vary === undefined
+      ? undefined
+      : parseSlopcameraGalleryVary(command.vary);
+    let explicitCandidates: readonly unknown[] | undefined;
+    if (command.candidatesFile !== undefined) {
+      const text = await readGatewayTextFile(
+        context.io.cwd(),
+        command.candidatesFile,
+        64 * 1024,
+      );
+      let parsedCandidates: unknown;
+      try {
+        parsedCandidates = JSON.parse(text) as unknown;
+      } catch {
+        throw new CliError(
+          "usage",
+          "--candidates must be valid JSON.",
+        );
+      }
+      if (!Array.isArray(parsedCandidates)) {
+        throw new CliError(
+          "usage",
+          "--candidates must be a JSON array of {id, prompt|variant} entries.",
+        );
+      }
+      explicitCandidates = parsedCandidates;
+    }
+    const plan = planSlopcameraGallery({
+      ...(explicitCandidates === undefined
+        ? {}
+        : { candidates: explicitCandidates }),
+      ...(command.count === undefined ? {} : { count: command.count }),
+      ...(command.galleryKind === undefined
+        ? {}
+        : { kind: command.galleryKind as SlopcameraGalleryKind }),
+      subject: command.subject,
+      ...(command.tiled === undefined ? {} : { tiled: command.tiled }),
+      ...(vary === undefined ? {} : { vary }),
+    });
+    const outputDir = resolve(context.io.cwd(), command.outputDir);
+    await mkdir(outputDir, { recursive: true });
+    for (const name of ["gallery.png", "receipt.json"] as const) {
+      const existing = await lstat(join(outputDir, name)).then(
+        () => true,
+        () => false,
+      );
+      if (existing) {
+        throw new CliError(
+          "conflict",
+          `Gallery outputs are never replaced; ${name} already exists in ${command.outputDir}.`,
+        );
+      }
+    }
+    const resolved = await mapBounded(
+      plan.candidates,
+      slopcameraGalleryLimits.concurrency,
+      async candidate => await dispatchGalleryCandidate(
+        context,
+        command,
+        plan,
+        candidate,
+        timeoutMs,
+      ),
+    );
+    const receipt = await composeSlopcameraImageGallery({
+      candidates: resolved,
+      ...(command.cell === undefined ? {} : { cellEdge: command.cell }),
+      model: command.model,
+      outputDir,
+      plan,
+    });
+    const summary = {
+      candidates: receipt.candidates.map(candidate => ({
+        id: candidate.id,
+        index: candidate.index,
+        ...(candidate.job === undefined
+          ? {}
+          : { job: displayPath(context.paths.repositoryRoot, candidate.job) }),
+        ...(candidate.path === undefined
+          ? {}
+          : { path: displayPath(context.paths.repositoryRoot, candidate.path) }),
+        ...(candidate.sha256 === undefined ? {} : { sha256: candidate.sha256 }),
+        status: candidate.status,
+        ...(candidate.tiled === undefined ? {} : { tiled: candidate.tiled }),
+        ...(candidate.cellImage === undefined
+          ? {}
+          : {
+            cellImage: {
+              ...(candidate.cellImage.path === undefined
+                ? {}
+                : {
+                  path: displayPath(
+                    context.paths.repositoryRoot,
+                    candidate.cellImage.path,
+                  ),
+                }),
+              sha256: candidate.cellImage.sha256,
+            },
+          }),
+        ...(candidate.error === undefined ? {} : { error: candidate.error }),
+      })),
+      counts: receipt.counts,
+      gallery: {
+        bytes: receipt.gallery.bytes,
+        height: receipt.gallery.height,
+        path: displayPath(context.paths.repositoryRoot, receipt.gallery.path),
+        sha256: receipt.gallery.sha256,
+        width: receipt.gallery.width,
+      },
+      kind: receipt.galleryKind,
+      model: receipt.model,
+      receiptPath: displayPath(
+        context.paths.repositoryRoot,
+        receipt.receiptPath,
+      ),
+      subject: receipt.subject,
+    };
+    writeValue(
+      context.io,
+      command.json,
+      summary,
+      () => [
+        `image.gallery ${receipt.counts.generated}/${receipt.counts.requested} candidates generated (${receipt.model})`,
+        ...receipt.candidates.map(candidate => (
+          `#${String(candidate.index)} ${candidate.id}\t${candidate.status}`
+          + (candidate.job === undefined
+            ? ""
+            : `\tjob ${displayPath(context.paths.repositoryRoot, candidate.job)}`)
+        )),
+        `gallery ${summary.gallery.path}`,
+        `receipt ${summary.receiptPath}`,
+      ].join("\n"),
+    );
+  });
+}
+
 async function handleAiVideoGenerate(
   context: CommandContext,
   command: Extract<CliCommand, { readonly kind: "ai-video-generate" }>,
@@ -5795,6 +6922,18 @@ async function dispatch(context: CommandContext, command: CliCommand): Promise<v
       writeValue(context.io, command.json, output, () => JSON.stringify(output, null, 2));
       return;
     }
+    case "spatial-asset": {
+      const output = await executeSpatialAssetCommand(applicationContext(context), command, {
+        ...(context.abortSignal === undefined ? {} : { signal: context.abortSignal }),
+      });
+      writeValue(context.io, command.json, output, () => JSON.stringify(output, null, 2));
+      return;
+    }
+    case "spatial-design": {
+      const output = await executeSpatialDesignCommand(applicationContext(context), command, context.abortSignal);
+      writeValue(context.io, command.json, output, () => JSON.stringify(output, null, 2));
+      return;
+    }
     case "spatial-scene": {
       const output = await executeSpatialSceneCommand(applicationContext(context), command, context.abortSignal);
       writeValue(context.io, command.json, output, () => JSON.stringify(output, null, 2));
@@ -5807,6 +6946,7 @@ async function dispatch(context: CommandContext, command: CliCommand): Promise<v
     }
     case "help": writeLine(context.io, commandHelp(command.topic)); return;
     case "version": writeLine(context.io, context.version); return;
+    case "capabilities": writeCapabilityManifest(context.io, command.json, context.version); return;
     case "operations-list": {
       const operations = operationDiscoveryList(
         createApplicationOperationRegistry({ toolVersion: context.version }),
@@ -6260,18 +7400,14 @@ async function dispatch(context: CommandContext, command: CliCommand): Promise<v
       for (const completion of completions(command.words)) writeLine(context.io, completion);
       return;
     case "doctor": {
-      const [capabilities, emoji, active, macVersion] = await Promise.all([
+      const [capabilities, emoji, macVersion] = await Promise.all([
         context.capabilities(),
         inspectEmojiAssets(context.paths.repositoryRoot),
-        context.recordingController === undefined
-          ? Promise.resolve(null)
-          : context.recordingController.status(),
         context.io.platform === "darwin"
           ? context.runner.run(["/usr/bin/sw_vers", "-productVersion"], { maxOutputBytes: 4_096 })
           : Promise.resolve({ exitCode: 0, stderr: "", stdout: "not-macos" }),
       ]);
       const output = {
-        activeRecording: active,
         artifactRoot: displayPath(context.paths.repositoryRoot, context.paths.artifactRoot),
         gatewayCredential: inspectGatewayCredential(context.io.env),
         emoji: {
@@ -6290,7 +7426,6 @@ async function dispatch(context: CommandContext, command: CliCommand): Promise<v
         `artifacts ${output.artifactRoot}`,
         `platform ${output.platform.name} ${output.platform.macOSVersion}`,
         ...capabilities.map((item) => `${item.name} ${item.available ? item.version ?? item.command : "unavailable"}`),
-        `recording ${active === null ? "controller-unavailable" : snapshotHuman(active)}`,
         `emoji ${emoji.provenance} ${emoji.installedCount}/${emoji.catalogCount}; generate: ${emoji.generationCommand}`,
       ].join("\n"));
       return;
@@ -6321,11 +7456,22 @@ async function dispatch(context: CommandContext, command: CliCommand): Promise<v
     case "ai-models-list": await handleAiModelsList(context, command); return;
     case "ai-models-show": await handleAiModelsShow(context, command); return;
     case "ai-image-generate": await handleAiImageGenerate(context, command); return;
+    case "ai-image-gallery": await handleAiImageGallery(context, command); return;
+    case "ai-scene-gallery": await handleAiSceneGallery(context, command); return;
     case "ai-video-generate": await handleAiVideoGenerate(context, command); return;
     case "ai-speech-generate": await handleAiSpeechGenerate(context, command); return;
     case "ai-transcribe": await handleAiTranscribe(context, command); return;
     case "media-audio": await handleMediaAudio(context, command); return;
     case "media-color": await handleMediaColor(context, command); return;
+    case "menubar": {
+      if (command.action === "run") await launchMenubar(context.io, context.paths.repositoryRoot, command.json, command.mode);
+      else await manageMenubar(context.io, context.paths.repositoryRoot, command.action, command.json);
+      return;
+    }
+    case "outputs": {
+      await reportOutputsRoot(context.io, context.stateRoot, command.json);
+      return;
+    }
     case "recordings-list": {
       const directories = (await listRecordingDirectories(context.paths.artifactRoot)).slice(0, command.limit);
       const recordings = await Promise.all(directories.map(async ({ id }) => {
@@ -6451,6 +7597,7 @@ async function dispatch(context: CommandContext, command: CliCommand): Promise<v
     case "project-metadata-edit": await handleProjectMetadataEdit(context, command); return;
     case "project-overlay-edit": await handleProjectOverlayEdit(context, command); return;
     case "project-render": await handleProjectRender(context, command); return;
+    case "project-cinema": await handleProjectCinema(context, command); return;
     case "align-analyze": await handleAlignAnalyze(context, command); return;
     case "align-apply": await handleAlignApply(context, command); return;
     case "inspect": {
@@ -6509,32 +7656,6 @@ async function dispatch(context: CommandContext, command: CliCommand): Promise<v
       ).join("\n"));
       return;
     }
-    case "record": {
-      if (context.recordingController === undefined) throw new CliError("unavailable", "Recording controller is unavailable.");
-      const options = command.action === "start"
-        ? {
-            camera: !command.webcam
-              ? { kind: "disabled" as const }
-              : command.cameraDeviceId === undefined
-              ? { kind: "default" as const }
-              : { deviceId: command.cameraDeviceId, kind: "device" as const },
-            displays: command.displays.length === 0
-              ? { kind: "all" as const }
-              : { displayIds: command.displays, kind: "selected" as const },
-            microphone: !command.microphone
-              ? { kind: "disabled" as const }
-              : command.microphoneDeviceId === undefined
-              ? { kind: "default" as const }
-              : { deviceId: command.microphoneDeviceId, kind: "device" as const },
-            strictInputs: command.strictInputs,
-            systemAudio: command.systemAudio,
-            typedText: command.typedText,
-          }
-        : undefined;
-      const snapshot = await executeRecordingAction(context.recordingController, command.action, options);
-      writeValue(context.io, command.json, snapshot, () => snapshotHuman(snapshot));
-      return;
-    }
     case "edit": await handleEdit(context, command); return;
     case "analyze-inactivity": await handleInactivity(context, command); return;
     case "analyze-faces": await handleFaceAnalysis(context, command); return;
@@ -6593,7 +7714,9 @@ function commandMutationReference(command: CliCommand): MutationReference | unde
     case "studio": return undefined; // Native jobs and the machine custody marker own explicit leases.
     case "directing": return undefined; // The directing store owns its explicit lease.
     case "spatial-world": return undefined; // Immutable world attempts and imports own their publication custody.
-    case "spatial-scene": return command.action === "init" || command.action === "patch" || command.action === "camera-track" ? { kind: "workspace-private" } : undefined;
+    case "spatial-asset": return undefined; // Content-addressed asset admission owns its publication custody.
+    case "spatial-design": return undefined; // Fresh directories and no-replace source publication own custody.
+    case "spatial-scene": return command.action === "init" || command.action === "patch" || command.action === "camera-track" || command.action === "solve" ? { kind: "workspace-private" } : undefined;
     case "spatial-project": return undefined; // Its explicit application adapter owns one version-aware lease.
     case "project-camera-edit": return command.action === "show"
       ? undefined
@@ -6603,6 +7726,7 @@ function commandMutationReference(command: CliCommand): MutationReference | unde
     case "project-metadata-edit":
     case "project-overlay-edit":
     case "project-render":
+    case "project-cinema":
     case "align-analyze":
     case "align-apply":
     case "analyze-faces":
@@ -6631,11 +7755,14 @@ function commandMutationReference(command: CliCommand): MutationReference | unde
     case "diagram-render":
     case "image-vectorize": return { kind: "workspace-private" };
     case "ai-image-generate":
+    case "ai-image-gallery":
+    case "ai-scene-gallery":
     case "ai-video-generate":
     case "ai-speech-generate":
     case "ai-transcribe": return undefined;
     case "help":
     case "version":
+    case "capabilities":
     case "operations-list":
     case "operations-show":
     case "diagram-check":
@@ -6662,11 +7789,12 @@ function commandMutationReference(command: CliCommand): MutationReference | unde
     case "fillers-list":
     case "emoji-search":
     case "emoji-resolve":
+    case "menubar":
+    case "outputs":
     case "complete": return undefined;
-    // These write outside an existing mutable bundle: fresh projects publish by
-    // atomic rename and capture has its own controller.
-    case "projects-create":
-    case "record": return undefined;
+    // Fresh projects write outside an existing mutable bundle and publish by
+    // atomic rename.
+    case "projects-create": return undefined;
   }
 }
 
@@ -6744,6 +7872,10 @@ export async function runCli(argv: readonly string[], dependencies: CliDependenc
       for (const completion of completions(command.words)) writeLine(io, completion);
       return 0;
     }
+    if (command.kind === "capabilities") {
+      writeCapabilityManifest(io, command.json, dependencies.version ?? SLOPCAMERA_VERSION);
+      return 0;
+    }
     const paths = dependencies.paths ?? await resolveRepositoryPaths(io.cwd(), io.env);
     const stateRoot = resolve(dependencies.stateRoot
       ?? defaultCliStateRoot(io.platform, io.env));
@@ -6808,12 +7940,16 @@ export async function runCli(argv: readonly string[], dependencies: CliDependenc
         ?? createDefaultHostResourceCoordinator(),
       io,
       paths,
-      recordingController: dependencies.recordingController,
       runner,
       sceneProviderFactory: dependencies.sceneProviderFactory
         ?? (options => createGatewaySceneProvider(options)),
+      spatialReviewProviderFactory: dependencies.spatialReviewProviderFactory
+        ?? (options => createGatewaySpatialReviewProvider(options)),
       sleep: dependencies.sleep ?? (async milliseconds => await Bun.sleep(milliseconds)),
       version: dependencies.version ?? SLOPCAMERA_VERSION,
+      ...(dependencies.renderGalleryScene === undefined
+        ? {}
+        : { renderGalleryScene: dependencies.renderGalleryScene }),
     };
     const mutationTarget = await resolveMutationTarget(paths, stateRoot, command);
     await withCommandHostResources(context, command, async admittedContext => {
@@ -6828,6 +7964,15 @@ export async function runCli(argv: readonly string[], dependencies: CliDependenc
         await dispatch(admittedContext, command);
       });
     });
+    if (command.kind === "projects-create" || command.kind === "project-inspect"
+      || command.kind === "project-add" || command.kind === "inspect"
+      || command.kind === "project-edit" || command.kind === "project-camera-edit"
+      || command.kind === "project-metadata-edit" || command.kind === "project-overlay-edit"
+      || command.kind === "edit"
+      || command.kind === "render-run" && !command.dryRun
+      || command.kind === "project-render" && command.action === "run" && !command.dryRun) {
+      reportUsefulResult(dependencies.onUsefulResult);
+    }
     return 0;
   } catch (error) {
     const failure = asCliError(error);