@liustack/pptfast 0.3.0 → 0.4.0

package/dist/cli.js

@@ -1,35 +1,40 @@
 #!/usr/bin/env node
+import {
+  PptxIRV3Schema,
+  VERSION,
+  assembleDeck,
+  disassembleDeck,
+  formatInvalidSpecError,
+  migrateDeckPlanToSpec,
+  migrateIrV3ToV4,
+  resolveSpecThemeId,
+  specJsonSchema,
+  validateSpec
+} from "./chunk-4W2YZPJJ.js";
+import {
+  installNodePlatform
+} from "./chunk-HFRNKYZ6.js";
 import {
   AUDIENCE_VALUES,
-  DELIVERY_BUDGETS,
-  MODE_DEFINITIONS,
+  NARRATIVE_PRESETS,
+  PACING_BUDGETS,
   PptfastError,
-  SCENARIO_PRESETS,
+  STRATEGY_DEFINITIONS,
   StyleOverrideSchema,
-  VERSION,
-  assembleDeck,
   auditDeck,
-  disassembleDeck,
-  formatInvalidPlanError,
   formatIssues,
   generatePptx,
   getInstalledThemeIds,
   irJsonSchema,
   listThemes,
-  planJsonSchema,
   renderSlideSvg,
-  resolvePlanThemeId,
-  resolveScenario,
+  resolveNarrative,
   styleJsonSchema,
-  validateIr,
-  validatePlan
-} from "./chunk-ZXWCOWJI.js";
-import {
-  installNodePlatform
-} from "./chunk-SROEW6BH.js";
+  validateIr
+} from "./chunk-7N4HGSMW.js";
 import {
   getPlatform
-} from "./chunk-G76EVNVT.js";
+} from "./chunk-L524YK63.js";
 
 // src/cli.ts
 import { Command } from "commander";
