@hraness/slopcamera 3.2.5 → 3.2.7

package/README.md

@@ -33,12 +33,15 @@ project database.
 
 ## Install Slopcamera
 
+The source tree prepares v3.2.7 with a compact interactive CLI introduction.
+The install below stays on the verified v3.2.6 release until publication completes.
+
 Install [Bun 1.3.14 or newer](https://bun.sh), then install the verified
-[Slopcamera v3.2.4 release](https://github.com/hraness/slopcamera/releases/tag/v3.2.4)
+[Slopcamera v3.2.6 release](https://github.com/hraness/slopcamera/releases/tag/v3.2.6)
 from its canonical archive:
 
 ```sh
-bun add --global https://github.com/hraness/slopcamera/releases/download/v3.2.4/hraness-slopcamera-3.2.4.tgz
+bun add --global https://github.com/hraness/slopcamera/releases/download/v3.2.6/hraness-slopcamera-3.2.6.tgz
 slopcamera skill install --target agents
 ```
 

package/apps/desktop/application/operation.ts

@@ -4,7 +4,7 @@ import type { z } from "zod";
 
 import type { ApplicationContext } from "./context";
 
-export const SLOPCAMERA_APPLICATION_TOOL_VERSION = "slopcamera-3.2.5" as const;
+export const SLOPCAMERA_APPLICATION_TOOL_VERSION = "slopcamera-3.2.7" as const;
 
 export const OPERATION_KINDS = [
   "scene.inspect",

package/apps/desktop/cli/args.ts

@@ -85,6 +85,7 @@ export type SpatialProjectCommand = JsonOption & {
 );
 
 export type CliCommand =
+  | { readonly kind: "html-render"; readonly input: string; readonly dryRun: boolean; readonly json: boolean }
   | StudioCommand
   | DirectingCommand
   | SpatialWorldCommand
@@ -3150,6 +3151,13 @@ export function parseCliArgs(argv: readonly string[]): CliCommand {
   }
   const command = argv[0]!;
   switch (command) {
+    case "html": {
+      if (argv[1] !== "render") fail("Use html render --input <scene.json> [--dry-run] [--json].");
+      const parsed = parseOptions(argv.slice(2), { "--input": "value", "--dry-run": "flag", "--json": "flag" });
+      const input = optionString(parsed, "--input");
+      if (input === undefined || parsed.positionals.length !== 0) fail("Use html render --input <scene.json> [--dry-run] [--json].");
+      return { kind: "html-render", input, dryRun: optionFlag(parsed, "--dry-run"), json: optionFlag(parsed, "--json") };
+    }
     case "studio": return parseStudioArgs(argv.slice(1));
     case "direct": return parseDirectingArgs(argv.slice(1));
     case "scene": return parseSpatialSceneArgs(argv.slice(1));

package/apps/desktop/cli/command-host-resources.ts

@@ -125,6 +125,9 @@ export function commandHostResourceClaims(
   coordinator: HostResourceCoordinator,
 ): readonly HostResourceClaim[] {
   switch (command.kind) {
+    case "html-render": return command.dryRun
+      ? claims(coordinator, ["cpu", "local-io"])
+      : claims(coordinator, ["cpu", "local-io", "browser", "ffmpeg", "output-publication", "project-render"]);
     case "align-analyze":
     case "analyze-inactivity":
     case "analyze-music":

package/apps/desktop/cli/commands.ts

@@ -133,6 +133,7 @@ import { resolveEmojiAsset, searchEmojiAssets, inspectEmojiAssets } from "./emoj
 import { asCliError, CliError, EXIT_CODE } from "./errors";
 import { commandHelp, completions } from "./help";
 import { PlaywrightHtmlOverlayRenderer } from "./html-overlay-renderer";
+import { executeHtmlSceneCommand } from "./html-scene";
 import { BunProcessRunner, processIo, writeJson, writeLine, type CliIo, type ProcessRunner } from "./io";
 import {
   codePreparationHostResourceClaims,
@@ -300,7 +301,7 @@ import {
   workflowRunStore,
 } from "./workflow-runs";
 
-export const SLOPCAMERA_VERSION = "3.2.5";
+export const SLOPCAMERA_VERSION = "3.2.7";
 
 // Legacy direct renders predate per-target output contracts. Keep them
 // bounded generously enough for long-form production while preventing one
@@ -5761,6 +5762,13 @@ async function handleMediaColor(
 
 async function dispatch(context: CommandContext, command: CliCommand): Promise<void> {
   switch (command.kind) {
+    case "html-render": {
+      const output = await executeHtmlSceneCommand(applicationContext(context), command,
+        context.abortSignal ?? new AbortController().signal,
+        { progress: stage => context.io.stderr(`HTML scene: ${stage}\n`) });
+      writeValue(context.io, command.json, output, () => JSON.stringify(output, null, 2));
+      return;
+    }
     case "studio": {
       const output = await executeStudioCommand(applicationContext(context), command, context.abortSignal ?? new AbortController().signal);
       writeValue(context.io, command.json, output, () => JSON.stringify(output, null, 2));
@@ -6581,6 +6589,7 @@ type MutationReference =
 
 function commandMutationReference(command: CliCommand): MutationReference | undefined {
   switch (command.kind) {
+    case "html-render": return undefined; // A fresh retained attempt owns its publication lease.
     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.

package/apps/desktop/cli/help.ts

@@ -17,7 +17,7 @@ Commands:
   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
-  html catalog|scaffold          Inspect or create a transparent HTML overlay starter
+  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
   runs list|show|resume|approve|cancel
@@ -162,12 +162,21 @@ content-addressed \`ai image generate\` lane and returns project-composable cont
   html: `Usage:
   slopcamera html catalog [--json]
   slopcamera html scaffold <${HTML_OVERLAY_SCAFFOLD_KIND_HELP}> --output <file.html>
+  slopcamera html render --input <scene.json> [--dry-run] [--json]
 
 Catalog lists the closed scaffold profiles in stable order with their primary jobs, render
 substrates, and current exact browser-library versions. Scaffold creates a complete transparent
 HTML overlay without overwriting an existing file. Scaffolds use the existing
 @hraness/slopcamera/local/html-overlay API and exact locked import maps. Render the document through
-workflow.media.htmlOverlay to receive a deterministic transparent video layer.`,
+workflow.media.htmlOverlay to receive a deterministic transparent video layer.
+
+Render accepts a slopcamera.html-scene source, retains its HTML, declared resources and
+optional local soundtrack, and returns an H.264/AAC MP4 plus an ordinary editable project
+with separate scene-video and original-audio tracks. Device dimensions must be even integers.
+Duration rounds up to whole frames; audio starts at zero and is trimmed or padded to that
+duration. Soundtracks encode as 48 kHz stereo AAC at 320 kb/s. Dry run checks source and
+workload bounds without launching a browser, importing audio, or writing project state.
+Progress uses stderr; --json keeps stdout machine-readable.`,
   operations: `Usage:
   slopcamera operations list [--json]
   slopcamera operations show <kind>[@<version>] [--json]
@@ -472,10 +481,11 @@ export function commandHelp(topic: readonly string[]): string {
 
 export function completions(words: readonly string[]): readonly string[] {
   const topLevel = [
-    "operations", "diagram", "direct", "studio", "image", "workflows", "code", "runs", "doctor", "ai", "media", "record", "recordings", "projects", "project", "inspect", "events", "edit", "analyze", "align", "faces", "fillers", "render", "assets",
+    "operations", "diagram", "direct", "studio", "image", "html", "workflows", "code", "runs", "doctor", "ai", "media", "record", "recordings", "projects", "project", "inspect", "events", "edit", "analyze", "align", "faces", "fillers", "render", "assets",
   ];
   if (words.length <= 1) return topLevel;
   const command = words[0];
+  if (command === "html") return ["catalog", "scaffold", "render"];
   if (command === "direct") return ["init", "anchor", "plan", "start", "inspect", "revise", "generate", "resume", "review", "assemble", "cleanup"];
   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"];

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

@@ -0,0 +1,368 @@
+import { createHash, randomUUID } from "node:crypto";
+import { constants } from "node:fs";
+import { open, readdir } from "node:fs/promises";
+import { join, relative, resolve } from "node:path";
+import { z } from "zod";
+import type { ApplicationContext } from "../application/context";
+import {
+  bindExactCapabilities, ExactCapabilityApplicationRunner,
+  type ExactCapabilityBinding,
+} from "../application/capability-binding";
+import { bindHtmlOverlayBrowserRuntime } from "../application/html-overlay-browser-runtime";
+import { assertHtmlOverlayExecutionProfileLibraries, createHtmlOverlayExecutionBundle, HtmlOverlayExecutionIntegritySchema } from "../application/html-overlay-integrity";
+import {
+  loadRepositoryMedia, type MediaArtifactReference,
+} from "../application/operations/media/shared";
+import {
+  ProjectAssetV1Schema, ProjectEditPlanV1Schema, ProjectPlacementV1Schema, VideoProjectV1Schema,
+  type ProjectAssetV1,
+} from "../contracts";
+import { canonicalJson, canonicalJsonSha256 } from "../core/canonical-json";
+import { createDefaultProjectEditPlan } from "../core/project-plan";
+import { createNodeBundleFileSystem } from "../core/storage";
+import {
+  HTML_OVERLAY_MAX_HTML_BYTES, HTML_OVERLAY_MAX_RESOURCE_BYTES,
+  HTML_OVERLAY_MAX_TOTAL_RESOURCE_BYTES, HtmlOverlayAuthoringInputSchema,
+  htmlOverlayFrameCount,
+} from "../html-overlay/contracts";
+import { HtmlSceneInputSchema } from "../html-overlay/scene";
+import { HtmlOverlayActiveLibraryLocksSchema, getApprovedHtmlOverlayLibraryLock } from "../html-overlay/libraries";
+import { assertHtmlOverlayGpuEvidenceProfile } from "../html-overlay/execution-profile";
+import { CliError } from "./errors";
+import { ingestProjectMedia, SELF_CONTAINED_MEDIA_INPUT_ARGUMENTS } from "./media-ingest";
+import { withMutationLock } from "./mutation-lock";
+import { ensurePhysicalPrivateDirectoryWithin } from "./paths";
+import { resolveVerifiedProjectMedia } from "./project-media-integrity";
+import { readSpatialJson } from "./spatial-scene-service";
+
+const MAX_MEDIA_BYTES = 512 * 1024 * 1024;
+const MAX_REQUEST_BYTES = 2 * 1024 * 1024;
+const PROCESS_TIMEOUT_MS = 5 * 60_000;
+
+export type HtmlSceneStage = "source" | "browser" | "frames" | "encode" | "verify" | "project" | "complete";
+export interface HtmlSceneDependencies {
+  /** Internal controlled-test seams; invocation input cannot replace host capabilities. */
+  readonly bindBrowser?: typeof bindHtmlOverlayBrowserRuntime;
+  readonly bindTools?: typeof bindExactCapabilities;
+  readonly progress?: (stage: HtmlSceneStage) => void;
+}
+
+async function readPngHeader(path: string, expectedBytes: number) {
+  const handle = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+  try {
+    const before = await handle.stat({ bigint: true });
+    if (!before.isFile() || before.size !== BigInt(expectedBytes)) throw new CliError("conflict", "Scene frame changed before header validation.");
+    const header = Buffer.alloc(Math.min(33, expectedBytes));
+    const read = await handle.read(header, 0, header.length, 0);
+    const after = await handle.stat({ bigint: true });
+    if (read.bytesRead !== header.length || before.size !== after.size
+      || before.mtimeNs !== after.mtimeNs || before.ctimeNs !== after.ctimeNs) {
+      throw new CliError("conflict", "Scene frame changed during header validation.");
+    }
+    return header;
+  } finally { await handle.close(); }
+}
+
+async function readSource(application: ApplicationContext, input: unknown, signal: AbortSignal) {
+  const request = HtmlSceneInputSchema.parse(input);
+  assertHtmlOverlayExecutionProfileLibraries(request.libraries, request.executionProfile);
+  const loadedDocument = "path" in request.document
+    ? await loadRepositoryMedia(application, request.document, signal, HTML_OVERLAY_MAX_HTML_BYTES)
+    : undefined;
+  const html = loadedDocument === undefined
+    ? (request.document as { readonly html: string }).html
+    : new TextDecoder("utf-8", { fatal: true }).decode(loadedDocument.data);
+  let totalBytes = 0;
+  const resources = [];
+  for (const resource of request.resources) {
+    const loaded = await loadRepositoryMedia(application, { path: resource.path }, signal,
+      Math.min(HTML_OVERLAY_MAX_RESOURCE_BYTES, HTML_OVERLAY_MAX_TOTAL_RESOURCE_BYTES - totalBytes));
+    totalBytes += loaded.data.byteLength;
+    if (totalBytes > HTML_OVERLAY_MAX_TOTAL_RESOURCE_BYTES) throw new CliError("invalid-data", "Scene resources exceed their aggregate byte bound.");
+    resources.push({ declaration: resource, loaded });
+  }
+  const authoring = HtmlOverlayAuthoringInputSchema.parse({
+    kind: "slopcamera.html-overlay", schemaVersion: 1, html,
+    canvas: request.canvas, timing: request.timing, libraries: request.libraries,
+    parameters: request.parameters, seed: request.seed,
+    resources: resources.map(({ declaration: { path: _path, ...declaration }, loaded }) => ({
+      ...declaration, bytes: loaded.artifact.bytes, sha256: loaded.artifact.sha256,
+    })),
+  });
+  const frameCount = htmlOverlayFrameCount(request.timing);
+  return { request, authoring, resources, frameCount,
+    durationUs: Math.round(frameCount * 1_000_000 / request.timing.fps),
+    width: request.canvas.width, height: request.canvas.height };
+}
+
+export async function planHtmlScene(application: ApplicationContext, input: unknown, signal: AbortSignal) {
+  const source = await readSource(application, input, signal);
+  return {
+    kind: "slopcamera.html-scene-plan" as const, schemaVersion: 1 as const,
+    executed: false, name: source.request.name, frameCount: source.frameCount,
+    requestedDurationUs: source.request.timing.durationUs, durationUs: source.durationUs,
+    width: source.width, height: source.height, fps: source.request.timing.fps,
+    authoringSha256: canonicalJsonSha256(source.authoring),
+    audio: source.request.audio === undefined ? "none" : "explicit-local-import",
+    timingPolicy: "ceil-frames-trim-or-pad-audio-v1",
+    audioValidated: false,
+  };
+}
+
+const ProbeSchema = z.object({
+  streams: z.array(z.object({
+    codec_type: z.enum(["video", "audio"]), codec_name: z.string(),
+    width: z.number().int().optional(), height: z.number().int().optional(),
+    nb_read_frames: z.string().optional(), channels: z.number().int().optional(),
+    sample_rate: z.string().optional(), start_time: z.string().optional(), duration: z.string().optional(),
+    pix_fmt: z.string().optional(), color_range: z.string().optional(), color_space: z.string().optional(),
+    color_transfer: z.string().optional(), color_primaries: z.string().optional(),
+  })).min(1).max(2),
+  format: z.object({ duration: z.string() }),
+});
+
+export function verifyHtmlSceneProbe(input: unknown, expected: {
+  readonly width: number; readonly height: number; readonly frameCount: number;
+  readonly durationUs: number; readonly audio: boolean;
+}) {
+  const probe = ProbeSchema.parse(input);
+  const videos = probe.streams.filter(stream => stream.codec_type === "video");
+  const audios = probe.streams.filter(stream => stream.codec_type === "audio");
+  const video = videos[0];
+  const timeUs = (text: string | undefined): number => text !== undefined && /^-?\d+(?:\.\d+)?$/u.test(text)
+    ? Math.round(Number(text) * 1_000_000) : Number.NaN;
+  const durationUs = timeUs(probe.format.duration);
+  if (videos.length !== 1 || video?.codec_name !== "h264"
+    || video.pix_fmt !== "yuv420p" || video.color_range !== "tv" || video.color_space !== "bt709"
+    || video.color_transfer !== "bt709" || video.color_primaries !== "bt709"
+    || video.width !== expected.width || video.height !== expected.height
+    || Number(video.nb_read_frames) !== expected.frameCount
+    || !Number.isSafeInteger(timeUs(video.start_time)) || Math.abs(timeUs(video.start_time)) > 1
+    || !Number.isSafeInteger(timeUs(video.duration)) || Math.abs(timeUs(video.duration) - expected.durationUs) > 2
+    || !Number.isSafeInteger(durationUs) || Math.abs(durationUs - expected.durationUs) > 50_000
+    || audios.length !== (expected.audio ? 1 : 0)
+    || audios.some(audio => audio.codec_name !== "aac" || !Number.isSafeInteger(timeUs(audio.start_time))
+      || Math.abs(timeUs(audio.start_time)) > 30_000
+      || !Number.isSafeInteger(timeUs(audio.duration)) || Math.abs(timeUs(audio.duration) - expected.durationUs) > 30_000
+      || audio.channels !== 2 || audio.sample_rate !== "48000")) {
+    throw new CliError("invalid-data", "Encoded scene failed dimensions, frame count, duration, color, or audio verification.");
+  }
+  return { frameCount: expected.frameCount, width: video.width, height: video.height, durationUs,
+    audio: audios.length === 0 ? null : { codec: "aac", channels: 2, sampleRateHz: 48000, startTimeUs: timeUs(audios[0]!.start_time), durationUs: timeUs(audios[0]!.duration) } };
+}
+
+function placement(asset: ProjectAssetV1, durationUs: number, suffix: string) {
+  const endUs = Math.min(asset.durationUs, durationUs);
+  return ProjectPlacementV1Schema.parse({
+    placementId: `placement_${suffix}`, assetId: asset.assetId, enabled: true,
+    assetRange: { startUs: 0, endUs },
+    sync: { anchors: [{ assetTimeUs: 0, projectTimeUs: 0 }, { assetTimeUs: endUs, projectTimeUs: endUs }], provenance: { kind: "identity" } },
+    video: asset.streams.filter(stream => stream.kind === "video").map(stream => ({ streamId: stream.streamId,
+      presentation: asset.role === "music" ? { enabled: false } : {
+        enabled: true, blendMode: "normal", crop: { kind: "none" }, fit: "fill", layer: 0,
+        layout: { kind: "normalized", x: 0, y: 0, width: 1, height: 1 }, opacity: 1,
+      } })),
+    audio: asset.streams.filter(stream => stream.kind === "audio").map(stream => ({ streamId: stream.streamId,
+      presentation: { enabled: true, gainDb: 0, pan: 0 } })),
+  });
+}
+
+/** Retain authoring and separate source tracks, then publish one ordinary editable video project. */
+export async function renderHtmlScene(
+  application: ApplicationContext, input: unknown, signal: AbortSignal, dependencies: HtmlSceneDependencies = {},
+) {
+  const active = async () => {
+    if (signal.aborted) throw new CliError("cancelled", "HTML scene rendering was cancelled.");
+    if (application.hostResourceLease === undefined) throw new CliError("unavailable", "HTML scene rendering requires an admitted host-resource lease.");
+    await application.hostResourceLease.assertOwned();
+  };
+  await active();
+  dependencies.progress?.("source");
+  const source = await readSource(application, input, signal);
+  if (application.htmlOverlayRenderer === undefined) throw new CliError("unavailable", "HTML scene renderer is unavailable.");
+  const tools = await (dependencies.bindTools ?? bindExactCapabilities)(application, ["ffmpeg", "ffprobe", "html-browser"]);
+  const tool = (name: string): ExactCapabilityBinding => {
+    const found = tools.find(candidate => candidate.name === name);
+    if (found === undefined) throw new CliError("unavailable", `Missing scene capability: ${name}`);
+    return found;
+  };
+  dependencies.progress?.("browser");
+  const browserRuntime = await (dependencies.bindBrowser ?? bindHtmlOverlayBrowserRuntime)(tool("html-browser"), signal);
+  const suffix = `html_${randomUUID().replaceAll("-", "")}`;
+  const jobDirectory = await ensurePhysicalPrivateDirectoryWithin(application.paths.repositoryRoot,
+    `artifacts/slopcamera/generated/html-scenes/${suffix}`);
+  const fs = createNodeBundleFileSystem(jobDirectory);
+  const rootFs = createNodeBundleFileSystem(application.paths.repositoryRoot);
+  const runner = new ExactCapabilityApplicationRunner(application.runner, tools, application.paths.privateRoot);
+  const artifact = async (path: string, maximumBytes = MAX_MEDIA_BYTES): Promise<MediaArtifactReference> => ({
+    path: relative(application.paths.repositoryRoot, join(jobDirectory, path)),
+    ...await fs.inspectFile!(path, maximumBytes),
+  });
+  return await withMutationLock(jobDirectory, { command: "html render", label: source.request.name }, async lease => {
+    const fence = async () => { await active(); await lease.assertOwned(); };
+    const retainJson = async (path: string, value: unknown) => {
+      await fs.writeTextNoReplace!(path, `${canonicalJson(value)}\n`, fence);
+      return await artifact(path, 4 * 1024 * 1024);
+    };
+    const run = async (argv: readonly [string, ...string[]]) => {
+      await fence();
+      const result = await runner.run(argv, { abortSignal: signal, timeoutMs: PROCESS_TIMEOUT_MS,
+        maxOutputBytes: 1024 * 1024, inheritedFileDescriptors: application.hostResourceLease!.inheritedFileDescriptors });
+      await fence();
+      if (result.exitCode !== 0) throw new CliError("subprocess", `HTML scene media step failed: ${result.stderr.trim().slice(0, 1000) || result.exitCode}`);
+      return result;
+    };
+    await ensurePhysicalPrivateDirectoryWithin(jobDirectory, "source");
+    await fs.writeTextNoReplace!("source/scene.html", source.authoring.html, fence);
+    const retainedDocument = await artifact("source/scene.html", HTML_OVERLAY_MAX_HTML_BYTES);
+    const retainedResources = [];
+    for (const { declaration, loaded } of source.resources) {
+      const destination = `source/${declaration.name}-${loaded.artifact.sha256}`;
+      await rootFs.copyFileNoReplace!(loaded.artifact.path,
+        relative(application.paths.repositoryRoot, join(jobDirectory, destination)), loaded.artifact, fence);
+      const { path: _path, ...resource } = declaration;
+      retainedResources.push({ ...resource, ...loaded.artifact, path: relative(application.paths.repositoryRoot, join(jobDirectory, destination)), absolutePath: join(jobDirectory, destination) });
+    }
+    let audio: Awaited<ReturnType<typeof ingestProjectMedia>> | undefined;
+    if (source.request.audio !== undefined) {
+      audio = await ingestProjectMedia({ ffprobe: tool("ffprobe").command, now: application.clock.now(),
+        projectDirectory: jobDirectory, repositoryRoot: application.paths.repositoryRoot, role: "music",
+        sourcePath: resolve(application.paths.repositoryRoot, source.request.audio.path), maximumBytes: MAX_MEDIA_BYTES,
+        runner: { run: async argv => await run(argv) } });
+      if (audio.asset.streams.filter(stream => stream.kind === "audio").length !== 1) throw new CliError("invalid-data", "A scene soundtrack must contain exactly one playable audio stream.");
+      const soundtrack = audio.asset.streams.find(stream => stream.kind === "audio")!;
+      if (soundtrack.segments.length !== 1 || soundtrack.segments[0]!.assetRange.startUs !== 0
+        || soundtrack.segments[0]!.fileRange.startUs !== 0) {
+        throw new CliError("invalid-data", "A scene soundtrack must begin at the imported media timeline origin. Supply an audio file without a delayed stream start.");
+      }
+    }
+    const retainedInput = HtmlSceneInputSchema.parse({ ...source.request,
+      document: { path: relative(application.paths.repositoryRoot, join(jobDirectory, "source/scene.html")) },
+      resources: retainedResources.map(({ absolutePath: _absolutePath, bytes: _bytes, sha256: _sha256, ...resource }) => resource),
+      ...(audio === undefined ? {} : { audio: { path: relative(application.paths.repositoryRoot, audio.absolutePath) } }),
+    });
+    const retainedSource = await retainJson("source.json", retainedInput);
+    const authoringReceipt = await retainJson("authoring.json", source.authoring);
+    const intent = await retainJson("intent.json", { kind: "slopcamera.html-scene-intent", schemaVersion: 1,
+      source: retainedSource, document: retainedDocument, authoring: authoringReceipt, tools, frameCount: source.frameCount,
+      durationUs: source.durationUs, requestedDurationUs: source.request.timing.durationUs,
+      timingPolicy: "ceil-frames-trim-or-pad-audio-v1" });
+    dependencies.progress?.("frames");
+    const frameDirectory = await ensurePhysicalPrivateDirectoryWithin(jobDirectory, "render");
+    const frames = await application.htmlOverlayRenderer!.renderFrames({ authoring: source.authoring,
+      browserRuntime, outputDirectory: frameDirectory, resources: retainedResources,
+      ...(source.request.executionProfile === undefined ? {} : { executionProfile: source.request.executionProfile }) }, signal);
+    await fence();
+    if (frames.frameCount !== source.frameCount || frames.framePattern !== join(frameDirectory, "frames", "frame-%08d.png")) {
+      throw new CliError("invalid-data", "Scene renderer returned an unexpected frame count or output location.");
+    }
+    const expectedIntegrity = createHtmlOverlayExecutionBundle(source.authoring, browserRuntime, source.request.executionProfile).integrity;
+    if (canonicalJsonSha256(HtmlOverlayExecutionIntegritySchema.parse(frames.executionIntegrity)) !== canonicalJsonSha256(expectedIntegrity)) {
+      throw new CliError("conflict", "Scene renderer returned integrity evidence that differs from the bound browser execution.");
+    }
+    if (canonicalJsonSha256(HtmlOverlayActiveLibraryLocksSchema.parse(frames.libraryLocks))
+      !== canonicalJsonSha256(source.authoring.libraries.map(getApprovedHtmlOverlayLibraryLock))) {
+      throw new CliError("conflict", "Scene renderer returned library locks that differ from the authoring selection.");
+    }
+    assertHtmlOverlayGpuEvidenceProfile(source.request.executionProfile, frames.gpuEvidence);
+    const frameFs = createNodeBundleFileSystem(join(frameDirectory, "frames"));
+    const verifyFrames = async () => {
+      const names = await readdir(join(frameDirectory, "frames"));
+      if (names.length !== source.frameCount) throw new CliError("invalid-data", "Scene frame directory contains an unexpected entry.");
+      const hash = createHash("sha256");
+      for (let index = 0; index < source.frameCount; index++) {
+        await fence();
+        const name = `frame-${String(index).padStart(8, "0")}.png`;
+        const found = await frameFs.inspectFile!(name, source.width * source.height * 5 + 1024 * 1024);
+        const first = await readPngHeader(join(frameDirectory, "frames", name), found.bytes);
+        if (first.length < 33 || first.subarray(0, 8).toString("hex") !== "89504e470d0a1a0a"
+          || first.toString("ascii", 12, 16) !== "IHDR" || first.readUInt32BE(16) !== source.width || first.readUInt32BE(20) !== source.height) {
+          throw new CliError("invalid-data", "Rendered scene frame differs from the declared PNG dimensions.");
+        }
+        hash.update(`${index}:${found.bytes}:${found.sha256}\n`);
+      }
+      return hash.digest("hex");
+    };
+    const frameSha256 = await verifyFrames();
+    const frameReceipt = await retainJson("frames.json", { ...frames, frameSha256 });
+    const videoPath = join(jobDirectory, "scene.mp4"), outputPath = join(jobDirectory, "video.mp4");
+    const frameRate = String(source.request.timing.fps), duration = (source.durationUs / 1_000_000).toFixed(6);
+    const background = source.request.background.replace("#", "0x");
+    dependencies.progress?.("encode");
+    await run([tool("ffmpeg").command, "-nostdin", "-v", "error", "-n", "-threads", "2",
+      "-protocol_whitelist", "file", "-f", "image2", "-framerate", frameRate, "-start_number", "0", "-i", frames.framePattern,
+      "-filter_complex_threads", "1", "-filter_complex",
+      `color=c=${background}:s=${source.width}x${source.height}:r=${frameRate},format=rgba[bg];[bg][0:v]overlay=shortest=1:format=auto,format=rgb24[v]`,
+      "-map", "[v]", "-an", "-frames:v", String(source.frameCount), "-c:v", "libx264rgb", "-crf", "0", "-preset", "fast",
+      "-threads", "2", "-color_trc", "iec61966-2-1", "-color_primaries", "bt709", "-colorspace", "rgb", "-color_range", "pc",
+      "-fs", String(MAX_MEDIA_BYTES), videoPath]);
+    const videoArtifact = await artifact("scene.mp4");
+    if (await verifyFrames() !== frameSha256) throw new CliError("conflict", "Scene frame bytes changed during encoding.");
+    const audioStream = audio?.asset.streams.find(stream => stream.kind === "audio");
+    if (audio !== undefined) for (const stream of audio.asset.streams) for (const segment of stream.segments) {
+      await resolveVerifiedProjectMedia({ repositoryRoot: application.paths.repositoryRoot, path: segment.path, expected: segment, label: "Scene soundtrack" });
+    }
+    await run([tool("ffmpeg").command, "-nostdin", "-v", "error", "-n", "-threads", "2",
+      ...SELF_CONTAINED_MEDIA_INPUT_ARGUMENTS, "-i", videoPath,
+      ...(audio === undefined ? [] : [...SELF_CONTAINED_MEDIA_INPUT_ARGUMENTS, "-i", audio.absolutePath]),
+      "-map", "0:v:0", ...(audioStream === undefined ? ["-an"] : ["-map", `1:${audioStream.segments[0]!.streamIndex}`, "-af", "asetpts=PTS-STARTPTS,apad", "-c:a", "aac", "-b:a", "320k", "-ar", "48000", "-ac", "2"]),
+      "-vf", "scale=in_range=pc:out_range=pc:out_color_matrix=bt709,format=yuv444p,colorspace=ispace=bt709:itrc=iec61966-2-1:iprimaries=bt709:irange=pc:space=bt709:trc=bt709:primaries=bt709:range=tv:format=yuv420p:fast=0",
+      "-c:v", "libx264", "-crf", "18", "-preset", "medium",
+      "-threads", "2", "-filter_threads", "1", "-t", duration, "-r", frameRate,
+      "-color_trc", "bt709", "-color_primaries", "bt709", "-colorspace", "bt709", "-color_range", "tv", "-movflags", "+faststart",
+      "-fs", String(MAX_MEDIA_BYTES), outputPath]);
+    dependencies.progress?.("verify");
+    const inspected = await run([tool("ffprobe").command, "-v", "error", ...SELF_CONTAINED_MEDIA_INPUT_ARGUMENTS,
+      "-count_frames", "-show_entries", "stream=codec_type,codec_name,width,height,nb_read_frames,channels,sample_rate,start_time,duration,pix_fmt,color_range,color_space,color_transfer,color_primaries:format=duration", "-of", "json", outputPath]);
+    const verification = verifyHtmlSceneProbe(JSON.parse(inspected.stdout) as unknown, { ...source, audio: audio !== undefined });
+    const output = await artifact("video.mp4");
+    const importedVideo = await ingestProjectMedia({ ffprobe: tool("ffprobe").command, now: application.clock.now(),
+      projectDirectory: jobDirectory, repositoryRoot: application.paths.repositoryRoot, role: "screen", sourcePath: videoPath,
+      maximumBytes: MAX_MEDIA_BYTES, runner: { run: async argv => await run(argv) } });
+    if (importedVideo.asset.source.kind !== "imported" || importedVideo.asset.source.sourceSha256 !== videoArtifact.sha256) {
+      throw new CliError("conflict", "Scene video changed before its editable project import.");
+    }
+    const videoAsset = ProjectAssetV1Schema.parse({ ...importedVideo.asset,
+      source: { kind: "generated", generator: "slopcamera.html-scene", generatorVersion: "1", sourceSha256: intent.sha256 } });
+    dependencies.progress?.("project");
+    const projectId = `project_${suffix}`, timestamp = application.clock.now().toISOString();
+    const videoPlacement = placement(videoAsset, source.durationUs, `${suffix}_video`);
+    const project = VideoProjectV1Schema.parse({
+      kind: "slopcamera.video-project", schemaVersion: 1, projectId, name: source.request.name,
+      createdAt: timestamp, updatedAt: timestamp, currentEditPlanPath: "edits/current.json", analyses: [],
+      assets: [videoAsset, ...(audio === undefined ? [] : [audio.asset])],
+      placements: [videoPlacement, ...(audio === undefined ? [] : [placement(audio.asset, source.durationUs, `${suffix}_audio`)])],
+      referencePlacementId: videoPlacement.placementId, timeline: { timebase: "microseconds", durationUs: source.durationUs },
+    });
+    const plan = createDefaultProjectEditPlan(project, ProjectEditPlanV1Schema.shape.planId.parse(`plan_${suffix}`), timestamp);
+    for (const retained of [retainedSource, retainedDocument, authoringReceipt, intent, frameReceipt, videoArtifact, output, ...retainedResources]) {
+      await fence();
+      await resolveVerifiedProjectMedia({ repositoryRoot: application.paths.repositoryRoot, path: retained.path, expected: retained, label: "Retained scene source" });
+    }
+    if (audio !== undefined) for (const stream of audio.asset.streams) for (const segment of stream.segments) {
+      await resolveVerifiedProjectMedia({ repositoryRoot: application.paths.repositoryRoot, path: segment.path, expected: segment, label: "Scene soundtrack after encoding" });
+    }
+    const projectDirectory = await ensurePhysicalPrivateDirectoryWithin(application.paths.projectRoot, projectId);
+    const projectFs = createNodeBundleFileSystem(projectDirectory);
+    await ensurePhysicalPrivateDirectoryWithin(projectDirectory, "edits");
+    const receipt = await retainJson("receipt.json", { kind: "slopcamera.html-scene-receipt", schemaVersion: 1,
+      intent, source: retainedSource, document: retainedDocument, authoring: authoringReceipt, frameReceipt, video: videoArtifact, output,
+      projectId, projectSha256: canonicalJsonSha256(project), planSha256: canonicalJsonSha256(plan), verification,
+      audio: audio?.asset ?? null, timingPolicy: "ceil-frames-trim-or-pad-audio-v1" });
+    await projectFs.writeTextNoReplace!("html-scene.json", canonicalJson({ source: retainedSource, receipt }), fence);
+    await projectFs.writeTextNoReplace!("edits/current.json", canonicalJson(plan), fence);
+    await projectFs.writeTextNoReplace!("project.json", canonicalJson(project), fence);
+    await fence();
+    dependencies.progress?.("complete");
+    return { kind: "slopcamera.html-scene-export" as const, schemaVersion: 1 as const, output, receipt,
+      source: retainedSource, projectId, projectPath: relative(application.paths.repositoryRoot, join(projectDirectory, "project.json")), verification };
+  });
+}
+
+export async function executeHtmlSceneCommand(application: ApplicationContext, command: {
+  readonly input: string; readonly dryRun: boolean;
+}, signal: AbortSignal, dependencies: HtmlSceneDependencies = {}) {
+  const input = await readSpatialJson(resolve(application.paths.repositoryRoot, command.input), MAX_REQUEST_BYTES);
+  return command.dryRun ? await planHtmlScene(application, input, signal)
+    : await renderHtmlScene(application, input, signal, dependencies);
+}

package/apps/desktop/cli/main.ts

@@ -13,6 +13,7 @@ import {
 } from "./portable-surface";
 import { RecordingDaemonClient, runRecordingDaemon } from "./recording-daemon";
 import { renamedEnvironmentValue } from "./renamed-environment";
+import { rootHelpIntro } from "./root-help-intro";
 
 function valueAfter(argv: readonly string[], name: string): string {
   const index = argv.indexOf(name);
@@ -74,6 +75,10 @@ export async function main(
   if (portableExitCode !== undefined) return portableExitCode;
   const earlyCommand = parseCliArgs(unifiedArgv);
   if (earlyCommand.kind === "help" || earlyCommand.kind === "version" || earlyCommand.kind === "complete") {
+    const intro = rootHelpIntro(unifiedArgv, {
+      isTTY: process.stdout.isTTY === true, term: process.env.TERM, columns: process.stdout.columns,
+    });
+    if (intro !== "") processIo.stdout(intro);
     return await runCli(unifiedArgv, { io: processIo });
   }
   const paths = await resolveRepositoryPaths(processIo.cwd(), processIo.env);
@@ -84,7 +89,7 @@ export async function main(
     daemonCommand: daemonCommand(),
     helperExecutable,
   });
-  if (earlyCommand.kind === "spatial-world" || earlyCommand.kind === "directing" || earlyCommand.kind === "studio"
+  if (earlyCommand.kind === "html-render" || earlyCommand.kind === "spatial-world" || earlyCommand.kind === "directing" || earlyCommand.kind === "studio"
     || earlyCommand.kind === "spatial-scene" && earlyCommand.action === "camera-track") {
     const controller = new AbortController();
     const cancel = () => controller.abort(new CliError("cancelled", "Command interrupted."));

package/apps/desktop/cli/media-ingest-model.ts

@@ -278,6 +278,8 @@ function importedStreamRole(
 }
 
 export interface IngestProjectMediaOptions {
+  /** A caller may narrow the import bound; it cannot expand the host limit. */
+  readonly maximumBytes?: number;
   /** @internal Injectable durability boundary for focused fault and ordering tests. */
   readonly durability?: MediaIngestDurability;
   readonly ffprobe: string;

package/apps/desktop/cli/media-ingest-program.ts

@@ -67,7 +67,7 @@ function removeStagedImport(
   }));
 }
 
-function stageImport(projectDirectory: string, sourcePath: string): Program<StagedMediaImport> {
+function stageImport(projectDirectory: string, sourcePath: string, maximumBytes: number): Program<StagedMediaImport> {
   return Effect.gen(function*() {
     const platform = yield* MediaIngestPlatform;
     const source = yield* platform.sourcePath(sourcePath);
@@ -78,8 +78,8 @@ function stageImport(projectDirectory: string, sourcePath: string): Program<Stag
       if (before.isSymbolicLink() || !before.isFile()) {
         throw new CliError("unsafe-path", `Media source must be a physical regular file: ${sourcePath}`);
       }
-      if (before.size <= 0 || before.size > MAX_MEDIA_BYTES) {
-        throw new CliError("invalid-data", `Media source must contain 1 through ${MAX_MEDIA_BYTES} bytes.`);
+      if (before.size <= 0 || before.size > maximumBytes) {
+        throw new CliError("invalid-data", `Media source must contain 1 through ${maximumBytes} bytes.`);
       }
     });
     const imports = yield* privateImportsDirectory(projectDirectory);
@@ -178,6 +178,11 @@ function commitImport(imported: StagedMediaImport): Program<boolean> {
 export function ingestProjectMediaProgram(options: IngestProjectMediaOptions): Program<IngestedProjectMedia> {
   return Effect.gen(function*() {
     const platform = yield* MediaIngestPlatform;
+    const maximumBytes = yield* operationValidation("media", () => {
+      const bound = options.maximumBytes ?? MAX_MEDIA_BYTES;
+      if (!Number.isSafeInteger(bound) || bound < 1 || bound > MAX_MEDIA_BYTES) throw new CliError("invalid-data", "Invalid media import byte bound.");
+      return bound;
+    });
     const role = yield* operationValidation("media", () => ProjectAssetRoleSchema.parse(options.role));
     const [repositoryRoot, projectDirectory] = yield* Effect.all([
       platform.realpath(options.repositoryRoot), platform.realpath(options.projectDirectory),
@@ -186,7 +191,7 @@ export function ingestProjectMediaProgram(options: IngestProjectMediaOptions): P
     })));
     yield* platform.assertWithin(repositoryRoot, projectDirectory, "Project media import directory is outside the repository.");
     return yield* operationResource(
-      stageImport(projectDirectory, options.sourcePath),
+      stageImport(projectDirectory, options.sourcePath, maximumBytes),
       imported => Effect.gen(function*() {
         const probe = yield* probeProjectMediaProgram(options.ffprobe, options.runner, imported.temporaryPath);
         const location = yield* platform.assetLocation(repositoryRoot, imported.absolutePath, options.sourcePath);

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

@@ -214,6 +214,7 @@ export async function runPortableSurface(
 ): Promise<number | undefined> {
   const argv = canonicalizeUnifiedCliArgs(argvInput);
   if (argv[0] === "html") {
+    if (argv[1] === "render" || argv.includes("--help") || argv.includes("-h")) return undefined;
     if (argv[1] === "catalog") return runHtmlCatalog(argv, dependencies);
     return await runHtmlScaffold(argv, dependencies);
   }

package/apps/desktop/cli/recording-controller.ts

@@ -1354,7 +1354,7 @@ export class CaptureHelperRecordingController implements RecordingController {
         helperVersion: this.#helperVersion,
         now: this.#now,
         recordingId,
-        toolVersion: "3.2.5",
+        toolVersion: "3.2.7",
         verifier: this.#verifier,
       });
       await this.#bundleWriter.initialize();

package/apps/desktop/cli/root-help-intro.ts

@@ -0,0 +1,14 @@
+const camera = "   __\n _|__|_\n|  (o) |\n|______|\n\n";
+
+/** Decoration is confined to readable, interactive root help. */
+export function rootHelpIntro(
+  argv: readonly string[],
+  terminal: Readonly<{ isTTY: boolean; term: string | undefined; columns: number | undefined }>,
+): string {
+  return terminal.isTTY && terminal.term !== "dumb"
+    && terminal.columns !== undefined && Number.isFinite(terminal.columns) && terminal.columns >= 48
+    && (argv.length === 0
+      || argv.length === 1 && (argv[0] === "help" || argv[0] === "--help" || argv[0] === "-h"))
+    ? camera
+    : "";
+}