@vanillaskyai/video 0.6.0 → 0.7.1

package/dist/cli.js

@@ -1,21 +1,21 @@
 #!/usr/bin/env node
-import "./chunk-EFL34TXF.js";
-import "./chunk-PNS52FL4.js";
-import "./chunk-3O7OMMMF.js";
-import {
-  getBuiltinTemplateMetadata,
-  listBuiltinTemplateMetadata
-} from "./chunk-3RV4YKB3.js";
+import "./chunk-AITKH6QT.js";
+import "./chunk-5SLENAJW.js";
 import {
   isTemplatePropertyFormatSupported,
   validateTemplateSchemaValue
 } from "./chunk-352ZZCET.js";
+import {
+  getBuiltinTemplateMetadata,
+  listBuiltinTemplateMetadata
+} from "./chunk-JNN3EYVP.js";
+import "./chunk-3O7OMMMF.js";
 import {
   assertTemplateTransitionMetadata
 } from "./chunk-2E6T633S.js";
 import {
   BUILTIN_TEMPLATE_MANIFEST
-} from "./chunk-HVCPEAQF.js";
+} from "./chunk-LKBZX7GV.js";
 import {
   externalVideoBackdropCapabilitySource
 } from "./chunk-WJ6FLKNC.js";
@@ -27,7 +27,7 @@ import {
 } from "./chunk-73NTSFFI.js";
 
 // src/cli/index.ts
-import { resolve as resolve7 } from "path";
+import { resolve as resolve9 } from "path";
 
 // src/cli/registry.ts
 import { randomUUID } from "crypto";