@@ -163,6 +168,7 @@ 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) {
@@ -202,31 +208,43 @@ async function resolveDeckTarget(arg, config, cwd = process.cwd()) {
 }
 function expectedLayoutHint() {
   const rows = [
-    [PLAN_FILENAME, "the locked plan (see `pptfast plan validate`)"],
+    [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 readPlanFile(dir) {
+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(planPath, "utf8");
+    text = await readFile3(specPath, "utf8");
   } catch (e) {
     if (e.code === "ENOENT") {
       throw new PptfastError(
-        `no ${PLAN_FILENAME} in ${dir} \u2014 expected a deck project directory:
+        `no ${SPEC_FILENAME} in ${dir} \u2014 expected a deck project directory:
 ${expectedLayoutHint()}`
       );
     }
-    throw new PptfastError(`cannot read plan file: ${planPath}`);
+    throw new PptfastError(`cannot read spec file: ${specPath}`);
   }
   try {
     return JSON.parse(text);
   } catch (e) {
-    throw new PptfastError(`plan file ${planPath} is not valid JSON: ${e.message}`);
+    throw new PptfastError(`spec file ${specPath} is not valid JSON: ${e.message}`);
   }
 }
 async function readPages(dir) {
@@ -273,9 +291,9 @@ async function scanAssets(dir) {
 }
 async function readDeckDir(dir) {
   const deckDir = resolve4(dir);
-  const plan2 = await readPlanFile(deckDir);
+  const spec2 = await readSpecFile(deckDir);
   const pages = await readPages(deckDir);
-  const { ir, generatedSeed, materializedLayoutCount } = assembleDeck(plan2, pages);
+  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 };
@@ -324,10 +342,18 @@ async function writeOneAsset(id, src, assetsDir, sourceBaseDir) {
 function escapeHtml(s) {
   return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&#39;");
 }
-function slideNode(slide) {
+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>` : "";
-  return `<div class="pf-slide" id="pf-slide-${slide.index}" data-index="${slide.index}"${idAttr}>${badge}${slide.svg}</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];
@@ -343,10 +369,15 @@ 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) {
+function thumbButton(slide, isActive, slotContent, findingCount) {
   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>`;
+  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}
@@ -356,11 +387,31 @@ body{display:flex;flex-direction:column;font-family:-apple-system,BlinkMacSystem
 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-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}
@@ -368,6 +419,7 @@ header{display:flex;align-items:center;justify-content:space-between;gap:12px;pa
 .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 () {
@@ -411,6 +463,7 @@ var JS = `
     nextThumb.classList.add('pf-thumb-active')
     current = i
     updateCounter(i)
+    renderAnnotations()
   }
 
   thumbs.forEach(function (t) {
@@ -427,15 +480,129 @@ var JS = `
       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 } = input;
+  const { title, slides, findings = [], auditNote, checks } = 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 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>
@@ -448,9 +615,12 @@ function buildPreviewHtml(input) {
 <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></div>
+<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>
@@ -569,6 +739,9 @@ function formatAuditReport(report, ir) {
   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");
@@ -586,23 +759,23 @@ ${formatIssues(v.errors)}`
     );
   }
   await resolveLocalAssets(v.ir, baseDir);
-  const report = auditDeck(v.ir);
+  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 runPlanValidate(planPath) {
-  const raw = await loadIrFile(planPath, "plan");
-  const v = validatePlan(raw);
+async function runSpecValidate(specPath) {
+  const raw = await loadIrFile(specPath, "spec");
+  const v = validateSpec(raw);
   if (!v.ok) {
-    throw new PptfastError(formatInvalidPlanError(v.errors));
+    throw new PptfastError(formatInvalidSpecError(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)}"`;
+  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 === "plan" ? planJsonSchema() : irJsonSchema();
+  const schema = mode === "style" ? styleJsonSchema() : mode === "spec" ? specJsonSchema() : irJsonSchema();
   return JSON.stringify(schema, null, 2);
 }
 function runThemes(asJson) {
@@ -610,22 +783,22 @@ function runThemes(asJson) {
   if (asJson) return JSON.stringify(themes, null, 2);
   return themes.map((t) => `${t.id.padEnd(12)} ${t.label}`).join("\n");
 }
-function runScenarios(asJson) {
+function runNarratives(asJson) {
   if (asJson) {
     return JSON.stringify(
       {
-        presets: SCENARIO_PRESETS,
-        modes: MODE_DEFINITIONS,
-        deliveries: DELIVERY_BUDGETS,
+        presets: NARRATIVE_PRESETS,
+        strategies: STRATEGY_DEFINITIONS,
+        pacings: PACING_BUDGETS,
         audiences: AUDIENCE_VALUES
       },
       null,
       2
     );
   }
-  const rows = Object.values(SCENARIO_PRESETS).map((p) => ({
+  const rows = Object.values(NARRATIVE_PRESETS).map((p) => ({
     id: p.id,
-    axes: `${p.axes.mode}/${p.axes.delivery}/${p.axes.audience}`,
+    axes: `${p.axes.strategy}/${p.axes.pacing}/${p.axes.audience}`,
     themes: p.themeRecommendations.join(", ")
   }));
   const idWidth = Math.max(...rows.map((r) => r.id.length));
@@ -674,6 +847,9 @@ ${formatIssues(v.errors)}`);
   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) => ({
@@ -682,10 +858,16 @@ ${formatIssues(v.errors)}`);
         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 notes.length > 0 ? `${ok}
 ${notes.join("\n")}` : ok;
@@ -716,7 +898,7 @@ async function runAssemble(target, opts = {}) {
   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`);
+    notes.push(`note: generated seed ${generatedSeed} \u2014 add "seed": ${generatedSeed} to deck.spec.json for revision stability`);
   }
   if (materializedLayoutCount !== void 0) {
     notes.push(
@@ -730,16 +912,16 @@ async function runDisassemble(irPath, outDir) {
   const v = validateIr(raw);
   if (!v.ok) throw new PptfastError(`invalid IR:
 ${formatIssues(v.errors)}`);
-  const { plan: plan2, pages } = disassembleDeck(v.ir);
+  const { spec: spec2, 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");
+  const specPath = join4(outDir, "deck.spec.json");
   await mkdir2(outDir, { recursive: true });
   try {
-    await writeFile2(planPath, JSON.stringify(plan2, null, 2) + "\n", { flag: "wx" });
+    await writeFile2(specPath, JSON.stringify(spec2, 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 new PptfastError(`${specPath} already exists \u2014 refusing to overwrite an existing deck project`);
     }
     throw e;
   }
@@ -761,13 +943,75 @@ ${formatIssues(v.errors)}`);
     );
     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}`;
+    return `wrote ${specPath}, ${pagesNote}${assetsNote}`;
   } catch (e) {
-    await rm(planPath, { force: true }).catch(() => {
+    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";
@@ -872,43 +1116,60 @@ program.command("validate").description("Validate an IR JSON file, deck project
   }
 });
 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) => {
+  "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 });
+    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("--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) => {
+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 runPlanValidate(planPath));
+    console.log(await runSpecValidate(specPath));
   } 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) => {
+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.plan.json + pages/)").argument("<ir.json>", "path to the IR file").requiredOption("-o, --output <dir>", "output deck project directory").action(async (irPath, opts) => {
+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 runDisassemble(irPath, opts.output));
   } catch (e) {
     fail(e);
   }
 });
+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 runMigrate(input, opts.output));
+  } catch (e) {
+    fail(e);
+  }
+});
 program.command("themes").description("List built-in themes").option("--json", "machine-readable output").action((opts) => console.log(runThemes(Boolean(opts.json))));
-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("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());