@liustack/pptfast 0.3.0 → 0.6.0

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import { z } from 'zod';
-export { P as PptfastPlatform, i as installPlatform } from './registry-CYKxZ0-U.js';
+export { P as PptfastPlatform, R as RasterizedImage, i as installPlatform } from './registry-V079Jkry.js';
 
-declare const VERSION = "0.3.0";
+declare const VERSION = "0.6.0";
 
 /** Error class thrown by pptfast's public API surface (validation, rendering, export). */
 declare class PptfastError extends Error {
@@ -392,9 +392,51 @@ declare const ComponentSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
         vs: "vs";
         before_after: "before_after";
     }>>;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"swot">;
+    strengths: z.ZodArray<z.ZodString>;
+    weaknesses: z.ZodArray<z.ZodString>;
+    opportunities: z.ZodArray<z.ZodString>;
+    threats: z.ZodArray<z.ZodString>;
+    labels: z.ZodOptional<z.ZodObject<{
+        strengths: z.ZodOptional<z.ZodString>;
+        weaknesses: z.ZodOptional<z.ZodString>;
+        opportunities: z.ZodOptional<z.ZodString>;
+        threats: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"bmc">;
+    key_partners: z.ZodArray<z.ZodString>;
+    key_activities: z.ZodArray<z.ZodString>;
+    key_resources: z.ZodArray<z.ZodString>;
+    value_propositions: z.ZodArray<z.ZodString>;
+    customer_relationships: z.ZodArray<z.ZodString>;
+    channels: z.ZodArray<z.ZodString>;
+    customer_segments: z.ZodArray<z.ZodString>;
+    cost_structure: z.ZodArray<z.ZodString>;
+    revenue_streams: z.ZodArray<z.ZodString>;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"waterfall">;
+    items: z.ZodArray<z.ZodObject<{
+        label: z.ZodString;
+        value: z.ZodNumber;
+        kind: z.ZodOptional<z.ZodEnum<{
+            delta: "delta";
+            total: "total";
+        }>>;
+    }, z.core.$strict>>;
+    unit: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"gantt">;
+    items: z.ZodArray<z.ZodObject<{
+        label: z.ZodString;
+        start: z.ZodNumber;
+        end: z.ZodNumber;
+    }, z.core.$strict>>;
+    axis_labels: z.ZodOptional<z.ZodArray<z.ZodString>>;
 }, z.core.$strict>], "type">;
 /**
- * All 24 component `type` discriminant values, derived from `ComponentSchema`
+ * All 28 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,
@@ -671,6 +713,48 @@ declare const SlideSchema: z.ZodObject<{
             vs: "vs";
             before_after: "before_after";
         }>>;
+    }, z.core.$strict>, z.ZodObject<{
+        type: z.ZodLiteral<"swot">;
+        strengths: z.ZodArray<z.ZodString>;
+        weaknesses: z.ZodArray<z.ZodString>;
+        opportunities: z.ZodArray<z.ZodString>;
+        threats: z.ZodArray<z.ZodString>;
+        labels: z.ZodOptional<z.ZodObject<{
+            strengths: z.ZodOptional<z.ZodString>;
+            weaknesses: z.ZodOptional<z.ZodString>;
+            opportunities: z.ZodOptional<z.ZodString>;
+            threats: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>, z.ZodObject<{
+        type: z.ZodLiteral<"bmc">;
+        key_partners: z.ZodArray<z.ZodString>;
+        key_activities: z.ZodArray<z.ZodString>;
+        key_resources: z.ZodArray<z.ZodString>;
+        value_propositions: z.ZodArray<z.ZodString>;
+        customer_relationships: z.ZodArray<z.ZodString>;
+        channels: z.ZodArray<z.ZodString>;
+        customer_segments: z.ZodArray<z.ZodString>;
+        cost_structure: z.ZodArray<z.ZodString>;
+        revenue_streams: z.ZodArray<z.ZodString>;
+    }, z.core.$strict>, z.ZodObject<{
+        type: z.ZodLiteral<"waterfall">;
+        items: z.ZodArray<z.ZodObject<{
+            label: z.ZodString;
+            value: z.ZodNumber;
+            kind: z.ZodOptional<z.ZodEnum<{
+                delta: "delta";
+                total: "total";
+            }>>;
+        }, z.core.$strict>>;
+        unit: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>, z.ZodObject<{
+        type: z.ZodLiteral<"gantt">;
+        items: z.ZodArray<z.ZodObject<{
+            label: z.ZodString;
+            start: z.ZodNumber;
+            end: z.ZodNumber;
+        }, z.core.$strict>>;
+        axis_labels: z.ZodOptional<z.ZodArray<z.ZodString>>;
     }, z.core.$strict>], "type">>>;
     background: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
         kind: z.ZodLiteral<"color">;
@@ -715,11 +799,12 @@ declare const SlideSchema: z.ZodObject<{
         right: "right";
     }>>;
     footnote: z.ZodOptional<z.ZodString>;
+    notes: z.ZodOptional<z.ZodString>;
 }, z.core.$strict>;
 declare const PptxIRSchema: z.ZodObject<{
-    version: z.ZodDefault<z.ZodLiteral<"3">>;
+    version: z.ZodDefault<z.ZodLiteral<"4">>;
     filename: z.ZodDefault<z.ZodString>;
-    scenario: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodUnknown>]>>;
+    narrative: 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<{
@@ -1071,6 +1156,48 @@ declare const PptxIRSchema: z.ZodObject<{
                 vs: "vs";
                 before_after: "before_after";
             }>>;
+        }, z.core.$strict>, z.ZodObject<{
+            type: z.ZodLiteral<"swot">;
+            strengths: z.ZodArray<z.ZodString>;
+            weaknesses: z.ZodArray<z.ZodString>;
+            opportunities: z.ZodArray<z.ZodString>;
+            threats: z.ZodArray<z.ZodString>;
+            labels: z.ZodOptional<z.ZodObject<{
+                strengths: z.ZodOptional<z.ZodString>;
+                weaknesses: z.ZodOptional<z.ZodString>;
+                opportunities: z.ZodOptional<z.ZodString>;
+                threats: z.ZodOptional<z.ZodString>;
+            }, z.core.$strict>>;
+        }, z.core.$strict>, z.ZodObject<{
+            type: z.ZodLiteral<"bmc">;
+            key_partners: z.ZodArray<z.ZodString>;
+            key_activities: z.ZodArray<z.ZodString>;
+            key_resources: z.ZodArray<z.ZodString>;
+            value_propositions: z.ZodArray<z.ZodString>;
+            customer_relationships: z.ZodArray<z.ZodString>;
+            channels: z.ZodArray<z.ZodString>;
+            customer_segments: z.ZodArray<z.ZodString>;
+            cost_structure: z.ZodArray<z.ZodString>;
+            revenue_streams: z.ZodArray<z.ZodString>;
+        }, z.core.$strict>, z.ZodObject<{
+            type: z.ZodLiteral<"waterfall">;
+            items: z.ZodArray<z.ZodObject<{
+                label: z.ZodString;
+                value: z.ZodNumber;
+                kind: z.ZodOptional<z.ZodEnum<{
+                    delta: "delta";
+                    total: "total";
+                }>>;
+            }, z.core.$strict>>;
+            unit: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>, z.ZodObject<{
+            type: z.ZodLiteral<"gantt">;
+            items: z.ZodArray<z.ZodObject<{
+                label: z.ZodString;
+                start: z.ZodNumber;
+                end: z.ZodNumber;
+            }, z.core.$strict>>;
+            axis_labels: z.ZodOptional<z.ZodArray<z.ZodString>>;
         }, z.core.$strict>], "type">>>;
         background: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
             kind: z.ZodLiteral<"color">;
@@ -1115,6 +1242,7 @@ declare const PptxIRSchema: z.ZodObject<{
             right: "right";
         }>>;
         footnote: z.ZodOptional<z.ZodString>;
+        notes: z.ZodOptional<z.ZodString>;
     }, z.core.$strict>>;
 }, z.core.$strict>;
 type PptxIR = z.infer<typeof PptxIRSchema>;
@@ -1134,8 +1262,9 @@ interface ValidationIssue {
      * 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})
+     * ({@link checkLayoutApplicability}, {@link checkBoundaryPageContent},
+     * 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
@@ -1155,34 +1284,86 @@ interface ValidateResult {
      * least one rewrite happened; informational, never gates `ok` on its own.
      */
     normalized?: string[];
