@liustack/pptwise 0.22.0 → 0.24.0

package/dist/index.js

@@ -2,28 +2,31 @@ import {
   BrandThemeFileSchema,
   DeckSpecSchema,
   PageSpecSchema,
-  PptxIRV3Schema,
   SPEC_PAGE_COUNT_RANGE,
+  THEME_PRESETS,
   VERSION,
   assembleDeck,
   buildAssetBrief,
+  copyThemePreset,
   disassembleDeck,
   extractBrandTheme,
+  forkTheme,
   formatSpecIssues,
-  migrateDeckPlanToSpec,
-  migrateIrV3ToV4,
+  getThemePreset,
+  isThemePresetId,
   parseBrandThemeFile,
   registerBrandThemeFile,
   resolveSpecThemeId,
   specJsonSchema,
   validateSpec
-} from "./chunk-M35M4QUC.js";
+} from "./chunk-2CA3JRFR.js";
 import {
   AUDIENCE_VALUES,
   BUILTIN_THEME_IDS,
   BrandConfigSchema,
   COMPONENT_TYPES,
   DEFAULT_NARRATIVE,
+  KIND_VALUES,
   NARRATIVE_PRESETS,
   PACING_BUDGETS,
   PACING_VALUES,
@@ -31,7 +34,6 @@ import {
   PptxIRSchema,
   STRATEGY_DEFINITIONS,
   STRATEGY_VALUES,
-  StyleOverrideSchema,
   ThemeSchema,
   auditDeck,
   formatIssues,
@@ -43,12 +45,11 @@ import {
   registerTheme,
   renderSlideSvg,
   resolveNarrative,
-  styleJsonSchema,
   validateIr
-} from "./chunk-WL5KWYKS.js";
+} from "./chunk-G7WQ7KSP.js";
 import {
   installPlatform
-} from "./chunk-VUOLBHD7.js";
+} from "./chunk-RQUKZYSH.js";
 export {
   AUDIENCE_VALUES,
   BUILTIN_THEME_IDS,
@@ -57,34 +58,36 @@ export {
   COMPONENT_TYPES,
   DEFAULT_NARRATIVE,
   DeckSpecSchema,
+  KIND_VALUES,
   NARRATIVE_PRESETS,
   PACING_BUDGETS,
   PACING_VALUES,
   PageSpecSchema,
   PptwiseError,
   PptxIRSchema,
-  PptxIRV3Schema,
   SPEC_PAGE_COUNT_RANGE,
   STRATEGY_DEFINITIONS,
   STRATEGY_VALUES,
-  StyleOverrideSchema,
+  THEME_PRESETS,
   ThemeSchema,
   VERSION,
   assembleDeck,
   auditDeck,
   buildAssetBrief,
+  copyThemePreset,
   disassembleDeck,
   extractBrandTheme,
+  forkTheme,
   formatIssues,
   formatSpecIssues,
   generatePptx,
   getInstalledThemeIds,
   getThemeDefinition,
+  getThemePreset,
   installPlatform,
   irJsonSchema,
+  isThemePresetId,
   listThemes,
-  migrateDeckPlanToSpec,
-  migrateIrV3ToV4,
   parseBrandThemeFile,
   registerBrandThemeFile,
   registerTheme,
@@ -92,7 +95,6 @@ export {
   resolveNarrative,
   resolveSpecThemeId,
   specJsonSchema,
-  styleJsonSchema,
   validateIr,
   validateSpec
 };

package/dist/node.d.ts

@@ -1,4 +1,4 @@
-export { P as PptwisePlatform, i as installPlatform } from './registry-C0GJH7ZT.js';
+export { P as PptwisePlatform, i as installPlatform } from './registry-D8bkC8ff.js';
 
 /** Wire Node implementations (linkedom DOM, sharp image re-encode + SVG
  *  rasterize) into the SDK. */

package/dist/node.js

@@ -1,9 +1,9 @@
 import {
   installNodePlatform
-} from "./chunk-3ZUKISTY.js";
+} from "./chunk-VEZGVYJS.js";
 import {
   installPlatform
-} from "./chunk-VUOLBHD7.js";
+} from "./chunk-RQUKZYSH.js";
 export {
   installNodePlatform,
   installPlatform

package/dist/{pixel-audit-H5K6JK3X.js → pixel-audit-M5Q5WCST.js}

@@ -5,11 +5,11 @@ import {
   blendOver,
   contrastRatio2 as contrastRatio,
   renderSlideSvg
-} from "./chunk-WL5KWYKS.js";
+} from "./chunk-G7WQ7KSP.js";
 import {
   findRemoteAssetRef,
   getPlatform
-} from "./chunk-VUOLBHD7.js";
+} from "./chunk-RQUKZYSH.js";
 
 // src/platform/browser.ts
 function isSecurityError(e) {
@@ -88,7 +88,7 @@ async function rasterizeSvgInBrowser(svgMarkup, width, height) {
   }
 }
 
-// src/svg/audit/pixel-audit.ts
+// src/audit/pixel-audit.ts
 var PIXEL_CANVAS_W = CANVAS_W_PX;
 var PIXEL_CANVAS_H = CANVAS_H_PX;
 var PIXEL_HARD_FINDING_MAX_RATIO = 1.5;
@@ -215,4 +215,4 @@ export {
   runPixelContrastAudit,
   stripTextNodes
 };
-//# sourceMappingURL=pixel-audit-H5K6JK3X.js.map
+//# sourceMappingURL=pixel-audit-M5Q5WCST.js.map

