@hraness/slopcamera 3.6.0 → 3.7.0

package/README.md

@@ -1,22 +1,22 @@
-# Slopcamera
+# SlopCamera
 
-[![Slopcamera: Visual work your agent can keep revising.](https://slopcamera.com/og.png)](https://slopcamera.com)
+[![SlopCamera: Images, diagrams, animation, 3D and video your coding agent can keep revising.](https://slopcamera.com/og.png)](https://slopcamera.com)
 
-**Slopcamera is a media studio for coding agents. Codex, Claude Code, and other
+**SlopCamera is a media studio for coding agents. Codex, Claude Code, and other
 agents make images, diagrams, animation, 3D scenes, and edited video from source
 files they can keep revising.**
 
 Describe the result you want to Codex, Claude Code, or another coding agent.
-Slopcamera gives the agent a Bun CLI, a TypeScript SDK, and an Agent Skill matched
+SlopCamera gives the agent a Bun CLI, a TypeScript SDK, and an Agent Skill matched
 to the CLI version, so it can inspect sources, set up cameras, edit a composition,
 and render. `slopcamera mcp` runs an MCP server with a smaller, fixed set of diagram,
-image, and scene tools. Projects stay in local files, and there is no Slopcamera
+image, and scene tools. Projects stay in local files, and there is no SlopCamera
 account. Generation uses your own Vercel AI Gateway account or, for prompt-only
 images, prepaid Hraness Credits.
 
 [Install](#install-slopcamera) · [Make a first diagram](#make-your-first-diagram) · [Capabilities](#what-slopcamera-does) · [Documentation](https://slopcamera.com/docs) · [slopcamera.com](https://slopcamera.com)
 
-## Made with Slopcamera
+## Made with SlopCamera
 
 [![An original brass optical instrument rendered in Blender](apps/web/media/native-product-poster-51b1658c46d3.webp)](https://slopcamera.com/docs/tutorials/first-native-film#inspect-the-finished-example)
 
@@ -27,7 +27,7 @@ The [portrait geometry lesson](https://slopcamera.com/docs/how-to/educational-vi
 adds mathematical typesetting, a presenter and authored captions. Each guide pairs
 the rendered output with source, runtime requirements and reproduction steps.
 
-## Why Slopcamera
+## Why SlopCamera
 
 - **Keep creative work editable.** Native scenes, portable scenes, diagrams,
   and video projects retain their own sources and settings. Rendered frames
@@ -45,16 +45,29 @@ the rendered output with source, runtime requirements and reproduction steps.
   instead run on the hosted API with prepaid Hraness Credits. Native Python
   authoring requires separate trust because it runs as your current user.
 
-## Install Slopcamera
+## Compared with other tools
 
-Slopcamera v3.5.0 includes 17 reusable film and animation direction profiles, deterministic exposure helpers, and a sample renderer that defaults to native 4K. Use the [style direction guide](docs/how-to/direct-visual-styles.md) to author cel animation, pixel art, mathematical explanations, and historical film treatments from retained sources. On macOS, `slopcamera menubar` puts Slopcamera in the menu bar and explains each macOS notice before it appears.
+- [Remotion](https://www.remotion.dev/) renders React components to video and can
+  render on AWS Lambda. It is source-available and needs a paid license for
+  companies of four or more people.
+- [HyperFrames](https://github.com/heygen-com/hyperframes) renders HTML to MP4
+  under Apache 2.0, with optional HeyGen-hosted rendering.
+- [MCP for Blender](https://github.com/ahujasid/mcp-for-blender), formerly Blender
+  MCP, lets an agent drive a running Blender interactively.
+
+SlopCamera renders HTML motion too, and adds diagrams, Three.js scenes, headless
+Blender, CadQuery, and Manim renders, and edits of your own footage in one local
+project. It has no cloud rendering and a much smaller community. See
+[the full comparison](https://slopcamera.com/docs/explanation/why-slopcamera#compared-with-other-tools).
+
+## Install SlopCamera
 
 Install [Bun 1.3.14 or newer](https://bun.sh), then install the verified
-[Slopcamera v3.5.0 release](https://github.com/hraness/slopcamera/releases/tag/v3.5.0)
+[SlopCamera v3.6.0 release](https://github.com/hraness/slopcamera/releases/tag/v3.6.0)
 from its canonical archive:
 
 ```sh
-bun add --global https://github.com/hraness/slopcamera/releases/download/v3.5.0/hraness-slopcamera-3.5.0.tgz
+bun add --global https://github.com/hraness/slopcamera/releases/download/v3.6.0/hraness-slopcamera-3.6.0.tgz
 slopcamera skill install --target agents
 ```
 
@@ -90,8 +103,8 @@ Native engines install separately. The [source-install guide](docs/how-to/use-cu
 explains workspace placement and durable-run identity; the
 [capability reference](docs/reference/capabilities.md) names runtime requirements.
 
-Slopcamera is a CLI. On macOS, an optional unbundled menu-bar companion shows
-what Slopcamera is rendering, how the last job ended, your last known credits
+SlopCamera is a CLI. On macOS, an optional unbundled menu-bar companion shows
+what SlopCamera is rendering, how the last job ended, your last known credits
 balance and the newest files in the agent outputs directory; `slopcamera menubar` runs a prebuilt
 companion directly and does not install or launch an application bundle. The
 companion is a thin product binary over the shared
@@ -106,14 +119,14 @@ when working from source.
 [Atet v3.2.3](https://github.com/hraness/atet/releases/tag/v3.2.3) and its
 [original archive](https://github.com/hraness/atet/releases/download/v3.2.3/hraness-atet-3.2.3.tgz)
 remain historical publication evidence. Those immutable bytes install Atet,
-not Slopcamera. Renaming the repository does not create a renamed package or
+not SlopCamera. Renaming the repository does not create a renamed package or
 change an existing release.
 
 </details>
 
 ## Make your first diagram
 
-After installing Slopcamera, this local task needs no model account. In a new directory,
+After installing SlopCamera, this local task needs no model account. In a new directory,
 create the included diagram, check it, and render it:
 
 ```sh
@@ -136,10 +149,12 @@ For detailed native 3D, follow
 [Your first native film](docs/tutorials/first-native-film.md). To generate editable
 architecture from dimensions, [build a parametric design](https://slopcamera.com/docs/how-to/parametric-design).
 
-## What Slopcamera does
+## What SlopCamera does
 
-Slopcamera lets your coding agent make images, diagrams, animation, 3D scenes,
+SlopCamera lets your coding agent make images, diagrams, animation, 3D scenes,
 and video from source files it can keep revising.
+Direct cel animation, pixel art, math explainers, and period film looks with the
+[style direction guide](docs/how-to/direct-visual-styles.md).
 
 ### Author scenes and direct cameras
 
@@ -158,7 +173,7 @@ rigged/morph profile in v3.3.1 admits bounded skins and morph targets. Saved spl
 capture appearance; they do not establish collision geometry or editable native
 meshes. See [Directed scenes](docs/spatial-scenes.md).
 
-Slopcamera v3.3.1 introduced the cinematic planning loop: a `slopcamera.spatial-direction`
+SlopCamera v3.3.1 introduced the cinematic planning loop: a `slopcamera.spatial-direction`
 document describes beats, actions, camera coverage, and look intents, compiles
 into proposed performance/camera/cinema/material-lighting/shot documents, and
 fans out into bounded galleries per axis. Declared effects bind into renders,
@@ -174,12 +189,12 @@ slopcamera workflows plan cinematic-world --input pack-input.json --json
 The `cinematic-world` workflow consumes one inert recipe pack — a bounded,
 content-addressed JSON document an agent can author — and stops before
 selection. Registration and selection stay explicit `scene project` operations.
-See [Direct a cinematic world](docs/how-to/direct-cinematic-worlds.md) and the
+See [Plan camera moves, lighting, and effects for a 3D scene](docs/how-to/direct-cinematic-worlds.md) and the
 [extension architecture](docs/extension-architecture.md).
 
 ### Film native worlds and educational animation
 
-Slopcamera can direct Blender for detailed sets, materials,
+SlopCamera can direct Blender for detailed sets, materials,
 lighting, skinned characters, cloth and liquid caches; CadQuery for parametric
 solids and STEP; and Manim Community for mathematical animation. Seven editable
 starters include a product, character, shaded street, cloth, liquid, CAD bracket,
@@ -195,7 +210,7 @@ camera clock for reuse. Supported GLB derivatives and calibrated cameras can
 cross between native and portable scenes; rigs, solvers, and procedural materials
 remain native. Blender and Python environments are installed separately, and
 source execution requires explicit current-user trust. See [Native film studio](docs/studio.md)
-and [Make an educational video](docs/how-to/educational-video.md).
+and [Make a math explainer video with Manim](docs/how-to/educational-video.md).
 
 ### Build diagrams and motion graphics
 
@@ -269,12 +284,12 @@ slopcamera workflows list --json
 slopcamera workflows show social-variants --json
 ```
 
-## How Slopcamera works
+## How SlopCamera works
 
 Keep the source that owns each creative decision. A native scene owns a rig or
 simulation; a portable scene owns supported geometry, cameras, and media surfaces;
 a diagram owns its objects and labels; a video project owns cuts and delivery.
-Slopcamera connects these through explicit assets and rendered derivatives.
+SlopCamera connects these through explicit assets and rendered derivatives.
 
 1. **Prepare the sources.** Import footage and assets or author a scene, diagram,
    or native program. Inspect available tools before choosing an engine.
@@ -318,7 +333,7 @@ declarative graphs, approvals, and resuming work.
 
 ## Design and trust
 
-There is no Slopcamera account, hosted project database, or browser generation service.
+There is no SlopCamera account, hosted project database, or browser generation service.
 Ordinary editing and rendering remain local. Gateway generation and selected
 cloud analysis use credentials from the local process and request explicit
 acknowledgement before uploading named media. The optional hosted API runs each
@@ -349,7 +364,7 @@ vision](https://algal.computer/docs/vision/) states the bet behind it.
 ## Documentation
 
 - **Learn:** [Your first diagram](docs/tutorials/first-diagram.md) · [Your first native film](docs/tutorials/first-native-film.md).
-- **Make a result:** [Edit video](docs/how-to/edit-video.md) · [Generate media](docs/how-to/generate-media.md) · [Run workflows](docs/how-to/run-workflows.md) · [Educational video](docs/how-to/educational-video.md) · [Direct a cinematic world](docs/how-to/direct-cinematic-worlds.md).
+- **Make a result:** [Edit video](docs/how-to/edit-video.md) · [Generate media](docs/how-to/generate-media.md) · [Run workflows](docs/how-to/run-workflows.md) · [Educational video](docs/how-to/educational-video.md) · [Plan camera moves, lighting, and effects for a 3D scene](docs/how-to/direct-cinematic-worlds.md).
 - **Look up support:** [Capabilities and release availability](docs/reference/capabilities.md) · [SDK entrypoints](docs/reference/sdk.md) · [Creative tools](docs/html-overlay-creative-toolkit.md).
 - **Understand the system:** [Architecture](docs/architecture.md) · [Native studio](docs/studio.md) · [Directed scenes](docs/spatial-scenes.md) · [Extension architecture](docs/extension-architecture.md).
 
@@ -413,4 +428,4 @@ an acknowledgment; the unacknowledged offer expires after ten minutes and does n
 consume the weekly shown cooldown. `support dismiss` opts out across the local suite;
 `support snooze` pauses for 30 days. `HRANESS_SUPPORT_AUDIENCE=off` disables ambient
 notices and claimed offers. Payment is an explicit human choice on the shared support
-page; Slopcamera has no product-updates mailing list or account-status lookup.
+page; SlopCamera has no product-updates mailing list or account-status lookup.

package/apps/desktop/README.md

@@ -1,4 +1,4 @@
-# Slopcamera local host and CLI
+# SlopCamera local host and CLI
 
 Slopcamera reads finished recording bundles from repository-local directories, combines independent camera and audio takes on one typed project clock, then applies non-destructive edits through the `slopcamera` CLI. The CLI is the product surface for agents. An optional unbundled `slopcamera menubar` companion surfaces the agent outputs directory in the macOS menu bar; it carries no capture or editing authority.
 

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

@@ -19,6 +19,12 @@ export interface HtmlOverlayFrameRenderRequest {
   readonly browserRuntime: HtmlOverlayBrowserRuntimeBinding;
   readonly outputDirectory: string;
   readonly resources: readonly BoundHtmlOverlayResource[];
+  /**
+   * Optional ascending subset of frame indexes to capture, for stills and
+   * previews. Omitted means every frame. Captured files keep their absolute
+   * frame index in the name, so `frame-%08d.png` stays addressable.
+   */
+  readonly frames?: readonly number[];
 }
 
 export interface HtmlOverlayFrameRenderResult {

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.6.0" as const;
+export const SLOPCAMERA_APPLICATION_TOOL_VERSION = "slopcamera-3.7.0" as const;
 
 export const OPERATION_KINDS = [
   "scene.audit",

package/apps/desktop/cli/args.ts

@@ -1,5 +1,6 @@
 import { CliError } from "./errors";
 import { MAX_EVENT_QUERY_LIMIT } from "./query-limits";
+import { HTML_FILM_CUTS, type HtmlFilmCommand, type HtmlFilmCut } from "./html-film-names";
 import { STUDIO_TEMPLATES, type StudioTemplate } from "./studio-template-names";
 import {
   slopcameraGalleryKinds,
@@ -121,6 +122,7 @@ export type SpatialProjectCommand = JsonOption & {
 
 export type CliCommand =
   | { readonly kind: "html-render"; readonly input: string; readonly dryRun: boolean; readonly json: boolean }
+  | HtmlFilmCommand
   | StudioCommand
   | DirectingCommand
   | SpatialWorldCommand
@@ -731,6 +733,63 @@ function fail(message: string): never {
   throw new CliError("usage", message);
 }
 
+const HTML_STILL_USAGE = "Use html still --input <scene.json> --at <seconds>[,<seconds>...] --output <dir> [--json].";
+const HTML_PREVIEW_USAGE = "Use html preview --input <scene.json> --output <dir> [--every <seconds>] [--json].";
+const HTML_DELIVER_USAGE = "Use html deliver <export.json> --basename <name> --poster-at <seconds> --social-at <seconds> [--cuts 1:1,9:16] [--per-beat-clips] [--beats <beats.json>] [--output <dir>] [--json].";
+
+function secondsList(value: string | undefined, usage: string): readonly number[] {
+  if (value === undefined) fail(usage);
+  return value.split(",").map(part => {
+    if (!/^(?:0|[1-9][0-9]*)(?:\.[0-9]+)?$/u.test(part.trim())) fail(`Times must be seconds such as 3 or 12.5; got ${part}.`);
+    return Number(part.trim());
+  });
+}
+
+function parseHtmlFilmArgs(action: "still" | "preview" | "deliver", argv: readonly string[]): HtmlFilmCommand {
+  if (action === "still") {
+    const parsed = parseOptions(argv, { "--input": "value", "--at": "value", "--output": "value", "--json": "flag" });
+    const input = optionString(parsed, "--input");
+    const output = optionString(parsed, "--output");
+    if (input === undefined || output === undefined || parsed.positionals.length !== 0) fail(HTML_STILL_USAGE);
+    return { kind: "html-film", action, input, output, at: secondsList(optionString(parsed, "--at"), HTML_STILL_USAGE), json: optionFlag(parsed, "--json") };
+  }
+  if (action === "preview") {
+    const parsed = parseOptions(argv, { "--input": "value", "--every": "value", "--output": "value", "--json": "flag" });
+    const input = optionString(parsed, "--input");
+    const output = optionString(parsed, "--output");
+    if (input === undefined || output === undefined || parsed.positionals.length !== 0) fail(HTML_PREVIEW_USAGE);
+    const every = optionString(parsed, "--every");
+    const [seconds] = every === undefined ? [2] : secondsList(every, HTML_PREVIEW_USAGE);
+    if (seconds === undefined || seconds <= 0) fail("--every must be more than 0 seconds.");
+    return { kind: "html-film", action, input, output, every: seconds, json: optionFlag(parsed, "--json") };
+  }
+  const parsed = parseOptions(argv, {
+    "--basename": "value", "--poster-at": "value", "--social-at": "value", "--cuts": "value",
+    "--per-beat-clips": "flag", "--beats": "value", "--output": "value", "--json": "flag",
+  });
+  const basename = optionString(parsed, "--basename");
+  if (parsed.positionals.length !== 1 || basename === undefined) fail(HTML_DELIVER_USAGE);
+  const single = (name: string) => {
+    const values = secondsList(optionString(parsed, name), HTML_DELIVER_USAGE);
+    if (values.length !== 1) fail(`${name} takes one time in seconds.`);
+    return values[0]!;
+  };
+  const cutsInput = optionString(parsed, "--cuts");
+  const cuts = cutsInput === undefined ? [] : cutsInput.split(",").map(cut => {
+    if (!(HTML_FILM_CUTS as readonly string[]).includes(cut)) fail(`--cuts takes ${HTML_FILM_CUTS.join(", ")}; got ${cut}.`);
+    return cut as HtmlFilmCut;
+  });
+  const beats = optionString(parsed, "--beats");
+  const output = optionString(parsed, "--output");
+  return {
+    kind: "html-film", action, exportPath: parsed.positionals[0]!, basename,
+    posterAt: single("--poster-at"), socialAt: single("--social-at"), cuts,
+    perBeatClips: optionFlag(parsed, "--per-beat-clips"),
+    ...(beats === undefined ? {} : { beats }), ...(output === undefined ? {} : { output }),
+    json: optionFlag(parsed, "--json"),
+  };
+}
+
 function parseOptions(argv: readonly string[], spec: OptionSpec): ParsedOptions {
   const options: Record<string, OptionValue> = {};
   const positionals: string[] = [];
@@ -3631,6 +3690,7 @@ export function parseCliArgs(argv: readonly string[]): CliCommand {
   const command = argv[0]!;
   switch (command) {
     case "html": {
+      if (argv[1] === "still" || argv[1] === "preview" || argv[1] === "deliver") return parseHtmlFilmArgs(argv[1], argv.slice(2));
       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");

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

@@ -125,6 +125,11 @@ export function commandHostResourceClaims(
   coordinator: HostResourceCoordinator,
 ): readonly HostResourceClaim[] {
   switch (command.kind) {
+    case "html-film": return command.action === "deliver"
+      ? claims(coordinator, ["cpu", "ffmpeg", "local-io"])
+      : claims(coordinator, command.action === "preview"
+        ? ["cpu", "local-io", "browser", "ffmpeg"]
+        : ["cpu", "local-io", "browser"]);
     case "html-render": return command.dryRun
       ? claims(coordinator, ["cpu", "local-io"])
       : claims(coordinator, ["cpu", "local-io", "browser", "ffmpeg", "output-publication", "project-render"]);

package/apps/desktop/cli/commands.ts

@@ -188,6 +188,7 @@ import { commandHelp, completions } from "./help";
 import { createLocalSlopcameraCapabilityManifest } from "./capability-manifest";
 import { PlaywrightHtmlOverlayRenderer } from "./html-overlay-renderer";
 import { executeHtmlSceneCommand } from "./html-scene";
+import { executeHtmlFilmCommand, formatHtmlFilmResult } from "./html-film";
 import { BunProcessRunner, processIo, writeJson, writeLine, type CliIo, type ProcessRunner } from "./io";
 import { launchMenubar, manageMenubar, reportOutputsRoot } from "./menubar";
 import {
@@ -363,7 +364,7 @@ import {
   workflowRunStore,
 } from "./workflow-runs";
 
-export const SLOPCAMERA_VERSION = "3.6.0";
+export const SLOPCAMERA_VERSION = "3.7.0";
 
 // Legacy direct renders predate per-target output contracts. Keep them
 // bounded generously enough for long-form production while preventing one
@@ -7450,6 +7451,16 @@ async function dispatch(context: CommandContext, command: CliCommand): Promise<v
       writeValue(context.io, command.json, output, () => JSON.stringify(output, null, 2));
       return;
     }
+    case "html-film": {
+      const output = await executeHtmlFilmCommand(applicationContext(context), command,
+        context.abortSignal ?? new AbortController().signal,
+        { progress: stage => context.io.stderr(`HTML film: ${stage}\n`) });
+      writeValue(context.io, command.json, output, () => formatHtmlFilmResult(output));
+      if (output.kind === "slopcamera.html-film-delivery" && !output.withinBudget) {
+        throw new CliError("invalid-data", "One or more delivered files are over budget.");
+      }
+      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));
@@ -8269,6 +8280,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 "html-film": return undefined; // Fresh private job directories; outputs are plain caller files.
     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

@@ -25,7 +25,8 @@ Commands:
                                  Author and render retained Blender, CAD and Manim productions
   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
+  html catalog|scaffold|init|render|still|preview|deliver
+                                 Author HTML scenes and launch films, render, and deliver web video
   style list|show                Discover reusable art direction and review criteria
   workflows list|show|plan|run   Plan or run a reviewed reusable workflow
   code init|check|plan|run       Author, preflight, and run trusted TypeScript workflows
@@ -304,7 +305,11 @@ compliance. Drawing sheets are exposed through this CLI and the root SDK, not co
         [--cell <n>] [--tile|--no-tile] [--json]
   slopcamera image icon <subject> --output <file.svg>
         [--purpose <mark|illustration>] [--model <model>] [--ink <#rgb>]
+        [--context <card|hero|inline>] [--candidates <1-4>]
         [--rounds <1-4>] [--critique-model <model>] [--keep-raster] [--json]
+  slopcamera image icon --set <file.json> --output-dir <directory>
+        [--context <card|hero|inline>] [--candidates <1-4>]
+        [--set-rounds <1-4>] [--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
@@ -312,7 +317,10 @@ caller's environment credential. The --prompt spelling without --output is an al
 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
+prompt between attempts. --context tunes the prompt and gates to where the art lands, and --set
+generates a manifest-declared family at once: pooled candidates, joint selection toward the
+family's measured coverage and stroke median, and a contact-sheet critique of the whole set before
+anything publishes. 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
@@ -330,7 +338,12 @@ direction, not proof of visual quality or historically authentic footage.`,
   html: `Usage:
   slopcamera html catalog [--json]
   slopcamera html scaffold <${HTML_OVERLAY_SCAFFOLD_KIND_HELP}> --output <file.html>
+  slopcamera html init <dir> --template launch-film [--aspect 16:9|1:1|9:16] [--json]
   slopcamera html render --input <scene.json> [--dry-run] [--json]
+  slopcamera html still --input <scene.json> --at <seconds>[,<seconds>...] --output <dir> [--json]
+  slopcamera html preview --input <scene.json> --output <dir> [--every <seconds>] [--json]
+  slopcamera html deliver <export.json> --basename <name> --poster-at <seconds> --social-at <seconds>
+      [--cuts 1:1,9:16,4:5] [--per-beat-clips] [--beats <beats.json>] [--output <dir>] [--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
@@ -344,7 +357,16 @@ with separate scene-video and original-audio tracks. Device dimensions must be e
 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.`,
+Progress uses stderr; --json keeps stdout machine-readable.
+
+Init creates a launch-film project (film.html, film.css, film.js, build.ts and a sample
+product mockup) in a new directory. Its build writes out/scene.json, out/beats.json and
+out/captions.vtt. Still and preview draw frames with the same injected runtime that render
+uses, so a still matches the rendered frame at that time; preview adds a contact sheet.
+Deliver reads output.path from html render --json output and writes a faststart H.264 MP4,
+a VP9 WebM, a poster, a 1200x630 social still, optional aspect cuts over a blurred fill, and
+optional 6 to 10 second clips per beat. It prints a receipt per file and exits non-zero when
+a file is over its budget: 12 MB per MP4, 10 MB for the WebM, 250 KB per JPEG.`,
   operations: `Usage:
   slopcamera operations list [--json]
   slopcamera operations show <kind>[@<version>] [--json]
@@ -712,7 +734,7 @@ export function completions(words: readonly string[]): readonly string[] {
   if (words.length <= 1) return topLevel;
   const command = words[0];
   if (command === "support") return ["protocol", "offer", "shown", "release", "dismiss", "snooze", "enable", "status"];
-  if (command === "html") return ["catalog", "scaffold", "render"];
+  if (command === "html") return ["catalog", "scaffold", "init", "render", "still", "preview", "deliver"];
   if (command === "style") return ["list", "show"];
   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"];

package/apps/desktop/cli/html-film-init.ts

@@ -0,0 +1,158 @@
+import { constants } from "node:fs";
+import { lstat, mkdir, open, readFile, realpath } from "node:fs/promises";
+import { basename, dirname, join, resolve } from "node:path";
+
+import { CliError } from "./errors";
+import { discoverRepositoryRoot } from "./paths";
+
+import { HTML_FILM_TEMPLATES, type HtmlFilmTemplate } from "./html-film-names";
+
+export { HTML_FILM_TEMPLATES, type HtmlFilmTemplate };
+export const HTML_FILM_ASPECTS = ["16:9", "1:1", "9:16"] as const;
+export type HtmlFilmAspect = (typeof HTML_FILM_ASPECTS)[number];
+
+/** Files copied from examples/html/<template>/, in write order. */
+export const HTML_FILM_TEMPLATE_FILES = [
+  "README.md", "build.ts", "film.css", "film.html", "film.js", "film.json", "mockups.tsx", "timeline.ts",
+] as const;
+
+const REACT_VERSION = "19.2.3";
+
+export interface HtmlFilmInitResult {
+  readonly kind: "slopcamera.html-film-init";
+  readonly schemaVersion: 1;
+  readonly directory: string;
+  readonly template: HtmlFilmTemplate;
+  readonly aspect: HtmlFilmAspect;
+  readonly slopcameraVersion: string;
+  readonly files: readonly string[];
+  readonly executed: false;
+  readonly next: readonly string[];
+}
+
+export interface HtmlFilmTemplateSource {
+  readonly version: string;
+  readonly files: Readonly<Record<string, string>>;
+}
+
+/** Reads the template from the installed package or checkout that runs this CLI. */
+export async function readHtmlFilmTemplate(template: HtmlFilmTemplate, from = import.meta.dir): Promise<HtmlFilmTemplateSource> {
+  if (from.startsWith("/$bunfs/")) {
+    throw new CliError("unavailable", "html init needs the @hraness/slopcamera package on disk. Run it through bunx @hraness/slopcamera or a checkout.");
+  }
+  const root = await discoverRepositoryRoot(from);
+  const manifest = JSON.parse(await readFile(join(root, "package.json"), "utf8")) as { readonly version?: unknown };
+  if (typeof manifest.version !== "string") throw new CliError("invalid-data", "The Slopcamera package has no version.");
+  const files: Record<string, string> = {};
+  for (const name of HTML_FILM_TEMPLATE_FILES) {
+    files[name] = await readFile(join(root, "examples", "html", template, name), "utf8");
+  }
+  return { version: manifest.version, files };
+}
+
+function packageName(directory: string): string {
+  const name = basename(directory).toLowerCase().replace(/[^a-z0-9._-]+/gu, "-").replace(/^[._-]+|[-]+$/gu, "");
+  return name === "" ? "launch-film" : name;
+}
+
+/**
+ * The files a new film project holds: the template, with its aspect set, plus
+ * a package.json that pins this Slopcamera version next to the source.
+ */
+export function htmlFilmProjectFiles(
+  source: HtmlFilmTemplateSource,
+  options: { readonly directory: string; readonly aspect: HtmlFilmAspect },
+): Readonly<Record<string, string>> {
+  const film = JSON.parse(source.files["film.json"]!) as Record<string, unknown>;
+  const files: Record<string, string> = { ...source.files, "film.json": `${JSON.stringify({ ...film, aspect: options.aspect }, null, 2)}\n` };
+  files["package.json"] = `${JSON.stringify({
+    name: packageName(options.directory),
+    private: true,
+    type: "module",
+    scripts: {
+      build: "bun build.ts",
+      still: "slopcamera html still --input out/scene.json --at 3,12.5 --output out/stills",
+      draft: "bun build.ts --scale 0.5 --fps 15",
+      render: "slopcamera html render --input out/scene.json --json > out/export.json",
+      deliver: "slopcamera html deliver out/export.json --basename launch --poster-at 9 --social-at 9 --cuts 1:1,9:16 --per-beat-clips",
+    },
+    dependencies: {
+      "@hraness/slopcamera": source.version,
+      react: REACT_VERSION,
+      "react-dom": REACT_VERSION,
+    },
+    devDependencies: {
+      "@types/bun": "latest",
+      "@types/react": "^19.2.0",
+      "@types/react-dom": "^19.2.0",
+    },
+  }, null, 2)}\n`;
+  files["tsconfig.json"] = `${JSON.stringify({
+    compilerOptions: {
+      target: "ES2023",
+      module: "Preserve",
+      moduleResolution: "bundler",
+      jsx: "react-jsx",
+      strict: true,
+      noEmit: true,
+      allowImportingTsExtensions: true,
+      skipLibCheck: true,
+      types: ["bun"],
+    },
+    include: ["*.ts", "*.tsx"],
+  }, null, 2)}\n`;
+  files[".gitignore"] = "node_modules/\nout/\n";
+  return files;
+}
+
+async function writeNew(path: string, text: string): Promise<void> {
+  const handle = await open(path, constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW | constants.O_WRONLY, 0o644);
+  try {
+    await handle.writeFile(text, "utf8");
+    await handle.sync();
+  } finally {
+    await handle.close();
+  }
+}
+
+/** Creates a new film project. It never merges into an existing directory. */
+export async function createHtmlFilmProject(
+  directoryInput: string,
+  options: { readonly template: HtmlFilmTemplate; readonly aspect: HtmlFilmAspect; readonly source?: HtmlFilmTemplateSource },
+): Promise<HtmlFilmInitResult> {
+  const requested = resolve(directoryInput);
+  const parent = await realpath(dirname(requested)).catch(() => {
+    throw new CliError("not-found", `The parent directory does not exist: ${dirname(requested)}`);
+  });
+  const directory = join(parent, basename(requested));
+  const source = options.source ?? await readHtmlFilmTemplate(options.template);
+  const files = htmlFilmProjectFiles(source, { directory, aspect: options.aspect });
+  try {
+    await mkdir(directory, { mode: 0o755 });
+  } catch (error) {
+    if (error instanceof Error && "code" in error && error.code === "EEXIST") {
+      throw new CliError("conflict", `Refusing to write into an existing path: ${directory}`);
+    }
+    throw error;
+  }
+  if (!(await lstat(directory)).isDirectory()) throw new CliError("conflict", "The film directory changed while it was created.");
+  const names = Object.keys(files).sort();
+  for (const name of names) await writeNew(join(directory, name), files[name]!);
+  return {
+    kind: "slopcamera.html-film-init",
+    schemaVersion: 1,
+    directory,
+    template: options.template,
+    aspect: options.aspect,
+    slopcameraVersion: source.version,
+    files: names,
+    executed: false,
+    next: [
+      `cd ${JSON.stringify(directory)} && bun install`,
+      "Edit film.json and mockups.tsx, then run bun run build.",
+      "slopcamera html still --input out/scene.json --at 3,12.5 --output out/stills",
+      "slopcamera html render --input out/scene.json --json > out/export.json",
+      "slopcamera html deliver out/export.json --basename launch --poster-at 9 --social-at 9",
+    ],
+  };
+}

package/apps/desktop/cli/html-film-names.ts

@@ -0,0 +1,17 @@
+/** Launch-film command shapes, kept free of runtime imports for the argument parser. */
+
+/** Film templates that `html init --template` writes; public copy cites these ids. */
+export const HTML_FILM_TEMPLATES = ["launch-film"] as const;
+export type HtmlFilmTemplate = (typeof HTML_FILM_TEMPLATES)[number];
+
+export const HTML_FILM_CUTS = ["1:1", "9:16", "4:5"] as const;
+export type HtmlFilmCut = (typeof HTML_FILM_CUTS)[number];
+
+export type HtmlFilmCommand =
+  | { readonly kind: "html-film"; readonly action: "still"; readonly input: string; readonly at: readonly number[]; readonly output: string; readonly json: boolean }
+  | { readonly kind: "html-film"; readonly action: "preview"; readonly input: string; readonly every: number; readonly output: string; readonly json: boolean }
+  | {
+    readonly kind: "html-film"; readonly action: "deliver"; readonly exportPath: string; readonly basename: string;
+    readonly posterAt: number; readonly socialAt: number; readonly cuts: readonly HtmlFilmCut[];
+    readonly perBeatClips: boolean; readonly beats?: string; readonly output?: string; readonly json: boolean;
+  };