@liustack/pptfast 0.1.0 → 0.3.0

package/dist/cli.js

@@ -1,17 +1,32 @@
 #!/usr/bin/env node
 import {
+  AUDIENCE_VALUES,
+  DELIVERY_BUDGETS,
+  MODE_DEFINITIONS,
   PptfastError,
+  SCENARIO_PRESETS,
+  StyleOverrideSchema,
   VERSION,
+  assembleDeck,
+  auditDeck,
+  disassembleDeck,
+  formatInvalidPlanError,
   formatIssues,
   generatePptx,
+  getInstalledThemeIds,
   irJsonSchema,
   listThemes,
+  planJsonSchema,
   renderSlideSvg,
-  validateIr
-} from "./chunk-DVMJWFDL.js";
+  resolvePlanThemeId,
+  resolveScenario,
+  styleJsonSchema,
+  validateIr,
+  validatePlan
+} from "./chunk-ZXWCOWJI.js";
 import {
   installNodePlatform
-} from "./chunk-4WISUDXE.js";
+} from "./chunk-SROEW6BH.js";
 import {
   getPlatform
 } from "./chunk-G76EVNVT.js";
@@ -20,39 +35,114 @@ import {
 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 +161,685 @@ async function resolveLocalAssets(ir, baseDir) {
   }
 }
 
+// src/cli/deck-dir.ts
+var PLAN_FILENAME = "deck.plan.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 = [
+    [PLAN_FILENAME, "the locked plan (see `pptfast plan 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 readPlanFile(dir) {
+  const planPath = join3(dir, PLAN_FILENAME);
+  let text;
+  try {
+    text = await readFile3(planPath, "utf8");
+  } catch (e) {
+    if (e.code === "ENOENT") {
+      throw new PptfastError(
+        `no ${PLAN_FILENAME} in ${dir} \u2014 expected a deck project directory:
+${expectedLayoutHint()}`
+      );
+    }
+    throw new PptfastError(`cannot read plan file: ${planPath}`);
+  }
+  try {
+    return JSON.parse(text);
+  } catch (e) {
+    throw new PptfastError(`plan file ${planPath} 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 plan2 = await readPlanFile(deckDir);
+  const pages = await readPages(deckDir);
+  const { ir, generatedSeed, materializedLayoutCount } = assembleDeck(plan2, 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 slideNode(slide) {
+  const idAttr = slide.id !== void 0 ? ` data-id="${escapeHtml(slide.id)}"` : "";
+  const badge = slide.placeholder ? `<div class="pf-badge" aria-hidden="true">unfilled</div>` : "";
+  return `<div class="pf-slide" id="pf-slide-${slide.index}" data-index="${slide.index}"${idAttr}>${badge}${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) {
+  const description = thumbDescription(slide);
+  const badge = slide.placeholder ? `<span class="pf-thumb-badge" aria-hidden="true">unfilled</span>` : "";
+  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}</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-stage-wrap{flex:1 1 auto;min-height:0;display:flex;align-items:center;justify-content:center;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-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}
+`.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)
+  }
+
+  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))
+    }
+  })
+})()
+`.trim();
+function buildPreviewHtml(input) {
+  const { title, slides } = input;
+  const total = slides.length;
+  const escapedTitle = escapeHtml(title);
+  const stageSlide = total > 0 ? slideNode(slides[0]) : "";
+  const thumbs = slides.map((s, i) => thumbButton(s, i === 0, i === 0 ? "" : slideNode(s))).join("");
+  const initialCounter = total > 0 ? counterText(slides[0], total) : "0 / 0";
+  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>
+</header>
+<div id="pf-stage-wrap"><div id="pf-stage">${stageSlide}</div></div>
+<nav id="pf-filmstrip" aria-label="slides">${thumbs}</nav>
+<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"}`
+  );
+  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 = 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 runPlanValidate(planPath) {
+  const raw = await loadIrFile(planPath, "plan");
+  const v = validatePlan(raw);
+  if (!v.ok) {
+    throw new PptfastError(formatInvalidPlanError(v.errors));
+  }
+  const plan2 = v.plan;
+  const axes = resolveScenario(plan2.scenario);
+  return `OK \u2014 ${plan2.pages.length} pages, scenario ${axes.mode}/${axes.delivery}/${axes.audience}, theme "${resolvePlanThemeId(plan2)}"`;
+}
+function runSchema(mode) {
+  const schema = mode === "style" ? styleJsonSchema() : mode === "plan" ? planJsonSchema() : 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 runScenarios(asJson) {
+  if (asJson) {
+    return JSON.stringify(
+      {
+        presets: SCENARIO_PRESETS,
+        modes: MODE_DEFINITIONS,
+        deliveries: DELIVERY_BUDGETS,
+        audiences: AUDIENCE_VALUES
+      },
+      null,
+      2
+    );
+  }
+  const rows = Object.values(SCENARIO_PRESETS).map((p) => ({
+    id: p.id,
+    axes: `${p.axes.mode}/${p.axes.delivery}/${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 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
+      }))
+    });
+    await writeFile2(htmlPath, html);
+    notes.push(`note: wrote self-contained preview to ${htmlPath}`);
+  }
+  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.plan.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 { plan: plan2, pages } = disassembleDeck(v.ir);
+  const ids = Object.keys(pages);
+  for (const id of ids) assertSafeFileSegment(id, "slide id");
+  const planPath = join4(outDir, "deck.plan.json");
+  await mkdir2(outDir, { recursive: true });
+  try {
+    await writeFile2(planPath, JSON.stringify(plan2, null, 2) + "\n", { flag: "wx" });
+  } catch (e) {
+    if (e.code === "EEXIST") {
+      throw new PptfastError(`${planPath} 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 ${planPath}, ${pagesNote}${assetsNote}`;
+  } catch (e) {
+    await rm(planPath, { force: true }).catch(() => {
+    });
+    throw e;
   }
-  return `wrote ${ir.slides.length} SVG files to ${outDir}`;
+}
+
+// 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 +850,92 @@ 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 runRender(ir, opts));
+    console.log(await runValidate(target));
   } catch (e) {
     fail(e);
   }
 });
-program.command("validate").description("Validate an IR JSON file against the schema").argument("<ir.json>").action(async (ir) => {
+program.command("audit").description(
+  "Deterministic geometry audit (overflow, out-of-bounds, low-contrast, overlap) \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)").action(async (target, opts) => {
   try {
-    console.log(await runValidate(ir));
+    const { output, hasFindings } = await runAudit(target, { json: opts.json });
+    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("--plan", "print the deck plan schema instead").action(
+  (opts) => console.log(runSchema(opts.plan ? "plan" : opts.style ? "style" : void 0))
+);
+var plan = program.command("plan").description("Deck plan commands (spec \xA75)");
+plan.command("validate").description("Validate a deck plan JSON file against the schema and mode-aware hard gates").argument("<plan.json>").action(async (planPath) => {
+  try {
+    console.log(await runPlanValidate(planPath));
+  } catch (e) {
+    fail(e);
+  }
+});
+program.command("assemble").description("Assemble a deck project directory (deck.plan.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.plan.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 runDisassemble(irPath, 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("scenarios").description("List named scenario presets (mode/delivery/audience axes + theme recommendations)").option("--json", "machine-readable output").action((opts) => console.log(runScenarios(Boolean(opts.json))));
+program.command("init").description("Scaffold a pptfast.config.json in the current directory").action(async () => {
   try {
-    console.log(await runPreview(ir, opts.output));
+    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 {
+    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);
   }