@hraness/slopcamera 3.2.8 → 3.3.2

package/apps/desktop/cli/gateway-review-provider.ts

@@ -0,0 +1,334 @@
+import { createBoundedJsonSnapshot } from "../../../src/code/json-snapshot";
+import {
+  SPATIAL_REVIEW_LIMITS,
+  SPATIAL_REVIEW_PROMPT,
+  SpatialReviewModelOutputSchema,
+  SpatialReviewProviderError,
+  redactedSpatialReviewProviderError,
+  validateSpatialReviewProviderRequest,
+  type SpatialReviewModelOutput,
+  type SpatialReviewProvider,
+  type SpatialReviewProviderResult,
+  type ValidatedSpatialReviewProviderRequest,
+} from "../../../src/spatial-scene/review";
+
+import { canonicalJson } from "../core/canonical-json";
+import type { ActiveGatewayCredential } from "./gateway-credential";
+import type { GatewayMediaCatalogTransport } from "./gateway-media-catalog";
+import {
+  createFixedSceneGatewayFetch,
+  sceneFrameDataUrl,
+  VERCEL_SCENE_GATEWAY_BASE_URL,
+  type SceneAiSdkLoader,
+  type SceneAiSdkModule,
+} from "./gateway-scene-provider";
+
+const MAXIMUM_CATALOG_BYTES = 8 * 1024 * 1024;
+const CATALOG_MODEL_LIMIT = 1_000;
+const DEFAULT_REVIEW_GATEWAY_TIMEOUT_MS = 120_000;
+const GOOGLE_GEMINI_MODEL = /^google\/gemini-[a-z0-9][a-z0-9._-]{0,239}$/u;
+
+type GatewayFetch = (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
+
+interface AiSdkResult {
+  readonly output?: unknown;
+  readonly response?: unknown;
+  readonly usage?: unknown;
+}
+
+async function loadAiSdk(): Promise<SceneAiSdkModule> {
+  const [gatewayValue, aiValue]: readonly unknown[] = await Promise.all([
+    import("@ai-sdk/gateway-v4"),
+    import("ai-v7"),
+  ]);
+  if (
+    typeof gatewayValue !== "object"
+    || gatewayValue === null
+    || !("createGateway" in gatewayValue)
+    || typeof gatewayValue.createGateway !== "function"
+    || typeof aiValue !== "object"
+    || aiValue === null
+    || !("generateText" in aiValue)
+    || typeof aiValue.generateText !== "function"
+    || !("Output" in aiValue)
+    || typeof aiValue.Output !== "object"
+    || aiValue.Output === null
+    || !("object" in aiValue.Output)
+    || typeof aiValue.Output.object !== "function"
+  ) {
+    throw new Error("The AI SDK review provider is unavailable.");
+  }
+  return {
+    Output: aiValue.Output as SceneAiSdkModule["Output"],
+    createGateway: gatewayValue.createGateway as SceneAiSdkModule["createGateway"],
+    generateText: aiValue.generateText as SceneAiSdkModule["generateText"],
+  };
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function boundedModelId(value: unknown): string | null {
+  return typeof value === "string"
+    && value.length >= 1
+    && value.length <= SPATIAL_REVIEW_LIMITS.modelIdChars
+    && value.includes("/")
+    && !/\s/u.test(value)
+    && !value.startsWith("/")
+    && !value.endsWith("/")
+    && ![...value].some(character => {
+      const code = character.codePointAt(0) ?? 0;
+      return code <= 31 || code === 127;
+    })
+    ? value
+    : null;
+}
+
+function modalityList(value: unknown): readonly string[] {
+  return Array.isArray(value)
+    ? value.filter((item): item is string => typeof item === "string")
+    : [];
+}
+
+export interface SpatialReviewModelSelection {
+  readonly catalogSha256: string;
+  readonly modelId: string;
+}
+
+/**
+ * Scans the fresh raw catalog payload for vision-capable language models:
+ * `type: "language"` rows whose input modalities include "image" and output
+ * modalities include "text". The media catalog projection drops pure language
+ * models, so review validates the untransformed document. Selection is
+ * deterministic: google/gemini-* ids first, then lexicographic order.
+ */
+export function selectSpatialReviewModel(payload: unknown): SpatialReviewModelSelection {
+  const snapshot = createBoundedJsonSnapshot(payload, MAXIMUM_CATALOG_BYTES, "Gateway model catalog", {
+    maximumDepth: 16, maximumValues: 200_000,
+  });
+  if (snapshot.sha256 === undefined) {
+    throw new SpatialReviewProviderError("gateway-unavailable");
+  }
+  const value = snapshot.value;
+  if (!isRecord(value) || !Array.isArray(value.data) || value.data.length > CATALOG_MODEL_LIMIT) {
+    throw new SpatialReviewProviderError("gateway-unavailable");
+  }
+  const candidates: string[] = [];
+  for (const row of value.data) {
+    if (!isRecord(row) || row.type !== "language") continue;
+    const modalities = isRecord(row.modalities) ? row.modalities : {};
+    const input = modalityList(modalities.input);
+    const output = modalityList(modalities.output);
+    if (!input.includes("image") || !output.includes("text")) continue;
+    const id = boundedModelId(row.id);
+    if (id === null) continue;
+    candidates.push(id);
+  }
+  if (candidates.length === 0) throw new SpatialReviewProviderError("model-unavailable");
+  candidates.sort((left, right) => left.localeCompare(right));
+  const preferred = candidates.filter(id => GOOGLE_GEMINI_MODEL.test(id));
+  return { catalogSha256: snapshot.sha256, modelId: (preferred[0] ?? candidates[0])! };
+}
+
+function userMessage(request: ValidatedSpatialReviewProviderRequest): Readonly<Record<string, unknown>> {
+  const content: Readonly<Record<string, unknown>>[] = [{
+    text: [
+      `Review ${request.frames.length} rendered beauty frame(s) for spatial scene ${request.scene.sceneId}.`,
+      `Scene sha256=${request.scene.sceneSha256}; camera ${request.scene.cameraId}; duration ${request.scene.durationUs} microseconds.`,
+      `Sampled times (microseconds): ${request.scene.timesUs.join(", ")}.`,
+      request.scene.entities.length === 0
+        ? "The scene declares no entities."
+        : `Declared entity catalog for attribution: ${canonicalJson(request.scene.entities)}.`,
+      "Attribute a finding to entityId only when it exactly matches one declared identifier.",
+    ].join(" "),
+    type: "text",
+  }];
+  for (const frame of request.frames) {
+    content.push({ text: `frameIndex ${frame.index} at ${frame.timeUs} microseconds follows.`, type: "text" });
+    content.push({
+      image: sceneFrameDataUrl("image/png", frame.bytes),
+      mediaType: "image/png",
+      type: "image",
+    });
+  }
+  return { content, role: "user" };
+}
+
+function record(value: unknown): Readonly<Record<string, unknown>> | null {
+  return isRecord(value) ? value : null;
+}
+
+function tokenCount(value: unknown, key: "inputTokens" | "outputTokens"): number {
+  const selected = record(value)?.[key];
+  return Number.isSafeInteger(selected) && (selected as number) >= 0
+    && (selected as number) <= SPATIAL_REVIEW_LIMITS.tokenCount
+    ? selected as number
+    : 0;
+}
+
+function resolvedModel(value: unknown): string | null {
+  const modelId = record(value)?.modelId;
+  return boundedModelId(modelId) ?? (typeof modelId === "string" && modelId.length >= 1 && modelId.length <= SPATIAL_REVIEW_LIMITS.modelIdChars ? modelId : null);
+}
+
+function providerResponseId(value: unknown): string | undefined {
+  const id = record(value)?.id;
+  return typeof id === "string" && id.length >= 1 && id.length <= SPATIAL_REVIEW_LIMITS.providerResponseIdChars
+    && ![...id].some(character => (character.codePointAt(0) ?? 0) <= 31)
+    ? id
+    : undefined;
+}
+
+function parseReviewProviderOutput(value: unknown): SpatialReviewModelOutput {
+  const parsed = SpatialReviewModelOutputSchema.safeParse(value);
+  if (!parsed.success) throw new SpatialReviewProviderError("invalid-response");
+  return parsed.data;
+}
+
+export interface GatewaySpatialReviewProviderOptions {
+  /** Lazy credential load: reads the environment only inside the dispatch. */
+  readonly credential: () => ActiveGatewayCredential;
+  readonly fetch?: GatewayFetch;
+  readonly loadAiSdk?: SceneAiSdkLoader;
+  readonly timeoutMs?: number;
+  /** Fresh catalog transport; the review dispatch performs one refresh. */
+  readonly transport: GatewayMediaCatalogTransport;
+}
+
+function boundedTimeout(value: number | undefined): number {
+  const timeoutMs = value ?? DEFAULT_REVIEW_GATEWAY_TIMEOUT_MS;
+  if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 300_000) {
+    throw new SpatialReviewProviderError("invalid-request");
+  }
+  return timeoutMs;
+}
+
+function disableAiSdkWarningLogging(): void {
+  (
+    globalThis as typeof globalThis & {
+      AI_SDK_LOG_WARNINGS?: false;
+    }
+  ).AI_SDK_LOG_WARNINGS = false;
+}
+
+function assertReviewDispatchActive(signal: AbortSignal): void {
+  if (signal.aborted) throw new SpatialReviewProviderError("aborted");
+}
+
+/**
+ * One consent-gated critique call against the fixed Gateway origin. The
+ * credential is loaded lazily after the fresh catalog proves a vision-capable
+ * language model; `maxRetries` is pinned to zero and an ambiguous dispatch is
+ * never resubmitted.
+ */
+export function createGatewaySpatialReviewProvider(
+  options: GatewaySpatialReviewProviderOptions,
+): SpatialReviewProvider {
+  const loader = options.loadAiSdk ?? loadAiSdk;
+  const gatewayFetch = createFixedSceneGatewayFetch(options.fetch ?? globalThis.fetch);
+  const timeoutMs = boundedTimeout(options.timeoutMs);
+  return {
+    critique: async (requestInput, signal): Promise<SpatialReviewProviderResult> => {
+      const request = validateSpatialReviewProviderRequest(requestInput);
+      let dispatched = false;
+      let timedOut = false;
+      const controller = new AbortController();
+      const abortFromCaller = (): void => controller.abort(signal?.reason);
+      signal?.addEventListener("abort", abortFromCaller, { once: true });
+      if (signal?.aborted === true) {
+        signal?.removeEventListener("abort", abortFromCaller);
+        throw new SpatialReviewProviderError("aborted");
+      }
+      const timer = setTimeout(() => {
+        timedOut = true;
+        controller.abort();
+      }, timeoutMs);
+      const interrupted = new Promise<never>((_resolve, reject) => {
+        const rejectInterrupted = (): void => reject(
+          dispatched
+            ? new SpatialReviewProviderError(
+                timedOut ? "gateway-outcome-unknown" : "aborted",
+                "ambiguous",
+              )
+            : new SpatialReviewProviderError(
+                timedOut ? "gateway-unavailable" : "aborted",
+              ),
+        );
+        controller.signal.addEventListener("abort", rejectInterrupted, { once: true });
+        if (controller.signal.aborted) rejectInterrupted();
+      });
+      try {
+        const operation = (async (): Promise<SpatialReviewProviderResult> => {
+          const refresh = await options.transport.refresh(undefined, controller.signal);
+          assertReviewDispatchActive(controller.signal);
+          if (refresh.status !== "modified") {
+            throw new SpatialReviewProviderError("gateway-unavailable");
+          }
+          const selection = selectSpatialReviewModel(refresh.payload);
+          disableAiSdkWarningLogging();
+          const ai = await loader();
+          assertReviewDispatchActive(controller.signal);
+          let credential: ActiveGatewayCredential;
+          try {
+            credential = options.credential();
+          } catch {
+            throw new SpatialReviewProviderError("credential-missing");
+          }
+          return await credential.withApiKey(async (apiKey) => {
+            assertReviewDispatchActive(controller.signal);
+            const gateway = ai.createGateway({
+              apiKey,
+              baseURL: VERCEL_SCENE_GATEWAY_BASE_URL,
+              fetch: gatewayFetch,
+            });
+            const output = ai.Output.object({
+              description: "Bounded advisory beauty-pass findings for one spatial scene review.",
+              name: "slopcamera_spatial_review",
+              schema: SpatialReviewModelOutputSchema,
+            });
+            assertReviewDispatchActive(controller.signal);
+            dispatched = true;
+            const result: AiSdkResult = await ai.generateText({
+              abortSignal: controller.signal,
+              maxOutputTokens: SPATIAL_REVIEW_LIMITS.responseTokens,
+              maxRetries: 0,
+              messages: [userMessage(request)],
+              model: gateway.languageModel(selection.modelId),
+              output,
+              providerOptions: {
+                gateway: {
+                  disallowPromptTraining: true,
+                  tags: ["slopcamera", "scene-review", "v1"],
+                  zeroDataRetention: true,
+                },
+              },
+              system: SPATIAL_REVIEW_PROMPT,
+              temperature: 0,
+            });
+            const responseId = providerResponseId(result.response);
+            return {
+              model: {
+                catalogSha256: selection.catalogSha256,
+                requestedModel: selection.modelId,
+                resolvedModel: resolvedModel(result.response),
+                ...(responseId === undefined ? {} : { providerResponseId: responseId }),
+              },
+              output: parseReviewProviderOutput(result.output),
+              usage: {
+                inputTokens: tokenCount(result.usage, "inputTokens"),
+                outputTokens: tokenCount(result.usage, "outputTokens"),
+              },
+            };
+          });
+        })();
+        return await Promise.race([operation, interrupted]);
+      } catch (error) {
+        throw redactedSpatialReviewProviderError(error, dispatched);
+      } finally {
+        clearTimeout(timer);
+        signal?.removeEventListener("abort", abortFromCaller);
+      }
+    },
+  };
+}

package/apps/desktop/cli/help.ts

@@ -8,15 +8,19 @@ const GLOBAL_HELP = `slopcamera — creative scenes and non-destructive media ed
 Usage: slopcamera <command> [options]
 
 Commands:
+  capabilities                   Discover the exact static capability modules and qualification status
   operations list|show           Discover host-owned typed operations and policies
   diagram init|check|render      Create, validate, or render portable diagram sources
-  scene init|check|inspect|patch|evaluate|camera-track|plan|render
+  scene init|check|inspect|diff|patch|evaluate|audit|render-audit|solve|review|camera-track|generate|plan|render|direction|effects|behavior|temporal-audit
                                  Author and inspect editable directed 3D scene sources
+  scene design catalog|init|inspect|set|compile|gallery
+                                 Build and revise geometry from named parameters and constraints
   direct init|plan|start|generate|review|assemble
                                  Direct short Gateway clips with retained takes and budgets
   studio init|bundle|plan|probe|run|encode|asset|assemble|inspect|reconcile
                                  Author and render retained Blender, CAD and Manim productions
-  image vectorize|generate      Create a local SVG or generated image file
+  image vectorize|generate|gallery|icon
+                                 Create local SVGs, generated images, or review galleries
   html catalog|scaffold|render   Author HTML scenes and export video with local audio
   workflows list|show|plan|run   Plan or run a reviewed reusable workflow
   code init|check|plan|run       Author, preflight, and run trusted TypeScript workflows
@@ -53,6 +57,9 @@ HRANESS_SUPPORT_AUDIENCE=off suppresses offers and incidental discovery.
 Run slopcamera help <command> for command-specific help.`;
 
 const HELP: Readonly<Record<string, string>> = {
+  capabilities: `Usage: slopcamera capabilities [--json]
+
+Print the exact statically assembled capability manifest for this CLI build. Each module owns named operation, workflow, MCP-tool, command, and runtime-profile identities. The manifest includes trust classes, resource/effect policies, runtime requirements, qualification status, and a canonical SHA-256. It reads no workspace source, loads no plugin, probes no runtime, and grants no authority. Use doctor separately to inspect this machine's currently available executables.`,
   studio: `Usage:
   slopcamera studio init <new-directory> [--template blender-product|blender-character|blender-shaded-street|blender-cloth|blender-fluid|cadquery-bracket|manim-lesson] [--json]
   slopcamera studio bundle <source.json> [--source-root <directory>] [--json]
@@ -119,27 +126,120 @@ project for slopcamera project render run. Review and assembly work without clou
 This workflow retains image and prompt continuity; it has no provider neural checkpoint
 or real-time session. Use slopcamera ai models list --type video for live model discovery.`,
   scene: `Usage:
+  slopcamera scene design catalog [--json]
+  slopcamera scene design init <directory> --template <id> [--json]
+  slopcamera scene design inspect <design.json> [--json]
+  slopcamera scene design set <design.json> --parameters <values.json> --output <new-design.json> [--json]
+  slopcamera scene design compile <design.json> [--scene <base.scene.json>] --output-dir <new-directory> [--json]
+  slopcamera scene design gallery <design.json> --variants <variants.json> [--scene <base.scene.json>] --output-dir <new-directory> [--json]
   slopcamera scene init <scene.json> [--json]
   slopcamera scene check <scene.json> [--json]
   slopcamera scene inspect <scene.json> [--json]
   slopcamera scene patch <scene.json> --patch <patch.json> --output <new-scene.json> [--json]
   slopcamera scene evaluate <scene.json> --camera <camera-id> --time-us <integer> [--json]
+  slopcamera scene audit <scene.json> --camera <camera-id> [--times-us <csv>] [--asset-bounds <bounds-or-admission.json>] [--json]
+  slopcamera scene render-audit <scene.json> --camera <camera-id> [--times-us <csv>] [--json]
+  slopcamera scene solve <scene.json> --goals <goals.json> [--output <patch.json>] [--asset-bounds <bounds-or-admission.json>] [--json]
+  slopcamera scene review <scene.json> --camera <camera-id> [--times-us <csv>] --allow-cloud-upload [--json]
   slopcamera scene camera-track <scene.json> --request <sampling.json> --output <new-track.json> [--json]
+  slopcamera scene generate --module <generator.ts> --generator-id <id>
+        [--parameters <params.json>] [--seed <n>] [--into <scene.json>] --output <new-scene.json> [--json]
   slopcamera scene plan|render <scene.json> --request <request.json> [--assets <bindings.json>] [--profile <profile>] [--json]
+  slopcamera scene direction check <direction.json> --scene <scene.json> [--json]
+  slopcamera scene direction plan <direction.json> --scene <scene.json> [--camera <camera-id>] [--output <out.json>] [--json]
+  slopcamera scene direction gallery <direction.json> --scene <scene.json> --axis <axis> [--camera <camera-id>] [--output <out.json>] [--json]
+  slopcamera scene effects check <effects.json> --scene <scene.json> [--json]
+  slopcamera scene effects plan <draft.json> --scene <scene.json> [--output <effects.json>] [--json]
+  slopcamera scene effects bake <plan.json> --scene <scene.json> --output <bake.json> [--json]
+  slopcamera scene behavior check <behavior.json> --scene <scene.json> [--json]
+  slopcamera scene behavior bake <behavior.json> --scene <scene.json> [--channel-map <map.json>] --output <bake.json> [--json]
+  slopcamera scene behavior gallery <behavior.json> --scene <scene.json> [--channel-map <map.json>] [--output <gallery.json>] [--json]
+  slopcamera scene behavior audit <bake.json> [--output <audit.json>] [--json]
+  slopcamera scene temporal-audit <scene.json> --camera <camera-id> [--times-us <csv>] [--contacts <contacts.json>] [--cut-before-us <csv>] [--json]
   slopcamera scene project snapshot <project-id> [--json]
   slopcamera scene project prepare-render <project-id> --input <request.json> --output <prepared-render.json> [--profile <profile>] [--json]
   slopcamera scene project migrate|patch|restore|add-shot|add-candidate|select-candidate|reconcile
         <project-id> --input <request.json> [--json]
   slopcamera scene world import --input <import.json> --source-root <directory>
         --output-root <directory-below-artifacts/slopcamera/generated> [--json]
+  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]
+
+Designs retain named numeric controls, derived values, dimensional constraints and
+geometry stages. Inspect resolves dependencies and checks budgets without creating
+meshes. Set applies a bounded JSON object of parameter values as a new revision.
+Compile creates a new directory containing design.json, scene.json, exact GLB/facts
+payloads, a compilation receipt and render.json when a camera is available. Pass
+the starter's base.scene.json to retain its cameras and lighting. Gallery compiles
+one to six labelled parameter variants into independent bundles; it does not render.
+Render each bundle through scene render <bundle/scene.json> --request <bundle/render.json>.
+Compilation is local and executes no authored code. Existing output paths conflict;
+interrupted bundles remain without a completion receipt. Use scene design catalog
+for the current architectural starters and docs/parametric-design.md for the contract.
 
 Hardware profiles: three-webgl2-hardware-v1 and three-spark-webgl2-hardware-v1.
 An explicit profile must agree with the request; omitting it preserves the request.
 Saved-world import works offline and preserves imported provenance receipts.
+Asset admit copies one local GLB into content-addressed storage beside --output,
+derives bounds and a mesh entity, and emits manifests plus ready-to-apply patch
+operations without overwriting existing paths.
 Scene sources retain stable entities, cameras, asset manifests and animation channels.
 Inspect reports editable controls and known bounds without decoding assets. Patch requires
 the exact expected scene digest in its patch document and writes a new source without
 overwriting either revision. Evaluate samples absolute time without launching a renderer.
+Audit samples bounded geometry against one camera over time and reports deterministic
+frustum findings; --asset-bounds supplies scene-space enclosures as a bounds map,
+admission documents, {manifest, facts} pairs, or arrays of those.
+Render-audit renders the real object-ID pass in the bound browser runtime and counts
+per-entity pixels at each sampled time, reporting splats and camera-bound view masks
+honestly as unsupported or non-attributable rather than estimating them.
+Solve turns declarative relation goals (onTopOf, nextTo, facing, align, at, groundSnap)
+into concrete transforms and a ready-to-apply patch document. Goals name scene entities;
+relations may target entities, cameras, or caller-supplied base entries, and goal targets
+see each other's solved transforms in dependency order. The emitted patch carries a
+placeholder expectedSceneSha256 — copy the digest from scene inspect before scene patch.
+Goal entities must be authored, unparented, world-placed, and free of transform
+overrides or transform channels; asset-derived bounds come from --asset-bounds.
+Review renders up to four bounded beauty frames locally, uploads only those exact
+frames to a vision-capable Gateway language model after explicit --allow-cloud-upload,
+and returns a structured advisory report. It makes exactly one Gateway call, records
+frame digests, model and attempt identity, and rubric version, and never modifies or
+auto-applies scene changes. The report is model-generated and unverified.
+Generate runs a trusted TypeScript generator at authoring time, stamps retained
+output with derived entity identity, and records source, closure, parameters, seed and
+runtime digests; it never reruns source during inspect, evaluate or render.
+Direction commands compile an authored direction document into deterministic,
+unverified proposals — performance actions, camera rigs, shots and looks bound to the
+actual scene digest. Check reports stale digests, unresolved references and intervals
+outside scene duration without compiling; plan emits the compilation (optionally to
+--output); gallery compiles a bounded set of single-axis variants as separate
+content-addressed candidates and never selects one. Direction gallery axes:
+performance, camera, lighting, materials, effects, sequence.
+Effects commands assemble and validate slopcamera.spatial-render-effects documents.
+Check verifies scene-digest bindings, entity and asset closure, and nested plan,
+particle and simulation digests before any host work; plan binds the caller's
+renderPlan, particleSystems and simulationBakes draft to the actual scene digest and
+emits a {document, documentSha256} binding; bake executes the bounded reference
+rigid-body integrator for one admitted simulation plan and publishes the canonical
+bake document. Native secondary-motion and hinge constraints remain unqualified.
+Behavior commands admit and execute slopcamera.spatial-behavior documents —
+inert ALGAL organism closures checked under the bake-safe profile (pure
+input/const/fn/repeat/each/organism cells only; effect-bearing cells reject
+before execution). Check reports manifest digests, wiring, entity and channel
+findings; bake runs the entry organism through the pinned ALGAL runtime with
+the closed pure fn catalog and publishes a canonical bake document — emitted
+semantic records, unverified performance directive proposals, and a receipt
+binding closure, scene, seed, run, and catalog digests; gallery bakes the
+document under deterministic seed variants as separate content-addressed
+candidates and never selects one. --channel-map binds emitted channels to
+clip runs and attach/release pairs; unmapped channels surface as unresolved
+intents rather than fabricated bindings.
+Temporal-audit evaluates the scene at bounded sample times under one camera and
+reports deterministic findings: visibility flicker, transform discontinuity,
+foot-slide against declared contact windows, camera acceleration/jerk/angular
+velocity, exposure and focus jumps, and per-sample resource spikes. Without
+--times-us it samples the scene duration at up to 17 evenly spaced times.
 Project operations use the exact full project ID and a versioned whole-project basis.
 Discover each request with slopcamera operations show spatial.project.<action> --json.
 Migration retains the frozen media/edit pair in V2 authority. Legacy project commands
@@ -161,11 +261,26 @@ operations separately publish equivalent derivatives by content hash for workflo
   slopcamera image generate <prompt> --output <file.webp> [--model <model>]
         [--idempotency-key <key>] [--json]
   slopcamera image generate --model <gateway-model> --prompt <prompt>
+  slopcamera image gallery <subject> --output-dir <directory> [--model <model>]
+        [--kind <image|texture|skybox|backdrop|sprite>] [--count <n>]
+        [--vary <axis[=v1,v2][;axis...]>] [--candidates <file.json>]
+        [--cell <n>] [--tile|--no-tile] [--json]
+  slopcamera image icon <subject> --output <file.svg>
+        [--purpose <mark|illustration>] [--model <model>] [--ink <#rgb>]
+        [--rounds <1-4>] [--critique-model <model>] [--keep-raster] [--json]
 
 Explicit --output file commands delegate to @hraness/slopcamera. Vectorization is local,
 bounded, checksum-pinned, and emits inert SVG. File generation uses Vercel AI Gateway with the
 caller's environment credential. The --prompt spelling without --output is an alias for the desktop
-content-addressed \`ai image generate\` lane and returns project-composable content hash references.`,
+content-addressed \`ai image generate\` lane and returns project-composable content hash references.
+Icon combines a style-locked Gateway raster, local ink extraction and VTracer tracing into a
+canonical isometric line-art SVG; --rounds above 1 adds a vision-model critique that revises the
+prompt between attempts. Gallery fans one subject out to bounded parallel candidates — driven by
+variation axes or an explicit candidate list — keeps every candidate with its provenance, and
+composes a labelled contact sheet plus receipt for agent review. Texture cells repeat the
+candidate 2×2 so seams are inspectable (--tile/--no-tile overrides). It never replaces existing
+outputs and never promotes a candidate into authored source; review the sheet and select
+explicitly.`,
   html: `Usage:
   slopcamera html catalog [--json]
   slopcamera html scaffold <${HTML_OVERLAY_SCAFFOLD_KIND_HELP}> --output <file.html>
@@ -254,6 +369,13 @@ run journal.`,
         [--max-output-tokens <n>] [--temperature <n>] [--stop <text> ...]
         [--provider-options <json-file>] [--timeout <time>]
         [--allow-cloud-upload] [--json]
+  slopcamera ai image gallery <subject> --model <id> --output-dir <directory>
+        [--kind <image|texture|skybox|backdrop|sprite>] [--count <n>]
+        [--vary <axis[=v1,v2][;axis...]>] [--candidates <json-file>]
+        [--cell <n>] [--tile|--no-tile] [--preview probe]
+        [--timeout <time>] [--json]
+  slopcamera ai scene gallery <scene.json> --variants <file.json> --output-dir <directory>
+        [--camera <camera-id>] [--time-us <integer>] [--cell <n>] [--json]
   slopcamera ai video generate --model <id> [--prompt <text> | --prompt-file <path>]
         [--image <path-or-https-url>] [--frame first=<path-or-https-url>]
         [--frame last=<path-or-https-url>]
@@ -295,6 +417,25 @@ image cannot accompany a first frame.
 provider-options inspect emits exactly the secret-free {sha256,namespaces} reference that workflow
 nodes store in their exact request; it never prints or persists the raw option values.
 
+ai image gallery runs one tracked paid job per candidate with bounded parallelism, then composes a
+labelled contact sheet and receipt into --output-dir. Each candidate keeps its durable artifact,
+prompt, digest, and job record so an agent can review the sheet once and promote a chosen candidate
+explicitly; generated bytes never replace authored source. --vary takes automatic variation axes,
+--candidates takes an explicit JSON list, and the two are mutually exclusive. Texture cells render
+as a 2×2 tile repeat so seams are visible at a glance; --no-tile keeps a flat cell and --tile opts
+other kinds in. --preview probe renders each settled candidate inside the fixed probe scene —
+textures applied to lit geometry, skyboxes as the environment, backdrops as a scene surface — so the
+sheet shows rendered stills. The receipt keeps the generated candidate path/digest and the rendered
+cellImage path/digest as separate fields; promotion always targets the candidate, never the still.
+
+ai scene gallery reads an authored scene plus a bounded variants file of typed scene patches, then
+renders each derived scene through the qualified scene renderer and composes the beauty stills into
+the same labelled contact sheet. Every variant is published as a new scene document under
+--output-dir/variants/<id>/ with its asset payloads staged alongside, so the derived scene is
+inspectable and re-renderable; the authored scene is never modified. The receipt keeps the base
+scene digest, each patch digest, each derived scene digest, and each rendered still digest so an
+agent can review once and promote a chosen variant explicitly.
+
 Reference media and transcription audio never upload implicitly. The appropriate explicit
 --allow-cloud-* acknowledgement is required after local files pass type and byte bounds. Image
 and video references may instead use a public credential-free HTTPS URL when the live catalog
@@ -461,6 +602,23 @@ Face track IDs describe local geometry continuity inside one immutable analysis.
   slopcamera project edit <project> overlay remove <id> [--json]
   slopcamera project render <plan|run> <project> [--width <px>] [--height <px>] [--fps <n>]
                        [--output <renders/path.mp4>] [--dry-run] [--allow-unverified-sync] [--json]
+  slopcamera project cinema init <project> [--force] [--json]
+  slopcamera project cinema check <project> [--json]
+  slopcamera project cinema plan <project> [--allow-placeholders] [--json]
+  slopcamera project cinema audit <project> [--json]
+  slopcamera project cinema gallery <project> --axis <audio|looks|mixed|pacing|structure|transitions>
+        [--output <cinema/path.json>] [--json]
+  slopcamera project cinema animatic <project> [--output <renders/path.mp4>] [--dry-run] [--json]
+  slopcamera project cinema run <project> [--output <renders/path.mp4>] [--allow-placeholders] [--dry-run] [--json]
+
+Cinema commands drive the content-addressed cinema sidecar (cinema/current.json), which binds exact
+project structure and edit-plan digests. Any project or edit change makes the sidecar stale until it is
+re-authorized. Animatics always allow deterministic placeholder frames for missing spatial artifacts;
+final runs require materialized media unless --allow-placeholders is explicit. Cinema never alters the
+project render plan or its identity. Audit reports layout-derived temporal evidence — pacing floors,
+transition overruns, cue concurrency and uniform pacing — with deterministic shot metrics. Gallery
+compiles a bounded set of single-axis candidate plans under cinema/galleries/, each re-validated and
+re-hashed through the canonical composition digest; it never selects a candidate.
 
 Imported media starts unverified. Align its audio before relying on synchronization. Structural edits are project-time operations and affect every placement. Camera moves address any placed video stream; metadata-driven screen zooms still require a recording-backed source placement. Face analysis and geometry tracks remain local. --select largest follows the largest currently visible prepared-layer face per frame. --require-all-selected makes a missing explicit/all-selected face invoke the chosen gap policy.`,
   render: `Usage: slopcamera render <plan|run> <recording> [--display <id|primary>] [--output <path>] [--dry-run] [--keep-inactivity] [--json]
@@ -475,7 +633,7 @@ export function commandHelp(topic: readonly string[]): string {
 
 export function completions(words: readonly string[]): readonly string[] {
   const topLevel = [
-    "operations", "diagram", "direct", "studio", "image", "html", "workflows", "code", "runs", "doctor", "ai", "media", "menubar", "support", "outputs", "recordings", "projects", "project", "inspect", "events", "edit", "analyze", "align", "faces", "fillers", "render", "assets",
+    "capabilities", "operations", "diagram", "direct", "studio", "image", "html", "workflows", "code", "runs", "doctor", "ai", "media", "menubar", "support", "outputs", "recordings", "projects", "project", "scene", "inspect", "events", "edit", "analyze", "align", "faces", "fillers", "render", "assets",
   ];
   if (words.length <= 1) return topLevel;
   const command = words[0];
@@ -485,13 +643,21 @@ export function completions(words: readonly string[]): readonly string[] {
   if (command === "studio") return words[2] === "assets" || words[1] === "assets" ? ["search", "describe", "plan", "import"] : ["init", "bundle", "plan", "probe", "run", "encode", "asset", "assemble", "inspect", "reconcile", "assets"];
   if (command === "operations") return ["list", "show"];
   if (command === "diagram") return ["check", "render"];
-  if (command === "image") return ["vectorize"];
+  if (command === "image") return ["vectorize", "generate", "gallery", "icon"];
   if (command === "workflows") return ["list", "show", "plan", "run"];
   if (command === "code") return ["init", "check", "plan", "run"];
   if (command === "runs") return ["list", "show", "resume", "approve", "cancel"];
   if (command === "recordings") return ["list"];
   if (command === "projects") return ["list", "create"];
-  if (command === "project") return ["inspect", "add", "edit", "render"];
+  if (command === "project") return words[1] === "cinema"
+    ? ["init", "check", "plan", "audit", "gallery", "animatic", "run"]
+    : ["inspect", "add", "edit", "render", "cinema"];
+  if (command === "scene") {
+    if (words[1] === "direction") return ["check", "plan", "gallery"];
+    if (words[1] === "effects") return ["check", "plan", "bake"];
+    if (words[1] === "behavior") return ["check", "bake", "gallery", "audit"];
+    return ["init", "check", "inspect", "diff", "patch", "evaluate", "audit", "render-audit", "solve", "review", "camera-track", "generate", "plan", "render", "direction", "effects", "behavior", "temporal-audit"];
+  }
   if (command === "edit") return ["init", "show", "trim", "cut", "speed", "zoom", "overlay", "cursor", "clicks", "keystrokes", "typed-text"];
   if (command === "analyze") return ["faces", "inactivity", "zooms", "music", "scenes", "speech"];
   if (command === "faces") return ["list"];

package/apps/desktop/cli/main.ts

@@ -46,7 +46,7 @@ export async function main(
   const portableExitCode = await runPortableSurface(unifiedArgv, portableDependencies);
   if (portableExitCode !== undefined) return portableExitCode;
   const earlyCommand = parseCliArgs(unifiedArgv);
-  if (earlyCommand.kind === "help" || earlyCommand.kind === "version" || earlyCommand.kind === "complete") {
+  if (earlyCommand.kind === "help" || earlyCommand.kind === "version" || earlyCommand.kind === "complete" || earlyCommand.kind === "capabilities") {
     const intro = rootHelpIntro(unifiedArgv, {
       isTTY: process.stdout.isTTY === true, term: process.env.TERM, columns: process.stdout.columns,
     });
@@ -54,8 +54,8 @@ export async function main(
     return await runCli(unifiedArgv, { io: processIo });
   }
   const paths = await resolveRepositoryPaths(processIo.cwd(), processIo.env);
-  if (earlyCommand.kind === "html-render" || earlyCommand.kind === "spatial-world" || earlyCommand.kind === "directing" || earlyCommand.kind === "studio"
-    || earlyCommand.kind === "spatial-scene" && earlyCommand.action === "camera-track") {
+  if (earlyCommand.kind === "html-render" || earlyCommand.kind === "spatial-world" || earlyCommand.kind === "spatial-asset" || earlyCommand.kind === "spatial-design" || earlyCommand.kind === "directing" || earlyCommand.kind === "studio"
+    || earlyCommand.kind === "spatial-scene" && (earlyCommand.action === "camera-track" || earlyCommand.action === "render-audit" || earlyCommand.action === "review")) {
     const controller = new AbortController();
     const cancel = () => controller.abort(new CliError("cancelled", "Command interrupted."));
     process.on("SIGINT", cancel);

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

@@ -235,7 +235,12 @@ export async function runPortableSurface(
     )
     || (
       argv[0] === "image"
-      && (argv[1] === "vectorize" || argv[1] === "generate")
+      && (
+        argv[1] === "vectorize" ||
+        argv[1] === "generate" ||
+        argv[1] === "icon" ||
+        argv[1] === "gallery"
+      )
     );
   if (!delegatesToHeadless) return undefined;