@shbernal/ts-pptx 1.0.0 → 3.0.0

package/dist/{presentation-RGOiun5P.d.ts → presentation-CTVPpiwP.d.ts}

@@ -1,4 +1,4 @@
-import { t as CustomPropertyValue } from "./pres-5x1bjCzk.js";
+import { t as CustomPropertyValue } from "./pres-2WsBGimU.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
@@ -6,37 +6,31 @@ import { a as Part, i as Relationships, n as OpcPackage, o as Element, t as OpcI
  * 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}.
+ * 6-hex RGB). Shared by the read-model colour getters and {@link ThemeContext}.
  */
 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).
+ * The source theme subgraph a slide, notes slide, layout or master resolves against: the
+ * {@link ColorContext} maps, the live `a:fmtScheme` for style-matrix resolution, and the roots
+ * of the inheritance chain a placeholder reads through.
+ *
+ * Every root here is **read-only** — nothing in this module or in `placeholder-inherit.ts`
+ * mutates one. The import-time flatten pass extends this with the one field it needs to write
+ * from (see `FlattenContext` in `read/api/ops/flatten.ts`).
  */
-interface FlattenContext extends ColorContext {
+interface ThemeContext 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.
+   * The source `slideLayout` root element, for resolving what a placeholder inherits.
+   * `null`/absent disables 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.
+   * The source `slideMaster` root element, for resolving placeholder inheritance via its
+   * placeholder `a:lstStyle` and `p:txStyles`.
    */
   masterRoot?: Element | null;
   /**
@@ -304,101 +298,448 @@ interface ShapeProperties {
   lnAfter: string[] | null;
 }
 //#endregion
-//#region src/read/api/text.d.ts
+//#region src/read/api/pattern-fill.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).
+ * A pattern fill (`a:pattFill`) — a two-colour preset hatch. The write-side
+ * `fill: { type: 'pattern', pattern: { preset, fgColor, bgColor } }` emits the same element,
+ * so the {@link preset} name and both colours round-trip. Colours resolve against the theme
+ * (a scheme token → literal hex) the same way a solid fill does.
  */
-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;
+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;
+}
+//#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;
 }
 /**
- * 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.
+ * 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 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;
+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 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).
+ * 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.
  */
