@liustack/pptfast 0.9.0 → 0.11.0

package/dist/validate.d.ts

@@ -1,11 +1,44 @@
 import { z } from 'zod';
 
-declare const VERSION = "0.9.0";
+declare const VERSION = "0.11.0";
 
 /** Error class thrown by pptfast's public API surface (validation, rendering, export). */
 declare class PptfastError extends Error {
 }
 
+/**
+ * The v4 IR schema root: theme/meta/assets/brand/background/slide/narrative
+ * and the top-level `PptxIRSchema` a deck document parses against
+ * (`parsePptxIR`). The frozen v3 shape lives in `./legacy-v3.ts`, kept only
+ * for `migrateIrV3ToV4`'s input parsing (spec §9.3).
+ *
+ * **The `ComponentSchema` union below is a pure aggregator (src domain reorg
+ * wave 2, spec §4.3), same discipline as `src/svg/layouts/registry.ts`'s T1d
+ * precedent.** Every one of the 32 component schemas used to live here as a
+ * literal `z.object({...})` entry directly inside the `discriminatedUnion`
+ * array. Each now lives in its own `src/ir/components/<name>.ts` domain file
+ * instead (schema + field aliases + render-trait declaration together, spec
+ * §4.1) — imported below and referenced by name, in the exact union position
+ * its literal used to occupy, so "take one component away whole" is a
+ * single-file operation instead of an edit split across this file,
+ * `field-aliases.ts`, and `component-traits.ts`. This file's own job for
+ * components is now purely computational: import all 32, construct
+ * `ComponentSchema` via `z.discriminatedUnion`, and derive `COMPONENT_TYPES`
+ * from the result — never a hand-copied literal, never a re-export relay. A
+ * handful of schema fragments genuinely shared by ≥2 components (only the
+ * icon-name enum, as of this wave) live in `src/ir/components/shared.ts`
+ * instead of any one domain file; every other named sub-schema that reads as
+ * "shared" at a glance (e.g. `GanttItemSchema`, `PestQuadrantSchema`,
+ * `SankeyNodeSchema`/`SankeyLinkSchema`) turned out to be single-consumer and
+ * moved into its own component's domain file with it.
+ *
+ * The rest of this module — everything outside the `// ── Components` section
+ * — is unrelated to the component-domain split and was never in its scope:
+ * background/theme/meta/assets/brand/slide/narrative and the top-level
+ * `PptxIRSchema` are genuinely this file's own content, not aggregated from
+ * elsewhere.
+ */
+
 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">;
