@openpresentation/opf 0.11.3 → 0.12.0

package/dist/{presentation-Cn6vTOCP.d.ts → presentation-DRx4hpNZ.d.ts}

@@ -278,25 +278,12 @@ type Asset = (string | {
     format?: string;
 });
 /**
- * A single named variable. A hex string is shorthand for { "type": "color", "value": value }.
+ * A single named variable: a hex string (shorthand for a color variable) or an object whose 'type' is color, text, number, date, image, url or list. 'value' is the current value and is optional: a variable with no value is unfilled, which a template allows and a normal deck does not. 'example' only illustrates the slot (fill forms, template previews) and never reaches output.
  *
  * 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;
-});
+type Variable = (HexColor | ColorVariable | TextVariable | NumberVariable | DateVariable | ImageVariable | UrlVariable | ListVariable);
 /**
  * A contiguous run of text. Strings cover unformatted spans; object form adds character formatting.
  *
@@ -348,6 +335,14 @@ type TextRun = (string | {
      * Whether the run is rendered as subscript.
      */
     subscript?: boolean;
+    /**
+     * One or more ids from the top-level references list that this run cites. Engines draw a superscript marker ('1', or '1,2' for several ids) directly after the run and list '<n> <reference text>' in the slide's footnote area; markers are numbered per deck in order of first use, and the same id keeps its number. An id missing from references is a validation error (cite-unknown-reference). Supported in text, bullets and list item runs.
+     */
+    cite?: (string | [string, ...(string)[]]);
+    /**
+     * An inline note for this run, without a references entry. Engines draw a superscript marker after the run and list the note in the slide's footnote area; every footnote takes a new number in the deck's marker sequence. Supported in text, bullets and list item runs.
+     */
+    footnote?: (string | [TextRun, ...(TextRun)[]]);
     [k: string]: unknown;
 });
 /**
@@ -369,6 +364,10 @@ type ListItem = (string | TextRun[] | {
      * Zero-based nesting level for the list item.
      */
     level?: number;
+    /**
+     * Restart the list's numbering at this number for this item (counted at its level); the entries after it continue from it. Only meaningful when the payload has `numbering`. Paginated continuation pages use it to keep the numbers of the whole list.
+     */
+    start?: number;
 });
 /**
  * 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.
@@ -385,7 +384,18 @@ type BulletItem = (string | TextRun[] | {
      * Zero-based nesting level for the bullet.
      */
     level?: number;
+    /**
+     * Restart the list's numbering at this number for this bullet (counted at its level); the entries after it continue from it. Only meaningful when the payload has `numbering`. Paginated continuation pages use it to keep the numbers of the whole list.
+     */
+    start?: number;
 });
+/**
+ * A list number style: 1, 2, 3; I, II, III; i, ii, iii; A, B, C; a, b, c. Alphabetic numbering past 26 repeats the letter as PowerPoint does (aa, bb, cc). Roman numerals stop at 3999; larger values are drawn in arabic with a numbering-adapted diagnostic.
+ *
+ * This interface was referenced by `Presentation`'s JSON-Schema
+ * via the `definition` "NumberingStyle".
+ */
+type NumberingStyle = ("arabic" | "roman-upper" | "roman-lower" | "alpha-upper" | "alpha-lower");
 /**
  * A cell in inline chart data.
  *
@@ -440,6 +450,10 @@ type ContentPayload = {
      * Text-style bullet payload. Presence of this field infers type 'text'.
      */
     bullets?: BulletItem[];
+    /**
+     * Number the payload's `items` or `bullets` instead of bulleting them. A style name (arabic, roman-upper, roman-lower, alpha-upper, alpha-lower) or a Numbering object applies to every list level; an array gives one entry per level (index = level, the last entry repeats for deeper levels). Counting follows PowerPoint: consecutive entries of one level count up from its start, and an entry of a shallower level restarts the deeper levels. Absent = bullets. Valid only with `items` or `bullets`. Native PowerPoint export writes a:buAutoNum with the matching scheme and startAt; the preview draws the same numbers at the same marker geometry.
+     */
+    numbering?: (NumberingStyle | Numbering | [(NumberingStyle | Numbering)] | [(NumberingStyle | Numbering), (NumberingStyle | Numbering)] | [(NumberingStyle | Numbering), (NumberingStyle | Numbering), (NumberingStyle | Numbering)] | [(NumberingStyle | Numbering), (NumberingStyle | Numbering), (NumberingStyle | Numbering), (NumberingStyle | Numbering)] | [(NumberingStyle | Numbering), (NumberingStyle | Numbering), (NumberingStyle | Numbering), (NumberingStyle | Numbering), (NumberingStyle | Numbering)] | [(NumberingStyle | Numbering), (NumberingStyle | Numbering), (NumberingStyle | Numbering), (NumberingStyle | Numbering), (NumberingStyle | Numbering), (NumberingStyle | Numbering)] | [(NumberingStyle | Numbering), (NumberingStyle | Numbering), (NumberingStyle | Numbering), (NumberingStyle | Numbering), (NumberingStyle | Numbering), (NumberingStyle | Numbering), (NumberingStyle | Numbering)] | [(NumberingStyle | Numbering), (NumberingStyle | Numbering), (NumberingStyle | Numbering), (NumberingStyle | Numbering), (NumberingStyle | Numbering), (NumberingStyle | Numbering), (NumberingStyle | Numbering), (NumberingStyle | Numbering)] | [(NumberingStyle | Numbering), (NumberingStyle | Numbering), (NumberingStyle | Numbering), (NumberingStyle | Numbering), (NumberingStyle | Numbering), (NumberingStyle | Numbering), (NumberingStyle | Numbering), (NumberingStyle | Numbering), (NumberingStyle | Numbering)]);
     /**
      * 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.
      */
