@openpresentation/opf 0.10.1 → 0.11.1

package/dist/{presentation-BMTdX6O1.d.ts → presentation-bceTClm8.d.ts}

@@ -121,24 +121,28 @@ type Language = (Language1 & {
      * 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.
      */
     bcp47?: string;
+    /**
+     * Curated culture tag for OOXML text-run language attributes (a:rPr/@lang, a:endParaRPr/@lang), in the language-[Script-]REGION form Office recognizes (e.g. 'ja-JP', 'ar-SA', 'ms-MY', 'nb-NO', 'fil-PH', 'zh-CN'). Engines emit it instead of 'bcp47' when the document names the language by catalog id or by a tag without a region; a region-bearing tag written by the author is emitted as written. Curated rather than inferred so output does not depend on the runtime's locale data.
+     */
+    ooxmlLang?: string;
     /**
      * ISO 639-3 or 639-2 language code carried for engines that prefer ISO codes.
      */
     code?: string;
     /**
-     * Base text direction for the language.
+     * Base text direction for the language. When omitted, engines derive it from the script: Arabic (Arab), Hebrew (Hebr), Syriac (Syrc), Thaana (Thaa), N'Ko (Nkoo), Adlam (Adlm), Samaritan (Samr), Mandaic (Mand) and Hanifi Rohingya (Rohg) are right-to-left; every other script is left-to-right. Bundled language records state it explicitly.
      */
     direction?: ("ltr" | "rtl");
     /**
-     * ISO 15924 script code when the writing system should be explicit.
+     * ISO 15924 script code of the language's writing system. The script selects the OOXML font slot the language's text uses: East Asian scripts (Hans, Hant, Hani, Jpan, Kore, Hang, Hira, Kana, Bopo, Yiii) use the eastAsian slot; complex scripts (for example Arab, Hebr, Syrc, Thaa, Deva, Beng, Guru, Gujr, Orya, Taml, Telu, Knda, Mlym, Sinh, Thai, Laoo, Tibt, Mymr, Khmr, Mong) use the complexScript slot; every other script (Latn, Cyrl, Grek, Armn, Geor, Ethi, ...) uses the latin slot. When omitted, engines infer it from the BCP-47 tag. Bundled language records state it explicitly. See docs/programs/font-fidelity-everywhere/script-font-model.md.
      */
     script?: string;
     /**
-     * Default font-scheme id for this language when targeting PowerPoint output.
+     * 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. Its major/minor families fill the language's script slot (eastAsian or complexScript, chosen by 'script') unless the effective design font scheme sets that slot itself; the latin slot always follows the design font scheme.
      */
     fontScheme?: string;
     /**
-     * Default font-scheme id for this language when targeting Google Slides output.
+     * 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. Used in place of 'fontScheme' when resolving script fonts for Google Slides output.
      */
     googleFontScheme?: string;
     /**
@@ -273,6 +277,26 @@ type Asset = (string | {
      */
     format?: string;
 });
