@hraness/slopcamera 3.2.4

package/apps/desktop/cli/overlay-playback.ts

@@ -0,0 +1,177 @@
+import { CliError } from "./errors";
+
+export const MAX_ANIMATED_OVERLAY_VIDEO_LOOP_BYTES = 512 * 1024 * 1024;
+export const MAX_ANIMATED_OVERLAY_AUDIO_LOOP_BYTES = 64 * 1024 * 1024;
+const RGBA_BYTES_PER_PIXEL = 4;
+const FLOAT32_STEREO_BYTES_PER_SAMPLE = 8;
+const VIDEO_ROW_ALIGNMENT_BYTES = 64;
+
+export interface AudibleSourceRangeOptions {
+  readonly audioDelayUs: number;
+  readonly audioEndUs: number;
+  readonly endBehavior: "freeze-end" | "hide" | "loop";
+  readonly requestedDurationUs: number;
+  readonly requestedStartUs: number;
+  readonly sourceWindowUs: number;
+}
+
+export interface AudibleSourceRange {
+  readonly endUs: number;
+  readonly startUs: number;
+}
+
+export function resolveAudibleSourceRange(options: AudibleSourceRangeOptions): AudibleSourceRange | null {
+  const {
+    audioDelayUs,
+    audioEndUs,
+    endBehavior,
+    requestedDurationUs,
+    requestedStartUs,
+    sourceWindowUs,
+  } = options;
+  const requestedEndUs = requestedStartUs + requestedDurationUs;
+  if (
+    !Number.isSafeInteger(audioDelayUs)
+    || !Number.isSafeInteger(audioEndUs)
+    || !Number.isSafeInteger(requestedDurationUs)
+    || !Number.isSafeInteger(requestedStartUs)
+    || !Number.isSafeInteger(requestedEndUs)
+    || !Number.isSafeInteger(sourceWindowUs)
+    || audioDelayUs < 0
+    || audioEndUs < 0
+    || requestedDurationUs <= 0
+    || requestedStartUs < 0
+    || sourceWindowUs <= 0
+    || audioEndUs > sourceWindowUs
+  ) {
+    throw new CliError("unsupported-plan", "Animated overlay audio has an unsupported playback window.");
+  }
+
+  if (audioEndUs <= audioDelayUs) return null;
+  if (endBehavior !== "loop") {
+    const startUs = Math.max(requestedStartUs, audioDelayUs);
+    const endUs = Math.min(requestedEndUs, audioEndUs);
+    return endUs > startUs ? { endUs, startUs } : null;
+  }
+
+  const positionInFirstCycleUs = requestedStartUs % sourceWindowUs;
+  const firstAudibleUs = positionInFirstCycleUs < audioDelayUs
+    ? requestedStartUs + audioDelayUs - positionInFirstCycleUs
+    : positionInFirstCycleUs < audioEndUs
+      ? requestedStartUs
+      : requestedStartUs + sourceWindowUs - positionInFirstCycleUs + audioDelayUs;
+  const endPositionUs = requestedEndUs % sourceWindowUs;
+  const lastAudibleUs = endPositionUs === 0
+    ? requestedEndUs - sourceWindowUs + audioEndUs
+    : endPositionUs <= audioDelayUs
+      ? requestedEndUs - endPositionUs - sourceWindowUs + audioEndUs
+      : endPositionUs <= audioEndUs
+        ? requestedEndUs
+        : requestedEndUs - endPositionUs + audioEndUs;
+  return lastAudibleUs > firstAudibleUs
+    ? { endUs: lastAudibleUs, startUs: firstAudibleUs }
+    : null;
+}
+
+export function assertVideoLoopBufferWithinLimit(options: {
+  readonly frameCount: number;
+  readonly label: string;
+  readonly pixelHeight: number;
+  readonly pixelWidth: number;
+}): void {
+  const { frameCount, label, pixelHeight, pixelWidth } = options;
+  const rowBytes = Math.ceil(pixelWidth * RGBA_BYTES_PER_PIXEL / VIDEO_ROW_ALIGNMENT_BYTES)
+    * VIDEO_ROW_ALIGNMENT_BYTES;
+  const frameBytes = rowBytes * pixelHeight;
+  if (
+    !Number.isSafeInteger(frameCount)
+    || frameCount <= 0
+    || !Number.isSafeInteger(pixelHeight)
+    || pixelHeight <= 0
+    || !Number.isSafeInteger(pixelWidth)
+    || pixelWidth <= 0
+    || !Number.isSafeInteger(frameBytes)
+    || frameBytes <= 0
+    || frameCount > Math.floor(MAX_ANIMATED_OVERLAY_VIDEO_LOOP_BYTES / frameBytes)
+  ) {
+    throw new CliError(
+      "unsupported-plan",
+      `${label} exceeds the ${MAX_ANIMATED_OVERLAY_VIDEO_LOOP_BYTES}-byte decoded video loop buffer bound.`,
+    );
+  }
+}
+
+export function assertAudioLoopBufferWithinLimit(options: {
+  readonly label: string;
+  readonly sampleCount: number;
+}): void {
+  const { label, sampleCount } = options;
+  if (
+    !Number.isSafeInteger(sampleCount)
+    || sampleCount <= 0
+    || sampleCount > Math.floor(
+      MAX_ANIMATED_OVERLAY_AUDIO_LOOP_BYTES / FLOAT32_STEREO_BYTES_PER_SAMPLE,
+    )
+  ) {
+    throw new CliError(
+      "unsupported-plan",
+      `${label} exceeds the ${MAX_ANIMATED_OVERLAY_AUDIO_LOOP_BYTES}-byte decoded audio loop buffer bound.`,
+    );
+  }
+}
+
+export interface AnimatedPlaybackWindowOptions {
+  readonly mediaDurationUs: number;
+  readonly outputDurationUs: number;
+  readonly playbackRate: number;
+  readonly sourceInUs: number;
+  readonly sourceOutUs: number | undefined;
+}
+
+export interface AnimatedPlaybackWindow {
+  readonly sourceInUs: number;
+  readonly sourceOutUs: number;
+}
+
+export function resolveAnimatedPlaybackWindow(
+  options: AnimatedPlaybackWindowOptions,
+): AnimatedPlaybackWindow {
+  const {
+    mediaDurationUs,
+    outputDurationUs,
+    playbackRate,
+    sourceInUs,
+    sourceOutUs: explicitSourceOutUs,
+  } = options;
+  if (!Number.isSafeInteger(mediaDurationUs) || mediaDurationUs <= 0) {
+    throw new CliError("invalid-data", "Animated overlay media has no positive, safe duration.");
+  }
+  if (!Number.isSafeInteger(sourceInUs) || sourceInUs < 0 || sourceInUs >= mediaDurationUs) {
+    throw new CliError(
+      "usage",
+      `Animated overlay --source-in must be before the media duration (${mediaDurationUs}us).`,
+    );
+  }
+  if (!Number.isSafeInteger(outputDurationUs) || outputDurationUs <= 0) {
+    throw new CliError("usage", "Animated overlay output duration must be positive.");
+  }
+  if (!Number.isFinite(playbackRate) || playbackRate <= 0 || playbackRate > 64) {
+    throw new CliError("usage", "Animated overlay --playback-rate must be greater than 0 and at most 64.");
+  }
+
+  // An omitted source-out means "through the immutable asset", not "for the
+  // edit's current mapped duration". The renderer still trims to the output
+  // range, while a later speed edit can reveal more source media without
+  // silently turning a hide into an early hide/loop/freeze.
+  const sourceOutUs = explicitSourceOutUs ?? mediaDurationUs;
+  if (!Number.isSafeInteger(sourceOutUs) || sourceOutUs <= sourceInUs) {
+    throw new CliError("usage", "Animated overlay --source-out must be after --source-in.");
+  }
+  if (sourceOutUs > mediaDurationUs) {
+    throw new CliError(
+      "usage",
+      `Animated overlay --source-out exceeds the media duration (${mediaDurationUs}us).`,
+    );
+  }
+  return { sourceInUs, sourceOutUs };
+}

