@hraness/slopcamera 3.6.0 → 3.8.0

package/apps/desktop/cli/desktop-status.ts

@@ -0,0 +1,271 @@
+import { lstatSync, readdirSync } from "node:fs";
+import { extname, join } from "node:path";
+
+import { okEnvelope, type Envelope, type NextStep } from "@hraness/desktop-foundation/registry";
+import { box, clean, table, type View } from "@hraness/desktop-foundation/tui";
+
+import type { LegacyLoginReport } from "./legacy-login";
+import type { ActivityStatus } from "./activity-status";
+
+/**
+ * `slopcamera status` and `slopcamera tui`: what Slopcamera is doing, how
+ * the last job ended, the last credits balance a command saw, the newest
+ * outputs, and whether the retired menu bar still starts at login. Pure
+ * except `listOutputs`, so every state has a golden.
+ */
+export const STATUS_SCHEMA = "slopcamera.status/1";
+export const OUTPUTS_LIMIT = 3;
+/** A job still marked running after this long crashed or was killed. */
+export const STALE_RUNNING_MS = 6 * 60 * 60 * 1000;
+const MAX_LABEL_CHARS = 40;
+
+export type ActivityState = "idle" | "running" | "done" | "failed" | "stale";
+
+export interface StatusActivity {
+  readonly state: ActivityState;
+  readonly headline: string;
+  readonly detail: string;
+  readonly label?: string;
+  readonly startedAt?: string;
+  readonly finishedAt?: string;
+  readonly error?: string;
+}
+
+export interface StatusCredits {
+  readonly usd: string;
+  readonly low: boolean;
+  readonly checkedAt: string;
+}
+
+export interface StatusOutput {
+  readonly name: string;
+  readonly kind: string;
+  readonly bytes: number;
+  readonly modifiedAt: string;
+}
+
+export interface StatusOutputs {
+  readonly root: string;
+  readonly total: number;
+  readonly latest: readonly StatusOutput[];
+}
+
+export interface StatusData {
+  readonly product: "slopcamera";
+  readonly version: string;
+  readonly attention: boolean;
+  readonly activity: StatusActivity;
+  readonly credits: StatusCredits | null;
+  readonly outputs: StatusOutputs;
+  readonly legacyLoginItem: LegacyLoginReport;
+}
+
+export interface StatusInput {
+  readonly version: string;
+  readonly status: ActivityStatus;
+  readonly outputs: StatusOutputs;
+  readonly legacyLogin: LegacyLoginReport;
+  readonly now: Date;
+}
+
+export function ago(thenMs: number, nowMs: number): string {
+  const seconds = Math.max(0, Math.floor((nowMs - thenMs) / 1000));
+  if (seconds < 60) return "just now";
+  if (seconds < 3_600) return `${Math.floor(seconds / 60)} min ago`;
+  if (seconds < 7_200) return "1 hour ago";
+  if (seconds < 86_400) return `${Math.floor(seconds / 3_600)} hours ago`;
+  if (seconds < 172_800) return "yesterday";
+  return `${Math.floor(seconds / 86_400)} days ago`;
+}
+
+export function dollars(usd: string): string {
+  const bare = usd.replace(/^\$+/u, "");
+  return bare !== "" && /^[0-9.,]+$/u.test(bare) ? `$${bare}` : usd;
+}
+
+export function explain(code: string): string {
+  switch (code) {
+    case "cancelled": return "It was stopped before it finished";
+    case "not-found": return "A file it needed wasn't found";
+    case "unavailable": return "A tool it needed isn't available on this computer";
+    case "authorization-required": return "It needs more credits first";
+    case "subprocess": return "A render tool stopped with an error";
+    case "invalid-data":
+    case "incompatible": return "Its input wasn't in a form Slopcamera can use";
+    case "unsafe-path": return "It was asked to use a folder Slopcamera won't write to";
+    case "usage": return "The command had a typo or a missing option";
+    case "conflict": return "Something else was changing the same project";
+    default: return "Something went wrong. Run the command again to see why";
+  }
+}
+
+function plain(text: string, max: number): boolean {
+  return text !== "" && [...text].length <= max && /^[\p{L}\p{N} .,'$-]+$/u.test(text);
+}
+
+function iso(ms: number): string | undefined {
+  return Number.isFinite(ms) && ms >= 0 && ms <= 8.64e15 ? new Date(ms).toISOString() : undefined;
+}
+
+function activityOf(status: ActivityStatus, now: number): StatusActivity {
+  const activity = status.activity;
+  if (activity === undefined || !plain(activity.label, MAX_LABEL_CHARS) || !Number.isFinite(activity.startedAt)) {
+    return { state: "idle", headline: "Ready", detail: "Nothing rendered yet" };
+  }
+  const startedAt = iso(activity.startedAt);
+  const finishedMs = activity.finishedAt ?? activity.startedAt;
+  const finishedAt = activity.finishedAt === undefined ? undefined : iso(activity.finishedAt);
+  const times = { ...(startedAt === undefined ? {} : { startedAt }), ...(finishedAt === undefined ? {} : { finishedAt }) };
+  if (activity.state === "running") {
+    if (now - activity.startedAt < STALE_RUNNING_MS) {
+      return { state: "running", headline: activity.label, detail: `Started ${ago(activity.startedAt, now)}`, label: activity.label, ...times };
+    }
+    return { state: "stale", headline: "Last job stopped early", detail: `${activity.label} · started ${ago(activity.startedAt, now)}`, label: activity.label, ...times };
+  }
+  if (activity.state === "failed") {
+    const error = typeof activity.error === "string" && /^[a-z][a-z-]{0,40}$/u.test(activity.error) ? activity.error : "internal";
+    return { state: "failed", headline: "Last job didn't finish", detail: `${activity.label} · ${explain(error)}`, label: activity.label, error, ...times };
+  }
+  return { state: "done", headline: "Ready", detail: `Last job finished ${ago(finishedMs, now)}`, label: activity.label, ...times };
+}
+
+function creditsOf(status: ActivityStatus): StatusCredits | null {
+  const credits = status.credits;
+  if (credits === undefined || !plain(credits.usd, 16) || typeof credits.low !== "boolean") return null;
+  const checkedAt = iso(credits.checkedAt);
+  return checkedAt === undefined ? null : { usd: credits.usd, low: credits.low, checkedAt };
+}
+
+export function statusData(input: StatusInput): StatusData {
+  const now = input.now.getTime();
+  const activity = activityOf(input.status, now);
+  const credits = creditsOf(input.status);
+  return {
+    product: "slopcamera",
+    version: input.version,
+    attention: activity.state === "failed" || credits?.low === true || input.legacyLogin.state === "found",
+    activity,
+    credits,
+    outputs: input.outputs,
+    legacyLoginItem: input.legacyLogin,
+  };
+}
+
+export function statusNext(data: StatusData): NextStep[] {
+  const next: NextStep[] = [];
+  if (data.activity.state === "failed" || data.activity.state === "stale") {
+    next.push({ command: "slopcamera runs list --json", why: "See which run stopped and whether it can resume.", audience: "agent" });
+  }
+  if (data.credits?.low === true) {
+    next.push({ command: "slopcamera credits topup", why: "Credits are low; adding more opens a checkout for a person.", audience: "human" });
+  }
+  if (data.legacyLoginItem.state === "found") {
+    next.push({ command: "slopcamera legacy retire --json", why: "The retired menu bar still opens at login; this moves its login item aside.", audience: "agent" });
+  }
+  return next;
+}
+
+export function statusEnvelope(input: StatusInput): Envelope<StatusData> {
+  const data = statusData(input);
+  const next = statusNext(data);
+  return okEnvelope(STATUS_SCHEMA, data, next.length === 0 ? undefined : next, input.now);
+}
+
+function size(bytes: number): string {
+  if (bytes < 1024) return `${bytes} B`;
+  const units = ["KB", "MB", "GB", "TB"];
+  let value = bytes / 1024;
+  let unit = 0;
+  while (value >= 1024 && unit < units.length - 1) {
+    value /= 1024;
+    unit += 1;
+  }
+  return `${value < 10 ? Math.round(value * 10) / 10 : Math.round(value)} ${units[unit]}`;
+}
+
+function day(modifiedAt: string, now: number): string {
+  const then = Date.parse(modifiedAt);
+  const days = Math.floor((now - then) / 86_400_000);
+  if (days <= 0) return "today";
+  if (days === 1) return "yesterday";
+  return `${days} days ago`;
+}
+
+function mark(state: ActivityState): string {
+  switch (state) {
+    case "idle": return "○";
+    case "running": return "↻";
+    case "done": return "✓";
+    default: return "⚠";
+  }
+}
+
+function loginLine(report: LegacyLoginReport): string {
+  switch (report.state) {
+    case "found": return "⚠ The old menu bar still opens at login · run slopcamera legacy retire";
+    case "not-ours": return "– A menu bar login item changed outside Slopcamera is left alone";
+    default: return "✓ Nothing starts at login";
+  }
+}
+
+/** The one Status view, rendered by both `tui` and `tui --snapshot`. */
+export function statusViews(now: () => Date): View<StatusData>[] {
+  return [{
+    id: "status",
+    title: "Slopcamera",
+    render(data, width) {
+      const nowMs = now().getTime();
+      const lines = [`${mark(data.activity.state)} ${clean(data.activity.headline)} · ${clean(data.activity.detail)}`];
+      if (data.credits !== null) {
+        const checked = ago(Date.parse(data.credits.checkedAt), nowMs);
+        lines.push(data.credits.low
+          ? `⚠ Credits are low · ${dollars(data.credits.usd)} left · checked ${checked}`
+          : `✓ ${dollars(data.credits.usd)} in credits · Checked ${checked}`);
+      }
+      const outputs = data.outputs.latest.length === 0
+        ? ["No outputs yet · Agents save finished files here"]
+        : table(["Output", "Size", "Saved", "Type"], data.outputs.latest.map(item => [
+          clean(item.name), size(item.bytes), day(item.modifiedAt, nowMs), item.kind,
+        ]), width - 2);
+      const more = data.outputs.total > data.outputs.latest.length
+        ? [`${data.outputs.total} outputs · slopcamera outputs list --json`]
+        : ["slopcamera outputs open"];
+      return [
+        ...box("Now", lines, width),
+        ...box("Outputs", [...outputs, ...more], width),
+        ...box("Login", [loginLine(data.legacyLoginItem)], width),
+      ];
+    },
+  }];
+}
+
+function kindOf(name: string): string {
+  const extension = extname(name).slice(1);
+  return extension === "" || extension.length > 8 ? "File" : extension.toUpperCase();
+}
+
+/**
+ * The newest regular files at the top of the outputs folder. Hidden files,
+ * links and folders are skipped; a missing folder is an empty list.
+ */
+export function listOutputs(root: string, limit: number): StatusOutputs {
+  let names: string[];
+  try {
+    names = readdirSync(root);
+  } catch {
+    return { root, total: 0, latest: [] };
+  }
+  const files: StatusOutput[] = [];
+  for (const name of names) {
+    if (name.startsWith(".")) continue;
+    try {
+      const info = lstatSync(join(root, name));
+      if (!info.isFile()) continue;
+      files.push({ name, kind: kindOf(name), bytes: info.size, modifiedAt: new Date(info.mtimeMs).toISOString() });
+    } catch {
+      // Removed while listing.
+    }
+  }
+  files.sort((left, right) => right.modifiedAt.localeCompare(left.modifiedAt) || left.name.localeCompare(right.name));
+  return { root, total: files.length, latest: files.slice(0, limit) };
+}

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
@@ -38,6 +39,11 @@ Commands:
                                  Buy and inspect hosted generation credits
   media audio|color              Apply local non-destructive audio and video effects
   outputs                        Print the agent outputs directory
+  outputs list|open|reveal       List the newest outputs or open one on this Mac
+  status                         What Slopcamera is doing, credits and newest outputs
+  tui [--snapshot]               The status screen; --snapshot prints it once
+  commands [--json]              List every command with what it may change
+  legacy retire                  Stop the old menu bar opening at login
   recordings list               List recording bundles
   projects list|create           List projects or create one from a recording
   project inspect|add|edit|render
@@ -64,28 +70,6 @@ ${slopcameraSupportHelpLine()}`;
 
 const HELP: Readonly<Record<string, string>> = {
   advanced: `${slopcameraSupportAdvancedHelp()}`,
-  menubar: `Usage:
-  slopcamera menubar [--foreground|--background] [--json]
-  slopcamera menubar install|uninstall|status|start [--json]
-
-Shows what Slopcamera is doing in the menu bar: a render in progress, how the
-last job ended and your last known credits balance, plus your newest outputs.
-It only reads that status and the outputs folder (slopcamera outputs).
-
-  menubar               Open it now; it closes when this command ends
-  menubar start         Open it now and return (same as --background)
-  menubar install       Open it every time you log in
-  menubar uninstall     Stop opening it at login and remove the installed copy
-  menubar status        Check whether it opens at login and is running
-
-If it's already in your menu bar, starting it again says so and succeeds.
-macOS shows a notice that slopcamera-menubar can open at login. Turn it off any
-time in System Settings › General › Login Items & Extensions.
-
-The menu bar isn't in released packages yet, so it isn't listed in
-slopcamera help. In a Slopcamera checkout, build it with
-cargo build --release --manifest-path desktop/Cargo.toml and slopcamera finds
-it; elsewhere, set SLOPCAMERA_MENUBAR to the built file.`,
   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.`,
@@ -304,7 +288,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 +300,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 +321,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 +340,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]
@@ -707,12 +712,12 @@ export function commandHelp(topic: readonly string[]): string {
 
 export function completions(words: readonly string[]): readonly string[] {
   const topLevel = [
-    "capabilities", "operations", "diagram", "direct", "studio", "image", "html", "style", "workflows", "code", "runs", "doctor", "ai", "credits", "media", "menubar", "support", "outputs", "recordings", "projects", "project", "scene", "inspect", "events", "edit", "analyze", "align", "faces", "fillers", "render", "assets",
+    "capabilities", "operations", "diagram", "direct", "studio", "image", "html", "style", "workflows", "code", "runs", "doctor", "ai", "credits", "media", "support", "outputs", "status", "tui", "commands", "legacy", "recordings", "projects", "project", "scene", "inspect", "events", "edit", "analyze", "align", "faces", "fillers", "render", "assets",
   ];
   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"];
@@ -733,7 +738,8 @@ export function completions(words: readonly string[]): readonly string[] {
     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 (words[1] === "design") return ["catalog", "init", "inspect", "set", "compile", "gallery"];
+    return ["init", "check", "inspect", "diff", "patch", "evaluate", "audit", "render-audit", "solve", "review", "camera-track", "generate", "plan", "render", "direction", "effects", "behavior", "design", "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"];
@@ -745,5 +751,7 @@ export function completions(words: readonly string[]): readonly string[] {
   if (command === "media") return ["audio", "color"];
   if (command === "render") return ["plan", "run"];
   if (command === "assets") return ["emoji"];
+  if (command === "outputs") return ["list", "open", "reveal"];
+  if (command === "legacy") return ["retire"];
   return [];
 }

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;
+  };