@liustack/pptfast 0.1.0 → 0.3.0

package/dist/index.d.ts

@@ -1,13 +1,13 @@
 import { z } from 'zod';
 export { P as PptfastPlatform, i as installPlatform } from './registry-CYKxZ0-U.js';
 
-declare const VERSION = "0.1.0";
+declare const VERSION = "0.3.0";
 
 /** Error class thrown by pptfast's public API surface (validation, rendering, export). */
 declare class PptfastError extends Error {
 }
 
-declare const THEME_IDS: readonly ["consulting", "enterprise", "academic", "insight", "campaign", "bloom", "classroom", "ink", "tech", "runway", "journal", "luxe", "heritage"];
+declare const BUILTIN_THEME_IDS: readonly ["consulting", "enterprise", "academic", "insight", "campaign", "bloom", "classroom", "ink", "tech", "runway", "journal", "luxe", "heritage"];
 declare const BackgroundSpecSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     kind: z.ZodLiteral<"color">;
     value: z.ZodString;
@@ -32,6 +32,79 @@ declare const BackgroundSpecSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
         contain: "contain";
     }>>;
 }, z.core.$strict>], "kind">;
+/**
+ * Style-token override (theme.style): deep-partial palette/fonts/shape
+ * merged over the built-in theme (see themes/index.ts resolveStyle). Scope is
+ * deliberately palette-level (spec §11): no defaultBackgrounds or manifest
+ * overrides. gapScale range mirrors the documented sane range in
+ * themes/tokens.ts StyleShape.
+ */
+declare const StyleOverrideSchema: z.ZodObject<{
+    colors: z.ZodOptional<z.ZodObject<{
+        bg: z.ZodOptional<z.ZodString>;
+        surface: z.ZodOptional<z.ZodString>;
+        panel: z.ZodOptional<z.ZodString>;
+        primary: z.ZodOptional<z.ZodString>;
+        accent: z.ZodOptional<z.ZodString>;
+        text: z.ZodOptional<z.ZodString>;
+        muted: z.ZodOptional<z.ZodString>;
+        border: z.ZodOptional<z.ZodString>;
+        chartPalette: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        accentPool: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        cardStroke: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+    fonts: z.ZodOptional<z.ZodObject<{
+        heading: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        body: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        mono: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>>;
+    shape: z.ZodOptional<z.ZodObject<{
+        radius: z.ZodOptional<z.ZodNumber>;
+        gapScale: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+type StyleOverride = z.infer<typeof StyleOverrideSchema>;
+/**
+ * Brand (logical slide-master) config: brand-chrome behavior owned by a theme.
+ * W1 scope = exactly the two flags migrated from the old manifest.chrome.
+ * Single source of truth — the TS type is inferred, never hand-written.
+ */
+declare const BrandConfigSchema: z.ZodObject<{
+    suppressFooterOnCardContent: z.ZodOptional<z.ZodBoolean>;
+    suppressFooterRule: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strict>;
+type BrandConfig = z.infer<typeof BrandConfigSchema>;
+declare const ThemeSchema: z.ZodObject<{
+    id: z.ZodDefault<z.ZodString>;
+    style: z.ZodOptional<z.ZodObject<{
+        colors: z.ZodOptional<z.ZodObject<{
+            bg: z.ZodOptional<z.ZodString>;
+            surface: z.ZodOptional<z.ZodString>;
+            panel: z.ZodOptional<z.ZodString>;
+            primary: z.ZodOptional<z.ZodString>;
+            accent: z.ZodOptional<z.ZodString>;
+            text: z.ZodOptional<z.ZodString>;
+            muted: z.ZodOptional<z.ZodString>;
+            border: z.ZodOptional<z.ZodString>;
+            chartPalette: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            accentPool: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            cardStroke: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>;
+        fonts: z.ZodOptional<z.ZodObject<{
+            heading: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            body: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            mono: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        }, z.core.$strict>>;
+        shape: z.ZodOptional<z.ZodObject<{
+            radius: z.ZodOptional<z.ZodNumber>;
+            gapScale: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>;
+    brand: z.ZodOptional<z.ZodObject<{
+        suppressFooterOnCardContent: z.ZodOptional<z.ZodBoolean>;
+        suppressFooterRule: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
 declare const MetaSchema: z.ZodObject<{
     organization: z.ZodOptional<z.ZodString>;
     authors: z.ZodOptional<z.ZodArray<z.ZodObject<{
@@ -74,7 +147,7 @@ declare const AssetsSchema: z.ZodObject<{
         error: z.ZodOptional<z.ZodString>;
     }, z.core.$strict>>>;
 }, z.core.$strict>;
-declare const BlockSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+declare const ComponentSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     type: z.ZodLiteral<"bullets">;
     items: z.ZodArray<z.ZodString>;
     style: z.ZodOptional<z.ZodEnum<{
@@ -127,9 +200,9 @@ declare const BlockSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     chart_type: z.ZodEnum<{
         line: "line";
         dumbbell: "dumbbell";
+        funnel: "funnel";
         bar: "bar";
         pie: "pie";
-        funnel: "funnel";
     }>;
     direction: z.ZodOptional<z.ZodEnum<{
         horizontal: "horizontal";
@@ -320,14 +393,27 @@ declare const BlockSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
         before_after: "before_after";
     }>>;
 }, z.core.$strict>], "type">;
+/**
+ * All 24 component `type` discriminant values, derived from `ComponentSchema`
+ * itself (never hand-copied) so this list can't drift from the union above.
+ * Typed as plain `readonly string[]` rather than `Component["type"][]` —
+ * every consumer of this list (W5's plan `focus` vocabulary gate,
+ * `src/plan/index.ts`) tests membership of an arbitrary author-supplied
+ * string, and TS's `Array.includes` is invariant in its element type, so a
+ * narrower literal-union type would reject that call at the caller.
+ */
+declare const COMPONENT_TYPES: readonly string[];
 declare const SlideSchema: z.ZodObject<{
-    type: z.ZodEnum<{
+    type: z.ZodDefault<z.ZodEnum<{
         cover: "cover";
         chapter: "chapter";
         content: "content";
         ending: "ending";
-    }>;
-    variant: z.ZodOptional<z.ZodEnum<{
+    }>>;
+    id: z.ZodOptional<z.ZodString>;
+    placeholder: z.ZodOptional<z.ZodLiteral<true>>;
+    layout: z.ZodOptional<z.ZodString>;
+    arrangement: z.ZodOptional<z.ZodEnum<{
         code: "code";
         quote: "quote";
         single: "single";
@@ -336,15 +422,11 @@ declare const SlideSchema: z.ZodObject<{
         image_focus: "image_focus";
         big_number: "big_number";
         assertion_evidence: "assertion_evidence";
-        image_split: "image_split";
-        image_top: "image_top";
-        image_bottom: "image_bottom";
-        image_annotate: "image_annotate";
         aside: "aside";
     }>>;
     heading: z.ZodOptional<z.ZodString>;
     subheading: z.ZodOptional<z.ZodString>;
-    blocks: z.ZodDefault<z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+    components: z.ZodDefault<z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
         type: z.ZodLiteral<"bullets">;
         items: z.ZodArray<z.ZodString>;
         style: z.ZodOptional<z.ZodEnum<{
@@ -397,9 +479,9 @@ declare const SlideSchema: z.ZodObject<{
         chart_type: z.ZodEnum<{
             line: "line";
             dumbbell: "dumbbell";
+            funnel: "funnel";
             bar: "bar";
             pie: "pie";
-            funnel: "funnel";
         }>;
         direction: z.ZodOptional<z.ZodEnum<{
             horizontal: "horizontal";
@@ -635,31 +717,40 @@ declare const SlideSchema: z.ZodObject<{
     footnote: z.ZodOptional<z.ZodString>;
 }, z.core.$strict>;
 declare const PptxIRSchema: z.ZodObject<{
-    version: z.ZodLiteral<"2">;
-    filename: z.ZodString;
-    theme: z.ZodObject<{
-        id: z.ZodEnum<{
-            consulting: "consulting";
-            enterprise: "enterprise";
-            academic: "academic";
-            insight: "insight";
-            campaign: "campaign";
-            bloom: "bloom";
-            classroom: "classroom";
-            ink: "ink";
-            tech: "tech";
-            runway: "runway";
-            journal: "journal";
-            luxe: "luxe";
-            heritage: "heritage";
-        }>;
-        override: z.ZodOptional<z.ZodObject<{
-            primary: z.ZodOptional<z.ZodString>;
-            accent: z.ZodOptional<z.ZodString>;
-            font_heading: z.ZodOptional<z.ZodArray<z.ZodString>>;
-            font_body: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    version: z.ZodDefault<z.ZodLiteral<"3">>;
+    filename: z.ZodDefault<z.ZodString>;
+    scenario: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodUnknown>]>>;
+    theme: z.ZodDefault<z.ZodObject<{
+        id: z.ZodDefault<z.ZodString>;
+        style: z.ZodOptional<z.ZodObject<{
+            colors: z.ZodOptional<z.ZodObject<{
+                bg: z.ZodOptional<z.ZodString>;
+                surface: z.ZodOptional<z.ZodString>;
+                panel: z.ZodOptional<z.ZodString>;
+                primary: z.ZodOptional<z.ZodString>;
+                accent: z.ZodOptional<z.ZodString>;
+                text: z.ZodOptional<z.ZodString>;
+                muted: z.ZodOptional<z.ZodString>;
+                border: z.ZodOptional<z.ZodString>;
+                chartPalette: z.ZodOptional<z.ZodArray<z.ZodString>>;
+                accentPool: z.ZodOptional<z.ZodArray<z.ZodString>>;
+                cardStroke: z.ZodOptional<z.ZodString>;
+            }, z.core.$strict>>;
+            fonts: z.ZodOptional<z.ZodObject<{
+                heading: z.ZodOptional<z.ZodArray<z.ZodString>>;
+                body: z.ZodOptional<z.ZodArray<z.ZodString>>;
+                mono: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            }, z.core.$strict>>;
+            shape: z.ZodOptional<z.ZodObject<{
+                radius: z.ZodOptional<z.ZodNumber>;
+                gapScale: z.ZodOptional<z.ZodNumber>;
+            }, z.core.$strict>>;
         }, z.core.$strict>>;
-    }, z.core.$strict>;
+        brand: z.ZodOptional<z.ZodObject<{
+            suppressFooterOnCardContent: z.ZodOptional<z.ZodBoolean>;
+            suppressFooterRule: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>;
     meta: z.ZodDefault<z.ZodObject<{
         organization: z.ZodOptional<z.ZodString>;
         authors: z.ZodOptional<z.ZodArray<z.ZodObject<{
@@ -711,14 +802,18 @@ declare const PptxIRSchema: z.ZodObject<{
             br: "br";
         }>>;
     }, z.core.$strict>>;
+    seed: z.ZodOptional<z.ZodNumber>;
     slides: z.ZodArray<z.ZodObject<{
-        type: z.ZodEnum<{
+        type: z.ZodDefault<z.ZodEnum<{
             cover: "cover";
             chapter: "chapter";
             content: "content";
             ending: "ending";
-        }>;
-        variant: z.ZodOptional<z.ZodEnum<{
+        }>>;
+        id: z.ZodOptional<z.ZodString>;
+        placeholder: z.ZodOptional<z.ZodLiteral<true>>;
+        layout: z.ZodOptional<z.ZodString>;
+        arrangement: z.ZodOptional<z.ZodEnum<{
             code: "code";
             quote: "quote";
             single: "single";
@@ -727,15 +822,11 @@ declare const PptxIRSchema: z.ZodObject<{
             image_focus: "image_focus";
             big_number: "big_number";
             assertion_evidence: "assertion_evidence";
-            image_split: "image_split";
-            image_top: "image_top";
-            image_bottom: "image_bottom";
-            image_annotate: "image_annotate";
             aside: "aside";
         }>>;
         heading: z.ZodOptional<z.ZodString>;
         subheading: z.ZodOptional<z.ZodString>;
-        blocks: z.ZodDefault<z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        components: z.ZodDefault<z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
             type: z.ZodLiteral<"bullets">;
             items: z.ZodArray<z.ZodString>;
             style: z.ZodOptional<z.ZodEnum<{
@@ -788,9 +879,9 @@ declare const PptxIRSchema: z.ZodObject<{
             chart_type: z.ZodEnum<{
                 line: "line";
                 dumbbell: "dumbbell";
+                funnel: "funnel";
                 bar: "bar";
                 pie: "pie";
-                funnel: "funnel";
             }>;
             direction: z.ZodOptional<z.ZodEnum<{
                 horizontal: "horizontal";
@@ -1027,7 +1118,7 @@ declare const PptxIRSchema: z.ZodObject<{
     }, z.core.$strict>>;
 }, z.core.$strict>;
 type PptxIR = z.infer<typeof PptxIRSchema>;
-type Block = z.infer<typeof BlockSchema>;
+type Component = z.infer<typeof ComponentSchema>;
 type BackgroundSpec = z.infer<typeof BackgroundSpecSchema>;
 type Slide = z.infer<typeof SlideSchema>;
 type Assets = z.infer<typeof AssetsSchema>;
@@ -1038,39 +1129,855 @@ interface ValidationIssue {
     message: string;
     /** 1-based slide number when the issue is scoped to a slide. */
     page?: number;
+    /**
+     * The offending slide's own `id` (`Slide.id`, `ir/index.ts`) — W5
+     * whole-branch review finding 2: the README already claimed "validation
+     * error messages reference [a slide] by [its] id"; this is what makes
+     * that true. Set by every page-scoped issue producer
+     * ({@link checkLayoutApplicability}, the content-quality-gate
+     * translation in {@link validateIr}, {@link checkDuplicateSlideIds})
+     * when the slide in question has an `id` — absent when the slide has
+     * none (bare, pre-W5 IR) or the issue is deck-level, not scoped to any
+     * single slide. {@link formatIssues} appends it in parens after the page
+     * number.
+     */
+    slideId?: string;
 }
 interface ValidateResult {
     ok: boolean;
     ir?: PptxIR;
     errors: ValidationIssue[];
+    /**
+     * Human-readable "`path`: `alias` → `canonical`" entries for every
+     * deterministic field-alias rewrite `validateIr` applied before parsing
+     * (W5 task 4, `ir/field-aliases.ts`'s `normalizeComponentAliases`) — e.g. a
+     * kpi item's `title` silently adopted as `label`. Present only when at
+     * least one rewrite happened; informational, never gates `ok` on its own.
+     */
+    normalized?: string[];
 }
 /**
- * Validate raw JSON against the IR schema, then — once it parses — run the
- * content-quality gate (`checkIrQuality`) against the parsed IR. Both stages
- * must pass for `ok: true`. Quality findings are reported the same way as
- * schema errors (page-scoped, 1-based). `checkIrQuality` itself tags findings
- * "warn" vs "error", but that split was designed for its original consumer
- * (surfacing informational warnings in a UI after generation, per its own
- * docstring) — here it is the pre-generation hard gate, so any finding blocks
- * (`ok: false`), not only "error"-severity ones. Treating "warn" findings
- * (e.g. a cover with no heading) as advisory-only would defeat the point of
- * wiring this in: the spec's core principle is a hard protocol gate, not
- * hoped-for prompt compliance.
+ * Validate raw JSON against the IR schema, then — once it parses — resolve
+ * `scenario` (`resolveScenario`, spec §5: an unrecognized preset name is a
+ * `scenario`-path error, page-less) and run the content-quality gate
+ * (`checkIrQuality`, passed the resolved axes) against the parsed IR. All
+ * stages must pass for `ok: true`. Quality findings are reported the same
+ * way as schema errors (page-scoped, 1-based). `checkIrQuality` itself tags
+ * findings "warn" vs "error", but that split was designed for its original
+ * consumer (surfacing informational warnings in a UI after generation, per
+ * its own docstring) — here it is the pre-generation hard gate, so any
+ * finding blocks (`ok: false`), not only "error"-severity ones. Treating
+ * "warn" findings (e.g. a cover with no heading) as advisory-only would
+ * defeat the point of wiring this in: the spec's core principle is a hard
+ * protocol gate, not hoped-for prompt compliance.
+ *
+ * Before any of that, `normalizeComponentAliases` (W5 task 4,
+ * `ir/field-aliases.ts`) gets one deterministic pass at `input` — rewriting
+ * a known synonym field name (kpi `title`→`label`, quote `content`→`text`,
+ * …) only where the canonical key is absent, so the schema parse below never
+ * sees the alias as an "unrecognized key" in the first place. Ordering
+ * versus the v2 migration check right above it is unobservable (v2 IR uses
+ * `blocks`, never `components`, so the normalizer's slide/component walk is
+ * always a no-op on it) — it runs second here only so a doomed v2 input
+ * skips the extra walk. Purely informational: every rewrite is recorded as a
+ * human-readable `path: alias → canonical` string and threaded onto
+ * `ValidateResult.normalized` on *every* return path below via
+ * `withNormalized`, success or failure alike — it never itself gates `ok`.
  */
 declare function validateIr(input: unknown): ValidateResult;
+/**
+ * `"page 2 (p-kpi) — path: message"` when the issue carries both a `page`
+ * and a `slideId` (W5 whole-branch review finding 2 — the README's own
+ * claim that a validation error "references [a slide] by [its] id", made
+ * true) — the parenthesized id is appended only alongside a `page` number,
+ * never on its own: a deck-level issue that happens to set a representative
+ * `slideId` with no `page` ({@link checkDuplicateSlideIds} above) keeps its
+ * pre-existing, unchanged format. Every other combination — `page` with no
+ * `slideId` (an id-less slide), or neither — is byte-identical to before
+ * this task.
+ */
 declare function formatIssues(errors: ValidationIssue[]): string;
 /** Render a single slide to standalone SVG markup (preview / self-check). */
 declare function renderSlideSvg(ir: PptxIR, slideIndex: number): string;
 /** Full pipeline: validate → SVG → DrawingML → animation patches → pptx bytes. */
-declare function generatePptx(input: unknown): Promise<Uint8Array>;
+declare function generatePptx(input: unknown, opts?: {
+    draft?: boolean;
+}): Promise<Uint8Array>;
 interface ThemeInfo {
     id: string;
     label: string;
     colors: Record<string, unknown>;
 }
-/** Built-in theme catalog with labels and color tokens. */
+/** Built-in theme catalog with labels and style color tokens. */
 declare function listThemes(): ThemeInfo[];
 /** JSON Schema for the IR — feed this to a model before it writes IR. */
 declare function irJsonSchema(): Record<string, unknown>;
+/** JSON Schema for style-token overrides (IR theme.style, --style files, config "style"). */
+declare function styleJsonSchema(): Record<string, unknown>;
+
+type LayoutType = "cover" | "chapter" | "content" | "ending";
+interface StyleColors {
+    bg: string;
+    surface: string;
+    panel?: string;
+    primary: string;
+    accent: string;
+    text: string;
+    muted: string;
+    border?: string;
+    chartPalette: string[];
+    /**
+     * Optional accent color pool for themes whose layout grammar cycles through
+     * multiple accent colors (e.g. tech card corner stripes). Themes that
+     * only use a single accent color can omit this.
+     */
+    accentPool?: string[];
+    /**
+     * Optional hairline stroke color for the shared "surface card" shells
+     * (kpi_cards / icon_cards / callout — see components/kpi.tsx,
+     * components/icon-cards.tsx, components/callout.tsx). Those component renderers are
+     * shared across every theme and must stay theme-agnostic (no
+     * `if (themeId === ...)` branching), so a theme that wants its cards
+     * outlined sets this token instead — the renderers just consult it and add
+     * a 1px stroke when it's defined. Omitted (`undefined`, the default) draws
+     * no stroke, so every theme that doesn't set it keeps its current
+     * fill-only card unchanged.
+     */
+    cardStroke?: string;
+}
+interface StyleFonts {
+    heading: string[];
+    body: string[];
+    mono?: string[];
+}
+interface StyleTokens {
+    id: string;
+    allowCustomBackground?: boolean;
+    colors: StyleColors;
+    fonts: StyleFonts;
+    shape?: StyleShape;
+    defaultBackgrounds: Record<LayoutType, BackgroundSpec>;
+}
+/**
+ * 主题细节 shape token（2026-07-10 用户立项，spec：
+ * .issues/specs/2026-07-10-pptx-theme-detail-tokens-design.md）。
+ * 全部可选——缺省时各消费点沿用自己的 baked 值（零观感）。
+ */
+interface StyleShape {
+    /** 卡片/横幅圆角 px（统一值）。缺省=各消费点原 baked 值（kpi 8/architecture 6/白卡 14 等）。 */
+    radius?: number;
+    /** 块间距缩放（1=现 BLOCK_GAP）。建议范围 [0.8, 1.3]。 */
+    gapScale?: number;
+}
+
+type MotifArchetypeId = "banner-motif" | "rail-motif" | "poster-motif" | "constellation-motif" | "corner-ornament-motif" | "tone-adaptive-motif" | "campaign-motif" | "bloom-motif" | "classroom-motif" | "ink-motif" | "luxe-motif" | "enterprise-motif" | "heritage-motif";
+
+/**
+ * A theme = distributable bundle: `style` (style tokens) + `brand` (brand
+ * chrome) + affinity tags (filled in W4).
+ *
+ * `id` is a plain `string`, not `CanonicalThemeId` — the 13 builtins satisfy
+ * this (`CanonicalThemeId` is a subtype of `string`), but `registerTheme`
+ * below (W3 task 4's SDK registration seam) must also accept ids outside that
+ * closed union.
+ */
+interface ThemeDefinition {
+    id: string;
+    style: StyleTokens;
+    brand: BrandConfig;
+    tags: readonly string[];
+    /**
+     * 主题的「选择权」配置（spec §3 theme.layouts 命名裁决；W2 任务 2 由
+     * src/themes/manifest.ts〔已删除〕的旧选择权类型原地迁居于此）——四页型
+     * 各自允许哪些 archetype 参与自动选型。排印/色彩在 style，这里只放集合。
+     * **W4 全集放开**（spec §3「缺省 = 全集，策展收窄塑造个性」，design
+     * decision 7）：十三内置主题四页型默认均为 {@link fullArchetypeSet} 的
+     * 全集。design decision 7/8 曾经的六处对比度策展排除（luxe/campaign/
+     * classroom 的 content 排除 banner-heading、tech 的 cover/content、
+     * consulting 的 chapter）已在 W4 fix round 随对比度自适应 ink helper
+     * （`src/svg/ink.ts`）的根因修复全部撤销。fix round 自身新发现的三处
+     * （bloom/classroom/heritage 的 chapter 排除 fashion-chapter）也已在
+     * post-v0.3 W8 fix round 随 `readableOn` 两墨实测对比度取优的根因修复一并
+     * 撤销（backlog item 2）——十三主题四页型现在均为不折不扣的全集，无任何
+     * 排除残留。页型空集 = 该页型回落调用侧兜底（十三主题四页型均非空，
+     * `definitions.test.ts` 锁死）。id 是通用 string（不再按页型区分
+     * archetype id 联合类型）。
+     */
+    layouts: Record<Slide["type"], readonly string[]>;
+    /** Motif：单值，非 allowed-set（spec §3 示意）。undefined = 该主题无 motif 装饰（十三主题中 runway 留空，其余均已设）。 */
+    motif?: MotifArchetypeId;
+}
+/**
+ * `registerTheme`'s input shape (W4, spec §3 "缺省 = 全集"): identical to
+ * {@link ThemeDefinition} except `layouts` is optional, and — when present —
+ * each of its four slide-type entries is independently optional too. A
+ * slide type this theme doesn't narrow (its own key omitted, or the whole
+ * `layouts` object omitted) defaults to that type's full registered-
+ * archetype set ({@link FULL_LAYOUTS}) — the exact same default every
+ * builtin theme in `LAYOUTS` above resolves to for a slide type it doesn't
+ * curate away from. `getThemeDefinition`/`REGISTERED_THEMES` still only ever
+ * hold the fully-resolved `ThemeDefinition` shape (`layouts` total over all
+ * four types) — `registerTheme` performs the defaulting once, here, so
+ * every downstream reader (`resolveArchetypeId` foremost) can keep assuming
+ * a total record and never re-derive "was this slide type curated or
+ * defaulted".
+ */
+type ThemeRegistration = Omit<ThemeDefinition, "layouts"> & {
+    layouts?: Partial<Record<Slide["type"], readonly string[]>>;
+};
+/**
+ * Register a theme at runtime (SDK seam, not the v0.4 distribution
+ * protocol). Validates just enough to keep the render chain from silently
+ * breaking on a malformed registration — not a full schema:
+ *
+ * - `id` must not collide with a builtin or an already-registered theme.
+ * - each of the four slide types, once defaulted ({@link ThemeRegistration}),
+ *   must have at least one layout id that is both registered in
+ *   `LAYOUT_REGISTRY` and valid for that slide type (the same registry
+ *   `resolveArchetypeId`/`FullSlideSvg` select from — a theme never ships
+ *   new render code, only a curated subset of the existing 30 archetypes +
+ *   4 takeovers, per `docs/architecture.md`'s "Adding a theme" section). An
+ *   *explicit* empty array for a slide type still fails this check (the
+ *   default only kicks in when the key — or `layouts` itself — is omitted
+ *   entirely, `undefined`, never for a caller-supplied `[]`).
+ * - `style` must be present (a JS caller can bypass the TS type).
+ *
+ * Once registered, the theme participates in `getInstalledThemeIds`,
+ * `getThemeDefinition` (hence `effective-layout.ts`/`FullSlideSvg`'s
+ * selection and `resolveBrand`), and `themes/index.ts`'s `resolveStyle` —
+ * every internal theme lookup, with no separate "registered theme" branch
+ * for callers to remember.
+ */
+declare function registerTheme(def: ThemeRegistration): void;
+/** Every installed theme id: the 13 builtins, then registered themes in registration order. */
+declare function getInstalledThemeIds(): readonly string[];
+/**
+ * Resolve a theme id to its full definition — a registered theme first, then
+ * the builtin fallback (`THEME_DEFINITIONS[resolveThemeId(id)]`, which itself
+ * folds an unrecognized id to consulting). The one lookup every internal
+ * consumer that used to read `THEME_DEFINITIONS[resolveThemeId(id)]`
+ * directly (`effective-layout.ts`, `FullSlideSvg.tsx`) now calls instead, so
+ * a registered theme's curated layouts actually drive selection end-to-end.
+ */
+declare function getThemeDefinition(id: string): ThemeDefinition;
+
+declare const MODE_VALUES: readonly ["pyramid", "narrative", "instructional", "showcase", "briefing"];
+declare const DELIVERY_VALUES: readonly ["text", "balanced", "presentation"];
+declare const AUDIENCE_VALUES: readonly ["executive", "technical", "customer", "public"];
+
+/**
+ * Narrative argument style (spec §5's five-way mode classification). Each
+ * mode carries a component/layout tendency set (soft-weight material,
+ * consumed by W4's weighted selection — nothing consumes it this wave) and
+ * a rhythm policy (consumed by W5's plan-validate rotation gate).
+ */
+type Mode = (typeof MODE_VALUES)[number];
+/**
+ * Content density budget + typographic baseline (spec §5 delivery table).
+ * See {@link DeliveryBudget} for the dual-attribute capacity split this axis
+ * is one half of.
+ */
+type Delivery = (typeof DELIVERY_VALUES)[number];
+/**
+ * Tone anchor only (spec §5: audience is tone-anchoring only, no rendering
+ * effect on the IR yet). Reserved for a future lint pass (e.g. executive ×
+ * long paragraphs → suggest kpi_cards/verdict_banner instead). The rule set
+ * itself is explicitly out of scope this wave (spec §10 open questions).
+ */
+type Audience = (typeof AUDIENCE_VALUES)[number];
+interface ScenarioAxes {
+    readonly mode: Mode;
+    readonly delivery: Delivery;
+    readonly audience: Audience;
+}
+
+interface ModeDefinition {
+    id: Mode;
+    /**
+     * Layout/component tendency set (soft-weight material). Filled row-for-row
+     * from spec §5's mode table for W4's weighted selection step (spec §6
+     * step 4: in-set candidates get ×3 weight, out-of-set ×1 floor — not
+     * implemented yet, this module only stores the data).
+     *
+     * The set deliberately mixes two different vocabularies: component `type`
+     * names (e.g. "kpi_cards", "chart" — see the `Component` discriminated
+     * union in `ir/index.ts`) and layout `id`s (e.g. "image-split" — see
+     * `LAYOUT_REGISTRY` in `svg/layouts/registry.ts`). This is intentional,
+     * not an oversight: W4's weighting step resolves each entry against
+     * whichever vocabulary it belongs to (component types when scoring a
+     * candidate's components, layout ids when scoring the candidate layout
+     * itself). Nothing in this wave (W3) reads this field.
+     */
+    tendencies: readonly string[];
+    /**
+     * Content-archetype soft-weight set for W4's weighted layout selection
+     * (spec §6 step 4: in-set candidates get `TENDENCY_WEIGHT` (×3), out-of-set
+     * get the `BASE_WEIGHT` floor (×1) — both named constants live in
+     * `svg/effective-layout.ts`, next to `resolveArchetypeId`, the sole
+     * consumer). Deliberately a separate field from {@link tendencies} above,
+     * not a reinterpretation of it: `tendencies` mixes component-type names and
+     * layout ids drawn from spec §5's mode table verbatim and also feeds W5's
+     * plan `focus` vocabulary gate, so narrowing its meaning here would be a
+     * breaking change to an existing consumer. This field holds only
+     * `LAYOUT_REGISTRY` content-archetype ids (`svg/layouts/registry.ts`'s
+     * `CONTENT_LAYOUTS` keys) — cover/chapter/ending ids never appear in any
+     * mode's list here, which is exactly why `resolveArchetypeId`'s weighting
+     * is a no-op for those three slide types (spec: "身份页个性来自 theme 不来自
+     * mode，均匀取样") without needing a slide-type special case — a weight
+     * lookup against an id that can never match falls through to the ×1 floor
+     * for every candidate, uniform by construction. `tone-adaptive-content`
+     * appears in no mode's list either (spec's "万金油" call-out: it is the one
+     * content archetype meant to read as mode-neutral, so it always gets the
+     * ×1 floor too).
+     */
+    layoutTendencies: readonly string[];
+    /**
+     * Rhythm template descriptor (spec §5's per-mode rhythm-default column),
+     * parameterized by mode for W5's plan-validate rotation gate — e.g.
+     * briefing is exempt from a generic "three same-rhythm pages in a row is
+     * an error" rule because uniform-dense *is* briefing's correct default,
+     * not a violation of it (spec §5's plan-gate section calls out that a
+     * generic same-rhythm-streak rule would reject briefing's own default).
+     * Not consumed this wave.
+     */
+    rhythmPolicy: "anchor-open" | "alternate" | "repetition-ok" | "anchor-sparse" | "uniform-dense";
+}
+declare const MODE_DEFINITIONS: Record<Mode, ModeDefinition>;
+
+interface DeliveryBudget {
+    /**
+     * Body-text baseline, in px, at 1280×720 slide geometry (spec §5
+     * delivery table's body-baseline column). Wired into rendering as of W4
+     * task 3 (design decision 9): `src/svg/FullSlideSvg.tsx` resolves
+     * `DELIVERY_BUDGETS[resolveScenario(ir.scenario).delivery].bodyBaselinePx`
+     * once and passes it into `buildCtx`, which stores it as
+     * `ComponentCtx.bodyFontPx` — the sole font-size input for the
+     * paragraph/bullets/callout trio ("正文" = continuous running text).
+     * Every other component's own bespoke type scale, the heading system, and
+     * quote's fixed 26px attribution line don't read this field. Since
+     * `balanced` (24px) is the scenario default, an omitted-scenario deck now
+     * renders body text at 24px, not the previous fixed 20px — the one-time,
+     * spec-sanctioned snapshot re-pin that landed alongside this wiring.
+     */
+    bodyBaselinePx: number;
+    /**
+     * Per-slide editorial budget (component count) — content discipline
+     * ("how many things belong on this slide"), not geometry. Spec §5's
+     * dual-attribute capacity split keeps *physical* capacity ("how many
+     * things fit in this layout's slots") on the layout registry's body-slot
+     * `capacity` metadata (`svg/layouts/registry.ts`). The W3 quality gate
+     * takes `min(this budget, the resolved layout's body capacity)`.
+     */
+    maxComponentsPerSlide: number;
+    bullets: {
+        maxItems: number;
+        /**
+         * Same "unit" concept the deleted `CAPACITY.bullets` used
+         * (`measureTextUnits`, CJK weight = 1.0) — a visual-width-weighted
+         * character count, not a raw `.length`. The old physical ceiling (53,
+         * derived from render geometry) was deleted in W3 without a replacement
+         * check because every delivery's editorial budget here (30/40/48) is
+         * already strictly tighter than it — the quality gate now applies
+         * exactly this one number per delivery.
+         */
+        maxUnitsPerItem: number;
+    };
+}
+/**
+ * Pinned to spec §5's delivery table (`bodyBaselinePx` / editorial budget /
+ * bullets budget columns): text 20/5/6×48, balanced 24/4/5×40,
+ * presentation 32/3/4×30.
+ */
+declare const DELIVERY_BUDGETS: Record<Delivery, DeliveryBudget>;
+
+interface ScenarioPreset {
+    id: string;
+    axes: ScenarioAxes;
+    /**
+     * Soft theme recommendations — a suggestion, never a hard constraint
+     * (spec §5). Surfaced in workflow step ① so an agent can open with a
+     * themed proposal — the user may still pick any theme. Every entry here
+     * must be a real `BUILTIN_THEME_IDS` member (`ir/index.ts`) — enforced by
+     * this module's test suite, which imports and tests against it.
+     */
+    themeRecommendations: readonly string[];
+}
+/** Pinned to spec §5's 7 named presets and their theme recommendation table. */
+declare const SCENARIO_PRESETS: Record<string, ScenarioPreset>;
+/**
+ * = `SCENARIO_PRESETS.general.axes` (briefing × balanced × public) — the
+ * global default when scenario is omitted entirely (spec §5's defaults
+ * chain).
+ */
+declare const DEFAULT_SCENARIO: ScenarioAxes;
+/**
+ * Resolve a scenario input down to concrete axes, per spec §5's design
+ * principle "omission gets the default, a typo is a hard error" (weak-model
+ * friendly: a model that leaves a field out gets a sane deck, a model that
+ * misspells a value gets a loud, actionable error instead of a silently
+ * wrong deck):
+ *
+ * - `undefined` → {@link DEFAULT_SCENARIO} (the `general` preset's axes)
+ * - a preset id string → that preset's axes (unknown id throws
+ *   {@link PptfastError}, listing the available preset ids)
+ * - a partial axes object → each axis defaults independently
+ *   (mode → "briefing", delivery → "balanced", audience → "public" — these
+ *   happen to equal `DEFAULT_SCENARIO`'s values because `general` *is* that
+ *   exact combination, but the fallback here is per-axis, not "any omitted
+ *   axis falls back to the whole default object")
+ *
+ * An unknown axis value, or an unknown key on the partial axes object,
+ * always throws {@link PptfastError} (never silently ignored or dropped) —
+ * omission and a typo are different intents, and only the former has a
+ * reasonable default.
+ */
+declare function resolveScenario(input: string | Partial<ScenarioAxes> | undefined): ScenarioAxes;
+
+/**
+ * Deck plan schema + validation (spec §5 "plan artifact and hard gates", W5 task 2).
+ *
+ * A plan is a workflow artifact, not a render prerequisite (spec §5's
+ * "escape hatch": a bare IR v3 renders directly, plan validate is a separate,
+ * optional gate for the plan-authoring stage of the six-phase workflow).
+ * This module stays pure and Node-free — no `fs`, no CLI concerns — so it
+ * can sit in `src/index.ts`'s dependency closure exactly like `src/ir` and
+ * `src/scenario` already do (`AGENTS.md`'s layout rule). `src/cli/commands.ts`
+ * owns the one Node-touching wrapper (`runPlanValidate`: read file, call
+ * {@link validatePlan}, format the result).
+ *
+ * Design mirrors `api.ts`'s `validateIr`/`ValidateResult` throughout
+ * (structural zod pass first, then a sequential chain of hard-gate
+ * categories, each short-circuiting the chain on its own failure — see
+ * {@link validatePlan}'s own comment for why): same overall shape, adapted
+ * for plan pages being keyed by an author-assigned `id` instead of IR's
+ * positional slide index.
+ */
+
+/**
+ * Mirrors `SlideSchema.type` / `SlideType` (`ir/index.ts`,
+ * `svg/layouts/registry.ts`) exactly. Kept as an independent literal tuple
+ * here (not imported from either) — a plan page's `type` is a 4-value enum
+ * on its own schema, not a re-export of IR's — but the `satisfies` clause
+ * makes any future drift between the two a compile error instead of a
+ * silent mismatch.
+ */
+declare const PAGE_TYPES: readonly ["cover", "chapter", "content", "ending"];
+declare const RHYTHM_VALUES: readonly ["anchor", "dense", "breathing"];
+type PlanPageType = (typeof PAGE_TYPES)[number];
+type PlanRhythm = (typeof RHYTHM_VALUES)[number];
+/**
+ * A single plan page (spec §5). `type`/`heading` are required — unlike IR's
+ * own `SlideSchema` (where both default/omit for weak-model friendliness),
+ * a plan is the authoring artifact those fields get *locked* from at
+ * assemble time (W5 task 3), so leaving either implicit here would defeat
+ * the point. `rhythm`/`focus`/`summary` stay optional per spec §5's defaults
+ * chain ("rhythm omitted → auto-rotates by page position — focus/summary/layout/slot can all be omitted").
+ */
+declare const PlanPageSchema: z.ZodObject<{
+    id: z.ZodString;
+    type: z.ZodEnum<{
+        cover: "cover";
+        chapter: "chapter";
+        content: "content";
+        ending: "ending";
+    }>;
+    heading: z.ZodString;
+    rhythm: z.ZodOptional<z.ZodEnum<{
+        anchor: "anchor";
+        dense: "dense";
+        breathing: "breathing";
+    }>>;
+    focus: z.ZodOptional<z.ZodString>;
+    summary: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+type PlanPage = z.infer<typeof PlanPageSchema>;
+/**
+ * Top-level deck plan shape (spec §5). `scenario`/`theme` deliberately have
+ * no schema-level `.default(...)` — same reasoning as `PptxIRSchema`'s own
+ * `scenario` field (`ir/index.ts`): the resolved value is never baked back
+ * into the parsed shape, {@link validatePlan} (here) and, later, assemble
+ * (W5 task 3) each resolve it themselves. `seed` is accepted but entirely
+ * unexamined by this module — "not validatePlan's concern" (spec's own wording):
+ * assemble generates and suggests writing one back on first materialization.
+ */
+declare const DeckPlanSchema: z.ZodObject<{
+    version: z.ZodDefault<z.ZodLiteral<"1">>;
+    scenario: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodUnknown>]>>;
+    theme: z.ZodOptional<z.ZodString>;
+    filename: z.ZodOptional<z.ZodString>;
+    seed: z.ZodOptional<z.ZodNumber>;
+    meta: z.ZodDefault<z.ZodObject<{
+        organization: z.ZodOptional<z.ZodString>;
+        authors: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            role: z.ZodOptional<z.ZodString>;
+            org: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>>;
+        date: z.ZodOptional<z.ZodString>;
+        version: z.ZodOptional<z.ZodString>;
+        confidentiality: z.ZodOptional<z.ZodEnum<{
+            public: "public";
+            internal: "internal";
+            confidential: "confidential";
+            restricted: "restricted";
+        }>>;
+        contact: z.ZodOptional<z.ZodObject<{
+            name: z.ZodOptional<z.ZodString>;
+            email: z.ZodOptional<z.ZodString>;
+            phone: z.ZodOptional<z.ZodString>;
+            website: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>;
+        copyright: z.ZodOptional<z.ZodString>;
+        animation: z.ZodOptional<z.ZodObject<{
+            transition: z.ZodOptional<z.ZodEnum<{
+                fade: "fade";
+                push: "push";
+                wipe: "wipe";
+                none: "none";
+            }>>;
+            elements: z.ZodOptional<z.ZodEnum<{
+                none: "none";
+                auto: "auto";
+            }>>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>;
+    brand: z.ZodOptional<z.ZodObject<{
+        logo_asset_id: z.ZodOptional<z.ZodString>;
+        position: z.ZodOptional<z.ZodEnum<{
+            tl: "tl";
+            tr: "tr";
+            bl: "bl";
+            br: "br";
+        }>>;
+    }, z.core.$strict>>;
+    pages: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        type: z.ZodEnum<{
+            cover: "cover";
+            chapter: "chapter";
+            content: "content";
+            ending: "ending";
+        }>;
+        heading: z.ZodString;
+        rhythm: z.ZodOptional<z.ZodEnum<{
+            anchor: "anchor";
+            dense: "dense";
+            breathing: "breathing";
+        }>>;
+        focus: z.ZodOptional<z.ZodString>;
+        summary: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+type DeckPlan = z.infer<typeof DeckPlanSchema>;
+/** JSON Schema for the deck plan — feed this to a model before it writes a plan (see `pptfast schema --plan`). */
+declare function planJsonSchema(): Record<string, unknown>;
+interface PlanValidationIssue {
+    path: string;
+    message: string;
+    /** The offending page's `id`, when the issue is scoped to one specific
+     *  page and that page's `id` could be determined — absent for deck-level
+     *  issues (e.g. "pages non-empty") and for structural issues on a page
+     *  whose own `id` itself failed to parse. */
+    pageId?: string;
+}
+interface PlanValidateResult {
+    ok: boolean;
+    plan?: DeckPlan;
+    errors: PlanValidationIssue[];
+}
+declare function formatPlanIssues(errors: PlanValidationIssue[]): string;
+/**
+ * Plan-level theme default (spec §5's defaults chain: "theme omitted →
+ * consulting") — the same default IR's own `theme.id` field carries
+ * (`ThemeSchema` in `ir/index.ts`). Exported so a caller already holding a
+ * validated {@link DeckPlan} (the CLI's OK-summary line) doesn't re-derive
+ * the fallback itself.
+ */
+declare function resolvePlanThemeId(plan: DeckPlan): string;
+/**
+ * Deck-level page-count range per delivery (spec §5's delivery table,
+ * initial values — "text 8-30 / balanced 6-24 / presentation 4-16", not yet
+ * tuned against real usage). Independent of `DELIVERY_BUDGETS`
+ * (`scenario/index.ts`, per-slide component-count/bullets editorial
+ * budget) — this is a separate, deck-wide page-count concern the spec calls
+ * out as its own hard gate ("page count vs. delivery recommended range").
+ */
+declare const PLAN_PAGE_COUNT_RANGE: Record<Delivery, {
+    min: number;
+    max: number;
+}>;
+/**
+ * Validate raw JSON against the plan schema, then — once it parses — run the
+ * spec §5 hard-gate chain. Mirrors `validateIr`'s (`api.ts`) overall shape: a
+ * structural zod pass first, then a sequence of isolated hard-gate
+ * categories, each short-circuiting the whole chain on its own failure
+ * (rather than accumulating errors across categories) so a later category
+ * never has to guess at what an earlier, already-broken one would have
+ * meant — e.g. rhythm-rotation and page-count both need a resolved
+ * scenario, so nothing past the scenario/theme stage runs until that
+ * resolves cleanly. Every plan-gate philosophy here is "hard block, no soft
+ * warning" (spec §5's "escape hatch" section — a plan that doesn't fit this shape
+ * should be authored as bare IR instead, not warned-and-shipped).
+ */
+declare function validatePlan(input: unknown): PlanValidateResult;
+
+/**
+ * One page's fillable content — everything a plan page's `id` does *not*
+ * already lock in. Deliberately excludes `type`/`heading` (plan-owned, see
+ * {@link assembleDeck}'s locked-field gate) and `subheading`/`decor`
+ * (legitimate `Slide` fields, but outside this record's shape by spec §7's
+ * own layout — "pages/<id>.json contains only components" — a plan/pages deck can't
+ * author either one — a hand-authored bare IR still can). Every field here is
+ * a same-name, same-shape subset of `Slide`'s own optional fields
+ * (`../ir`'s `SlideSchema`) — reused, not redeclared, so the two can't drift.
+ */
+interface PageContent {
+    components?: Component[];
+    layout?: string;
+    arrangement?: NonNullable<Slide["arrangement"]>;
+    background?: BackgroundSpec;
+    image_side?: "left" | "right";
+    footnote?: string;
+}
+interface AssembleResult {
+    ir: PptxIR;
+    /**
+     * Set only when `plan.seed` was absent and {@link assembleDeck} generated
+     * one deterministically (see the seed section of this function's doc
+     * comment) — `undefined` when `plan.seed` was already present and simply
+     * passed through. The CLI shell (W5 task 5) is the one that acts on this:
+     * suggest writing the value back into the plan file, never rewrite it
+     * itself (assemble stays a pure function, no fs side effects here).
+     */
+    generatedSeed?: number;
+    /**
+     * Count of pages whose `layout` field this call filled in via
+     * {@link materializeEffectiveLayouts} (W4 design decision 10) —
+     * `undefined` when zero, same "absent means nothing to report" posture as
+     * {@link generatedSeed} just above (a page with an explicit pin already in
+     * its page file, or every omitted page landing on the image-cover
+     * takeover's `null` bypass, both leave this unset). Purely informational:
+     * the CLI shell (`runAssemble`, `../cli/commands.ts`) surfaces it as a
+     * one-line note, nothing here or downstream acts on the number itself.
+     */
+    materializedLayoutCount?: number;
+}
+/**
+ * Assemble a validated plan plus a per-page content record into a renderable
+ * IR. See this module's own top comment for the overall shape. Step numbers
+ * below match the W5 task-3 brief's own numbered "inject semantics" list verbatim —
+ * kept in that exact order because two of them (locked-field vs. orphan)
+ * both throw and their relative order is otherwise unobservable from either
+ * doc comment alone.
+ *
+ * 1. `plan` is `unknown` (same boundary `validatePlan` itself has — a plan
+ *    is almost always freshly `JSON.parse`d off disk by the caller) —
+ *    invalid shape or a failed hard gate throws {@link PptfastError} with
+ *    `validatePlan`'s own formatted issue list, not a re-derived message.
+ * 2. Shape guard + locked-field protection: a `pages[id]` entry must first be
+ *    a plain object — not `null`, an array, or a primitive — else throws.
+ *    `pages` is `unknown`-shaped off disk same as `plan` itself (step 1), so
+ *    a JSON `null`/string/array content value is a real possibility, not
+ *    just a type-system hole, and `Object.hasOwn` throws its own
+ *    uninformative native `TypeError` on `null` (and silently no-ops on a
+ *    string/array/number) rather than this gate's own readable message.
+ *    Once that holds, a `pages[id]` entry that carries a `type` or `heading`
+ *    *key* — even set to `undefined` — throws. `Object.hasOwn`, not a
+ *    `!== undefined` read, is what makes that "even `undefined`" case
+ *    catchable: `PageContent` itself never declares either field, but a
+ *    page file freshly parsed off disk is `unknown` before it reaches this
+ *    function's declared `PageContent` parameter type, so a stray
+ *    `"heading": null`-turned-`undefined` or a copy-pasted empty key is
+ *    exactly the drift this gate exists to catch instead of silently
+ *    ignoring.
+ * 3. Orphan keys: a `pages` entry whose id isn't any plan page's id. Listed
+ *    together with a fix suggestion, checked only after every present page
+ *    has cleared the locked-field gate (step 2) — an orphan file that
+ *    *also* happens to redeclare `heading` reports as locked-field first.
+ * 4. Missing pages (a plan id with no `pages` entry) become a placeholder
+ *    slide — never an error. Spec §7's own words: "assemble's precise
+ *    semantics — a missing page always succeeds (placeholder), a structural
+ *    contradiction (orphan file / bad plan / id conflict) errors". A
+ *    declared `summary` becomes the placeholder's `subheading` (the one spot
+ *    `summary` — otherwise a plan-only anchor, see step 5 — does reach the
+ *    IR) so a `--draft` preview of an unfilled deck still reads as more than
+ *    a bare "Untitled".
+ * 5. Present pages become a full slide: `id`/`type`/`heading` from the plan
+ *    page (never the content record — see step 2), plus whichever of
+ *    {@link PageContent}'s six fields the content record actually set.
+ *    `rhythm`/`focus`/`summary` never reach the IR for a present page —
+ *    they are plan-only authoring anchors (rhythm/focus steer a future
+ *    fill/select step, summary is "for the fill step's own reading only"), not slide content.
+ * 6. Top-level: `version` is always the literal `"3"` (IR's own version,
+ *    unrelated to the plan's own `version: "1"`). `scenario`/`theme`/
+ *    `filename`/`brand`/`meta`/`seed` (step 7) carry over from the plan when
+ *    present. When absent, this function omits the field from the raw
+ *    object it hands to {@link PptxIRSchema} rather than re-deriving IR's
+ *    own default value a second time — one default source of truth, the
+ *    schema itself (e.g. `theme` omitted here becomes `{ id: "consulting" }`,
+ *    exactly like a bare hand-authored IR that never mentions theme at all —
+ *    not a value this function needs to know).
+ * 7. Seed: `plan.seed` present → passed through, `generatedSeed` stays
+ *    `undefined` on the result. Absent → {@link generateSeed} derives one
+ *    from `filename` + the plan's own ordered page-id list (never page
+ *    *content* — see that function's own doc comment for why), written to
+ *    `ir.seed` *and* returned as `generatedSeed` so a CLI shell can suggest
+ *    writing it back into the plan file (this function never touches disk
+ *    itself).
+ * 8. Idempotence: every step above is a pure function of its inputs (no
+ *    randomness, no wall-clock, no reliance on unordered iteration) — two
+ *    calls with structurally-equal `plan`/`pages` produce deep-equal
+ *    results, `generatedSeed` included. Exercised directly by this module's
+ *    test suite rather than asserted here.
+ */
+declare function assembleDeck(plan: unknown, pages: Record<string, PageContent>): AssembleResult;
+/**
+ * Inverse of {@link assembleDeck}: reconstructs `{ plan, pages }` from an
+ * existing IR well enough that `assembleDeck(...disassembleDeck(ir))`
+ * reproduces every slide's content — but the map is not lossless in both
+ * directions, only in the direction the round trip actually exercises
+ * (IR → plan/pages → IR). Fields with no IR-side home never survive being
+ * written *to* the IR in the first place, so there is nothing here to read
+ * back:
+ *
+ * - `rhythm` and `focus` never appear on any produced {@link PlanPage} —
+ *   both are plan-only authoring anchors with no corresponding `Slide`
+ *   field at all (see {@link assembleDeck} step 5's doc comment). Nothing
+ *   here could recover a value that was never written anywhere.
+ * - `summary` is recovered *only* for a placeholder slide, by reversing
+ *   step 4's `summary` → `subheading` injection (`slide.subheading` back to
+ *   `planPage.summary`). A non-placeholder slide's own `subheading` — a
+ *   legitimate, independent `Slide` field a hand-authored bare IR is free to
+ *   set — has no {@link PageContent} field to land in (spec §7's pages/
+ *   record is deliberately narrower than `Slide` itself, see that
+ *   interface's own doc comment) and no `summary` semantics either (`summary`
+ *   only ever flows to a *placeholder*'s `subheading`, never the reverse for
+ *   a filled page) — so it is dropped. Same for `decor`: a real `Slide`
+ *   field, absent from `PageContent`'s shape entirely.
+ * - `theme.style` / `theme.brand` overrides collapse to a bare theme-id
+ *   string (`DeckPlanSchema.theme` has no shape for either) — only `theme.id`
+ *   survives. That `theme.brand` is `ThemeSchema.brand` (`BrandConfigSchema`
+ *   — `suppressFooterOnCardContent`/`suppressFooterRule`, footer-chrome
+ *   flags owned by the *theme*) — not to be confused with the deck-level
+ *   `brand` field below, a different, unrelated schema despite the shared
+ *   name.
+ * - `ir.assets.images` is not part of this function's return value at all —
+ *   `{ plan, pages }` has no `assets` field, and this module stays zero-fs
+ *   by design (this file's own top comment), so it has no way to write an
+ *   `assets/` directory itself. Any `asset_id` reference inside a copied
+ *   `components`/`background` survives untouched ({@link extractPageContent}
+ *   copies both as-is), but the underlying image bytes are deliberately left
+ *   for the caller: the CLI shell closes that gap. `runDisassemble`
+ *   (`../cli/commands.ts`) walks the *input* IR's `ir.assets.images` itself
+ *   and materializes every entry into `<outDir>/assets/<id>.<ext>`
+ *   (`writeDeckAssets`, `../cli/deck-dir.ts`) so a later `readDeckDir`'s
+ *   `scanAssets` re-registers them exactly like any other deck-directory
+ *   asset. Skipping that shell-side step is not a doc-comment nuance — it
+ *   reproduces as a real bug: an image deck disassembles with every
+ *   `asset_id` left dangling, then re-assembles and renders with the image
+ *   silently missing.
+ *
+ * Round-trip-safe despite the above, worth calling out because of that name
+ * collision: the top-level `brand` field (`BrandSchema` — `logo_asset_id` /
+ * `position`, the deck logo/position `BrandChrome` reads,
+ * `src/svg/BrandChrome.tsx`) is a plain passthrough on both sides
+ * ({@link assembleDeck} step 6 reads `plan.brand` into `ir.brand` — this
+ * function reads `ir.brand` back into `plan.brand` below) — carried through
+ * unmodified, same as `scenario`/`filename`/`seed`, never synthesized or
+ * dropped.
+ *
+ * `layout` deserves a different kind of callout: it round-trips as plain
+ * content like any other field ({@link extractPageContent} copies
+ * `slide.layout` into `PageContent.layout` whenever the slide has one, no
+ * special case) — but a `deck.json` produced by {@link assembleDeck} now
+ * carries a `layout` on nearly every slide (W4 design decision 10's
+ * materialization, see that function's own doc comment), even on pages whose
+ * *original page file* never set one. Nothing on `Slide` marks which is
+ * which — `layout` is just a string either way — so disassembling an
+ * already-assembled `deck.json` writes every materialized pick into the
+ * regenerated page file as if it had been an explicit pin all along, and a
+ * later re-`assembleDeck` call skips materialization for that page from then
+ * on, same as any hand-authored pin. Accepted, not a bug: `disassembleDeck`
+ * is a one-time bare-IR importer into an editable project directory, not a
+ * round-trip channel for `deck.json` itself. A deck project's own
+ * `pages/<id>.json` files are the durable, edit-in-place artifacts —
+ * `deck.json` is downstream output, and feeding it back through
+ * `disassembleDeck` (instead of editing the project directory that produced
+ * it) is what actually costs those pages their revision-stability
+ * re-selection eligibility going forward. A real, user-visible narrowing,
+ * worth knowing about here, not worth adding code to guard against for a
+ * usage pattern nothing in this codebase actually exercises.
+ *
+ * Two structural fields are synthesized rather than copied when the source
+ * slide omits them, each documented where it is generated:
+ * {@link UNTITLED_HEADING} for a missing/blank `heading`, and a positional
+ * `p-<1-based-ordinal>-<type>` scheme for a missing `id` (stable across
+ * repeated calls on the same IR — it is a pure function of slide position
+ * and type — but, unlike a plan-assigned id, *not* stable across inserting
+ * or reordering slides — out of scope here, since a bare IR with no `id` at
+ * all has no stabler identity to fall back to in the first place).
+ *
+ * That generated `p-<ordinal>-<type>` id is safe by construction as a
+ * page/asset file-name segment (W5 whole-branch review finding 1, verified
+ * — not just asserted — rather than also routing it through
+ * `assertSafeFileSegment`, `../cli/deck-dir.ts`): `<ordinal>` is
+ * `index + 1`, always a plain non-negative integer, and `<type>` is a
+ * `Slide["type"]`, a closed schema enum (`"cover" | "chapter" | "content" |
+ * "ending"`, `SlideSchema.type` in `../ir/index.ts`) — neither half can ever
+ * contain a `/`, a `\`, or resolve to `".."`, so the joined id can't either.
+ * A carried-over `slide.id` (the `??` branch's other side) has no such
+ * guarantee — that is the one this function passes straight through
+ * unchecked, same as every other field {@link extractPageContent} copies —
+ * which is exactly why the write-time gate in `../cli/deck-dir.ts` (not this
+ * function) is what actually closes the vulnerability.
+ */
+declare function disassembleDeck(ir: PptxIR): {
+    plan: DeckPlan;
+    pages: Record<string, PageContent>;
+};
+
+/**
+ * `pptfast audit` finding shape (v0.3 W6, spec §7 workflow ④). `page` is
+ * 1-based (matches `ValidationIssue.page` in `api.ts`); `slideId` is set
+ * whenever the offending slide has a stable `id` (assemble-stamped or
+ * author-supplied), same "page + optional id" convention `formatIssues`
+ * already uses for validate errors.
+ */
+interface AuditFinding {
+    page: number;
+    slideId?: string;
+    code: "overflow" | "out-of-bounds" | "low-contrast" | "overlap";
+    message: string;
+    detail?: Record<string, unknown>;
+}
+interface AuditReport {
+    findings: AuditFinding[];
+    pagesAudited: number;
+    pagesSkipped: number;
+}
+/**
+ * Deterministic geometry audit over an already-valid deck (v0.3 W6, spec §7
+ * workflow ④): render every non-placeholder slide off-screen
+ * (`renderSlideSvg`, the same single-source SVG the preview and exporter
+ * both use) and run three check families against the rendered markup —
+ * overflow/out-of-bounds (reusing `svg-audit.ts`'s existing walker
+ * verbatim), low-contrast (WCAG relative luminance), and overlap (pairwise
+ * `data-audit-box` intersection). Pure — no I/O, no Node dependency (see
+ * `parseSvg`'s doc comment) — `auditDeck` itself never calls
+ * `installNodePlatform()`; that's the caller's job (the CLI does it
+ * automatically).
+ *
+ * Advisory, not a hard gate: `validateIr` already rejects structurally
+ * invalid or over-dense decks before a caller ever gets this far; this
+ * function looks for the visual problems that can still slip through a
+ * valid deck at render time (an author-chosen near-background text color,
+ * two components whose combined content happens to collide). A non-empty
+ * `findings` array is a prompt for a human/agent to look, not a rejection.
+ *
+ * Placeholder pages (`slide.placeholder === true`) are skipped — assemble's
+ * stand-in for content nobody has written yet has nothing to audit, same
+ * reasoning `checkIrQuality` already uses to skip them (`ir-quality.ts`).
+ */
+declare function auditDeck(ir: PptxIR): AuditReport;
 
-export { type Assets, type BackgroundSpec, type Block, type Meta, PptfastError, type PptxIR, PptxIRSchema, type Slide, THEME_IDS, type ThemeInfo, VERSION, type ValidateResult, type ValidationIssue, formatIssues, generatePptx, irJsonSchema, listThemes, renderSlideSvg, validateIr };
+export { AUDIENCE_VALUES, type AssembleResult, type Assets, type Audience, type AuditFinding, type AuditReport, BUILTIN_THEME_IDS, type BackgroundSpec, type BrandConfig, BrandConfigSchema, COMPONENT_TYPES, type Component, DEFAULT_SCENARIO, DELIVERY_BUDGETS, DELIVERY_VALUES, type DeckPlan, DeckPlanSchema, type Delivery, type DeliveryBudget, MODE_DEFINITIONS, MODE_VALUES, type Meta, type Mode, type ModeDefinition, PLAN_PAGE_COUNT_RANGE, type PageContent, type PlanPage, PlanPageSchema, type PlanPageType, type PlanRhythm, type PlanValidateResult, type PlanValidationIssue, PptfastError, type PptxIR, PptxIRSchema, SCENARIO_PRESETS, type ScenarioAxes, type ScenarioPreset, type Slide, type StyleOverride, StyleOverrideSchema, type ThemeDefinition, type ThemeInfo, type ThemeRegistration, ThemeSchema, VERSION, type ValidateResult, type ValidationIssue, assembleDeck, auditDeck, disassembleDeck, formatIssues, formatPlanIssues, generatePptx, getInstalledThemeIds, getThemeDefinition, irJsonSchema, listThemes, planJsonSchema, registerTheme, renderSlideSvg, resolvePlanThemeId, resolveScenario, styleJsonSchema, validateIr, validatePlan };