@shbernal/ts-pptx 0.0.1

package/dist/presentation-RGOiun5P.d.ts

@@ -0,0 +1,3249 @@
+import { t as CustomPropertyValue } from "./pres-5x1bjCzk.js";
+import { c as ImportSlideMastersOptions, d as LayoutHandle, f as SlideSize, l as ImportSlideOptions, o as FromTemplateOptions, p as SlideSource, r as EmbeddedFontInfo, s as ImportShapeOptions, t as AppendSlidesOptions, u as ImportedSlideMaster } from "./presentation-types-BVw0EknS.js";
+import { a as Part, i as Relationships, n as OpcPackage, o as Element, t as OpcInput } from "./package-CaOLXSNi.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 FlattenContext}.
+ */
+interface ColorContext {
+  clrMap: Map<string, string>;
+  clrScheme: Map<string, string>;
+}
+/**
+ * Everything {@link flattenSlide} needs from the slide's source theme subgraph:
+ * the {@link ColorContext} maps plus the live `a:fmtScheme` element (for
+ * style-matrix resolution).
+ */
+interface FlattenContext extends ColorContext {
+  fmtScheme: Element | null;
+  /**
+   * The slide's effective background inherited from the *source*
+   * `slideLayout`/`slideMaster` (the raw `p:bg` element), or `null` when the
+   * slide carries its own. Applied onto the slide before flattening so the
+   * background survives rebinding to the destination master. See
+   * {@link flattenSlide}.
+   */
+  inheritedBackground?: Element | null;
+  /**
+   * The source `slideLayout` root element, for resolving placeholder-inherited
+   * run colours (gap 1). Read-only — never mutated. `null`/absent disables the
+   * placeholder run-colour pass for the layout tier.
+   */
+  layoutRoot?: Element | null;
+  /**
+   * The source `slideMaster` root element, for resolving placeholder-inherited
+   * run colours via its placeholder `a:lstStyle` and `p:txStyles`. Read-only —
+   * never mutated.
+   */
+  masterRoot?: Element | null;
+  /**
+   * 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
+   * token unresolved.
+   */
+  fontScheme?: Element | null;
+  /**
+   * The notesMaster's `p:notesStyle` (a `CT_TextListStyle`), for resolving the
+   * character properties a *notes-body* run inherits when it sets none of its own.
+   * Only ever set on a notes context (see `resolveNotesColorContext`); on a slide
+   * context it is absent, so the slide placeholder chain (layout/master
+   * `a:lstStyle` → `p:txStyles`) is unaffected. It is the notes analogue of the
+   * master `p:txStyles` category style, keyed by level rather than placeholder
+   * type. Read-only — never mutated.
+   */
+  notesStyle?: Element | null;
+  /**
+   * The presentation's `p:defaultTextStyle` (a `CT_TextListStyle` from
+   * `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.
+   * Read-only — never mutated.
+   */
+  defaultTextStyle?: Element | null;
+}
+//#endregion
+//#region src/read/api/theme-context.d.ts
+/** Identifies a placeholder by its `p:ph` `type`/`idx` for inheritance lookups. */
+interface PlaceholderRef {
+  type: string | null;
+  idx: string;
+}
+/** Which tier of the slide → layout → master chain a {@link ResolvedFrame} resolved from. */
+type GeometrySource = 'own' | 'layout' | 'master';
+/** A shape's effective position and size in EMU, tagged with where it resolved from. */
+interface ResolvedFrame {
+  left: number;
+  top: number;
+  width: number;
+  height: number;
+  source: GeometrySource;
+}
+/**
+ * A DrawingML colour reference resolved against a slide's theme to a literal hex.
+ *
+ * `hex` is the **base** token colour and `transforms` reports the colour-transform
+ * children (`lumMod`/`lumOff`/`shade`/`tint`/`alpha`/…) in document order as
+ * `{ name, value }` pairs — both kept for traceability and for the
+ * `theme: 'preserve'` flatten path that re-emits the transforms verbatim.
+ *
+ * `effectiveHex` is the colour a renderer actually paints: `hex` with its
+ * `transforms` applied (see {@link applyColorTransforms}). Read this for the final
+ * rendered colour. `alpha` (0–1) is present only when an `alpha*` transform set an
+ * opacity.
+ */
+interface ResolvedColor {
+  hex: string;
+  transforms: {
+    name: string;
+    value: string | null;
+  }[];
+  effectiveHex: string;
+  alpha?: number;
+}
+/**
+ * Resolve a DrawingML colour *element* (`a:srgbClr`/`a:schemeClr`/`a:sysClr`)
+ * against `ctx` into a full {@link ResolvedColor} — base hex, raw transform list,
+ * and the `effectiveHex`/`alpha` after applying those transforms. `null` when the
+ * element cannot be made literal (unmapped token, or a colour model we do not
+ * resolve). Shared by the solid-fill and gradient-stop colour reads.
+ */
+declare function resolveColorElement(colorEl: Element | null, ctx: ColorContext): ResolvedColor | null;
+/** 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. */
+  color: ResolvedColor | null;
+  /** The face named by `a:fontRef/@idx` (`major`→`+mj-lt`, `minor`→`+mn-lt`) resolved through the theme `fontScheme`, or `null` for `idx="none"` / an unresolvable token. */
+  face: string | null;
+}
+//#endregion
+//#region src/read/api/gradient.d.ts
+/** One stop of a gradient fill (`a:gsLst/a:gs`), as read from a shape. */
+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 a scheme colour. */
+  color: string | null;
+  /** Theme colour token (`a:schemeClr/@val`, e.g. `accent1`), or `null` when the stop uses an explicit colour. */
+  schemeColor: string | null;
+  /**
+   * The stop's colour resolved against the slide theme **with its colour
+   * transforms applied** — the final rendered hex (the gradient counterpart of
+   * {@link import('./theme-context.js').ResolvedColor.effectiveHex}). `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`. */
+  alpha?: number;
+}
+/**
+ * A gradient fill (`a:gradFill`), as read from a container — the stops plus the
+ * geometry that a bare stop list omits. `linear` gradients carry an
+ * {@link GradientFill.angleDeg} (the `a:lin/@ang` direction); `radial`/`path`
+ * gradients carry a {@link GradientFill.path} shape (`a:path/@path`, e.g.
+ * `circle`). The angle is in **OOXML degrees** (clockwise from 3 o'clock), the
+ * same convention the write-side `GradientFillProps.angle` expects, so it
+ * round-trips directly.
+ */
+interface GradientFill {
+  /** `linear` (`a:lin`) or `path` (`a:path`, i.e. radial/rectangular). `null` when neither child is present. */
+  kind: 'linear' | 'path' | null;
+  /** Linear direction in OOXML degrees (clockwise from 3 o'clock), or `null` for a path gradient / when unset. */
+  angleDeg: number | null;
+  /** Path-gradient shape (`a:path/@path`: `circle`/`rect`/`shape`), or `null` for a linear gradient. */
+  path: string | null;
+  /** The gradient stops in document order. */
+  stops: GradientStop[];
+}
+//#endregion
+//#region src/read/api/picture-fill.d.ts
+/** A rectangle expressed as per-edge fractions (`a:srcRect`/`a:fillRect`), `0.1` = 10 %. */
+interface FillRect {
+  left: number;
+  top: number;
+  right: number;
+  bottom: number;
+}
+/**
+ * The tiling geometry of a tiled picture fill (`a:blipFill/a:tile`). Offsets stay
+ * in EMU (the attribute's own unit); scales are fractions (`1` = 100 %), matching
+ * the read API's convention elsewhere.
+ */
+interface PictureFillTile {
+  /** Horizontal tile offset in EMU (`@tx`), `0` when unset. */
+  offsetXEmu: number;
+  /** Vertical tile offset in EMU (`@ty`), `0` when unset. */
+  offsetYEmu: number;
+  /** Horizontal tile scale as a fraction (`@sx`, thousandths of a percent), `1` when unset. */
+  scaleX: number;
+  /** Vertical tile scale as a fraction (`@sy`), `1` when unset. */
+  scaleY: number;
+  /** Tile mirroring (`@flip`: `none`/`x`/`y`/`xy`), or `null` when unset. */
+  flip: string | null;
+  /** Tile alignment within the surface (`@algn`, e.g. `tl`), or `null` when unset. */
+  align: string | null;
+}
+/**
+ * A picture (image) fill (`a:blipFill`) read from a fill-bearing container. The
+ * image itself is {@link relId} / {@link partName}; the rest is the geometry a
+ * faithful replica needs — {@link mode} (`stretch` or `tile`), the source crop
+ * {@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
+ * 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.
+ */
+interface PictureFill {
+  /** Relationship id of the embedded image (`a:blip/@r:embed`), or `null` when the blip embeds none. */
+  relId: string | null;
+  /** Absolute partname of the embedded image, or `null` when it has no rel id / no resolvable target. */
+  partName: string | null;
+  /** `stretch` (`a:stretch`) or `tile` (`a:tile`); `null` when the fill states neither. */
+  mode: 'stretch' | 'tile' | null;
+  /** Source crop as per-edge fractions (`a:srcRect`), or `null` when absent. An explicit `<a:srcRect/>` reports zeros. */
+  srcRect: FillRect | null;
+  /** Stretch destination rect as per-edge fractions (`a:stretch/a:fillRect`), or `null` when absent. */
+  fillRect: FillRect | null;
+  /** Tiling geometry (`a:tile`), or `null` when the fill is not tiled. */
+  tile: PictureFillTile | null;
+  /** Blip opacity 0–1 (`a:blip/a:alphaModFix/@amt`), or `null` when the blip sets none. */
+  alpha: number | null;
+  /** DPI override the image is rendered at (`@dpi`), or `null` when unset. `0` means "use the image's own". */
+  dpi: number | null;
+  /** Whether the fill rotates with its shape (`@rotWithShape`), or `null` when unset. */
+  rotWithShape: boolean | null;
+}
+//#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';
+/**
+ * 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.
+ *
+ * The `image` variant keeps `relId`/`partName` at the top level — the fields
+ * callers already read — and adds the full {@link PictureFill} (stretch/tile
+ * geometry, crop, alpha) under `picture`.
+ */
+type BackgroundFill = {
+  type: 'solid';
+  color: ResolvedColor | null;
+} | {
+  type: 'gradient';
+  gradient: GradientFill;
+} | {
+  type: 'image';
+  picture: PictureFill;
+  relId: string | null;
+  partName: string | null;
+} | {
+  type: 'pattern';
+  preset: string | null;
+  foreground: ResolvedColor | null;
+  background: ResolvedColor | null;
+} | {
+  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`
+ * 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).
+ */
+type SlideBackground = {
+  type: 'solid';
+  source: BackgroundSource;
+  color: ResolvedColor | null;
+} | {
+  type: 'gradient';
+  source: BackgroundSource;
+  gradient: GradientFill;
+} | {
+  type: 'image';
+  source: BackgroundSource;
+  picture: PictureFill;
+  relId: string | null;
+  partName: string | null;
+} | {
+  type: 'pattern';
+  source: BackgroundSource;
+  preset: string | null;
+  foreground: ResolvedColor | null;
+  background: ResolvedColor | null;
+} | {
+  type: 'themeRef';
+  source: BackgroundSource;
+  idx: number | null;
+  color: ResolvedColor | null;
+  resolvedFill: BackgroundFill | null;
+} | {
+  type: 'none';
+  source: BackgroundSource;
+};
+//#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/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: FlattenContext;
+  /** The shape's resolved `p:style/a:fontRef` colour + face tier, or `null` when it has none. */
+  fontRef?: StyleFontRef | null;
+}
+/**
+ * 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.
+ */
+interface RunHyperlink {
+  /** 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`. */
+  targetPartName: string | null;
+  /** Navigation action token (`@action`, e.g. `ppaction://hlinksldjump`), or `null` when absent/empty. */
+  action: string | null;
+  /** Tooltip text (`@tooltip`), or `null` when absent/empty. */
+  tooltip: string | null;
+  /** The relationship id (`@r:id`) backing the link, or `null` when the link is action-only. */
+  relId: string | 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
+ * single-line height (`a:spcPct` — e.g. `percent: 150` for 1.5× spacing).
+ */
+type LineSpacing = {
+  type: 'points';
+  valuePt: number;
+} | {
+  type: 'percent';
+  percent: number;
+};
+/** One text run (`a:r`): a span of text with uniform character formatting. */
+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.
+   */
+  private readonly inheritedColor?;
+  /**
+   * 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.
+   */
+  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?;
+  /**
+   * 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?: FlattenContext | 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,
+  /**
+   * 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`.
+   */
+  relationships?: Relationships | undefined,
+  /**
+   * 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`.
+   */
+  fontRef?: (StyleFontRef | null) | undefined);
+  /** The run's text (`a:t`), verbatim — whitespace is not normalized. */
+  get text(): string;
+  set text(value: string);
+  /** Font size in points (`a:rPr/@sz` is hundredths of a point), or `null` if unset. */
+  get fontSizePt(): number | null;
+  set fontSizePt(value: number | null);
+  /** Bold (`a:rPr/@b`), or `null` when unset (inherited from style). */
+  get bold(): boolean | null;
+  set bold(value: boolean | null);
+  /** Italic (`a:rPr/@i`), or `null` when unset (inherited from style). */
+  get italic(): boolean | null;
+  set italic(value: boolean | null);
+  /** Underline style token (`a:rPr/@u`, e.g. `sng`), or `null` when unset. */
+  get underline(): string | null;
+  set underline(value: string | null);
+  /**
+   * Strikethrough token (`a:rPr/@strike`: `noStrike` | `sngStrike` |
+   * `dblStrike`), or `null` when unset (inherited from the style). Surfaced as
+   * the raw token — `sngStrike` is the writer's single-strike value.
+   */
+  get strike(): string | null;
+  /**
+   * Capitalization token (`a:rPr/@cap`: `none` | `small` | `all`), or `null`
+   * when unset. `small` renders small-caps, `all` renders all-caps.
+   */
+  get caps(): string | null;
+  /**
+   * Baseline shift as a percentage of the font size (`a:rPr/@baseline`, stored
+   * 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).
+   */
+  get baselinePct(): number | null;
+  /**
+   * Character spacing (tracking) in points (`a:rPr/@spc`, authored in hundredths
+   * of a point), or `null` when unset. Negative tightens. The read counterpart of
+   * the write-side `charSpacing` option.
+   */
+  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.
+   */
+  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`).
+   */
+  get hyperlink(): RunHyperlink | null;
+  /** Latin typeface name (`a:rPr/a:latin/@typeface`), or `null` when unset. */
+  get fontName(): string | null;
+  set fontName(value: string | null);
+  /** Explicit RGB fill colour as a 6-hex string (`a:solidFill/a:srgbClr/@val`), or `null`. */
+  get color(): string | null;
+  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;
+  set schemeColor(value: string | null);
+  /**
+   * The colour this run effectively renders, resolved against the owning slide's
+   * theme to a literal hex. It is the run's own solid fill
+   * ({@link color}/{@link schemeColor}) when set; otherwise the shape's
+   * `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.
+   * The returned {@link ResolvedColor} carries `effectiveHex` — the base colour with
+   * its child transforms (`lumMod`/`shade`/…) applied — for the final rendered colour.
+   */
+  get resolvedColor(): ResolvedColor | null;
+  /**
+   * The point size this run effectively renders. It is the run's own `@sz`
+   * ({@link fontSizePt}) when set; otherwise, for a run inside a placeholder, the
+   * size it inherits from the placeholder/list-style chain (paragraph `a:defRPr` →
+   * slide `a:lstStyle` → layout → master placeholder `a:lstStyle` → master
+   * `p:txStyles`). `null` when the run sets no size and inherits none — the
+   * resolved counterpart of {@link fontSizePt}, which reports only the run's own value.
+   */
+  get resolvedSizePt(): number | null;
+  /**
+   * The typeface this run effectively renders, resolved to a literal face name. It
+   * is the run's own `a:latin` ({@link fontName}) when set; otherwise the face named
+   * by the shape's `p:style/a:fontRef` (`idx` → theme major/minor font), then — for a
+   * run inside a placeholder — the face it inherits from the placeholder/list-style
+   * chain, then the presentation's `p:defaultTextStyle`. A `+mj-*`/`+mn-*`
+   * major/minor theme-font token — on the run itself or reached through the chain —
+   * is resolved through the theme `fontScheme` to its concrete face. `null` when the
+   * run names no face and inherits none, or a token cannot be resolved — the resolved
+   * counterpart of {@link fontName}, which reports the raw `@typeface` (possibly a token).
+   */
+  get resolvedFontFace(): string | null;
+  /**
+   * Whether this run effectively renders bold. It is the run's own `@b`
+   * ({@link bold}) when set; otherwise, for a run inside a placeholder, the bold
+   * state it inherits from the placeholder/list-style chain (paragraph `a:defRPr` →
+   * slide `a:lstStyle` → layout → master placeholder `a:lstStyle` → master
+   * `p:txStyles`). `null` when the run sets no `@b` and inherits none — the
+   * resolved counterpart of {@link bold}, which reports only the run's own value.
+   */
+  get resolvedBold(): boolean | null;
+  /** Escape hatch: the underlying `a:r` 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 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?: FlattenContext | 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);
+  /** 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. */
+  get level(): number;
+  /**
+   * Horizontal alignment token (`a:pPr/@algn`: `l` | `ctr` | `r` | `just` |
+   * `dist` | `thaiDist`), or `null` when unset (inherited from the list style).
+   */
+  get align(): string | null;
+  /**
+   * Space before the paragraph in points (`a:pPr/a:spcBef/a:spcPts/@val` is
+   * hundredths of a point), or `null` when unset or expressed as a percentage
+   * (`a:spcPct`, which has no fixed point value).
+   */
+  get spaceBeforePt(): number | null;
+  /** Space after the paragraph in points; see {@link spaceBeforePt} for the percentage caveat. */
+  get spaceAfterPt(): number | null;
+  /**
+   * The paragraph's line spacing (`a:pPr/a:lnSpc`), as an exact point height
+   * (`a:spcPts`) or a percentage of the single-line height (`a:spcPct`), or
+   * `null` when unset (inherited from the list style). See {@link LineSpacing}.
+   */
+  get lineSpacing(): LineSpacing | null;
+  /** Left margin of the paragraph in points (`a:pPr/@marL` is EMU; 12700 EMU = 1pt), or `null` when unset. */
+  get marginLeftPt(): number | null;
+  /** First-line indent in points (`a:pPr/@indent` is EMU; negative for a hanging indent), or `null` when unset. */
+  get indentPt(): number | null;
+  /**
+   * Bullet description for this paragraph, derived from the `a:pPr` bullet
+   * children, or `null` when unset (inherited from the list style):
+   * - `'none'`          — explicit `a:buNone` (bullet suppressed)
+   * - `'char:•'`        — `a:buChar/@char` (the literal glyph follows the colon)
+   * - `'autoNum:arabicPeriod'` — `a:buAutoNum/@type` (auto-numbered)
+   */
+  get bullet(): string | null;
+  /**
+   * The paragraph's text: run (`a:r`) and field (`a:fld`) text concatenated in
+   * document order, with each line break (`a:br`) rendered as `\n`.
+   */
+  get text(): string;
+  /** Escape hatch: the underlying `a:p` 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;
+}
+/** A shape's text frame (`p:txBody`): an ordered list of paragraphs. */
+/**
+ * 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
+ * — the difference between a label that clears a left rail and one that overlaps
+ * it. Only **explicitly set** attributes are reported; an absent inset means the
+ * PowerPoint default (`lIns`/`rIns` = 0.1", `tIns`/`bIns` = 0.05").
+ */
+interface BodyProperties {
+  /** Text direction (`@vert`: `horz`/`vert`/`vert270`/`eaVert`/`wordArtVert`…), or `null` when horizontal/unset. */
+  vert: string | null;
+  /** Vertical anchor (`@anchor`: `t`/`ctr`/`b`), or `null` when unset (defaults to top). */
+  anchor: string | null;
+  /** Wrap mode (`@wrap`: `square`/`none`), or `null` when unset. */
+  wrap: string | null;
+  /** Explicitly-set text insets in points (`@lIns`/`@rIns`/`@tIns`/`@bIns` ÷ 12700); a missing side uses the PowerPoint default. */
+  insetsPt: {
+    left?: number;
+    right?: number;
+    top?: number;
+    bottom?: number;
+  };
+}
+/**
+ * A text frame's vertical-autofit mode, read from its `a:bodyPr` autofit child:
+ * - `'none'`       — `a:noAutofit`, or no autofit child at all (the box has a fixed
+ *                    size and text can overflow); write-side `fit: 'none'`.
+ * - `'normAutofit'`— `a:normAutofit` (shrink text to fit); write-side `fit: 'shrink'`.
+ * - `'spAutoFit'`  — `a:spAutoFit` (resize the shape to fit text); write-side `fit: 'resize'`.
+ */
+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?: FlattenContext | 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);
+  /** Paragraphs (`a:p`) in document order. */
+  get paragraphs(): Paragraph[];
+  /**
+   * The frame's body properties (`a:bodyPr`: insets, anchor, vertical text), or
+   * `null` when there is no `a:bodyPr`. Only explicitly-set insets are reported
+   * (a missing side is the PowerPoint default — see {@link BodyProperties}).
+   */
+  get bodyProperties(): BodyProperties | null;
+  /**
+   * The effective vertical anchor (`t`/`ctr`/`b`): the frame's own
+   * `a:bodyPr/@anchor` when set, else the anchor it inherits from its
+   * layout → master placeholder `a:bodyPr`. `null` when nothing in the chain sets
+   * one (PowerPoint then defaults to top). Unlike {@link bodyProperties}'s
+   * `anchor` (own attribute only), this surfaces the inherited anchor a
+   * placeholder title relies on — the difference between a top- and
+   * centre-anchored title that own-attribute reads alone cannot see.
+   */
+  get resolvedAnchor(): string | null;
+  /**
+   * The frame's vertical-autofit mode (`a:bodyPr` autofit child), or `null` when
+   * there is no `a:bodyPr`. A `bodyPr` with no autofit child — or an explicit
+   * `a:noAutofit` — reads `'none'`. See {@link AutofitMode}. This is the deep-model
+   * counterpart of `inspectPptx`'s per-shape `autofit`; unlike the shallow surface
+   * it hangs off the navigable text frame.
+   */
+  get autofit(): AutofitMode | null;
+  /**
+   * The baked shrink scale of a `normAutofit` frame as a percent (62.5 = 62.5%),
+   * or `null` when the frame has no `a:normAutofit` or bakes no scale. A bare
+   * `<a:normAutofit/>` (write-side `fit: 'shrink'`) carries no scale — PowerPoint
+   * computes it on edit and draws at 100% until then — so it too reads `null`; an
+   * explicit scale comes from `fit: { type: 'shrink', fontScale }`.
+   */
+  get autofitFontScale(): number | null;
+  /**
+   * The baked line-spacing reduction of a `normAutofit` frame as a percent
+   * (`a:normAutofit/@lnSpcReduction` ÷ 1000), or `null` when unset. The companion
+   * to {@link autofitFontScale} (write-side `fit: { type: 'shrink', lnSpcReduction }`).
+   */
+  get autofitLineSpaceReduction(): number | null;
+  /** All paragraph text joined by `\n` (mirrors python-pptx `TextFrame.text`). */
+  get text(): string;
+  /**
+   * Replace the frame's text with a single paragraph and run, preserving the
+   * character formatting (`a:rPr`) of the frame's first existing run when there
+   * is one. For multiple runs or per-run formatting, edit
+   * `paragraphs[].runs[]` directly.
+   */
+  set text(value: string);
+  /** Escape hatch: the underlying `p:txBody` 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/types.d.ts
+/** Discriminator for the concrete `Shape` subclass. */
+type ShapeType = 'autoShape' | 'picture' | 'connector' | 'graphicFrame' | 'group';
+/** One end of a connector/line (`a:ln/a:headEnd` or `a:tailEnd`), as read from a shape. */
+interface LineEnd {
+  /** Arrowhead type (`@type`: `none`/`triangle`/`stealth`/`diamond`/`oval`/`arrow`). */
+  type: string;
+  /** Width class (`@w`: `sm`/`med`/`lg`), or `null` when unset. */
+  width: string | null;
+  /** Length class (`@len`: `sm`/`med`/`lg`), or `null` when unset. */
+  length: string | null;
+}
+/** Both ends of a shape's line/border, when either carries an arrowhead. */
+interface LineEnds {
+  head: LineEnd | null;
+  tail: LineEnd | null;
+}
+/**
+ * One bound end of a connector (`p:nvCxnSpPr/p:cNvCxnSpPr/a:stCxn` or `a:endCxn`),
+ * as read. A connector authored with `startShape`/`endShape` attaches each end to
+ * a shape by that shape's `p:cNvPr/@id` plus a connection-site index; an unbound
+ * end (the writer emits a bare `p:cNvCxnSpPr`) reports no site at all — see
+ * {@link Connector.startConnection}. This is the read counterpart of the write
+ * API's `startShape`/`startShapeIdx` split, which binds by `objectName` and
+ * resolves the name → id at serialize time.
+ */
+interface ConnectionSite {
+  /** The bound shape's drawing id (`@id`, i.e. its `p:cNvPr/@id`). */
+  shapeId: number;
+  /** Connection-site index on the bound shape (`@idx`; 0-based, preset-dependent). */
+  siteIndex: number;
+  /**
+   * The bound shape resolved to a read-model shape via {@link Slide.shapeByIdDeep},
+   * which descends into groups — so a connector bound to a shape nested in a group
+   * resolves the same as one bound to a top-level shape. `null` only when no shape
+   * anywhere on the slide carries that id (a genuinely dangling binding), which is
+   * faithful degradation and does not throw.
+   */
+  boundShape: AnyShape | null;
+}
+/**
+ * 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.
+ */
+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;
+  /** Blur radius in points (`@blurRad` ÷ 12700), or `undefined` when unset. */
+  blurPt?: number;
+  /** Offset distance in points (`@dist` ÷ 12700), or `undefined` when unset. */
+  offsetPt?: number;
+  /** Offset direction in degrees, clockwise from 3 o'clock (`@dir` ÷ 60000), or `undefined` when unset. */
+  angleDeg?: number;
+}
+/**
+ * A shape's inner shadow (`spPr/a:effectLst/a:innerShdw`), resolved against the
+ * slide theme. Identical fields to {@link OuterShadow} — CT_InnerShadowEffect
+ * carries the same `blurRad`/`dist`/`dir` + colour — but a distinct type so a
+ * consumer can tell an inset shadow from a drop shadow. Distances in points,
+ * 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;
+  /** Blur radius in points (`@blurRad` ÷ 12700), or `undefined` when unset. */
+  blurPt?: number;
+  /** Offset distance in points (`@dist` ÷ 12700), or `undefined` when unset. */
+  offsetPt?: number;
+  /** Offset direction in degrees, clockwise from 3 o'clock (`@dir` ÷ 60000), or `undefined` when unset. */
+  angleDeg?: number;
+}
+/**
+ * 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.
+ */
+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;
+  /** Glow radius in points (`@rad` ÷ 12700), or `undefined` when unset. */
+  radiusPt?: number;
+}
+/**
+ * A shape's reflection effect (`spPr/a:effectLst/a:reflection`) — a mirrored fade
+ * beneath the shape. This library's writer authors none, so this is a **read-only**
+ * surface: a consumer that finds one should carry the part verbatim rather than
+ * regenerate it. Only the attributes a faithful replica needs are decoded —
+ * distances in points (÷ 12700), directions in degrees (÷ 60000), and the start/end
+ * alpha and position pairs as 0–1 fractions (the `1000`ths-of-a-percent source
+ * ÷ 100000). All fields are optional; an attribute absent from the source is omitted.
+ */
+interface Reflection {
+  /** Blur radius in points (`@blurRad` ÷ 12700). */
+  blurPt?: number;
+  /** Start opacity 0–1 (`@stA` ÷ 100000). */
+  startAlpha?: number;
+  /** Start position along the reflection 0–1 (`@stPos` ÷ 100000). */
+  startPos?: number;
+  /** End opacity 0–1 (`@endA` ÷ 100000). */
+  endAlpha?: number;
+  /** End position along the reflection 0–1 (`@endPos` ÷ 100000). */
+  endPos?: number;
+  /** Offset distance in points (`@dist` ÷ 12700). */
+  distPt?: number;
+  /** Offset direction in degrees (`@dir` ÷ 60000). */
+  angleDeg?: number;
+  /** Fade direction in degrees (`@fadeDir` ÷ 60000). */
+  fadeAngleDeg?: number;
+}
+/**
+ * A shape's soft-edge effect (`spPr/a:effectLst/a:softEdge`) — a feathered border.
+ * Like {@link Reflection}, the writer authors none, so carry it verbatim. `@rad`
+ * (the feather radius) ÷ 12700 → points.
+ */
+interface SoftEdge {
+  /** Feather radius in points (`@rad` ÷ 12700). */
+  radiusPt: number;
+}
+/**
+ * A shape's pattern fill (`spPr/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 slide theme (a scheme token → literal hex) the same
+ * way {@link Shape.resolvedFill} resolves a solid fill.
+ */
+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;
+}
+/**
+ * One segment of a custom-geometry path (`a:path`), as read from a shape. The
+ * command verbs mirror the write-side `GeometryPoint` DSL (`src/types/`)
+ * so a consumer can map a `GeometryCommand[]` to `GeometryPoint[]` one-to-one.
+ *
+ * Coordinates (`x`/`y`/`x1`…) are raw path-unit integers in the path's own
+ * `0..w` / `0..h` space (see {@link CustomGeometryPath.w}); they are not EMU and
+ * must be scaled by the consumer against the shape's box. `arcTo` angles are in
+ * **degrees** (the raw `60000`ths-of-a-degree values divided by 60000), matching
+ * the write DSL's degree input.
+ */
+type GeometryCommand = {
+  cmd: 'moveTo';
+  x: number;
+  y: number;
+} | {
+  cmd: 'lnTo';
+  x: number;
+  y: number;
+} | {
+  cmd: 'cubicBezTo';
+  x1: number;
+  y1: number;
+  x2: number;
+  y2: number;
+  x: number;
+  y: number;
+} | {
+  cmd: 'quadBezTo';
+  x1: number;
+  y1: number;
+  x: number;
+  y: number;
+} | {
+  cmd: 'arcTo';
+  wR: number;
+  hR: number;
+  stAng: number;
+  swAng: number;
+} | {
+  cmd: 'close';
+};
+/** One `<a:path>` of a custom geometry, with its path-unit viewport and render attrs. */
+interface CustomGeometryPath {
+  /** Path-unit width (`a:path/@w`); the `x` denominator for this path's coords. Default `0`. */
+  w: number;
+  /** Path-unit height (`a:path/@h`); the `y` denominator for this path's coords. Default `0`. */
+  h: number;
+  /** Fill mode (`a:path/@fill`, `ST_PathFillMode`, e.g. `norm`/`none`/`lighten`). Default `norm`. */
+  fill: string;
+  /** Whether the path is stroked (`a:path/@stroke`). Default `true`. */
+  stroke: boolean;
+  /** The path's segments in document order — order *is* the geometry. */
+  commands: GeometryCommand[];
+}
+/**
+ * Custom freeform geometry (`spPr/a:custGeom/a:pathLst`), as read from a shape.
+ * Faithfully exposes every `a:path` rather than flattening to a single command
+ * list: the schema allows repeatable `a:path`, each with independent
+ * `fill`/`stroke`. Desktop PowerPoint's own freeforms only ever emit one
+ * `a:path` (a hole is one path with two `moveTo`…`close` contours), but
+ * multi-`a:path` input is schema-legal (e.g. SVG import) and preserved here.
+ */
+interface CustomGeometry {
+  paths: CustomGeometryPath[];
+}
+/** A shape's resolved position and size in slide-absolute EMU. */
+interface AbsoluteFrame {
+  left: number;
+  top: number;
+  width: number;
+  height: number;
+  /** Effective clockwise rotation in degrees after composing enclosing group rotations. */
+  rotation: number;
+  /** Effective horizontal flip after XOR-composing enclosing group flips. */
+  flipH: boolean;
+  /** Effective vertical flip after XOR-composing enclosing group flips. */
+  flipV: boolean;
+}
+/**
+ * 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.
+ */
+type Recolor = {
+  kind: 'duotone';
+  stops: RecolorColor[];
+} | {
+  kind: 'clrChange';
+  from: RecolorColor | null;
+  to: RecolorColor | null;
+} | {
+  kind: 'grayscale';
+} | {
+  kind: 'biLevel';
+  threshold: number | null;
+} | {
+  kind: 'alphaModFix';
+  amount: number;
+};
+//#endregion
+//#region src/read/api/shapes/base.d.ts
+/** Common base for every shape in a slide's shape tree. */
+declare abstract class Shape {
+  #private;
+  protected readonly element: Element;
+  readonly slide: Slide;
+  constructor(element: Element, slide: Slide);
+  /** Which concrete shape kind this is. */
+  abstract readonly shapeType: ShapeType;
+  /** The transform element (`a:xfrm` or `p:xfrm`) carrying this shape's geometry, or `null` if inherited. */
+  protected abstract xfrm(): Element | null;
+  /** The transform element, creating it (and its container) in document order if absent. */
+  protected abstract getOrAddXfrm(): Element;
+  /**
+   * Mark the owning slide part dirty so `save()` reserializes it. Public
+   * because {@link element_} hands out the live DOM node: the hatch and the
+   * obligation that comes with it belong on the same object.
+   */
+  markDirty(): void;
+  /** Drawing id (`p:cNvPr/@id`), or `null` if absent. */
+  get id(): number | null;
+  /** Shape name (`p:cNvPr/@name`), or `''` if unnamed. */
+  get name(): string;
+  /**
+   * 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
+   * rendered — decks use it as a fallback layer (e.g. a duotone-recolour source
+   * sitting behind the visible icon), so a faithful reader must distinguish it
+   * from the drawn shapes.
+   */
+  get hidden(): boolean;
+  /**
+   * The shape's alt-text description (`p:cNvPr/@descr`), or `null` when unset.
+   * This is the accessibility primitive a screen reader announces; an audit or
+   * accessible-export tool reads it here. Distinct from {@link name}, which is
+   * the authoring-time shape name and is never surfaced to assistive tech.
+   */
+  get description(): string | null;
+  /**
+   * Set (or clear, with `''`) the alt-text description. Requires the shape's
+   * `p:cNvPr` to exist, which every well-formed shape carries.
+   */
+  set description(value: string);
+  /**
+   * The shape's alt-text title (`p:cNvPr/@title`), or `null` when unset. Modern
+   * PowerPoint no longer exposes a separate title field (only description +
+   * "mark as decorative"), so this is usually `null`; it survives on decks
+   * authored by older PowerPoint or other producers that still write it.
+   */
+  get title(): string | null;
+  /**
+   * Whether the shape is flagged **decorative** (`p:cNvPr/a:extLst/a:ext`
+   * uri `{C183D7F6-…}` / `adec:decorative@val`), PowerPoint's "Mark as
+   * decorative" — a purely visual element assistive tech should skip. `false`
+   * when the extension is absent. A decorative shape typically has no
+   * {@link description}; the two are alternatives, not companions.
+   */
+  get isDecorative(): boolean;
+  /** Left edge in EMU (`a:off/@x`), or `null` when the shape has no own transform. */
+  get left(): number | null;
+  set left(value: number);
+  /** Top edge in EMU (`a:off/@y`), or `null` when the shape has no own transform. */
+  get top(): number | null;
+  set top(value: number);
+  /** Width in EMU (`a:ext/@cx`), or `null` when the shape has no own transform. */
+  get width(): number | null;
+  set width(value: number);
+  /** Height in EMU (`a:ext/@cy`), or `null` when the shape has no own transform. */
+  get height(): number | null;
+  set height(value: number);
+  /**
+   * This shape's effective position and size in EMU: its own `a:xfrm` when it has
+   * one ({@link left}/{@link top}/{@link width}/{@link height}, tagged
+   * `source: 'own'`); otherwise, for a placeholder, the geometry it inherits from
+   * the matching layout placeholder, else the master's (tagged accordingly). A
+   * non-placeholder shape with no own transform has nothing to inherit from and
+   * reads `null`, as does a placeholder whose layout/master chain defines no
+   * matching geometry either.
+   *
+   * The writer always emits an explicit `a:xfrm` on every placeholder it authors,
+   * so `source` reads `'own'` for every authored deck; `'layout'`/`'master'` is
+   * the case an *imported* deck exercises, when PowerPoint itself leaves a
+   * placeholder's geometry to inherit.
+   */
+  get resolvedFrame(): ResolvedFrame | null;
+  /**
+   * Clockwise rotation in degrees (`a:xfrm/@rot` ÷ 60000), or `null` when the
+   * shape has no own transform. A present xfrm with no `@rot` reads as `0`, so
+   * — mirroring {@link left}/{@link top}/{@link width}/{@link height} — `null`
+   * ("inherits layout geometry") stays distinct from `0` ("has a transform, not
+   * rotated"). The value is faithful to the XML and not normalised to a signed
+   * range, so a `@rot` past 360° (e.g. a negative angle stored as `19216344`)
+   * reads back greater than 360. This is the shape's own orientation; use
+   * {@link absoluteFrame} when you need the effective orientation after
+   * enclosing group transforms are composed.
+   */
+  get rotation(): number | null;
+  /**
+   * Whether the shape is flipped horizontally (`a:xfrm/@flipH`); `false` when
+   * unset or when the shape has no own transform. This is the shape's own
+   * horizontal flip; use {@link absoluteFrame} for the effective value after
+   * enclosing group transforms are composed.
+   */
+  get flipH(): boolean;
+  /**
+   * Whether the shape is flipped vertically (`a:xfrm/@flipV`); `false` when
+   * unset or when the shape has no own transform. This is the shape's own
+   * vertical flip; use {@link absoluteFrame} for the effective value after
+   * enclosing group transforms are composed.
+   */
+  get flipV(): boolean;
+  /**
+   * This shape's position, size, and effective orientation in **slide-absolute**
+   * EMU/degrees, composing every enclosing group transform.
+   *
+   * {@link left}/{@link top}/{@link width}/{@link height} report a group child's
+   * geometry in its group's child coordinate space (`a:chOff`/`a:chExt`), which is
+   * not directly placeable on the slide. This getter walks the `p:grpSp` ancestor
+   * chain outward, mapping the box through each group's
+   * `off + (p - chOff) * (ext / chExt)` transform, then composing group flips and
+   * rotations about the group centre. For a shape already at slide level the box
+   * equals its own `{ left, top, width, height }`, while `rotation`/`flipH`/`flipV`
+   * equal the shape's own transform values.
+   *
+   * `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.
+   *
+   * 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;
+  /** 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;
+  /** 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);
+  /** Theme colour token when the fill is a scheme colour (`a:solidFill/a:schemeClr/@val`, e.g. `accent2`), or `null`. */
+  get fillSchemeColor(): string | null;
+  set fillSchemeColor(value: string | null);
+  /**
+   * Set an explicit `<a:noFill/>` on the shape — a transparent surface. This is
+   * distinct from clearing the fill (`fillColor = null`), which removes the
+   * `a:solidFill` and lets the fill inherit from the shape's style/placeholder.
+   */
+  noFill(): void;
+  /** Explicit RGB line/border colour (`spPr/a:ln/a:solidFill/a:srgbClr/@val`), or `null`. */
+  get lineColor(): string | null;
+  set lineColor(value: string | null);
+  /** Theme colour token when the line is a scheme colour (`a:ln/a:solidFill/a:schemeClr/@val`), or `null`. */
+  get lineSchemeColor(): string | null;
+  set lineSchemeColor(value: string | null);
+  /** Line/border width in points (`spPr/a:ln/@w` is EMU; 12700 EMU = 1pt), or `null` when unset. */
+  get lineWidthPt(): number | null;
+  /**
+   * The line/border dash style (`spPr/a:ln/a:prstDash/@val`), e.g. `'dash'`,
+   * `'lgDashDot'`, `'sysDot'`, or `null` when the line is solid/unset. A faithful
+   * replica of dashed dividers and dashed card borders needs this — it is
+   * otherwise invisible in {@link lineColor}/{@link lineWidthPt} alone.
+   */
+  get lineDash(): string | null;
+  /**
+   * `true` when the shape sets an explicit no-line (`spPr/a:ln/a:noFill`) — a
+   * deliberately border-less shape. Distinct from simply having no `a:ln`
+   * (an inherited line), which {@link resolvedLine} cannot tell apart: both
+   * report `null`. A replica that relies on a shadow instead of a border needs
+   * to know the border was explicitly suppressed.
+   */
+  get lineNoFill(): boolean;
+  /**
+   * Preset geometry name (`spPr/a:prstGeom/@prst`, e.g. `rect`), or `null` for
+   * custom geometry or none. Not an auto-shape-only property: PowerPoint gives a
+   * picture and a connector a preset geometry too (a `p:pic` is `rect` unless it
+   * has been cropped to a shape), so it reads off whichever properties element
+   * this kind carries. A group has no geometry of its own and reads `null`.
+   */
+  get presetGeometry(): string | 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
+   * adjust handles (or uses custom geometry). Pair with {@link presetGeometry}.
+   */
+  get adjustValues(): Record<string, string>;
+  /**
+   * Gradient fill stops (`spPr/a:gradFill/a:gsLst/a:gs`) in document order, or
+   * `null` when the shape's fill is not a gradient. Each stop carries its
+   * position (0–1, from `@pos` in thousandths of a percent) and either an
+   * explicit `color` (hex) or a `schemeColor` token, mirroring the
+   * {@link fillColor} / {@link fillSchemeColor} split for solid fills.
+   */
+  get gradientStops(): GradientStop[] | null;
+  /**
+   * The shape's gradient fill with its geometry (`spPr/a:gradFill`), or `null`
+   * when the fill is not a gradient. Unlike {@link gradientStops} (stops only),
+   * this also carries the linear {@link GradientFill.angleDeg} or the
+   * {@link GradientFill.path} shape — the geometry a faithful replica needs and
+   * which the bare stop list omits.
+   */
+  get gradientFill(): GradientFill | null;
+  /**
+   * The shape's line/border **gradient** stroke (`spPr/a:ln/a:gradFill`), or
+   * `null` when the line is a solid, absent, or inherited border (see
+   * {@link resolvedLine}). The line counterpart of {@link gradientFill}: a
+   * gradient-stroked connector — common for faded process arrows in styled decks
+   * — otherwise surfaces only its {@link lineWidthPt}, dropping the colour
+   * entirely, so a replica cannot reproduce the stroke.
+   */
+  get lineGradient(): GradientFill | null;
+  /**
+   * The shape's line/connector arrowheads (`a:ln/a:headEnd` + `a:tailEnd`), or
+   * `null` when neither end carries one. Essential for replicating connectors,
+   * whose dot/arrow ends are otherwise invisible in the geometry.
+   */
+  get lineEnds(): LineEnds | null;
+  /**
+   * The shape's outer drop shadow (`spPr/a:effectLst/a:outerShdw`), resolved
+   * against the slide theme, or `null` when the shape has no outer shadow. The
+   * soft brand shadows the eye reads as "floating" panels live here and are
+   * invisible in geometry/fill alone.
+   */
+  get shadow(): OuterShadow | null;
+  /**
+   * The shape's **inner** shadow (`spPr/a:effectLst/a:innerShdw`), resolved against
+   * the slide theme, or `null` when the shape has no inner shadow. The inset
+   * counterpart of {@link shadow}: the write-side `shadow: { type: 'inner' }`
+   * emits it, and it is invisible in geometry/fill alone.
+   */
+  get innerShadow(): InnerShadow | null;
+  /**
+   * The shape's glow halo (`spPr/a:effectLst/a:glow`), resolved against the slide
+   * 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.
+   */
+  get glow(): Glow | null;
+  /**
+   * The shape's reflection (`spPr/a:effectLst/a:reflection`), or `null` when it has
+   * none. Read-only: this library authors no reflection, so a replica should carry
+   * the part rather than regenerate it — see {@link Reflection}.
+   */
+  get reflection(): Reflection | null;
+  /**
+   * The shape's soft (feathered) edge (`spPr/a:effectLst/a:softEdge`), or `null`
+   * when it has none. Read-only like {@link reflection}: carry, don't regenerate.
+   */
+  get softEdge(): SoftEdge | null;
+  /**
+   * The shape's pattern (hatch) fill (`spPr/a:pattFill`), or `null` when the fill
+   * is not a pattern. Surfaces the {@link PatternFill.preset} name and both
+   * colours resolved against the slide theme — the pattern counterpart of
+   * {@link resolvedFill}, which reports `null` for a non-solid fill and so drops a
+   * hatched surface entirely.
+   */
+  get patternFill(): PatternFill | null;
+  /**
+   * The shape's picture (image) fill (`spPr/a:blipFill`), or `null` when the fill
+   * is not a picture. The image-fill counterpart of {@link patternFill}: a shape
+   * whose *surface* is an image is not a {@link Picture} — it is an autoShape with
+   * a blip fill — and {@link resolvedFill} reports `null` for one, so without this
+   * an image-filled shape reads as unfilled. Carries the embedded image
+   * ({@link PictureFill.relId}/{@link PictureFill.partName}) plus the stretch/tile
+   * geometry.
+   */
+  get pictureFill(): PictureFill | null;
+  /**
+   * The shape's solid fill resolved against the slide's theme
+   * ({@link Slide.themeContext}) to a literal hex — the resolved counterpart of
+   * {@link fillColor}/{@link fillSchemeColor}, which report the raw reference.
+   * `null` when the shape has no `a:solidFill` (a gradient/none/inherited fill)
+   * or the colour cannot be made literal. The returned {@link ResolvedColor}
+   * carries the base `hex` and raw transforms, and `effectiveHex` — the base with
+   * its colour transforms (`lumMod`/`shade`/…) applied (read that for the final
+   * rendered colour).
+   *
+   * When the shape carries no explicit `spPr` fill choice, this falls back to the
+   * fill the shape inherits from its `p:style` `a:fillRef` (the theme style
+   * matrix), resolved the same way the `theme: 'preserve'` flatten path bakes it.
+   */
+  get resolvedFill(): ResolvedColor | null;
+  /**
+   * The shape's line/border solid fill resolved against the slide's theme to a
+   * literal hex — the resolved counterpart of {@link lineColor}/{@link lineSchemeColor}.
+   * `null` when the shape has no `a:ln/a:solidFill` or it cannot be made literal.
+   * 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).
+   */
+  get resolvedLine(): ResolvedColor | null;
+  /** Whether this shape can hold text (only `p:sp` does in this read model). */
+  get hasTextFrame(): boolean;
+  /** The shape's text frame, or `null` when it cannot hold text. */
+  get textFrame(): TextFrame | null;
+  /** Convenience: the shape's full text, or `''` if it has none. */
+  get text(): string;
+  /**
+   * Convenience: replace the shape's text with a single run, preserving the
+   * first existing run's formatting (see {@link TextFrame.text}). Throws when the
+   * shape has no text frame. For multiple runs or per-run formatting, edit
+   * `textFrame.paragraphs[].runs[]` directly.
+   */
+  set text(value: string);
+  /**
+   * This shape's placeholder identity (`p:ph` `type`/`idx`), or `null` when it is
+   * not a placeholder. Only `p:sp` shapes can be placeholders, so the base
+   * implementation always returns `null`; {@link AutoShape} overrides it.
+   */
+  get placeholder(): PlaceholderRef | null;
+  /**
+   * Remove this shape from its parent (the slide's shape tree, or an enclosing
+   * group) and mark the owning slide part dirty. The proxy is dead afterwards.
+   */
+  delete(): void;
+  /** Escape hatch: the underlying shape element. After mutating it call {@link markDirty}, or `save()` writes the original bytes. */
+  get element_(): Element;
+}
+//#endregion
+//#region src/read/api/shapes/autoshape.d.ts
+/** An auto shape, text box, or placeholder (`p:sp`). The only kind that holds text. */
+declare class AutoShape extends Shape {
+  readonly shapeType: "autoShape";
+  protected xfrm(): Element | null;
+  protected getOrAddXfrm(): Element;
+  get hasTextFrame(): boolean;
+  get textFrame(): TextFrame | null;
+  /**
+   * This shape's placeholder identity (`p:ph` `type`/`idx`), or `null` when it is
+   * not a placeholder. `idx` defaults to `'0'` when the attribute is absent, as
+   * 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
+/** A picture (`p:pic`). */
+declare class Picture extends Shape {
+  #private;
+  readonly shapeType: "picture";
+  protected xfrm(): Element | null;
+  protected getOrAddXfrm(): Element;
+  protected get supportsFill(): boolean;
+  /** Relationship id of the embedded image (`p:blipFill/a:blip/@r:embed`), or `null`. */
+  get imageRelId(): string | null;
+  /**
+   * Repoint the blip at a relationship id already present in the slide's
+   * relationships, without minting a new media part. The caller owns ensuring
+   * 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 slide's relationships, or `null`. */
+  get imagePartName(): string | null;
+  /**
+   * Relationship id of the embedded **vector (SVG)** image, read from the
+   * Microsoft SVG blip extension (`a:blip/a:extLst/a:ext/asvg:svgBlip/@r:embed`),
+   * or `null` when the picture has no SVG. PowerPoint usually pairs this with a
+   * raster fallback in `a:blip/@r:embed` ({@link imageRelId}), but some exporters
+   * emit an SVG-only blip where `imageRelId` is absent and only this resolves —
+   * 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 slide's relationships, or `null`. */
+  get svgPartName(): string | null;
+  /**
+   * Which drawable media this picture carries:
+   * - `'raster'` — only a raster blip (`a:blip/@r:embed`);
+   * - `'svg'` — only a vector blip (`asvg:svgBlip/@r:embed`, no raster). This
+   *   is what PowerPoint's *Insert → Icons* and a plain SVG insert produce;
+   * - `'both'` — a raster fallback *and* an SVG (PowerPoint's usual pairing);
+   * - `'none'` — a `p:pic` with no embedded blip at all (e.g. a linked image).
+   *
+   * Lets a caller distinguish an SVG-only picture — where {@link imagePartName}
+   * is legitimately `null` — from a genuinely empty one, without two null checks.
+   */
+  get mediaKind(): 'raster' | 'svg' | 'both' | 'none';
+  /**
+   * Absolute partname of whichever part actually carries this picture's drawn
+   * data — the raster part when present, otherwise the SVG part — or `null`
+   * when the picture embeds neither. Use this when you just want "the bytes
+   * this picture shows"; prefer {@link imagePartName} / {@link svgPartName}
+   * (and {@link mediaKind}) when you need to know *which* kind it is. An
+   * SVG-only picture returns its SVG part here even though `imagePartName` is
+   * `null`.
+   */
+  get mediaPartName(): string | null;
+  /**
+   * The picture's crop as fractions of the *source image*, read from
+   * `p:blipFill/a:srcRect` — `{ left, top, right, bottom }`, each the amount
+   * trimmed off that edge (so `0.1` = 10 % cropped away, an uncropped edge is
+   * `0`). `null` when there is no `a:srcRect` at all; an explicit
+   * `{0,0,0,0}` crop still reports zeros, since its presence is meaningful.
+   * The raw attributes are thousandths of a percent; this divides by 100000 to
+   * match the fraction convention used elsewhere in the read API (see
+   * {@link recolor}).
+   */
+  get crop(): {
+    left: number;
+    top: number;
+    right: number;
+    bottom: number;
+  } | 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
+   * needs to reproduce a recoloured image: `a:duotone` (the two-stop icon-tint
+   * trick), `a:clrChange`, `a:grayscl`, `a:biLevel`, and `a:alphaModFix`; the
+   * first such effect in document order wins. Colours mirror the
+   * {@link GradientStop} split (`color`/`schemeColor`/`presetColor`) so theme
+   * tokens resolve through {@link Slide.themeContext}. `threshold`/`amount` are
+   * 0–1 fractions. {@link hidden} (the duotone fallback-layer trick) reports the
+   * *visibility* of a recolour source; this reports the *tint* itself.
+   */
+  get recolor(): Recolor | null;
+  /**
+   * Replace this picture's image with new bytes. Mints a fresh media part under
+   * `/ppt/media/`, registers its content type, wires an `image` relationship
+   * from the owning slide, and repoints the blip's `@r:embed` at it.
+   *
+   * Copy-on-write: the previous media part is never mutated or removed, so any
+   * other picture sharing it (common after `importSlide`/dedup) is unaffected;
+   * an orphaned old part is left in place for a later GC pass to prune.
+   *
+   * `contentType` is required (e.g. `image/png`); the bytes are not sniffed.
+   * `extension` defaults from the content type.
+   *
+   * `fit` controls the picture's `a:srcRect` crop against its current frame
+   * extent (`a:xfrm/a:ext`):
+   * - omitted (default): geometry and crop are left untouched — the caller owns
+   *   sizing. Note an inherited `a:srcRect` was tuned to the *previous* image's
+   *   aspect ratio, so swapping in an image of a different ratio reuses a crop
+   *   that no longer fits and the result looks stretched; pass `fit` to refit.
+   * - `'cover'`: fill the frame, cropping the overflowing axis (no distortion).
+   * - `'contain'`: fit the whole image inside the frame, letterboxing the short
+   *   axis (no distortion).
+   * - `'stretch'`: drop any crop so the full image is stretched to the frame.
+   *
+   * `'cover'`/`'contain'` measure the new bytes' natural size; if unmeasurable
+   * (e.g. an unknown format) the crop is left as-is and a warning is emitted.
+   */
+  setImage(bytes: Uint8Array, options: {
+    contentType: string;
+    extension?: string;
+    fit?: 'cover' | 'contain' | 'stretch';
+  }): void;
+}
+//#endregion
+//#region src/read/api/shapes/connector.d.ts
+/** A connector / line (`p:cxnSp`). */
+declare class Connector extends Shape {
+  #private;
+  readonly shapeType: "connector";
+  protected xfrm(): Element | null;
+  protected getOrAddXfrm(): Element;
+  /**
+   * The connector's **start**-point shape binding (`p:nvCxnSpPr/p:cNvCxnSpPr/a:stCxn`),
+   * or `null` when the start point is unbound (a bare `p:cNvCxnSpPr`, i.e. a
+   * connector placed by static endpoint geometry). Mirrors the write API's
+   * `startShape`/`startShapeIdx` split; see {@link endConnection} for the other end.
+   */
+  get startConnection(): ConnectionSite | null;
+  /**
+   * The connector's **end**-point shape binding (`p:nvCxnSpPr/p:cNvCxnSpPr/a:endCxn`),
+   * or `null` when the end point is unbound. See {@link startConnection}.
+   */
+  get endConnection(): ConnectionSite | null;
+}
+//#endregion
+//#region src/read/api/chart.d.ts
+/** A chart axis number format (`c:numFmt`). */
+interface AxisNumberFormat {
+  /** The format mask (`@formatCode`), e.g. `"General"`, `"0.0%"`. */
+  formatCode: string | null;
+  /** Whether the mask is linked to the source cell format (`@sourceLinked`). */
+  sourceLinked: boolean | null;
+}
+/** A chart legend (`c:legend`). */
+interface ChartLegend {
+  /** Legend position (`c:legendPos/@val`): `r`/`l`/`t`/`b`/`tr`. */
+  position: string | null;
+  /** 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. */
+interface ChartDataLabels {
+  /** Show the point value (`c:showVal`). */
+  showValue: boolean | null;
+  /** Show the series name (`c:showSerName`). */
+  showSeriesName: boolean | null;
+  /** Show the category name (`c:showCatName`). */
+  showCategoryName: boolean | null;
+  /** Show the percentage (`c:showPercent`). */
+  showPercent: boolean | null;
+  /** Show the legend key swatch (`c:showLegendKey`). */
+  showLegendKey: boolean | null;
+  /** Show the bubble size (`c:showBubbleSize`). */
+  showBubbleSize: boolean | null;
+  /** Show leader lines (`c:showLeaderLines`). */
+  showLeaderLines: boolean | null;
+  /** Label position (`c:dLblPos/@val`), or `null` when auto. */
+  position: string | null;
+  /** Label number format (`c:numFmt`), or `null` when absent. */
+  numberFormat: AxisNumberFormat | null;
+}
+/** 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;
+  /** Whether the fill is explicitly suppressed (`a:noFill`). */
+  noFill: boolean;
+}
+/** A series' line/stroke (`c:ser/c:spPr/a:ln`). */
+interface ChartLine {
+  /** Stroke width in points (`@w`/12700), or `null` when unset. */
+  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;
+  /** Whether the line is explicitly suppressed (`a:noFill`). */
+  noFill: boolean;
+}
+/** A chart graphic-frame's chart, backed by its chart part. */
+declare class Chart {
+  #private;
+  /** The chart's OPC part (`/ppt/charts/chartN.xml`). */
+  readonly part: Part;
+  constructor(
+  /** The chart's OPC part (`/ppt/charts/chartN.xml`). */
+  part: Part);
+  /** Partname of the chart part. */
+  get partName(): string;
+  /**
+   * The chart-group type tokens present in the plot area, in document order
+   * (e.g. `['line']`, `['bar']`, `['bar', 'line']` for a combo chart). Derived
+   * from the plot-area element local names (`lineChart` → `line`).
+   */
+  get chartTypes(): string[];
+  /** The first chart-group type, or `null` for an empty plot area. */
+  get chartType(): string | null;
+  /** The chart title (`c:chart/c:title` rich text), or `null` when absent/auto. */
+  get title(): string | null;
+  /**
+   * The category/value/series axes (`c:catAx`/`c:valAx`/`c:dateAx`/`c:serAx`)
+   * in plot-area document order. Empty for pie/doughnut charts (no axes).
+   */
+  get axes(): ChartAxis[];
+  /** The category axis (`c:catAx`/`c:dateAx`), or `null` when the chart has none. */
+  get categoryAxis(): ChartAxis | null;
+  /** The (primary) value axis (`c:valAx`), or `null` when the chart has none. */
+  get valueAxis(): ChartAxis | null;
+  /** The legend (`c:chart/c:legend`) position + overlay, or `null` when hidden. */
+  get legend(): ChartLegend | null;
+  /**
+   * 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).
+   */
+  get dataLabels(): ChartDataLabels | null;
+  /** The data series (`c:ser`) across all chart groups, in document order. */
+  get series(): ChartSeries[];
+  /**
+   * Category labels, read from the first series' cached categories
+   * (`c:cat`), as written. Empty when the chart has no category axis.
+   */
+  get categories(): (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_}. */
+  markDirty(): void;
+}
+/**
+ * One axis (`c:catAx`/`c:valAx`/`c:dateAx`/`c:serAx`) of a chart's plot area.
+ * All four share the scaling/delete/position/tickmark structure; `kind`
+ * distinguishes them.
+ */
+declare class ChartAxis {
+  #private;
+  private readonly ax;
+  /** The owning chart's OPC part, so {@link markDirty} can reach it from {@link element_}. */
+  private readonly part;
+  constructor(ax: Element,
+  /** The owning chart's OPC part, so {@link markDirty} can reach it from {@link element_}. */
+  part: Part);
+  /** Axis kind derived from the element name: `cat`/`val`/`date`/`ser`. */
+  get kind(): 'cat' | 'val' | 'date' | 'ser' | null;
+  /** Axis id (`c:axId/@val`). */
+  get id(): number | null;
+  /** Scaling orientation (`c:scaling/c:orientation/@val`): `minMax`/`maxMin`. */
+  get orientation(): string | null;
+  /** Scale minimum (`c:scaling/c:min/@val`), or `null` when auto. */
+  get min(): number | null;
+  /** Scale maximum (`c:scaling/c:max/@val`), or `null` when auto. */
+  get max(): number | null;
+  /** Logarithmic scale base (`c:scaling/c:logBase/@val`), or `null` when linear. */
+  get logBase(): number | null;
+  /** Whether the axis is hidden (`c:delete/@val` = 1). */
+  get hidden(): boolean;
+  /** Axis position (`c:axPos/@val`): `b`/`l`/`r`/`t`. */
+  get position(): string | null;
+  /** Whether the axis draws major gridlines (`c:majorGridlines`). */
+  get majorGridlines(): boolean;
+  /** Whether the axis draws minor gridlines (`c:minorGridlines`). */
+  get minorGridlines(): boolean;
+  /** Axis title text (`c:title` rich text), or `null` when absent. */
+  get title(): string | null;
+  /** Axis number format (`c:numFmt`), or `null` when absent. */
+  get numberFormat(): AxisNumberFormat | null;
+  /** Major tick-mark style (`c:majorTickMark/@val`): `out`/`in`/`cross`/`none`. */
+  get majorTickMark(): string | null;
+  /** Minor tick-mark style (`c:minorTickMark/@val`). */
+  get minorTickMark(): string | null;
+  /** Tick-label position (`c:tickLblPos/@val`): `nextTo`/`high`/`low`/`none`. */
+  get tickLabelPosition(): string | null;
+  /** Major unit (`c:majorUnit/@val`), or `null` when auto. */
+  get majorUnit(): number | null;
+  /** Minor unit (`c:minorUnit/@val`), or `null` when auto. */
+  get minorUnit(): number | null;
+  /** Escape hatch: the underlying axis 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_}. */
+  markDirty(): void;
+}
+/** One data series (`c:ser`) of a chart. */
+declare class ChartSeries {
+  private readonly ser;
+  /** The owning chart's OPC part, so {@link markDirty} can reach it from {@link element_}. */
+  private readonly part;
+  constructor(ser: Element,
+  /** The owning chart's OPC part, so {@link markDirty} can reach it from {@link element_}. */
+  part: Part);
+  /**
+   * Series fill (`c:spPr` solid fill / no-fill). `null` when the series carries
+   * no `c:spPr` or its `c:spPr` declares no fill choice (inherits the theme).
+   */
+  get fill(): ChartFill | null;
+  /**
+   * Series line/stroke (`c:spPr/a:ln`) — width, dash, colour. `null` when the
+   * series `c:spPr` has no `a:ln` (bar/area fills carry no line by default).
+   */
+  get line(): ChartLine | null;
+  /** Series index (`c:idx/@val`), or `null` if absent. */
+  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`. */
+  get values(): (number | null)[];
+  /** Cached category labels for this series (`c:cat`), as written. */
+  get categories(): (string | 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_}. */
+  markDirty(): void;
+}
+//#endregion
+//#region src/read/api/chartex.d.ts
+/** A chartEx legend (`cx:legend`) — a leaf element carrying position/alignment attributes. */
+interface ChartExLegend {
+  /** Legend position (`@pos`): `t`/`b`/`l`/`r`. */
+  position: string | null;
+  /** Legend alignment along its edge (`@align`), e.g. `ctr`. */
+  align: string | null;
+  /** Whether the legend overlays the plot area (`@overlay`). */
+  overlay: boolean | null;
+}
+/** A chartEx series' data-label toggles (`cx:dataLabels` + its `cx:visibility` child). */
+interface ChartExDataLabels {
+  /** Label position (`@pos`), e.g. `outEnd`, or `null` when unset. */
+  position: string | null;
+  /** Show the point value (`cx:visibility/@value`). */
+  value: boolean | null;
+  /** Show the series name (`cx:visibility/@seriesName`). */
+  seriesName: boolean | null;
+  /** Show the category name (`cx:visibility/@categoryName`). */
+  categoryName: boolean | null;
+}
+/** A chartEx graphic-frame's chart, backed by its `cx:chartSpace` part. */
+declare class ChartEx {
+  #private;
+  /** The chartEx chart's OPC part (`/ppt/charts/chartEx{N}.xml`). */
+  readonly part: Part;
+  constructor(
+  /** The chartEx chart's OPC part (`/ppt/charts/chartEx{N}.xml`). */
+  part: Part);
+  /** Partname of the chartEx chart part. */
+  get partName(): string;
+  /**
+   * The `cx:series/@layoutId` tokens in plot-area document order — the raw chartEx
+   * layout names (`waterfall`, `funnel`, `treemap`, `sunburst`, `boxWhisker`,
+   * `regionMap`, or `clusteredColumn`/`paretoLine` for histogram & pareto). This is
+   * the OOXML truth: a histogram and a pareto both surface as `clusteredColumn`, so
+   * the token does not always round-trip to the write-side `ChartType`.
+   */
+  get layoutIds(): string[];
+  /** The first series' `@layoutId`, or `null` for an empty plot area. */
+  get layoutId(): string | null;
+  /** The chart title (`cx:chart/cx:title` rich text), or `null` when absent. */
+  get title(): string | null;
+  /** The legend (`cx:chart/cx:legend`) position/alignment, or `null` when hidden. */
+  get legend(): ChartExLegend | null;
+  /** The data series (`cx:plotAreaRegion/cx:series`) in document order. */
+  get series(): ChartExSeries[];
+  /** The plot-area axes (`cx:plotArea/cx:axis`) in document order. */
+  get axes(): ChartExAxis[];
+  /**
+   * Category labels from the first series' cached leaf level (`cx:strDim`'s first
+   * `cx:lvl`). Empty for a category-less layout (a histogram bins raw observations).
+   */
+  get categories(): (string | null)[];
+  /** Escape hatch: the underlying `cx:chartSpace` element. After mutating it call {@link markDirty}, or `save()` writes the original bytes. */
+  get element_(): Element | null;
+  /** Mark the chartEx part dirty so `save()` reserializes it. Call after mutating {@link element_}. */
+  markDirty(): void;
+  /**
+   * The `cx:data` block a series' `cx:dataId` points at (`cx:chartData/cx:data[@id]`),
+   * or `null` when the id is unset or unmatched.
+   */
+  dataElementById(id: number | null): Element | null;
+}
+/** One data series (`cx:series`) of a chartEx chart. */
+declare class ChartExSeries {
+  private readonly ser;
+  private readonly chart;
+  constructor(ser: Element, chart: ChartEx);
+  /** The layout token (`@layoutId`) that keys this series' geometry, e.g. `waterfall`. */
+  get layoutId(): string | null;
+  /** The deterministic series GUID (`@uniqueId`), or `null`. */
+  get uniqueId(): string | null;
+  /**
+   * The owner series index (`@ownerIdx`) for a derived series (a `paretoLine`
+   * derives its data from series 0), or `null` for a self-contained series.
+   */
+  get ownerIndex(): number | null;
+  /** Series name from the cached `cx:tx/cx:txData/cx:v`, or `null` when unnamed. */
+  get name(): string | null;
+  /** The data-block id this series plots (`cx:dataId/@val`), or `null`. */
+  get dataId(): number | null;
+  /** Cached numeric values (`cx:numDim`); non-numeric or missing points are `null`. */
+  get values(): (number | null)[];
+  /**
+   * Cached category labels (`cx:strDim`'s leaf `cx:lvl` — the first level, which
+   * the writer emits leaf-first). Empty when the data block carries no `cx:strDim`.
+   */
+  get categories(): (string | null)[];
+  /** The data-label toggles (`cx:dataLabels`), or `null` when the series shows none. */
+  get dataLabels(): ChartExDataLabels | null;
+  /** Escape hatch: the underlying `cx:series` element. After mutating it call {@link markDirty}, or `save()` writes the original bytes. */
+  get element_(): Element;
+  /** Mark the owning chartEx part dirty so `save()` reserializes it. Call after mutating {@link element_}. */
+  markDirty(): void;
+}
+/**
+ * One axis (`cx:axis`) of a chartEx plot area. chartEx axes carry no `catAx`/`valAx`
+ * element-name distinction; the kind is read from the scaling child
+ * (`cx:catScaling` vs `cx:valScaling`).
+ */
+declare class ChartExAxis {
+  private readonly ax;
+  /** The owning chartEx chart, so {@link markDirty} can reach its part from {@link element_}. */
+  private readonly chart;
+  constructor(ax: Element,
+  /** The owning chartEx chart, so {@link markDirty} can reach its part from {@link element_}. */
+  chart: ChartEx);
+  /** Axis id (`@id`), the value a series' `cx:axisId` binds to. */
+  get id(): number | null;
+  /** Axis kind from its scaling child: `cat` (`cx:catScaling`) / `val` (`cx:valScaling`). */
+  get kind(): 'cat' | 'val' | null;
+  /**
+   * Category-axis gap width (`cx:catScaling/@gapWidth`) as a fraction (1.0 = 100%,
+   * the chartEx convention, unlike the classic integer percent), or `null`.
+   */
+  get gapWidth(): number | null;
+  /** Value-axis scale minimum (`cx:valScaling/@min`), or `null` when auto. */
+  get min(): number | null;
+  /** Value-axis scale maximum (`cx:valScaling/@max`), or `null` when auto. */
+  get max(): number | null;
+  /** Whether the axis draws major gridlines (`cx:majorGridlines`). */
+  get majorGridlines(): boolean;
+  /** Whether the axis draws tick labels (`cx:tickLabels`). */
+  get tickLabels(): boolean;
+  /** Escape hatch: the underlying `cx:axis` element. After mutating it call {@link markDirty}, or `save()` writes the original bytes. */
+  get element_(): Element;
+  /** Mark the owning chartEx part dirty so `save()` reserializes it. Call after mutating {@link element_}. */
+  markDirty(): void;
+}
+//#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
+/**
+ * The context a cell needs to resolve its style-graph fill: the table's resolved
+ * `a:tblStyle`, its condition flags, and the grid dimensions. Threaded from
+ * {@link Table} down to each {@link TableCell} alongside the cell's own position.
+ * `null` when the table references no resolvable style.
+ */
+interface TableCellStyleContext {
+  style: ResolvedTableStyle;
+  flags: TableConditionFlags;
+  rowCount: number;
+  colCount: number;
+  ctx: FlattenContext;
+}
+/**
+ * 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.
+ */
+interface CellBorder {
+  /** Border width in points (`@w` is EMU; 12700 EMU = 1pt), or `null` when unset. */
+  widthPt: number | null;
+  /** Dash style (`a:prstDash/@val`, e.g. `solid`/`sysDash`), or `null` when unset. */
+  dash: string | null;
+  /** The stroke colour resolved against the table theme to a literal hex (`effectiveHex`), or `null`. */
+  color: string | null;
+  /** Raw `schemeClr` token of the stroke (`a:solidFill/a:schemeClr/@val`), or `null` for an srgb/absent colour. */
+  schemeColor: string | null;
+  /** `true` when the edge is an explicit no-border (`a:noFill`) — a deliberately suppressed side. */
+  noFill: boolean;
+}
+/**
+ * A table cell's six possible borders, keyed by edge. Each side is `null` when the
+ * cell defines no line for it; the diagonals ({@link tlToBr} `╲`, {@link blToTr} `╱`)
+ * are rarely authored. The whole object is `null` when the cell carries no border
+ * element at all (see {@link TableCell.borders}).
+ */
+interface CellBorders {
+  left: CellBorder | null;
+  right: CellBorder | null;
+  top: CellBorder | null;
+  bottom: CellBorder | null;
+  tlToBr: CellBorder | null;
+  blToTr: CellBorder | 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?: FlattenContext | 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;
+  /** 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;
+  /** 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?: FlattenContext | 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?;
+  /** 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?;
+  constructor(tc: Element, part: Part,
+  /** The owning slide's theme colour context, threaded to the cell's text for `Run.resolvedColor`. */
+  themeColors?: FlattenContext | undefined,
+  /** The table's style-resolution context, for the {@link resolvedFill} style-graph fallback. */
+  style?: (TableCellStyleContext | null) | undefined,
+  /** This cell's zero-based row index in the table. */
+  rowIndex?: number,
+  /** This cell's zero-based column index in its row. */
+  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). */
+  get textFrame(): TextFrame | null;
+  /** The cell's text, paragraphs joined by `\n`. */
+  get text(): string;
+  /**
+   * Replace the cell's text with a single paragraph and run, preserving the
+   * formatting (`a:rPr`) of the cell's first existing run when there is one.
+   * For finer control (multiple runs, per-run formatting), edit
+   * `textFrame.paragraphs[].runs[]` directly.
+   */
+  set text(value: string);
+  /**
+   * 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
+   * `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
+   * with an empty `a:tcPr` reports the colour PowerPoint actually renders rather
+   * than `null`.
+   *
+   * 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 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
+   * 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.
+   */
+  get resolvedFill(): ResolvedColor | null;
+  /**
+   * 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}
+   * 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
+   * geometry; {@link PictureFill.partName} needs the owning slide's relationships,
+   * which a {@link Table} built without them cannot supply.
+   */
+  get pictureFill(): PictureFill | null;
+  /**
+   * The raw `schemeClr` token of the cell's solid fill (`a:tcPr/a:solidFill/a:schemeClr/@val`),
+   * e.g. `accent1`/`bg1`, or `null` when the fill is absent or an explicit `srgbClr`.
+   * The resolved literal is {@link resolvedFill}; this is the unresolved reference.
+   */
+  get fillSchemeColor(): string | null;
+  /**
+   * The cell's edge borders (`a:tcPr/a:lnL|lnR|lnT|lnB|lnTlToBr|lnBlToTr`), or
+   * `null` when the cell defines none. Each present edge decodes to a
+   * {@link CellBorder} (width / dash / resolved + raw colour / suppressed flag);
+   * absent edges are `null`. Cell borders are the biggest visible table gap — a
+   * replica built only from geometry and fill draws every cell edge-to-edge with
+   * no rule, so this surfaces the per-side stroke the writer's `border` option emits.
+   */
+  get borders(): CellBorders | null;
+  /**
+   * The cell's text direction (`a:tcPr/@vert`), e.g. `vert270` for a bottom-to-top
+   * vertical label, or `null` for default horizontal text.
+   */
+  get verticalText(): string | null;
+  /**
+   * The cell's vertical text anchor (`a:tcPr/@anchor`): `t`/`ctr`/`b` (top/middle/
+   * bottom), or `null` when unset (PowerPoint defaults to top).
+   */
+  get anchor(): string | null;
+  /**
+   * The cell's text insets in EMU (`a:tcPr/@marL`/`@marR`/`@marT`/`@marB`), or
+   * `null` when the cell sets none. Each side is `null` when only some are set.
+   */
+  get marginsEmu(): {
+    left: number | null;
+    right: number | null;
+    top: number | null;
+    bottom: number | null;
+  } | null;
+  /** Number of grid columns this cell spans (`a:tc/@gridSpan`), default 1. */
+  get gridSpan(): number;
+  /** Number of rows this cell spans (`a:tc/@rowSpan`), default 1. */
+  get rowSpan(): number;
+  /** Whether this cell is a continuation of a merge (`@hMerge` or `@vMerge`), i.e. not the merge origin. */
+  get isMergeContinuation(): boolean;
+  /** Escape hatch: the underlying `a:tc` 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 and charts. */
+declare class GraphicFrame extends Shape {
+  #private;
+  readonly shapeType: "graphicFrame";
+  protected xfrm(): Element | null;
+  protected getOrAddXfrm(): Element;
+  protected getOrAddProperties(): ShapeProperties;
+  /** 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). */
+  get hasChartEx(): boolean;
+  /** The hosted table, or `null` when this frame is not a table. */
+  get table(): Table | null;
+  /** The hosted chart, or `null` when this frame is not a chart or its part is missing. */
+  get chart(): Chart | null;
+  /**
+   * The hosted chartEx chart (waterfall/funnel/treemap/…), or `null` when this
+   * frame is not a chartEx chart or its part is missing. The reference child is
+   * `cx:chart` (not the classic `c:chart`), carrying the MS `chartEx` rel id.
+   */
+  get chartEx(): ChartEx | null;
+}
+//#endregion
+//#region src/read/api/shapes.d.ts
+/**
+ * A group shape (`p:grpSp`) — contains nested shapes.
+ *
+ * It is the one kind defined here rather than under `./shapes/`: its `shapes` getter recurses
+ * through `buildShapes` below, so putting it in a sibling module would make the dispatch and the
+ * group import each other.
+ */
+declare class GroupShape extends Shape {
+  #private;
+  readonly shapeType: "group";
+  protected xfrm(): Element | null;
+  protected getOrAddXfrm(): Element;
+  protected properties(): Element | null;
+  protected getOrAddProperties(): ShapeProperties;
+  /** The shapes nested directly inside this group, in document order. */
+  get shapes(): AnyShape[];
+}
+/**
+ * The concrete shape kinds as a discriminated union keyed on the
+ * {@link Shape.shapeType} literal. The read API (`Slide.shapes`,
+ * `Slide.shapeById`, `GroupShape.shapes`, `Presentation.importShape`, …) returns
+ * this rather than the abstract {@link Shape} base, so a consumer can narrow to a
+ * subtype by its discriminant and reach the subtype-only members — e.g.
+ * `if (shape.shapeType === 'graphicFrame') shape.chart` or, equivalently, the
+ * {@link isGraphicFrame} guard. The abstract {@link Shape} base is still exported
+ * for the "common members only" case and for `instanceof` checks.
+ */
+type AnyShape = AutoShape | Picture | Connector | GraphicFrame | GroupShape;
+/** Narrow a shape to an {@link AutoShape} (`p:sp` — auto shape, text box, or placeholder). */
+declare function isAutoShape(shape: Shape): shape is AutoShape;
+/** Narrow a shape to a {@link Picture} (`p:pic`). */
+declare function isPicture(shape: Shape): shape is Picture;
+/** Narrow a shape to a {@link Connector} (`p:cxnSp`). */
+declare function isConnector(shape: Shape): shape is Connector;
+/** Narrow a shape to a {@link GraphicFrame} (`p:graphicFrame` — table/chart host). */
+declare function isGraphicFrame(shape: Shape): shape is GraphicFrame;
+/** Narrow a shape to a {@link GroupShape} (`p:grpSp`). */
+declare function isGroupShape(shape: Shape): shape is GroupShape;
+//#endregion
+//#region src/read/api/notes.d.ts
+/**
+ * One placeholder shape (`p:sp`) of a notes slide. A notes slide holds a fixed set:
+ * the slide thumbnail (`type="sldImg"`), the notes body (`type="body"`), and the
+ * slide number (`type="sldNum"`). Geometry getters read the placeholder's *own*
+ * `a:xfrm` and are `null` when it inherits geometry from the notesMaster (the case
+ * on an authored deck, whose `sldImg`/`sldNum` carry an empty `p:spPr`).
+ */
+declare class NotesPlaceholder {
+  #private;
+  private readonly sp;
+  private readonly part;
+  /** The notes theme context (notesMaster → `theme2.xml`), threaded to {@link textFrame}. */
+  private readonly themeContext;
+  /** The notes part's relationships, threaded to {@link textFrame} for hyperlink resolution. */
+  private readonly relationships;
+  constructor(sp: Element, part: Part,
+  /** The notes theme context (notesMaster → `theme2.xml`), threaded to {@link textFrame}. */
+  themeContext: FlattenContext,
+  /** The notes part's relationships, threaded to {@link textFrame} for hyperlink resolution. */
+  relationships: Relationships);
+  /** Placeholder type (`p:ph/@type`: `sldImg` | `body` | `sldNum`), or `null` when absent. */
+  get type(): string | null;
+  /** Placeholder index (`p:ph/@idx`), or `null` when unset. */
+  get idx(): string | null;
+  /** Shape name (`p:cNvPr/@name`), or `''` when unnamed. */
+  get name(): string;
+  /** Drawing id (`p:cNvPr/@id`), or `null` when absent. */
+  get id(): number | null;
+  /** Left edge in EMU (`a:off/@x`), or `null` when geometry is inherited (no own `a:xfrm`). */
+  get left(): number | null;
+  /** Top edge in EMU (`a:off/@y`), or `null` when geometry is inherited. */
+  get top(): number | null;
+  /** Width in EMU (`a:ext/@cx`), or `null` when geometry is inherited. */
+  get width(): number | null;
+  /** Height in EMU (`a:ext/@cy`), or `null` when geometry is inherited. */
+  get height(): number | null;
+  /**
+   * The placeholder's text as a navigable {@link TextFrame} (`p:txBody`), or `null`
+   * when it carries no text body (the `sldImg` thumbnail). The body placeholder's
+   * runs round-trip a slide's authored notes; the `sldNum` placeholder's frame
+   * holds the slide-number `a:fld`, whose value surfaces through `TextFrame.text`.
+   */
+  get textFrame(): TextFrame | null;
+  /** The placeholder's flattened text (paragraphs joined by `\n`), or `''` when it has no text body. */
+  get text(): string;
+  /** Escape hatch: the underlying `p:sp` element. After mutating it call {@link markDirty}, or `save()` writes the original bytes. */
+  get element_(): Element;
+  /** Mark the owning notes-slide part dirty so `save()` reserializes it. Call after mutating {@link element_}. */
+  markDirty(): void;
+}
+/**
+ * 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
+ * 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 {
+  #private;
+  private readonly opc;
+  /** The notes slide's OPC part (`/ppt/notesSlides/notesSlideN.xml`). */
+  readonly part: Part;
+  constructor(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 theme context, resolved through the notesMaster → `theme2.xml` chain
+   * and cached. Backs {@link NotesPlaceholder.textFrame}'s `Run.resolvedColor`.
+   */
+  themeContext(): FlattenContext;
+  /** The placeholders (`p:sp`) in the notes shape tree, in document order. */
+  get placeholders(): NotesPlaceholder[];
+  /** The notes body placeholder (`p:ph type="body"`), or `null` when the notes slide has none. */
+  get body(): NotesPlaceholder | null;
+  /** The slide-thumbnail placeholder (`p:ph type="sldImg"`), or `null` when absent. */
+  get slideImage(): NotesPlaceholder | null;
+  /** The slide-number placeholder (`p:ph type="sldNum"`, carrying the slide-number field), or `null`. */
+  get slideNumber(): NotesPlaceholder | null;
+  /** The notes body as a navigable {@link TextFrame}, or `null` when there is no body text frame. */
+  get textFrame(): TextFrame | null;
+  /** The notes body text flattened (paragraphs joined by `\n`), or `''` when the body is empty/absent. */
+  get text(): string;
+}
+//#endregion
+//#region src/read/api/comments.d.ts
+/** One entry of the deck-wide comment-author registry (`p:cmAuthor`). */
+interface CommentAuthor {
+  /** Author id (`@id`), referenced by each comment's `@authorId`. */
+  id: number | null;
+  /** Display name (`@name`). */
+  name: string;
+  /** Initials shown in the comment marker (`@initials`). */
+  initials: string;
+  /** Highest per-author comment index used (`@lastIdx`). */
+  lastIdx: number | null;
+  /** Author colour slot (`@clrIdx`). */
+  clrIdx: number | null;
+}
+/** One legacy review comment (`p:cm`), with its author resolved via the registry. */
+interface Comment {
+  /** Resolved author display name (via `@authorId` → `commentAuthors.xml`), or `null` when unresolved. */
+  author: string | null;
+  /** Resolved author initials, or `null` when unresolved. */
+  authorInitials: string | null;
+  /** The comment's `@authorId`, or `null` when absent/unparseable. */
+  authorId: number | null;
+  /** The comment's per-author 1-based index (`@idx`), or `null` when absent. */
+  idx: number | null;
+  /** The comment body text (`p:text`). */
+  text: string;
+  /** Marker X position in EMU (`p:pos/@x`), or `null` when absent. */
+  x: number | null;
+  /** Marker Y position in EMU (`p:pos/@y`), or `null` when absent. */
+  y: number | null;
+  /** Authored timestamp (`@dt`, ISO-8601 as written), or `null` when absent. */
+  date: string | null;
+}
+/** One entry of the modern deck-wide author registry (`p188:author`). */
+interface ModernCommentAuthor {
+  /** Author id (`@id`) — a GUID string like `{E8A64ABA-…}`, referenced by each comment's `@authorId`. */
+  id: string | null;
+  /** Display name (`@name`). */
+  name: string;
+  /** Initials (`@initials`). */
+  initials: string;
+  /** Account identifier (`@userId`, e.g. an email), or `null`. */
+  userId: string | null;
+  /** Identity provider (`@providerId`, e.g. `Windows Live`), or `null`. */
+  providerId: string | null;
+}
+/** One modern comment or reply (`p188:cm` / `p188:reply`), with its author resolved via the registry. */
+interface ModernComment {
+  /** The comment's own GUID id (`@id`), or `null` when absent. */
+  id: string | null;
+  /** Resolved author display name (via `@authorId` → `authors.xml`), or `null` when unresolved. */
+  author: string | null;
+  /** Resolved author initials, or `null` when unresolved. */
+  authorInitials: string | null;
+  /** The comment's `@authorId` GUID, or `null` when absent. */
+  authorId: string | null;
+  /** Creation timestamp (`@created`, ISO-8601 as written), or `null` when absent. */
+  created: string | null;
+  /** The comment body text; multiple paragraphs are joined with `\n`. */
+  text: string;
+  /** Marker X position in EMU (`p188:pos/@x`), or `null` (replies carry no position). */
+  x: number | null;
+  /** Marker Y position in EMU (`p188:pos/@y`), or `null` (replies carry no position). */
+  y: number | null;
+  /** Nested replies in thread order; each is itself a {@link ModernComment} with no further replies. */
+  replies: ModernComment[];
+}
+/** Which comment schema a deck carries. `'none'` when it has neither part. */
+type CommentSchema = 'legacy' | 'modern' | 'none';
+//#endregion
+//#region src/read/api/tags.d.ts
+/** One programmatic tag (`p:tag`) — a name/value string pair. */
+interface Tag {
+  /** The tag's `@name`. */
+  name: string;
+  /** The tag's `@val`. */
+  val: string;
+}
+/**
+ * Read every tag referenced by `ownerPartName` (a slide part or the presentation
+ * part), resolving the owner's `tags` relationship(s) to their `ppt/tags/tagN.xml`
+ * part(s) and flattening each part's `p:tag` children into `{ name, val }`. `[]`
+ * when the owner references no tag part. Rel-driven rather than walking
+ * `p:custDataLst`, so it is robust to element ordering in the owner.
+ */
+declare function readTagsForPart(opc: OpcPackage, ownerPartName: string): Tag[];
+//#endregion
+//#region src/read/api/chrome.d.ts
+/** The 12 theme colour-scheme slots (`a:clrScheme` children), in schema order. */
+type ThemeColorSlot = 'dk1' | 'lt1' | 'dk2' | 'lt2' | 'accent1' | 'accent2' | 'accent3' | 'accent4' | 'accent5' | 'accent6' | 'hlink' | 'folHlink';
+/** The 12 colour-map tokens (`p:clrMap` attributes), each pointing at a {@link ThemeColorSlot}. */
+type ColorMapToken = 'bg1' | 'tx1' | 'bg2' | 'tx2' | 'accent1' | 'accent2' | 'accent3' | 'accent4' | 'accent5' | 'accent6' | 'hlink' | 'folHlink';
+/**
+ * One theme font family (`a:majorFont` or `a:minorFont`): the primary Latin face
+ * plus the East-Asian and complex-script faces. Each is `null` when the theme
+ * leaves that slot empty (`typeface=""`, PowerPoint's default for `ea`/`cs`). The
+ * per-script `<a:font>` fallback list is not decoded here.
+ */
+interface ThemeFontFace {
+  /** `<a:latin@typeface>` — the primary face (e.g. `Calibri Light`), or `null` when empty. */
+  latin: string | null;
+  /** `<a:ea@typeface>` — the East-Asian face, or `null` when empty. */
+  ea: string | null;
+  /** `<a:cs@typeface>` — the complex-script face, or `null` when empty. */
+  cs: string | null;
+}
+/** A theme's `a:fontScheme`: its name plus the major (heading) and minor (body) font families. */
+interface ThemeFontScheme {
+  /** `<a:fontScheme@name>` (e.g. `Office`), or `null` when unnamed. */
+  name: string | null;
+  /** The `a:majorFont` family — the heading (`+mj-*`) fonts. */
+  major: ThemeFontFace;
+  /** The `a:minorFont` family — the body (`+mn-*`) fonts. */
+  minor: ThemeFontFace;
+}
+/**
+ * A deck's theme part (`theme1.xml`) as a modeled object. Exposes the two property
+ * tiers a slide resolves against: the {@link colorScheme} (the 12 `a:clrScheme`
+ * slots as literal hex, `a:sysClr` resolved via its `lastClr`) and the
+ * {@link fontScheme} (major/minor Latin/EA/CS faces). Reachable from
+ * {@link SlideMaster.theme} and `Slide.theme`.
+ */
+declare class Theme {
+  #private;
+  /** The theme's OPC part (`/ppt/theme/themeN.xml`). */
+  readonly part: Part;
+  constructor(
+  /** The theme's OPC part (`/ppt/theme/themeN.xml`). */
+  part: Part);
+  /** Partname of the theme part. */
+  get partName(): string;
+  /** Theme name (`a:theme/@name`, e.g. `Office Theme`), or `null` when unnamed. */
+  get name(): string | null;
+  /** Colour-scheme name (`a:clrScheme/@name`, e.g. `Office`), or `null`. */
+  get colorSchemeName(): string | null;
+  /**
+   * The theme colour scheme: the 12 {@link ThemeColorSlot}s resolved to a 6-hex RGB
+   * (an `a:sysClr` slot resolves through its `lastClr`). A slot the theme does not
+   * 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. */
+  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;
+  /** Escape hatch: the underlying `a:theme` element. After mutating it call {@link markDirty}, or `save()` writes the original bytes. */
+  get element_(): Element | null;
+  /** Mark the theme part dirty so `save()` reserializes it. Call after mutating {@link element_}. */
+  markDirty(): void;
+}
+/**
+ * One placeholder shape (`p:sp` with a `p:ph`) of a slide master or slide layout —
+ * the definition a slide's placeholder of the same `type`/`idx` inherits geometry
+ * and text style from. Geometry getters read the placeholder's *own* `a:xfrm`,
+ * which a master/layout placeholder carries explicitly (so it round-trips, unlike a
+ * notes placeholder's inherited geometry).
+ */
+declare class Placeholder {
+  #private;
+  private readonly sp;
+  private readonly part;
+  /** The owning master/layout theme context, threaded to {@link textFrame}. */
+  private readonly themeContext;
+  /** The owning part's relationships, threaded to {@link textFrame} for hyperlink resolution. */
+  private readonly relationships;
+  constructor(sp: Element, part: Part,
+  /** The owning master/layout theme context, threaded to {@link textFrame}. */
+  themeContext: FlattenContext,
+  /** The owning part's relationships, threaded to {@link textFrame} for hyperlink resolution. */
+  relationships: Relationships);
+  /** 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. */
+  get idx(): string | null;
+  /** Shape name (`p:cNvPr/@name`), or `''` when unnamed. */
+  get name(): string;
+  /** Drawing id (`p:cNvPr/@id`), or `null` when absent. */
+  get id(): number | null;
+  /** Left edge in EMU (`a:off/@x`), or `null` when the placeholder carries no own `a:xfrm`. */
+  get left(): number | null;
+  /** Top edge in EMU (`a:off/@y`), or `null` when the placeholder carries no own `a:xfrm`. */
+  get top(): number | null;
+  /** Width in EMU (`a:ext/@cx`), or `null` when the placeholder carries no own `a:xfrm`. */
+  get width(): number | null;
+  /** Height in EMU (`a:ext/@cy`), or `null` when the placeholder carries no own `a:xfrm`. */
+  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`.
+   */
+  get textFrame(): TextFrame | null;
+  /** Escape hatch: the underlying `p:sp` element. After mutating it call {@link markDirty}, or `save()` writes the original bytes. */
+  get element_(): Element;
+  /** Mark the owning master/layout part dirty so `save()` reserializes it. Call after mutating {@link element_}. */
+  markDirty(): void;
+}
+/**
+ * A deck's slide master (`slideMasterN.xml`) as a modeled object. Exposes the
+ * property tiers a bound slide inherits: the {@link colorMap} (token → theme slot),
+ * its {@link theme}, its {@link placeholders} (with geometry), its own
+ * {@link background}, and the {@link layouts} that build on it. Reachable from
+ * {@link SlideLayout.master} and `Slide.master`.
+ */
+declare class SlideMaster {
+  #private;
+  private readonly opc;
+  /** The master's OPC part (`/ppt/slideMasters/slideMasterN.xml`). */
+  readonly part: Part;
+  constructor(opc: OpcPackage,
+  /** The master's OPC part (`/ppt/slideMasters/slideMasterN.xml`). */
+  part: Part);
+  /** Partname of the master part. */
+  get partName(): string;
+  /** The master's authoring name (`p:cSld/@name`), or `''` when unnamed (the writer's default). */
+  get name(): string;
+  /** The master's theme (via its `theme` relationship), or `null` when absent. */
+  get theme(): Theme | null;
+  /**
+   * The master's colour map (`p:clrMap`): each of the 12 {@link ColorMapToken}s
+   * mapped to the {@link ThemeColorSlot} it resolves through. This is the indirection
+   * that lets a slide's `schemeClr val="tx1"` reach a theme slot (e.g. `tx1` → `dk1`).
+   * A token the map omits reads `null`.
+   */
+  get colorMap(): Record<ColorMapToken, string | null>;
+  /** The master's placeholder shapes (`p:sp` carrying a `p:ph`), in document order. */
+  get placeholders(): Placeholder[];
+  /** The layouts built on this master (via `p:sldLayoutIdLst` → its relationships), in list order. */
+  get layouts(): SlideLayout[];
+  /**
+   * The master's *own* background (`p:cSld/p:bg`), decoded, or `null` when it defines
+   * none. Scoped to the master's own element — a slide's *effective* background,
+   * resolved through the slide → layout → master chain, is `Slide.background`.
+   */
+  get background(): SlideBackground | null;
+  /**
+   * The master's colour/font context (its `p:clrMap` + theme), resolved once and
+   * cached. Backs each {@link Placeholder}'s text frame.
+   */
+  themeContext(): FlattenContext;
+}
+/**
+ * A deck's slide layout (`slideLayoutN.xml`) as a modeled object — the gallery entry
+ * a slide binds to. Exposes its {@link name}, its {@link type} (import-only; the
+ * writer authors none), its {@link master} (and, through it, the {@link theme}), its
+ * {@link placeholders} (with geometry), and its own {@link background}. Reachable
+ * from `Slide.layout` and {@link SlideMaster.layouts}.
+ */
+declare class SlideLayout {
+  #private;
+  private readonly opc;
+  /** The layout's OPC part (`/ppt/slideLayouts/slideLayoutN.xml`). */
+  readonly part: Part;
+  constructor(opc: OpcPackage,
+  /** The layout's OPC part (`/ppt/slideLayouts/slideLayoutN.xml`). */
+  part: Part);
+  /** Partname of the layout part. */
+  get partName(): string;
+  /** The layout's authoring name (`p:cSld/@name`, e.g. `Title and Content`), or `''` when unnamed. */
+  get name(): string;
+  /**
+   * The layout type (`p:sldLayout/@type`, e.g. `title` | `obj` | `blank`), or `null`
+   * when the layout declares none. Import-only: the writer authors no `@type`, so an
+   * authored deck reads `null`; an imported deck carries PowerPoint's value.
+   */
+  get type(): string | null;
+  /** The master this layout is built on (via its `slideMaster` relationship), or `null` when absent. */
+  get master(): SlideMaster | null;
+  /** The theme this layout resolves against, via its {@link master}, or `null`. */
+  get theme(): Theme | null;
+  /** The layout's placeholder shapes (`p:sp` carrying a `p:ph`), in document order. */
+  get placeholders(): Placeholder[];
+  /**
+   * The layout's *own* background (`p:cSld/p:bg`), decoded, or `null` when it defines
+   * none. A layout usually authors one — an explicit fill (`p:bgPr`) or a
+   * theme-indexed reference (`p:bgRef`). The slide's *effective* background is
+   * `Slide.background`.
+   */
+  get background(): SlideBackground | null;
+  /**
+   * The layout's colour/font context (walked layout → master → theme), resolved once
+   * and cached. Backs each {@link Placeholder}'s text frame.
+   */
+  themeContext(): FlattenContext;
+}
+//#endregion
+//#region src/read/api/transition.d.ts
+/** `ST_TransitionSpeed` — the coarse speed bucket (`spd`), default `fast`. */
+type TransitionSpeed = 'slow' | 'med' | 'fast';
+/** Decoded slide transition (`p:transition`), as returned by {@link Slide.transition}. */
+interface TransitionInfo {
+  /**
+   * The transition-type element's local name (e.g. `fade`, `push`, `wipe`,
+   * `cut`, `dissolve`). Base ECMA-376 types use the `p` namespace; modern
+   * PowerPoint types live in `p14`/`p15`/`p159` (see {@link namespace}).
+   */
+  type: string;
+  /** The transition element's namespace prefix (`p` for base, else `p14`/`p15`/`p159`). */
+  namespace: string;
+  /** Coarse speed bucket; `fast` when `spd` is absent (its schema default). */
+  speed: TransitionSpeed;
+  /** Exact duration in milliseconds (`p14:dur`), or `null` when only a speed bucket is set. */
+  durationMs: number | null;
+  /** Whether the slide advances on click (`advClick`, default `true`). */
+  advanceOnClick: boolean;
+  /** Auto-advance delay in milliseconds (`advTm`), or `null` when not timed. */
+  advanceAfterMs: number | null;
+  /** Type-specific variant attributes (e.g. `{ dir: 'd' }` for push, `{ spokes: '2' }` for wheel). */
+  variant: Record<string, string>;
+  /** Transition sound (`p:sndAc`), or `null` when the transition is silent. */
+  sound: TransitionSoundInfo | null;
+}
+/** Decoded transition sound (`p:sndAc`). A start sound (`p:stSnd`) or the stop-previous form (`p:endSnd`). */
+interface TransitionSoundInfo {
+  /** `start` for an embedded start sound (`p:stSnd`), `stop` for the stop-previous form (`p:endSnd`). */
+  form: 'start' | 'stop';
+  /** Whether the start sound loops until the next sound (`p:stSnd @loop`). Always `false` for `stop`. */
+  loop: boolean;
+  /** Relationship id of the embedded WAV (`p:snd @r:embed`), or `null` (stop form / missing). */
+  embedRid: string | null;
+  /** 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`. */
+interface TransitionInput {
+  type: string;
+  /** Namespace prefix for the type element; defaults to `p` (base ECMA-376). */
+  namespace?: string;
+  speed?: TransitionSpeed;
+  durationMs?: number | null;
+  advanceOnClick?: boolean;
+  advanceAfterMs?: number | null;
+  variant?: Record<string, string>;
+}
+//#endregion
+//#region src/read/api/slide.d.ts
+/** Options for {@link Slide.addTextBox}. Geometry is in EMU. */
+interface AddTextBoxOptions {
+  /** Left edge in EMU (`a:off/@x`). */
+  left: number;
+  /** Top edge in EMU (`a:off/@y`). */
+  top: number;
+  /** Width in EMU (`a:ext/@cx`); must be positive. */
+  width: number;
+  /** Height in EMU (`a:ext/@cy`); must be positive. */
+  height: number;
+  /** Initial text; omitted/empty yields an empty paragraph. */
+  text?: string;
+  /** Shape name (`p:cNvPr/@name`); defaults to `TextBox <id>`. */
+  name?: string;
+}
+/** Options for {@link Slide.addPicture}. Geometry is in EMU. */
+interface AddPictureOptions {
+  /** Left edge in EMU (`a:off/@x`). */
+  left: number;
+  /** Top edge in EMU (`a:off/@y`). */
+  top: number;
+  /** Width in EMU (`a:ext/@cx`); must be positive. */
+  width: number;
+  /** Height in EMU (`a:ext/@cy`); must be positive. */
+  height: number;
+  /** Shape name (`p:cNvPr/@name`); defaults to `Picture <id>`. */
+  name?: string;
+  /**
+   * Image file extension (e.g. `png`). When omitted it is sniffed from the
+   * image's magic bytes; supply it (with `contentType`) for formats the
+   * sniffer does not recognize.
+   */
+  extension?: string;
+  /** MIME content type (e.g. `image/png`); sniffed alongside `extension` when omitted. */
+  contentType?: string;
+}
+declare class Slide {
+  #private;
+  readonly presentation: Presentation;
+  /** The slide's OPC part (`/ppt/slides/slideN.xml`). */
+  readonly part: Part;
+  /** The slide id from `p:sldIdLst` (`p:sldId/@id`). */
+  readonly slideId: number;
+  /** Zero-based position in presentation order. */
+  readonly index: number;
+  constructor(presentation: Presentation,
+  /** The slide's OPC part (`/ppt/slides/slideN.xml`). */
+  part: Part,
+  /** The slide id from `p:sldIdLst` (`p:sldId/@id`). */
+  slideId: number,
+  /** Zero-based position in presentation order. */
+  index: number);
+  /** Partname of this slide's part. */
+  get partName(): string;
+  /**
+   * Escape hatch: the underlying `p:sld` element. After mutating it call
+   * {@link markDirty}, or `save()` writes the original bytes. Slide-level DOM
+   * access is also reachable as `slide.part.dom`; this getter is the same node,
+   * on the same rung of the ladder as `Shape.element_` and the rest.
+   */
+  get element_(): Element;
+  /** Mark this slide's part dirty so `save()` reserializes it. Call after mutating {@link element_}. */
+  markDirty(): void;
+  /** This slide part's relationships (image embeds, layout, hyperlinks, …). */
+  get relationships(): Relationships;
+  /**
+   * The slide's resolved theme context (`clrMap` + `clrScheme` + the theme
+   * `fmtScheme` + `fontScheme`, plus the layout/master roots), walked once from
+   * slide → layout → master → theme and cached on this proxy. Backs the read-model
+   * resolved getters ({@link Shape.resolvedFill}, `Run.resolvedColor`,
+   * `Run.resolvedSizePt`, `Run.resolvedFontFace`) so a `schemeClr` token — including
+   * one delivered through a shape's `p:style` `fillRef`/`lnRef` — resolves to a
+   * literal hex, and a placeholder run's inherited size/typeface (a `+mj-*`/`+mn-*`
+   * font token included) resolves to a literal value. The maps/roots are empty when
+   * the theme chain is incomplete, in which case tokens simply stay unresolved.
+   */
+  themeContext(): FlattenContext;
+  /** Authoring name of the slide (`p:cSld/@name`), or `null` if unnamed. */
+  get name(): string | null;
+  /**
+   * Whether this slide is hidden (`p:sld/@show="0"`). The attribute is
+   * `xsd:boolean` defaulting to `true`, so an absent attribute means shown.
+   * Hidden slides are dropped from PowerPoint/LibreOffice presentations and
+   * exported PDFs, so render order diverges from model order when any earlier
+   * slide is hidden.
+   */
+  get hidden(): boolean;
+  /**
+   * Hide or show this slide. Hiding writes `p:sld/@show="0"`; showing removes
+   * the attribute, restoring PowerPoint's canonical shown form (absent ⇒ shown).
+   * Marks the slide part dirty.
+   */
+  set hidden(value: boolean);
+  /**
+   * The slide's show transition (`p:transition`), decoded into a typed model, or
+   * `null` when the slide has none. Handles both PowerPoint forms: the bare
+   * `<p:transition>` and the `mc:AlternateContent` wrapper that carries the exact
+   * `p14:dur` duration (the `p14` Choice is preferred so `durationMs` is recovered).
+   */
+  get transition(): TransitionInfo | null;
+  /**
+   * Set or clear the slide's show transition. Assigning `null` removes it.
+   * Writing a transition with `durationMs` emits the `mc:AlternateContent` form
+   * (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.
+   */
+  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}.
+   */
+  get hasAnimations(): boolean;
+  /**
+   * @internal The sorted, de-duplicated set of shape ids (`spid`) referenced by
+   * the slide's animations (`<p:spTgt spid>` and `<p:bldP spid>`). Exposed for the
+   * import paths' spid-coherence checks.
+   */
+  animationSpids(): number[];
+  /**
+   * @internal Rewrite every animation `spid` per `mapping` (old → new), keeping
+   * the opaque timing tree coherent when shape ids are reassigned. Marks the slide
+   * part dirty only when a reference changed.
+   */
+  remapAnimationSpids(mapping: Map<number, number>): void;
+  /**
+   * @internal Remove the build animations targeting the given shape ids (their
+   * `<p:bldP>` and effect nodes), so deleting a shape never leaves a dangling
+   * `spid` reference. Marks the slide part dirty only when something was removed.
+   */
+  pruneAnimationSpids(spids: Iterable<number>): void;
+  /**
+   * Flatten the slide's build animations: remove the `<p:timing>` block so the
+   * slide renders and edits as its final static state, with every shape shown at
+   * once. Gated like {@link hasAnimations} — a `<p:timing>` that is purely a media
+   * loop (no `<p:bldP>` or `presetID`) is preserved so media playback survives.
+   * Marks the slide part dirty and returns `true` only when a timing block was
+   * removed.
+   *
+   * This removes click-through staging only; it does not delete shapes. If a slide
+   * animated alternating states over the same region, the flattened render shows
+   * them all at once — keep that distinct from removing staged/duplicate shapes.
+   */
+  flattenAnimations(): boolean;
+  /** Top-level shapes in the slide's shape tree, in document order. */
+  get shapes(): AnyShape[];
+  /**
+   * All text on the slide, flattened in document order — the read-model
+   * counterpart to {@link TextFrame.text} one level up. Every text-bearing shape
+   * contributes its text, recursing into groups ({@link GroupShape}) and reading
+   * table cells ({@link GraphicFrame.table}); text-free shapes (pictures,
+   * connectors, empty boxes) contribute nothing. Blocks are joined by `\n`; within
+   * a table, cells in a row are joined by `\t` and rows by `\n`.
+   *
+   * This is deliberately scoped to the slide's own shape tree. It does **not**
+   * include speaker notes (read those via {@link notesText}) or chart data labels
+   * (read those via {@link GraphicFrame.chart}); folding those in would force
+   * ordering and separator choices a caller is better placed to make. Extract a
+   * whole deck with `deck.slides.map((s) => s.text)`.
+   */
+  get text(): string;
+  /**
+   * The slide's speaker-note text — the companion to {@link text} for the notes
+   * that {@link text} deliberately excludes. Delegates to {@link notesSlide}: finds
+   * the notes body placeholder (`p:ph` `type="body"`) and flattens its text frame
+   * the same way {@link TextFrame.text} does (paragraphs joined by `\n`).
+   *
+   * Returns `null` when the slide has **no notes slide part at all** — distinct
+   * from `''`, which means a notes slide exists but its body is empty (PowerPoint
+   * often attaches an empty notes slide to every slide). Only the body placeholder
+   * is read; the slide-thumbnail (`sldImg`) and slide-number (`sldNum`)
+   * placeholders a notes slide also carries are read via {@link notesSlide}.
+   */
+  get notesText(): string | null;
+  /**
+   * The slide's speaker-note body as a navigable {@link TextFrame} — the rich
+   * companion to {@link notesText}, which flattens the same body to a plain string.
+   * Walk `paragraphs → runs` to recover per-run formatting (bold/italic/underline,
+   * colour, size, face) and any notes hyperlink that {@link notesText} discards.
+   *
+   * `null` when the slide has **no notes slide part** (the same boundary
+   * {@link notesText} returns `null` at), and also when a notes part exists but
+   * carries no body-placeholder text frame — there is then no frame to hand back
+   * (whereas {@link notesText} reports `''` for that empty-body case). Convenience
+   * for `notesSlide.textFrame`; see {@link notesSlide} for the whole modeled notes
+   * slide (its `sldImg`/`sldNum` placeholders and their geometry).
+   */
+  get notesTextFrame(): TextFrame | null;
+  /**
+   * The slide's speaker-notes slide (`notesSlideN.xml`) as a modeled
+   * {@link NotesSlide}, or `null` when the slide has no notes slide part. Beyond the
+   * body text {@link notesText}/{@link notesTextFrame} surface, this exposes the
+   * notes slide's three placeholders — the slide thumbnail (`slideImage`), the notes
+   * body, and the slide-number field (`slideNumber`) — each with its geometry and
+   * (where present) a navigable text frame.
+   *
+   * The writer authors all three placeholders but leaves `sldImg`/`sldNum` with an
+   * empty `p:spPr`, so on an authored deck their geometry reads `null` while an
+   * imported deck carries the notesMaster-derived geometry. The body text and the
+   * slide-number field round-trip either way.
+   */
+  get notesSlide(): NotesSlide | null;
+  /**
+   * The slide layout this slide is bound to (`slideLayout` relationship), as a
+   * modeled {@link SlideLayout}, or `null` when the slide has no layout. The layout
+   * carries the placeholder geometry and background a slide inherits; walk on to
+   * {@link master} and {@link theme} through it (`slide.layout.master.theme`).
+   */
+  get layout(): SlideLayout | null;
+  /**
+   * The slide master this slide resolves against, via its {@link layout}, as a
+   * modeled {@link SlideMaster}, or `null` when the layout/master chain is broken.
+   * The master owns the colour map (`schemeClr` token → theme slot) and the default
+   * text styles a placeholder inherits.
+   */
+  get master(): SlideMaster | null;
+  /**
+   * The theme this slide resolves colour and font tokens against, via its
+   * {@link layout} → {@link master} → theme, as a modeled {@link Theme}, or `null`.
+   * Read its {@link Theme.colorScheme}/{@link Theme.fontScheme} to see the literal
+   * palette and faces a `schemeClr`/`+mj-*` token resolves to.
+   */
+  get theme(): Theme | null;
+  /**
+   * The slide's **legacy** review comments (`p:cm` in its `comments/commentN.xml`
+   * part), `[]` when it has none. Each {@link Comment} carries its body text, marker
+   * 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.
+   */
+  get comments(): Comment[];
+  /**
+   * The slide's **modern** (2018) review comments (`p188:cm` in its
+   * `modernComment_*.xml` part), `[]` when it has none. Each {@link ModernComment}
+   * carries its body text, `created` timestamp, marker position (EMU), its author
+   * resolved through the deck-wide {@link Presentation.modernCommentAuthors}
+   * registry (`@authorId` GUID → name/initials), and its reply thread nested under
+   * `replies`. Read-only — the writer authors the legacy schema; see
+   * {@link Presentation.commentSchema} to tell which schema a deck uses.
+   */
+  get modernComments(): ModernComment[];
+  /**
+   * The slide's programmatic tags (`p:custDataLst/p:tags` on the slide part,
+   * resolved to `ppt/tags/tagN.xml`) as `{ name, val }` string pairs, `[]` when it
+   * has none. Host/add-in metadata with no visible rendering and no writer —
+   * read-only, preserved byte-for-byte on round-trip. Deck-level tags are
+   * {@link Presentation.tags}.
+   */
+  get tags(): Tag[];
+  /**
+   * The slide's effective background (`p:cSld/p:bg`), decoded into a typed
+   * {@link SlideBackground}. Resolved through the inheritance chain: the slide's
+   * own `p:bg` wins; failing that the slideLayout's, then the slideMaster's — the
+   * result's `source` records which supplied it. `null` when nothing in the chain
+   * defines a background.
+   *
+   * 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.
+   */
+  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
+   * 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
+   * the master's `p:hf`/placeholder (with no shape on the slide) is a master-level
+   * concern this getter does not resolve.
+   */
+  get slideNumberPlaceholder(): AutoShape | null;
+  /** The first top-level shape with the given drawing id (`p:cNvPr/@id`), or `undefined`. */
+  shapeById(id: number): AnyShape | undefined;
+  /**
+   * The first shape *anywhere* in the slide's shape tree with the given drawing id
+   * (`p:cNvPr/@id`), descending into groups — unlike {@link shapeById}, which scans
+   * only top-level shapes. Walked pre-order (a group is visited before its children),
+   * matching how the writer allocates ids. `undefined` when no shape carries that id.
+   *
+   * 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
+   * resolve a binding into a group that top-level {@link shapeById} cannot see.
+   */
+  shapeByIdDeep(id: number): AnyShape | undefined;
+  /** The first top-level shape with the given name (`p:cNvPr/@name`), or `undefined`. */
+  shapeByName(name: string): AnyShape | undefined;
+  /**
+   * The first placeholder of the given type (`p:ph/@type`, e.g. `title`,
+   * `ctrTitle`, `subTitle`, `body`), optionally narrowed by `idx`. Returns
+   * `undefined` when none match. Only `p:sp` shapes can be placeholders, so the
+   * result is an {@link AutoShape}.
+   */
+  placeholder(type: string, idx?: string): AutoShape | undefined;
+  /**
+   * Append a text box (`p:sp` with `txBox="1"`) to the slide's shape tree and
+   * return it. Geometry is required (EMU); width and height must be positive.
+   * Allocates a drawing id unique within the slide. Marks the slide part dirty.
+   */
+  addTextBox(options: AddTextBoxOptions): AutoShape;
+  /**
+   * Add a picture (`p:pic`) from raw image bytes and return it. Creates a media
+   * part under `/ppt/media/`, registers its content type, wires an `image`
+   * relationship from this slide, and appends the picture to the shape tree.
+   * Geometry is required (EMU); width and height must be positive. The image
+   * format is sniffed from the bytes unless `extension`/`contentType` are given.
+   */
+  addPicture(image: Uint8Array, options: AddPictureOptions): Picture;
+  /**
+   * @internal The slide's shape tree (`p:cSld/p:spTree`), or `null` if absent.
+   * Exposed for cross-slide composition (`Presentation.importShape`).
+   */
+  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.
+   */
+  nextShapeId(): number;
+}
+//#endregion
+//#region src/read/api/document-properties.d.ts
+/**
+ * Decoded `docProps/core.xml`. Every field is optional (present only when the
+ * element is). `created`/`modified`/`lastPrinted` are kept as the **raw W3CDTF
+ * string** rather than parsed to `Date`, avoiding timezone round-trip loss and
+ * matching the byte-preserve ethos of the read model.
+ */
+interface CoreProperties {
+  /** `dc:title`. */
+  title?: string;
+  /** `dc:subject`. */
+  subject?: string;
+  /** `dc:creator` (the write-side `pptx.author`). */
+  creator?: string;
+  /** `cp:keywords`. */
+  keywords?: string;
+  /** `dc:description`. */
+  description?: string;
+  /** `cp:lastModifiedBy`. */
+  lastModifiedBy?: string;
+  /** `cp:revision`. */
+  revision?: string;
+  /** `cp:category`. */
+  category?: string;
+  /** `cp:contentStatus`. */
+  contentStatus?: string;
+  /** `dcterms:created`, raw W3CDTF string. */
+  created?: string;
+  /** `dcterms:modified`, raw W3CDTF string. */
+  modified?: string;
+  /** `cp:lastPrinted`, raw W3CDTF string. */
+  lastPrinted?: string;
+}
+/** One user-defined custom document property (`docProps/custom.xml`). */
+interface CustomProperty {
+  /** The property's `@name`. */
+  name: string;
+  /** The decoded value, typed from its `vt:` child element. */
+  value: CustomPropertyValue;
+}
+/**
+ * Read the deck's core document properties from `/docProps/core.xml`, resolved
+ * via the package-root `core-properties` relationship (fallback: the part's
+ * content type). Missing part → `{}` (all fields undefined). Present-but-empty
+ * elements decode to the empty string.
+ */
+declare function readCoreProperties(opc: OpcPackage): CoreProperties;
+/**
+ * Read the deck's user-defined custom properties from `/docProps/custom.xml`,
+ * resolved via the package-root `custom-properties` relationship (fallback: the
+ * part's content type). Each `<property name=...>` maps to `{ name, value }`,
+ * with `value` typed from its single `vt:` child. Missing part → `[]`. A
+ * `<property>` without a `@name` or without a `vt:` child is skipped.
+ *
+ * The `vt:` child and `<property>` element sit in namespaces outside the read
+ * model's qname registry, so children are matched by local name rather than the
+ * `firstChild`/`getElements` helpers.
+ */
+declare function readCustomProperties(opc: OpcPackage): CustomProperty[];
+//#endregion
+//#region src/read/api/presentation.d.ts
+declare class Presentation {
+  #private;
+  readonly opc: OpcPackage;
+  private constructor();
+  /** Open a `.pptx` from bytes and wrap it as a navigable `Presentation`. */
+  static load(input: OpcInput): Promise<Presentation>;
+  /** Wrap an already-loaded OPC package (e.g. from the lower-level API). */
+  static fromPackage(opc: OpcPackage): Presentation;
+  /**
+   * Open a PowerPoint template (`.pptx` or `.potx`) and return it as an empty
+   * deck shell ready to author onto: its slide masters, layouts, and theme are
+   * kept **byte-identical**, while any sample slides the template carried are
+   * stripped so only the shared chrome remains.
+   *
+   * Use it to build a fresh deck on a corporate template without rebuilding the
+   * masters in code: discover the bindable layouts with {@link layouts}, then
+   * author slides with a generator sized to match the template and graft them in
+   * with {@link appendSlides} (which enforces an equal slide size). Saving yields
+   * an editable `.pptx` that reuses the template's authored chrome verbatim.
+   *
+   * ```ts
+   * const deck = await Presentation.fromTemplate(templateBytes) // .pptx or .potx
+   * deck.layouts().map(l => l.name)                             // discover layouts
+   * await deck.appendSlides(pptx, { layout: 'Title and Content' })
+   * const out = await deck.save()                               // editable .pptx
+   * ```
+   *
+   * A `.potx` package declares its main part with the template content type; by
+   * default that override is flipped to the editable presentation type so the
+   * saved output opens as a normal deck. Pass `keepTemplateContentType: true` to
+   * preserve the template type. A `.pptx` input needs no flip, and a template
+   * that already carries zero slides makes the strip a no-op.
+   */
+  static fromTemplate(input: OpcInput, options?: FromTemplateOptions): Promise<Presentation>;
+  /** The main presentation part (`/ppt/presentation.xml`), resolved via the package `officeDocument` relationship. */
+  get presentationPart(): Part;
+  /** The slides in presentation order (resolved from `p:sldIdLst` + the presentation's relationships). */
+  get slides(): Slide[];
+  /** Slide dimensions (`p:sldSz`), or `null` if the presentation declares none. */
+  get slideSize(): SlideSize | null;
+  /**
+   * The deck's embedded font families (`p:embeddedFontLst` in `presentation.xml`),
+   * `[]` when it embeds none. Each entry names the typeface and resolves every
+   * embedded face's `r:id` to the absolute partname of its `.fntdata` binary — the
+   * read counterpart to the write-side `pptx.embedFont` / `importSlide({ embedFonts })`
+   * carry. An entry whose `p:font` has no `@typeface`, or a face whose `r:id` is
+   * missing or dangling, is skipped (faithful degradation, no throw). Read-only.
+   */
+  get embeddedFonts(): EmbeddedFontInfo[];
+  /**
+   * 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.
+   */
+  get commentAuthors(): CommentAuthor[];
+  /**
+   * The deck-wide **modern** (2018) comment-author registry (`p188:authorLst` in
+   * `ppt/authors.xml`), `[]` when the deck carries no modern comments. Unlike the
+   * legacy {@link commentAuthors}, each entry is keyed by a GUID `id` (plus
+   * `userId`/`providerId`); each slide's {@link Slide.modernComments} resolves its
+   * `@authorId` against this list. Read-only — the writer emits legacy comments.
+   */
+  get modernCommentAuthors(): ModernCommentAuthor[];
+  /**
+   * Which comment schema this deck uses: `'modern'` when it carries any 2018
+   * `modernComment_*` part (read via {@link Slide.modernComments} /
+   * {@link modernCommentAuthors}), `'legacy'` when it carries classic
+   * `commentN.xml` parts (read via {@link Slide.comments} / {@link commentAuthors}),
+   * or `'none'`. The two schemas do not coexist in practice, so this tells a
+   * consumer which accessor to read without probing both.
+   */
+  get commentSchema(): CommentSchema;
+  /**
+   * The deck's core document properties (`docProps/core.xml`): title, subject,
+   * creator, keywords, revision, and the created/modified/lastPrinted timestamps
+   * (kept as raw W3CDTF strings). `{}` when the deck carries no core-properties
+   * part. The read counterpart of the write-side `pptx.title`/`subject`/`author`
+   * (→ `creator`)/`revision` setters.
+   */
+  get coreProperties(): CoreProperties;
+  /**
+   * The deck's user-defined custom document properties (`docProps/custom.xml`) as
+   * `{ name, value }` pairs, each value typed from its `vt:` element (string,
+   * number, boolean, or a raw filetime string). `[]` when the deck carries no
+   * custom-properties part. The read counterpart of `pptx.setCustomProperty(...)`.
+   */
+  get customProperties(): CustomProperty[];
+  /**
+   * The deck-level programmatic tags (`p:custDataLst/p:tags` on `presentation.xml`,
+   * resolved to `ppt/tags/tagN.xml`) as `{ name, val }` string pairs, `[]` when the
+   * deck carries none. These are add-in/host metadata with no visible rendering and
+   * no writer — read-only, preserved byte-for-byte on round-trip. Per-slide tags are
+   * {@link Slide.tags}.
+   */
+  get tags(): Tag[];
+  /**
+   * Duplicate the slide at `index` and insert the copy at `options.at` (deck
+   * order; `0` = first), defaulting to appending at the end when `at` is omitted
+   * or out of range. Returns the new slide. The new slide part copies the source
+   * bytes verbatim and shares the source's relationship targets (layout, images,
+   * …) by copying its `.rels`; a new presentation→slide relationship and a
+   * `p:sldId` entry are wired up. Marks the presentation part dirty.
+   *
+   * Note: relationships are copied as-is, so a source slide that owns a
+   * one-to-one part (e.g. a notes slide) would end up shared with the clone.
+   */
+  cloneSlide(index: number, options?: {
+    at?: number;
+  }): Slide;
+  /**
+   * Remove the slide at `index` (deck order) and return its former partname. The
+   * `p:sldId` entry and the presentation→slide relationship are dropped, the slide
+   * part and its `.rels` are deleted, and any part the slide *privately* owned
+   * (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).
+   *
+   * Untouched parts stay byte-identical, matching the package fidelity contract.
+   * Throws when there is no slide at `index`.
+   */
+  removeSlide(index: number): string;
+  /**
+   * Append a copy of `source.slides[index]` to this presentation and return it.
+   *
+   * Unlike {@link cloneSlide} (same-deck duplicate), this copies a slide across
+   * a package boundary: it brings the connected sub-graph the slide depends on —
+   * its `slideLayout` → `slideMaster` → `theme`, plus any media, charts, and
+   * embeddings — into this package under fresh partnames, rewriting every
+   * partname, relationship id, and content-type registration so the result is a
+   * self-consistent OPC package. Parts of this (target) package that are not
+   * touched stay byte-identical, matching `cloneSlide`'s fidelity contract.
+   *
+   * Only the layout(s) actually used by imported slides are copied; the imported
+   * master's `p:sldLayoutIdLst` is pruned to exactly those, mirroring how
+   * PowerPoint's "Reuse Slides" brings a slide across. Parts shared by repeated
+   * imports from the same source deck are copied once and reused.
+   *
+   * With `{ theme: 'preserve' }` the slide's source theme is instead *flattened*
+   * into the slide XML and the slide is bound to this deck's existing
+   * master/layout; with `{ theme: 'restyle' }` the slide is bound to this deck's
+   * 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 }`.
+   */
+  importSlide(source: Presentation, index: number, options?: ImportSlideOptions): Slide;
+  /**
+   * Graft slide master(s) from another open package into this one and return what
+   * was copied. Unlike {@link importSlide} — which brings a master across only as
+   * the dependency of an imported *slide* and prunes it to the one layout that
+   * slide uses — this copies a master together with its **whole** layout family
+   * and attaches it to no slide: the master and its layouts land in this deck's
+   * layout gallery (PowerPoint's *Insert ▸ New Slide* / *Layout* picker) without
+   * changing any existing slide.
+   *
+   * It is the "ship a brand template's layouts into a generated deck" capability,
+   * kept brand-agnostic here: the caller supplies the source `.pptx`. Each grafted
+   * master is wired into `p:sldMasterIdLst` (so renderers treat it as active) and
+   * its `p:sldLayoutIdLst` is rebuilt to list exactly the copied layouts; the
+   * connected theme/media/tag parts come across under fresh partnames, and parts
+   * shared with earlier imports from the same source are reused (the copy
+   * registry), so a re-call is idempotent. Untouched parts of this package stay
+   * byte-identical, matching {@link importSlide}'s fidelity contract.
+   *
+   * `options.masters` / `options.layouts` narrow what is grafted; by default every
+   * master and every layout comes across. The source and destination slide sizes
+   * must match unless `options.requireEqualSize` is `false` (see
+   * {@link ImportSlideMastersOptions}).
+   *
+   * Presentation-level parts are carried only on request: embedded fonts via
+   * `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.
+   */
+  importSlideMasters(source: Presentation, options?: ImportSlideMastersOptions): ImportedSlideMaster[];
+  /**
+   * The deck's slide masters, in `p:sldMasterIdLst` order, as modeled
+   * {@link SlideMaster}s — the typed read model over the shared chrome (each
+   * master's colour map, theme, placeholders, and the layouts built on it). Walk
+   * `pres.masters()[i].layouts` for the rich layout model, or use {@link layouts}
+   * for the flat {@link LayoutHandle} gallery {@link appendSlides} binds to.
+   * Read-only: it copies nothing and leaves the package byte-identical.
+   */
+  masters(): SlideMaster[];
+  /**
+   * The deck's slide layouts, in master then layout order — the gallery a new
+   * slide can bind to. Each {@link LayoutHandle} addresses one layout for
+   * {@link appendSlides}; the `name` is its `p:cSld@name`. Read-only enumeration:
+   * it copies nothing and leaves the package byte-identical.
+   */
+  layouts(): LayoutHandle[];
+  /**
+   * Append generator-produced slides onto this deck, binding each to an existing
+   * layout, and return the new {@link Slide}s. This is the hybrid
+   * "generate-onto-existing" path: the deck's masters, layouts, theme — and every
+   * other untouched part — stay **byte-identical** (only `presentation.xml`, its
+   * `.rels`, `[Content_Types].xml`, and the freshly-added slide/media parts
+   * change), because the existing chrome is never regenerated.
+   *
+   * `source` is any slide producer (a `TsPptx` instance); its authored slides
+   * are serialized via {@link SlideSource.extractSlides} and spliced in under
+   * fresh partnames, with each slide's `slideLayout` relationship pointed at the
+   * layout named by `options.layout` and its image/hyperlink relationships rebuilt
+   * (preserving the body's relationship ids). Insert position follows
+   * `options.at` (see {@link AppendSlidesOptions}).
+   *
+   * Charts and internal slide-to-slide hyperlinks are carried across: chart parts
+   * (chart XML + `.rels` + embedded workbook) are injected under fresh names, and a
+   * `slide:N` link is repointed at the Nth appended slide's new partname.
+   *
+   * The generator's presentation-level embedded fonts (`pptx.embedFont`) are also
+   * carried into this deck and merged into its `p:embeddedFontLst`, de-duped by
+   * typeface + face slot — so author-side embedded fonts survive the append onto a
+   * template that may itself already embed fonts.
+   *
+   * Embedded audio/video is carried too: the media part backs the ECMA audio/video rel
+   * and the MS-2007 `media` rel sharing one Target, plus a separate preview image part,
+   * with the media content type registered as a Default extension entry (what PowerPoint
+   * authors). Online (external-link) video rides as two External rels over the link.
+   *
+   * Speaker notes ride across too: a slide authored with `addNotes` gets a `notesSlide`
+   * part wired back to it, with its hyperlink rels preserved. A notes slide must bind to
+   * a notes master, and a template commonly has none, so the generator's is installed
+   * (with the theme its `.rels` needs) — but only when this deck has none of its own, so
+   * an existing notes master and its styling always win.
+   *
+   * Limitations:
+   * - An internal link to a source slide outside the appended batch throws (its
+   *   target has no counterpart in the destination).
+   * - Appended slides are concrete absolute-positioned content with no placeholder
+   *   inheritance from the bound layout; the binding governs theme/`clrMap`
+   *   resolution and the "based on" link, not placeholder geometry. Author with
+   *   concrete colours — any `schemeClr` re-resolves against the destination theme.
+   * - Source and destination slide sizes must match (no geometry rescale).
+   */
+  appendSlides(source: SlideSource, options: AppendSlidesOptions): Promise<Slide[]>;
+  /**
+   * Copy one shape — an autoshape, picture, table/chart graphic frame, connector,
+   * or group — from `source.shapes[shapeIndex]` onto `target`, returning the new
+   * {@link Shape}. `target` must be a slide of *this* presentation; `source` may
+   * belong to any open presentation.
+   *
+   * The lifted subtree is copied self-consistently: every media/chart/embedding it
+   * depends on is dragged into this package (deduped against earlier imports from
+   * the same source), its `r:embed`/`r:id`/… are rewritten to fresh host-slide
+   * relationships, and its drawing ids (including a group's children) are reassigned
+   * so they cannot collide with the host. With `theme: 'preserve'` (default) the
+   * shape's theme references are baked to literals against the *source* theme so it
+   * renders the same on a foreign host; `restyle` leaves them symbolic to re-brand;
+   * `copy` brings the XML across untouched — see {@link ImportShapeOptions}.
+   *
+   * Differing slide sizes need `{ rescale }` (see {@link ImportShapeOptions.rescale});
+   * a lifted `preserve` placeholder is baked self-contained and demoted to a plain
+   * shape (see {@link ImportShapeOptions.theme}), so it neither re-inherits from nor
+   * collides with the host. A shape's build animation lives in the slide-scoped
+   * `p:timing`, not in its subtree, so the shape lands static unless
+   * `{ carryAnimation: true }` opts in (see {@link ImportShapeOptions.carryAnimation}).
+   */
+  importShape(target: Slide, source: Slide, shapeIndex: number, options?: ImportShapeOptions): AnyShape;
+  /**
+   * Batch form of {@link importShape}: copy several shapes from one source slide
+   * onto `target` in the given order. Media/chart/embedding parts shared by the
+   * lifted shapes (and by earlier imports from the same source deck) are copied
+   * once via the copy registry, and shared images resolve to a single host-slide
+   * relationship. Returns the new {@link Shape}s in `shapeIndices` order.
+   */
+  importShapes(target: Slide, source: Slide, shapeIndices: number[], options?: ImportShapeOptions): AnyShape[];
+  /** Re-emit the package; untouched parts stay byte-identical (see `OpcPackage.save`). */
+  save(): Promise<Uint8Array>;
+}
+//#endregion
+export { ChartFill as $, GroupShape as A, BackgroundFill as At, TableCell as B, ColorContext as Bt, CommentAuthor as C, AutofitMode as Ct, NotesPlaceholder as D, Run as Dt, ModernCommentAuthor as E, Paragraph as Et, isPicture as F, PictureFillTile as Ft, ChartExAxis as G, ResolvedTableStyle as H, GraphicFrame as I, GradientFill as It, ChartExSeries as J, ChartExDataLabels as K, CellBorder as L, GradientStop as Lt, isConnector as M, SlideBackground as Mt, isGraphicFrame as N, FillRect as Nt, NotesSlide as O, RunHyperlink as Ot, isGroupShape as P, PictureFill as Pt, ChartDataLabels as Q, CellBorders as R, ResolvedColor as Rt, Comment as S, SoftEdge as St, ModernComment as T, LineSpacing as Tt, TableConditionFlags as U, TableRow as V, ChartEx as W, Chart as X, AxisNumberFormat as Y, ChartAxis as Z, ThemeColorSlot as _, PatternFill as _t, readCustomProperties as a, AutoShape as at, Tag as b, Reflection as bt, Slide as c, ConnectionSite as ct, TransitionSpeed as d, GeometryCommand as dt, ChartLegend as et, ColorMapToken as f, Glow as ft, Theme as g, OuterShadow as gt, SlideMaster as h, LineEnds as ht, readCoreProperties as i, Picture as it, isAutoShape as j, BackgroundSource as jt, AnyShape as k, TextFrame as kt, TransitionInfo as l, CustomGeometry as lt, SlideLayout as m, LineEnd as mt, CoreProperties as n, ChartSeries as nt, AddPictureOptions as o, Shape as ot, Placeholder as p, InnerShadow as pt, ChartExLegend as q, CustomProperty as r, Connector as rt, AddTextBoxOptions as s, AbsoluteFrame as st, Presentation as t, ChartLine as tt, TransitionInput as u, CustomGeometryPath as ut, ThemeFontFace as v, Recolor as vt, CommentSchema as w, BodyProperties as wt, readTagsForPart as x, ShapeType as xt, ThemeFontScheme as y, RecolorColor as yt, Table as z, resolveColorElement as zt };
+//# sourceMappingURL=presentation-RGOiun5P.d.ts.map