@@ -342,7 +342,7 @@ function minimalEnvironment() {
   return Object.fromEntries(names.flatMap((name) => process.env[name] == null ? [] : [[name, process.env[name]]]));
 }
 function delay(milliseconds) {
-  return new Promise((resolve8) => setTimeout(resolve8, milliseconds));
+  return new Promise((resolve10) => setTimeout(resolve10, milliseconds));
 }
 function signalProcessGroup(pid, signal) {
   try {
@@ -373,7 +373,7 @@ async function runTrustedSourceProcess(args, options) {
   const operation = options.operation ?? "loading";
   let cleanup;
   let processId;
-  const result = new Promise((resolve8, reject) => {
+  const result = new Promise((resolve10, reject) => {
     const child = spawn(process.execPath, [...args], {
       cwd: options.cwd,
       detached: true,
@@ -429,7 +429,7 @@ async function runTrustedSourceProcess(args, options) {
         ));
         return;
       }
-      resolve8(Buffer.concat(protocol).toString("utf8"));
+      resolve10(Buffer.concat(protocol).toString("utf8"));
     });
   });
   try {
@@ -595,7 +595,7 @@ async function discoverProjectTemplates(cwd, options = {}) {
 }
 
 // src/cli/sync.ts
-var GENERATED_NOTICE = "// Generated by `vanillasky sync`. Do not edit.\n";
+var GENERATED_NOTICE = "// Generated by `vanillasky templates sync`. Do not edit.\n";
 function browserSource(templates) {
   const imports = templates.map(({ exportName, importPath }, index) => exportName === "default" ? `import template${index} from ${JSON.stringify(importPath)};` : `import { ${exportName} as template${index} } from ${JSON.stringify(importPath)};`);
   const names = templates.map((_, index) => `template${index}`);
@@ -760,7 +760,7 @@ async function syncTemplates(options = {}) {
     if (await currentSource(output.path) !== output.source) drifted.push(relative3(cwd, output.path));
   }
   if (options.check && drifted.length > 0) {
-    throw new Error(`Generated template files are out of date: ${drifted.join(", ")}. Run \`vanillasky sync\`.`);
+    throw new Error(`Generated template files are out of date: ${drifted.join(", ")}. Run \`vanillasky templates sync\`.`);
   }
   if (!options.check && drifted.length > 0) {
     await mkdir(vanillaskyDirectory, { recursive: true });
@@ -1138,7 +1138,7 @@ async function checkTemplates(options = {}) {
   }));
   const generated = await inspectGeneratedTemplateStatus(cwd, templates);
   if (!generated.current) {
-    throw new Error(`Generated template files are out of date: ${generated.stale.join(", ")}. Run \`vanillasky sync\`.`);
+    throw new Error(`Generated template files are out of date: ${generated.stale.join(", ")}. Run \`vanillasky templates sync\`.`);
   }
   let renders = 0;
   for (const item2 of examples) {
@@ -1435,19 +1435,372 @@ async function findEffectiveTemplate(cwd, id) {
   return (await effectiveTemplateCatalog(cwd)).find((entry) => entry.id === id);
 }
 
+// src/cli/init.ts
+import { spawn as spawn2 } from "child_process";
+import {
+  existsSync as existsSync3,
+  mkdirSync as mkdirSync2,
+  readFileSync as readFileSync2,
+  renameSync as renameSync2,
+  unlinkSync as unlinkSync2,
+  writeFileSync as writeFileSync2
+} from "fs";
+import { basename as basename4, dirname as dirname3, isAbsolute, join as join8, resolve as resolve7 } from "path";
+import { fileURLToPath as fileURLToPath2 } from "url";
+
+// src/cli/gitignore.ts
+var ROOT_ENVIRONMENT_FILE = ".env.local";
+function escapeRegex(character) {
+  return /[\\^$.*+?()[\]{}|]/.test(character) ? `\\${character}` : character;
+}
+function matchesRootEnvironment(patternInput) {
+  let pattern = patternInput;
+  if (pattern.startsWith("/")) pattern = pattern.slice(1);
+  while (pattern.startsWith("**/")) pattern = pattern.slice(3);
+  if (pattern.endsWith("/") || pattern.includes("/")) return false;
+  let expression = "^";
+  for (let index = 0; index < pattern.length; index += 1) {
+    const character = pattern[index];
+    if (character === "\\" && index + 1 < pattern.length) {
+      expression += escapeRegex(pattern[index + 1]);
+      index += 1;
+    } else if (character === "*") {
+      while (pattern[index + 1] === "*") index += 1;
+      expression += ".*";
+    } else if (character === "?") {
+      expression += ".";
+    } else if (character === "[") {
+      const closing = pattern.indexOf("]", index + 1);
+      if (closing === -1) expression += "\\[";
+      else {
+        const contents = pattern.slice(index + 1, closing);
+        const negated = contents.startsWith("!") ? `^${contents.slice(1)}` : contents;
+        expression += `[${negated.replaceAll("\\", "\\\\")}]`;
+        index = closing;
+      }
+    } else {
+      expression += escapeRegex(character);
+    }
+  }
+  try {
+    return new RegExp(`${expression}$`).test(ROOT_ENVIRONMENT_FILE);
+  } catch {
+    return false;
+  }
+}
+function effectivelyIgnoresLocalEnvironment(source) {
+  let ignored = false;
+  for (const rawLine of source.replaceAll("\r\n", "\n").split("\n")) {
+    let line = rawLine.trim();
+    if (!line || line.startsWith("#")) continue;
+    const negated = line.startsWith("!");
+    if (negated) line = line.slice(1);
+    if (!matchesRootEnvironment(line)) continue;
+    ignored = !negated;
+  }
+  return ignored;
+}
+
+// src/cli/init.ts
+var SCAFFOLD_FILES = [
+  ".env.example",
+  "README.md",
+  "index.html",
+  "server.ts",
+  "src/main.tsx",
+  "stock.ts",
+  "tsconfig.json",
+  "vite.config.ts"
+];
+var DEFAULT_GITIGNORE = ["node_modules", "dist", ".env.local", ""].join("\n");
+function locateStarterRoot() {
+  const moduleDirectory = dirname3(fileURLToPath2(import.meta.url));
+  const candidates = [
+    resolve7(moduleDirectory, "../../starters/video-chat"),
+    resolve7(moduleDirectory, "../starters/video-chat")
+  ];
+  const found = candidates.find((candidate) => existsSync3(join8(candidate, "package.json")));
+  if (!found) throw new Error("The packaged video-chat starter is missing. Reinstall @vanillaskyai/video.");
+  return found;
+}
+function readJson(path) {
+  try {
+    const value = JSON.parse(readFileSync2(path, "utf8"));
+    if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("expected an object");
+    return value;
+  } catch (cause) {
+    const detail = cause instanceof Error ? cause.message : String(cause);
+    throw new Error(`Cannot read ${basename4(path)}: ${detail}`);
+  }
+}
+function stringMap(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return {};
+  return Object.fromEntries(Object.entries(value).filter((entry) => typeof entry[1] === "string"));
+}
+function resolvedSdkSpec(starterRoot, invokedSpec) {
+  const spec = invokedSpec?.trim();
+  if (!spec) return void 0;
+  if (spec === "@vanillaskyai/video" || spec.startsWith("@vanillaskyai/video@")) {
+    const packageManifest = readJson(resolve7(starterRoot, "../..", "package.json"));
+    return typeof packageManifest.version === "string" ? packageManifest.version : void 0;
+  }
+  if (spec.startsWith("file:")) return spec;
+  return isAbsolute(spec) ? `file:${spec}` : void 0;
+}
+function mergedManifest(cwd, starterRoot, invokedSpec) {
+  const destination = join8(cwd, "package.json");
+  const existing = existsSync3(destination) ? readJson(destination) : {};
+  const starter = readJson(join8(starterRoot, "package.json"));
+  const packageName = typeof existing.name === "string" && existing.name.trim() ? existing.name : basename4(cwd).toLowerCase().replace(/[^a-z0-9._-]+/g, "-");
+  const existingDependencies = stringMap(existing.dependencies);
+  const starterDependencies = stringMap(starter.dependencies);
+  const existingScripts = stringMap(existing.scripts);
+  const starterScripts = stringMap(starter.scripts);
+  for (const [name, command] of Object.entries(starterScripts)) {
+    if (Object.prototype.hasOwnProperty.call(existingScripts, name) && existingScripts[name] !== command) {
+      throw new Error(`package.json script ${name} already exists with a different command. Run init in a new npm project.`);
+    }
+  }
+  if (Object.prototype.hasOwnProperty.call(existing, "type") && existing.type !== "module") {
+    throw new Error(`package.json type ${String(existing.type)} is incompatible with the video-chat starter. Run init in a new npm project.`);
+  }
+  const sdkVersion = existingDependencies["@vanillaskyai/video"] ?? resolvedSdkSpec(starterRoot, invokedSpec) ?? starterDependencies["@vanillaskyai/video"];
+  if (!sdkVersion) throw new Error("Install @vanillaskyai/video before running vanillasky init.");
+  const dependencies = {
+    ...starterDependencies,
+    ...existingDependencies,
+    "@vanillaskyai/video": sdkVersion
+  };
+  const devDependencies = {
+    ...stringMap(starter.devDependencies),
+    ...stringMap(existing.devDependencies)
+  };
+  const manifest = {
+    ...starter,
+    ...existing,
+    name: packageName,
+    private: true,
+    type: "module",
+    scripts: { ...existingScripts, ...starterScripts },
+    dependencies,
+    devDependencies
+  };
+  return `${JSON.stringify(manifest, null, 2)}
+`;
+}
+function mergeGitignore(existing) {
+  if (existing == null) return DEFAULT_GITIGNORE;
+  const lines = existing.replaceAll("\r\n", "\n").split("\n");
+  for (const entry of ["node_modules", "dist"]) {
+    if (!lines.includes(entry)) lines.push(entry);
+  }
+  if (!effectivelyIgnoresLocalEnvironment(lines.join("\n"))) lines.push(".env.local");
+  return `${lines.filter((line, index) => line !== "" || index < lines.length - 1).join("\n")}
+`;
+}
+function atomicWrite(path, contents) {
+  mkdirSync2(dirname3(path), { recursive: true });
+  const temporary = `${path}.vanillasky-${process.pid}-${Math.random().toString(16).slice(2)}.tmp`;
+  try {
+    writeFileSync2(temporary, contents, { encoding: "utf8", flag: "wx", mode: 420 });
+    renameSync2(temporary, path);
+  } finally {
+    if (existsSync3(temporary)) unlinkSync2(temporary);
+  }
+}
+function defaultInstall(cwd) {
+  return new Promise((resolvePromise, reject) => {
+    const child = spawn2("npm", ["install", "--no-audit", "--no-fund"], {
+      cwd,
+      shell: false,
+      stdio: "inherit"
+    });
+    child.once("error", reject);
+    child.once("exit", (code, signal) => {
+      if (code === 0) resolvePromise();
+      else reject(new Error(`npm install failed${signal ? ` (${signal})` : code == null ? "" : ` with exit code ${code}`}`));
+    });
+  });
+}
+async function initVideoChatApp(options) {
+  const cwd = resolve7(options.cwd);
+  const starterRoot = resolve7(options.starterRoot ?? locateStarterRoot());
+  const planned = /* @__PURE__ */ new Map();
+  for (const path of SCAFFOLD_FILES) {
+    planned.set(path, readFileSync2(join8(starterRoot, path), "utf8"));
+  }
+  planned.set("package.json", mergedManifest(cwd, starterRoot, options.sdkSpec));
+  planned.set(".gitignore", mergeGitignore(
+    existsSync3(join8(cwd, ".gitignore")) ? readFileSync2(join8(cwd, ".gitignore"), "utf8") : void 0
+  ));
+  if (!existsSync3(join8(cwd, ".env.local"))) {
+    planned.set(".env.local", planned.get(".env.example"));
+  }
+  let changed = false;
+  for (const [path, contents] of planned) {
+    const destination = safeProjectPath(cwd, path);
+    if (!existsSync3(destination)) {
+      changed = true;
+      continue;
+    }
+    const current = readFileSync2(destination, "utf8");
+    if (current === contents) continue;
+    if (path === "package.json" || path === ".gitignore") {
+      changed = true;
+      continue;
+    }
+    throw new Error(`${path} already exists with different content. Run init in a new npm project.`);
+  }
+  if (!changed) return { initialized: false, installed: false };
+  for (const [path, contents] of planned) {
+    const destination = safeProjectPath(cwd, path);
+    if (!existsSync3(destination) || readFileSync2(destination, "utf8") !== contents) atomicWrite(destination, contents);
+  }
+  try {
+    await (options.installDependencies ?? defaultInstall)(cwd);
+  } catch (cause) {
+    const detail = cause instanceof Error ? cause.message : String(cause);
+    throw new Error(`${detail}. The app files are ready; run npm install to finish setup.`);
+  }
+  return { initialized: true, installed: true };
+}
+
+// src/cli/doctor.ts
+import { existsSync as existsSync4, readFileSync as readFileSync3 } from "fs";
+import { join as join9, resolve as resolve8 } from "path";
+var REQUIRED_FILES = [
+  ".env.local",
+  "index.html",
+  "server.ts",
+  "src/main.tsx",
+  "stock.ts",
+  "tsconfig.json",
+  "vite.config.ts"
+];
+var REQUIRED_DEPENDENCIES = [
+  "@vanillaskyai/video",
+  "@ai-sdk/anthropic",
+  "@ai-sdk/xai",
+  "@fal-ai/client",
+  "ai",
+  "react",
+  "react-dom"
+];
+var PROVIDER_KEYS = /* @__PURE__ */ new Set(["ANTHROPIC_API_KEY", "XAI_API_KEY", "FAL_KEY", "PEXELS_API_KEY"]);
+var CLIENT_ENV_PREFIXES = ["VITE", "NEXT_PUBLIC"].map((prefix) => `${prefix}_`);
+function parseEnvironment(source) {
+  const result = /* @__PURE__ */ new Map();
+  for (const rawLine of source.replaceAll("\r\n", "\n").split("\n")) {
+    const line = rawLine.trim();
+    if (!line || line.startsWith("#")) continue;
+    const match = /^(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*)$/.exec(line);
+    if (!match) continue;
+    let value = match[2].trim();
+    if (value.startsWith('"') && value.endsWith('"') || value.startsWith("'") && value.endsWith("'")) {
+      value = value.slice(1, -1);
+    } else {
+      value = value.replace(/\s+#.*$/, "").trim();
+    }
+    result.set(match[1], value);
+  }
+  return result;
+}
+function stringMap2(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return {};
+  return Object.fromEntries(Object.entries(value).filter((entry) => typeof entry[1] === "string"));
+}
+function isJsonObject(value) {
+  return value != null && typeof value === "object" && !Array.isArray(value);
+}
+function doctorVideoChatApp(cwdInput) {
+  const cwd = resolve8(cwdInput);
+  const lines = [];
+  let ok = true;
+  for (const path of REQUIRED_FILES) {
+    if (!existsSync4(join9(cwd, path))) {
+      ok = false;
+      lines.push(`MISSING  ${path}`);
+    }
+  }
+  let manifest = {};
+  try {
+    const parsed = JSON.parse(readFileSync3(join9(cwd, "package.json"), "utf8"));
+    if (!isJsonObject(parsed)) throw new Error("expected an object");
+    manifest = parsed;
+  } catch {
+    ok = false;
+    lines.push("MISSING  valid package.json");
+  }
+  const dependencies = { ...stringMap2(manifest.dependencies), ...stringMap2(manifest.devDependencies) };
+  const missingDependencies = REQUIRED_DEPENDENCIES.filter((name) => !dependencies[name]);
+  for (const name of missingDependencies) {
+    ok = false;
+    lines.push(`MISSING  dependency ${name}`);
+  }
+  const scripts = stringMap2(manifest.scripts);
+  if (scripts.dev !== "vite" || scripts.build !== "tsc && vite build") {
+    ok = false;
+    lines.push("MISSING  video-chat dev/build scripts");
+  }
+  const ignore = existsSync4(join9(cwd, ".gitignore")) ? readFileSync3(join9(cwd, ".gitignore"), "utf8") : "";
+  if (!effectivelyIgnoresLocalEnvironment(ignore)) {
+    ok = false;
+    lines.push("UNSAFE   .env.local is not ignored");
+  }
+  const environment = existsSync4(join9(cwd, ".env.local")) ? parseEnvironment(readFileSync3(join9(cwd, ".env.local"), "utf8")) : /* @__PURE__ */ new Map();
+  for (const name of environment.keys()) {
+    if (CLIENT_ENV_PREFIXES.some((prefix) => name.startsWith(prefix) && PROVIDER_KEYS.has(name.slice(prefix.length)))) {
+      ok = false;
+      lines.push(`UNSAFE   ${name} exposes a provider key to the browser`);
+    }
+  }
+  lines.push("READY    templates + browser voice");
+  if (environment.get("ANTHROPIC_API_KEY")) lines.push("READY    ANTHROPIC_API_KEY");
+  else {
+    ok = false;
+    lines.push("MISSING  ANTHROPIC_API_KEY in .env.local");
+  }
+  lines.push(environment.get("XAI_API_KEY") ? "READY    generated speech" : "OPTIONAL generated speech \u2014 add XAI_API_KEY");
+  lines.push(environment.get("FAL_KEY") ? "READY    generated video + transcription" : "OPTIONAL generated video + transcription \u2014 add FAL_KEY");
+  lines.push(environment.get("PEXELS_API_KEY") ? "READY    stock media" : "OPTIONAL stock media \u2014 add PEXELS_API_KEY");
+  if (existsSync4(join9(cwd, "vanillasky", "templates"))) {
+    lines.push("CHECK    custom templates with npx vanillasky templates check");
+  }
+  return { ok, lines };
+}
+
 // src/cli/index.ts
 function help() {
+  return [
+    "VanillaSky video chat",
+    "",
+    "Usage:",
+    "  vanillasky init",
+    "  vanillasky doctor",
+    "  vanillasky templates <command>",
+    "",
+    "Template commands:",
+    "  vanillasky templates list [--builtin] [--json]",
+    "  vanillasky templates describe <template> [--builtin] [--json]",
+    "  vanillasky templates add <template...> [--dry-run|--diff] [--overwrite]",
+    "  vanillasky templates add --all [--dry-run|--diff] [--overwrite]",
+    "  vanillasky templates sync [--check]",
+    "  vanillasky templates check",
+    "  vanillasky templates create <id>"
+  ].join("\n");
+}
+function templateHelp() {
   return [
     "VanillaSky source-owned templates",
     "",
     "Usage:",
-    "  vanillasky list [--builtin] [--json]",
-    "  vanillasky describe <template> [--builtin] [--json]",
-    "  vanillasky add <template...> [--dry-run|--diff] [--overwrite]",
-    "  vanillasky add --all [--dry-run|--diff] [--overwrite]",
-    "  vanillasky sync [--check]",
-    "  vanillasky check",
-    "  vanillasky create <id>"
+    "  vanillasky templates list [--builtin] [--json]",
+    "  vanillasky templates describe <template> [--builtin] [--json]",
+    "  vanillasky templates add <template...> [--dry-run|--diff] [--overwrite]",
+    "  vanillasky templates add --all [--dry-run|--diff] [--overwrite]",
+    "  vanillasky templates sync [--check]",
+    "  vanillasky templates check",
+    "  vanillasky templates create <id>"
   ].join("\n");
 }
 function unknownOption(command, args, allowed) {
@@ -1481,21 +1834,76 @@ function sanitizeTerminalOutput(value) {
 function runVanillaSkyCli(argv, environment = {}) {
   const output = environment.write ?? console.log;
   const write = (line) => output(sanitizeTerminalOutput(line));
-  const cwd = resolve7(environment.cwd ?? process.cwd());
-  const [command, ...args] = argv;
+  const cwd = resolve9(environment.cwd ?? process.cwd());
+  const [rootCommand, ...rootArgs] = argv;
+  if (rootCommand === "init") {
+    return (async () => {
+      try {
+        const unknown = unknownOption("init", rootArgs, []);
+        if (unknown) throw new Error(unknown);
+        if (rootArgs.length > 0) throw new Error(`Unexpected init argument: ${rootArgs[0]}`);
+        const result = await initVideoChatApp({
+          cwd,
+          starterRoot: environment.starterRoot,
+          sdkSpec: environment.sdkSpec ?? process.env.npm_config_package,
+          installDependencies: environment.installDependencies
+        });
+        if (!result.initialized) {
+          write("Video chat is already initialized.");
+          return 0;
+        }
+        write("Video chat initialized with packaged templates and browser voice.");
+        write("Add ANTHROPIC_API_KEY to .env.local.");
+        write("Then run: npm run dev");
+        write("Check setup: npx vanillasky doctor");
+        return 0;
+      } catch (error) {
+        write(error instanceof Error ? error.message : String(error));
+        return 1;
+      }
+    })();
+  }
+  if (rootCommand === "doctor") {
+    const unknown = unknownOption("doctor", rootArgs, []);
+    if (unknown) {
+      write(unknown);
+      return 1;
+    }
+    if (rootArgs.length > 0) {
+      write(`Unexpected doctor argument: ${rootArgs[0]}`);
+      return 1;
+    }
+    const result = doctorVideoChatApp(cwd);
+    for (const line of result.lines) write(line);
+    return result.ok ? 0 : 1;
+  }
+  if (rootCommand !== "templates") {
+    const removed = /* @__PURE__ */ new Set(["list", "describe", "add", "sync", "check", "create"]);
+    if (rootCommand && removed.has(rootCommand)) {
+      write(`Template commands moved. Use: vanillasky templates ${argv.join(" ")}`);
+      return 1;
+    }
+    write(help());
+    return rootCommand == null || rootCommand === "help" || rootCommand === "--help" || rootCommand === "-h" ? 0 : 1;
+  }
+  const [command, ...args] = rootArgs;
+  if (command == null || command === "help" || command === "--help" || command === "-h") {
+    write(templateHelp());
+    return 0;
+  }
   if (command === "create") {
     return (async () => {
       try {
         const unknown = unknownOption("create", args, []);
         if (unknown) throw new Error(unknown);
-        if (args.length === 0) throw new Error("Choose one template id. Usage: vanillasky create <id>.");
+        if (args.length === 0) throw new Error("Choose one template id. Usage: vanillasky templates create <id>.");
         if (args.length > 1) throw new Error(`Unexpected create argument: ${args[1]}`);
         const id = args[0];
         const result = await createTemplate({ cwd, id });
         write(`Created template: ${result.path}`);
         write(`Synced ${result.templates} template${result.templates === 1 ? "" : "s"} to vanillasky/index.ts and vanillasky/server.ts.`);
         write(`Source: ${result.path}`);
-        write("Validate templates: vanillasky check");
+        write("Validate templates: vanillasky templates check");
         for (const warning of result.warnings ?? []) write(`Warning: ${warning}`);
         return 0;
       } catch (error) {
@@ -1593,7 +2001,7 @@ function runVanillaSkyCli(argv, environment = {}) {
     }
     const names = addAll ? listRegistryTemplates().map(({ id }) => id) : positional;
     if (names.length === 0) {
-      write("Choose at least one template. Run `vanillasky list` to see the catalog.");
+      write("Choose at least one template. Run `vanillasky templates list` to see the catalog.");
       return 1;
     }
     return (async () => {
@@ -1649,7 +2057,7 @@ function runVanillaSkyCli(argv, environment = {}) {
     const name = names[0];
     const render = (item2) => {
       if (!item2) {
-        write(`Unknown template: ${name ?? ""}. Run \`vanillasky list\` to see the catalog.`);
+        write(`Unknown template: ${name ?? ""}. Run \`vanillasky templates list\` to see the catalog.`);
         return 1;
       }
       if (args.includes("--json")) {
@@ -1688,8 +2096,8 @@ function runVanillaSkyCli(argv, environment = {}) {
       return 1;
     });
   }
-  write(help());
-  return command == null || command === "help" || command === "--help" || command === "-h" ? 0 : 1;
+  write(templateHelp());
+  return 1;
 }
 
 // src/cli.ts

package/dist/{compose-video-JWIEDTEJ.js → compose-video-PD6LKKRK.js}

@@ -1,10 +1,10 @@
 import {
   createVideo
-} from "./chunk-3OU7HIEB.js";
+} from "./chunk-RE4IMWJR.js";
 import "./chunk-E7CL7UPB.js";
-import "./chunk-FZHMQFG3.js";
-import "./chunk-G66Z5CWR.js";
-import "./chunk-66MNRUCR.js";
+import "./chunk-GAIOHGNR.js";
+import "./chunk-MMUXVA47.js";
+import "./chunk-2PYO6VAC.js";
 import "./chunk-AOWSXU2K.js";
 import "./chunk-3O7OMMMF.js";
 import "./chunk-XGRA2MUV.js";

package/dist/{cta-logo-JJOGK4UC.js → cta-logo-YR7LYUR5.js}

@@ -4,7 +4,7 @@ import {
 import {
   SceneBackground,
   getMediaBackgroundProps
-} from "./chunk-7BGAU6C3.js";
+} from "./chunk-MXZSDGZQ.js";
 import "./chunk-FRN6WKHA.js";
 import "./chunk-W3VDIBGR.js";
 import {

package/dist/{cta-media-IQ3MAWEH.js → cta-media-DQJBKUO2.js}

@@ -5,10 +5,10 @@ import {
 import {
   SceneBackground,
   getMediaBackgroundProps
-} from "./chunk-7BGAU6C3.js";
+} from "./chunk-MXZSDGZQ.js";
 import {
   TemplateText
-} from "./chunk-TCEHK2BW.js";
+} from "./chunk-YJJC4N4D.js";
 import "./chunk-L5BTTCZV.js";
 import "./chunk-FRN6WKHA.js";
 import "./chunk-W3VDIBGR.js";

package/dist/{events-BBP30j3c.d.ts → events-B6qS1Lsb.d.ts}

@@ -1,7 +1,7 @@
-import { b as VideoOrientation, V as VideoStyle, c as Video, a as VideoCapabilities, d as VideoAudio, e as VideoScene, f as VIDEO_PROTOCOL_VERSION } from './types-BV9IqExh.js';
+import { b as VideoOrientation, V as VideoStyle, c as Video, a as VideoCapabilities, d as VideoAudio, e as VideoScene, f as VIDEO_PROTOCOL_VERSION } from './types-2wHBqtg8.js';
 
 type VideoWarningCategory = "validation" | "readability" | "grounding" | "provider" | "media" | "protocol";
-type VideoWarningCode = "scene_duration_adjusted" | "scene_omitted_unreadable" | "scene_omitted_for_closer" | "chart_scale_imbalance" | "plan_incomplete" | "plan_missing_closer" | "provider_warning" | "provider_diagnostics_unavailable";
+type VideoWarningCode = "scene_duration_adjusted" | "scene_omitted_unreadable" | "scene_omitted_for_closer" | "scene_variable_clipped" | "chart_scale_imbalance" | "plan_incomplete" | "plan_missing_closer" | "provider_warning" | "provider_diagnostics_unavailable" | "media_budget_reached";
 /** A bounded, client-safe diagnostic that never includes provider payloads. */
 interface VideoWarning {
     code: VideoWarningCode;

package/dist/{incoming-call-KXF67OT2.js → incoming-call-54KQ7O5A.js}

@@ -5,7 +5,7 @@ import {
 import {
   SceneBackground,
   getMediaBackgroundProps
-} from "./chunk-7BGAU6C3.js";
+} from "./chunk-MXZSDGZQ.js";
 import "./chunk-FRN6WKHA.js";
 import "./chunk-W3VDIBGR.js";
 import {