@@ -531,6 +545,23 @@ type ContentPayload = {
          */
         events: [TimelineEvent, ...(TimelineEvent)[]];
     });
+    /**
+     * Caption for an image, chart, table or video payload, composed inside the block's region (below the media by default). Invalid on other payload kinds and on groups.
+     */
+    caption?: (string | TextRun[] | {
+        /**
+         * Caption text: a string or TextRun[] for inline rich text.
+         */
+        text: (string | TextRun[]);
+        /**
+         * Where the caption band sits inside the block's region: below the media (default) or above it. Core composition reserves the band and shrinks the media by its height.
+         */
+        position?: ("below" | "above");
+        /**
+         * Horizontal alignment of the caption text within the block. Defaults to left.
+         */
+        align?: ("left" | "center" | "right");
+    });
     /**
      * Ordered children of a group. Each child is a leaf or another group.
      *
@@ -631,6 +662,10 @@ interface Presentation {
     tags?: string[];
     design?: Design;
     variables?: Variables;
+    /**
+     * Marks this document as a template: an incomplete OPF file. A template declares variables (top-level 'variables') and references them from content, and may leave required variables unfilled; validation then reports the unfilled variables instead of failing, and previews and exports use each variable's 'example'. Filling a template (resolveVariables, or 'opf fill') returns a normal deck with this marker removed. Absent or false: a normal deck, where an unfilled required variable is an error. See docs/templates-and-variables.md.
+     */
+    template?: boolean;
     /**
      * Structured storyline describing the deck's arc and beats. Resolves to the 'id' of a 'narratives' catalog record.
      *
@@ -649,6 +684,10 @@ interface Presentation {
      * @minItems 1
      */
     slides: [Slide, ...(Slide)[]];
