@openpresentation/opf 0.2.1 → 0.3.0

package/dist/docs.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/generated/docs.ts","../src/docs.ts"],"names":[],"mappings":";AAaA,IAAM,QAAA,GAAiC,OAAO,MAAA,CAAO;AAAA,EACnD;AAAA,IACE,MAAA,EAAQ,0BAAA;AAAA,IACR,MAAA,EAAQ,kCAAA;AAAA,IACR,OAAA,EAAS,8BAAA;AAAA,IACT,UAAA,EAAY;AAAA,GACd;AAAA,EACA;AAAA,IACE,MAAA,EAAQ,+BAAA;AAAA,IACR,MAAA,EAAQ,uCAAA;AAAA,IACR,OAAA,EAAS,iCAAA;AAAA,IACT,UAAA,EAAY;AAAA,GACd;AAAA,EACA;AAAA,IACE,MAAA,EAAQ,kBAAA;AAAA,IACR,MAAA,EAAQ,0BAAA;AAAA,IACR,OAAA,EAAS,kBAAA;AAAA,IACT,UAAA,EAAY;AAAA,GACd;AAAA,EACA;AAAA,IACE,MAAA,EAAQ,mBAAA;AAAA,IACR,MAAA,EAAQ,2BAAA;AAAA,IACR,OAAA,EAAS,mBAAA;AAAA,IACT,UAAA,EAAY;AAAA,GACd;AAAA,EACA;AAAA,IACE,MAAA,EAAQ,UAAA;AAAA,IACR,MAAA,EAAQ,kBAAA;AAAA,IACR,OAAA,EAAS,oBAAA;AAAA,IACT,UAAA,EAAY;AAAA,GACd;AAAA,EACA;AAAA,IACE,MAAA,EAAQ,eAAA;AAAA,IACR,MAAA,EAAQ,uBAAA;AAAA,IACR,OAAA,EAAS,eAAA;AAAA,IACT,UAAA,EAAY;AAAA,GACd;AAAA,EACA;AAAA,IACE,MAAA,EAAQ,kBAAA;AAAA,IACR,MAAA,EAAQ,0BAAA;AAAA,IACR,OAAA,EAAS,mCAAA;AAAA,IACT,UAAA,EAAY;AAAA;AAEhB,CAAyB,CAAA;AAElB,IAAM,OAAA,GAAU,QAAA;;;AC7ChB,IAAM,IAAA,GAA6B;AAGnC,SAAS,OAAO,IAAA,EAAqC;AAC1D,EAAA,OAAO,QAAQ,IAAA,CAAK,CAAC,GAAA,KAAQ,GAAA,CAAI,SAAS,IAAI,CAAA;AAChD","file":"docs.js","sourcesContent":["// Generated by scripts/generate-content.mjs from docs/*.md. Do not edit by hand.\n\nexport interface DocRecord {\n  /** Filename slug, without the `.md` suffix. */\n  readonly slug: string;\n  /** Path relative to the repo root, with forward slashes. */\n  readonly file: string;\n  /** First-level heading from the markdown, falling back to a slug-derived title. */\n  readonly title: string;\n  /** Raw markdown content. */\n  readonly markdown: string;\n}\n\nconst docsData: readonly DocRecord[] = Object.freeze([\n  {\n    \"slug\": \"catalog-schema-reference\",\n    \"file\": \"docs/catalog-schema-reference.md\",\n    \"title\": \"OPF Catalog Schema Reference\",\n    \"markdown\": \"# OPF Catalog Schema Reference\\n\\nCatalog records are reusable presets that OPF documents reference by id. This page summarizes every companion schema in `spec/schemas/` except the top-level presentation schema.\\n\\nOPF documents usually reference these records with string ids such as `design.theme = \\\"minimal\\\"`, `tone = \\\"formal\\\"`, or `chart.type = \\\"line\\\"`. Dense examples may also embed catalog sources or inline records under `catalogs`.\\n\\n## Audience\\n\\n- File: `spec/schemas/audience.schema.json`\\n- Schema id: `https://openpresentation.org/schema/opf-audience/v1`\\n- Type: `object`\\n- Required fields: `$schema`, `id`, `name`\\n- Purpose: Schema for audience records in the pptx.gallery library. Each record names an audience archetype (e.g. 'executives', 'engineering-team', 'investors') and carries seniority, technical-fluency, decision-power, and attention-budget hints used by AI-driven generation. Audiences are referenced from OPF documents via audience; the engine resolves the reference against catalogs.audiences (inline) catalogs.audiences.source the default catalog at https://www.pptx.gallery/audiences. The audience field...\\n\\n| Field | Required | Type | Notes |\\n| --- | --- | --- | --- |\\n| `$schema` | yes | `const:\\\"https://openpresentation.org/schema/opf-audience/v1\\\"` | Identifies this record as an audience in the openpresentation.org catalog. |\\n| `id` | yes | `string` | Stable slug used by OPF documents to reference this audience via audience. Lowercase kebab-case. |\\n| `name` | yes | `string` | Human-readable audience name shown in pickers. |\\n| `summary` | no | `string` | One-sentence positioning of the audience who they are and what they care about. |\\n| `description` | no | `string` | Longer prose describing the audience archetype and how to address them. |\\n| `seniority` | no | `enum:ic \\\\| manager \\\\| director \\\\| vp \\\\| c-suite \\\\| mixed` | Typical seniority level of the audience. Engines use this as a hint for default depth and pacing. |\\n| `technicalFluency` | no | `enum:low \\\\| medium \\\\| high \\\\| mixed` | Typical technical fluency of the audience. AI generation uses this to decide whether to expand or assume technical terminology. |\\n| `decisionPower` | no | `enum:informational \\\\| advisory \\\\| decision-maker` | Whether the audience is expected to be informed, to advise, or to actually decide. Shapes the strength of the closing ask. |\\n| `attentionBudgetMinutes` | no | `number` | Realistic upper bound on this audience's focused attention for a single presentation, in minutes. Used as a hint when comparing against duration and the resolved narrative's durationRange. |\\n| `recommendedNarratives` | no | `array<string>` | Soft cross-link: narrative-catalog ids that work well for this audience. Used by picker UIs to suggest narratives once an audience is chosen. Validators warn on unknown ids; never error. |\\n| `recommendedTones` | no | `array<string>` | Soft cross-link: tone-catalog ids that work well for this audience. |\\n| `tags` | no | `array<string>` | Free-form labels for filtering and search. |\\n| `preview` | no | `object` | Visual previews of the record, used by picker UIs and inline rendering. All sub-fields are optional. |\\n\\n## Chart Type\\n\\n- File: `spec/schemas/chart-type.schema.json`\\n- Schema id: `https://openpresentation.org/schema/opf-chart-type/v1`\\n- Type: `object`\\n- Required fields: `$schema`, `id`, `name`, `mappings`\\n- Purpose: Schema for chart-type records in the pptx.gallery catalog. Each record describes a named chart variant, its Open XML mapping, its series/category cardinality, the column structure of the underlying workbook, and a small sample dataset suitable for previews. Chart types are referenced from OPF chart content payloads; the engine resolves the reference against catalogs.chartTypes (inline) -> catalogs.chartTypes.source -> the default catalog at https://www.pptx.gallery/chart-types.\\n\\n| Field | Required | Type | Notes |\\n| --- | --- | --- | --- |\\n| `$schema` | yes | `const:\\\"https://openpresentation.org/schema/opf-chart-type/v1\\\"` | Identifies this record as a chart type in the open presentation catalog. |\\n| `id` | yes | `string` | Stable slug used by OPF documents to reference this chart type. Lowercase kebab-case. Chart type ids may start with a digit (e.g., '100pct-stacked-column', '3d-column') to mirror conventional chart naming. |\\n| `name` | yes | `string` | Stable display/programmatic name for this chart type. |\\n| `label` | no | `string` | Human-readable label shown in chart pickers. |\\n| `summary` | no | `string` | One-sentence positioning: when to reach for this chart variant. |\\n| `description` | no | `string` | Longer prose describing the chart and ideal use cases. |\\n| `mappings` | yes | `ref:ChartTypeMappings` | Canonical and optional renderer-specific mappings used by engines to render this chart type. |\\n| `group` | no | `string` | Top-level grouping in the chart picker (column, bar, line, area, pie, radar, etc.). |\\n| `groupSort` | no | `integer` | Display ordering hint within the chart group. |\\n| `complexity` | no | `enum:simple \\\\| calculated \\\\| hierarchical \\\\| normalized` | Shape of the underlying data: a flat series ('simple'), one with engine-side calculation ('calculated'), parent-child rows ('hierarchical'), or pre-normalized rows ('normalized'). |\\n| `series` | no | `integer` | Number of data series this chart type expects. |\\n| `categories` | no | `integer` | Number of category labels this chart type expects on the primary axis. |\\n| `seriesGroups` | no | `integer` | Number of series groups (axis bands) this chart type uses; >1 for combo or banded charts. |\\n| `useSecondaryCategories` | no | `boolean` | Whether the chart type uses a secondary category axis. |\\n| `workbookRange` | no | `string` | A1 reference to the source range in the embedded workbook. |\\n| `columns` | no | `array<string>` | Column header names of the embedded workbook, in left-to-right order. |\\n| `dataColumns` | no | `array<ref:ChartDataColumn>` | Per-column metadata describing the role and position of each column in the workbook source. |\\n| `helperColumns` | no | `array<string>` | Optional auxiliary column names used by calculated or banded charts (e.g., 'Excellent', 'Good', 'Fair', 'Poor' for a bullet chart). |\\n| `sampleData` | no | `ref:ChartSampleData` | Inline sample dataset for previews and pickers. |\\n| `slideNumber` | no | `integer` | Source slide number in the original chart-gallery deck. Carried for traceability. |\\n| `tags` | no | `array<string>` | Free-form labels for filtering and search. |\\n| `preview` | no | `object` | Visual previews of the record, used by picker UIs and inline rendering. All sub-fields are optional; engines fall back gracefully when previews aren't available. |\\n\\n### Nested Types\\n\\n#### ChartTypeMappings\\n\\n- Type: `object`\\n- Required fields: `openxml`\\n\\n| Field | Required | Type | Notes |\\n| --- | --- | --- | --- |\\n| `openxml` | yes | `ref:OpenXmlChartMapping` | Canonical mapping to Open XML chart structures. |\\n| `renderers` | no | `object` | Optional renderer-specific mappings. Keys are renderer ids; values are intentionally opaque to OPF. |\\n\\n#### OpenXmlChartMapping\\n\\n- Type: `object`\\n- Required fields: none\\n\\n| Field | Required | Type | Notes |\\n| --- | --- | --- | --- |\\n| `element` | no | `string` | Primary Open XML chart element or extension chart element, such as 'barChart', 'lineChart', 'pieChart', 'treemapChart', or 'waterfallChart'. |\\n| `barDir` | no | `enum:bar \\\\| col` | Bar direction for Open XML barChart mappings. |\\n| `grouping` | no | `enum:standard \\\\| clustered \\\\| stacked \\\\| percentStacked` | Open XML chart grouping value when the chart family supports grouping. |\\n| `marker` | no | `boolean` | Whether the chart type expects visible data markers. |\\n| `radarStyle` | no | `enum:standard \\\\| marker \\\\| filled` | Open XML radarStyle value for radarChart mappings. |\\n| `scatterStyle` | no | `enum:line \\\\| lineMarker \\\\| marker \\\\| smooth \\\\| smoothMarker` | Open XML scatterStyle value for scatterChart mappings. |\\n| `composition` | no | `enum:single \\\\| mixed \\\\| extension` | Whether the chart maps to one standard chart element, multiple combined chart elements, or an Open XML extension chart. |\\n| `extension` | no | `string` | Optional Open XML extension namespace or element hint for extension charts. |\\n| `series` | no | `array<ref:OpenXmlChartMapping>` | Open XML chart elements used by mixed/composite chart types. |\\n| `notes` | no | `string` | Short implementation note for mappings that need renderer interpretation. |\\n\\n#### ChartDataColumn\\n\\n- Type: `object`\\n- Required fields: `name`, `role`, `type`\\n- Purpose: One column of the embedded chart workbook, annotated with its role and grid position.\\n\\n| Field | Required | Type | Notes |\\n| --- | --- | --- | --- |\\n| `name` | yes | `string` | Column header name (e.g. 'Series 1', 'Value', 'Level1', 'Level2'). |\\n| `role` | yes | `enum:categoryLabel \\\\| series \\\\| helper` | Role this column plays: a category label (axis tick), a series (plotted values), or a helper (calculated/auxiliary). |\\n| `type` | yes | `enum:string \\\\| number` | Cell value type for the column. |\\n| `position` | no | `string` | Grid position of the column header in the source workbook, as 'row<N>_col<M>' (zero-indexed). |\\n\\n#### ChartSampleData\\n\\n- Type: `object`\\n- Required fields: `headers`, `rows`\\n- Purpose: Inline sample dataset for previews. Mirrors a small workbook with header row plus data rows.\\n\\n| Field | Required | Type | Notes |\\n| --- | --- | --- | --- |\\n| `headers` | yes | `array<string>` | Header row labels. The first cell typically labels the series column; the rest are category labels. |\\n| `rows` | yes | `array<array<string \\\\| number>>` | Two-dimensional sample data. Each row aligns by index with the headers first cell is the row label, remaining cells are values. |\\n\\n## Color Scheme\\n\\n- File: `spec/schemas/color-scheme.schema.json`\\n- Schema id: `https://openpresentation.org/schema/opf-color-scheme/v1`\\n- Type: `object`\\n- Required fields: `$schema`, `id`, `name`\\n- Purpose: Schema for color-scheme records in the pptx.gallery library. Each scheme is a named palette with the twelve PowerPoint color slots (six accents, two darks, two lights, plus hyperlink and followed-hyperlink), suitable for being mapped directly into OOXML theme XML. Color schemes are referenced from OPF documents via design.colorScheme or design.colorScheme.id; the engine resolves the reference against catalogs.colorSchemes (inline) -> catalogs.colorSchemes.source -> the default catalog at http...\\n\\n| Field | Required | Type | Notes |\\n| --- | --- | --- | --- |\\n| `$schema` | yes | `const:\\\"https://openpresentation.org/schema/opf-color-scheme/v1\\\"` | Identifies this record as a color scheme in the openpresentation.org catalog. |\\n| `id` | yes | `string` | Stable slug used by OPF documents to reference this color scheme. Lowercase kebab-case. |\\n| `name` | yes | `string` | Human-readable scheme name shown in pickers. |\\n| `summary` | no | `string` | One-sentence positioning of the palette what mood it evokes and where to use it. |\\n| `description` | no | `string` | Longer prose describing the palette and its intended use. |\\n| `accent1` | no | `string` | Accent 1 color (hex). Mirrors the OOXML accent1 slot. |\\n| `accent2` | no | `string` | Accent 2 color (hex). Mirrors the OOXML accent2 slot. |\\n| `accent3` | no | `string` | Accent 3 color (hex). Mirrors the OOXML accent3 slot. |\\n| `accent4` | no | `string` | Accent 4 color (hex). Mirrors the OOXML accent4 slot. |\\n| `accent5` | no | `string` | Accent 5 color (hex). Mirrors the OOXML accent5 slot. |\\n| `accent6` | no | `string` | Accent 6 color (hex). Mirrors the OOXML accent6 slot. |\\n| `dark1` | no | `string` | Dark 1 color (hex). Typically the deepest neutral; OOXML dark1. |\\n| `dark2` | no | `string` | Dark 2 color (hex). Secondary dark; OOXML dark2. |\\n| `light1` | no | `string` | Light 1 color (hex). Typically the slide canvas; OOXML lt1. |\\n| `light2` | no | `string` | Light 2 color (hex). Secondary light surface; OOXML lt2. |\\n| `hyperlink` | no | `string` | Hyperlink color (hex). OOXML hlink. |\\n| `followedHyperlink` | no | `string` | Followed-hyperlink color (hex). OOXML folHlink. |\\n| `tags` | no | `array<string>` | Free-form labels for filtering and search. |\\n| `preview` | no | `object` | Visual previews of the record, used by picker UIs and inline rendering. All sub-fields are optional; engines fall back gracefully when previews aren't available. |\\n\\n## Font Scheme\\n\\n- File: `spec/schemas/font-scheme.schema.json`\\n- Schema id: `https://openpresentation.org/schema/opf-font-scheme/v1`\\n- Type: `object`\\n- Required fields: `$schema`, `id`, `name`, `major`, `minor`\\n- Purpose: Schema for font-scheme records in the pptx.gallery library. Each scheme pairs a major (heading) and minor (body) font family in the OOXML majorFont/minorFont sense, scoped to a target app (PowerPoint or Google Slides) and a language family (Latin, East Asian, or Complex Script). Font schemes are referenced from OPF documents via design.fontScheme or design.fontScheme.id; the engine resolves the reference against catalogs.fontSchemes (inline) catalogs.fontSchemes.source the default catalog at...\\n\\n| Field | Required | Type | Notes |\\n| --- | --- | --- | --- |\\n| `$schema` | yes | `const:\\\"https://openpresentation.org/schema/opf-font-scheme/v1\\\"` | Identifies this record as a font scheme in the openpresentation.org catalog. |\\n| `id` | yes | `string` | Stable slug used by OPF documents to reference this font scheme. Lowercase kebab-case. |\\n| `name` | yes | `string` | Human-readable scheme name shown in pickers. |\\n| `major` | yes | `string` | Heading (major) font family mirrors the OOXML majorFont entry. |\\n| `minor` | yes | `string` | Body (minor) font family mirrors the OOXML minorFont entry. |\\n| `type` | no | `enum:sans-serif \\\\| serif \\\\| monospace` | High-level typographic class of the scheme. |\\n| `app` | no | `enum:PowerPoint \\\\| Google Slides` | Target application this font pairing is intended for. |\\n| `languageFamily` | no | `enum:latin \\\\| ea \\\\| cs` | OOXML font-language family this scheme is intended for: 'latin' for Latin-script content, 'ea' for East Asian scripts, 'cs' for Complex Scripts. |\\n| `languages` | no | `array<string>` | Optional list of human-readable language names this scheme is curated for. Useful for picker UIs that group fonts by language coverage. |\\n| `textSample` | no | `string` | Short specimen string used by picker UIs to preview the scheme. |\\n| `summary` | no | `string` | One-sentence positioning of the font pairing. |\\n| `description` | no | `string` | Longer prose describing the font scheme and where it shines. |\\n| `tags` | no | `array<string>` | Free-form labels for filtering and search. |\\n| `preview` | no | `object` | Visual previews of the record, used by picker UIs and inline rendering. All sub-fields are optional; engines fall back gracefully when previews aren't available. |\\n\\n## Language\\n\\n- File: `spec/schemas/language.schema.json`\\n- Schema id: `https://openpresentation.org/schema/opf-language/v1`\\n- Type: `object`\\n- Required fields: `$schema`, `id`, `name`, `bcp47`\\n- Purpose: Schema for language records in the pptx.gallery library. Each record names a presentation language, carries a BCP-47 language tag, and pairs it with sensible default font schemes for PowerPoint and Google Slides output. Languages are referenced from OPF documents via language; the engine resolves the reference against catalogs.languages (inline) catalogs.languages.source the default catalog at https://www.pptx.gallery/languages. The presentation language field also accepts BCP-47 tags directl...\\n\\n| Field | Required | Type | Notes |\\n| --- | --- | --- | --- |\\n| `$schema` | yes | `const:\\\"https://openpresentation.org/schema/opf-language/v1\\\"` | Identifies this record as a language in the openpresentation.org catalog. |\\n| `id` | yes | `string` | Stable slug used by OPF documents to reference this language via language. Lowercase kebab-case. |\\n| `name` | yes | `string` | Human-readable language name. |\\n| `code` | no | `string` | ISO 639-3 (or 639-2) three-letter language code. Carried for engines that prefer ISO codes. |\\n| `bcp47` | yes | `string` | BCP-47 language tag for this record. Use 'en-GB' for UK English; 'en-UK' is not a valid BCP-47 region form. |\\n| `direction` | no | `enum:ltr \\\\| rtl` | Base text direction for the language. |\\n| `script` | no | `string` | ISO 15924 script code when the writing system should be explicit. |\\n| `fontScheme` | no | `string` | Default font-scheme id for this language when targeting PowerPoint output. Resolves against catalogs.fontSchemes the same way design.fontScheme or design.fontScheme.id does. |\\n| `googleFontScheme` | no | `string` | Default font-scheme id for this language when targeting Google Slides output. Resolves against catalogs.fontSchemes the same way design.fontScheme or design.fontScheme.id does. |\\n| `summary` | no | `string` | One-sentence note about coverage or font defaults. |\\n| `description` | no | `string` | Longer prose describing the language record and any font-pairing rationale. |\\n| `tags` | no | `array<string>` | Free-form labels for filtering and search. |\\n| `preview` | no | `object` | Visual previews of the record, used by picker UIs and inline rendering. All sub-fields are optional; engines fall back gracefully when previews aren't available. |\\n\\n## Slide Layout\\n\\n- File: `spec/schemas/layout.schema.json`\\n- Schema id: `https://openpresentation.org/schema/opf-layout/v1`\\n- Type: `object`\\n- Required fields: `$schema`, `id`, `name`\\n- Purpose: Schema for slide-layout records in the pptx.gallery library. Each record describes a semantic slide layout what regions it exposes and what content kinds those regions are intended to hold. Layouts are referenced from OPF documents via Slide.layout; the engine resolves the reference against catalogs.layouts (inline) catalogs.layouts.source the default catalog at https://www.pptx.gallery/layouts. Free-form custom layout names that don't resolve through any catalog fall through to engine-define...\\n\\n| Field | Required | Type | Notes |\\n| --- | --- | --- | --- |\\n| `$schema` | yes | `const:\\\"https://openpresentation.org/schema/opf-layout/v1\\\"` | Identifies this record as a slide layout in the openpresentation.org catalog. |\\n| `id` | yes | `string` | Stable slug used by OPF documents to reference this layout via Slide.layout. Lowercase kebab-case. |\\n| `name` | yes | `string` | Human-readable layout name shown in layout pickers. |\\n| `summary` | no | `string` | One-sentence positioning of the layout when to reach for it. |\\n| `description` | no | `string` | Longer prose describing the layout structure and ideal use cases. |\\n| `contentType` | no | `enum:Title \\\\| Text \\\\| List \\\\| Image \\\\| Number \\\\| Chart` | Primary kind of content the layout holds. Drives pickers and AI placement decisions. |\\n| `contentMultiple` | no | `enum:None \\\\| 1x \\\\| 2x \\\\| 3x \\\\| 4x \\\\| 5x \\\\| 6x` | How many parallel content blocks the layout exposes ('2x' = two-column, '3x' = three-up, etc.). |\\n| `contentAlignment` | no | `enum:None \\\\| Left \\\\| Center` | Default horizontal alignment of the content area. |\\n| `contentBox` | no | `boolean` | Whether the content area is rendered inside a visible box / card. |\\n| `contentTypeChartPrimary` | no | `enum:None \\\\| Top \\\\| Bottom \\\\| Left \\\\| Right` | For chart layouts, where the primary chart sits relative to the rest of the content. |\\n| `contentTypeImageFill` | no | `enum:None \\\\| Crop \\\\| Fit` | For image layouts, how the image fills its slot. |\\n| `contentTypeListBullet` | no | `enum:None \\\\| Character \\\\| Image` | For list layouts, how bullets are rendered. |\\n| `contentTypeListHeading` | no | `boolean` | For list layouts, whether each list item carries a heading. |\\n| `slideTag` | no | `boolean` | Whether the layout includes a small slide-level tag / label region above or near the title. |\\n| `slideTitle` | no | `boolean` | Whether the layout includes a slide title region. |\\n| `slideSubtitle` | no | `boolean` | Whether the layout includes a slide-level subtitle or supporting-description region. When placeholders is present, this is true exactly when the layout exposes a placeholder with type 'subtitle'. |\\n| `slideTitleAlignment` | no | `enum:None \\\\| Left \\\\| Center` | Horizontal alignment of the slide title region. |\\n| `slideImage` | no | `boolean` | Whether the layout includes a dedicated slide-level image region (separate from any content image). |\\n| `slideImageAlignment` | no | `enum:None \\\\| Top \\\\| Bottom \\\\| Left \\\\| Right \\\\| Background` | Where the slide-level image sits relative to the content. |\\n| `slideLayoutDirection` | no | `enum:None \\\\| Horizontal \\\\| Vertical` | Axis along which the layout's primary regions are arranged. |\\n| `placeholders` | no | `array<ref:Placeholder>` | Ordered regions the layout exposes. The engine fills 'title', 'subtitle', and 'tag' placeholders from Slide.title, Slide.subtitle, and Slide.tag. Other placeholders are content-kind hints for renderers and pickers. Sl... |\\n| `tags` | no | `array<string>` | Free-form labels for filtering and search. |\\n| `preview` | no | `object` | Visual previews of the record, used by picker UIs and inline rendering. All sub-fields are optional; engines fall back gracefully when previews aren't available. |\\n\\n### Nested Types\\n\\n#### Placeholder\\n\\n- Type: `object`\\n- Required fields: `type`\\n- Purpose: A single region inside a slide layout. Title, subtitle, and tag placeholders bind to the corresponding Slide fields; other placeholders describe the intended content kind for that region. The array order in the surrounding 'placeholders' field preserves layout region order.\\n\\n| Field | Required | Type | Notes |\\n| --- | --- | --- | --- |\\n| `type` | yes | `enum:title \\\\| subtitle \\\\| tag \\\\| text \\\\| list \\\\| chart \\\\| picture \\\\| table \\\\| media \\\\| diagram \\\\| code` | OPF placeholder kind. 'text' and 'list' are flexible textual content regions. The named kinds describe a specific content role used by pickers, AI generation, and engine defaulting. |\\n\\n## Narrative Template\\n\\n- File: `spec/schemas/narrative.schema.json`\\n- Schema id: `https://openpresentation.org/schema/opf-narrative/v1`\\n- Type: `object`\\n- Required fields: `$schema`, `id`, `name`, `beats`\\n- Purpose: Schema for narrative template files in the openpresentation.org catalog. Each template describes a named story arc (e.g. 'problem-solution', 'scqa') as an ordered list of beats. Templates are referenced from OPF documents via narrative either as a bare id string (e.g. 'classic-story') or as an inline object whose shape matches this schema (sans '$schema').\\n\\n| Field | Required | Type | Notes |\\n| --- | --- | --- | --- |\\n| `$schema` | yes | `const:\\\"https://openpresentation.org/schema/opf-narrative/v1\\\"` |  |\\n| `id` | yes | `string` | Stable slug used by OPF documents to reference this template, e.g. 'problem-solution'. Lowercase kebab-case. |\\n| `name` | yes | `string` | Human-readable template name, e.g. 'Problem Solution'. |\\n| `summary` | no | `string` | One-sentence description of when and why to use this narrative. |\\n| `description` | no | `string` | Longer prose describing the narrative arc and ideal use cases. Used by AI-driven generation to seed deck-level direction. |\\n| `audienceFit` | no | `array<string>` | Audiences this narrative works well for, e.g. ['executives', 'investors', 'customers']. |\\n| `durationRange` | no | `object` | Typical talk-length window this narrative suits. |\\n| `tags` | no | `array<string>` | Free-form labels for filtering and search, e.g. ['business', 'pitch', 'internal']. |\\n| `preview` | no | `object` | Visual previews of the record, used by picker UIs and inline rendering. All sub-fields are optional; engines fall back gracefully when previews aren't available. |\\n| `beats` | yes | `array<ref:Beat>` | Ordered list of beats that make up the narrative arc. |\\n\\n### Nested Types\\n\\n#### Beat\\n\\n- Type: `object`\\n- Required fields: `id`, `name`\\n- Purpose: A single narrative beat a labeled segment of the story arc with a specific dramatic purpose. Mirrors the NarrativeBeat definition in opf.schema.json so library entries and inline OPF beats are interchangeable.\\n\\n| Field | Required | Type | Notes |\\n| --- | --- | --- | --- |\\n| `id` | yes | `string` | Stable slug used by Slide.beat to reference this beat. Lowercase kebab-case. |\\n| `name` | yes | `string` | Human-readable beat name, e.g. 'The Problem'. |\\n| `description` | no | `string` | Curator-written prose that explains what this beat should accomplish. |\\n| `instructions` | no | `string` | Short author-facing instruction for the beat typically one phrase. Complements 'description' with a concise directive. |\\n| `slideCount` | no | `integer` | Optional explicit slide count for this beat. Defaults to 1 when omitted; values >1 are reserved for beats that intentionally span multiple slides. Prefer decomposing a heavy beat into multiple beats over setting a hig... |\\n| `slideType` | no | `enum:text \\\\| list \\\\| image \\\\| shape \\\\| chart \\\\| table \\\\| video \\\\| code \\\\| metric \\\\| quote \\\\| timeline` | Default content kind for the beat's slide. Mirrors ContentPayload.type and helps engines choose a sensible layout when only the beat is specified. |\\n| `layoutHint` | no | `string` | Suggested layout id for the beat's opening slide, e.g. 'section-divider', 'title-slide', 'text-left'. Resolves the same way as Slide.layout against catalogs.layouts and the default catalog at https://www.pptx.gallery/... |\\n| `thoughtCues` | no | `array<string>` | Optional speaker or thinking cues attached to the beat. Surfaced in presenter notes. |\\n\\n## Purpose\\n\\n- File: `spec/schemas/purpose.schema.json`\\n- Schema id: `https://openpresentation.org/schema/opf-purpose/v1`\\n- Type: `object`\\n- Required fields: `$schema`, `id`, `name`\\n- Purpose: Schema for purpose records in the pptx.gallery library. Each record names a presentation objective such as informing, aligning, persuading, driving a decision, or selling. Purposes are referenced from OPF documents via purpose; the engine resolves the reference against catalogs.purposes (inline) catalogs.purposes.source the default catalog at https://www.pptx.gallery/purposes. The purpose field also accepts free-form strings and inline Purpose objects.\\n\\n| Field | Required | Type | Notes |\\n| --- | --- | --- | --- |\\n| `$schema` | yes | `const:\\\"https://openpresentation.org/schema/opf-purpose/v1\\\"` | Identifies this record as a purpose in the openpresentation.org catalog. |\\n| `id` | yes | `string` | Stable slug used by OPF documents to reference this purpose via purpose. Lowercase kebab-case. |\\n| `name` | yes | `string` | Human-readable purpose name shown in pickers. |\\n| `summary` | no | `string` | One-sentence positioning of the purpose what this deck is trying to accomplish. |\\n| `description` | no | `string` | Longer prose describing when to use this purpose and how it should shape a deck. |\\n| `outcome` | no | `string` | Desired audience outcome after the presentation. |\\n| `successCriteria` | no | `array<string>` | Observable signals that the deck accomplished this purpose. |\\n| `recommendedNarratives` | no | `array<string>` | Soft cross-link: narrative-catalog ids that work well for this purpose. |\\n| `recommendedTones` | no | `array<string>` | Soft cross-link: tone-catalog ids that work well for this purpose. |\\n| `tags` | no | `array<string>` | Free-form labels for filtering and search. |\\n| `preview` | no | `object` | Visual previews of the record, used by picker UIs and inline rendering. All sub-fields are optional. |\\n\\n## Social Platform\\n\\n- File: `spec/schemas/social-platform.schema.json`\\n- Schema id: `https://openpresentation.org/schema/opf-social-platform/v1`\\n- Type: `object`\\n- Required fields: `$schema`, `id`, `name`\\n- Purpose: Schema for social-platform records in the pptx.gallery library. Each record describes a single social-media platform its base URL, profile-URL pattern, handle prefix, brand color, and themed icons. Records are referenced from OPF documents indirectly: the property keys of any Socials object (Organization.socials, Speaker.socials) match record ids, and renderers use the catalog record to format URLs and pick icons. The engine resolves references against catalogs.socialPlatforms (inline) catalo...\\n\\n| Field | Required | Type | Notes |\\n| --- | --- | --- | --- |\\n| `$schema` | yes | `const:\\\"https://openpresentation.org/schema/opf-social-platform/v1\\\"` | Identifies this record as a social-platform entry in the openpresentation.org catalog. |\\n| `id` | yes | `string` | Stable slug used by OPF documents to reference this platform appears as a property key on Socials objects. Lowercase kebab-case. |\\n| `name` | yes | `string` | Human-readable platform name shown in pickers and footers. |\\n| `summary` | no | `string` | One-sentence positioning of the platform what it's used for and who's on it. |\\n| `description` | no | `string` | Longer prose describing the platform and any rendering conventions (e.g., handle prefixes, distributed instances). |\\n| `baseUrl` | no | `string` | Canonical base URL of the platform used as the prefix when normalizing handles to full URLs. |\\n| `profileUrlPattern` | no | `string` | URL pattern for individual member profiles. Use '{handle}' as the placeholder for the handle (with the prefix already stripped). |\\n| `companyUrlPattern` | no | `string` | Optional URL pattern for organization / company pages, when the platform distinguishes them from member profiles. Use '{handle}' as the placeholder. |\\n| `handlePrefix` | no | `string` | Conventional prefix character displayed before the handle (e.g. '@' for X / Mastodon / Threads / TikTok). Empty string when no prefix is used. Renderers strip it before substituting into URL patterns. |\\n| `handleExample` | no | `string` | Example handle in its conventional rendered form, used by picker UIs and validation hints. |\\n| `brandColor` | no | `string` | Brand color (hex) used for branded icon chips, link styling, or section accents. |\\n| `icon` | no | `string` | Default icon source. Accepts an HTTPS URL, data URI, relative path, or asset reference. Used as the fallback when a themed (Light/Dark) variant isn't set. |\\n| `iconLight` | no | `string` | Light-colored icon variant intended for rendering on dark backgrounds. |\\n| `iconDark` | no | `string` | Dark-colored icon variant intended for rendering on light backgrounds. |\\n| `tags` | no | `array<string>` | Free-form labels for filtering and search. |\\n| `preview` | no | `object` | Visual previews of the record, used by picker UIs and inline rendering. All sub-fields are optional; engines fall back gracefully when previews aren't available. |\\n\\n## Theme\\n\\n- File: `spec/schemas/theme.schema.json`\\n- Schema id: `https://openpresentation.org/schema/opf-theme/v1`\\n- Type: `object`\\n- Required fields: `$schema`, `id`, `name`\\n- Purpose: Schema for theme records in the pptx.gallery library. Each theme is a small, named bundle that pairs a color scheme, a font scheme, a default theme-controlled background, and a slide size. Themes are referenced from OPF documents via design.theme or design.theme.id; the engine resolves the reference against catalogs.themes (inline) catalogs.themes.source the default catalog at https://www.pptx.gallery/themes. Inline overrides on design.colorScheme / design.fontScheme / design.background / des...\\n\\n| Field | Required | Type | Notes |\\n| --- | --- | --- | --- |\\n| `$schema` | yes | `const:\\\"https://openpresentation.org/schema/opf-theme/v1\\\"` | Identifies this record as a theme in the openpresentation.org catalog. |\\n| `id` | yes | `string` | Stable slug used by OPF documents to reference this theme via design.theme. Lowercase kebab-case. |\\n| `name` | yes | `string` | Human-readable theme name shown in pickers. |\\n| `summary` | no | `string` | One-sentence positioning of the theme when to reach for it. |\\n| `description` | no | `string` | Longer prose describing what the theme looks and feels like and the kinds of decks it suits. |\\n| `colorScheme` | no | `string` | Catalog reference to the theme's default color scheme resolved against catalogs.colorSchemes the same way design.colorScheme or design.colorScheme.id is. Accepts a bare id, HTTPS URL, or 'pkg:' reference. |\\n| `fontScheme` | no | `string` | Catalog reference to the theme's default font scheme resolved against catalogs.fontSchemes the same way design.fontScheme or design.fontScheme.id is. Accepts a bare id, HTTPS URL, or 'pkg:' reference. |\\n| `background` | no | `ref:ThemeBackground` |  |\\n| `dimensions` | no | `enum:16:9 \\\\| 4:3 \\\\| 16:10 \\\\| letter \\\\| a4 \\\\| widescreen \\\\| standard` | Default slide size for this theme. Accepts the same preset values as design.dimensions.preset. |\\n| `tags` | no | `array<string>` | Free-form labels for filtering and search. |\\n| `preview` | no | `object` | Visual previews of the record, used by picker UIs and inline rendering. All sub-fields are optional; engines fall back gracefully when previews aren't available. |\\n\\n### Nested Types\\n\\n#### ThemeBackgroundSlot\\n\\n- Type: `enum:light1 | light2 | dark1 | dark2`\\n- Required fields: none\\n- Purpose: PowerPoint theme-controlled slide background slot from the active color scheme. These are slots, not assumptions about actual colors: light1 is usually white and dark1 is usually black by convention, but the color scheme controls the real values.\\n\\n_No named properties._\\n\\n#### ThemeBackground\\n\\n- Type: `object`\\n- Required fields: `type`, `slot`\\n- Purpose: Theme-controlled PowerPoint slide background. The slot is resolved through the active color scheme and remains theme-aware.\\n\\n| Field | Required | Type | Notes |\\n| --- | --- | --- | --- |\\n| `type` | yes | `const:\\\"theme\\\"` | Theme-controlled background fill. |\\n| `slot` | yes | `ref:ThemeBackgroundSlot` |  |\\n\\n## Tone\\n\\n- File: `spec/schemas/tone.schema.json`\\n- Schema id: `https://openpresentation.org/schema/opf-tone/v1`\\n- Type: `object`\\n- Required fields: `$schema`, `id`, `name`\\n- Purpose: Schema for tone records in the pptx.gallery library. Each record names a presentation tone (e.g. 'formal', 'casual', 'inspirational') and carries voice cues, anti-patterns, and sample phrases that AI-driven generation uses to shape output. Tones are referenced from OPF documents via tone; the engine resolves the reference against catalogs.tones (inline) catalogs.tones.source the default catalog at https://www.pptx.gallery/tones.\\n\\n| Field | Required | Type | Notes |\\n| --- | --- | --- | --- |\\n| `$schema` | yes | `const:\\\"https://openpresentation.org/schema/opf-tone/v1\\\"` | Identifies this record as a tone in the openpresentation.org catalog. |\\n| `id` | yes | `string` | Stable slug used by OPF documents to reference this tone via tone. Lowercase kebab-case. |\\n| `name` | yes | `string` | Human-readable tone name shown in pickers. |\\n| `summary` | no | `string` | One-sentence positioning of the tone when to reach for it. |\\n| `description` | no | `string` | Longer prose describing the tone and the kinds of decks it suits. |\\n| `voiceCues` | no | `array<string>` | Short directives that shape AI generation toward this tone. Phrased as imperatives, e.g. 'use second-person', 'favor short sentences', 'lead with the recommendation'. |\\n| `avoid` | no | `array<string>` | Anti-patterns that AI generation should not produce when this tone is active. |\\n| `samplePhrases` | no | `array<string>` | Short example phrases that exemplify this tone. Used by picker UIs and as few-shot examples for AI generation. |\\n| `recommendedNarratives` | no | `array<string>` | Soft cross-link: narrative-catalog ids this tone pairs well with. Used by picker UIs to suggest narratives once a tone is chosen. Validators warn on unknown ids; never error. |\\n| `tags` | no | `array<string>` | Free-form labels for filtering and search. |\\n| `preview` | no | `object` | Visual previews of the record, used by picker UIs and inline rendering. All sub-fields are optional. |\\n\"\n  },\n  {\n    \"slug\": \"content-item-design-overrides\",\n    \"file\": \"docs/content-item-design-overrides.md\",\n    \"title\": \"Possible Content Payload Design\",\n    \"markdown\": \"# Possible Content Payload Design\\n\\nThis is a parking-lot note for design controls intentionally removed from slide content payloads while the v1 content model stabilizes.\\n\\nCurrent principle: root slide payload fields and promoted region payloads should describe what the slide contains. Layout and rendering decide how it looks. If per-payload styling returns later, it should live in an explicit override surface rather than mixing presentation controls into the base content payload.\\n\\n## Possible Shape\\n\\n```jsonc\\n{\\n  \\\"title\\\": \\\"Revenue\\\",\\n  \\\"left\\\": {\\n    \\\"text\\\": \\\"Revenue grew 28%\\\",\\n    \\\"design\\\": {\\n      \\\"text\\\": {\\n        \\\"alignment\\\": \\\"center\\\"\\n      }\\n    }\\n  }\\n}\\n```\\n\\nOpen question: whether overrides belong inline on each content payload, in `slides[].design`, or in a reusable style catalog keyed by region key or payload `type`.\\n\\n## Deferred Fields\\n\\nThese fields were deliberately kept out of `ContentPayload` for now:\\n\\n| Area | Candidate fields |\\n| --- | --- |\\n| Placement | `position`, `size`, `zIndex`, `rotation` |\\n| Text | `style`, `fontSize`, `fontFamily`, `color`, `alignment`, `lineHeight`, `textTransform`, `verticalAlignment` |\\n| Image/media | `fit`, `borderRadius`, `shadow`, `opacity`, `crop`, `focalPoint` |\\n| Chart | `chartPreset`, `options`, `legend`, `showValues`, `showGrid`, `stacked`, `xAxis`, `yAxis`, palette overrides |\\n| Table | `tableStyle`, `stripedRows`, `compact`, border colors, header colors |\\n| Shape | `fill`, `stroke`, `cornerRadius`, `path` |\\n| Code | `theme`, `showLineNumbers`, syntax-highlighting theme |\\n\\n## Decision Criteria\\n\\nBring these back only when there is a concrete renderer or authoring workflow that needs them. Prefer small, typed override objects over a large flat bag of visual fields on every content payload.\\n\"\n  },\n  {\n    \"slug\": \"content-payloads\",\n    \"file\": \"docs/content-payloads.md\",\n    \"title\": \"Content Payloads\",\n    \"markdown\": \"# Content Payloads\\n\\nSlide content lives directly on a slide as a full-slide payload, in layout-agnostic `blocks`, or inside a promoted region key such as `left`, `center+right`, or `top:left`.\\n\\nThe optional payload `type` can make intent explicit, but OPF should usually infer the content kind from the field present:\\n\\n| Field | Inferred type | Notes |\\n| --- | --- | --- |\\n| `text` | `text` | Plain string or `TextRun[]`. |\\n| `bullets` | `text` | Simple text bullets, usually `string[]`. |\\n| `items` | `list` | Generic list payload, usually `string[]` or `ListItem[]`. |\\n| `image` | `image` | Asset string shorthand or `Asset` object with `src` and optional metadata. |\\n| `video` | `video` | Asset string shorthand or `Asset` object with `src` and optional metadata. |\\n| `chart` | `chart` | Chart object with `type` and tabular `data`. |\\n| `table` | `table` | Table object with optional `columns` and required `rows`. |\\n| `code` | `code` | String shorthand or `Code` object with `source`, `language`, and `filename`. |\\n| `metric` | `metric` | String/number shorthand or `Metric` object with `value`, `label`, `description`, `unit`, `delta`, and `trend`. |\\n| `quote` | `quote` | String shorthand or `Quote` object with `text`, `attribution`, and `source`. |\\n| `timeline` | `timeline` | Array shorthand or `Timeline` object with `name`, `description`, and `events`. |\\n\\n## Blocks\\n\\nUse slide-level `blocks` when a slide contains multiple content payloads, but exact placement should be inferred by the renderer. Blocks are not recursive; each block is a concrete content payload.\\n\\n```json\\n{\\n  \\\"title\\\": \\\"Customer Feedback Summary\\\",\\n  \\\"blocks\\\": [\\n    {\\n      \\\"table\\\": {\\n        \\\"columns\\\": [\\\"Theme\\\", \\\"Mentions\\\"],\\n        \\\"rows\\\": [\\n          [\\\"Speed\\\", 42],\\n          [\\\"Ease of use\\\", 31]\\n        ]\\n      }\\n    },\\n    {\\n      \\\"quote\\\": {\\n        \\\"text\\\": \\\"The new workflow cut review time in half.\\\",\\n        \\\"attribution\\\": \\\"Operations Lead\\\",\\n        \\\"source\\\": \\\"Customer interview\\\"\\n      }\\n    }\\n  ]\\n}\\n```\\n\\nAt slide root only, multiple content payload kinds are accepted as shorthand for the equivalent blocks form when there is no explicit `type`, no `blocks`, and no promoted region keys:\\n\\n```json\\n{\\n  \\\"title\\\": \\\"Habitat & Territory\\\",\\n  \\\"text\\\": \\\"Jaguars are strongly associated with presence of water and dense cover.\\\",\\n  \\\"items\\\": [\\n    \\\"Primary habitats include dense rainforests, swamps, and seasonally flooded wetlands.\\\",\\n    \\\"Solitary animals that establish and defend large territories.\\\"\\n  ]\\n}\\n```\\n\\nThe same shorthand works for other content kinds:\\n\\n```json\\n{\\n  \\\"title\\\": \\\"Evidence Snapshot\\\",\\n  \\\"chart\\\": {\\n    \\\"type\\\": \\\"line\\\",\\n    \\\"data\\\": {\\n      \\\"columns\\\": [\\\"Quarter\\\", \\\"Sightings\\\"],\\n      \\\"rows\\\": [\\n        [\\\"Q1\\\", 12],\\n        [\\\"Q2\\\", 18]\\n      ]\\n    }\\n  },\\n  \\\"quote\\\": {\\n    \\\"text\\\": \\\"Jaguar conservation depends on connected habitat.\\\",\\n    \\\"attribution\\\": \\\"Field researcher\\\"\\n  }\\n}\\n```\\n\\n## Chart\\n\\nChart-specific fields are grouped under `chart`. Do not put loose chart data directly on a slide or region.\\n\\n```json\\n{\\n  \\\"title\\\": \\\"Revenue Trend\\\",\\n  \\\"chart\\\": {\\n    \\\"type\\\": \\\"line\\\",\\n    \\\"data\\\": {\\n      \\\"columns\\\": [\\\"Quarter\\\", \\\"Revenue\\\", \\\"Costs\\\"],\\n      \\\"rows\\\": [\\n        [\\\"Q1\\\", 12, 8],\\n        [\\\"Q2\\\", 18, 11],\\n        [\\\"Q3\\\", 24, 15]\\n      ]\\n    }\\n  }\\n}\\n```\\n\\nInline chart data is tabular by default. Renderers convert `columns` and `rows` into series, axes, legends, and workbook data internally.\\n\\nAsset-backed data is still table-oriented:\\n\\n```json\\n{\\n  \\\"chart\\\": {\\n    \\\"type\\\": \\\"column\\\",\\n    \\\"data\\\": {\\n      \\\"src\\\": \\\"asset:revenue-csv\\\",\\n      \\\"columns\\\": [\\\"Quarter\\\", \\\"Revenue\\\"]\\n    }\\n  }\\n}\\n```\\n\\n## Table\\n\\nTable-specific fields are grouped under `table`. Do not put loose `columns` or `rows` directly on a slide or region.\\n\\n```json\\n{\\n  \\\"title\\\": \\\"Pipeline\\\",\\n  \\\"table\\\": {\\n    \\\"columns\\\": [\\\"Stage\\\", \\\"Count\\\", \\\"Value\\\"],\\n    \\\"rows\\\": [\\n      [\\\"Qualified\\\", 42, \\\"$1.2M\\\"],\\n      [\\\"Proposal\\\", 18, \\\"$840K\\\"]\\n    ]\\n  }\\n}\\n```\\n\\n## Code\\n\\nCode-specific fields are grouped under `code`. A string value is shorthand for `code.source`; use object form when syntax highlighting or a file label matters. In object form, `source` is required.\\n\\n```json\\n{\\n  \\\"title\\\": \\\"Decision Rule\\\",\\n  \\\"code\\\": {\\n    \\\"source\\\": \\\"if risk > threshold:\\\\n    escalate(owner)\\\\nelse:\\\\n    approve(change)\\\",\\n    \\\"language\\\": \\\"python\\\",\\n    \\\"filename\\\": \\\"decision.py\\\"\\n  }\\n}\\n```\\n\\n## Metric\\n\\nMetric-specific fields are grouped under `metric`. A string or number value is shorthand for `metric.value`; numeric values stay numeric and are formatted by renderers at display time. Use object form when labels, descriptions, units, deltas, or trends matter.\\n\\n```json\\n{\\n  \\\"title\\\": \\\"Operating Metric\\\",\\n  \\\"metric\\\": {\\n    \\\"value\\\": \\\"42%\\\",\\n    \\\"label\\\": \\\"Review cycle reduction\\\",\\n    \\\"description\\\": \\\"Median reduction across customer review workflows.\\\",\\n    \\\"delta\\\": \\\"+11 pts\\\",\\n    \\\"trend\\\": \\\"up\\\"\\n  }\\n}\\n```\\n\\n## Quote\\n\\nQuote-specific fields are grouped under `quote`. A string value is shorthand for `quote.text`; use object form when attribution or citation matters.\\n\\n```json\\n{\\n  \\\"title\\\": \\\"Customer Proof\\\",\\n  \\\"quote\\\": {\\n    \\\"text\\\": \\\"The new workflow made exceptions visible before they became escalations.\\\",\\n    \\\"attribution\\\": \\\"VP Operations, Acme Corp\\\",\\n    \\\"source\\\": \\\"Customer interview\\\"\\n  }\\n}\\n```\\n\\n## Timeline\\n\\nTimeline-specific fields are grouped under `timeline`. An array value is shorthand for `timeline.events`; use object form when the timeline needs a name or description. Timeline events use `when`, `what`, and `description`.\\n\\n```json\\n{\\n  \\\"title\\\": \\\"Rollout Plan\\\",\\n  \\\"timeline\\\": {\\n    \\\"name\\\": \\\"Regional Rollout\\\",\\n    \\\"description\\\": \\\"Major milestones for the rollout.\\\",\\n    \\\"events\\\": [\\n      {\\n        \\\"when\\\": \\\"Q1\\\",\\n        \\\"what\\\": \\\"Pilot\\\",\\n        \\\"description\\\": \\\"Launch with one operations team.\\\"\\n      },\\n      {\\n        \\\"when\\\": \\\"Q2\\\",\\n        \\\"what\\\": \\\"Rollout\\\",\\n        \\\"description\\\": \\\"Expand to all regions.\\\"\\n      }\\n    ]\\n  }\\n}\\n```\\n\\n## Regions\\n\\nRegion keys address a 3×3 grid of rows (`top`, `middle`, `bottom`) and columns (`left`, `center`, `right`):\\n\\n```\\n                  left                 center                 right\\n         +--------------------+--------------------+--------------------+\\n   top   |  top:left          |  top:center        |  top:right         |\\n         +--------------------+--------------------+--------------------+\\n  middle |  middle:left       |  middle:center     |  middle:right      |\\n         +--------------------+--------------------+--------------------+\\n  bottom |  bottom:left       |  bottom:center     |  bottom:right      |\\n         +--------------------+--------------------+--------------------+\\n```\\n\\n- A bare column key (`left`) spans all three rows; a bare row key (`top`) spans all three columns.\\n- `+` spans adjacent rows or columns: `center+right`, `top+middle`.\\n- `row:column` combines the two: `top:left`, `middle+bottom:center+right`.\\n- Keys on one slide must not overlap, and regions cannot be mixed with root payload fields.\\n\\nSpans compose into common slide shapes:\\n\\n```\\n  \\\"left\\\" + \\\"center+right\\\"             \\\"top\\\" + \\\"middle+bottom\\\"\\n  (sidebar + main)                    (headline band + body)\\n  +----------+------------------+     +-------------------------------+\\n  |          |                  |     |              top              |\\n  |          |                  |     +-------------------------------+\\n  |   left   |  center+right    |     |                               |\\n  |          |                  |     |         middle+bottom         |\\n  |          |                  |     |                               |\\n  +----------+------------------+     +-------------------------------+\\n\\n  \\\"top\\\" + \\\"middle+bottom:left\\\" + \\\"middle+bottom:center+right\\\"\\n  (headline band, then sidebar + main)\\n  +---------------------------------------------+\\n  |                     top                     |\\n  +---------------+-----------------------------+\\n  |               |                             |\\n  | middle+bottom | middle+bottom:center+right  |\\n  | :left         |                             |\\n  |               |                             |\\n  +---------------+-----------------------------+\\n```\\n\\nThe same payload objects work inside regions — here, the sidebar-plus-main shape:\\n\\n```json\\n{\\n  \\\"title\\\": \\\"Operating Snapshot\\\",\\n  \\\"left\\\": {\\n    \\\"table\\\": {\\n      \\\"columns\\\": [\\\"Metric\\\", \\\"Value\\\"],\\n      \\\"rows\\\": [\\n        [\\\"Revenue\\\", \\\"$4.2M\\\"],\\n        [\\\"Gross margin\\\", \\\"68%\\\"]\\n      ]\\n    }\\n  },\\n  \\\"center+right\\\": {\\n    \\\"chart\\\": {\\n      \\\"type\\\": \\\"line\\\",\\n      \\\"data\\\": {\\n        \\\"columns\\\": [\\\"Month\\\", \\\"Revenue\\\"],\\n        \\\"rows\\\": [\\n          [\\\"Jan\\\", 3.4],\\n          [\\\"Feb\\\", 3.8],\\n          [\\\"Mar\\\", 4.2]\\n        ]\\n      }\\n    }\\n  }\\n}\\n```\\n\"\n  },\n  {\n    \"slug\": \"design-resolution\",\n    \"file\": \"docs/design-resolution.md\",\n    \"title\": \"Design Resolution\",\n    \"markdown\": \"# Design Resolution\\n\\nHow an engine decides the effective design for any given slide. The schema spreads these rules across field descriptions; this page states them once, as an algorithm.\\n\\n## Precedence\\n\\nFor every design field independently, the most specific source wins:\\n\\n```\\n  wins   +--------------------------------------------------------+\\n    ^    | 1. slide design     slides[i].design.*                 |\\n    |    +--------------------------------------------------------+\\n    |    | 2. deck design      design.* on the presentation root  |\\n    |    +--------------------------------------------------------+\\n    |    | 3. resolved theme   colorScheme, fontScheme,            |\\n    |    |                     background, dimensions from the     |\\n    |    |                     theme record                        |\\n    |    +--------------------------------------------------------+\\n  loses  | 4. engine defaults  e.g. spec/reference/                |\\n    v    |                     engine-defaults.json                |\\n         +--------------------------------------------------------+\\n```\\n\\n1. **Slide design** — `slides[].design.*`\\n2. **Deck design** — `design.*` on the presentation root\\n3. **Resolved theme** — defaults carried by the theme record (`colorScheme`, `fontScheme`, `background`, `dimensions`)\\n4. **Engine defaults** — engine configuration such as [`spec/reference/engine-defaults.json`](../spec/reference/engine-defaults.json)\\n\\nResolution is **per field**, not per object. A slide that sets only `design.contentAlignment` inherits everything else from the deck design; a deck that sets only `design.colorScheme` keeps the theme's font scheme and background.\\n\\nTwo field-level rules complete the picture:\\n\\n- **Base-plus-overrides within one object.** Wherever a reference object carries an `id` (`Theme`, `ColorScheme`, `FontScheme`), the `id` resolves a catalog record as the base and sibling fields override the resolved record per key. The string shorthand (`\\\"colorScheme\\\": \\\"cool-horizon\\\"`) is equivalent to setting only `id`.\\n\\n  ```\\n  \\\"colorScheme\\\": { \\\"id\\\": \\\"cool-horizon\\\", \\\"accent1\\\": \\\"#0F4C81\\\" }\\n\\n     catalog record \\\"cool-horizon\\\"        sibling fields on the object\\n     accent1: \\\"#2874A6\\\"   <-- replaced -- accent1: \\\"#0F4C81\\\"\\n     accent2: \\\"#1B4F72\\\"   <-- kept\\n     light1:  \\\"#FFFFFF\\\"   <-- kept\\n                  |\\n                  v\\n     effective scheme: accent1 from the override, everything else\\n     from the record\\n  ```\\n- **Explicit suppression.** `watermark`, `header`, and `footer` accept `false` to switch off an inherited value — distinct from omitting the field, which inherits.\\n\\nCatalog lookups inside this chain follow the standard resolution order (inline `catalogs.<kind>.records[]` → `catalogs.<kind>.source` → default catalog); see [`how-opf-works.md`](./how-opf-works.md).\\n\\n## Worked example 1: color scheme through every level\\n\\n```json\\n{\\n  \\\"design\\\": {\\n    \\\"theme\\\": \\\"classic\\\",\\n    \\\"colorScheme\\\": \\\"forest-green\\\"\\n  },\\n  \\\"slides\\\": [\\n    { \\\"title\\\": \\\"Inherits the deck\\\" },\\n    {\\n      \\\"title\\\": \\\"Slide override\\\",\\n      \\\"design\\\": {\\n        \\\"colorScheme\\\": { \\\"id\\\": \\\"cool-horizon\\\", \\\"accent1\\\": \\\"#0F4C81\\\" }\\n      }\\n    }\\n  ]\\n}\\n```\\n\\n- Slide 1: the `classic` theme record supplies its own default color scheme, but the deck design sets `colorScheme` explicitly, so `forest-green` wins (level 2 beats level 3). Fonts, background, and dimensions still come from `classic`.\\n- Slide 2: slide design beats deck design (level 1 beats level 2). The `cool-horizon` record resolves as the base, then `accent1` is replaced by `#0F4C81`. All other `cool-horizon` slots survive.\\n\\nThere is no ambiguity between \\\"override\\\" and \\\"reference\\\": every scheme value *is* a reference, and any sibling fields on the same object are overrides applied after the reference resolves.\\n\\n## Worked example 2: backgrounds and suppression\\n\\n```json\\n{\\n  \\\"design\\\": {\\n    \\\"theme\\\": \\\"dark\\\",\\n    \\\"background\\\": \\\"light1\\\",\\n    \\\"footer\\\": {\\n      \\\"left\\\": { \\\"text\\\": \\\"Acme Corp\\\" },\\n      \\\"right\\\": { \\\"slideNumber\\\": true }\\n    }\\n  },\\n  \\\"slides\\\": [\\n    { \\\"title\\\": \\\"Light slide in a dark theme\\\" },\\n    {\\n      \\\"title\\\": \\\"Section divider\\\",\\n      \\\"design\\\": {\\n        \\\"background\\\": {\\n          \\\"type\\\": \\\"gradient\\\",\\n          \\\"gradient\\\": {\\n            \\\"angle\\\": 90,\\n            \\\"stops\\\": [\\n              { \\\"color\\\": \\\"#0B1B2B\\\", \\\"position\\\": 0 },\\n              { \\\"color\\\": \\\"#123A5F\\\", \\\"position\\\": 1 }\\n            ]\\n          }\\n        },\\n        \\\"footer\\\": false\\n      }\\n    }\\n  ]\\n}\\n```\\n\\n- Slide 1: the deck-level `background: \\\"light1\\\"` overrides the `dark` theme's default background. `light1` is a theme slot — it resolves through the effective color scheme, which itself resolved through the chain above.\\n- Slide 2: the gradient replaces the deck background for this slide only, and `footer: false` suppresses the inherited footer rather than inheriting or replacing it.\\n\\n## Worked example 3: font scheme models\\n\\n```json\\n{\\n  \\\"design\\\": {\\n    \\\"fontScheme\\\": {\\n      \\\"id\\\": \\\"aptos\\\",\\n      \\\"code\\\": { \\\"family\\\": \\\"JetBrains Mono\\\" }\\n    }\\n  }\\n}\\n```\\n\\nThe `aptos` record supplies the OOXML pair (`major`/`minor`). The `code` role is an OPF-specific addition with no OOXML slot, so it layers on top without disturbing the pair. When serializing to PowerPoint, engines write `major`/`minor` to `majorFont`/`minorFont` and map abstract roles (`heading`, `body`) onto those slots; roles like `accent` and `code` are renderer concerns. The same slot-versus-role split applies to color schemes: OOXML slots (`accent1`–`accent6`, `dark1/2`, `light1/2`) round-trip directly, abstract roles (`primary`, `text`, `surface`, …) are mapped onto slots by the engine.\\n\\n## What is *not* part of this chain\\n\\nContent payloads carry no design controls in v1 — `position`, `fontSize`, per-payload colors and the like were deliberately kept out while the content model stabilizes (see [`content-item-design-overrides.md`](./content-item-design-overrides.md)). The design system above, plus layout hints (`titleAlignment`, `contentBox`, `chartPrimary`, …), is the entire styling surface of an OPF document.\\n\"\n  },\n  {\n    \"slug\": \"examples\",\n    \"file\": \"docs/examples.md\",\n    \"title\": \"OPF Examples Guide\",\n    \"markdown\": \"# OPF Examples Guide\\n\\nThe `examples/` directory has three layers:\\n\\n- `examples/technical/` contains compact fixtures that isolate one or two schema behaviors.\\n- `examples/gallery/` contains scenario-oriented decks that show OPF working across industries, functions, education, government, international, presentation-type, and design/media use cases.\\n- The examples root is kept as an organizing directory rather than a home for standalone OPF files.\\n\\n## Technical Fixtures\\n\\nStart with [`examples/technical/full-feature-tour.opf.json`](../examples/technical/full-feature-tour.opf.json), one deck that touches every major schema surface — useful as a copy-paste source and as a single fixture for renderer smoke tests.\\n\\nUse `examples/technical/` when you want a small file that exercises a specific schema surface:\\n\\n- content payloads, rich text, blocks, charts, tables, media, metrics, quotes, and timelines\\n- promoted region keys and span combinations\\n- asset string/object forms and asset-backed chart data\\n- design backgrounds, logo sets, headers, footers, watermarks, and slide-level overrides\\n- metadata array forms, language metadata, narrative beats, and catalog overrides\\n\\n## Gallery Folders\\n\\n| Folder | What It Demonstrates |\\n| --- | --- |\\n| `industries/` | Vertical market decks with operating plans, investment briefs, readiness reviews, and launch coordination. |\\n| `business-functions/` | Department-specific decks for sales, marketing, product, engineering, finance, HR, legal, security, support, procurement, and strategy. |\\n| `education/` | K-12, higher education, research, advising, workforce, advancement, and student services scenarios. |\\n| `government/` | Public health, transit, emergency management, utilities, regulators, courts, parks, workforce, tax, and civic engagement decks. |\\n| `presentation-types/` | Reusable deck archetypes such as pitches, board updates, QBRs, conference talks, workshops, postmortems, launches, policy briefings, training, and research reports. |\\n| `international/` | Region- or language-specific decks, including examples of language object metadata and right-to-left direction. |\\n| `design-and-media/` | Decks that emphasize design controls, image/video assets, data storytelling, and self-running orientation patterns. |\\n\\n## Patterns To Look For\\n\\n- Technical fixtures that isolate validator and renderer behavior.\\n- Sparse gallery documents that use shorthand catalog references and a small slide list.\\n- Medium documents with schema ids, metadata, organization and speaker records, design overrides, assets, and richer slide payloads.\\n- Dense documents with inline `catalogs` sources and records, promoted region keys, `blocks`, media assets, code payloads, header/footer configuration, logo sets, watermarks, and extensions.\\n- Mixed content payloads across text, bullets, lists, image, video, chart, table, code, metric, quote, and timeline slides.\\n- Catalog references across narratives, layouts, chart types, themes, color schemes, font schemes, languages, audiences, purposes, tones, and social platforms.\\n\\n## Validation\\n\\nRun the example validator after changing any `*.opf.json` file:\\n\\n```sh\\nnode scripts/validate-examples.mjs\\n```\\n\\nThe script walks every OPF document under `examples/` and reports schema or semantic validation issues with file paths.\\n\"\n  },\n  {\n    \"slug\": \"how-opf-works\",\n    \"file\": \"docs/how-opf-works.md\",\n    \"title\": \"How OPF Works\",\n    \"markdown\": \"# How OPF Works\\n\\nAn OPF document is one JSON file that answers three questions about a presentation:\\n\\n- **What does it say?** — `slides`, with content payloads and assets.\\n- **Who is it for and why?** — `audience`, `purpose`, `tone`, `language`, and `narrative`.\\n- **What should it look like?** — `design`, resolved through themes, color schemes, and font schemes.\\n\\nThe document records intent; an engine (a renderer, exporter, or editor) turns that intent into pixels or `.pptx` output. OPF deliberately stops at the format boundary: it never embeds OOXML, layout geometry, or renderer-specific state. You — or your agent — own the story, the data, and the ask; the format's job is to keep all of that readable, diffable, and out of `<p:sp>` tags.\\n\\n## Anatomy of a document\\n\\n```\\nPresentation\\n├── identity ...... name, description, organization, speaker, author\\n├── intent ........ audience, purpose, tone, language, narrative, takeaway, duration\\n├── content ....... slides[]\\n│                     ├── title / subtitle / tag / notes / section / beat / layout\\n│                     └── one content shape:\\n│                           root payload   (a single content kind)\\n│                           blocks[]       (ordered payloads, placement inferred)\\n│                           region keys    (3x3 placement grid)\\n├── design ........ theme, colorScheme, fontScheme, background, logo, header, footer\\n├── assets ........ named media sources, referenced as \\\"asset:<id>\\\"\\n└── catalogs ...... per-kind overrides: inline records and/or custom sources\\n```\\n\\nOnly `slides` is required. The smallest valid document:\\n\\n```json\\n{\\n  \\\"name\\\": \\\"Minimal OPF Deck\\\",\\n  \\\"slides\\\": [\\n    { \\\"title\\\": \\\"Minimal OPF Deck\\\" },\\n    { \\\"title\\\": \\\"Next Steps\\\", \\\"text\\\": \\\"Use this as a starting point.\\\" }\\n  ]\\n}\\n```\\n\\nEverything else in the format is optional and additive.\\n\\n## Slides and content\\n\\nA slide carries its content in one of three shapes. Pick the loosest shape that says what you mean — engines handle placement.\\n\\n**1. Root payload** — one content kind directly on the slide. The kind is inferred from the field present (`text`, `items`, `chart`, `table`, `image`, `video`, `code`, `metric`, `quote`, `timeline`); see [`content-payloads.md`](./content-payloads.md) for the full table.\\n\\n```json\\n{\\n  \\\"title\\\": \\\"Operating Metric\\\",\\n  \\\"metric\\\": { \\\"value\\\": \\\"42%\\\", \\\"label\\\": \\\"Review cycle reduction\\\", \\\"trend\\\": \\\"up\\\" }\\n}\\n```\\n\\nMultiple kinds at the slide root (with no explicit `type`, `blocks`, or regions) are shorthand for the equivalent `blocks`:\\n\\n```json\\n{\\n  \\\"title\\\": \\\"Habitat\\\",\\n  \\\"text\\\": \\\"Jaguars are strongly associated with water and dense cover.\\\",\\n  \\\"items\\\": [\\\"Rainforests and flooded wetlands\\\", \\\"Large defended territories\\\"]\\n}\\n```\\n\\n**2. `blocks`** — an ordered list of payloads when a slide has several pieces of content but placement should stay renderer-inferred:\\n\\n```json\\n{\\n  \\\"title\\\": \\\"Customer Feedback\\\",\\n  \\\"blocks\\\": [\\n    { \\\"table\\\": { \\\"columns\\\": [\\\"Theme\\\", \\\"Mentions\\\"], \\\"rows\\\": [[\\\"Speed\\\", 42], [\\\"Ease of use\\\", 31]] } },\\n    { \\\"quote\\\": { \\\"text\\\": \\\"The new workflow cut review time in half.\\\", \\\"attribution\\\": \\\"Operations Lead\\\" } }\\n  ]\\n}\\n```\\n\\n**3. Promoted region keys** — a 3×3 placement grid when position matters:\\n\\n```\\n                  left                 center                 right\\n         +--------------------+--------------------+--------------------+\\n   top   |  top:left          |  top:center        |  top:right         |\\n         +--------------------+--------------------+--------------------+\\n  middle |  middle:left       |  middle:center     |  middle:right      |\\n         +--------------------+--------------------+--------------------+\\n  bottom |  bottom:left       |  bottom:center     |  bottom:right      |\\n         +--------------------+--------------------+--------------------+\\n\\n  A bare column key (\\\"left\\\") spans all three rows.\\n  A bare row key (\\\"top\\\") spans all three columns.\\n  Keys span neighbors with \\\"+\\\" and intersect rows with columns via \\\":\\\".\\n```\\n\\nThe spans compose into the slide shapes you actually want:\\n\\n```\\n  \\\"left\\\" + \\\"center+right\\\"             \\\"top\\\" + \\\"middle+bottom\\\"\\n  (sidebar + main)                    (headline band + body)\\n  +----------+------------------+     +-------------------------------+\\n  |          |                  |     |              top              |\\n  |          |                  |     +-------------------------------+\\n  |   left   |  center+right    |     |                               |\\n  |          |                  |     |         middle+bottom         |\\n  |          |                  |     |                               |\\n  +----------+------------------+     +-------------------------------+\\n\\n  \\\"top\\\" + \\\"middle+bottom:left\\\" + \\\"middle+bottom:center+right\\\"\\n  (headline band, then sidebar + main)\\n  +---------------------------------------------+\\n  |                     top                     |\\n  +---------------+-----------------------------+\\n  |               |                             |\\n  | middle+bottom | middle+bottom:center+right  |\\n  | :left         |                             |\\n  |               |                             |\\n  +---------------+-----------------------------+\\n```\\n\\nThat last shape in JSON:\\n\\n```json\\n{\\n  \\\"title\\\": \\\"Adoption Doubled\\\",\\n  \\\"top\\\": { \\\"text\\\": \\\"Adoption doubled while support load stayed flat.\\\" },\\n  \\\"middle+bottom:left\\\": { \\\"metric\\\": { \\\"value\\\": \\\"2.1x\\\", \\\"label\\\": \\\"Adoption\\\" } },\\n  \\\"middle+bottom:center+right\\\": {\\n    \\\"chart\\\": { \\\"type\\\": \\\"line\\\", \\\"data\\\": { \\\"columns\\\": [\\\"Month\\\", \\\"Teams\\\"], \\\"rows\\\": [[\\\"Jan\\\", 12], [\\\"Feb\\\", 18]] } }\\n  }\\n}\\n```\\n\\nAnd the two-column shape from the grid above:\\n\\n```json\\n{\\n  \\\"title\\\": \\\"Operating Snapshot\\\",\\n  \\\"left\\\": { \\\"table\\\": { \\\"columns\\\": [\\\"Metric\\\", \\\"Value\\\"], \\\"rows\\\": [[\\\"Revenue\\\", \\\"$4.2M\\\"]] } },\\n  \\\"center+right\\\": { \\\"chart\\\": { \\\"type\\\": \\\"line\\\", \\\"data\\\": { \\\"columns\\\": [\\\"Month\\\", \\\"Revenue\\\"], \\\"rows\\\": [[\\\"Jan\\\", 3.4]] } } }\\n}\\n```\\n\\nRegion keys on one slide must not overlap, and regions cannot be mixed with a root payload. Slide-level strings `title`, `subtitle`, and `tag` sit alongside whichever content shape you use, and render into the matching placeholders of the resolved layout.\\n\\n## Layouts are hints, not contracts\\n\\n`Slide.layout` optionally references a record in the `layouts` catalog. The layout's placeholders describe what the layout *exposes* (a title slot, chart regions, image treatment) — they do not constrain what the slide may contain. This loose coupling is intentional:\\n\\n- A slide may use any region keys or payloads regardless of its declared layout. Validators do not error on a slide/layout mismatch.\\n- When `layout` is omitted, engines infer one from the slide's payload or region keys.\\n- Free-form layout names that don't resolve through any catalog fall through to engine-defined layouts.\\n\\nThe principle, used throughout OPF: **slides are the source of truth**. Layouts, narratives, and design records guide rendering; they never invalidate content.\\n\\n## Narrative is intent, not structure\\n\\n`narrative` declares the deck's story arc. It resolves to a record in the `narratives` catalog (e.g. `\\\"classic-story\\\"`, `\\\"pitch-deck\\\"`), each of which defines ordered **beats** — labeled segments of the arc such as `hook`, `problem`, `evidence`, `ask` — with optional slide-blueprint hints (`slideType`, `layoutHint`, `instructions`, `thoughtCues`).\\n\\nSlides opt into beats via `Slide.beat`. Nothing forces them to: validators warn on drift (orphan slides, unused beats) but never error.\\n\\n```json\\n{\\n  \\\"name\\\": \\\"Schema Pitch\\\",\\n  \\\"narrative\\\": {\\n    \\\"id\\\": \\\"technical-proof\\\",\\n    \\\"name\\\": \\\"Technical Proof\\\",\\n    \\\"beats\\\": [\\n      { \\\"id\\\": \\\"contract\\\", \\\"name\\\": \\\"Contract\\\", \\\"slideType\\\": \\\"text\\\", \\\"instructions\\\": \\\"State what stays stable.\\\" },\\n      { \\\"id\\\": \\\"evidence\\\", \\\"name\\\": \\\"Evidence\\\", \\\"slideType\\\": \\\"chart\\\" },\\n      { \\\"id\\\": \\\"adoption\\\", \\\"name\\\": \\\"Adoption\\\", \\\"slideType\\\": \\\"list\\\" }\\n    ]\\n  },\\n  \\\"slides\\\": [\\n    { \\\"beat\\\": \\\"contract\\\", \\\"title\\\": \\\"The Contract\\\", \\\"text\\\": \\\"Beats describe intent without constraining slides.\\\" },\\n    { \\\"beat\\\": [\\\"evidence\\\", \\\"adoption\\\"], \\\"title\\\": \\\"Proof And Ask\\\", \\\"items\\\": [\\\"One slide may cover several beats.\\\"] }\\n  ]\\n}\\n```\\n\\nObject form supports overrides: `{ \\\"id\\\": \\\"classic-story\\\", \\\"beats\\\": [...] }` merges inline beats into the catalog record by beat `id`. An object whose `id` matches no record — like `technical-proof` above — is a fully custom inline narrative. Deck-level concerns that aren't part of the storyline (`audience`, `tone`, `takeaway`, `duration`) live as siblings on the presentation root, not inside the narrative.\\n\\n## Catalog references and how they resolve\\n\\nMost reusable values in OPF are references into **catalogs**: named collections of records, each identified by a kebab-case `id`. The referencing fields are `narrative`, `language`, `tone`, `audience`, `purpose`, `design.theme`, `design.colorScheme`, `design.fontScheme`, `Slide.layout`, `Chart.type`, and the platform keys in `socials`.\\n\\nEvery reference resolves through the same chain, first match wins:\\n\\n```\\n        \\\"design\\\": { \\\"colorScheme\\\": \\\"cool-horizon\\\" }\\n                          |\\n                          v\\n   1. catalogs.colorSchemes.records[]    inline records in this document\\n                          | miss\\n                          v\\n   2. catalogs.colorSchemes.source       custom registry declared in this document\\n                          | miss\\n                          v\\n   3. default catalog                    https://www.pptx.gallery/color-schemes\\n                          | miss         (bundled in spec/catalogs/ and in\\n                          v               the @openpresentation/opf package)\\n   validation warning — never an error — and an engine fallback\\n```\\n\\nWhen a reference is omitted entirely, engines fall back to their own defaults (see [`spec/reference/engine-defaults.json`](../spec/reference/engine-defaults.json) for a reference example — that file is engine configuration, not part of the document contract).\\n\\nThree reference forms are accepted wherever a catalog reference is allowed:\\n\\n- **Bare id** for the common case: `\\\"narrative\\\": \\\"classic-story\\\"`.\\n- **Object form** for catalog-backed overrides: `{ \\\"id\\\": \\\"cool-horizon\\\", \\\"accent1\\\": \\\"#0F4C81\\\" }` resolves the record as a base, then inline fields win per key.\\n- **URL or `pkg:` reference**, which skips the catalog lookup and resolves directly.\\n\\nA document can carry its own records or point at a private registry, which also silences unknown-id warnings for that kind:\\n\\n```json\\n{\\n  \\\"name\\\": \\\"Branded Deck\\\",\\n  \\\"design\\\": { \\\"colorScheme\\\": \\\"acme-brand\\\" },\\n  \\\"catalogs\\\": {\\n    \\\"colorSchemes\\\": {\\n      \\\"records\\\": [{ \\\"id\\\": \\\"acme-brand\\\", \\\"accent1\\\": \\\"#0F4C81\\\", \\\"light1\\\": \\\"#FFFFFF\\\", \\\"dark1\\\": \\\"#0B1B2B\\\" }]\\n    },\\n    \\\"narratives\\\": { \\\"source\\\": \\\"https://catalogs.example.com/narratives\\\" }\\n  },\\n  \\\"slides\\\": [{ \\\"title\\\": \\\"Branded Deck\\\" }]\\n}\\n```\\n\\n## Design in one paragraph\\n\\n`design` selects a `theme` (which bundles default color scheme, font scheme, background, and dimensions) and may override any of those directly; `Slide.design` overrides the deck design per slide. More specific always wins, field by field. Color schemes and font schemes each support two mixable models — OOXML slots/pairs that round-trip to PowerPoint, and abstract roles (`primary`, `heading`, `code`, …) that engines map onto slots. The full precedence chain with worked examples is in [`design-resolution.md`](./design-resolution.md).\\n\\n## Assets\\n\\nBinary content lives in the top-level `assets` registry, keyed by id. Content payloads and design fields reference entries with `asset:<id>` strings; asset `src` values accept HTTPS URLs, data URIs, and paths resolved against the OPF file location.\\n\\n## A complete small deck\\n\\nEverything above, together — intent metadata, a catalog-backed narrative with beats, design, an organization and speaker, an asset-backed chart, regions, notes, and sections:\\n\\n```json\\n{\\n  \\\"$schema\\\": \\\"https://openpresentation.org/schema/opf/v1\\\",\\n  \\\"name\\\": \\\"Q3 Business Review\\\",\\n  \\\"description\\\": \\\"Quarterly review for the executive team.\\\",\\n  \\\"audience\\\": \\\"executives\\\",\\n  \\\"purpose\\\": \\\"decide\\\",\\n  \\\"tone\\\": \\\"formal\\\",\\n  \\\"language\\\": \\\"en-US\\\",\\n  \\\"narrative\\\": \\\"qbr\\\",\\n  \\\"takeaway\\\": \\\"Approve the expanded rollout budget.\\\",\\n  \\\"duration\\\": 20,\\n  \\\"organization\\\": {\\n    \\\"id\\\": \\\"acme\\\",\\n    \\\"name\\\": \\\"Acme Corp\\\",\\n    \\\"domain\\\": \\\"acme.com\\\",\\n    \\\"socials\\\": { \\\"linkedin\\\": \\\"acme\\\" }\\n  },\\n  \\\"speaker\\\": { \\\"id\\\": \\\"alice\\\", \\\"name\\\": \\\"Alice Chen\\\", \\\"title\\\": \\\"VP Operations\\\", \\\"organizationId\\\": \\\"acme\\\" },\\n  \\\"design\\\": {\\n    \\\"theme\\\": \\\"classic\\\",\\n    \\\"colorScheme\\\": \\\"forest-green\\\",\\n    \\\"footer\\\": { \\\"left\\\": { \\\"organization\\\": true }, \\\"right\\\": { \\\"slideNumber\\\": true } }\\n  },\\n  \\\"assets\\\": {\\n    \\\"adoption-csv\\\": { \\\"src\\\": \\\"./data/adoption.csv\\\", \\\"alt\\\": \\\"Monthly adoption data\\\" }\\n  },\\n  \\\"slides\\\": [\\n    {\\n      \\\"layout\\\": \\\"title\\\",\\n      \\\"beat\\\": \\\"objectives\\\",\\n      \\\"title\\\": \\\"Q3 Business Review\\\",\\n      \\\"subtitle\\\": \\\"Operations — October 2025\\\"\\n    },\\n    {\\n      \\\"beat\\\": \\\"performance-headline\\\",\\n      \\\"title\\\": \\\"Adoption Doubled\\\",\\n      \\\"left\\\": { \\\"metric\\\": { \\\"value\\\": \\\"2.1x\\\", \\\"label\\\": \\\"Quarter-over-quarter adoption\\\", \\\"trend\\\": \\\"up\\\" } },\\n      \\\"center+right\\\": {\\n        \\\"chart\\\": { \\\"type\\\": \\\"line\\\", \\\"data\\\": { \\\"src\\\": \\\"asset:adoption-csv\\\", \\\"columns\\\": [\\\"Month\\\", \\\"Active Teams\\\"] } }\\n      },\\n      \\\"notes\\\": \\\"Pause here; this is the slide the decision hangs on.\\\"\\n    },\\n    {\\n      \\\"beat\\\": \\\"risks\\\",\\n      \\\"section\\\": \\\"Decision\\\",\\n      \\\"title\\\": \\\"What Could Go Wrong\\\",\\n      \\\"items\\\": [\\n        \\\"Capacity: two regions are at 85% utilization.\\\",\\n        {\\n          \\\"text\\\": \\\"Churn risk in the legacy tier.\\\",\\n          \\\"description\\\": \\\"Mitigation: migration incentives ship in November.\\\"\\n        }\\n      ]\\n    },\\n    {\\n      \\\"beat\\\": \\\"asks\\\",\\n      \\\"title\\\": \\\"The Ask\\\",\\n      \\\"text\\\": \\\"Approve $1.2M to expand the rollout to all regions in Q4.\\\"\\n    }\\n  ]\\n}\\n```\\n\\nThe beat ids (`objectives`, `performance-headline`, `risks`, `asks`) come from the `qbr` narrative record; the theme, color scheme, chart type, and layout all resolve through the bundled catalogs. For a fixture that exercises the full surface in one file, see [`examples/technical/full-feature-tour.opf.json`](../examples/technical/full-feature-tour.opf.json).\\n\\n## Validation philosophy\\n\\nTwo layers, with a deliberate split:\\n\\n- **Schema errors** for structural problems: wrong types, overlapping region keys, payloads mixing incompatible content kinds, a region payload missing concrete content.\\n- **Warnings** for advisory drift: unknown catalog ids, narrative/slide mismatches. These never make a document invalid.\\n\\n`validatePresentation` from `@openpresentation/opf` applies both layers locally.\\n\\n## Where to go next\\n\\n- [`schema-reference.md`](./schema-reference.md) — every field of every object in the presentation schema.\\n- [`catalog-schema-reference.md`](./catalog-schema-reference.md) — every field of every catalog record schema.\\n- [`content-payloads.md`](./content-payloads.md) — payload shapes and inference rules with examples.\\n- [`design-resolution.md`](./design-resolution.md) — the design precedence algorithm.\\n- [`examples.md`](./examples.md) — guide to the example decks under `examples/`.\\n\\nThen write a deck, commit it, revise it, and read the diff. A two-line diff for a two-word change is the whole argument for the format.\\n\"\n  },\n  {\n    \"slug\": \"schema-reference\",\n    \"file\": \"docs/schema-reference.md\",\n    \"title\": \"OPF Presentation Schema Reference\",\n    \"markdown\": \"# OPF Presentation Schema Reference\\n\\nThis reference documents the author-facing shape of a complete `*.opf.json` presentation document. It summarizes the canonical schema in `spec/schemas/opf.schema.json`; the schema remains the source of truth for validators.\\n\\n## Document Contract\\n\\n- Schema id: `https://openpresentation.org/schema/opf/v1`\\n- Required top-level fields: `slides`\\n- Additional top-level fields: not allowed\\n\\n## Top-Level Fields\\n\\n| Field | Required | Type | Notes |\\n| --- | --- | --- | --- |\\n| `$schema` | no | `const:\\\"https://openpresentation.org/schema/opf/v1\\\"` | Optional OPF schema version. When omitted, validators and engines should assume the latest supported OPF schema. |\\n| `name` | no | `string` | Display name of the presentation for GUI/TUI lists, library/search indexing, OS-level metadata, and default export filenames. This is deck identity, not slide content. Use slides[].title and slides[].subtitle for text... |\\n| `description` | no | `string` | Free-form prose describing what this presentation is about. Used by agents and humans as a deck-level summary; complements purpose (the goal) and narrative (the structured storyline). Round-trips to OOXML 'docProps/co... |\\n| `filename` | no | `string` | Optional base filename for exports (without extension). Engine strips a trailing .pptx, .pdf, .png, or .svg (case-insensitive) and appends the target format's extension. When omitted, the engine slugifies name when pr... |\\n| `organization` | no | `oneOf:ref:Organization / array<ref:Organization>` | Organization associated with the presentation, usually the presenting company. Array form supports hosts, partners, clients, and sponsors. The primary organization (declared via Organization.role or, if no role is set... |\\n| `speaker` | no | `oneOf:ref:Speaker / array<ref:Speaker>` | Person presenting the deck. Array form supports panels and multi-speaker decks. Used for cover slides, bio slides, footers, and panel attribution. |\\n| `author` | no | `oneOf:string / array<string>` | Optional credit for the person who authored or contributed to the deck, distinct from speaker. Array form supports multiple contributors. Round-trips to OOXML 'docProps/core.xml' as '<dc:creator>' (semicolon-joined wh... |\\n| `audience` | no | `oneOf:string / array<oneOf:string / ref:Audience>` | Intended audiences for the presentation. Accepts either: - A single string shorthand: free-form description ('Series B investors'), an audiences catalog id ('executives'), an HTTPS URL, or a 'pkg:' reference. - An arr... |\\n| `purpose` | no | `oneOf:string / ref:Purpose` | Primary goal of the presentation. Accepts either: - A string shorthand: free-form goal ('Raise a Series B round of $30M'), a purposes catalog id ('decide', 'align'), an HTTPS URL, or a 'pkg:' reference. - An inline Pu... |\\n| `language` | no | `oneOf:string / ref:Language` | Language for the presentation content. Accepts either: - A string shorthand: a BCP-47 language tag ('en-US', 'en-GB', 'ja-JP', 'fr'), a languages catalog id ('english', 'japanese'), an HTTPS URL, or a 'pkg:' reference... |\\n| `tone` | no | `oneOf:string / ref:Tone` | Desired tone for the presentation. Accepts either: - A string shorthand: a tones catalog id ('formal'), an HTTPS URL, or a 'pkg:' reference. - An inline Tone object for custom tone metadata or catalog-backed overrides... |\\n| `takeaway` | no | `oneOf:string / array<string>` | Audience-facing takeaway the presentation should leave behind. Array form supports multiple takeaways. Deck-level intent used by AI to seed and pressure-test slide content. |\\n| `duration` | no | `integer` | Target presentation duration, as an integer number of minutes. Used by AI to set pace and depth, and to compare against the resolved narrative's durationRange. |\\n| `tags` | no | `array<string>` | Free-form labels used for categorization, search, and filtering. Lowercase kebab-case is recommended for consistency across a deck library. |\\n| `design` | no | `ref:Design` | Optional design system covering theme, color scheme, font scheme, dimensions, background, logo, watermark, header, and footer applied to the deck. When omitted, engines use their default design configuration. |\\n| `narrative` | no | `oneOf:string / ref:Narrative` | Structured storyline describing the deck's arc and beats. Resolves to the 'id' of a 'narratives' catalog record. Accepts two forms: - String shorthand for the common case: 'narrative = \\\"classic-story\\\"'. Accepts a bare... |\\n| `slides` | yes | `array<ref:Slide>` | Ordered array of slides that make up the presentation. |\\n| `assets` | no | `ref:Assets` | Optional reusable asset registry for images, data files, videos, documents, fonts, and other resources referenced elsewhere in the deck via 'asset:<id>' strings. |\\n| `catalogs` | no | `ref:Catalogs` | Optional per-kind catalog overrides. Each kind may declare a non-default 'source' and/or inline 'records' that override or supplement the default catalog at https://www.pptx.gallery/<kind>. References elsewhere in the... |\\n| `extensions` | no | `object` | Custom data passthrough for agent workflows; ignored by the engine but preserved across read/write round-trips. |\\n\\n## Object And Type Reference\\n\\n### Assets\\n\\n- Type: `object`\\n- Required fields: none\\n- Purpose: Reusable asset registry for resources used by slides, charts, metadata, and design. Keys are stable asset ids referenced elsewhere as 'asset:<id>'. Each asset can be a source string or an object with src plus optional metadata.\\n\\n_No named properties._\\n\\n\\n### Asset\\n\\n- Type: `oneOf:string / object`\\n- Required fields: none\\n- Purpose: Reusable or inline resource. A string is shorthand for { \\\"src\\\": value }. Source strings accept 'asset:<id>' references, HTTPS URLs, data URIs, relative paths resolved against the OPF file location, or local filesystem paths. Use object form when metadata such as alt text, title, mediaType, or format matters.\\n\\n_No named properties._\\n\\n\\n### Audience\\n\\n- Type: `anyOf:schema / schema`\\n- Required fields: none\\n- Purpose: Inline audience metadata for the presentation. Use 'id' to reference an audiences catalog record and override selected fields, or use 'name' for a custom inline audience.\\n- Conditional requirement: `id` or `name`\\n\\n| Field | Required | Type | Notes |\\n| --- | --- | --- | --- |\\n| `id` | no | `string` | Optional audiences catalog id to resolve before applying inline overrides. |\\n| `name` | no | `string` | Human-readable audience name shown in pickers. |\\n| `summary` | no | `string` | One-sentence positioning of the audience. |\\n| `description` | no | `string` | Longer prose describing the audience and how to address them. |\\n| `seniority` | no | `enum:ic \\\\| manager \\\\| director \\\\| vp \\\\| c-suite \\\\| mixed` | Typical seniority level of the audience. |\\n| `technicalFluency` | no | `enum:low \\\\| medium \\\\| high \\\\| mixed` | Typical technical fluency of the audience. |\\n| `decisionPower` | no | `enum:informational \\\\| advisory \\\\| decision-maker` | Whether the audience is expected to be informed, advise, or decide. |\\n| `attentionBudgetMinutes` | no | `number` | Realistic upper bound on focused attention for a single presentation, in minutes. |\\n| `recommendedNarratives` | no | `array<string>` | Soft cross-link: narrative-catalog ids that work well for this audience. |\\n| `recommendedTones` | no | `array<string>` | Soft cross-link: tone-catalog ids that work well for this audience. |\\n| `tags` | no | `array<string>` | Free-form labels for filtering and search. |\\n\\n\\n### Purpose\\n\\n- Type: `anyOf:schema / schema`\\n- Required fields: none\\n- Purpose: Inline purpose metadata for the presentation. Use 'id' to reference a purposes catalog record and override selected fields, or use 'name' for a custom inline purpose.\\n- Conditional requirement: `id` or `name`\\n\\n| Field | Required | Type | Notes |\\n| --- | --- | --- | --- |\\n| `id` | no | `string` | Optional purposes catalog id to resolve before applying inline overrides. |\\n| `name` | no | `string` | Human-readable purpose name shown in pickers. |\\n| `summary` | no | `string` | One-sentence positioning of the purpose. |\\n| `description` | no | `string` | Longer prose describing when to use this purpose and how it should shape a deck. |\\n| `outcome` | no | `string` | Desired audience outcome after the presentation. |\\n| `successCriteria` | no | `array<string>` | Observable signals that the deck accomplished this purpose. |\\n| `recommendedNarratives` | no | `array<string>` | Soft cross-link: narrative-catalog ids that work well for this purpose. |\\n| `recommendedTones` | no | `array<string>` | Soft cross-link: tone-catalog ids that work well for this purpose. |\\n| `tags` | no | `array<string>` | Free-form labels for filtering and search. |\\n\\n\\n### Language\\n\\n- Type: `anyOf:schema / schema`\\n- Required fields: none\\n- Purpose: Inline language metadata for the presentation. Use 'id' to reference a languages catalog record and override selected fields, or use 'bcp47' for a custom language tag without a catalog record.\\n- Conditional requirement: `id` or `bcp47`\\n\\n| Field | Required | Type | Notes |\\n| --- | --- | --- | --- |\\n| `id` | no | `string` | Optional languages catalog id to resolve before applying inline overrides. |\\n| `name` | no | `string` | Human-readable language name. |\\n| `bcp47` | no | `string` | BCP-47 language tag used for locale-aware rendering, proofing, and accessibility metadata. Use 'en-GB' for UK English; 'en-UK' is not a valid BCP-47 region form. |\\n| `code` | no | `string` | ISO 639-3 or 639-2 language code carried for engines that prefer ISO codes. |\\n| `direction` | no | `enum:ltr \\\\| rtl` | Base text direction for the language. |\\n| `script` | no | `string` | ISO 15924 script code when the writing system should be explicit. |\\n| `fontScheme` | no | `string` | Default font-scheme id for this language when targeting PowerPoint output. |\\n| `googleFontScheme` | no | `string` | Default font-scheme id for this language when targeting Google Slides output. |\\n| `summary` | no | `string` | One-sentence note about coverage or font defaults. |\\n| `description` | no | `string` | Longer prose describing the language record and any font-pairing rationale. |\\n| `tags` | no | `array<string>` | Free-form labels for filtering and search. |\\n\\n\\n### Tone\\n\\n- Type: `anyOf:schema / schema`\\n- Required fields: none\\n- Purpose: Inline tone metadata for the presentation. Use 'id' to reference a tones catalog record and override selected fields, or use 'name' for a custom inline tone.\\n- Conditional requirement: `id` or `name`\\n\\n| Field | Required | Type | Notes |\\n| --- | --- | --- | --- |\\n| `id` | no | `string` | Optional tones catalog id to resolve before applying inline overrides. |\\n| `name` | no | `string` | Human-readable tone name shown in pickers. |\\n| `summary` | no | `string` | One-sentence positioning of the tone. |\\n| `description` | no | `string` | Longer prose describing the tone and the kinds of decks it suits. |\\n| `voiceCues` | no | `array<string>` | Short directives that shape AI generation toward this tone. |\\n| `avoid` | no | `array<string>` | Anti-patterns that AI generation should not produce when this tone is active. |\\n| `samplePhrases` | no | `array<string>` | Short example phrases that exemplify this tone. |\\n| `recommendedNarratives` | no | `array<string>` | Soft cross-link: narrative-catalog ids this tone pairs well with. |\\n| `tags` | no | `array<string>` | Free-form labels for filtering and search. |\\n\\n\\n### Organization\\n\\n- Type: `object`\\n- Required fields: `id`, `name`\\n- Purpose: An organization associated with the presentation typically the presenting company, but also hosts, partners, clients, or sponsors. Surfaced on cover slides, footers, and brand bars; the primary organization's logo is the default deck logo unless overridden by design.logo.\\n\\n| Field | Required | Type | Notes |\\n| --- | --- | --- | --- |\\n| `id` | yes | `string` | Stable identifier for the organization, used to reference it from Speaker.organizationId. Must be unique within the deck. |\\n| `name` | yes | `string` | Display name shown on slides. |\\n| `legalName` | no | `string` | Optional legal entity name when it differs from the display name. |\\n| `logo` | no | `ref:Asset` | Source for the organization's logo image. Accepts an HTTPS URL, data URI, relative path (resolved against the OPF file location), local path, or 'asset:<id>' reference. Common formats are SVG (preferred for vector log... |\\n| `domain` | no | `string` | Bare internet domain for the organization. Used for footers, contact slides, and engine-driven asset lookups (e.g., favicon-based brand defaults). |\\n| `email` | no | `string` | General contact email for the organization. Used on contact slides and footer attribution. |\\n| `phone` | no | `string` | Main contact phone number for the organization. E.164 format is recommended. |\\n| `tagline` | no | `string` | Short tagline rendered alongside the organization name on cover slides. |\\n| `role` | no | `enum:primary \\\\| partner \\\\| client \\\\| sponsor \\\\| host` | Role of the organization relative to the presentation. When omitted, the single organization or first organization in array form is treated as primary. |\\n| `socials` | no | `ref:Socials` | Optional social media handles or URLs for the organization. |\\n\\n\\n### Speaker\\n\\n- Type: `object`\\n- Required fields: `id`, `name`\\n- Purpose: A person presenting the deck. Used for cover slides, bio/intro slides, footer attribution, and panel formats with multiple presenters.\\n\\n| Field | Required | Type | Notes |\\n| --- | --- | --- | --- |\\n| `id` | yes | `string` | Stable identifier for the speaker, used for cross-references within the deck. Must be unique within the deck. |\\n| `name` | yes | `string` | Display name. |\\n| `title` | no | `string` | Role or title. Often paired with the speaker's organization on cover slides. |\\n| `photo` | no | `ref:Asset` | Source for the speaker's headshot image. Accepts an HTTPS URL, data URI, relative path (resolved against the OPF file location), local path, or 'asset:<id>' reference. Common formats are JPG or PNG; SVG is not appropr... |\\n| `email` | no | `string` | Contact email, used on contact slides or footer attribution when appropriate. |\\n| `phone` | no | `string` | Contact phone number for the speaker. E.164 format is recommended. |\\n| `bio` | no | `string` | Short biographical paragraph for bio or 'about the speaker' slides. |\\n| `organizationId` | no | `string` | Reference to an Organization.id in organization. Lets a speaker be attributed to their org in panel or multi-org decks without repeating organization details. |\\n| `socials` | no | `ref:Socials` | Optional social media handles or URLs for the speaker. |\\n\\n\\n### Socials\\n\\n- Type: `object`\\n- Required fields: none\\n- Purpose: Social media handles or URLs, keyed by platform id from the 'socialPlatforms' catalog. Each value is a string either a full URL or a platform handle (e.g., '@acme'). The catalog record for each platform carries the URL pattern, handle prefix, brand color, and themed icons used by renderers. Keys resolve to the 'id' of a 'socialPlatforms' catalog record. Resolution order: inline catalogs.socialPlatforms.records[] catalogs.socialPlatforms.source default catalog at https://www.pptx.gallery/socia...\\n\\n_No named properties._\\n\\n\\n### Narrative\\n\\n- Type: `object`\\n- Required fields: none\\n- Purpose: Structured storyline used by AI to shape generated content. Mirrors the OPF Narrative Template record at https://openpresentation.org/schema/opf-narrative/v1 (sans '$schema'), so a library record and an inline narrative are interchangeable. Narrative declares the deck's intended story arc; slides may opt into beats via Slide.beat. The narrative does not constrain slide structure validators warn on drift (orphan slides, unused beats) but never error. Slides are the source of truth; narrative i...\\n\\n| Field | Required | Type | Notes |\\n| --- | --- | --- | --- |\\n| `id` | no | `string` | Stable slug identifying this narrative. When it matches a record in the resolved 'narratives' catalog, the catalog record's beats and metadata seed this narrative; inline fields override per-key. When it doesn't match... |\\n| `name` | no | `string` | Human-readable narrative name. |\\n| `summary` | no | `string` | One-sentence description of when and why to use this narrative. |\\n| `description` | no | `string` | Longer prose describing the narrative arc and ideal use cases. Used by AI-driven generation to seed deck-level direction. |\\n| `audienceFit` | no | `array<string>` | Audiences this narrative works well for. Free-form strings or 'audiences' catalog ids. |\\n| `durationRange` | no | `object` | Typical talk-length window this narrative suits. Compared by validators against duration. |\\n| `tags` | no | `array<string>` | Free-form labels for filtering and search. |\\n| `preview` | no | `object` | Visual previews of the narrative, used by picker UIs and inline rendering. All sub-fields are optional. |\\n| `beats` | no | `array<ref:NarrativeBeat>` | Ordered list of beats that make up the narrative arc. When 'id' matches a catalog record, beats here override or extend matching catalog beats by their own 'id'. Beat IDs must be unique within the narrative. |\\n\\n\\n### NarrativeBeat\\n\\n- Type: `object`\\n- Required fields: `id`, `name`\\n- Purpose: A single narrative beat a labeled segment of the story arc with a specific dramatic purpose (e.g. 'hook', 'problem', 'evidence', 'ask'). Slides reference beats via Slide.beat. Beats may also carry slide-blueprint hints (slideType, layoutHint, thoughtCues, instructions) that guide the assigned slide. Mirrors the Beat definition in narrative.schema.json (https://openpresentation.org/schema/opf-narrative/v1) so library entries and inline OPF beats are interchangeable.\\n\\n| Field | Required | Type | Notes |\\n| --- | --- | --- | --- |\\n| `id` | yes | `string` | Stable slug used by Slide.beat to reference this beat. Lowercase kebab-case. |\\n| `name` | yes | `string` | Human-readable beat name. |\\n| `description` | no | `string` | Curator-written prose that explains what this beat should accomplish. |\\n| `instructions` | no | `string` | Short author-facing instruction for the beat typically one phrase. Complements 'description' with a concise directive. |\\n| `slideCount` | no | `integer` | Optional explicit slide count for this beat. Defaults to 1 when omitted; values >1 are reserved for beats that intentionally span multiple slides. Prefer decomposing a heavy beat into multiple beats over setting a hig... |\\n| `slideType` | no | `enum:text \\\\| list \\\\| image \\\\| chart \\\\| table \\\\| video \\\\| code \\\\| metric \\\\| quote \\\\| timeline` | Default content kind for the beat's slide. Mirrors ContentPayload.type and helps engines choose a sensible layout when only the beat is specified. |\\n| `layoutHint` | no | `string` | Suggested layout id for the beat's opening slide. Resolves the same way as Slide.layout against catalogs.layouts and the default catalog at https://www.pptx.gallery/layouts. |\\n| `thoughtCues` | no | `array<string>` | Optional speaker or thinking cues attached to the beat. Surfaced in presenter notes. |\\n\\n\\n### Design\\n\\n- Type: `object`\\n- Required fields: none\\n- Purpose: Visual design system applied to the presentation; individual slides may override fields via Slide.design.\\n\\n| Field | Required | Type | Notes |\\n| --- | --- | --- | --- |\\n| `theme` | no | `oneOf:string / ref:Theme` | Theme for the deck. Accepts two forms: - String shorthand: 'design.theme = \\\"minimal\\\"'. Bare id, HTTPS URL, or 'pkg:' reference resolved as the 'id' of a 'themes' catalog record. - Object form: a Theme with an optional... |\\n| `colorScheme` | no | `oneOf:string / ref:ColorScheme` | Color scheme for the presentation. Accepts two forms: - String shorthand: 'design.colorScheme = \\\"cool-horizon\\\"'. Bare id, HTTPS URL, or 'pkg:' reference resolved as the 'id' of a 'colorSchemes' catalog record. - Objec... |\\n| `fontScheme` | no | `oneOf:string / ref:FontScheme` | Font scheme for heading, body, accent, and code text. Accepts two forms: - String shorthand: 'design.fontScheme = \\\"aptos\\\"'. Bare id, HTTPS URL, or 'pkg:' reference resolved as the 'id' of a 'fontSchemes' catalog recor... |\\n| `dimensions` | no | `oneOf:ref:DimensionPreset / ref:Dimensions` | Slide dimensions and aspect ratio. String shorthand such as 'widescreen' is equivalent to { preset: 'widescreen' }. |\\n| `background` | no | `oneOf:ref:BackgroundShortcut / ref:Background` | Default slide background applied across the deck unless overridden on a slide. String shorthand accepts theme slots ('light1', 'light2', 'dark1', 'dark2') or hex colors; object forms support theme, solid, gradient, im... |\\n| `logo` | no | `oneOf:ref:Asset / ref:LogoSet` | Deck logo assets used by layouts, covers, section dividers, headers, and footers. A string is the default logo source; object form provides light/dark, stacked, icon, and wordmark variants. When omitted, the renderer... |\\n| `watermark` | no | `oneOf:const:false / ref:Asset / ref:Watermark` | Optional decorative watermark applied across slides. Use false to suppress an inherited watermark in slide-level design; a string is equivalent to { src: value }. |\\n| `header` | no | `oneOf:const:false / ref:HeaderFooter` | Repeated header furniture rendered outside the main slide content. Use false to suppress an inherited header. |\\n| `footer` | no | `oneOf:const:false / ref:HeaderFooter` | Repeated footer furniture rendered outside the main slide content. Use false to suppress an inherited footer. |\\n| `titleAlignment` | no | `enum:left \\\\| center \\\\| right` | Default horizontal alignment for title placeholders in resolved layouts. |\\n| `contentAlignment` | no | `enum:left \\\\| center \\\\| right` | Default horizontal alignment for body/content regions in resolved layouts. |\\n| `contentBox` | no | `boolean` | Whether body/content regions are rendered inside a visible card or surface. |\\n| `slideImage` | no | `oneOf:ref:Asset / object` | Optional slide-level image treatment used by layouts that support a decorative or editorial image separate from content images. |\\n| `contentDirection` | no | `enum:horizontal \\\\| vertical` | Axis along which parallel body/content regions are arranged. |\\n| `chartPrimary` | no | `enum:none \\\\| top \\\\| bottom \\\\| left \\\\| right` | For chart layouts, where the primary chart sits relative to supporting content. 'none' means chart regions have equal weight. |\\n| `imageFill` | no | `enum:crop \\\\| fit` | How picture placeholders fill their allocated region. |\\n| `listBullet` | no | `enum:character \\\\| image` | Default bullet rendering style for list layouts. |\\n\\n\\n### Theme\\n\\n- Type: `object`\\n- Required fields: none\\n- Purpose: Theme bundle used by the design system. In design.theme, 'id' resolves a themes catalog record as the base; any sibling fields override the resolved theme. The string shorthand on design.theme is equivalent to setting only 'id'.\\n\\n| Field | Required | Type | Notes |\\n| --- | --- | --- | --- |\\n| `id` | no | `string` | Theme reference. Resolves to the 'id' of a 'themes' catalog record. Accepts a bare id (lowercase kebab-case, e.g. 'minimal'), an HTTPS URL pointing at a record file, or a 'pkg:' reference. Field overrides on the surro... |\\n| `name` | no | `string` | Human-readable theme name shown in pickers. |\\n| `summary` | no | `string` | One-sentence positioning of the theme - when to reach for it. |\\n| `description` | no | `string` | Longer prose describing what the theme looks and feels like and the kinds of decks it suits. |\\n| `colorScheme` | no | `oneOf:string / ref:ColorScheme` | Default color scheme for this theme. A string resolves against catalogs.colorSchemes; an object may provide an 'id' base reference plus overrides. |\\n| `fontScheme` | no | `oneOf:string / ref:FontScheme` | Default font scheme for this theme. A string resolves against catalogs.fontSchemes; an object may provide an 'id' base reference plus overrides. |\\n| `background` | no | `oneOf:ref:BackgroundShortcut / ref:Background` | Default background for this theme. String shorthand accepts theme slots ('light1', 'light2', 'dark1', 'dark2') or hex colors. |\\n| `dimensions` | no | `oneOf:ref:DimensionPreset / ref:Dimensions` | Default slide size for this theme. A string preset is equivalent to { preset: value }. |\\n| `tags` | no | `array<string>` | Free-form labels for filtering and search. |\\n\\n\\n### ColorScheme\\n\\n- Type: `object`\\n- Required fields: none\\n- Purpose: Color palette used by the design system. The slot fields (accent1-accent6, dark1, dark2, light1, light2, hyperlink, followedHyperlink) mirror color-scheme.schema.json (https://openpresentation.org/schema/opf-color-scheme/v1) so library records and inline OPF overrides are interchangeable on those fields. Two parallel models are supported and may be mixed: - OOXML slots - the 12-slot PowerPoint theme model that round-trips directly to OOXML. Use these for full control over the palette as Power...\\n\\n| Field | Required | Type | Notes |\\n| --- | --- | --- | --- |\\n| `id` | no | `string` | Color scheme reference. Resolves to the 'id' of a 'colorSchemes' catalog record. Accepts a bare id (lowercase kebab-case, e.g. 'cool-horizon'), an HTTPS URL pointing at a record file, or a 'pkg:' reference. Slot and r... |\\n| `accent1` | no | `string` | Accent 1 color (hex). Mirrors the OOXML accent1 slot. |\\n| `accent2` | no | `string` | Accent 2 color (hex). Mirrors the OOXML accent2 slot. |\\n| `accent3` | no | `string` | Accent 3 color (hex). Mirrors the OOXML accent3 slot. |\\n| `accent4` | no | `string` | Accent 4 color (hex). Mirrors the OOXML accent4 slot. |\\n| `accent5` | no | `string` | Accent 5 color (hex). Mirrors the OOXML accent5 slot. |\\n| `accent6` | no | `string` | Accent 6 color (hex). Mirrors the OOXML accent6 slot. |\\n| `dark1` | no | `string` | Dark 1 color (hex). Typically the deepest neutral; OOXML dark1. |\\n| `dark2` | no | `string` | Dark 2 color (hex). Secondary dark; OOXML dark2. |\\n| `light1` | no | `string` | Light 1 color (hex). Typically the slide canvas; OOXML lt1. |\\n| `light2` | no | `string` | Light 2 color (hex). Secondary light surface; OOXML lt2. |\\n| `hyperlink` | no | `string` | Hyperlink color (hex). OOXML hlink. |\\n| `followedHyperlink` | no | `string` | Followed-hyperlink color (hex). OOXML folHlink. |\\n| `primary` | no | `string` | Abstract role: primary brand color (hex). The engine maps this onto an OOXML accent slot when serializing. |\\n| `secondary` | no | `string` | Abstract role: secondary brand color (hex). |\\n| `accent` | no | `string` | Abstract role: accent color used for highlights and emphasis (hex). |\\n| `background` | no | `string` | Abstract role: default slide background color (hex). The engine maps this to one of light1 / light2 / dark1 / dark2 when serializing. |\\n| `surface` | no | `string` | Abstract role: color for elevated surfaces such as cards and panels (hex). |\\n| `text` | no | `string` | Abstract role: primary body text color (hex). |\\n| `textSecondary` | no | `string` | Abstract role: secondary or muted text color used for captions and supporting copy (hex). |\\n| `custom` | no | `object` | Map of custom named colors for advanced or theme-specific use. |\\n\\n\\n### FontScheme\\n\\n- Type: `object`\\n- Required fields: none\\n- Purpose: Typography selections used by the design system. The pair fields (major, minor) and refinement fields (type, app, languageFamily) mirror font-scheme.schema.json (https://openpresentation.org/schema/opf-font-scheme/v1) so library records and inline OPF overrides are interchangeable on those fields. Two parallel models are supported and may be mixed: - OOXML pairs (major, minor) - heading and body family names that round-trip directly to PowerPoint majorFont/minorFont entries. - Abstract roles...\\n\\n| Field | Required | Type | Notes |\\n| --- | --- | --- | --- |\\n| `id` | no | `string` | Font scheme reference. Resolves to the 'id' of a 'fontSchemes' catalog record. Accepts a bare id (lowercase kebab-case, e.g. 'aptos'), an HTTPS URL pointing at a record file, or a 'pkg:' reference. Field overrides on... |\\n| `major` | no | `string` | Heading (major) font family mirrors the OOXML majorFont entry. Pairs with 'minor'. |\\n| `minor` | no | `string` | Body (minor) font family mirrors the OOXML minorFont entry. Pairs with 'major'. |\\n| `type` | no | `enum:sans-serif \\\\| serif \\\\| monospace` | High-level typographic class of the scheme. |\\n| `app` | no | `enum:PowerPoint \\\\| Google Slides` | Target application this font pairing is intended for. |\\n| `languageFamily` | no | `enum:latin \\\\| ea \\\\| cs` | OOXML font-language family this scheme is intended for: 'latin' for Latin-script content, 'ea' for East Asian scripts, 'cs' for Complex Scripts. |\\n| `heading` | no | `ref:Font` | Abstract role: font used for slide titles and headings. Maps onto the OOXML major slot when serializing. |\\n| `body` | no | `ref:Font` | Abstract role: font used for body copy. Maps onto the OOXML minor slot when serializing. |\\n| `accent` | no | `ref:Font` | Abstract role: font used for accent text such as quotes or callouts. No direct OOXML slot. |\\n| `code` | no | `ref:Font` | Abstract role: monospaced font used for code blocks. No direct OOXML slot. |\\n\\n\\n### Font\\n\\n- Type: `object`\\n- Required fields: `family`\\n- Purpose: Specification for a single font role.\\n\\n| Field | Required | Type | Notes |\\n| --- | --- | --- | --- |\\n| `family` | yes | `string` | Font family name. |\\n| `weight` | no | `number` | Numeric font weight (e.g., 400 for regular, 700 for bold). |\\n| `style` | no | `enum:normal \\\\| italic` | Font style. |\\n| `letterSpacing` | no | `number` | Letter spacing (tracking) in ems. |\\n\\n\\n### DimensionPreset\\n\\n- Type: `enum:16:9 | 4:3 | 16:10 | letter | a4 | widescreen | standard`\\n- Required fields: none\\n- Purpose: Named dimension preset; chooses both aspect ratio and physical size. 'widescreen' is an alias for 16:9 in PowerPoint widescreen size; 'standard' is an alias for 4:3 in PowerPoint standard size.\\n\\n_No named properties._\\n\\n\\n### Dimensions\\n\\n- Type: `object`\\n- Required fields: none\\n- Purpose: Slide dimensions; either pick a preset or specify custom inches.\\n\\n| Field | Required | Type | Notes |\\n| --- | --- | --- | --- |\\n| `preset` | no | `ref:DimensionPreset` |  |\\n| `widthInches` | no | `number` | Custom slide width in inches; overrides the preset width when provided. |\\n| `heightInches` | no | `number` | Custom slide height in inches; overrides the preset height when provided. |\\n\\n\\n### ThemeBackgroundSlot\\n\\n- Type: `enum:light1 | light2 | dark1 | dark2`\\n- Required fields: none\\n- Purpose: PowerPoint theme-controlled slide background slot from the active color scheme. These are slots, not assumptions about actual colors: light1 is usually white and dark1 is usually black by convention, but the color scheme controls the real values.\\n\\n_No named properties._\\n\\n\\n### HexColor\\n\\n- Type: `string`\\n- Required fields: none\\n- Purpose: Hex color shorthand accepted by selected string fields.\\n\\n_No named properties._\\n\\n\\n### BackgroundShortcut\\n\\n- Type: `oneOf:ref:ThemeBackgroundSlot / ref:HexColor`\\n- Required fields: none\\n- Purpose: String shorthand for a background. Theme slots ('light1', 'light2', 'dark1', 'dark2') are equivalent to { type: 'theme', slot: value }; hex colors are equivalent to { type: 'solid', color: value }.\\n\\n_No named properties._\\n\\n\\n### Background\\n\\n- Type: `oneOf:ref:ThemeBackground / ref:SolidBackground / ref:GradientBackground / ref:ImageBackground / ref:PatternBackground`\\n- Required fields: none\\n- Purpose: Background fill applied to slides. Theme backgrounds preserve PowerPoint's color-scheme background choice; other variants represent fixed background fills.\\n\\n_No named properties._\\n\\n\\n### ThemeBackground\\n\\n- Type: `object`\\n- Required fields: `type`, `slot`\\n- Purpose: Theme-controlled PowerPoint slide background. The slot is resolved through the active color scheme and remains theme-aware.\\n\\n| Field | Required | Type | Notes |\\n| --- | --- | --- | --- |\\n| `type` | yes | `const:\\\"theme\\\"` | Theme-controlled background fill. |\\n| `slot` | yes | `ref:ThemeBackgroundSlot` |  |\\n\\n\\n### SolidBackground\\n\\n- Type: `object`\\n- Required fields: `type`, `color`\\n- Purpose: Fixed solid slide background fill.\\n\\n| Field | Required | Type | Notes |\\n| --- | --- | --- | --- |\\n| `type` | yes | `const:\\\"solid\\\"` | Fixed solid background fill. |\\n| `color` | yes | `string` | Fixed solid fill color, usually a hex string. Use { type: 'theme', slot: ... } for PowerPoint's four theme-controlled background choices. |\\n| `opacity` | no | `number` | Background opacity from 0 (fully transparent) to 1 (fully opaque). |\\n\\n\\n### GradientBackground\\n\\n- Type: `object`\\n- Required fields: `type`, `gradient`\\n- Purpose: Fixed gradient slide background fill.\\n\\n| Field | Required | Type | Notes |\\n| --- | --- | --- | --- |\\n| `type` | yes | `const:\\\"gradient\\\"` | Fixed gradient background fill. |\\n| `gradient` | yes | `object` | Gradient fill definition. |\\n| `opacity` | no | `number` | Background opacity from 0 (fully transparent) to 1 (fully opaque). |\\n\\n\\n### ImageBackground\\n\\n- Type: `object`\\n- Required fields: `type`, `image`\\n- Purpose: Fixed image slide background fill.\\n\\n| Field | Required | Type | Notes |\\n| --- | --- | --- | --- |\\n| `type` | yes | `const:\\\"image\\\"` | Fixed image background fill. |\\n| `image` | yes | `object` | Image fill definition. |\\n| `opacity` | no | `number` | Background opacity from 0 (fully transparent) to 1 (fully opaque). |\\n\\n\\n### PatternBackground\\n\\n- Type: `object`\\n- Required fields: `type`, `pattern`\\n- Purpose: Fixed pattern slide background fill.\\n\\n| Field | Required | Type | Notes |\\n| --- | --- | --- | --- |\\n| `type` | yes | `const:\\\"pattern\\\"` | Fixed pattern background fill. |\\n| `pattern` | yes | `object` | Pattern fill definition. |\\n| `opacity` | no | `number` | Background opacity from 0 (fully transparent) to 1 (fully opaque). |\\n\\n\\n### LogoSet\\n\\n- Type: `object`\\n- Required fields: none\\n- Purpose: Deck logo variants surfaced by layouts, covers, section dividers, headers, and footers. Organization identity lives in organization; this object only controls visual rendering assets. Renderer convention: on dark backgrounds prefer the 'light' variant, on light backgrounds prefer the 'dark' variant, and in square/vertical slots prefer the stacked family when present.\\n\\n| Field | Required | Type | Notes |\\n| --- | --- | --- | --- |\\n| `default` | no | `ref:Asset` | Default full-lockup logo. Used as fallback when no more specific variant is set. |\\n| `light` | no | `ref:Asset` | Light-colored full-lockup logo intended for rendering on dark backgrounds. |\\n| `dark` | no | `ref:Asset` | Dark-colored full-lockup logo intended for rendering on light backgrounds. |\\n| `stacked` | no | `ref:Asset` | Stacked vertical logo lockup, suited to portrait or square brand-mark slots. |\\n| `stackedLight` | no | `ref:Asset` | Light-colored stacked logo variant intended for rendering on dark backgrounds. |\\n| `stackedDark` | no | `ref:Asset` | Dark-colored stacked logo variant intended for rendering on light backgrounds. |\\n| `icon` | no | `ref:Asset` | Default icon, mark, or symbol without wordmark. Useful for tight spaces such as footers, badges, and slide-corner marks. |\\n| `iconLight` | no | `ref:Asset` | Light-colored icon variant intended for rendering on dark backgrounds. |\\n| `iconDark` | no | `ref:Asset` | Dark-colored icon variant intended for rendering on light backgrounds. |\\n| `wordmark` | no | `ref:Asset` | Default wordmark: the organization name set in branded typography, without icon. |\\n| `wordmarkLight` | no | `ref:Asset` | Light-colored wordmark variant intended for rendering on dark backgrounds. |\\n| `wordmarkDark` | no | `ref:Asset` | Dark-colored wordmark variant intended for rendering on light backgrounds. |\\n\\n\\n### Watermark\\n\\n- Type: `object`\\n- Required fields: `opacity`\\n- Purpose: Decorative watermark image and rendering options. Use design.watermark = false to disable an inherited watermark.\\n\\n| Field | Required | Type | Notes |\\n| --- | --- | --- | --- |\\n| `src` | no | `string` | Source for the watermark image. |\\n| `opacity` | yes | `number` | Watermark opacity from 0 (fully transparent) to 1 (fully opaque). |\\n\\n\\n### HeaderFooter\\n\\n- Type: `object`\\n- Required fields: none\\n- Purpose: Repeated header or footer content split into left, center, and right zones. Header/footer content is slide furniture, separate from the main slide content payloads.\\n\\n| Field | Required | Type | Notes |\\n| --- | --- | --- | --- |\\n| `left` | no | `ref:HeaderFooterItem` | Left-aligned header/footer content. |\\n| `center` | no | `ref:HeaderFooterItem` | Centered header/footer content. |\\n| `right` | no | `ref:HeaderFooterItem` | Right-aligned header/footer content. |\\n\\n\\n### HeaderFooterItem\\n\\n- Type: `object`\\n- Required fields: none\\n- Purpose: One header/footer zone. Fields may be combined when the renderer supports it; otherwise renderers should prefer image, then text-like generated content.\\n\\n| Field | Required | Type | Notes |\\n| --- | --- | --- | --- |\\n| `text` | no | `string` | Literal text rendered in this zone. |\\n| `image` | no | `ref:Asset` | Generic image rendered in this zone, such as a logo, partner mark, certification badge, or icon. |\\n| `slideNumber` | no | `boolean` | Whether to render the current slide number in this zone. |\\n| `date` | no | `oneOf:boolean / string` | Whether to render the presentation date, or a literal date string to render. |\\n| `organization` | no | `boolean` | Whether to render the primary organization name from organization. |\\n| `section` | no | `boolean` | Whether to render the current slide section label. |\\n\\n\\n### Slide\\n\\n- Type: `object`\\n- Required fields: none\\n- Purpose: A single slide. Content can be authored as a full-slide root payload, or inside promoted named region keys such as 'left', 'center+right', and 'top:left'.\\n\\n| Field | Required | Type | Notes |\\n| --- | --- | --- | --- |\\n| `id` | no | `string` | Optional stable identifier for the slide within the document. Use when another system needs to reference a slide across edits, comments, generation state, exports, or narrative tooling. Slide order is defined by the s... |\\n| `type` | no | `enum:text \\\\| list \\\\| image \\\\| chart \\\\| table \\\\| video \\\\| code \\\\| metric \\\\| quote \\\\| timeline` | Optional full-slide content kind. When omitted, engines infer the kind from root payload fields. |\\n| `beat` | no | `oneOf:string / array<string>` | Optional reference to one or more narrative beats (each value matches an id from narrative.beats or the resolved template). A single string declares the slide's primary beat; an array declares that one slide covers mu... |\\n| `layout` | no | `string` | Optional slide layout reference. Resolves to the 'id' of a 'layouts' catalog record. When omitted, engines infer a layout from the slide's root payload or promoted region keys. Accepts a bare id (lowercase kebab-case,... |\\n| `title` | no | `string` | Slide-level title content. When the resolved layout exposes a 'title' placeholder, the engine renders this value there. |\\n| `subtitle` | no | `string` | Slide-level subtitle or supporting line. When the resolved layout exposes a 'subtitle' placeholder, the engine renders this value there. |\\n| `tag` | no | `string` | Small slide-level label or badge. When the resolved layout exposes a 'tag' placeholder, the engine renders this value there. |\\n| `text` | no | `oneOf:string / array<ref:TextRun>` | Full-slide text payload. Use a string for plain text or TextRun[] for inline rich text. TextRun items may be plain strings or formatted run objects. |\\n| `items` | no | `array<ref:ListItem>` | Full-slide generic list payload. Presence of this field infers type 'list'. At slide root, multiple content payload kinds with no explicit type, blocks, or regions are accepted as shorthand for layout-agnostic blocks. |\\n| `bullets` | no | `array<ref:BulletItem>` | Full-slide text-style bullet payload. Presence of this field infers type 'text'. |\\n| `image` | no | `ref:Asset` | Full-slide image source. Presence of this field infers type 'image'. |\\n| `video` | no | `ref:Asset` | Full-slide video source. Presence of this field infers type 'video'. |\\n| `chart` | no | `ref:Chart` | Full-slide chart payload. Presence of this field infers type 'chart'. |\\n| `table` | no | `ref:Table` | Full-slide table payload. Presence of this field infers type 'table'. |\\n| `code` | no | `oneOf:string / ref:Code` | Full-slide code payload. A string is shorthand for { \\\"source\\\": value }; object form carries optional syntax language and filename metadata. |\\n| `metric` | no | `oneOf:string / number / ref:Metric` | Full-slide metric payload. A string or number is shorthand for { \\\"value\\\": value }; object form carries optional label, description, unit, delta, and trend metadata. Numeric values remain numbers; renderers format them... |\\n| `quote` | no | `oneOf:string / ref:Quote` | Full-slide quote payload. A string is shorthand for { \\\"text\\\": value }; object form carries optional attribution and source metadata. Presence of this field infers type 'quote'. |\\n| `timeline` | no | `ref:Timeline` | Full-slide timeline payload. An array is shorthand for { \\\"events\\\": value }; object form carries optional name and description metadata. Presence of this field infers type 'timeline'. |\\n| `blocks` | no | `array<ref:ContentPayload>` | Layout-agnostic content blocks rendered together as a composed payload when exact placement is unspecified. At slide root, multiple content payload kinds with no explicit type, blocks, or regions are accepted as shorthand for equivalent blocks. |\\n| `design` | no | `ref:Design` | Slide-level design applied on top of the deck-wide design. |\\n| `left` | no | `ref:ContentPayload` |  |\\n| `center` | no | `ref:ContentPayload` |  |\\n| `right` | no | `ref:ContentPayload` |  |\\n| `left+center` | no | `ref:ContentPayload` |  |\\n| `center+right` | no | `ref:ContentPayload` |  |\\n| `left+center+right` | no | `ref:ContentPayload` |  |\\n| `top` | no | `ref:ContentPayload` |  |\\n| `middle` | no | `ref:ContentPayload` |  |\\n| `bottom` | no | `ref:ContentPayload` |  |\\n| `top+middle` | no | `ref:ContentPayload` |  |\\n| `middle+bottom` | no | `ref:ContentPayload` |  |\\n| `top+middle+bottom` | no | `ref:ContentPayload` |  |\\n| `top:left` | no | `ref:ContentPayload` |  |\\n| `top:center` | no | `ref:ContentPayload` |  |\\n| `top:right` | no | `ref:ContentPayload` |  |\\n| `top:left+center` | no | `ref:ContentPayload` |  |\\n| `top:center+right` | no | `ref:ContentPayload` |  |\\n| `top:left+center+right` | no | `ref:ContentPayload` |  |\\n| `middle:left` | no | `ref:ContentPayload` |  |\\n| `middle:center` | no | `ref:ContentPayload` |  |\\n| `middle:right` | no | `ref:ContentPayload` |  |\\n| `middle:left+center` | no | `ref:ContentPayload` |  |\\n| `middle:center+right` | no | `ref:ContentPayload` |  |\\n| `middle:left+center+right` | no | `ref:ContentPayload` |  |\\n| `bottom:left` | no | `ref:ContentPayload` |  |\\n| `bottom:center` | no | `ref:ContentPayload` |  |\\n| `bottom:right` | no | `ref:ContentPayload` |  |\\n| `bottom:left+center` | no | `ref:ContentPayload` |  |\\n| `bottom:center+right` | no | `ref:ContentPayload` |  |\\n| `bottom:left+center+right` | no | `ref:ContentPayload` |  |\\n| `top+middle:left` | no | `ref:ContentPayload` |  |\\n| `top+middle:center` | no | `ref:ContentPayload` |  |\\n| `top+middle:right` | no | `ref:ContentPayload` |  |\\n| `top+middle:left+center` | no | `ref:ContentPayload` |  |\\n| `top+middle:center+right` | no | `ref:ContentPayload` |  |\\n| `top+middle:left+center+right` | no | `ref:ContentPayload` |  |\\n| `middle+bottom:left` | no | `ref:ContentPayload` |  |\\n| `middle+bottom:center` | no | `ref:ContentPayload` |  |\\n| `middle+bottom:right` | no | `ref:ContentPayload` |  |\\n| `middle+bottom:left+center` | no | `ref:ContentPayload` |  |\\n| `middle+bottom:center+right` | no | `ref:ContentPayload` |  |\\n| `middle+bottom:left+center+right` | no | `ref:ContentPayload` |  |\\n| `top+middle+bottom:left` | no | `ref:ContentPayload` |  |\\n| `top+middle+bottom:center` | no | `ref:ContentPayload` |  |\\n| `top+middle+bottom:right` | no | `ref:ContentPayload` |  |\\n| `top+middle+bottom:left+center` | no | `ref:ContentPayload` |  |\\n| `top+middle+bottom:center+right` | no | `ref:ContentPayload` |  |\\n| `top+middle+bottom:left+center+right` | no | `ref:ContentPayload` |  |\\n| `notes` | no | `string` | Speaker notes shown in presenter view. |\\n| `section` | no | `string` | PowerPoint-style slide section label. Consecutive slides with the same value belong to the same section in presenter view, outlines, and PowerPoint section-aware exports. |\\n| `hidden` | no | `boolean` | Whether the slide is hidden from the presented sequence. |\\n\\n\\n### ContentPayload\\n\\n- Type: `allOf:schema + schema + schema + schema + schema + schema + schema + schema + schema`\\n- Required fields: none\\n- Purpose: A single content payload. The optional 'type' discriminator can make intent explicit, but validators and engines infer it from fields such as text, bullets, items, image, video, chart, table, code, metric, quote, or timeline.\\n\\n| Field | Required | Type | Notes |\\n| --- | --- | --- | --- |\\n| `type` | no | `enum:text \\\\| list \\\\| image \\\\| chart \\\\| table \\\\| video \\\\| code \\\\| metric \\\\| quote \\\\| timeline` | Optional content kind. When omitted, engines infer the kind from the fields present. |\\n| `text` | no | `oneOf:string / array<ref:TextRun>` | Text payload. Use a string for plain text or TextRun[] for inline rich text. TextRun items may be plain strings or formatted run objects. |\\n| `items` | no | `array<ref:ListItem>` | Generic list payload. Each item is either a plain string, a TextRun[] rich text sequence, or a ListItem object. List nesting uses item.level rather than nested content payloads. |\\n| `bullets` | no | `array<ref:BulletItem>` | Text-style bullet payload. Presence of this field infers type 'text'. |\\n| `image` | no | `ref:Asset` | Source for an image item. |\\n| `video` | no | `ref:Asset` | Source for a video item. |\\n| `chart` | no | `ref:Chart` | Chart payload. Presence of this field infers type 'chart'. |\\n| `table` | no | `ref:Table` | Table payload. Presence of this field infers type 'table'. |\\n| `code` | no | `oneOf:string / ref:Code` | Code payload. A string is shorthand for { \\\"source\\\": value }; object form carries optional syntax language and filename metadata. |\\n| `metric` | no | `oneOf:string / number / ref:Metric` | Metric payload. A string or number is shorthand for { \\\"value\\\": value }; object form carries optional label, description, unit, delta, and trend metadata. Numeric values remain numbers; renderers format them for display. |\\n| `quote` | no | `oneOf:string / ref:Quote` | Quote payload. A string is shorthand for { \\\"text\\\": value }; object form carries optional attribution and source metadata. |\\n| `timeline` | no | `ref:Timeline` | Timeline payload ordered by narrative or chronology. |\\n\\n\\n### Quote\\n\\n- Type: `object`\\n- Required fields: `text`\\n- Purpose: Quote content with optional attribution metadata. Use 'text' for the quoted text, 'attribution' for the credited person or organization, and 'source' for a citation or URL. A string value in a quote field is shorthand for { \\\"text\\\": value }.\\n\\n| Field | Required | Type | Notes |\\n| --- | --- | --- | --- |\\n| `text` | yes | `string` | Quoted text. |\\n| `attribution` | no | `string` | Person or organization credited for the quote. |\\n| `source` | no | `string` | Optional quote source, citation, or URL. |\\n\\n\\n### Code\\n\\n- Type: `object`\\n- Required fields: `source`\\n- Purpose: Code content with optional rendering metadata. Use 'source' for the code text, 'language' for syntax highlighting, and 'filename' when the rendered block should show a file label. A string value in a code field is shorthand for { \\\"source\\\": value }.\\n\\n| Field | Required | Type | Notes |\\n| --- | --- | --- | --- |\\n| `source` | yes | `string` | Source code text to display. |\\n| `language` | no | `string` | Language identifier used for syntax highlighting. |\\n| `filename` | no | `string` | Optional file label shown with the code block. |\\n\\n\\n### Metric\\n\\n- Type: `object`\\n- Required fields: `value`\\n- Purpose: Metric content with optional display metadata. Use 'value' for the primary value, 'label' for the metric name, 'description' for supporting context, 'unit' for a suffix/currency marker, 'delta' for change, and 'trend' for direction. A string or number value in a metric field is shorthand for { \\\"value\\\": value }; numeric values remain numbers and are formatted by renderers.\\n\\n| Field | Required | Type | Notes |\\n| --- | --- | --- | --- |\\n| `value` | yes | `oneOf:string / number` | Primary metric value. |\\n| `label` | no | `string` | Metric label. |\\n| `description` | no | `string` | Optional supporting context for the metric. |\\n| `unit` | no | `string` | Metric unit, suffix, or currency marker. |\\n| `delta` | no | `oneOf:string / number` | Metric change value. |\\n| `trend` | no | `enum:up \\\\| down \\\\| flat` | Metric trend direction. |\\n\\n\\n### Timeline\\n\\n- Type: `oneOf:array<ref:TimelineEvent> / object`\\n- Required fields: none\\n- Purpose: Timeline content. An array is shorthand for { \\\"events\\\": value }; object form carries optional name and description metadata.\\n\\n_No named properties._\\n\\n\\n### TimelineEvent\\n\\n- Type: `object`\\n- Required fields: `what`\\n- Purpose: A single event inside a timeline content payload.\\n\\n| Field | Required | Type | Notes |\\n| --- | --- | --- | --- |\\n| `when` | no | `string` | Event time, date, or sequence label. Use ISO-like values when possible, but human labels are allowed for quarters, eras, and relative milestones. |\\n| `what` | yes | `string` | Short event label. |\\n| `description` | no | `string` | Optional event detail. |\\n\\n\\n### ListItem\\n\\n- Type: `oneOf:string / array<ref:TextRun> / object`\\n- Required fields: none\\n- Purpose: A flat item inside a list. Strings cover the common case, TextRun[] supports inline rich text without an object wrapper, and object form adds description and nesting depth without creating nested slide content payloads.\\n\\n_No named properties._\\n\\n\\n### BulletItem\\n\\n- Type: `oneOf:string / array<ref:TextRun> / object`\\n- Required fields: none\\n- Purpose: A flat bullet item. Strings cover the common case, TextRun[] supports inline rich text without an object wrapper, and object form adds nesting depth without list-item descriptions.\\n\\n_No named properties._\\n\\n\\n### TextRun\\n\\n- Type: `oneOf:string / object`\\n- Required fields: none\\n- Purpose: A contiguous run of text. Strings cover unformatted spans; object form adds character formatting.\\n\\n_No named properties._\\n\\n\\n### Chart\\n\\n- Type: `object`\\n- Required fields: `type`, `data`\\n- Purpose: Chart content. The chart object keeps chart-specific fields together so slides and regions do not expose loose chart fields.\\n\\n| Field | Required | Type | Notes |\\n| --- | --- | --- | --- |\\n| `type` | yes | `string` | Chart type id. Resolves to the id of a chartTypes catalog record; renderers map that record through mappings.openxml and any renderer-specific mapping they understand. |\\n| `data` | yes | `oneOf:ref:ChartData / ref:ChartDataSource` | Chart data. Inline data uses a tabular columns/rows shape; renderers convert rows to chart series internally. |\\n\\n\\n### Table\\n\\n- Type: `object`\\n- Required fields: `rows`\\n- Purpose: Table content. Columns are optional; rows are the only required field.\\n\\n| Field | Required | Type | Notes |\\n| --- | --- | --- | --- |\\n| `columns` | no | `array<string>` | Optional column labels rendered above table rows. |\\n| `rows` | yes | `array<array<ref:TableCell>>` | Two-dimensional table row data; each row aligns by index with columns when columns are supplied. |\\n\\n\\n### ChartData\\n\\n- Type: `object`\\n- Required fields: `columns`, `rows`\\n- Purpose: Inline tabular data driving a chart. The first column usually supplies category/x-axis labels; subsequent columns are plotted measures unless a chart type or renderer maps them differently.\\n\\n| Field | Required | Type | Notes |\\n| --- | --- | --- | --- |\\n| `columns` | yes | `array<string>` | Ordered column labels for the chart data table. |\\n| `rows` | yes | `array<array<ref:ChartDataCell>>` | Tabular chart rows. Each row aligns by index with columns. |\\n\\n\\n### ChartDataSource\\n\\n- Type: `object`\\n- Required fields: `src`\\n- Purpose: Chart data sourced from an asset reference, URL, data URI, relative path, or local path such as CSV, TSV, JSON, or XLSX. The source is interpreted as a table; optional columns select or order fields from that table.\\n\\n| Field | Required | Type | Notes |\\n| --- | --- | --- | --- |\\n| `src` | yes | `string` | Data source. Use 'asset:<id>' to reference the top-level assets registry, or provide an HTTPS URL, data URI, relative path, or local filesystem path. |\\n| `sheet` | no | `string` | Optional sheet name or table name for spreadsheet-like assets. |\\n| `range` | no | `string` | Optional A1-style range or engine-defined range selector for spreadsheet-like assets. |\\n| `columns` | no | `array<string>` | Optional ordered columns or fields to read from the source. When omitted, renderers may use the source's own header row or schema. |\\n\\n\\n### ChartDataCell\\n\\n- Type: `oneOf:string / number / boolean / null`\\n- Required fields: none\\n- Purpose: A cell in inline chart data.\\n\\n_No named properties._\\n\\n\\n### TableCell\\n\\n- Type: `oneOf:string / number / boolean / null`\\n- Required fields: none\\n- Purpose: A cell in table content.\\n\\n_No named properties._\\n\\n\\n### Catalogs\\n\\n- Type: `object`\\n- Required fields: none\\n- Purpose: Catalog overrides for the in-document references. Every property is optional. The default catalog for a kind lives at https://www.pptx.gallery/<kind> (e.g. https://www.pptx.gallery/narratives, https://www.pptx.gallery/themes). For each kind, declaring a 'source' replaces the default registry and/or 'records' adds inline records that take precedence over anything fetched from a source. Resolution order for any reference (e.g. narrative, design.theme): inline catalogs.<kind>.records[] catalogs....\\n\\n| Field | Required | Type | Notes |\\n| --- | --- | --- | --- |\\n| `narratives` | no | `ref:CatalogEntry` | Catalog of narrative templates. Records validate against https://openpresentation.org/schema/opf-narrative/v1. Default source: https://www.pptx.gallery/narratives. |\\n| `themes` | no | `ref:CatalogEntry` | Catalog of themes. Records validate against https://openpresentation.org/schema/opf-theme/v1. Default source: https://www.pptx.gallery/themes. |\\n| `colorSchemes` | no | `ref:CatalogEntry` | Catalog of color schemes. Records validate against https://openpresentation.org/schema/opf-color-scheme/v1. Default source: https://www.pptx.gallery/color-schemes. |\\n| `fontSchemes` | no | `ref:CatalogEntry` | Catalog of font schemes. Records validate against https://openpresentation.org/schema/opf-font-scheme/v1. Default source: https://www.pptx.gallery/font-schemes. |\\n| `languages` | no | `ref:CatalogEntry` | Catalog of languages. Records validate against https://openpresentation.org/schema/opf-language/v1. Default source: https://www.pptx.gallery/languages. |\\n| `layouts` | no | `ref:CatalogEntry` | Catalog of slide layouts. Records validate against https://openpresentation.org/schema/opf-layout/v1. Default source: https://www.pptx.gallery/layouts. |\\n| `chartTypes` | no | `ref:CatalogEntry` | Catalog of chart types. Records validate against https://openpresentation.org/schema/opf-chart-type/v1. Default source: https://www.pptx.gallery/chart-types. |\\n| `tones` | no | `ref:CatalogEntry` | Catalog of presentation tones. Records validate against https://openpresentation.org/schema/opf-tone/v1. Default source: https://www.pptx.gallery/tones. Referenced from tone. |\\n| `purposes` | no | `ref:CatalogEntry` | Catalog of presentation purposes. Records validate against https://openpresentation.org/schema/opf-purpose/v1. Default source: https://www.pptx.gallery/purposes. Referenced from purpose. |\\n| `audiences` | no | `ref:CatalogEntry` | Catalog of presentation audiences. Records validate against https://openpresentation.org/schema/opf-audience/v1. Default source: https://www.pptx.gallery/audiences. Referenced from audience. |\\n| `socialPlatforms` | no | `ref:CatalogEntry` | Catalog of social-media platforms. Records validate against https://openpresentation.org/schema/opf-social-platform/v1. Default source: https://www.pptx.gallery/social-platforms. Referenced via the property keys of an... |\\n\\n\\n### CatalogEntry\\n\\n- Type: `object`\\n- Required fields: none\\n- Purpose: A catalog override for one record kind. 'source' replaces the default registry; 'records' adds inline records that take precedence over anything fetched from a source. Either or both may be provided; both omitted means the kind uses its default catalog.\\n\\n| Field | Required | Type | Notes |\\n| --- | --- | --- | --- |\\n| `source` | no | `oneOf:ref:CatalogSource / array<ref:CatalogSource>` | Single source or an ordered search path of sources. When omitted, the engine falls back to https://www.pptx.gallery/<kind>. |\\n| `records` | no | `array<object>` | Inline catalog records embedded in this OPF document. Each record validates against the kind's companion schema (e.g. https://openpresentation.org/schema/opf-narrative/v1 for narratives). Inline records win over anyth... |\\n\\n\\n### CatalogSource\\n\\n- Type: `string`\\n- Required fields: none\\n- Purpose: Catalog source location. Accepts: - A bare URL pointing at a catalog directory (e.g. 'https://acme.com/decks/narratives'); record ids resolve to '<base>/<id>.json'. - A URL pointing at an index file (e.g. 'https://acme.com/decks/narratives/index.json'); records are resolved relative to the index file's directory and the index entries describe what's available. - A package reference of the form 'pkg:<package>[/<subpath>]'; resolved through a locally-installed package on the engine's package path.\\n\\n_No named properties._\\n\"\n  }\n] as readonly DocRecord[]);\n\nexport const docsRaw = docsData;\n","// Bundled OPF documentation pages.\n//\n// Source-of-truth: ../../../docs/*.md (top-level only — `BACKLOG.md` and the\n// `docs/migrations/`, `docs/plans/` subdirectories are intentionally excluded\n// for now). The build step inlines the raw markdown into this module so\n// consumers can render or link to the docs without filesystem access.\n\nimport { docsRaw } from \"./generated/docs.js\";\nimport type { DocRecord } from \"./generated/docs.js\";\n\nexport type { DocRecord };\n\n/** Every documentation page shipped with this release, sorted by slug. */\nexport const docs: readonly DocRecord[] = docsRaw;\n\n/** Look up a documentation page by slug (the filename without `.md`). */\nexport function getDoc(slug: string): DocRecord | undefined {\n  return docsRaw.find((doc) => doc.slug === slug);\n}\n"]}