-type LineSpacing = {
-  type: 'points';
-  valuePt: number;
+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;
+}
+/**
+ * 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;
 } | {
-  type: 'percent';
-  percent: 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 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
+/** 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 group shape's own child coordinate space (`p:grpSpPr/a:xfrm/a:chOff` and
+ * `a:chExt`) in EMU — the space its children's `a:off`/`a:ext` are authored in.
+ *
+ * Named after the OOXML attributes rather than in the `left`/`top`/`width`/
+ * `height` vocabulary the rest of the read model uses, because this is not a
+ * frame on the slide: it is the source rectangle of the
+ * `off + (p - chOff) * (ext / chExt)` mapping, and nothing about it is
+ * positional. A consumer reaching for it is rebuilding that mapping, so the
+ * names it needs are the ones the mapping is written in.
+ */
+interface ChildFrame {
+  /** `a:chOff/@x`. */
+  offsetX: number;
+  /** `a:chOff/@y`. */
+  offsetY: number;
+  /** `a:chExt/@cx`. */
+  extentX: number;
+  /** `a:chExt/@cy`. */
+  extentY: number;
+}
+/**
+ * A colour reference inside a picture recolour effect, split by colour model
+ * (mirrors {@link GradientStop}). At most one field is non-`null`.
+ */
+interface RecolorColor {
+  /** Explicit RGB as 6-hex (`a:srgbClr/@val`), or `null`. */
+  color: string | null;
+  /** Theme colour token (`a:schemeClr/@val`, e.g. `accent1`), or `null`. */
+  schemeColor: string | null;
+  /** Preset colour name (`a:prstClr/@val`, e.g. `black`/`white` — the duotone icon-tint stops), or `null`. */
+  presetColor: string | null;
+}
+/**
+ * A picture's blip recolour effect (`p:blipFill/a:blip` recolour child), as read.
+ * A small discriminated union over the effects a faithful reader needs to
+ * reproduce a recoloured image. Colours use the same `color`/`schemeColor`/
+ * `presetColor` split as {@link GradientStop}, so theme tokens can resolve through
+ * {@link Slide.themeContext}. `threshold`/`amount` are 0–1 fractions.
+ */
+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/text.d.ts
+/**
+ * What a {@link Run}'s text body needs to resolve an *inherited* run
+ * colour/size/face/bold: which placeholder the text lives in (or `null` for a
+ * non-placeholder shape, which still resolves its `p:style/a:fontRef` and the
+ * presentation `p:defaultTextStyle`), the slide theme context (with the
+ * layout/master roots) to resolve against, and the shape's resolved
+ * `p:style/a:fontRef` text tier. The owning slide's text body `a:lstStyle` is added
+ * per text frame. Absent only for text reached without a theme context (table cells).
+ */
+interface PlaceholderTextContext {
+  ph: PlaceholderRef | null;
+  flatten: ThemeContext;
+  /** The shape's resolved `p:style/a:fontRef` colour + face tier, or `null` when it has none. */
+  fontRef?: StyleFontRef | null;
+}
+/**
+ * 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;
+};
+/**
+ * The bullet's own font, size and colour (`a:buFont` / `a:buSzPct` / `a:buSzPts` /
+ * `a:buClr`) — the properties that style the glyph or number itself rather than
+ * the text after it. Every field is `null` when the paragraph leaves it to be
+ * inherited from the list style.
+ *
+ * These are siblings of the bullet kind in `a:pPr`, not children of it, so they
+ * are carried alongside each kind rather than inside it.
+ */
+interface BulletStyle {
+  /** `a:buFont/@typeface` — the face the glyph is drawn in (a symbol font such as `Wingdings`), or `null`. */
+  font: string | null;
+  /** `a:buSzPct/@val` as a percentage of the run size (e.g. `80`; the raw attribute is thousandths of a percent), or `null`. */
+  sizePct: number | null;
+  /** `a:buSzPts/@val` as an absolute point size (the raw attribute is hundredths of a point), or `null`. The alternative to {@link sizePct}; at most one is set. */
+  sizePt: number | null;
+  /** Explicit RGB bullet colour as 6-hex (`a:buClr/a:srgbClr/@val`), or `null`. */
+  color: string | null;
+  /** Theme colour token when the bullet colour is a scheme colour (`a:buClr/a:schemeClr/@val`), or `null`. */
+  schemeColor: string | null;
+  /** The bullet colour resolved against the slide theme with its transforms applied, or `null` when unset or not resolvable to a literal. */
+  resolvedColor: ResolvedColor | null;
+}
+/**
+ * A paragraph's bullet, as the structured counterpart of the `a:pPr` bullet
+ * children. Discriminated on {@link kind}, which is one of the four mutually
+ * exclusive choices the schema allows:
+ *
+ * - `'none'`    — `a:buNone`, the bullet explicitly suppressed. Carries no style,
+ *                 because there is no glyph to style.
+ * - `'char'`    — `a:buChar`, a literal glyph.
+ * - `'autoNum'` — `a:buAutoNum`, an auto-numbered list.
+ * - `'picture'` — `a:buBlip`, an image used as the glyph.
+ *
+ * A paragraph that names none of them inherits its bullet from the list style and
+ * reports `null` rather than a member of this union.
+ */
+type BulletDetail = {
+  kind: 'none';
+} | ({
+  kind: 'char';
+  /** The glyph itself (`a:buChar/@char`) — a bare character, never a tagged string. */
+  char: string;
+} & BulletStyle) | ({
+  kind: 'autoNum';
+  /** The numbering scheme (`a:buAutoNum/@type`, e.g. `arabicPeriod`). */
+  scheme: string;
+  /**
+   * The number this list starts at (`a:buAutoNum/@startAt`), or `null` when
+   * unset (the schema default is 1). Content rather than styling: a list
+   * continuing "5. Deploy" that restarts at 1 is a different slide.
+   */
+  startAt: number | null;
+} & BulletStyle) | ({
+  kind: 'picture';
+  /**
+   * Absolute partname of the image used as the glyph (`a:buBlip/a:blip/@r:embed`,
+   * resolved through the owning part's relationships), or `null` when the
+   * paragraph was reached without them or the blip carries no `r:embed`.
+   */
+  imagePartName: string | null;
+} & BulletStyle);
+/** 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,
+  themeContext?: ThemeContext | undefined,
   /**
    * Resolves the colour this run inherits from its placeholder/list-style chain
    * when it sets none of its own (item A). Built by the owning {@link Paragraph}
@@ -569,7 +910,7 @@ declare class Paragraph {
   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,
+  themeContext?: ThemeContext | undefined,
   /**
    * Placeholder + slide-list-style context for resolving a placeholder-inherited
    * run colour/size/face; absent for non-placeholder text. The owning
@@ -610,13 +951,18 @@ declare class Paragraph {
   /** 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)
+   * This paragraph's bullet — its kind, and for a drawn bullet the glyph, the
+   * numbering start, and the bullet's own font/size/colour. `null` when the
+   * paragraph names no bullet at all and inherits one from the list style.
+   *
+   * Structured rather than a tagged string, which is not merely tidier. The
+   * previous `bullet` accessor reported `'none'` / `'char:•'` /
+   * `'autoNum:arabicPeriod'`, and that shape is ambiguous when the glyph is
+   * itself a colon; worse, it reads as a bare glyph, which is exactly how the
+   * script converter first consumed it — `'none'.codePointAt(0)` put a literal
+   * `n` bullet on every converted deck, silently. See {@link BulletDetail}.
    */