package/dist/pixel-audit-M5Q5WCST.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/platform/browser.ts","../src/audit/pixel-audit.ts"],"sourcesContent":["import { findRemoteAssetRef, type RasterizedImage } from \"./registry\"\n\n/**\n * Browser default for `rasterizeSvg` (audit-v2 phase B, spec §4.3/§11.8) —\n * native `Image` + `OffscreenCanvas`/`<canvas>` only, zero new dependency.\n * Applied at the pixel-audit call site (`../audit/pixel-audit.ts`) the\n * same way `domParser`'s `?? globalThis.DOMParser` fallback already works\n * (`deck-audit.ts`'s `parseSvg`) — nothing calls `installPlatform()`\n * automatically in a browser, so this is a plain fallback function, not\n * something wired through `installPlatform()` itself. Lives outside\n * `src/platform/node.ts` (which imports `linkedom`/`sharp`) so it can sit\n * inside `src/index.ts`'s own browser-safe dependency closure without\n * pulling in either.\n *\n * Two explicit-failure paths, both load-bearing per the audit-v2 controller\n * ruling on browser remote assets (own tests: `browser.test.ts`):\n *\n * 1. `findRemoteAssetRef` — scanned *before* ever touching `Image`/canvas.\n *    An `<img>`/`Image` load of an `http(s):` asset happens in a restricted\n *    context: the resource is silently dropped rather than reliably\n *    tainting the canvas, so without this guard a remote-image slide would\n *    rasterize to a *blank* region and get sampled as if that blank were\n *    the real background — exactly the \"checked nothing, reported clean\"\n *    failure this wave rules out. (`node.ts`'s Sharp implementation shares\n *    this same guard for a different reason — see `findRemoteAssetRef`'s own\n *    doc comment.)\n * 2. `getImageData`'s own `SecurityError` — kept as a fallback for\n *    whatever the markup scan didn't anticipate (a future asset kind, a\n *    same-origin-but-still-tainting edge case): caught and re-thrown as an\n *    explicit, readable error rather than left as a raw `DOMException` (or,\n *    worse, silently producing zeroed pixel data some engines return\n *    instead of throwing).\n */\n\ninterface Minimal2dContext {\n  drawImage(image: CanvasImageSource, dx: number, dy: number, dw: number, dh: number): void\n  getImageData(sx: number, sy: number, sw: number, sh: number): ImageData\n}\n\ninterface MinimalCanvas {\n  getContext(id: \"2d\"): Minimal2dContext | null\n}\n\n/** `DOMException` is *not* an `Error` subclass per the WebIDL spec (real\n *  browsers: `new DOMException(\"x\", \"SecurityError\") instanceof Error` is\n *  `false`) — duck-type on `.name` rather than `instanceof Error`. */\nfunction isSecurityError(e: unknown): boolean {\n  return typeof e === \"object\" && e !== null && (e as { name?: unknown }).name === \"SecurityError\"\n}\n\n/**\n * Maximum time (ms) to wait for `Image.onload`/`onerror` to fire before\n * treating the decode as stuck and rejecting explicitly, rather than\n * hanging the whole `rasterizeSvgInBrowser` call forever — unlike the\n * Node/Sharp path (`node.ts`'s `rasterizeSvg`, a synchronous, bounded\n * call), a browser `Image` decode has no timeout of its own, and a\n * genuinely stuck one (a browser/OS decoder bug, an unresponsive tab) would\n * otherwise leave the caller (e.g. a pixel-contrast audit) awaiting forever\n * with no way to know why. 30s: generous for even a large local decode —\n * this rasterizer only ever reaches `Image` for a local/data-URI SVG\n * (`findRemoteAssetRef` already rejected any remote asset reference above)\n * — but short enough that a stuck decode fails loud well within any\n * interactive caller's own patience.\n */\nexport const IMAGE_LOAD_TIMEOUT_MS = 30_000\n\nfunction loadImage(url: string): Promise<HTMLImageElement> {\n  return new Promise((resolve, reject) => {\n    const timer = setTimeout(() => {\n      reject(\n        new Error(\n          `rasterizeSvg: timed out after ${IMAGE_LOAD_TIMEOUT_MS}ms waiting for the browser to decode the rasterized SVG as an image (a stuck decode, never a silent hang)`,\n        ),\n      )\n    }, IMAGE_LOAD_TIMEOUT_MS)\n    const img = new Image()\n    img.onload = () => {\n      clearTimeout(timer)\n      resolve(img)\n    }\n    img.onerror = () => {\n      clearTimeout(timer)\n      reject(new Error(\"rasterizeSvg: the browser could not decode the rasterized SVG as an image\"))\n    }\n    img.src = url\n  })\n}\n\nfunction createCanvas(width: number, height: number): MinimalCanvas {\n  if (typeof OffscreenCanvas !== \"undefined\") {\n    return new OffscreenCanvas(width, height) as unknown as MinimalCanvas\n  }\n  if (typeof document !== \"undefined\") {\n    const canvas = document.createElement(\"canvas\")\n    canvas.width = width\n    canvas.height = height\n    return canvas as unknown as MinimalCanvas\n  }\n  throw new Error(\n    'rasterizeSvg unavailable — in Node, call installNodePlatform() from \"@liustack/pptwise/node\" first (the pptwise CLI does this automatically); in a browser, OffscreenCanvas or a DOM canvas is required',\n  )\n}\n\nexport async function rasterizeSvgInBrowser(svgMarkup: string, width: number, height: number): Promise<RasterizedImage> {\n  const remoteRef = findRemoteAssetRef(svgMarkup)\n  if (remoteRef) {\n    throw new Error(\n      `rasterizeSvg: refusing to rasterize an SVG that references a remote image (${remoteRef}) — only data-URI (or other local) assets are supported (a remote asset would silently drop when loaded this way, not rasterize)`,\n    )\n  }\n  if (typeof Image === \"undefined\") {\n    throw new Error(\n      'rasterizeSvg unavailable — in Node, call installNodePlatform() from \"@liustack/pptwise/node\" first (the pptwise CLI does this automatically); in a browser, the Image constructor is required',\n    )\n  }\n\n  const blob = new Blob([svgMarkup], { type: \"image/svg+xml\" })\n  const url = URL.createObjectURL(blob)\n  try {\n    const img = await loadImage(url)\n    const canvas = createCanvas(width, height)\n    const ctx = canvas.getContext(\"2d\")\n    if (!ctx) throw new Error(\"rasterizeSvg: could not obtain a 2d canvas context\")\n    ctx.drawImage(img, 0, 0, width, height)\n    let imageData: ImageData\n    try {\n      imageData = ctx.getImageData(0, 0, width, height)\n    } catch (e) {\n      if (isSecurityError(e)) {\n        throw new Error(\n          \"rasterizeSvg: the canvas was tainted while reading back pixel data (a cross-origin or otherwise untrusted asset) — only data-URI (or other local) assets are supported\",\n        )\n      }\n      throw e\n    }\n    return { width: imageData.width, height: imageData.height, data: imageData.data }\n  } finally {\n    URL.revokeObjectURL(url)\n  }\n}\n","import type { PptxIR } from \"@/ir\"\nimport { renderSlideSvg } from \"../api\"\nimport { CANVAS_H_PX, CANVAS_W_PX } from \"../constants\"\nimport { rasterizeSvgInBrowser } from \"../platform/browser\"\nimport { getPlatform, type RasterizedImage } from \"../platform/registry\"\nimport {\n  __collectImageBackedTextRuns,\n  blendOver,\n  contrastRatio,\n  type AuditFinding,\n  type ImageBackedTextRun,\n} from \"./deck-audit\"\n\n/**\n * Optional pixel-level contrast audit (audit-v2 phase B, spec §4.3) — the\n * one pixel blind spot the deterministic SVG audit can't see: text painted\n * directly over a bare or too-faintly-scrimmed `<image>`, where\n * `deck-audit.ts`'s own SVG-color walk correctly gives up rather than guess\n * (`ImageBackedTextRun`, `__collectImageBackedTextRuns`). Never imported by\n * `deck-audit.ts` at the top level — `auditDeck`'s `pixels: true` branch\n * reaches this module through a lazy `import(\"./pixel-audit\")` instead\n * (that function's own doc comment explains why: this file statically\n * depends on `deck-audit.ts` for its shared primitives, so a *static*\n * import the other way would form a module cycle; nothing here needs to be\n * loaded at all for the far more common `pixels` left unset case).\n *\n * Flow per spec §4.3, steps 2-6:\n * 1. `__collectImageBackedTextRuns` — reuse the exact same background-\n *    resolution walk the deterministic audit already ran, just reading its\n *    \"could not resolve\" runs instead of discarding them. A page with none\n *    skips rasterization entirely (no rasterizer call, no risk of that\n *    page's own remote-asset guard ever firing) — real cost only where\n *    there is real work to do.\n * 2. `stripTextNodes` — the \"去文字克隆\" clone.\n * 3. `rasterizeSvg(stripped, 1280, 720)` — platform primitive (Sharp in\n *    Node, native canvas in a browser — see `resolveRasterizer`).\n * 4/5. `worstCaseSample` — grid-sample each run's estimated box against the\n *    rasterized pixels, tracking the least-favorable (lowest-ratio) point.\n * 6. Only a sample below `PIXEL_HARD_FINDING_MAX_RATIO` becomes a finding —\n *    spec §4.3's own anti-false-positive gate, see that constant's doc\n *    comment.\n */\n\nconst PIXEL_CANVAS_W = CANVAS_W_PX\nconst PIXEL_CANVAS_H = CANVAS_H_PX\n\n/**\n * Below this, a pixel-sampled contrast finding is emitted regardless of the\n * real WCAG target (`ImageBackedTextRun.required`) — spec §4.3's own \"为了\n * 控制误报，首版只有低于 1.5:1 才进入 hard finding\" gate. Pixel sampling\n * carries antialiasing/rasterizer noise the SVG-only walk never has to deal\n * with (spec §11.10's determinism footnote: no cross-platform byte\n * guarantee for this layer) — `node-rasterize.test.ts`'s own transparency\n * probe found up to ~1/255-per-channel sequential-blend rounding drift,\n * nowhere near enough to move a real ratio across this floor. Deliberately\n * far below either real WCAG floor (3/4.5) so only a genuinely broken\n * pairing fires, not a borderline-but-fine one.\n */\nconst PIXEL_HARD_FINDING_MAX_RATIO = 1.5\n\n/**\n * Strip every `<text>...</text>` (and self-closing `<text/>`) element from\n * SVG markup — spec §4.3 step 2's \"去文字克隆\" (clone with text removed). A\n * plain string replace, not a DOM parse/remove/reserialize round-trip:\n * removing an element has zero effect on sibling/ancestor geometry in SVG\n * (no reflow, unlike HTML), so a round-trip would only add risk — a\n * serializer (linkedom in Node) producing markup that doesn't byte-match\n * what a real browser's `XMLSerializer` would, for zero benefit. Sound\n * under two preconditions this renderer's own architecture already\n * guarantees: `renderToStaticMarkup` (React) HTML/XML-escapes every text\n * *node*, so a literal `</text>` substring appearing in `markup` can only\n * ever be a real closing tag, never escaped slide content; and `<text>` is\n * never nested inside another `<text>` anywhere in `src/render` (verified\n * across every emitter while building this task).\n */\nconst TEXT_ELEMENT_RE = /<text\\b[^>]*\\/>|<text\\b[^>]*>[\\s\\S]*?<\\/text>/g\n\nexport function stripTextNodes(markup: string): string {\n  return markup.replace(TEXT_ELEMENT_RE, \"\")\n}\n\nfunction rgbToHex(r: number, g: number, b: number): string {\n  // Rounds first: callers now include averaged (non-integer) channel values\n  // (`averageWindow`'s own doc comment) alongside the original raw-integer\n  // ones — `Math.round` is a no-op for the latter, so this stays byte-for-\n  // byte compatible with every pre-existing call shape.\n  const toHex = (v: number) => Math.round(v).toString(16).padStart(2, \"0\")\n  return `#${toHex(r)}${toHex(g)}${toHex(b)}`.toUpperCase()\n}\n\n/**\n * Ascent/descent as a fraction of `fontSize`, defining the vertical band\n * `worstCaseSample` grids over — no real font metrics are available at\n * audit time (this renderer never embeds/queries a font file), so both are\n * the same kind of declared-size-relative heuristic `deck-audit.ts`'s own\n * `TEXT_DESCENT_RATIO` (0.25, used for v-overflow/derived-box-height) is —\n * `SAMPLE_DESCENT_RATIO` mirrors it exactly for consistency between the two\n * auditors' notion of \"how far below the baseline a glyph's ink extends\".\n * `SAMPLE_ASCENT_RATIO` (0.75) is this task's own addition — no existing\n * constant to mirror since nothing before this needed a text run's *top*\n * edge — a standard approximation for common UI sans-serif cap-height/\n * ascender proportion.\n */\nconst SAMPLE_ASCENT_RATIO = 0.75\nconst SAMPLE_DESCENT_RATIO = 0.25\n\n/**\n * Minimum contiguous low-contrast patch size (px, both axes, at the\n * 1280×720 rasterization scale) the sampling design below guarantees never\n * to miss — \"glyph scale\": at or below the narrowest highlight/shadow\n * sliver a single character can plausibly introduce (the deep-acceptance\n * review's own demonstrated miss used a 24px-wide patch, comfortably above\n * this floor with margin to spare). Anchors both `SAMPLE_STRIDE_PX`\n * (coverage) and the `SAMPLE_STRIDE_PX` vs `AGGREGATION_HALF_PX` margin\n * (noise robustness) — see `worstCaseSample`'s own doc comment for the\n * covering argument these three constants together satisfy.\n */\nconst MIN_GUARANTEED_PATCH_PX = 10\n\n/**\n * Sample-center spacing (px), both axes — half of `MIN_GUARANTEED_PATCH_PX`,\n * computed rather than duplicated as a literal so the two constants can\n * never drift apart. The standard \"sample at <= half the feature size\"\n * covering rule. Replaces\n * the old fixed 5×3-point grid (`SAMPLE_COLS`/`SAMPLE_ROWS`), whose own\n * justifying comment (\"15 points is already enough...\") the deep-acceptance\n * review falsified with a hand-verified repro: a real 1.03:1 contrast patch\n * sitting 35px from the nearest sample column (columns were 70px apart at\n * ImageCoverPage's real org-line scale) produced zero findings, yet the\n * identical patch was caught the moment it landed on a column — pure\n * alignment luck, not a real \"worst-case band\" guarantee. A dense,\n * position-independent stride closes that gap entirely (see the coverage\n * proof below) instead of shrinking it.\n */\nconst SAMPLE_STRIDE_PX = MIN_GUARANTEED_PATCH_PX / 2\n\n/**\n * Half-width (px) of the small square window averaged at each sample\n * center before the worst-case comparison — the noise-robustness half of\n * this design. A lone single-pixel outlier (rasterizer antialiasing noise\n * under a glyph edge, photo grain) is diluted to at most 1/9 of a 3×3\n * window's mean, never enough on its own to pull a genuinely-safe\n * surrounding patch's averaged ratio under the 1.5 hard-finding floor (this\n * file's own test: a single near-black (8) pixel inside an otherwise-232\n * 3×3 window averages to ~207.5, nowhere near dark enough to fail near-\n * black text). Small enough — window width 3, well under `SAMPLE_STRIDE_PX\n * × 2 = 10` — that it cannot itself straddle a genuine\n * `MIN_GUARANTEED_PATCH_PX`-wide bad patch and a safe neighbor closely\n * enough to dilute a real defect back above the floor (this file's own\n * test: a real 12px-wide dark patch at the same spot the noise test uses\n * still produces a finding).\n */\nconst AGGREGATION_HALF_PX = 1\n\ninterface WorstCaseSample {\n  ratio: number\n  background: string\n}\n\n/**\n * Dense sample-center positions from `lo` to `hi` inclusive, `SAMPLE_STRIDE_PX`\n * apart. Always includes both endpoints, even when the span isn't an exact\n * stride multiple (the last gap can be shorter than the stride, never\n * longer) — a run's own edges are never under-sampled relative to its\n * interior. `[lo]` when the span has collapsed to (or below) a point, same\n * degenerate-input guard the old fixed-fraction grid had.\n */\nfunction samplePositions(lo: number, hi: number): number[] {\n  if (hi <= lo) return [lo]\n  const positions: number[] = []\n  for (let v = lo; v < hi; v += SAMPLE_STRIDE_PX) positions.push(v)\n  positions.push(hi)\n  return positions\n}\n\n/**\n * Mean RGB of the `(2*AGGREGATION_HALF_PX+1)²` pixel block centered at\n * `(cx, cy)` (rounded to the nearest pixel) — the noise-robustness\n * aggregation step, see `AGGREGATION_HALF_PX`'s own doc comment. Skips any\n * pixel that's off-canvas or below full alpha, same indeterminate rule the\n * original single-point design used; a window with at least one usable\n * pixel still contributes its partial average rather than being discarded\n * outright, maximizing real coverage near a run's own box edges. Returns\n * `null` only when the window contained zero usable pixels.\n */\nfunction averageWindow(image: RasterizedImage, cx: number, cy: number): { r: number; g: number; b: number } | null {\n  const x0 = Math.round(cx)\n  const y0 = Math.round(cy)\n  let sumR = 0\n  let sumG = 0\n  let sumB = 0\n  let count = 0\n  for (let dy = -AGGREGATION_HALF_PX; dy <= AGGREGATION_HALF_PX; dy++) {\n    const y = y0 + dy\n    if (y < 0 || y >= image.height) continue\n    for (let dx = -AGGREGATION_HALF_PX; dx <= AGGREGATION_HALF_PX; dx++) {\n      const x = x0 + dx\n      if (x < 0 || x >= image.width) continue\n      const i = (y * image.width + x) * 4\n      const alpha = image.data[i + 3]!\n      if (alpha < 255) continue\n      sumR += image.data[i]!\n      sumG += image.data[i + 1]!\n      sumB += image.data[i + 2]!\n      count++\n    }\n  }\n  if (count === 0) return null\n  return { r: sumR / count, g: sumG / count, b: sumB / count }\n}\n\n/**\n * Grid-sample `run`'s estimated box against `image` at a dense,\n * deterministic stride (`SAMPLE_STRIDE_PX`) — each sample point itself a\n * small-window average (`averageWindow`/`AGGREGATION_HALF_PX`) rather than\n * one raw pixel — tracking the least-favorable (lowest) contrast ratio\n * found overall: spec §4.3 step 6's \"WCAG 最不利带\" (worst-case band).\n *\n * **Coverage guarantee:** any axis-aligned contiguous low-contrast patch at\n * least `MIN_GUARANTEED_PATCH_PX` (10px) wide *and* tall is always fully\n * covered by at least one sample's aggregation window, regardless of the\n * patch's position relative to the grid — no alignment/phase assumption,\n * unlike the fixed grid this replaces. Proof, one axis at a time: sample\n * centers sit at a fixed stride S=5px; a window centered at `c` is fully\n * inside a patch spanning `[a, a+10]` exactly when\n * `c ∈ [a+1, a+9]` (window half-width 1px each side) — an interval of\n * length 8 >= S, so by the covering property of a grid spaced S apart (any\n * interval of length >= S must contain a grid point, since consecutive\n * centers are only S apart), that interval always contains at least one\n * sample center. The same argument applies independently on the\n * perpendicular axis, so a 2D patch of that minimum size is always hit on\n * both axes at once. (The deep-acceptance review's demonstrated miss used a\n * 24px patch — comfortably inside this guarantee with margin to spare.)\n *\n * **Noise robustness:** see `AGGREGATION_HALF_PX`'s own doc comment — the\n * same small window that provides the guarantee above also means a single\n * noisy pixel can't flip a genuinely-safe patch into a false finding.\n *\n * Returns `null` when *no* sample window anywhere yielded any usable pixel\n * at all (every window skipped, or the run's box fell entirely outside the\n * rasterized canvas) — the caller treats that as \"nothing proven either\n * way\", not a finding.\n */\nfunction worstCaseSample(run: ImageBackedTextRun, image: RasterizedImage): WorstCaseSample | null {\n  const top = run.baseline - run.fontSize * SAMPLE_ASCENT_RATIO\n  const bottom = run.baseline + run.fontSize * SAMPLE_DESCENT_RATIO\n  let worst: WorstCaseSample | null = null\n\n  const ys = samplePositions(top, bottom)\n  const xs = samplePositions(run.left, run.right)\n\n  for (const y of ys) {\n    for (const x of xs) {\n      const avg = averageWindow(image, x, y)\n      if (!avg) continue\n\n      const bgHex = rgbToHex(avg.r, avg.g, avg.b)\n      const effective = blendOver(run.fill, bgHex, run.alpha)\n      const ratio = contrastRatio(effective, bgHex)\n      if (!worst || ratio < worst.ratio) worst = { ratio, background: bgHex }\n    }\n  }\n  return worst\n}\n\nexport interface PixelContrastIssue {\n  text: string\n  fill: string\n  /** The small-window-averaged RGB (hex) at the worst-case sample center —\n   *  a rasterized-and-aggregated sample, never a resolved SVG paint (see\n   *  `averageWindow`). */\n  background: string\n  ratio: number\n  required: number\n  fontSize: number\n}\n\nfunction pixelContrastMessage(issue: PixelContrastIssue): string {\n  return (\n    `text \"${issue.text}\" has a pixel-sampled contrast ratio of ${issue.ratio.toFixed(2)}:1 against its image background ` +\n    `(sampled ${issue.background}, target ${issue.required}:1) — this text sits directly on an image with no resolvable ` +\n    `solid backing color; reposition it, add an opaque-enough scrim behind it, or recolor the text`\n  )\n}\n\ntype Rasterizer = (svgMarkup: string, width: number, height: number) => Promise<RasterizedImage>\n\n/**\n * `getPlatform().rasterizeSvg` (Sharp once `installNodePlatform()` ran) or\n * the browser default — the exact same `?? fallback` shape `deck-audit.ts`'s\n * `parseSvg` already uses for `domParser`. Never throws itself: an\n * environment with neither capability surfaces through\n * `rasterizeSvgInBrowser`'s own curated \"rasterizeSvg unavailable\" error the\n * first time the returned function is actually called (its `Image`/canvas\n * capability guards — see `browser.ts`), which is the explicit-failure\n * contract spec §11.7's \"契约层\" asks for either way.\n */\nfunction resolveRasterizer(): Rasterizer {\n  return getPlatform().rasterizeSvg ?? rasterizeSvgInBrowser\n}\n\nasync function pixelFindingsForPage(\n  markup: string,\n  page: number,\n  slideId: string | undefined,\n  rasterize: Rasterizer,\n): Promise<AuditFinding[]> {\n  const runs = __collectImageBackedTextRuns(markup)\n  if (runs.length === 0) return []\n\n  const stripped = stripTextNodes(markup)\n  const image = await rasterize(stripped, PIXEL_CANVAS_W, PIXEL_CANVAS_H)\n\n  const findings: AuditFinding[] = []\n  for (const run of runs) {\n    const sampled = worstCaseSample(run, image)\n    if (!sampled) continue\n    if (sampled.ratio < PIXEL_HARD_FINDING_MAX_RATIO) {\n      const issue: PixelContrastIssue = {\n        text: run.text,\n        fill: run.fill,\n        background: sampled.background,\n        ratio: sampled.ratio,\n        required: run.required,\n        fontSize: run.fontSize,\n      }\n      findings.push({\n        page,\n        ...(slideId !== undefined ? { slideId } : {}),\n        code: \"low-contrast\",\n        message: pixelContrastMessage(issue),\n        // `source: \"pixels\"` distinguishes this from an SVG-color-resolved\n        // low-contrast finding's own `detail` shape (`ContrastIssue`,\n        // `deck-audit.ts`) — same `code`, since both are the same category\n        // of defect (text fails contrast against its real background), just\n        // measured through a different, more reliable source for that\n        // background's color.\n        detail: { ...issue, source: \"pixels\" },\n      })\n    }\n  }\n  return findings\n}\n\n/**\n * Test-only re-export (`__`-prefixed, same \"SDK-internal, not part of any\n * public barrel\" convention `deck-audit.ts`'s own `__collectBgRegions`/\n * `__pathBoundingBox` establish): lets `pixel-audit.test.ts` exercise the\n * sampling-grid + `PIXEL_HARD_FINDING_MAX_RATIO` threshold logic directly,\n * with a hand-crafted `rasterize` function returning exact, controlled\n * pixel data — real component geometry (`image-pages.tsx`'s `DarkScrim`, in\n * particular) turned out unable to organically produce a sub-1.5 ratio for\n * *any* photo brightness at the org-line's single-scrim-layer position\n * (confirmed empirically while building this task's own test suite: even a\n * pure-white source image only reaches ~1.83), which is the calibration\n * working as designed (spec §4.3's own \"control false positives\" gate) but\n * makes the threshold-crossing branch unreachable through real IR/layout\n * fixtures alone.\n */\nexport const __pixelFindingsForPage = pixelFindingsForPage\n\n/**\n * The pixel-audit pass over an already-valid deck — `auditDeck(ir, {pixels:\n * true})`'s own async branch (`deck-audit.ts`). Independently walks\n * `ir.slides` (skipping placeholders the same way `runDeterministicAudit`\n * does) rather than reusing that function's own loop, so this module has no\n * static dependency back on it beyond the few named imports at the top of\n * this file — `renderSlideSvg` is pure and synchronous, so re-rendering\n * each non-placeholder slide a second time costs a little CPU, never\n * correctness (spec's own \"no second renderer\" non-goal is about a\n * *different* rendering path, not calling the one true renderer twice).\n *\n * Sequential, not `Promise.all` — deliberately bounds rasterization\n * concurrency to 1 (each Sharp call is real CPU-bound work) and makes the\n * page-order-stable output an obvious property of the code rather than an\n * incidental one `Promise.all`'s array-order guarantee happens to provide.\n *\n * A rasterization failure on any one page (missing platform capability, a\n * remote asset reference, a tainted canvas) propagates out of this function\n * entirely, aborting the whole pixel pass rather than silently skipping\n * just that page — spec §11.7's \"契约层\": a requested-but-failed pixel audit\n * is an explicit failure, never a partial \"clean\".\n */\nexport async function runPixelContrastAudit(ir: PptxIR): Promise<AuditFinding[]> {\n  const rasterize = resolveRasterizer()\n  const findings: AuditFinding[] = []\n  for (let i = 0; i < ir.slides.length; i++) {\n    const slide = ir.slides[i]!\n    if (slide.placeholder) continue\n    const page = i + 1\n    const slideId = slide.id\n    const markup = renderSlideSvg(ir, i)\n    findings.push(...(await pixelFindingsForPage(markup, page, slideId, rasterize)))\n  }\n  return findings\n}\n"],"mappings":"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","names":[]}

