@liustack/pptfast 0.1.0 → 0.4.0

package/dist/cli.js

@@ -1,58 +1,153 @@
 #!/usr/bin/env node
 import {
-  PptfastError,
+  PptxIRV3Schema,
   VERSION,
+  assembleDeck,
+  disassembleDeck,
+  formatInvalidSpecError,
+  migrateDeckPlanToSpec,
+  migrateIrV3ToV4,
+  resolveSpecThemeId,
+  specJsonSchema,
+  validateSpec
+} from "./chunk-4W2YZPJJ.js";
+import {
+  installNodePlatform
+} from "./chunk-HFRNKYZ6.js";
+import {
+  AUDIENCE_VALUES,
+  NARRATIVE_PRESETS,
+  PACING_BUDGETS,
+  PptfastError,
+  STRATEGY_DEFINITIONS,
+  StyleOverrideSchema,
+  auditDeck,
   formatIssues,
   generatePptx,
+  getInstalledThemeIds,
   irJsonSchema,
   listThemes,
   renderSlideSvg,
+  resolveNarrative,
+  styleJsonSchema,
   validateIr
-} from "./chunk-DVMJWFDL.js";
-import {
-  installNodePlatform
-} from "./chunk-4WISUDXE.js";
+} from "./chunk-7N4HGSMW.js";
 import {
   getPlatform
-} from "./chunk-G76EVNVT.js";
+} from "./chunk-L524YK63.js";
 
 // src/cli.ts
 import { Command } from "commander";
 
 // src/cli/commands.ts
-import { mkdir, writeFile } from "fs/promises";
-import { dirname, join, resolve as resolve2 } from "path";
+import { mkdir as mkdir2, rm, writeFile as writeFile2 } from "fs/promises";
+import { dirname as dirname2, join as join4, relative as relative2, resolve as resolve5 } from "path";
 
-// src/cli/load-ir.ts
+// src/cli/config.ts
 import { readFile } from "fs/promises";