package/dist/examples.d.ts

@@ -0,0 +1,43 @@
+import { P as Presentation } from './presentation-C8BOK0-5.js';
+
+interface ExampleRecord {
+    /** Filename slug, without the `.opf.json` suffix. */
+    readonly slug: string;
+    /** Path relative to the repo root, with forward slashes. */
+    readonly file: string;
+    /** Top-level examples/<category> bucket (`gallery`, `technical`, …). */
+    readonly category: string;
+    /** Gallery slug when the example lives under `examples/gallery/<slug>/`; otherwise `null`. */
+    readonly gallery: string | null;
+    /** Parsed OPF document. Validated against `presentation.schema.json` at build time. */
+    readonly deck: Presentation;
+}
+interface GalleryRecord {
+    /** Gallery slug (folder name under `examples/gallery/`). */
+    readonly slug: string;
+    /** Directory path relative to the repo root. */
+    readonly dir: string;
+    /** Lightweight summary of every example deck inside the gallery. */
+    readonly examples: readonly {
+        readonly slug: string;
+        readonly file: string;
+        readonly name: string | null;
+    }[];
+}
+
+/** Every example deck shipped with this release, sorted by file path. */
+declare const examples: readonly ExampleRecord[];
+/** Examples grouped by `examples/gallery/<slug>/` folder. */
+declare const galleries: readonly GalleryRecord[];
+/** Top-level `examples/<category>` buckets present in this release. */
+declare const exampleCategories: readonly string[];
+/** Look up an example deck by slug (the filename without `.opf.json`). */
+declare function getExample(slug: string): ExampleRecord | undefined;
+/** Look up a gallery by slug. */
+declare function getGallery(slug: string): GalleryRecord | undefined;
+/** All examples that belong to a given gallery slug. */
+declare function getExamplesByGallery(slug: string): readonly ExampleRecord[];
+/** All examples that belong to a given top-level category (`gallery`, `technical`, …). */
+declare function getExamplesByCategory(category: string): readonly ExampleRecord[];
+
+export { type ExampleRecord, type GalleryRecord, exampleCategories, examples, galleries, getExample, getExamplesByCategory, getExamplesByGallery, getGallery };