@openpresentation/opf 0.12.2 → 0.14.0

package/dist/{composition-DWbCiMwF.d.ts → composition-_WEwBe2a.d.ts}

@@ -1,3 +1,5 @@
+import './chart-data-B_3z9VTb.js';
+
 /** Canonical table grid. No renderer, fonts, DOM or network dependencies. */
 interface TableBorder {
     color: string;
@@ -41,6 +43,110 @@ declare function tableGrid(value: unknown, path?: string): TableGrid;
 /** Row boundaries that preserve every vertical merge, used by pagination. */
 declare function tableRowBoundaries(value: unknown): number[];
 
+/** The `design` keys that a layout record, the deck and a slide all share and that composition resolves per key. */
+declare const DESIGN_HINT_KEYS: readonly ["titleAlignment", "contentAlignment", "contentBox", "contentDirection", "chartPrimary", "imageFill", "listBullet"];
+type DesignHintKey = typeof DESIGN_HINT_KEYS[number];
+/** Where an effective design hint came from: the slide's own `design`, the deck's `design`, or the slide's layout record. */
+type DesignHintSource = 'slide' | 'deck' | 'layout';
+/** The effective value of every shared design key. A key nobody sets is absent, so the engine default applies. */
+interface DesignHints {
+    titleAlignment?: 'left' | 'center' | 'right';
+    contentAlignment?: 'left' | 'center' | 'right';
+    contentBox?: boolean;
+    contentDirection?: 'horizontal' | 'vertical';
+    chartPrimary?: 'none' | 'top' | 'bottom' | 'left' | 'right';
+    imageFill?: 'crop' | 'fit';
+    listBullet?: 'character' | 'image';
+}
+/** The effective hints plus which level supplied each key and the document path that names it. */
+interface ResolvedDesignHints extends DesignHints {
+    /** The level that supplied each key that is set. */
+    sources: {
+        [K in DesignHintKey]?: DesignHintSource;
+    };
+    /** Path of the supplying value: `slides.N.design.key`, `design.key`, or for a layout `slides.N.layout` (the reference that selected the record). */
+    paths: {
+        [K in DesignHintKey]?: string;
+    };
+}
+interface ResolveDesignHintsOptions {
+    /** The slide, for its own `design`. */
+    slide?: unknown;
+    /** The slide's resolved layout record, for its `design`. */
+    layout?: unknown;
+    /** The document, for the deck's `design`. */
+    presentation?: unknown;
+    /** Index used in the reported paths; defaults to 0. */
+    slideIndex?: number;
+    /** Host-resolved deck-level values. They rank with the deck's `design`, above it, and below the slide's. */
+    deck?: DesignHints;
+}
+/**
+ * Resolves the shared design keys with one merge, per key, the slide winning: the slide's `design`, then the
+ * deck's `design` (or the host's `deck` values), then the resolved layout record's `design`. A key none of them
+ * sets stays absent. A value the schema does not allow for its key is skipped, so the next level answers. Composition, the renderer, the PPTX exporter and the audit all take their values from here
+ * (`SlideComposition.design`), so they cannot disagree.
+ */
+declare function resolveDesignHints(options?: ResolveDesignHintsOptions): ResolvedDesignHints;
+
+/**
+ * Metric trend mark (RR-07, FA-06): the arrow and colour that show `metric.trend` and
+ * `metric.sentiment` in the SVG preview and the PPTX export. Core's metric layout places the trend word (up, down, flat) as ordinary
+ * text; this derives, from that accepted line geometry, one arrow beside it so both engines draw
+ * the same shape in the same place and colour. The word stays the text alternative: the arrow
+ * adds a visual cue and an `ariaLabel`, never rewritten source text. The arrow always points the
+ * way the trend does; its colour (and the trend and delta text colour) follows the sentiment, which
+ * defaults to the conventional reading of the trend (up positive, down negative, flat neutral).
+ */
+
+type MetricTrend = 'up' | 'down' | 'flat';
+/** Whether a change is good news: the colour of the trend mark. */
+type MetricSentiment = 'positive' | 'negative' | 'neutral';
+/** The DrawingML preset geometry that draws each trend (`a:prstGeom prst`). */
+declare const METRIC_TREND_SHAPES: Readonly<Record<MetricTrend, 'upArrow' | 'downArrow' | 'rightArrow'>>;
+declare const METRIC_TREND_MIN_CONTRAST = 4.5;
+interface MetricTrendColorOptions {
+    /** The slide background the metric text sits on. */
+    background: string;
+    /** Neutral colour for a neutral sentiment (the deck's muted text). */
+    neutral?: string;
+    /** Whether the change is good news; absent, the trend's default (up positive, down negative, flat neutral). */
+    sentiment?: MetricSentiment;
+}
+/** The colour of a trend (or, with `options.sentiment`, of its sentiment), kept at >= 4.5:1 against the slide background. */
+declare function metricTrendColor(trend: MetricTrend, options: MetricTrendColorOptions): string;
+interface MetricTrendMark {
+    trend: MetricTrend;
+    /** The sentiment the colour follows: the metric's own, else the default for the trend. */
+    sentiment: MetricSentiment;
+    /** DrawingML preset name for native export. */
+    shape: 'upArrow' | 'downArrow' | 'rightArrow';
+    /** Arrow bounding box in layout pixels (96 per inch). */
+    box: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    /** The arrow outline as polygon points in layout pixels: the preset geometry at default adjustments. */
+    points: [number, number][];
+    color: string;
+    /** Text alternative for the arrow. */
+    ariaLabel: string;
+    /** Path of the trend field the mark belongs to. */
+    path: string;
+}
+/** Outline of the DrawingML upArrow, downArrow or rightArrow preset (adj1 = adj2 = 50000) in `box`. */
+declare function metricTrendPoints(shape: MetricTrendMark['shape'], box: MetricTrendMark['box']): [number, number][];
+/**
+ * The arrow for a laid-out metric, or undefined when the metric has no (visible) trend or the
+ * arrow has no room. It is square, as tall as the trend word's capitals, on the baseline, and
+ * sits after the word for left-aligned metrics and before it for centred or right-aligned ones,
+ * so it grows away from the alignment edge. It never leaves the trend field's box. The colour
+ * follows `options.sentiment`, else the layout's own (`metric.sentiment`), else the trend's default.
+ */
+declare function metricTrendMark(layout: MetricLayout, options: MetricTrendColorOptions): MetricTrendMark | undefined;
+
 /** A positioned thing whose reading position is wanted. */
 interface ReadingBox {
     box: {
@@ -60,7 +166,7 @@ interface ReadingBox {
  * The boxes are read as given: pass them in logical (unmirrored) coordinates and the order is the reading
  * order of both a left-to-right and a right-to-left deck, because mirroring a deck moves where an item is
  * drawn and where a line starts together. For boxes that are already mirrored, pass `direction: 'rtl'` to
- * order each row from right to left. composeSlide uses this for promoted regions and `opf audit` uses it to
+ * order each row from right to left. composeSlide uses this for promoted regions and `opf/reading-order` uses it to
  * check the composed order, so the two cannot drift apart.
  */
 declare function visualReadingOrder<T extends ReadingBox>(items: readonly T[], direction?: 'ltr' | 'rtl'): T[];
@@ -216,7 +322,7 @@ declare function formatSlideNumber(format: string, current: number, total: numbe
 
 /** Normalize a literal hex color to uppercase #RRGGBB. */
 declare function normalizeHexColor(value: unknown): string | undefined;
-type ResolveColorRefRoles = Partial<Record<'primary' | 'secondary' | 'accent' | 'background' | 'surface' | 'text' | 'textSecondary', string>>;
+type ResolveColorRefRoles = Partial<Record<'primary' | 'secondary' | 'accent' | 'background' | 'surface' | 'surfaceAlt' | 'text' | 'textSecondary', string>>;
 interface ResolveColorRefOptions {
     /** Effective color scheme after design resolution (OOXML slots plus optional role hex overrides). */
     colorScheme: Record<string, unknown>;
@@ -229,6 +335,52 @@ interface ResolveColorRefOptions {
 }
 /** Resolve a ColorRef or TextRun.color string to a literal hex color. */
 declare function resolveColorRef(reference: string, options: ResolveColorRefOptions): string;
+/** WCAG relative luminance below which a slide background counts as dark (the point where white and black text contrast equally). */
+declare const DARK_BACKGROUND_LUMINANCE = 0.179;
+/** True when text on this color should be light: its relative luminance is under {@link DARK_BACKGROUND_LUMINANCE}. An unreadable color is not dark. */
+declare function isDarkColor(color: unknown): boolean;
+/**
+ * The slide background a color scheme implies when the design names no single-color background: the scheme's
+ * `background` role override, else its light1 slot, else white. Gradient and picture backgrounds use it too.
+ */
+declare function defaultSlideBackground(colorScheme: Record<string, unknown>): string;
+interface ResolvedColorRoles {
+    /** Role override, else accent1. */
+    primary: string;
+    /** Role override, else accent2. */
+    secondary: string;
+    /** Role override, else accent3. */
+    accent: string;
+    /** The slide background: the resolved single-color background of the slide, else {@link defaultSlideBackground}. */
+    background: string;
+    /** Role override, else dark2 on a dark background and light2 on a light one. */
+    surface: string;
+    /** The alternate surface of banded table rows: {@link surfaceAltColor} of `surface` and `text`, always distinguishable from `surface`. */
+    surfaceAlt: string;
+    /** Default text. On a dark background light1. On a light background the `text` role override, else dark1. */
+    text: string;
+    /** Role override, else light2 on a dark background and dark2 on a light one. */
+    textSecondary: string;
+    /** The color of a link run that sets no color of its own: the scheme's hyperlink slot (OOXML hlink), unless that has under 4.5:1 contrast against the slide background, then the slide `text` color. */
+    hyperlink: string;
+    /** Followed-hyperlink slot (OOXML folHlink). */
+    followedHyperlink: string;
+    /** Whether the slide background is dark; text, surface and textSecondary defaults follow it. */
+    dark: boolean;
+}
+interface ResolveColorRolesOptions {
+    /** The slide's resolved single-color background (solid, theme-slot or pattern background color). Omit for a gradient, picture or no background. */
+    background?: string | null;
+}
+/**
+ * Resolve a color scheme's abstract roles for one slide: the single definition the opf-render preview, the
+ * PPTX export and the audit share, so the same deck draws the same colors in all three. Role overrides on the
+ * scheme (`primary`, `secondary`, `accent`, `background`, `surface`, `text`, `textSecondary`) win over the slots they
+ * default to. The background-dependent roles follow {@link isDarkColor} of the slide background; a `text`
+ * override applies only on a light background, so a dark slide always gets readable light1 text.
+ * Values are uppercase #RRGGBB, or #RRGGBBAA where the scheme color carries an alpha byte.
+ */
+declare function resolveColorRoles(colorScheme: Record<string, unknown>, options?: ResolveColorRolesOptions): ResolvedColorRoles;
 declare function colorContrast(foreground: string, background: string): number | undefined;
 /** Keep an inherited text color at >=4.5:1; otherwise select black or white.
  * Callers must preserve explicit text-color overrides before using this fallback.
@@ -272,12 +424,424 @@ declare const CHART_SERIES_MIN_DIFFERENCE = 12;
  * and preview and export (which both call this function) draw the same ones.
  */
 declare function chartPaletteForFill(fill: string, palette: readonly string[]): string[];
+/** Share of the text colour mixed into the surface to make the muted colour of a highlighted chart. */
+declare const CHART_HIGHLIGHT_MUTED_MIX = 0.3;
+/** Smallest contrast the muted colour keeps against the surface: recessive, but still a visible mark. */
+declare const CHART_HIGHLIGHT_MUTED_MIN_CONTRAST = 1.6;
+/**
+ * The two colours of a chart that highlights marks (`chart.highlight`), derived from the theme only: `accent` for the highlighted
+ * marks, `muted` for every other mark.
+ *
+ * - `accent` is the deck's primary colour, kept at >= 3:1 against the surface by `chartColorForFill` (a primary that already has
+ *   that contrast is returned unchanged).
+ * - `muted` is the surface mixed {@link CHART_HIGHLIGHT_MUTED_MIX} of the way towards the text colour: a light grey on a light surface
+ *   and a dim grey on a dark one, in the surface's own hue. When that falls below {@link CHART_HIGHLIGHT_MUTED_MIN_CONTRAST} against
+ *   the surface (a surface and text that are close together) the mix moves towards the text colour until it holds.
+ *
+ * Pure arithmetic on opaque colours: the preview and the PPTX export both call it with the chart panel, the primary and the label
+ * colour, so they draw and write the same two colours. An unresolved colour is replaced by white (surface), the surface's own
+ * best contrast partner (text) or black (primary).
+ */
+declare function chartHighlightColors(surface: string, primary: string, text: string): {
+    accent: string;
+    muted: string;
+};
+/** Share of the text colour mixed into the surface for the `surfaceAlt` role. */
+declare const SURFACE_ALT_MIX = 0.1;
+/** Smallest contrast `surfaceAlt` keeps against `surface`, so a band is visible next to a plain row. */
+declare const SURFACE_ALT_MIN_CONTRAST = 1.1;
+/**
+ * The `surfaceAlt` colour role: the fill of the banded rows of a table whose other body rows take `surface`. It is the surface
+ * mixed {@link SURFACE_ALT_MIX} of the way towards the text colour (a slightly darker band on a light table, a slightly lighter one
+ * on a dark table), moved further until it differs from the surface by {@link SURFACE_ALT_MIN_CONTRAST}, while the text keeps
+ * 4.5:1 on it. When mixing towards the text cannot keep both (a surface and text that are close together), the band moves the
+ * other way, away from the text, which only raises the text contrast. Pure arithmetic on opaque colours, so the preview and
+ * the PPTX export, which both resolve the `surfaceAlt` ColorRef from their own `surface` and `text` roles, draw and write the
+ * same colour. An unresolved surface is white; an unresolved text colour is the surface's best contrast partner.
+ */
+declare function surfaceAltColor(surface: string, text: string): string;
+
+/**
+ * Language/script font model (font-fidelity-everywhere FF-18).
+ *
+ * Resolves, for a presentation's language and effective font scheme, the font
+ * family for each OOXML script slot (`a:latin`, `a:ea`, `a:cs`) of the major
+ * (heading) and minor (body) theme fonts, plus the language tags and base
+ * direction. Pure: no DOM, fonts, network or mutation. Catalog references
+ * resolve against inline `catalogs.<kind>.records[]` first and the bundled
+ * catalogs second; a custom `source` is not fetched.
+ *
+ * Catalog ids and catalog tags resolve deterministically from vendored tables.
+ * Only a tag that matches no catalog record may consult the runtime's ICU
+ * likely subtags (`Intl.Locale#maximize`) to find its script.
+ *
+ * Design: docs/programs/font-fidelity-everywhere/script-font-model.md.
+ */
+/** OOXML script slot a writing system uses: `a:latin`, `a:ea` or `a:cs`. */
+type ScriptRole = "latin" | "eastAsian" | "complexScript";
+/** FontScheme.languageFamily as written: the short OOXML names and the long slot names are one value. */
+type LanguageFamilyName = "latin" | "ea" | "cs" | "eastAsian" | "complexScript";
+/**
+ * Read a FontScheme `languageFamily` as one of three values. `eastAsian` is `ea` and `complexScript` is
+ * `cs`; anything that is not one of the five names returns undefined.
+ */
+declare function normalizeLanguageFamily(value: unknown): "latin" | "ea" | "cs" | undefined;
+/** Target application whose language font-scheme defaults apply. */
+type ScriptFontApp = "powerpoint" | "google-slides";
+/** Font family per OOXML script slot for one theme font (major or minor). */
+interface ScriptFontSlots {
+    latin: string;
+    eastAsian: string;
+    complexScript: string;
+}
+/**
+ * Where a resolved eastAsian/complexScript family came from:
+ * - `fontScheme`: an explicit `eastAsian`/`complexScript` slot on the effective design font scheme.
+ * - `schemeFamily`: the design font scheme's own major/minor, because its `languageFamily` names this
+ *   slot and its `languages` list is empty or names the presentation language.
+ * - `language`: the presentation language's font scheme (`fontScheme`, or `googleFontScheme` for Google Slides).
+ * - `latin`: no script-specific choice exists, so the slot repeats the latin family.
+ */
+type ScriptFontSource = "fontScheme" | "schemeFamily" | "language" | "latin";
+/** A per-script supplemental theme font, as in OOXML `<a:font script="Jpan" typeface="..."/>`. */
+interface ScriptFontSupplement {
+    /** OOXML theme script tag (ISO 15924, except Korean uses `Hang`). */
+    script: string;
+    heading: string;
+    body: string;
+}
+interface ResolveScriptFontsOptions {
+    /** Which language font-scheme default applies. Defaults to `powerpoint` (`language.fontScheme`); `google-slides` prefers `language.googleFontScheme`. */
+    app?: ScriptFontApp;
+    /** Merge `slides[slideIndex].design` over the deck design, per field, before resolving the font scheme. */
+    slideIndex?: number;
+    /** Language reference to resolve instead of the document's `language` (catalog id, BCP-47 tag or Language object). */
+    language?: unknown;
+    /** Language tag used when neither the document nor `options.language` names a resolvable language. Defaults to `en-US`. */
+    defaultLanguage?: string;
+}
+interface ResolvedScriptFonts extends ScriptFontSlots {
+    /**
+     * Tag for OOXML `a:rPr/@lang` (and `a:endParaRPr/@lang`): an authored tag that carries a region,
+     * else the language record's curated `ooxmlLang`, else the canonical BCP-47 tag.
+     */
+    lang: string;
+    /** Canonically cased BCP-47 tag for HTML/SVG `lang`: the authored tag, else the record's `bcp47`. */
+    bcp47: string;
+    /** Matched languages catalog record id, when one matched. */
+    languageId?: string;
+    /** `default` when the tag came from `defaultLanguage` because no language resolved. */
+    languageSource: "document" | "option" | "default";
+    /** ISO 15924 script (`Zzzz` when it cannot be determined). */
+    script: string;
+    /** Script slot the language's own text uses. */
+    scriptRole: ScriptRole;
+    direction: "ltr" | "rtl";
+    rtl: boolean;
+    /** Major (heading) theme font slots. */
+    heading: ScriptFontSlots;
+    /** Minor (body) theme font slots. The top-level latin/eastAsian/complexScript repeat these. */
+    body: ScriptFontSlots;
+    /**
+     * Supplemental theme font for the language's script. Present only when an explicit slot, the
+     * design scheme's own script family or the language's font scheme supplies one; absent for
+     * Latin, Cyrillic, Greek and for scripts with no script font. For Armenian, Georgian and
+     * Ethiopic (latin slot) an explicit `complexScript` slot or a design `cs` scheme that serves the
+     * language replaces the language's own font scheme.
+     */
+    supplement?: ScriptFontSupplement;
+    sources: {
+        eastAsian: ScriptFontSource;
+        complexScript: ScriptFontSource;
+    };
+}
+
+/** The OOXML script slot for an ISO 15924 script code. Unknown scripts use the latin slot. */
+declare function scriptFontRole(script: string): ScriptRole;
+/**
+ * Resolve the per-script theme fonts, language tags and direction for a
+ * presentation (or a `{ design, language, catalogs }` subset of one).
+ *
+ * The latin slot follows the effective design font scheme exactly as
+ * `resolveFontFamilies` does; when nothing names a font scheme it falls back to
+ * the shared `DEFAULT_FONT_SCHEME`. Each of the eastAsian and complexScript slots
+ * takes, in order: the design font scheme's explicit slot; the scheme's own
+ * families when its `languageFamily` names the slot and its `languages` list
+ * is empty or names the language; the language's font scheme when the
+ * language's script uses the slot; otherwise the latin family.
+ */
+declare function resolveScriptFonts(input: unknown, options?: ResolveScriptFontsOptions): ResolvedScriptFonts;
+/**
+ * The deck base direction composition lays a slide out in: the direction of the presentation language's script
+ * (`rtl` for Arabic, Hebrew and the other right-to-left scripts), `ltr` when the document names no language or
+ * the language does not resolve. Layout, preview and export all read this one value (RR-05).
+ */
+declare function resolveSlideDirection(presentation: unknown, slideIndex?: number): "ltr" | "rtl";
+
+/**
+ * Deterministic syntax highlighting shared by the SVG preview and the PPTX export (RR-07).
+ *
+ * `tokenizeCode(source, language)` returns coloured token ranges over the exact source
+ * string; everything between tokens is plain. `codeSyntaxPalette` derives one colour per
+ * token kind from the deck theme and keeps each at WCAG contrast >= 4.5:1 against the code
+ * panel. The scanner is a small hand-written one (no dependency, no network, no locale or
+ * clock input): it recognises comments, strings, numbers, keywords, definition names, calls,
+ * capitalised types and the structure of JSON, YAML, TOML, HTML/XML and CSS. It never edits
+ * the text: callers colour ranges of `code.source` and the concatenated runs equal the source.
+ * An unknown or missing language yields no tokens (plain text).
+ */
+type CodeTokenKind = 'comment' | 'keyword' | 'string' | 'number' | 'function' | 'type' | 'property';
+interface CodeToken {
+    start: number;
+    end: number;
+    kind: CodeTokenKind;
+}
+/** A slice of one source line: `kind` is absent for plain text. */
+interface CodeRun {
+    start: number;
+    end: number;
+    kind?: CodeTokenKind;
+}
+type CodeSyntaxPalette = Record<CodeTokenKind | 'plain', string>;
+/** Source longer than this is left plain: highlighting must stay bounded. */
+declare const CODE_HIGHLIGHT_MAX_LENGTH = 200000;
+/** Contrast the palette keeps against the code panel. */
+declare const CODE_SYNTAX_MIN_CONTRAST = 4.5;
+/** The code panel colour the preview and the PPTX export both draw. */
+declare const CODE_PANEL_BACKGROUND = "#111827";
+declare const CODE_PANEL_FOREGROUND = "#E5E7EB";
+/** Language ids with a scanner (the keys the aliases resolve to). */
+declare const CODE_HIGHLIGHT_LANGUAGES: readonly string[];
+/** The scanner id for a `code.language` value, or undefined when the language is not highlighted. */
+declare function resolveCodeLanguage(language: unknown): string | undefined;
+/**
+ * Token ranges of `source` for a `code.language` value, sorted and non-overlapping. Empty for
+ * an unknown language, a missing language, or source longer than CODE_HIGHLIGHT_MAX_LENGTH.
+ */
+declare function tokenizeCode(source: string, language?: unknown): CodeToken[];
+/**
+ * The runs of one source line `[start, end)`: consecutive slices that cover the line exactly.
+ * A token that crosses the line boundary is clipped, so each native text line can be coloured
+ * on its own while concatenating the runs returns the line text unchanged. With `source`, a tab
+ * character is always its own plain run, as in the preview where a tab is a measured segment: a
+ * token (a multi-line string, say) never colours a tab stop.
+ */
+declare function codeLineRuns(tokens: readonly CodeToken[], start: number, end: number, source?: string): CodeRun[];
+interface CodeSyntaxPaletteOptions {
+    background?: string;
+    foreground?: string;
+    minimumContrast?: number;
+}
+interface CodeSyntaxPaletteTheme {
+    primary?: string;
+    secondary?: string;
+    accent?: string;
+    mutedText?: string;
+}
+/**
+ * One colour per token kind from the deck theme: keyword = primary, string = accent,
+ * number = secondary, comment = a fixed slate; function, type and property take fixed hues
+ * (blue, cyan, pink) rotated away from any theme colour they would collide with. Every
+ * colour is lightened until it keeps `minimumContrast` (4.5:1) against the code panel, so a
+ * dark theme colour is raised rather than dropped. Deterministic for a given theme.
+ */
+declare function codeSyntaxPalette(theme?: CodeSyntaxPaletteTheme, options?: CodeSyntaxPaletteOptions): CodeSyntaxPalette;
+/**
+ * The palette for a resolved colour scheme record (`primary`, `secondary`, `accent`, or the
+ * `accent1` to `accent3` slots they default to). The preview and the PPTX export both call this
+ * with the scheme they resolved, so they cannot disagree on the inputs.
+ */
+declare function codeSyntaxPaletteForScheme(scheme: unknown, options?: CodeSyntaxPaletteOptions): CodeSyntaxPalette;
+
+/**
+ * Timeline event status (FA-11): how a `done`, `current` or `planned` event looks in the SVG
+ * preview and in the PPTX export. Core's timeline layout places the markers and the text and
+ * records each event's status on them (see `TimelineLayout.markers` and `TimelineTextPart.status`).
+ * This derives, from that geometry and the deck's colors, the shapes and text colors to draw, so
+ * both engines draw the same marker in the same place and colors.
+ *
+ * - no status, `done`: a filled marker in the primary color, normal text (today's marker).
+ * - `current` ("we are here"): the same filled marker inside a ring, and the label is bold
+ *   (layout sets the weight, so the measured line breaks already include it).
+ * - `planned`: a hollow marker (primary-color outline over the slide background) and muted text.
+ *
+ * Text colors are kept at 4.5:1 against the slide background, outlines and rings at 3:1.
+ */
+
+declare const TIMELINE_STATUSES: readonly ["done", "current", "planned"];
+declare const TIMELINE_TEXT_MIN_CONTRAST = 4.5;
+declare const TIMELINE_OUTLINE_MIN_CONTRAST = 3;
+interface TimelineStatusColors {
+    /** The slide background the timeline sits on. */
+    background: string;
+    /** The marker color (the deck's primary color). */
+    primary: string;
+    /** The color of normal timeline text. */
+    text: string;
+    /** The muted color of planned events' text (the deck's secondary text). */
+    mutedText: string;
+}
+interface TimelineMarkerShape {
+    /** `marker` is the event's dot (or hollow circle), `ring` the circle around a current event's dot. */
+    role: 'marker' | 'ring';
+    /** DrawingML preset name for native export. */
+    shape: 'ellipse';
+    cx: number;
+    cy: number;
+    /** Radius of the drawn ellipse (the marker's `radius`, or the ring's `ring.radius`, 1.6 times it). An outline is centered on the edge, so it reaches half its width beyond. */
+    radius: number;
+    /** Fill color; undefined means no fill (nothing draws inside the shape). */
+    fill?: string;
+    /** Outline; undefined means no outline. */
+    stroke?: {
+        color: string;
+        width: number;
+    };
+}
+/** The shapes of one marker from `layout.markers`, back to front: the ring (current only), then the marker. */
+declare function timelineMarkerShapes(marker: TimelineLayout['markers'][number], colors: TimelineStatusColors): TimelineMarkerShape[];
+/** The color of one timeline text part: muted for a planned event, the normal text color otherwise, kept at >= 4.5:1. */
+declare function timelineTextColor(part: Pick<TimelineTextPart, 'status'>, colors: TimelineStatusColors): string;
+
+/**
+ * Line emphasis for code blocks (`code.highlight`), shared by the SVG preview, the PPTX export and the
+ * validator so they cannot disagree.
+ *
+ * `code.highlight` lists 1-based source lines: a line number or an inclusive `[start, end]` range.
+ * Lines are counted by line break in `code.source`, so a soft-wrapped line is still one line and every
+ * displayed line of it takes the same number (`codeLineNumbers`). Engines draw one band behind each
+ * run of marked displayed lines (`codeHighlightBands`) and set the unmarked lines in a slightly dimmed
+ * colour (`codeHighlightColors`); both colour sets keep WCAG contrast >= 4.5:1 against what they sit on.
+ * Everything here is deterministic: no clock, locale or network.
+ */
+
+/** One `code.highlight` entry: a line number or an inclusive `[start, end]` range. */
+type CodeHighlightEntry = number | [number, number];
+interface CodeHighlightIssue {
+    code: 'code-highlight-out-of-range' | 'code-highlight-range-reversed' | 'code-highlight-invalid';
+    /** Index of the entry in `code.highlight`. */
+    index: number;
+    message: string;
+}
+interface CodeHighlightLines {
+    /** Lines in the source (a final empty line after a trailing line break is not counted). */
+    lineCount: number;
+    /** The marked lines inside the source, ascending and unique. Empty when nothing is marked. */
+    lines: number[];
+    /** Entries that are ignored: past the last line, written end before start, or not line numbers. */
+    issues: CodeHighlightIssue[];
+}
+/** Resolve `code.highlight` against its source: the marked lines, and the entries that are ignored. */
+declare function codeHighlightLines(highlight: unknown, source: string): CodeHighlightLines;
+/** The source line number (from 1) of every displayed line; wrapped lines repeat their line's number. */
+declare function codeLineNumbers(sourceLines: readonly {
+    boundary: 'soft' | 'hard' | 'end';
+}[]): number[];
+/** A run of consecutive displayed lines (indexes into `sourceLines`, inclusive) whose source lines are marked. */
+interface CodeHighlightBand {
+    first: number;
+    last: number;
+}
+/** One band per run of consecutive displayed lines that belong to a marked line. */
+declare function codeHighlightBands(sourceLines: readonly {
+    boundary: 'soft' | 'hard' | 'end';
+}[], lines: readonly number[]): CodeHighlightBand[];
+interface CodeHighlightColors {
+    /** The band behind marked lines: the panel colour tinted with the theme's primary colour. */
+    band: string;
+    /** Marked lines: the syntax palette, each colour at least 4.5:1 on `band`. */
+    lit: CodeSyntaxPalette;
+    /** Unmarked lines: the syntax palette moved toward the panel, never below 4.5:1 on it. */
+    dim: CodeSyntaxPalette;
+}
+/**
+ * The highlight colours for a resolved colour scheme record. The band takes the scheme's `primary`
+ * (or `accent1`); the palette is `codeSyntaxPaletteForScheme(scheme)` so highlighted lines keep their syntax
+ * colours. Preview and export call this with the scheme they resolved.
+ */
+declare function codeHighlightColors(scheme: unknown, palette?: CodeSyntaxPalette): CodeHighlightColors;
+
+/**
+ * Geometry of a text watermark (`design.watermark = { text, opacity }`), shared by the SVG preview and the
+ * PPTX export so both draw the same stamp.
+ *
+ * The stamp is one line of text, centered on the slide and rotated 30 degrees counterclockwise (rising to
+ * the right), the usual diagonal DRAFT or CONFIDENTIAL mark. It is sized so the line spans at most 70% of the
+ * slide width and its height is at most 30% of the shorter slide edge, which keeps the rotated line inside
+ * every preset from 9:16 portrait to 16:9 widescreen.
+ */
+
+interface WatermarkTextOptions {
+    /** The heading family of the design. Defaults to `sans-serif`. */
+    fontFamily?: string;
+    /** Defaults to 700. */
+    fontWeight?: number;
+    textMeasurement?: TextMeasurement;
+}
+interface WatermarkTextLayout {
+    /** The text as drawn: line breaks become spaces and the ends are trimmed. */
+    text: string;
+    fontFamily: string;
+    fontWeight: number;
+    /** The resolved text style (the host's font registry may rename the family). */
+    style: TextStyle;
+    /** In the unit of the size passed in (reference pixels for a composed slide). */
+    fontSize: number;
+    /** Measured width of the line at `fontSize`. */
+    textWidth: number;
+    /** The unrotated text box, centered on the slide; PPTX rotates it about its center. */
+    box: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    /** Rotation about the slide center in degrees, clockwise positive. */
+    rotation: number;
+}
+/** Lay out a text watermark on a slide of `size`; undefined when the text is empty. */
+declare function layoutWatermark(text: unknown, size: {
+    width: number;
+    height: number;
+}, options?: WatermarkTextOptions): WatermarkTextLayout | undefined;
+
+/**
+ * DrawingML preset pattern fills (ECMA-376 20.1.10.51 ST_PresetPatternVal) as 8x8 bitmaps,
+ * shared by the SVG preview (RR-07) and the PPTX export, which writes the same names as native
+ * `a:pattFill prst="..."`.
+ *
+ * ECMA-376 names the 54 presets but does not define their pixels. These tiles are MEASURED from
+ * desktop PowerPoint (Office 365, Windows, 2026-10-01): each preset was exported as a full-slide
+ * pattern background (black on white) to a 1280 x 720 PNG and opf-render's
+ * `scripts/derive-pattern-bitmaps.mjs` voted every pixel into its (x mod 8, y mod 8) cell; every
+ * tile was uniform across all repeats (confidence 1.00) at one image pixel per pattern pixel, so a
+ * pattern pixel is one 1/96 inch unit. The tile is anchored at the slide's top-left corner (the
+ * phase of the line, grid and diagonal presets matched at no shift). Measured pixel data is
+ * committed as data; no third-party table was used. A tile is one row per line, '#' = foreground,
+ * '.' = background, top to bottom, left to right.
+ */
+/** ST_PresetPatternVal, in specification order. */
+declare const PATTERN_PRESETS: readonly string[];
+/** Engine ids that are not DrawingML names, with the preset they draw and export as. */
+declare const PATTERN_PRESET_ALIASES: Readonly<Record<string, string>>;
+/** The pattern size PowerPoint tiles: 8 x 8 units, one unit per 1/96 inch. */
+declare const PATTERN_TILE_SIZE = 8;
+/** The DrawingML preset a pattern id draws as: a preset name, an alias (diagStripe), or undefined. */
+declare function resolvePatternPreset(preset: unknown): string | undefined;
+/** Eight row bytes, top to bottom, most significant bit = leftmost pixel; undefined for an unknown id. */
+declare function patternBitmap(preset: unknown): readonly number[] | undefined;
+/** Horizontal runs of set pixels (`x`, `y`, `width` in tile units), in reading order. */
+declare function patternRuns(preset: unknown): {
+    x: number;
+    y: number;
+    width: number;
+}[] | undefined;
 
 /**
  * Footnotes, citations and captions (RR-34).
  *
  * - A TextRun may `cite` one or more ids of the deck's top-level `references`, or carry an inline
- *   `footnote`. Markers are numbered per deck in reading order of first use (slides, then regions,
+ *   `footnote`. Markers are numbered per deck in reading order of first use (slides: the heading group tag, title, subtitle, then regions,
  *   blocks and runs); the same reference id keeps its number, every footnote takes a new one. A run's
  *   marker is a superscript fragment drawn directly after the run (`1`, or `1,2` for several ids);
  *   `richTextLayouter` emits it from `RichTextOptions.citationMarker`, so it wraps with its word and
@@ -343,8 +907,9 @@ interface AnnotatedRun {
     footnote?: RichText;
 }
 /**
- * Visit every rich-text run of a slide that can carry a citation (text, bullets and list item runs),
- * in reading order: promoted regions (sorted keys), then blocks (recursively), then the root payload.
+ * Visit every rich-text run of a slide that can carry a citation (the slide tag, title and subtitle, then
+ * text, bullets, list item and quote runs), in reading order: the heading group first (tag, title, subtitle),
+ * then promoted regions (sorted keys), then blocks (recursively), then the root payload.
  * `basePath` is the slide's dotted path (`slides.3`).
  */
 declare function walkCitationRuns(slide: unknown, basePath: string, visit: (entry: AnnotatedRun) => void): void;
@@ -488,7 +1053,8 @@ interface ReferencesSlideOptions {
 declare function referencesSlide(presentation: unknown, options?: ReferencesSlideOptions): Record<string, unknown>;
 
 /** The chart constructs the engines draw. Every catalog chart type id resolves to one (see `chartOptionTarget`). */
-type ChartOptionKind = 'bar' | 'line' | 'area' | 'pie' | 'doughnut' | 'scatter' | 'radar' | 'treemap' | 'histogram' | 'pareto' | 'box' | 'waterfall' | 'funnel' | 'map';
+/** `combo` (FA-15) draws clustered columns and line series in one plot, the lines optionally on a secondary value axis. */
+type ChartOptionKind = 'bar' | 'line' | 'area' | 'pie' | 'doughnut' | 'scatter' | 'radar' | 'treemap' | 'histogram' | 'pareto' | 'box' | 'waterfall' | 'funnel' | 'map' | 'combo';
 interface ChartOptionTarget {
     kind: ChartOptionKind;
     /** Stacked and 100% stacked columns, bars, lines and areas: their data labels have no outside-end position. */
@@ -499,7 +1065,7 @@ type ChartLabelContent = 'category' | 'value' | 'percent';
 type ChartLabelPosition = 'center' | 'inside-end' | 'inside-base' | 'outside-end' | 'above' | 'below' | 'left' | 'right';
 interface ChartOptionDiagnostic {
     code: 'chart-option-adapted';
-    /** The option that was adapted: `axisTitles.category`, `axisTitles.value`, `legend`, `dataLabels`, `dataLabels.content`, `dataLabels.position` or `dataLabels.separator`. */
+    /** The option that was adapted: `axisTitles.category`, `axisTitles.value`, `axisTitles.secondary`, `legend`, `dataLabels`, `dataLabels.content`, `dataLabels.position`, `dataLabels.separator`, `line`, `secondaryAxis`, `highlight.series` or `highlight.categories`. */
     option: string;
     reason: 'unsupported-type' | 'unsupported-content' | 'unsupported-position';
     message: string;
@@ -507,34 +1073,57 @@ interface ChartOptionDiagnostic {
 interface ResolvedChartDataLabels {
     /** Canonical order: category, value, percent. Never empty. */
     content: ChartLabelContent[];
-    /** The concrete position, or null for a construct whose labels have no position choice (area, doughnut, radar, treemap). */
+    /** The concrete position, or null for a construct whose labels have no position choice (area, doughnut, radar, treemap). On a combo chart, the column series' position. */
     position: ChartLabelPosition | null;
+    /** Combo charts only: the concrete position of the line series' labels (`position` is the column series' one). */
+    linePosition?: ChartLabelPosition;
     separator: string;
 }
+/** FA-14: the series and category names `chart.highlight` keeps for a chart type (what the type cannot highlight is dropped, with a diagnostic). */
+interface ResolvedChartHighlight {
+    /** Series (column) names whose marks take the accent colour. */
+    series: string[];
+    /** Category (row label) names whose marks take the accent colour. */
+    categories: string[];
+}
 interface ResolvedChartOptions {
     /** True when the chart carries at least one option (after adaptation); false means every engine keeps today's output. */
     active: boolean;
+    /** `secondary` titles the secondary value axis of a combo chart. */
     axisTitles: {
         category?: string;
         value?: string;
+        secondary?: string;
     };
     /** Undefined = no legend option: each engine keeps its default (a right legend on multi-series, pie and doughnut charts). */
     legend?: ChartLegendPosition;
     dataLabels?: ResolvedChartDataLabels;
     /** True when `dataLabels: false` switches off the labels a construct draws by default (funnel values, treemap category names). */
     dataLabelsOff?: boolean;
+    /**
+     * FA-14: the names `chart.highlight` keeps; undefined when the chart has no highlight or its type can highlight nothing it names.
+     * It does not make `active` true: a highlight changes the colours of marks, never the geometry or the reserved space.
+     */
+    highlight?: ResolvedChartHighlight;
     diagnostics: ChartOptionDiagnostic[];
 }
 interface ChartOptionSupport {
+    /** `secondary`: the construct can have a secondary value axis (a combo chart whose `secondaryAxis` names a line series). */
     axisTitles: {
         category: boolean;
         value: boolean;
+        secondary: boolean;
     };
     legend: boolean;
+    /** FA-14: what `chart.highlight` can name: series (a whole series' marks) and categories (one category's marks, or a pie slice). */
+    highlight: {
+        series: boolean;
+        categories: boolean;
+    };
     dataLabels: {
         supported: boolean;
         content: readonly ChartLabelContent[];
-        /** Empty when labels have no position choice. */
+        /** Empty when labels have no position choice. A combo chart lists the column positions, then the line-only ones. */
         positions: readonly ChartLabelPosition[];
         /** The position `auto` resolves to; null with no positions. */
         defaultPosition: ChartLabelPosition | null;
@@ -544,7 +1133,7 @@ interface ChartOptionSupport {
 }
 /** What a chart construct can show. The table the docs, the validator, the preview and the exporter all follow. */
 declare function chartOptionSupport(target: ChartOptionTarget): ChartOptionSupport;
-/** The option target for a catalog chart type id (deprecated ids resolve to their replacement); undefined for an id outside the catalog. */
+/** The option target for a catalog chart type id; undefined for an id outside the catalog. */
 declare function chartOptionTarget(typeId: unknown): ChartOptionTarget | undefined;
 declare const DEFAULT_CHART_LABEL_SEPARATOR = ", ";
 /**
@@ -562,6 +1151,53 @@ declare function chartLabelText(parts: {
     value?: string;
     percent?: string;
 }, content: readonly ChartLabelContent[], separator?: string): string;
+/** Which marks of a chart a highlight names, in the order of the resolved chart data. */
+interface ChartHighlightMarks {
+    /** One flag per plotted series (the columns after the category and X columns): its marks are highlighted. */
+    series: boolean[];
+    /** One flag per data row: the marks of that category are highlighted. */
+    categories: boolean[];
+}
+/**
+ * FA-14: which series and categories of a chart are highlighted. `highlight` is `resolveChartOptions(...).highlight` and `data` the
+ * chart's `resolveChartData` result (its `columns`, `hasX` and `rows`). A mark is highlighted when its series OR its category is
+ * named: a column or bar of series s in row i takes the accent colour when `series[s] || categories[i]`; every other mark takes the muted
+ * colour (`chartHighlightColors`). Category names match the row labels as text (a number label `2024` matches `"2024"`, an empty label
+ * matches `""`), every row that carries the label. Returns undefined when there is no highlight or it names nothing the chart plots (a
+ * name that matches no column or label is the `chart-highlight-unknown-name` validation error), so the engines then draw the chart as if
+ * it had none.
+ */
+declare function chartHighlightMarks(highlight: ResolvedChartHighlight | undefined, data: {
+    columns: readonly string[];
+    hasX?: boolean;
+    rows: readonly (readonly unknown[])[];
+}): ChartHighlightMarks | undefined;
+
+/** Placeholder kinds that hold slide content (everything except the three heading kinds). */
+declare const LAYOUT_BODY_KINDS: readonly ["text", "list", "image", "video", "chart", "table", "code", "metric", "quote", "timeline"];
+type LayoutBodyKind = typeof LAYOUT_BODY_KINDS[number];
+/** What a layout record holds, derived from its placeholders. */
+interface LayoutContent {
+    /** The most frequent body placeholder kind (a tie goes to the kind that appears first in placeholder order), or 'title' when the layout has no body placeholder. */
+    kind: LayoutBodyKind | 'title';
+    /** The number of body placeholders. */
+    count: number;
+    /** Which heading placeholders the layout has. */
+    heading: {
+        title: boolean;
+        subtitle: boolean;
+        tag: boolean;
+    };
+}
+/**
+ * Derives what a layout holds from its `placeholders`, which are the single source of truth: the content kind,
+ * the number of body regions and which headings it has are never stored on the record.
+ */
+declare function layoutContent(record: {
+    placeholders?: ReadonlyArray<{
+        type?: string;
+    } | null | undefined>;
+} | null | undefined): LayoutContent;
 
 /** Portable layout geometry. No fonts, DOM, renderer, or network dependencies. */
 interface Composition {
@@ -597,6 +1233,8 @@ interface TextStyle {
     italic?: boolean;
     path?: string;
     fontFace?: FontFaceSelection;
+    /** BCP-47 tag of a run that overrides the deck language (`TextRun.lang`); absent when the deck language applies. */
+    lang?: string;
 }
 /** Role families. `accent` is present only when the scheme defines an accent role; the slide tag and quote body use it. */
 interface FontFamilies {
@@ -635,7 +1273,7 @@ declare function resolveFontSchemeReference(reference: unknown, lookup: (id: str
  * A scheme that names no heading or body family gets the DEFAULT_FONT_SCHEME families (Aptos Display, Aptos).
  * `code` comes from the scheme's `code` role, which catalog records such as consolas and courier-new
  * carry; otherwise it is Roboto Mono. Heading and body families are never reused for code.
- * `accent` is returned only when the scheme defines an `accent` role (a family string or Font object);
+ * `accent` is returned only when the scheme defines an `accent` role (a family name string);
  * the slide tag and the quote body use it in place of the body and heading families. */
 declare function resolveFontFamilies(input: unknown): FontFamilies;
 interface TextMeasurement {
@@ -645,6 +1283,14 @@ interface TextMeasurement {
      * Null means no outline. These are not hinted/antialiased raster bounds. */
     outlineBounds?: (text: string, fontSize: number, style: TextStyle) => LayoutBox | null;
 }
+/**
+ * The fonts handle every deck-level verb takes as `{ fonts }`. Core reads only `textMeasurement`: how wide the
+ * host's real fonts draw a string. The renderer's `loadFonts()` returns a richer handle (embedded fonts, font
+ * files, registry, manifest) that extends this one, so the same object goes to every verb.
+ */
+interface Fonts {
+    textMeasurement?: TextMeasurement;
+}
 type MeasureTextWidth = (text: string, fontSize: number) => number;
 declare function resolveTextStyle(style: TextStyle, measurement?: TextMeasurement): TextStyle;
 declare function textWidthMeasurer(style: TextStyle, measurement?: TextMeasurement): MeasureTextWidth;
@@ -723,15 +1369,15 @@ interface ComposedItem {
     composition: Composition;
     /**
      * Resolved horizontal text alignment for this item: titleAlignment for the
-     * title, contentAlignment for every other item (slide design, then host
-     * option, then left). Engines anchor native and preview text to this value.
+     * title, contentAlignment for every other item (slide design, deck design, layout design,
+     * then left). Engines anchor native and preview text to this value.
      */
     alignment: 'left' | 'center' | 'right';
 }
 /**
  * Slide-level image resolved from design.slideImage. It is active when the slide sets its own
- * design.slideImage, or when the deck sets one and either the slide's layout record declares
- * slideImage: true or the slide's root image is the same source.
+ * design.slideImage, or when the deck sets one and either the slide's layout record sets
+ * design.slideImage, or the slide's root image is the same source.
  * Content composes in the part of the slide the image does not occupy; 'background' leaves the whole slide.
  */
 interface ComposedSlideImage {
@@ -880,6 +1526,12 @@ interface SlideComposition {
     composition: Composition;
     /** Repeated furniture is measured separately from body pagination leaves. */
     furniture?: FurnitureLayout;
+    /**
+     * Effective shared design hints of this slide: slide design, then deck design, then the layout record's design,
+     * per key. Renderers and exporters read titleAlignment, contentAlignment, contentBox, imageFill and
+     * listBullet here instead of re-deriving them from the document.
+     */
+    design: ResolvedDesignHints;
     /** Active slide-level image; absent when design.slideImage does not apply to this slide. */
     slideImage?: ComposedSlideImage;
     /** Deck logo on a cover or section slide; absent on content slides and when no logo resolves. */
@@ -906,11 +1558,16 @@ interface ComposeSlideOptions {
             contentDirection?: unknown;
             chartPrimary?: unknown;
             listBullet?: unknown;
+            titleAlignment?: unknown;
+            contentAlignment?: unknown;
+            contentBox?: unknown;
         };
         organization?: unknown;
+        speaker?: unknown;
         slides?: unknown;
         catalogs?: unknown;
         references?: unknown;
+        datasets?: unknown;
     };
     /**
      * Whether the slide background is dark, by the host's own luminance test. Selects the light logo
@@ -933,7 +1590,7 @@ interface ComposeSlideOptions {
      * consults a clock; without this option a current date is reported as unresolved content.
      */
     date?: string;
-    fonts?: Partial<FontFamilies>;
+    fontFamilies?: Partial<FontFamilies>;
     /**
      * Deck base direction (RR-05). Defaults to the direction of the presentation language's script. In a right-to-left deck
      * composition mirrors the arrangement (the first column or `left` region is drawn at the right, slide images, logos and
@@ -941,12 +1598,12 @@ interface ComposeSlideOptions {
      * reports each paragraph's direction. Alignment stays logical: `left` is the start edge.
      */
     direction?: TextDirection;
-    /** Host-resolved alignment for shared content; slide design can override it. */
+    /** Deck-level alignment a host resolved itself. It ranks with `presentation.design`, above the layout record's design and below the slide's own design; hosts normally omit it because composition reads `presentation.design` and the layout. */
     contentAlignment?: 'left' | 'center' | 'right';
     titleAlignment?: 'left' | 'center' | 'right';
     /** Unscaled reference pixels around provided vector outlines; defaults to 1 for body text and 2 for furniture. Explicit values apply to both. */
     textRasterPadding?: number;
-    /** Host-resolved body cards. A slide's explicit design.contentBox overrides this value. */
+    /** Deck-level body cards a host resolved itself, ranked like contentAlignment. A slide's explicit design.contentBox overrides this value. */
     contentBox?: boolean;
     textMeasurement?: TextMeasurement;
     width?: number;
@@ -990,7 +1647,7 @@ declare function resolveLogo(presentation: unknown, slide: unknown, options?: Re
 interface FurniturePartBase {
     kind: 'header' | 'footer';
     zone: 'left' | 'center' | 'right';
-    field: 'text' | 'image' | 'logo' | 'organization' | 'socials' | 'section' | 'slideNumber' | 'date';
+    field: 'text' | 'image' | 'logo' | 'organization' | 'speaker' | 'socials' | 'section' | 'slideNumber' | 'date';
     /** Literal field or controlling flag, with the actual inherited/local path. */
     path: string;
     /** String/asset source, when different from a generated field's flag. */
@@ -1088,9 +1745,12 @@ declare const FONT_SIZE_GRID_PER_PX = 75;
 declare function snapFontSizeDown(px: number): number;
 /** Smallest grid size not below `px`. Used for readability floors, so a floor is never undercut. */
 declare function snapFontSizeUp(px: number): number;
+/** `text` is a string or TextRun[] (FA-10); attribution, role and source stay plain strings. */
 interface QuoteContent {
-    text: string;
+    text: string | readonly (string | RichTextRun)[];
     attribution?: string;
+    role?: string;
+    photo?: unknown;
     source?: string;
 }
 /** Source and displayed-text ranges are half-open UTF-16 offsets. Added punctuation has no source range. */
@@ -1112,24 +1772,46 @@ interface QuoteTextPart {
     minFontSize: number;
     requestedStyle: TextStyle;
     style: TextStyle;
-    /** Absent when the available box is invalid; never fit against an invented one-pixel box. */
-    fit?: TextFit;
+    /**
+     * The displayed runs of a rich quote body (FA-10): the quote's TextRun[] with the quotation marks joined to its first and
+     * last run, so a run's index and a citation marker's position never shift. Absent for a string body and for the footer.
+     */
+    runs?: (string | RichTextRun)[];
+    /** Absent when the available box is invalid; never fit against an invented one-pixel box. A rich body reports a RichTextFit. */
+    fit?: TextFit | RichTextFit;
 }
 interface QuoteLayoutDiagnostic extends LayoutDiagnostic {
-    reason: 'invalid-part-box' | 'part-outside-cell' | 'text-fit' | 'part-overlap';
+    reason: 'invalid-part-box' | 'part-outside-cell' | 'text-fit' | 'part-overlap' | 'photo-fit';
     parts: QuoteTextPart['role'][];
 }
+/**
+ * The attributed person's headshot (FA-12): a circle at the start edge of the footer row, beside the
+ * attribution and role lines (the left in a left-to-right deck, the right in a right-to-left one). Its diameter is
+ * three times the footer font size, so it follows the text when the footer shrinks toward the readability floor.
+ */
+interface QuotePhoto {
+    /** Path of the photo value, `<quote path>.photo`. */
+    path: string;
+    /** Asset value (string or Asset object) that engines resolve like any other image; crop to cover the frame. */
+    value: unknown;
+    /** Square frame, in reference pixels. */
+    box: LayoutBox;
+    /** Circle mask: the `ellipse` DrawingML preset and the same outline as an SVG path, as design.slideImage shape 'circle'. */
+    shape: SlideImageShape;
+}
 interface QuoteLayout {
     algorithm: 'quote-flow-v1';
     textMeasurement: 'estimated' | 'provided';
     parts: QuoteTextPart[];
+    /** Present when the quote has a photo; absent otherwise, and then the layout is the footer-only layout. */
+    photo?: QuotePhoto;
     diagnostics: QuoteLayoutDiagnostic[];
     overflow: boolean;
 }
 interface QuoteLayoutOptions {
     /** Canvas short edge divided by 720. Insets retain the current 18 reference-pixel contract. */
     scale?: number;
-    fonts?: Partial<FontFamilies>;
+    fontFamilies?: Partial<FontFamilies>;
     /** Readability floor in reference pixels, before canvas scaling. */
     minFontSize?: number;
     overflow?: Composition['overflow'];
@@ -1137,6 +1819,8 @@ interface QuoteLayoutOptions {
     textMeasurement?: TextMeasurement;
     /** Deck direction; in a right-to-left deck every part fit reports its paragraphs' directions (RR-05). */
     direction?: TextDirection;
+    /** Marker text for a rich body run by its dotted path (`<path>.text.<runIndex>`); composeSlide supplies the deck numbering. */
+    citationMarker?: (runPath: string) => string | undefined;
 }
 /**
  * Allocate and measure quote body/footer space for composition, rendering and export. Callers must
@@ -1150,7 +1834,11 @@ interface MetricContent {
     unit?: string;
     delta?: string | number;
     trend?: 'up' | 'down' | 'flat';
+    /** Whether the change is good news; colours the trend arrow, trend word and delta text (see metricTrendColor). */
+    sentiment?: MetricSentiment;
 }
+/** The text fields of a metric, each laid out as its own part. `sentiment` is metadata, not text. */
+type MetricTextRole = Exclude<keyof MetricContent, 'sentiment'>;
 /** Ranges address String(sourceValue), not the numeric token spelling in serialized JSON. */
 interface MetricTextSource {
     path: string;
@@ -1159,7 +1847,7 @@ interface MetricTextSource {
     end: number;
 }
 interface MetricTextPart {
-    role: keyof MetricContent;
+    role: MetricTextRole;
     path: string;
     text: string;
     sources: MetricTextSource[];
@@ -1187,6 +1875,8 @@ interface MetricLayout {
     alignment: 'left' | 'center' | 'right';
     textMeasurement: 'estimated' | 'provided';
     arrangement: 'inline-unit' | 'stacked';
+    /** The metric's `sentiment`, passed through for metricTrendMark; omitted when the content has none. */
+    sentiment?: MetricSentiment;
     /** At most 48 arrangements; value fitting is bounded by 77 reference-size trials per arrangement. */
     attempts: number;
     parts: MetricTextPart[];
@@ -1205,10 +1895,13 @@ interface MetricLayoutOptions extends QuoteLayoutOptions {
  * beside it from these accepted parts. Consumers must reuse these accepted parts and source ranges.
  */
 declare function layoutMetric(value: string | number | MetricContent, box: LayoutBox, options?: MetricLayoutOptions): MetricLayout;
+/** Progress of a timeline event (FA-11). Engines draw it from the deck's colors; see `timelineMarkerShapes`. */
+type TimelineStatus = 'done' | 'current' | 'planned';
 interface TimelineEvent {
     when?: string;
     what: string;
     description?: string;
+    status?: TimelineStatus;
 }
 interface TimelineContent {
     name?: string;
@@ -1218,6 +1911,8 @@ interface TimelineContent {
 interface TimelineTextPart {
     role: 'name' | 'description' | 'when' | 'what' | 'event-description';
     eventIndex?: number;
+    /** The event's status; absent for metadata parts and for events without a status. */
+    status?: TimelineStatus;
     path: string;
     text: string;
     sources: {
@@ -1244,12 +1939,23 @@ interface TimelineLayout {
     textMeasurement: 'provided' | 'estimated';
     textOutlines: 'provided' | 'unavailable';
     parts: TimelineTextPart[];
+    /**
+     * One marker per event. `radius` is the marker's own radius; `status` repeats the event's status
+     * (absent without one). A 'current' marker also has `ring.radius`, 1.6 times `radius`, and a
+     * 'current' or 'planned' marker has the `strokeWidth` of its outline and ring. Every radius is that
+     * of the drawn ellipse; an outline is centered on the ellipse edge, so it reaches half a stroke beyond.
+     */
     markers: {
         path: string;
         eventIndex: number;
         x: number;
         y: number;
         radius: number;
+        status?: TimelineStatus;
+        ring?: {
+            radius: number;
+        };
+        strokeWidth?: number;
     }[];
     connector: {
         x1: number;
@@ -1344,6 +2050,10 @@ interface RichTextRun {
     link?: string;
     superscript?: boolean;
     subscript?: boolean;
+    /** Inline code: the run takes the design's code font (`RichTextOptions.codeFontFamily`) unless it names its own `fontFamily`. */
+    code?: boolean;
+    /** BCP-47 tag that overrides the deck language for this run; it reaches the fragment style as `style.lang`. */
+    lang?: string;
     /** RR-34: reference ids this run cites (a marker follows the run; the deck's `references` list resolves them). */
     cite?: string | string[];
     /** RR-34: an inline footnote for this run (a marker follows the run; the note is listed in the slide's footnote area). */
@@ -1382,6 +2092,8 @@ interface RichTextFit extends TextFit {
 }
 interface RichTextOptions {
     style: TextStyle;
+    /** The design's code family for runs with `code: true`; `monospace` when absent. */
+    codeFontFamily?: string;
     textMeasurement?: TextMeasurement;
     /** Use one measured line advance for every line, as native table cells do. */
     uniformLineHeight?: boolean;
@@ -1469,8 +2181,14 @@ interface TableLayoutOptions {
     scale?: number;
     minFontSize?: number;
     fontFamily?: string;
+    /** The design's code family for cell runs with `code: true`. */
+    codeFontFamily?: string;
     textMeasurement?: TextMeasurement;
     path?: string;
+    /** RR-54: the document, for a dataset-backed table (`{ dataset }`): its headers, rows and column formats come from `datasets`. */
+    presentation?: {
+        datasets?: unknown;
+    };
     /**
      * Deck direction. A right-to-left deck lays the columns out right to left: the first column is the rightmost
      * and each cell's text reports its paragraph direction (RR-05).
@@ -1520,4 +2238,4 @@ declare function resolveCanvasDimensions(input: unknown): {
     height: number;
 };
 
-export { DEFAULT_FURNITURE_DATE_FORMAT as $, type AnnotatedRun as A, type CodeLayoutOptions as B, type ComposeSlideOptions as C, type CodeLineSegment as D, type CodeLineSource as E, type FontSchemeDiagnostic as F, type CodeTextFit as G, type CodeTextPart as H, type ComposedCaption as I, type ComposedFlow as J, type ComposedFootnoteEntry as K, type LayoutDiagnostic as L, type MetricLayout as M, type ComposedFootnotes as N, type ComposedGroup as O, type ComposedItem as P, type ComposedLogo as Q, type ComposedSlideImage as R, type Composition as S, type TextMeasurement as T, type CompositionCandidate as U, type CompositionDecision as V, type CompositionExplanation as W, type CompositionPenalties as X, type CompositionTrack as Y, DEFAULT_CHART_LABEL_SEPARATOR as Z, DEFAULT_FONT_SCHEME as _, type AnnotationFitter as a, type RichTextRun as a$, DEFAULT_SLIDE_NUMBER_FORMAT as a0, type DeckCitations as a1, FONT_SIZE_GRID_PER_PX as a2, FOOTNOTE_MAX_RATIO as a3, type FontFamilies as a4, type FootnoteLayoutOptions as a5, type FurnitureField as a6, type FurnitureImagePart as a7, type FurnitureLayout as a8, type FurniturePart as a9, type NumberingInput as aA, type NumberingStyleName as aB, type NumberingSuffix as aC, OPFCompositionError as aD, PICTURE_BULLET_SCALE as aE, type PhysicalAlignment as aF, type QuoteContent as aG, type QuoteLayout as aH, type QuoteLayoutDiagnostic as aI, type QuoteLayoutOptions as aJ, type QuoteTextPart as aK, type QuoteTextSource as aL, type Reference as aM, type ReferencesSlideOptions as aN, type ResolveColorRefOptions as aO, type ResolveColorRefRoles as aP, type ResolveLogoOptions as aQ, type ResolvedChartDataLabels as aR, type ResolvedChartOptions as aS, type ResolvedFontScheme as aT, type ResolvedLogo as aU, type ResolvedNumbering as aV, type RichText as aW, type RichTextFit as aX, type RichTextFragment as aY, type RichTextLine as aZ, type RichTextOptions as a_, type FurniturePartBase as aa, type FurnitureSocialLink as ab, type FurnitureTextExtras as ac, type FurnitureTextPart as ad, type LayoutBox as ae, type ListBulletImage as af, type ListEntryLayout as ag, type ListFit as ah, type ListFitOptions as ai, type ListNumber as aj, type ListText as ak, type ListValue as al, type LogoSlot as am, MAX_COMPOSITION_DEPTH as an, MAX_NUMBERING_LEVELS as ao, MAX_NUMBERING_VALUE as ap, MAX_ROMAN_VALUE as aq, type MeasureTextWidth as ar, type MetricContent as as, type MetricLayoutDiagnostic as at, type MetricLayoutOptions as au, type MetricTextPart as av, type MetricTextSource as aw, NUMBERING_STYLES as ax, NUMBERING_SUFFIXES as ay, type Numbering as az, type AnnotationLayoutOptions as b, sliceNumberedItems as b$, type SlideCitations as b0, type SlideComposition as b1, type SlideImageShape as b2, type SocialPlatformRecord as b3, type SocialProfile as b4, type TextDirection as b5, type TextFit as b6, type TextLineInk as b7, type TextPlacement as b8, type TextPlacementLine as b9, layoutCaption as bA, layoutCode as bB, layoutFootnotes as bC, layoutFurniture as bD, layoutMetric as bE, layoutQuote as bF, layoutTimeline as bG, listNumbers as bH, measureText as bI, measureTextOutline as bJ, normalizeHexColor as bK, numberingAtLevel as bL, numberingStyleDraws as bM, paragraphDirection as bN, paragraphDirectionAt as bO, physicalAlignment as bP, placeTextLines as bQ, referencesSlide as bR, resolveCanvasDimensions as bS, resolveChartOptions as bT, resolveColorRef as bU, resolveFontFamilies as bV, resolveFontSchemeReference as bW, resolveLogo as bX, resolveNumbering as bY, resolveSocialProfile as bZ, resolveTextStyle as b_, type TextStyle as ba, type TimelineContent as bb, type TimelineEvent as bc, type TimelineLayout as bd, type TimelineLayoutDiagnostic as be, type TimelineLayoutOptions as bf, type TimelineTextPart as bg, annotationText as bh, captionSettings as bi, chartColorForFill as bj, chartLabelText as bk, chartOptionSupport as bl, chartOptionTarget as bm, chartPaletteForFill as bn, citationMarkerText as bo, collectCitations as bp, colorContrast as bq, composeSlide as br, fitList as bs, fitRichText as bt, fitText as bu, formatChartLabelNumber as bv, formatChartLabelPercent as bw, formatFurnitureDate as bx, formatListNumber as by, formatSlideNumber as bz, CAPTIONABLE_FIELDS as c, slideCitations as c0, snapFontSizeDown as c1, snapFontSizeUp as c2, textColorForFill as c3, textWidthMeasurer as c4, walkCitationRuns as c5, wrapText as c6, type FontFaceSelection as c7, type ReadingBox as c8, type SourceTextFit as c9, type TableBorder as ca, type TableCellLayout as cb, type TableCellStyle as cc, type TableGrid as cd, type TableGridCell as ce, type TableGridIssue as cf, type TableLayout as cg, type TableLayoutOptions as ch, type TableRowLayout as ci, type TextLineSegment as cj, type TextLineSource as ck, layoutTable as cl, slideImageShape as cm, tableGrid as cn, tableRowBoundaries as co, visualReadingOrder as cp, CAPTION_FONT_RATIO as d, CAPTION_MAX_RATIO as e, CHART_SERIES_MIN_DIFFERENCE as f, CHART_SERIES_MIN_LIGHTNESS_STEP as g, CITATION_MARKER_RAISE as h, CITATION_MARKER_SCALE as i, type Caption as j, type CaptionAlignment as k, type CaptionObject as l, type CaptionPosition as m, type CaptionSettings as n, type ChartLabelContent as o, type ChartLabelPosition as p, type ChartLegendPosition as q, type ChartOptionDiagnostic as r, type ChartOptionKind as s, type ChartOptionSupport as t, type ChartOptionTarget as u, type CitationMarker as v, type CitationNote as w, type CodeContent as x, type CodeLayout as y, type CodeLayoutDiagnostic as z };
+export { type CodeRun as $, type AnnotatedRun as A, type ChartHighlightMarks as B, type ComposeSlideOptions as C, type ChartLabelContent as D, type ChartLabelPosition as E, type FontFamilies as F, type ChartLegendPosition as G, type ChartOptionDiagnostic as H, type ChartOptionKind as I, type ChartOptionSupport as J, type ChartOptionTarget as K, type LanguageFamilyName as L, type MeasureTextWidth as M, type CitationMarker as N, type CitationNote as O, type CodeContent as P, type CodeHighlightBand as Q, type CodeHighlightColors as R, type CodeHighlightEntry as S, type TextMeasurement as T, type CodeHighlightIssue as U, type CodeHighlightLines as V, type CodeLayout as W, type CodeLayoutDiagnostic as X, type CodeLayoutOptions as Y, type CodeLineSegment as Z, type CodeLineSource as _, type FontSchemeDiagnostic as a, type MetricLayoutDiagnostic as a$, type CodeSyntaxPalette as a0, type CodeSyntaxPaletteOptions as a1, type CodeSyntaxPaletteTheme as a2, type CodeTextFit as a3, type CodeTextPart as a4, type CodeToken as a5, type CodeTokenKind as a6, type ComposedCaption as a7, type ComposedFlow as a8, type ComposedFootnoteEntry as a9, type FurnitureImagePart as aA, type FurnitureLayout as aB, type FurniturePart as aC, type FurniturePartBase as aD, type FurnitureSocialLink as aE, type FurnitureTextExtras as aF, type FurnitureTextPart as aG, LAYOUT_BODY_KINDS as aH, type LayoutBodyKind as aI, type LayoutBox as aJ, type LayoutContent as aK, type ListBulletImage as aL, type ListEntryLayout as aM, type ListFit as aN, type ListFitOptions as aO, type ListNumber as aP, type ListText as aQ, type ListValue as aR, type LogoSlot as aS, MAX_COMPOSITION_DEPTH as aT, MAX_NUMBERING_LEVELS as aU, MAX_NUMBERING_VALUE as aV, MAX_ROMAN_VALUE as aW, METRIC_TREND_MIN_CONTRAST as aX, METRIC_TREND_SHAPES as aY, type MetricContent as aZ, type MetricLayout as a_, type ComposedFootnotes as aa, type ComposedGroup as ab, type ComposedItem as ac, type ComposedLogo as ad, type ComposedSlideImage as ae, type Composition as af, type CompositionCandidate as ag, type CompositionDecision as ah, type CompositionExplanation as ai, type CompositionPenalties as aj, type CompositionTrack as ak, DARK_BACKGROUND_LUMINANCE as al, DEFAULT_CHART_LABEL_SEPARATOR as am, DEFAULT_FONT_SCHEME as an, DEFAULT_FURNITURE_DATE_FORMAT as ao, DEFAULT_SLIDE_NUMBER_FORMAT as ap, DESIGN_HINT_KEYS as aq, type DeckCitations as ar, type DesignHintKey as as, type DesignHintSource as at, type DesignHints as au, FONT_SIZE_GRID_PER_PX as av, FOOTNOTE_MAX_RATIO as aw, type FontFaceSelection as ax, type FootnoteLayoutOptions as ay, type FurnitureField as az, type Fonts as b, TIMELINE_OUTLINE_MIN_CONTRAST as b$, type MetricLayoutOptions as b0, type MetricSentiment as b1, type MetricTextPart as b2, type MetricTextSource as b3, type MetricTrend as b4, type MetricTrendColorOptions as b5, type MetricTrendMark as b6, NUMBERING_STYLES as b7, NUMBERING_SUFFIXES as b8, type Numbering as b9, type ResolvedChartHighlight as bA, type ResolvedChartOptions as bB, type ResolvedColorRoles as bC, type ResolvedDesignHints as bD, type ResolvedFontScheme as bE, type ResolvedLogo as bF, type ResolvedNumbering as bG, type ResolvedScriptFonts as bH, type RichText as bI, type RichTextFit as bJ, type RichTextFragment as bK, type RichTextLine as bL, type RichTextOptions as bM, type RichTextRun as bN, SURFACE_ALT_MIN_CONTRAST as bO, SURFACE_ALT_MIX as bP, type ScriptFontApp as bQ, type ScriptFontSlots as bR, type ScriptFontSource as bS, type ScriptFontSupplement as bT, type ScriptRole as bU, type SlideCitations as bV, type SlideComposition as bW, type SlideImageShape as bX, type SocialPlatformRecord as bY, type SocialProfile as bZ, type SourceTextFit as b_, type NumberingInput as ba, type NumberingStyleName as bb, type NumberingSuffix as bc, OPFCompositionError as bd, PATTERN_PRESETS as be, PATTERN_PRESET_ALIASES as bf, PATTERN_TILE_SIZE as bg, PICTURE_BULLET_SCALE as bh, type PhysicalAlignment as bi, type QuoteContent as bj, type QuoteLayout as bk, type QuoteLayoutDiagnostic as bl, type QuoteLayoutOptions as bm, type QuotePhoto as bn, type QuoteTextPart as bo, type QuoteTextSource as bp, type ReadingBox as bq, type Reference as br, type ReferencesSlideOptions as bs, type ResolveColorRefOptions as bt, type ResolveColorRefRoles as bu, type ResolveColorRolesOptions as bv, type ResolveDesignHintsOptions as bw, type ResolveLogoOptions as bx, type ResolveScriptFontsOptions as by, type ResolvedChartDataLabels as bz, type LayoutDiagnostic as c, layoutFurniture as c$, TIMELINE_STATUSES as c0, TIMELINE_TEXT_MIN_CONTRAST as c1, type TableBorder as c2, type TableCellLayout as c3, type TableCellStyle as c4, type TableGrid as c5, type TableGridCell as c6, type TableGridIssue as c7, type TableLayout as c8, type TableLayoutOptions as c9, chartOptionTarget as cA, chartPaletteForFill as cB, citationMarkerText as cC, codeHighlightBands as cD, codeHighlightColors as cE, codeHighlightLines as cF, codeLineNumbers as cG, codeLineRuns as cH, codeSyntaxPalette as cI, codeSyntaxPaletteForScheme as cJ, collectCitations as cK, colorContrast as cL, composeSlide as cM, defaultSlideBackground as cN, fitList as cO, fitRichText as cP, fitText as cQ, formatChartLabelNumber as cR, formatChartLabelPercent as cS, formatFurnitureDate as cT, formatListNumber as cU, formatSlideNumber as cV, isDarkColor as cW, layoutCaption as cX, layoutCode as cY, layoutContent as cZ, layoutFootnotes as c_, type TableRowLayout as ca, type TextDirection as cb, type TextFit as cc, type TextLineInk as cd, type TextLineSegment as ce, type TextLineSource as cf, type TextPlacement as cg, type TextPlacementLine as ch, type TimelineContent as ci, type TimelineEvent as cj, type TimelineLayout as ck, type TimelineLayoutDiagnostic as cl, type TimelineLayoutOptions as cm, type TimelineMarkerShape as cn, type TimelineStatus as co, type TimelineStatusColors as cp, type TimelineTextPart as cq, type WatermarkTextLayout as cr, type WatermarkTextOptions as cs, annotationText as ct, captionSettings as cu, chartColorForFill as cv, chartHighlightColors as cw, chartHighlightMarks as cx, chartLabelText as cy, chartOptionSupport as cz, type TextStyle as d, layoutMetric as d0, layoutQuote as d1, layoutTable as d2, layoutTimeline as d3, layoutWatermark as d4, listNumbers as d5, measureText as d6, measureTextOutline as d7, metricTrendColor as d8, metricTrendMark as d9, resolveTextStyle as dA, scriptFontRole as dB, sliceNumberedItems as dC, slideCitations as dD, slideImageShape as dE, snapFontSizeDown as dF, snapFontSizeUp as dG, surfaceAltColor as dH, tableGrid as dI, tableRowBoundaries as dJ, textColorForFill as dK, textWidthMeasurer as dL, timelineMarkerShapes as dM, timelineTextColor as dN, tokenizeCode as dO, visualReadingOrder as dP, walkCitationRuns as dQ, wrapText as dR, metricTrendPoints as da, normalizeHexColor as db, numberingAtLevel as dc, numberingStyleDraws as dd, paragraphDirection as de, paragraphDirectionAt as df, patternBitmap as dg, patternRuns as dh, physicalAlignment as di, placeTextLines as dj, referencesSlide as dk, resolveCanvasDimensions as dl, resolveChartOptions as dm, resolveCodeLanguage as dn, resolveColorRef as dp, resolveColorRoles as dq, resolveDesignHints as dr, resolveFontFamilies as ds, resolveFontSchemeReference as dt, resolveLogo as du, resolveNumbering as dv, resolvePatternPreset as dw, resolveScriptFonts as dx, resolveSlideDirection as dy, resolveSocialProfile as dz, type AnnotationFitter as e, type AnnotationLayoutOptions as f, CAPTIONABLE_FIELDS as g, CAPTION_FONT_RATIO as h, CAPTION_MAX_RATIO as i, CHART_HIGHLIGHT_MUTED_MIN_CONTRAST as j, CHART_HIGHLIGHT_MUTED_MIX as k, CHART_SERIES_MIN_DIFFERENCE as l, CHART_SERIES_MIN_LIGHTNESS_STEP as m, normalizeLanguageFamily as n, CITATION_MARKER_RAISE as o, CITATION_MARKER_SCALE as p, CODE_HIGHLIGHT_LANGUAGES as q, CODE_HIGHLIGHT_MAX_LENGTH as r, CODE_PANEL_BACKGROUND as s, CODE_PANEL_FOREGROUND as t, CODE_SYNTAX_MIN_CONTRAST as u, type Caption as v, type CaptionAlignment as w, type CaptionObject as x, type CaptionPosition as y, type CaptionSettings as z };