@openpresentation/opf 0.11.4 → 0.12.1

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

@@ -41,6 +41,149 @@ declare function tableGrid(value: unknown, path?: string): TableGrid;
 /** Row boundaries that preserve every vertical merge, used by pagination. */
 declare function tableRowBoundaries(value: unknown): number[];
 
+/** A positioned thing whose reading position is wanted. */
+interface ReadingBox {
+    box: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+}
+/**
+ * Visual reading order: rows from top to bottom, and within a row from the start to the end of the line.
+ *
+ * Items whose vertical centre falls inside an existing row's vertical extent join that row (so a full-height
+ * item shares one row with everything beside it and the row reads left to right). Rows are ordered by their
+ * top edge. Ties keep the input order, so the result is deterministic.
+ *
+ * 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
+ * check the composed order, so the two cannot drift apart.
+ */
+declare function visualReadingOrder<T extends ReadingBox>(items: readonly T[], direction?: 'ltr' | 'rtl'): T[];
+
+/**
+ * Text direction primitives shared by composition, the renderer and the PPTX exporter (RR-05).
+ * Pure: no fonts, DOM or catalogs. Deck direction comes from the presentation language's script
+ * (script-fonts.ts); a paragraph's own direction comes from its first strong character.
+ */
+/** Paragraph base direction. */
+type TextDirection = "ltr" | "rtl";
+/**
+ * The base direction of one paragraph in a deck, shared by the renderer and
+ * the PPTX exporter so preview and export agree. In a right-to-left deck a
+ * paragraph is right-to-left when its first strong character is
+ * right-to-left, or when it has no strong character (digits, punctuation or
+ * empty text); a paragraph whose first strong character is left-to-right
+ * (for example an English quote or code) stays left-to-right. In a
+ * left-to-right deck every paragraph is left-to-right.
+ *
+ * Strong characters follow UAX #9 rule P2: text inside directional isolates
+ * (LRI, RLI or FSI up to the matching PDI) is skipped. Letters count as
+ * strong; RTL letters are those of right-to-left scripts. The result does not
+ * depend on locale data, only on the JavaScript engine's Unicode tables.
+ */
+declare function paragraphDirection(text: string, deckDirection: TextDirection | string | undefined): TextDirection;
+/** Horizontal alignment as drawn: the physical left, centre or right of the text box. */
+type PhysicalAlignment = "left" | "center" | "right";
+/**
+ * Authored alignment is logical for right-to-left text (RR-05): `left` means the start edge and
+ * `right` the end edge, so in a right-to-left paragraph `left` is drawn at the right edge and
+ * `right` at the left edge. `center` is unchanged, and so is every left-to-right paragraph.
+ */
+declare function physicalAlignment(alignment: PhysicalAlignment | undefined, direction: TextDirection | undefined): PhysicalAlignment;
+/**
+ * The base direction at a UTF-16 offset of `text`, where paragraphs are the segments between hard
+ * line breaks (CR, LF or CRLF). Every wrapped line of a paragraph shares its direction, so a
+ * line made only of Latin words or digits never changes the paragraph it belongs to.
+ */
+declare function paragraphDirectionAt(text: string, deckDirection: TextDirection | string | undefined): (offset: number) => TextDirection;
+
+/**
+ * Numbered lists: the `numbering` field of `items` and `bullets` payloads.
+ *
+ * Pure helpers shared by composition (marker text and hanging indent), the validator, pagination and the
+ * exporters, so the preview and the native PowerPoint export number every entry identically. Nothing here
+ * measures text or reads a document beyond the items it is given.
+ */
+/** The five number styles OPF supports; each maps to a native PowerPoint auto-number scheme. */
+declare const NUMBERING_STYLES: readonly ["arabic", "roman-upper", "roman-lower", "alpha-upper", "alpha-lower"];
+type NumberingStyleName = typeof NUMBERING_STYLES[number];
+/** `period` draws `1.`, `paren` draws `1)` and `paren-both` draws `(1)`. */
+declare const NUMBERING_SUFFIXES: readonly ["period", "paren", "paren-both"];
+type NumberingSuffix = typeof NUMBERING_SUFFIXES[number];
+/** Object form of one level's numbering. Every field is optional. */
+interface Numbering {
+    /** Default `arabic`. */
+    style?: NumberingStyleName;
+    /** First number of the level, an integer from 1 to 32767 (the native `startAt` range). Default 1. */
+    start?: number;
+    /** Default `period`. */
+    suffix?: NumberingSuffix;
+}
+/**
+ * The `numbering` field: one style name, one {@link Numbering} object (both apply to every level) or an array with
+ * one entry per list level (index = level; the last entry repeats for deeper levels).
+ */
+type NumberingInput = NumberingStyleName | Numbering | readonly (NumberingStyleName | Numbering)[];
+/** One level's numbering with every default applied. */
+interface ResolvedNumbering {
+    style: NumberingStyleName;
+    start: number;
+    suffix: NumberingSuffix;
+}
+/** Largest value a native auto-number can start at (`a:buAutoNum@startAt`, ST_TextStartAt). */
+declare const MAX_NUMBERING_VALUE = 32767;
+/** Largest value drawn as a Roman numeral; larger values are drawn in arabic. */
+declare const MAX_ROMAN_VALUE = 3999;
+/** Deepest list level a native paragraph can carry (`a:pPr@lvl` is 0 to 8). */
+declare const MAX_NUMBERING_LEVELS = 9;
+/**
+ * Resolve a `numbering` value to one entry per authored level (a single entry when it applies to every level).
+ * Use {@link numberingAtLevel} to read the entry for a level. Throws on a value the schema rejects.
+ */
+declare function resolveNumbering(input: NumberingInput): ResolvedNumbering[];
+/** The numbering of one list level: the entry at that index, else the last entry. */
+declare function numberingAtLevel(levels: readonly ResolvedNumbering[], level: number): ResolvedNumbering;
+/** Whether `style` can draw `value` as that style (Roman numerals stop at 3999). */
+declare function numberingStyleDraws(style: NumberingStyleName, value: number): boolean;
+/**
+ * Format a list number as the preview draws it and PowerPoint's matching `a:buAutoNum` scheme draws it:
+ * `formatListNumber(4, 'roman-lower')` is `iv.`, `(3, 'alpha-upper', 'paren')` is `C)` and `(27, 'alpha-lower')` is `aa.`.
+ * Roman values above 3999 fall back to arabic (see {@link listNumbers} for the reported adaptation).
+ */
+declare function formatListNumber(value: number, style?: NumberingStyleName, suffix?: NumberingSuffix): string;
+/** The number of one list entry. */
+interface ListNumber {
+    /** Position of the entry in the list. */
+    index: number;
+    level: number;
+    /** The counted number (1 or more). */
+    value: number;
+    /** The style actually drawn: `arabic` when the authored style cannot draw `value`. */
+    style: NumberingStyleName;
+    suffix: NumberingSuffix;
+    /** The drawn marker, for example `iv.`. */
+    text: string;
+    /** Why the drawn style differs from the authored one: Roman numerals stop at 3999. */
+    adapted?: 'roman-range';
+}
+/**
+ * The numbers of a list, counted as PowerPoint counts them: consecutive entries of one level count up from that
+ * level's `start`; an entry of a shallower level restarts every deeper level; deeper entries between two entries of
+ * one level do not interrupt it. An object item's own `start` (an integer from 1 to 32767) restarts the count at that
+ * entry. Items are read for their `level` and `start` only.
+ */
+declare function listNumbers(items: readonly unknown[], numbering: NumberingInput): ListNumber[];
+/**
+ * The slice `items[from, to)` of a numbered list as the items of a continuation, with `start` set on every entry whose
+ * number would otherwise change, so a paginated list keeps the numbers of the whole list.
+ */
+declare function sliceNumberedItems<T>(items: readonly T[], numbering: NumberingInput, from: number, to?: number): T[];
+
 /**
  * Deterministic header/footer field formatting. Nothing here consults a clock,
  * the host locale or the host time zone: dates are calendar dates supplied by the
@@ -99,6 +242,326 @@ declare function textColorForFill(fill: string, preferred: string): string;
  * Explicit mark overrides belong to the caller; unresolved alpha is preserved.
  */
 declare function chartColorForFill(fill: string, preferred: string): string;