package/apps/desktop/cli/paths.ts

@@ -0,0 +1,265 @@
+import { chmod, lstat, mkdir, realpath } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { CliError } from "./errors";
+
+async function isDirectory(path: string): Promise<boolean> {
+  try {
+    return (await lstat(path)).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+async function isFile(path: string): Promise<boolean> {
+  try {
+    return (await lstat(path)).isFile();
+  } catch {
+    return false;
+  }
+}
+
+export async function discoverRepositoryRoot(start: string): Promise<string> {
+  let candidate = resolve(start);
+  while (true) {
+    if (
+      await isFile(join(candidate, "package.json"))
+      && await isDirectory(join(candidate, "apps", "desktop"))
+    ) {
+      return await realpath(candidate);
+    }
+    const parent = dirname(candidate);
+    if (parent === candidate) break;
+    candidate = parent;
+  }
+  throw new CliError(
+    "not-found",
+    `Could not find a Slopcamera checkout from ${resolve(start)} (expected package.json and apps/desktop).`,
+  );
+}
+
+export function defaultArtifactRoot(repositoryRoot: string): string {
+  return join(repositoryRoot, "artifacts", "slopcamera", "recordings");
+}
+
+function defaultProjectRoot(repositoryRoot: string): string {
+  return join(repositoryRoot, "artifacts", "slopcamera", "projects");
+}
+
+function defaultPrivateRoot(repositoryRoot: string): string {
+  return join(repositoryRoot, "artifacts", "slopcamera", "private");
+}
+
+/** Shared local state coordinates resource admission across checkouts. */
+export function defaultCliStateRoot(
+  platform: NodeJS.Platform,
+  env: Readonly<Record<string, string | undefined>>,
+): string {
+  const userHome = homedir();
+  if (platform === "darwin") {
+    return join(userHome, "Library", "Application Support", "Slopcamera", "cli");
+  }
+  if (platform === "win32") {
+    const localAppData = env.LOCALAPPDATA;
+    return join(
+      localAppData !== undefined && isAbsolute(localAppData)
+        ? localAppData
+        : join(userHome, "AppData", "Local"),
+      "Slopcamera",
+      "cli",
+    );
+  }
+  const stateHome = env.XDG_STATE_HOME;
+  return join(
+    stateHome !== undefined && isAbsolute(stateHome)
+      ? stateHome
+      : join(userHome, ".local", "state"),
+    "slopcamera",
+  );
+}
+
+export function displayPath(repositoryRoot: string, path: string): string {
+  const pathRelative = relative(repositoryRoot, path);
+  if (pathRelative === "") return ".";
+  if (!pathRelative.startsWith("..") && !isAbsolute(pathRelative)) return pathRelative;
+  return path;
+}
+
+export async function ensurePrivateDirectory(path: string): Promise<void> {
+  try {
+    const details = await lstat(path);
+    if (details.isSymbolicLink() || !details.isDirectory()) {
+      throw new CliError("unsafe-path", `Private directory must be a real directory, not a symlink or file: ${path}`);
+    }
+  } catch (error) {
+    if (error instanceof CliError) throw error;
+    if (!(error instanceof Error && "code" in error && error.code === "ENOENT")) throw error;
+    await mkdir(path, { mode: 0o700, recursive: true });
+    const details = await lstat(path);
+    if (details.isSymbolicLink() || !details.isDirectory()) {
+      throw new CliError("unsafe-path", `Private directory creation was redirected: ${path}`);
+    }
+  }
+  await chmod(path, 0o700);
+}
+
+/** Create a private directory by walking physical components below an existing physical root. */
+export async function ensurePhysicalPrivateDirectoryWithin(
+  root: string,
+  requested: string,
+): Promise<string> {
+  if (requested.trim() === "" || isAbsolute(requested)) {
+    throw new CliError("unsafe-path", `Private directory must be relative to its root: ${requested}`);
+  }
+  const lexicalRoot = resolve(root);
+  const rootDetails = await lstat(lexicalRoot);
+  if (rootDetails.isSymbolicLink() || !rootDetails.isDirectory()) {
+    throw new CliError("unsafe-path", `Private directory root must be a physical directory: ${root}`);
+  }
+  const physicalRoot = await realpath(lexicalRoot);
+  const target = resolve(physicalRoot, requested);
+  if (!isWithin(physicalRoot, target) || target === physicalRoot) {
+    throw new CliError("unsafe-path", `Private directory escapes its root: ${requested}`);
+  }
+  let current = physicalRoot;
+  for (const part of relative(physicalRoot, target).split(sep)) {
+    current = join(current, part);
+    try {
+      const details = await lstat(current);
+      if (details.isSymbolicLink() || !details.isDirectory()) {
+        throw new CliError("unsafe-path", `Private directory requires physical components: ${requested}`);
+      }
+    } catch (error) {
+      if (error instanceof CliError) throw error;
+      if (!(error instanceof Error && "code" in error && error.code === "ENOENT")) throw error;
+      try {
+        await mkdir(current, { mode: 0o700 });
+      } catch (mkdirError) {
+        if (!(mkdirError instanceof Error && "code" in mkdirError && mkdirError.code === "EEXIST")) {
+          throw mkdirError;
+        }
+      }
+      const created = await lstat(current);
+      if (created.isSymbolicLink() || !created.isDirectory()) {
+        throw new CliError("unsafe-path", `Private directory creation was redirected: ${requested}`);
+      }
+    }
+  }
+  return current;
+}
+
+function isWithin(root: string, candidate: string): boolean {
+  const pathRelative = relative(root, candidate);
+  return pathRelative === "" || (!pathRelative.startsWith("..") && !isAbsolute(pathRelative));
+}
+
+async function nearestExistingPath(path: string): Promise<string> {
+  let candidate = path;
+  while (true) {
+    try {
+      await lstat(candidate);
+      return candidate;
+    } catch {
+      const parent = dirname(candidate);
+      if (parent === candidate) return candidate;
+      candidate = parent;
+    }
+  }
+}
+
+export async function resolveSafePath(root: string, requested: string): Promise<string> {
+  if (requested.trim() === "") {
+    throw new CliError("usage", "Output path cannot be empty.");
+  }
+  const absoluteRoot = resolve(root);
+  const rootDetails = await lstat(absoluteRoot);
+  if (rootDetails.isSymbolicLink() || !rootDetails.isDirectory()) {
+    throw new CliError("unsafe-path", `Output root must be a physical directory: ${absoluteRoot}`);
+  }
+  const target = isAbsolute(requested) ? resolve(requested) : resolve(absoluteRoot, requested);
+  if (!isWithin(absoluteRoot, target)) {
+    throw new CliError("unsafe-path", `Output path escapes ${absoluteRoot}: ${requested}`);
+  }
+
+  const [realRoot, existing] = await Promise.all([realpath(absoluteRoot), nearestExistingPath(target)]);
+  const realExisting = await realpath(existing);
+  if (!isWithin(realRoot, realExisting)) {
+    throw new CliError("unsafe-path", `Output path crosses a symlink outside ${absoluteRoot}: ${requested}`);
+  }
+
+  try {
+    const targetRealPath = await realpath(target);
+    if (!isWithin(realRoot, targetRealPath)) {
+      throw new CliError("unsafe-path", `Output path resolves outside ${absoluteRoot}: ${requested}`);
+    }
+  } catch (error) {
+    if (error instanceof CliError) throw error;
+    // A missing leaf is safe because its nearest existing ancestor was checked.
+  }
+  return target;
+}
+
+export interface RepositoryPaths {
+  readonly artifactRoot: string;
+  readonly desktopRoot: string;
+  readonly privateRoot: string;
+  readonly projectRoot: string;
+  readonly repositoryRoot: string;
+}
+
+export async function resolveRepositoryPaths(
+  cwd: string,
+  env: Readonly<Record<string, string | undefined>>,
+  installedFrom: string = import.meta.dir,
+  executable: string = process.execPath,
+): Promise<RepositoryPaths> {
+  // A copied Bun executable embeds its source under a read-only virtual root.
+  // Optional native helpers may live beside that executable; state never does.
+  const desktopRoot = installedFrom.startsWith("/$bunfs/")
+    ? dirname(await realpath(executable))
+    : join(await discoverRepositoryRoot(installedFrom), "apps", "desktop");
+  const repositoryRootInput = env.SLOPCAMERA_REPOSITORY_ROOT;
+  const requestedRoot = resolve(repositoryRootInput ?? cwd);
+  if (requestedRoot === "/$bunfs" || requestedRoot.startsWith("/$bunfs/")) {
+    throw new CliError("unsafe-path", "Slopcamera project state requires a physical caller workspace, not the embedded executable filesystem.");
+  }
+  if (!await isDirectory(requestedRoot)) {
+    throw new CliError("not-found", `Slopcamera project root is not a directory: ${requestedRoot}`);
+  }
+  const repositoryRoot = await realpath(requestedRoot);
+  const requiredArtifactRoot = defaultArtifactRoot(repositoryRoot);
+  const configuredArtifactRoot = env.SLOPCAMERA_ARTIFACT_ROOT;
+  if (
+    configuredArtifactRoot !== undefined
+    && resolve(configuredArtifactRoot) !== resolve(requiredArtifactRoot)
+  ) {
+    throw new CliError(
+      "unsafe-path",
+      `SLOPCAMERA_ARTIFACT_ROOT must remain ${requiredArtifactRoot}; external recording roots are forbidden.`,
+    );
+  }
+  const artifactRoot = await ensurePhysicalPrivateDirectoryWithin(
+    repositoryRoot,
+    "artifacts/slopcamera/recordings",
+  );
+  const projectRoot = await ensurePhysicalPrivateDirectoryWithin(
+    repositoryRoot,
+    relative(repositoryRoot, defaultProjectRoot(repositoryRoot)),
+  );
+  const privateRoot = await ensurePhysicalPrivateDirectoryWithin(
+    repositoryRoot,
+    relative(repositoryRoot, defaultPrivateRoot(repositoryRoot)),
+  );
+  await Promise.all([
+    ensurePrivateDirectory(artifactRoot),
+    ensurePrivateDirectory(projectRoot),
+    ensurePrivateDirectory(privateRoot),
+  ]);
+  return {
+    artifactRoot,
+    desktopRoot,
+    privateRoot,
+    projectRoot,
+    repositoryRoot,
+  };
+}

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

@@ -0,0 +1,242 @@
+import { constants } from "node:fs";
+import { mkdir, open } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+
+import { canonicalJson } from "../core/canonical-json";
+import {
+  HTML_OVERLAY_SCAFFOLD_KINDS,
+  HTML_OVERLAY_SCAFFOLD_PROFILES,
+  createHtmlOverlayScaffold,
+  getApprovedHtmlOverlayLibraryLock,
+  getHtmlOverlayScaffoldProfile,
+  type HtmlOverlayLibrarySpecifier,
+  type HtmlOverlayScaffoldKind,
+} from "../html-overlay";
+import { CliError } from "./errors";
+
+const HEADLESS_SLOPCAMERA_CLI_MODULE = "@hraness/slopcamera/cli";
+
+async function runHeadlessSlopcameraCli(argv: readonly string[]): Promise<void> {
+  // Keep this as a runtime package import so the headless CLI retains its own
+  // package-relative skill and asset resolution inside an installed bundle.
+  const module: unknown = await import(HEADLESS_SLOPCAMERA_CLI_MODULE);
+  if (
+    typeof module !== "object"
+    || module === null
+    || !("main" in module)
+    || typeof module.main !== "function"
+  ) {
+    throw new CliError("unavailable", "The portable Slopcamera CLI is unavailable.");
+  }
+  await module.main(argv);
+}
+
+export interface PortableSurfaceDependencies {
+  readonly cwd?: () => string;
+  readonly log?: (value: string) => void;
+  readonly runHeadless?: (argv: readonly string[]) => Promise<void>;
+  readonly writeScaffold?: (path: string, html: string) => Promise<void>;
+}
+function optionValue(argv: readonly string[], name: string): string | undefined {
+  const indexes = argv.flatMap((value, index) => value === name ? [index] : []);
+  if (indexes.length > 1) {
+    throw new CliError("usage", `${name} may be supplied at most once.`);
+  }
+  const index = indexes[0];
+  if (index === undefined) return undefined;
+  const value = argv[index + 1];
+  if (value === undefined || value.startsWith("--")) {
+    throw new CliError("usage", `${name} requires a value.`);
+  }
+  return value;
+}
+
+/**
+ * `image generate --prompt ...` is the project/media spelling and stays on the
+ * desktop Gateway lane. The portable file command has an explicit --output
+ * and delegates to @hraness/slopcamera without duplicating its parser.
+ */
+export function canonicalizeUnifiedCliArgs(
+  argv: readonly string[],
+): readonly string[] {
+  if (argv[0] !== "image" || argv[1] !== "generate") return argv;
+  const output = optionValue(argv, "--output");
+  const prompt = optionValue(argv, "--prompt");
+  if (output === undefined) {
+    return ["ai", "image", "generate", ...argv.slice(2)];
+  }
+  if (prompt === undefined) return argv;
+  const promptIndex = argv.indexOf("--prompt");
+  return [
+    "image",
+    "generate",
+    prompt,
+    ...argv.slice(2, promptIndex),
+    ...argv.slice(promptIndex + 2),
+  ];
+}
+
+function scaffoldKind(input: string | undefined): HtmlOverlayScaffoldKind {
+  if (input !== undefined) {
+    try {
+      return getHtmlOverlayScaffoldProfile(input as HtmlOverlayScaffoldKind).kind;
+    } catch {
+      // Preserve one stable CLI usage error for every foreign scaffold kind.
+    }
+  }
+  throw new CliError(
+    "usage",
+    `HTML scaffold must be one of: ${HTML_OVERLAY_SCAFFOLD_KINDS.join(", ")}.`,
+  );
+}
+
+function catalogLibraries(
+  specifiers: readonly HtmlOverlayLibrarySpecifier[],
+): readonly Readonly<{ specifier: string; version: string }>[] {
+  return specifiers.map(specifier => {
+    const lock = getApprovedHtmlOverlayLibraryLock(specifier);
+    return Object.freeze({
+      specifier: lock.specifier,
+      version: lock.version,
+    });
+  });
+}
+
+function htmlOverlayCatalogJson(): string {
+  return canonicalJson({
+    profiles: HTML_OVERLAY_SCAFFOLD_PROFILES.map(profile => ({
+      bestFor: profile.bestFor,
+      clockIntegration: profile.clockIntegration,
+      kind: profile.kind,
+      libraries: catalogLibraries(profile.libraries),
+      primaryJob: profile.primaryJob,
+      substrate: profile.substrate,
+      summary: profile.summary,
+    })),
+    schemaVersion: 1,
+  });
+}
+
+function htmlOverlayCatalogText(): string {
+  const rows = ["HTML overlay scaffold profiles:"];
+  for (const profile of HTML_OVERLAY_SCAFFOLD_PROFILES) {
+    const libraries = catalogLibraries(profile.libraries)
+      .map(library => `${library.specifier}@${library.version}`)
+      .join(", ") || "none";
+    rows.push(
+      `${profile.kind}  job=${profile.primaryJob}  substrate=${profile.substrate}  libraries=${libraries}`,
+      `  ${profile.summary} Best for: ${profile.bestFor}`,
+    );
+  }
+  return rows.join("\n");
+}
+
+async function writeScaffoldWithoutReplacement(
+  path: string,
+  html: string,
+): Promise<void> {
+  await mkdir(dirname(path), { mode: 0o700, recursive: true });
+  let handle;
+  try {
+    handle = await open(
+      path,
+      constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW | constants.O_WRONLY,
+      0o600,
+    );
+  } catch (error) {
+    if (error instanceof Error && "code" in error && error.code === "EEXIST") {
+      throw new CliError("conflict", `Refusing to overwrite existing file: ${path}`);
+    }
+    throw error;
+  }
+  try {
+    await handle.writeFile(html, "utf8");
+    await handle.sync();
+  } finally {
+    await handle.close();
+  }
+}
+
+async function runHtmlScaffold(
+  argv: readonly string[],
+  dependencies: PortableSurfaceDependencies,
+): Promise<number> {
+  if (argv[1] !== "scaffold") {
+    throw new CliError("usage", "Use slopcamera html scaffold <kind> --output <file.html>.");
+  }
+  const kind = scaffoldKind(argv[2]);
+  const output = optionValue(argv, "--output");
+  if (output === undefined) {
+    throw new CliError("usage", "slopcamera html scaffold requires --output <file.html>.");
+  }
+  if (!output.toLowerCase().endsWith(".html")) {
+    throw new CliError("usage", "HTML scaffold output must end in .html.");
+  }
+  if (
+    argv.length !== 5
+    || argv[3] !== "--output"
+  ) {
+    throw new CliError(
+      "usage",
+      "Use slopcamera html scaffold <kind> --output <file.html>.",
+    );
+  }
+  const outputPath = resolve((dependencies.cwd ?? process.cwd)(), output);
+  await (dependencies.writeScaffold ?? writeScaffoldWithoutReplacement)(
+    outputPath,
+    createHtmlOverlayScaffold(kind),
+  );
+  (dependencies.log ?? console.log)(`Created ${outputPath}`);
+  return 0;
+}
+
+function runHtmlCatalog(
+  argv: readonly string[],
+  dependencies: PortableSurfaceDependencies,
+): number {
+  const options = argv.slice(2);
+  if (
+    options.length > 1
+    || (options.length === 1 && options[0] !== "--json")
+  ) {
+    throw new CliError("usage", "Use slopcamera html catalog [--json].");
+  }
+  const output = options[0] === "--json"
+    ? htmlOverlayCatalogJson()
+    : htmlOverlayCatalogText();
+  (dependencies.log ?? console.log)(output);
+  return 0;
+}
+
+export async function runPortableSurface(
+  argvInput: readonly string[],
+  dependencies: PortableSurfaceDependencies = {},
+): Promise<number | undefined> {
+  const argv = canonicalizeUnifiedCliArgs(argvInput);
+  if (argv[0] === "html") {
+    if (argv[1] === "catalog") return runHtmlCatalog(argv, dependencies);
+    return await runHtmlScaffold(argv, dependencies);
+  }
+  const delegatesToHeadless = argv[0] === "diagram"
+    || argv[0] === "mcp"
+    || argv[0] === "canvas"
+    || argv[0] === "skill"
+    || (
+      argv[0] === "code"
+      && (argv[1] === "search" || argv[1] === "execute")
+    )
+    || (
+      argv[0] === "image"
+      && (argv[1] === "vectorize" || argv[1] === "generate")
+    );
+  if (!delegatesToHeadless) return undefined;
+
+  const previousExitCode = process.exitCode;
+  process.exitCode = undefined;
+  try {
+    await (dependencies.runHeadless ?? runHeadlessSlopcameraCli)(argv);
+    return process.exitCode ?? 0;
+  } finally {
+    process.exitCode = previousExitCode;
+  }
+}