+    /**
+     * Backward-compatible addition (borrow wave, Task 2 — dual-threshold
+     * severity recalibration): warn-severity {@link checkIrQuality} findings
+     * (editorial-budget codes — `missing_heading`/`long_heading`/`density`/
+     * `bullets_overflow`/`bullet_item_long`/`big_number_no_kpi`), formatted the
+     * same shape {@link formatIssues} already prints for `errors` (page/id/path
+     * all included). Present only when at least one warn-severity finding
+     * exists, and never gates `ok` on its own — that is exactly what moved
+     * these findings off `errors` and onto here. Can be present alongside a
+     * failing (`ok:false`) result too, whenever `checkIrQuality` itself ran
+     * (an *earlier* hard gate — schema, theme id, layout applicability,
+     * full-body exclusivity, boundary-page content, duplicate ids, narrative —
+     * short-circuits before `checkIrQuality` runs at all, so a deck rejected
+     * by one of those never reaches this field either way, see `validateIr`'s
+     * own body for the exact gate order). {@link formatWarnings} renders this
+     * array as CLI-ready `"warning: ..."` lines.
+     */
+    warnings?: ValidationIssue[];
 }
 /**
  * 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.
+ * `narrative` (`resolveNarrative`, spec §5: an unrecognized preset name is a
+ * `narrative`-path error, page-less) and run the content-quality gate
+ * (`checkIrQuality`, passed the resolved axes) against the parsed IR. Every
+ * hard-gate stage (schema, theme id, layout applicability, full-body
+ * exclusivity, boundary-page content, duplicate ids, narrative) must pass for
+ * `ok: true`, same as before. Quality findings are reported the same way as
+ * schema errors (page-scoped, 1-based).
  *
- * 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
+ * Dual-threshold severity (borrow wave, Task 2 — recalibrated from the prior
+ * "any finding blocks" design): `checkIrQuality`'s own "warn" vs "error" tag
+ * is now respected, not flattened. Only "error"-severity findings
+ * (`empty_deck`, `bullet_item_overflow` — content genuinely lost: an empty
+ * deck, or a bullet item long enough to hit `bullets.tsx`'s MIN_FONT floor
+ * and actually get truncated) gate `ok`. "warn"-severity findings — the
+ * editorial-budget codes (`missing_heading`/`long_heading`/`density`/
+ * `bullets_overflow`/`bullet_item_long`/`big_number_no_kpi`) — surface on
+ * {@link ValidateResult.warnings} instead: visible to every caller (the SDK,
+ * the CLI's `validate`/`render` pre-flight), never blocking. This reverses
+ * the prior posture (this comment used to read "any finding blocks... not
+ * only 'error'-severity ones") because the evidence behind it did not hold:
+ * a boundary scan (borrow-wave fact-report, Q3) found the editorial bullets
+ * threshold blocking content roughly 3.5x below where `bullets.tsx`'s own
+ * render safety net (2-line wrap, shrink to a 14px floor) actually starts
+ * losing characters — so the hard gate was rejecting deck content that
+ * would have rendered with zero visible defect, and a tight hard gate on an
+ * editorial (not geometric) threshold taught truncate-content-to-pass
+ * workarounds rather than catching real loss. `generatePptx`'s default path
+ * inherits this unchanged (`if (!v.ok) throw`) — it already only ever
+ * blocked on `ok`, never inspected `errors`/`warnings` directly.
+ *
+ * Before any of that, one deterministic alias pass runs
+ * ({@link normalizeComponentAliases}, W5 task 4) for the component
+ * field-name synonym rescue only (kpi `title`→`label`, quote
+ * `content`→`text`, …) — a weak-model rescue for schema-internal synonym
+ * drift, scoped to `slides[]`. It only rewrites where the canonical key is
+ * absent, so the schema parse below never sees an alias as an "unrecognized
+ * key" in the first place. 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`.
+ *
+ * There is deliberately no root/narrative-level alias pass (spec §16,
+ * reversing the now-superseded §15.4): a v4 document that still spells its
+ * pre-rename vocabulary — `scenario` instead of `narrative`, `mode`/
+ * `delivery` instead of `strategy`/`pacing`, or the old enum values
+ * `"text"`/`"presentation"`/`"narrative"` — is not old-vocabulary
+ * *compatibility*, it is exactly the vocabulary this rename retired, so it
+ * hard-errors like any other unknown key or value: `scenario` fails the
+ * schema's `.strict()` parse below as an unrecognized key, and an old enum
+ * value (or the axis-key names `mode`/`delivery` inside `narrative`, which
+ * the schema itself leaves open) fails `resolveNarrative`'s own runtime
+ * check, listing the current values. `pptfast migrate` (`ir/migrate.ts`)
+ * remains the sanctioned bridge for a genuine v3 document — see the v3 hard
+ * reject below, which points there.
+ *
+ * The component-alias pass only ever runs for a document already headed for
+ * the v4 schema — an explicit `version: "2"` or `version: "3"` is
+ * hard-rejected first, below, before the alias pass or any schema parse
+ * (spec §9.3: a v2/v3 document is never silently reinterpreted as v4).
  */
 declare function validateIr(input: unknown): ValidateResult;
 /**
@@ -1215,6 +1396,494 @@ 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>;
 
+/**
+ * The frozen IR v3 top-level shape (vocabulary-v4 rename, task 1 — spec
+ * §9.3: "v3 已冻结... 顶层字段和枚举改名必须进入新的 IR 版本，不能在 v3
+ * 内静默改变含义"). `./index.ts`'s `PptxIRSchema` is v4 now — this module
+ * exists only so a genuinely v3-shaped document still has somewhere to parse
+ * against: `migrateIrV3ToV4`'s input type (`./migrate.ts`), and the
+ * v3-hard-reject path's own tests (constructing a *valid* v3 IR to prove the
+ * reject fires on version alone, not on some other schema defect).
+ *
+ * `validateIr` (`src/api.ts`) never calls this schema itself — an incoming
+ * v3 document (`version === "3"`) is hard-rejected before any schema parse
+ * runs at all (spec §9.3), full stop. This schema is a migration-tooling and
+ * test fixture, not a second accepted input shape.
+ *
+ * Every field but `version` and `scenario` is byte-identical to `./index.ts`'s
+ * v4 `PptxIRSchema` (spec §9.1: "其余 IR 字段保持不变") — reuses the exact
+ * same `ThemeSchema`/`MetaSchema`/`AssetsSchema`/`BrandSchema`/`SlideSchema`
+ * instances rather than redefining them, so there is no way for this frozen
+ * shape to silently drift from the fields it shares with v4.
+ */
+declare const PptxIRV3Schema: z.ZodObject<{
+    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>>;
+        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<{
+            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>>;
+    assets: z.ZodDefault<z.ZodObject<{
+        images: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{
+            src: z.ZodString;
+            alt: z.ZodOptional<z.ZodString>;
+            error: z.ZodOptional<z.ZodString>;
+        }, 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>>;
+    seed: z.ZodOptional<z.ZodNumber>;
+    slides: z.ZodArray<z.ZodObject<{
+        type: z.ZodDefault<z.ZodEnum<{
+            cover: "cover";
+            chapter: "chapter";
+            content: "content";
+            ending: "ending";
+        }>>;
+        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";
+            two_column: "two_column";
+            kpi_focus: "kpi_focus";
+            image_focus: "image_focus";
+            big_number: "big_number";
+            assertion_evidence: "assertion_evidence";
+            aside: "aside";
+        }>>;
+        heading: z.ZodOptional<z.ZodString>;
+        subheading: z.ZodOptional<z.ZodString>;
+        components: z.ZodDefault<z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+            type: z.ZodLiteral<"bullets">;
+            items: z.ZodArray<z.ZodString>;
+            style: z.ZodOptional<z.ZodEnum<{
+                default: "default";
+                checklist: "checklist";
+                numbered: "numbered";
+                plain: "plain";
+                divided: "divided";
+            }>>;
+        }, z.core.$strict>, z.ZodObject<{
+            type: z.ZodLiteral<"paragraph">;
+            text: z.ZodString;
+        }, z.core.$strict>, z.ZodObject<{
+            type: z.ZodLiteral<"quote">;
+            text: z.ZodString;
+            attribution: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>, z.ZodObject<{
+            type: z.ZodLiteral<"callout">;
+            variant: z.ZodEnum<{
+                info: "info";
+                warn: "warn";
+                tip: "tip";
+            }>;
+            text: z.ZodString;
+            icon: z.ZodOptional<z.ZodEnum<{
+                [x: string]: string;
+            }>>;
+        }, z.core.$strict>, z.ZodObject<{
+            type: z.ZodLiteral<"code">;
+            language: z.ZodString;
+            code: z.ZodString;
+        }, z.core.$strict>, z.ZodObject<{
+            type: z.ZodLiteral<"kpi_cards">;
+            items: z.ZodArray<z.ZodObject<{
+                value: z.ZodString;
+                unit: z.ZodOptional<z.ZodString>;
+                label: z.ZodString;
+                delta: z.ZodOptional<z.ZodEnum<{
+                    up: "up";
+                    down: "down";
+                    flat: "flat";
+                }>>;
+                icon: z.ZodOptional<z.ZodEnum<{
+                    [x: string]: string;
+                }>>;
+                source: z.ZodOptional<z.ZodString>;
+            }, z.core.$strict>>;
+        }, z.core.$strict>, z.ZodObject<{
+            type: z.ZodLiteral<"chart">;
+            chart_type: z.ZodEnum<{
+                line: "line";
+                dumbbell: "dumbbell";
+                funnel: "funnel";
+                bar: "bar";
+                pie: "pie";
+            }>;
+            direction: z.ZodOptional<z.ZodEnum<{
+                horizontal: "horizontal";
+                vertical: "vertical";
+            }>>;
+            style: z.ZodOptional<z.ZodEnum<{
+                donut: "donut";
+            }>>;
+            axes: z.ZodOptional<z.ZodObject<{
+                x_title: z.ZodOptional<z.ZodString>;
+                y_title: z.ZodOptional<z.ZodString>;
+                show_grid: z.ZodOptional<z.ZodBoolean>;
+            }, z.core.$strict>>;
+            series: z.ZodArray<z.ZodObject<{
+                name: z.ZodString;
+                data: z.ZodArray<z.ZodObject<{
+                    x: z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>;
+                    y: z.ZodNumber;
+                }, z.core.$strict>>;
+            }, z.core.$strict>>;
+        }, z.core.$strict>, z.ZodObject<{
+            type: z.ZodLiteral<"flowchart">;
+            nodes: z.ZodArray<z.ZodObject<{
+                id: z.ZodString;
+                label: z.ZodString;
+                kind: z.ZodOptional<z.ZodEnum<{
+                    rect: "rect";
+                    diamond: "diamond";
+                    round: "round";
+                }>>;
+            }, z.core.$strict>>;
+            edges: z.ZodArray<z.ZodObject<{
+                from: z.ZodString;
+                to: z.ZodString;
+                label: z.ZodOptional<z.ZodString>;
+            }, z.core.$strict>>;
+            direction: z.ZodOptional<z.ZodEnum<{
+                TB: "TB";
+                TD: "TD";
+                BT: "BT";
+                LR: "LR";
+                RL: "RL";
+            }>>;
+        }, z.core.$strict>, z.ZodObject<{
+            type: z.ZodLiteral<"architecture">;
+            layers: z.ZodArray<z.ZodObject<{
+                title: z.ZodString;
+                items: z.ZodArray<z.ZodString>;
+            }, z.core.$strict>>;
+        }, z.core.$strict>, z.ZodObject<{
+            type: z.ZodLiteral<"timeline">;
+            layout: z.ZodOptional<z.ZodEnum<{
+                horizontal: "horizontal";
+                vertical: "vertical";
+            }>>;
+            milestones: z.ZodArray<z.ZodObject<{
+                date: z.ZodString;
+                title: z.ZodString;
+                desc: z.ZodOptional<z.ZodString>;
+                highlight: z.ZodOptional<z.ZodBoolean>;
+            }, z.core.$strict>>;
+        }, z.core.$strict>, z.ZodObject<{
+            type: z.ZodLiteral<"comparison">;
+            columns: z.ZodArray<z.ZodString>;
+            rows: z.ZodArray<z.ZodObject<{
+                label: z.ZodString;
+                cells: z.ZodArray<z.ZodString>;
+            }, z.core.$strict>>;
+        }, z.core.$strict>, z.ZodObject<{
+            type: z.ZodLiteral<"icon_cards">;
+            items: z.ZodArray<z.ZodObject<{
+                icon: z.ZodEnum<{
+                    [x: string]: string;
+                }>;
+                title: z.ZodString;
+                text: z.ZodString;
+            }, z.core.$strict>>;
+        }, z.core.$strict>, z.ZodObject<{
+            type: z.ZodLiteral<"row_cards">;
+            items: z.ZodArray<z.ZodObject<{
+                icon: z.ZodOptional<z.ZodEnum<{
+                    [x: string]: string;
+                }>>;
+                title: z.ZodString;
+                text: z.ZodOptional<z.ZodString>;
+                sub: z.ZodOptional<z.ZodString>;
+                highlight: z.ZodOptional<z.ZodBoolean>;
+            }, z.core.$strict>>;
+        }, z.core.$strict>, z.ZodObject<{
+            type: z.ZodLiteral<"steps">;
+            items: z.ZodArray<z.ZodObject<{
+                title: z.ZodString;
+                text: z.ZodString;
+            }, z.core.$strict>>;
+        }, z.core.$strict>, z.ZodObject<{
+            type: z.ZodLiteral<"rings">;
+            items: z.ZodArray<z.ZodObject<{
+                label: z.ZodString;
+                desc: z.ZodOptional<z.ZodString>;
+            }, z.core.$strict>>;
+        }, z.core.$strict>, z.ZodObject<{
+            type: z.ZodLiteral<"numbered_cards">;
+            items: z.ZodArray<z.ZodObject<{
+                title: z.ZodString;
+                text: z.ZodOptional<z.ZodString>;
+                sub: z.ZodOptional<z.ZodString>;
+            }, z.core.$strict>>;
+        }, z.core.$strict>, z.ZodObject<{
+            type: z.ZodLiteral<"roadmap">;
+            items: z.ZodArray<z.ZodObject<{
+                title: z.ZodString;
+                period: z.ZodOptional<z.ZodString>;
+                rows: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                    label: z.ZodString;
+                    value: z.ZodString;
+                }, z.core.$strict>>>;
+            }, z.core.$strict>>;
+        }, z.core.$strict>, z.ZodObject<{
+            type: z.ZodLiteral<"matrix">;
+            x_title: z.ZodOptional<z.ZodString>;
+            y_title: z.ZodOptional<z.ZodString>;
+            cols: z.ZodNumber;
+            items: z.ZodArray<z.ZodObject<{
+                title: z.ZodString;
+                tag: z.ZodOptional<z.ZodString>;
+                tone: z.ZodOptional<z.ZodEnum<{
+                    info: "info";
+                    accent: "accent";
+                    neutral: "neutral";
+                }>>;
+            }, z.core.$strict>>;
+        }, z.core.$strict>, z.ZodObject<{
+            type: z.ZodLiteral<"insight_panel">;
+            title: z.ZodString;
+            rows: z.ZodArray<z.ZodObject<{
+                label: z.ZodString;
+                text: z.ZodString;
+            }, z.core.$strict>>;
+            footnote: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>, z.ZodObject<{
+            type: z.ZodLiteral<"verdict_banner">;
+            text: z.ZodString;
+            tone: z.ZodEnum<{
+                neutral: "neutral";
+                positive: "positive";
+                warning: "warning";
+            }>;
+            icon: z.ZodOptional<z.ZodEnum<{
+                [x: string]: string;
+            }>>;
+        }, z.core.$strict>, z.ZodObject<{
+            type: z.ZodLiteral<"citation">;
+            sources: z.ZodArray<z.ZodObject<{
+                label: z.ZodString;
+                url: z.ZodOptional<z.ZodString>;
+                ref: z.ZodOptional<z.ZodString>;
+            }, z.core.$strict>>;
+        }, z.core.$strict>, z.ZodObject<{
+            type: z.ZodLiteral<"image">;
+            asset_id: z.ZodString;
+            caption: z.ZodOptional<z.ZodString>;
+            fit: z.ZodDefault<z.ZodEnum<{
+                cover: "cover";
+                contain: "contain";
+            }>>;
+        }, z.core.$strict>, z.ZodObject<{
+            type: z.ZodLiteral<"image_grid">;
+            items: z.ZodArray<z.ZodObject<{
+                asset_id: z.ZodString;
+                caption: z.ZodOptional<z.ZodString>;
+            }, z.core.$strict>>;
+            emphasis: z.ZodOptional<z.ZodEnum<{
+                none: "none";
+                first: "first";
+            }>>;
+        }, z.core.$strict>, z.ZodObject<{
+            type: z.ZodLiteral<"image_compare">;
+            left: z.ZodObject<{
+                asset_id: z.ZodString;
+                label: z.ZodString;
+            }, z.core.$strict>;
+            right: z.ZodObject<{
+                asset_id: z.ZodString;
+                label: z.ZodString;
+            }, z.core.$strict>;
+            style: z.ZodOptional<z.ZodEnum<{
+                vs: "vs";
+                before_after: "before_after";
+            }>>;
+        }, z.core.$strict>, z.ZodObject<{
+            type: z.ZodLiteral<"swot">;
+            strengths: z.ZodArray<z.ZodString>;
+            weaknesses: z.ZodArray<z.ZodString>;
+            opportunities: z.ZodArray<z.ZodString>;
+            threats: z.ZodArray<z.ZodString>;
+            labels: z.ZodOptional<z.ZodObject<{
+                strengths: z.ZodOptional<z.ZodString>;
+                weaknesses: z.ZodOptional<z.ZodString>;
+                opportunities: z.ZodOptional<z.ZodString>;
+                threats: z.ZodOptional<z.ZodString>;
+            }, z.core.$strict>>;
+        }, z.core.$strict>, z.ZodObject<{
+            type: z.ZodLiteral<"bmc">;
+            key_partners: z.ZodArray<z.ZodString>;
+            key_activities: z.ZodArray<z.ZodString>;
+            key_resources: z.ZodArray<z.ZodString>;
+            value_propositions: z.ZodArray<z.ZodString>;
+            customer_relationships: z.ZodArray<z.ZodString>;
+            channels: z.ZodArray<z.ZodString>;
+            customer_segments: z.ZodArray<z.ZodString>;
+            cost_structure: z.ZodArray<z.ZodString>;
+            revenue_streams: z.ZodArray<z.ZodString>;
+        }, z.core.$strict>, z.ZodObject<{
+            type: z.ZodLiteral<"waterfall">;
+            items: z.ZodArray<z.ZodObject<{
+                label: z.ZodString;
+                value: z.ZodNumber;
+                kind: z.ZodOptional<z.ZodEnum<{
+                    delta: "delta";
+                    total: "total";
+                }>>;
+            }, z.core.$strict>>;
+            unit: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>, z.ZodObject<{
+            type: z.ZodLiteral<"gantt">;
+            items: z.ZodArray<z.ZodObject<{
+                label: z.ZodString;
+                start: z.ZodNumber;
+                end: z.ZodNumber;
+            }, z.core.$strict>>;
+            axis_labels: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        }, z.core.$strict>], "type">>>;
+        background: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+            kind: z.ZodLiteral<"color">;
+            value: z.ZodString;
+        }, z.core.$strict>, z.ZodObject<{
+            kind: z.ZodLiteral<"gradient">;
+            from: z.ZodString;
+            to: z.ZodString;
+            direction: z.ZodOptional<z.ZodEnum<{
+                tb: "tb";
+                lr: "lr";
+                diagonal: "diagonal";
+            }>>;
+        }, z.core.$strict>, z.ZodObject<{
+            kind: z.ZodLiteral<"asset">;
+            asset_id: z.ZodString;
+            overlay: z.ZodOptional<z.ZodObject<{
+                color: z.ZodString;
+                opacity: z.ZodNumber;
+            }, z.core.$strict>>;
+            fit: z.ZodOptional<z.ZodEnum<{
+                cover: "cover";
+                contain: "contain";
+            }>>;
+        }, z.core.$strict>], "kind">>;
+        decor: z.ZodOptional<z.ZodObject<{
+            kind: z.ZodEnum<{
+                big_number: "big_number";
+                corner_tag: "corner_tag";
+                rule_line: "rule_line";
+                quote_marks: "quote_marks";
+                geo_dots: "geo_dots";
+            }>;
+            intensity: z.ZodOptional<z.ZodEnum<{
+                subtle: "subtle";
+                normal: "normal";
+            }>>;
+            text: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>;
+        image_side: z.ZodOptional<z.ZodEnum<{
+            left: "left";
+            right: "right";
+        }>>;
+        footnote: z.ZodOptional<z.ZodString>;
+        notes: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+type PptxIRV3 = z.infer<typeof PptxIRV3Schema>;
+
+/**
+ * Deterministic, pure IR v3 → v4 migration (spec §9.1). Field-for-field,
+ * value-for-value per the mapping in {@link migrateNarrativeInput}'s
+ * docstring — every field this function doesn't touch (`filename`, `theme`,
+ * `meta`, `assets`, `brand`, `seed`, `slides`) carries across by the exact
+ * same reference it came in with, unchanged (spec §9.1: "其余 IR 字段保持不
+ * 变"; spec §10: no weight/budget/selection/render change is in scope for
+ * this migration, ever).
+ *
+ * Exported from the SDK surface (`src/index.ts`) as the deterministic
+ * migration primitive the `pptfast migrate` CLI command (task 2) wraps —
+ * this function itself does no I/O and never runs a model, per spec §9.3's
+ * "只做已声明的结构映射，不运行模型，不重写内容，不重新选择 layout".
+ *
+ * Takes an already-parsed `PptxIRV3` (i.e. `PptxIRV3Schema.parse(...)`'s
+ * output, defaults already applied) rather than raw `unknown` JSON — schema
+ * validation of the v3 input is the caller's job (the CLI parses-then-
+ * migrates; `validateIr`'s own v3 path hard-rejects before ever reaching
+ * this function, spec §9.3, so `validateIr` itself never calls this).
+ */
+declare function migrateIrV3ToV4(v3: PptxIRV3): PptxIR;
+
 type LayoutType = "cover" | "chapter" | "content" | "ending";
 interface StyleColors {
     bg: string;
@@ -1361,41 +2030,44 @@ declare function getInstalledThemeIds(): readonly string[];
  */
 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 STRATEGY_VALUES: readonly ["pyramid", "storytelling", "instructional", "showcase", "briefing"];
+declare const PACING_VALUES: readonly ["dense", "balanced", "spacious"];
 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).
+ * Narrative argument style (spec §5's five-way strategy classification,
+ * renamed from "mode" — spec §8.1). Each strategy carries a
+ * component/layout tendency set (soft-weight material, consumed by W4's
+ * weighted selection — nothing consumes it this wave) and a beat policy
+ * (renamed from "rhythm policy" — spec §2.3's deck/page beat split; consumed
+ * by W5's spec-validate rotation gate).
  */
-type Mode = (typeof MODE_VALUES)[number];
+type Strategy = (typeof STRATEGY_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.
+ * Content density budget + typographic baseline (spec §5 pacing table,
+ * renamed from "delivery" — spec §8.1). See {@link PacingBudget} for the
+ * dual-attribute capacity split this axis is one half of.
  */
-type Delivery = (typeof DELIVERY_VALUES)[number];
+type Pacing = (typeof PACING_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).
+ * Name unchanged by the vocabulary-v4 rename (spec §4.3: "audience 保持不变").
  */
 type Audience = (typeof AUDIENCE_VALUES)[number];
-interface ScenarioAxes {
-    readonly mode: Mode;
-    readonly delivery: Delivery;
+interface NarrativeProfile {
+    readonly strategy: Strategy;
+    readonly pacing: Pacing;
     readonly audience: Audience;
 }
 
-interface ModeDefinition {
-    id: Mode;
+interface StrategyDefinition {
+    id: Strategy;
     /**
      * 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
+     * from spec §5's strategy 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).
      *
@@ -1416,48 +2088,50 @@ interface ModeDefinition {
      * `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
+     * layout ids drawn from spec §5's strategy table verbatim and also feeds W5's
+     * spec `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
+     * strategy'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
+     * strategy，均匀取样") 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).
+     * appears in no strategy's list either (spec's "万金油" call-out: it is the
+     * one content archetype meant to read as strategy-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.
+     * Beat template descriptor (spec §5's per-strategy beat-default column,
+     * renamed from "rhythm" — spec §2.3), parameterized by strategy for W5's
+     * spec-validate rotation gate — e.g. briefing is exempt from a generic
+     * "three same-beat pages in a row is an error" rule because uniform-dense
+     * *is* briefing's correct default, not a violation of it (spec §5's
+     * spec-gate section calls out that a generic same-beat-streak rule would
+     * reject briefing's own default). Not consumed this wave.
      */
-    rhythmPolicy: "anchor-open" | "alternate" | "repetition-ok" | "anchor-sparse" | "uniform-dense";
+    beatPolicy: "anchor-open" | "alternate" | "repetition-ok" | "anchor-sparse" | "uniform-dense";
 }
-declare const MODE_DEFINITIONS: Record<Mode, ModeDefinition>;
+declare const STRATEGY_DEFINITIONS: Record<Strategy, StrategyDefinition>;
 
-interface DeliveryBudget {
+interface PacingBudget {
     /**
-     * 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`
+     * Body-text baseline, in px, at 1280×720 slide geometry (spec §5 pacing
+     * table's body-baseline column). Wired into rendering as of W4 task 3
+     * (design decision 9): `src/svg/FullSlideSvg.tsx` resolves
+     * `PACING_BUDGETS[resolveNarrative(ir.narrative).pacing].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.
+     * `balanced` (24px) is the narrative default, an omitted-narrative 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 (W4 task 3, unchanged since — vocabulary-v4 only renames this
+     * table, it doesn't touch any of its numbers, spec §10).
      */
     bodyBaselinePx: number;
     /**
@@ -1476,23 +2150,24 @@ interface DeliveryBudget {
          * (`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
+         * check because every pacing's editorial budget here (30/40/48) is
          * already strictly tighter than it — the quality gate now applies
-         * exactly this one number per delivery.
+         * exactly this one number per pacing.
          */
         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.
+ * Pinned to spec §5's pacing table (`bodyBaselinePx` / editorial budget /
+ * bullets budget columns): dense 20/5/6×48, balanced 24/4/5×40, spacious
+ * 32/3/4×30 — same three rows as the pre-rename `text`/`balanced`/
+ * `presentation` delivery table, values byte-for-byte unchanged (spec §10).
  */
-declare const DELIVERY_BUDGETS: Record<Delivery, DeliveryBudget>;
+declare const PACING_BUDGETS: Record<Pacing, PacingBudget>;
 
-interface ScenarioPreset {
+interface NarrativePreset {
     id: string;
-    axes: ScenarioAxes;
+    axes: NarrativeProfile;
     /**
      * Soft theme recommendations — a suggestion, never a hard constraint
      * (spec §5). Surfaced in workflow step ① so an agent can open with a
@@ -1502,27 +2177,33 @@ interface ScenarioPreset {
      */
     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
+ * Pinned to spec §5's 7 named presets and their theme recommendation table.
+ * Preset ids are unchanged by the vocabulary-v4 rename (spec §5: "预设 ID
+ * 保持不变") — only each preset's internal axes keys/values follow the
+ * strategy/pacing rename (e.g. `annual-review`'s `mode: "narrative"` is now
+ * `strategy: "storytelling"`, spec §5's own worked example).
+ */
+declare const NARRATIVE_PRESETS: Record<string, NarrativePreset>;
+/**
+ * = `NARRATIVE_PRESETS.general.axes` (briefing × balanced × public) — the
+ * global default when narrative is omitted entirely (spec §5's defaults
  * chain).
  */
-declare const DEFAULT_SCENARIO: ScenarioAxes;
+declare const DEFAULT_NARRATIVE: NarrativeProfile;
 /**
- * Resolve a scenario input down to concrete axes, per spec §5's design
+ * Resolve a narrative 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)
+ * - `undefined` → {@link DEFAULT_NARRATIVE} (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
+ *   (strategy → "briefing", pacing → "balanced", audience → "public" — these
+ *   happen to equal `DEFAULT_NARRATIVE`'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")
  *
@@ -1530,50 +2211,64 @@ declare const DEFAULT_SCENARIO: ScenarioAxes;
  * always throws {@link PptfastError} (never silently ignored or dropped) —
  * omission and a typo are different intents, and only the former has a
  * reasonable default.
+ *
+ * Renamed from `resolveScenario` (spec §8.1). Callers that still hold a
+ * pre-rename `mode`/`delivery` shaped input (e.g. a v3 IR's `scenario`
+ * field) must migrate it first — see `migrateIrV3ToV4`
+ * (`src/ir/migrate.ts`) for the deterministic field/value mapping. A
+ * v4-track document that still writes the old field/value spelling gets no
+ * such rescue (spec §16, reversing the now-superseded §15.4): this function
+ * hard-errors on it, same as any other unknown axis key or value.
  */
-declare function resolveScenario(input: string | Partial<ScenarioAxes> | undefined): ScenarioAxes;
+declare function resolveNarrative(input: string | Partial<NarrativeProfile> | undefined): NarrativeProfile;
 
 /**
- * Deck plan schema + validation (spec §5 "plan artifact and hard gates", W5 task 2).
+ * Deck spec schema + validation (spec §5 "plan artifact and hard gates", W5
+ * task 2 — renamed to "Deck Spec" per the vocabulary-v4 rename, spec §6/§8.1;
+ * "spec §N" citations throughout this file that predate this rename still
+ * point at that original W5 design doc, not this rename's own spec — left
+ * as historical citations, not renumbered).
  *
- * 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).
+ * A deck spec is a workflow artifact, not a render prerequisite (spec §5's
+ * "escape hatch": a bare IR v3 renders directly, `spec validate` is a
+ * separate, optional gate for the spec-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/narrative` already do (`AGENTS.md`'s layout rule).
+ * `src/cli/commands.ts` owns the one Node-touching wrapper
+ * (`runSpecValidate`: read file, call {@link validateSpec}, 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
+ * {@link validateSpec}'s own comment for why): same overall shape, adapted
+ * for spec 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
+ * here (not imported from either) — a page spec'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];
+declare const BEAT_VALUES: readonly ["anchor", "dense", "breathing"];
+type PageSpecType = (typeof PAGE_TYPES)[number];
+type PageBeat = (typeof BEAT_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").
+ * A single page spec (spec §5, §6). `type`/`heading` are required — unlike
+ * IR's own `SlideSchema` (where both default/omit for weak-model
+ * friendliness), a deck spec is the authoring artifact those fields get
+ * *locked* from at assemble time (W5 task 3), so leaving either implicit
+ * here would defeat the point. `beat`/`focus`/`summary` stay optional per
+ * spec §5's defaults chain ("beat omitted → auto-rotates by page position —
+ * focus/summary/layout/slot can all be omitted").
  */
-declare const PlanPageSchema: z.ZodObject<{
+declare const PageSpecSchema: z.ZodObject<{
     id: z.ZodString;
     type: z.ZodEnum<{
         cover: "cover";
@@ -1582,7 +2277,7 @@ declare const PlanPageSchema: z.ZodObject<{
         ending: "ending";
     }>;
     heading: z.ZodString;
-    rhythm: z.ZodOptional<z.ZodEnum<{
+    beat: z.ZodOptional<z.ZodEnum<{
         anchor: "anchor";
         dense: "dense";
         breathing: "breathing";
@@ -1590,19 +2285,27 @@ declare const PlanPageSchema: z.ZodObject<{
     focus: z.ZodOptional<z.ZodString>;
     summary: z.ZodOptional<z.ZodString>;
 }, z.core.$strict>;
-type PlanPage = z.infer<typeof PlanPageSchema>;
+type PageSpec = z.infer<typeof PageSpecSchema>;
 /**
- * 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.
+ * Top-level deck spec shape (spec §5, §6). `narrative`/`theme` deliberately
+ * have no schema-level `.default(...)` — same reasoning as `PptxIRSchema`'s
+ * own `narrative` field (`ir/index.ts`): the resolved value is never baked
+ * back into the parsed shape, {@link validateSpec} (here) and, later,
+ * assemble (W5 task 3) each resolve it themselves. `seed` is accepted but
+ * entirely unexamined by this module — "not validateSpec's concern" (spec's
+ * own wording): assemble generates and suggests writing one back on first
+ * materialization.
+ *
+ * `version` stays the literal `"1"` (unchanged value) but now carries an
+ * independent Deck Spec versioning scheme (spec §6: "`deck.spec.json` 使用
+ * 独立的 spec 版本 1。它是新工件，不继承 `deck.plan.json` 的版本号语义") —
+ * this "1" is the Deck Spec artifact's own first version, not a continuation
+ * of the old deck-plan artifact's version counter, even though the digit is
+ * the same.
  */
-declare const DeckPlanSchema: z.ZodObject<{
+declare const DeckSpecSchema: z.ZodObject<{
     version: z.ZodDefault<z.ZodLiteral<"1">>;
-    scenario: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodUnknown>]>>;
+    narrative: 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>;
@@ -1659,7 +2362,7 @@ declare const DeckPlanSchema: z.ZodObject<{
             ending: "ending";
         }>;
         heading: z.ZodString;
-        rhythm: z.ZodOptional<z.ZodEnum<{
+        beat: z.ZodOptional<z.ZodEnum<{
             anchor: "anchor";
             dense: "dense";
             breathing: "breathing";
@@ -1668,10 +2371,10 @@ declare const DeckPlanSchema: z.ZodObject<{
         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 {
+type DeckSpec = z.infer<typeof DeckSpecSchema>;
+/** JSON Schema for the deck spec — feed this to a model before it writes one (see `pptfast schema --spec`). */
+declare function specJsonSchema(): Record<string, unknown>;
+interface SpecValidationIssue {
     path: string;
     message: string;
     /** The offending page's `id`, when the issue is scoped to one specific
@@ -1680,53 +2383,57 @@ interface PlanValidationIssue {
      *  whose own `id` itself failed to parse. */
     pageId?: string;
 }
-interface PlanValidateResult {
+interface SpecValidateResult {
     ok: boolean;
-    plan?: DeckPlan;
-    errors: PlanValidationIssue[];
+    spec?: DeckSpec;
+    errors: SpecValidationIssue[];
 }
-declare function formatPlanIssues(errors: PlanValidationIssue[]): string;
+declare function formatSpecIssues(errors: SpecValidationIssue[]): string;
 /**
- * Plan-level theme default (spec §5's defaults chain: "theme omitted →
+ * Deck-spec-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
+ * validated {@link DeckSpec} (the CLI's OK-summary line) doesn't re-derive
  * the fallback itself.
  */
-declare function resolvePlanThemeId(plan: DeckPlan): string;
+declare function resolveSpecThemeId(spec: DeckSpec): 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
+ * Deck-level page-count range per pacing (spec §5's pacing table,
+ * initial values — "dense 8-30 / balanced 6-24 / spacious 4-16", not yet
+ * tuned against real usage). Independent of `PACING_BUDGETS`
+ * (`narrative/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").
+ * out as its own hard gate ("page count vs. pacing recommended range").
+ * Message wording renamed from "delivery" to "pacing" (vocabulary-v4
+ * residual, routed from the task 1 review) — the axis itself was already
+ * `Pacing` at the type level, this closes the last stale word in the
+ * error text.
  */
-declare const PLAN_PAGE_COUNT_RANGE: Record<Delivery, {
+declare const SPEC_PAGE_COUNT_RANGE: Record<Pacing, {
     min: number;
     max: number;
 }>;
 /**
- * Validate raw JSON against the plan schema, then — once it parses — run the
+ * Validate raw JSON against the spec 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
+ * meant — e.g. beat-rotation and page-count both need a resolved
+ * narrative, so nothing past the narrative/theme stage runs until that
+ * resolves cleanly. Every spec-gate philosophy here is "hard block, no soft
+ * warning" (spec §5's "escape hatch" section — a spec that doesn't fit this shape
  * should be authored as bare IR instead, not warned-and-shipped).
  */
-declare function validatePlan(input: unknown): PlanValidateResult;
+declare function validateSpec(input: unknown): SpecValidateResult;
 
 /**
- * One page's fillable content — everything a plan page's `id` does *not*
- * already lock in. Deliberately excludes `type`/`heading` (plan-owned, see
+ * One page's fillable content — everything a page spec's `id` does *not*
+ * already lock in. Deliberately excludes `type`/`heading` (spec-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
+ * own layout — "pages/<id>.json contains only components" — a spec/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.
@@ -1738,15 +2445,16 @@ interface PageContent {
     background?: BackgroundSpec;
     image_side?: "left" | "right";
     footnote?: string;
+    notes?: string;
 }
 interface AssembleResult {
     ir: PptxIR;
     /**
-     * Set only when `plan.seed` was absent and {@link assembleDeck} generated
+     * Set only when `spec.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
+     * comment) — `undefined` when `spec.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
+     * suggest writing the value back into the spec file, never rewrite it
      * itself (assemble stays a pure function, no fs side effects here).
      */
     generatedSeed?: number;
@@ -1763,20 +2471,20 @@ interface AssembleResult {
     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.
+ * Assemble a validated deck spec 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
+ * 1. `spec` is `unknown` (same boundary `validateSpec` itself has — a spec
  *    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.
+ *    `validateSpec`'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
+ *    `pages` is `unknown`-shaped off disk same as `spec` 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
@@ -1790,63 +2498,69 @@ interface AssembleResult {
  *    `"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
+ * 3. Orphan keys: a `pages` entry whose id isn't any spec 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
+ * 4. Missing pages (a spec 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
+ *    contradiction (orphan file / bad spec / 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
+ *    `summary` — otherwise a spec-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
+ * 5. Present pages become a full slide: `id`/`type`/`heading` from the page
+ *    spec (never the content record — see step 2), plus whichever of
+ *    {@link PageContent}'s seven fields the content record actually set.
+ *    `beat`/`focus`/`summary` never reach the IR for a present page —
+ *    they are spec-only authoring anchors (beat/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
+ * 6. Top-level: `version` is always the literal `"4"` (IR's own version,
+ *    unrelated to the deck spec's own `version: "1"`) — the deck spec's own
+ *    `narrative` field (renamed this task from `scenario`, spec §8.1's
+ *    `DeckPlan`→`DeckSpec` rename, task 2) carries across into the v4 IR's
+ *    own `narrative` field, its value already in the new strategy/pacing
+ *    vocabulary (vocabulary-v4 rename, task 1 — `plan/index.ts`'s own
+ *    `resolveNarrative` call already validates it against that vocabulary
+ *    before this function ever runs).
+ *    `theme`/`filename`/`brand`/`meta`/`seed` (step 7) carry over from the spec 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
+ * 7. Seed: `spec.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
+ *    from `filename` + the spec'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
+ *    writing it back into the spec 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
+ *    calls with structurally-equal `spec`/`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;
+declare function assembleDeck(spec: unknown, pages: Record<string, PageContent>): AssembleResult;
 /**
- * Inverse of {@link assembleDeck}: reconstructs `{ plan, pages }` from an
+ * Inverse of {@link assembleDeck}: reconstructs `{ spec, 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
+ * (IR → spec/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`
+ * - `beat` and `focus` never appear on any produced {@link PageSpec} —
+ *   both are spec-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
+ *   `pageSpec.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
@@ -1855,14 +2569,14 @@ declare function assembleDeck(plan: unknown, pages: Record<string, PageContent>)
  *   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`
+ *   string (`DeckSpecSchema.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
+ *   `{ spec, 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}
@@ -1881,10 +2595,10 @@ declare function assembleDeck(plan: unknown, pages: Record<string, PageContent>)
  * 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.
+ * ({@link assembleDeck} step 6 reads `spec.brand` into `ir.brand` — this
+ * function reads `ir.brand` back into `spec.brand` below) — carried through
+ * unmodified, same as `narrative`/`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
@@ -1913,7 +2627,7 @@ declare function assembleDeck(plan: unknown, pages: Record<string, PageContent>)
  * {@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
+ * and type — but, unlike a spec-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).
  *
@@ -1932,10 +2646,44 @@ declare function assembleDeck(plan: unknown, pages: Record<string, PageContent>)
  * function) is what actually closes the vulnerability.
  */
 declare function disassembleDeck(ir: PptxIR): {
-    plan: DeckPlan;
+    spec: DeckSpec;
     pages: Record<string, PageContent>;
 };
 
+/**
+ * Deterministic, pure `deck.plan.json` → `deck.spec.json` migration (spec
+ * §9.2, vocabulary-v4 rename, task 2). Mirrors `../ir/migrate.ts`'s
+ * `migrateIrV3ToV4` in spirit — mechanical field rename only, no schema
+ * validation, no model call, no content rewrite (same posture spec §9.3
+ * states for the IR v3→v4 primitive: "只做已声明的结构映射，不运行模型，
+ * 不重写内容，不重新选择 layout" — this function is that same contract
+ * applied to the other artifact this rename touches). A caller should run
+ * `validateSpec` (`./index.ts`) against the result to confirm it lands as a
+ * legal deck spec, exactly as it would for a `deck.spec.json` authored by
+ * hand — this function itself never parses against `DeckSpecSchema`.
+ *
+ * Field-for-field, value-for-value per spec §9.2's table:
+ *
+ * ```text
+ * deck.plan.json                       → deck.spec.json
+ * scenario                             → narrative
+ * pages[].rhythm                       → pages[].beat
+ * 其余字段                              → 原样保留
+ * ```
+ *
+ * Takes the raw, `JSON.parse`d `deck.plan.json` contents (`unknown`) rather
+ * than an already-validated shape — unlike `migrateIrV3ToV4` (which takes an
+ * already-`PptxIRV3Schema.parse`d object), there is no schema left in this
+ * codebase a pre-rename plan file could validate against: `DeckSpecSchema`
+ * (`./index.ts`) already requires the *post*-rename field names (`narrative`,
+ * `beat`), so parsing a plan-shaped document against it would just fail on
+ * the very keys this function exists to rename. Non-object input, or a
+ * `pages` value that isn't an array, passes through completely unchanged —
+ * reporting a malformed source file is `runMigrate`'s job
+ * (`../cli/commands.ts`), not this mechanical rename step's.
+ */
+declare function migrateDeckPlanToSpec(raw: unknown): unknown;
+
 /**
  * `pptfast audit` finding shape (v0.3 W6, spec §7 workflow ④). `page` is
  * 1-based (matches `ValidationIssue.page` in `api.ts`); `slideId` is set
@@ -1946,38 +2694,72 @@ declare function disassembleDeck(ir: PptxIR): {
 interface AuditFinding {
     page: number;
     slideId?: string;
-    code: "overflow" | "out-of-bounds" | "low-contrast" | "overlap";
+    code: "overflow" | "out-of-bounds" | "low-contrast" | "overlap" | "content-truncated" | "content-dropped";
     message: string;
     detail?: Record<string, unknown>;
 }
+/**
+ * Which check families actually ran (audit-v2 phase B, spec §4.2/§11.6) —
+ * the one piece of the spec's original metrics design that survives into
+ * this wave (§11.6: metrics itself deferred, "唯一现值是 checks 结构"). This
+ * is the wave's own spirit made literal: a field can only ever be
+ * `"completed"` once its check family genuinely ran over every audited
+ * page, never a default that silently reads as "passed". `svg` has no
+ * `"not-requested"` state — the deterministic SVG audit always runs, so it
+ * is always `"completed"`. `pixels` starts `"not-requested"` and only ever
+ * becomes `"completed"`; there is deliberately no `"failed"` value — a
+ * failed pixel audit throws (spec §11.7's "契约层"), it never reports
+ * itself as a completed check that happens to carry no findings.
+ */
+interface AuditChecks {
+    svg: "completed";
+    pixels: "not-requested" | "completed";
+}
 interface AuditReport {
     findings: AuditFinding[];
     pagesAudited: number;
     pagesSkipped: number;
+    checks: AuditChecks;
+}
+/** `auditDeck`'s second parameter (audit-v2 phase B) — see that function's
+ *  own doc comment for the overload contract this shape backs. */
+interface AuditDeckOptions {
+    pixels?: boolean;
 }
 /**
- * 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.
+ * The SDK entry point. 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
+ * card list that had to drop an item to fit). 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`).
+ *
+ * `auditDeck` itself never calls `installNodePlatform()`; that's the
+ * caller's job (the CLI does it automatically).
+ *
+ * `opts.pixels` (audit-v2 phase B, spec §4.3/§11.7) opts into the optional
+ * pixel-level contrast audit over image-backed text (`../svg/audit/pixel-audit.ts`)
+ * — overloaded so the far more common omitted/`false` case keeps returning
+ * a plain, synchronous `AuditReport` (spec §11.7's "语义层": the default
+ * audit stays pure TS with zero added latency or Promise-wrapping), while
+ * `pixels: true` returns a `Promise<AuditReport>` that resolves once the
+ * rasterization pass completes. A caller holding a non-literal
+ * `{ pixels: someBoolean }` won't match either overload directly (TypeScript
+ * can't narrow it to one specific branch) — branch on the boolean first and
+ * call this function with a literal in each arm, e.g. `opts.pixels ? await
+ * auditDeck(ir, { pixels: true }) : auditDeck(ir)` (`cli/commands.ts`'s
+ * `runAudit` does exactly this).
  */
-declare function auditDeck(ir: PptxIR): AuditReport;
+declare function auditDeck(ir: PptxIR, opts?: {
+    pixels?: false;
+}): AuditReport;
+declare function auditDeck(ir: PptxIR, opts: {
+    pixels: true;
+}): Promise<AuditReport>;
 
-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 };
+export { AUDIENCE_VALUES, type AssembleResult, type Assets, type Audience, type AuditChecks, type AuditDeckOptions, type AuditFinding, type AuditReport, BUILTIN_THEME_IDS, type BackgroundSpec, type BrandConfig, BrandConfigSchema, COMPONENT_TYPES, type Component, DEFAULT_NARRATIVE, type DeckSpec, DeckSpecSchema, type Meta, NARRATIVE_PRESETS, type NarrativePreset, type NarrativeProfile, PACING_BUDGETS, PACING_VALUES, type Pacing, type PacingBudget, type PageBeat, type PageContent, type PageSpec, PageSpecSchema, type PageSpecType, PptfastError, type PptxIR, PptxIRSchema, type PptxIRV3, PptxIRV3Schema, SPEC_PAGE_COUNT_RANGE, STRATEGY_DEFINITIONS, STRATEGY_VALUES, type Slide, type SpecValidateResult, type SpecValidationIssue, type Strategy, type StrategyDefinition, type StyleOverride, StyleOverrideSchema, type ThemeDefinition, type ThemeInfo, type ThemeRegistration, ThemeSchema, VERSION, type ValidateResult, type ValidationIssue, assembleDeck, auditDeck, disassembleDeck, formatIssues, formatSpecIssues, generatePptx, getInstalledThemeIds, getThemeDefinition, irJsonSchema, listThemes, migrateDeckPlanToSpec, migrateIrV3ToV4, registerTheme, renderSlideSvg, resolveNarrative, resolveSpecThemeId, specJsonSchema, styleJsonSchema, validateIr, validateSpec };