@@ -27,8 +60,8 @@ declare const BackgroundSpecSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
         opacity: z.ZodNumber;
     }, z.core.$strict>>;
     fit: z.ZodOptional<z.ZodEnum<{
-        cover: "cover";
         contain: "contain";
+        cover: "cover";
     }>>;
 }, z.core.$strict>], "kind">;
 /**
@@ -129,9 +162,9 @@ declare const MetaSchema: z.ZodObject<{
     animation: z.ZodOptional<z.ZodObject<{
         transition: z.ZodOptional<z.ZodEnum<{
             push: "push";
+            none: "none";
             fade: "fade";
             wipe: "wipe";
-            none: "none";
         }>>;
         elements: z.ZodOptional<z.ZodEnum<{
             none: "none";
@@ -329,8 +362,8 @@ declare const ComponentSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
         tag: z.ZodOptional<z.ZodString>;
         tone: z.ZodOptional<z.ZodEnum<{
             info: "info";
-            accent: "accent";
             neutral: "neutral";
+            accent: "accent";
         }>>;
     }, z.core.$strict>>;
 }, z.core.$strict>, z.ZodObject<{
@@ -345,9 +378,9 @@ declare const ComponentSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     type: z.ZodLiteral<"verdict_banner">;
     text: z.ZodString;
     tone: z.ZodEnum<{
-        neutral: "neutral";
         positive: "positive";
         warning: "warning";
+        neutral: "neutral";
     }>;
     icon: z.ZodOptional<z.ZodEnum<{
         [x: string]: string;
@@ -364,8 +397,8 @@ declare const ComponentSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     asset_id: z.ZodString;
     caption: z.ZodOptional<z.ZodString>;
     fit: z.ZodDefault<z.ZodEnum<{
-        cover: "cover";
         contain: "contain";
+        cover: "cover";
     }>>;
 }, z.core.$strict>, z.ZodObject<{
     type: z.ZodLiteral<"image_grid">;
@@ -521,30 +554,49 @@ declare const ComponentSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
         to: z.ZodString;
         value: z.ZodNumber;
     }, z.core.$strict>>;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"data_table">;
+    columns: z.ZodArray<z.ZodObject<{
+        key: z.ZodString;
+        label: z.ZodString;
+        align: z.ZodOptional<z.ZodEnum<{
+            left: "left";
+            right: "right";
+            center: "center";
+        }>>;
+    }, z.core.$strict>>;
+    rows: z.ZodArray<z.ZodObject<{
+        cells: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+        emphasis: z.ZodOptional<z.ZodEnum<{
+            highlight: "highlight";
+            total: "total";
+        }>>;
+    }, z.core.$strict>>;
+    source: z.ZodOptional<z.ZodString>;
 }, z.core.$strict>], "type">;
 /**
  * All 32 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
+ * `src/spec/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.ZodDefault<z.ZodEnum<{
+        content: "content";
         cover: "cover";
         chapter: "chapter";
-        content: "content";
         ending: "ending";
     }>>;
     id: z.ZodOptional<z.ZodString>;
     placeholder: z.ZodOptional<z.ZodLiteral<true>>;
     layout: z.ZodOptional<z.ZodString>;
     beat: z.ZodOptional<z.ZodEnum<{
-        anchor: "anchor";
         dense: "dense";
+        anchor: "anchor";
         breathing: "breathing";
     }>>;
     arrangement: z.ZodOptional<z.ZodEnum<{
@@ -743,8 +795,8 @@ declare const SlideSchema: z.ZodObject<{
             tag: z.ZodOptional<z.ZodString>;
             tone: z.ZodOptional<z.ZodEnum<{
                 info: "info";
-                accent: "accent";
                 neutral: "neutral";
+                accent: "accent";
             }>>;
         }, z.core.$strict>>;
     }, z.core.$strict>, z.ZodObject<{
@@ -759,9 +811,9 @@ declare const SlideSchema: z.ZodObject<{
         type: z.ZodLiteral<"verdict_banner">;
         text: z.ZodString;
         tone: z.ZodEnum<{
-            neutral: "neutral";
             positive: "positive";
             warning: "warning";
+            neutral: "neutral";
         }>;
         icon: z.ZodOptional<z.ZodEnum<{
             [x: string]: string;
@@ -778,8 +830,8 @@ declare const SlideSchema: z.ZodObject<{
         asset_id: z.ZodString;
         caption: z.ZodOptional<z.ZodString>;
         fit: z.ZodDefault<z.ZodEnum<{
-            cover: "cover";
             contain: "contain";
+            cover: "cover";
         }>>;
     }, z.core.$strict>, z.ZodObject<{
         type: z.ZodLiteral<"image_grid">;
@@ -935,6 +987,25 @@ declare const SlideSchema: z.ZodObject<{
             to: z.ZodString;
             value: z.ZodNumber;
         }, z.core.$strict>>;
+    }, z.core.$strict>, z.ZodObject<{
+        type: z.ZodLiteral<"data_table">;
+        columns: z.ZodArray<z.ZodObject<{
+            key: z.ZodString;
+            label: z.ZodString;
+            align: z.ZodOptional<z.ZodEnum<{
+                left: "left";
+                right: "right";
+                center: "center";
+            }>>;
+        }, z.core.$strict>>;
+        rows: z.ZodArray<z.ZodObject<{
+            cells: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+            emphasis: z.ZodOptional<z.ZodEnum<{
+                highlight: "highlight";
+                total: "total";
+            }>>;
+        }, z.core.$strict>>;
+        source: z.ZodOptional<z.ZodString>;
     }, z.core.$strict>], "type">>>;
     background: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
         kind: z.ZodLiteral<"color">;
@@ -956,8 +1027,8 @@ declare const SlideSchema: z.ZodObject<{
             opacity: z.ZodNumber;
         }, z.core.$strict>>;
         fit: z.ZodOptional<z.ZodEnum<{
-            cover: "cover";
             contain: "contain";
+            cover: "cover";
         }>>;
     }, z.core.$strict>], "kind">>;
     decor: z.ZodOptional<z.ZodObject<{
@@ -1041,9 +1112,9 @@ declare const PptxIRSchema: z.ZodObject<{
         animation: z.ZodOptional<z.ZodObject<{
             transition: z.ZodOptional<z.ZodEnum<{
                 push: "push";
+                none: "none";
                 fade: "fade";
                 wipe: "wipe";
-                none: "none";
             }>>;
             elements: z.ZodOptional<z.ZodEnum<{
                 none: "none";
@@ -1070,17 +1141,17 @@ declare const PptxIRSchema: z.ZodObject<{
     seed: z.ZodOptional<z.ZodNumber>;
     slides: z.ZodArray<z.ZodObject<{
         type: z.ZodDefault<z.ZodEnum<{
+            content: "content";
             cover: "cover";
             chapter: "chapter";
-            content: "content";
             ending: "ending";
         }>>;
         id: z.ZodOptional<z.ZodString>;
         placeholder: z.ZodOptional<z.ZodLiteral<true>>;
         layout: z.ZodOptional<z.ZodString>;
         beat: z.ZodOptional<z.ZodEnum<{
-            anchor: "anchor";
             dense: "dense";
+            anchor: "anchor";
             breathing: "breathing";
         }>>;
         arrangement: z.ZodOptional<z.ZodEnum<{
@@ -1279,8 +1350,8 @@ declare const PptxIRSchema: z.ZodObject<{
                 tag: z.ZodOptional<z.ZodString>;
                 tone: z.ZodOptional<z.ZodEnum<{
                     info: "info";
-                    accent: "accent";
                     neutral: "neutral";
+                    accent: "accent";
                 }>>;
             }, z.core.$strict>>;
         }, z.core.$strict>, z.ZodObject<{
@@ -1295,9 +1366,9 @@ declare const PptxIRSchema: z.ZodObject<{
             type: z.ZodLiteral<"verdict_banner">;
             text: z.ZodString;
             tone: z.ZodEnum<{
-                neutral: "neutral";
                 positive: "positive";
                 warning: "warning";
+                neutral: "neutral";
             }>;
             icon: z.ZodOptional<z.ZodEnum<{
                 [x: string]: string;
@@ -1314,8 +1385,8 @@ declare const PptxIRSchema: z.ZodObject<{
             asset_id: z.ZodString;
             caption: z.ZodOptional<z.ZodString>;
             fit: z.ZodDefault<z.ZodEnum<{
-                cover: "cover";
                 contain: "contain";
+                cover: "cover";
             }>>;
         }, z.core.$strict>, z.ZodObject<{
             type: z.ZodLiteral<"image_grid">;
@@ -1471,6 +1542,25 @@ declare const PptxIRSchema: z.ZodObject<{
                 to: z.ZodString;
                 value: z.ZodNumber;
             }, z.core.$strict>>;
+        }, z.core.$strict>, z.ZodObject<{
+            type: z.ZodLiteral<"data_table">;
+            columns: z.ZodArray<z.ZodObject<{
+                key: z.ZodString;
+                label: z.ZodString;
+                align: z.ZodOptional<z.ZodEnum<{
+                    left: "left";
+                    right: "right";
+                    center: "center";
+                }>>;
+            }, z.core.$strict>>;
+            rows: z.ZodArray<z.ZodObject<{
+                cells: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+                emphasis: z.ZodOptional<z.ZodEnum<{
+                    highlight: "highlight";
+                    total: "total";
+                }>>;
+            }, z.core.$strict>>;
+            source: z.ZodOptional<z.ZodString>;
         }, z.core.$strict>], "type">>>;
         background: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
             kind: z.ZodLiteral<"color">;
@@ -1492,8 +1582,8 @@ declare const PptxIRSchema: z.ZodObject<{
                 opacity: z.ZodNumber;
             }, z.core.$strict>>;
             fit: z.ZodOptional<z.ZodEnum<{
-                cover: "cover";
                 contain: "contain";
+                cover: "cover";
             }>>;
         }, z.core.$strict>], "kind">>;
         decor: z.ZodOptional<z.ZodObject<{
@@ -1611,18 +1701,32 @@ interface ValidateResult {
  * 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`.
+ * Before any of that, two deterministic pre-parse rewrite passes run, each
+ * threading its rewrite notes onto `ValidateResult.normalized` on *every*
+ * return path below via `withNormalized`, success or failure alike — neither
+ * ever gates `ok` on its own:
+ *  - {@link normalizeComponentAliases} (W5 task 4): the component
+ *    field-name synonym rescue (kpi `title`→`label`, quote `content`→`text`,
+ *    …), scoped to `slides[]`. 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.
+ *  - {@link normalizeNarrativeShape} (`./narrative`, T0b bench-evidence fix
+ *    2 — see its own doc comment for the full rationale): the root-level
+ *    `narrative: {id: <preset>}` shape rescue. A model that just wrote
+ *    `theme: {id: "consulting"}` a few lines above pattern-matches the same
+ *    wrapper shape onto `narrative`; this rewrites it to the bare preset
+ *    string `resolveNarrative`'s string branch actually expects. Fires only
+ *    when `id` is the object's sole narrative-relevant key (none of
+ *    strategy/pacing/audience alongside it) — a mixed shape stays
+ *    unrescued, ambiguous, and hard-errors exactly as it did before this
+ *    pass existed.
+ *
+ * Both are the same class of fix — a weak-model *synonym* rescue (a name
+ * drift for the component-alias pass, a *shape* drift for the narrative
+ * pass) — which is the actual boundary the next paragraph's "no
+ * old-vocabulary rescue" draws, not "no rewrite ever touches `narrative`."
  *
- * There is deliberately no root/narrative-level alias pass (spec §16,
+ * There is still deliberately no *old-vocabulary* rescue (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
@@ -1632,21 +1736,24 @@ interface ValidateResult {
  * 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. Hard-erroring is not the same as
- * leaving the error message unhelpful, though: the schema-parse branch below
- * appends a rename hint to `scenario` and the rest of the documented v2/v3
- * rename map (`blocks`/`variant`/`theme.override` — `./ir/rename-hints.ts`,
- * borrow-wave task 3) whenever the offending key matches one, and a generic
- * "belongs inside components[]" hint for any other slide-level unrecognized
- * key — message-layer annotation only, never a second, silent rewrite path
- * alongside {@link normalizeComponentAliases}.
+ * check, listing the current values. `{id: <preset>}` was never a v3
+ * `scenario` shape, so `normalizeNarrativeShape` above does not reopen this
+ * door — it rescues a shape weak models invent by analogy to `theme.id`, not
+ * a shape the pre-rename vocabulary ever spoke. `pptfast migrate`
+ * (`ir/migrate.ts`) remains the sanctioned bridge for a genuine v3 document —
+ * see the v3 hard reject below, which points there. Hard-erroring is not the
+ * same as leaving the error message unhelpful, though: the schema-parse
+ * branch below appends a rename hint to `scenario` and the rest of the
+ * documented v2/v3 rename map (`blocks`/`variant`/`theme.override` —
+ * `./ir/rename-hints.ts`, borrow-wave task 3) whenever the offending key
+ * matches one, and a generic "belongs inside components[]" hint for any
+ * other slide-level unrecognized key — message-layer annotation only, never
+ * a second, silent rewrite path alongside the two passes above.
  *
- * 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).
+ * Both pre-parse passes only ever run for a document already headed for the
+ * v4 schema — an explicit `version: "2"` or `version: "3"` is hard-rejected
+ * first, below, before either pass or any schema parse (spec §9.3: a v2/v3
+ * document is never silently reinterpreted as v4).
  */
 declare function validateIr(input: unknown): ValidateResult;
 /**