pptx-react-viewer 2.16.10 → 2.18.0

package/dist/internals.d.ts

@@ -1145,6 +1145,22 @@ interface ShapeStyle {
   fontRefIdx?: string;
   /** Raw XML colour child of `<a:fontRef>`. */
   fontRefColorXml?: XmlObject;
+  /**
+   * The fill `<a:fillRef>` resolved to, recorded ONLY when the shape's own
+   * `spPr` authored no fill at all, so the reference is what paints it.
+   *
+   * Its absence therefore means "the fill is the shape's own", and its
+   * presence plus an unchanged flat fill means "still purely inherited": see
+   * `authored-shape-style.ts`, the shape-scope twin of `TextStyle`'s
+   * `inheritedRunStyle`.
+   */
+  inheritedFillStyle?: ShapeStyle;
+  /**
+   * The outline `<a:lnRef>` resolved to, recorded before `spPr/a:ln` was
+   * layered on top. A property that still equals this baseline was never
+   * authored on the shape and must not be written back as if it were.
+   */
+  inheritedLineStyle?: ShapeStyle;
 }
 //#endregion
 //#region src/core/types/text.d.ts
@@ -1185,6 +1201,60 @@ interface ShapeStyle {
 interface TextStyle {
   /** Original `a:rPr` XML retained by projections that share the shape-text model. */
   runPropertiesXml?: XmlObject;
+  /**
+   * The properties this run's OWN `a:rPr` authored, and nothing else.
+   *
+   * A run style is assembled as
+   * `{...inheritedRunStyle, ...authoredRunStyle}`, so the flat style is a
+   * fully RESOLVED view: it cannot say whether `fontSize: 60` came from the
+   * run, from the shape's `a:lstStyle`, from the layout placeholder, from the
+   * master `p:txStyles` or from the theme. Omission is meaningful in OOXML
+   * (§21.1.2.3), so a writer that re-emits the resolved view converts every
+   * inherited value into an authored one and the deck stops being
+   * theme-driven after one save.
+   *
+   * This is the run-scope twin of {@link TextSegment.paragraphProperties},
+   * which is parsed strictly from the paragraph's own `a:pPr` for the same
+   * reason. Present only for runs that came from a parsed deck; absent for
+   * SDK-built text, where the flat style IS the only description and must be
+   * written out in full.
+   */
+  authoredRunStyle?: TextStyle;
+  /**
+   * The resolved inheritance baseline {@link authoredRunStyle} was layered
+   * on top of (shape `a:lstStyle` -> placeholder -> layout -> master
+   * `p:txStyles` -> theme -> `p:defaultTextStyle`).
+   *
+   * Kept alongside the authored half because the two answer different
+   * questions. The authored half says "the source pinned this"; the baseline
+   * says "this value is what inheritance already produces", which is how an
+   * EDIT is told apart from an inherited value: an editor mutates the flat
+   * style without knowing about either field, so a property that now differs
+   * from the baseline was either authored or edited and must be written,
+   * while one that still matches can be left to inherit.
+   *
+   * Holds a reference to the per-paragraph baseline object rather than a
+   * copy, so carrying it costs one pointer per run.
+   */
+  inheritedRunStyle?: TextStyle;
+  /**
+   * Snapshot of the ELEMENT-scope paragraph geometry (alignment, margins,
+   * indent, line and paragraph spacing, tab stops, rtl, line-break flags) as
+   * the load pipeline resolved it.
+   *
+   * Present only on an `element.textStyle` that came from a parsed deck, and
+   * populated only with the geometry keys. It exists so the save path can
+   * answer one question it otherwise cannot: has the user CHANGED the body's
+   * alignment or indent, or is the value simply what the shape's
+   * `a:lstStyle`, its layout placeholder and the master already produce?
+   * Element-level text panels (`textAdvancedPatch`, `alignPatch` and friends
+   * in `pptx-viewer-shared`) write `element.textStyle` and never touch
+   * `segment.paragraphProperties`, so a diff against this snapshot is the
+   * only way to tell an edit from an inheritance artefact.
+   *
+   * @see element-paragraph-geometry.ts
+   */
+  resolvedParagraphGeometry?: TextStyle;
   fontFamily?: string;
   fontSize?: number;
   /** When true, renderer should shrink text to fit the shape bounds. */
@@ -1640,7 +1710,28 @@ interface BulletInfo {
   autoNumType?: string;
   /** Auto-numbering start value. */
   autoNumStartAt?: number;
-  /** Zero-based paragraph index within the text body (for auto-numbering). */
+  /**
+   * Auto-numbering ORDINAL OFFSET: the zero-based distance of this paragraph
+   * within its own numbered list, such that
+   * `autoNumStartAt + paragraphIndex` is the ordinal to render. Despite the
+   * name it is NOT the paragraph's position in the text body; the two agree
+   * only for a list that starts at the first paragraph and is never
+   * interrupted.
+   *
+   * It has to be the offset rather than the raw position because every
+   * consumer that re-derives a marker from `BulletInfo` alone (the renderer's
+   * `resolveParagraphBullet`, the Markdown converter's `resolveListMarker`)
+   * computes `autoNumStartAt + paragraphIndex`. The load path resolves the
+   * real sequence itself, restarting the count after any paragraph that
+   * interrupts the list, and publishes the offset here so those consumers
+   * land on the same number. With the raw position they did not, and BOTH
+   * markers were painted ("3.1. Item"), because the paragraph builder drops
+   * the parsed marker segment only when the two strings agree.
+   *
+   * Runtime-only: derived at parse time and never serialized. OOXML has no
+   * counterpart (`a:buAutoNum` carries only `@type` and `@startAt`), so the
+   * writer neither reads nor emits it.
+   */
   paragraphIndex?: number;
   /** Bullet font family from `a:buFont`. */
   fontFamily?: string;
@@ -1828,6 +1919,15 @@ interface PptxElementBase {
   shapeId?: string;
   /** Element name from `cNvPr/@name`. Used for morph transition matching via the `!!` naming convention. */
   name?: string;
+  /**
+   * `p:nvSpPr/p:nvPr/p:ph/@type` (lower-cased) when the shape is a placeholder:
+   * `title`, `ctrtitle`, `body`, `subtitle`, `ftr`, `dt`, `sldnum`, ...
+   *
+   * Captured on load so consumers can tell a footer placeholder from a text box
+   * without re-walking `rawXml`. Absent on non-placeholder shapes and on
+   * SDK-created elements.
+   */
+  placeholderType?: string;
   x: number;
   y: number;
   width: number;
@@ -1888,6 +1988,19 @@ interface PptxTextProperties {
   }>;
   /** Placeholder prompt text inherited from layout/master (e.g. "Click to add title"). Shown as a greyed-out hint when the shape has no user-entered text. */
   promptText?: string;
+  /**
+   * The string {@link text} was INHERITED from, when this is a header / footer /
+   * date / slide-number placeholder whose own body the file leaves empty.
+   *
+   * PowerPoint keeps the footer string on the slide master and writes each
+   * slide's copy of the `ftr` placeholder empty, so the empty body means
+   * "render the master's footer here". Rendering needs the resolved string, but
+   * SAVING it into the slide would pin that slide to today's master text and
+   * silently detach it from the Header & Footer dialog. The save writer
+   * therefore leaves the authored empty body alone while `text` still equals
+   * this value, and writes a genuine per-slide override once it does not.
+   */
+  inheritedPlaceholderText?: string;
   /** Linked text box chain ID from `a:bodyPr > a:linkedTxbx/@id` or `a:txbx > a:linkedTxbx/@id`. Text overflows from one linked frame to the next. */
   linkedTxbxId?: number;
   /** Sequence number within a linked text box chain (0-based). */
@@ -2298,6 +2411,12 @@ interface PptxChartLineStyle {
 }
 /** Marker symbol types for line/scatter chart data points. */
 type PptxChartMarkerSymbol = 'circle' | 'dash' | 'diamond' | 'dot' | 'none' | 'picture' | 'plus' | 'square' | 'star' | 'triangle' | 'x' | 'auto';
+/**
+ * `ST_ScatterStyle` (ECMA-376 §21.2.3.40): how a scatter chart joins its points.
+ * `line`/`lineMarker` connect them with straight segments, `smooth`/
+ * `smoothMarker` with a bezier, `marker`/`none` not at all.
+ */
+type PptxChartScatterStyle = 'none' | 'line' | 'lineMarker' | 'marker' | 'smooth' | 'smoothMarker';
 /** Shape properties extracted from c:spPr for chart formatting. */
 interface PptxChartShapeProps {
   fillColor?: string;
@@ -2499,6 +2618,42 @@ interface PptxChartTreemapOptions {
 interface PptxChartSeries {
   name: string;
   values: number[];
+  /**
+   * Per-series x values from `c:ser/c:xVal` (scatter and bubble series only).
+   *
+   * Every `CT_ScatterSer` / `CT_BubbleSer` carries its OWN `c:xVal`, so two
+   * series in one scatter chart routinely plot against different x ranges (the
+   * normal case for measurement data). Reading the x values off the first
+   * series and reusing them everywhere plotted every series against series 1's
+   * x axis. Absent for category-axis chart kinds, where
+   * {@link PptxChartData.categories} is the x axis.
+   */
+  xValues?: number[];
+  /**
+   * Per-series bubble sizes from `c:ser/c:bubbleSize` (bubble series only),
+   * aligned index-for-index with {@link values}.
+   *
+   * `CT_BubbleSer` carries x, y AND size, so a one-series bubble chart is fully
+   * specified. Absent when the source omits `c:bubbleSize`.
+   */
+  bubbleSizes?: number[];
+  /**
+   * Series-level data-label content flags from `c:ser/c:dLbls`.
+   *
+   * PowerPoint writes the flags a user picks in "Format Data Labels" onto the
+   * SERIES, and leaves the chart-type-level `c:dLbls` all-zero, so reading only
+   * the chart-level group reports "show nothing" for a chart that visibly shows
+   * percentages. These override {@link PptxChartStyle.dataLabels}.
+   */
+  dataLabelOptions?: PptxChartDataLabelOptions;
+  /**
+   * Whether the series line is explicitly suppressed
+   * (`c:ser/c:spPr/a:ln/a:noFill`). Line-drawn kinds (line, scatter, radar)
+   * use this to decide whether to draw a connecting line at all; a marker-only
+   * scatter is authored as `scatterStyle="lineMarker"` PLUS this flag, never by
+   * changing the scatter style.
+   */
+  lineNoFill?: boolean;
   /**
    * Blank-value mask aligned index-for-index with {@link values}: `true` marks
    * a category whose numeric cache point (`c:numCache/c:pt`) was absent or
@@ -2842,6 +2997,17 @@ interface PptxChartData {
    * default), so only horizontal bar charts need to carry the field.
    */
   barDirection?: PptxChartBarDirection;
+  /**
+   * Scatter presentation mode (`c:scatterChart/c:scatterStyle/@val`).
+   *
+   * `lineMarker` (PowerPoint's own default for every scatter it writes) and
+   * `smoothMarker` draw a connecting line; `marker` and `none` do not. Whether
+   * the MARKERS appear is decided separately by `c:marker/c:symbol`, and
+   * whether the LINE appears is further gated by
+   * {@link PptxChartSeries.lineNoFill} - PowerPoint expresses "markers only" as
+   * `lineMarker` plus an `a:ln/a:noFill`, not as `marker`.
+   */
+  scatterStyle?: PptxChartScatterStyle;
   /**
    * Bar/column gap between category clusters as a percentage of bar width
    * (`c:gapWidth/@val`, 0 through 500). Absent uses the renderer default.
@@ -2995,6 +3161,53 @@ interface PptxChartData {
  * // => { brightness: 20, contrast: -10, grayscale: true } satisfies PptxImageEffects
  * ```
  */
+/**
+ * One `a14:foregroundMark` / `a14:backgroundMark` polyline hint recorded while
+ * the user painted over the picture in PowerPoint's "Remove Background" mode.
+ * Coordinates are 0..1 fractions of the image.
+ */
+interface PptxBackgroundRemovalMark {
+  x1: number;
+  y1: number;
+  x2: number;
+  y2: number;
+}
+/**
+ * PowerPoint "Remove Background" state (`a14:backgroundRemoval`).
+ *
+ * The four edges are the RETAINED rectangle as 0..1 fractions of the image
+ * (OOXML stores them as per-100000 relative units), and the mark lists are the
+ * segmentation hints the user painted.
+ *
+ * **This is edit-time metadata, not a render instruction.** PowerPoint bakes the
+ * removal into the bitmap referenced by the main `a:blip/@r:embed` and keeps the
+ * pristine original in `a14:imgLayer/@r:embed`. Verified against PowerPoint COM:
+ * a slide exported with and without this element is byte-identical. A renderer
+ * that clips to the retained rectangle would clip an image whose background has
+ * already been removed.
+ *
+ * @example
+ * ```ts
+ * const removal: PptxBackgroundRemoval = { top: 0.12, bottom: 0.88, left: 0.07, right: 0.93 };
+ * // => retains the middle of the image; the marks list stays empty
+ * ```
+ */
+interface PptxBackgroundRemoval {
+  /** Top edge of the retained rectangle (0..1 fraction of the image height). */
+  top: number;
+  /** Bottom edge of the retained rectangle (0..1 fraction of the image height). */
+  bottom: number;
+  /** Left edge of the retained rectangle (0..1 fraction of the image width). */
+  left: number;
+  /** Right edge of the retained rectangle (0..1 fraction of the image width). */
+  right: number;
+  /** Strokes marking regions the user forced to be foreground. */
+  foregroundMarks?: PptxBackgroundRemovalMark[];
+  /** Strokes marking regions the user forced to be background. */
+  backgroundMarks?: PptxBackgroundRemovalMark[];
+  /** Original effect XML, retained for lossless re-emission. */
+  rawXml?: XmlObject;
+}
 interface PptxImageEffects {
   /** Brightness adjustment (-100 to 100). */
   brightness?: number;
@@ -3018,8 +3231,38 @@ interface PptxImageEffects {
   };
   /** Artistic effect name (blur, pencilGrayscale, paintStrokes, etc.). */
   artisticEffect?: string;
-  /** Artistic effect radius/amount. */
+  /** Artistic effect radius/amount, normalised to 0..100. */
   artisticRadius?: number;
+  /**
+   * Every numeric attribute of the source `a14:artistic*` element, raw and
+   * un-normalised (`trans`, `pencilSize`, `crackSpacing`, …). The attribute set
+   * differs per effect, so this is the lossless companion to the single
+   * {@link PptxImageEffects.artisticRadius} number.
+   */
+  artisticParams?: Record<string, number>;
+  /**
+   * Name of the artistic effect ALREADY baked into the image data, which a
+   * renderer must not apply a second time. Set from the `a14` blip extension,
+   * which PowerPoint writes alongside a pre-rendered bitmap (see
+   * {@link PptxBackgroundRemoval}), and normally equal to
+   * {@link PptxImageEffects.artisticEffect}.
+   *
+   * It records the NAME rather than a boolean so that picking a different
+   * effect in this library's inspector (which patches `artisticEffect` alone)
+   * still renders: the two names then differ.
+   */
+  artisticPrerenderedEffect?: string;
+  /**
+   * PowerPoint "Remove Background" state (`a14:backgroundRemoval`). Edit-time
+   * metadata: the removal is already baked into the image data.
+   */
+  backgroundRemoval?: PptxBackgroundRemoval;
+  /**
+   * `a14:imgLayer/@r:embed` — relationship id of the PRISTINE original image
+   * the baked effects were derived from (PowerPoint stores it as an HD Photo
+   * `.wdp` part, which browsers cannot decode).
+   */
+  originalImageRelId?: string;
   /** Alpha modulation fixed: non-negative percentage (100 means unchanged opacity). */
   alphaModFix?: number;
   /** Original alpha modulation fixed node, including foreign attributes. */
@@ -3935,6 +4178,11 @@ interface PptxTableCellStyle {
   italic?: boolean;
   underline?: boolean;
   color?: string;
+  /**
+   * Font family from the first run's `a:rPr/a:latin@typeface` (falling back to
+   * `a:ea` / `a:cs`). Per-run families live on {@link PptxTableCellTextRun}.
+   */
+  fontFamily?: string;
   /**
    * Raw XML colour-choice node preserved from `a:tc/a:txBody/.../a:rPr/a:solidFill`
    * for round-trip serialisation. Currently unused by the cell-level writer
@@ -4090,6 +4338,45 @@ interface PptxTableCell3D {
   /** Light rig direction (`a:lightRig@dir`, e.g. `tl`, `t`, `tr`). */
   lightRigDirection?: string;
 }
+/**
+ * One styled text run inside a table cell's `a:txBody`.
+ *
+ * `PptxTableCell.text` is a flat string and `PptxTableCell.style` describes
+ * only the FIRST run, so a cell mixing formats ("Revenue **grew 42%** last
+ * year") cannot be represented by those two alone. {@link PptxTableCell.runs}
+ * carries the full sequence, with paragraph and line breaks as marker entries
+ * so a renderer can walk it linearly.
+ *
+ * Structurally identical to `pptx-viewer-shared`'s `CellTextRun`, which every
+ * binding's table renderer already consumes.
+ *
+ * @example
+ * ```ts
+ * const runs: PptxTableCellTextRun[] = [
+ *   { text: "Revenue " },
+ *   { text: "grew 42%", bold: true, color: "#C00000" },
+ * ];
+ * // => satisfies PptxTableCellTextRun[]
+ * ```
+ */
+interface PptxTableCellTextRun {
+  /** Run text. Empty for the break markers below. */
+  text: string;
+  /** This entry starts a new paragraph (`a:p` boundary) rather than carrying text. */
+  isParagraphBreak?: boolean;
+  /** This entry is a soft line break (`a:br`) rather than carrying text. */
+  isLineBreak?: boolean;
+  bold?: boolean;
+  italic?: boolean;
+  underline?: boolean;
+  strikethrough?: boolean;
+  /** Resolved run colour as a CSS colour string. */
+  color?: string;
+  /** Run font size in points (`a:rPr@sz` / 100). */
+  fontSize?: number;
+  /** Run font family from `a:rPr/a:latin@typeface` (or `a:ea` / `a:cs`). */
+  fontFamily?: string;
+}
 /**
  * A single table cell with text content, optional style, and merge info.
  *
@@ -4106,6 +4393,15 @@ interface PptxTableCell3D {
 interface PptxTableCell {
   text: string;
   style?: PptxTableCellStyle;
+  /**
+   * Per-run formatting for the cell's text, when it has any beyond what
+   * {@link style} can express. Present only for cells whose `a:txBody`
+   * actually carries runs; renderers fall back to {@link text} when absent.
+   *
+   * Editing a cell's text invalidates these (the editor produces a plain
+   * string), so an edit path must clear them alongside setting `text`.
+   */
+  textRuns?: PptxTableCellTextRun[];
   /** Column span (defaults to 1). */
   gridSpan?: number;
   /** Row span (defaults to 1). */
@@ -4878,13 +5174,42 @@ interface UnknownPptxElement extends PptxElementBase {
 /**
  * A single element on a PPTX slide.
  *
- * This is a **discriminated union** — narrow on `element.type` to access
+ * This is a **discriminated union**: narrow on `element.type` to access
  * variant-specific properties like `imageData` (image/picture), `pathData`
  * (shape), or `textSegments` (text/shape).
  */
 type PptxElement = TextPptxElement | ShapePptxElement | ConnectorPptxElement | ImagePptxElement | PicturePptxElement | TablePptxElement | ChartPptxElement | SmartArtPptxElement | OlePptxElement | MediaPptxElement | GroupPptxElement | InkPptxElement | ContentPartPptxElement | ZoomPptxElement | Model3DPptxElement | UnknownPptxElement;
 //#endregion
 //#region src/core/types/masters.d.ts
+/**
+ * A placeholder slot declared on a master or layout.
+ *
+ * The geometry fields are in CSS pixels (EMU / {@link EMU_PER_PX}) and are only
+ * present when the shape carried an explicit `a:xfrm`. Placeholders that
+ * inherit their frame from the master leave them undefined, so consumers that
+ * draw placeholder outlines (the layout gallery) must skip those entries
+ * rather than assume a zero-sized box at the origin.
+ *
+ * @example
+ * ```ts
+ * const frame: PptxPlaceholderFrame = { type: "body", idx: "1", x: 63, y: 130 };
+ * // => satisfies PptxPlaceholderFrame
+ * ```
+ */
+interface PptxPlaceholderFrame {
+  /** `p:ph/@type`, lower-cased by the parser; defaults to `body` when omitted. */
+  type: string;
+  /** `p:ph/@idx`, when present. */
+  idx?: string;
+  /** Left offset in CSS pixels, when the shape declares `a:off`. */
+  x?: number;
+  /** Top offset in CSS pixels, when the shape declares `a:off`. */
+  y?: number;
+  /** Width in CSS pixels, when the shape declares `a:ext`. */
+  width?: number;
+  /** Height in CSS pixels, when the shape declares `a:ext`. */
+  height?: number;
+}
 /**
  * Parsed notes master from `ppt/notesMasters/notesMaster1.xml`.
  *
@@ -4906,10 +5231,7 @@ interface PptxNotesMaster {
   /** Background image data URL. */
   backgroundImage?: string;
   /** Placeholder shapes found on the notes master. */
-  placeholders?: Array<{
-    type: string;
-    idx?: string;
-  }>;
+  placeholders?: PptxPlaceholderFrame[];
   /** Editable elements on the notes master (header, footer, date, page number, slide image, notes body). */
   elements?: PptxElement[];
   /** Header/footer flags from `<p:hf>` on the notes master (P-H3). */
@@ -4937,10 +5259,7 @@ interface PptxHandoutMaster {
   /** Background image data URL. */
   backgroundImage?: string;
   /** Placeholder shapes found on the handout master. */
-  placeholders?: Array<{
-    type: string;
-    idx?: string;
-  }>;
+  placeholders?: PptxPlaceholderFrame[];
   /** Editable elements on the handout master (header, footer, date, page number, slide placeholders). */
   elements?: PptxElement[];
   /** Number of slides per page for handout print layout (1, 2, 3, 4, 6, or 9). */
@@ -4988,10 +5307,7 @@ interface PptxSlideMaster {
   /** Layout paths associated with this master. */
   layoutPaths?: string[];
   /** Placeholder shapes on the master. */
-  placeholders?: Array<{
-    type: string;
-    idx?: string;
-  }>;
+  placeholders?: PptxPlaceholderFrame[];
   /** Parsed element shapes on the master slide (for master view rendering). */
   elements?: PptxElement[];
   /** Parsed slide layout objects associated with this master. */
@@ -5063,10 +5379,7 @@ interface PptxSlideLayout {
   /** Parsed element shapes on the layout. */
   elements?: PptxElement[];
   /** Placeholder shapes on the layout. */
-  placeholders?: Array<{
-    type: string;
-    idx?: string;
-  }>;
+  placeholders?: PptxPlaceholderFrame[];
   /** Matching name attribute for layout identification (`@matchingName`). */
   matchingName?: string;
   /** Whether the layout is marked as preserved (prevent deletion, `@preserve`). */
@@ -5080,6 +5393,42 @@ interface PptxSlideLayout {
   /** Header/footer flags from `<p:hf>` on this layout (P-H3). */
   headerFooter?: PptxHeaderFooterFlags;
 }
+/**
+ * Rendered content of a single layout, used to draw gallery thumbnails.
+ *
+ * Produced on demand rather than during load: materialising every layout's
+ * artwork (and decoding its images) up front costs a noticeable amount of time
+ * on decks with many masters, and most sessions never open the layout gallery
+ * at all.
+ *
+ * @example
+ * ```ts
+ * const preview: PptxLayoutPreview = {
+ *   path: "ppt/slideLayouts/slideLayout2.xml",
+ *   width: 960,
+ *   height: 540,
+ *   elements: [],
+ *   placeholders: [{ type: "title" }],
+ * };
+ * // => satisfies PptxLayoutPreview
+ * ```
+ */
+interface PptxLayoutPreview {
+  /** ZIP path of the layout this preview belongs to. */
+  path: string;
+  /** Slide width in CSS pixels, so a thumbnail can compute its own scale. */
+  width: number;
+  /** Slide height in CSS pixels. */
+  height: number;
+  /** Background resolved from the layout, falling back to its master's. */
+  backgroundColor?: string;
+  /** Background image data URL, when the layout or master declares one. */
+  backgroundImage?: string;
+  /** The layout's own artwork (pictures, shapes and static text). */
+  elements: PptxElement[];
+  /** Placeholder slots, drawn as outlined frames in the gallery. */
+  placeholders: PptxPlaceholderFrame[];
+}
 /**
  * A theme part available in the presentation package.
  *
@@ -5568,6 +5917,54 @@ interface PptxEmbeddedFontList {
   rawXml?: XmlObject;
 }
 //#endregion
+//#region src/core/types/comment-mentions.d.ts
+/**
+ * A single `@`-mention inside a modern comment body.
+ *
+ * Offsets index into the comment's FLATTENED plain text: every `a:t` value
+ * below `p188:txBody` concatenated, with paragraphs joined by `\n`. That is the
+ * same string `PptxComment.text` carries, so an edit to `text` invalidates
+ * every offset after the edit point and the serializer re-bases them.
+ *
+ * The markup Office uses for a mention is `CT_Mention` (documented for the
+ * SpreadsheetML `2018/threadedcomments` part): `mentionpersonId`, `mentionId`,
+ * `startIndex` and `length`. The PowerPoint `2018/8/main` schema does not
+ * publish a mention element at all, so `rawXml` is retained and re-emitted
+ * attribute-for-attribute: a producer that spells the attributes differently
+ * still round-trips.
+ *
+ * @example
+ * ```ts
+ * const mention: PptxCommentMention = {
+ *   personId: "{2CB2E9D0-D392-EB21-5D46-FBA34C1295E6}",
+ *   authorName: "Bob Example",
+ *   startIndex: 3,
+ *   length: 11,
+ * };
+ * // => "Hi Bob Example can you check this".slice(3, 14) === "Bob Example"
+ * ```
+ */
+interface PptxCommentMention {
+  /** `mentionId`: GUID identifying this mention instance. */
+  id?: string;
+  /** `mentionpersonId`: the `p188:author` id of the mentioned person. */
+  personId: string;
+  /** Display name resolved from the author list at parse time, when known. */
+  authorName?: string;
+  /** Character offset of the mentioned span in the flattened plain text. */
+  startIndex: number;
+  /** Character length of the mentioned span. */
+  length: number;
+  /**
+   * `uri` of the `p188:ext` this mention list was read from. Undefined means
+   * the list is a direct child of `p188:cm`, which is where it is written for
+   * newly authored mentions.
+   */
+  containerUri?: string;
+  /** Original `p188:mention` node, retained for unknown-attribute preservation. */
+  rawXml?: XmlObject;
+}
+//#endregion
 //#region src/core/types/metadata.d.ts
 /**
  * A slide comment — may be a legacy positional comment or a modern
@@ -5614,6 +6011,8 @@ interface PptxComment {
   title?: string;
   /** Modern threaded comment support (p15:threadingInfo). */
   threadId?: string;
+  /** `@`-mentions, indexed into `text` (see {@link PptxCommentMention}). */
+  mentions?: PptxCommentMention[];
   /** Replies to this comment (for modern threaded comments). */
   replies?: PptxComment[];
   /** ID of the element this comment is associated with (if any). */
@@ -6133,7 +6532,7 @@ interface PptxTheme {
  * // => "morph" — one of 40+ transition effects
  * ```
  */
-type PptxTransitionType = 'none' | 'cut' | 'fade' | 'push' | 'wipe' | 'split' | 'randomBar' | 'blinds' | 'checker' | 'circle' | 'comb' | 'cover' | 'diamond' | 'dissolve' | 'plus' | 'pull' | 'random' | 'strips' | 'uncover' | 'wedge' | 'wheel' | 'zoom' | 'newsflash' | 'morph' | 'conveyor' | 'doors' | 'ferris' | 'flash' | 'flythrough' | 'gallery' | 'glitter' | 'honeycomb' | 'pan' | 'prism' | 'reveal' | 'ripple' | 'shred' | 'switch' | 'vortex' | 'warp' | 'wheelReverse' | 'window' | 'cube' | 'flip' | 'rotate' | 'orbit' | 'fallOver' | 'drape' | 'curtains' | 'wind' | 'prestige' | 'fracture' | 'crush' | 'peelOff' | 'pageCurlDouble' | 'pageCurlSingle' | 'airplane' | 'origami';
+type PptxTransitionType = 'none' | 'cut' | 'fade' | 'push' | 'wipe' | 'split' | 'randomBar' | 'blinds' | 'checker' | 'circle' | 'comb' | 'cover' | 'diamond' | 'dissolve' | 'plus' | 'pull' | 'random' | 'strips' | 'uncover' | 'wedge' | 'wheel' | 'zoom' | 'newsflash' | 'morph' | 'conveyor' | 'doors' | 'ferris' | 'flash' | 'flythrough' | 'gallery' | 'glitter' | 'honeycomb' | 'pan' | 'prism' | 'reveal' | 'ripple' | 'shred' | 'switch' | 'vortex' | 'warp' | 'wheelReverse' | 'window' | 'cube' | 'flip' | 'rotate' | 'box' | 'orbit' | 'fallOver' | 'drape' | 'curtains' | 'wind' | 'prestige' | 'fracture' | 'crush' | 'peelOff' | 'pageCurlDouble' | 'pageCurlSingle' | 'airplane' | 'origami';
 /** Split orientation from OOXML `@_orient`. */
 type PptxSplitOrientation = 'horz' | 'vert';
 /** Schema-defined `ST_TransitionSpeed` values. */
@@ -6428,6 +6827,18 @@ interface PptxSlideBackgroundPattern {
 interface PptxSlide {
   id: string;
   rId: string;
+  /**
+   * `p:sldIdLst/p:sldId/@id` (ST_SlideId, 256..2147483647): the numeric key
+   * that sections (`p14:sldIdLst/p14:sldId/@id`) and section/summary zooms
+   * name slides by.
+   *
+   * It lives in `presentation.xml`, NOT in the slide part, so it cannot be
+   * recovered from `rawXml`. Without it on the model, code that writes a
+   * section's membership has nothing correct to write and falls back to the
+   * slide NUMBER, which is 1-based and therefore never matches a real deck's
+   * ids: the section reloads with no slides in it.
+   */
+  slideId?: string;
   sourceSlideId?: string;
   /** Optional author-supplied slide name (set via `SlideBuilder.setName`). */
   name?: string;
@@ -6630,6 +7041,26 @@ interface PptxPresentationProperties {
   /** Kiosk auto-restart interval in milliseconds (from `p:kiosk/@restart`). Only meaningful when showType is "kiosk". */
   kioskRestartTime?: number;
 }
+/**
+ * Slide dimensions from `p:sldSz` (CT_SlideSize, ECMA-376 §19.2.1.39).
+ *
+ * @example
+ * ```ts
+ * const size: PptxSlideSize = { widthEmu: 9144000, heightEmu: 6858000, type: 'screen4x3' };
+ * // => satisfies PptxSlideSize
+ * ```
+ */
+interface PptxSlideSize {
+  /** `@cx` in EMU. Omitted or non-positive values leave the loaded width alone. */
+  widthEmu?: number;
+  /** `@cy` in EMU. Omitted or non-positive values leave the loaded height alone. */
+  heightEmu?: number;
+  /**
+   * `@type` (ST_SlideSizeType). The schema default is `custom`, which is
+   * why PowerPoint omits the attribute for a non-preset size.
+   */
+  type?: string;
+}
 /**
  * A named custom slide show (`p:custShowLst / p:custShow`).
  *
@@ -7644,6 +8075,19 @@ interface PptxHandlerSaveOptions {
   customerData?: PptxCustomerData[];
   /** Photo album metadata to save back to `p:photoAlbum`. */
   photoAlbum?: PptxPhotoAlbum;
+  /**
+   * Slide dimensions to write back to `p:sldSz`.
+   *
+   * Omitting the option preserves the load-time dimensions verbatim, which
+   * is why an edit made through a viewer's Slide Size control has to reach
+   * the save call: nothing else in the pipeline can observe it.
+   *
+   * PowerPoint derives `Presentation.PageSetup.SlideSize` from `@cx`/`@cy`
+   * alone (verified by COM: an A4-typed `p:sldSz` carrying 4:3 dimensions
+   * still reports `ppSlideSizeCustom`), so `type` is written for fidelity
+   * but the dimensions are what actually decide the reported preset.
+   */
+  slideSize?: PptxSlideSize;
   /** East Asian line-break settings to save back to `p:kinsoku`. */
   kinsoku?: PptxKinsoku | null;
   /** Write-protection verifier. Set to `null` to remove, `undefined` to preserve existing. */
@@ -7699,6 +8143,8 @@ interface IPptxHandlerRuntime {
   revokeBlobUrls(): void;
   getCompatibilityWarnings(): PptxCompatibilityWarning[];
   getLayoutOptions(): PptxLayoutOption[];
+  getLayoutPreview(layoutPath: string): Promise<PptxLayoutPreview | null>;
+  getLayoutPreviews(layoutPaths?: readonly string[]): Promise<PptxLayoutPreview[]>;
   createXmlBuilder(data: PptxData): PptxXmlBuilder;
   Builder(data: PptxData): PptxXmlBuilder;
   setTemplateBackground(path: string, backgroundColor: string | undefined): void;
@@ -7887,6 +8333,26 @@ declare class PptxHandlerCore {
    * @returns Array of {@link PptxLayoutOption} entries.
    */
   getLayoutOptions(): PptxLayoutOption[];
+  /**
+   * Build the artwork thumbnails backing the New Slide / Layout galleries.
+   *
+   * Parsing happens on first request and is memoised afterwards, so opening
+   * the gallery costs one pass over the layout parts and reopening it costs
+   * nothing. Callers that only need one entry should prefer
+   * {@link getLayoutPreview}.
+   *
+   * @param layoutPaths - Restrict the result to these layouts; defaults to
+   *   every layout in the presentation.
+   * @returns One {@link PptxLayoutPreview} per resolvable layout.
+   */
+  getLayoutPreviews(layoutPaths?: readonly string[]): Promise<PptxLayoutPreview[]>;
+  /**
+   * Build the artwork thumbnail for a single layout.
+   *
+   * @param layoutPath - Archive path of the `p:sldLayout` part.
+   * @returns The preview, or `null` when the presentation has no such layout.
+   */
+  getLayoutPreview(layoutPath: string): Promise<PptxLayoutPreview | null>;
   /**
    * Create a fluent XML builder scoped to the given presentation data.
    *
@@ -8213,24 +8679,38 @@ declare class PptxHandlerCore {
     name?: string;
   }>>;
   /**
-   * Export selected slides as individual PPTX files.
+   * Export selected slides to a vector or raster format, keyed by slide index.
    *
-   * Each entry in the returned map is keyed by slide index and contains a
-   * standalone `Uint8Array` PPTX with only that slide.
+   * **This does not produce PPTX files.** The previous version of this comment
+   * said each entry was "a standalone PPTX with only that slide", named the
+   * option `slideIndexes` (the real field is `slideIndices`), and wrote the
+   * bytes to `slide_N.pptx`. None of that was ever true: the runtime has
+   * always taken a `format` of `svg` / `png` / `pdf`. Per-slide PPTX
+   * extraction is a different operation and is not implemented here.
+   *
+   * Only `svg` works without a host-supplied backend, and it works fully:
+   * the headless {@link SvgExporter} renders it with no DOM. `png` and `pdf`
+   * THROW, because this package carries no rasteriser; use a viewer binding's
+   * browser export pipeline, or override `exportSlides` on the runtime with
+   * your own backend.
    *
    * @param slides  - Full slide array.
-   * @param options - Export options (slide indexes, format, etc.).
-   * @returns A `Map<slideIndex, Uint8Array>` of exported files.
+   * @param options - Export options (`format`, `slideIndices`, `width`, ...).
+   * @returns A `Map<slideIndex, Uint8Array>` of exported files. Hidden slides
+   *   are omitted unless `options.includeHidden` is set, so the map can be
+   *   smaller than `options.slideIndices`.
+   * @throws {Error} when `options.format` is `png` or `pdf`.
    *
    * @example
    * ```ts
    * const exports = await handler.exportSlides(data.slides, {
-   *   slideIndexes: [0, 2],
+   *   format: 'svg',
+   *   slideIndices: [0, 2],
    * });
    * for (const [idx, bytes] of exports) {
-   *   await fs.writeFile(`slide_${idx}.pptx`, Buffer.from(bytes));
+   *   await fs.writeFile(`slide_${idx}.svg`, Buffer.from(bytes));
    * }
-   * // => Map<number, Uint8Array> — one standalone .pptx per exported slide
+   * // => Map<number, Uint8Array>: one SVG document per exported slide
    * ```
    */
   exportSlides(slides: PptxSlide[], options: PptxExportOptions): Promise<Map<number, Uint8Array>>;
@@ -8680,6 +9160,91 @@ interface MorphTransitionPlan {
 //#region src/render/text-case-transform.d.ts
 type ChangeCaseMode = 'sentence' | 'lower' | 'upper' | 'capitalize' | 'toggle';
 //#endregion
+//#region src/render/shape-adjustment-model.d.ts
+/**
+ * `shape-adjustment-model`: the vocabulary the adjust-handle modules share.
+ *
+ * The `a:ahLst` work is split three ways for the repo's file-size budget:
+ * `shape-adjustment-probe` measures the geometry, `shape-adjustment-handles`
+ * derives the handles from those measurements, and `shape-adjustment-solver`
+ * turns a pointer position back into guide values. All three need these types
+ * and the one rule that operates purely on them, so they live here and the
+ * dependency graph stays a DAG rather than a cycle.
+ *
+ * @module render/shape-adjustment-model
+ */
+/**
+ * How a pointer position becomes a guide value, captured once when the gesture
+ * starts so `pointermove` stays pure arithmetic.
+ */
+interface ShapeAdjustmentSolver {
+  /** `linear`: the handle slides. `angular`: it swings about {@link centerX}. */
+  kind: 'linear' | 'angular';
+  /** Handle position in element-local px at {@link startValue}. */
+  anchorX: number;
+  anchorY: number;
+  /** Element-local px the handle travels per ONE unit of guide value. */
+  dirX: number;
+  dirY: number;
+  /** Pivot for an angular handle (the shape centre). */
+  centerX: number;
+  centerY: number;
+  /** The guide value the anchor was measured at. */
+  startValue: number;
+  /** Guide-space bounds, taken from the preset's own `pin` clamp. */
+  min: number;
+  max: number;
+}
+/** One guide a handle drives. */
+interface AdjustmentAxisSolver {
+  key: string;
+  solver: ShapeAdjustmentSolver;
+}
+/** Descriptor for one draggable adjustment handle (the amber diamond). */
+interface ShapeAdjustmentHandleDescriptor {
+  /** The `a:avLst` guide name this handle writes (`adj`, `adj1`, ...). */
+  key: string;
+  /** Handle x offset in element-local px (origin = element top-left). */
+  left: number;
+  /** Handle y offset in element-local px. */
+  top: number;
+  /**
+   * Current adjustment value in GUIDE units, not a 0-1 fraction. Most presets
+   * range 0..50000 or 0..100000 and the angular ones run to 21,600,000.
+   */
+  value: number;
+  cursor: string;
+  /**
+   * How this handle's drag resolves, measured off the preset geometry: one
+   * entry per `a:avLst` guide it drives (callouts drive two). Absent only for
+   * a caller that built a descriptor by hand.
+   */
+  solvers?: AdjustmentAxisSolver[];
+}
+/** Live drag state captured when an adjustment gesture starts. */
+interface ShapeAdjustmentDragState {
+  elementId: string;
+  key: string;
+  shapeType: string;
+  startClientX: number;
+  startClientY: number;
+  startAdjustment: number;
+  startWidth: number;
+  startHeight: number;
+  moved: boolean;
+  /** Copied from the descriptor the gesture started on. */
+  solvers?: AdjustmentAxisSolver[];
+  /**
+   * The element's whole `a:avLst` map at gesture start.
+   *
+   * A binding writes `shapeAdjustments` as one object, so a drag that sent
+   * only the guide it changed would DELETE every other authored adjustment on
+   * a multi-adjust preset (a `quadArrow` would lose two of its three the first
+   * time one was touched).
+   */
+  startAdjustments?: Record<string, number>;
+}
+//#endregion
 //#region src/render/collaboration-text-codec.d.ts
 /**
  * collaboration-text-codec.ts: TextSegment[] <-> Y.Text delta codec used by the
@@ -8798,6 +9363,12 @@ interface CompareResult {
   changedCount: number;
   unchangedCount: number;
 }
+interface SlideSizeEmu {
+  widthEmu: number;
+  heightEmu: number;
+  /** ST_SlideSizeType token, or `''` for a size with no preset. */
+  type: string;
+}
 //#endregion
 //#region src/render/mobile-viewport.d.ts
 /**
@@ -8900,6 +9471,34 @@ interface ElementClipboardPayload {
   element: PptxElement;
   isTemplate: boolean;
 }
+/** What the "Embed fonts in the file" toggle should look like and do. */
+interface FontEmbeddingDescriptor {
+  /** Distinct typeface names the loaded deck currently embeds. */
+  embeddedFamilies: string[];
+  /**
+   * Whether the toggle accepts input. False when the deck embeds nothing,
+   * because turning it on could not produce an embedded font.
+   */
+  interactive: boolean;
+  /**
+   * The position the toggle must START in so that it describes the file that
+   * would be written right now. A deck that arrived with embedded fonts keeps
+   * them on save, so the switch has to read "on" from the outset; the previous
+   * hardcoded `false` said the opposite of what save actually did.
+   */
+  initialEnabled: boolean;
+  /** Present only when `interactive` is false. */
+  disabledReasonKey?: string;
+}
+//#endregion
+//#region src/render/master-view.d.ts
+/** Which part the master view is currently pointed at. */
+interface MasterViewTarget {
+  tab: MasterViewTab;
+  masterIndex: number;
+  /** `null` selects the master itself rather than one of its layouts. */
+  layoutIndex: number | null;
+}
 //#endregion
 //#region src/render/virtualized-list.d.ts
 /** Framework-neutral virtual-list range used by every thumbnail sidebar. */
@@ -8915,6 +9514,51 @@ interface VirtualizedRange {
 }
 /** Compute the rendered item window for fixed-height virtual lists. */
 declare function computeVirtualRange(totalItems: number, itemHeight: number, scrollTop: number, viewportHeight: number, overscan?: number): VirtualizedRange;
+/**
+ * Why the deck is being serialised, which is a separate question from whether
+ * the user protected it.
+ *
+ * - `user-file` (the default): the bytes leave the viewer as a file. Save,
+ *   Save As, Export, the host-facing `getContent()`. Protection applies.
+ * - `recovery-snapshot`: the bytes exist only so the viewer can read them back.
+ *   The autosave crash-recovery snapshot in IndexedDB, and the internal
+ *   re-serialise-then-reload cycle behind "apply theme". Protection does NOT
+ *   apply: these are always written in the clear.
+ *
+ * ## Why a recovery snapshot must stay plaintext
+ *
+ * Nothing that reads a snapshot back has a password to give it.
+ * `readBackstageRecentFile`, `restoreSessionDeck` and the Version History
+ * panel's Restore all hand `record.data` straight to `PptxHandler.load()` with
+ * no `password` option, and an encrypted package refuses to open without one
+ * (`EncryptedFileError`). So an encrypted snapshot is not an inconvenience, it
+ * is unreadable: the moment the user turns on protection their crash-recovery
+ * data is silently destroyed, which is the exact opposite of what autosave is
+ * for.
+ *
+ * Encrypting it "properly" is not available either. Decrypting on recovery
+ * means the key has to outlive the crash the snapshot exists for, so it would
+ * have to sit in the same IndexedDB / localStorage as the snapshot itself,
+ * next to the ciphertext it unlocks. That is not a security boundary, it is
+ * theatre. Prompting the user instead only works if they remember the password
+ * of a deck they lost, which is precisely the moment they will not.
+ *
+ * ## The tradeoff this accepts (deliberately, not by omission)
+ *
+ * A password-protected deck DOES leave its content in cleartext at rest in the
+ * origin's IndexedDB. Anyone with the browser profile, or any script running on
+ * the origin, can read it. What limits the exposure: snapshots are scoped to
+ * the origin and profile, aged out by the store, and clearable from
+ * File > Account > Storage & Privacy (`clearLocalStorageData`). A user who
+ * cannot accept plaintext at rest should switch AutoSave off, which stops the
+ * snapshot being written at all.
+ *
+ * The rejected alternative was "skip autosave entirely while a password is
+ * set". It removes the plaintext, but it also removes crash recovery without
+ * telling anyone, so a crash loses the whole editing session. Losing data
+ * quietly is the failure mode we are fixing, not a fix for it.
+ */
+type DeckSavePurpose = 'user-file' | 'recovery-snapshot';
 //#endregion
 //#region src/render/toolbar-actions.d.ts
 /**
@@ -8970,6 +9614,15 @@ interface ViewerGeneralOptions {
   userName: string;
   userInitials: string;
   showStartScreen: boolean;
+  /**
+   * Lets the user hand a local font file to the viewer so decks authored
+   * with a font the browser lacks render with the real face.
+   *
+   * Off by default. The registration reads a file the user picks and adds it
+   * to the page's font set for the session, which is a capability a host
+   * embedding the viewer should opt into rather than inherit.
+   */
+  enableCustomFontUpload: boolean;
 }
 interface ViewerProofingOptions {
   autoCorrectTwoInitialCapitals: boolean;
@@ -8986,13 +9639,25 @@ interface ViewerProofingOptions {
   checkSpellingAsYouType: boolean;
   hideSpellingErrors: boolean;
 }
+/**
+ * File > Options > Save.
+ *
+ * Font embedding deliberately has NO entry here. It is owned by the File >
+ * Fonts panel, whose toggle is the one the save path reads (see
+ * `render/font-embedding`: `describeFontEmbedding` decides the toggle's start
+ * position and whether it can do anything at all, `embeddedFontSaveOptions`
+ * turns it into the `PptxHandler.save()` slice). This group used to carry a
+ * second `embedFonts` boolean, plus an `embedAllFontCharacters` companion, and
+ * neither was read by anything: the pane moved a switch that changed no saved
+ * byte, while the panel next door moved the real one. Two switches for one
+ * setting, one of them lying, is worse than one switch in a less
+ * PowerPoint-shaped place.
+ */
 interface ViewerSaveOptions {
   autoSave: boolean;
   autoRecoverIntervalMinutes: number;
   keepLastAutoRecoveredVersion: boolean;
   defaultExportFormat: DefaultExportFormat;
-  embedFonts: boolean;
-  embedAllFontCharacters: boolean;
   cacheRetentionDays: number;
   clearCacheOnClose: boolean;
 }
@@ -9211,22 +9876,6 @@ interface ResizeState {
   lastWidth: number;
   lastHeight: number;
 }
-/**
- * Tracks the state of an ongoing shape adjustment handle drag.
- * Used when the user drags the yellow diamond handle to alter
- * shape-specific parameters (e.g. corner radius on a rounded rectangle).
- */
-interface ShapeAdjustmentDragState {
-  elementId: string;
-  key: string;
-  shapeType: string;
-  startClientX: number;
-  startClientY: number;
-  startAdjustment: number;
-  startWidth: number;
-  startHeight: number;
-  moved: boolean;
-}
 /**
  * A snapshot of editor state captured for undo/redo history.
  * Contains the full slide deck state at a point in time so that
@@ -9497,10 +10146,20 @@ interface ToolbarProps {
   onTransformTextCase: (mode: ChangeCaseMode) => void;
   isOverflowMenuOpen: boolean;
   onSetOverflowMenuOpen: (open: boolean) => void;
-  layoutOptions: Array<{
-    path: string;
-    name: string;
-  }>;
+  layoutOptions: PptxLayoutOption[];
+  /** `layoutPath` of the active slide, marking the current gallery tile. */
+  currentLayoutPath?: string;
+  /** Supplies gallery artwork; without it the menus stay name-only. */
+  loadLayoutPreviews?: () => Promise<PptxLayoutPreview[]>;
+  /** Theme major/minor latin faces, leading the font dropdown. */
+  themeFonts?: {
+    heading?: string;
+    body?: string;
+  };
+  /** Families the deck embeds, offered as their own dropdown group. */
+  embeddedFontFamilies?: readonly string[];
+  /** Families registered this session via File > Options > Fonts. */
+  customFontFamilies?: readonly string[];
   onInsertSlideFromLayout: (path: string, name?: string) => void;
   /** Re-map the active slide onto another of its master's layouts. */
   onApplyLayout?: (path: string) => void;
@@ -9519,6 +10178,8 @@ interface ToolbarProps {
   onToggleVersionHistory?: () => void;
   onOpenPasswordProtection?: () => void;
   onOpenDocumentProperties?: () => void;
+  /** Design > Slide Size: reveal the inspector card that owns the slide size. */
+  onOpenSlideSize?: () => void;
   onOpenFontEmbedding?: () => void;
   onOpenDigitalSignatures?: () => void;
   onEnterMasterView: () => void;
@@ -9552,6 +10213,22 @@ interface ToolbarProps {
   activeSlide?: PptxSlide;
   onTransitionChange: (updates: Partial<PptxSlideTransition>) => void;
   onApplyTransitionToAll: () => void;
+  /**
+   * Home > Slides > Reset: re-apply the active slide's own layout, restoring
+   * inherited placeholder geometry. Undeclared until now, which is why
+   * `SlidesGroup` bound `undefined` and the button did nothing.
+   */
+  onResetSlide?: () => void;
+  /** Home > Slides > Section: start a new section at the active slide. */
+  onAddSection?: () => void;
+  /** Home > Editing > Select > Select All (every element on the active slide). */
+  onSelectAll?: () => void;
+  /**
+   * Slide Show > Options: what the four checkboxes read, and how a tick is
+   * committed. See shared `ribbon-slide-show-options`.
+   */
+  presentationProperties?: PptxPresentationProperties;
+  onPresentationPropertiesChange?: (updates: Partial<PptxPresentationProperties>) => void;
   /** Host-supplied list of toolbar buttons/ribbon tabs to hide. See `PowerPointViewerProps.hiddenActions`. */
   hiddenActions?: readonly ToolbarActionId[];
   /** Whether the AI assistant is available (the host passed the `ai` prop). */
@@ -9628,7 +10305,7 @@ interface SlideCanvasProps {
   /** Called when the user presses mouse down on empty canvas space. */
   onCanvasMouseDown?: (e: React$1.MouseEvent) => void;
   onResizePointerDown: (elementId: string, e: React$1.MouseEvent, handle: string) => void;
-  onAdjustmentPointerDown: (elementId: string, e: React$1.MouseEvent) => void;
+  onAdjustmentPointerDown: (elementId: string, e: React$1.MouseEvent, descriptor: ShapeAdjustmentHandleDescriptor) => void;
   /** Commit a new rotation (degrees) when the on-canvas rotate handle is dragged. */
   onRotate?: (elementId: string, rotationDeg: number) => void;
   onInlineEditChange: (text: string) => void;
@@ -9747,6 +10424,17 @@ interface UseAutosaveInput {
   intervalSeconds?: number;
   /** Whether autosave is enabled. */
   enabled?: boolean;
+  /**
+   * The values a snapshot is built from, read fresh on each tick.
+   *
+   * `isDirty` stays true from the first edit until the user performs a real
+   * save, so on its own it makes the timer re-serialize and rewrite an
+   * identical deck every N seconds forever. Vue, Svelte and Vanilla never had
+   * that problem because they debounce on the slides array being reassigned;
+   * this is the same trigger, and `shouldWriteAutosaveSnapshot` writes
+   * whenever it is unsure. Omit it and every tick writes, as before.
+   */
+  getChangeSources?: () => readonly unknown[];
 }
 interface UseAutosaveResult {
   /** Current autosave status for display in the StatusBar. */
@@ -10192,6 +10880,18 @@ interface EditorHistoryInput {
   maxHistoryEntries?: number;
   hasActivePointerInteraction: () => boolean;
   pointerCommitNonce: number;
+  /**
+   * Raised whenever a local edit is committed, i.e. exactly when this hook
+   * learns the deck has diverged from what was last loaded or saved.
+   *
+   * This is what drives `state.isDirty`, and through it the status bar, the
+   * host's `onDirtyChange` (the demos hang their "* filename" title marker off
+   * it) and - critically - `useAutosave`, which short-circuits on a clean
+   * document. Before this existed, `isDirty` was raised only by a few
+   * master-view and document-property paths, so an element nudge, Home > New
+   * Slide or a notes edit left the flag false and crash recovery never ran.
+   */
+  onDirty?: () => void;
   setSlides: (slides: PptxSlide[]) => void;
   setCanvasSize: (size: CanvasSize) => void;
   setActiveSlideIndex: (index: number) => void;
@@ -10306,6 +11006,8 @@ interface UsePresentationModeInput {
   onToggleToolbar?: () => void;
   /** Open the All Slides navigator (Ctrl+S). */
   onShowAllSlides?: () => void;
+  /** Show or hide live captions (PowerPoint's bare J). */
+  onToggleSubtitles?: () => void;
   /** Called to persist rehearsal timings into slide transitions. */
   onSaveRehearsalTimings?: (timings: Record<number, number>) => void;
   /** Whether to loop continuously (kiosk or explicit loop setting). */
@@ -10682,6 +11384,15 @@ interface ViewerCoreState {
   /** Width and height of the slide canvas in CSS pixels. */
   canvasSize: CanvasSize;
   setCanvasSize: React$1.Dispatch<React$1.SetStateAction<CanvasSize>>;
+  /**
+   * `p:sldSz` in EMU, seeded from the loaded deck and updated by Design >
+   * Slide Size. It is what a save persists: the pixel `canvasSize` above
+   * cannot round-trip a preset (Ledger's 12179300 EMU is 1278.5px, and the
+   * integer pixel it rounds to costs the deck its `ppSlideSizeLedgerPaper`
+   * identity). `undefined` until a deck loads or the user picks a preset.
+   */
+  slideSizeEmu: SlideSizeEmu | undefined;
+  setSlideSizeEmu: React$1.Dispatch<React$1.SetStateAction<SlideSizeEmu | undefined>>;
   /** Zero-based index of the currently active (visible) slide. */
   activeSlideIndex: number;
   setActiveSlideIndex: React$1.Dispatch<React$1.SetStateAction<number>>;
@@ -10961,6 +11672,8 @@ interface UseLoadContentInput {
   setTemplateElementsBySlideId: React.Dispatch<React.SetStateAction<Record<string, PptxElement[]>>>;
   mediaDataUrls: Map<string, string>;
   setCanvasSize: React.Dispatch<React.SetStateAction<CanvasSize>>;
+  /** Seeds the EMU `p:sldSz` that a save persists (see `ViewerCoreState.slideSizeEmu`). */
+  setSlideSizeEmu: React.Dispatch<React.SetStateAction<SlideSizeEmu | undefined>>;
   setHeaderFooter: React.Dispatch<React.SetStateAction<PptxHeaderFooter>>;
   setLayoutOptions: React.Dispatch<React.SetStateAction<Array<{
     path: string;
@@ -10971,6 +11684,12 @@ interface UseLoadContentInput {
   setTableStyleMap: React.Dispatch<React.SetStateAction<ParsedTableStyleMap | undefined>>;
   setThemeOptions: React.Dispatch<React.SetStateAction<PptxThemeOption[]>>;
   setCustomShows: React.Dispatch<React.SetStateAction<PptxCustomShow[]>>;
+  /**
+   * Seeds the running show from `p:showPr/p:custShow/@id`, so a deck authored
+   * to open into a custom show plays that subset instead of the whole deck.
+   * A later manual pick still wins: this only fires on load.
+   */
+  setActiveCustomShowId: React.Dispatch<React.SetStateAction<string | null>>;
   setSections: React.Dispatch<React.SetStateAction<PptxSection[]>>;
   setPresentationProperties: React.Dispatch<React.SetStateAction<PptxPresentationProperties>>;
   setNotesMaster: React.Dispatch<React.SetStateAction<PptxNotesMaster | undefined>>;
@@ -11004,9 +11723,28 @@ interface UseLoadContentInput {
 interface UseLoadContentResult {
   handlerRef: React.MutableRefObject<PptxHandler | null>;
 }
-declare function useLoadContent({ content, clearSelection, history, setSlides, setTemplateElementsBySlideId, mediaDataUrls, setCanvasSize, setHeaderFooter, setLayoutOptions, setSlideMasters, setTheme, setTableStyleMap, setThemeOptions, setCustomShows, setSections, setPresentationProperties, setNotesMaster, setHandoutMaster, setNotesCanvasSize, setCustomProperties, setTagCollections, setCoreProperties, setAppProperties, setEmbeddedFonts, setActiveSlideIndex, setHasMacros, setHasDigitalSignatures, setDigitalSignatureCount, setGuides, setLoading, setError, setIsDirty, setIsEncrypted, onContentApplied }: UseLoadContentInput): UseLoadContentResult;
+declare function useLoadContent({ content, clearSelection, history, setSlides, setTemplateElementsBySlideId, mediaDataUrls, setCanvasSize, setSlideSizeEmu, setHeaderFooter, setLayoutOptions, setSlideMasters, setTheme, setTableStyleMap, setThemeOptions, setCustomShows, setActiveCustomShowId, setSections, setPresentationProperties, setNotesMaster, setHandoutMaster, setNotesCanvasSize, setCustomProperties, setTagCollections, setCoreProperties, setAppProperties, setEmbeddedFonts, setActiveSlideIndex, setHasMacros, setHasDigitalSignatures, setDigitalSignatureCount, setGuides, setLoading, setError, setIsDirty, setIsEncrypted, onContentApplied }: UseLoadContentInput): UseLoadContentResult;
 //#endregion
 //#region src/viewer/hooks/useElementOperations.d.ts
+/**
+ * View > Slide Master routing.
+ *
+ * The master view paints a part that is not in `slides`, so an edit made
+ * there has to be written back into the master / layout / notes / handout
+ * model instead. React previously keyed a pseudo-slide on the master's
+ * archive path and pushed edits into `templateElementsBySlideId`, where
+ * `buildSaveSlides` looks parts up by real slide id and so never found them:
+ * the change showed on screen and vanished on save.
+ */
+interface MasterViewRouting {
+  target: MasterViewTarget | null;
+  slideMasters: PptxSlideMaster[];
+  notesMaster: PptxNotesMaster | undefined;
+  handoutMaster: PptxHandoutMaster | undefined;
+  setSlideMasters: React.Dispatch<React.SetStateAction<PptxSlideMaster[]>>;
+  setNotesMaster: React.Dispatch<React.SetStateAction<PptxNotesMaster | undefined>>;
+  setHandoutMaster: React.Dispatch<React.SetStateAction<PptxHandoutMaster | undefined>>;
+}
 interface UseElementOperationsInput {
   slides: PptxSlide[];
   activeSlide: PptxSlide | undefined;
@@ -11017,6 +11755,8 @@ interface UseElementOperationsInput {
   editTemplateMode: boolean;
   /** Template (master/layout) elements for the active slide. */
   templateElements: PptxElement[];
+  /** Set while View > Slide Master is open; routes writes to the master part. */
+  masterView?: MasterViewRouting | undefined;
   history: EditorHistoryResult;
   setSlides: React.Dispatch<React.SetStateAction<PptxSlide[]>>;
   setTemplateElementsBySlideId: React.Dispatch<React.SetStateAction<Record<string, PptxElement[]>>>;
@@ -11064,6 +11804,12 @@ interface SectionOperations {
   moveSectionUp: (sectionId: string) => void;
   moveSectionDown: (sectionId: string) => void;
   moveSlidesToSection: (slideIndexes: number[], targetSectionId: string) => void;
+  /**
+   * Flip `section.collapsed`, the `p14:section/@collapsed` flag core already
+   * round-trips. React alone kept collapse in component-local state, so the
+   * one binding that could not persist a collapsed section was this one.
+   */
+  toggleSectionCollapse: (sectionId: string) => void;
 }
 declare function useSectionOperations(input: UseSectionOperationsInput): SectionOperations;
 //#endregion
@@ -11134,7 +11880,7 @@ interface CanvasInteractionHandlers {
   handleElementContextMenu: (elementId: string, e: React.MouseEvent) => void;
   handleCanvasMouseDown: (e: React.MouseEvent) => void;
   handleResizePointerDown: (elementId: string, e: React.MouseEvent, handle: string) => void;
-  handleAdjustmentPointerDown: (elementId: string, e: React.MouseEvent) => void;
+  handleAdjustmentPointerDown: (elementId: string, e: React.MouseEvent, descriptor: ShapeAdjustmentHandleDescriptor) => void;
   /** Commit a new rotation (degrees) for an element from the on-canvas rotate handle. */
   handleRotate: (elementId: string, rotationDeg: number) => void;
   /** Commit an inline (on-canvas) SmartArt node edit through the element-update path. */
@@ -11398,6 +12144,8 @@ interface UseExportHandlersInput {
   appProperties: Record<string, unknown> | null;
   customProperties: Array<Record<string, unknown>>;
   tagCollections: Array<Record<string, unknown>>;
+  /** The slide masters and their layouts; see `UseExportSaveAsInput`. */
+  slideMasters: PptxSlideMaster[];
   notesMaster: Record<string, unknown> | undefined;
   handoutMaster: Record<string, unknown> | undefined;
   guides: Array<{
@@ -11410,6 +12158,12 @@ interface UseExportHandlersInput {
   theme: PptxTheme | undefined;
   /** Slide canvas size in CSS pixels, carried into the deck-JSON export. */
   canvasSize: CanvasSize;
+  /**
+   * The EMU `p:sldSz` the viewer holds. Save-As builds its own save options
+   * rather than reusing `useSerialize`, so without this a Slide Size edit
+   * reached Save and not Save As (or the backstage Save, which routes here).
+   */
+  slideSizeEmu?: SlideSizeEmu | undefined;
   password?: string;
 }
 interface ExportHandlersResult {
@@ -11610,6 +12364,12 @@ interface UseViewerDialogsInput {
   isDirty: boolean;
   /** Editor history instance (used for markDirty on settings changes). */
   history: EditorHistoryResult;
+  /**
+   * Typeface names the loaded deck embeds (`p:embeddedFontLst`). Decides
+   * whether the "Embed fonts" toggle can do anything, and which position it
+   * starts in.
+   */
+  embeddedFontFamilies?: readonly string[];
 }
 /**
  * Output shape of the {@link useViewerDialogs} hook.
@@ -11656,9 +12416,15 @@ interface ViewerDialogsResult {
   /** OMML data for the equation currently being edited, or null. */
   editingEquationOmml: Record<string, unknown> | null;
   setEditingEquationOmml: React.Dispatch<React.SetStateAction<Record<string, unknown> | null>>;
-  /** Whether font embedding is enabled for save. */
+  /**
+   * Whether the saved file will carry the deck's embedded fonts. Read by
+   * `useSerialize` via `embeddedFontSaveOptions`; false strips
+   * `p:embeddedFontLst` and the `.fntdata` parts.
+   */
   embedFontsEnabled: boolean;
   setEmbedFontsEnabled: React.Dispatch<React.SetStateAction<boolean>>;
+  /** Whether the toggle can do anything on this deck, and why not when it cannot. */
+  fontEmbedding: FontEmbeddingDescriptor;
   /** True when the container is narrower than 768px (triggers compact layout). */
   isNarrowViewport: boolean;
   /** Switches the viewer to master view mode, preserving the previous mode for restoration. */
@@ -11773,6 +12539,16 @@ interface UseSerializeInput {
   /** Separated master/layout (template) elements, merged back at save time. */
   templateElementsBySlideId: Record<string, PptxElement[]>;
   activeSlideIndex: number;
+  /** The pixel canvas the raw Slide Size W/H inputs edit. */
+  canvasSize: CanvasSize;
+  /**
+   * The EMU `p:sldSz` the viewer is holding (seeded on load, replaced by a
+   * preset/orientation pick). Passed with `canvasSize` to
+   * `resolveSlideSizeSelection`, which keeps the EMU whenever the two still
+   * agree so a preset survives the save, and takes the pixels when the user
+   * has typed into the raw inputs.
+   */
+  slideSizeEmu?: SlideSizeEmu | undefined;
   guides: Array<{
     id: string;
     axis: 'h' | 'v';
@@ -11790,12 +12566,43 @@ interface UseSerializeInput {
   appProperties: PptxAppProperties | undefined;
   customProperties: PptxCustomProperty[];
   tagCollections: PptxTagCollection[];
+  /**
+   * The slide masters and their layouts, as View > Slide Master left them.
+   *
+   * Required, not optional: this was the one save option React never passed,
+   * and core rewrites a master or layout part only for the ones the caller
+   * hands back. Every master-view edit therefore showed on screen and was
+   * dropped by the save - a deleted master shape came back on reload, and a
+   * master background reverted to white. The other four bindings pass it.
+   * Core compares each part against the element list parsed at load and
+   * rewrites only what actually changed, so passing the whole array on every
+   * save costs an untouched deck nothing.
+   */
+  slideMasters: PptxSlideMaster[];
   notesMaster: PptxNotesMaster | undefined;
   handoutMaster: PptxHandoutMaster | undefined;
   handlerRef: React$1.RefObject<PptxHandler | null>;
   inlineEditingElementIdRef: React$1.MutableRefObject<string | null>;
   inlineEditingTextRef: React$1.MutableRefObject<string>;
   password?: string;
+  /**
+   * File > Fonts > "Embed fonts in the file". `false` passes
+   * `embeddedFontList: null`, which strips `p:embeddedFontLst`, the `/font`
+   * relationships and the `.fntdata` parts; `true` (the default) leaves core to
+   * re-embed whatever the deck arrived with. Before this the toggle reached no
+   * save call at all and the saved bytes were identical either way.
+   */
+  embedFonts?: boolean;
+  /**
+   * Why these bytes are being produced. Defaults to `'user-file'` (Save, Save
+   * As, Export, the imperative `getContent()`), which honours `password`.
+   * `'recovery-snapshot'` is for bytes the viewer reads back itself - the
+   * autosave snapshot and the re-serialise-then-reload cycle - and is always
+   * plaintext, because nothing on the way back in can supply the password.
+   * See `deck-save-encryption` in `pptx-viewer-shared` for the full rationale
+   * and the privacy tradeoff it accepts.
+   */
+  purpose?: DeckSavePurpose;
 }
 declare function useSerialize(input: UseSerializeInput): () => Promise<Uint8Array | null>;
 //#endregion
@@ -11838,6 +12645,12 @@ interface UsePresentationSetupInput {
   promptKeepInkAnnotations?: boolean;
   /** Options > Advanced > "Show popup toolbar" (default true). */
   popupToolbarEnabled?: boolean;
+  /**
+   * Show or hide live captions. PowerPoint toggles them on a bare `J` during a
+   * show, and the shared slide-show keymap resolves that key for every binding;
+   * without this callback the key is mapped and then lands nowhere.
+   */
+  onToggleSubtitles?: () => void;
 }
 interface PresentationSetupResult {
   presentation: UsePresentationModeResult;
@@ -11899,6 +12712,12 @@ interface UseIOHandlersInput {
   };
   handlerRef: React$1.RefObject<PptxHandler | null>;
   serializeSlides: () => Promise<Uint8Array | null>;
+  /**
+   * Plaintext serialisation for bytes the viewer feeds straight back into its
+   * own loader. "Apply theme" does exactly that, and the loader has no password
+   * to offer, so it must never receive an encrypted package.
+   */
+  serializeForRecovery: () => Promise<Uint8Array | null>;
   setContent: React$1.Dispatch<React$1.SetStateAction<ArrayBuffer | Uint8Array | null>>;
   onContentChange: ((content: Uint8Array) => void) | undefined;
   password?: string;
@@ -11917,6 +12736,18 @@ interface UseContentLifecycleInput {
   filePath: string | undefined;
   /** AutoSave toggle state; when false the recovery autosave timer is off. */
   autosaveEnabled?: boolean;
+  /**
+   * AutoRecover cadence in seconds, from
+   * `resolveAutosaveIntervalSeconds(File > Options > Save)`. React was the only
+   * binding that never passed one (vanilla, svelte and angular all resolve it),
+   * so the option's number field moved and the timer kept its 120s default.
+   */
+  autosaveIntervalSeconds?: number;
+  /**
+   * File > Fonts > "Embed fonts in the file". Forwarded to `useSerialize`, so
+   * turning it off actually strips the embedded font data on the next save.
+   */
+  embedFonts?: boolean;
   slides: PptxSlide[];
   state: ViewerState;
   history: EditorHistoryResult;
@@ -11929,7 +12760,14 @@ interface UseContentLifecycleInput {
 }
 interface ContentLifecycleResult {
   handlerRef: React$1.RefObject<PptxHandler | null>;
+  /** Serialise for the user: honours "Encrypt with Password". */
   serializeSlides: () => Promise<Uint8Array | null>;
+  /**
+   * Serialise for bytes the viewer reads back itself (autosave snapshot,
+   * re-serialise-then-reload). Always plaintext, so recovery - which has no
+   * password to offer - can actually open them.
+   */
+  serializeForRecovery: () => Promise<Uint8Array | null>;
   autosaveStatus: AutosaveStatus;
 }
 declare function useContentLifecycle(input: UseContentLifecycleInput): ContentLifecycleResult;
@@ -11962,6 +12800,11 @@ interface UseViewerIntegrationInput {
   filePath: string | undefined;
   /** AutoSave toggle state from the title bar. */
   autosaveEnabled: boolean;
+  /**
+   * AutoRecover cadence in seconds, resolved from File > Options > Save.
+   * Optional: omitting it keeps `useAutosave`'s 120s default.
+   */
+  autosaveIntervalSeconds?: number;
   canEdit: boolean;
   mode: ViewerState['mode'];
   slides: PptxSlide[];
@@ -12101,6 +12944,14 @@ interface LayoutSwitchingResult {
   loadAvailableLayouts: () => Promise<void>;
   /** Apply a layout to the active slide by its archive path. */
   applyLayout: (layoutPath: string) => Promise<void>;
+  /**
+   * Build the artwork thumbnails the New Slide / Layout galleries draw.
+   *
+   * Deliberately a callback rather than state: parsing every layout is only
+   * worth doing once the user opens one of those menus, and core memoises the
+   * result so reopening costs nothing.
+   */
+  loadLayoutPreviews: () => Promise<PptxLayoutPreview[]>;
   /** The current slide's layout path (if known). */
   currentLayoutPath: string | undefined;
 }
@@ -12285,6 +13136,13 @@ interface UseExportSaveAsInput {
   appProperties: Record<string, unknown> | null;
   customProperties: Array<Record<string, unknown>>;
   tagCollections: Array<Record<string, unknown>>;
+  /**
+   * The slide masters and their layouts, as View > Slide Master left them.
+   * Save As builds its own options rather than reusing `useSerialize`, so it
+   * needs the same array: without it a master-view edit reached Save and not
+   * Save As. (For a long while it reached neither.)
+   */
+  slideMasters: PptxSlideMaster[];
   notesMaster: Record<string, unknown> | undefined;
   handoutMaster: Record<string, unknown> | undefined;
   guides: Array<{
@@ -12297,6 +13155,8 @@ interface UseExportSaveAsInput {
   theme: PptxTheme | undefined;
   /** Slide canvas size in CSS pixels, carried into the deck-JSON export. */
   canvasSize: CanvasSize;
+  /** The EMU `p:sldSz` the viewer holds; see `UseExportHandlersInput`. */
+  slideSizeEmu?: SlideSizeEmu | undefined;
   modalControls: ExportModalControls;
   password?: string;
 }
@@ -12364,6 +13224,13 @@ interface UseKeyboardShortcutsInput {
   onUngroup?: () => void;
   /** Show or hide the keyboard-shortcut reference ("?"). */
   onToggleShortcuts?: () => void;
+  /**
+   * Open or close the find bar (Ctrl/Cmd+F). Left unwired by the default
+   * shell, where `useFindReplace` owns the find state and resolves the same
+   * chord against the same shared keymap; the case exists so the switch stays
+   * exhaustive and so a host driving this hook directly can handle it.
+   */
+  onFind?: () => void;
   /** Navigate to previous visible slide (edit mode, no selection). */
   onPrevSlide?: () => void;
   /** Navigate to next visible slide (edit mode, no selection). */
@@ -12522,6 +13389,8 @@ interface UsePresentationKeyboardInput {
   onToggleToolbar?: () => void;
   /** Open the All Slides navigator (Ctrl+S). */
   onShowAllSlides?: () => void;
+  /** Show or hide live captions (J). */
+  onToggleSubtitles?: () => void;
   onToggleBlackScreen?: () => void;
   onToggleWhiteScreen?: () => void;
   rehearsing: boolean;