-  get bullet(): string | null;
+  get bulletDetail(): BulletDetail | 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`.
@@ -627,379 +973,116 @@ declare class Paragraph {
   /** 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[];
-}
+/** A shape's text frame (`p:txBody`): an ordered list of paragraphs. */
 /**
- * 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.
+ * 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 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;
+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 colour reference inside a picture recolour effect, split by colour model
- * (mirrors {@link GradientStop}). At most one field is non-`null`.
+ * 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'`.
  */
-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;
+type AutofitMode = 'none' | 'normAutofit' | 'spAutoFit';
+declare class TextFrame {
+  #private;
+  private readonly txBody;
+  private readonly part;
+  /** The owning slide's theme context (colour maps + `fontScheme`), threaded to each {@link Paragraph}/{@link Run} for the `resolved*` getters. */
+  private readonly themeContext?;
+  /**
+   * The placeholder this text body lives in, when any — enables
+   * placeholder-inherited run colour/size/face resolution. Absent for ordinary
+   * text boxes and table cells.
+   */
+  private readonly placeholder?;
+  /** The owning part's relationships, threaded to each {@link Paragraph}/{@link Run} for hyperlink `@r:id` resolution; absent when reached without them. */
+  private readonly relationships?;
+  constructor(txBody: Element, part: Part,
+  /** The owning slide's theme context (colour maps + `fontScheme`), threaded to each {@link Paragraph}/{@link Run} for the `resolved*` getters. */
+  themeContext?: ThemeContext | undefined,
+  /**
+   * The placeholder this text body lives in, when any — enables
+   * placeholder-inherited run colour/size/face resolution. Absent for ordinary
+   * text boxes and table cells.
+   */
+  placeholder?: PlaceholderTextContext | undefined,
+  /** The owning part's relationships, threaded to each {@link Paragraph}/{@link Run} for hyperlink `@r:id` resolution; absent when reached without them. */
+  relationships?: Relationships | undefined);
+  /** 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;
 }
-/**
- * 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. */
@@ -1148,10 +1231,23 @@ declare abstract class Shape {
   /** 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);
+  /**
+   * `true` when the shape sets an explicit no-fill (`spPr/a:noFill`) — a
+   * deliberately transparent surface. The fill-side counterpart of
+   * {@link lineNoFill}, and the only accessor that separates it from a shape
+   * carrying no fill child at all (one inheriting through `p:style/a:fillRef`):
+   * every other fill accessor — {@link fillColor}, {@link fillSchemeColor},
+   * {@link resolvedFill}, {@link gradientFill}, {@link patternFill},
+   * {@link pictureFill} — reports `null` for both. The two paint completely
+   * differently, so a consumer that cannot tell them apart paints a transparent
+   * shape in the theme's accent colour.
+   */
+  get fillNoFill(): boolean;
   /**
    * 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.
+   * Read it back with {@link fillNoFill}.
    */
   noFill(): void;
   /** Explicit RGB line/border colour (`spPr/a:ln/a:solidFill/a:srgbClr/@val`), or `null`. */
@@ -1177,6 +1273,26 @@ declare abstract class Shape {
    * to know the border was explicitly suppressed.
    */
   get lineNoFill(): boolean;
+  /**
+   * The line end cap (`spPr/a:ln/@cap`) as the raw OOXML token — `'flat'`,
+   * `'rnd'` (round) or `'sq'` (square) — or `null` when unset (PowerPoint's
+   * default is `flat`). The write API authors this attribute through
+   * `ShapeLineProps.cap`, so without the accessor a deck this library produced
+   * could not be read back without losing it.
+   *
+   * Not cosmetic on a thick dashed rule: the cap decides whether each dash reads
+   * as a rectangle or a lozenge, and it extends every dash by the stroke width.
+   * SVG's `stroke-linecap` is the exact equivalent (`flat`→`butt`, `rnd`→`round`,
+   * `sq`→`square`).
+   */
+  get lineCap(): string | null;
+  /**
+   * The line alignment (`spPr/a:ln/@algn`) as the raw OOXML token — `'ctr'`
+   * (centred on the shape's outline) or `'in'` (inset, drawn wholly inside it) —
+   * or `null` when unset. It shifts a thick outline by half its width, so it
+   * changes where the border sits relative to the fill.
+   */
+  get lineAlign(): string | null;
   /**
    * 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
@@ -1805,6 +1921,19 @@ declare class ChartExAxis {
   markDirty(): void;
 }
 //#endregion
+//#region src/read/api/table-edit.d.ts
+/** The four edges plus the two diagonals, keyed as {@link TableCellEdge} names them. */
+declare const EDGE_QNAMES: {
+  readonly left: "a:lnL";
+  readonly right: "a:lnR";
+  readonly top: "a:lnT";
+  readonly bottom: "a:lnB";
+  readonly tlToBr: "a:lnTlToBr";
+  readonly blToTr: "a:lnBlToTr";
+};
+/** Which border of a cell an edit addresses. */
+type TableCellEdge = keyof typeof EDGE_QNAMES;
+//#endregion
 //#region src/read/api/table-style-resolve.d.ts
 /**
  * The `a:tblPr` condition flags that gate which style parts apply to a table.
@@ -1837,6 +1966,26 @@ interface ResolvedTableStyle {
 }
 //#endregion
 //#region src/read/api/table.d.ts
+/**
+ * One border as {@link TableCell.setBorder} takes it — the write-side mirror of
+ * {@link CellBorder}, which is what reading one gives back.
+ *
+ * Deliberately not `CellBorder` itself: that type reports every field, `null` included, so
+ * passing one back would make "leave this alone" unsayable. Here an omitted field is simply
+ * not written, which is what an edit usually means.
+ */
+interface TableCellBorderEdit {
+  /** Border width in points; omitted leaves `@w` unset, which renders as a hairline. */
+  widthPt?: number | null;
+  /** Dash preset (`a:prstDash/@val`, e.g. `sysDash`); omitted leaves the border solid. */
+  dash?: string;
+  /** Explicit colour as 6-hex (`#` optional). Ignored when {@link schemeColor} is given. */
+  color?: string;
+  /** Theme colour token (e.g. `accent1`); preferred over {@link color} when both are set. */
+  schemeColor?: string;
+  /** Write an explicit `a:noFill` — a deliberately suppressed edge, not an absent one. */
+  noFill?: boolean;
+}
 /**
  * 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
@@ -1848,7 +1997,7 @@ interface TableCellStyleContext {
   flags: TableConditionFlags;
   rowCount: number;
   colCount: number;
-  ctx: FlattenContext;
+  ctx: ThemeContext;
 }
 /**
  * One edge border of a table cell (`a:tcPr/a:lnL|lnR|lnT|lnB|lnTlToBr|lnBlToTr`).
@@ -1883,6 +2032,29 @@ interface CellBorders {
   tlToBr: CellBorder | null;
   blToTr: CellBorder | null;
 }
+/**
+ * A table cell's 3-D bevel (`a:tcPr/a:cell3D`), as read back. Every field is `null` when the
+ * source leaves it to the schema default, so a reader can tell "PowerPoint wrote `circle`"
+ * from "PowerPoint wrote nothing and `circle` is what it means".
+ */
+interface CellThreeD {
+  /** `a:cell3D/@prstMaterial` (`ST_PresetMaterialType`), or `null` when unset. */
+  material: string | null;
+  /** The required `a:bevel`. Present whenever the cell has a `a:cell3D` at all. */
+  bevel: {
+    /** `a:bevel/@prst` (`ST_BevelPresetType`), or `null` when unset. */
+    preset: string | null;
+    /** `a:bevel/@w` converted from EMU to points, or `null` when unset. */
+    widthPt: number | null;
+    /** `a:bevel/@h` converted from EMU to points, or `null` when unset. */
+    heightPt: number | null;
+  };
+  /** `a:cell3D/a:lightRig`, or `null` when the cell leaves lighting to the renderer. */
+  lightRig: {
+    rig: string | null;
+    dir: string | null;
+  } | null;
+}
 /** A table: a grid of rows and cells inside a graphic frame. */
 declare class Table {
   #private;
@@ -1896,7 +2068,7 @@ declare class Table {
   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,
+  themeColors?: ThemeContext | undefined,
   /** The deck package, for resolving `a:tableStyleId` against `tableStyles.xml` (style-graph cell fills). */
   opc?: OpcPackage | undefined,
   /** The owning slide's relationships, for resolving a cell picture fill's `r:embed` to a partname. */
@@ -1927,6 +2099,42 @@ declare class Table {
    * table style, so it is the read counterpart of the writer's `tableStyle` option.
    */
   get styleId(): string | null;
+  /**
+   * The table's own background (`a:tblPr` fill) resolved against the slide's theme colour
+   * context to a literal hex, or `null` when the table carries no solid background.
+   *
+   * This is the table-level counterpart of {@link TableCell.resolvedFill}, and it is a
+   * genuinely different thing from a cell fill: a `a:tblPr` fill sits *behind* the grid, so
+   * a cell with no fill of its own shows it through. Reports `null` for a non-solid choice
+   * (`a:blipFill`/`a:gradFill`/`a:pattFill`/`a:noFill`) — read {@link pictureFill} for an
+   * image background — and `null` with no theme context.
+   */
+  get resolvedFill(): ResolvedColor | null;
+  /**
+   * The table's picture background (`a:tblPr/a:blipFill`), or `null` when the table is not
+   * image-backed. The table-level twin of {@link TableCell.pictureFill}, and needed for the
+   * same reason: {@link resolvedFill} decodes only solid colours, so without this an
+   * image-backed table is indistinguishable from an unfilled one.
+   */
+  get pictureFill(): PictureFill | null;
+  /**
+   * The table's gradient background (`a:tblPr/a:gradFill`), or `null` when it is not
+   * gradient-filled. Needed for the same reason {@link pictureFill} is:
+   * {@link resolvedFill} decodes only solid colours.
+   */
+  get gradientFill(): GradientFill | null;
+  /**
+   * The table's pattern (hatch) background (`a:tblPr/a:pattFill`), or `null` when it is not
+   * pattern-filled.
+   */
+  get patternFill(): PatternFill | null;
+  /**
+   * The raw `schemeClr` token of the table's own background
+   * (`a:tblPr/a:solidFill/a:schemeClr/@val`), or `null` for an absent or `srgbClr` fill.
+   * {@link resolvedFill} is the literal it resolves to; this is the unresolved reference,
+   * which is what a replica should carry so the copy still tracks its theme.
+   */
+  get fillSchemeColor(): string | null;
   /** Whether the first row is styled as a header (`a:tblPr/@firstRow`). */
   get firstRowHeader(): boolean;
   /** Whether rows are banded (`a:tblPr/@bandRow`). */
@@ -1937,6 +2145,64 @@ declare class Table {
    * spans columns (`gridSpan`) occupies a single index here.
    */
   cell(rowIndex: number, columnIndex: number): TableCell | null;
+  /**
+   * Insert a row, defaulting to the bottom of the table. Returns the new {@link TableRow}.
+   *
+   * The new row is auto-height (`a:tr/@h="0"`) and its cells are empty. Inserting *through*
+   * a vertical merge extends that merge rather than interrupting it: the span's origin
+   * grows by a row and the new cell joins as a continuation, because an origin claiming
+   * more rows than it has continuations is a table PowerPoint reports as corrupt.
+   * @param {number} [index] - where to insert, `0`..`rowCount`; appended when omitted
+   * @throws {InvalidOptionError} when `index` is outside that range
+   */
+  addRow(index?: number): TableRow;
+  /**
+   * Remove the row at `index`, with its content.
+   *
+   * A cell in the row that *continues* a vertical merge shortens that merge. A cell that
+   * *starts* one hands the region to its first continuation, which becomes the new origin —
+   * the merged region survives one row shorter, and only the removed row's own text is lost.
+   * @throws {InvalidOptionError} when `index` is out of range
+   */
+  removeRow(index: number): void;
+  /**
+   * Insert a column, defaulting to the right-hand end. Updates `a:tblGrid` **and** every
+   * row, which is the pair that has to stay in step.
+   *
+   * The mirror of {@link addRow}'s merge case: inserting inside a horizontal merge widens
+   * it instead of splitting it.
+   * @param {number} [index] - where to insert, `0`..`columnCount`; appended when omitted
+   * @param {number} [widthEmu] - the new column's width; defaults to 1 inch
+   * @throws {InvalidOptionError} when `index` is outside that range
+   */
+  addColumn(index?: number, widthEmu?: number): void;
+  /**
+   * Remove the column at `index`, from `a:tblGrid` and from every row.
+   *
+   * Inside a horizontal merge the region narrows by one and keeps its content: a covered
+   * cell is dropped rather than the origin. Elsewhere the column's cells go with it.
+   * @throws {InvalidOptionError} when `index` is out of range
+   */
+  removeColumn(index: number): void;
+  /**
+   * Merge the rectangle between two cell positions into one cell. The top-left cell keeps
+   * its content; the rest become covered cells and are emptied, since a covered cell is
+   * never rendered.
+   *
+   * A rectangle that cuts through an existing merge is **rejected**, not silently widened
+   * to fit — the caller asked for a specific region, and quietly producing a different one
+   * is how a layout ends up wrong with nothing to point at. Unmerge first.
+   * @throws {InvalidOptionError} when an index is out of range, the range covers one cell,
+   *   or it partially overlaps an existing merge
+   */
+  mergeCells(row1: number, col1: number, row2: number, col2: number): void;
+  /**
+   * Split the merged cell whose **origin** is `(row, col)` back into individual cells.
+   * A no-op on a cell that is not merged; addressing a covered cell instead of the origin
+   * throws, and the message names the origin to use.
+   * @throws {InvalidOptionError} when an index is out of range or the cell is a covered cell
+   */
+  unmergeCell(row: number, col: number): void;
   /** Escape hatch: the underlying `a:tbl` element. After mutating it call {@link markDirty}, or `save()` writes the original bytes. */
   get element_(): Element;
   /** Mark the owning part dirty so `save()` reserializes it. Call after mutating {@link element_}. */
@@ -1956,7 +2222,7 @@ declare class TableRow {
   private readonly rels?;
   constructor(tr: Element, part: Part,
   /** The owning slide's theme colour context, threaded to each {@link TableCell}. */
-  themeColors?: FlattenContext | undefined,
+  themeColors?: ThemeContext | undefined,
   /** The table's style-resolution context, threaded to each cell for {@link TableCell.resolvedFill}. */
   style?: (TableCellStyleContext | null) | undefined,
   /** This row's zero-based index in the table, for style-graph banding/edge conditions. */
@@ -1989,7 +2255,7 @@ declare class TableCell {
   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,
+  themeColors?: ThemeContext | 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. */
@@ -2009,6 +2275,82 @@ declare class TableCell {
    * `textFrame.paragraphs[].runs[]` directly.
    */
   set text(value: string);
+  /**
+   * Set (or clear) the cell's vertical text anchor (`a:tcPr/@anchor`).
+   * `null` removes the attribute, leaving PowerPoint's default of top.
+   * @throws {InvalidOptionError} when the value is outside `ST_TextAnchoringType`
+   */
+  setAnchor(value: string | null): void;
+  /**
+   * Set (or clear) the cell's text direction (`a:tcPr/@vert`), e.g. `'vert270'`.
+   * `null` removes the attribute, leaving the default horizontal text.
+   * @throws {InvalidOptionError} when the value is outside `ST_TextVerticalType`
+   */
+  setVerticalText(value: string | null): void;
+  /**
+   * Set (or clear) `a:tcPr/@horzOverflow` — what a single glyph too wide for the cell does.
+   * `null` removes the attribute; so does `'clip'` in effect, since it is the schema
+   * default, but the attribute is still written as asked.
+   * @throws {InvalidOptionError} when the value is outside `ST_TextHorzOverflowType`
+   */
+  setHorzOverflow(value: string | null): void;
+  /**
+   * Centre the cell's text block horizontally, or stop doing so (`a:tcPr/@anchorCtr`).
+   * `false` removes the attribute rather than writing `"0"`, since `false` is the schema
+   * default and the two are indistinguishable to a renderer.
+   */
+  setAnchorCtr(value: boolean): void;
+  /**
+   * Set the cell's text insets in EMU (`a:tcPr/@marL`/`@marR`/`@marT`/`@marB`).
+   *
+   * Partial: only the sides named are touched, so `{ left: 0 }` flushes the text left and
+   * leaves the other three alone. A side given as `null` has its attribute removed, which
+   * returns it to the schema default (91440 EMU left/right, 45720 top/bottom) — not to
+   * zero. Pass `{}` to change nothing.
+   * @throws {InvalidOptionError} when a value is not a finite number
+   */
+  setMarginsEmu(margins: {
+    left?: number | null;
+    right?: number | null;
+    top?: number | null;
+    bottom?: number | null;
+  }): void;
+  /**
+   * Set (or clear) one of the cell's six borders — the four edges and the two diagonals.
+   *
+   * `null` removes the element entirely, which is "inherit", and is a different thing from
+   * `{ noFill: true }`, which writes an explicit no-border and suppresses whatever would
+   * otherwise be inherited. The element is inserted at its schema position rather than
+   * appended: `CT_TableCellProperties` is a sequence, and an out-of-order `a:tcPr` is
+   * reported by PowerPoint as a corrupt file rather than as a bad edit.
+   *
+   * Colour is either `color` (6-hex, `#` optional) or `schemeColor` (a theme token); giving
+   * both prefers the token, matching how the read side reports them.
+   * @throws {InvalidOptionError} when the width or colour cannot be written
+   */
+  setBorder(edge: TableCellEdge, border: TableCellBorderEdit | null): void;
+  /**
+   * Replace the cell's fill with a solid colour (`a:tcPr/a:solidFill`), or clear it.
+   *
+   * `null` removes the `a:solidFill` and lets the cell inherit from the table style again.
+   * That is not the same as {@link noFill}, which writes an explicit `a:noFill` and so
+   * suppresses the inherited shading. Any competing fill choice (`a:gradFill`,
+   * `a:blipFill`, …) is dropped first — `EG_FillProperties` admits one.
+   * @throws {InvalidOptionError} when `color` is not a 6-digit hex string
+   */
+  setFillColor(color: string | null): void;
+  /**
+   * Replace the cell's fill with a theme colour token (`a:solidFill/a:schemeClr/@val`), or
+   * clear it. Preferred over {@link setFillColor} when the deck's theme should keep
+   * driving the colour.
+   */
+  setFillSchemeColor(token: string | null): void;
+  /**
+   * Write an explicit `<a:noFill/>` on the cell — a transparent cell that shows the table
+   * background (or the slide) through. Distinct from `setFillColor(null)`, which removes
+   * the fill and lets the table style's shading apply again.
+   */
+  noFill(): void;
   /**
    * The cell's solid fill resolved against the table's theme colour context to a
    * literal hex — the table-cell counterpart of
@@ -2030,6 +2372,18 @@ declare class TableCell {
    * `lumMod`/`lumOff`/… transforms applied) — read that for the final colour.
    */
   get resolvedFill(): ResolvedColor | null;
+  /**
+   * Whether the cell carries a fill of its **own** (`a:tcPr` holds an `EG_FillProperties`
+   * child), as opposed to inheriting one from the table style's header/banding rules.
+   *
+   * This is the flag that disambiguates {@link resolvedFill}, which deliberately reports
+   * either — it answers "what colour does this cell render as", and both sources are valid
+   * answers to that. Anything that has to reproduce the cell rather than describe it needs
+   * to know which: baking an inherited banding colour into a copy makes the copy look right
+   * until someone changes its table style, and then nothing moves. `false` for a cell whose
+   * `a:tcPr` is empty or absent, whatever the style graph would render it as.
+   */
+  get hasOwnFill(): boolean;
   /**
    * The cell's picture (image) fill (`a:tcPr/a:blipFill`), or `null` when the cell
    * is not image-filled. The cell counterpart of
@@ -2041,6 +2395,18 @@ declare class TableCell {
    * which a {@link Table} built without them cannot supply.
    */
   get pictureFill(): PictureFill | null;
+  /**
+   * The cell's gradient fill (`a:tcPr/a:gradFill`), or `null` when the cell is not
+   * gradient-filled. The cell twin of {@link Table.gradientFill}, and needed for the same
+   * reason {@link pictureFill} is: {@link resolvedFill} reports `null` for every non-solid
+   * choice, so without this a gradient cell is indistinguishable from an unfilled one.
+   */
+  get gradientFill(): GradientFill | null;
+  /**
+   * The cell's pattern (hatch) fill (`a:tcPr/a:pattFill`), or `null` when the cell is not
+   * pattern-filled.
+   */
+  get patternFill(): PatternFill | 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`.
@@ -2066,6 +2432,53 @@ declare class TableCell {
    * bottom), or `null` when unset (PowerPoint defaults to top).
    */
   get anchor(): string | null;
+  /**
+   * Whether the cell's whole text **block** is centred horizontally within it
+   * (`a:tcPr/@anchorCtr`). `false` when unset — that is the schema default, and it is
+   * what PowerPoint writes nothing for.
+   *
+   * Distinct from a paragraph's `align`, which decides where each *line* sits inside the
+   * text block; this decides where the block sits inside the cell.
+   */
+  get anchorCtr(): boolean;
+  /**
+   * The cell's 3-D bevel (`a:tcPr/a:cell3D`), or `null` when it has none.
+   *
+   * `CT_Cell3D` requires an `a:bevel`, so a present `cell3D` always reports a bevel;
+   * `lightRig` is `null` when the cell leaves the scene lighting to the renderer. Sizes are
+   * reported in **points** (the attributes are EMU), matching how the write option takes them.
+   */
+  get cell3D(): CellThreeD | null;
+  /**
+   * The cell's unique identifier (`a:tc/@id`), or `null` when it has none.
+   *
+   * This is what {@link headerIds} references: a data cell names the header cells that
+   * govern it by their `@id`, which is how a complex table tells a screen reader what a
+   * value means. Unrelated to the shape-level `p:cNvPr/@id` — it is an `xs:string` scoped
+   * to the table, not a slide-wide numeric id.
+   *
+   * **PowerPoint does not write this and strips it on save**, so it will read `null` on
+   * any deck PowerPoint has saved, however it was produced. It is surfaced for decks from
+   * other producers. There is deliberately no write-API counterpart — see
+   * `test/read/fixtures/authoring/probe-table-cell-a11y-and-3d.ps1` for the measurement.
+   */
+  get id(): string | null;
+  /**
+   * The `@id`s of the header cells that govern this cell
+   * (`a:tcPr/a:headers/a:header/@val`), in document order. Empty when the cell declares no
+   * header association — which is the common case, since only a complex table needs one.
+   *
+   * Carries the same caveat as {@link id}: PowerPoint strips `a:headers` on save, so this
+   * is empty on any PowerPoint-saved deck. `Table.firstRowHeader` (`a:tblPr/@firstRow`) is
+   * the header marker PowerPoint does keep.
+   */
+  get headerIds(): string[];
+  /**
+   * How the cell treats a glyph too wide for its text width (`a:tcPr/@horzOverflow`):
+   * `'clip'` cuts it at the cell edge, `'overflow'` lets it draw past. `null` when unset
+   * (PowerPoint clips). Not a wrap flag — cell text always wraps to the column width.
+   */
+  get horzOverflow(): 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.
@@ -2129,6 +2542,20 @@ declare class GroupShape extends Shape {
   protected getOrAddXfrm(): Element;
   protected properties(): Element | null;
   protected getOrAddProperties(): ShapeProperties;
+  /**
+   * The group's own child coordinate space (`p:grpSpPr/a:xfrm/a:chOff` and
+   * `a:chExt`) in EMU, or `null` when the group has no transform or either
+   * element is incomplete.
+   *
+   * Most consumers should not need this: {@link Shape.absoluteFrame} already
+   * composes the whole ancestor chain — child space, group flips and rotations —
+   * and doing that arithmetic per consumer is how a shape in a nested group ends
+   * up subtly displaced. It is here for a *replica* consumer rather than a
+   * *paint* one: rebuilding this group and its children as OOXML needs the
+   * source child space to reproduce the scaling, and without it only groups whose
+   * child space is the identity can be rebuilt.
+   */
+  get childFrame(): ChildFrame | null;
   /** The shapes nested directly inside this group, in document order. */
   get shapes(): AnyShape[];
 }
@@ -2172,7 +2599,7 @@ declare class NotesPlaceholder {
   private readonly relationships;
   constructor(sp: Element, part: Part,
   /** The notes theme context (notesMaster → `theme2.xml`), threaded to {@link textFrame}. */
-  themeContext: FlattenContext,
+  themeContext: ThemeContext,
   /** 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. */
@@ -2228,7 +2655,7 @@ declare class NotesSlide {
    * The notes theme context, resolved through the notesMaster → `theme2.xml` chain
    * and cached. Backs {@link NotesPlaceholder.textFrame}'s `Run.resolvedColor`.
    */
-  themeContext(): FlattenContext;
+  themeContext(): ThemeContext;
   /** 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. */
@@ -2410,7 +2837,7 @@ declare class Placeholder {
   private readonly relationships;
   constructor(sp: Element, part: Part,
   /** The owning master/layout theme context, threaded to {@link textFrame}. */
-  themeContext: FlattenContext,
+  themeContext: ThemeContext,
   /** 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). */
@@ -2482,7 +2909,7 @@ declare class SlideMaster {
    * The master's colour/font context (its `p:clrMap` + theme), resolved once and
    * cached. Backs each {@link Placeholder}'s text frame.
    */
-  themeContext(): FlattenContext;
+  themeContext(): ThemeContext;
 }
 /**
  * A deck's slide layout (`slideLayoutN.xml`) as a modeled object — the gallery entry
@@ -2526,7 +2953,7 @@ declare class SlideLayout {
    * The layout's colour/font context (walked layout → master → theme), resolved once
    * and cached. Backs each {@link Placeholder}'s text frame.
    */
-  themeContext(): FlattenContext;
+  themeContext(): ThemeContext;
 }
 //#endregion
 //#region src/read/api/transition.d.ts
@@ -2655,7 +3082,7 @@ declare class Slide {
    * 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;
+  themeContext(): ThemeContext;
   /** Authoring name of the slide (`p:cSld/@name`), or `null` if unnamed. */
   get name(): string | null;
   /**
@@ -3245,5 +3672,5 @@ declare class Presentation {
   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
+export { Chart as $, GroupShape as A, Recolor as At, Table as B, PictureFill as Bt, CommentAuthor as C, CustomGeometryPath as Ct, NotesPlaceholder as D, LineEnd as Dt, ModernCommentAuthor as E, InnerShadow as Et, isPicture as F, PatternFill as Ft, TableConditionFlags as G, resolveColorElement as Gt, TableCellBorderEdit as H, GradientFill as Ht, GraphicFrame as I, BackgroundFill as It, ChartExAxis as J, TableCellEdge as K, ColorContext as Kt, CellBorder as L, BackgroundSource as Lt, isConnector as M, Reflection as Mt, isGraphicFrame as N, ShapeType as Nt, NotesSlide as O, LineEnds as Ot, isGroupShape as P, SoftEdge as Pt, AxisNumberFormat as Q, CellBorders as R, SlideBackground as Rt, Comment as S, CustomGeometry as St, ModernComment as T, Glow as Tt, TableRow as U, GradientStop as Ut, TableCell as V, PictureFillTile as Vt, ResolvedTableStyle as W, ResolvedColor as Wt, ChartExLegend as X, ChartExDataLabels as Y, ChartExSeries as Z, ThemeColorSlot as _, RunHyperlink as _t, readCustomProperties as a, ChartSeries as at, Tag as b, ChildFrame as bt, Slide as c, AutoShape as ct, TransitionSpeed as d, BodyProperties as dt, ChartAxis as et, ColorMapToken as f, BulletDetail as ft, Theme as g, Run as gt, SlideMaster as h, Paragraph as ht, readCoreProperties as i, ChartLine as it, isAutoShape as j, RecolorColor as jt, AnyShape as k, OuterShadow as kt, TransitionInfo as l, Shape as lt, SlideLayout as m, LineSpacing as mt, CoreProperties as n, ChartFill as nt, AddPictureOptions as o, Connector as ot, Placeholder as p, BulletStyle as pt, ChartEx as q, CustomProperty as r, ChartLegend as rt, AddTextBoxOptions as s, Picture as st, Presentation as t, ChartDataLabels as tt, TransitionInput as u, AutofitMode as ut, ThemeFontFace as v, TextFrame as vt, CommentSchema as w, GeometryCommand as wt, readTagsForPart as x, ConnectionSite as xt, ThemeFontScheme as y, AbsoluteFrame as yt, CellThreeD as z, FillRect as zt };
+//# sourceMappingURL=presentation-CTVPpiwP.d.ts.map