-import { extname, isAbsolute, resolve } from "path";
+import { dirname, join as join2, resolve as resolve2 } from "path";
+import { z } from "zod";
+
+// src/cli/home.ts
+import { homedir } from "os";
+import { join, resolve } from "path";
+function pptfastHome() {
+  return process.env.PPTFAST_HOME ?? join(homedir(), ".pptfast");
+}
+function decksRoot(config) {
+  return resolve(pptfastHome(), config?.decksDir ?? "decks");
+}
+function userConfigPath() {
+  return join(pptfastHome(), "config.json");
+}
+
+// src/cli/config.ts
+var ConfigSchema = z.object({
+  theme: z.string().optional(),
+  style: StyleOverrideSchema.optional(),
+  decksDir: z.string().optional()
+}).strict();
+var UserConfigSchema = z.object({
+  theme: z.string().optional(),
+  style: StyleOverrideSchema.optional(),
+  decksDir: z.string().optional()
+}).strict();
+var CONFIG_FILENAME = "pptfast.config.json";
+async function readConfigFile(path, schema) {
+  let text;
+  try {
+    text = await readFile(path, "utf8");
+  } catch {
+    return null;
+  }
+  let raw;
+  try {
+    raw = JSON.parse(text);
+  } catch (e) {
+    throw new PptfastError(`${path} is not valid JSON: ${e.message}`);
+  }
+  const r = schema.safeParse(raw);
+  if (!r.success) {
+    const detail = r.error.issues.map((i) => `${i.path.join(".") || "(root)"}: ${i.message}`).join("\n");
+    throw new PptfastError(`invalid ${path}:
+${detail}`);
+  }
+  return { path, config: r.data };
+}
+async function findConfig(startDir) {
+  let dir = resolve2(startDir);
+  for (; ; ) {
+    const hit = await readConfigFile(join2(dir, CONFIG_FILENAME), ConfigSchema);
+    if (hit) return hit;
+    const parent = dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+async function findUserConfig() {
+  return readConfigFile(userConfigPath(), UserConfigSchema);
+}
+
+// src/cli/deck-dir.ts
+import { copyFile, mkdir, readFile as readFile3, readdir, stat, writeFile } from "fs/promises";
+import { basename, extname as extname2, isAbsolute as isAbsolute2, join as join3, relative, resolve as resolve4 } from "path";
+
+// src/cli/load-ir.ts
+import { readFile as readFile2 } from "fs/promises";
+import { extname, isAbsolute, resolve as resolve3 } from "path";
 var MIME_BY_EXT = {
   ".png": "image/png",
   ".jpg": "image/jpeg",
   ".jpeg": "image/jpeg",
   ".gif": "image/gif"
 };
-async function loadIrFile(irPath) {
+var EXT_BY_MIME = {
+  "image/png": ".png",
+  "image/jpeg": ".jpg",
+  "image/gif": ".gif",
+  "image/webp": ".webp"
+};
+async function loadIrFile(irPath, kind = "IR") {
   let text;
   try {
-    text = await readFile(irPath, "utf8");
+    text = await readFile2(irPath, "utf8");
   } catch {
-    throw new PptfastError(`cannot read IR file: ${irPath}`);
+    throw new PptfastError(`cannot read ${kind} file: ${irPath}`);
   }
   try {
     return JSON.parse(text);
   } catch (e) {
-    throw new PptfastError(`${irPath} is not valid JSON: ${e.message}`);
+    throw new PptfastError(`${kind} file ${irPath} is not valid JSON: ${e.message}`);
   }
 }
 async function resolveLocalAssets(ir, baseDir) {
   for (const [name, asset] of Object.entries(ir.assets.images)) {
     const src = asset.src;
     if (src.startsWith("data:") || /^https?:\/\//.test(src)) continue;
-    const abs = isAbsolute(src) ? src : resolve(baseDir, src);
+    const abs = isAbsolute(src) ? src : resolve3(baseDir, src);
     let bytes;
     try {
-      bytes = await readFile(abs);
+      bytes = await readFile2(abs);
     } catch {
       throw new PptfastError(`asset "${name}": cannot read image file ${abs} (from src "${src}")`);
     }
@@ -71,53 +166,924 @@ async function resolveLocalAssets(ir, baseDir) {
   }
 }
 
+// src/cli/deck-dir.ts
+var PLAN_FILENAME = "deck.plan.json";
+var SPEC_FILENAME = "deck.spec.json";
+var PAGES_DIRNAME = "pages";
+var ASSETS_DIRNAME = "assets";
+function assertSafeFileSegment(id, context) {
+  const safeBase = resolve4("/pptfast-safe-base");
+  const rel = relative(safeBase, resolve4(safeBase, id));
+  const safe = !isAbsolute2(id) && !id.includes("/") && !id.includes("\\") && id !== ".." && !rel.startsWith("..") && !isAbsolute2(rel);
+  if (!safe) {
+    throw new PptfastError(
+      `${context} "${id}" is not a safe file name \u2014 ids used as page/asset file names must not contain path separators or ".."`
+    );
+  }
+}
+async function isDeckDirectory(path) {
+  try {
+    return (await stat(path)).isDirectory();
+  } catch (e) {
+    if (e.code === "ENOENT") return false;
+    throw new PptfastError(`cannot check ${path}: ${e.message}`);
+  }
+}
+async function pathExists(path) {
+  try {
+    await stat(path);
+    return true;
+  } catch (e) {
+    if (e.code === "ENOENT") return false;
+    throw new PptfastError(`cannot check path ${path}: ${e.message}`);
+  }
+}
+async function resolveDeckTarget(arg, config, cwd = process.cwd()) {
+  if (arg.trim() === "") throw new PptfastError("deck target must not be empty");
+  if (arg.includes("/") || arg.includes("\\")) return resolve4(cwd, arg);
+  const local = resolve4(cwd, arg);
+  if (await pathExists(local)) return local;
+  const fallback = join3(decksRoot(config), arg);
+  return await pathExists(fallback) ? fallback : local;
+}
+function expectedLayoutHint() {
+  const rows = [
+    [SPEC_FILENAME, "the locked spec (see `pptfast spec validate`)"],
+    [`${PAGES_DIRNAME}/<page-id>.json`, "one file per filled page (missing pages become placeholders)"],
+    [`${ASSETS_DIRNAME}/`, "optional local images"]
+  ];
+  const width = Math.max(...rows.map(([name]) => name.length)) + 2;
+  return rows.map(([name, desc]) => `  ${name.padEnd(width)}${desc}`).join("\n");
+}
+async function readSpecFile(dir) {
+  const specPath = join3(dir, SPEC_FILENAME);
+  const planPath = join3(dir, PLAN_FILENAME);
+  const [specExists, planExists] = await Promise.all([pathExists(specPath), pathExists(planPath)]);
+  if (specExists && planExists) {
+    throw new PptfastError(
+      `both ${SPEC_FILENAME} and ${PLAN_FILENAME} exist in ${dir} \u2014 ambiguous, refusing to guess which one wins. Delete ${PLAN_FILENAME} once you have confirmed ${SPEC_FILENAME} is correct (\`pptfast migrate\` never deletes the source file it read)`
+    );
+  }
+  if (!specExists && planExists) {
+    throw new PptfastError(
+      `${dir} has ${PLAN_FILENAME} but no ${SPEC_FILENAME} \u2014 deck project directories now use ${SPEC_FILENAME}. Run \`pptfast migrate ${dir} -o ${dir}\` to convert it`
+    );
+  }
+  let text;
+  try {
+    text = await readFile3(specPath, "utf8");
+  } catch (e) {
+    if (e.code === "ENOENT") {
+      throw new PptfastError(
+        `no ${SPEC_FILENAME} in ${dir} \u2014 expected a deck project directory:
+${expectedLayoutHint()}`
+      );
+    }
+    throw new PptfastError(`cannot read spec file: ${specPath}`);
+  }
+  try {
+    return JSON.parse(text);
+  } catch (e) {
+    throw new PptfastError(`spec file ${specPath} is not valid JSON: ${e.message}`);
+  }
+}
+async function readPages(dir) {
+  const pagesDir = join3(dir, PAGES_DIRNAME);
+  let entries;
+  try {
+    entries = (await readdir(pagesDir, { withFileTypes: true })).filter((entry) => entry.isFile() && extname2(entry.name) === ".json").map((entry) => entry.name);
+  } catch (e) {
+    if (e.code === "ENOENT") return {};
+    throw new PptfastError(`cannot read ${PAGES_DIRNAME}/ directory ${pagesDir}: ${e.message}`);
+  }
+  const pages = {};
+  await Promise.all(
+    entries.map(async (entry) => {
+      const id = basename(entry, ".json");
+      pages[id] = await loadIrFile(join3(pagesDir, entry), `page "${id}"`);
+    })
+  );
+  return pages;
+}
+async function scanAssets(dir) {
+  const assetsDir = join3(dir, ASSETS_DIRNAME);
+  let entries;
+  try {
+    entries = (await readdir(assetsDir, { withFileTypes: true })).filter((entry) => entry.isFile() && !entry.name.startsWith(".")).map((entry) => entry.name);
+  } catch (e) {
+    if (e.code === "ENOENT") return {};
+    throw new PptfastError(`cannot read ${ASSETS_DIRNAME}/ directory ${assetsDir}: ${e.message}`);
+  }
+  const images = {};
+  const sourceFile = /* @__PURE__ */ new Map();
+  for (const entry of entries) {
+    const id = basename(entry, extname2(entry));
+    const previous = sourceFile.get(id);
+    if (previous !== void 0) {
+      throw new PptfastError(
+        `${ASSETS_DIRNAME}/${previous} and ${ASSETS_DIRNAME}/${entry} both register image id "${id}" \u2014 rename one of the files`
+      );
+    }
+    sourceFile.set(id, entry);
+    images[id] = { src: `${ASSETS_DIRNAME}/${entry}` };
+  }
+  return images;
+}
+async function readDeckDir(dir) {
+  const deckDir = resolve4(dir);
+  const spec2 = await readSpecFile(deckDir);
+  const pages = await readPages(deckDir);
+  const { ir, generatedSeed, materializedLayoutCount } = assembleDeck(spec2, pages);
+  const images = await scanAssets(deckDir);
+  const merged = { ...ir, assets: { images: { ...ir.assets.images, ...images } } };
+  return { ir: merged, generatedSeed, materializedLayoutCount, deckDir };
+}
+async function writeDeckAssets(images, outDir, sourceBaseDir) {
+  const entries = Object.entries(images);
+  const assetsDir = join3(outDir, ASSETS_DIRNAME);
+  if (entries.length === 0) return { count: 0, assetsDir };
+  await mkdir(assetsDir, { recursive: true });
+  await Promise.all(entries.map(([id, asset]) => writeOneAsset(id, asset.src, assetsDir, sourceBaseDir)));
+  return { count: entries.length, assetsDir };
+}
+var DATA_URI_RE = /^data:([^;,]+);base64,(.*)$/s;
+async function writeOneAsset(id, src, assetsDir, sourceBaseDir) {
+  assertSafeFileSegment(id, "asset id");
+  if (src.startsWith("data:")) {
+    const match = DATA_URI_RE.exec(src);
+    if (!match) {
+      throw new PptfastError(`asset "${id}": only base64-encoded data URIs can be disassembled (malformed data URI)`);
+    }
+    const mime = match[1];
+    const payload = match[2];
+    const ext = EXT_BY_MIME[mime];
+    if (!ext) {
+      throw new PptfastError(
+        `asset "${id}": cannot disassemble a data URI with mime "${mime}" \u2014 expected one of ${Object.keys(EXT_BY_MIME).join(", ")}`
+      );
+    }
+    await writeFile(join3(assetsDir, `${id}${ext}`), Buffer.from(payload, "base64"));
+    return;
+  }
+  if (/^https?:\/\//.test(src)) {
+    throw new PptfastError(
+      `asset "${id}": URL assets cannot be disassembled into a deck directory \u2014 inline it as a data URI or download it first`
+    );
+  }
+  const abs = isAbsolute2(src) ? src : resolve4(sourceBaseDir, src);
+  try {
+    await copyFile(abs, join3(assetsDir, `${id}${extname2(abs)}`));
+  } catch {
+    throw new PptfastError(`asset "${id}": cannot read source image ${abs} (from src "${src}") \u2014 cannot disassemble`);
+  }
+}
+
+// src/cli/preview-html.ts
+function escapeHtml(s) {
+  return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&#39;");
+}
+function embedJson(value) {
+  return JSON.stringify(value).replace(/</g, "\\u003c");
+}
+function findingBadge(count, className) {
+  if (count === 0) return "";
+  return `<div class="${className}" aria-hidden="true">${count}</div>`;
+}
+function slideNode(slide, findingCount) {
+  const idAttr = slide.id !== void 0 ? ` data-id="${escapeHtml(slide.id)}"` : "";
+  const badge = slide.placeholder ? `<div class="pf-badge" aria-hidden="true">unfilled</div>` : "";
+  const fBadge = findingBadge(findingCount, "pf-finding-badge");
+  return `<div class="pf-slide" id="pf-slide-${slide.index}" data-index="${slide.index}"${idAttr}>${badge}${fBadge}${slide.svg}</div>`;
+}
+function thumbDescription(slide) {
+  const parts = [`slide ${slide.index + 1}`, slide.type];
+  if (slide.id !== void 0) parts.push(slide.id);
+  if (slide.placeholder) parts.push("unfilled");
+  return escapeHtml(parts.join(" \xB7 "));
+}
+function positionLabel(slide) {
+  const idPart = slide.id !== void 0 ? ` \xB7 ${slide.id}` : "";
+  return escapeHtml(`${slide.index + 1}${idPart}`);
+}
+function counterText(slide, total) {
+  const idPart = slide.id !== void 0 ? ` \xB7 ${slide.id}` : "";
+  return escapeHtml(`${slide.index + 1} / ${total}${idPart}`);
+}
+function thumbButton(slide, isActive, slotContent, findingCount) {
+  const description = thumbDescription(slide);
+  const badge = slide.placeholder ? `<span class="pf-thumb-badge" aria-hidden="true">unfilled</span>` : "";
+  const fBadge = findingBadge(findingCount, "pf-thumb-finding-badge");
+  return `<button type="button" class="pf-thumb${isActive ? " pf-thumb-active" : ""}" id="pf-thumb-${slide.index}" data-index="${slide.index}" title="${description}" aria-label="${description}"><span class="pf-thumb-slot" id="pf-slot-${slide.index}">${slotContent}</span><span class="pf-thumb-label">${positionLabel(slide)}</span>${badge}${fBadge}</button>`;
+}
+function findingPanelEntry(f) {
+  const idPart = f.slideId !== void 0 ? ` \xB7 ${escapeHtml(f.slideId)}` : "";
+  return `<button type="button" class="pf-finding" data-page-index="${f.page - 1}"><span class="pf-finding-loc">page ${f.page}${idPart}</span><span class="pf-finding-code">[${escapeHtml(f.code)}]</span> <span class="pf-finding-msg">${escapeHtml(f.message)}</span></button>`;
+}
+var CSS = `
+:root{color-scheme:light}
+*{box-sizing:border-box}
+html,body{height:100%;margin:0}
+body{display:flex;flex-direction:column;font-family:-apple-system,BlinkMacSystemFont,"Segoe UI",Helvetica,Arial,sans-serif;background:#f4f4f4;color:#1a1a1a}
+header{display:flex;align-items:center;justify-content:space-between;gap:12px;padding:10px 16px;background:#fff;border-bottom:1px solid #ddd;font-size:14px;flex:0 0 auto}
+#pf-title{font-weight:600;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}
+#pf-counter{font-variant-numeric:tabular-nums;color:#555;white-space:nowrap}
+#pf-audit-note{color:#b45309;font-size:12px;white-space:nowrap;overflow:hidden;text-overflow:ellipsis}
+#pf-export-btn{font:inherit;font-size:13px;padding:6px 10px;border:1px solid #2563eb;background:#2563eb;color:#fff;border-radius:4px;cursor:pointer;white-space:nowrap;flex:0 0 auto}
+#pf-export-btn:hover{background:#1d4ed8}
+#pf-stage-wrap{flex:1 1 auto;min-height:0;display:flex;align-items:center;justify-content:center;gap:16px;padding:16px}
+#pf-stage{position:relative;background:#000;box-shadow:0 2px 16px rgba(0,0,0,.15);aspect-ratio:16/9;width:min(100%,calc((100vh - 190px) * 16 / 9));max-height:100%}
+#pf-stage,.pf-thumb-slot{position:relative}
+.pf-slide{position:absolute;inset:0}
+.pf-slide svg{display:block;width:100%;height:100%}
+#pf-side{flex:0 0 260px;align-self:stretch;overflow-y:auto;background:#fff;border:1px solid #ddd;border-radius:6px;padding:12px;font-size:13px}
+#pf-side h2{margin:0 0 8px;font-size:11px;text-transform:uppercase;letter-spacing:.04em;color:#666}
+#pf-side section+section{margin-top:16px;padding-top:16px;border-top:1px solid #eee}
+#pf-audit-checks{margin:0 0 12px;font-size:12px;color:#555}
+.pf-finding{display:block;width:100%;text-align:left;background:#fff;border:1px solid #eee;border-radius:4px;padding:6px 8px;margin-bottom:6px;cursor:pointer;font:inherit}
+.pf-finding:hover{border-color:#93c5fd}
+.pf-finding-loc{display:block;font-size:11px;color:#888}
+.pf-finding-code{display:inline-block;font-size:11px;font-weight:700;color:#b91c1c}
+.pf-finding-msg{font-size:12px;color:#333}
+#pf-annotate-current-label{font-size:11px;color:#888;margin-bottom:6px}
+#pf-annotate-list{list-style:none;margin:0 0 8px;padding:0}
+.pf-annotate-item{display:flex;justify-content:space-between;gap:6px;align-items:flex-start;padding:4px 0;border-bottom:1px solid #f0f0f0;font-size:12px}
+.pf-annotate-remove{border:none;background:none;color:#999;cursor:pointer;font-size:14px;line-height:1;padding:0 2px}
+.pf-annotate-remove:hover{color:#dc2626}
+#pf-annotate-input{width:100%;box-sizing:border-box;font:inherit;font-size:12px;padding:6px;border:1px solid #ddd;border-radius:4px;resize:vertical}
+#pf-annotate-add{font:inherit;font-size:12px;margin-top:6px;width:100%;padding:6px 10px;border:1px solid #2563eb;background:#2563eb;color:#fff;border-radius:4px;cursor:pointer}
+#pf-annotate-add:hover{background:#1d4ed8}
+#pf-filmstrip{display:flex;gap:8px;padding:10px 16px;overflow-x:auto;background:#fff;border-top:1px solid #ddd;flex:0 0 auto}
+.pf-thumb{flex:0 0 auto;width:160px;padding:0;margin:0;border:2px solid transparent;background:#eee;cursor:pointer;border-radius:6px;overflow:hidden;position:relative;font:inherit;text-align:left}
+.pf-thumb:hover{border-color:#93c5fd}
+.pf-thumb-active,.pf-thumb-active:hover{border-color:#2563eb;background:#dbeafe}
+.pf-thumb-slot{display:block;width:100%;aspect-ratio:16/9;background:#ddd}
+.pf-thumb-label{display:block;font-size:11px;line-height:1.4;padding:3px 6px;color:#444;white-space:nowrap;overflow:hidden;text-overflow:ellipsis}
+.pf-badge,.pf-thumb-badge{position:absolute;top:4px;right:4px;background:#d97706;color:#fff;font-size:10px;font-weight:700;letter-spacing:.03em;padding:2px 6px;border-radius:3px;text-transform:uppercase;z-index:2;pointer-events:none}
+.pf-finding-badge,.pf-thumb-finding-badge{position:absolute;top:4px;left:4px;background:#dc2626;color:#fff;font-size:10px;font-weight:700;padding:2px 6px;border-radius:3px;z-index:2;pointer-events:none}
+`.trim();
+var JS = `
+(function () {
+  var stage = document.getElementById('pf-stage')
+  var counter = document.getElementById('pf-counter')
+  var thumbs = Array.prototype.slice.call(document.querySelectorAll('.pf-thumb'))
+  var total = thumbs.length
+  if (total === 0) return
+  var current = parseInt(thumbs[0].getAttribute('data-index'), 10)
+
+  function slideEl(i) { return document.getElementById('pf-slide-' + i) }
+  function slotEl(i) { return document.getElementById('pf-slot-' + i) }
+  function thumbEl(i) { return document.getElementById('pf-thumb-' + i) }
+  function thumbPos(i) {
+    for (var t = 0; t < thumbs.length; t++) {
+      if (parseInt(thumbs[t].getAttribute('data-index'), 10) === i) return t
+    }
+    return -1
+  }
+
+  function updateCounter(i) {
+    var el = slideEl(i)
+    if (!el) return
+    var text = (thumbPos(i) + 1) + ' / ' + total
+    var id = el.getAttribute('data-id')
+    if (id) text += ' \xB7 ' + id
+    counter.textContent = text
+  }
+
+  function activate(i) {
+    if (i === current) return
+    var nextSlide = slideEl(i)
+    var nextThumb = thumbEl(i)
+    if (!nextSlide || !nextThumb) return
+    var prevSlide = slideEl(current)
+    var prevSlot = slotEl(current)
+    if (prevSlide && prevSlot) prevSlot.appendChild(prevSlide)
+    var prevThumb = thumbEl(current)
+    if (prevThumb) prevThumb.classList.remove('pf-thumb-active')
+    stage.appendChild(nextSlide)
+    nextThumb.classList.add('pf-thumb-active')
+    current = i
+    updateCounter(i)
+    renderAnnotations()
+  }
+
+  thumbs.forEach(function (t) {
+    t.addEventListener('click', function () {
+      activate(parseInt(t.getAttribute('data-index'), 10))
+    })
+  })
+
+  document.addEventListener('keydown', function (e) {
+    var pos = thumbPos(current)
+    if (e.key === 'ArrowRight' && pos < total - 1) {
+      activate(parseInt(thumbs[pos + 1].getAttribute('data-index'), 10))
+    } else if (e.key === 'ArrowLeft' && pos > 0) {
+      activate(parseInt(thumbs[pos - 1].getAttribute('data-index'), 10))
+    }
+  })
+
+  // ---- audit findings panel: click a finding, jump to its page (same
+  // activate() every thumbnail click already uses) ----
+  Array.prototype.slice.call(document.querySelectorAll('.pf-finding')).forEach(function (b) {
+    b.addEventListener('click', function () {
+      activate(parseInt(b.getAttribute('data-page-index'), 10))
+    })
+  })
+
+  // ---- annotations: in-memory only, keyed by the slide's 0-based array
+  // index (current) \u2014 never by pageId, since an object key coerces every
+  // key to a string and would silently collide a numeric page-fallback
+  // pageId with a same-looking slide id (or lose the numeric/string type
+  // distinction the exported JSON needs); pageIdFor() below resolves the
+  // real pageId fresh from the DOM only at render/export time. ----
+  var annotations = {}
+  var annotateList = document.getElementById('pf-annotate-list')
+  var annotateInput = document.getElementById('pf-annotate-input')
+  var annotateLabel = document.getElementById('pf-annotate-current-label')
+  var annotateAdd = document.getElementById('pf-annotate-add')
+  var exportBtn = document.getElementById('pf-export-btn')
+
+  // Slide id when the active slide has one, else its 1-based page number \u2014
+  // mirrors AuditFinding.page's own "1-based page number when there is no
+  // slide id" convention (../svg/audit/deck-audit.ts) rather than this
+  // file's internal 0-based data-index, so a revision-request.json's
+  // pageId lines up with what pptfast audit/validate already print.
+  function pageIdFor(i) {
+    var el = slideEl(i)
+    var id = el ? el.getAttribute('data-id') : null
+    return id !== null ? id : thumbPos(i) + 1
+  }
+
+  function renderAnnotations() {
+    var pid = pageIdFor(current)
+    annotateLabel.textContent = 'page ' + (thumbPos(current) + 1) + (typeof pid === 'string' ? ' \xB7 ' + pid : '')
+    var list = annotations[current] || []
+    annotateList.innerHTML = ''
+    list.forEach(function (text, idx) {
+      var li = document.createElement('li')
+      li.className = 'pf-annotate-item'
+      var span = document.createElement('span')
+      span.textContent = text
+      var rm = document.createElement('button')
+      rm.type = 'button'
+      rm.className = 'pf-annotate-remove'
+      rm.setAttribute('aria-label', 'remove annotation')
+      rm.textContent = '\\u00d7'
+      rm.addEventListener('click', function () {
+        list.splice(idx, 1)
+        renderAnnotations()
+      })
+      li.appendChild(span)
+      li.appendChild(rm)
+      annotateList.appendChild(li)
+    })
+  }
+
+  annotateAdd.addEventListener('click', function () {
+    var text = annotateInput.value.trim()
+    if (!text) return
+    if (!annotations[current]) annotations[current] = []
+    annotations[current].push(text)
+    annotateInput.value = ''
+    renderAnnotations()
+  })
+
+  // "Export revision requests": preview.html stays read-only end to end \u2014
+  // this never writes back into the deck itself, only produces a JSON file
+  // of requests for an agent/human to route through pages/*.json (see
+  // skills/pptfast/SKILL.md's phase-6 revision-request handling). Zero
+  // network/storage \u2014 an in-memory Blob + a synthetic <a download> click,
+  // the standard browser-only download pattern.
+  exportBtn.addEventListener('click', function () {
+    var requests = []
+    Object.keys(annotations).forEach(function (key) {
+      var i = parseInt(key, 10)
+      var pid = pageIdFor(i)
+      annotations[i].forEach(function (text) {
+        requests.push({ pageId: pid, annotation: text, createdAt: new Date().toISOString() })
+      })
+    })
+    var deckTitle = document.getElementById('pf-title').textContent
+    var payload = { version: '1', deck: deckTitle, requests: requests }
+    var blob = new Blob([JSON.stringify(payload, null, 2)], { type: 'application/json' })
+    var url = URL.createObjectURL(blob)
+    var a = document.createElement('a')
+    a.href = url
+    a.download = 'revision-request.json'
+    document.body.appendChild(a)
+    a.click()
+    document.body.removeChild(a)
+    URL.revokeObjectURL(url)
+  })
+
+  renderAnnotations()
+})()
+`.trim();
+var ANNOTATE_PANEL = `<section id="pf-annotate-panel">
+<h2>Annotations</h2>
+<div id="pf-annotate-current-label"></div>
+<ul id="pf-annotate-list"></ul>
+<textarea id="pf-annotate-input" rows="3" placeholder="Add a note for this page\u2026"></textarea>
+<button type="button" id="pf-annotate-add">Add annotation</button>
+</section>`;
+function buildPreviewHtml(input) {
+  const { title, slides, findings = [], auditNote, checks } = input;
+  const total = slides.length;
+  const escapedTitle = escapeHtml(title);
+  const findingsByPage = /* @__PURE__ */ new Map();
+  for (const f of findings) {
+    const list = findingsByPage.get(f.page);
+    if (list) list.push(f);
+    else findingsByPage.set(f.page, [f]);
+  }
+  const countFor = (slide) => findingsByPage.get(slide.index + 1)?.length ?? 0;
+  const stageSlide = total > 0 ? slideNode(slides[0], countFor(slides[0])) : "";
+  const thumbs = slides.map((s, i) => thumbButton(s, i === 0, i === 0 ? "" : slideNode(s, countFor(s)), countFor(s))).join("");
+  const initialCounter = total > 0 ? counterText(slides[0], total) : "0 / 0";
+  const auditPanel = findings.length > 0 ? `<section id="pf-audit-panel"><h2>Audit findings (${findings.length})</h2><div id="pf-audit-list">${findings.map(findingPanelEntry).join("")}</div></section>` : "";
+  const findingsDataScript = findings.length > 0 ? `<script type="application/json" id="pf-audit-findings">${embedJson(findings)}</script>` : "";
+  const auditNoteHtml = auditNote !== void 0 ? `<span id="pf-audit-note">${escapeHtml(auditNote)}</span>` : "";
+  const checksLine = checks !== void 0 ? `<div id="pf-audit-checks">audit checks: svg ${checks.svg} \xB7 pixels ${checks.pixels}</div>` : "";
+  return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>${escapedTitle} \u2014 pptfast preview</title>
+<style>${CSS}</style>
+</head>
+<body>
+<header>
+<span id="pf-title">${escapedTitle}</span>
+<span id="pf-counter">${initialCounter}</span>
+${auditNoteHtml}
+<button type="button" id="pf-export-btn">Export revision requests</button>
+</header>
+<div id="pf-stage-wrap"><div id="pf-stage">${stageSlide}</div><aside id="pf-side">${checksLine}${auditPanel}${ANNOTATE_PANEL}</aside></div>
+<nav id="pf-filmstrip" aria-label="slides">${thumbs}</nav>
+${findingsDataScript}
+<script>${JS}</script>
+</body>
+</html>
+`;
+}
+
 // src/cli/commands.ts
-async function runRender(irPath, opts) {
-  const raw = await loadIrFile(irPath);
-  if (opts.theme && typeof raw === "object" && raw !== null) {
-    ;
-    raw.theme = { id: opts.theme };
+async function loadStyleFile(path) {
+  const raw = await loadIrFile(path);
+  const r = StyleOverrideSchema.safeParse(raw);
+  if (!r.success) {
+    const detail = r.error.issues.map((i) => `${i.path.join(".") || "(root)"}: ${i.message}`).join("\n");
+    throw new PptfastError(`invalid style file ${path}:
+${detail}`);
+  }
+  return r.data;
+}
+function describeThemeSource(opts, projectHit, userHit) {
+  if (opts.theme !== void 0) return "--theme";
+  if (projectHit?.config.theme !== void 0) return projectHit.path;
+  if (userHit?.config.theme !== void 0) return userHit.path;
+  return "the deck's own theme";
+}
+function resolveDecksDirSource(projectHit, userHit) {
+  if (projectHit?.config.decksDir !== void 0) {
+    return { decksDir: resolve5(dirname2(projectHit.path), projectHit.config.decksDir) };
+  }
+  return userHit?.config;
+}
+async function applyDeckConfig(raw, opts) {
+  if (typeof raw !== "object" || raw === null) return;
+  const deck = raw;
+  const irTheme = typeof deck.theme === "object" && deck.theme !== null ? deck.theme : {};
+  const [projectHit, userHit] = await Promise.all([
+    opts.projectHit !== void 0 ? Promise.resolve(opts.projectHit) : findConfig(opts.cwd),
+    opts.userHit !== void 0 ? Promise.resolve(opts.userHit) : findUserConfig()
+  ]);
+  const theme = opts.theme ?? projectHit?.config.theme ?? userHit?.config.theme ?? irTheme.id;
+  const style = opts.stylePath ? await loadStyleFile(opts.stylePath) : projectHit?.config.style ?? userHit?.config.style ?? irTheme.style;
+  if (theme !== void 0) {
+    const installedThemeIds = getInstalledThemeIds();
+    if (!installedThemeIds.includes(theme)) {
+      throw new PptfastError(
+        `unknown theme "${theme}" (from ${describeThemeSource(opts, projectHit, userHit)}) \u2014 available: ${installedThemeIds.join(", ")} (see \`pptfast themes\`)`
+      );
+    }
   }
+  if (theme === void 0 && style === void 0) return;
+  deck.theme = { ...irTheme, id: theme, ...style !== void 0 ? { style } : {} };
+}
+async function loadDeckTarget(arg, cwd, projectHit, userHit) {
+  const target = await resolveDeckTarget(arg, resolveDecksDirSource(projectHit, userHit), cwd);
+  if (await isDeckDirectory(target)) {
+    const { ir, deckDir } = await readDeckDir(target);
+    return { raw: ir, baseDir: deckDir, isDir: true };
+  }
+  const raw = await loadIrFile(target);
+  return { raw, baseDir: dirname2(resolve5(target)), isDir: false };
+}
+async function runRender(irPath, opts) {
+  const cwd = opts.cwd ?? process.cwd();
+  const [projectHit, userHit] = await Promise.all([findConfig(cwd), findUserConfig()]);
+  const { raw, baseDir } = await loadDeckTarget(irPath, cwd, projectHit, userHit);
+  await applyDeckConfig(raw, { theme: opts.theme, stylePath: opts.stylePath, cwd, projectHit, userHit });
   const v = validateIr(raw);
   if (!v.ok) throw new PptfastError(`invalid IR:
 ${formatIssues(v.errors)}`);
-  await resolveLocalAssets(v.ir, dirname(resolve2(irPath)));
-  const bytes = await generatePptx(v.ir);
-  await mkdir(dirname(resolve2(opts.output)), { recursive: true });
-  await writeFile(opts.output, bytes);
-  return `wrote ${opts.output} (${v.ir.slides.length} slides, ${bytes.length} bytes)`;
+  await resolveLocalAssets(v.ir, baseDir);
+  const bytes = await generatePptx(v.ir, { draft: opts.draft });
+  await mkdir2(dirname2(resolve5(opts.output)), { recursive: true });
+  await writeFile2(opts.output, bytes);
+  const ok = `wrote ${opts.output} (${v.ir.slides.length} slides, ${bytes.length} bytes)`;
+  const note = normalizedNote(v.normalized);
+  return note ? `${ok}
+${note}` : ok;
 }
-async function runValidate(irPath) {
-  const raw = await loadIrFile(irPath);
+function normalizedNote(normalized) {
+  if (!normalized || normalized.length === 0) return void 0;
+  const n = normalized.length;
+  return `note: ${n} field alias${n === 1 ? "" : "es"} normalized
+${normalized.map((line) => `  ${line}`).join("\n")}`;
+}
+function placeholderNote(ir) {
+  const placeholders = ir.slides.map((slide, i) => ({ slide, page: i + 1 })).filter(({ slide }) => slide.placeholder);
+  if (placeholders.length === 0) return void 0;
+  const refs = placeholders.map(({ slide, page }) => slide.id ? `${slide.id} (page ${page})` : `page ${page}`).join(", ");
+  return `note: ${placeholders.length} unfilled placeholder page${placeholders.length === 1 ? "" : "s"}: ${refs}`;
+}
+async function runValidate(irPath, cwd = process.cwd()) {
+  const [projectHit, userHit] = await Promise.all([findConfig(cwd), findUserConfig()]);
+  const { raw, isDir } = await loadDeckTarget(irPath, cwd, projectHit, userHit);
+  await applyDeckConfig(raw, { cwd, projectHit, userHit });
   const v = validateIr(raw);
   if (!v.ok)
     throw new PptfastError(
       `invalid IR (${v.errors.length} issue${v.errors.length === 1 ? "" : "s"}):
 ${formatIssues(v.errors)}`
     );
-  return `OK \u2014 ${v.ir.slides.length} slides, theme "${v.ir.theme.id}"`;
+  const ok = `OK \u2014 ${v.ir.slides.length} slides, theme "${v.ir.theme.id}"`;
+  const notes = [];
+  const aliasNote = normalizedNote(v.normalized);
+  if (aliasNote) notes.push(aliasNote);
+  if (isDir) {
+    const note = placeholderNote(v.ir);
+    if (note) notes.push(note);
+  }
+  return notes.length > 0 ? `${ok}
+${notes.join("\n")}` : ok;
+}
+function formatAuditFinding(f) {
+  const idSuffix = f.slideId !== void 0 ? ` (${f.slideId})` : "";
+  return `page ${f.page}${idSuffix}: [${f.code}] ${f.message}`;
 }
-function runSchema() {
-  return JSON.stringify(irJsonSchema(), null, 2);
+function formatAuditReport(report, ir) {
+  const lines = report.findings.map(formatAuditFinding);
+  lines.push(
+    `audited ${report.pagesAudited} page${report.pagesAudited === 1 ? "" : "s"}, ${report.pagesSkipped} skipped, ${report.findings.length} finding${report.findings.length === 1 ? "" : "s"}`
+  );
+  if (report.checks.pixels === "completed") {
+    lines.push("pixel-contrast check: completed");
+  }
+  const note = placeholderNote(ir);
+  if (note) lines.push(note);
+  return lines.join("\n");
+}
+async function runAudit(target, opts = {}) {
+  const cwd = opts.cwd ?? process.cwd();
+  const [projectHit, userHit] = await Promise.all([findConfig(cwd), findUserConfig()]);
+  const { raw, baseDir } = await loadDeckTarget(target, cwd, projectHit, userHit);
+  await applyDeckConfig(raw, { cwd, projectHit, userHit });
+  const v = validateIr(raw);
+  if (!v.ok) {
+    throw new PptfastError(
+      `invalid IR (${v.errors.length} issue${v.errors.length === 1 ? "" : "s"}):
+${formatIssues(v.errors)}`
+    );
+  }
+  await resolveLocalAssets(v.ir, baseDir);
+  const report = opts.pixels ? await auditDeck(v.ir, { pixels: true }) : auditDeck(v.ir);
+  const hasFindings = report.findings.length > 0;
+  const output = opts.json ? JSON.stringify(report, null, 2) : formatAuditReport(report, v.ir);
+  return { output, hasFindings };
+}
+async function runSpecValidate(specPath) {
+  const raw = await loadIrFile(specPath, "spec");
+  const v = validateSpec(raw);
+  if (!v.ok) {
+    throw new PptfastError(formatInvalidSpecError(v.errors));
+  }
+  const spec2 = v.spec;
+  const axes = resolveNarrative(spec2.narrative);
+  return `OK \u2014 ${spec2.pages.length} pages, narrative ${axes.strategy}/${axes.pacing}/${axes.audience}, theme "${resolveSpecThemeId(spec2)}"`;
+}
+function runSchema(mode) {
+  const schema = mode === "style" ? styleJsonSchema() : mode === "spec" ? specJsonSchema() : irJsonSchema();
+  return JSON.stringify(schema, null, 2);
 }
 function runThemes(asJson) {
   const themes = listThemes();
   if (asJson) return JSON.stringify(themes, null, 2);
   return themes.map((t) => `${t.id.padEnd(12)} ${t.label}`).join("\n");
 }
-async function runPreview(irPath, outDir) {
-  const raw = await loadIrFile(irPath);
+function runNarratives(asJson) {
+  if (asJson) {
+    return JSON.stringify(
+      {
+        presets: NARRATIVE_PRESETS,
+        strategies: STRATEGY_DEFINITIONS,
+        pacings: PACING_BUDGETS,
+        audiences: AUDIENCE_VALUES
+      },
+      null,
+      2
+    );
+  }
+  const rows = Object.values(NARRATIVE_PRESETS).map((p) => ({
+    id: p.id,
+    axes: `${p.axes.strategy}/${p.axes.pacing}/${p.axes.audience}`,
+    themes: p.themeRecommendations.join(", ")
+  }));
+  const idWidth = Math.max(...rows.map((r) => r.id.length));
+  const axesWidth = Math.max(...rows.map((r) => r.axes.length));
+  return rows.map((r) => `${r.id.padEnd(idWidth + 2)}${r.axes.padEnd(axesWidth + 2)}${r.themes}`).join("\n");
+}
+var CONFIG_TEMPLATE = {
+  theme: "consulting",
+  style: {
+    colors: { primary: "#0B5FFF", accent: "#FF6A00" }
+  }
+};
+async function runInit(cwd = process.cwd()) {
+  const target = join4(cwd, CONFIG_FILENAME);
+  try {
+    await writeFile2(target, JSON.stringify(CONFIG_TEMPLATE, null, 2) + "\n", { flag: "wx" });
+  } catch (e) {
+    if (e.code === "EEXIST") {
+      throw new PptfastError(`${target} already exists \u2014 edit it instead`);
+    }
+    throw e;
+  }
+  return `wrote ${target} \u2014 themes: \`pptfast themes\`, style schema: \`pptfast schema --style\``;
+}
+async function runPreview(irPath, outDir, opts = {}) {
+  const cwd = opts.cwd ?? process.cwd();
+  const [projectHit, userHit] = await Promise.all([findConfig(cwd), findUserConfig()]);
+  const { raw, baseDir } = await loadDeckTarget(irPath, cwd, projectHit, userHit);
+  await applyDeckConfig(raw, { cwd, projectHit, userHit });
   const v = validateIr(raw);
   if (!v.ok) throw new PptfastError(`invalid IR:
 ${formatIssues(v.errors)}`);
-  await resolveLocalAssets(v.ir, dirname(resolve2(irPath)));
-  await mkdir(outDir, { recursive: true });
+  await resolveLocalAssets(v.ir, baseDir);
+  await mkdir2(outDir, { recursive: true });
   const ir = v.ir;
+  const svgs = [];
   for (let i = 0; i < ir.slides.length; i++) {
+    const svg = renderSlideSvg(ir, i);
+    svgs.push(svg);
     const name = `${String(i + 1).padStart(3, "0")}-${ir.slides[i].type}.svg`;
-    await writeFile(join(outDir, name), renderSlideSvg(ir, i));
+    await writeFile2(join4(outDir, name), svg);
+  }
+  const ok = `wrote ${ir.slides.length} SVG files to ${outDir}`;
+  const notes = [];
+  const aliasNote = normalizedNote(v.normalized);
+  if (aliasNote) notes.push(aliasNote);
+  if (opts.htmlOut) {
+    const htmlPath = join4(outDir, "preview.html");
+    const hasPlaceholder = ir.slides.some((slide) => slide.placeholder);
+    const auditReport = hasPlaceholder ? void 0 : auditDeck(ir);
+    const auditFindings = auditReport?.findings ?? [];
+    const html = buildPreviewHtml({
+      title: ir.filename,
+      slides: ir.slides.map((slide, i) => ({
+        index: i,
+        id: slide.id,
+        type: slide.type,
+        svg: svgs[i],
+        placeholder: slide.placeholder
+      })),
+      findings: auditFindings.map((f) => ({ page: f.page, slideId: f.slideId, code: f.code, message: f.message })),
+      auditNote: hasPlaceholder ? "audit overlay skipped \u2014 deck has unfilled placeholder pages; fill every page and re-run `pptfast preview --html` to see audit findings" : void 0,
+      checks: auditReport?.checks
+    });
+    await writeFile2(htmlPath, html);
+    notes.push(`note: wrote self-contained preview to ${htmlPath}`);
+    if (auditFindings.length > 0) {
+      notes.push(`note: audit found ${auditFindings.length} finding${auditFindings.length === 1 ? "" : "s"} \u2014 see preview.html`);
+    }
   }
-  return `wrote ${ir.slides.length} SVG files to ${outDir}`;
+  return notes.length > 0 ? `${ok}
+${notes.join("\n")}` : ok;
+}
+function withRewrittenAssetPaths(ir, deckDir, outDir) {
+  const images = Object.fromEntries(
+    Object.entries(ir.assets.images).map(([id, asset]) => {
+      if (asset.src.startsWith("data:") || /^https?:\/\//.test(asset.src)) return [id, asset];
+      return [id, { ...asset, src: relative2(outDir, join4(deckDir, asset.src)) }];
+    })
+  );
+  return { ...ir, assets: { images } };
+}
+async function runAssemble(target, opts = {}) {
+  const cwd = opts.cwd ?? process.cwd();
+  const [projectHit, userHit] = await Promise.all([findConfig(cwd), findUserConfig()]);
+  const dir = await resolveDeckTarget(target, resolveDecksDirSource(projectHit, userHit), cwd);
+  if (await pathExists(dir) && !await isDeckDirectory(dir)) {
+    throw new PptfastError(`expected a deck project directory: ${dir}`);
+  }
+  const { ir, generatedSeed, materializedLayoutCount, deckDir } = await readDeckDir(dir);
+  const outPath = opts.output ? resolve5(cwd, opts.output) : join4(deckDir, "deck.json");
+  const outDir = dirname2(outPath);
+  const outIr = outDir === deckDir ? ir : withRewrittenAssetPaths(ir, deckDir, outDir);
+  await mkdir2(outDir, { recursive: true });
+  await writeFile2(outPath, JSON.stringify(outIr, null, 2) + "\n");
+  const placeholderCount = outIr.slides.filter((s) => s.placeholder).length;
+  const summary = `wrote ${outPath} (${outIr.slides.length} slides, ${placeholderCount} placeholder${placeholderCount === 1 ? "" : "s"})`;
+  const notes = [];
+  if (generatedSeed !== void 0) {
+    notes.push(`note: generated seed ${generatedSeed} \u2014 add "seed": ${generatedSeed} to deck.spec.json for revision stability`);
+  }
+  if (materializedLayoutCount !== void 0) {
+    notes.push(
+      `note: ${materializedLayoutCount} layout${materializedLayoutCount === 1 ? "" : "s"} auto-selected into deck.json \u2014 pin "layout" in a page file to lock one`
+    );
+  }
+  return [summary, ...notes].join("\n");
+}
+async function runDisassemble(irPath, outDir) {
+  const raw = await loadIrFile(irPath);
+  const v = validateIr(raw);
+  if (!v.ok) throw new PptfastError(`invalid IR:
+${formatIssues(v.errors)}`);
+  const { spec: spec2, pages } = disassembleDeck(v.ir);
+  const ids = Object.keys(pages);
+  for (const id of ids) assertSafeFileSegment(id, "slide id");
+  const specPath = join4(outDir, "deck.spec.json");
+  await mkdir2(outDir, { recursive: true });
+  try {
+    await writeFile2(specPath, JSON.stringify(spec2, null, 2) + "\n", { flag: "wx" });
+  } catch (e) {
+    if (e.code === "EEXIST") {
+      throw new PptfastError(`${specPath} already exists \u2014 refusing to overwrite an existing deck project`);
+    }
+    throw e;
+  }
+  const pagesDir = join4(outDir, "pages");
+  try {
+    if (ids.length > 0) {
+      await mkdir2(pagesDir, { recursive: true });
+      await Promise.all(
+        ids.map((id) => {
+          const content = pages[id];
+          return writeFile2(join4(pagesDir, `${id}.json`), JSON.stringify(content, null, 2) + "\n");
+        })
+      );
+    }
+    const { count: assetCount, assetsDir } = await writeDeckAssets(
+      v.ir.assets.images,
+      outDir,
+      dirname2(resolve5(irPath))
+    );
+    const pagesNote = ids.length > 0 ? `${ids.length} page file${ids.length === 1 ? "" : "s"} to ${pagesDir}` : "no pages (every slide was a placeholder)";
+    const assetsNote = assetCount > 0 ? `, and ${assetCount} asset file${assetCount === 1 ? "" : "s"} to ${assetsDir}` : "";
+    return `wrote ${specPath}, ${pagesNote}${assetsNote}`;
+  } catch (e) {
+    await rm(specPath, { force: true }).catch(() => {
+    });
+    throw e;
+  }
+}
+async function runMigrate(input, output, cwd = process.cwd()) {
+  const resolvedInput = resolve5(cwd, input);
+  if (await isDeckDirectory(resolvedInput)) {
+    return runMigrateDeckDir(resolvedInput, output, cwd);
+  }
+  return runMigrateIrFile(resolvedInput, output, cwd);
+}
+async function runMigrateDeckDir(dir, output, cwd) {
+  const planPath = join4(dir, PLAN_FILENAME);
+  const sourceSpecPath = join4(dir, SPEC_FILENAME);
+  if (!await pathExists(planPath) && await pathExists(sourceSpecPath)) {
+    throw new PptfastError(
+      `${dir} has ${SPEC_FILENAME} but no ${PLAN_FILENAME} \u2014 this deck project is already migrated, nothing to do`
+    );
+  }
+  const raw = await loadIrFile(planPath, "plan");
+  const migrated = migrateDeckPlanToSpec(raw);
+  const outDir = resolve5(cwd, output);
+  const specPath = join4(outDir, SPEC_FILENAME);
+  await mkdir2(outDir, { recursive: true });
+  try {
+    await writeFile2(specPath, JSON.stringify(migrated, null, 2) + "\n", { flag: "wx" });
+  } catch (e) {
+    if (e.code === "EEXIST") {
+      throw new PptfastError(`${specPath} already exists \u2014 refusing to overwrite, delete it first or choose a different -o`);
+    }
+    throw e;
+  }
+  return `wrote ${specPath} \u2014 run \`pptfast spec validate ${specPath}\` to confirm it, then delete ${planPath} (a directory with both files present is rejected)`;
+}
+async function runMigrateIrFile(filePath, output, cwd) {
+  const raw = await loadIrFile(filePath);
+  const version = typeof raw === "object" && raw !== null ? raw.version : void 0;
+  if (version === "2") {
+    throw new PptfastError(
+      "pptfast migrate does not support IR v2 (spec \xA715.3: v2 has no real users) \u2014 run `pptfast validate` on the v2 file to see the full v2\u2192v4 combined field mapping and rewrite it by hand"
+    );
+  }
+  if (version !== "3") {
+    throw new PptfastError(
+      `pptfast migrate only converts an IR v3 file (version: "3") or a deck project directory containing ${PLAN_FILENAME} \u2014 got version ${JSON.stringify(version)} in ${filePath}`
+    );
+  }
+  const parsed = PptxIRV3Schema.safeParse(raw);
+  if (!parsed.success) {
+    const detail = parsed.error.issues.map((issue) => `${issue.path.join(".") || "(root)"}: ${issue.message}`).join("\n");
+    throw new PptfastError(`invalid IR v3 file ${filePath}:
+${detail}`);
+  }
+  const migrated = migrateIrV3ToV4(parsed.data);
+  const outPath = resolve5(cwd, output);
+  await mkdir2(dirname2(outPath), { recursive: true });
+  try {
+    await writeFile2(outPath, JSON.stringify(migrated, null, 2) + "\n", { flag: "wx" });
+  } catch (e) {
+    if (e.code === "EEXIST") {
+      throw new PptfastError(`${outPath} already exists \u2014 refusing to overwrite, delete it first or choose a different -o`);
+    }
+    throw e;
+  }
+  return `wrote ${outPath} (migrated IR v3 \u2192 v4)`;
+}
+
+// src/cli/update.ts
+import { execFile } from "child_process";
+var PACKAGE_NAME = "@liustack/pptfast";
+function normalizeVersion(version) {
+  const normalized = version.trim().replace(/^v/i, "").split("-")[0];
+  if (!normalized) throw new Error(`invalid version: ${version}`);
+  return normalized;
+}
+function parseVersion(version) {
+  return normalizeVersion(version).split(".").map((segment) => {
+    const value = Number.parseInt(segment, 10);
+    if (!Number.isFinite(value)) throw new Error(`invalid version segment: ${segment}`);
+    return value;
+  });
+}
+function compareVersions(left, right) {
+  const l = parseVersion(left);
+  const r = parseVersion(right);
+  for (let i = 0; i < Math.max(l.length, r.length); i++) {
+    const a = l[i] ?? 0;
+    const b = r[i] ?? 0;
+    if (a !== b) return a < b ? -1 : 1;
+  }
+  return 0;
+}
+var runCommand = (command, args) => new Promise((resolve6, reject) => {
+  execFile(command, args, { encoding: "utf8" }, (error, stdout, stderr) => {
+    if (error) {
+      reject(new Error(stderr.trim() || error.message));
+      return;
+    }
+    resolve6(stdout.trim());
+  });
+});
+async function checkForUpdate({
+  currentVersion,
+  packageName = PACKAGE_NAME,
+  run = runCommand
+}) {
+  const current = normalizeVersion(currentVersion);
+  try {
+    const latest = normalizeVersion(await run("npm", ["view", packageName, "version"]));
+    return {
+      packageName,
+      currentVersion: current,
+      latestVersion: latest,
+      updateAvailable: compareVersions(current, latest) < 0,
+      checked: true
+    };
+  } catch (error) {
+    return {
+      packageName,
+      currentVersion: current,
+      latestVersion: null,
+      updateAvailable: false,
+      checked: false,
+      error: error instanceof Error ? error.message : String(error)
+    };
+  }
+}
+function createSelfUpdater(run = runCommand) {
+  return async ({
+    currentVersion,
+    packageName = PACKAGE_NAME
+  }) => {
+    const info = await checkForUpdate({ currentVersion, packageName, run });
+    if (!info.checked) throw new Error(`unable to check for updates: ${info.error ?? "unknown error"}`);
+    if (!info.updateAvailable) return { ...info, updated: false };
+    await run("npm", ["install", "-g", `${packageName}@latest`]);
+    return { ...info, updated: true };
+  };
 }
 
 // src/cli.ts
@@ -128,25 +1094,109 @@ function fail(e) {
   console.error(e instanceof Error ? e.message : String(e));
   process.exit(1);
 }
-program.command("render").description("Render an IR JSON file to a .pptx").argument("<ir.json>", "path to the IR file").requiredOption("-o, --output <file>", "output .pptx path").option("--theme <id>", "override the deck theme (see `pptfast themes`)").action(async (ir, opts) => {
+program.command("render").description("Render an IR JSON file, deck project directory, or bare deck name to a .pptx").argument("<target>", "IR JSON file, deck project directory, or bare name under ~/.pptfast/decks").requiredOption("-o, --output <file>", "output .pptx path").option("--theme <id>", "override the deck theme (see `pptfast themes`)").option("--style <path>", "style overrides JSON re-coloring the theme (see `pptfast schema --style`)").option("--draft", "allow unfilled placeholder pages (skip the draft gate)").action(async (target, opts) => {
+  try {
+    console.log(
+      await runRender(target, {
+        output: opts.output,
+        theme: opts.theme,
+        stylePath: opts.style,
+        draft: opts.draft
+      })
+    );
+  } catch (e) {
+    fail(e);
+  }
+});
+program.command("validate").description("Validate an IR JSON file, deck project directory, or bare deck name against the schema").argument("<target>", "IR JSON file, deck project directory, or bare name under ~/.pptfast/decks").action(async (target) => {
+  try {
+    console.log(await runValidate(target));
+  } catch (e) {
+    fail(e);
+  }
+});
+program.command("audit").description(
+  "Deterministic geometry audit (overflow, out-of-bounds, low-contrast, overlap, content-truncated, content-dropped), plus an optional --pixels contrast pass \u2014 exits 1 when it finds anything"
+).argument("<target>", "IR JSON file, deck project directory, or bare name under ~/.pptfast/decks").option("--json", "machine-readable output (the full AuditReport)").option("--pixels", "also run the optional pixel-contrast pass over image-backed text (requires sharp)").action(async (target, opts) => {
+  try {
+    const { output, hasFindings } = await runAudit(target, { json: opts.json, pixels: opts.pixels });
+    console.log(output);
+    if (hasFindings) process.exit(1);
+  } catch (e) {
+    fail(e);
+  }
+});
+program.command("schema").description("Print the IR JSON Schema (feed this to a model before it writes IR)").option("--style", "print the style-override schema instead").option("--spec", "print the deck spec schema instead").option("--plan", "removed \u2014 use --spec instead").action((opts) => {
+  if (opts.plan) {
+    fail(new Error("`pptfast schema --plan` has been renamed to `pptfast schema --spec` \u2014 run `pptfast schema --spec` instead"));
+  }
+  console.log(runSchema(opts.spec ? "spec" : opts.style ? "style" : void 0));
+});
+var plan = program.command("plan").description("Removed \u2014 use `pptfast spec` instead");
+plan.command("validate").description("Removed \u2014 use `pptfast spec validate` instead").argument("<file>").action(() => {
+  fail(new Error("`pptfast plan validate` has been renamed to `pptfast spec validate` \u2014 run `pptfast spec validate <file>` instead"));
+});
+var spec = program.command("spec").description("Deck spec commands (spec \xA76)");
+spec.command("validate").description("Validate a deck spec JSON file against the schema and strategy-aware hard gates").argument("<spec.json>").action(async (specPath) => {
+  try {
+    console.log(await runSpecValidate(specPath));
+  } catch (e) {
+    fail(e);
+  }
+});
+program.command("assemble").description("Assemble a deck project directory (deck.spec.json + pages/ + assets/) into an IR JSON file").argument("<dir|name>", "deck project directory, or bare name under ~/.pptfast/decks").option("-o, --output <file>", "output IR JSON path (default: <dir>/deck.json)").action(async (target, opts) => {
+  try {
+    console.log(await runAssemble(target, { output: opts.output }));
+  } catch (e) {
+    fail(e);
+  }
+});
+program.command("disassemble").description("Split an IR JSON file into a deck project directory (deck.spec.json + pages/)").argument("<ir.json>", "path to the IR file").requiredOption("-o, --output <dir>", "output deck project directory").action(async (irPath, opts) => {
   try {
-    console.log(await runRender(ir, opts));
+    console.log(await runDisassemble(irPath, opts.output));
   } catch (e) {
     fail(e);
   }
 });
-program.command("validate").description("Validate an IR JSON file against the schema").argument("<ir.json>").action(async (ir) => {
+program.command("migrate").description("Convert a v3 IR file to v4, or a deck.plan.json project directory to deck.spec.json \u2014 deterministic, no model").argument("<input>", "IR v3 JSON file, or a deck project directory containing deck.plan.json").requiredOption("-o, --output <output>", "output path \u2014 an IR JSON file for a v3 file input, a directory for a deck-project-directory input").action(async (input, opts) => {
   try {
-    console.log(await runValidate(ir));
+    console.log(await runMigrate(input, opts.output));
   } catch (e) {
     fail(e);
   }
 });
-program.command("schema").description("Print the IR JSON Schema (feed this to a model before it writes IR)").action(() => console.log(runSchema()));
 program.command("themes").description("List built-in themes").option("--json", "machine-readable output").action((opts) => console.log(runThemes(Boolean(opts.json))));
-program.command("preview").description("Render each slide to an SVG file for visual self-check").argument("<ir.json>").requiredOption("-o, --output <dir>", "output directory").action(async (ir, opts) => {
+program.command("narratives").description("List named narrative presets (strategy/pacing/audience axes + theme recommendations)").option("--json", "machine-readable output").action((opts) => console.log(runNarratives(Boolean(opts.json))));
+program.command("scenarios").description("Removed \u2014 use `pptfast narratives` instead").action(() => {
+  fail(new Error("`pptfast scenarios` has been renamed to `pptfast narratives` \u2014 run `pptfast narratives` instead"));
+});
+program.command("init").description("Scaffold a pptfast.config.json in the current directory").action(async () => {
+  try {
+    console.log(await runInit());
+  } catch (e) {
+    fail(e);
+  }
+});
+program.command("preview").description("Render each slide to an SVG file for visual self-check").argument("<target>", "IR JSON file, deck project directory, or bare name under ~/.pptfast/decks").requiredOption("-o, --output <dir>", "output directory").option("--html", "also write a self-contained preview.html (all slides inlined \u2014 thumbnail strip, keyboard navigation) for human review").action(async (target, opts) => {
+  try {
+    console.log(await runPreview(target, opts.output, { htmlOut: opts.html }));
+  } catch (e) {
+    fail(e);
+  }
+});
+program.command("check-update").description("Check npm for a newer pptfast release").action(async () => {
+  const info = await checkForUpdate({ currentVersion: VERSION });
+  if (!info.checked) fail(new Error(`update check failed: ${info.error}`));
+  console.log(
+    info.updateAvailable ? `update available: ${info.currentVersion} \u2192 ${info.latestVersion} (run \`pptfast self-update\`)` : `pptfast ${info.currentVersion} is up to date`
+  );
+});
+program.command("self-update").description("Update the global pptfast install to the latest release").action(async () => {
   try {
-    console.log(await runPreview(ir, opts.output));
+    const result = await createSelfUpdater()({ currentVersion: VERSION });
+    console.log(
+      result.updated ? `updated: ${result.currentVersion} \u2192 ${result.latestVersion}` : `already at the latest version (${result.currentVersion})`
+    );
   } catch (e) {
     fail(e);
   }