+/** Smallest CIE L* step kept between neighbouring series (a printed or greyscale chart tells them apart by lightness alone). */
+declare const CHART_SERIES_MIN_LIGHTNESS_STEP = 11;
+/** Smallest CIE76 colour difference kept between any two series that were at least that far apart before the surface adjustment. */
+declare const CHART_SERIES_MIN_DIFFERENCE = 12;
+/** Series colours for a chart drawn on `fill`: the palette in order, each colour adjusted for contrast
+ * (`chartColorForFill`) without letting the adjustment merge series.
+ *
+ * Lifting or darkening a colour for a dark or mid-tone surface moves every failing colour towards the same
+ * few lightness values, so two blues that differ on white can end up identical on a dark card. Colours that
+ * already have >= 3:1 contrast against `fill` are kept exactly. A colour the contrast adjustment would move is
+ * placed again on the lightness axis, keeping its hue and as much of its chroma as sRGB allows, subject to
+ * >= 3:1 contrast against `fill` and these separations from the other series (each capped at the separation
+ * that pair had in `palette`, so a pair the palette itself made close is not asked to be far apart):
+ *
+ * - a colour difference (CIE76) of at least {@link CHART_SERIES_MIN_DIFFERENCE} from every other series;
+ * - a lightness step of at least {@link CHART_SERIES_MIN_LIGHTNESS_STEP} (CIE L*) from the neighbouring
+ *   series, which is what keeps neighbours apart on a greyscale print;
+ * - the same lightness step from the remaining series, as a weaker aim.
+ *
+ * Series are placed in order against the kept colours and the colours placed before them. The placement
+ * with the lowest cost wins: its distance (in L*) from the contrast-adjusted colour plus a penalty for
+ * every point it falls short of those separations, so a colour that is already clear of the others is
+ * simply the adjusted colour, a near miss is not worth a large change, and a collision is resolved at the
+ * nearest lightness that clears it. The result is deterministic and in series order. An unresolved or
+ * translucent fill or colour is passed through, like `chartColorForFill`.
+ *
+ * It depends only on the surface and the palette, so every chart on a surface gets the same series colours,
+ * and preview and export (which both call this function) draw the same ones.
+ */
+declare function chartPaletteForFill(fill: string, palette: readonly string[]): string[];
+
+/**
+ * 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,
+ *   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
+ *   never shifts run indexes or source offsets.
+ * - A slide that carries markers gets a footnote area directly above the footer band: `layoutFootnotes`
+ *   lists `<n> <text>` for the slide's markers in number order, and `composeSlide` shrinks the content
+ *   area by exactly its height. Slides without markers are unchanged.
+ * - `caption` on an image, chart, table or video payload reserves a caption band inside the block's
+ *   region (`layoutCaption`): the media keeps the rest. Captions use the body family at the caption size
+ *   (0.6 of the body size, clamped to the readable floor) in the muted text colour.
+ *
+ * Geometry is shared: renderers and exporters only draw what these functions return.
+ */
+type CaptionPosition = 'below' | 'above';
+type CaptionAlignment = 'left' | 'center' | 'right';
+type RichText = string | readonly (string | RichTextRun)[];
+interface CaptionObject {
+    text: RichText;
+    position?: CaptionPosition;
+    align?: CaptionAlignment;
+}
+type Caption = RichText | CaptionObject;
+interface Reference {
+    id: string;
+    text: RichText;
+    url?: string;
+}
+interface CaptionSettings {
+    text: RichText;
+    position: CaptionPosition;
+    align: CaptionAlignment;
+}
+/**
+ * A marker is exported as a superscript run at the marked run's own size with DrawingML `baseline="30000"`, the way a user ticks
+ * Superscript. PowerPoint then draws the glyph at 2/3 of that nominal size and raises it by baseline x nominal size. Measured in
+ * PowerPoint 365 on Windows on 2026-10-01 with probe-superscript.pptx (Roboto and Aptos, 10 to 44 pt, digit ink height of a
+ * superscript run against a plain run of the same size): ratio 0.655 to 0.69, mean 0.667, independent of face and size; raise
+ * 0.30 of the nominal size at every size (baseline 30000). An explicit smaller sz on top is reduced again (0.7 x sz drew at about
+ * 0.47 of the run), which is why the exporter does not write one. The preview composes the same glyph size and raise.
+ *
+ * The drawn marker glyph is this fraction of the nominal size (the marked run's size), snapped to the 0.01 pt grid.
+ */
+declare const CITATION_MARKER_SCALE: number;
+/** The raise as a fraction of the NOMINAL size (the marked run's size): DrawingML `baseline="30000"`. */
+declare const CITATION_MARKER_RAISE = 0.3;
+/** Caption text size as a fraction of the body size, before the readable floor. */
+declare const CAPTION_FONT_RATIO = 0.6;
+/** A caption band takes at most this fraction of its block region. */
+declare const CAPTION_MAX_RATIO = 0.35;
+/** A footnote area takes at most this fraction of the span between heading top and footer band. */
+declare const FOOTNOTE_MAX_RATIO = 0.35;
+/** Payload fields whose blocks may carry a caption. */
+declare const CAPTIONABLE_FIELDS: readonly string[];
+/** Flatten a string or TextRun[] to its plain text. */
+declare function annotationText(value: unknown): string;
+/** Normalize a Caption value to its text, position and alignment. */
+declare function captionSettings(value: unknown): CaptionSettings | undefined;
+/** A run that cites or carries a footnote, with its dotted OPF path (`slides.0.blocks.1.text.2`). */
+interface AnnotatedRun {
+    path: string;
+    run: RichTextRun;
+    cite: string[];
+    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.
+ * `basePath` is the slide's dotted path (`slides.3`).
+ */
+declare function walkCitationRuns(slide: unknown, basePath: string, visit: (entry: AnnotatedRun) => void): void;
+/** One numbered note: a cited reference (by id) or an inline footnote. */
+interface CitationNote {
+    number: number;
+    kind: 'reference' | 'footnote';
+    /** Reference id for `kind: 'reference'`. */
+    id?: string;
+    /** Note text: the reference text (its id when the references list does not resolve it) or the footnote. */
+    text: RichText;
+    /** `references.N` for a reference, the marked run's path for a footnote. */
+    sourcePath: string;
+    url?: string;
+    /** False when a cited id has no references entry. */
+    resolved: boolean;
+}
+/** A marked run on a slide and the numbers its marker shows. */
+interface CitationMarker {
+    path: string;
+    numbers: number[];
+    text: string;
+}
+interface SlideCitations {
+    /** Marker text by run path, in reading order. */
+    markers: Map<string, string>;
+    /** Every marked run on the slide, in reading order. */
+    marked: CitationMarker[];
+    /** The notes the slide's markers use, in number order (each number once). */
+    notes: CitationNote[];
+}
+interface DeckCitations {
+    /** Every note of the deck in number order. */
+    notes: CitationNote[];
+    /** Cited references in number order (inline footnotes excluded). */
+    references: CitationNote[];
+    /** Per slide index. Slides without markers are absent. */
+    slides: Map<number, SlideCitations>;
+    /** Reference ids no run cites, in references order. */
+    unused: string[];
+}
+/** Marker text for a set of numbers: `1`, or `1,2` for several ids. */
+declare const citationMarkerText: (numbers: readonly number[]) => string;
+/**
+ * Number every marker of a deck in reading order. Slides are read from `presentation.slides`; a
+ * hidden slide still takes part so numbers do not change when it is shown.
+ */
+declare function collectCitations(presentation: unknown): DeckCitations;
+/**
+ * Citations of one slide with the deck's numbering: the markers of `presentation.slides[0..slideIndex-1]`
+ * are counted first, then the runs of `slide` itself (which may be a paginated page or a copy of the
+ * document's slide). Without a presentation the slide's own markers start at 1 and reference texts
+ * cannot be resolved (`resolved: false`).
+ */
+declare function slideCitations(slide: unknown, slideIndex: number, presentation?: unknown): SlideCitations | undefined;
+/** Fits a string or TextRun[] into a box at a requested size (composeSlide supplies its placed fitter). */
+type AnnotationFitter = (value: RichText, box: LayoutBox, requestedSize: number, minFontSize: number, path: string, alignment: CaptionAlignment) => TextFit | RichTextFit;
+interface AnnotationLayoutOptions {
+    scale: number;
+    minFontSize: number;
+    fit: AnnotationFitter;
+    textStyle: (path: string) => TextStyle;
+}
+/** A composed caption band inside a block region. */
+interface ComposedCaption {
+    /** Dotted path of the caption field (`slides.0.blocks.1.caption`). */
+    path: string;
+    value: Caption;
+    text: RichText;
+    position: CaptionPosition;
+    alignment: CaptionAlignment;
+    /** The caption band. */
+    box: LayoutBox;
+    /** The media box after the band is reserved; `ComposedItem.box` equals it. */
+    mediaBox: LayoutBox;
+    fit: TextFit | RichTextFit;
+    textStyle: TextStyle;
+    fontSize: number;
+    overflow: boolean;
+    diagnostics: LayoutDiagnostic[];
+}
+/** Reserve a caption band in `box` (the payload box) and return the band and the media box. */
+declare function layoutCaption(value: unknown, box: LayoutBox, path: string, options: AnnotationLayoutOptions): ComposedCaption | undefined;
+/** One listed note in a slide's footnote area. */
+interface ComposedFootnoteEntry {
+    number: number;
+    kind: 'reference' | 'footnote';
+    id?: string;
+    /** `references.N` or the marked run's path. */
+    sourcePath: string;
+    /** The listed value: `<n> <text>` as a string, or runs starting with the number. */
+    value: RichText;
+    text: RichText;
+    box: LayoutBox;
+    fit: TextFit | RichTextFit;
+    textStyle: TextStyle;
+    url?: string;
+    overflow: boolean;
+}
+/** The footnote area of a slide: a rule, then the slide's notes in number order. */
+interface ComposedFootnotes {
+    algorithm: 'footnote-area-v1';
+    /** Dotted slide path (`slides.3`). */
+    path: string;
+    box: LayoutBox;
+    /** Thin rule along the top of the area. */
+    rule: {
+        x: number;
+        y: number;
+        width: number;
+        thickness: number;
+    };
+    entries: ComposedFootnoteEntry[];
+    /** Marked runs of the slide with their marker text. */
+    markers: CitationMarker[];
+    fontSize: number;
+    overflow: boolean;
+    diagnostics: LayoutDiagnostic[];
+}
+interface FootnoteLayoutOptions extends AnnotationLayoutOptions {
+    /** Left edge and width of the content area. */
+    x: number;
+    width: number;
+    /** The area's bottom edge (the top of the footer band gap). */
+    bottom: number;
+    /** Largest height the area may take. */
+    maxHeight: number;
+    /** Slide path for the area (`slides.3`). */
+    path: string;
+}
+/** List a slide's notes in a footnote area whose bottom sits at `options.bottom`. */
+declare function layoutFootnotes(citations: SlideCitations, options: FootnoteLayoutOptions): ComposedFootnotes;
+interface ReferencesSlideOptions {
+    title?: string;
+}
+/**
+ * An ordinary list slide of the deck's cited references in marker order (`n. text`, linked to the
+ * reference url when there is one). Inline footnotes are not listed. A deck that cites nothing gets
+ * a slide with the title only.
+ */
+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';
+interface ChartOptionTarget {
+    kind: ChartOptionKind;
+    /** Stacked and 100% stacked columns, bars, lines and areas: their data labels have no outside-end position. */
+    stacked?: boolean;
+}
+type ChartLegendPosition = 'none' | 'top' | 'bottom' | 'left' | 'right';
+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`. */
+    option: string;
+    reason: 'unsupported-type' | 'unsupported-content' | 'unsupported-position';
+    message: string;
+}
+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). */
+    position: ChartLabelPosition | null;
+    separator: string;
+}
+interface ResolvedChartOptions {
+    /** True when the chart carries at least one option (after adaptation); false means every engine keeps today's output. */
+    active: boolean;
+    axisTitles: {
+        category?: string;
+        value?: 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;
+    diagnostics: ChartOptionDiagnostic[];
+}
+interface ChartOptionSupport {
+    axisTitles: {
+        category: boolean;
+        value: boolean;
+    };
+    legend: boolean;
+    dataLabels: {
+        supported: boolean;
+        content: readonly ChartLabelContent[];
+        /** Empty when labels have no position choice. */
+        positions: readonly ChartLabelPosition[];
+        /** The position `auto` resolves to; null with no positions. */
+        defaultPosition: ChartLabelPosition | null;
+        /** True for the constructs that label their marks by default (funnel, treemap): `dataLabels: false` removes those labels. */
+        defaultOn: boolean;
+    };
+}
+/** 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. */
+declare function chartOptionTarget(typeId: unknown): ChartOptionTarget | undefined;
+declare const DEFAULT_CHART_LABEL_SEPARATOR = ", ";
+/**
+ * Normalise a chart's `axisTitles`, `legend` and `dataLabels` against what its type can show. `target` is undefined for a chart type
+ * outside the catalog: nothing is adapted then (the engines fall back to their legacy output for such charts anyway).
+ */
+declare function resolveChartOptions(chart: unknown, target?: ChartOptionTarget): ResolvedChartOptions;
+/** A General-format number as a label: at most twelve significant digits, no exponent unless the value needs one. */
+declare function formatChartLabelNumber(value: number): string;
+/** A share as PowerPoint's `0%` label. */
+declare function formatChartLabelPercent(share: number): string;
+/** The label text: the selected parts in the fixed order category, value, percent, joined by the separator. */
+declare function chartLabelText(parts: {
+    category?: string;
+    value?: string;
+    percent?: string;
+}, content: readonly ChartLabelContent[], separator?: string): string;
 
 /** Portable layout geometry. No fonts, DOM, renderer, or network dependencies. */
 interface Composition {
@@ -118,7 +581,7 @@ interface LayoutBox {
     height: number;
 }
 interface LayoutDiagnostic {
-    code: "text-overflow" | "small-cell" | "unresolved-content" | "unsupported-image-treatment";
+    code: "text-overflow" | "small-cell" | "unresolved-content" | "unsupported-image-treatment" | "numbering-adapted";
     path: string;
     message: string;
 }
@@ -201,6 +664,8 @@ interface TextPlacementLine {
     height: number;
     width: number;
     outline: LayoutBox | null;
+    /** Physical alignment this line was placed with. Present only in a right-to-left deck, where `left` and `right` are logical start and end. */
+    alignment?: PhysicalAlignment;
 }
 interface TextPlacement {
     alignment: 'left' | 'center' | 'right';
@@ -216,10 +681,15 @@ interface TextFit {
     lineHeight: number;
     overflow: boolean;
     placement?: TextPlacement;
+    /**
+     * Base direction of the paragraph each line belongs to, in line order. Present only when the fit was
+     * made for a right-to-left deck; every wrapped line shares its paragraph's direction (RR-05).
+     */
+    directions?: TextDirection[];
 }
 /** Place complete measured lines, preserving alignment where it leaves room for ink.
  * Move following baselines together when outlines need more vertical separation. */
-declare function placeTextLines(lines: readonly TextLineInk[], box: LayoutBox, alignment?: TextPlacement['alignment'], rasterPadding?: number): TextPlacement;
+declare function placeTextLines(lines: readonly TextLineInk[], box: LayoutBox, alignment?: TextPlacement['alignment'], rasterPadding?: number, directions?: readonly TextDirection[]): TextPlacement;
 interface ComposedItem {
     path: string;
     field: string;
@@ -244,6 +714,11 @@ interface ComposedItem {
      * and the deck's icon logo resolves. Every entry marker in `text.listEntries` carries the same value.
      */
     bulletImage?: ListBulletImage;
+    /**
+     * Caption band of an image, chart, table or video payload that carries `caption` (RR-34). `box` is
+     * the media box after the band is reserved; `caption.box` is the band inside the same region.
+     */
+    caption?: ComposedCaption;
     /** Effective container settings, including inherited readability constraints. */
     composition: Composition;
     /**
@@ -330,7 +805,7 @@ interface ComposedLogo {
     path: string;
     source: unknown;
     variant: string;
-    anchor: 'left';
+    anchor: 'left' | 'right';
 }
 /** Picture bullet source for list markers: the deck's icon logo and the OPF path it was read from. */
 interface ListBulletImage {
@@ -409,11 +884,19 @@ interface SlideComposition {
     slideImage?: ComposedSlideImage;
     /** Deck logo on a cover or section slide; absent on content slides and when no logo resolves. */
     logo?: ComposedLogo;
+    /**
+     * Footnote area of a slide whose runs cite references or carry footnotes (RR-34): directly above the
+     * footer band, the content area is shrunk by exactly its height. Absent on slides without markers.
+     */
+    footnotes?: ComposedFootnotes;
+    /** `rtl` when the slide was composed for a right-to-left deck (mirrored arrangement); absent for left-to-right decks. */
+    direction?: 'rtl';
     explanation?: CompositionExplanation;
 }
 interface ComposeSlideOptions {
-    /** Context for inherited furniture, generated organization names, social profiles, logos and layout hints. */
+    /** Context for inherited furniture, generated organization names, social profiles, logos, layout hints, references and marker numbering. */
     presentation?: {
+        language?: unknown;
         design?: {
             header?: unknown;
             footer?: unknown;
@@ -427,6 +910,7 @@ interface ComposeSlideOptions {
         organization?: unknown;
         slides?: unknown;
         catalogs?: unknown;
+        references?: unknown;
     };
     /**
      * Whether the slide background is dark, by the host's own luminance test. Selects the light logo
@@ -450,6 +934,13 @@ interface ComposeSlideOptions {
      */
     date?: string;
     fonts?: 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
+     * header/footer zones swap sides, tables run right to left), lists put their markers at the right, and every text fit
+     * 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. */
     contentAlignment?: 'left' | 'center' | 'right';
     titleAlignment?: 'left' | 'center' | 'right';
@@ -585,7 +1076,18 @@ declare function layoutFurniture(input: unknown, options?: ComposeSlideOptions):
 /** Deterministic estimate, not a font shaping engine. Preserves explicit line breaks. */
 declare function measureText(text: string, fontSize: number): number;
 declare function wrapText(text: string, width: number, fontSize: number, measure?: MeasureTextWidth): string[];
-declare function fitText(text: string, box: LayoutBox, requestedSize?: number, minFontSize?: number, measure?: MeasureTextWidth): SourceTextFit;
+declare function fitText(text: string, box: LayoutBox, requestedSize?: number, minFontSize?: number, measure?: MeasureTextWidth, direction?: TextDirection): SourceTextFit;
+/**
+ * PowerPoint stores a run size (`sz`) in hundredths of a point, and composition pixels are CSS pixels (96 per
+ * inch, so a point is 4/3 px). Every composed font size is therefore a whole multiple of 0.01 pt, which is
+ * 1/75 px: the preview then measures, breaks and draws exactly the size the export writes (RR-16).
+ * The tolerance absorbs binary rounding noise (a size already on the grid must not drop a step).
+ */
+declare const FONT_SIZE_GRID_PER_PX = 75;
+/** Largest grid size not above `px`. Rounding down keeps a size that fit before snapping fitting. */
+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;
 interface QuoteContent {
     text: string;
     attribution?: string;
@@ -633,6 +1135,8 @@ interface QuoteLayoutOptions {
     overflow?: Composition['overflow'];
     path?: string;
     textMeasurement?: TextMeasurement;
+    /** Deck direction; in a right-to-left deck every part fit reports its paragraphs' directions (RR-05). */
+    direction?: TextDirection;
 }
 /**
  * Allocate and measure quote body/footer space for composition, rendering and export. Callers must
@@ -697,7 +1201,8 @@ interface MetricLayoutOptions extends QuoteLayoutOptions {
 /**
  * Measure every metric field before accepting geometry. Short single-line values and units can
  * share a baseline; longer values or units stack. No locale formatting, trend icons or rewritten
- * source text are invented. Consumers must reuse these accepted parts and source ranges.
+ * source text are invented here: the trend stays its word, and metricTrendMark derives the arrow
+ * 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;
 interface TimelineEvent {
@@ -721,6 +1226,7 @@ interface TimelineTextPart {
         end: number;
     }[];
     box: LayoutBox;
+    /** Logical alignment: `left` is the start edge, which a right-to-left line draws at the right (see `fit.directions`). */
     alignment: 'left' | 'center';
     requestedFontSize: number;
     minFontSize: number;
@@ -838,10 +1344,18 @@ interface RichTextRun {
     link?: string;
     superscript?: boolean;
     subscript?: boolean;
+    /** 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). */
+    footnote?: string | (string | RichTextRun)[];
 }
 interface RichTextFragment {
-    /** Tabs are source-preserving layout controls with a fixed advance, not glyph text. */
-    kind?: 'tab';
+    /**
+     * Tabs are source-preserving layout controls with a fixed advance, not glyph text. A marker is the
+     * superscript citation/footnote number drawn after a run that cites or carries a footnote (RR-34): it
+     * has no source range (`start === end === run.text.length`), so run indexes and offsets never shift.
+     */
+    kind?: 'tab' | 'marker';
     text: string;
     runIndex: number;
     start: number;
@@ -850,6 +1364,8 @@ interface RichTextFragment {
     width: number;
     fontSize: number;
     baselineShift: number;
+    /** A marker only: the size the exporter writes (the marked run's size); `fontSize` is the glyph PowerPoint draws for it (2/3). */
+    nominalSize?: number;
     style: TextStyle;
     run: RichTextRun;
 }
@@ -869,6 +1385,13 @@ interface RichTextOptions {
     textMeasurement?: TextMeasurement;
     /** Use one measured line advance for every line, as native table cells do. */
     uniformLineHeight?: boolean;
+    /** Deck direction. In a right-to-left deck every line reports its paragraph's direction in `directions`. */
+    direction?: TextDirection;
+    /**
+     * Marker text (`1`, `1,2`) for a run by its dotted path (`${style.path}.${runIndex}`), or undefined.
+     * composeSlide supplies the deck numbering from `slideCitations`; a marker fragment is emitted after the run.
+     */
+    citationMarker?: (runPath: string) => string | undefined;
 }
 /** Fit mixed styles without flattening font metrics. Run fontSize is in points. */
 declare function fitRichText(input: readonly (string | RichTextRun)[], box: LayoutBox, requestedSize?: number, minFontSize?: number, options?: RichTextOptions): RichTextFit;
@@ -877,6 +1400,7 @@ type ListValue = ListText | {
     text: ListText;
     description?: ListText;
     level?: number;
+    start?: number;
 };
 interface ListEntryLayout {
     index: number;
@@ -889,6 +1413,13 @@ interface ListEntryLayout {
     description?: RichTextFit;
     textBox: LayoutBox;
     descriptionBox?: LayoutBox;
+    /**
+     * `x` is the marker's left edge, or its right edge when `anchor` is `end` (a right-to-left entry, whose marker sits at the right and
+     * whose text box is the column to its left).
+     * The entry marker: the bullet glyph, or for a numbered list (`numbering`) the formatted number such as `iv.`.
+     * A numbered marker also carries `number` and its measured `width`; its `style` is the list style with the weight and
+     * slant of the entry's first run, as PowerPoint draws an auto-number in the first run's character formatting.
+     */
     marker: {
         text: string;
         x: number;
@@ -896,12 +1427,18 @@ interface ListEntryLayout {
         fontSize: number;
         style: TextStyle;
         indent: number;
+        number?: ListNumber;
+        width?: number;
+        anchor?: 'end';
     };
+    /** Paragraph direction of this entry. Present only when the list was fitted for a right-to-left deck. */
+    direction?: TextDirection;
     /** Picture bullet replacing the marker glyph; drawn in `bulletBox`. Marker geometry is unchanged. */
     bulletImage?: ListBulletImage;
     /**
      * Where the picture bullet draws: a square of side `marker.fontSize * PICTURE_BULLET_SCALE` whose
-     * bottom sits on the marker baseline (`marker.y`) and whose left edge is `marker.x`. Present with `bulletImage`.
+     * bottom sits on the marker baseline (`marker.y`) and whose left edge is `marker.x` (right edge when `marker.anchor` is `end`).
+     * Present with `bulletImage`.
      */
     bulletBox?: LayoutBox;
 }
@@ -918,6 +1455,11 @@ interface ListFit extends TextFit {
     height: number;
 }
 interface ListFitOptions extends RichTextOptions {
+    /**
+     * Number the entries instead of bulleting them (the payload's `numbering` field). The hanging indent becomes the larger of
+     * 1.1 em and the widest marker plus 0.3 em, so wide markers never touch their text; unnumbered lists are unchanged.
+     */
+    numbering?: NumberingInput;
     /** Picture bullet for every entry (effective `design.listBullet: "image"` with a resolved icon logo). */
     bulletImage?: ListBulletImage;
 }
@@ -929,6 +1471,11 @@ interface TableLayoutOptions {
     fontFamily?: string;
     textMeasurement?: TextMeasurement;
     path?: string;
+    /**
+     * 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).
+     */
+    direction?: TextDirection;
 }
 interface TableCellLayout {
     value: unknown;
@@ -946,6 +1493,8 @@ interface TableCellLayout {
     textBox: LayoutBox;
     textStyle: TextStyle;
     fit: TextFit | RichTextFit;
+    /** Paragraph direction of the cell text; present only in a right-to-left deck. */
+    direction?: TextDirection;
 }
 interface TableRowLayout {
     box: LayoutBox;
@@ -971,4 +1520,4 @@ declare function resolveCanvasDimensions(input: unknown): {
     height: number;
 };
 
-export { type QuoteContent as $, type FurniturePartBase as A, type FurnitureSocialLink as B, type ComposeSlideOptions as C, DEFAULT_FONT_SCHEME as D, type FurnitureTextExtras as E, type FontSchemeDiagnostic as F, type FurnitureTextPart as G, type LayoutBox as H, type ListBulletImage as I, type ListEntryLayout as J, type ListFit as K, type LayoutDiagnostic as L, type ListFitOptions as M, type ListText as N, type ListValue as O, type LogoSlot as P, MAX_COMPOSITION_DEPTH as Q, type MeasureTextWidth as R, type MetricContent as S, type TextMeasurement as T, type MetricLayout as U, type MetricLayoutDiagnostic as V, type MetricLayoutOptions as W, type MetricTextPart as X, type MetricTextSource as Y, OPFCompositionError as Z, PICTURE_BULLET_SCALE as _, type CodeContent as a, type TableGridCell as a$, type QuoteLayout as a0, type QuoteLayoutDiagnostic as a1, type QuoteLayoutOptions as a2, type QuoteTextPart as a3, type QuoteTextSource as a4, type ResolveColorRefOptions as a5, type ResolveColorRefRoles as a6, type ResolveLogoOptions as a7, type ResolvedFontScheme as a8, type ResolvedLogo as a9, formatFurnitureDate as aA, formatSlideNumber as aB, layoutCode as aC, layoutFurniture as aD, layoutMetric as aE, layoutQuote as aF, layoutTimeline as aG, measureText as aH, measureTextOutline as aI, normalizeHexColor as aJ, placeTextLines as aK, resolveCanvasDimensions as aL, resolveColorRef as aM, resolveFontFamilies as aN, resolveFontSchemeReference as aO, resolveLogo as aP, resolveSocialProfile as aQ, resolveTextStyle as aR, textColorForFill as aS, textWidthMeasurer as aT, wrapText as aU, type FontFaceSelection as aV, type SourceTextFit as aW, type TableBorder as aX, type TableCellLayout as aY, type TableCellStyle as aZ, type TableGrid as a_, type RichTextFit as aa, type RichTextFragment as ab, type RichTextLine as ac, type RichTextOptions as ad, type RichTextRun as ae, type SlideComposition as af, type SlideImageShape as ag, type SocialPlatformRecord as ah, type SocialProfile as ai, type TextFit as aj, type TextLineInk as ak, type TextPlacement as al, type TextPlacementLine as am, type TextStyle as an, type TimelineContent as ao, type TimelineEvent as ap, type TimelineLayout as aq, type TimelineLayoutDiagnostic as ar, type TimelineLayoutOptions as as, type TimelineTextPart as at, chartColorForFill as au, colorContrast as av, composeSlide as aw, fitList as ax, fitRichText as ay, fitText as az, type CodeLayout as b, type TableGridIssue as b0, type TableLayout as b1, type TableLayoutOptions as b2, type TableRowLayout as b3, type TextLineSegment as b4, type TextLineSource as b5, layoutTable as b6, slideImageShape as b7, tableGrid as b8, tableRowBoundaries as b9, type CodeLayoutDiagnostic as c, type CodeLayoutOptions as d, type CodeLineSegment as e, type CodeLineSource as f, type CodeTextFit as g, type CodeTextPart as h, type ComposedFlow as i, type ComposedGroup as j, type ComposedItem as k, type ComposedLogo as l, type ComposedSlideImage as m, type Composition as n, type CompositionCandidate as o, type CompositionDecision as p, type CompositionExplanation as q, type CompositionPenalties as r, type CompositionTrack as s, DEFAULT_FURNITURE_DATE_FORMAT as t, DEFAULT_SLIDE_NUMBER_FORMAT as u, type FontFamilies as v, type FurnitureField as w, type FurnitureImagePart as x, type FurnitureLayout as y, type FurniturePart as z };
+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 };