pptx-ts 3.7.0 → 4.0.0

package/dist/{presentation-types-CDjScsev.d.ts → presentation-types-8jLQHI4M.d.ts}

@@ -1,35 +1,12 @@
-import { lt as ColorMapToken, pt as ThemeColorSlot } from "./slide-ZqAdVvHV.js";
-import { t as CustomPropertyValue } from "./pres-BcBR3CSM.js";
-import { a as Part, i as Relationships, n as OpcPackage, o as Element, t as OpcInput } from "./package-CaOLXSNi.js";
-//#region src/embedded-fonts.d.ts
-/**
- * The four face slots of `CT_EmbeddedFontListEntry`, in schema child order
- * (`font` first, then these). Iterate in this order everywhere so the read- and
- * write-side emitters agree on element order.
- */
-declare const EMBEDDED_FONT_SLOTS: readonly ['regular', 'bold', 'italic', 'boldItalic'];
-type EmbeddedFontSlot = (typeof EMBEDDED_FONT_SLOTS)[number];
-/** One embeddable face: a slot plus the raw font bytes (absent in pure read-side merges). */
-interface EmbeddedFontFace {
-  slot: EmbeddedFontSlot;
-  bytes?: Uint8Array;
-}
-/** A typeface family with 1..4 embedded faces — one `p:embeddedFont` entry. */
-interface EmbeddedFont {
-  /** `p:font/@typeface` — MUST match the family name used in run/`fontFace` typefaces or PowerPoint won't bind it. */
-  typeface: string;
-  panose?: string;
-  pitchFamily?: number;
-  charset?: number;
-  faces: EmbeddedFontFace[];
-}
-//#endregion
+import { Sn as ThemeColorSlot, sn as ColorMapToken, t as CustomPropertyValue } from "./pres-C6qgOFAa.js";
+import { t as EmbeddedFont } from "./embedded-fonts-DarT9aoa.js";
+import { a as Part, i as Relationships, n as OpcPackage, o as Element, t as OpcInput } from "./package-J49Ck6S2.js";
 //#region src/read/oxml/theme.d.ts
 /**
  * The colour-resolution context: the two maps that turn a DrawingML colour
  * reference into a literal hex — the effective colour map (token → `clrScheme`
  * slot, honouring any slide `clrMapOvr`) and the resolved colour scheme (slot →
- * 6-hex RGB). Shared by the read-model colour getters and {@link ThemeContext}.
+ * 6-hex RGB). Shared by the read-model colour getters and `ThemeContext`.
  */
 interface ColorContext {
   clrMap: Map<string, string>;
@@ -59,7 +36,9 @@ interface ThemeContext extends ColorContext {
   /**
    * The theme's `a:fontScheme`, for resolving a `+mj-*`/`+mn-*` major/minor font
    * token (the placeholder-inherited typeface chain bottoms out in one) to a
-   * literal face name via {@link resolveThemeFont}. `null`/absent leaves such a
+   * literal face name via `resolveThemeFont` in this module. (Named rather than linked: it is
+   * internal, so a reference link to it resolves to nothing in the published reference.)
+   * `null`/absent leaves such a
    * token unresolved.
    */
   fontScheme?: Element | null;
@@ -78,10 +57,29 @@ interface ThemeContext extends ColorContext {
    * `presentation.xml`), keyed by level — PowerPoint's lowest-priority text
    * fallback, applying to any run (placeholder or not) that resolves nothing
    * above it. Only ever set on a *slide* context (see `resolveSlideColorContext`);
-   * absent on notes/master/layout contexts, so their chains are unaffected.
+   * absent on notes/master/layout contexts, so their chains are unaffected. A table
+   * cell's text is read against a copy that holds the slide master's `p:otherStyle`
+   * here instead, the tier PowerPoint resolves cell text through (`TableCell.textFrame`).
    * Read-only — never mutated.
    */
   defaultTextStyle?: Element | null;
+  /**
+   * Memo for the placeholder lookups `findPlaceholder` (`read/oxml/placeholder-inherit.ts`)
+   * performs against
+   * {@link layoutRoot} and {@link masterRoot}, keyed by tier, placeholder type and `idx`.
+   *
+   * The lookup is a full subtree scan, and reading one run's five inherited properties used
+   * to perform ten of them: each property walks the tier chain, and each tier walk scans a
+   * layout and a master. The answer depends only on the roots and the `(type, idx)` asked
+   * for, and the roots on a context never change — so it is computed once per context.
+   *
+   * The memo lives here rather than in a module-level cache keyed by the root element
+   * because that is what scopes it correctly: a context is built per `Slide`/`TemplatePart`
+   * proxy, so the memo lasts exactly as long as the captured roots it agrees with, and a
+   * caller who mutates the deck and reads again gets a fresh context along with a fresh
+   * everything else. Written by `placeholder-inherit.ts` and read by nothing else.
+   */
+  placeholderMemo?: Map<string, Element | null>;
 }
 //#endregion
 //#region src/read/oxml/color-transform.d.ts
@@ -150,6 +148,37 @@ interface ResolvedColor {
  * resolve). Shared by the solid-fill and gradient-stop colour reads.
  */
 declare function resolveColorElement(colorEl: Element | null, ctx: ColorContext): ResolvedColor | null;
+/**
+ * A DrawingML colour as the file writes it and as it renders. Every read value type that carries a
+ * colour carries one of these: a gradient stop, a shadow or glow, a bullet, a cell border, a
+ * pattern's two colours, a picture's recolour, a solid background, and a chart series' fill and line.
+ *
+ * At most one of {@link srgb}, {@link scheme} and {@link preset} is set, naming the colour model the
+ * file used. A colour written as `a:sysClr` or `a:hslClr` sets none of the three and is reported
+ * through {@link resolved} alone. With no colour at all, every field is `null`.
+ */
+interface ColorRef {
+  /** `a:srgbClr/@val`, a 6-hex literal, or `null`. */
+  srgb: string | null;
+  /** `a:schemeClr/@val`, a theme token such as `accent1`, or `null`. */
+  scheme: string | null;
+  /** `a:prstClr/@val`, a preset name such as `black`, or `null`; `presetColorHex` makes one literal. */
+  preset: string | null;
+  /**
+   * The colour resolved against the theme, with its transforms applied, or `null` when there is no
+   * colour, it cannot be made literal (an unmapped token, or `a:scrgbClr`), or it was read without a
+   * theme, as a chart part's colours are. Read `resolved.transforms` when re-authoring against a
+   * different theme: `effectiveHex` alone is one theme baked in, and an empty list means the file
+   * stated no transforms.
+   */
+  resolved: ResolvedColor | null;
+}
+/**
+ * Read a colour element into a {@link ColorRef}.
+ * @param colorEl - an `a:EG_ColorChoice` element, or `null` for no colour
+ * @param ctx - the theme to resolve against, or `null` to leave {@link ColorRef.resolved} unset
+ */
+declare function readColorRef(colorEl: Element | null, ctx: ColorContext | null): ColorRef;
 /** A shape's resolved `p:style/a:fontRef` text tier: its colour and theme face. */
 interface StyleFontRef {
   /** The `a:fontRef` child colour (`a:schemeClr`/`a:srgbClr`/…) resolved through the theme, or `null` when it names none / cannot be made literal. */
@@ -163,48 +192,11 @@ interface StyleFontRef {
 interface GradientStop {
   /** Stop offset along the gradient, 0–1 (from `@pos`, thousandths of a percent), or `null` if unset. */
   position: number | null;
-  /** Explicit RGB colour as 6-hex (`a:srgbClr/@val`), or `null` when the stop uses another colour model. */
-  color: string | null;
-  /** Theme colour token (`a:schemeClr/@val`, e.g. `accent1`), or `null` when the stop uses another colour model. */
-  schemeColor: string | null;
-  /**
-   * Preset colour name (`a:prstClr/@val`, e.g. `black`/`cornflowerBlue` — the
-   * ECMA-376 §20.1.10.47 table), or `null` when the stop uses another colour
-   * model. The same raw/resolved split {@link import('./shapes/types.js').RecolorColor}
-   * uses; {@link import('../oxml/preset-color.js').presetColorHex}, exported from
-   * `ts-pptx/read`, makes one literal.
-   *
-   * These three raw fields name three of the five colour models the reader
-   * resolves. A stop written as `a:sysClr` or `a:hslClr` leaves all three `null`
-   * and is reported through {@link resolvedColor} alone, which is the only place
-   * its colour appears; `a:scrgbClr`, which the reader deliberately does not
-   * resolve, leaves {@link resolvedColor} `null` too.
-   */
-  presetColor: string | null;
-  /**
-   * The stop's colour as a full {@link ResolvedColor} — base `hex`, the raw
-   * `transforms` list (`lumMod`/`shade`/…) in document order, and the
-   * `effectiveHex`/`alpha` after applying them — exactly what a solid fill's
-   * `resolvedFill` gives. `null` when the colour cannot be made literal (an
-   * unmapped token, or a colour model we do not resolve).
-   *
-   * This is the field to read when re-authoring a stop against a *different*
-   * theme: {@link effectiveHex} alone is one theme baked in, so carrying it
-   * forward as a literal silently stops the stop tracking the theme it came from.
-   * `transforms` is what says whether there was anything to track, and an empty
-   * list here means the stop stated none — not that the reader could not see them.
-   */
-  resolvedColor: ResolvedColor | null;
-  /**
-   * The stop's colour resolved against the slide theme **with its colour
-   * transforms applied** — the final rendered hex, i.e. exactly
-   * `resolvedColor?.effectiveHex ?? null`, kept as a flat field because painting a
-   * gradient is what most callers want. `null` when the colour cannot be made
-   * literal (an unmapped token, or a colour model we do not resolve).
-   */
-  effectiveHex: string | null;
-  /** The stop's opacity (0–1) when an `alpha*` transform set one, else `undefined`. Mirrors `resolvedColor.alpha`. */
-  alpha?: number;
+  /**
+   * The stop's colour, as written and resolved against the slide theme. Its `resolved.effectiveHex` is
+   * the rendered colour and `resolved.alpha` the stop's opacity, when an `alpha*` transform set one.
+   */
+  colorRef: ColorRef;
 }
 /**
  * A gradient fill (`a:gradFill`), as read from a container — the stops plus the
@@ -260,7 +252,7 @@ interface PictureFillTile {
  * {@link srcRect}, the destination inset {@link fillRect}, and {@link tile}.
  *
  * Rect fields follow the read API's fraction convention (see
- * {@link import('./shapes.js').Picture.crop}): the raw attributes are
+ * {@link Picture.crop}): the raw attributes are
  * thousandths of a percent and are divided by 100000, so `0.1` is 10 % and a
  * negative value (a `fillRect` that bleeds past the edge) stays negative.
  */
@@ -285,6 +277,21 @@ interface PictureFill {
   rotWithShape: boolean | null;
 }
 //#endregion
+//#region src/read/api/pattern-fill.d.ts
+/**
+ * A pattern fill (`a:pattFill`) — a two-colour preset hatch. The write-side
+ * `fill: { type: 'pattern', pattern: { preset, fgColor, bgColor } }` emits the same element,
+ * so the {@link preset} name and both colours round-trip.
+ */
+interface PatternFill {
+  /** Preset pattern name (`@prst`, e.g. `pct50`/`diagCross`/`ltUpDiag`), or `null` when unset. */
+  preset: string | null;
+  /** Foreground colour (`a:fgClr`); every field is `null` when the pattern states none. */
+  foreground: ColorRef;
+  /** Background colour (`a:bgClr`); every field is `null` when the pattern states none. */
+  background: ColorRef;
+}
+//#endregion
 //#region src/read/api/slide-background.d.ts
 /** Where a slide's effective background comes from in the slide → layout → master chain. */
 type BackgroundSource = 'slide' | 'layout' | 'master';
@@ -292,7 +299,7 @@ type BackgroundSource = 'slide' | 'layout' | 'master';
  * An explicit background fill, decoded from a `p:bgPr` (or from a `p:bgRef`'s
  * resolved `fmtScheme` entry). The source-less core of {@link SlideBackground}: the
  * top-level variants add {@link BackgroundSource}, and it is what a `themeRef`'s
- * {@link SlideBackground.resolvedFill} carries.
+ * `SlideBackground.resolvedFill` carries.
  *
  * The `image` variant keeps `relId`/`partName` at the top level — the fields
  * callers already read — and adds the full {@link PictureFill} (stretch/tile
@@ -300,7 +307,7 @@ type BackgroundSource = 'slide' | 'layout' | 'master';
  */
 type BackgroundFill = {
   type: 'solid';
-  color: ResolvedColor | null;
+  colorRef: ColorRef;
 } | {
   type: 'gradient';
   gradient: GradientFill;
@@ -309,19 +316,16 @@ type BackgroundFill = {
   picture: PictureFill;
   relId: string | null;
   partName: string | null;
-} | {
+} | ({
   type: 'pattern';
-  preset: string | null;
-  foreground: ResolvedColor | null;
-  background: ResolvedColor | null;
-} | {
+} & PatternFill) | {
   type: 'none';
 };
 /**
  * A slide's effective background (`p:cSld/p:bg`), as a discriminated union on
- * `type`. Every variant carries {@link BackgroundSource}. `solid`/`gradient`/`image`
- * are what the writer authors and round-trip faithfully; `pattern`/`themeRef` are
- * read-only (imported decks) and `none` is an explicit `a:noFill`. A `themeRef`
+ * `type`. Every variant carries {@link BackgroundSource}. `solid`/`gradient`/`pattern`/`image`
+ * are what the writer authors and round-trip faithfully; `themeRef` is read-only
+ * (imported decks) and `none` is an explicit `a:noFill`. A `themeRef`
  * keeps its raw `idx` for fidelity and also exposes `resolvedFill` — the concrete
  * fill that `idx` resolves to through the slide theme's `fmtScheme` (`null` when the
  * theme/entry cannot be resolved).
@@ -329,7 +333,7 @@ type BackgroundFill = {
 type SlideBackground = {
   type: 'solid';
   source: BackgroundSource;
-  color: ResolvedColor | null;
+  colorRef: ColorRef;
 } | {
   type: 'gradient';
   source: BackgroundSource;
@@ -340,17 +344,14 @@ type SlideBackground = {
   picture: PictureFill;
   relId: string | null;
   partName: string | null;
-} | {
+} | ({
   type: 'pattern';
   source: BackgroundSource;
-  preset: string | null;
-  foreground: ResolvedColor | null;
-  background: ResolvedColor | null;
-} | {
+} & PatternFill) | {
   type: 'themeRef';
   source: BackgroundSource;
   idx: number | null;
-  color: ResolvedColor | null;
+  colorRef: ColorRef;
   resolvedFill: BackgroundFill | null;
 } | {
   type: 'none';
@@ -359,30 +360,15 @@ type SlideBackground = {
 //#endregion
 //#region src/read/api/shapes/oxml.d.ts
 /**
- * A shape's properties element (`p:spPr` / `p:grpSpPr`) paired with the schema
- * successors for ordered insertion of its `a:solidFill` and `a:ln` children.
- * `lnAfter` is `null` for kinds with no `a:ln` (group shapes).
- */
-interface ShapeProperties {
-  props: Element;
-  fillAfter: string[];
-  lnAfter: string[] | null;
-}
-//#endregion
-//#region src/read/api/pattern-fill.d.ts
-/**
- * A pattern fill (`a:pattFill`) — a two-colour preset hatch. The write-side
- * `fill: { type: 'pattern', pattern: { preset, fgColor, bgColor } }` emits the same element,
- * so the {@link preset} name and both colours round-trip. Colours resolve against the theme
- * (a scheme token → literal hex) the same way a solid fill does.
+ * Where a shape kind's paint is written: its properties element (`p:spPr` / `p:grpSpPr`), created
+ * in document order on demand, and for each paint the schema successors that paint's element is
+ * inserted before, or `null` for a paint the kind cannot carry (a group's `p:grpSpPr` has no
+ * `a:ln`).
  */
-interface PatternFill {
-  /** Preset pattern name (`@prst`, e.g. `pct50`/`diagCross`/`ltUpDiag`), or `null` when unset. */
-  preset: string | null;
-  /** Foreground colour (`a:fgClr`) resolved against the theme, or `null`. */
-  foreground: ResolvedColor | null;
-  /** Background colour (`a:bgClr`) resolved against the theme, or `null`. */
-  background: ResolvedColor | null;
+interface PaintSurface {
+  getOrAdd(): Element;
+  fill: readonly string[] | null;
+  line: readonly string[] | null;
 }
 //#endregion
 //#region src/read/api/shapes/types.d.ts
@@ -429,15 +415,14 @@ interface ConnectionSite {
  * A shape's outer drop shadow (`spPr/a:effectLst/a:outerShdw`), as read from a
  * shape and resolved against the slide theme. Distances are in points (the EMU
  * source ÷ 12700) and the direction in degrees (the `60000`ths source ÷ 60000),
- * matching the write-side {@link ShadowProps} convention so it round-trips.
+ * matching the write-side `ShadowProps` convention so it round-trips.
  */
 interface OuterShadow {
-  /** Effective shadow colour as 6-hex (theme-resolved, transforms applied), or `null`. */
-  color: string | null;
-  /** Theme colour token when the shadow colour was a scheme colour (e.g. `accent1`), else `undefined`. */
-  colorToken?: string;
-  /** Shadow opacity 0–1 (from the colour's `a:alpha`), or `undefined` when fully opaque. */
-  alpha?: number;
+  /**
+   * The shadow colour, as written and resolved against the slide theme. Its `resolved.alpha` is the
+   * shadow's opacity, absent when it is fully opaque.
+   */
+  colorRef: ColorRef;
   /** Blur radius in points (`@blurRad` ÷ 12700), or `undefined` when unset. */
   blurPt?: number;
   /** Offset distance in points (`@dist` ÷ 12700), or `undefined` when unset. */
@@ -453,12 +438,11 @@ interface OuterShadow {
  * direction in degrees, matching the write-side `shadow: { type: 'inner' }`.
  */
 interface InnerShadow {
-  /** Effective shadow colour as 6-hex (theme-resolved, transforms applied), or `null`. */
-  color: string | null;
-  /** Theme colour token when the shadow colour was a scheme colour (e.g. `accent1`), else `undefined`. */
-  colorToken?: string;
-  /** Shadow opacity 0–1 (from the colour's `a:alpha`), or `undefined` when fully opaque. */
-  alpha?: number;
+  /**
+   * The shadow colour, as written and resolved against the slide theme. Its `resolved.alpha` is the
+   * shadow's opacity, absent when it is fully opaque.
+   */
+  colorRef: ColorRef;
   /** Blur radius in points (`@blurRad` ÷ 12700), or `undefined` when unset. */
   blurPt?: number;
   /** Offset distance in points (`@dist` ÷ 12700), or `undefined` when unset. */
@@ -468,17 +452,15 @@ interface InnerShadow {
 }
 /**
  * A shape's glow effect (`spPr/a:effectLst/a:glow`) — a coloured halo — resolved
- * against the slide theme. The write-side text glow (`glow: { size, color,
- * opacity }`) emits the same element, so {@link radiusPt} (`@rad` ÷ 12700) and the
- * colour round-trip.
+ * against the slide theme. The write-side `glow` option is a text glow: it writes
+ * `a:glow` into each run's `a:rPr/a:effectLst`, which this does not read.
  */
 interface Glow {
-  /** Effective glow colour as 6-hex (theme-resolved, transforms applied), or `null`. */
-  color: string | null;
-  /** Theme colour token when the glow colour was a scheme colour (e.g. `accent1`), else `undefined`. */
-  colorToken?: string;
-  /** Glow opacity 0–1 (from the colour's `a:alpha`), or `undefined` when fully opaque. */
-  alpha?: number;
+  /**
+   * The glow colour, as written and resolved against the slide theme. Its `resolved.alpha` is the
+   * glow's opacity, absent when it is fully opaque.
+   */
+  colorRef: ColorRef;
   /** Glow radius in points (`@rad` ÷ 12700), or `undefined` when unset. */
   radiusPt?: number;
 }
@@ -597,6 +579,22 @@ interface AbsoluteFrame {
   /** Effective vertical flip after XOR-composing enclosing group flips. */
   flipV: boolean;
 }
+/**
+ * Why {@link Shape.absoluteFrame} could not resolve a frame.
+ *
+ * - `no-own-transform` — the shape states no `a:xfrm` of its own, or an incomplete
+ *   one: typically a placeholder inheriting its box from the layout. Nothing is
+ *   wrong with the deck; the read model reports what the shape itself states.
+ * - `group-transform-missing` — an enclosing `p:grpSp` states no complete
+ *   `a:off`/`a:ext` **and** `a:chOff`/`a:chExt` pair, so its child space is unknown.
+ * - `group-transform-degenerate` — an enclosing group's `a:chExt` is zero on an
+ *   axis, so the child-space ratio the mapping divides by is undefined.
+ *
+ * A missing group transform outranks a degenerate one wherever the two meet in
+ * one chain: composing needs every group's mapping, so an ancestor that states
+ * none is reported even when a nearer group is the degenerate one.
+ */
+type AbsoluteFrameFailure = 'no-own-transform' | 'group-transform-missing' | 'group-transform-degenerate';
 /**
  * A group shape's own child coordinate space (`p:grpSpPr/a:xfrm/a:chOff` and
  * `a:chExt`) in EMU — the space its children's `a:off`/`a:ext` are authored in.
@@ -618,32 +616,20 @@ interface ChildFrame {
   /** `a:chExt/@cy`. */
   extentY: number;
 }
-/**
- * A colour reference inside a picture recolour effect, split by colour model
- * (mirrors {@link GradientStop}). At most one field is non-`null`.
- */
-interface RecolorColor {
-  /** Explicit RGB as 6-hex (`a:srgbClr/@val`), or `null`. */
-  color: string | null;
-  /** Theme colour token (`a:schemeClr/@val`, e.g. `accent1`), or `null`. */
-  schemeColor: string | null;
-  /** Preset colour name (`a:prstClr/@val`, e.g. `black`/`white` — the duotone icon-tint stops), or `null`. */
-  presetColor: string | null;
-}
 /**
  * A picture's blip recolour effect (`p:blipFill/a:blip` recolour child), as read.
  * A small discriminated union over the effects a faithful reader needs to
- * reproduce a recoloured image. Colours use the same `color`/`schemeColor`/
- * `presetColor` split as {@link GradientStop}, so theme tokens can resolve through
- * {@link Slide.themeContext}. `threshold`/`amount` are 0–1 fractions.
+ * reproduce a recoloured image. Each colour is a {@link ColorRef}, resolved against the
+ * slide theme, so a duotone's `a:prstClr` and `a:sysClr` stops resolve as any other colour
+ * does. `threshold`/`amount` are 0–1 fractions.
  */
 type Recolor = {
   kind: 'duotone';
-  stops: RecolorColor[];
+  stops: ColorRef[];
 } | {
   kind: 'clrChange';
-  from: RecolorColor | null;
-  to: RecolorColor | null;
+  from: ColorRef | null;
+  to: ColorRef | null;
 } | {
   kind: 'grayscale';
 } | {
@@ -654,29 +640,13 @@ type Recolor = {
   amount: number;
 };
 //#endregion
-//#region src/read/api/text.d.ts
-/**
- * What a {@link Run}'s text body needs to resolve an *inherited* run
- * colour/size/face/bold: which placeholder the text lives in (or `null` for a
- * non-placeholder shape, which still resolves its `p:style/a:fontRef` and the
- * presentation `p:defaultTextStyle`), the slide theme context (with the
- * layout/master roots) to resolve against, and the shape's resolved
- * `p:style/a:fontRef` text tier. The owning slide's text body `a:lstStyle` is added
- * per text frame. Absent only for text reached without a theme context (table cells).
- */
-interface PlaceholderTextContext {
-  ph: PlaceholderRef | null;
-  flatten: ThemeContext;
-  /** The shape's resolved `p:style/a:fontRef` colour + face tier, or `null` when it has none. */
-  fontRef?: StyleFontRef | null;
-}
+//#region src/read/api/hyperlink.d.ts
 /**
- * A run's click hyperlink (`a:rPr/a:hlinkClick`): a link on a span of text. A URL
- * link carries an external {@link url}; a slide jump carries the internal
- * {@link targetPartName} (the linked slide's part) alongside its `hlinksldjump`
- * {@link action}. `tooltip` and `relId` are surfaced when present.
+ * A click hyperlink (`a:hlinkClick`), on a run or on a shape. A URL link carries an external
+ * {@link url}; a slide jump carries the internal {@link targetPartName} (the linked slide's part)
+ * alongside its `hlinksldjump` {@link action}. `tooltip` and `relId` are surfaced when present.
  */
-interface RunHyperlink {
+interface Hyperlink {
   /** External URL target (its `@r:id` resolves to a `TargetMode="External"` rel), or `null` for an internal/action-only link. */
   url: string | null;
   /** Absolute partname of an internal target (e.g. the slide a jump points at), or `null`. */
@@ -688,6 +658,104 @@ interface RunHyperlink {
   /** The relationship id (`@r:id`) backing the link, or `null` when the link is action-only. */
   relId: string | null;
 }
+//#endregion
+//#region src/read/api/table-style-resolve.d.ts
+/**
+ * The `a:tblPr` condition flags that gate which style parts apply to a table.
+ * `firstRow`/`bandRow` are the ones PowerPoint turns on by default; the rest are
+ * off unless the author enabled the corresponding "Header Column" / "Total Row" /
+ * "Banded Columns" toggle.
+ */
+interface TableConditionFlags {
+  firstRow: boolean;
+  lastRow: boolean;
+  firstCol: boolean;
+  lastCol: boolean;
+  bandRow: boolean;
+  bandCol: boolean;
+}
+/** A table's resolved entry in `tableStyles.xml`: its GUID, display name, and raw element. */
+interface ResolvedTableStyle {
+  /** The matched `@styleId` GUID (e.g. `{5C22544A-…}`). */
+  styleId: string;
+  /** The style's display name (`@styleName`, e.g. `Medium Style 2 - Accent 1`), or `null`. */
+  name: string | null;
+  /** Escape hatch: the underlying `a:tblStyle` element. After mutating it call {@link ResolvedTableStyle.markDirty}, or `save()` writes the original bytes. */
+  element_: Element;
+  /**
+   * Mark `tableStyles.xml` dirty so `save()` reserializes it. Call after mutating
+   * {@link ResolvedTableStyle.element_}. Note the part is deck-wide: an edit here
+   * reaches every table bound to this style.
+   */
+  markDirty(): void;
+}
+/**
+ * What a table style's text styles (`a:tcTxStyle`) give the text of one cell. Each property is
+ * taken from the highest-precedence part that states it, so a `firstRow` that makes the header
+ * bold and white still leaves the header's other properties to `wholeTbl`. Every field is `null`
+ * when no applicable part states it.
+ */
+interface TableCellTextStyle {
+  /** The text colour: the style's own colour child, else its `a:fontRef` colour, resolved. */
+  color: ResolvedColor | null;
+  /** The face its `a:font/a:latin` names, or the theme font its `a:fontRef/@idx` names, resolved. */
+  face: string | null;
+  /** `@b`: `on` is `true` and `off` is `false`; `def`, the schema default, states nothing. */
+  bold: boolean | null;
+  /** `@i`, read the same way as {@link bold}. */
+  italic: boolean | null;
+}
+//#endregion
+//#region src/read/api/text/run.d.ts
+/**
+ * What a text body is read against, handed from a {@link TextFrame} to each paragraph and run: the
+ * part an edit marks dirty, the theme the `resolved*` getters resolve against, the relationships
+ * a hyperlink or a picture bullet resolves through, and the inheritance its runs fall back through.
+ */
+interface TextContext {
+  /** The part the text lives in. */
+  part: Part;
+  /** The theme the text resolves against: the colour maps, `fontScheme`, and the layout and master roots. */
+  ctx: ThemeContext;
+  /**
+   * The owning part's relationships, or `null` for text read without them — a SmartArt drawing's
+   * cached text — whose run hyperlinks then report their raw `@r:id`, `@action` and `@tooltip`.
+   */
+  rels: Relationships | null;
+  /**
+   * What a run that sets no colour, size, face, bold or italic of its own inherits through, or
+   * `null` for text that inherits through nothing, such as a SmartArt point's.
+   */
+  inherit: TextInheritance | null;
+}
+/** The inheritance a shape's or a table cell's text resolves through below its own run properties. */
+interface TextInheritance {
+  /**
+   * The placeholder the text lives in, or `null` for a non-placeholder shape, which still resolves
+   * its `p:style/a:fontRef` and the presentation's `p:defaultTextStyle`.
+   */
+  ph: PlaceholderRef | null;
+  /** The shape's resolved `p:style/a:fontRef` colour and face, or `null` when it has none. */
+  fontRef: StyleFontRef | null;
+  /**
+   * A table cell's text style: what the table style's `a:tcTxStyle` gives the cell's region, with
+   * the theme's `tx1` and minor font where it names no colour or face. Read after {@link fontRef}
+   * and before the list-style chain. Absent for text outside a table.
+   */
+  tableText?: TableCellTextStyle | null;
+}
+/**
+ * What the runs of one paragraph inherit, each property resolved at most once and only when a run
+ * that sets no value of its own asks. Every run in a paragraph shares its level and `a:pPr`, so
+ * they share one of these.
+ */
+interface InheritedRunProps {
+  color(): ResolvedColor | null;
+  size(): number | null;
+  face(): string | null;
+  bold(): boolean | null;
+  italic(): boolean | null;
+}
 /**
  * A paragraph's line spacing (`a:pPr/a:lnSpc`), in whichever of the two OOXML
  * forms the file uses: an exact point height (`a:spcPts`) or a percentage of the
@@ -716,16 +784,12 @@ interface BulletStyle {
   sizePct: number | null;
   /** `a:buSzPts/@val` as an absolute point size (the raw attribute is hundredths of a point), or `null`. The alternative to {@link sizePct}; at most one is set. */
   sizePt: number | null;
-  /** Explicit RGB bullet colour as 6-hex (`a:buClr/a:srgbClr/@val`), or `null`. */
-  color: string | null;
-  /** Theme colour token when the bullet colour is a scheme colour (`a:buClr/a:schemeClr/@val`), or `null`. */
-  schemeColor: string | null;
-  /** The bullet colour resolved against the slide theme with its transforms applied, or `null` when unset or not resolvable to a literal. */
-  resolvedColor: ResolvedColor | null;
+  /** The bullet's own colour (`a:buClr`); every field is `null` when the paragraph leaves it to be inherited. */
+  colorRef: ColorRef;
 }
 /**
  * A paragraph's bullet, as the structured counterpart of the `a:pPr` bullet
- * children. Discriminated on {@link kind}, which is one of the four mutually
+ * children. Discriminated on `kind`, which is one of the four mutually
  * exclusive choices the schema allows:
  *
  * - `'none'`    — `a:buNone`, the bullet explicitly suppressed. Carries no style,
@@ -766,102 +830,31 @@ type BulletDetail = {
 declare class Run {
   #private;
   private readonly element;
-  private readonly part;
-  /** The owning slide's theme context (colour maps + `fontScheme`), for the `resolved*` getters; absent when the run was reached without one. */
-  private readonly themeContext?;
   /**
-   * Resolves the colour this run inherits from its placeholder/list-style chain
-   * when it sets none of its own (item A). Built by the owning {@link Paragraph}
-   * for placeholder text; absent for non-placeholder runs. Called lazily.
+   * What the run is read against; see {@link TextContext}. Its `inherit.fontRef` is the tier
+   * {@link resolvedColor} and {@link resolvedFontFace} consult just below the run's own `a:rPr`
+   * and above the placeholder and `p:defaultTextStyle` chain.
    */
-  private readonly inheritedColor?;
+  private readonly context;
   /**
-   * Resolves the point size this run inherits from the same chain when it sets no
-   * own `@sz`. Built by the owning {@link Paragraph} for placeholder text; absent
-   * for non-placeholder runs. Called lazily.
+   * What the run inherits when it sets no colour, size, face, bold or italic of its own, or `null`
+   * for text that inherits through nothing. Built by the owning {@link Paragraph} and shared by
+   * its runs; nothing in it is resolved until a run asks.
    */
-  private readonly inheritedSize?;
-  /**
-   * Resolves the typeface this run inherits from the same chain (a `+mj-*`/`+mn-*`
-   * theme token already resolved to a literal face) when it sets no own `a:latin`.
-   * Built by the owning {@link Paragraph} for placeholder text; absent otherwise.
-   * Called lazily.
-   */
-  private readonly inheritedFace?;
-  /**
-   * Resolves whether this run inherits bold from the same chain when it sets no
-   * own `@b`. Built by the owning {@link Paragraph} for placeholder text; absent
-   * for non-placeholder runs. Called lazily.
-   */
-  private readonly inheritedBold?;
-  /**
-   * Resolves whether this run inherits italic from the same chain when it sets no
-   * own `@i`. Built by the owning {@link Paragraph} for placeholder text; absent
-   * for non-placeholder runs. Called lazily.
-   */
-  private readonly inheritedItalic?;
-  /**
-   * The owning part's relationships, used to resolve a run hyperlink's `@r:id`
-   * to its external URL or internal target partname. Absent when the run was
-   * reached without them (e.g. table-cell or notes text), in which case
-   * {@link hyperlink} still reports the raw `@r:id`/`@action`/`@tooltip`.
-   */
-  private readonly relationships?;
-  /**
-   * The owning shape's resolved `p:style/a:fontRef` colour + face tier — the
-   * fallback consulted for {@link resolvedColor}/{@link resolvedFontFace} just
-   * below the run's own `a:rPr` and above the placeholder/`p:defaultTextStyle`
-   * chain. Absent when the shape has no `p:style/a:fontRef`.
-   */
-  private readonly fontRef?;
-  constructor(element: Element, part: Part,
-  /** The owning slide's theme context (colour maps + `fontScheme`), for the `resolved*` getters; absent when the run was reached without one. */
-  themeContext?: ThemeContext | undefined,
-  /**
-   * Resolves the colour this run inherits from its placeholder/list-style chain
-   * when it sets none of its own (item A). Built by the owning {@link Paragraph}
-   * for placeholder text; absent for non-placeholder runs. Called lazily.
-   */
-  inheritedColor?: (() => ResolvedColor | null) | undefined,
-  /**
-   * Resolves the point size this run inherits from the same chain when it sets no
-   * own `@sz`. Built by the owning {@link Paragraph} for placeholder text; absent
-   * for non-placeholder runs. Called lazily.
-   */
-  inheritedSize?: (() => number | null) | undefined,
-  /**
-   * Resolves the typeface this run inherits from the same chain (a `+mj-*`/`+mn-*`
-   * theme token already resolved to a literal face) when it sets no own `a:latin`.
-   * Built by the owning {@link Paragraph} for placeholder text; absent otherwise.
-   * Called lazily.
-   */
-  inheritedFace?: (() => string | null) | undefined,
-  /**
-   * Resolves whether this run inherits bold from the same chain when it sets no
-   * own `@b`. Built by the owning {@link Paragraph} for placeholder text; absent
-   * for non-placeholder runs. Called lazily.
-   */
-  inheritedBold?: (() => boolean | null) | undefined,
-  /**
-   * Resolves whether this run inherits italic from the same chain when it sets no
-   * own `@i`. Built by the owning {@link Paragraph} for placeholder text; absent
-   * for non-placeholder runs. Called lazily.
-   */
-  inheritedItalic?: (() => boolean | null) | undefined,
+  private readonly inherited;
+  constructor(element: Element,
   /**
-   * The owning part's relationships, used to resolve a run hyperlink's `@r:id`
-   * to its external URL or internal target partname. Absent when the run was
-   * reached without them (e.g. table-cell or notes text), in which case
-   * {@link hyperlink} still reports the raw `@r:id`/`@action`/`@tooltip`.
+   * What the run is read against; see {@link TextContext}. Its `inherit.fontRef` is the tier
+   * {@link resolvedColor} and {@link resolvedFontFace} consult just below the run's own `a:rPr`
+   * and above the placeholder and `p:defaultTextStyle` chain.
    */
-  relationships?: Relationships | undefined,
+  context: TextContext,
   /**
-   * The owning shape's resolved `p:style/a:fontRef` colour + face tier — the
-   * fallback consulted for {@link resolvedColor}/{@link resolvedFontFace} just
-   * below the run's own `a:rPr` and above the placeholder/`p:defaultTextStyle`
-   * chain. Absent when the shape has no `p:style/a:fontRef`.
+   * What the run inherits when it sets no colour, size, face, bold or italic of its own, or `null`
+   * for text that inherits through nothing. Built by the owning {@link Paragraph} and shared by
+   * its runs; nothing in it is resolved until a run asks.
    */
-  fontRef?: StyleFontRef | null | undefined);
+  inherited: InheritedRunProps | null);
   /** The run's text (`a:t`), verbatim — whitespace is not normalized. */
   get text(): string;
   set text(value: string);
@@ -876,6 +869,7 @@ declare class Run {
   set italic(value: boolean | null);
   /** Underline style token (`a:rPr/@u`, e.g. `sng`), or `null` when unset. */
   get underline(): string | null;
+  /** @throws {InvalidOptionError} when the token is not an `ST_TextUnderlineType` */
   set underline(value: string | null);
   /**
    * Strikethrough token (`a:rPr/@strike`: `noStrike` | `sngStrike` |
@@ -893,6 +887,9 @@ declare class Run {
    * in 1000ths of a percent): positive for superscript (the writer's default is
    * `30`), negative for subscript (`-40`), or `null` when unset. Reported as the
    * percentage (`@baseline` ÷ 1000).
+   *
+   * `@baseline` is `a:ST_Percentage`, a union that also admits `"62.5%"` — the only form the
+   * Strict profile has — so it is read through `parsePercentPoints` rather than as a bare number.
    */
   get baselinePct(): number | null;
   /**
@@ -903,21 +900,20 @@ declare class Run {
   get charSpacingPt(): number | null;
   /**
    * The run's highlight colour (`a:rPr/a:highlight`), resolved to a literal hex
-   * through the owning slide's theme, or `null` when the run has no highlight
-   * (or a token colour cannot be made literal without a theme context). The
-   * writer authors highlights from a hex colour, so `effectiveHex` is that
-   * colour; imported decks may carry a theme token, resolved here when possible.
+   * through the owning slide's theme, or `null` when the run has no highlight or
+   * its colour cannot be made literal. The writer authors highlights from a hex
+   * colour, so `effectiveHex` is that colour; imported decks may carry a theme token.
    */
   get highlight(): ResolvedColor | null;
   /**
    * The run's click hyperlink (`a:rPr/a:hlinkClick`), or `null` when the run
    * carries none. A URL link resolves its `@r:id` to the external target
-   * ({@link RunHyperlink.url}); a slide jump resolves it to the linked slide's
-   * partname ({@link RunHyperlink.targetPartName}). When the run was reached
-   * without the owning part's relationships, only the raw `@r:id`/`@action`/
-   * `@tooltip` are reported (the target stays `null`).
+   * ({@link Hyperlink.url}); a slide jump resolves it to the linked slide's
+   * partname ({@link Hyperlink.targetPartName}). When the run is read without
+   * its part's relationships (see {@link TextContext.rels}), only the raw
+   * `@r:id`/`@action`/`@tooltip` are reported (the target stays `null`).
    */
-  get hyperlink(): RunHyperlink | null;
+  get hyperlink(): Hyperlink | null;
   /** Latin typeface name (`a:rPr/a:latin/@typeface`), or `null` when unset. */
   get fontName(): string | null;
   set fontName(value: string | null);
@@ -926,6 +922,7 @@ declare class Run {
   set color(value: string | null);
   /** Theme colour token when the fill is a scheme colour (`a:schemeClr/@val`, e.g. `accent2`), or `null`. */
   get schemeColor(): string | null;
+  /** @throws {InvalidOptionError} when the token is not an `ST_SchemeColorVal` */
   set schemeColor(value: string | null);
   /**
    * The colour this run effectively renders, resolved against the owning slide's
@@ -934,8 +931,11 @@ declare class Run {
    * `p:style/a:fontRef` colour, then — for a run inside a placeholder — the colour
    * it inherits from the placeholder/list-style chain (layout → master placeholder
    * `a:lstStyle` → master `p:txStyles`), then the presentation's
-   * `p:defaultTextStyle`. `null` when the run sets no colour and inherits none, the
-   * colour cannot be made literal, or the run was reached without a theme context.
+   * `p:defaultTextStyle`. `null` when the run sets no colour and inherits none, or the
+   * colour cannot be made literal.
+   * `null` too when the run's own fill is not a solid colour (`a:noFill`, a gradient):
+   * the run decides its own colour then, and the one it would otherwise inherit is not
+   * what it paints in, the rule `Shape.resolvedFill` and `TableCell.resolvedFill` follow.
    * The returned {@link ResolvedColor} carries `effectiveHex` — the base colour with
    * its child transforms (`lumMod`/`shade`/…) applied — for the final rendered colour.
    */
@@ -986,37 +986,27 @@ declare class Run {
   /** Mark the owning part dirty so `save()` reserializes it. Call after mutating {@link element_}. */
   markDirty(): void;
 }
+//#endregion
+//#region src/read/api/text/paragraph.d.ts
 /** One paragraph (`a:p`) of a text frame. */
 declare class Paragraph {
   #private;
   private readonly element;
-  private readonly part;
-  /** The owning slide's theme context (colour maps + `fontScheme`), threaded to each {@link Run} for the `resolved*` getters. */
-  private readonly themeContext?;
-  /**
-   * Placeholder + slide-list-style context for resolving a placeholder-inherited
-   * run colour/size/face; absent for non-placeholder text. The owning
-   * {@link TextFrame} supplies the placeholder identity and the text body's
-   * `a:lstStyle`.
-   */
-  private readonly inherit?;
-  /** The owning part's relationships, threaded to each {@link Run} for hyperlink `@r:id` resolution; absent when reached without them. */
-  private readonly relationships?;
-  constructor(element: Element, part: Part,
-  /** The owning slide's theme context (colour maps + `fontScheme`), threaded to each {@link Run} for the `resolved*` getters. */
-  themeContext?: ThemeContext | undefined,
-  /**
-   * Placeholder + slide-list-style context for resolving a placeholder-inherited
-   * run colour/size/face; absent for non-placeholder text. The owning
-   * {@link TextFrame} supplies the placeholder identity and the text body's
-   * `a:lstStyle`.
-   */
-  inherit?: {
-    placeholder: PlaceholderTextContext;
-    slideLstStyle: Element | null;
-  } | undefined,
-  /** The owning part's relationships, threaded to each {@link Run} for hyperlink `@r:id` resolution; absent when reached without them. */
-  relationships?: Relationships | undefined);
+  /** What the paragraph is read against; see {@link TextContext}. */
+  private readonly context;
+  /**
+   * The owning text body's own `a:lstStyle`, the tier just below the paragraph in the chain its
+   * runs inherit through. Read only when {@link TextContext.inherit} is set.
+   */
+  private readonly slideLstStyle;
+  constructor(element: Element,
+  /** What the paragraph is read against; see {@link TextContext}. */
+  context: TextContext,
+  /**
+   * The owning text body's own `a:lstStyle`, the tier just below the paragraph in the chain its
+   * runs inherit through. Read only when {@link TextContext.inherit} is set.
+   */
+  slideLstStyle: Element | null);
   /** The runs (`a:r`) in document order. Fields (`a:fld`) and breaks are not runs; see `text`. */
   get runs(): Run[];
   /** Indent level (`a:pPr/@lvl`), 0 when unset. */
@@ -1075,6 +1065,8 @@ declare class Paragraph {
   markDirty(): void;
 }
 /** A shape's text frame (`p:txBody`): an ordered list of paragraphs. */
+//#endregion
+//#region src/read/api/text/frame.d.ts
 /**
  * A text frame's body properties (`a:bodyPr`), as read from a shape. Carries the
  * inset/anchor/vertical-text settings that govern where text sits inside its box
@@ -1108,28 +1100,17 @@ type AutofitMode = 'none' | 'normAutofit' | 'spAutoFit';
 declare class TextFrame {
   #private;
   private readonly txBody;
-  private readonly part;
-  /** The owning slide's theme context (colour maps + `fontScheme`), threaded to each {@link Paragraph}/{@link Run} for the `resolved*` getters. */
-  private readonly themeContext?;
-  /**
-   * The placeholder this text body lives in, when any — enables
-   * placeholder-inherited run colour/size/face resolution. Absent for ordinary
-   * text boxes and table cells.
-   */
-  private readonly placeholder?;
-  /** The owning part's relationships, threaded to each {@link Paragraph}/{@link Run} for hyperlink `@r:id` resolution; absent when reached without them. */
-  private readonly relationships?;
-  constructor(txBody: Element, part: Part,
-  /** The owning slide's theme context (colour maps + `fontScheme`), threaded to each {@link Paragraph}/{@link Run} for the `resolved*` getters. */
-  themeContext?: ThemeContext | undefined,
-  /**
-   * The placeholder this text body lives in, when any — enables
-   * placeholder-inherited run colour/size/face resolution. Absent for ordinary
-   * text boxes and table cells.
-   */
-  placeholder?: PlaceholderTextContext | undefined,
-  /** The owning part's relationships, threaded to each {@link Paragraph}/{@link Run} for hyperlink `@r:id` resolution; absent when reached without them. */
-  relationships?: Relationships | undefined);
+  /**
+   * What the frame is read against — its part, the theme, the part's relationships and the
+   * inheritance its runs fall back through — handed on to each {@link Paragraph} and {@link Run}.
+   */
+  private readonly context;
+  constructor(txBody: Element,
+  /**
+   * What the frame is read against — its part, the theme, the part's relationships and the
+   * inheritance its runs fall back through — handed on to each {@link Paragraph} and {@link Run}.
+   */
+  context: TextContext);
   /** Paragraphs (`a:p`) in document order. */
   get paragraphs(): Paragraph[];
   /**
@@ -1186,7 +1167,7 @@ declare class TextFrame {
 }
 //#endregion
 //#region src/read/api/shapes/host.d.ts
-/** The part-level surface a {@link import('./base.js').Shape} resolves against. */
+/** The part-level surface a {@link Shape} resolves against. */
 interface ShapeHost {
   /** The OPC part holding the shape tree (`p:sld` / `p:sldLayout` / `p:sldMaster`). */
   readonly part: Part;
@@ -1242,6 +1223,19 @@ declare abstract class Shape {
   get id(): number | null;
   /** Shape name (`p:cNvPr/@name`), or `''` if unnamed. */
   get name(): string;
+  /**
+   * The shape's own click hyperlink (`p:cNvPr/a:hlinkClick`), or `null` when it carries none.
+   *
+   * This is the link PowerPoint's Insert > Link puts on a whole shape, as opposed to the one a
+   * {@link Run} carries on a span of text. It is the same element, read the same way, and it had
+   * no reader at all -- so a linked shape read back as an ordinary one and a replica lost the
+   * link with nothing to say so. `addShape`, `addText` and `addImage` all take `hyperlink`.
+   *
+   * A URL link resolves its `@r:id` to the external target; a slide jump resolves it to the
+   * linked slide's partname and reports `ppaction://hlinksldjump` as its `action`. An
+   * action-only link (a slide-show navigation button) has no `@r:id` and resolves to neither.
+   */
+  get hyperlink(): Hyperlink | null;
   /**
    * Whether the shape is explicitly hidden (`p:cNvPr/@hidden="1"`); `false` when
    * the attribute is unset. A hidden shape stays in the slide XML but is not
@@ -1345,21 +1339,39 @@ declare abstract class Shape {
    *
    * `null` when the shape (or any enclosing group) has no own transform, or a
    * group's `a:chExt` is degenerate (zero) — there is then no resolvable frame.
+   * {@link absoluteFrameFailure} says which of those it was.
    *
    * A rotated shape's returned `left`/`top` remain PowerPoint's unrotated
    * placement box (the same box PowerPoint writes after Ungroup), with the
    * effective rotation exposed separately.
    */
   get absoluteFrame(): AbsoluteFrame | null;
+  /**
+   * Why {@link absoluteFrame} is `null`, or `null` when it resolved.
+   *
+   * `absoluteFrame` reports one `null` for three different situations, and only a
+   * caller that wants to *report* the unresolvable shape needs them apart — an
+   * inherited placeholder box is ordinary, a group with no usable `a:xfrm` is not.
+   * The distinction is not recoverable from the `null`, and re-deriving it means
+   * walking the same ancestry a second time, so it is named here instead. See
+   * {@link AbsoluteFrameFailure} for what each value means.
+   */
+  get absoluteFrameFailure(): AbsoluteFrameFailure | null;
   /** The shape's properties element (`p:spPr` / `p:grpSpPr`), or `null` when absent. */
   protected properties(): Element | null;
-  /** Get-or-add the properties element in document order, with the successor
-   *  arrays for inserting its fill / line children. Subclasses override this
-   *  to point at `p:grpSpPr`, or to reject kinds with no properties element. */
-  protected getOrAddProperties(): ShapeProperties;
-  /** Whether a solid fill can be set on this shape kind. Pictures and graphic
-   *  frames opt out (they carry their own image / table-cell fill model). */
-  protected get supportsFill(): boolean;
+  /**
+   * Where this kind's paint is written, and which paints it can carry: its properties element,
+   * and for each paint the successors that paint's element goes before, or `null` for a paint
+   * the kind cannot carry. `null` for a kind with no properties element at all.
+   *
+   * The one capability a kind declares about paint, checked in one place. Setting a fill (a
+   * colour, a theme token, {@link noFill}) on a kind that cannot carry one throws
+   * `shape/fill-unsupported`, and setting a line colour throws `shape/line-unsupported`.
+   * Clearing never throws: a kind that cannot be *given* a paint may still hold one a deck wrote,
+   * so clearing removes whatever of that paint the element has, and changes nothing when it has
+   * none.
+   */
+  protected paintSurface(): PaintSurface | null;
   /** Explicit RGB fill colour as a 6-hex string (`spPr/a:solidFill/a:srgbClr/@val`), or `null`. */
   get fillColor(): string | null;
   set fillColor(value: string | null);
@@ -1436,6 +1448,19 @@ declare abstract class Shape {
    * this kind carries. A group has no geometry of its own and reads `null`.
    */
   get presetGeometry(): string | null;
+  /**
+   * Custom freeform geometry (`spPr/a:custGeom/a:pathLst`), or `null` when the
+   * shape uses preset geometry / none. The faithful, multi-path counterpart of
+   * {@link presetGeometry}: each `a:path` keeps its own path-unit viewport
+   * (`w`/`h`) and ordered {@link GeometryCommand}s. Coordinates are raw path-unit
+   * integers, not EMU — pair the path `w`/`h` with the shape's box size to map
+   * them into slide space.
+   *
+   * Not an auto-shape-only property either: a picture clipped to a freeform (what
+   * PowerPoint writes when Merge Shapes intersects a picture with a shape, and what
+   * `addImage({ points })` writes) carries its clip here. A group reads `null`.
+   */
+  get customGeometry(): CustomGeometry | null;
   /**
    * Preset-geometry adjustment values (`spPr/a:prstGeom/a:avLst/a:gd`) as a
    * name → formula map, e.g. `{ adj: 'val 16667' }`. Empty when the shape has no
@@ -1489,8 +1514,8 @@ declare abstract class Shape {
   get innerShadow(): InnerShadow | null;
   /**
    * The shape's glow halo (`spPr/a:effectLst/a:glow`), resolved against the host's
-   * theme, or `null` when the shape has no glow. Same element the write-side text
-   * glow emits, so its {@link Glow.radiusPt} and colour round-trip.
+   * theme, or `null` when the shape has no glow. The write-side `glow` option is a
+   * text glow in run properties, so it does not read back here.
    */
   get glow(): Glow | null;
   /**
@@ -1544,8 +1569,11 @@ declare abstract class Shape {
    * Like {@link resolvedFill}, the result carries `effectiveHex` (the base colour
    * with its transforms applied) for the final rendered colour.
    *
-   * When the shape carries no explicit `spPr/a:ln`, this falls back to the line
-   * the shape inherits from its `p:style` `a:lnRef` (the theme style matrix).
+   * When the shape's `spPr/a:ln` states no fill of its own, this falls back to the line
+   * colour the shape inherits from its `p:style` `a:lnRef` (the theme style matrix). An
+   * `a:ln` without a fill is not a replacement: PowerPoint layers it over the style line one
+   * property at a time, and changing only an outline's weight writes `<a:ln w="76200"/>`
+   * and paints the style colour (`test/read/fixtures/shape-line-style-override.pptx`).
    */
   get resolvedLine(): ResolvedColor | null;
   /** Whether this shape can hold text (only `p:sp` does in this read model). */
@@ -1570,6 +1598,10 @@ declare abstract class Shape {
   /**
    * Remove this shape from its parent (the host's shape tree, or an enclosing
    * group) and mark the owning host's part dirty. The proxy is dead afterwards.
+   *
+   * The build animations targeting the shape, or any shape inside a deleted group, go with it,
+   * and a connector attached to one of them keeps its geometry with that end unbound. PowerPoint
+   * refuses a deck whose animation names a shape that is not on the slide.
    */
   delete(): void;
   /** Escape hatch: the underlying shape element. After mutating it call {@link markDirty}, or `save()` writes the original bytes. */
@@ -1588,15 +1620,6 @@ declare class AutoShape extends Shape {
    * PowerPoint does. Use {@link Slide.placeholder} to find a placeholder by type.
    */
   get placeholder(): PlaceholderRef | null;
-  /**
-   * Custom freeform geometry (`spPr/a:custGeom/a:pathLst`), or `null` when the
-   * shape uses preset geometry / none. The faithful, multi-path counterpart of
-   * {@link presetGeometry}: each `a:path` keeps its own path-unit viewport
-   * (`w`/`h`) and ordered {@link GeometryCommand}s. Coordinates are raw path-unit
-   * integers, not EMU — pair the path `w`/`h` with the shape's box size to map
-   * them into slide space.
-   */
-  get customGeometry(): CustomGeometry | null;
 }
 //#endregion
 //#region src/read/api/shapes/picture.d.ts
@@ -1604,7 +1627,7 @@ declare class AutoShape extends Shape {
 declare class Picture extends Shape {
   #private;
   readonly shapeType: 'picture';
-  protected get supportsFill(): boolean;
+  protected paintSurface(): PaintSurface | null;
   /** Relationship id of the embedded image (`p:blipFill/a:blip/@r:embed`), or `null`. */
   get imageRelId(): string | null;
   /**
@@ -1613,7 +1636,13 @@ declare class Picture extends Shape {
    * the id exists and targets an image; use {@link setImage} to add fresh bytes.
    */
   set imageRelId(value: string);
-  /** Absolute partname of the embedded image, resolved via the owning part's relationships, or `null`. */
+  /**
+   * Absolute partname of the embedded image, resolved via the owning part's relationships.
+   *
+   * `null` covers every way there is nothing to name: no `r:embed`, an id the part does not
+   * declare, or a relationship whose target is external (a LINKED image). It used to throw on
+   * the last two while the same blip reached through a picture fill returned `null`.
+   */
   get imagePartName(): string | null;
   /**
    * Relationship id of the embedded **vector (SVG)** image, read from the
@@ -1624,7 +1653,7 @@ declare class Picture extends Shape {
    * so a reader that wants the real drawn art must consult both.
    */
   get svgRelId(): string | null;
-  /** Absolute partname of the embedded SVG image, resolved via the owning part's relationships, or `null`. */
+  /** Absolute partname of the embedded SVG image, or `null`. Same rule as {@link imagePartName}. */
   get svgPartName(): string | null;
   /**
    * Which drawable media this picture carries:
@@ -1658,12 +1687,7 @@ declare class Picture extends Shape {
    * match the fraction convention used elsewhere in the read API (see
    * {@link recolor}).
    */
-  get crop(): {
-    left: number;
-    top: number;
-    right: number;
-    bottom: number;
-  } | null;
+  get crop(): FillRect | null;
   /**
    * The picture's blip recolour effect (`p:blipFill/a:blip` recolour child), or
    * `null` when the blip carries none. Recognises the effects a faithful reader
@@ -1743,7 +1767,7 @@ interface ChartLegend {
   /** Whether the legend overlays the plot area (`c:overlay/@val`). */
   overlay: boolean | null;
 }
-/** A chart's data-label settings (`c:dLbls`), read from the first plot group. */
+/** Data-label settings (`c:dLbls`), read from a plot group or from one series. */
 interface ChartDataLabels {
   /** Show the point value (`c:showVal`). */
   showValue: boolean | null;
@@ -1766,10 +1790,11 @@ interface ChartDataLabels {
 }
 /** A series' solid fill (`c:ser/c:spPr`). */
 interface ChartFill {
-  /** Literal fill colour (`a:srgbClr/@val`), or `null` for a scheme/no fill. */
-  color: string | null;
-  /** Raw scheme-colour token (`a:schemeClr/@val`), unresolved. */
-  schemeColor: string | null;
+  /**
+   * The fill's solid colour; every field is `null` for a non-solid fill. A chart part is read
+   * without a theme, so `resolved` is always `null` and a scheme colour stays a token.
+   */
+  colorRef: ColorRef;
   /** Whether the fill is explicitly suppressed (`a:noFill`). */
   noFill: boolean;
 }
@@ -1779,10 +1804,8 @@ interface ChartLine {
   widthPt: number | null;
   /** Dash style (`a:prstDash/@val`), or `null` when solid/unset. */
   dash: string | null;
-  /** Literal stroke colour (`a:srgbClr/@val`), or `null`. */
-  color: string | null;
-  /** Raw scheme-colour token (`a:schemeClr/@val`), unresolved. */
-  schemeColor: string | null;
+  /** The stroke's solid colour; unresolved, as {@link ChartFill.colorRef} is. */
+  colorRef: ColorRef;
   /** Whether the line is explicitly suppressed (`a:noFill`). */
   noFill: boolean;
 }
@@ -1820,7 +1843,12 @@ declare class Chart {
   /**
    * The chart-level data-label settings, read from the first plot group's
    * aggregate `c:dLbls` (the group-wide block after the series). `null` when the
-   * plot group carries no data-label block (e.g. pie via a different builder).
+   * plot group carries no data-label block.
+   *
+   * A pie keeps its labels on the series instead: PowerPoint writes the flags the
+   * user set into `c:ser/c:dLbls` and leaves this block all off, and this library's
+   * writer emits no group block for a pie at all. Read those through
+   * {@link ChartSeries.dataLabels}.
    */
   get dataLabels(): ChartDataLabels | null;
   /** The data series (`c:ser`) across all chart groups, in document order. */
@@ -1830,6 +1858,8 @@ declare class Chart {
    * (`c:cat`), as written. Empty when the chart has no category axis.
    */
   get categories(): (string | null)[];
+  /** Every category level of the first series, leaf first; see {@link ChartSeries.categoryLevels}. */
+  get categoryLevels(): (string | null)[][];
   /** Escape hatch: the underlying `c:chartSpace` element. After mutating it call {@link markDirty}, or `save()` writes the original bytes. */
   get element_(): Element | null;
   /** Mark the chart part dirty so `save()` reserializes it. Call after mutating {@link element_}. */
@@ -1889,6 +1919,7 @@ declare class ChartAxis {
 }
 /** One data series (`c:ser`) of a chart. */
 declare class ChartSeries {
+  #private;
   private readonly ser;
   /** The owning chart's OPC part, so {@link markDirty} can reach it from {@link element_}. */
   private readonly part;
@@ -1909,10 +1940,49 @@ declare class ChartSeries {
   get index(): number | null;
   /** Series name from the cached `c:tx`, or `null` when unnamed. */
   get name(): string | null;
-  /** Cached numeric values (`c:val`); non-numeric or missing points are `null`. */
+  /**
+   * Cached numeric values (`c:val`); non-numeric or missing points are `null`. Empty on a
+   * scatter or bubble series, which caches its values as {@link yValues} instead.
+   */
   get values(): (number | null)[];
-  /** Cached category labels for this series (`c:cat`), as written. */
+  /**
+   * Cached X values of a scatter or bubble series (`c:xVal`); missing points are `null`.
+   * A series plotted against text X labels reads `null` at every point, a label that looks like a
+   * number included: {@link xLabels} has the text. A series with no `c:xVal` reads `[]`, and
+   * PowerPoint plots it at X = 1, 2, … n, as it does a series plotted against text.
+   */
+  get xValues(): (number | null)[];
+  /**
+   * The X labels of a series plotted against text (`c:xVal` holding a string cache rather than
+   * numbers), as written, or `null` when its X values are numbers or absent.
+   *
+   * One text cell makes the whole X column a string cache, so the numbers in it arrive as text too.
+   * PowerPoint then plots the points at X = 1, 2, … n in point order and uses none of the labels
+   * as a coordinate, not even one that reads as a number.
+   */
+  get xLabels(): (string | null)[] | null;
+  /** Cached Y values of a scatter or bubble series (`c:yVal`); non-numeric or missing points are `null`. */
+  get yValues(): (number | null)[];
+  /** Cached bubble sizes of a bubble series (`c:bubbleSize`); non-numeric or missing points are `null`. */
+  get bubbleSizes(): (number | null)[];
+  /**
+   * Cached category labels for this series (`c:cat`), as written. On a multi-level axis this
+   * is the leaf level, the labels next to the plot; {@link categoryLevels} has the rest.
+   */
   get categories(): (string | null)[];
+  /**
+   * Every level of cached category labels (`c:cat`), leaf first: the order PowerPoint writes the
+   * `c:multiLvlStrCache/c:lvl` children in, and the order `OptsChartData.labels` takes them.
+   * Each level is as long as the leaf level. An outer level names a group once, at the group's
+   * first category, so the other slots of that group are `null`. A single-level axis reads as
+   * one level, and a series with no categories as none.
+   */
+  get categoryLevels(): (string | null)[][];
+  /**
+   * The data-label settings this series carries itself (`c:ser/c:dLbls`), or `null` when it has
+   * none. This is where a pie's labels are: see {@link Chart.dataLabels}.
+   */
+  get dataLabels(): ChartDataLabels | null;
   /** Escape hatch: the underlying `c:ser` element. After mutating it call {@link markDirty}, or `save()` writes the original bytes. */
   get element_(): Element;
   /** Mark the owning chart part dirty so `save()` reserializes it. Call after mutating {@link element_}. */
@@ -2132,8 +2202,22 @@ interface DiagramDrawnShape {
 declare class DrawingIndex {
   #private;
   private readonly drawingPart;
-  private readonly themeContext?;
-  constructor(root: Element | null, drawingPart: Part | null, themeContext?: ThemeContext | undefined);
+  private readonly themeContext;
+  /**
+   * The drawing part's own relationships, so a hyperlink in the cached text resolves to a url
+   * rather than reporting a raw `@r:id`. It used to be read without them, so the same run
+   * answered differently depending on which of the two paths reached it: through the point's
+   * own `textFrame` it resolved, through `drawnShape.textFrame` it did not.
+   */
+  private readonly drawingRelationships;
+  constructor(root: Element | null, drawingPart: Part | null, themeContext: ThemeContext,
+  /**
+   * The drawing part's own relationships, so a hyperlink in the cached text resolves to a url
+   * rather than reporting a raw `@r:id`. It used to be read without them, so the same run
+   * answered differently depending on which of the two paths reached it: through the point's
+   * own `textFrame` it resolved, through `drawnShape.textFrame` it did not.
+   */
+  drawingRelationships: Relationships | null);
   /**
    * Resolve one authored point to the `pres` point that presents it and to the drawn
    * paragraph carrying its text.
@@ -2156,13 +2240,13 @@ declare class DiagramPoint {
   private readonly pt;
   /** The diagram data part, so a text edit marks the right part dirty. */
   private readonly part;
-  private readonly themeContext?;
-  private readonly relationships?;
+  private readonly themeContext;
+  private readonly relationships;
   /** The owning diagram's drawing index, built on first use; absent when reached without one. */
   private readonly drawing?;
   constructor(pt: Element,
   /** The diagram data part, so a text edit marks the right part dirty. */
-  part: Part, themeContext?: ThemeContext | undefined, relationships?: Relationships | undefined,
+  part: Part, themeContext: ThemeContext, relationships: Relationships,
   /** The owning diagram's drawing index, built on first use; absent when reached without one. */
   drawing?: (() => DrawingIndex) | undefined);
   /** This point's id (`@modelId`), which connections reference. */
@@ -2277,14 +2361,14 @@ declare class Diagram {
   private readonly opc;
   /** Relationships of the part holding the frame — what `dgm:relIds` resolves against. */
   private readonly frameRelationships;
-  private readonly themeContext?;
+  private readonly themeContext;
   constructor(
   /** The diagram's data part (`/ppt/diagrams/data{N}.xml`), whose root is `dgm:dataModel`. */
   part: Part,
   /** The frame's `dgm:relIds`, which names the other three parts by relationship id. */
   relIds: Element, opc: OpcPackage,
   /** Relationships of the part holding the frame — what `dgm:relIds` resolves against. */
-  frameRelationships: Relationships, themeContext?: ThemeContext | undefined);
+  frameRelationships: Relationships, themeContext: ThemeContext);
   /** Partname of the diagram data part. */
   get partName(): string;
   /**
@@ -2292,7 +2376,7 @@ declare class Diagram {
    * points and the `doc` root included. Filter on {@link DiagramPoint.type} for the user's
    * nodes; {@link text} is the shortcut for the common case, {@link nodes} the structured one.
    *
-   * Built per access like every other read proxy (`docs/reference/pptx-read.md`, "Object
+   * Built per access like every other read proxy (`docs/reference/read-object-model.md`, "Object
    * model"), so `points[0] !== points[0]` while both wrap the same `dgm:pt`. Key a `Map`
    * on {@link DiagramPoint.modelId}, not on the point.
    */
@@ -2369,38 +2453,7 @@ declare const EDGE_QNAMES: {
 /** Which border of a cell an edit addresses. */
 type TableCellEdge = keyof typeof EDGE_QNAMES;
 //#endregion
-//#region src/read/api/table-style-resolve.d.ts
-/**
- * The `a:tblPr` condition flags that gate which style parts apply to a table.
- * `firstRow`/`bandRow` are the ones PowerPoint turns on by default; the rest are
- * off unless the author enabled the corresponding "Header Column" / "Total Row" /
- * "Banded Columns" toggle.
- */
-interface TableConditionFlags {
-  firstRow: boolean;
-  lastRow: boolean;
-  firstCol: boolean;
-  lastCol: boolean;
-  bandRow: boolean;
-  bandCol: boolean;
-}
-/** A table's resolved entry in `tableStyles.xml`: its GUID, display name, and raw element. */
-interface ResolvedTableStyle {
-  /** The matched `@styleId` GUID (e.g. `{5C22544A-…}`). */
-  styleId: string;
-  /** The style's display name (`@styleName`, e.g. `Medium Style 2 - Accent 1`), or `null`. */
-  name: string | null;
-  /** Escape hatch: the underlying `a:tblStyle` element. After mutating it call {@link ResolvedTableStyle.markDirty}, or `save()` writes the original bytes. */
-  element_: Element;
-  /**
-   * Mark `tableStyles.xml` dirty so `save()` reserializes it. Call after mutating
-   * {@link ResolvedTableStyle.element_}. Note the part is deck-wide: an edit here
-   * reaches every table bound to this style.
-   */
-  markDirty(): void;
-}
-//#endregion
-//#region src/read/api/table.d.ts
+//#region src/read/api/table-cell.d.ts
 /**
  * One border as {@link TableCell.setBorder} takes it — the write-side mirror of
  * {@link CellBorder}, which is what reading one gives back.
@@ -2437,9 +2490,8 @@ interface TableCellStyleContext {
 /**
  * One edge border of a table cell (`a:tcPr/a:lnL|lnR|lnT|lnB|lnTlToBr|lnBlToTr`).
  * Mirrors the `a:ln`-style decode used for shape strokes: {@link widthPt} from
- * `@w` (EMU → points), {@link dash} from `a:prstDash/@val`, and the stroke colour
- * split into a resolved {@link color} (literal hex) and the raw {@link schemeColor}
- * token — the cell-border counterpart of a shape's line accessors.
+ * `@w` (EMU → points), {@link dash} from `a:prstDash/@val`, and the stroke colour as a
+ * {@link ColorRef} — the cell-border counterpart of a shape's line accessors.
  */
 interface CellBorder {
   /** Border width in points (`@w` is EMU; 12700 EMU = 1pt), or `null` when unset. */
@@ -2447,28 +2499,12 @@ interface CellBorder {
   /** Dash style (`a:prstDash/@val`, e.g. `solid`/`sysDash`), or `null` when unset. */
   dash: string | null;
   /**
-   * The stroke colour as a full {@link ResolvedColor} — base `hex`, the raw
-   * `transforms` list (`lumMod`/`shade`/…) in document order, and the
-   * `effectiveHex`/`alpha` after applying them — the same object a shape's
-   * `resolvedLine` gives. `null` when the edge carries no solid fill, or the
-   * colour cannot be made literal.
-   *
-   * This is the field to read when re-authoring a border against a *different*
-   * theme: {@link color} alone is one theme baked in, so a `lumMod`-darkened
-   * accent carried forward as a literal hex silently stops tracking the theme it
-   * came from. `transforms` is what says whether there was anything to track, and
-   * an empty list here means the edge stated none — not that the reader could not
-   * see them.
-   */
-  resolvedColor: ResolvedColor | null;
-  /**
-   * The stroke colour resolved against the table theme to a literal hex — exactly
-   * `resolvedColor?.effectiveHex ?? null`, kept as a flat field because painting a
-   * rule is what most callers want. `null` when the edge has no resolvable colour.
+   * The stroke's solid colour, as written and resolved against the slide theme; every field is
+   * `null` when the edge carries no solid fill. `resolved.effectiveHex` is what a renderer paints,
+   * and `resolved.transforms` is what to carry when re-authoring a border against a different
+   * theme: a `lumMod`-darkened accent carried forward as a literal hex stops tracking its theme.
    */
-  color: string | null;
-  /** Raw `schemeClr` token of the stroke (`a:solidFill/a:schemeClr/@val`), or `null` for an srgb/absent colour. */
-  schemeColor: string | null;
+  colorRef: ColorRef;
   /** `true` when the edge is an explicit no-border (`a:noFill`) — a deliberately suppressed side. */
   noFill: boolean;
 }
@@ -2509,216 +2545,43 @@ interface CellThreeD {
     dir: string | null;
   } | null;
 }
-/** A table: a grid of rows and cells inside a graphic frame. */
-declare class Table {
-  #private;
-  private readonly tbl;
-  private readonly part;
-  /** The owning slide's theme colour context, threaded to each cell's text for `Run.resolvedColor`. */
-  private readonly themeColors?;
-  /** The deck package, for resolving `a:tableStyleId` against `tableStyles.xml` (style-graph cell fills). */
-  private readonly opc?;
-  /** The owning slide's relationships, for resolving a cell picture fill's `r:embed` to a partname. */
-  private readonly rels?;
-  constructor(tbl: Element, part: Part,
-  /** The owning slide's theme colour context, threaded to each cell's text for `Run.resolvedColor`. */
-  themeColors?: ThemeContext | undefined,
-  /** The deck package, for resolving `a:tableStyleId` against `tableStyles.xml` (style-graph cell fills). */
-  opc?: OpcPackage | undefined,
-  /** The owning slide's relationships, for resolving a cell picture fill's `r:embed` to a partname. */
-  rels?: Relationships | undefined);
-  /** The table's rows (`a:tr`) in document (top-to-bottom) order. */
-  get rows(): TableRow[];
-  /**
-   * The table's style graph entry (`styleId`, `name`, raw `a:tblStyle`) resolved
-   * from the deck's `tableStyles.xml`, or `null` when the table names no
-   * `a:tableStyleId`, the deck has no `tableStyles.xml`, or the id is a built-in
-   * `[MS-OE376]` style the deck does not materialise. This is what supplies the
-   * banded-row / header shading a cell with no own fill inherits — read the
-   * resolved per-cell colour off {@link TableCell.resolvedFill}.
-   */
-  get resolvedStyle(): ResolvedTableStyle | null;
-  /** Number of rows (`a:tr`). */
-  get rowCount(): number;
-  /** Number of grid columns (`a:tblGrid/a:gridCol`). */
-  get columnCount(): number;
-  /** Column widths in EMU (`a:gridCol/@w`), one per grid column. */
-  get columnWidths(): (number | null)[];
-  /**
-   * The table's style GUID (`a:tblPr/a:tableStyleId` text), e.g.
-   * `{5940675A-B579-460E-94D1-54222C63F5DA}`, or `null` when the table carries no
-   * `a:tableStyleId`. This is the reference into `ppt/tableStyles.xml` (or a
-   * built-in `[MS-OE376]` style) that supplies the banded-row / header shading the
-   * `firstRow`/`bandRow` flags activate — without it a replica loses the whole
-   * table style, so it is the read counterpart of the writer's `tableStyle` option.
-   */
-  get styleId(): string | null;
-  /**
-   * The table's own background (`a:tblPr` fill) resolved against the slide's theme colour
-   * context to a literal hex, or `null` when the table carries no solid background.
-   *
-   * This is the table-level counterpart of {@link TableCell.resolvedFill}, and it is a
-   * genuinely different thing from a cell fill: a `a:tblPr` fill sits *behind* the grid, so
-   * a cell with no fill of its own shows it through. Reports `null` for a non-solid choice
-   * (`a:blipFill`/`a:gradFill`/`a:pattFill`/`a:noFill`) — read {@link pictureFill} for an
-   * image background — and `null` with no theme context.
-   */
-  get resolvedFill(): ResolvedColor | null;
-  /**
-   * The table's picture background (`a:tblPr/a:blipFill`), or `null` when the table is not
-   * image-backed. The table-level twin of {@link TableCell.pictureFill}, and needed for the
-   * same reason: {@link resolvedFill} decodes only solid colours, so without this an
-   * image-backed table is indistinguishable from an unfilled one.
-   */
-  get pictureFill(): PictureFill | null;
-  /**
-   * The table's gradient background (`a:tblPr/a:gradFill`), or `null` when it is not
-   * gradient-filled. Needed for the same reason {@link pictureFill} is:
-   * {@link resolvedFill} decodes only solid colours.
-   */
-  get gradientFill(): GradientFill | null;
-  /**
-   * The table's pattern (hatch) background (`a:tblPr/a:pattFill`), or `null` when it is not
-   * pattern-filled.
-   */
-  get patternFill(): PatternFill | null;
-  /**
-   * The raw `schemeClr` token of the table's own background
-   * (`a:tblPr/a:solidFill/a:schemeClr/@val`), or `null` for an absent or `srgbClr` fill.
-   * {@link resolvedFill} is the literal it resolves to; this is the unresolved reference,
-   * which is what a replica should carry so the copy still tracks its theme.
-   */
-  get fillSchemeColor(): string | null;
-  /** Whether the first row is styled as a header (`a:tblPr/@firstRow`). */
-  get firstRowHeader(): boolean;
-  /** Whether rows are banded (`a:tblPr/@bandRow`). */
-  get bandedRows(): boolean;
-  /**
-   * The cell at `(rowIndex, columnIndex)` (both zero-based), or `null` when out
-   * of range. Column index counts `a:tc` elements in the row, so a cell that
-   * spans columns (`gridSpan`) occupies a single index here.
-   */
-  cell(rowIndex: number, columnIndex: number): TableCell | null;
-  /**
-   * Insert a row, defaulting to the bottom of the table. Returns the new {@link TableRow}.
-   *
-   * The new row is auto-height (`a:tr/@h="0"`) and its cells are empty. Inserting *through*
-   * a vertical merge extends that merge rather than interrupting it: the span's origin
-   * grows by a row and the new cell joins as a continuation, because an origin claiming
-   * more rows than it has continuations is a table PowerPoint reports as corrupt.
-   * @param {number} [index] - where to insert, `0`..`rowCount`; appended when omitted
-   * @throws {InvalidOptionError} when `index` is outside that range
-   */
-  addRow(index?: number): TableRow;
-  /**
-   * Remove the row at `index`, with its content.
-   *
-   * A cell in the row that *continues* a vertical merge shortens that merge. A cell that
-   * *starts* one hands the region to its first continuation, which becomes the new origin —
-   * the merged region survives one row shorter, and only the removed row's own text is lost.
-   * @throws {InvalidOptionError} when `index` is out of range
-   */
-  removeRow(index: number): void;
-  /**
-   * Insert a column, defaulting to the right-hand end. Updates `a:tblGrid` **and** every
-   * row, which is the pair that has to stay in step.
-   *
-   * The mirror of {@link addRow}'s merge case: inserting inside a horizontal merge widens
-   * it instead of splitting it.
-   * @param {number} [index] - where to insert, `0`..`columnCount`; appended when omitted
-   * @param {number} [widthEmu] - the new column's width; defaults to 1 inch
-   * @throws {InvalidOptionError} when `index` is outside that range
-   */
-  addColumn(index?: number, widthEmu?: number): void;
-  /**
-   * Remove the column at `index`, from `a:tblGrid` and from every row.
-   *
-   * Inside a horizontal merge the region narrows by one and keeps its content: a covered
-   * cell is dropped rather than the origin. Elsewhere the column's cells go with it.
-   * @throws {InvalidOptionError} when `index` is out of range
-   */
-  removeColumn(index: number): void;
-  /**
-   * Merge the rectangle between two cell positions into one cell. The top-left cell keeps
-   * its content; the rest become covered cells and are emptied, since a covered cell is
-   * never rendered.
-   *
-   * A rectangle that cuts through an existing merge is **rejected**, not silently widened
-   * to fit — the caller asked for a specific region, and quietly producing a different one
-   * is how a layout ends up wrong with nothing to point at. Unmerge first.
-   * @throws {InvalidOptionError} when an index is out of range, the range covers one cell,
-   *   or it partially overlaps an existing merge
-   */
-  mergeCells(row1: number, col1: number, row2: number, col2: number): void;
-  /**
-   * Split the merged cell whose **origin** is `(row, col)` back into individual cells.
-   * A no-op on a cell that is not merged; addressing a covered cell instead of the origin
-   * throws, and the message names the origin to use.
-   * @throws {InvalidOptionError} when an index is out of range or the cell is a covered cell
-   */
-  unmergeCell(row: number, col: number): void;
-  /** Escape hatch: the underlying `a:tbl` element. After mutating it call {@link markDirty}, or `save()` writes the original bytes. */
-  get element_(): Element;
-  /** Mark the owning part dirty so `save()` reserializes it. Call after mutating {@link element_}. */
-  markDirty(): void;
-}
-/** One table row (`a:tr`). */
-declare class TableRow {
-  private readonly tr;
-  private readonly part;
-  /** The owning slide's theme colour context, threaded to each {@link TableCell}. */
-  private readonly themeColors?;
-  /** The table's style-resolution context, threaded to each cell for {@link TableCell.resolvedFill}. */
-  private readonly style?;
-  /** This row's zero-based index in the table, for style-graph banding/edge conditions. */
-  private readonly rowIndex;
-  /** The owning slide's relationships, threaded to each cell for {@link TableCell.pictureFill}. */
-  private readonly rels?;
-  constructor(tr: Element, part: Part,
-  /** The owning slide's theme colour context, threaded to each {@link TableCell}. */
-  themeColors?: ThemeContext | undefined,
-  /** The table's style-resolution context, threaded to each cell for {@link TableCell.resolvedFill}. */
-  style?: TableCellStyleContext | null | undefined,
-  /** This row's zero-based index in the table, for style-graph banding/edge conditions. */
-  rowIndex?: number,
-  /** The owning slide's relationships, threaded to each cell for {@link TableCell.pictureFill}. */
-  rels?: Relationships | undefined);
-  /** The row's cells (`a:tc`) in left-to-right order. */
-  get cells(): TableCell[];
-  /** Row height in EMU (`a:tr/@h`), or `null` if unset. */
-  get heightEmu(): number | null;
-  /** Escape hatch: the underlying `a:tr` element. After mutating it call {@link markDirty}, or `save()` writes the original bytes. */
-  get element_(): Element;
-  /** Mark the owning part dirty so `save()` reserializes it. Call after mutating {@link element_}. */
-  markDirty(): void;
-}
 /** One table cell (`a:tc`). */
 declare class TableCell {
   #private;
   private readonly tc;
   private readonly part;
   /** The owning slide's theme colour context, threaded to the cell's text for `Run.resolvedColor`. */
-  private readonly themeColors?;
-  /** The table's style-resolution context, for the {@link resolvedFill} style-graph fallback. */
-  private readonly style?;
+  private readonly themeContext;
+  /** The table's style-resolution context, for the {@link resolvedFill} style-graph fallback; `null` when no style resolves. */
+  private readonly style;
   /** This cell's zero-based row index in the table. */
   private readonly rowIndex;
   /** This cell's zero-based column index in its row. */
   private readonly colIndex;
   /** The owning slide's relationships, for resolving {@link pictureFill}'s `r:embed` to a partname. */
-  private readonly rels?;
+  private readonly rels;
   constructor(tc: Element, part: Part,
   /** The owning slide's theme colour context, threaded to the cell's text for `Run.resolvedColor`. */
-  themeColors?: ThemeContext | undefined,
-  /** The table's style-resolution context, for the {@link resolvedFill} style-graph fallback. */
-  style?: TableCellStyleContext | null | undefined,
+  themeContext: ThemeContext,
+  /** The table's style-resolution context, for the {@link resolvedFill} style-graph fallback; `null` when no style resolves. */
+  style: TableCellStyleContext | null,
   /** This cell's zero-based row index in the table. */
-  rowIndex?: number,
+  rowIndex: number,
   /** This cell's zero-based column index in its row. */
-  colIndex?: number,
+  colIndex: number,
   /** The owning slide's relationships, for resolving {@link pictureFill}'s `r:embed` to a partname. */
-  rels?: Relationships | undefined);
-  /** The cell's text frame (`a:txBody`); `null` only if the cell has none (non-conformant). */
+  rels: Relationships);
+  /**
+   * The cell's text frame (`a:txBody`); `null` only if the cell has none (non-conformant).
+   *
+   * A run that sets nothing of its own resolves the way PowerPoint paints it
+   * (`test/read/fixtures/table-text-inheritance.pptx`). Its colour, face, bold and italic come
+   * first from the table style's text style for the cell's region, and a colour or face no part
+   * states is the theme's `tx1` and minor font, with no table style at all as much as with one.
+   * Below that, the chain a text box's runs walk bottoms out in the slide master's
+   * `p:otherStyle` rather than in `p:defaultTextStyle`, which cell text never reads. So size comes
+   * from `p:otherStyle`, and so do bold and italic where the table style says nothing.
+   */
   get textFrame(): TextFrame | null;
   /** The cell's text, paragraphs joined by `\n`. */
   get text(): string;
@@ -2808,7 +2671,7 @@ declare class TableCell {
   /**
    * The cell's solid fill resolved against the table's theme colour context to a
    * literal hex — the table-cell counterpart of
-   * {@link import('./shapes.js').AutoShape.resolvedFill}. The cell's own
+   * {@link AutoShape.resolvedFill}. The cell's own
    * `a:tcPr/a:solidFill` wins; when the cell defines none, this falls back to the
    * table **style** graph (the `firstRow`/banded/`wholeTbl` shading the
    * `a:tableStyleId` supplies — see {@link Table.resolvedStyle}), so a styled cell
@@ -2818,9 +2681,9 @@ declare class TableCell {
    * A cell that carries *some other* fill choice (`a:blipFill`/`a:gradFill`/
    * `a:pattFill`/`a:noFill`) overrides the style graph in PowerPoint, so this
    * reports `null` for one rather than falling through to the inherited shading —
-   * the same guard {@link import('./shapes.js').AutoShape.resolvedFill} applies to
+   * the same guard {@link AutoShape.resolvedFill} applies to
    * the style matrix. Read {@link pictureFill} for an image-filled cell. Also
-   * `null` with no theme context, or when neither source yields a solid colour (an
+   * `null` when neither source yields a solid colour (an
    * unmapped token, an explicit style `a:noFill`). The returned
    * {@link ResolvedColor} carries `effectiveHex` (the base colour with its
    * `lumMod`/`lumOff`/… transforms applied) — read that for the final colour.
@@ -2841,13 +2704,13 @@ declare class TableCell {
   /**
    * `true` when the cell sets an explicit no-fill (`a:tcPr/a:noFill`) — a deliberately
    * transparent cell showing the table background (or the slide) through. The cell-side
-   * counterpart of {@link import('./shapes.js').AutoShape.fillNoFill}, and what
+   * counterpart of {@link AutoShape.fillNoFill}, and what
    * {@link noFill} writes.
    *
    * {@link hasOwnFill} is not this question: it is `true` for *any* `EG_FillProperties`
    * child, so on its own it cannot separate a suppressed fill from a gradient or an image
-   * one — and every colour accessor ({@link resolvedFill}, {@link fillColor},
-   * {@link fillSchemeColor}) reports `null` for a no-fill cell exactly as it does for a
+   * one — and every colour accessor ({@link resolvedFill}, {@link fillSchemeColor})
+   * reports `null` for a no-fill cell exactly as it does for a
    * cell that inherits its shading from the table style. Deriving it as "has a fill of its
    * own, and no accessor recognises it" instead of reading it has two failure modes: it
    * folds `a:grpFill` in with `a:noFill`, and its meaning changes silently the day a
@@ -2859,7 +2722,7 @@ declare class TableCell {
   /**
    * The cell's picture (image) fill (`a:tcPr/a:blipFill`), or `null` when the cell
    * is not image-filled. The cell counterpart of
-   * {@link import('./shapes.js').AutoShape.pictureFill}: {@link resolvedFill}
+   * {@link AutoShape.pictureFill}: {@link resolvedFill}
    * decodes only solid colours, so without this an image-filled cell is
    * indistinguishable from an empty one. Carries the embedded image
    * ({@link PictureFill.relId}/{@link PictureFill.partName}) plus the stretch/tile
@@ -2974,6 +2837,214 @@ declare class TableCell {
   markDirty(): void;
 }
 //#endregion
+//#region src/read/api/table-row.d.ts
+/** One table row (`a:tr`). */
+declare class TableRow {
+  private readonly tr;
+  private readonly part;
+  /** The owning slide's theme colour context, threaded to each {@link TableCell}. */
+  private readonly themeContext;
+  /** The table's style-resolution context, threaded to each cell for {@link TableCell.resolvedFill}; `null` when no style resolves. */
+  private readonly style;
+  /** This row's zero-based index in the table, for style-graph banding/edge conditions. */
+  private readonly rowIndex;
+  /** The owning slide's relationships, threaded to each cell for {@link TableCell.pictureFill}. */
+  private readonly rels;
+  constructor(tr: Element, part: Part,
+  /** The owning slide's theme colour context, threaded to each {@link TableCell}. */
+  themeContext: ThemeContext,
+  /** The table's style-resolution context, threaded to each cell for {@link TableCell.resolvedFill}; `null` when no style resolves. */
+  style: TableCellStyleContext | null,
+  /** This row's zero-based index in the table, for style-graph banding/edge conditions. */
+  rowIndex: number,
+  /** The owning slide's relationships, threaded to each cell for {@link TableCell.pictureFill}. */
+  rels: Relationships);
+  /** The row's cells (`a:tc`) in left-to-right order. */
+  get cells(): TableCell[];
+  /** Row height in EMU (`a:tr/@h`), or `null` if unset. */
+  get heightEmu(): number | null;
+  /** Escape hatch: the underlying `a:tr` element. After mutating it call {@link markDirty}, or `save()` writes the original bytes. */
+  get element_(): Element;
+  /** Mark the owning part dirty so `save()` reserializes it. Call after mutating {@link element_}. */
+  markDirty(): void;
+}
+//#endregion
+//#region src/read/api/table.d.ts
+/** A table: a grid of rows and cells inside a graphic frame. */
+declare class Table {
+  #private;
+  private readonly tbl;
+  private readonly part;
+  /** The owning slide's theme colour context, threaded to each cell's text for `Run.resolvedColor`. */
+  private readonly themeContext;
+  /** The deck package, for resolving `a:tableStyleId` against `tableStyles.xml` (style-graph cell fills). */
+  private readonly opc;
+  /** The owning slide's relationships, for resolving a cell picture fill's `r:embed` to a partname. */
+  private readonly rels;
+  constructor(tbl: Element, part: Part,
+  /** The owning slide's theme colour context, threaded to each cell's text for `Run.resolvedColor`. */
+  themeContext: ThemeContext,
+  /** The deck package, for resolving `a:tableStyleId` against `tableStyles.xml` (style-graph cell fills). */
+  opc: OpcPackage,
+  /** The owning slide's relationships, for resolving a cell picture fill's `r:embed` to a partname. */
+  rels: Relationships);
+  /** The table's rows (`a:tr`) in document (top-to-bottom) order. */
+  get rows(): TableRow[];
+  /**
+   * The table's style graph entry (`styleId`, `name`, raw `a:tblStyle`) resolved
+   * from the deck's `tableStyles.xml`, or `null` when the table names no
+   * `a:tableStyleId`, the deck has no `tableStyles.xml`, or the id is a built-in
+   * `[MS-OE376]` style the deck does not materialise. This is what supplies the
+   * banded-row / header shading a cell with no own fill inherits — read the
+   * resolved per-cell colour off {@link TableCell.resolvedFill}.
+   *
+   * Resolved afresh on every read, not through the per-instance memo the cells share, so an
+   * edit made through the returned `element_` shows in the next read's `name`. A caller reads
+   * this once per table; the memo exists for the per-cell path that reads it hundreds of times.
+   */
+  get resolvedStyle(): ResolvedTableStyle | null;
+  /** Number of rows (`a:tr`). */
+  get rowCount(): number;
+  /** Number of grid columns (`a:tblGrid/a:gridCol`). */
+  get columnCount(): number;
+  /** Column widths in EMU (`a:gridCol/@w`), one per grid column. */
+  get columnWidths(): (number | null)[];
+  /**
+   * The table's style GUID (`a:tblPr/a:tableStyleId` text), e.g.
+   * `{5940675A-B579-460E-94D1-54222C63F5DA}`, or `null` when the table carries no
+   * `a:tableStyleId`. This is the reference into `ppt/tableStyles.xml` (or a
+   * built-in `[MS-OE376]` style) that supplies the banded-row / header shading the
+   * `firstRow`/`bandRow` flags activate — without it a replica loses the whole
+   * table style, so it is the read counterpart of the writer's `tableStyle` option.
+   */
+  get styleId(): string | null;
+  /**
+   * The table's own background (`a:tblPr` fill) resolved against the slide's theme colour
+   * context to a literal hex, or `null` when the table carries no solid background.
+   *
+   * This is the table-level counterpart of {@link TableCell.resolvedFill}, and it is a
+   * genuinely different thing from a cell fill: a `a:tblPr` fill sits *behind* the grid, so
+   * a cell with no fill of its own shows it through. Reports `null` for a non-solid choice
+   * (`a:blipFill`/`a:gradFill`/`a:pattFill`/`a:noFill`) — read {@link pictureFill} for an
+   * image background.
+   */
+  get resolvedFill(): ResolvedColor | null;
+  /**
+   * The table's picture background (`a:tblPr/a:blipFill`), or `null` when the table is not
+   * image-backed. The table-level twin of {@link TableCell.pictureFill}, and needed for the
+   * same reason: {@link resolvedFill} decodes only solid colours, so without this an
+   * image-backed table is indistinguishable from an unfilled one.
+   */
+  get pictureFill(): PictureFill | null;
+  /**
+   * The table's gradient background (`a:tblPr/a:gradFill`), or `null` when it is not
+   * gradient-filled. Needed for the same reason {@link pictureFill} is:
+   * {@link resolvedFill} decodes only solid colours.
+   */
+  get gradientFill(): GradientFill | null;
+  /**
+   * The table's pattern (hatch) background (`a:tblPr/a:pattFill`), or `null` when it is not
+   * pattern-filled.
+   */
+  get patternFill(): PatternFill | null;
+  /**
+   * The raw `schemeClr` token of the table's own background
+   * (`a:tblPr/a:solidFill/a:schemeClr/@val`), or `null` for an absent or `srgbClr` fill.
+   * {@link resolvedFill} is the literal it resolves to; this is the unresolved reference,
+   * which is what a replica should carry so the copy still tracks its theme.
+   */
+  get fillSchemeColor(): string | null;
+  /**
+   * Whether the first row is styled as a header (`a:tblPr/@firstRow`), which `addTable` writes
+   * from `hasHeader`.
+   *
+   * This and the five below are PowerPoint's Table Style Options, the six flags that decide which
+   * regions of the table style paint. Two of them were readable and four were not, although
+   * {@link resolvedStyle} has always read all six to resolve a cell: `addTable` writes every one,
+   * so a table read back and re-authored lost its footer row, its banded columns and its first
+   * and last column emphasis with nothing to say so.
+   */
+  get firstRowHeader(): boolean;
+  /** Whether the last row is styled as a footer (`a:tblPr/@lastRow`), from `addTable`'s `hasFooter`. */
+  get lastRowFooter(): boolean;
+  /** Whether rows are banded (`a:tblPr/@bandRow`), from `addTable`'s `hasBandedRows`. */
+  get bandedRows(): boolean;
+  /** Whether columns are banded (`a:tblPr/@bandCol`), from `addTable`'s `hasBandedColumns`. */
+  get bandedColumns(): boolean;
+  /** Whether the first column is emphasised (`a:tblPr/@firstCol`), from `addTable`'s `hasFirstColumn`. */
+  get firstColumnHeader(): boolean;
+  /** Whether the last column is emphasised (`a:tblPr/@lastCol`), from `addTable`'s `hasLastColumn`. */
+  get lastColumnFooter(): boolean;
+  /**
+   * The cell at `(rowIndex, columnIndex)` (both zero-based), or `null` when out
+   * of range. Column index counts `a:tc` elements in the row, so a cell that
+   * spans columns (`gridSpan`) occupies a single index here.
+   */
+  cell(rowIndex: number, columnIndex: number): TableCell | null;
+  /**
+   * Insert a row, defaulting to the bottom of the table. Returns the new {@link TableRow}.
+   *
+   * The new row is auto-height (`a:tr/@h="0"`) and its cells are empty. Inserting *through*
+   * a vertical merge extends that merge rather than interrupting it: the span's origin
+   * grows by a row and the new cell joins as a continuation, because an origin claiming
+   * more rows than it has continuations is a table PowerPoint reports as corrupt.
+   * @param {number} [index] - where to insert, `0`..`rowCount`; appended when omitted
+   * @throws {InvalidOptionError} when `index` is outside that range
+   */
+  addRow(index?: number): TableRow;
+  /**
+   * Remove the row at `index`, with its content.
+   *
+   * A cell in the row that *continues* a vertical merge shortens that merge. A cell that
+   * *starts* one hands the region to its first continuation, which becomes the new origin —
+   * the merged region survives one row shorter, and only the removed row's own text is lost.
+   * @throws {InvalidOptionError} when `index` is out of range
+   */
+  removeRow(index: number): void;
+  /**
+   * Insert a column, defaulting to the right-hand end. Updates `a:tblGrid` **and** every
+   * row, which is the pair that has to stay in step.
+   *
+   * The mirror of {@link addRow}'s merge case: inserting inside a horizontal merge widens
+   * it instead of splitting it.
+   * @param {number} [index] - where to insert, `0`..`columnCount`; appended when omitted
+   * @param {number} [widthEmu] - the new column's width; defaults to 1 inch
+   * @throws {InvalidOptionError} when `index` is outside that range
+   */
+  addColumn(index?: number, widthEmu?: number): void;
+  /**
+   * Remove the column at `index`, from `a:tblGrid` and from every row.
+   *
+   * Inside a horizontal merge the region narrows by one and keeps its content: a covered
+   * cell is dropped rather than the origin. Elsewhere the column's cells go with it.
+   * @throws {InvalidOptionError} when `index` is out of range
+   */
+  removeColumn(index: number): void;
+  /**
+   * Merge the rectangle between two cell positions into one cell. The top-left cell keeps
+   * its content; the rest become covered cells and are emptied, since a covered cell is
+   * never rendered.
+   *
+   * A rectangle that cuts through an existing merge is **rejected**, not silently widened
+   * to fit — the caller asked for a specific region, and quietly producing a different one
+   * is how a layout ends up wrong with nothing to point at. Unmerge first.
+   * @throws {InvalidOptionError} when an index is out of range, the range covers one cell,
+   *   or it partially overlaps an existing merge
+   */
+  mergeCells(row1: number, col1: number, row2: number, col2: number): void;
+  /**
+   * Split the merged cell whose **origin** is `(row, col)` back into individual cells.
+   * A no-op on a cell that is not merged; addressing a covered cell instead of the origin
+   * throws, and the message names the origin to use.
+   * @throws {InvalidOptionError} when an index is out of range or the cell is a covered cell
+   */
+  unmergeCell(row: number, col: number): void;
+  /** Escape hatch: the underlying `a:tbl` element. After mutating it call {@link markDirty}, or `save()` writes the original bytes. */
+  get element_(): Element;
+  /** Mark the owning part dirty so `save()` reserializes it. Call after mutating {@link element_}. */
+  markDirty(): void;
+}
+//#endregion
 //#region src/read/api/shapes/graphic-frame.d.ts
 /** A graphic frame (`p:graphicFrame`) — host for tables, charts and SmartArt diagrams. */
 declare class GraphicFrame extends Shape {
@@ -2981,14 +3052,20 @@ declare class GraphicFrame extends Shape {
   readonly shapeType: 'graphicFrame';
   protected xfrm(): Element | null;
   protected getOrAddXfrm(): Element;
-  protected getOrAddProperties(): ShapeProperties;
+  protected paintSurface(): PaintSurface | null;
   /** Whether this frame hosts a table (`a:graphicData/@uri` is the table URI). */
   get hasTable(): boolean;
   /** Whether this frame hosts a classic chart (`a:graphicData/@uri` is the chart URI). */
   get hasChart(): boolean;
-  /** Whether this frame hosts a chartEx chart (`a:graphicData/@uri` is the chartEx URI). */
+  /**
+   * Whether this frame hosts a chartEx chart. Its `a:graphicData/@uri` is the `cx` namespace,
+   * which the reference child (`cx:chart`) is also in.
+   */
   get hasChartEx(): boolean;
-  /** Whether this frame hosts a SmartArt diagram (`a:graphicData/@uri` is the diagram URI). */
+  /**
+   * Whether this frame hosts a SmartArt diagram. Its `a:graphicData/@uri` is the `dgm`
+   * namespace, and the payload under it is a `dgm:relIds` reference rather than the drawing.
+   */
   get hasDiagram(): boolean;
   /**
    * The `a:graphicData/@uri` verbatim — the namespace naming what this frame hosts, or
@@ -3032,7 +3109,7 @@ declare class GroupShape extends Shape {
   protected xfrm(): Element | null;
   protected getOrAddXfrm(): Element;
   protected properties(): Element | null;
-  protected getOrAddProperties(): ShapeProperties;
+  protected paintSurface(): PaintSurface | null;
   /**
    * The group's own child coordinate space (`p:grpSpPr/a:xfrm/a:chOff` and
    * `a:chExt`) in EMU, or `null` when the group has no transform or either
@@ -3122,7 +3199,12 @@ declare class Theme {
    * define reads `null`. Use {@link color} to look one slot up.
    */
   get colorScheme(): Record<ThemeColorSlot, string | null>;
-  /** The 6-hex RGB of one colour-scheme slot, or `null` when the theme does not define it. */
+  /**
+   * The 6-hex RGB of one colour-scheme slot, or `null` when the theme does not define it.
+   *
+   * Parsed once per proxy: the whole `a:clrScheme` is read to answer for one slot, and a
+   * caller asking for several -- which is the normal way to ask -- re-read it each time.
+   */
   color(slot: ThemeColorSlot): string | null;
   /** The theme's `a:fontScheme` (major/minor font families), or `null` when the theme declares none. */
   get fontScheme(): ThemeFontScheme | null;
@@ -3146,27 +3228,38 @@ declare class Theme {
  * *draw* it.
  */
 declare class Placeholder {
-  #private;
   /** The placeholder's `p:sp`. `protected` so {@link NotesPlaceholder} can read it. */
   protected readonly sp: Element;
   /** The part the `p:sp` lives in — a master, a layout, or a notes slide. */
-  protected readonly part: Part;
-  /** The owning part's theme context, threaded to {@link textFrame}. */
-  protected readonly themeContext: ThemeContext;
-  /** The owning part's relationships, threaded to {@link textFrame} for hyperlink resolution. */
-  protected readonly relationships: Relationships;
+  protected readonly host: ShapeHost;
+  /**
+   * The same `p:sp` as an {@link AutoShape}. Identity, geometry and the text frame are
+   * forwarded to it rather than re-derived here.
+   *
+   * They used to be re-derived, and the two answers had drifted apart. `#cNvPr()` hard-coded
+   * `p:nvSpPr` where `nonVisualCNvPr` finds any `p:nv*Pr`; the four geometry getters read the
+   * `p:spPr/a:xfrm` chain through a helper no other caller used, against `Shape`'s own
+   * `xfrm()` + `emuFrom`; and,
+   * the one that showed, the text frame was built with **no** inheritance context, so
+   * `Run.resolvedSizePt`, `resolvedFontFace`, `resolvedColor` and `resolvedBold` resolved
+   * through `SlideMaster.shapes` and came back `null` through `SlideMaster.placeholders` —
+   * two views of one element disagreeing about the same run.
+   */
+  protected readonly shape: AutoShape;
   constructor(
   /** The placeholder's `p:sp`. `protected` so {@link NotesPlaceholder} can read it. */
   sp: Element,
   /** The part the `p:sp` lives in — a master, a layout, or a notes slide. */
-  part: Part,
-  /** The owning part's theme context, threaded to {@link textFrame}. */
-  themeContext: ThemeContext,
-  /** The owning part's relationships, threaded to {@link textFrame} for hyperlink resolution. */
-  relationships: Relationships);
+  host: ShapeHost);
   /** Placeholder type (`p:ph/@type`: `title` | `body` | `sldNum` | …), or `null` when absent (a body placeholder). */
   get type(): string | null;
-  /** Placeholder index (`p:ph/@idx`), or `null` when unset. */
+  /**
+   * Placeholder index (`p:ph/@idx`), or `null` when unset.
+   *
+   * Not forwarded to {@link AutoShape.placeholder}, whose `idx` defaults to `'0'` the way
+   * PowerPoint resolves it. Here the absence is the contract: this view reports what the
+   * part says.
+   */
   get idx(): string | null;
   /** Shape name (`p:cNvPr/@name`), or `''` when unnamed. */
   get name(): string;
@@ -3182,8 +3275,9 @@ declare class Placeholder {
   get height(): number | null;
   /**
    * The placeholder's text as a navigable {@link TextFrame} (`p:txBody`), or `null`
-   * when it carries no text body. Threaded with the owning master/layout theme
-   * context so a run's own `schemeClr` resolves through `Run.resolvedColor`.
+   * when it carries no text body. Threaded with the owning tier's theme context and
+   * placeholder identity, so a run's `resolved*` getters walk the same inheritance chain
+   * they walk through {@link SlideMaster.shapes}.
    */
   get textFrame(): TextFrame | null;
   /** Escape hatch: the underlying `p:sp` element. After mutating it call {@link markDirty}, or `save()` writes the original bytes. */
@@ -3359,23 +3453,39 @@ declare class NotesPlaceholder extends Placeholder {
 }
 /**
  * A slide's speaker-notes slide (`notesSlideN.xml`) as a modeled object — the deep
- * companion to {@link import('./slide.js').Slide.notesText}. Exposes the notes
+ * companion to {@link Slide.notesText}. Exposes the notes
  * shape tree as {@link NotesPlaceholder}s ({@link body}/{@link slideImage}/
  * {@link slideNumber}) plus the body {@link textFrame} the older getters flatten.
  *
  * The theme context (notesMaster → `theme2.xml`) is resolved once and shared across
  * every placeholder's text frame.
  */
-declare class NotesSlide {
+declare class NotesSlide implements ShapeHost {
   #private;
-  private readonly opc;
+  /** The package the notes slide belongs to, for reaching the notesMaster and its theme. */
+  readonly opc: OpcPackage;
   /** The notes slide's OPC part (`/ppt/notesSlides/notesSlideN.xml`). */
   readonly part: Part;
-  constructor(opc: OpcPackage,
+  constructor(
+  /** The package the notes slide belongs to, for reaching the notesMaster and its theme. */
+  opc: OpcPackage,
   /** The notes slide's OPC part (`/ppt/notesSlides/notesSlideN.xml`). */
   part: Part);
   /** Partname of the notes slide part. */
   get partName(): string;
+  /** The notes part's own relationships — a notes hyperlink resolves through these. */
+  get relationships(): Relationships;
+  /**
+   * The notes shape tree as full shapes, in document order.
+   *
+   * A notes slide holds nothing but its three placeholders, so {@link placeholders} is the
+   * view to read. This one exists because a notes slide is a {@link ShapeHost} — which is
+   * what lets a {@link NotesPlaceholder} be the same {@link AutoShape} view of its `p:sp`
+   * that a master or layout placeholder is, rather than a second reading of one.
+   */
+  get shapes(): AnyShape[];
+  /** The shape anywhere in the notes tree with the given drawing id, or `undefined`. */
+  shapeByIdDeep(id: number): AnyShape | undefined;
   /**
    * The notes theme context, resolved through the notesMaster → `theme2.xml` chain
    * and cached. Backs {@link NotesPlaceholder.textFrame}'s `Run.resolvedColor`.
@@ -3519,16 +3629,40 @@ interface TransitionSoundInfo {
   /** Display name on `p:snd @name`, or `null`. */
   name: string | null;
 }
-/** Transition fields accepted by the {@link Slide.transition} setter. `speed` defaults are derived from `durationMs`. */
+/**
+ * Transition fields accepted by the {@link Slide.transition} setter. A {@link TransitionInfo} read
+ * from the same slide is a valid input, so `slide.transition = { ...slide.transition, speed: 'slow' }`
+ * changes the speed and keeps everything else, the sound included.
+ */
 interface TransitionInput {
   type: string;
   /** Namespace prefix for the type element; defaults to `p` (base ECMA-376). */
   namespace?: string;
+  /**
+   * Coarse speed bucket (`spd`). When omitted it is derived from `durationMs` if one is given, and
+   * otherwise not written. A stated `fast`, the schema default, is not written when the slide's
+   * transition had no `spd` either, so a transition read back and assigned again keeps its markup.
+   */
   speed?: TransitionSpeed;
+  /** Exact duration in milliseconds (`p14:dur`), a finite number from 0; `null` or omitted writes none. */
   durationMs?: number | null;
   advanceOnClick?: boolean;
+  /** Auto-advance delay in milliseconds (`advTm`), a finite number from 0; `null` or omitted writes none. */
   advanceAfterMs?: number | null;
   variant?: Record<string, string>;
+  /**
+   * The transition sound (`p:sndAc`), in three states.
+   *
+   * - **omitted** keeps the sound the slide's transition already has;
+   * - **`null`** removes it;
+   * - **a value** is accepted only when it is that same sound, as a spread of the getter passes it.
+   *
+   * A different sound throws `transition/sound-unsupported`: a start sound names an embedded audio
+   * part, which this setter does not add, so writing one would point the slide at a relationship it
+   * may not have. Add a sound when authoring the deck (`slide.transition = { sound }` on the write
+   * side) instead.
+   */
+  sound?: TransitionSoundInfo | null;
 }
 //#endregion
 //#region src/read/api/slide.d.ts
@@ -3657,12 +3791,17 @@ declare class Slide implements ShapeHost {
    * (a `p14` Choice carrying `p14:dur` plus a base `mc:Fallback`); otherwise the
    * bare `<p:transition>` is written. The node is inserted at its schema slot —
    * after `p:clrMapOvr`, before `p:timing`/`p:extLst`. Marks the slide part dirty.
+   *
+   * The new transition is built from the current one before that is removed: it keeps the sound
+   * unless `sound` says otherwise (see {@link TransitionInput.sound}), and a value that is refused
+   * (a `durationMs` or `advanceAfterMs` that is not a number of milliseconds from 0, or a sound
+   * that is not the slide's own) leaves the slide as it was.
    */
   set transition(value: TransitionInput | null);
   /**
    * Whether the slide carries build animations (`p:timing` with a `<p:bldP>` or a
    * `presetID`-bearing time node). The animation tree itself is preserved opaquely;
-   * see {@link animationSpids}.
+   * see `animationSpids`.
    */
   get hasAnimations(): boolean;
   /**
@@ -3786,7 +3925,7 @@ declare class Slide implements ShapeHost {
    * position (EMU), timestamp, and its author resolved through the deck-wide
    * {@link Presentation.commentAuthors} registry (`@authorId` → name/initials). These
    * are the comments the writer authors via `slide.addComment(...)`; the 2018 modern
-   * comment parts (`p188:cm`) are a separate schema, preserved but not decoded.
+   * comment parts (`p188:cm`) are a separate schema, read by {@link modernComments}.
    */
   get comments(): Comment[];
   /**
@@ -3817,15 +3956,15 @@ declare class Slide implements ShapeHost {
    * Colour tokens resolve against this slide's theme; an image background's
    * `r:embed` resolves to an absolute part name through the *owning* part's
    * relationships (the layout's rels for a layout-inherited image, etc.). Solid,
-   * gradient, and image backgrounds are the three the writer authors and so
-   * round-trip faithfully; `pattern`/`themeRef` are read-only for imported decks.
+   * gradient, pattern and image backgrounds are the ones the writer authors and so
+   * round-trip faithfully; `themeRef` is read-only for imported decks.
    */
   get background(): SlideBackground | null;
   /**
    * The slide's own slide-number placeholder (`p:sp` with `p:ph type="sldNum"`,
    * carrying an `<a:fld type="slidenum">`), or `null` when the slide shows no slide
-   * number of its own. This is the concrete shape the writer emits for
-   * `pptx.setSlideNumber(...)` on a slide's layout; its geometry and run formatting
+   * number of its own. This is the concrete shape the writer emits for a slide given
+   * `slide.slideNumber`, or added to a master defined with `slideNumber`; its geometry and run formatting
    * read off the returned {@link AutoShape} the same as any placeholder.
    *
    * Scoped to the slide's *own* shape tree — a slide number inherited purely from
@@ -3843,7 +3982,7 @@ declare class Slide implements ShapeHost {
    *
    * Drawing ids are unique within a slide, so the first match is the only match; the
    * pre-order walk just fixes a deterministic order. This backs the connector-binding
-   * resolution ({@link import('./shapes.js').Connector.startConnection}), which must
+   * resolution ({@link Connector.startConnection}), which must
    * resolve a binding into a group that top-level {@link shapeById} cannot see.
    */
   shapeByIdDeep(id: number): AnyShape | undefined;
@@ -3899,9 +4038,13 @@ declare class Slide implements ShapeHost {
    */
   shapeTree(): Element | null;
   /**
-   * @internal The smallest drawing id (`p:cNvPr/@id`) not already used on this
-   * slide. Exposed so `Presentation.importShape` can give a lifted shape (and its
-   * group children) collision-free ids on the host.
+   * @internal One past the highest drawing id (`p:cNvPr/@id`) in use on this slide. Exposed so
+   * `Presentation.importShape` can give a lifted shape (and its group children) collision-free
+   * ids on the host.
+   *
+   * It does NOT fill gaps, and it does not reserve what it hands out: calling it twice without
+   * appending in between returns the same id both times. A caller allocating several ids at
+   * once counts up from one call rather than calling repeatedly.
    */
   nextShapeId(): number;
 }
@@ -3939,6 +4082,32 @@ interface CoreProperties {
   /** `cp:lastPrinted`, raw W3CDTF string. */
   lastPrinted?: string;
 }
+/**
+ * Decoded `docProps/app.xml` — the *extended* properties, which are the producer's own
+ * account of the deck rather than the author's metadata. Every field is optional (present
+ * only when the element is).
+ *
+ * Deliberately a subset. `<Slides>`, `<Words>`, `<Paragraphs>` and the rest are statistics
+ * the producing application computed for the file it wrote; reporting them from a read model
+ * that can hand back an edited deck would be reporting a number about a document that no
+ * longer exists. The four here identify the producer and name the deck's parts, which stay
+ * true, and `company` is the one this library's write API can set.
+ */
+interface ExtendedProperties {
+  /** `<Application>` — the producing application, e.g. `Microsoft Office PowerPoint`. */
+  application?: string;
+  /** `<AppVersion>` — that application's version, in its own `major.minor` spelling (`16.0000`). */
+  appVersion?: string;
+  /** `<Company>` (the write-side `pptx.company`). */
+  company?: string;
+  /**
+   * `<TitlesOfParts>` — the flat `vt:lpstr` vector naming the deck's fonts, themes and slide
+   * titles in one list. It is the vector as written, NOT split by section: `<HeadingPairs>`
+   * holds the counts that partition it, and this library does not read them, so the caller
+   * that wants the slide titles alone has to pair the two itself.
+   */
+  titlesOfParts?: string[];
+}
 /** One user-defined custom document property (`docProps/custom.xml`). */
 interface CustomProperty {
   /** The property's `@name`. */
@@ -3953,6 +4122,17 @@ interface CustomProperty {
  * elements decode to the empty string.
  */
 declare function readCoreProperties(opc: OpcPackage): CoreProperties;
+/**
+ * Read the deck's extended document properties from `/docProps/app.xml`, resolved
+ * via the package-root `extended-properties` relationship (fallback: the part's
+ * content type). Missing part → `{}` (all fields undefined). Present-but-empty
+ * elements decode to the empty string.
+ *
+ * Children are matched by **local name**: the extended-properties namespace is not in the
+ * read model's qname registry, and its elements are unprefixed there, so this reads them the
+ * way {@link readCustomProperties} reads a `<property>`'s `vt:` child.
+ */
+declare function readExtendedProperties(opc: OpcPackage): ExtendedProperties;
 /**
  * Read the deck's user-defined custom properties from `/docProps/custom.xml`,
  * resolved via the package-root `custom-properties` relationship (fallback: the
@@ -3966,6 +4146,134 @@ declare function readCoreProperties(opc: OpcPackage): CoreProperties;
  */
 declare function readCustomProperties(opc: OpcPackage): CustomProperty[];
 //#endregion
+//#region src/read/api/ops/deck-target.d.ts
+/** The destination deck: just the package and its main part. `Presentation` satisfies it. */
+interface DeckTarget {
+  readonly opc: OpcPackage;
+  readonly presentationPart: Part;
+}
+//#endregion
+//#region src/read/api/ops/part-copy.d.ts
+/**
+ * One import in progress: where parts are going, where they are coming from, and
+ * what has already come across.
+ *
+ * `source` and `registry` are one fact, not two — a registry maps partnames *of
+ * that package*, so pairing it with any other package silently returns partnames
+ * for parts that were never copied. Holding them in a single value makes the
+ * pairing a type invariant rather than a call-site convention; mint one with
+ * `Presentation`'s factory, which reads through to the per-source registry that
+ * outlives any one call (see {@link copyPart}'s idempotence).
+ */
+interface ImportContext {
+  /** The deck being copied into. */
+  readonly dest: DeckTarget;
+  /** The package being copied out of. */
+  readonly source: OpcPackage;
+  /** Source partname → the partname allocated for it in `dest`. */
+  readonly registry: Map<string, string>;
+  /**
+   * The pages this call is materializing, and where each is headed: source slide
+   * partname → the destination partname pre-allocated for it. A page named here
+   * gets its own part even when the registry already holds a copy of it, which is
+   * what lets one source page be imported more than once.
+   *
+   * Both import entry points set it — {@link Presentation.importSlides} for the
+   * whole batch, {@link copySlidePart} for the single page of one
+   * {@link Presentation.importSlide}. For the batch it carries a second meaning:
+   * `slide → slide` relationships resolve only within the set, so an imported page
+   * may link to another *selected* page (rewritten to its fresh partname) but must
+   * not drag an unselected source page across as a dependency.
+   *
+   * One destination per source page is deliberate: a page is a link target as well
+   * as an output, and a map to *many* destinations would make every jump link
+   * ambiguous. A batch asked for the same page N times therefore runs the
+   * traversal N times, each round naming that page's Nth reserved partname and the
+   * other pages' first — see `importSlides` step 3.
+   */
+  readonly selection?: SelectionPlan;
+  /**
+   * Set when the traversal is planning rather than copying: every write goes to the
+   * plan instead of `dest`, and `registry` is the plan's own copy of the real one.
+   */
+  readonly plan?: CopyPlan;
+}
+/** Which pages of one source package an import is materializing, and where each is headed. */
+interface SelectionPlan {
+  /** Source slide partname → the destination partname reserved for it. */
+  readonly destinations: ReadonlyMap<string, string>;
+}
+/**
+ * What a copy writes through: the destination package, or a {@link CopyPlan} standing in for it.
+ * `OpcPackage` satisfies it.
+ */
+interface CopyTarget {
+  reservePartNameLike(templatePartName: string): string;
+  part(partName: string): unknown;
+  addPart(partName: string, contentType: string, bytes: Uint8Array): unknown;
+  relationshipsFor(partName: string): Pick<Relationships, 'add' | 'addWithId'>;
+}
+/** One part a {@link CopyPlan} would add. */
+interface PlannedPart {
+  readonly partName: string;
+  readonly contentType: string;
+}
+/** One relationship a {@link CopyPlan} would add; `id` is absent where the copy allocates one. */
+interface PlannedRel {
+  readonly from: string;
+  readonly id?: string;
+  readonly type: string;
+  readonly target: string;
+  readonly targetMode?: 'Internal' | 'External';
+}
+/**
+ * An import's copy, run without writing: the parts and relationships it would add, and every error
+ * it would throw, found before anything in the destination moves.
+ *
+ * This is what lets a refused import leave the deck byte-identical. The copy changes the deck as it
+ * goes — parts added, a master registered in `presentation.xml`, a layout linked into its master —
+ * so a failure it met halfway would leave all of that behind. An import therefore runs the same
+ * traversal twice: first with a plan in its context, which throws what the copy would and writes
+ * nothing, then for real. The dry run used to be a separate walk of the source, transcribed from the
+ * copy under a comment asking readers to keep the two in step, and it had drifted: it walked a
+ * rebinding import's source layout chain, which the rebind never reads, and every source's notes
+ * master in a batch, where the copy reads only the first one it installs.
+ *
+ * A plan stands in for the destination package as a {@link CopyTarget}. It hands out the partnames
+ * the copy will be given, keeps its own copy of each source's registry so a part it planned is found
+ * again as the copy would find it, and remembers the notes master it would install in a deck that has
+ * none. Destination bookkeeping that adds no part — registering a master, linking a layout into it —
+ * is not recorded.
+ */
+declare class CopyPlan implements CopyTarget {
+  #private;
+  readonly api: string;
+  readonly linkable?: ReadonlySet<string> | undefined;
+  /** The parts the copy would add, in the order it would add them. */
+  readonly parts: PlannedPart[];
+  /** The relationships the copy would add to the parts it copies. */
+  readonly rels: PlannedRel[];
+  /** The notes master the copy would install in a deck that has none; later notes bind to it. */
+  notesMaster: string | undefined;
+  /**
+   * @param dest      the deck the import copies into
+   * @param api       the public method planning, which opens every error the plan throws
+   * @param linkable  the pages a jump link may land on when the traversal has no selection of its
+   *                  own: the page a rebinding import builds itself
+   */
+  constructor(dest: DeckTarget, api: string, linkable?: ReadonlySet<string> | undefined);
+  /** This plan's context for an import out of `ctx.source`, over the plan's copy of its registry. */
+  contextFor(ctx: ImportContext): ImportContext;
+  reservePartNameLike(templatePartName: string): string;
+  part(partName: string): unknown;
+  addPart(partName: string, contentType: string): void;
+  relationshipsFor(from: string): Pick<Relationships, 'add' | 'addWithId'>;
+}
+//#endregion
+//#region src/read/api/ops/rescale.d.ts
+/** How an import's rescale maps the source canvas onto the destination's. */
+type RescaleMode = 'fit' | 'stretch';
+//#endregion
 //#region src/read/api/presentation.d.ts
 declare class Presentation {
   #private;
@@ -4020,7 +4328,8 @@ declare class Presentation {
    * The deck-wide **legacy** comment-author registry (`p:cmAuthorLst` in
    * `ppt/commentAuthors.xml`), `[]` when the deck has no comments. Each slide's
    * {@link Slide.comments} resolves its `@authorId` against this list. The 2018
-   * modern comment authors (`ppt/authors.xml`) are a separate part, not decoded here.
+   * modern comment authors (`ppt/authors.xml`) are a separate part, read by
+   * {@link modernCommentAuthors}.
    */
   get commentAuthors(): CommentAuthor[];
   /**
@@ -4048,6 +4357,17 @@ declare class Presentation {
    * (→ `creator`)/`revision` setters.
    */
   get coreProperties(): CoreProperties;
+  /**
+   * The deck's extended document properties (`docProps/app.xml`): the producing
+   * application and its version, the company, and the flat `TitlesOfParts` vector.
+   * `{}` when the deck carries no extended-properties part. The read counterpart of
+   * the write-side `pptx.company` setter — the only one of the four this library
+   * writes from a caller's value; the other three it states about itself.
+   *
+   * A deliberate subset of the part: see {@link ExtendedProperties} for why the
+   * statistics (`Slides`, `Words`, `Paragraphs`, …) are not reported.
+   */
+  get appProperties(): ExtendedProperties;
   /**
    * The deck's user-defined custom document properties (`docProps/custom.xml`) as
    * `{ name, value }` pairs, each value typed from its `vt:` element (string,
@@ -4089,7 +4409,9 @@ declare class Presentation {
    * (its notes slide, slide-only media, charts/embeddings) that no remaining part
    * references is pruned too — recursively. Shared deck chrome (layout, master,
    * theme, …) is never pruned, so the deck stays renderable; removing every slide
-   * leaves a valid master/layout-only package (a template shell).
+   * leaves a valid master/layout-only package (a template shell). The slide also
+   * leaves every custom show and section it was in, which stay even when that
+   * empties them, as PowerPoint leaves them.
    *
    * Untouched parts stay byte-identical, matching the package fidelity contract.
    * Throws when there is no slide at `index`.
@@ -4120,10 +4442,15 @@ declare class Presentation {
    * master/layout with its theme references left symbolic, so it re-brands to the
    * destination palette — see {@link ImportSlideOptions}.
    *
-   * v1 limitations: by default the source slide size must equal this
-   * presentation's — pass `{ rescale: 'fit' | 'stretch' }` to rescale the imported
-   * geometry onto this deck's canvas instead (geometry only, not fonts/line
-   * widths). Source notes are dropped unless you pass `{ importNotes: true }`.
+   * By default the source slide size must equal this presentation's. Pass
+   * `{ rescale: 'fit' | 'stretch' }` to rescale the imported geometry onto this
+   * deck's canvas instead (geometry only, not fonts or line widths). Source notes
+   * are dropped unless you pass `{ importNotes: true }`.
+   *
+   * A jump link on the page must land on a page an earlier import from the same source already
+   * brought across, the rule {@link importSlides} applies to a batch: a link to any other page
+   * throws `import/unresolved-slide-link`. Like that check, a missing or unparseable source part
+   * is found before anything is copied, so a refused import leaves this deck unchanged.
    */
   importSlide(source: Presentation, index: number, options?: ImportSlideOptions): Slide;
   /**
@@ -4166,11 +4493,21 @@ declare class Presentation {
    * several requests gets its own copy of its notes each time, as of everything
    * else that page owns.
    *
+   * `embedFonts` and `rescale` travel per request as well, and both are whole-deck
+   * decisions wearing a per-page spelling, so the batch reconciles them before it
+   * moves anything. A source deck's embedded fonts are carried once when *any* of
+   * its requests asks for them (the list does not record which page uses which
+   * face, so there is nothing finer to carry), and the font parts are part of the
+   * up-front dry run like everything else. `rescale` must **agree** across every
+   * request naming one source: a `'copy'` import rescales the imported layout and
+   * master alongside the page, and those are shared, so a batch that rescaled one
+   * page of a source and not another would leave the second bound to a rescaled
+   * master. Disagreement is `import/rescale-conflict` rather than a silent pick.
+   *
    * Scope: pages come across under `'copy'` theme semantics (their own layout →
-   * master → theme subgraph, shared parts deduped via the copy registry).
-   * Embedded fonts are not carried, and sizes must match, since there is no batch
-   * spelling for `embedFonts` or `rescale`. Use {@link importSlide} when you need
-   * either of those.
+   * master → theme subgraph, shared parts deduped via the copy registry). There is
+   * still no batch spelling for `theme`, `carryMasterGraphics` or `remapLiterals`;
+   * use {@link importSlide} when you need one of those.
    */
   importSlides(requests: readonly ImportSlidesRequest[]): Slide[];
   /**
@@ -4200,8 +4537,9 @@ declare class Presentation {
    * `options.embedFonts` and table styles via `options.tableStyles`. By default a
    * grafted master is appended after the deck's existing masters; `options.primary`
    * moves the grafted masters to the front so the deck presents as their theme (see
-   * {@link ImportSlideMastersOptions}). The v1 limitation mirroring
-   * {@link importSlide} is that geometry is not rescaled.
+   * {@link ImportSlideMastersOptions}). Geometry is never rescaled: unlike
+   * {@link importSlide}, {@link importSlides} and {@link importShape}, this method
+   * takes no `rescale` option.
    */
   importSlideMasters(source: Presentation, options?: ImportSlideMastersOptions): ImportedSlideMaster[];
   /**
@@ -4299,6 +4637,28 @@ declare class Presentation {
    * relationship. Returns the new {@link Shape}s in `shapeIndices` order.
    */
   importShapes(target: Slide, source: Slide, shapeIndices: number[], options?: ImportShapeOptions): AnyShape[];
+  /**
+   * @internal Wire a new slide part into `p:sldIdLst` at position `at`, as the private
+   * method below does. Exposed for `presentation-imports.ts`; this one stays because
+   * {@link cloneSlide} and {@link appendSlides} wire their slides in through it too.
+   */
+  insertSlidePart(newPart: Part, at?: number): Slide;
+  /**
+   * @internal The parts whose geometry a rescale has already rewritten, and in which mode.
+   * Exposed for `presentation-imports.ts` as a live map the callee adds to — the memo is what
+   * makes a layout or master shared across repeated imports from one source scale exactly
+   * once, so like the copy registry it has to outlive the call that fills it.
+   */
+  get rescaledParts(): Map<string, RescaleMode>;
+  /**
+   * @internal Open an import out of `source`: this deck as the destination, paired with
+   * the copy registry for that package (created on first use). The registry is held on
+   * the class rather than in the context because it must outlive any one call — that is
+   * what makes a second import from the same source reuse the layout, master, theme, and
+   * media it already copied instead of duplicating them, and it is why the import bodies
+   * in `presentation-imports.ts` call back here rather than carrying it with them.
+   */
+  importContext(source: OpcPackage): ImportContext;
   /** Re-emit the package; untouched parts stay byte-identical (see `OpcPackage.save`). */
   save(): Promise<Uint8Array>;
 }
@@ -4856,6 +5216,33 @@ interface ImportSlidesRequest {
    * has none, exactly as `importSlide` and `appendSlides` do.
    */
   importNotes?: boolean;
+  /**
+   * Carry this request's *source deck's* embedded fonts across, as
+   * `importSlide`'s {@link ImportSlideOptions.embedFonts} does. Default false.
+   *
+   * Spelled per request for symmetry with the rest, but the carry itself is a
+   * whole-deck operation: `p:embeddedFontLst` does not record which page uses
+   * which face, so a source deck whose requests include even one `embedFonts`
+   * carries **all** of its faces, once. Merging into this deck de-dupes by
+   * typeface and face slot, so several sources embedding the same family
+   * contribute it once.
+   */
+  embedFonts?: boolean;
+  /**
+   * Rescale this page's geometry onto this deck's canvas when the source deck's
+   * slide size differs, as `importSlide`'s {@link ImportSlideOptions.rescale}
+   * does (`'fit'`/`true` preserves aspect ratio and centres; `'stretch'` fills).
+   * Default false, which keeps the batch's requirement that the sizes match.
+   *
+   * **Every request naming one source must give the same value.** A batch import
+   * uses `'copy'` theme semantics, so a rescale rewrites the imported layout and
+   * master shape trees as well as the page's, and those are shared between that
+   * source's pages: rescaling one page and not another would leave the second
+   * aligned against a master that had moved under it. A batch that disagrees is
+   * refused with `import/rescale-conflict` before anything is copied. Different
+   * sources are independent and may each choose.
+   */
+  rescale?: boolean | 'fit' | 'stretch';
 }
 /** Options for {@link Presentation.fromTemplate}. */
 interface FromTemplateOptions {
@@ -4868,5 +5255,5 @@ interface FromTemplateOptions {
   keepTemplateContentType?: boolean;
 }
 //#endregion
-export { TableCell as $, ShapeType as $t, CommentSchema as A, AutofitMode as At, ThemeFontScheme as B, ChildFrame as Bt, TransitionInfo as C, ChartLine as Ct, readTagsForPart as D, AutoShape as Dt, Tag as E, Picture as Et, Placeholder as F, Paragraph as Ft, isGraphicFrame as G, Glow as Gt, GroupShape as H, CustomGeometry as Ht, SlideLayout as I, Run as It, GraphicFrame as J, LineEnds as Jt, isGroupShape as K, InnerShadow as Kt, SlideMaster as L, RunHyperlink as Lt, ModernCommentAuthor as M, BulletDetail as Mt, NotesPlaceholder as N, BulletStyle as Nt, Comment as O, Shape as Ot, NotesSlide as P, LineSpacing as Pt, Table as Q, Reflection as Qt, Theme as R, TextFrame as Rt, Slide as S, ChartLegend as St, TransitionSpeed as T, Connector as Tt, isAutoShape as U, CustomGeometryPath as Ut, AnyShape as V, ConnectionSite as Vt, isConnector as W, GeometryCommand as Wt, CellBorders as X, Recolor as Xt, CellBorder as Y, OuterShadow as Yt, CellThreeD as Z, RecolorColor as Zt, CustomProperty as _, AxisNumberFormat as _t, ExtractedSlides as a, FillRect as an, Diagram as at, AddPictureOptions as b, ChartDataLabels as bt, ImportSlideMastersOptions as c, GradientFill as cn, DiagramDrawnShape as ct, ImportedSlideMaster as d, resolveColorElement as dn, DiagramPointType as dt, SoftEdge as en, TableCellBorderEdit as et, LayoutHandle as f, ColorTransform as fn, ChartEx as ft, CoreProperties as g, EmbeddedFontSlot as gn, ChartExSeries as gt, Presentation as h, ColorContext as hn, ChartExLegend as ht, ExtractedSlide as i, SlideBackground as in, TableCellEdge as it, ModernComment as j, BodyProperties as jt, CommentAuthor as k, ShapeHost as kt, ImportSlideOptions as l, GradientStop as ln, DiagramNode as lt, SlideSource as m, applyColorTransforms as mn, ChartExDataLabels as mt, EmbeddedFontFaceInfo as n, BackgroundFill as nn, ResolvedTableStyle as nt, FromTemplateOptions as o, PictureFill as on, DiagramConnection as ot, SlideSize as p, EffectiveColor as pn, ChartExAxis as pt, isPicture as q, LineEnd as qt, EmbeddedFontInfo as r, BackgroundSource as rn, TableConditionFlags as rt, ImportShapeOptions as s, PictureFillTile as sn, DiagramConnectionType as st, AppendSlidesOptions as t, PatternFill as tn, TableRow as tt, ImportSlidesRequest as u, ResolvedColor as un, DiagramPoint as ut, readCoreProperties as v, Chart as vt, TransitionInput as w, ChartSeries as wt, AddTextBoxOptions as x, ChartFill as xt, readCustomProperties as y, ChartAxis as yt, ThemeFontFace as z, AbsoluteFrame as zt };
-//# sourceMappingURL=presentation-types-CDjScsev.d.ts.map
+export { isGroupShape as $, ConnectionSite as $t, TransitionInput as A, EffectiveColor as An, Connector as At, NotesPlaceholder as B, BulletStyle as Bt, readCoreProperties as C, PlaceholderRef as Cn, Chart as Ct, AddTextBoxOptions as D, readColorRef as Dn, ChartLegend as Dt, AddPictureOptions as E, StyleFontRef as En, ChartFill as Et, Comment as F, AutofitMode as Ft, Theme as G, TextInheritance as Gt, Placeholder as H, LineSpacing as Ht, CommentAuthor as I, BodyProperties as It, AnyShape as J, TableConditionFlags as Jt, ThemeFontFace as K, ResolvedTableStyle as Kt, CommentSchema as L, TextFrame as Lt, TransitionSpeed as M, ColorContext as Mn, AutoShape as Mt, Tag as N, ThemeContext as Nn, Shape as Nt, Slide as O, resolveColorElement as On, ChartLine as Ot, readTagsForPart as P, ShapeHost as Pt, isGraphicFrame as Q, ChildFrame as Qt, ModernComment as R, Paragraph as Rt, ExtendedProperties as S, GeometrySource as Sn, AxisNumberFormat as St, readExtendedProperties as T, ResolvedFrame as Tn, ChartDataLabels as Tt, SlideLayout as U, Run as Ut, NotesSlide as V, InheritedRunProps as Vt, SlideMaster as W, TextContext as Wt, isAutoShape as X, AbsoluteFrame as Xt, GroupShape as Y, Hyperlink as Yt, isConnector as Z, AbsoluteFrameFailure as Zt, SlideSize as _, PictureFill as _n, ChartEx as _t, ExtractedChart as a, LineEnd as an, CellBorders as at, CoreProperties as b, GradientStop as bn, ChartExLegend as bt, ExtractedSlides as c, Recolor as cn, TableCellBorderEdit as ct, ImportSlideMastersOptions as d, SoftEdge as dn, DiagramConnection as dt, CustomGeometry as en, isPicture as et, ImportSlideOptions as f, BackgroundFill as fn, DiagramConnectionType as ft, OnlineMediaItem as g, FillRect as gn, DiagramPointType as gt, LayoutHandle as h, PatternFill as hn, DiagramPoint as ht, EmbeddedFontInfo as i, InnerShadow as in, CellBorder as it, TransitionSoundInfo as j, applyColorTransforms as jn, Picture as jt, TransitionInfo as k, ColorTransform as kn, ChartSeries as kt, FromTemplateOptions as l, Reflection as ln, TableCellEdge as lt, ImportedSlideMaster as m, SlideBackground as mn, DiagramNode as mt, AvMediaItem as n, GeometryCommand as nn, Table as nt, ExtractedNotes as o, LineEnds as on, CellThreeD as ot, ImportSlidesRequest as p, BackgroundSource as pn, DiagramDrawnShape as pt, ThemeFontScheme as q, TableCellTextStyle as qt, EmbeddedFontFaceInfo as r, Glow as rn, TableRow as rt, ExtractedSlide as s, OuterShadow as sn, TableCell as st, AppendSlidesOptions as t, CustomGeometryPath as tn, GraphicFrame as tt, ImportShapeOptions as u, ShapeType as un, Diagram as ut, SlideSource as v, PictureFillTile as vn, ChartExAxis as vt, readCustomProperties as w, ResolvedColor as wn, ChartAxis as wt, CustomProperty as x, ColorRef as xn, ChartExSeries as xt, Presentation as y, GradientFill as yn, ChartExDataLabels as yt, ModernCommentAuthor as z, BulletDetail as zt };
+//# sourceMappingURL=presentation-types-8jLQHI4M.d.ts.map