+/**
+ * A single named variable. A hex string is shorthand for { "type": "color", "value": value }.
+ *
+ * This interface was referenced by `Presentation`'s JSON-Schema
+ * via the `definition` "Variable".
+ */
+type Variable = (HexColor | {
+    /**
+     * Variable kind. Only 'color' is defined today; other kinds may be added when content surfaces exist to consume them.
+     */
+    type: "color";
+    /**
+     * Hex color shorthand accepted by selected string fields.
+     */
+    value: string;
+    /**
+     * Optional prose describing what the variable is for, surfaced by pickers and agents.
+     */
+    description?: string;
+});
 /**
  * A contiguous run of text. Strings cover unformatted spans; object form adds character formatting.
  *
@@ -301,7 +325,7 @@ type TextRun = (string | {
      */
     strikethrough?: boolean;
     /**
-     * Run text color as a hex string.
+     * Run text color. Documented forms: a hex string ('#RGB', '#RRGGBB', '#RRGGBBAA'), a color-scheme slot or role name resolved through the effective color scheme ('accent2', 'text'), or a 'var:<id>' reference into the top-level variables map. Prefer names over hex so runs survive re-theming. Any other string stays schema-valid so imported decks keep validating: validators warn and renderers fall back to the theme text color.
      */
     color?: string;
     /**
@@ -390,6 +414,16 @@ type TableCellValue = (string | number | boolean | null | TextRun[]);
  * via the `definition` "ContentPayload".
  */
 type ContentPayload = {
+    /**
+     * Optional stable identifier for this payload, unique among slide and payload ids in the document. Use when another system needs to address the payload across edits — patch-style agent edits, comments, review state, or generation provenance. Identity survives reordering where array indexes do not.
+     */
+    id?: string;
+    /**
+     * Custom data passthrough for agent workflows at payload scope; ignored by the engine but preserved across read/write round-trips.
+     */
+    extensions?: {
+        [k: string]: unknown;
+    };
     /**
      * Optional content kind. When omitted, engines infer the kind from the fields present.
      */
@@ -520,7 +554,7 @@ type CatalogSource = string;
  *
  * Fields that reference catalog records (narrative, language, tone, audience, purpose, design.theme / design.theme.id, design.colorScheme / design.colorScheme.id, design.fontScheme / design.fontScheme.id, Slide.layout, Chart.type, Organization.socials / Speaker.socials) resolve through the catalog system: inline 'catalogs.<kind>.records[]' on the document → 'catalogs.<kind>.source' on the document → engine defaults → the default catalog at https://www.pptx.gallery/<kind>. Every reference resolves to the catalog record's 'id' field. When an OPF document omits a reference entirely, the engine falls back to engine defaults (see /spec/reference/engine-defaults.json for a reference example). The defaults file is engine configuration; it is not part of the OPF document contract and has no JSON Schema.
  *
- * Most catalog references accept the bare 'id' as a string for the common case (e.g. narrative = 'classic-story', design.colorScheme = 'cool-horizon'). Audience, purpose, tone, design, and language object forms use 'id' as a base catalog reference plus inline overrides. Asset references use 'asset:<id>' strings that point into the top-level assets registry.
+ * Most catalog references accept the bare 'id' as a string for the common case (e.g. narrative = 'classic-story', design.colorScheme = 'cool-horizon'). Audience, purpose, tone, design, and language object forms use 'id' as a base catalog reference plus inline overrides. Asset references use 'asset:<id>' strings that point into the top-level assets registry, and content color fields (rich-text runs, styled table cells) accept hex values, color-scheme slot/role names, or 'var:<id>' references into the top-level variables map.
  */
 interface Presentation {
     /**
@@ -596,6 +630,7 @@ interface Presentation {
      */
     tags?: string[];
     design?: Design;
+    variables?: Variables;
     /**
      * Structured storyline describing the deck's arc and beats. Resolves to the 'id' of a 'narratives' catalog record.
      *
@@ -695,7 +730,7 @@ interface Organization {
     [k: string]: unknown;
 }
 /**
- * Optional social media handles or URLs for the organization.
+ * Optional social media handles or URLs for the organization. The primary organization's socials render in header/footer zones that set socials: true; otherwise they are authoring metadata.
  */
 interface Socials {
     /**
@@ -771,7 +806,7 @@ interface Speaker {
     [k: string]: unknown;
 }
 /**
- * Optional social media handles or URLs for the speaker.
+ * Optional social media handles or URLs for the speaker. Authoring metadata: no header/footer field renders speaker socials yet.
  */
 interface Socials1 {
     /**
@@ -846,7 +881,7 @@ interface Design {
      */
     contentBox?: boolean;
     /**
-     * Optional slide-level image treatment used by layouts that support a decorative or editorial image separate from content images.
+     * Optional slide-level image, separate from content images. It applies to a slide that sets its own design.slideImage, and to slides whose layout declares slideImage: true or whose root image is the same source as a deck-level value. A root image with the same source becomes the slide image instead of a content item. Blur, shadows, soft edges, background removal and device artwork are not part of the treatment vocabulary; see docs/image-treatments.md.
      */
     slideImage?: (Asset | {
         /**
@@ -854,9 +889,88 @@ interface Design {
          */
         src?: string;
         /**
-         * Where the slide-level image sits relative to the content. 'background' is a full-bleed image behind the content.
+         * Where the slide-level image sits relative to the content. 'background' is a full-bleed image behind the content. The other positions give the image a band along that edge (see size) and compose headings and content in the rest of the slide.
          */
         position: ("background" | "top" | "bottom" | "left" | "right");
+        /**
+         * Alternative text for the slide-level image. Overrides the alt text of a referenced asset.
+         */
+        alt?: string;
+        /**
+         * How the image fills its frame: 'crop' covers the frame from the center; 'fit' shows the whole image centered inside it. Overrides design.imageFill for this image. Default: design.imageFill, else 'crop'.
+         */
+        fill?: ("crop" | "fit");
+        /**
+         * Share of the slide width (left/right) or height (top/bottom) given to the image band. Ignored for 'background'. Default 0.5.
+         */
+        size?: number;
+        /**
+         * Place the frame inside the slide padding instead of edge to edge, like a card. Default false.
+         */
+        inset?: boolean;
+        /**
+         * Width-to-height ratio of the frame. The frame becomes the largest centered box with this ratio inside the band or slide, for example 2.39 for a cinematic letterbox or 0.5 for a phone-shaped frame. 'circle' always uses 1.
+         */
+        aspectRatio?: number;
+        /**
+         * Mask applied to the frame, exported as the picture's native preset geometry (rect, roundRect, ellipse, hexagon). 'circle' makes the frame square. Default 'rectangle'.
+         */
+        shape?: ("rectangle" | "rounded" | "circle" | "hexagon");
+        /**
+         * Corner radius for shape 'rounded' as a fraction of the frame's shorter side. Default 0.16667, PowerPoint's roundRect default.
+         */
+        cornerRadius?: number;
+        /**
+         * Solid line along the frame's shape. A thick dark border on a rounded portrait frame gives a device bezel.
+         */
+        border?: {
+            /**
+             * Line color: a hex color, a color-scheme slot or role name, or a 'var:<id>' variable reference.
+             */
+            color: (HexColor | ("accent1" | "accent2" | "accent3" | "accent4" | "accent5" | "accent6" | "dark1" | "dark2" | "light1" | "light2" | "hyperlink" | "followedHyperlink" | "primary" | "secondary" | "accent" | "background" | "surface" | "text" | "textSecondary") | string);
+            /**
+             * Line width in reference pixels at a 720-pixel short edge, centered on the frame outline like a native picture line. 0 removes the line.
+             */
+            width: number;
+        };
+        /**
+         * Image opacity from 0 to 1, exported as a native alphaModFix. The border and overlay keep their own opacity. Default 1.
+         */
+        opacity?: number;
+        /**
+         * Color treatment for the image pixels. Luminance uses Rec. 601 weights (0.299, 0.587, 0.114) on sRGB values.
+         */
+        recolor?: ("grayscale" | {
+            /**
+             * Color at luminance 0.
+             */
+            dark: (HexColor | ("accent1" | "accent2" | "accent3" | "accent4" | "accent5" | "accent6" | "dark1" | "dark2" | "light1" | "light2" | "hyperlink" | "followedHyperlink" | "primary" | "secondary" | "accent" | "background" | "surface" | "text" | "textSecondary") | string);
+            /**
+             * Color at luminance 1.
+             */
+            light: (HexColor | ("accent1" | "accent2" | "accent3" | "accent4" | "accent5" | "accent6" | "dark1" | "dark2" | "light1" | "light2" | "hyperlink" | "followedHyperlink" | "primary" | "secondary" | "accent" | "background" | "surface" | "text" | "textSecondary") | string);
+        });
+        /**
+         * Solid scrim drawn over the image in the frame's shape, beneath headings and content, for example to keep overlaid text readable. Exported as a native shape above the picture.
+         */
+        overlay?: {
+            /**
+             * Overlay fill color.
+             */
+            color: (HexColor | ("accent1" | "accent2" | "accent3" | "accent4" | "accent5" | "accent6" | "dark1" | "dark2" | "light1" | "light2" | "hyperlink" | "followedHyperlink" | "primary" | "secondary" | "accent" | "background" | "surface" | "text" | "textSecondary") | string);
+            /**
+             * Overlay fill opacity.
+             */
+            opacity: number;
+            /**
+             * Cover only a band along this edge of the frame, for example a caption strip. Rectangle frames only; other shapes report unsupported-image-treatment and draw no overlay. Omit to cover the whole frame.
+             */
+            edge?: ("top" | "bottom" | "left" | "right");
+            /**
+             * Band share of the frame for an edge overlay. Default 0.3.
+             */
+            size?: number;
+        };
     });
     /**
      * Axis along which parallel body/content regions are arranged.
@@ -1031,7 +1145,7 @@ interface ColorScheme {
  *
  * 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 (heading, body, accent, code) - OPF-specific Font objects the engine maps onto the OOXML pair when serializing. Convenient for inline overrides and for adding accent/code roles that don't have a direct OOXML slot; not part of the catalog record schema.
+ * - Abstract roles (heading, body, accent, code) - OPF-specific Font objects the engine maps onto the OOXML pair when serializing. Convenient for inline overrides and for adding accent/code roles that don't have a direct OOXML slot. Catalog records may also carry 'code' (for example the consolas and courier-new records); heading, body and accent are not part of the catalog record schema.
  *
  * In design.fontScheme, 'id' resolves a fontSchemes catalog record as the base; pair and role overrides on the same object take precedence over the resolved scheme. The string shorthand on design.fontScheme is equivalent to setting only 'id'.
  *
@@ -1053,6 +1167,32 @@ interface FontScheme {
      * Body (minor) font family — mirrors the OOXML minorFont entry. Pairs with 'major'.
      */
     minor?: string;
+    /**
+     * East Asian script fonts. Maps to the OOXML a:ea element of majorFont (major) and minorFont (minor), and to run-level a:ea. When set, they fill the eastAsian slot for every language; when omitted, the slot comes from this scheme's own major/minor when languageFamily is 'ea' and the scheme's languages list is empty or names the presentation language, then from the presentation language's font scheme for East Asian languages, and otherwise from the latin (major/minor) families. A missing 'major' or 'minor' falls back to the other.
+     */
+    eastAsian?: {
+        /**
+         * Heading (major) eastAsian font family — mirrors majorFont a:ea.
+         */
+        major?: string;
+        /**
+         * Body (minor) eastAsian font family — mirrors minorFont a:ea.
+         */
+        minor?: string;
+    };
+    /**
+     * Complex-script fonts (for example Arabic, Hebrew, Indic and Thai). Maps to the OOXML a:cs element of majorFont (major) and minorFont (minor), and to run-level a:cs. When set, they fill the complexScript slot for every language; when omitted, the slot comes from this scheme's own major/minor when languageFamily is 'cs' and the scheme's languages list is empty or names the presentation language, then from the presentation language's font scheme for complex-script languages, and otherwise from the latin (major/minor) families. A missing 'major' or 'minor' falls back to the other.
+     */
+    complexScript?: {
+        /**
+         * Heading (major) complexScript font family — mirrors majorFont a:cs.
+         */
+        major?: string;
+        /**
+         * Body (minor) complexScript font family — mirrors minorFont a:cs.
+         */
+        minor?: string;
+    };
     /**
      * High-level typographic class of the scheme.
      */
@@ -1062,7 +1202,7 @@ interface FontScheme {
      */
     app?: ("PowerPoint" | "Google Slides");
     /**
-     * OOXML font-language family this scheme is intended for: 'latin' for Latin-script content, 'ea' for East Asian scripts, 'cs' for Complex Scripts.
+     * OOXML font-language family this scheme is intended for: 'latin' for Latin-script content, 'ea' for East Asian scripts, 'cs' for Complex Scripts. As the design font scheme, an 'ea' or 'cs' scheme also fills that script slot with its own major/minor families when its languages list is empty or names the presentation language.
      */
     languageFamily?: ("latin" | "ea" | "cs");
     heading?: Font;
@@ -1138,7 +1278,7 @@ interface Font2 {
     [k: string]: unknown;
 }
 /**
- * Abstract role: monospaced font used for code blocks. No direct OOXML slot.
+ * Abstract role: monospaced font used for code blocks and inline code. No direct OOXML slot. Resolution: this override, then the resolved catalog record's 'code' (for example Consolas for the consolas scheme), then the engine fallback Roboto Mono. Heading and body families are never used as the code fallback.
  */
 interface Font3 {
     /**
@@ -1284,7 +1424,7 @@ interface PatternBackground {
      */
     pattern: {
         /**
-         * Pattern preset or engine-defined pattern id.
+         * Pattern preset or engine-defined pattern id. DrawingML preset names (ECMA-376 ST_PresetPatternVal, for example pct5, ltHorz, wdUpDiag) are portable: PPTX export writes them as native pattern fills and import returns the same name. Engine-defined ids are renderer-specific; the legacy preview id diagStripe remains accepted and exports as wdUpDiag.
          */
         preset: string;
         /**
@@ -1743,13 +1883,21 @@ interface HeaderFooterItem {
         format?: string;
     });
     /**
-     * Whether to render the current slide number in this zone.
+     * Whether to render the current slide number in this zone. PPTX export writes a native slide-number field when its value fits within one accepted text line; a value split across lines exports as static text with a diagnostic.
      */
     slideNumber?: boolean;
     /**
-     * Whether to render the presentation date, or a literal date string to render.
+     * Template for the slide number when slideNumber is true. {current} is the displayed slide number (a native PPTX field when its value fits within one accepted text line); {total} is the number of slides in the rendered or exported deck, written as fixed text because PowerPoint has no slide-count field. Other characters are literal. Defaults to "{current}".
+     */
+    slideNumberFormat?: string;
+    /**
+     * true renders the current date: the renderer or exporter must be given an explicit ISO date by its host (core never reads a clock). PPTX export writes a native date field only for a supported dateFormat whose complete value fits within one accepted text line; otherwise it writes static text with a diagnostic. Native PowerPoint refresh and save/reopen compatibility require separate verification. A string is fixed: with dateFormat it must be an ISO YYYY-MM-DD date and is formatted; without dateFormat it is literal text rendered as written.
      */
     date?: (boolean | string);
+    /**
+     * Date pattern for date. Tokens: yyyy (2026), yy (26), MMMM (April), MMM (Apr), MM (04), M (4), dd (09), d (9), EEEE (Thursday), EEE (Thu). Text in single quotes and other non-letter characters are literal. Month and weekday names are English, independent of host locale. Defaults to "M/d/yyyy" for a current date. PPTX export writes a native current-date field only when its complete value fits within one accepted text line and the pattern matches a PowerPoint en-US date field ('M/d/yyyy'; 'EEEE, MMMM d, yyyy'; 'd MMMM yyyy'; 'MMMM d, yyyy'; 'd-MMM-yy'; 'MMMM yy'; 'MMM-yy'). Other patterns and wrapped fields export as static text with a diagnostic. Full provenance can recover generated-date intent from unchanged supported wrapped dates on OPF reimport; the existing PPTX text remains static.
+     */
+    dateFormat?: string;
     /**
      * Whether to render the primary organization name from organization.
      */
@@ -1758,6 +1906,10 @@ interface HeaderFooterItem {
      * Whether to render the current slide section label.
      */
     section?: boolean;
+    /**
+     * Whether to render the primary organization's social profiles from organization.socials, one line per platform in key order. A handle is formatted through the platform's socialPlatforms record (companyUrlPattern, else profileUrlPattern, else baseUrl, with handlePrefix stripped) and shown as that profile URL without its 'https://' scheme; a value that is already a URL is shown without an 'https://' scheme; an unknown platform key shows the raw value. Exporters link each line to its full URL when one exists. Speaker socials are not rendered by this field.
+     */
+    socials?: boolean;
     [k: string]: unknown;
 }
 /**
@@ -1798,13 +1950,21 @@ interface HeaderFooterItem1 {
         format?: string;
     });
     /**
-     * Whether to render the current slide number in this zone.
+     * Whether to render the current slide number in this zone. PPTX export writes a native slide-number field when its value fits within one accepted text line; a value split across lines exports as static text with a diagnostic.
      */
     slideNumber?: boolean;
     /**
-     * Whether to render the presentation date, or a literal date string to render.
+     * Template for the slide number when slideNumber is true. {current} is the displayed slide number (a native PPTX field when its value fits within one accepted text line); {total} is the number of slides in the rendered or exported deck, written as fixed text because PowerPoint has no slide-count field. Other characters are literal. Defaults to "{current}".
+     */
+    slideNumberFormat?: string;
+    /**
+     * true renders the current date: the renderer or exporter must be given an explicit ISO date by its host (core never reads a clock). PPTX export writes a native date field only for a supported dateFormat whose complete value fits within one accepted text line; otherwise it writes static text with a diagnostic. Native PowerPoint refresh and save/reopen compatibility require separate verification. A string is fixed: with dateFormat it must be an ISO YYYY-MM-DD date and is formatted; without dateFormat it is literal text rendered as written.
      */
     date?: (boolean | string);
+    /**
+     * Date pattern for date. Tokens: yyyy (2026), yy (26), MMMM (April), MMM (Apr), MM (04), M (4), dd (09), d (9), EEEE (Thursday), EEE (Thu). Text in single quotes and other non-letter characters are literal. Month and weekday names are English, independent of host locale. Defaults to "M/d/yyyy" for a current date. PPTX export writes a native current-date field only when its complete value fits within one accepted text line and the pattern matches a PowerPoint en-US date field ('M/d/yyyy'; 'EEEE, MMMM d, yyyy'; 'd MMMM yyyy'; 'MMMM d, yyyy'; 'd-MMM-yy'; 'MMMM yy'; 'MMM-yy'). Other patterns and wrapped fields export as static text with a diagnostic. Full provenance can recover generated-date intent from unchanged supported wrapped dates on OPF reimport; the existing PPTX text remains static.
+     */
+    dateFormat?: string;
     /**
      * Whether to render the primary organization name from organization.
      */
@@ -1813,6 +1973,10 @@ interface HeaderFooterItem1 {
      * Whether to render the current slide section label.
      */
     section?: boolean;
+    /**
+     * Whether to render the primary organization's social profiles from organization.socials, one line per platform in key order. A handle is formatted through the platform's socialPlatforms record (companyUrlPattern, else profileUrlPattern, else baseUrl, with handlePrefix stripped) and shown as that profile URL without its 'https://' scheme; a value that is already a URL is shown without an 'https://' scheme; an unknown platform key shows the raw value. Exporters link each line to its full URL when one exists. Speaker socials are not rendered by this field.
+     */
+    socials?: boolean;
     [k: string]: unknown;
 }
 /**
@@ -1853,13 +2017,21 @@ interface HeaderFooterItem2 {
         format?: string;
     });
     /**
-     * Whether to render the current slide number in this zone.
+     * Whether to render the current slide number in this zone. PPTX export writes a native slide-number field when its value fits within one accepted text line; a value split across lines exports as static text with a diagnostic.
      */
     slideNumber?: boolean;
     /**
-     * Whether to render the presentation date, or a literal date string to render.
+     * Template for the slide number when slideNumber is true. {current} is the displayed slide number (a native PPTX field when its value fits within one accepted text line); {total} is the number of slides in the rendered or exported deck, written as fixed text because PowerPoint has no slide-count field. Other characters are literal. Defaults to "{current}".
+     */
+    slideNumberFormat?: string;
+    /**
+     * true renders the current date: the renderer or exporter must be given an explicit ISO date by its host (core never reads a clock). PPTX export writes a native date field only for a supported dateFormat whose complete value fits within one accepted text line; otherwise it writes static text with a diagnostic. Native PowerPoint refresh and save/reopen compatibility require separate verification. A string is fixed: with dateFormat it must be an ISO YYYY-MM-DD date and is formatted; without dateFormat it is literal text rendered as written.
      */
     date?: (boolean | string);
+    /**
+     * Date pattern for date. Tokens: yyyy (2026), yy (26), MMMM (April), MMM (Apr), MM (04), M (4), dd (09), d (9), EEEE (Thursday), EEE (Thu). Text in single quotes and other non-letter characters are literal. Month and weekday names are English, independent of host locale. Defaults to "M/d/yyyy" for a current date. PPTX export writes a native current-date field only when its complete value fits within one accepted text line and the pattern matches a PowerPoint en-US date field ('M/d/yyyy'; 'EEEE, MMMM d, yyyy'; 'd MMMM yyyy'; 'MMMM d, yyyy'; 'd-MMM-yy'; 'MMMM yy'; 'MMM-yy'). Other patterns and wrapped fields export as static text with a diagnostic. Full provenance can recover generated-date intent from unchanged supported wrapped dates on OPF reimport; the existing PPTX text remains static.
+     */
+    dateFormat?: string;
     /**
      * Whether to render the primary organization name from organization.
      */
@@ -1868,8 +2040,18 @@ interface HeaderFooterItem2 {
      * Whether to render the current slide section label.
      */
     section?: boolean;
+    /**
+     * Whether to render the primary organization's social profiles from organization.socials, one line per platform in key order. A handle is formatted through the platform's socialPlatforms record (companyUrlPattern, else profileUrlPattern, else baseUrl, with handlePrefix stripped) and shown as that profile URL without its 'https://' scheme; a value that is already a URL is shown without an 'https://' scheme; an unknown platform key shows the raw value. Exporters link each line to its full URL when one exists. Speaker socials are not rendered by this field.
+     */
+    socials?: boolean;
     [k: string]: unknown;
 }
+/**
+ * Optional named color variables for values the deck uses in more than one place or wants to name for intent (e.g. a risk red, a brand highlight). Content color fields reference entries as 'var:<id>' strings. Variables complement the color scheme: scheme slots and roles stay the primary vocabulary; variables cover deck-specific named colors that have no scheme slot.
+ */
+interface Variables {
+    [k: string]: Variable;
+}
 /**
  * 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.
  *
@@ -2188,13 +2370,19 @@ interface Slide {
      */
     hidden?: boolean;
     composition?: Composition1;
+    /**
+     * Custom data passthrough for agent workflows at slide scope; ignored by the engine but preserved across read/write round-trips. Use for review state, generation provenance, or authoring conventions such as { "authoring": { "locked": true } }.
+     */
+    extensions?: {
+        [k: string]: unknown;
+    };
 }
 /**
  * Full-slide chart payload. Presence of this field infers type 'chart'.
  */
 interface Chart {
     /**
-     * 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.
+     * 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. The bundled catalog covers the chart types Aspose.Slides officially supports; deprecated ids still resolve but validate with a warning naming their replacement.
      */
     type: string;
     /**
@@ -2288,13 +2476,13 @@ interface StyledTableCell {
  */
 interface TableCellStyle {
     /**
-     * Explicit RGB or RGBA color. Eight-digit colors include alpha; #00000000 is transparent.
+     * Cell background: a hex color, a color-scheme slot or role name, or a 'var:<id>' variable reference. Eight-digit hex colors include alpha; #00000000 is transparent.
      */
-    fill?: string;
+    fill?: (HexColor | ("accent1" | "accent2" | "accent3" | "accent4" | "accent5" | "accent6" | "dark1" | "dark2" | "light1" | "light2" | "hyperlink" | "followedHyperlink" | "primary" | "secondary" | "accent" | "background" | "surface" | "text" | "textSecondary") | string);
     /**
-     * Default text color, overridden by individual rich run colors.
+     * Default text color, overridden by individual rich run colors. Accepts a hex color, a color-scheme slot or role name, or a 'var:<id>' variable reference.
      */
-    color?: string;
+    color?: (HexColor | ("accent1" | "accent2" | "accent3" | "accent4" | "accent5" | "accent6" | "dark1" | "dark2" | "light1" | "light2" | "hyperlink" | "followedHyperlink" | "primary" | "secondary" | "accent" | "background" | "surface" | "text" | "textSecondary") | string);
     /**
      * Horizontal text alignment inside the cell.
      */
@@ -2334,9 +2522,9 @@ interface TableCellPadding {
  */
 interface TableCellBorder {
     /**
-     * Explicit RGB or RGBA color. Eight-digit colors include alpha; #00000000 is transparent.
+     * Border color: a hex color, a color-scheme slot or role name, or a 'var:<id>' variable reference. Eight-digit hex colors include alpha; #00000000 is transparent.
      */
-    color: string;
+    color: (HexColor | ("accent1" | "accent2" | "accent3" | "accent4" | "accent5" | "accent6" | "dark1" | "dark2" | "light1" | "light2" | "hyperlink" | "followedHyperlink" | "primary" | "secondary" | "accent" | "background" | "surface" | "text" | "textSecondary") | string);
     /**
      * Border width in reference pixels; 0 removes this edge.
      */
@@ -2443,7 +2631,7 @@ interface TimelineEvent {
  */
 interface Chart1 {
     /**
-     * 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.
+     * 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. The bundled catalog covers the chart types Aspose.Slides officially supports; deprecated ids still resolve but validate with a warning naming their replacement.
      */
     type: string;
     /**
@@ -2567,7 +2755,7 @@ interface Design1 {
      */
     contentBox?: boolean;
     /**
-     * Optional slide-level image treatment used by layouts that support a decorative or editorial image separate from content images.
+     * Optional slide-level image, separate from content images. It applies to a slide that sets its own design.slideImage, and to slides whose layout declares slideImage: true or whose root image is the same source as a deck-level value. A root image with the same source becomes the slide image instead of a content item. Blur, shadows, soft edges, background removal and device artwork are not part of the treatment vocabulary; see docs/image-treatments.md.
      */
     slideImage?: (Asset | {
         /**
@@ -2575,9 +2763,88 @@ interface Design1 {
          */
         src?: string;
         /**
-         * Where the slide-level image sits relative to the content. 'background' is a full-bleed image behind the content.
+         * Where the slide-level image sits relative to the content. 'background' is a full-bleed image behind the content. The other positions give the image a band along that edge (see size) and compose headings and content in the rest of the slide.
          */
         position: ("background" | "top" | "bottom" | "left" | "right");
+        /**
+         * Alternative text for the slide-level image. Overrides the alt text of a referenced asset.
+         */
+        alt?: string;
+        /**
+         * How the image fills its frame: 'crop' covers the frame from the center; 'fit' shows the whole image centered inside it. Overrides design.imageFill for this image. Default: design.imageFill, else 'crop'.
+         */
+        fill?: ("crop" | "fit");
+        /**
+         * Share of the slide width (left/right) or height (top/bottom) given to the image band. Ignored for 'background'. Default 0.5.
+         */
+        size?: number;
+        /**
+         * Place the frame inside the slide padding instead of edge to edge, like a card. Default false.
+         */
+        inset?: boolean;
+        /**
+         * Width-to-height ratio of the frame. The frame becomes the largest centered box with this ratio inside the band or slide, for example 2.39 for a cinematic letterbox or 0.5 for a phone-shaped frame. 'circle' always uses 1.
+         */
+        aspectRatio?: number;
+        /**
+         * Mask applied to the frame, exported as the picture's native preset geometry (rect, roundRect, ellipse, hexagon). 'circle' makes the frame square. Default 'rectangle'.
+         */
+        shape?: ("rectangle" | "rounded" | "circle" | "hexagon");
+        /**
+         * Corner radius for shape 'rounded' as a fraction of the frame's shorter side. Default 0.16667, PowerPoint's roundRect default.
+         */
+        cornerRadius?: number;
+        /**
+         * Solid line along the frame's shape. A thick dark border on a rounded portrait frame gives a device bezel.
+         */
+        border?: {
+            /**
+             * Line color: a hex color, a color-scheme slot or role name, or a 'var:<id>' variable reference.
+             */
+            color: (HexColor | ("accent1" | "accent2" | "accent3" | "accent4" | "accent5" | "accent6" | "dark1" | "dark2" | "light1" | "light2" | "hyperlink" | "followedHyperlink" | "primary" | "secondary" | "accent" | "background" | "surface" | "text" | "textSecondary") | string);
+            /**
+             * Line width in reference pixels at a 720-pixel short edge, centered on the frame outline like a native picture line. 0 removes the line.
+             */
+            width: number;
+        };
+        /**
+         * Image opacity from 0 to 1, exported as a native alphaModFix. The border and overlay keep their own opacity. Default 1.
+         */
+        opacity?: number;
+        /**
+         * Color treatment for the image pixels. Luminance uses Rec. 601 weights (0.299, 0.587, 0.114) on sRGB values.
+         */
+        recolor?: ("grayscale" | {
+            /**
+             * Color at luminance 0.
+             */
+            dark: (HexColor | ("accent1" | "accent2" | "accent3" | "accent4" | "accent5" | "accent6" | "dark1" | "dark2" | "light1" | "light2" | "hyperlink" | "followedHyperlink" | "primary" | "secondary" | "accent" | "background" | "surface" | "text" | "textSecondary") | string);
+            /**
+             * Color at luminance 1.
+             */
+            light: (HexColor | ("accent1" | "accent2" | "accent3" | "accent4" | "accent5" | "accent6" | "dark1" | "dark2" | "light1" | "light2" | "hyperlink" | "followedHyperlink" | "primary" | "secondary" | "accent" | "background" | "surface" | "text" | "textSecondary") | string);
+        });
+        /**
+         * Solid scrim drawn over the image in the frame's shape, beneath headings and content, for example to keep overlaid text readable. Exported as a native shape above the picture.
+         */
+        overlay?: {
+            /**
+             * Overlay fill color.
+             */
+            color: (HexColor | ("accent1" | "accent2" | "accent3" | "accent4" | "accent5" | "accent6" | "dark1" | "dark2" | "light1" | "light2" | "hyperlink" | "followedHyperlink" | "primary" | "secondary" | "accent" | "background" | "surface" | "text" | "textSecondary") | string);
+            /**
+             * Overlay fill opacity.
+             */
+            opacity: number;
+            /**
+             * Cover only a band along this edge of the frame, for example a caption strip. Rectangle frames only; other shapes report unsupported-image-treatment and draw no overlay. Omit to cover the whole frame.
+             */
+            edge?: ("top" | "bottom" | "left" | "right");
+            /**
+             * Band share of the frame for an edge overlay. Default 0.3.
+             */
+            size?: number;
+        };
     });
     /**
      * Axis along which parallel body/content regions are arranged.

package/dist/repo-readme.js

@@ -1,5 +1,5 @@
 // src/generated/repo-readme.ts
-var repoReadmeRaw = '# Open Presentation Format (OPF)\n\n[![npm version](https://img.shields.io/npm/v/@openpresentation/opf?label=npm)](https://www.npmjs.com/package/@openpresentation/opf)\n[![npm downloads](https://img.shields.io/npm/dw/@openpresentation/opf)](https://www.npmjs.com/package/@openpresentation/opf)\n[![license](https://img.shields.io/npm/l/@openpresentation/opf)](./LICENSE)\n\nPublic npm package: [`@openpresentation/opf`](https://www.npmjs.com/package/@openpresentation/opf) (`npm install @openpresentation/opf`).\n\nOpen Presentation Format is the portable, human-readable JSON document format for slide decks.\n\nThis repository is the canonical home for the OPF **spec**, **JSON Schemas**, **catalog presets**, examples, generated developer types, local validation tooling, and planning docs for the future render/edit/convert toolkit. OpenPresentation publishes open-source code and documentation only; it does not provide hosted APIs, hosted rendering functions, queues, storage, authentication, jobs, previews, SLAs, telemetry, or managed infrastructure.\n\nFor AI agents, use the [OPF skill set](docs/agent-skills.md) for authoring, layout, presets, editing, export, and schema inspection.\n\nCLI 0.5.0 installs all six skills into your project with `npx @openpresentation/cli@latest skills install`. It uses local copies, preserves existing instructions and refuses to overwrite customized skills. See the [installation and update guide](docs/agent-skills.md) for personal or agent-specific targets and pre-release testing.\n\nFor LLM authoring, start with [the authoring guide](docs/llm-authoring.md), [dynamic composition](docs/dynamic-composition.md), and [local ecosystem verification](docs/ecosystem-development.md).\n\n## File naming\n\nOpen Presentation Format documents are JSON files. Use `*.opf.json` for complete OPF presentation documents, for example `board-review.opf.json` or `deck.opf.json`.\n\nAvoid using bare `*.opf` for OPF JSON. The `.opf` extension is already used by other document and project formats, while `.opf.json` keeps the OPF identity and still makes the underlying JSON format clear to editors, validators, agents, and version-control tooling.\n\n## Naming and reuse\n\nThe format name is **Open Presentation Format**. The schemas, catalogs, packages, and local tooling in this repository are free and open source under the MIT license, so third-party tools may read, write, validate, render, convert, and describe support for Open Presentation Format without adopting any product-specific branding.\n\n## Why OPF\n\n`.pptx` is a zipped bundle of XML. Humans can\'t diff it, LLMs can\'t read or write it reliably, and git can\'t track it meaningfully. Every change looks like a binary blob.\n\nOPF is plain JSON. A human can open it in an editor. A model can read and write it without guessing at schema-by-example. Decks live in git like the rest of your work.\n\nThat\'s the shift that lets LLMs actually *author* decks. When the format stops fighting them, models can do the work that matters \u2014 narrative structure, persuasive framing, data analysis, chart recommendations, ruthless revision passes \u2014 instead of wrestling with `<p:sp>` tags.\n\nAnd they don\'t start from a blank canvas. [pptx.gallery](https://pptx.gallery) is the human-browsable reference for OPF catalog presets: layouts, themes, color schemes, font schemes, chart types, narratives, audiences, purposes, tones, languages, and social platforms.\n\n## Start in three steps\n\n1. **Install the format package.** `npm install @openpresentation/opf`.\n2. **Author and validate a deck.** Write a `*.opf.json` file \u2014 start from [`docs/how-opf-works.md`](./docs/how-opf-works.md) or copy [`examples/technical/full-feature-tour.opf.json`](./examples/technical/full-feature-tour.opf.json) \u2014 and run `validatePresentation` on it.\n3. **Build on it.** Browse presets at [pptx.gallery](https://pptx.gallery), pin the schemas in your pipeline, and track the [toolkit libraries](#toolkit-libraries) for the render and convert libraries.\n\nYour deck lives in git from the first commit. Nothing in these steps calls a hosted service, and nothing ever will \u2014 that boundary is the point.\n\n## JavaScript and TypeScript\n\nThe canonical JavaScript/TypeScript package is published at [`packages/javascript`](./packages/javascript) as [`@openpresentation/opf`](https://www.npmjs.com/package/@openpresentation/opf). The schema is pre-stable (0.x \u2014 expect breaking changes between minor versions until 1.0). Its responsibility is local and format-level only:\n\n- export the canonical schemas from [`spec/`](./spec)\n- export bundled catalog records from [`spec/`](./spec)\n- export a typed raw spec file manifest for package-addressable `spec/` content\n- generate TypeScript types, with `Presentation` as the top-level type\n- validate OPF JSON and catalog records locally\n\nIt does not render `.pptx`, parse `.pptx`, generate content with AI, fetch remote catalogs, call hosted APIs, or provide managed services. Render/edit/convert packages live in separate MIT repos that depend on `@openpresentation/opf`. The format package also exposes pure composition geometry so those packages share layout behavior.\n\n## Toolkit libraries\n\nThe local toolkit lives in sibling repositories. See [ecosystem development](docs/ecosystem-development.md) for coordinated builds and verification, and [dynamic composition](docs/dynamic-composition.md) for portable layout rules.\n\n| Repo | Role | Boundary |\n|---|---|---|\n| `opf-render` | OPF to SVG/PNG/PDF | Local and embeddable rendering library |\n| `opf-editor` | WYSIWYG bindings/components | Headless editor primitives plus optional UI components |\n| `opf-pptx` | OPF to PPTX and PPTX to OPF | Pure local import/export library for browser and server use where supported |\n\nThese repos provide OSS primitives only. Downstream applications own hosting, auth, storage, collaboration, queues, previews, analytics, support, and workflow UX.\n\n## Usage\n\nInstall from npm:\n\n```sh\npnpm add @openpresentation/opf\n# or: npm install @openpresentation/opf\n```\n\nTo work on the package itself, clone this repo and build the workspace:\n\n```sh\npnpm install\npnpm build\n```\n\nUse the format package from JavaScript or TypeScript:\n\n```ts\nimport {\n  presentation,\n  audiences,\n  purposes,\n  tones,\n  validatePresentation,\n} from "@openpresentation/opf";\n\nimport type { Presentation } from "@openpresentation/opf";\n\nconst deck: Presentation = {\n  name: "Quarterly Review",\n  slides: [{ title: "Quarterly Review", items: ["Revenue", "Product", "Hiring"] }],\n};\n\nconst result = validatePresentation(deck);\nconsole.log(result.valid); // schema correctness\nconsole.log(result.warnings); // advisory issues, e.g. unknown catalog ids\nconsole.log(audiences.length, purposes.length, tones.length);\n```\n\nUse focused imports when you only need one surface:\n\n```ts\nimport { presentation } from "@openpresentation/opf/schemas";\nimport { audiences, purposes } from "@openpresentation/opf/catalogs";\nimport { specFileEntries } from "@openpresentation/opf/spec-files";\nimport { validate } from "@openpresentation/opf/validator";\nimport type { Presentation } from "@openpresentation/opf/types";\n```\n\nUse raw JSON when an engine or resolver needs package-addressable files:\n\n```ts\nimport presentationSchema from "@openpresentation/opf/spec/schemas/opf.schema.json" with {\n  type: "json",\n};\n```\n\nUse the [installable OPF CLI](./packages/cli/README.md) to create, validate, and edit files locally:\n\n```sh\npnpm --filter @openpresentation/cli build\nnode packages/cli/dist/index.js create deck.opf.json --title "Decision brief"\nnode packages/cli/dist/index.js validate deck.opf.json\nnode packages/cli/dist/index.js edit deck.opf.json --patch changes.json --in-place\n```\n\nSee [CSV and JSON data import](./docs/data-import.md) for editable tables and charts in the editor, CLI, and package API.\n\n## Layout\n\n| Path | Contents |\n|---|---|\n| [`spec/schemas/opf.schema.json`](./spec/schemas/opf.schema.json) | Canonical JSON Schema for top-level OPF `Presentation` documents. |\n| [`docs/how-opf-works.md`](./docs/how-opf-works.md) | Conceptual introduction: the document model, content shapes, catalog resolution, and the validation philosophy. Start here. |\n| [`docs/design-resolution.md`](./docs/design-resolution.md) | The design precedence algorithm (slide design \u2192 deck design \u2192 resolved theme \u2192 engine defaults) with worked examples. |\n| [`docs/schema-reference.md`](./docs/schema-reference.md) | Author-facing reference for top-level OPF fields and every presentation schema `$defs` object/type. |\n| [`docs/catalog-schema-reference.md`](./docs/catalog-schema-reference.md) | Author-facing reference for every companion catalog schema. |\n| [`docs/content-payloads.md`](./docs/content-payloads.md) | Author-facing notes for slide and region content payloads, including chart and table object shapes. |\n| [`docs/examples.md`](./docs/examples.md) | Guide to the expanded scenario-oriented examples under `examples/gallery/`. |\n| [`docs/live-editor.md`](./docs/live-editor.md) | Browser canvas, live OPF editing, font loading, installable preview packages, and current fidelity limits. |\n| [`docs/release-process.md`](./docs/release-process.md) | Maintainer runbook for tagging, trusted npm publishing, verification, and GitHub release notes. |\n| [`spec/schemas/*.schema.json`](./spec/schemas) | Companion schemas for catalog records and sub-objects. |\n| [`spec/catalogs/<catalog-kind>/`](./spec/catalogs) | Canonical bundled catalog records. |\n| [`spec/openapi.yaml`](./spec/openapi.yaml) | Optional reference OpenAPI contract for downstream services that choose to expose OPF over HTTP. OpenPresentation does not host this API. |\n| [`examples/technical/`](./examples/technical) | Focused OPF fixtures for validator, renderer, catalog-resolution, design, content-payload, and region behavior. |\n| [`examples/gallery/`](./examples/gallery) | Broader OPF example decks organized by industry, function, education, government, presentation type, international, and design/media scenarios. |\n| [`packages/javascript/`](./packages/javascript) | Public pre-stable source for `@openpresentation/opf`. |\n| [`packages/cli/`](./packages/cli) | Installable local CLI for creating, validating, editing, and inspecting OPF. |\n| [`legacy/`](./legacy) | Tombstone for service-specific clients, CLIs, tool integrations, and workflows removed from the OpenPresentation OSS repo. |\n\n## OpenPresentation Boundary\n\nOpenPresentation defines the format, bundled presets, local validation, examples, docs, and planned local render/edit/convert libraries. It does not provide hosted functions or managed product surfaces.\n\nFuture non-JavaScript OPF packages should follow the same local-first boundary: Python and Go packages should expose schemas, types/models, catalogs, validation, and package-addressable assets. Future toolkit packages should expose embeddable library APIs with no required network calls, hosted callbacks, hidden telemetry, or managed infrastructure assumptions.\n\nThe published JavaScript package copies package-addressable OPF schemas, catalogs, reference assets, and the optional reference `spec/openapi.yaml` from `spec/`. It intentionally remains `@openpresentation/opf` instead of introducing a separate `@openpresentation/opf-spec` package so downstream imports can advance by semver-pinning one canonical package.\n\n## License\n\nMIT. See [LICENSE](./LICENSE).\n';
+var repoReadmeRaw = '# Open Presentation Format (OPF)\n\n[![npm version](https://img.shields.io/npm/v/@openpresentation/opf?label=npm)](https://www.npmjs.com/package/@openpresentation/opf)\n[![npm downloads](https://img.shields.io/npm/dw/@openpresentation/opf)](https://www.npmjs.com/package/@openpresentation/opf)\n[![license](https://img.shields.io/npm/l/@openpresentation/opf)](./LICENSE)\n\nPublic npm package: [`@openpresentation/opf`](https://www.npmjs.com/package/@openpresentation/opf) (`npm install @openpresentation/opf`).\n\nOpen Presentation Format is the portable, human-readable JSON document format for slide decks.\n\nThis repository is the canonical home for the OPF **spec**, **JSON Schemas**, **catalog presets**, examples, generated developer types, local validation tooling, and integration docs for the render/edit/convert toolkit. OpenPresentation publishes open-source code and documentation only; it does not provide hosted APIs, hosted rendering functions, queues, storage, authentication, jobs, previews, SLAs, telemetry, or managed infrastructure.\n\nFor AI agents, use the [OPF skill set](docs/agent-skills.md) for authoring, layout, presets, editing, export, and schema inspection.\n\nPublished CLI 0.9.0 installs all six skills into your project with `npx @openpresentation/cli@0.9.0 skills install`. It uses local copies, preserves existing instructions and refuses to overwrite customized skills. See the [installation and update guide](docs/agent-skills.md) for personal or agent-specific targets and source development.\n\nFor a fresh Node 24 project that installs **published** packages (not this\ncheckout), follow the [developer quickstart](docs/quickstart.md) and the\n[compatibility matrix](docs/compatibility-matrix.md).\n\nFor LLM authoring, start with [the authoring guide](docs/llm-authoring.md), [dynamic composition](docs/dynamic-composition.md), and [local ecosystem verification](docs/ecosystem-development.md).\n\n## File naming\n\nOpen Presentation Format documents are JSON files. Use `*.opf.json` for complete OPF presentation documents, for example `board-review.opf.json` or `deck.opf.json`.\n\nAvoid using bare `*.opf` for OPF JSON. The `.opf` extension is already used by other document and project formats, while `.opf.json` keeps the OPF identity and still makes the underlying JSON format clear to editors, validators, agents, and version-control tooling.\n\n## Naming and reuse\n\nThe format name is **Open Presentation Format**. The schemas, catalogs, packages, and local tooling in this repository are free and open source under the MIT license, so third-party tools may read, write, validate, render, convert, and describe support for Open Presentation Format without adopting any product-specific branding.\n\n## Why OPF\n\n`.pptx` is a zipped bundle of XML. Humans can\'t diff it, LLMs can\'t read or write it reliably, and git can\'t track it meaningfully. Every change looks like a binary blob.\n\nOPF is plain JSON. A human can open it in an editor. A model can read and write it without guessing at schema-by-example. Decks live in git like the rest of your work.\n\nThat\'s the shift that lets LLMs actually *author* decks. When the format stops fighting them, models can do the work that matters \u2014 narrative structure, persuasive framing, data analysis, chart recommendations, ruthless revision passes \u2014 instead of wrestling with `<p:sp>` tags.\n\nAnd they don\'t start from a blank canvas. [pptx.gallery](https://pptx.gallery) is the human-browsable reference for OPF catalog presets: layouts, themes, color schemes, font schemes, chart types, narratives, audiences, purposes, tones, languages, and social platforms.\n\n## Start in three steps\n\n1. **Install the coordinated published packages** on Node 24. See [the developer quickstart](docs/quickstart.md) for the current pin set: core 0.11.0, renderer 0.9.0, editor 0.8.0, PPTX 0.9.1 and CLI 0.9.0.\n2. **Author, lint, paginate, preview and export.** Copy [`docs/quickstart/developer-quickstart.opf.json`](./docs/quickstart/developer-quickstart.opf.json) and run the commands in that guide. `validatePresentation` / `opf validate` is local schema checking, not visual verification.\n3. **Know the limits.** The [compatibility matrix](docs/compatibility-matrix.md) lists shipped APIs versus renderer issue 24, native PowerPoint issue 87, and other deferred work. Browse presets at [pptx.gallery](https://pptx.gallery).\n\nYour deck can live in git from the first commit. After installing dependencies and supplying referenced assets, these commands run locally without a model provider, account or hosted OPF API.\n\n## JavaScript and TypeScript\n\nThe canonical JavaScript/TypeScript package is published at [`packages/javascript`](./packages/javascript) as [`@openpresentation/opf`](https://www.npmjs.com/package/@openpresentation/opf). The schema is pre-stable (0.x \u2014 expect breaking changes between minor versions until 1.0). Its responsibility is local and format-level only:\n\n- export the canonical schemas from [`spec/`](./spec)\n- export bundled catalog records from [`spec/`](./spec)\n- export a typed raw spec file manifest for package-addressable `spec/` content\n- generate TypeScript types, with `Presentation` as the top-level type\n- validate OPF JSON and catalog records locally\n\nIt does not render `.pptx`, parse `.pptx`, generate content with AI, fetch remote catalogs, call hosted APIs, or provide managed services. Render/edit/convert packages live in separate MIT repos that depend on `@openpresentation/opf`. The format package also exposes pure composition geometry so those packages share layout behavior.\n\n## Toolkit libraries\n\nThe local toolkit lives in sibling repositories. See [ecosystem development](docs/ecosystem-development.md) for coordinated builds and verification, and [dynamic composition](docs/dynamic-composition.md) for portable layout rules.\n\n| Repo | Role | Boundary |\n|---|---|---|\n| `opf-render` | OPF to SVG/PNG/PDF | Local and embeddable rendering library |\n| `opf-editor` | WYSIWYG bindings/components | Headless editor primitives plus optional UI components |\n| `opf-pptx` | OPF to PPTX and PPTX to OPF | Pure local import/export library for browser and server use where supported |\n\nThese repos provide OSS primitives only. Downstream applications own hosting, auth, storage, collaboration, queues, previews, analytics, support, and workflow UX.\n\n## Usage\n\nInstall from npm:\n\n```sh\npnpm add @openpresentation/opf\n# or: npm install @openpresentation/opf\n```\n\nTo work on the package itself, clone this repo and build the workspace:\n\n```sh\npnpm install\npnpm build\n```\n\nUse the format package from JavaScript or TypeScript:\n\n```ts\nimport {\n  presentation,\n  audiences,\n  purposes,\n  tones,\n  validatePresentation,\n} from "@openpresentation/opf";\n\nimport type { Presentation } from "@openpresentation/opf";\n\nconst deck: Presentation = {\n  name: "Quarterly Review",\n  slides: [{ title: "Quarterly Review", items: ["Revenue", "Product", "Hiring"] }],\n};\n\nconst result = validatePresentation(deck);\nconsole.log(result.valid); // schema correctness\nconsole.log(result.warnings); // advisory issues, e.g. unknown catalog ids\nconsole.log(audiences.length, purposes.length, tones.length);\n```\n\nUse focused imports when you only need one surface:\n\n```ts\nimport { presentation } from "@openpresentation/opf/schemas";\nimport { audiences, purposes } from "@openpresentation/opf/catalogs";\nimport { specFileEntries } from "@openpresentation/opf/spec-files";\nimport { validate } from "@openpresentation/opf/validator";\nimport type { Presentation } from "@openpresentation/opf/types";\n```\n\nUse raw JSON when an engine or resolver needs package-addressable files:\n\n```ts\nimport presentationSchema from "@openpresentation/opf/spec/schemas/opf.schema.json" with {\n  type: "json",\n};\n```\n\nUse the [installable OPF CLI](./packages/cli/README.md) to create, validate, and edit files locally:\n\n```sh\npnpm --filter @openpresentation/cli build\nnode packages/cli/dist/index.js create deck.opf.json --title "Decision brief"\nnode packages/cli/dist/index.js validate deck.opf.json\nnode packages/cli/dist/index.js edit deck.opf.json --patch changes.json --in-place\n```\n\nSee [CSV and JSON data import](./docs/data-import.md) for editable tables and charts in the editor, CLI, and package API.\n\n## Layout\n\n| Path | Contents |\n|---|---|\n| [`spec/schemas/opf.schema.json`](./spec/schemas/opf.schema.json) | Canonical JSON Schema for top-level OPF `Presentation` documents. |\n| [`docs/how-opf-works.md`](./docs/how-opf-works.md) | Conceptual introduction: the document model, content shapes, catalog resolution, and the validation philosophy. Start here. |\n| [`docs/design-resolution.md`](./docs/design-resolution.md) | The design precedence algorithm (slide design \u2192 deck design \u2192 resolved theme \u2192 engine defaults) with worked examples. |\n| [`docs/schema-reference.md`](./docs/schema-reference.md) | Author-facing reference for top-level OPF fields and every presentation schema `$defs` object/type. |\n| [`docs/catalog-schema-reference.md`](./docs/catalog-schema-reference.md) | Author-facing reference for every companion catalog schema. |\n| [`docs/content-payloads.md`](./docs/content-payloads.md) | Author-facing notes for slide and region content payloads, including chart and table object shapes. |\n| [`docs/examples.md`](./docs/examples.md) | Guide to the expanded scenario-oriented examples under `examples/gallery/`. |\n| [`docs/live-editor.md`](./docs/live-editor.md) | Browser canvas, live OPF editing, font loading, published packages, and current fidelity limits. |\n| [`docs/release-process.md`](./docs/release-process.md) | Maintainer runbook for tagging, trusted npm publishing, verification, and GitHub release notes. |\n| [`spec/schemas/*.schema.json`](./spec/schemas) | Companion schemas for catalog records and sub-objects. |\n| [`spec/catalogs/<catalog-kind>/`](./spec/catalogs) | Canonical bundled catalog records. |\n| [`spec/openapi.yaml`](./spec/openapi.yaml) | Optional reference OpenAPI contract for downstream services that choose to expose OPF over HTTP. OpenPresentation does not host this API. |\n| [`examples/technical/`](./examples/technical) | Focused OPF fixtures for validator, renderer, catalog-resolution, design, content-payload, and region behavior. |\n| [`examples/gallery/`](./examples/gallery) | Broader OPF example decks organized by industry, function, education, government, presentation type, international, and design/media scenarios. |\n| [`packages/javascript/`](./packages/javascript) | Public pre-stable source for `@openpresentation/opf`. |\n| [`packages/cli/`](./packages/cli) | Installable local CLI for creating, validating, editing, and inspecting OPF. |\n| [`legacy/`](./legacy) | Tombstone for service-specific clients, CLIs, tool integrations, and workflows removed from the OpenPresentation OSS repo. |\n\n## OpenPresentation Boundary\n\nOpenPresentation defines the format, bundled presets, local validation, examples, docs, and planned local render/edit/convert libraries. It does not provide hosted functions or managed product surfaces.\n\nFuture non-JavaScript OPF packages should follow the same local-first boundary: Python and Go packages should expose schemas, types/models, catalogs, validation, and package-addressable assets. Future toolkit packages should expose embeddable library APIs with no required network calls, hosted callbacks, hidden telemetry, or managed infrastructure assumptions.\n\nThe published JavaScript package copies package-addressable OPF schemas, catalogs, reference assets, and the optional reference `spec/openapi.yaml` from `spec/`. It intentionally remains `@openpresentation/opf` instead of introducing a separate `@openpresentation/opf-spec` package so downstream imports can advance by semver-pinning one canonical package.\n\n## License\n\nMIT. See [LICENSE](./LICENSE).\n';
 
 // src/repo-readme.ts
 var repoReadme = repoReadmeRaw;