package/dist/{registry-C0GJH7ZT.d.ts → registry-D8bkC8ff.d.ts}

@@ -24,7 +24,7 @@ interface PptwisePlatform {
      * Rasterize SVG markup to a fixed-size pixel buffer (audit-v2 phase B,
      * spec §4.3/§11.7) — the one primitive the optional pixel-contrast audit
      * needs and the *only* one Sharp/canvas-shaped work is allowed to hide
-     * behind (`src/svg/audit/pixel-audit.ts` never imports a rasterizer
+     * behind (`src/audit/pixel-audit.ts` never imports a rasterizer
      * itself). `installNodePlatform()` wires this to Sharp; a real browser
      * gets its own default (`./browser.ts`'s `rasterizeSvgInBrowser`) applied
      * at the call site the same way `domParser`'s `?? globalThis.DOMParser`

package/dsh/preview-tool.js

@@ -80,7 +80,7 @@
 
 import { randomUUID } from 'node:crypto'
 import { cpSync, existsSync, realpathSync, renameSync, rmSync } from 'node:fs'
-import { mkdir, readFile, rename, rm, stat, writeFile } from 'node:fs/promises'
+import { copyFile, mkdir, readFile, rename, rm, stat, writeFile } from 'node:fs/promises'
 import { homedir } from 'node:os'
 import { basename, dirname, isAbsolute, join, resolve } from 'node:path'
 import { runChild } from './spawnHidden.js'
@@ -1021,8 +1021,8 @@ async function isFile(path) {
 }
 
 /**
- * Where a deck project directory target actually lives, for the one thing
- * `assemble` cannot carry into the snapshot: a deck-local `theme.json`.
+ * Where a deck project directory target actually lives so its adjacent
+ * `theme.json` can be copied into the snapshot directory.
  *
  * The CLI auto-loads that file for a deck *directory* only, so an assembled
  * IR naming a brand theme would fail to render from anywhere else. Path-form
@@ -1043,6 +1043,15 @@ async function locateDeckDir(target) {
   return undefined
 }
 
+/** Copy an adjacent theme file into the immutable snapshot directory. */
+async function snapshotThemeFile(sourceDir, outDir) {
+  const source = join(sourceDir, THEME_FILE)
+  if (!(await isFile(source))) return undefined
+  const themeFile = join(outDir, THEME_FILE)
+  await copyFile(source, themeFile)
+  return themeFile
+}
+
 /**
  * Copy a single-file IR target, rewriting every local asset src to an
  * absolute path.
@@ -1184,33 +1193,27 @@ async function inlineLocalImages(snapshotPath) {
  * snapshot on its own pins *which* deck rather than the bytes it is made of —
  * which left every later run free to re-read those files. `inlineLocalImages`
  * closes that for the formats it can (see its own note for the ones it
- * cannot).
+ * cannot). An adjacent `theme.json` is copied into the same directory for
+ * both single-file IR and deck-directory targets.
  */
 async function captureSnapshot(cliPath, target, outDir, signal) {
   const snapshot = join(outDir, SNAPSHOT_FILE)
   if (await isFile(target)) {
     await snapshotIrFile(target, snapshot)
     await inlineLocalImages(snapshot)
-    return { snapshot, themeFile: undefined }
+    const themeFile = await snapshotThemeFile(dirname(resolve(target)), outDir)
+    return { snapshot, themeFile }
   }
   await runCli(cliPath, ['assemble', target, '-o', snapshot], signal)
   await inlineLocalImages(snapshot)
   const deckDir = await locateDeckDir(target)
   if (deckDir) {
-    const source = join(deckDir, THEME_FILE)
-    if (await isFile(source)) {
-      const themeFile = join(outDir, THEME_FILE)
-      await writeFile(themeFile, await readFile(source, 'utf8'))
-      return { snapshot, themeFile }
-    }
+    const themeFile = await snapshotThemeFile(deckDir, outDir)
+    if (themeFile) return { snapshot, themeFile }
   }
   return { snapshot, themeFile: undefined }
 }
 
-function themeArgs(record) {
-  return record.themeFile ? ['--theme-file', record.themeFile] : []
-}
-
 /**
  * Read what the card's thumbnail strip needs: the manifest, plus the SVG of
  * every page the strip will actually draw, inlined so the card needs no
@@ -1726,7 +1729,7 @@ export function createPreviewService(cliPath) {
     // that everything the user later does with this preview refers back to.
     await runCli(
       cliPath,
-      ['preview', snapshot, '-o', outDir, '--html', ...themeArgs({ themeFile })],
+      ['preview', snapshot, '-o', outDir, '--html'],
       exec?.signal,
     )
     const bundle = await readPreviewBundle(outDir)
@@ -1754,7 +1757,7 @@ export function createPreviewService(cliPath) {
       const draftArgs = bundle.draft ? ['--draft'] : []
       await runCli(
         cliPath,
-        ['render', snapshot, '-o', pptxPath, ...draftArgs, ...themeArgs({ themeFile })],
+        ['render', snapshot, '-o', pptxPath, ...draftArgs],
         exec?.signal,
       )
     } catch (error) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@liustack/pptwise",
-  "version": "0.22.0",
+  "version": "0.24.0",
   "description": "Stable, editable PPTX generation for AI agents — semantic IR in, native DrawingML out",
   "type": "module",
   "sideEffects": false,
@@ -54,6 +54,7 @@
     "bench:score": "tsx tests/bench/score.mts",
     "docs:list": "node scripts/docs-list.js",
     "gallery": "tsx scripts/gallery.mts",
+    "gen:skill-refs": "tsx scripts/gen-skill-refs.mts",
     "evals:gallery": "tsx evals/gallery/run.mts",
     "fixtures:unassigned-bytes": "tsx scripts/write-unassigned-bytes.mts",
     "prepublishOnly": "pnpm check && pnpm e2e",

package/skills/pptwise/SKILL.md

@@ -1,100 +1,163 @@
 ---
 name: pptwise
-description: Generate a native, editable PPTX deck from an outline, notes, or a document using the pptwise CLI (semantic IR → validate → render). Use when the user asks to create a PPT, deck, presentation, or slides (做PPT/生成PPT/制作演示文稿/幻灯片) and wants a stable, editable, brand-consistent result rather than freeform drawn slides.
+description: Generate a native, editable PPTX deck from an outline, notes, or source material with the pptwise CLI. Use when the user asks to create a PPT, deck, presentation, or slides and wants a deterministic, editable, theme-consistent result.
 ---
 
-# pptwise — deck generation playbook
+# pptwise deck generation playbook
 
-pptwise turns a JSON IR (intermediate representation) into a native DrawingML `.pptx` — every shape stays editable in PowerPoint. You own the content model. The tool owns layout, style, and motion. You never draw SVG or position anything: pick from a controlled vocabulary and let the validate gate catch what will not fit.
+pptwise turns semantic JSON into native DrawingML `.pptx` files. Text and shapes stay editable in PowerPoint. Authors describe what each page is doing and which typed components it contains. The theme and engine own the page face, geometry, color, type, and decoration.
 
-## Run it
+Use this one-way chain. Do not skip backward or decide two layers at once.
 
-Everything in this playbook runs through the CLI: schema, spec/assemble, validate, render, audit, preview, serve, brand extract. Every one of those commands goes through the launcher bundled with this skill, which resolves a working runtime for you. Replace `<skill-dir>` with the directory this SKILL.md lives in:
+```text
+intent -> narrative -> theme binding -> spec with kind -> fill -> render
+```
+
+## Run the CLI
+
+Run every command through the launcher bundled beside this file. Replace `<skill-dir>` with this skill directory.
 
 ```bash
 bash <skill-dir>/scripts/run.sh <args>                                       # macOS / Linux
 powershell -ExecutionPolicy Bypass -File <skill-dir>\scripts\run.ps1 <args>  # Windows
 ```
 
-It tries a compatible `pptwise` on `PATH` first, then `npx`, then `bunx`, forwarding your arguments and its exit code unchanged. Nothing to install first, and the version it runs is pinned to this skill. Exit 78 means no runtime at all: relay the `nextSteps` from its stderr JSON instead of retrying.
+The launcher tries a compatible `pptwise` on `PATH`, then `npx`, then `bunx`. It forwards arguments and exit codes unchanged. Exit 78 means no JavaScript runtime was found. Relay the `nextSteps` from stderr instead of retrying.
 
-Wherever this playbook writes `pptwise <args>`, run it through that launcher.
+If scripts are unavailable, use the first available route:
 
-Right after an install, and any time a command misbehaves in a way the error message does not explain, run `pptwise doctor` before anything else. It reports the runtime, every installed skill copy and whether one is stale, the dsh plugin's version, which optional capabilities are present, and a self-test render. Relay what it says instead of guessing.
+1. `pptwise <args>` when the installed major version matches this skill and is at least the pinned version.
+2. `npx --yes --package @liustack/pptwise@0.24.0 pptwise <args>`.
+3. `bunx --bun @liustack/pptwise@0.24.0 <args>`.
+4. Otherwise ask the user to install Node 22.19+ or Bun.
 
-If your harness forbids running scripts, work down the same order by hand and use the first line that applies:
+Run `pptwise doctor` after installation and whenever a failure is not explained by its own error. Relay the result instead of guessing.
 
-1. A `pptwise` on `PATH` at the same major version as the pin below and no older: `pptwise <args>`.
-2. Otherwise, if `npx` exists: `npx --yes --package @liustack/pptwise@0.22.0 pptwise <args>`.
-3. Otherwise, if `bunx` exists: `bunx --bun @liustack/pptwise@0.22.0 <args>`.
-4. Otherwise tell the user no JavaScript runtime was found, and that installing Node 22.19+ (https://nodejs.org) or Bun (https://bun.sh) is the next step. Do not report pptwise itself as broken.
+## Read live truth first
+
+Never write IR or a spec from memory. Run these at the start of each deck task:
+
+```bash
+pptwise schema
+pptwise schema --spec
+pptwise narratives --json
+pptwise themes --json
+```
+
+Scan the workspace before asking questions. An existing `deck.spec.json` already records the narrative, bound theme, page order, headings, and content kinds. A deck-local `theme.json`, a workspace `themes/` file, a named theme, or a supplied `.thmx`, `.potx`, or branded `.pptx` is a theme signal.
 
 ## Workflow
 
-Interview → spec → pages → validate → audit → render. Re-enter at the smallest step that captures a change. A very small deck (a handful of slides) may skip the spec file and write a single IR, still validating with `pptwise validate`. Never write IR or a spec from memory of a previous session or from this file. Run these fresh every session:
+### 1. Intent
+
+Record four facts before choosing how to tell the story: audience, desired outcome, whether the deck will be presented or circulated, and available time. Derive facts already present in the request or workspace. If a user is present and material facts are still missing, ask all unresolved questions in one round.
+
+### 2. Narrative
+
+Choose the narrative before the theme. The narrative decides argument strategy, pacing, and tone. Use a named preset when it matches, or write explicit `strategy`, `pacing`, and `audience` axes. Pacing controls editorial budgets and the body-text baseline. Narrative never chooses a page face.
+
+Confirm the narrative package before continuing. See `references/spec.md` for the compact interview and spec example.
+
+### 3. Bind a theme
+
+A theme is one complete, self-contained file containing style, a page menu, optional brand rules, and occasion metadata. Its content menu serves a subset of the 11 global `kind` words. Missing words are intentional.
+
+Resolve theme names in this order:
+
+1. The deck directory.
+2. A workspace `themes/` directory while walking upward.
+3. The 24 factory presets.
+
+Use request and workspace signals to shortlist themes by `occasions` and `identity`. Compare two to four candidates with the fixed fitting-room sample:
+
+```bash
+pptwise theme try consulting,swiss,memo
+```
+
+Create means copy. With no existing asset, copy the closest preset into the workspace. With an Office brand file, extract its colors and fonts while copying a suitable donor menu. For a color change, fork the current theme so the whole palette is rederived and the original stays untouched.
+
+```bash
+pptwise theme new --from consulting --id acme-report
+pptwise brand extract corp.pptx -o themes/acme.theme.json --from consulting
+pptwise theme fork acme --primary '#0B5FFF' --id acme-blue
+```
+
+Write the selected theme name into `deck.spec.json` before writing page content. Bound deck commands use that name. There is no render-time theme switch.
+
+A same-menu color fork may replace the bound theme during the workflow. A different menu means a different theme. Return to this step, keep the intent, narrative, facts, data, images, and useful copy, then rewrite the spec and fill against the new menu.
+
+### 4. Write the spec with `kind`
+
+The spec locks theme, narrative, branding posture, page order, page type, heading, and the `kind` of every content page. It contains no render selection state.
+
+- `cover`, `chapter`, and `ending` are page types and do not use `kind`.
+- Every `content` page requires exactly one explicit `kind`.
+- Authors write only a semantic `kind`, never a page face or geometry choice.
+- `focus` and `summary` are optional writing hints.
+
+Run `pptwise spec validate deck.spec.json` until it prints `OK`. A content `kind` outside the bound theme menu is a hard error that lists what the menu offers. Do not relabel the page merely to silence the error. Change the page's intent only when that is semantically honest, or return to the theme step.
+
+The 11 words and their boundaries are in `references/layouts.md`. Full spec guidance and theme creation are in `references/spec.md`.
+
+### 5. Fill pages
+
+Write `pages/<id>.json` in batches of at most four. A page file may contain `components`, `background`, `image_side`, `footnote`, and `notes`. Never repeat `type`, `kind`, or `heading`, because the spec owns them.
+
+Choose components that serve the page's `kind`. `quote` is a page kind. The quotation component is `blockquote`. Component ownership and lookalike choices are in `references/components.md`. Pacing and physical capacity are in `references/density.md`. Image workflows are in `references/images.md`.
+
+After each batch:
 
 ```bash
-pptwise schema             # IR JSON Schema: the single source of truth
-pptwise schema --spec      # deck spec schema
-pptwise narratives --json  # named narrative presets (strategy/pacing/audience axes + theme recommendations)
-pptwise themes --json      # built-in themes (id + label)
+pptwise assemble deck-dir/
+pptwise validate deck-dir/
 ```
 
-Also scan the workspace before asking anyone anything. A confirmed `deck.spec.json` already locks narrative, theme, and branding: do not re-interview, revise that deck instead. A `theme.json`, pinned `pptwise.config.json` theme, user-named theme id, or supplied `.thmx` / `.potx` / branded `.pptx` is a brand signal: extract or honor it. Do not ask whether a template exists.
-
-**Boundary-page rule:** `chapter` and `ending` pages never render `components` or `footnote`. `cover` pages never render `footnote`. A `cover` may carry `components` only when its locked layout declares a slot for them. Today that is `verdict-index` (consulting), which reads the first `bullets` block as up to three numbered arguments. Every other cover layout still drops components. Put body content on a `content` page unless you are filling that consulting argument row. Wrong/right JSON and spec writing: `references/spec.md`.
-
-1. **Interview** (at most one round) when a user is present and any of audience, how it is told, or pacing is still unknown. Relay unresolved questions in **one** message, then stop. Do not fill them in. Q1–Q4, ★ defaults, lookup, `NARRATIVE_INTERVIEW` gate: `references/spec.md`.
-2. **Spec and confirm** before any page content. Write `deck.spec.json` (opens on `cover`, closes on `ending`, everything in between is `content` or `chapter`). Run `pptwise spec validate` until `OK`, then persist a `seed`. Do not re-spec a confirmed spec. How to write it: `references/spec.md`. Branding posture: `references/branding.md`.
-3. **Pages** in batches of at most 4. Write `pages/<id>.json` (`components`, optional `layout`/`notes`). Never write `type`/`heading`. Pin-only and sparse climax layouts: `references/layouts.md`. Component forms: `references/components.md`. Density, beat, capacity: `references/density.md`. Images: `references/images.md`.
-4. **Validate** after every batch: `pptwise assemble deck-dir/` then `pptwise validate deck-dir/` until both print `OK`. Restructure flagged content, never delete it. The assemble/validate/audit/preview/serve loop: `references/validate.md`.
-5. **Audit** once every page is filled: `pptwise audit deck-dir/` until exit 0. Do not substitute a screenshot. Then hand the deck over (`pptwise_preview`, else `preview --html`, else `serve --no-open`): `references/validate.md`.
-6. **Render:** `pptwise render deck-dir/`. Report the absolute path it prints. `--draft` and `--allow-dropped-content` only when the user says so.
-
-Follow-up: edit a page → steps 3–6 on that file only. A new deck → step 1. Unrelated → do not invoke pptwise.
-
-## Component selection
-
-| Content shape | Use | Not |
-|---|---|---|
-| 2–5 headline metrics | `kpi_cards` | `chart` |
-| Series data (trend, comparison, share) | `chart` (`bar`/`line`/`pie`/`funnel`/`dumbbell`/`scatter`/`area`/`donut`/`gauge`) | numbers buried in `bullets` |
-| Exact figures the audience reads row-by-row (price list, spec sheet, metrics-by-period grid) | `data_table` | `chart` |
-| Linear process, no branches | `steps` | `flowchart` |
-| Branching process that reaches an endpoint | `flowchart` | `steps` |
-| Cyclical process with no endpoint — loops back to its own start (PDCA, a product lifecycle, a flywheel, a seasonal cycle) | `cycle` | `flowchart` |
-| Two-sided contrast | `comparison` | two bullet lists |
-| System/organizational layering (a stack of bands, e.g. tech-stack layers or a maturity ladder) | `architecture` | `bullets` |
-| Dated milestones | `timeline` | `bullets` with dates |
-| Phased plan with workstreams | `roadmap` | `timeline` |
-| Phased plan with dated bars on a shared axis | `gantt` | `roadmap` |
-| One verdict or takeaway sentence | `verdict_banner` or `callout` | `paragraph` |
-| 2×2 strategic assessment (strengths/weaknesses/opportunities/threats) | `swot` | `matrix` |
-| 9-block business model canvas | `bmc` | separate `bullets`/`row_cards` |
-| Cumulative bridge/variance breakdown | `waterfall` | `chart` |
-| 2×2 macro-environment scan (political/economic/social/technological) | `pest` | `swot` |
-| Competitive-structure analysis (rivalry + 4 surrounding forces) | `five_forces` | `matrix` |
-| Two-axis value grid with color-coded cells (e.g. region × quarter) | `heatmap` | `matrix` |
-| Proportional flow/quantity distribution across stages (e.g. budget allocation, energy mix) | `sankey` | `chart` (funnel) or `flowchart` |
-| A product/software screenshot that the slide needs to read as "this is real, running software" (an app dashboard, a live product UI) | `device_mockup` | `image` |
-| A roster of people (team, speaker lineup, judging panel, author list) needing an identity anchor with no photo available | `people_cards` | `row_cards`/`icon_cards` |
-| A set of short parallel labels (a tech stack, capabilities, keywords, certifications) — labels, not described items | `tag_row` | `bullets`/`row_cards` |
-
-Lookalike pairs, field notes, and full-body types: `references/components.md`.
+Fix every error and rerun both commands. Restructure content instead of deleting what validation caught.
+
+### 6. Audit, review, and render
+
+When all pages are filled, run:
+
+```bash
+pptwise audit deck-dir/
+pptwise preview deck-dir/ --html
+pptwise render deck-dir/
+```
+
+`audit` must exit 0 before delivery. Add `--pixels` when text sits over photo backgrounds. Use an available `pptwise_preview` tool first. Otherwise hand over the printed `preview.html` path, or run `pptwise serve deck-dir/ --no-open` for a live browser review. Report the absolute `.pptx` path printed by `render`.
+
+Use `--draft` or `--allow-dropped-content` only when the user explicitly requests that compromise.
+
+## Fast component routing
+
+| Page intent | `kind` | Typical component |
+| --- | --- | --- |
+| Ordered reasoning | `points` | `bullets`, `numbered_cards`, `paragraph` |
+| Reorderable inventory | `list` | `row_cards`, `icon_cards`, `tag_row`, `people_cards` |
+| Side-by-side differences | `comparison` | `comparison`, `image_compare`, `matrix`, `swot` |
+| Directed steps or time | `process` | `steps`, `flowchart`, `timeline`, `roadmap`, `gantt`, `cycle` |
+| Numeric structure | `data` | `chart`, `data_table`, `kpi_cards`, `heatmap`, `sankey` |
+| Image as the message | `photo` | `image`, `image_grid`, `device_mockup` |
+| Author's own proposition | `statement` | `verdict_banner`, `callout`, or no component |
+| Another speaker's words | `quote` | `blockquote` |
+| One number as the message | `fact` | one-item `kpi_cards` or no component |
+| Claim plus one exhibit | `evidence` | `image`, `chart`, `data_table`, `code`, `device_mockup` |
+| Containment or levels | `hierarchy` | `architecture`, `bmc`, `five_forces`, `rings` |
 
 ## Rules
 
-- Never edit or post-process the generated `.pptx`
-- Never bypass a `validate` error by deleting the content it flagged — restructure it (split the slide, tighten the heading, pick a denser component type)
-- Public deck text follows the user's language, IR structural fields are always the English enum values from the schema
-- Never tell a user that a `chart`'s or `data_table`'s numbers are editable inside PowerPoint: those components render as grouped shapes and text, fully restylable and retypable, but with no native chart part or `<a:tbl>` behind them. To change the numbers, edit the IR and re-render.
+- Never edit or post-process the generated `.pptx`.
+- Never add coordinates, SVG, page face names, or geometry controls to authored content.
+- Keep public deck copy in the user's language. Keep schema keys and enum values in English.
+- Never claim that `chart` or `data_table` values are native PowerPoint data objects. They export as editable grouped shapes and text. Change figures in the source and rerender.
+- Preview is read-only. Revisions go back into `deck.spec.json`, `pages/*.json`, assets, or the bound theme file.
 
 ## Read when
 
-- `references/spec.md` — writing `deck.spec.json`, choosing page types, or running the narrative interview
-- `references/layouts.md` — pinning a layout, including climax, quote, and evidence sparse pages
-- `references/components.md` — a lookalike pair or a component's fields and limits
-- `references/density.md` — pacing budgets, `beat`, capacity warnings, or slide `decor`
-- `references/branding.md` — extracting a company template, or whether to write `branding: "full"`
-- `references/images.md` — declaring assets, searching stock, or generating art
-- `references/validate.md` — assemble / validate / audit / preview / serve, or revising a page
+- `references/spec.md`: intent, narrative, theme creation, binding, rebinding, spec, and menu errors.
+- `references/layouts.md`: choosing among the 11 `kind` words.
+- `references/components.md`: component ownership, fields, and lookalike choices.
+- `references/density.md`: pacing, capacity, full-page components, and local decoration.
+- `references/branding.md`: deck branding posture, frameless pages, logos, and brand extraction.
+- `references/images.md`: image assets, stock search, generation, and `photo` versus `evidence`.
+- `references/validate.md`: assemble, validate, audit, preview, serve, render, and revision loops.