+    /**
+     * Sources that text runs cite with 'cite'. Ids are unique. A cited reference is listed in the footnote area of every slide that cites it, with a marker number assigned per deck in order of first use; a reference no run cites is a lint warning (opf/unused-reference). referencesSlide() turns the cited references into an ordinary list slide.
+     */
+    references?: Reference[];
     assets?: Assets;
     catalogs?: Catalogs;
     /**
@@ -678,7 +717,7 @@ interface Organization {
      */
     legalName?: string;
     /**
-     * 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 logos), PNG (with transparency), or JPG. The primary organization's logo is used by default for cover-slide and footer branding; design.logo overrides the source.
+     * 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 logos), PNG (with transparency), or JPG. The primary organization's logo (role 'primary', else the first organization) is the fallback source wherever the deck logo is drawn: a slide's design.logo, then design.logo, then this value. It is therefore drawn on cover and section slides and by header/footer zones with logo: true, exactly as design.logo would be (see design.logo and docs/design-resolution.md).
      */
     logo?: (string | {
         /**
@@ -758,7 +797,7 @@ interface Speaker {
      */
     title?: string;
     /**
-     * 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 appropriate for photographic content. Used on cover and bio slides.
+     * 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 appropriate for photographic content. Authoring metadata for hosts and layouts (cover and bio slides built by a host): the reference renderer and exporter do not draw it, because no slide field or layout slot places a speaker; it round-trips through PPTX provenance.
      */
     photo?: (string | {
         /**
@@ -853,7 +892,7 @@ interface Design {
      */
     background?: (BackgroundShortcut | Background);
     /**
-     * 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 falls back to the primary organization logo.
+     * Deck logo assets used by covers, section dividers, headers, footers and picture bullets. A string or Asset object is the default logo source; the LogoSet object form provides light/dark, stacked, icon, and wordmark variants (see LogoSet for the selection order). Source precedence: a slide's design.logo, then this value, then the primary organization's logo; absence inherits. Placement (reference engines, vetoable): on a cover or section slide (no body payload on a heading-only layout such as title, title-subtitle or section-divider, or no layout) the lockup variant is drawn at the top-left of the free area, inside the slide padding and below any header furniture, in a box 56 reference pixels tall and at most four times as wide; the tag/title/subtitle group then centers in the remaining span. Content slides never get an automatic logo. Header and footer zones draw the icon variant when they set logo: true, and design.listBullet 'image' draws it as the picture bullet. composeSlide returns the cover box as geometry.logo.
      */
     logo?: (Asset | LogoSet);
     /**
@@ -973,11 +1012,11 @@ interface Design {
         };
     });
     /**
-     * Axis along which parallel body/content regions are arranged.
+     * Axis along which parallel body content is arranged. Sets the root arrangement mode of blocks and root payloads when no composition.mode is set on the slide or on its layout record: 'vertical' is column, 'horizontal' is row. Precedence: composition.mode (the slide's own, else the layout record's geometry contract), then this value (slide design, then deck design), then the layout record's slideLayoutDirection, then automatic selection. A layout that carries a composition.mode keeps its grid or direction whatever this value says. Promoted regions (left, top:left, ...) keep their explicit geometry and nested groups keep their own composition.
      */
     contentDirection?: ("horizontal" | "vertical");
     /**
-     * For chart layouts, where the primary chart sits relative to supporting content. 'none' means chart regions have equal weight.
+     * Where the primary chart sits relative to supporting content. Effective value: slide design, then deck design, then the layout record's contentTypeChartPrimary. When the slide has no promoted regions and no composition.mode of its own, and its root nodes mix at least one chart with other content, the first chart becomes a primary track and the other nodes form one synthetic sub-grid: 'left'/'right' is a two-track row and 'top'/'bottom' a two-track column, weighted 3:2 in favor of the chart; explicit root columns and weights are ignored while it applies. 'none' (the default) keeps the ordinary automatic grid with equal weight.
      */
     chartPrimary?: ("none" | "top" | "bottom" | "left" | "right");
     /**
@@ -985,7 +1024,7 @@ interface Design {
      */
     imageFill?: ("crop" | "fit");
     /**
-     * Default bullet rendering style for list layouts.
+     * Marker style for items and bullets lists. 'character' (the default) draws the glyph marker. 'image' draws the deck's icon logo (a slide's design.logo, then design.logo, then the primary organization's logo; light variants on dark backgrounds) as a picture bullet: a square of the marker's font size whose bottom sits on the marker baseline, so list geometry does not change. Without a logo the glyph is drawn and the engine reports unresolved-content at this field.
      */
     listBullet?: ("character" | "image");
     [k: string]: unknown;
@@ -1256,7 +1295,7 @@ interface Font1 {
     [k: string]: unknown;
 }
 /**
- * Abstract role: font used for accent text such as quotes or callouts. No direct OOXML slot.
+ * Abstract role: font used for accent text. When set, the slide tag (eyebrow) and the quote body use this family instead of the body and heading families; nothing else changes. resolveFontFamilies() returns it as accent only when the scheme defines it. No direct OOXML slot: PPTX export writes it on those runs, and the theme fonts stay major/minor.
  */
 interface Font2 {
     /**
@@ -1325,7 +1364,7 @@ interface SolidBackground {
      */
     type: "solid";
     /**
-     * Fixed solid fill color, usually a hex string. Use { type: 'theme', slot: ... } for PowerPoint's four theme-controlled background choices.
+     * Fixed solid fill color: a hex string, a color-scheme slot or role name, or a var:<id> variable reference (a ColorRef, resolved against the effective color scheme and the deck variables). Use { type: 'theme', slot: ... } for PowerPoint's four theme-controlled background choices.
      */
     color: string;
     /**
@@ -1360,7 +1399,7 @@ interface GradientBackground {
          */
         stops?: {
             /**
-             * Stop color as a hex string.
+             * Stop color: a hex string, a color-scheme slot or role name, or a var:<id> variable reference (a ColorRef).
              */
             color: string;
             /**
@@ -1428,11 +1467,11 @@ interface PatternBackground {
          */
         preset: string;
         /**
-         * Foreground color for the pattern, usually a hex string.
+         * Foreground color for the pattern: a hex string, a color-scheme slot or role name, or a var:<id> variable reference (a ColorRef).
          */
         foregroundColor?: string;
         /**
-         * Background color behind the pattern, usually a hex string.
+         * Background color behind the pattern: a hex string, a color-scheme slot or role name, or a var:<id> variable reference (a ColorRef).
          */
         backgroundColor?: string;
         [k: string]: unknown;
@@ -1462,7 +1501,7 @@ interface Dimensions {
     [k: string]: unknown;
 }
 /**
- * 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.
+ * Deck logo variants surfaced by covers, section dividers, headers, footers and picture bullets. Organization identity lives in organization; this object only controls visual rendering assets. Engines select one variant per slot and background tone (resolveLogo in @openpresentation/opf): same-tone variants first, neutral ones next, the opposite tone last. Lockup on a dark background: light, default, stackedLight, stacked, wordmarkLight, wordmark, iconLight, icon, then dark, stackedDark, wordmarkDark, iconDark; on a light background: dark, default, stackedDark, stacked, wordmarkDark, wordmark, iconDark, icon, then light, stackedLight, wordmarkLight, iconLight. The icon slot (headers, footers, picture bullets) tries iconLight or iconDark for the tone, then icon, then the lockup chain; the stacked slot tries stackedLight or stackedDark, then stacked, then the lockup chain.
  *
  * This interface was referenced by `Presentation`'s JSON-Schema
  * via the `definition` "LogoSet".
@@ -1849,6 +1888,10 @@ interface HeaderFooter {
  * Left-aligned header/footer content.
  */
 interface HeaderFooterItem {
+    /**
+     * Whether to render the deck's icon logo in this zone: a slide's design.logo, then design.logo, then the primary organization's logo (LogoSet icon variants first, light ones on dark backgrounds). It is a generated image part in the same box as image; without a logo the engine reports unresolved-content at this field. Use image for a literal picture that is not the deck logo.
+     */
+    logo?: boolean;
     /**
      * Literal text rendered in this zone.
      */
@@ -1916,6 +1959,10 @@ interface HeaderFooterItem {
  * Centered header/footer content.
  */
 interface HeaderFooterItem1 {
+    /**
+     * Whether to render the deck's icon logo in this zone: a slide's design.logo, then design.logo, then the primary organization's logo (LogoSet icon variants first, light ones on dark backgrounds). It is a generated image part in the same box as image; without a logo the engine reports unresolved-content at this field. Use image for a literal picture that is not the deck logo.
+     */
+    logo?: boolean;
     /**
      * Literal text rendered in this zone.
      */
@@ -1983,6 +2030,10 @@ interface HeaderFooterItem1 {
  * Right-aligned header/footer content.
  */
 interface HeaderFooterItem2 {
+    /**
+     * Whether to render the deck's icon logo in this zone: a slide's design.logo, then design.logo, then the primary organization's logo (LogoSet icon variants first, light ones on dark backgrounds). It is a generated image part in the same box as image; without a logo the engine reports unresolved-content at this field. Use image for a literal picture that is not the deck logo.
+     */
+    logo?: boolean;
     /**
      * Literal text rendered in this zone.
      */
@@ -2047,11 +2098,293 @@ interface HeaderFooterItem2 {
     [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.
+ * Optional named variables: deck colors referenced as 'var:<id>' (the original use), and typed content variables (text, number, date, image, url, list) referenced inline as '{{<id>}}' or whole as 'var:<id>'. Variables are what makes a deck a fillable template when combined with 'template': true. Color 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;
 }
+/**
+ * A named color. Content color fields reference it as 'var:<id>'. Colors resolve at render time through the ordinary color-reference path, so a color variable keeps working as before.
+ *
+ * This interface was referenced by `Presentation`'s JSON-Schema
+ * via the `definition` "ColorVariable".
+ */
+interface ColorVariable {
+    /**
+     * Variable kind. One of color, text, number, date, image, url or list.
+     */
+    type: "color";
+    /**
+     * Hex color shorthand accepted by selected string fields.
+     */
+    value?: string;
+    /**
+     * Whether the variable must be filled. Defaults to true: a variable with no 'value' is unfilled, and an unfilled required variable is an error in a normal deck and expected in a template. Set false for an optional slot: an unfilled optional variable resolves to empty text (inline tokens) or the field that references it is omitted.
+     */
+    required?: boolean;
+    /**
+     * Optional short human label for forms and fill panels.
+     */
+    label?: string;
+    /**
+     * Optional prose describing what the variable is for, surfaced by pickers, fill forms and agents.
+     */
+    description?: string;
+    /**
+     * Hex color shorthand accepted by selected string fields.
+     */
+    example?: string;
+}
+/**
+ * Text content. Plain string or rich TextRun[]. Insert it inline as '{{<id>}}' inside any string (rich text is flattened to plain text there), or reference it whole as 'var:<id>' in a field that accepts string or TextRun[] (the rich runs are kept).
+ *
+ * This interface was referenced by `Presentation`'s JSON-Schema
+ * via the `definition` "TextVariable".
+ */
+interface TextVariable {
+    /**
+     * Variable kind. One of color, text, number, date, image, url or list.
+     */
+    type: "text";
+    /**
+     * Text this variable resolves to: a plain string, or TextRun[] for rich text.
+     */
+    value?: (string | TextRun[]);
+    /**
+     * Whether the variable must be filled. Defaults to true: a variable with no 'value' is unfilled, and an unfilled required variable is an error in a normal deck and expected in a template. Set false for an optional slot: an unfilled optional variable resolves to empty text (inline tokens) or the field that references it is omitted.
+     */
+    required?: boolean;
+    /**
+     * Optional short human label for forms and fill panels.
+     */
+    label?: string;
+    /**
+     * Optional prose describing what the variable is for, surfaced by pickers, fill forms and agents.
+     */
+    description?: string;
+    /**
+     * Illustrative text shown in fill forms and used when a template is previewed with examples. Never written to output.
+     */
+    example?: (string | TextRun[]);
+}
+/**
+ * A number. '{{<id>}}' inserts it as text using 'format'; 'var:<id>' as a whole field supplies the number itself (chart values, font sizes).
+ *
+ * This interface was referenced by `Presentation`'s JSON-Schema
+ * via the `definition` "NumberVariable".
+ */
+interface NumberVariable {
+    /**
+     * Variable kind. One of color, text, number, date, image, url or list.
+     */
+    type: "number";
+    /**
+     * Number this variable resolves to.
+     */
+    value?: number;
+    /**
+     * Whether the variable must be filled. Defaults to true: a variable with no 'value' is unfilled, and an unfilled required variable is an error in a normal deck and expected in a template. Set false for an optional slot: an unfilled optional variable resolves to empty text (inline tokens) or the field that references it is omitted.
+     */
+    required?: boolean;
+    /**
+     * Optional short human label for forms and fill panels.
+     */
+    label?: string;
+    /**
+     * Optional prose describing what the variable is for, surfaced by pickers, fill forms and agents.
+     */
+    description?: string;
+    /**
+     * Illustrative number shown in fill forms and used when a template is previewed with examples. Never written to output.
+     */
+    example?: number;
+    /**
+     * Display pattern used by '{{<id>}}'. A literal prefix, a numeric part of '#', '0', ',' and '.', and a literal suffix. '0' pads digits, '#' is optional, ',' groups thousands, digits after '.' fix the decimals ('0' required, '#' optional), and a '%' in the suffix scales by 100. English separators only. Absent: the shortest decimal form.
+     */
+    format?: string;
+}
+/**
+ * A calendar date as an ISO YYYY-MM-DD string. No time zone and no clock are involved. '{{<id>}}' inserts it formatted with 'format'.
+ *
+ * This interface was referenced by `Presentation`'s JSON-Schema
+ * via the `definition` "DateVariable".
+ */
+interface DateVariable {
+    /**
+     * Variable kind. One of color, text, number, date, image, url or list.
+     */
+    type: "date";
+    /**
+     * ISO calendar date (YYYY-MM-DD) this variable resolves to.
+     */
+    value?: string;
+    /**
+     * Whether the variable must be filled. Defaults to true: a variable with no 'value' is unfilled, and an unfilled required variable is an error in a normal deck and expected in a template. Set false for an optional slot: an unfilled optional variable resolves to empty text (inline tokens) or the field that references it is omitted.
+     */
+    required?: boolean;
+    /**
+     * Optional short human label for forms and fill panels.
+     */
+    label?: string;
+    /**
+     * Optional prose describing what the variable is for, surfaced by pickers, fill forms and agents.
+     */
+    description?: string;
+    /**
+     * Illustrative ISO date shown in fill forms and used when a template is previewed with examples. Never written to output.
+     */
+    example?: string;
+    /**
+     * Date display pattern, the same LDML-style tokens as header/footer dateFormat: yyyy, yy, MMMM, MMM, MM, M, dd, d, EEEE, EEE and quoted literals. English names. Default 'MMMM d, yyyy'.
+     */
+    format?: string;
+}
+/**
+ * An image source: any Asset (an 'asset:<id>' reference, HTTPS URL, data URI, relative or local path, or an object with src, alt and metadata). Reference it whole as 'var:<id>' in an image, asset or src field; '{{<id>}}' inserts the source string.
+ *
+ * This interface was referenced by `Presentation`'s JSON-Schema
+ * via the `definition` "ImageVariable".
+ */
+interface ImageVariable {
+    /**
+     * Variable kind. One of color, text, number, date, image, url or list.
+     */
+    type: "image";
+    /**
+     * 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.
+     */
+    value?: (string | {
+        /**
+         * Resource source. Accepts an 'asset:<id>' reference, HTTPS URL, data URI, relative path resolved against the OPF file location, or local filesystem path.
+         */
+        src: string;
+        /**
+         * Alternative text for images and other visual assets.
+         */
+        alt?: string;
+        /**
+         * Human-readable asset title for editors and asset pickers.
+         */
+        title?: string;
+        /**
+         * Optional notes about the asset's contents, provenance, or intended use.
+         */
+        description?: string;
+        /**
+         * Optional MIME media type when it cannot be inferred from src.
+         */
+        mediaType?: string;
+        /**
+         * Optional authoring/parsing format hint. Useful when format is more convenient than a full MIME media type.
+         */
+        format?: string;
+    });
+    /**
+     * Whether the variable must be filled. Defaults to true: a variable with no 'value' is unfilled, and an unfilled required variable is an error in a normal deck and expected in a template. Set false for an optional slot: an unfilled optional variable resolves to empty text (inline tokens) or the field that references it is omitted.
+     */
+    required?: boolean;
+    /**
+     * Optional short human label for forms and fill panels.
+     */
+    label?: string;
+    /**
+     * Optional prose describing what the variable is for, surfaced by pickers, fill forms and agents.
+     */
+    description?: string;
+    /**
+     * 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.
+     */
+    example?: (string | {
+        /**
+         * Resource source. Accepts an 'asset:<id>' reference, HTTPS URL, data URI, relative path resolved against the OPF file location, or local filesystem path.
+         */
+        src: string;
+        /**
+         * Alternative text for images and other visual assets.
+         */
+        alt?: string;
+        /**
+         * Human-readable asset title for editors and asset pickers.
+         */
+        title?: string;
+        /**
+         * Optional notes about the asset's contents, provenance, or intended use.
+         */
+        description?: string;
+        /**
+         * Optional MIME media type when it cannot be inferred from src.
+         */
+        mediaType?: string;
+        /**
+         * Optional authoring/parsing format hint. Useful when format is more convenient than a full MIME media type.
+         */
+        format?: string;
+    });
+}
+/**
+ * A link target (http, https, mailto or tel). Use it as '{{<id>}}' inside a link string or reference it whole as 'var:<id>' in a link field.
+ *
+ * This interface was referenced by `Presentation`'s JSON-Schema
+ * via the `definition` "UrlVariable".
+ */
+interface UrlVariable {
+    /**
+     * Variable kind. One of color, text, number, date, image, url or list.
+     */
+    type: "url";
+    /**
+     * Link target this variable resolves to.
+     */
+    value?: string;
+    /**
+     * Whether the variable must be filled. Defaults to true: a variable with no 'value' is unfilled, and an unfilled required variable is an error in a normal deck and expected in a template. Set false for an optional slot: an unfilled optional variable resolves to empty text (inline tokens) or the field that references it is omitted.
+     */
+    required?: boolean;
+    /**
+     * Optional short human label for forms and fill panels.
+     */
+    label?: string;
+    /**
+     * Optional prose describing what the variable is for, surfaced by pickers, fill forms and agents.
+     */
+    description?: string;
+    /**
+     * Illustrative link shown in fill forms and used when a template is previewed with examples. Never written to output.
+     */
+    example?: string;
+}
+/**
+ * A list of strings, for bullets and list items. A whole-string array element 'var:<id>' splices every entry into the array in place; a whole field 'var:<id>' becomes the array; '{{<id>}}' joins the entries with ', ' (or the separator after a pipe: '{{<id>|; }}').
+ *
+ * This interface was referenced by `Presentation`'s JSON-Schema
+ * via the `definition` "ListVariable".
+ */
+interface ListVariable {
+    /**
+     * Variable kind. One of color, text, number, date, image, url or list.
+     */
+    type: "list";
+    /**
+     * Entries this variable resolves to.
+     */
+    value?: string[];
+    /**
+     * Whether the variable must be filled. Defaults to true: a variable with no 'value' is unfilled, and an unfilled required variable is an error in a normal deck and expected in a template. Set false for an optional slot: an unfilled optional variable resolves to empty text (inline tokens) or the field that references it is omitted.
+     */
+    required?: boolean;
+    /**
+     * Optional short human label for forms and fill panels.
+     */
+    label?: string;
+    /**
+     * Optional prose describing what the variable is for, surfaced by pickers, fill forms and agents.
+     */
+    description?: string;
+    /**
+     * Illustrative entries shown in fill forms and used when a template is previewed with examples. Never written to output.
+     */
+    example?: string[];
+}
 /**
  * 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.
  *
@@ -2213,6 +2546,10 @@ interface Slide {
      * Full-slide text-style bullet payload. Presence of this field infers type 'text'.
      */
     bullets?: BulletItem[];
+    /**
+     * Number the full-slide `items` or `bullets` instead of bulleting them. A style name (arabic, roman-upper, roman-lower, alpha-upper, alpha-lower) or a Numbering object applies to every list level; an array gives one entry per level (index = level, the last entry repeats for deeper levels). Counting follows PowerPoint: consecutive entries of one level count up from its start, and an entry of a shallower level restarts the deeper levels. Absent = bullets. Valid only with `items` or `bullets`. Native PowerPoint export writes a:buAutoNum with the matching scheme and startAt; the preview draws the same numbers at the same marker geometry.
+     */
+    numbering?: (NumberingStyle | Numbering | [(NumberingStyle | Numbering)] | [(NumberingStyle | Numbering), (NumberingStyle | Numbering)] | [(NumberingStyle | Numbering), (NumberingStyle | Numbering), (NumberingStyle | Numbering)] | [(NumberingStyle | Numbering), (NumberingStyle | Numbering), (NumberingStyle | Numbering), (NumberingStyle | Numbering)] | [(NumberingStyle | Numbering), (NumberingStyle | Numbering), (NumberingStyle | Numbering), (NumberingStyle | Numbering), (NumberingStyle | Numbering)] | [(NumberingStyle | Numbering), (NumberingStyle | Numbering), (NumberingStyle | Numbering), (NumberingStyle | Numbering), (NumberingStyle | Numbering), (NumberingStyle | Numbering)] | [(NumberingStyle | Numbering), (NumberingStyle | Numbering), (NumberingStyle | Numbering), (NumberingStyle | Numbering), (NumberingStyle | Numbering), (NumberingStyle | Numbering), (NumberingStyle | Numbering)] | [(NumberingStyle | Numbering), (NumberingStyle | Numbering), (NumberingStyle | Numbering), (NumberingStyle | Numbering), (NumberingStyle | Numbering), (NumberingStyle | Numbering), (NumberingStyle | Numbering), (NumberingStyle | Numbering)] | [(NumberingStyle | Numbering), (NumberingStyle | Numbering), (NumberingStyle | Numbering), (NumberingStyle | Numbering), (NumberingStyle | Numbering), (NumberingStyle | Numbering), (NumberingStyle | Numbering), (NumberingStyle | Numbering), (NumberingStyle | Numbering)]);
     /**
      * 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.
      */
@@ -2304,6 +2641,23 @@ interface Slide {
          */
         events: [TimelineEvent, ...(TimelineEvent)[]];
     });
+    /**
+     * Caption for the slide's root image, chart, table or video payload. Valid only when the slide root holds exactly one of those payloads.
+     */
+    caption?: (string | TextRun[] | {
+        /**
+         * Caption text: a string or TextRun[] for inline rich text.
+         */
+        text: (string | TextRun[]);
+        /**
+         * Where the caption band sits inside the block's region: below the media (default) or above it. Core composition reserves the band and shrinks the media by its height.
+         */
+        position?: ("below" | "above");
+        /**
+         * Horizontal alignment of the caption text within the block. Defaults to left.
+         */
+        align?: ("left" | "center" | "right");
+    });
     /**
      * 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.
      */
@@ -2377,6 +2731,26 @@ interface Slide {
         [k: string]: unknown;
     };
 }
+/**
+ * Numbering of one list level.
+ *
+ * This interface was referenced by `Presentation`'s JSON-Schema
+ * via the `definition` "Numbering".
+ */
+interface Numbering {
+    /**
+     * A list number style: 1, 2, 3; I, II, III; i, ii, iii; A, B, C; a, b, c. Alphabetic numbering past 26 repeats the letter as PowerPoint does (aa, bb, cc). Roman numerals stop at 3999; larger values are drawn in arabic with a numbering-adapted diagnostic.
+     */
+    style?: ("arabic" | "roman-upper" | "roman-lower" | "alpha-upper" | "alpha-lower");
+    /**
+     * First number counted at this level. Default 1. Native PowerPoint accepts 1 to 32767.
+     */
+    start?: number;
+    /**
+     * Text after the number: period (1.), paren (1)) or paren-both ((1)). Default period.
+     */
+    suffix?: ("period" | "paren" | "paren-both");
+}
 /**
  * Full-slide chart payload. Presence of this field infers type 'chart'.
  */
@@ -2389,6 +2763,15 @@ interface Chart {
      * Chart data. Inline data uses a tabular columns/rows shape; renderers convert rows to chart series internally.
      */
     data: (ChartData | ChartDataSource);
+    axisTitles?: ChartAxisTitles;
+    /**
+     * Optional legend position. 'none' hides the legend. Absent keeps today's behaviour exactly (a legend at the right of multi-series charts and of pie and doughnut charts, none for single-series charts). A named position shows the legend there even for a single-series chart. Of the Office 2016 constructs only box-and-whisker takes a legend; histogram, pareto, waterfall, funnel, treemap and map drop the option with a 'chart-option-adapted' diagnostic.
+     */
+    legend?: ("none" | "top" | "bottom" | "left" | "right");
+    /**
+     * Optional data labels. true shows value labels at each type's default position, false (or absent) shows none, which is today's behaviour. Use the object form for the label content, position and separator.
+     */
+    dataLabels?: (boolean | ChartDataLabels);
 }
 /**
  * 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.
@@ -2434,6 +2817,41 @@ interface ChartDataSource {
      */
     columns?: string[];
 }
+/**
+ * Optional axis titles. Absent keeps today's untitled axes. Supported on the chart types that have a category/value (or X/Y) axis pair (column, bar, line, area, scatter, and the histogram, pareto, waterfall and box-and-whisker constructs; the funnel construct takes a category title only); a title on a type without that axis (pie, doughnut, radar, treemap, map) is dropped with a 'chart-option-adapted' diagnostic by renderers and exporters.
+ */
+interface ChartAxisTitles {
+    /**
+     * Title of the category (X) axis.
+     */
+    category?: string;
+    /**
+     * Title of the value (Y) axis.
+     */
+    value?: string;
+}
+/**
+ * Data label settings. A label shows the selected content parts in the fixed order category, value, percent, joined by the separator.
+ *
+ * This interface was referenced by `Presentation`'s JSON-Schema
+ * via the `definition` "ChartDataLabels".
+ */
+interface ChartDataLabels {
+    /**
+     * Which parts a label shows. Defaults to ['value']. 'percent' is the share of the total and exists only on pie and doughnut charts; 'category' shows the category name (the X value on a scatter chart). A part a chart type cannot show is dropped with a 'chart-option-adapted' diagnostic.
+     *
+     * @minItems 1
+     */
+    content?: [("value" | "percent" | "category"), ...(("value" | "percent" | "category"))[]];
+    /**
+     * Where a label sits relative to its mark. 'auto' (the default) is the type's default: outside-end for clustered columns and bars, pie slices and the histogram, pareto and waterfall constructs; center for stacked columns and bars; above for line and scatter points. Clustered columns and bars and the histogram, pareto and waterfall constructs take center, inside-end, inside-base and outside-end; stacked columns and bars take center, inside-end and inside-base; pie takes center, inside-end and outside-end; line and scatter points take above, below, left, right and center. Area, doughnut and radar charts and the funnel and treemap constructs take only 'auto' (the box-and-whisker and map constructs have no data labels). An unsupported position falls back to 'auto' with a 'chart-option-adapted' diagnostic.
+     */
+    position?: ("auto" | "center" | "inside-end" | "inside-base" | "outside-end" | "above" | "below" | "left" | "right");
+    /**
+     * Text between the parts of a label that shows more than one. Defaults to ', '.
+     */
+    separator?: string;
+}
 /**
  * Full-slide table payload. Presence of this field infers type 'table'.
  */
@@ -2638,6 +3056,15 @@ interface Chart1 {
      * Chart data. Inline data uses a tabular columns/rows shape; renderers convert rows to chart series internally.
      */
     data: (ChartData | ChartDataSource);
+    axisTitles?: ChartAxisTitles;
+    /**
+     * Optional legend position. 'none' hides the legend. Absent keeps today's behaviour exactly (a legend at the right of multi-series charts and of pie and doughnut charts, none for single-series charts). A named position shows the legend there even for a single-series chart. Of the Office 2016 constructs only box-and-whisker takes a legend; histogram, pareto, waterfall, funnel, treemap and map drop the option with a 'chart-option-adapted' diagnostic.
+     */
+    legend?: ("none" | "top" | "bottom" | "left" | "right");
+    /**
+     * Optional data labels. true shows value labels at each type's default position, false (or absent) shows none, which is today's behaviour. Use the object form for the label content, position and separator.
+     */
+    dataLabels?: (boolean | ChartDataLabels);
 }
 /**
  * Table payload. Presence of this field infers type 'table'.
@@ -2727,7 +3154,7 @@ interface Design1 {
      */
     background?: (BackgroundShortcut | Background);
     /**
-     * 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 falls back to the primary organization logo.
+     * Deck logo assets used by covers, section dividers, headers, footers and picture bullets. A string or Asset object is the default logo source; the LogoSet object form provides light/dark, stacked, icon, and wordmark variants (see LogoSet for the selection order). Source precedence: a slide's design.logo, then this value, then the primary organization's logo; absence inherits. Placement (reference engines, vetoable): on a cover or section slide (no body payload on a heading-only layout such as title, title-subtitle or section-divider, or no layout) the lockup variant is drawn at the top-left of the free area, inside the slide padding and below any header furniture, in a box 56 reference pixels tall and at most four times as wide; the tag/title/subtitle group then centers in the remaining span. Content slides never get an automatic logo. Header and footer zones draw the icon variant when they set logo: true, and design.listBullet 'image' draws it as the picture bullet. composeSlide returns the cover box as geometry.logo.
      */
     logo?: (Asset | LogoSet);
     /**
@@ -2847,11 +3274,11 @@ interface Design1 {
         };
     });
     /**
-     * Axis along which parallel body/content regions are arranged.
+     * Axis along which parallel body content is arranged. Sets the root arrangement mode of blocks and root payloads when no composition.mode is set on the slide or on its layout record: 'vertical' is column, 'horizontal' is row. Precedence: composition.mode (the slide's own, else the layout record's geometry contract), then this value (slide design, then deck design), then the layout record's slideLayoutDirection, then automatic selection. A layout that carries a composition.mode keeps its grid or direction whatever this value says. Promoted regions (left, top:left, ...) keep their explicit geometry and nested groups keep their own composition.
      */
     contentDirection?: ("horizontal" | "vertical");
     /**
-     * For chart layouts, where the primary chart sits relative to supporting content. 'none' means chart regions have equal weight.
+     * Where the primary chart sits relative to supporting content. Effective value: slide design, then deck design, then the layout record's contentTypeChartPrimary. When the slide has no promoted regions and no composition.mode of its own, and its root nodes mix at least one chart with other content, the first chart becomes a primary track and the other nodes form one synthetic sub-grid: 'left'/'right' is a two-track row and 'top'/'bottom' a two-track column, weighted 3:2 in favor of the chart; explicit root columns and weights are ignored while it applies. 'none' (the default) keeps the ordinary automatic grid with equal weight.
      */
     chartPrimary?: ("none" | "top" | "bottom" | "left" | "right");
     /**
@@ -2859,7 +3286,7 @@ interface Design1 {
      */
     imageFill?: ("crop" | "fit");
     /**
-     * Default bullet rendering style for list layouts.
+     * Marker style for items and bullets lists. 'character' (the default) draws the glyph marker. 'image' draws the deck's icon logo (a slide's design.logo, then design.logo, then the primary organization's logo; light variants on dark backgrounds) as a picture bullet: a square of the marker's font size whose bottom sits on the marker baseline, so list geometry does not change. Without a logo the glyph is drawn and the engine reports unresolved-content at this field.
      */
     listBullet?: ("character" | "image");
     [k: string]: unknown;
@@ -2903,6 +3330,26 @@ interface Composition1 {
      */
     overflow?: ("warn" | "error");
 }
+/**
+ * A source that runs cite with 'cite'. Cited references are listed in the footnote area of the slides that cite them, numbered per deck in order of first use; referencesSlide() builds an ordinary list slide of them.
+ *
+ * This interface was referenced by `Presentation`'s JSON-Schema
+ * via the `definition` "Reference".
+ */
+interface Reference {
+    /**
+     * Identifier runs cite. Unique within the references list.
+     */
+    id: string;
+    /**
+     * The reference as it is listed: a string or TextRun[] for inline rich text.
+     */
+    text: (string | TextRun[]);
+    /**
+     * Optional link for the reference; a references slide links its entry to it.
+     */
+    url?: string;
+}
 /**
  * Optional reusable asset registry for images, data files, videos, documents, fonts, and other resources referenced elsewhere in the deck via 'asset:<id>' strings.
  */