@a-company/atelier 0.29.0 → 0.37.0

package/dist/cli.cjs

@@ -1443,6 +1443,7 @@ var import_zod11 = require("zod");
 var import_zod12 = require("zod");
 var import_zod13 = require("zod");
 var import_zod14 = require("zod");
+var import_zod15 = require("zod");
 var import_yaml = require("yaml");
 var PixelSchema = import_zod.z.number();
 var PercentageSchema = import_zod.z.string().regex(/^-?\d+(\.\d+)?%$/, {
@@ -1866,6 +1867,121 @@ var AtelierDocumentSchema = import_zod14.z.object({
   layers: import_zod14.z.array(LayerSchema),
   states: import_zod14.z.record(import_zod14.z.string(), StateSchema)
 });
+var SilencePolicySchema = import_zod15.z.object({
+  noise: import_zod15.z.string().optional(),
+  min_silence: import_zod15.z.number().nonnegative().optional(),
+  default_padding_pre: import_zod15.z.number().nonnegative().optional(),
+  default_padding_post: import_zod15.z.number().nonnegative().optional(),
+  match_tolerance: import_zod15.z.number().nonnegative().optional()
+}).strict();
+var CaptionStyleSchema = import_zod15.z.object({
+  font_family: import_zod15.z.string().optional(),
+  font_size: import_zod15.z.number().positive().optional(),
+  font_weight: import_zod15.z.union([import_zod15.z.literal("normal"), import_zod15.z.literal("bold"), import_zod15.z.number()]).optional(),
+  text_align: import_zod15.z.enum(["left", "center", "right"]).optional(),
+  color: import_zod15.z.string().optional(),
+  y_ratio: import_zod15.z.number().min(0).max(1).optional(),
+  width_ratio: import_zod15.z.number().min(0).max(1).optional(),
+  fade_seconds: import_zod15.z.number().nonnegative().optional()
+}).strict();
+var CaptionGroupingSchema = import_zod15.z.object({
+  max_words: import_zod15.z.number().int().positive().optional(),
+  pause_gap: import_zod15.z.number().nonnegative().optional()
+}).strict();
+var OverlayAnchorSchema = import_zod15.z.enum([
+  "top-left",
+  "top-right",
+  "bottom-left",
+  "bottom-right"
+]);
+var OverlayTextStyleSchema = import_zod15.z.object({
+  font_family: import_zod15.z.string().optional(),
+  font_size: import_zod15.z.number().positive().optional(),
+  font_weight: import_zod15.z.union([import_zod15.z.literal("normal"), import_zod15.z.literal("bold"), import_zod15.z.number()]).optional(),
+  color: import_zod15.z.string().optional()
+}).strict();
+function validatePageNumberFormat(format, ctx) {
+  if (format.length === 0) {
+    ctx.addIssue({
+      code: import_zod15.z.ZodIssueCode.custom,
+      message: "format must be a non-empty string"
+    });
+    return;
+  }
+  const open = (format.match(/\{/g) ?? []).length;
+  const close = (format.match(/\}/g) ?? []).length;
+  if (open !== close) {
+    ctx.addIssue({
+      code: import_zod15.z.ZodIssueCode.custom,
+      message: `format has unbalanced braces (${open} '{' vs ${close} '}')`
+    });
+    return;
+  }
+  const groupRe = /\{([^{}]*)\}/g;
+  const groupRule = /^(current|total)(:0\d+d)?$/;
+  let m;
+  let sawCurrent = false;
+  let sawTotal = false;
+  while ((m = groupRe.exec(format)) !== null) {
+    const inner = m[1];
+    if (!groupRule.test(inner)) {
+      ctx.addIssue({
+        code: import_zod15.z.ZodIssueCode.custom,
+        message: `format placeholder "{${inner}}" is not recognized \u2014 expected {current}, {total}, {current:0Nd}, or {total:0Nd}`
+      });
+      return;
+    }
+    if (inner.startsWith("current")) sawCurrent = true;
+    if (inner.startsWith("total")) sawTotal = true;
+  }
+  if (!sawCurrent && !sawTotal) {
+    ctx.addIssue({
+      code: import_zod15.z.ZodIssueCode.custom,
+      message: "format must contain at least one {current} or {total} placeholder"
+    });
+  }
+}
+var OverlayHandleRuleSchema = import_zod15.z.object({
+  text: import_zod15.z.string().min(1),
+  anchor: OverlayAnchorSchema,
+  margin: import_zod15.z.number().nonnegative().optional(),
+  style: OverlayTextStyleSchema.optional()
+}).strict();
+var OverlayPageNumberRuleSchema = import_zod15.z.object({
+  format: import_zod15.z.string().superRefine(validatePageNumberFormat),
+  anchor: OverlayAnchorSchema,
+  margin: import_zod15.z.number().nonnegative().optional(),
+  style: OverlayTextStyleSchema.optional()
+}).strict();
+var OverlayRulesSchema = import_zod15.z.object({
+  handle: OverlayHandleRuleSchema.optional(),
+  page_number: OverlayPageNumberRuleSchema.optional()
+}).strict();
+var StudioRecipeSchema = import_zod15.z.object({
+  version: import_zod15.z.string(),
+  name: import_zod15.z.string(),
+  description: import_zod15.z.string().optional(),
+  author: import_zod15.z.string().optional(),
+  tags: import_zod15.z.array(import_zod15.z.string()).optional(),
+  silence_policy: SilencePolicySchema.optional(),
+  caption_style: CaptionStyleSchema.optional(),
+  caption_grouping: CaptionGroupingSchema.optional(),
+  // Phase 1.5 — first-class overlay rules
+  overlay_rules: OverlayRulesSchema.optional(),
+  // Reserved — Phase 3 (parse-opaque)
+  caption_highlight: import_zod15.z.unknown().optional(),
+  transition_kit: import_zod15.z.unknown().optional(),
+  palette: import_zod15.z.unknown().optional(),
+  audio_policy: import_zod15.z.unknown().optional(),
+  aspect_targets: import_zod15.z.array(import_zod15.z.unknown()).optional()
+}).strict();
+var RESERVED_RECIPE_FIELDS = [
+  "caption_highlight",
+  "transition_kit",
+  "palette",
+  "audio_policy",
+  "aspect_targets"
+];
 function formatErrors(error) {
   return error.issues.map((issue) => ({
     path: issue.path.join(".") || "(root)",
@@ -1908,6 +2024,22 @@ function validateVideoLayer(visual, videoMetaDuration) {
   if (errors.length > 0) return { success: false, errors };
   return { success: true, data: visual };
 }
+function validateRecipe(recipe) {
+  const parsed = StudioRecipeSchema.safeParse(recipe);
+  if (!parsed.success) {
+    return { success: false, errors: formatErrors(parsed.error) };
+  }
+  const warnings = [];
+  const data = parsed.data;
+  for (const field of RESERVED_RECIPE_FIELDS) {
+    if (data[field] !== void 0) {
+      warnings.push(
+        `${field} is reserved for Phase 3 and currently has no effect.`
+      );
+    }
+  }
+  return { success: true, data, ...warnings.length > 0 && { warnings } };
+}
 function parseAtelier(yamlString) {
   let parsed;
   try {
@@ -1920,6 +2052,9 @@ function parseAtelier(yamlString) {
   }
   return validateDocument(parsed);
 }
+function serializeAtelier(doc) {
+  return (0, import_yaml.stringify)(doc, { indent: 2 });
+}
 
 // src/commands/validate.ts
 init_dist2();
@@ -2043,29 +2178,1842 @@ function formatResult(result) {
     for (const err of gate.errors) {
       lines.push(`       ${err}`);
     }
-  }
-  return lines.join("\n");
-}
-function lintCommand(program2) {
-  program2.command("lint <files...>").description(
-    "Lint .atelier files against all gates (^valid-document, ^valid-delta, ^valid-video-layer)"
-  ).option("--json", "Output results as JSON array").action((files, opts) => {
-    const results = files.map(lintFile);
-    if (opts.json) {
-      console.log(JSON.stringify(results, null, 2));
-    } else {
-      for (const result of results) {
-        console.log(formatResult(result));
+  }
+  return lines.join("\n");
+}
+function lintCommand(program2) {
+  program2.command("lint <files...>").description(
+    "Lint .atelier files against all gates (^valid-document, ^valid-delta, ^valid-video-layer)"
+  ).option("--json", "Output results as JSON array").action((files, opts) => {
+    const results = files.map(lintFile);
+    if (opts.json) {
+      console.log(JSON.stringify(results, null, 2));
+    } else {
+      for (const result of results) {
+        console.log(formatResult(result));
+      }
+    }
+    const allValid = results.every((r) => r.valid);
+    if (!allValid) process.exit(1);
+  });
+}
+
+// src/lib/video-project.ts
+var import_node_fs3 = require("fs");
+var import_node_path3 = require("path");
+var VIDEO_PROJECT_VERSION = "1.0";
+var VIDEO_CUTLIST_VERSION = "1.1";
+var VIDEO_TRANSCRIPT_VERSION = "1.1";
+function effectiveSpan(cut, duration) {
+  return {
+    start: Math.max(0, cut.rawStart - cut.paddingPre),
+    end: Math.min(duration, cut.rawEnd + cut.paddingPost)
+  };
+}
+function loadVideoProject(dir) {
+  const projectDir = (0, import_node_path3.resolve)(dir);
+  const possibleExts = [".mp4", ".mov", ".webm", ".mkv", ".avi"];
+  let sourceFilename = "source.mp4";
+  for (const ext of possibleExts) {
+    if ((0, import_node_fs3.existsSync)((0, import_node_path3.join)(projectDir, `source${ext}`))) {
+      sourceFilename = `source${ext}`;
+      break;
+    }
+  }
+  const manifest = {
+    source: sourceFilename,
+    composition: "project.atelier",
+    transcript: "transcript.json",
+    cuts: "cuts.json",
+    exportDir: "export/",
+    createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+    version: VIDEO_PROJECT_VERSION
+  };
+  return {
+    dir: projectDir,
+    sourcePath: (0, import_node_path3.join)(projectDir, sourceFilename),
+    compositionPath: (0, import_node_path3.join)(projectDir, "project.atelier"),
+    transcriptPath: (0, import_node_path3.join)(projectDir, "transcript.json"),
+    cutsPath: (0, import_node_path3.join)(projectDir, "cuts.json"),
+    exportDir: (0, import_node_path3.join)(projectDir, "export"),
+    manifest
+  };
+}
+function readCutList(project) {
+  if (!(0, import_node_fs3.existsSync)(project.cutsPath)) {
+    return { version: VIDEO_CUTLIST_VERSION, source: project.manifest.source, cuts: [] };
+  }
+  const raw = JSON.parse((0, import_node_fs3.readFileSync)(project.cutsPath, "utf-8"));
+  const cuts = raw.cuts.map((entry) => {
+    if ("rawStart" in entry) return entry;
+    return {
+      rawStart: entry.start,
+      rawEnd: entry.end,
+      paddingPre: 0,
+      paddingPost: 0,
+      ...entry.label !== void 0 && { label: entry.label }
+    };
+  });
+  return {
+    version: VIDEO_CUTLIST_VERSION,
+    source: raw.source,
+    cuts
+  };
+}
+function writeCutList(project, cuts) {
+  const payload = { ...cuts, version: VIDEO_CUTLIST_VERSION };
+  (0, import_node_fs3.writeFileSync)(project.cutsPath, JSON.stringify(payload, null, 2), "utf-8");
+}
+function readTranscript(project) {
+  if (!(0, import_node_fs3.existsSync)(project.transcriptPath)) return null;
+  const raw = JSON.parse((0, import_node_fs3.readFileSync)(project.transcriptPath, "utf-8"));
+  const segments = raw.segments.map((seg) => ({
+    text: seg.text,
+    start: seg.start,
+    end: seg.end,
+    words: seg.words.map((w) => {
+      if ("detected" in w) return w;
+      return {
+        detected: w.word,
+        text: w.word,
+        start: w.start,
+        end: w.end,
+        ...w.confidence !== void 0 && { confidence: w.confidence }
+      };
+    })
+  }));
+  return {
+    version: VIDEO_TRANSCRIPT_VERSION,
+    ...raw.language !== void 0 && { language: raw.language },
+    segments
+  };
+}
+function writeTranscript(project, transcript) {
+  const payload = { ...transcript, version: VIDEO_TRANSCRIPT_VERSION };
+  (0, import_node_fs3.writeFileSync)(project.transcriptPath, JSON.stringify(payload, null, 2), "utf-8");
+}
+function readComposition(project) {
+  return JSON.parse((0, import_node_fs3.readFileSync)(project.compositionPath, "utf-8"));
+}
+function writeComposition(project, doc) {
+  (0, import_node_fs3.writeFileSync)(project.compositionPath, JSON.stringify(doc, null, 2), "utf-8");
+}
+function rewriteCutLayers(doc, cuts, sourceFilename, sourceDuration, assetId = "src") {
+  const preserved = doc.layers.filter((l) => !(l.tags ?? []).includes("silence-trim"));
+  const fps = doc.canvas.fps;
+  let cumulativeFrame = 0;
+  const trimLayers = cuts.map((cut, idx) => {
+    const span = effectiveSpan(cut, sourceDuration);
+    const sourceOffsetFrames = Math.floor(span.start * fps) / fps;
+    const sourceEndFrames = Math.ceil(span.end * fps) / fps;
+    const durationFrames = Math.max(1, Math.round((sourceEndFrames - sourceOffsetFrames) * fps));
+    const layer = {
+      id: `clip-trim-${idx}`,
+      tags: ["silence-trim"],
+      visual: {
+        type: "video",
+        assetId,
+        src: sourceFilename,
+        startFrame: cumulativeFrame,
+        sourceOffset: sourceOffsetFrames,
+        sourceEnd: sourceEndFrames,
+        playbackRate: 1,
+        objectFit: "contain"
+      },
+      frame: { x: 0, y: 0 },
+      bounds: { width: doc.canvas.width, height: doc.canvas.height }
+    };
+    cumulativeFrame += durationFrames;
+    return layer;
+  });
+  return { ...doc, layers: [...preserved, ...trimLayers] };
+}
+
+// src/lib/silence-detect.ts
+var import_node_child_process = require("child_process");
+async function probeSilencedetect() {
+  const stdout = await runCapture("ffmpeg", ["-hide_banner", "-filters"]);
+  if (!/\bsilencedetect\b/.test(stdout)) {
+    throw new Error(
+      "Your ffmpeg build lacks the silencedetect filter. Install a standard ffmpeg \u2265 4.0 (brew install ffmpeg / apt install ffmpeg)."
+    );
+  }
+}
+async function probeDuration(sourcePath) {
+  const stdout = await runCapture("ffprobe", [
+    "-v",
+    "error",
+    "-show_entries",
+    "format=duration",
+    "-of",
+    "csv=p=0",
+    sourcePath
+  ]);
+  const n = parseFloat(stdout.trim());
+  if (!Number.isFinite(n) || n <= 0) {
+    throw new Error(`ffprobe returned invalid duration for ${sourcePath}: "${stdout}"`);
+  }
+  return n;
+}
+async function runSilenceDetect(sourcePath, options = {}) {
+  const noise = options.noise ?? "-30dB";
+  const minSilence = options.minSilence ?? 0.35;
+  const filter = `silencedetect=noise=${noise}:d=${minSilence}`;
+  const stderr = await runCaptureStderr("ffmpeg", [
+    "-hide_banner",
+    "-nostats",
+    "-i",
+    sourcePath,
+    "-af",
+    filter,
+    "-f",
+    "null",
+    "-"
+  ]);
+  return parseSilenceDetectStderr(stderr);
+}
+function parseSilenceDetectStderr(stderr) {
+  const intervals = [];
+  const startRe = /silence_start:\s*(-?[\d.]+)/;
+  const endRe = /silence_end:\s*(-?[\d.]+)/;
+  let pendingStart = null;
+  for (const line of stderr.split(/\r?\n/)) {
+    const sm = line.match(startRe);
+    if (sm) {
+      pendingStart = parseFloat(sm[1]);
+      continue;
+    }
+    const em = line.match(endRe);
+    if (em && pendingStart !== null) {
+      const end = parseFloat(em[1]);
+      intervals.push({ start: Math.max(0, pendingStart), end });
+      pendingStart = null;
+    }
+  }
+  return intervals;
+}
+function runCapture(cmd, args) {
+  return new Promise((resolve16, reject) => {
+    const proc = (0, import_node_child_process.spawn)(cmd, args, { stdio: ["ignore", "pipe", "pipe"] });
+    let stdout = "";
+    proc.stdout.on("data", (b) => stdout += b.toString());
+    proc.on("error", (err) => {
+      const e = err;
+      if (e.code === "ENOENT") {
+        reject(new Error(`${cmd} not found on PATH. Install ffmpeg/ffprobe (brew install ffmpeg).`));
+      } else {
+        reject(err);
+      }
+    });
+    proc.on("close", (code) => {
+      if (code !== 0) reject(new Error(`${cmd} exited ${code}`));
+      else resolve16(stdout);
+    });
+  });
+}
+function runCaptureStderr(cmd, args) {
+  return new Promise((resolve16, reject) => {
+    const proc = (0, import_node_child_process.spawn)(cmd, args, { stdio: ["ignore", "ignore", "pipe"] });
+    let stderr = "";
+    proc.stderr.on("data", (b) => stderr += b.toString());
+    proc.on("error", (err) => {
+      const e = err;
+      if (e.code === "ENOENT") {
+        reject(new Error(`${cmd} not found on PATH. Install ffmpeg (brew install ffmpeg).`));
+      } else {
+        reject(err);
+      }
+    });
+    proc.on("close", () => resolve16(stderr));
+  });
+}
+
+// src/lib/cut-model.ts
+var DEFAULT_PADDING_PRE = 0.08;
+var DEFAULT_PADDING_POST = 0.12;
+var DEFAULT_MATCH_TOLERANCE = 0.5;
+function invertToSpeechIntervals(silences, duration) {
+  if (silences.length === 0) {
+    return duration > 0 ? [{ start: 0, end: duration }] : [];
+  }
+  const sorted = [...silences].sort((a, b) => a.start - b.start);
+  const speech = [];
+  if (sorted[0].start > 0) {
+    speech.push({ start: 0, end: sorted[0].start });
+  }
+  for (let i = 0; i < sorted.length - 1; i++) {
+    const gapStart = sorted[i].end;
+    const gapEnd = sorted[i + 1].start;
+    if (gapEnd > gapStart) {
+      speech.push({ start: gapStart, end: gapEnd });
+    }
+  }
+  const last = sorted[sorted.length - 1];
+  if (last.end < duration) {
+    speech.push({ start: last.end, end: duration });
+  }
+  return speech;
+}
+function buildInitialCuts(speech, paddingPre = DEFAULT_PADDING_PRE, paddingPost = DEFAULT_PADDING_POST) {
+  return speech.map((s) => ({
+    rawStart: s.start,
+    rawEnd: s.end,
+    paddingPre,
+    paddingPost
+  }));
+}
+function resolveOverlaps(cuts) {
+  for (let i = 0; i < cuts.length - 1; i++) {
+    const a = cuts[i];
+    const b = cuts[i + 1];
+    const aEnd = a.rawEnd + a.paddingPost;
+    const bStart = b.rawStart - b.paddingPre;
+    if (aEnd > bStart) {
+      const mid = (a.rawEnd + b.rawStart) / 2;
+      a.paddingPost = Math.max(0, mid - a.rawEnd);
+      b.paddingPre = Math.max(0, b.rawStart - mid);
+    }
+  }
+}
+function clampBoundaries(cuts, duration) {
+  if (cuts.length === 0) return;
+  const first = cuts[0];
+  if (first.rawStart - first.paddingPre < 0) {
+    first.paddingPre = first.rawStart;
+  }
+  const last = cuts[cuts.length - 1];
+  if (last.rawEnd + last.paddingPost > duration) {
+    last.paddingPost = Math.max(0, duration - last.rawEnd);
+  }
+}
+function mergeWithExisting(fresh, existing, tolerance = DEFAULT_MATCH_TOLERANCE) {
+  return fresh.map((f) => {
+    const match = existing.find(
+      (e) => Math.abs(e.rawStart - f.rawStart) < tolerance && Math.abs(e.rawEnd - f.rawEnd) < tolerance
+    );
+    if (!match) return f;
+    return {
+      rawStart: f.rawStart,
+      rawEnd: f.rawEnd,
+      paddingPre: match.paddingPre,
+      paddingPost: match.paddingPost,
+      ...match.label !== void 0 && { label: match.label }
+    };
+  });
+}
+function applyGlobalPadding(cuts, deltaSeconds) {
+  for (const cut of cuts) {
+    cut.paddingPre = Math.max(0, cut.paddingPre + deltaSeconds);
+    cut.paddingPost = Math.max(0, cut.paddingPost + deltaSeconds);
+  }
+}
+
+// src/lib/recipe.ts
+var import_node_fs4 = require("fs");
+var import_node_path4 = require("path");
+var import_node_os = require("os");
+var import_yaml2 = require("yaml");
+var RECIPE_VERSION = "1.0";
+function resolveRecipePath(pathOrName, projectDir) {
+  if ((0, import_node_path4.isAbsolute)(pathOrName) || pathOrName.includes("/") || pathOrName.includes("\\")) {
+    return (0, import_node_path4.resolve)(pathOrName);
+  }
+  const candidates = [];
+  const exts = [".recipe.yaml", ".recipe.json", ".yaml", ".yml", ".json"];
+  if (projectDir) {
+    const projectRecipesDir = (0, import_node_path4.join)((0, import_node_path4.resolve)(projectDir), ".atelier", "recipes");
+    for (const ext of exts) candidates.push((0, import_node_path4.join)(projectRecipesDir, `${pathOrName}${ext}`));
+  }
+  const userRecipesDir = (0, import_node_path4.join)((0, import_node_os.homedir)(), ".atelier", "recipes");
+  for (const ext of exts) candidates.push((0, import_node_path4.join)(userRecipesDir, `${pathOrName}${ext}`));
+  for (const candidate of candidates) {
+    if ((0, import_node_fs4.existsSync)(candidate)) return candidate;
+  }
+  throw new Error(
+    `Recipe "${pathOrName}" not found. Looked in:
+${candidates.map((c) => `  ${c}`).join("\n")}`
+  );
+}
+function loadRecipe(pathOrName, projectDir) {
+  const path = resolveRecipePath(pathOrName, projectDir);
+  const raw = (0, import_node_fs4.readFileSync)(path, "utf-8");
+  let parsed;
+  if (path.endsWith(".json")) {
+    parsed = JSON.parse(raw);
+  } else {
+    parsed = (0, import_yaml2.parse)(raw);
+  }
+  const result = validateRecipe(parsed);
+  if (!result.success) {
+    const msg = result.errors.map((e) => `  ${e.path}: ${e.message}`).join("\n");
+    throw new Error(`Invalid recipe at ${path}:
+${msg}`);
+  }
+  return {
+    recipe: result.data,
+    path,
+    warnings: result.warnings ?? []
+  };
+}
+function scaffoldRecipeYaml(name) {
+  return `# Studio Recipe \u2014 ${name}
+# Phase 1 \u2014 manual authoring + apply
+# https://github.com/ascend42/a-atelier/blob/main/.paradigm/specs/studio-recipe.md
+
+version: "${RECIPE_VERSION}"
+name: "${name}"
+description: ""
+author: ""
+tags: []
+
+# \u2500\u2500 Silence-trim policy \u2014 consumed by \`atelier trim\` \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+silence_policy:
+  # silencedetect noise threshold (default: -30dB)
+  noise: "-30dB"
+  # Minimum silence duration to register, in seconds (default: 0.35)
+  min_silence: 0.35
+  # Default leading padding for new cuts, in seconds (default: 0.08)
+  default_padding_pre: 0.08
+  # Default trailing padding for new cuts, in seconds (default: 0.12)
+  default_padding_post: 0.12
+  # Re-detect match tolerance for preserving user padding, in seconds (default: 0.5)
+  match_tolerance: 0.5
+
+# \u2500\u2500 Caption visual style \u2014 consumed by \`atelier transcribe\` \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+caption_style:
+  font_family: "Inter"
+  font_size: 84
+  font_weight: "bold"     # normal | bold | numeric (100..900)
+  text_align: "center"    # left | center | right
+  color: "#FFFFFF"
+  y_ratio: 0.85           # 0=top, 1=bottom
+  width_ratio: 0.9
+  fade_seconds: 0.05
+
+# \u2500\u2500 Caption phrase grouping \u2014 consumed by \`atelier transcribe\` \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+caption_grouping:
+  max_words: 5
+  pause_gap: 0.4
+
+# \u2500\u2500 Overlay rules (Phase 1.5) \u2014 anchored handle + page-number overlays \u2500
+# overlay_rules:
+#   handle:
+#     text: "@username"
+#     anchor: "bottom-left"   # top-left | top-right | bottom-left | bottom-right
+#     margin: 24              # px from anchored edges
+#     style:
+#       font_family: "Inter"
+#       font_size: 36
+#       font_weight: "bold"
+#       color: "#FFFFFF"
+#   page_number:
+#     format: "{current}/{total}"   # supports {current:02d} / {total:02d} zero-pad
+#     anchor: "top-right"
+#     margin: 24
+#     style:
+#       font_family: "Inter"
+#       font_size: 36
+#       font_weight: "normal"
+#       color: "#FFFFFF"
+
+# \u2500\u2500 Phase 3 fields (reserved \u2014 Phase 1 ignores these) \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+# caption_highlight: {}
+# transition_kit: {}
+# palette: {}
+# audio_policy: {}
+# aspect_targets: []
+`;
+}
+function applyRecipeToTrimOptions(recipe, cliOptions) {
+  const policy = recipe?.silence_policy;
+  if (!policy) return cliOptions;
+  return {
+    ...cliOptions,
+    noise: cliOptions.noise ?? policy.noise,
+    minSilence: cliOptions.minSilence ?? policy.min_silence,
+    padPre: cliOptions.padPre ?? policy.default_padding_pre,
+    padPost: cliOptions.padPost ?? policy.default_padding_post,
+    // matchTolerance is recipe-only at this layer (no CLI flag yet)
+    matchTolerance: cliOptions.matchTolerance ?? policy.match_tolerance
+  };
+}
+function applyRecipeToCaptionOptions(recipe) {
+  if (!recipe) return {};
+  const style = recipe.caption_style;
+  const grouping = recipe.caption_grouping;
+  const runtimeStyle = {};
+  if (style) {
+    if (style.font_family !== void 0) runtimeStyle.fontFamily = style.font_family;
+    if (style.font_size !== void 0) runtimeStyle.fontSize = style.font_size;
+    if (style.font_weight !== void 0) runtimeStyle.fontWeight = style.font_weight;
+    if (style.text_align !== void 0) runtimeStyle.textAlign = style.text_align;
+    if (style.color !== void 0) runtimeStyle.color = style.color;
+    if (style.y_ratio !== void 0) runtimeStyle.yRatio = style.y_ratio;
+    if (style.width_ratio !== void 0) runtimeStyle.widthRatio = style.width_ratio;
+    if (style.fade_seconds !== void 0) runtimeStyle.fadeSeconds = style.fade_seconds;
+  }
+  return {
+    ...Object.keys(runtimeStyle).length > 0 && { style: runtimeStyle },
+    ...grouping?.max_words !== void 0 && { maxWords: grouping.max_words },
+    ...grouping?.pause_gap !== void 0 && { pauseGap: grouping.pause_gap }
+  };
+}
+function applyRecipeToTranscribeOptions(recipe, cliOptions) {
+  if (!recipe) return cliOptions;
+  const captionOptions = applyRecipeToCaptionOptions(recipe);
+  return {
+    ...cliOptions,
+    captionOptions
+  };
+}
+function renderRecipeWithDefaults(recipe) {
+  const defaults = {
+    silence_policy: {
+      noise: "-30dB",
+      min_silence: 0.35,
+      default_padding_pre: 0.08,
+      default_padding_post: 0.12,
+      match_tolerance: 0.5
+    },
+    caption_style: {
+      font_family: "Inter",
+      font_size: 84,
+      font_weight: "bold",
+      text_align: "center",
+      color: "#FFFFFF",
+      y_ratio: 0.85,
+      width_ratio: 0.9,
+      fade_seconds: 0.05
+    },
+    caption_grouping: {
+      max_words: 5,
+      pause_gap: 0.4
+    }
+  };
+  return {
+    ...recipe,
+    silence_policy: { ...defaults.silence_policy, ...recipe.silence_policy },
+    caption_style: { ...defaults.caption_style, ...recipe.caption_style },
+    caption_grouping: { ...defaults.caption_grouping, ...recipe.caption_grouping }
+  };
+}
+function recipeToYaml(recipe) {
+  return (0, import_yaml2.stringify)(recipe);
+}
+var DEFAULT_OVERLAY_MARGIN = 24;
+var DEFAULT_OVERLAY_TEXT_STYLE = {
+  fontFamily: "Inter",
+  fontSize: 24,
+  fontWeight: 600,
+  color: "#F5F5F7"
+};
+var HANDLE_LAYER_ID = "overlay-handle";
+var PAGE_NUMBER_LAYER_ID = "overlay-page-number";
+function applyRecipeToOverlay(doc, recipe, ctx) {
+  const preserved = doc.layers.filter((l) => !(l.tags ?? []).includes("overlay"));
+  const overlayLayers = [];
+  const rules = recipe.overlay_rules;
+  if (!rules) {
+    return { ...doc, layers: preserved };
+  }
+  if (rules.handle) {
+    overlayLayers.push(buildHandleLayer(rules.handle, doc.canvas));
+  }
+  if (rules.page_number) {
+    if (ctx?.currentIndex != null && ctx?.totalCount != null) {
+      overlayLayers.push(
+        buildPageNumberLayer(rules.page_number, doc.canvas, ctx.currentIndex, ctx.totalCount)
+      );
+    } else {
+      console.warn(
+        `applyRecipeToOverlay: recipe.overlay_rules.page_number present but currentIndex/totalCount not provided \u2014 skipping page_number layer.`
+      );
+    }
+  }
+  return {
+    ...doc,
+    layers: [...preserved, ...overlayLayers]
+  };
+}
+function buildHandleLayer(rule, canvas) {
+  const margin = rule.margin ?? DEFAULT_OVERLAY_MARGIN;
+  const { frame, anchorPoint } = anchorToFrame(rule.anchor, canvas, margin);
+  return {
+    id: HANDLE_LAYER_ID,
+    tags: ["overlay"],
+    visual: {
+      type: "text",
+      content: rule.text,
+      style: mergeOverlayStyle(rule.style)
+    },
+    frame,
+    bounds: { width: 600, height: 80 },
+    anchorPoint
+  };
+}
+function buildPageNumberLayer(rule, canvas, currentIndex, totalCount) {
+  const margin = rule.margin ?? DEFAULT_OVERLAY_MARGIN;
+  const { frame, anchorPoint } = anchorToFrame(rule.anchor, canvas, margin);
+  return {
+    id: PAGE_NUMBER_LAYER_ID,
+    tags: ["overlay"],
+    visual: {
+      type: "text",
+      content: renderPageNumberFormat(rule.format, currentIndex, totalCount),
+      style: mergeOverlayStyle(rule.style)
+    },
+    frame,
+    bounds: { width: 200, height: 80 },
+    anchorPoint
+  };
+}
+function anchorToFrame(anchor, canvas, margin) {
+  switch (anchor) {
+    case "top-left":
+      return { frame: { x: margin, y: margin }, anchorPoint: { x: 0, y: 0 } };
+    case "top-right":
+      return { frame: { x: canvas.width - margin, y: margin }, anchorPoint: { x: 1, y: 0 } };
+    case "bottom-left":
+      return { frame: { x: margin, y: canvas.height - margin }, anchorPoint: { x: 0, y: 1 } };
+    case "bottom-right":
+      return {
+        frame: { x: canvas.width - margin, y: canvas.height - margin },
+        anchorPoint: { x: 1, y: 1 }
+      };
+  }
+}
+function mergeOverlayStyle(style) {
+  return {
+    fontFamily: style?.font_family ?? DEFAULT_OVERLAY_TEXT_STYLE.fontFamily,
+    fontSize: style?.font_size ?? DEFAULT_OVERLAY_TEXT_STYLE.fontSize,
+    fontWeight: style?.font_weight ?? DEFAULT_OVERLAY_TEXT_STYLE.fontWeight,
+    color: style?.color ?? DEFAULT_OVERLAY_TEXT_STYLE.color
+  };
+}
+function renderPageNumberFormat(format, currentIndex, totalCount) {
+  return format.replace(
+    /\{(current|total)(?::0(\d+)d)?\}/g,
+    (_, name, padWidth) => {
+      const value = name === "current" ? currentIndex : totalCount;
+      const str = String(value);
+      if (padWidth) {
+        const width = parseInt(padWidth, 10);
+        return str.padStart(width, "0");
+      }
+      return str;
+    }
+  );
+}
+
+// src/commands/trim.ts
+async function trimProject(projectDir, options = {}) {
+  const project = loadVideoProject(projectDir);
+  await probeSilencedetect();
+  const duration = await probeDuration(project.sourcePath);
+  const silences = await runSilenceDetect(project.sourcePath, {
+    noise: options.noise,
+    minSilence: options.minSilence
+  });
+  const speech = invertToSpeechIntervals(silences, duration);
+  const padPre = options.padPre ?? DEFAULT_PADDING_PRE;
+  const padPost = options.padPost ?? DEFAULT_PADDING_POST;
+  let cuts = buildInitialCuts(speech, padPre, padPost);
+  if (!options.reset) {
+    const existing = readCutList(project);
+    cuts = mergeWithExisting(cuts, existing.cuts, options.matchTolerance);
+  }
+  if (typeof options.tightenMs === "number") {
+    applyGlobalPadding(cuts, -options.tightenMs / 1e3);
+  }
+  if (typeof options.loosenMs === "number") {
+    applyGlobalPadding(cuts, options.loosenMs / 1e3);
+  }
+  if (typeof options.cutIndex === "number") {
+    if (options.cutIndex < 0 || options.cutIndex >= cuts.length) {
+      throw new Error(
+        `--cut ${options.cutIndex} out of range (have ${cuts.length} cuts)`
+      );
+    }
+    if (options.padPre !== void 0) cuts[options.cutIndex].paddingPre = options.padPre;
+    if (options.padPost !== void 0) cuts[options.cutIndex].paddingPost = options.padPost;
+  }
+  resolveOverlaps(cuts);
+  clampBoundaries(cuts, duration);
+  const result = {
+    projectDir: project.dir,
+    duration,
+    cuts,
+    layerCount: cuts.length
+  };
+  if (options.dryRun) return result;
+  writeCutList(project, {
+    version: "1.1",
+    source: project.manifest.source,
+    cuts
+  });
+  const doc = readComposition(project);
+  const updated = rewriteCutLayers(doc, cuts, project.manifest.source, duration);
+  writeComposition(project, updated);
+  return result;
+}
+function formatResult2(result) {
+  const lines = [];
+  lines.push(`Trimmed ${result.projectDir}`);
+  lines.push(`  source duration:  ${result.duration.toFixed(2)}s`);
+  lines.push(`  cuts:             ${result.cuts.length}`);
+  for (let i = 0; i < result.cuts.length; i++) {
+    const c = result.cuts[i];
+    const effStart = Math.max(0, c.rawStart - c.paddingPre);
+    const effEnd = Math.min(result.duration, c.rawEnd + c.paddingPost);
+    const dur = effEnd - effStart;
+    lines.push(
+      `    [${i}] ${effStart.toFixed(2)}s \u2192 ${effEnd.toFixed(2)}s (${dur.toFixed(2)}s, pad ${c.paddingPre.toFixed(2)}/${c.paddingPost.toFixed(2)})` + (c.label ? `  "${c.label}"` : "")
+    );
+  }
+  return lines.join("\n");
+}
+function trimCommand(program2) {
+  program2.command("trim <project>").description(
+    "Detect silence and rewrite project.atelier with parametric cuts (silence-trim tagged layers). Preserves user padding overrides on re-run."
+  ).option("--noise <dB>", "Silence threshold (default: -30dB)", "-30dB").option(
+    "--min-silence <seconds>",
+    "Minimum silence duration to register (default: 0.35)",
+    (v) => parseFloat(v),
+    0.35
+  ).option(
+    "--pad-pre <seconds>",
+    `Default leading padding (default: ${DEFAULT_PADDING_PRE})`,
+    (v) => parseFloat(v)
+  ).option(
+    "--pad-post <seconds>",
+    `Default trailing padding (default: ${DEFAULT_PADDING_POST})`,
+    (v) => parseFloat(v)
+  ).option("--tighten <ms>", "Reduce all current padding by N ms", (v) => parseInt(v, 10)).option("--loosen <ms>", "Increase all current padding by N ms", (v) => parseInt(v, 10)).option(
+    "--cut <index>",
+    "Apply --pad-pre / --pad-post to one specific cut only",
+    (v) => parseInt(v, 10)
+  ).option("--reset", "Discard existing padding; re-detect from scratch").option("--recipe <name>", "Apply a Studio Recipe's silence_policy as the baseline").option("--dry-run", "Print computed cuts; don't write files").option("--json", "Output result as JSON for piping").action(async (project, opts) => {
+    try {
+      let trimOpts = {
+        noise: opts.noise,
+        minSilence: opts.minSilence,
+        padPre: opts.padPre,
+        padPost: opts.padPost,
+        tightenMs: opts.tighten,
+        loosenMs: opts.loosen,
+        cutIndex: opts.cut,
+        reset: opts.reset,
+        dryRun: opts.dryRun
+      };
+      if (opts.recipe) {
+        const { recipe } = loadRecipe(opts.recipe, project);
+        trimOpts = applyRecipeToTrimOptions(recipe, trimOpts);
+      }
+      const result = await trimProject(project, trimOpts);
+      if (opts.json) {
+        console.log(JSON.stringify(result, null, 2));
+      } else {
+        console.log(formatResult2(result));
+        if (opts.dryRun) console.log("(dry-run \u2014 no files written)");
+      }
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      console.error(`atelier trim: ${msg}`);
+      process.exit(1);
+    }
+  });
+}
+
+// src/lib/whisper.ts
+var import_node_child_process2 = require("child_process");
+var import_node_fs5 = require("fs");
+async function probeWhisper() {
+  if (await commandExists("whisper-cli")) return "whisper-cpp";
+  if (process.env.OPENAI_API_KEY) return "openai-api";
+  return "none";
+}
+async function runWhisperCpp(sourcePath, options = {}) {
+  const model = options.modelPath ?? options.model ?? "base.en";
+  const args = [
+    sourcePath,
+    "--model",
+    model,
+    "--output-json",
+    "--word-thold",
+    "0.01",
+    // emit word-level timestamps
+    "--print-progress",
+    "false"
+  ];
+  if (options.language) {
+    args.push("--language", options.language);
+  }
+  return runCaptureStdout("whisper-cli", args);
+}
+function parseWhisperCppJson(jsonStr) {
+  const raw = JSON.parse(jsonStr);
+  const segments = (raw.transcription ?? []).map((seg) => {
+    const segStart = (seg.offsets?.from ?? 0) / 1e3;
+    const segEnd = (seg.offsets?.to ?? 0) / 1e3;
+    const segText = seg.text.trim();
+    let words;
+    if (seg.tokens && seg.tokens.length > 0) {
+      words = seg.tokens.filter((t) => t.text.trim().length > 0 && !t.text.startsWith("[_")).map((t) => ({
+        detected: t.text.trim(),
+        text: t.text.trim(),
+        start: (t.offsets?.from ?? segStart * 1e3) / 1e3,
+        end: (t.offsets?.to ?? segEnd * 1e3) / 1e3,
+        ...t.p !== void 0 && { confidence: t.p }
+      }));
+    } else {
+      const tokens = segText.split(/\s+/).filter((t) => t.length > 0);
+      const span = segEnd - segStart;
+      const per = tokens.length > 0 ? span / tokens.length : 0;
+      words = tokens.map((tok, i) => ({
+        detected: tok,
+        text: tok,
+        start: segStart + i * per,
+        end: segStart + (i + 1) * per
+      }));
+    }
+    return {
+      text: segText,
+      start: segStart,
+      end: segEnd,
+      words
+    };
+  });
+  return {
+    version: "1.1",
+    ...raw.result?.language !== void 0 && { language: raw.result.language },
+    segments
+  };
+}
+async function commandExists(name) {
+  if (name.startsWith("/") || name.match(/^[A-Z]:\\/)) {
+    return (0, import_node_fs5.existsSync)(name);
+  }
+  return new Promise((resolve16) => {
+    const probe = (0, import_node_child_process2.spawn)(process.platform === "win32" ? "where" : "which", [name], {
+      stdio: ["ignore", "ignore", "ignore"]
+    });
+    probe.on("error", () => resolve16(false));
+    probe.on("close", (code) => resolve16(code === 0));
+  });
+}
+function runCaptureStdout(cmd, args) {
+  return new Promise((resolve16, reject) => {
+    const proc = (0, import_node_child_process2.spawn)(cmd, args, { stdio: ["ignore", "pipe", "pipe"] });
+    let stdout = "";
+    let stderr = "";
+    proc.stdout.on("data", (b) => stdout += b.toString());
+    proc.stderr.on("data", (b) => stderr += b.toString());
+    proc.on("error", (err) => {
+      const e = err;
+      if (e.code === "ENOENT") {
+        reject(new Error(
+          `${cmd} not found on PATH. Install whisper.cpp (brew install whisper-cpp) or run \`pnpm add @xenova/transformers\` for the ONNX fallback.`
+        ));
+      } else {
+        reject(err);
+      }
+    });
+    proc.on("close", (code) => {
+      if (code !== 0) {
+        reject(new Error(`${cmd} exited ${code}
+${stderr}`));
+      } else {
+        resolve16(stdout);
+      }
+    });
+  });
+}
+
+// src/lib/transcript-model.ts
+var DEFAULT_TRANSCRIPT_MATCH_TOLERANCE = 0.3;
+var DEFAULT_PHRASE_MAX_WORDS = 5;
+var DEFAULT_PHRASE_PAUSE_GAP_SECONDS = 0.4;
+var END_PUNCT = /[.!?,;:]\s*$/;
+function flattenWords(transcript) {
+  return transcript.segments.flatMap((s) => s.words);
+}
+function groupIntoPhrases(transcript, options = {}) {
+  const maxWords = options.maxWords ?? DEFAULT_PHRASE_MAX_WORDS;
+  const pauseGap = options.pauseGap ?? DEFAULT_PHRASE_PAUSE_GAP_SECONDS;
+  const phrases = [];
+  const visibleWords = flattenWords(transcript).filter((w) => !w.hidden);
+  let current = [];
+  for (let i = 0; i < visibleWords.length; i++) {
+    const w = visibleWords[i];
+    current.push(w);
+    const next = visibleWords[i + 1];
+    const gap = next ? next.start - w.end : 0;
+    const endsOnPunct = END_PUNCT.test(w.text);
+    const atMax = current.length >= maxWords;
+    if (!next || atMax || endsOnPunct || gap > pauseGap) {
+      phrases.push({
+        start: current[0].start,
+        end: current[current.length - 1].end,
+        text: current.map((c) => c.text).join(" "),
+        words: current
+      });
+      current = [];
+    }
+  }
+  return phrases;
+}
+function mergeTranscriptWithExisting(fresh, existing, tolerance = DEFAULT_TRANSCRIPT_MATCH_TOLERANCE) {
+  const existingWords = flattenWords(existing);
+  const merged = {
+    version: "1.1",
+    ...fresh.language !== void 0 && { language: fresh.language },
+    segments: fresh.segments.map((seg) => ({
+      text: seg.text,
+      start: seg.start,
+      end: seg.end,
+      words: seg.words.map((freshWord) => {
+        const match = existingWords.find(
+          (e) => !e.userAdded && Math.abs(e.start - freshWord.start) < tolerance && e.detected === freshWord.detected
+        );
+        if (!match) return freshWord;
+        return {
+          detected: freshWord.detected,
+          text: match.text,
+          start: freshWord.start,
+          end: freshWord.end,
+          ...freshWord.confidence !== void 0 && { confidence: freshWord.confidence },
+          ...match.userEdited && { userEdited: true },
+          ...match.hidden && { hidden: true }
+        };
+      })
+    }))
+  };
+  const orphans = existingWords.filter((w) => w.userAdded);
+  for (const orphan of orphans) {
+    const segIdx = merged.segments.findIndex(
+      (s) => orphan.start >= s.start && orphan.start <= s.end
+    );
+    const targetSeg = segIdx >= 0 ? merged.segments[segIdx] : merged.segments[merged.segments.length - 1];
+    if (!targetSeg) continue;
+    const insertIdx = targetSeg.words.findIndex((w) => w.start > orphan.start);
+    if (insertIdx === -1) targetSeg.words.push(orphan);
+    else targetSeg.words.splice(insertIdx, 0, orphan);
+  }
+  return merged;
+}
+function applyTextEdit(transcript, wordIndex, newText) {
+  return mapWord(transcript, wordIndex, (w) => ({
+    ...w,
+    text: newText,
+    userEdited: true
+  }));
+}
+function applyBatchReplace(transcript, find, replace) {
+  return {
+    ...transcript,
+    segments: transcript.segments.map((seg) => ({
+      ...seg,
+      words: seg.words.map(
+        (w) => w.detected === find ? { ...w, text: replace, userEdited: true } : w
+      )
+    }))
+  };
+}
+function applyHide(transcript, wordIndex) {
+  return mapWord(transcript, wordIndex, (w) => ({ ...w, hidden: true }));
+}
+function applyAdd(transcript, afterIndex, text, duration = 0.15) {
+  const flat = flattenWords(transcript);
+  if (afterIndex < 0 || afterIndex >= flat.length) {
+    throw new Error(`afterIndex ${afterIndex} out of range (have ${flat.length} words)`);
+  }
+  const anchor = flat[afterIndex];
+  const newWord = {
+    detected: text,
+    text,
+    start: anchor.end,
+    end: anchor.end + duration,
+    userAdded: true
+  };
+  let cursor = 0;
+  return {
+    ...transcript,
+    segments: transcript.segments.map((seg) => {
+      const segStart = cursor;
+      cursor += seg.words.length;
+      if (afterIndex < segStart || afterIndex >= cursor) return seg;
+      const localIdx = afterIndex - segStart;
+      return {
+        ...seg,
+        words: [...seg.words.slice(0, localIdx + 1), newWord, ...seg.words.slice(localIdx + 1)]
+      };
+    })
+  };
+}
+function applyMerge(transcript, firstIndex) {
+  const flat = flattenWords(transcript);
+  if (firstIndex < 0 || firstIndex >= flat.length - 1) {
+    throw new Error(`firstIndex ${firstIndex} out of range for merge`);
+  }
+  const a = flat[firstIndex];
+  const b = flat[firstIndex + 1];
+  const mergedWord = {
+    detected: a.detected + b.detected,
+    text: a.text + b.text,
+    start: a.start,
+    end: b.end,
+    userEdited: true
+  };
+  let cursor = 0;
+  return {
+    ...transcript,
+    segments: transcript.segments.map((seg) => {
+      const segStart = cursor;
+      cursor += seg.words.length;
+      if (firstIndex < segStart || firstIndex >= cursor - 1) return seg;
+      const localIdx = firstIndex - segStart;
+      return {
+        ...seg,
+        words: [...seg.words.slice(0, localIdx), mergedWord, ...seg.words.slice(localIdx + 2)]
+      };
+    })
+  };
+}
+function applySplit(transcript, wordIndex, fraction, firstText, secondText) {
+  if (fraction <= 0 || fraction >= 1) {
+    throw new Error(`split fraction must be in (0, 1), got ${fraction}`);
+  }
+  const flat = flattenWords(transcript);
+  if (wordIndex < 0 || wordIndex >= flat.length) {
+    throw new Error(`wordIndex ${wordIndex} out of range`);
+  }
+  const w = flat[wordIndex];
+  const splitTime = w.start + (w.end - w.start) * fraction;
+  const cutChar = Math.max(1, Math.floor(w.text.length * fraction));
+  const first = {
+    detected: w.detected,
+    text: firstText ?? w.text.slice(0, cutChar),
+    start: w.start,
+    end: splitTime,
+    userEdited: true
+  };
+  const second = {
+    detected: w.detected,
+    text: secondText ?? w.text.slice(cutChar),
+    start: splitTime,
+    end: w.end,
+    userEdited: true
+  };
+  let cursor = 0;
+  return {
+    ...transcript,
+    segments: transcript.segments.map((seg) => {
+      const segStart = cursor;
+      cursor += seg.words.length;
+      if (wordIndex < segStart || wordIndex >= cursor) return seg;
+      const localIdx = wordIndex - segStart;
+      return {
+        ...seg,
+        words: [...seg.words.slice(0, localIdx), first, second, ...seg.words.slice(localIdx + 1)]
+      };
+    })
+  };
+}
+function mapWord(transcript, wordIndex, fn) {
+  const flat = flattenWords(transcript);
+  if (wordIndex < 0 || wordIndex >= flat.length) {
+    throw new Error(`wordIndex ${wordIndex} out of range (have ${flat.length} words)`);
+  }
+  let cursor = 0;
+  return {
+    ...transcript,
+    segments: transcript.segments.map((seg) => {
+      const segStart = cursor;
+      cursor += seg.words.length;
+      if (wordIndex < segStart || wordIndex >= cursor) return seg;
+      const localIdx = wordIndex - segStart;
+      return {
+        ...seg,
+        words: seg.words.map((w, i) => i === localIdx ? fn(w) : w)
+      };
+    })
+  };
+}
+
+// src/lib/caption-builder.ts
+var DEFAULT_STYLE = {
+  fontFamily: "Inter",
+  fontSize: 84,
+  fontWeight: "bold",
+  textAlign: "center",
+  color: "#FFFFFF",
+  yRatio: 0.85,
+  widthRatio: 0.9,
+  fadeSeconds: 0.05
+};
+function buildCaptionLayers(transcript, canvas, options = {}) {
+  const style = { ...DEFAULT_STYLE, ...options.style };
+  const phrases = groupIntoPhrases(transcript, {
+    maxWords: options.maxWords,
+    pauseGap: options.pauseGap
+  });
+  const layers = [];
+  const deltas = [];
+  const fps = canvas.fps;
+  phrases.forEach((phrase, idx) => {
+    const layerId = `caption-${idx}`;
+    layers.push(buildPhraseLayer(layerId, phrase, canvas, style));
+    deltas.push(...buildPhraseDeltas(layerId, phrase, style.fadeSeconds, fps));
+  });
+  return { layers, deltas };
+}
+function rewriteCaptionLayers(doc, transcript, options = {}) {
+  const preserved = doc.layers.filter((l) => !(l.tags ?? []).includes("caption"));
+  const { layers: captionLayers, deltas: captionDeltas } = buildCaptionLayers(
+    transcript,
+    doc.canvas,
+    options
+  );
+  const captionLayerIds = new Set(captionLayers.map((l) => l.id));
+  const stateNames = Object.keys(doc.states);
+  const targetStateName = stateNames.includes("default") ? "default" : stateNames[0];
+  const states = { ...doc.states };
+  if (targetStateName && states[targetStateName]) {
+    const existing = states[targetStateName];
+    const preservedDeltas = existing.deltas.filter(
+      (d) => !captionLayerIds.has(d.layer)
+    );
+    states[targetStateName] = {
+      ...existing,
+      deltas: [...preservedDeltas, ...captionDeltas]
+    };
+  }
+  return {
+    ...doc,
+    layers: [...preserved, ...captionLayers],
+    states
+  };
+}
+function buildPhraseLayer(id, phrase, canvas, style) {
+  return {
+    id,
+    tags: ["caption"],
+    visual: {
+      type: "text",
+      content: phrase.text,
+      style: {
+        fontFamily: style.fontFamily,
+        fontSize: style.fontSize,
+        fontWeight: style.fontWeight,
+        textAlign: style.textAlign,
+        color: style.color
+      }
+    },
+    frame: {
+      x: canvas.width / 2,
+      y: canvas.height * style.yRatio
+    },
+    bounds: {
+      width: canvas.width * style.widthRatio,
+      height: Math.max(120, style.fontSize * 1.6)
+    },
+    anchorPoint: { x: 0.5, y: 0.5 },
+    opacity: 0
+  };
+}
+function buildPhraseDeltas(layerId, phrase, fadeSeconds, fps) {
+  const fadeFrames = Math.max(1, Math.round(fadeSeconds * fps));
+  const startFrame = Math.floor(phrase.start * fps);
+  const endFrame = Math.ceil(phrase.end * fps);
+  const fadeOutStart = Math.max(startFrame + 1, endFrame - fadeFrames);
+  return [
+    // Fade in to visible at phrase start
+    {
+      layer: layerId,
+      property: "opacity",
+      range: [Math.max(0, startFrame - fadeFrames), startFrame],
+      from: 0,
+      to: 1,
+      easing: "ease-out"
+    },
+    // Hold visible through the phrase
+    // (no explicit delta needed — value persists between deltas)
+    // Fade out at phrase end
+    {
+      layer: layerId,
+      property: "opacity",
+      range: [fadeOutStart, endFrame],
+      from: 1,
+      to: 0,
+      easing: "ease-in"
+    }
+  ];
+}
+
+// src/commands/transcribe.ts
+async function transcribeProject(projectDir, options = {}) {
+  const project = loadVideoProject(projectDir);
+  const backend = await probeWhisper();
+  if (backend === "none") {
+    throw new Error(
+      "No Whisper backend available. Install whisper.cpp (brew install whisper-cpp) or set OPENAI_API_KEY and pass --use-api."
+    );
+  }
+  if (backend === "openai-api") {
+    throw new Error(
+      "OpenAI API backend is not yet implemented. Install whisper.cpp for local transcription."
+    );
+  }
+  const rawJson = await runWhisperCpp(project.sourcePath, {
+    model: options.model,
+    language: options.language
+  });
+  let transcript = parseWhisperCppJson(rawJson);
+  if (!options.reset) {
+    const existing = readTranscript(project);
+    if (existing) {
+      transcript = mergeTranscriptWithExisting(transcript, existing);
+    }
+  }
+  const wordCount = transcript.segments.reduce((n, s) => n + s.words.length, 0);
+  const result = {
+    projectDir: project.dir,
+    backend,
+    transcript,
+    wordCount,
+    captionsGenerated: false
+  };
+  if (options.dryRun) return result;
+  writeTranscript(project, transcript);
+  if (!options.noCaptions) {
+    const doc = readComposition(project);
+    const updated = rewriteCaptionLayers(doc, transcript, options.captionOptions);
+    writeComposition(project, updated);
+    result.captionsGenerated = true;
+  }
+  return result;
+}
+function formatResult3(result) {
+  const lines = [];
+  lines.push(`Transcribed ${result.projectDir} via ${result.backend}`);
+  if (result.transcript.language) {
+    lines.push(`  language:  ${result.transcript.language}`);
+  }
+  lines.push(`  segments:  ${result.transcript.segments.length}`);
+  lines.push(`  words:     ${result.wordCount}`);
+  if (result.captionsGenerated) {
+    lines.push(`  captions:  written to project.atelier`);
+  } else {
+    lines.push(`  captions:  skipped`);
+  }
+  return lines.join("\n");
+}
+function transcribeCommand(program2) {
+  program2.command("transcribe <project>").description(
+    "Transcribe source video via Whisper, write transcript.json, and rewrite caption-tagged TextVisual layers in project.atelier. Preserves user transcript edits on re-run."
+  ).option("--model <name>", "Whisper model: tiny|base|small|medium|large-v3", "base.en").option("--language <code>", "BCP-47 language hint (omit for autodetect)").option("--reset", "Discard existing user edits; full fresh transcript").option("--no-captions", "Write transcript.json only; skip caption layer generation").option("--recipe <name>", "Apply a Studio Recipe's caption_style + caption_grouping").option("--dry-run", "Print transcript; don't write files").option("--json", "Output result as JSON for piping").action(async (project, opts) => {
+    try {
+      let transcribeOpts = {
+        model: opts.model,
+        language: opts.language,
+        reset: opts.reset,
+        noCaptions: !opts.captions,
+        dryRun: opts.dryRun
+      };
+      if (opts.recipe) {
+        const { recipe } = loadRecipe(opts.recipe, project);
+        transcribeOpts = applyRecipeToTranscribeOptions(recipe, transcribeOpts);
+      }
+      const result = await transcribeProject(project, transcribeOpts);
+      if (opts.json) {
+        console.log(JSON.stringify(result, null, 2));
+      } else {
+        console.log(formatResult3(result));
+        if (opts.dryRun) console.log("(dry-run \u2014 no files written)");
+      }
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      console.error(`atelier transcribe: ${msg}`);
+      process.exit(1);
+    }
+  });
+}
+
+// src/commands/transcript.ts
+function loadOrThrow(projectDir) {
+  const project = loadVideoProject(projectDir);
+  const transcript = readTranscript(project);
+  if (!transcript) {
+    throw new Error(
+      `No transcript.json in ${projectDir}. Run \`atelier transcribe ${projectDir}\` first.`
+    );
+  }
+  return { project, transcript };
+}
+function save(project, transcript, noRegenerate) {
+  writeTranscript(project, transcript);
+  if (!noRegenerate) {
+    const doc = readComposition(project);
+    const updated = rewriteCaptionLayers(doc, transcript);
+    writeComposition(project, updated);
+  }
+}
+function transcriptCommand(program2) {
+  const transcript = program2.command("transcript").description("Edit transcript.json \u2014 fix, add, delete, merge, split, list");
+  transcript.command("fix <project>").description("Apply text correction(s). Use --replace 'wrong=right' for batch, or --word <idx> --text '<correction>' for single edit.").option("--replace <pair...>", "Batch find/replace, format: 'detected=replacement' (repeatable)").option("--word <index>", "Single-word edit by index", (v) => parseInt(v, 10)).option("--text <text>", "Correction text (paired with --word)").option("--no-regenerate", "Skip caption layer regeneration after edit").action(async (projectDir, opts) => {
+    try {
+      const { project, transcript: transcript2 } = loadOrThrow(projectDir);
+      let updated = transcript2;
+      if (opts.replace?.length) {
+        for (const pair of opts.replace) {
+          const [find, repl] = pair.split("=");
+          if (!find || repl === void 0) {
+            throw new Error(`Invalid --replace pair: "${pair}". Use 'detected=replacement'.`);
+          }
+          updated = applyBatchReplace(updated, find, repl);
+        }
+      }
+      if (typeof opts.word === "number") {
+        if (opts.text === void 0) {
+          throw new Error("--word requires --text <correction>");
+        }
+        updated = applyTextEdit(updated, opts.word, opts.text);
+      }
+      if (!opts.replace?.length && opts.word === void 0) {
+        throw new Error("Provide --replace 'wrong=right' or --word <idx> --text '...'");
+      }
+      save(project, updated, !opts.regenerate);
+      console.log(`Updated transcript in ${project.dir}`);
+    } catch (err) {
+      console.error(`atelier transcript fix: ${err instanceof Error ? err.message : err}`);
+      process.exit(1);
+    }
+  });
+  transcript.command("add <project>").description("Insert a user-added word after the anchor word.").requiredOption("--after-word <index>", "Anchor word index", (v) => parseInt(v, 10)).requiredOption("--text <text>", "Text of the new word").option("--duration <seconds>", "Word duration in seconds (default: 0.15)", (v) => parseFloat(v), 0.15).option("--no-regenerate", "Skip caption layer regeneration").action(async (projectDir, opts) => {
+    try {
+      const { project, transcript: transcript2 } = loadOrThrow(projectDir);
+      const updated = applyAdd(transcript2, opts.afterWord, opts.text, opts.duration);
+      save(project, updated, !opts.regenerate);
+      console.log(`Inserted "${opts.text}" after word ${opts.afterWord} in ${project.dir}`);
+    } catch (err) {
+      console.error(`atelier transcript add: ${err instanceof Error ? err.message : err}`);
+      process.exit(1);
+    }
+  });
+  transcript.command("delete <project>").description("Hide a word (excluded from captions, kept in transcript).").requiredOption("--word <index>", "Word index", (v) => parseInt(v, 10)).option("--no-regenerate", "Skip caption layer regeneration").action(async (projectDir, opts) => {
+    try {
+      const { project, transcript: transcript2 } = loadOrThrow(projectDir);
+      const updated = applyHide(transcript2, opts.word);
+      save(project, updated, !opts.regenerate);
+      console.log(`Hidden word ${opts.word} in ${project.dir}`);
+    } catch (err) {
+      console.error(`atelier transcript delete: ${err instanceof Error ? err.message : err}`);
+      process.exit(1);
+    }
+  });
+  transcript.command("merge <project>").description("Merge two adjacent words at indices i and i+1.").requiredOption("--word <index>", "First of the two words to merge", (v) => parseInt(v, 10)).option("--no-regenerate", "Skip caption layer regeneration").action(async (projectDir, opts) => {
+    try {
+      const { project, transcript: transcript2 } = loadOrThrow(projectDir);
+      const updated = applyMerge(transcript2, opts.word);
+      save(project, updated, !opts.regenerate);
+      console.log(`Merged words ${opts.word} and ${opts.word + 1} in ${project.dir}`);
+    } catch (err) {
+      console.error(`atelier transcript merge: ${err instanceof Error ? err.message : err}`);
+      process.exit(1);
+    }
+  });
+  transcript.command("split <project>").description("Split one word at a fractional point.").requiredOption("--word <index>", "Word to split", (v) => parseInt(v, 10)).requiredOption("--at <fraction>", "Split point (0\u20131)", (v) => parseFloat(v)).option("--first <text>", "Override text for first half").option("--second <text>", "Override text for second half").option("--no-regenerate", "Skip caption layer regeneration").action(async (projectDir, opts) => {
+    try {
+      const { project, transcript: transcript2 } = loadOrThrow(projectDir);
+      const updated = applySplit(transcript2, opts.word, opts.at, opts.first, opts.second);
+      save(project, updated, !opts.regenerate);
+      console.log(`Split word ${opts.word} at ${opts.at} in ${project.dir}`);
+    } catch (err) {
+      console.error(`atelier transcript split: ${err instanceof Error ? err.message : err}`);
+      process.exit(1);
+    }
+  });
+  transcript.command("list <project>").description("Print all words with their indices for reference.").option("--json", "Output as JSON").action(async (projectDir, opts) => {
+    try {
+      const { transcript: transcript2 } = loadOrThrow(projectDir);
+      const words = flattenWords(transcript2);
+      if (opts.json) {
+        console.log(JSON.stringify(words.map((w, i) => ({ index: i, ...w })), null, 2));
+      } else {
+        for (let i = 0; i < words.length; i++) {
+          const w = words[i];
+          const flags = [];
+          if (w.userEdited) flags.push("edited");
+          if (w.userAdded) flags.push("added");
+          if (w.hidden) flags.push("hidden");
+          const flagStr = flags.length ? ` [${flags.join(", ")}]` : "";
+          const editedDisplay = w.text !== w.detected ? ` \u2190 "${w.detected}"` : "";
+          console.log(
+            `  [${i.toString().padStart(4)}]  ${w.start.toFixed(2).padStart(7)}s  "${w.text}"${editedDisplay}${flagStr}`
+          );
+        }
+      }
+    } catch (err) {
+      console.error(`atelier transcript list: ${err instanceof Error ? err.message : err}`);
+      process.exit(1);
+    }
+  });
+}
+
+// src/commands/captions.ts
+function captionsCommand(program2) {
+  const captions = program2.command("captions").description("Manage caption layers in a VideoProject");
+  captions.command("regenerate <project>").description(
+    "Re-derive caption-tagged TextVisual layers from the current transcript.json. Used when caption styling changes without re-running Whisper."
+  ).option("--recipe <name>", "Apply a Studio Recipe's caption_style + caption_grouping").action(async (projectDir, opts) => {
+    try {
+      const project = loadVideoProject(projectDir);
+      const transcript = readTranscript(project);
+      if (!transcript) {
+        throw new Error(
+          `No transcript.json in ${projectDir}. Run \`atelier transcribe ${projectDir}\` first.`
+        );
+      }
+      const captionOptions = opts.recipe ? applyRecipeToCaptionOptions(loadRecipe(opts.recipe, projectDir).recipe) : {};
+      const doc = readComposition(project);
+      const updated = rewriteCaptionLayers(doc, transcript, captionOptions);
+      writeComposition(project, updated);
+      const captionLayers = updated.layers.filter(
+        (l) => (l.tags ?? []).includes("caption")
+      );
+      console.log(
+        `Regenerated ${captionLayers.length} caption layer${captionLayers.length === 1 ? "" : "s"} in ${project.dir}`
+      );
+    } catch (err) {
+      console.error(`atelier captions regenerate: ${err instanceof Error ? err.message : err}`);
+      process.exit(1);
+    }
+  });
+}
+
+// src/commands/recipe.ts
+var import_node_fs6 = require("fs");
+var import_node_path5 = require("path");
+function recipeCommand(program2) {
+  const recipe = program2.command("recipe").description("Manage Studio Recipes \u2014 reusable style presets");
+  recipe.command("new <name>").description("Scaffold a starter recipe YAML with all current defaults filled in").option("--dir <path>", "Where to write the recipe (default: ./.atelier/recipes/)").action((name, opts) => {
+    try {
+      const baseDir = opts.dir ?? (0, import_node_path5.join)((0, import_node_path5.resolve)(process.cwd()), ".atelier", "recipes");
+      if (!(0, import_node_fs6.existsSync)(baseDir)) {
+        (0, import_node_fs6.mkdirSync)(baseDir, { recursive: true });
+      }
+      const hasKnownExt = /\.(recipe\.yaml|recipe\.json|yaml|yml|json)$/i.test(name);
+      const fileName = hasKnownExt ? name : `${name}.recipe.yaml`;
+      const outPath = (0, import_node_path5.join)(baseDir, fileName);
+      if ((0, import_node_fs6.existsSync)(outPath)) {
+        throw new Error(`Recipe already exists at ${outPath} \u2014 refusing to overwrite.`);
+      }
+      const recipeName = name.replace(/\.(recipe\.yaml|recipe\.json|yaml|yml|json)$/i, "");
+      const yaml = scaffoldRecipeYaml(recipeName);
+      (0, import_node_fs6.writeFileSync)(outPath, yaml, "utf-8");
+      console.log(`Created ${outPath}`);
+    } catch (err) {
+      console.error(`atelier recipe new: ${err instanceof Error ? err.message : err}`);
+      process.exit(1);
+    }
+  });
+  recipe.command("validate <path>").description("Validate a recipe against the schema (^valid-recipe gate). Warns on reserved Phase 3 fields.").option("--json", "Output result as JSON").action((path, opts) => {
+    try {
+      const loaded = loadRecipe(path, process.cwd());
+      if (opts.json) {
+        console.log(JSON.stringify({
+          valid: true,
+          path: loaded.path,
+          warnings: loaded.warnings
+        }, null, 2));
+      } else {
+        console.log(`PASS  ${loaded.path}`);
+        for (const w of loaded.warnings) {
+          console.log(`  \u26A0  ${w}`);
+        }
+      }
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      if (opts.json) {
+        console.log(JSON.stringify({ valid: false, error: msg }, null, 2));
+      } else {
+        console.error(`FAIL  ${path}`);
+        console.error(`  ${msg}`);
+      }
+      process.exit(1);
+    }
+  });
+  recipe.command("show <path>").description("Print a recipe; --with-defaults fills in every omitted field with its code default.").option("--with-defaults", "Overlay code defaults onto omitted fields").action((path, opts) => {
+    try {
+      const loaded = loadRecipe(path, process.cwd());
+      const out = opts.withDefaults ? renderRecipeWithDefaults(loaded.recipe) : loaded.recipe;
+      console.log(recipeToYaml(out));
+      for (const w of loaded.warnings) {
+        console.error(`# \u26A0  ${w}`);
+      }
+    } catch (err) {
+      console.error(`atelier recipe show: ${err instanceof Error ? err.message : err}`);
+      process.exit(1);
+    }
+  });
+}
+
+// src/commands/apply-recipe.ts
+function applyRecipeCommand(program2) {
+  program2.command("apply-recipe <project> <recipe>").description(
+    "Apply a Studio Recipe by running atelier trim + atelier transcribe with the same recipe, in that order."
+  ).option("--reset", "Apply --reset to both pipelines (destructive \u2014 discards existing user padding and transcript edits)").option("--no-trim", "Skip the atelier trim step").option("--no-transcribe", "Skip the atelier transcribe step").action(async (project, recipeRef, opts) => {
+    try {
+      const { recipe, path, warnings } = loadRecipe(recipeRef, project);
+      console.log(`Loaded recipe ${path}`);
+      for (const w of warnings) console.log(`  \u26A0  ${w}`);
+      if (opts.trim) {
+        const trimOpts = applyRecipeToTrimOptions(recipe, { reset: opts.reset });
+        console.log(`
+Running atelier trim...`);
+        const r = await trimProject(project, trimOpts);
+        console.log(`  ${r.cuts.length} cut${r.cuts.length === 1 ? "" : "s"} written`);
+      }
+      if (opts.transcribe) {
+        const transcribeOpts = applyRecipeToTranscribeOptions(recipe, { reset: opts.reset });
+        console.log(`
+Running atelier transcribe...`);
+        const r = await transcribeProject(project, transcribeOpts);
+        console.log(`  ${r.wordCount} words, ${r.captionsGenerated ? "captions written" : "captions skipped"}`);
+      }
+      if (recipe.overlay_rules) {
+        const vp = loadVideoProject(project);
+        const doc = readComposition(vp);
+        const updated = applyRecipeToOverlay(doc, recipe);
+        writeComposition(vp, updated);
+        console.log(`
+Applied overlay rules to ${vp.compositionPath}`);
+      }
+      console.log(`
+Done.`);
+    } catch (err) {
+      console.error(`atelier apply-recipe: ${err instanceof Error ? err.message : err}`);
+      process.exit(1);
+    }
+  });
+}
+
+// src/commands/carousel.ts
+var import_node_fs7 = require("fs");
+var import_node_path6 = require("path");
+
+// src/lib/render-image.ts
+init_dist2();
+var import_canvas = require("@napi-rs/canvas");
+function fitImageToCanvas(canvas, natural) {
+  const cw = canvas.width;
+  const ch = canvas.height;
+  const iw = natural.width;
+  const ih = natural.height;
+  if (!iw || !ih) {
+    return { bounds: { width: cw, height: ch }, frame: { x: cw / 2, y: ch / 2 } };
+  }
+  const imageAspect = iw / ih;
+  const canvasAspect = cw / ch;
+  let width;
+  let height;
+  if (imageAspect > canvasAspect) {
+    width = cw;
+    height = cw / imageAspect;
+  } else {
+    height = ch;
+    width = ch * imageAspect;
+  }
+  width = Math.min(width, cw);
+  height = Math.min(height, ch);
+  return { bounds: { width, height }, frame: { x: cw / 2, y: ch / 2 } };
+}
+var CanvasUnavailableError = class extends Error {
+  constructor() {
+    super(
+      "The '@napi-rs/canvas' rasterizer could not be loaded.\nThis package ships prebuilt platform binaries \u2014 no system libraries needed.\nTry reinstalling dependencies (e.g. `npm install`) to fetch the binary for this platform."
+    );
+    this.name = "CanvasUnavailableError";
+  }
+};
+async function loadCanvasModule() {
+  if (typeof import_canvas.createCanvas !== "function" || typeof import_canvas.loadImage !== "function") {
+    throw new CanvasUnavailableError();
+  }
+  return {
+    createCanvas: import_canvas.createCanvas,
+    loadImage: import_canvas.loadImage
+  };
+}
+function resolveExportDimensions(docWidth, docHeight, width, height) {
+  if (width !== void 0 && height !== void 0) {
+    return { width, height };
+  }
+  if (width !== void 0) {
+    const h = Math.max(1, Math.round(width * docHeight / docWidth));
+    return { width, height: h };
+  }
+  if (height !== void 0) {
+    const w = Math.max(1, Math.round(height * docWidth / docHeight));
+    return { width: w, height };
+  }
+  return { width: docWidth, height: docHeight };
+}
+async function preloadImages(doc, loadImage2) {
+  const { ImageCache: ImageCache2 } = await Promise.resolve().then(() => (init_dist3(), dist_exports));
+  const sources = /* @__PURE__ */ new Set();
+  for (const layer of doc.layers) {
+    if (layer.visual.type === "image") {
+      const iv = layer.visual;
+      if (iv.src) sources.add(iv.src);
+      else if (iv.assetId && doc.assets?.[iv.assetId]) sources.add(doc.assets[iv.assetId].src);
+    }
+  }
+  if (sources.size === 0) {
+    return { imageCache: new ImageCache2(), loaded: /* @__PURE__ */ new Map() };
+  }
+  const preloaded = /* @__PURE__ */ new Map();
+  await Promise.all(
+    [...sources].map(async (src) => {
+      try {
+        preloaded.set(src, await loadImage2(src));
+      } catch {
+      }
+    })
+  );
+  const imageCache = new ImageCache2({
+    createImage: (src, onLoad, onError) => {
+      const img = preloaded.get(src);
+      if (img) {
+        process.nextTick(onLoad);
+        return img;
+      }
+      process.nextTick(onError);
+      return {};
+    }
+  });
+  for (const src of preloaded.keys()) imageCache.load(src);
+  await new Promise((resolve16) => process.nextTick(resolve16));
+  return { imageCache, loaded: preloaded };
+}
+async function renderDocumentToPng(doc, opts = {}) {
+  const stateNames = Object.keys(doc.states);
+  if (stateNames.length === 0) {
+    throw new Error("Document has no states");
+  }
+  const stateName = opts.state ?? stateNames[0];
+  if (!doc.states[stateName]) {
+    throw new Error(`State "${stateName}" not found. Available: ${stateNames.join(", ")}`);
+  }
+  const frameNumber = opts.frame ?? 0;
+  if (!Number.isInteger(frameNumber) || frameNumber < 0) {
+    throw new Error(`Invalid frame number: ${frameNumber}`);
+  }
+  const duration = doc.states[stateName].duration;
+  if (frameNumber >= duration) {
+    throw new Error(
+      `Frame ${frameNumber} is out of range for state "${stateName}" (duration ${duration})`
+    );
+  }
+  const { createCanvas: createCanvas2, loadImage: loadImage2 } = await loadCanvasModule();
+  const { renderFrame: renderFrame2 } = await Promise.resolve().then(() => (init_dist3(), dist_exports));
+  const { imageCache, loaded } = await preloadImages(doc, loadImage2);
+  let renderDoc = doc;
+  if (opts.refitImageBounds && loaded.size > 0) {
+    renderDoc = {
+      ...doc,
+      layers: doc.layers.map((layer) => {
+        if (layer.visual.type !== "image") return layer;
+        const iv = layer.visual;
+        const src = iv.src ?? (iv.assetId ? doc.assets?.[iv.assetId]?.src : void 0);
+        const natural = src ? loaded.get(src) : void 0;
+        if (!natural || !natural.width || !natural.height) return layer;
+        const fit = opts.refitImageBounds({ canvas: doc.canvas, natural });
+        return { ...layer, bounds: fit.bounds, frame: fit.frame };
+      })
+    };
+  }
+  const { width: outW, height: outH } = resolveExportDimensions(
+    renderDoc.canvas.width,
+    renderDoc.canvas.height,
+    opts.width,
+    opts.height
+  );
+  const resolved = resolveFrame(renderDoc, stateName, frameNumber);
+  const cvs = createCanvas2(outW, outH);
+  const ctx = cvs.getContext("2d");
+  const sx = outW / renderDoc.canvas.width;
+  const sy = outH / renderDoc.canvas.height;
+  if (sx !== 1 || sy !== 1) ctx.scale(sx, sy);
+  renderFrame2(ctx, resolved, renderDoc, imageCache);
+  return cvs.toBuffer("image/png");
+}
+
+// src/commands/carousel.ts
+var IMAGE_EXTS = /* @__PURE__ */ new Set([".png", ".jpg", ".jpeg", ".webp"]);
+var DEFAULT_CANVAS = 1080;
+function expandInputs(pattern) {
+  const abs = (0, import_node_path6.resolve)(pattern);
+  let isDir = false;
+  try {
+    isDir = (0, import_node_fs7.statSync)(abs).isDirectory();
+  } catch {
+    isDir = false;
+  }
+  if (isDir) {
+    return listImages(abs);
+  }
+  const dir = (0, import_node_path6.dirname)(abs);
+  const base = (0, import_node_path6.basename)(abs);
+  if (base.includes("*")) {
+    const matcher = globToRegExp(base);
+    let entries;
+    try {
+      entries = (0, import_node_fs7.readdirSync)(dir);
+    } catch {
+      return [];
+    }
+    return entries.filter((name) => matcher.test(name) && isImageFile(name)).map((name) => (0, import_node_path6.join)(dir, name)).sort();
+  }
+  return isImageFile(base) ? [abs] : [];
+}
+function listImages(dir) {
+  let entries;
+  try {
+    entries = (0, import_node_fs7.readdirSync)(dir);
+  } catch {
+    return [];
+  }
+  return entries.filter(isImageFile).map((name) => (0, import_node_path6.join)(dir, name)).sort();
+}
+function isImageFile(name) {
+  return IMAGE_EXTS.has((0, import_node_path6.extname)(name).toLowerCase());
+}
+function globToRegExp(glob) {
+  const escaped = glob.replace(/[.+^${}()|[\]\\]/g, "\\$&");
+  const pattern = escaped.replace(/\*/g, `[^${import_node_path6.sep === "\\" ? "\\\\" : import_node_path6.sep}]*`).replace(/\?/g, ".");
+  return new RegExp(`^${pattern}$`);
+}
+function composeCarouselFrameDoc(args) {
+  const { imagePath, index, total, width, height, recipe } = args;
+  const canvas = { width, height };
+  const fit = fitImageToCanvas(canvas, { width: 0, height: 0 });
+  const assetId = "carousel-image-asset";
+  const baseDoc = {
+    version: "1.0",
+    name: `carousel-${index}`,
+    canvas: { width, height, fps: 30, background: args.background ?? "#000000" },
+    assets: { [assetId]: { type: "image", src: imagePath } },
+    layers: [
+      {
+        id: "carousel-image",
+        visual: { type: "image", assetId, src: imagePath },
+        frame: fit.frame,
+        bounds: fit.bounds,
+        anchorPoint: { x: 0.5, y: 0.5 },
+        opacity: 1
+      }
+    ],
+    states: { default: { duration: 1, deltas: [] } }
+  };
+  return applyRecipeToOverlay(baseDoc, recipe, { currentIndex: index, totalCount: total });
+}
+function carouselFileName(index, total, imagePath) {
+  const padWidth = Math.max(2, String(total).length);
+  const prefix = String(index).padStart(padWidth, "0");
+  const ext = (0, import_node_path6.extname)(imagePath);
+  const stem = (0, import_node_path6.basename)(imagePath, ext);
+  return `${prefix}-${stem}.png`;
+}
+function parseDim(raw, name) {
+  if (raw === void 0) return void 0;
+  const n = parseInt(raw, 10);
+  if (isNaN(n) || n <= 0) {
+    console.error(`Invalid --${name}: ${raw}`);
+    process.exit(1);
+  }
+  return n;
+}
+function carouselCommand(program2) {
+  program2.command("carousel <recipe>").description(
+    "Batch-compose a folder of images into recipe-overlaid PNGs. Each image becomes a fit-to-canvas post with the recipe's handle + page-number ('i/N') overlays, written to --out-dir as zero-padded PNGs."
+  ).requiredOption("-i, --inputs <glob>", "Input images: a directory, file, or single-segment *-glob").requiredOption("-d, --out-dir <dir>", "Destination directory for composed PNGs").option("--width <number>", "Canvas width (px)", String(DEFAULT_CANVAS)).option("--height <number>", "Canvas height (px)", String(DEFAULT_CANVAS)).option("-f, --frame <number>", "Frame to render (defaults to 0)", "0").action(async (recipeRef, options) => {
+    let recipe;
+    try {
+      const loaded = loadRecipe(recipeRef);
+      recipe = loaded.recipe;
+      console.log(`Loaded recipe ${loaded.path}`);
+      for (const w of loaded.warnings) console.log(`  \u26A0  ${w}`);
+    } catch (err) {
+      console.error(`atelier carousel: ${err instanceof Error ? err.message : err}`);
+      process.exit(1);
+      return;
+    }
+    const inputs = expandInputs(options.inputs);
+    if (inputs.length === 0) {
+      console.error(
+        `atelier carousel: no image files matched --inputs "${options.inputs}" (accepted: ${[...IMAGE_EXTS].join(", ")})`
+      );
+      process.exit(1);
+      return;
+    }
+    const width = parseDim(options.width, "width") ?? DEFAULT_CANVAS;
+    const height = parseDim(options.height, "height") ?? DEFAULT_CANVAS;
+    const frame = parseInt(options.frame, 10);
+    if (isNaN(frame) || frame < 0) {
+      console.error(`Invalid frame number: ${options.frame}`);
+      process.exit(1);
+      return;
+    }
+    const outDir = (0, import_node_path6.resolve)(options.outDir);
+    try {
+      (0, import_node_fs7.mkdirSync)(outDir, { recursive: true });
+    } catch (err) {
+      console.error(`atelier carousel: cannot create out-dir ${outDir}: ${err.message}`);
+      process.exit(1);
+      return;
+    }
+    const total = inputs.length;
+    console.log(`Composing ${total} image${total === 1 ? "" : "s"} \u2192 ${outDir}`);
+    try {
+      for (let n = 0; n < total; n++) {
+        const index = n + 1;
+        const imagePath = inputs[n];
+        const doc = composeCarouselFrameDoc({
+          imagePath,
+          index,
+          total,
+          width,
+          height,
+          recipe
+        });
+        const buffer = await renderDocumentToPng(doc, {
+          frame,
+          // Re-fit the image to the canvas using real natural dims once decoded.
+          refitImageBounds: ({ canvas, natural }) => fitImageToCanvas(canvas, natural)
+        });
+        const outName = carouselFileName(index, total, imagePath);
+        (0, import_node_fs7.writeFileSync)((0, import_node_path6.join)(outDir, outName), buffer);
+        console.log(`  [${index}/${total}] ${(0, import_node_path6.basename)(imagePath)} \u2192 ${outName}`);
+      }
+    } catch (err) {
+      if (err instanceof CanvasUnavailableError) {
+        console.error(err.message);
+        process.exit(1);
+        return;
       }
+      console.error(`atelier carousel: ${err instanceof Error ? err.message : err}`);
+      process.exit(1);
+      return;
     }
-    const allValid = results.every((r) => r.valid);
-    if (!allValid) process.exit(1);
+    console.log(`
+Done. ${total} image${total === 1 ? "" : "s"} \u2192 ${outDir}`);
   });
 }
 
 // src/commands/info.ts
-var import_node_fs3 = require("fs");
-var import_node_path3 = require("path");
+var import_node_fs8 = require("fs");
+var import_node_path7 = require("path");
 function getInfo(doc) {
   return {
     name: doc.name,
@@ -2122,10 +4070,10 @@ function formatInfo(info) {
   return lines.join("\n");
 }
 function readAndParse(file) {
-  const absPath = (0, import_node_path3.resolve)(file);
+  const absPath = (0, import_node_path7.resolve)(file);
   let content;
   try {
-    content = (0, import_node_fs3.readFileSync)(absPath, "utf-8");
+    content = (0, import_node_fs8.readFileSync)(absPath, "utf-8");
   } catch {
     console.error(`Cannot read file: ${absPath}`);
     return process.exit(1);
@@ -2149,8 +4097,8 @@ function infoCommand(program2) {
 }
 
 // src/commands/still.ts
-var import_node_fs4 = require("fs");
-var import_node_path4 = require("path");
+var import_node_fs9 = require("fs");
+var import_node_path8 = require("path");
 init_dist2();
 function resolveStill(doc, stateName, frame) {
   const stateNames = Object.keys(doc.states);
@@ -2167,10 +4115,10 @@ function resolveStill(doc, stateName, frame) {
   return resolveFrame(doc, resolvedStateName, resolvedFrame);
 }
 function readAndParse2(file) {
-  const absPath = (0, import_node_path4.resolve)(file);
+  const absPath = (0, import_node_path8.resolve)(file);
   let content;
   try {
-    content = (0, import_node_fs4.readFileSync)(absPath, "utf-8");
+    content = (0, import_node_fs9.readFileSync)(absPath, "utf-8");
   } catch {
     console.error(`Cannot read file: ${absPath}`);
     return process.exit(1);
@@ -2221,27 +4169,19 @@ function stillCommand(program2) {
         if (options.format === "json") {
           const json = JSON.stringify(resolved, null, 2);
           if (options.output) {
-            (0, import_node_fs4.writeFileSync)((0, import_node_path4.resolve)(options.output), json, "utf-8");
+            (0, import_node_fs9.writeFileSync)((0, import_node_path8.resolve)(options.output), json, "utf-8");
           } else {
             console.log(json);
           }
         } else {
-          let canvasMod;
-          try {
-            canvasMod = await import("canvas");
-          } catch {
-            console.error("PNG output requires the 'canvas' package. Install it: npm i canvas");
-            process.exit(1);
-            return;
-          }
+          const { createCanvas: createCanvas2 } = await import("@napi-rs/canvas");
           const { renderFrame: renderFrame2 } = await Promise.resolve().then(() => (init_dist3(), dist_exports));
-          const { createCanvas } = canvasMod;
-          const cvs = createCanvas(doc.canvas.width, doc.canvas.height);
+          const cvs = createCanvas2(doc.canvas.width, doc.canvas.height);
           const ctx = cvs.getContext("2d");
           renderFrame2(ctx, resolved, doc);
           const buffer = cvs.toBuffer("image/png");
           if (options.output) {
-            (0, import_node_fs4.writeFileSync)((0, import_node_path4.resolve)(options.output), buffer);
+            (0, import_node_fs9.writeFileSync)((0, import_node_path8.resolve)(options.output), buffer);
           } else {
             process.stdout.write(buffer);
           }
@@ -2257,18 +4197,18 @@ function stillCommand(program2) {
 }
 
 // src/commands/render.ts
-var import_node_fs5 = require("fs");
-var import_node_path5 = require("path");
+var import_node_fs10 = require("fs");
+var import_node_path9 = require("path");
 
 // src/commands/render-pipeline.ts
-var import_node_child_process = require("child_process");
+var import_node_child_process3 = require("child_process");
 init_dist2();
 init_dist3();
 async function checkFfmpeg() {
-  return new Promise((resolve11) => {
-    const proc = (0, import_node_child_process.spawn)("ffmpeg", ["-version"], { stdio: "pipe" });
-    proc.on("error", () => resolve11(false));
-    proc.on("close", (code) => resolve11(code === 0));
+  return new Promise((resolve16) => {
+    const proc = (0, import_node_child_process3.spawn)("ffmpeg", ["-version"], { stdio: "pipe" });
+    proc.on("error", () => resolve16(false));
+    proc.on("close", (code) => resolve16(code === 0));
   });
 }
 function buildFfmpegArgs(width, height, fps, format, output) {
@@ -2310,7 +4250,7 @@ function buildFfmpegArgs(width, height, fps, format, output) {
     output
   ];
 }
-async function preloadImages(doc, loadImage) {
+async function preloadImages2(doc, loadImage2) {
   const sources = /* @__PURE__ */ new Set();
   for (const layer of doc.layers) {
     if (layer.visual.type === "image") {
@@ -2329,7 +4269,7 @@ async function preloadImages(doc, loadImage) {
   await Promise.all(
     [...sources].map(async (src) => {
       try {
-        preloaded.set(src, await loadImage(src));
+        preloaded.set(src, await loadImage2(src));
       } catch {
       }
     })
@@ -2348,20 +4288,20 @@ async function preloadImages(doc, loadImage) {
   for (const src of preloaded.keys()) {
     imageCache.load(src);
   }
-  await new Promise((resolve11) => process.nextTick(resolve11));
+  await new Promise((resolve16) => process.nextTick(resolve16));
   return imageCache;
 }
 async function renderDocument(doc, opts) {
   const canvasModuleName = "canvas";
-  let createCanvas;
-  let loadImage;
+  let createCanvas2;
+  let loadImage2;
   try {
     const canvasModule = await import(
       /* webpackIgnore: true */
       canvasModuleName
     );
-    createCanvas = canvasModule.createCanvas;
-    loadImage = canvasModule.loadImage;
+    createCanvas2 = canvasModule.createCanvas;
+    loadImage2 = canvasModule.loadImage;
   } catch {
     throw new Error(
       "The 'canvas' package is not installed.\nInstall it with:\n  npm install canvas\nPrerequisites vary by OS:\n  macOS:   brew install pkg-config cairo pango libpng jpeg giflib librsvg pixman\n  Ubuntu:  sudo apt install build-essential libcairo2-dev libpango1.0-dev libjpeg-dev libgif-dev librsvg2-dev\nSee: https://github.com/Automattic/node-canvas#compiling"
@@ -2390,11 +4330,11 @@ async function renderDocument(doc, opts) {
   if (totalFrames === 0) {
     throw new Error("Nothing to render \u2014 all states have duration 0");
   }
-  const imageCache = await preloadImages(doc, loadImage);
-  const canvas = createCanvas(width, height);
+  const imageCache = await preloadImages2(doc, loadImage2);
+  const canvas = createCanvas2(width, height);
   const ctx = canvas.getContext("2d");
   const ffmpegArgs = buildFfmpegArgs(width, height, fps, format, output);
-  const ffmpeg = (0, import_node_child_process.spawn)("ffmpeg", ffmpegArgs, {
+  const ffmpeg = (0, import_node_child_process3.spawn)("ffmpeg", ffmpegArgs, {
     stdio: ["pipe", "pipe", "pipe"]
   });
   let stderrOutput = "";
@@ -2412,7 +4352,7 @@ async function renderDocument(doc, opts) {
       const canWrite = ffmpeg.stdin.write(raw);
       if (!canWrite) {
         await new Promise(
-          (resolve11) => ffmpeg.stdin.once("drain", resolve11)
+          (resolve16) => ffmpeg.stdin.once("drain", resolve16)
         );
       }
       frameIndex++;
@@ -2425,8 +4365,8 @@ async function renderDocument(doc, opts) {
     }
   }
   ffmpeg.stdin.end();
-  const exitCode = await new Promise((resolve11) => {
-    ffmpeg.on("close", resolve11);
+  const exitCode = await new Promise((resolve16) => {
+    ffmpeg.on("close", resolve16);
   });
   if (exitCode !== 0) {
     throw new Error(
@@ -2445,10 +4385,10 @@ ${stderrOutput.slice(-500)}`
 
 // src/commands/render.ts
 function readAndParse3(file) {
-  const absPath = (0, import_node_path5.resolve)(file);
+  const absPath = (0, import_node_path9.resolve)(file);
   let content;
   try {
-    content = (0, import_node_fs5.readFileSync)(absPath, "utf-8");
+    content = (0, import_node_fs10.readFileSync)(absPath, "utf-8");
   } catch {
     console.error(`Cannot read file: ${absPath}`);
     return process.exit(1);
@@ -2465,7 +4405,7 @@ function readAndParse3(file) {
 }
 function inferFormat(output) {
   if (!output) return "mp4";
-  const ext = (0, import_node_path5.extname)(output).toLowerCase();
+  const ext = (0, import_node_path9.extname)(output).toLowerCase();
   if (ext === ".gif") return "gif";
   return "mp4";
 }
@@ -2499,12 +4439,12 @@ function renderCommand(program2) {
       } else {
         format = inferFormat(options.output);
       }
-      const inputName = (0, import_node_path5.basename)(file, (0, import_node_path5.extname)(file));
+      const inputName = (0, import_node_path9.basename)(file, (0, import_node_path9.extname)(file));
       const output = options.output ?? `${inputName}.${format}`;
       const startTime = Date.now();
       try {
         const result = await renderDocument(doc, {
-          output: (0, import_node_path5.resolve)(output),
+          output: (0, import_node_path9.resolve)(output),
           format,
           states: options.state,
           onProgress: ({ frame, totalFrames, state, percent }) => {
@@ -2530,8 +4470,8 @@ function renderCommand(program2) {
 }
 
 // src/commands/export-svg.ts
-var import_node_fs6 = require("fs");
-var import_node_path6 = require("path");
+var import_node_fs11 = require("fs");
+var import_node_path10 = require("path");
 
 // ../svg/dist/index.js
 init_dist2();
@@ -2996,10 +4936,10 @@ function renderRefSVG(eff, visual, _parentDoc, opts, _depth, _visitedRefs) {
 
 // src/commands/export-svg.ts
 function readAndParse4(file) {
-  const absPath = (0, import_node_path6.resolve)(file);
+  const absPath = (0, import_node_path10.resolve)(file);
   let content;
   try {
-    content = (0, import_node_fs6.readFileSync)(absPath, "utf-8");
+    content = (0, import_node_fs11.readFileSync)(absPath, "utf-8");
   } catch {
     console.error(`Cannot read file: ${absPath}`);
     return process.exit(1);
@@ -3041,7 +4981,7 @@ function exportSvgCommand(program2) {
           xmlDeclaration: options.xmlDeclaration
         });
         if (options.output) {
-          (0, import_node_fs6.writeFileSync)((0, import_node_path6.resolve)(options.output), svg, "utf-8");
+          (0, import_node_fs11.writeFileSync)((0, import_node_path10.resolve)(options.output), svg, "utf-8");
         } else {
           console.log(svg);
         }
@@ -3054,8 +4994,8 @@ function exportSvgCommand(program2) {
 }
 
 // src/commands/export-lottie.ts
-var import_node_fs7 = require("fs");
-var import_node_path7 = require("path");
+var import_node_fs12 = require("fs");
+var import_node_path11 = require("path");
 
 // ../lottie/dist/index.js
 function colorToLottie(color) {
@@ -3624,10 +5564,10 @@ function exportToLottie(doc, opts) {
 
 // src/commands/export-lottie.ts
 function readAndParse5(file) {
-  const absPath = (0, import_node_path7.resolve)(file);
+  const absPath = (0, import_node_path11.resolve)(file);
   let content;
   try {
-    content = (0, import_node_fs7.readFileSync)(absPath, "utf-8");
+    content = (0, import_node_fs12.readFileSync)(absPath, "utf-8");
   } catch {
     console.error(`Cannot read file: ${absPath}`);
     return process.exit(1);
@@ -3655,7 +5595,7 @@ function exportLottieCommand(program2) {
         }
         const output = JSON.stringify(json, null, 2);
         if (options.output) {
-          (0, import_node_fs7.writeFileSync)((0, import_node_path7.resolve)(options.output), output, "utf-8");
+          (0, import_node_fs12.writeFileSync)((0, import_node_path11.resolve)(options.output), output, "utf-8");
         } else {
           console.log(output);
         }
@@ -3667,9 +5607,73 @@ function exportLottieCommand(program2) {
   );
 }
 
+// src/commands/export-image.ts
+var import_node_fs13 = require("fs");
+var import_node_path12 = require("path");
+function readAndParse6(file) {
+  const absPath = (0, import_node_path12.resolve)(file);
+  let content;
+  try {
+    content = (0, import_node_fs13.readFileSync)(absPath, "utf-8");
+  } catch {
+    console.error(`Cannot read file: ${absPath}`);
+    return process.exit(1);
+  }
+  const result = parseAtelier(content);
+  if (!result.success) {
+    console.error("Parse errors:");
+    for (const error of result.errors) {
+      console.error(`  - ${error.path}: ${error.message}`);
+    }
+    return process.exit(1);
+  }
+  return result.data;
+}
+function parseDim2(raw, name) {
+  if (raw === void 0) return void 0;
+  const n = parseInt(raw, 10);
+  if (isNaN(n) || n <= 0) {
+    console.error(`Invalid --${name}: ${raw}`);
+    process.exit(1);
+  }
+  return n;
+}
+function exportImageCommand(program2) {
+  program2.command("export-image <file>").description(
+    "Export a single frame as a PNG image. Aspect-preserving when only one of --width/--height is set; if both are set the renderer uses both verbatim (may squash)."
+  ).requiredOption("-o, --out <path>", "Output PNG file path").option("-s, --state <name>", "State name (defaults to first state)").option("-f, --frame <number>", "Frame number (defaults to 0)", "0").option("--width <number>", "Override output width (px)").option("--height <number>", "Override output height (px)").action(async (file, options) => {
+    const doc = readAndParse6(file);
+    const frameNumber = parseInt(options.frame, 10);
+    if (isNaN(frameNumber) || frameNumber < 0) {
+      console.error(`Invalid frame number: ${options.frame}`);
+      process.exit(1);
+      return;
+    }
+    const width = parseDim2(options.width, "width");
+    const height = parseDim2(options.height, "height");
+    try {
+      const buffer = await renderDocumentToPng(doc, {
+        state: options.state,
+        frame: frameNumber,
+        width,
+        height
+      });
+      (0, import_node_fs13.writeFileSync)((0, import_node_path12.resolve)(options.out), buffer);
+    } catch (err) {
+      if (err instanceof CanvasUnavailableError) {
+        console.error(err.message);
+        process.exit(1);
+        return;
+      }
+      console.error(err.message);
+      process.exit(1);
+    }
+  });
+}
+
 // src/commands/assets.ts
-var import_node_fs8 = require("fs");
-var import_node_path8 = require("path");
+var import_node_fs14 = require("fs");
+var import_node_path13 = require("path");
 function getAssets(doc) {
   const assets = doc.assets ?? {};
   return Object.entries(assets).map(([assetId, asset]) => {
@@ -3700,11 +5704,11 @@ function formatAssets(assets) {
   }
   return lines.join("\n");
 }
-function readAndParse6(file) {
-  const absPath = (0, import_node_path8.resolve)(file);
+function readAndParse7(file) {
+  const absPath = (0, import_node_path13.resolve)(file);
   let content;
   try {
-    content = (0, import_node_fs8.readFileSync)(absPath, "utf-8");
+    content = (0, import_node_fs14.readFileSync)(absPath, "utf-8");
   } catch {
     console.error(`Cannot read file: ${absPath}`);
     return process.exit(1);
@@ -3721,15 +5725,15 @@ function readAndParse6(file) {
 }
 function assetsCommand(program2) {
   program2.command("assets <file>").description("List all assets in an .atelier file with usage info").action((file) => {
-    const doc = readAndParse6(file);
+    const doc = readAndParse7(file);
     const assets = getAssets(doc);
     console.log(formatAssets(assets));
   });
 }
 
 // src/commands/variables.ts
-var import_node_fs9 = require("fs");
-var import_node_path9 = require("path");
+var import_node_fs15 = require("fs");
+var import_node_path14 = require("path");
 init_dist2();
 function getVariables(doc) {
   const variables = doc.variables ?? {};
@@ -3764,11 +5768,11 @@ function formatVariables(info) {
   }
   return lines.join("\n");
 }
-function readAndParse7(file) {
-  const absPath = (0, import_node_path9.resolve)(file);
+function readAndParse8(file) {
+  const absPath = (0, import_node_path14.resolve)(file);
   let content;
   try {
-    content = (0, import_node_fs9.readFileSync)(absPath, "utf-8");
+    content = (0, import_node_fs15.readFileSync)(absPath, "utf-8");
   } catch {
     console.error(`Cannot read file: ${absPath}`);
     return process.exit(1);
@@ -3785,48 +5789,160 @@ function readAndParse7(file) {
 }
 function variablesCommand(program2) {
   program2.command("variables <file>").description("List all variables in an .atelier file with usage info").action((file) => {
-    const doc = readAndParse7(file);
+    const doc = readAndParse8(file);
     const info = getVariables(doc);
     console.log(formatVariables(info));
   });
 }
 
 // src/commands/studio.ts
-var import_node_path10 = require("path");
-var import_node_fs10 = require("fs");
-var import_node_os = require("os");
+var import_node_path15 = require("path");
+var import_node_fs16 = require("fs");
+var import_node_os2 = require("os");
 var import_node_crypto = require("crypto");
-var import_node_child_process2 = require("child_process");
+var import_node_child_process4 = require("child_process");
+var import_atelier_mcp = require("@a-company/atelier-mcp");
+var import_ws = require("ws");
 var import_meta = {};
 function findAtelierFiles(dir, base = dir) {
   const results = [];
   let entries;
   try {
-    entries = (0, import_node_fs10.readdirSync)(dir);
+    entries = (0, import_node_fs16.readdirSync)(dir);
   } catch {
     return results;
   }
   for (const entry of entries) {
     if (entry === "node_modules" || entry === "dist" || entry === ".git") continue;
-    const full = (0, import_node_path10.join)(dir, entry);
+    const full = (0, import_node_path15.join)(dir, entry);
     let stat;
     try {
-      stat = (0, import_node_fs10.statSync)(full);
+      stat = (0, import_node_fs16.statSync)(full);
     } catch {
       continue;
     }
     if (stat.isDirectory()) {
       results.push(...findAtelierFiles(full, base));
     } else if (entry.endsWith(".atelier")) {
-      results.push((0, import_node_path10.relative)(base, full));
+      results.push((0, import_node_path15.relative)(base, full));
     }
   }
   return results.sort();
 }
 function isSafePath(filePath) {
-  if (!filePath || filePath.includes("..") || filePath.startsWith("/")) return false;
-  const resolved = (0, import_node_path10.resolve)(process.cwd(), filePath);
-  return resolved.startsWith(process.cwd());
+  if (!filePath || filePath.startsWith("/")) return false;
+  const cwd = process.cwd();
+  const resolved = (0, import_node_path15.resolve)(cwd, filePath);
+  return resolved === cwd || resolved.startsWith(cwd + import_node_path15.sep);
+}
+function writeFileEnsuringDir(absPath, body) {
+  (0, import_node_fs16.mkdirSync)((0, import_node_path15.dirname)(absPath), { recursive: true });
+  (0, import_node_fs16.writeFileSync)(absPath, body, "utf-8");
+}
+function isAllowedOrigin(origin, port) {
+  if (!origin) return false;
+  return origin === `http://localhost:${port}` || origin === `http://127.0.0.1:${port}`;
+}
+function isAllowedMcpOrigin(origin, port) {
+  return origin === void 0 || isAllowedOrigin(origin, port);
+}
+function shouldBroadcastMutation(source) {
+  return source === "llm";
+}
+function attachBridgeClient(ws, state, clients, loadDocFromDisk, persistHumanPatch) {
+  clients.add(ws);
+  const clientId = (0, import_node_crypto.randomBytes)(6).toString("hex");
+  const send = (env) => {
+    if (ws.readyState !== ws.OPEN) return;
+    ws.send(JSON.stringify(env));
+  };
+  send({ type: "hello", clientId, protocolVersion: import_atelier_mcp.BRIDGE_PROTOCOL_VERSION });
+  if (state.currentDocId) {
+    const existing = state.store.get(state.currentDocId);
+    if (existing) {
+      send({ type: "doc:loaded", documentId: state.currentDocId, doc: existing });
+    } else {
+      const raw = loadDocFromDisk(state.currentDocId);
+      if (raw) {
+        const parsed = parseAtelier(raw);
+        if (parsed.success) {
+          state.store.set(state.currentDocId, parsed.data, "system");
+          send({ type: "doc:loaded", documentId: state.currentDocId, doc: parsed.data });
+        }
+      }
+    }
+  }
+  const onMessage = (data) => {
+    let text;
+    if (typeof data === "string") text = data;
+    else if (data instanceof Buffer) text = data.toString("utf-8");
+    else if (Array.isArray(data)) text = Buffer.concat(data).toString("utf-8");
+    else text = String(data);
+    let env;
+    try {
+      env = JSON.parse(text);
+    } catch {
+      send({ type: "error", code: "parse_error", message: "invalid JSON" });
+      return;
+    }
+    if (!(0, import_atelier_mcp.isBridgeEnvelope)(env)) {
+      send({ type: "error", code: "invalid_envelope", message: "unknown envelope shape" });
+      return;
+    }
+    if (env.type === "doc:patch") {
+      try {
+        state.store.set(env.documentId, env.doc, "human");
+        state.currentDocId = env.documentId;
+        persistHumanPatch(env.documentId, env.doc);
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        send({ type: "error", code: "persist_failed", message: msg, opId: env.opId });
+      }
+      return;
+    }
+    if (env.type === "doc:load") {
+      const existing = state.store.get(env.documentId);
+      if (existing) {
+        send({ type: "doc:loaded", documentId: env.documentId, doc: existing });
+        return;
+      }
+      const raw = loadDocFromDisk(env.documentId);
+      if (raw) {
+        const parsed = parseAtelier(raw);
+        if (parsed.success) {
+          state.store.set(env.documentId, parsed.data, "system");
+          send({ type: "doc:loaded", documentId: env.documentId, doc: parsed.data });
+          return;
+        }
+      }
+      send({ type: "error", code: "not_found", message: `document ${env.documentId} not found` });
+      return;
+    }
+  };
+  const onClose = () => {
+    clients.delete(ws);
+  };
+  ws.on("message", onMessage);
+  ws.on("close", onClose);
+  ws.on("error", onClose);
+  return () => {
+    clients.delete(ws);
+    try {
+      ws.close();
+    } catch {
+    }
+  };
+}
+function broadcastToBridge(clients, envelope) {
+  const payload = JSON.stringify(envelope);
+  for (const ws of clients) {
+    if (ws.readyState === ws.OPEN) {
+      try {
+        ws.send(payload);
+      } catch {
+      }
+    }
+  }
 }
 function getInlineHTML() {
   return `<!DOCTYPE html>
@@ -3845,431 +5961,59 @@ function getInlineHTML() {
   </body>
 </html>`;
 }
-function getInlineApp(initialFile) {
+function getInlineApp(initialFile, cliPackageDir) {
   const initialFileStr = initialFile ? JSON.stringify(initialFile) : "null";
-  return `import { AtelierStudio, exportDocument, ImageCache } from "@a-company/atelier-studio";
-import "@a-company/atelier-studio/styles.css";
-import { parseAtelier, serializeAtelier } from "@a-company/atelier-schema";
-
-// \u2500\u2500 Types \u2500\u2500
-interface FileEntry {
-  path: string;
-  name: string;
-  folder: string;
-}
-
-// \u2500\u2500 State \u2500\u2500
-let studio: AtelierStudio | null = null;
-let currentFile: string | null = null;
-let files: FileEntry[] = [];
-let saveTimeout: ReturnType<typeof setTimeout> | null = null;
-
-// \u2500\u2500 API helpers \u2500\u2500
-async function fetchFiles(): Promise<FileEntry[]> {
-  const res = await fetch("/api/files");
-  return res.json();
-}
-
-async function fetchFileContent(path: string): Promise<string> {
-  const res = await fetch("/api/file?path=" + encodeURIComponent(path));
-  return res.text();
-}
-
-async function saveFileContent(path: string, content: string): Promise<void> {
-  await fetch("/api/file?path=" + encodeURIComponent(path), {
-    method: "POST",
-    headers: { "Content-Type": "text/plain" },
-    body: content,
-  });
-}
-
-async function saveExportBlob(path: string, blob: Blob): Promise<void> {
-  const buf = await blob.arrayBuffer();
-  await fetch("/api/export?path=" + encodeURIComponent(path), {
-    method: "POST",
-    headers: { "Content-Type": "application/octet-stream" },
-    body: buf,
-  });
+  const appModulePath = (0, import_node_path15.join)(cliPackageDir, "src", "web", "inline-app.ts").split(import_node_path15.sep).join("/");
+  return `import { bootStudioApp } from ${JSON.stringify(appModulePath)};
+bootStudioApp({ initialFile: ${initialFileStr} });
+`;
 }
-
-async function exportAll(format: "gif" | "mp4" | "webm"): Promise<void> {
-  if (files.length === 0) return;
-
-  // Create progress overlay
-  const overlay = document.createElement("div");
-  overlay.style.cssText = "position:fixed;inset:0;background:rgba(0,0,0,0.75);display:flex;align-items:center;justify-content:center;z-index:10000";
-  const card = document.createElement("div");
-  card.style.cssText = "background:#333;border:1px solid #4A4A4A;border-radius:8px;padding:32px 40px;min-width:360px;color:#F5F0EB;font-family:'Cormorant Garamond',Georgia,serif";
-  overlay.appendChild(card);
-  document.body.appendChild(overlay);
-
-  const title = document.createElement("div");
-  title.style.cssText = "font-size:18px;margin-bottom:16px;font-weight:600";
-  title.textContent = "Exporting All Files\u2026";
-  card.appendChild(title);
-
-  const fileLabel = document.createElement("div");
-  fileLabel.style.cssText = "font-size:13px;color:#A89F95;margin-bottom:8px;font-family:'SF Mono','Fira Code',monospace";
-  card.appendChild(fileLabel);
-
-  const progress = document.createElement("progress");
-  progress.style.cssText = "width:100%;height:6px;appearance:none;-webkit-appearance:none";
-  progress.max = files.length;
-  progress.value = 0;
-  card.appendChild(progress);
-
-  const statusText = document.createElement("div");
-  statusText.style.cssText = "font-size:12px;color:#A89F95;margin-top:8px";
-  card.appendChild(statusText);
-
-  let exported = 0;
-  let errors = 0;
-
-  for (const file of files) {
-    fileLabel.textContent = file.path;
-    statusText.textContent = (exported + errors + 1) + " / " + files.length;
-
-    try {
-      const content = await fetchFileContent(file.path);
-      const result = parseAtelier(content);
-      if (!result.success) {
-        errors++;
-        progress.value = exported + errors;
-        continue;
-      }
-
-      const doc = result.data;
-      const w = doc.canvas.width;
-      const h = doc.canvas.height;
-      const canvas = document.createElement("canvas");
-      canvas.width = w;
-      canvas.height = h;
-      const imageCache = new ImageCache();
-
-      const exportResult = await exportDocument(doc, canvas, imageCache, {
-        format,
-        onProgress: ({ percent }) => {
-          statusText.textContent = (exported + errors + 1) + " / " + files.length + " \u2014 " + percent + "%";
-        },
-      });
-
-      // Save alongside the source file: e.g. "dir/my-anim.atelier" \u2192 "dir/my-anim.gif"
-      const outPath = file.path.replace(/\\.atelier$/, "." + format);
-      await saveExportBlob(outPath, exportResult.blob);
-      exported++;
-    } catch (e) {
-      console.error("Export failed:", file.path, e);
-      errors++;
+function resolveCliPackageDir() {
+  const here = (0, import_node_path15.dirname)(new URL(import_meta.url).pathname);
+  const candidates = [
+    (0, import_node_path15.resolve)(here, ".."),
+    (0, import_node_path15.resolve)(here, "..", "..")
+  ];
+  for (const c of candidates) {
+    if ((0, import_node_fs16.existsSync)((0, import_node_path15.join)(c, "package.json"))) {
+      return c;
     }
-    progress.value = exported + errors;
   }
-
-  // Done
-  title.textContent = "Export Complete";
-  fileLabel.textContent = "";
-  statusText.textContent = exported + " exported" + (errors > 0 ? ", " + errors + " failed" : "");
-  if (errors > 0) console.warn("Export All finished with " + errors + " error(s). Check console for details.");
-
-  const closeBtn = document.createElement("button");
-  closeBtn.style.cssText = "margin-top:16px;padding:6px 20px;background:#3D3D3D;color:#F5F0EB;border:1px solid #4A4A4A;border-radius:4px;cursor:pointer;font-family:inherit;font-size:13px";
-  closeBtn.textContent = "Close";
-  closeBtn.addEventListener("click", () => document.body.removeChild(overlay));
-  card.appendChild(closeBtn);
+  return candidates[0];
 }
-
-// \u2500\u2500 Theme (matches branded theme from showcase) \u2500\u2500
-const theme = {
-  bg: "#2C2C2C",
-  bgSecondary: "#333333",
-  bgTertiary: "#3D3D3D",
-  text: "#F5F0EB",
-  textMuted: "#A89F95",
-  textAccent: "#F5F0EB",
-  border: "#4A4A4A",
-  buttonBg: "#3D3D3D",
-  buttonHover: "#4A4A4A",
-  buttonActive: "#555555",
-  accent: "#C75B39",
-  accentHover: "#D4724E",
-  sliderTrack: "#4A4A4A",
-  sliderThumb: "#C75B39",
-  fontFamily: "'Cormorant Garamond', Georgia, serif",
-  fontMono: "'SF Mono', 'Fira Code', monospace",
-  canvasShadow: "0 4px 60px rgba(199, 91, 57, 0.12), 0 0 40px rgba(0,0,0,0.4)",
-};
-
-// \u2500\u2500 Styles \u2500\u2500
-const style = document.createElement("style");
-style.textContent = \`
-  * { margin: 0; padding: 0; box-sizing: border-box; }
-  html, body { height: 100%; overflow: hidden; background: #2C2C2C; color: #F5F0EB; }
-  body { font-family: 'Cormorant Garamond', Georgia, serif; }
-  #studio { display: flex; height: 100vh; width: 100vw; }
-
-  .sidebar {
-    width: 260px;
-    min-width: 260px;
-    background: #333333;
-    border-right: 1px solid #4A4A4A;
-    display: flex;
-    flex-direction: column;
-    overflow: hidden;
-  }
-  .sidebar__header {
-    padding: 16px 20px;
-    border-bottom: 1px solid #4A4A4A;
-    font-size: 11px;
-    font-weight: 600;
-    letter-spacing: 2px;
-    text-transform: uppercase;
-    color: #A89F95;
-    display: flex;
-    align-items: center;
-    gap: 8px;
-  }
-  .sidebar__header span {
-    color: #C75B39;
-    font-size: 13px;
-  }
-  .sidebar__list {
-    flex: 1;
-    overflow-y: auto;
-    padding: 8px 0;
-  }
-  .sidebar__list::-webkit-scrollbar { width: 6px; }
-  .sidebar__list::-webkit-scrollbar-track { background: transparent; }
-  .sidebar__list::-webkit-scrollbar-thumb { background: #4A4A4A; border-radius: 3px; }
-
-  .sidebar__folder {
-    padding: 10px 20px 4px;
-    font-size: 10px;
-    font-weight: 600;
-    letter-spacing: 1.5px;
-    text-transform: uppercase;
-    color: #A89F95;
-  }
-  .sidebar__item {
-    padding: 8px 20px 8px 28px;
-    font-size: 13px;
-    cursor: pointer;
-    color: #A89F95;
-    transition: background 0.15s, color 0.15s;
-    white-space: nowrap;
-    overflow: hidden;
-    text-overflow: ellipsis;
-    font-family: 'SF Mono', 'Fira Code', monospace;
-    font-size: 11.5px;
-  }
-  .sidebar__item:hover { background: #363636; color: #F5F0EB; }
-  .sidebar__item--active {
-    background: rgba(199, 91, 57, 0.12) !important;
-    color: #C75B39 !important;
+function scaffoldWelcomeIfEmpty(cwd, cliPackageDir) {
+  const existing = findAtelierFiles(cwd);
+  if (existing.length > 0) return null;
+  const templatesDir = (0, import_node_path15.join)(cliPackageDir, "templates");
+  const welcomeSrc = (0, import_node_path15.join)(templatesDir, "welcome.atelier");
+  if (!(0, import_node_fs16.existsSync)(welcomeSrc)) return null;
+  const welcomeDest = (0, import_node_path15.join)(cwd, "welcome.atelier");
+  if ((0, import_node_fs16.existsSync)(welcomeDest)) return null;
+  try {
+    (0, import_node_fs16.copyFileSync)(welcomeSrc, welcomeDest);
+  } catch {
+    return null;
   }
-
-  .main {
-    flex: 1;
-    display: flex;
-    flex-direction: column;
-    overflow: hidden;
-  }
-  .main__status {
-    height: 32px;
-    min-height: 32px;
-    display: flex;
-    align-items: center;
-    padding: 0 16px;
-    background: #333333;
-    border-bottom: 1px solid #4A4A4A;
-    font-size: 11px;
-    color: #A89F95;
-    font-family: 'SF Mono', 'Fira Code', monospace;
-    gap: 12px;
-  }
-  .main__status .save-indicator {
-    display: inline-flex;
-    align-items: center;
-    gap: 4px;
-    margin-left: auto;
-    transition: opacity 0.3s;
-  }
-  .main__status .save-indicator--saving { color: #C75B39; }
-  .main__status .save-indicator--saved { color: #6B8E6B; }
-  .main__editor {
-    flex: 1;
-    overflow: hidden;
-  }
-  .main__empty {
-    flex: 1;
-    display: flex;
-    align-items: center;
-    justify-content: center;
-    color: #A89F95;
-    font-size: 18px;
-  }
-\`;
-document.head.appendChild(style);
-
-// \u2500\u2500 Build UI \u2500\u2500
-const root = document.getElementById("studio")!;
-const sidebar = document.createElement("div");
-sidebar.className = "sidebar";
-
-const sidebarHeader = document.createElement("div");
-sidebarHeader.className = "sidebar__header";
-sidebarHeader.innerHTML = '<span>&#9670;</span> ATELIER STUDIO';
-sidebar.appendChild(sidebarHeader);
-
-const sidebarList = document.createElement("div");
-sidebarList.className = "sidebar__list";
-sidebar.appendChild(sidebarList);
-
-const sidebarFooter = document.createElement("div");
-sidebarFooter.style.cssText = "padding:12px 16px;border-top:1px solid #4A4A4A;display:flex;gap:8px;align-items:center";
-const exportAllSelect = document.createElement("select");
-exportAllSelect.style.cssText = "flex:1;background:#3D3D3D;color:#F5F0EB;border:1px solid #4A4A4A;border-radius:4px;padding:4px 8px;font-size:11px;font-family:'SF Mono','Fira Code',monospace;cursor:pointer";
-for (const [val, label] of [["gif","GIF"],["mp4","MP4"],["webm","WebM"]] as const) {
-  const o = document.createElement("option");
-  o.value = val;
-  o.textContent = label;
-  exportAllSelect.appendChild(o);
-}
-sidebarFooter.appendChild(exportAllSelect);
-const exportAllBtn = document.createElement("button");
-exportAllBtn.style.cssText = "background:#C75B39;color:#F5F0EB;border:none;border-radius:4px;padding:5px 12px;font-size:11px;font-family:inherit;cursor:pointer;white-space:nowrap";
-exportAllBtn.textContent = "Export All";
-exportAllBtn.addEventListener("click", () => {
-  exportAll(exportAllSelect.value as "gif" | "mp4" | "webm");
-});
-sidebarFooter.appendChild(exportAllBtn);
-sidebar.appendChild(sidebarFooter);
-
-const main = document.createElement("div");
-main.className = "main";
-
-const statusBar = document.createElement("div");
-statusBar.className = "main__status";
-main.appendChild(statusBar);
-
-const editorContainer = document.createElement("div");
-editorContainer.className = "main__editor";
-main.appendChild(editorContainer);
-
-root.appendChild(sidebar);
-root.appendChild(main);
-
-// \u2500\u2500 File list rendering \u2500\u2500
-function renderFileList(): void {
-  sidebarList.innerHTML = "";
-  let lastFolder = "";
-
-  for (const file of files) {
-    if (file.folder && file.folder !== lastFolder) {
-      lastFolder = file.folder;
-      const folder = document.createElement("div");
-      folder.className = "sidebar__folder";
-      folder.textContent = file.folder;
-      sidebarList.appendChild(folder);
+  const bgSrc = (0, import_node_path15.join)(templatesDir, "welcome-bg.png");
+  if ((0, import_node_fs16.existsSync)(bgSrc)) {
+    const bgDest = (0, import_node_path15.join)(cwd, "welcome-bg.png");
+    if (!(0, import_node_fs16.existsSync)(bgDest)) {
+      try {
+        (0, import_node_fs16.copyFileSync)(bgSrc, bgDest);
+      } catch {
+      }
     }
-
-    const item = document.createElement("div");
-    item.className = "sidebar__item" + (file.path === currentFile ? " sidebar__item--active" : "");
-    item.textContent = file.name;
-    item.title = file.path;
-    item.addEventListener("click", () => loadFile(file.path));
-    sidebarList.appendChild(item);
-  }
-}
-
-// \u2500\u2500 Load a file into the studio \u2500\u2500
-async function loadFile(path: string): Promise<void> {
-  currentFile = path;
-  renderFileList();
-
-  const content = await fetchFileContent(path);
-  const result = parseAtelier(content);
-
-  if (!result.success) {
-    editorContainer.innerHTML = "";
-    const err = document.createElement("div");
-    err.className = "main__empty";
-    err.style.flexDirection = "column";
-    err.style.gap = "8px";
-    err.innerHTML = '<div style="color:#C75B39">Parse Error</div><div style="font-size:13px;font-family:monospace">' +
-      result.errors.map(e => e.path + ": " + e.message).join("<br>") + "</div>";
-    editorContainer.appendChild(err);
-    return;
-  }
-
-  statusBar.innerHTML = '<span>' + path + '</span><span class="save-indicator save-indicator--saved">&#10003; saved</span>';
-
-  if (studio) {
-    studio.destroy();
-    studio = null;
   }
-
-  // Set filename for export downloads (strip path and .atelier extension)
-  const baseName = path.split("/").pop()?.replace(/\\.atelier$/, "") || null;
-
-  studio = new AtelierStudio(editorContainer, {
-    mode: "full",
-    initialTab: "yaml",
-    allowSave: true,
-    onDocumentChange: (doc) => {
-      // Auto-save with debounce
-      const indicator = statusBar.querySelector(".save-indicator");
-      if (indicator) {
-        indicator.className = "save-indicator save-indicator--saving";
-        indicator.innerHTML = "&#9679; saving...";
-      }
-
-      if (saveTimeout) clearTimeout(saveTimeout);
-      saveTimeout = setTimeout(async () => {
-        if (!currentFile) return;
-        const yaml = serializeAtelier(doc);
-        await saveFileContent(currentFile, yaml);
-        const ind = statusBar.querySelector(".save-indicator");
-        if (ind) {
-          ind.className = "save-indicator save-indicator--saved";
-          ind.innerHTML = "&#10003; saved";
-        }
-      }, 800);
-    },
-  });
-  studio.setTheme(theme);
-  studio.setFilename(baseName);
-  studio.loadDocument(result.data);
+  return "welcome.atelier";
 }
-
-// \u2500\u2500 Boot \u2500\u2500
-async function boot(): Promise<void> {
-  files = await fetchFiles();
-
-  if (files.length === 0) {
-    editorContainer.innerHTML = "";
-    const empty = document.createElement("div");
-    empty.className = "main__empty";
-    empty.textContent = "No .atelier files found in this directory";
-    editorContainer.appendChild(empty);
-    statusBar.textContent = "No files";
-    renderFileList();
-    return;
-  }
-
-  renderFileList();
-
-  const initialFile = ${initialFileStr};
-  const target = initialFile
-    ? files.find(f => f.path === initialFile || f.path.endsWith(initialFile))
-    : files[0];
-
-  if (target) {
-    await loadFile(target.path);
+function readCliVersion(cliPackageDir) {
+  try {
+    const pkg = JSON.parse((0, import_node_fs16.readFileSync)((0, import_node_path15.join)(cliPackageDir, "package.json"), "utf-8"));
+    return typeof pkg.version === "string" ? pkg.version : "unknown";
+  } catch {
+    return "unknown";
   }
 }
-
-boot();
-`;
-}
 function studioCommand(program2) {
   program2.command("studio [file]").description("Launch the browser-based Atelier editor").option("-p, --port <number>", "Port to serve on", "4321").option("--no-open", "Don't auto-open browser").action(
     async (file, options) => {
@@ -4279,21 +6023,27 @@ function studioCommand(program2) {
         process.exit(1);
       }
       const cwd = process.cwd();
-      const cliPackageDir = (0, import_node_path10.resolve)((0, import_node_path10.dirname)(new URL(import_meta.url).pathname), "..");
+      const cliPackageDir = resolveCliPackageDir();
+      const version = readCliVersion(cliPackageDir);
+      const scaffolded = scaffoldWelcomeIfEmpty(cwd, cliPackageDir);
+      console.log("");
+      console.log(`  Atelier Studio \xB7 v${version}`);
+      if (scaffolded) {
+        console.log(`   Scaffolded ${scaffolded} \u2014 opening\u2026`);
+      }
       const tmpId = (0, import_node_crypto.randomBytes)(4).toString("hex");
-      const tmpDirRaw = (0, import_node_path10.join)((0, import_node_os.tmpdir)(), `atelier-studio-${tmpId}`);
-      (0, import_node_fs10.mkdirSync)(tmpDirRaw, { recursive: true });
-      const tmpDir = (0, import_node_fs10.realpathSync)(tmpDirRaw);
-      (0, import_node_fs10.writeFileSync)((0, import_node_path10.join)(tmpDir, "index.html"), getInlineHTML());
-      (0, import_node_fs10.writeFileSync)((0, import_node_path10.join)(tmpDir, "main.ts"), getInlineApp(file ?? null));
-      const cliNodeModules = (0, import_node_path10.join)(cliPackageDir, "node_modules");
-      if ((0, import_node_fs10.existsSync)(cliNodeModules)) {
+      const tmpDirRaw = (0, import_node_path15.join)((0, import_node_os2.tmpdir)(), `atelier-studio-${tmpId}`);
+      (0, import_node_fs16.mkdirSync)(tmpDirRaw, { recursive: true });
+      const tmpDir = (0, import_node_fs16.realpathSync)(tmpDirRaw);
+      (0, import_node_fs16.writeFileSync)((0, import_node_path15.join)(tmpDir, "index.html"), getInlineHTML());
+      (0, import_node_fs16.writeFileSync)((0, import_node_path15.join)(tmpDir, "main.ts"), getInlineApp(file ?? null, cliPackageDir));
+      const cliNodeModules = (0, import_node_path15.join)(cliPackageDir, "node_modules");
+      if ((0, import_node_fs16.existsSync)(cliNodeModules)) {
         try {
-          (0, import_node_fs10.symlinkSync)(cliNodeModules, (0, import_node_path10.join)(tmpDir, "node_modules"), "dir");
+          (0, import_node_fs16.symlinkSync)(cliNodeModules, (0, import_node_path15.join)(tmpDir, "node_modules"), "dir");
         } catch {
         }
       }
-      console.log(`Starting Atelier Studio...`);
       console.log(`  Working directory: ${cwd}`);
       let vite;
       try {
@@ -4304,9 +6054,42 @@ function studioCommand(program2) {
         process.exit(1);
         return;
       }
+      const HOSTNAME = "127.0.0.1";
+      const bridgeState = {
+        store: new import_atelier_mcp.DocumentStore(),
+        currentDocId: null
+      };
+      const bridgeClients = /* @__PURE__ */ new Set();
+      const loadDocFromDisk = (docId) => {
+        if (!isSafePath(docId)) return null;
+        try {
+          return (0, import_node_fs16.readFileSync)((0, import_node_path15.resolve)(cwd, docId), "utf-8");
+        } catch {
+          return null;
+        }
+      };
+      const persistHumanPatch = (docId, doc) => {
+        if (!isSafePath(docId)) return;
+        writeFileEnsuringDir((0, import_node_path15.resolve)(cwd, docId), serializeAtelier(doc));
+      };
+      bridgeState.store.onChange((id, doc, source) => {
+        if (!shouldBroadcastMutation(source)) return;
+        if (doc === null) return;
+        try {
+          persistHumanPatch(id, doc);
+        } catch {
+        }
+        broadcastToBridge(bridgeClients, {
+          type: "llm:mutation",
+          documentId: id,
+          doc,
+          source
+        });
+      });
       const server = await vite.createServer({
         root: tmpDir,
         server: {
+          host: HOSTNAME,
           port,
           strictPort: false,
           fs: {
@@ -4317,8 +6100,21 @@ function studioCommand(program2) {
           {
             name: "atelier-api",
             configureServer(server2) {
+              const allowedOrigins = /* @__PURE__ */ new Set([
+                `http://localhost:${port}`,
+                `http://127.0.0.1:${port}`
+              ]);
+              const MUTATING = /* @__PURE__ */ new Set(["POST", "PUT", "DELETE", "PATCH"]);
               server2.middlewares.use((req, res, next) => {
-                const url2 = new URL(req.url ?? "/", `http://localhost:${port}`);
+                const url2 = new URL(req.url ?? "/", `http://${HOSTNAME}:${port}`);
+                if (req.method && MUTATING.has(req.method) && url2.pathname.startsWith("/api/")) {
+                  const origin = req.headers.origin;
+                  if (!origin || !allowedOrigins.has(origin)) {
+                    res.statusCode = 403;
+                    res.end("Forbidden: cross-origin mutating request rejected");
+                    return;
+                  }
+                }
                 if (url2.pathname === "/api/files") {
                   const atelierFiles2 = findAtelierFiles(cwd);
                   const entries = atelierFiles2.map((p) => {
@@ -4340,10 +6136,15 @@ function studioCommand(program2) {
                     res.end("Invalid path");
                     return;
                   }
-                  const absPath = (0, import_node_path10.resolve)(cwd, filePath);
+                  const absPath = (0, import_node_path15.resolve)(cwd, filePath);
                   if (req.method === "GET") {
                     try {
-                      const content = (0, import_node_fs10.readFileSync)(absPath, "utf-8");
+                      const content = (0, import_node_fs16.readFileSync)(absPath, "utf-8");
+                      const parsed = parseAtelier(content);
+                      if (parsed.success) {
+                        bridgeState.store.set(filePath, parsed.data, "system");
+                        bridgeState.currentDocId = filePath;
+                      }
                       res.setHeader("Content-Type", "text/plain");
                       res.end(content);
                     } catch {
@@ -4359,11 +6160,17 @@ function studioCommand(program2) {
                     });
                     req.on("end", () => {
                       try {
-                        (0, import_node_fs10.writeFileSync)(absPath, body, "utf-8");
+                        writeFileEnsuringDir(absPath, body);
+                        const parsed = parseAtelier(body);
+                        if (parsed.success) {
+                          bridgeState.store.set(filePath, parsed.data, "human");
+                          bridgeState.currentDocId = filePath;
+                        }
                         res.end("OK");
-                      } catch {
+                      } catch (e) {
+                        const msg = e instanceof Error ? e.message : String(e);
                         res.statusCode = 500;
-                        res.end("Write failed");
+                        res.end(msg);
                       }
                     });
                     return;
@@ -4376,19 +6183,20 @@ function studioCommand(program2) {
                     res.end("Invalid path");
                     return;
                   }
-                  const absPath = (0, import_node_path10.resolve)(cwd, filePath);
+                  const absPath = (0, import_node_path15.resolve)(cwd, filePath);
                   const chunks = [];
                   req.on("data", (chunk) => {
                     chunks.push(chunk);
                   });
                   req.on("end", () => {
                     try {
-                      (0, import_node_fs10.mkdirSync)((0, import_node_path10.dirname)(absPath), { recursive: true });
-                      (0, import_node_fs10.writeFileSync)(absPath, Buffer.concat(chunks));
+                      (0, import_node_fs16.mkdirSync)((0, import_node_path15.dirname)(absPath), { recursive: true });
+                      (0, import_node_fs16.writeFileSync)(absPath, Buffer.concat(chunks));
                       res.end("OK");
-                    } catch {
+                    } catch (e) {
+                      const msg = e instanceof Error ? e.message : String(e);
                       res.statusCode = 500;
-                      res.end("Write failed");
+                      res.end(msg);
                     }
                   });
                   return;
@@ -4406,6 +6214,51 @@ function studioCommand(program2) {
         logLevel: "warn"
       });
       await server.listen();
+      const httpServer = server.httpServer;
+      if (httpServer) {
+        const wssBridge = new import_ws.WebSocketServer({ noServer: true });
+        const wssMcp = new import_ws.WebSocketServer({ noServer: true });
+        httpServer.on("upgrade", (req, socket, head) => {
+          const url2 = new URL(req.url ?? "/", `http://${HOSTNAME}:${port}`);
+          if (url2.pathname !== "/bridge" && url2.pathname !== "/mcp") return;
+          const origin = req.headers.origin;
+          const originOk = url2.pathname === "/mcp" ? isAllowedMcpOrigin(origin, port) : isAllowedOrigin(origin, port);
+          if (!originOk) {
+            socket.write("HTTP/1.1 403 Forbidden\r\n\r\n");
+            socket.destroy();
+            return;
+          }
+          if (url2.pathname === "/bridge") {
+            wssBridge.handleUpgrade(req, socket, head, (ws) => {
+              wssBridge.emit("connection", ws, req);
+            });
+            return;
+          }
+          wssMcp.handleUpgrade(req, socket, head, (ws) => {
+            wssMcp.emit("connection", ws, req);
+          });
+        });
+        wssBridge.on("connection", (ws) => {
+          attachBridgeClient(
+            ws,
+            bridgeState,
+            bridgeClients,
+            loadDocFromDisk,
+            persistHumanPatch
+          );
+        });
+        wssMcp.on("connection", (ws) => {
+          const { server: mcpServer } = (0, import_atelier_mcp.createServer)(bridgeState.store);
+          const transport = new import_atelier_mcp.WebSocketServerTransport(ws);
+          mcpServer.connect(transport).catch((err) => {
+            console.error("MCP-over-WS connect failed:", err);
+            try {
+              ws.close();
+            } catch {
+            }
+          });
+        });
+      }
       const resolvedUrl = server.resolvedUrls?.local[0] ?? `http://localhost:${port}`;
       const url = resolvedUrl;
       console.log(`  Server running at: ${url}`);
@@ -4417,13 +6270,13 @@ function studioCommand(program2) {
       console.log(`  Press Ctrl+C to stop
 `);
       if (options.open) {
-        (0, import_node_child_process2.exec)(`open "${url}"`);
+        (0, import_node_child_process4.exec)(`open "${url}"`);
       }
       const cleanup = () => {
         console.log("\nShutting down...");
         server.close();
         try {
-          (0, import_node_fs10.rmSync)(tmpDir, { recursive: true, force: true });
+          (0, import_node_fs16.rmSync)(tmpDir, { recursive: true, force: true });
         } catch {
         }
         process.exit(0);
@@ -4440,11 +6293,19 @@ var program = new import_commander.Command();
 program.name("atelier").description("Atelier animation CLI").version((0, import_node_module.createRequire)(import_meta2.url)("../package.json").version);
 validateCommand(program);
 lintCommand(program);
+trimCommand(program);
+transcribeCommand(program);
+transcriptCommand(program);
+captionsCommand(program);
+recipeCommand(program);
+applyRecipeCommand(program);
+carouselCommand(program);
 infoCommand(program);
 stillCommand(program);
 renderCommand(program);
 exportSvgCommand(program);
 exportLottieCommand(program);
+exportImageCommand(program);
 assetsCommand(program);
 variablesCommand(program);
 studioCommand(program);