import { ComponentOptionsMixin } from 'vue';
import { ComponentProvideOptions } from 'vue';
import { ComputedRef } from 'vue';
import { CSSProperties as CSSProperties_2 } from 'vue';
import { DefineComponent } from 'vue';
import { Doc } from 'yjs';
import { InjectionKey } from 'vue';
import { MaybeRefOrGetter } from 'vue';
import { PublicProps } from 'vue';
import { Ref } from 'vue';
import { ShallowRef } from 'vue';

declare const __VLS_export: DefineComponent<__VLS_Props, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {} & {
    done: () => any;
}, string, PublicProps, Readonly<__VLS_Props> & Readonly<{
    onDone?: (() => any) | undefined;
}>, {
    scale: number;
}, {}, {}, {}, string, ComponentProvideOptions, false, {}, any>;

declare const __VLS_export_2: DefineComponent<__VLS_Props_2, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {}, string, PublicProps, Readonly<__VLS_Props_2> & Readonly<{}>, {}, {}, {}, {}, string, ComponentProvideOptions, false, {}, any>;

declare const __VLS_export_3: DefineComponent<__VLS_Props_3, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {}, string, PublicProps, Readonly<__VLS_Props_3> & Readonly<{}>, {}, {}, {}, {}, string, ComponentProvideOptions, false, {}, any>;

/**
 * PresentationTransitionOverlay - animates a slide change in presentation mode.
 *
 * It stacks two {@link SlideStage} layers, both scaled-to-fit identically to the
 * underlying presentation frame:
 *   - the **outgoing** (old) slide as a snapshot layer, and
 *   - the **incoming** (new) slide.
 *
 * The active slide's {@link PptxSlideTransition} is mapped to CSS `animation`
 * shorthands (via {@link resolveSlideTransition}); each layer's `z-index` is set
 * from `outgoingOnTop`. When the configured duration elapses the overlay emits
 * `done`, at which point the host should drop the overlay and leave the static
 * incoming slide rendered by its main stage.
 *
 * `PresentationMode` is expected to mount this **only while a transition is
 * playing** (between the outgoing and incoming slides), render nothing of its
 * own animated stage during that window, and remove it on `@done`.
 */
declare type __VLS_Props = {
    /** The outgoing (previous) slide rendered in the exit layer. */
    outgoingSlide: PptxSlide | undefined;
    /** The incoming (new) slide rendered in the entrance layer. */
    incomingSlide: PptxSlide | undefined;
    /** Slide surface dimensions (px). */
    canvasSize: CanvasSize;
    /** Resolved media data URLs, threaded to each {@link SlideStage}. */
    mediaDataUrls: Map<string, string>;
    /** Fit-to-viewport scale (same value the host applies to its main stage). */
    scale?: number;
    /** The transition definition from the incoming slide. */
    transition: PptxSlideTransition | undefined;
};

/**
 * The two morph-only layers `PresentationTransitionOverlay.vue` paints ABOVE
 * its outgoing/incoming pair, split out to keep that file under the
 * project's per-file LOC budget:
 *
 *  - the **lifted** layer: arriving shapes a ghost above them would
 *    otherwise hide for the whole morph, painted here so they dissolve in
 *    where a viewer can see them (issue #146). Their copy on the incoming
 *    layer is held invisible by the plan, so nothing composites twice.
 *  - the **crossfade groups**: pairs the overlay paints BOTH halves of, each
 *    as one isolated group so the halves are SUMMED rather than stacked
 *    (issue #161).
 */
declare type __VLS_Props_2 = {
    liftedSlide: PptxSlide | undefined;
    liftedLayerStyle: CSSProperties_2;
    crossfadeGroups: readonly MorphCrossfadeGroupView[];
    canvasSize: CanvasSize;
    mediaDataUrls: Map<string, string>;
    scale: number;
};

/**
 * FragmentedTransitionLayer - renders one `FragmentedLayer` (from
 * `getFragmentedTransitionDescriptor` in `pptx-viewer-shared`) as N clipped
 * copies of `SlideStage` - the Vue mapping of the seven multi-fragment
 * cinematic transitions (`vortex`, `honeycomb`, `glitter`, `shred`,
 * `fracture`, `curtains`, `airplane`; see `slide-transition-fragments.ts` in
 * `pptx-viewer-shared` for the COM measurement and the pure decision
 * function this maps).
 *
 * Every fragment is `position:absolute` + `clip-path` + a shared
 * `@keyframes` animation (already folded into the injected
 * `SLIDE_TRANSITION_KEYFRAMES_CSS` aggregate) parameterised by CSS custom
 * properties, so the whole set stays transform/opacity-only and
 * GPU-composited with no per-frame JS.
 *
 * Mounted by `PresentationTransitionOverlay.vue` INSIDE its existing
 * `data-pptx-transition-layer` wrapper, in place of a single `SlideStage`,
 * so the outer wrapper's z-index/`data-pptx-transition-fragments` marker are
 * unaffected by this split.
 */
declare type __VLS_Props_3 = {
    layer: FragmentedLayer;
    slide: PptxSlide | undefined;
    canvasSize: CanvasSize;
    mediaDataUrls: Map<string, string>;
    scale: number;
    layerName: 'outgoing' | 'incoming';
};

declare interface AccessibilityCheckOptions {
    /** Minimum WCAG contrast ratio (default 4.5 for AA normal text). */
    minContrastRatio?: number;
    /** Skip contrast checks (useful when background can't be resolved). */
    skipContrast?: boolean;
    /** Skip blank slide checks. */
    skipBlankSlide?: boolean;
}

declare interface AccessibilityIssue {
    type: AccessibilityIssueType;
    severity: AccessibilityIssueSeverity;
    slideIndex: number;
    elementId?: string;
    message: string;
    suggestion: string;
}

declare type AccessibilityIssueSeverity = 'error' | 'warning' | 'tip';

declare type AccessibilityIssueType = 'missingAltText' | 'missingSlideTitle' | 'lowContrast' | 'complexTable' | 'duplicateTitle' | 'blankSlide';

/**
 * Polar-style adjustment handle (`a:ahPolar`) on a custom geometry.
 *
 * Drives a guide via radial distance and angle rather than XY coordinates.
 *
 * @example
 * ```ts
 * const handle: AdjustHandlePolar = {
 *   gdRefR: "adj1",
 *   gdRefAng: "adj2",
 *   posX: "wd2",
 *   posY: "hd2",
 * };
 * // => satisfies AdjustHandlePolar
 * ```
 */
declare interface AdjustHandlePolar {
    /** Guide reference for the radial distance (`@_gdRefR`). */
    gdRefR?: string;
    /** Guide reference for the angle (`@_gdRefAng`). */
    gdRefAng?: string;
    /** Minimum radial value (`@_minR`). */
    minR?: string;
    /** Maximum radial value (`@_maxR`). */
    maxR?: string;
    /** Minimum angle (`@_minAng`). */
    minAng?: string;
    /** Maximum angle (`@_maxAng`). */
    maxAng?: string;
    /** Handle position X from `a:pos/@_x`. */
    posX?: string;
    /** Handle position Y from `a:pos/@_y`. */
    posY?: string;
}

/**
 * XY-style adjustment handle (`a:ahXY`) on a custom geometry.
 *
 * Allows interactive editing of one or two guide values constrained to a
 * rectangular range. Coordinates are formula references (e.g. `"adj1"`,
 * `"w/2"`, `"0"`) preserved verbatim so they can re-emit unchanged.
 *
 * @example
 * ```ts
 * const handle: AdjustHandleXY = {
 *   gdRefX: "adj1",
 *   minX: "0",
 *   maxX: "w",
 *   posX: "adj1",
 *   posY: "h/2",
 * };
 * // => satisfies AdjustHandleXY
 * ```
 */
declare interface AdjustHandleXY {
    /** Guide reference for the X axis (`@_gdRefX`). */
    gdRefX?: string;
    /** Guide reference for the Y axis (`@_gdRefY`). */
    gdRefY?: string;
    /** Minimum X value, as a formula reference (`@_minX`). */
    minX?: string;
    /** Maximum X value (`@_maxX`). */
    maxX?: string;
    /** Minimum Y value (`@_minY`). */
    minY?: string;
    /** Maximum Y value (`@_maxY`). */
    maxY?: string;
    /** Handle position X (formula or literal) from `a:pos/@_x`. */
    posX?: string;
    /** Handle position Y from `a:pos/@_y`. */
    posY?: string;
}

/**
 * Pure geometry helpers for the align / distribute editor operations.
 *
 * These functions operate over a list of slide elements (anything carrying the
 * `{ id, x, y, width, height }` bounding-box fields of {@link PptxElement}) and
 * return a `Map` keyed by element `id` describing the *new* position(s) for the
 * elements that need to move. Elements that already sit on the target edge (or
 * the two outer-most elements during distribution) are still included with
 * their unchanged coordinate so callers can apply the whole map uniformly; the
 * map only ever contains the axis that the operation touches.
 *
 * The reference box the selection is aligned against is either the union of
 * the selected boxes (PowerPoint's "Align Selected Objects") or the slide
 * itself ("Align to Slide"). PowerPoint defaults to the slide whenever a
 * single object is selected, which is why a one-element selection is not a
 * no-op once a `slideSize` is supplied: Align Center on a lone title is one
 * of the commonest arrange gestures there is.
 *
 * The helpers are deliberately framework-agnostic: no DOM, no Vue reactivity,
 * no side effects. The host wires them into the editor by feeding the current
 * selection in and applying the returned `Map` via its element-transform
 * operation (one batched history entry per call).
 */
/** Edge / centre that {@link alignElements} can snap a selection to. */
declare type AlignEdge = 'left' | 'centerH' | 'right' | 'top' | 'middle' | 'bottom';

/**
 * The bucket a ribbon gallery click targets. Widens the three preset buckets
 * with `motionPath` so a binding's single "apply animation" callback can carry
 * a motion-path preset id too, instead of every binding growing a second
 * callback threaded through the same six components.
 */
declare type AnimationApplyGroup = 'entrance' | 'emphasis' | 'exit' | 'motionPath';

/** A single click-triggered group of animations that play as one step. */
export declare interface AnimationClickGroup {
    /** Animations belonging to this group, in document order. */
    animations: PptxElementAnimation[];
}

/**
 * Structured representation of a single OOXML animation condition
 * from `p:cond` elements inside `p:stCondLst` or `p:endCondLst`.
 *
 * Conditions control when an animation starts or ends, and can reference
 * events, time delays, and target time node IDs.
 *
 * @example
 * ```ts
 * const cond: AnimationCondition = {
 *   event: "onClick",
 *   delay: 0,
 *   targetShapeId: "shape_5",
 * };
 * ```
 */
declare interface AnimationCondition {
    /** Event that triggers the condition. */
    event?: AnimationConditionEvent;
    /**
     * The media element/bookmark this condition fires for, when
     * {@link event} is `onMediaBookmark`. See {@link PptxMediaBookmarkTarget}.
     */
    bookmarkTarget?: PptxMediaBookmarkTarget;
    /** Delay in milliseconds (from `@_delay`). "indefinite" is represented as -1. */
    delay?: number;
    /** Target time node ID reference (from `@_tn`). */
    targetTimeNodeId?: number;
    /** Target shape ID from `p:tgtEl/p:spTgt/@spid`. */
    targetShapeId?: string;
    /** Whether the condition targets a slide (from `p:tgtEl/p:sldTgt`). */
    targetSlide?: boolean;
    /** Full target choice, including `p:sndTgt` and `p:inkTgt`. */
    target?: PptxAnimationTarget;
}

/**
 * Event types for animation conditions from `p:cond/@evt`.
 *
 * These map directly to OOXML condition event attribute values
 * (ISO/IEC 29500-1 S19.5.28 CT_TLTimeCondition).
 */
declare type AnimationConditionEvent = 'onBegin' | 'onEnd' | 'begin' | 'end' | 'onClick' | 'onMouseOver' | 'onMouseOut' | 'onNext' | 'onPrev' | 'onStopAudio' | 'onDblClick' | 'onMediaBookmark';

declare interface AnimationInput {
    preset: PptxAnimationPreset;
    trigger?: PptxAnimationTrigger;
    duration?: number;
    delay?: number;
}

export declare interface AnnotationPoint {
    x: number;
    y: number;
}

export declare interface AnnotationStroke {
    id: string;
    points: AnnotationPoint[];
    color: string;
    width: number;
    opacity: number;
}

/**
 * Autosave status, surfaced for status-pill rendering.
 *
 *  - `idle`     : nothing has been saved yet (or no edits since mount).
 *  - `disabled` : autosave is inactive because requirements are not met.
 *  - `saving`   : an `onSave` invocation is currently in flight.
 *  - `saved`    : the most recent save succeeded.
 *  - `error`    : the most recent save threw.
 */
export declare type AutosaveStatus = 'idle' | 'disabled' | 'saving' | 'saved' | 'error';

/**
 * Timer-injection seam so the debounce window is testable with
 * `vi.useFakeTimers()`. Defaults to the global `setTimeout` /
 * `clearTimeout`; tests can leave them unset (fake timers patch the
 * globals) or override explicitly.
 */
export declare interface AutosaveTimerApi {
    setTimer: (handler: () => void, timeoutMs: number) => number;
    clearTimer: (id: number) => void;
}

/**
 * Structural interface for the lazily-imported Yjs awareness surface. Every
 * binding's live `y-protocols/awareness` `Awareness` instance satisfies this.
 */
declare interface AwarenessLike {
    clientID?: number;
    setLocalStateField: (field: string, value: unknown) => void;
    getStates: () => Map<number, Record<string, unknown>>;
    on: (event: string, cb: () => void) => void;
    off?: (event: string, cb: () => void) => void;
}

declare type BackgroundInput = {
    type: 'solid';
    color: string;
} | {
    type: 'gradient';
    /**
     * Slide backgrounds are stored as a ready-made CSS gradient string
     * (`PptxSlide.backgroundGradient`), so this is a CSS
     * `linear-gradient()` angle: degrees clockwise from "to top"
     * (`90` = left to right, `180` = top to bottom). Defaults to `180`.
     */
    angle?: number;
    stops: Array<{
        color: string;
        position: number;
    }>;
} | {
    type: 'image';
    source: string;
};

/**
 * Every action card the File-tab backstage can show, keyed by the operation it
 * triggers rather than by its wording.
 *
 * The five bindings used to hardcode a title and a body string each, which made
 * the whole backstage untranslatable and let the copy drift: the same card
 * carried four different descriptions depending on which binding you opened it
 * in. Both halves now live here as a dictionary key plus an English fallback,
 * so a wording change lands everywhere at once and a translator only has to
 * translate it once.
 */
declare type BackstageCardId = 'protect' | 'inspect' | 'embedFonts' | 'signatures' | 'versionHistory' | 'saveAsPptx' | 'saveAsPpsx' | 'saveAsPptm' | 'saveAsPpt' | 'pdf' | 'png' | 'video' | 'gif' | 'json' | 'copyImage' | 'print' | 'share';

declare type BackstagePage = 'home' | 'new' | 'open' | 'info' | 'save' | 'saveAs' | 'print' | 'share' | 'export' | 'close' | 'account' | 'options';

declare interface BehaviorBase {
    /** Lower-cased `p:attrNameLst` entries, in document order. */
    attrNames: string[];
    /** `p:cBhvr/@additive` (`base`, `sum`, `repl`, `mult`, `none`). */
    additive?: string;
    timing: PptxAnimationBehaviorTiming;
}

/**
 * 3-D effect properties, text warp (WordArt) presets, and scene/shape bevel
 * definitions parsed from OOXML `a:sp3d`, `a:scene3d`, and `a:bodyPr/a:prstTxWarp`.
 *
 * @module pptx-types/three-d
 */
/**
 * Bevel preset type tokens from OOXML `a:bevelT/@prst` / `a:bevelB/@prst`.
 *
 * @example
 * ```ts
 * const bevel: BevelPresetType = "circle";
 * // => "circle" — one of: "circle" | "relaxedInset" | "cross" | "coolSlant" | "angle" | …
 * ```
 */
declare type BevelPresetType = 'circle' | 'relaxedInset' | 'cross' | 'coolSlant' | 'angle' | 'softRound' | 'convex' | 'slope' | 'divot' | 'riblet' | 'hardEdge' | 'artDeco' | 'none';

/** Bounding box passed to every layout function. */
declare interface BoundingBox {
    width: number;
    height: number;
}

/**
 * Splits an ordered animation list into click groups. The first animation
 * always begins a group even if it isn't explicitly `onClick` (PowerPoint shows
 * the first build on the first advance). Subsequent `withPrevious` /
 * `afterPrevious` animations attach to the group in progress.
 */
export declare function buildClickGroups(animations: readonly PptxElementAnimation[]): AnimationClickGroup[];

/**
 * Structured bullet metadata attached to the first {@link TextSegment}
 * of each paragraph.
 *
 * Describes how the paragraph bullet should render: character bullets
 * (`char`), auto-numbered lists (`autoNumType`), or picture bullets
 * (`imageRelId` / `imageDataUrl`). Set `none: true` when `a:buNone`
 * explicitly suppresses the bullet.
 *
 * @example
 * ```ts
 * // Simple character bullet:
 * const bullet: BulletInfo = { char: "•", color: "#333333" };
 *
 * // Auto-numbered list starting at 1:
 * const numbered: BulletInfo = {
 *   autoNumType: "arabicPeriod",
 *   autoNumStartAt: 1,
 * };
 * // => { char: "•", color: "#333333" } and { autoNumType: "arabicPeriod", autoNumStartAt: 1 }
 * ```
 */
declare interface BulletInfo {
    /** Bullet character (e.g. "•", "-", "»") from `a:buChar`. */
    char?: string;
    /** Auto-numbering type (e.g. "arabicPeriod", "romanUcPeriod") from `a:buAutoNum`. */
    autoNumType?: string;
    /** Auto-numbering start value. */
    autoNumStartAt?: number;
    /**
     * Auto-numbering ORDINAL OFFSET: the zero-based distance of this paragraph
     * within its own numbered list, such that
     * `autoNumStartAt + paragraphIndex` is the ordinal to render. Despite the
     * name it is NOT the paragraph's position in the text body; the two agree
     * only for a list that starts at the first paragraph and is never
     * interrupted.
     *
     * It has to be the offset rather than the raw position because every
     * consumer that re-derives a marker from `BulletInfo` alone (the renderer's
     * `resolveParagraphBullet`, the Markdown converter's `resolveListMarker`)
     * computes `autoNumStartAt + paragraphIndex`. The load path resolves the
     * real sequence itself, restarting the count after any paragraph that
     * interrupts the list, and publishes the offset here so those consumers
     * land on the same number. With the raw position they did not, and BOTH
     * markers were painted ("3.1. Item"), because the paragraph builder drops
     * the parsed marker segment only when the two strings agree.
     *
     * Runtime-only: derived at parse time and never serialized. OOXML has no
     * counterpart (`a:buAutoNum` carries only `@type` and `@startAt`), so the
     * writer neither reads nor emits it.
     */
    paragraphIndex?: number;
    /** Bullet font family from `a:buFont`. */
    fontFamily?: string;
    /**
     * PANOSE font-matching hint from `a:buFont/@panose`. `a:buFont` is a
     * CT_TextFont, the same complex type as `a:latin`/`a:ea`/`a:cs`/`a:sym`
     * (which carry the equivalent `TextStyle.latinFontPanose` etc.), so a
     * bullet's own PANOSE/pitch-family/charset decide the fallback glyph
     * PowerPoint substitutes when the named typeface is missing.
     */
    fontPanose?: string;
    /** Font pitch-and-family byte from `a:buFont/@pitchFamily`. */
    fontPitchFamily?: number;
    /** Font character-set byte from `a:buFont/@charset`. */
    fontCharset?: number;
    /** Bullet size as percentage of text font size from `a:buSzPct`. */
    sizePercent?: number;
    /** Bullet size in points from `a:buSzPts`. */
    sizePts?: number;
    /** Bullet color as hex string from `a:buClr`. */
    color?: string;
    /**
     * Raw colour-choice XML captured from `<a:buClr>` so that themed bullets
     * (`a:schemeClr`, `a:sysClr`, `a:prstClr`) round-trip with their original
     * identity rather than being flattened to `<a:srgbClr/>` on save.
     */
    colorXml?: XmlObject;
    /**
     * Typed theme colour reference for the bullet colour, set when
     * {@link colorXml} is a plain `a:schemeClr`. Wins on save, same as
     * {@link TextStyle.colorRef}.
     */
    colorRef?: PptxThemeColorRef;
    /** True when `a:buNone` explicitly suppresses bullets. */
    none?: boolean;
    /** Picture bullet: relationship ID from `a:buBlip` → `a:blip[@r:embed]`. */
    imageRelId?: string;
    /** Picture bullet: data URL of the embedded image. */
    imageDataUrl?: string;
    /**
     * Raw `<a:buBlip>` XML captured at parse time. Carries the full blipFill
     * subtree (`a:tile`, `a:stretch`, `a:srcRect`, `a:blip > a:extLst`) so the
     * writer can emit the complete original definition rather than the bare
     * `a:blip[@r:embed]` mapping. When set, the writer prefers it over
     * {@link imageRelId} for emission.
     */
    imageBlipFillXml?: XmlObject;
    /** When true, `<a:buFontTx/>` was specified — inherit the bullet font from
     *  the run text, not from a buFont declaration. */
    fontInherit?: boolean;
    /** When true, `<a:buClrTx/>` was specified — inherit the bullet colour from
     *  the run text. */
    colorInherit?: boolean;
    /** When true, `<a:buSzTx/>` was specified — inherit the bullet size from
     *  the run text font size. */
    sizeInherit?: boolean;
    /**
     * True when this bullet resolution came from the paragraph's OWN `a:pPr`
     * rather than the shape's `a:lstStyle`, an inherited placeholder, or the
     * master's `a:defPPr` / `p:txStyles`. `resolveParagraphBulletInfo` walks
     * that cascade and returns the first match, so without this flag a
     * writer that re-emits every resolved `BulletInfo` in full pins an
     * inherited bullet (e.g. a master `buFont="Arial"` / `buChar="•"`) onto
     * every paragraph's own `a:pPr` the moment the slide is rewritten. The
     * save path only writes the bullet group when this is `true`, mirroring
     * how `paragraphProperties` gates every other per-paragraph field.
     */
    ownedByParagraph?: boolean;
}

/**
 * The right-click menu for the empty slide canvas (no element under the
 * cursor), as distinct from {@link ./context-menu-commands}'s per-element menu.
 *
 * Right-clicking empty canvas used to do nothing at all in every binding: React
 * and Vue both bailed out early (`getElementIdFromEvent` returns `null`, so the
 * handler just returns) rather than opening a menu, and the other three never
 * wired a handler for it either. PowerPoint offers Paste, Layout, Reset,
 * Format Background and view toggles (Grid and Guides, Ruler) from this menu;
 * this module is the one list every binding renders instead of five omissions.
 *
 * @module render/canvas-context-menu-commands
 */
/** Every command the empty-canvas context menu can offer, in no particular order. */
declare type CanvasContextMenuCommandId = 'paste' | 'layout' | 'reset-slide' | 'format-background' | 'grid-and-guides' | 'ruler';

/** Canvas dimensions in pixels. */
declare interface CanvasSize {
    width: number;
    height: number;
}

declare type Catalog = typeof RIBBON_CONTROL_CATALOG;

/** A cell coordinate within a table (0-based). */
declare interface CellCoord {
    row: number;
    col: number;
}

/** The bounding rectangle of a cell selection (inclusive end coordinates). */
declare interface CellRect {
    startRow: number;
    startCol: number;
    endRow: number;
    endCol: number;
}

declare type ChangeCaseMode = 'sentence' | 'lower' | 'upper' | 'capitalize' | 'toggle';

/** Edit shape for axis-title font styling (matches the core op). */
export declare interface ChartAxisTitleStyleEdit {
    fontFamily?: string | null;
    fontSize?: number | null;
    fontBold?: boolean;
    fontColor?: string | null;
}

/**
 * `animation-timeline-build-descriptors` - staged-build (`p:bldChart` /
 * `p:bldDgm`) reveal descriptor types, split out of `animation-timeline-types`
 * to keep that module under the file-size limit. Re-exported from
 * `animation-timeline-types` so existing imports are unaffected.
 *
 * @module render/animation-timeline-build-descriptors
 */
/**
 * Normalized staged-reveal mode for a chart graphic frame, derived from the
 * OOXML `a:bldChart/@bld` (or `p:bldOleChart/@bld`) token:
 *  - `asOne`      the whole chart appears at once (`allAtOnce`).
 *  - `bySeries`   one data series is revealed per stage (`series`).
 *  - `byCategory` one category is revealed per stage (`category`).
 *  - `byElement`  one series/category ELEMENT is revealed per stage
 *                 (`seriesElement` / `categoryElement`).
 */
declare type ChartBuildMode = 'asOne' | 'bySeries' | 'byCategory' | 'byElement';

/** The mutation helpers a chart inspector needs. */
export declare interface ChartEditing extends ChartOpEditing {
    patchChartData: (patch: Partial<PptxChartData>) => void;
    updateStyle: (patch: Partial<PptxChartStyle>) => void;
    updateAxis: (axisType: PptxChartAxisFormatting['axisType'], patch: Partial<PptxChartAxisFormatting>) => void;
    setSeriesColor: (index: number, color: string | null) => void;
    setSeriesTrendline: (index: number, trendline: PptxChartTrendline | null) => void;
    setSeriesErrorBars: (index: number, errBars: PptxChartErrBars | null) => void;
    /** Patch a single series (e.g. rename) in place, preserving the rest. */
    updateSeries: (index: number, patch: Partial<PptxChartSeries>) => void;
    /** Rename one category label. */
    updateCategoryLabel: (catIndex: number, value: string) => void;
    /** Set one numeric value from a raw input string (ignored if not finite). */
    updateValue: (seriesIndex: number, catIndex: number, raw: string) => void;
    /** Append an empty series/category, or remove one by index. */
    addSeries: () => void;
    removeSeries: (seriesIndex: number) => void;
    addCategory: () => void;
    removeCategory: (catIndex: number) => void;
    /** PowerPoint "Chart Filters": hide a currently-visible series. */
    hideSeries: (seriesIndex: number) => void;
    /** PowerPoint "Chart Filters": restore a series it hid. */
    restoreSeries: (filteredIndex: number) => void;
    /** "Value From Cells": edit one cached custom-label string for a series. */
    setLabelsRangeCache: (seriesIndex: number, pointIndex: number, text: string) => void;
}

/** Edit shape for gridline line styling (matches the core op). */
export declare interface ChartGridlineStyleEdit {
    color?: string | null;
    width?: number | null;
    dashStyle?: string | null;
}

declare interface ChartInput {
    series: ChartSeriesInput[];
    categories: string[];
    /** ChartEx hierarchy levels in leaf-to-root XML order. */
    categoryLevels?: string[][];
    title?: string;
    hasLegend?: boolean;
    legendPosition?: 't' | 'b' | 'l' | 'r' | 'tr';
    grouping?: 'clustered' | 'stacked' | 'percentStacked';
    /** Bar series direction (`c:barDir`): vertical columns (default) or horizontal bars. */
    barDirection?: 'col' | 'bar';
}

/** Patch shape for a series marker (subset accepted by the core op). */
export declare interface ChartMarkerEdit {
    symbol?: PptxChartMarkerSymbol;
    size?: number;
    fillColor?: string;
}

/** The SDK-op mutation helpers a chart inspector needs. */
declare interface ChartOpEditing {
    setAxisLogScale: (axisType: PptxChartAxisFormatting['axisType'], opts: {
        enabled: boolean;
        base?: number;
    }) => void;
    setAxisTitleStyle: (axisType: PptxChartAxisFormatting['axisType'], edit: ChartAxisTitleStyleEdit) => void;
    setGridlineStyle: (axisType: PptxChartAxisFormatting['axisType'], which: 'major' | 'minor', edit: ChartGridlineStyleEdit) => void;
    setSeriesMarker: (index: number, marker: ChartMarkerEdit | null) => void;
    setSeriesType: (index: number, seriesType: PptxChartType | null) => void;
    setPointFill: (seriesIndex: number, pointIndex: number, color: string | null) => void;
    setPointExplosion: (seriesIndex: number, pointIndex: number, explosion: number | null) => void;
    setPointMarker: (seriesIndex: number, pointIndex: number, marker: ChartMarkerEdit | null) => void;
    setPointLabel: (seriesIndex: number, pointIndex: number, text: string | null) => void;
}

declare interface ChartOptions extends Partial<ElementPosition> {}

/**
 * A chart embedded via a `<p:graphicFrame>`.
 *
 * Chart data is parsed from the related `chartN.xml` / `chartExN.xml`
 * parts inside the PPTX archive.
 */
declare interface ChartPptxElement extends PptxElementBase {
    type: 'chart';
    chartData?: PptxChartData;
    /** Accessibility description from `p:nvGraphicFramePr/p:cNvPr/@descr`. */
    altText?: string;
    /** Accessibility title from `p:nvGraphicFramePr/p:cNvPr/@title`. */
    title?: string;
    /** Unrecognised graphicFrame extLst extensions, captured verbatim for round-trip. */
    extensionXml?: PptxGraphicFrameExtension[];
}

/**
 * Playback-time chart reveal state derived from AUTHORED `p:graphicEl`
 * indices (see `chart-reveal-descriptor`'s `resolveChartRevealDescriptor`),
 * rather than from click-count/time progress. Present on
 * {@link import('./animation-timeline-group').ElementAnimationState.chartReveal}
 * only when every fired chart-build step for the element carried index data;
 * a renderer prefers this over the progress-based `build`/`ElementBuildState`
 * path when present, since it reflects the real authored reveal set (correct
 * even for a reversed-order or gapped chart build), and falls back to `build`
 * when absent.
 */
declare interface ChartRevealDescriptor {
    /**
     * Whether the chart's background/axes/gridlines/legend should currently be
     * visible: always `true` when the chart's `animateBackground` is `false`
     * ("shown throughout"), otherwise `true` from the first revealed stage
     * onward.
     */
    background: boolean;
    /** Whole series revealed by a `bldStep="series"` effect. */
    series: ReadonlySet<number>;
    /** Whole categories revealed by a `bldStep="category"` effect. */
    categories: ReadonlySet<number>;
    /** Individual cells revealed by a `bldStep="seriesEl"`/`"categoryEl"` effect. */
    points: readonly ChartRevealPoint[];
}

/**
 * One authored `p:graphicEl` reveal unit resolved onto a chart, per
 * `TimelineStepGraphicElement`'s "both indices set" case: a single (series,
 * category) cell revealed by a `bldStep="seriesEl"`/`"categoryEl"` effect.
 */
declare interface ChartRevealPoint {
    seriesIdx: number;
    categoryIdx: number;
}

declare interface ChartSeriesInput {
    name: string;
    values: number[];
    color?: string;
    boxWhiskerOptions?: PptxChartBoxWhiskerOptions;
    histogramOptions?: PptxChartHistogramOptions;
    waterfallOptions?: PptxChartWaterfallOptions;
    regionMapOptions?: PptxChartRegionMapOptions;
    treemapOptions?: PptxChartTreemapOptions;
}

/**
 * `@keyframes` backing every cinematic transition. Fold into the injected
 * aggregate (`SLIDE_TRANSITION_KEYFRAMES`) so these animate wherever it is
 * injected. `pptx-tr-fade-in` (reused by wind/fracture/airplane incoming) is
 * already defined in the core block, so it is intentionally not redefined here.
 */
export declare const CINEMATIC_TRANSITION_KEYFRAMES: string;

/** Parsed `clrChange` effect, as carried on `PptxImageEffects`. */
export declare type ClrChangeEffect = NonNullable<PptxImageEffects['clrChange']>;

/**
 * Who asked for the deck that just finished loading, and what that means for a
 * room that already holds slides.
 *
 * Every binding brackets its content-load with an adoption check: when a load
 * lands while a collaboration session is up and the shared doc already has
 * slides, the ROOM wins and the freshly parsed deck is thrown away. That rule
 * exists for one case only - a late joiner whose bootstrap deck (the blank or
 * sample deck the host mounted the viewer with) finishes parsing after the
 * room's real slides arrived, which would otherwise clobber them with nothing
 * left to repair it, since the doc itself never changed.
 *
 * Applied to EVERY load it also swallows the deck a user deliberately opens
 * during a session. Joining a room and then opening a file left the viewer on
 * the room's blank starter deck: the file parsed, was committed, and was
 * immediately overwritten (reproduced in the vanilla demo - a 7-slide deck
 * opened in a room settled back to the room's 1 slide, and the bigger the file
 * the longer the window). Opening a file is an act of authorship, so it is
 * published to the room instead.
 *
 * @module render/collaboration-load-origin
 */
/**
 * Why a content load ran.
 *
 * - `bootstrap`: the deck the host handed the viewer at mount (`source`), or a
 *   session restore. Nobody chose it during the session.
 * - `user`: opened during the session - File > Open, a recent file, a dropped
 *   file, or a host calling the load API.
 */
declare type CollabLoadOrigin = 'bootstrap' | 'user';

/**
 * Real-time collaboration configuration.
 *
 * The same shape is accepted by every framework binding.
 */
declare interface CollaborationConfig {
    /** Unique identifier for the collaboration room (alphanumeric, hyphens, underscores). */
    roomId: string;
    /**
     * WebSocket server URL for the Yjs provider (e.g. "wss://collab.example.com").
     * Ignored (may be empty) for `externalSession` or when `transport` is `'webrtc'`.
     */
    serverUrl: string;
    /** Transport to use. Defaults to `'websocket'`. */
    transport?: CollaborationTransport;
    /**
     * Use the host's document, awareness and transport instead of creating a
     * provider. Transport, serverUrl, signaling and authToken are ignored. The
     * viewer only detaches its listeners and presence on stop; it never destroys
     * these resources. Keep this object stable and report readiness via subscribe.
     */
    externalSession?: ExternalCollaborationSession;
    /**
     * WebRTC signaling server URLs (only used when `transport` is `'webrtc'`).
     * Defaults to y-webrtc's built-in public signaling list. Same-browser tabs
     * sync via BroadcastChannel regardless of signaling availability.
     */
    signaling?: string[];
    /** Display name for the local user. */
    userName: string;
    /** Avatar URL for the local user (optional). */
    userAvatar?: string;
    /** Hex colour for the local user's cursor/presence indicator. */
    userColor?: string;
    /** Optional authentication token sent with the WebSocket handshake. */
    authToken?: string;
    /** Role in the session; defaults to `'collaborator'`. */
    role?: CollaborationRole;
    /**
     * Whether this client created the room or joined an existing room. Providers
     * do not use this value, but hosts can use it to avoid publishing local file
     * bytes when handling a join request. Omitted values retain the legacy
     * create-session behaviour.
     */
    sessionIntent?: CollaborationSessionIntent;
    /**
     * Elected-writer write-back callback (Area 3 of the C3 hardening plan).
     *
     * When the local user has `role: 'owner'`, the binding debounces changes and
     * serializes the current Y.Doc state to a PPTX byte array, then calls this
     * callback so the host can persist the snapshot. Only one writer (the owner)
     * does this; other collaborators never trigger write-back, eliminating the
     * last-save-wins problem.
     */
    onWriteBack?: (bytes: Uint8Array) => void;
    /**
     * Debounce delay (ms) between the last Y.Doc change and the write-back
     * invocation. Defaults to 5000 ms. Set to 0 to write back on every change
     * (not recommended for large documents).
     */
    writeBackDebounceMs?: number;
}

declare interface CollaborationInlineSnapshot extends CollaborationTextSnapshot {
    readonly inline: InlineTextEditSnapshot;
}

declare interface CollaborationLivePatcher {
    /** Bind a mounted native editor; its handle must be disposed on unmount. */
    beginTextEdit?: (slideId: string | undefined, elementId: string, onChange?: () => void, ownsModel?: (element: PptxElement) => boolean) => CollaborationTextTarget | undefined;
    /** Attach a live doc (or `null` to go dormant). Pending patches are dropped. */
    configure: (doc: YDocLike | null, factories: YjsFactories | null,
    /** Publish synchronously when the host may revoke write readiness at any time. */
    immediate?: boolean) => void;
    /** True when a doc + factories are attached, i.e. patches will be written. */
    isActive: () => boolean;
    /** Queue interim geometry for an element. */
    patchGeometry: (slideId: string | undefined, elementId: string, geometry: LiveGeometryPatch) => void;
    /** Queue interim text for an element (remapped over `source`'s segments). */
    patchText: (slideId: string | undefined, elementId: string, text: string, source?: LiveTextSource) => void;
    /** Write everything queued right now (call on gesture end / edit commit). */
    flush: () => void;
    /** Drop pending work, cancel timers and detach the doc. */
    dispose: () => void;
}

/** Collaboration role within a session. */
declare type CollaborationRole = 'owner' | 'collaborator' | 'viewer';

/** How the local user entered a collaboration session. */
declare type CollaborationSessionIntent = 'create' | 'join';

declare interface CollaborationShellState {
    canEdit: boolean;
    status: ConnectionStatus;
    remoteUsers: readonly SanitizedPresence[];
    connectedCount: number;
}

declare interface CollaborationTextSession {
    applyLocalDelta: (delta: readonly DeltaOp[], edit?: LocalTextEdit) => boolean;
    readMerged: () => CollaborationTextSnapshot | undefined;
    adoptMerged: (snapshot: CollaborationTextSnapshot) => boolean;
    /** Capture an offset in the last painted/local draft, not the newer remote string. */
    bookmark: (index: number, association: number) => () => number | null;
    dispose: () => void;
}

/** Opaque acknowledgement identity for an exact remote snapshot painted by an adapter. */
declare interface CollaborationTextSnapshot {
    readonly delta: readonly DeltaOp[];
}

/** A mounted editor owns this handle, never the document or its provider. */
declare interface CollaborationTextTarget extends CollaborationTextSession {
    readMerged: () => CollaborationInlineSnapshot | undefined;
    /** A bookmark follows character identity rather than a mutable numeric offset. */
    bookmark: (index: number, association: number) => () => number | null;
}

/**
 * Collaboration transport.
 *
 * - `'websocket'` (default): y-websocket against `serverUrl`.
 * - `'webrtc'`: y-webrtc peer-to-peer; needs no document server. Peers meet
 *   through the `signaling` servers (WebRTC signaling only, no document data)
 *   and same-browser tabs additionally sync via BroadcastChannel even without
 *   any signaling server, which makes this mode usable from static hosting.
 */
declare type CollaborationTransport = 'websocket' | 'webrtc';

declare interface CompareResult {
    diffs: SlideDiff[];
    baseSlideCount: number;
    compareSlideCount: number;
    addedCount: number;
    removedCount: number;
    changedCount: number;
    unchangedCount: number;
}

/**
 * Pure next-selection computation for a cell click. Shift+click within the same
 * table (anchored at the previous selection) yields a rectangular multi-cell
 * selection expanded across any merges it overlaps; any other click selects the
 * single clicked cell. Mirrors React's `table-render` onClick branch.
 */
export declare function computeCellSelection(prev: TableSelectionState | null, elementId: string, rowIndex: number, columnIndex: number, shiftKey: boolean, tableData: PptxTableData): TableSelectionState;

/** Compute current counts rather than trusting potentially stale app.xml totals. */
export declare function computeDocumentStatistics(slides: readonly PptxSlide[], coreProperties: PptxCoreProperties | undefined): DocumentStatistics;

/**
 * Compute the elapsed time (ms) between a start timestamp and `now`, subtracting
 * any accumulated paused time and the open pause segment. Returns 0 when not
 * started. Never negative.
 *
 * @param startTime - Timestamp (ms) the timer started, or `null` if not started.
 * @param now - The reference "now" timestamp (ms).
 * @param pausedAccumulatedMs - Already-accumulated paused time (ms).
 * @param pauseStart - Timestamp (ms) the current pause began, or `null`.
 */
export declare function computeElapsed(startTime: number | null, now: number, pausedAccumulatedMs?: number, pauseStart?: number | null): number;

/**
 * Connection site (`a:cxn`) on a custom geometry.
 *
 * Defines a point on a custom shape that connectors may snap to.
 *
 * @example
 * ```ts
 * const cxn: ConnectionSite = { ang: "0", posX: "0", posY: "hd2" };
 * // => satisfies ConnectionSite
 * ```
 */
declare interface ConnectionSite {
    /** Approach angle (`@_ang`) — formula or literal degree-1/60000 value. */
    ang?: string;
    /** Site position X from `a:pos/@_x`. */
    posX?: string;
    /** Site position Y from `a:pos/@_y`. */
    posY?: string;
}

/** Connection lifecycle states for the Yjs WebSocket provider. */
declare type ConnectionStatus = 'disconnected' | 'connecting' | 'connected' | 'error';

/**
 * Arrow head types for connector start/end.
 *
 * Maps to `a:headEnd/@type` and `a:tailEnd/@type` in OOXML.
 *
 * @example
 * ```ts
 * const arrow: ConnectorArrowType = "triangle";
 * // => "triangle" — one of: none | triangle | stealth | diamond | oval | arrow
 * ```
 */
declare type ConnectorArrowType = 'none' | 'triangle' | 'stealth' | 'diamond' | 'oval' | 'arrow';

/**
 * Connector connection point reference — links a connector endpoint to a
 * specific shape on the slide.
 *
 * When both `shapeId` and `connectionSiteIndex` are set, the connector
 * end snaps to that shapes’s connection site and “follows” the shape when
 * it is moved.
 *
 * @example
 * ```ts
 * const start: ConnectorConnectionPoint = {
 *   shapeId: "shape_1",
 *   connectionSiteIndex: 2,
 * };
 * // => { shapeId: "shape_1", connectionSiteIndex: 2 } satisfies ConnectorConnectionPoint
 * ```
 */
declare interface ConnectorConnectionPoint {
    /** ID of the shape this connector endpoint is attached to. */
    shapeId?: string;
    /** Connection site index on the target shape (0-based). */
    connectionSiteIndex?: number;
}

declare interface ConnectorOptions extends Partial<ElementPosition> {
    type?: 'straight' | 'bent' | 'curved';
    stroke?: StrokeInput;
    startArrow?: ConnectorArrowType;
    endArrow?: ConnectorArrowType;
    from?: {
        elementId: string;
        site: number;
    };
    to?: {
        elementId: string;
        site: number;
    };
}

/**
 * A connector (straight, bent, or curved line between shapes).
 *
 * Connector endpoints can snap to specific shapes via
 * `shapeStyle.connectorStartConnection` / `connectorEndConnection`.
 *
 * @example
 * ```ts
 * const line: ConnectorPptxElement = {
 *   type: "connector",
 *   id: "cxn_1", x: 100, y: 100, width: 200, height: 0,
 *   shapeStyle: {
 *     strokeColor: "#333",
 *     connectorEndArrow: "triangle",
 *   },
 * };
 * // => satisfies ConnectorPptxElement
 * ```
 */
declare interface ConnectorPptxElement extends PptxElementBase, PptxTextProperties, PptxShapeProperties, PptxNonVisualDescription {
    type: 'connector';
}

/**
 * Source of the container element observed for container-based breakpoints:
 * either a Vue `Ref` (e.g. a `templateRef`) or a plain getter. Resolved lazily
 * each time the observer (re)reads it so late-mounted refs are picked up.
 */
export declare type ContainerSource = Ref<HTMLElement | null | undefined> | (() => HTMLElement | null | undefined);

/**
 * A single ink stroke within a {@link ContentPartPptxElement}.
 */
declare interface ContentPartInkStroke {
    path: string;
    color: string;
    width: number;
    opacity: number;
    /**
     * Per-point pressure values (0-1) for this stroke.
     *
     * When present, the renderer uses these values to produce
     * variable-width strokes that reflect stylus/pen pressure.
     */
    pressures?: number[];
    /**
     * Per-point pen-tilt lean direction (radians), decoded from the source
     * InkML's `OTx`/`OTy` tilt-offset channels or its `AZIMUTH` channel.
     *
     * When present (paired with {@link tiltMagnitudes}), the renderer widens
     * each point perpendicular to the lean direction, approximating a
     * calligraphic (chisel-tip) nib. Absent when the source declared no tilt
     * channel, in which case rendering is unaffected.
     */
    tiltAngles?: number[];
    /**
     * Per-point pen-tilt strength (0 upright, 1 maximally leaned), paired with
     * {@link tiltAngles}.
     */
    tiltMagnitudes?: number[];
    /**
     * Which InkML channel pair {@link tiltAngles}/{@link tiltMagnitudes} were
     * decoded from: `'azimuthAltitude'` when the source declared `AZIMUTH`
     * (optionally paired with `ALTITUDE`); omitted (implying `OTx`/`OTy`, i.e.
     * `'vector'`) otherwise, including for tilt this library itself captured
     * from the Draw tool's `PointerEvent.tiltX`/`tiltY`.
     *
     * A save that has to rewrite this content part's InkML (see
     * `inkml-content-part-writer.ts`) uses this to re-declare the SAME channel
     * pair the file already used, rather than always converting to `OTx`/`OTy`;
     * the rendered lean is identical either way; only the written channel
     * NAMES differ.
     */
    tiltEncoding?: 'vector' | 'azimuthAltitude';
    /**
     * Per-point timestamps (milliseconds), decoded from the source InkML
     * trace's `T` channel when it declared one.
     *
     * Absent for the overwhelming majority of real decks: PowerPoint's own
     * SaveAs output declares only `X`/`Y` and has no per-point time channel at
     * all (see `contentpart-real-ink-roundtrip.test.ts`'s fixture), so this is
     * populated only for InkML sources that genuinely author one (a captured
     * digitizer session, OneNote, a Surface Hub export). When present, ink
     * replay ("watch the ink get drawn") uses each stroke's own first/last
     * timestamp to time its reveal instead of the fixed per-stroke cascade; see
     * `pptx-viewer-shared`'s `render/ink-replay-timeline.ts`.
     */
    pointTimestamps?: number[];
}

/**
 * A content-part element wrapped in `mc:AlternateContent`.
 *
 * Typically contains ink strokes from modern PowerPoint pen/highlighter.
 */
declare interface ContentPartPptxElement extends PptxElementBase {
    type: 'contentPart';
    /** Ink strokes contained in this content part. */
    inkStrokes?: ContentPartInkStroke[];
    /** Package path of the related InkML part. */
    inkPartPath?: string;
    /** Parsed InkML root retained for unknown-node preservation on dirty save. */
    inkPartRawXml?: XmlObject;
}

/** Every command a canvas context menu can offer, in no particular order. */
declare type ContextMenuCommandId = 'copy' | 'cut' | 'paste' | 'duplicate' | 'edit-text' | 'edit-points' | 'bring-forward' | 'send-backward' | 'bring-front' | 'send-back' | 'ai-ask' | 'ai-fix' | 'comment' | 'hyperlink' | 'table-insert-row-above' | 'table-insert-row-below' | 'table-delete-row' | 'table-insert-col-left' | 'table-insert-col-right' | 'table-delete-col' | 'table-merge-selected' | 'table-merge-right' | 'table-merge-down' | 'table-split' | 'group' | 'ungroup' | 'crop' | MergeShapesCommandId | 'save-as-picture' | 'edit-alt-text' | 'size-and-position' | 'format-shape' | 'delete';

/**
 * ContextMenu: generic right-click menu for the Vue editor.
 *
 * Vue port of the React `ContextMenu` component (see
 * `packages/react/src/viewer/components/ContextMenu.tsx`), generalised into a
 * data-driven menu: the caller supplies the item list and maps `select(id)`
 * back to editor operations.
 */
declare interface ContextMenuItem {
    /** Stable id emitted via `select`. Ignored for separators. */
    id: string;
    /** Visible label. */
    label: string;
    /** When true the item is shown greyed-out and is non-interactive. */
    disabled?: boolean;
    /** When true the entry renders as a divider instead of a button. */
    separator?: boolean;
    /**
     * A checkbox-style toggle (Grid and Guides, Ruler) in this state, rather
     * than a one-shot command. Omitted for ordinary commands, which keep
     * `role="menuitem"`.
     */
    checked?: boolean;
}

/** Reactive open/position/target state for the element context menu. */
export declare interface ContextMenuState {
    open: boolean;
    x: number;
    y: number;
    elementId: string | null;
}

export declare function countWords(text: string | undefined): number;

/** Build a new stroke for the given pen/highlighter tool at a start point. */
export declare function createStroke(tool: 'pen' | 'highlighter', x: number, y: number, penColor: string, highlighterColor: string): AnnotationStroke;

/** What a crop edit writes back onto the picture element. */
declare type CropElementUpdate = CropInsets & CropRect;

/** The four `a:srcRect` insets as fractions of the image (negative pads). */
declare interface CropInsets {
    cropLeft: number;
    cropTop: number;
    cropRight: number;
    cropBottom: number;
}

/** An axis-aligned rectangle in slide pixels. */
declare interface CropRect {
    x: number;
    y: number;
    width: number;
    height: number;
}

/** Minimal CSS-properties shape: kebab-case property → value. */
export declare type CSSProperties = Record<string, string>;

/**
 * A single sub-path in a custom geometry definition (maps to one `a:path`).
 *
 * @example
 * ```ts
 * const path: CustomGeometryPath = {
 *   width: 100,
 *   height: 100,
 *   segments: [
 *     { type: "moveTo", pt: { x: 0, y: 0 } },
 *     { type: "lineTo", pt: { x: 100, y: 100 } },
 *   ],
 * };
 * // => satisfies CustomGeometryPath
 * ```
 */
declare interface CustomGeometryPath {
    /** Coordinate-space width for this sub-path. */
    width: number;
    /** Coordinate-space height for this sub-path. */
    height: number;
    /** Ordered list of drawing segments. */
    segments: CustomGeometrySegment[];
    /** Path fill mode (`a:path/@fill`): norm, lighten, lightenLess, darken, darkenLess, none. */
    fillMode?: 'norm' | 'lighten' | 'lightenLess' | 'darken' | 'darkenLess' | 'none';
    /** Whether the path is stroked (`a:path/@stroke`). */
    stroke?: boolean;
    /** 3D extrusion compatibility (`a:path/@extrusionOk`). */
    extrusionOk?: boolean;
}

/**
 * A single point in a custom geometry path.
 *
 * @example
 * ```ts
 * const pt: CustomGeometryPoint = { x: 100, y: 200 };
 * // => satisfies CustomGeometryPoint
 * ```
 */
declare interface CustomGeometryPoint {
    x: number;
    y: number;
}

/**
 * Auxiliary raw XML preserved from `a:custGeom` for round-trip serialization.
 * These are stored opaquely so adjustment guides, handles, connection sites,
 * and the text rectangle are not lost when a custGeom is edited and saved.
 */
declare interface CustomGeometryRawData {
    /** Raw `a:avLst` XML content (adjustment value list). */
    avLstXml?: unknown;
    /** Raw `a:gdLst` XML content (guide list). */
    gdLstXml?: unknown;
    /** Raw `a:ahLst` XML content (adjustment handles). */
    ahLstXml?: unknown;
    /** Raw `a:cxnLst` XML content (connection sites). */
    cxnLstXml?: unknown;
    /** Raw `a:rect` XML content (text rectangle). */
    rectXml?: unknown;
    /**
     * Raw `a:pathLst` XML content: every `a:path`'s formula-bearing `a:pt`
     * x/y attributes, `a:arcTo` params, `a:close`, and per-path `@w`/`@h`/
     * `@fill`/`@stroke`/`@extrusionOk`, preserved verbatim (not the
     * parse-time-resolved numbers in `customGeometryPaths`). Lets a live
     * `shapeAdjustments` drag re-evaluate the outline against the CURRENT
     * guide values instead of the ones baked in at parse time; see
     * `geometry/custom-geometry-live-eval.ts`.
     */
    pathLstXml?: unknown;
}

/**
 * A segment within a custom geometry path.
 *
 * Discriminated union over `type` — can be a moveTo, lineTo,
 * cubic Bézier, quadratic Bézier, or close command.
 *
 * @example
 * ```ts
 * const segments: CustomGeometrySegment[] = [
 *   { type: "moveTo", pt: { x: 0, y: 0 } },
 *   { type: "lineTo", pt: { x: 100, y: 0 } },
 *   { type: "lineTo", pt: { x: 100, y: 100 } },
 *   { type: "close" },
 * ];
 * // => satisfies CustomGeometrySegment[]
 * ```
 */
declare type CustomGeometrySegment = {
    type: 'moveTo';
    pt: CustomGeometryPoint;
} | {
    type: 'lineTo';
    pt: CustomGeometryPoint;
} | {
    type: 'cubicBezTo';
    pts: [CustomGeometryPoint, CustomGeometryPoint, CustomGeometryPoint];
} | {
    type: 'quadBezTo';
    pts: [CustomGeometryPoint, CustomGeometryPoint];
} | {
    type: 'arcTo';
    /** Horizontal radius of the ellipse. */
    wR: number;
    /** Vertical radius of the ellipse. */
    hR: number;
    /** Start angle in 60000ths of a degree. */
    stAng: number;
    /** Sweep angle in 60000ths of a degree. */
    swAng: number;
} | {
    type: 'close';
};

/**
 * Typed text rectangle (`a:rect`) on a custom geometry.
 *
 * Each edge is the formula or literal string preserved from the source XML
 * (`"l"`, `"t"`, `"r"`, `"b"`, or any guide name / formula).
 */
declare interface CustomGeometryTextRect {
    /** Left edge formula reference (`@_l`). */
    l?: string;
    /** Top edge (`@_t`). */
    t?: string;
    /** Right edge (`@_r`). */
    r?: string;
    /** Bottom edge (`@_b`). */
    b?: string;
}

/** A debounced function plus its `cancel` / `flush` controls. */
export declare interface DebouncedCallback<A extends readonly unknown[]> {
    (...args: A): void;
    /** Discard any pending trailing call. */
    cancel: () => void;
    /** Run any pending trailing call right away. */
    flush: () => void;
}

/**
 * What the Protect-Presentation UI knows at save time. `password` is the secret
 * the dialog captured; `passwordProtected` is the separate "is protected" flag
 * some bindings track for the badge. When the flag is explicitly `false` the
 * deck saves in the clear even if a stale secret is still around, so removing
 * a password can never leave the next save encrypted.
 *
 * `purpose` defaults to `'user-file'`; see {@link DeckSavePurpose} for why
 * `'recovery-snapshot'` overrides the password.
 */
declare interface DeckSaveIntent {
    password?: string | null;
    passwordProtected?: boolean;
    purpose?: DeckSavePurpose;
}

/**
 * Why the deck is being serialised, which is a separate question from whether
 * the user protected it.
 *
 * - `user-file` (the default): the bytes leave the viewer as a file. Save,
 *   Save As, Export, the host-facing `getContent()`. Protection applies.
 * - `recovery-snapshot`: the bytes exist only so the viewer can read them back.
 *   The autosave crash-recovery snapshot in IndexedDB, and the internal
 *   re-serialise-then-reload cycle behind "apply theme". Protection does NOT
 *   apply: these are always written in the clear.
 *
 * ## Why a recovery snapshot must stay plaintext
 *
 * Nothing that reads a snapshot back has a password to give it.
 * `readBackstageRecentFile`, `restoreSessionDeck` and the Version History
 * panel's Restore all hand `record.data` straight to `PptxHandler.load()` with
 * no `password` option, and an encrypted package refuses to open without one
 * (`EncryptedFileError`). So an encrypted snapshot is not an inconvenience, it
 * is unreadable: the moment the user turns on protection their crash-recovery
 * data is silently destroyed, which is the exact opposite of what autosave is
 * for.
 *
 * Encrypting it "properly" is not available either. Decrypting on recovery
 * means the key has to outlive the crash the snapshot exists for, so it would
 * have to sit in the same IndexedDB / localStorage as the snapshot itself,
 * next to the ciphertext it unlocks. That is not a security boundary, it is
 * theatre. Prompting the user instead only works if they remember the password
 * of a deck they lost, which is precisely the moment they will not.
 *
 * ## The tradeoff this accepts (deliberately, not by omission)
 *
 * A password-protected deck DOES leave its content in cleartext at rest in the
 * origin's IndexedDB. Anyone with the browser profile, or any script running on
 * the origin, can read it. What limits the exposure: snapshots are scoped to
 * the origin and profile, aged out by the store, and clearable from
 * File > Account > Storage & Privacy (`clearLocalStorageData`). A user who
 * cannot accept plaintext at rest should switch AutoSave off, which stops the
 * snapshot being written at all.
 *
 * The rejected alternative was "skip autosave entirely while a password is
 * set". It removes the plaintext, but it also removes crash recovery without
 * telling anyone, so a crash loses the whole editing session. Losing data
 * quietly is the failure mode we are fixing, not a fix for it.
 */
declare type DeckSavePurpose = 'user-file' | 'recovery-snapshot';

/** Default cap on retained snapshots (oldest dropped first when exceeded). */
export declare const DEFAULT_MAX_VERSIONS = 50;

/**
 * Default Morph duration (ms) for a transition that declares NEITHER an
 * explicit `p14:dur` (which lands in `durationMs` and always wins) NOR a legacy
 * `spd` speed (see {@link TRANSITION_SPEED_DURATION_MS}).
 *
 * A Morph that declares nothing carries no duration hint at all, and desktop
 * PowerPoint then plays it at its own 0.5s fallback (the Duration box shows
 * 0.50 for such slides and the transition measures at half a second); the
 * previous 1.0s/2.0s defaults made those decks play at double PowerPoint
 * speed.
 */
export declare const DEFAULT_MORPH_DURATION_MS = 500;

/** All off: the safe default outside `PowerPointViewer` (tests, isolated thumbnails). */
export declare const DEFAULT_RENDERING_3D_FLAGS: Rendering3DFlags;

/**
 * Default transition duration (ms) when the transition omits `durationMs`. This
 * is the React/Vue default consumed by `resolveSlideTransition`. The Angular
 * binding uses its own (smaller, floored) duration policy.
 */
export declare const DEFAULT_TRANSITION_DURATION_MS = 1000;

declare type DefaultExportFormat = 'pptx' | 'pdf' | 'png';

/**
 * collaboration-text-codec.ts: TextSegment[] <-> Y.Text delta codec used by the
 * collaboration sync layer. Split out of collaboration-sync.ts to keep both
 * modules focused.
 *
 * Exports:
 *  - DeltaOp / YTextLike: structural Yjs text interfaces (no yjs import)
 *  - encodeTextBody: write TextSegment[] into a live YTextLike
 *  - encodeSegmentsToDelta: pure simulation of the delta Y.Text would produce
 *  - decodeDelta / decodeTextBody: delta -> TextSegment[]
 *  - isYTextLike: runtime guard
 */
declare interface DeltaOp {
    insert?: unknown;
    attributes?: Record<string, unknown>;
}

/** Device orientation as reported by the screen / viewport aspect ratio. */
export declare type DeviceOrientation = 'portrait' | 'landscape';

/**
 * Normalized staged-reveal mode for a SmartArt diagram, derived from the OOXML
 * `a:bldDgm/@bld` or `p:bldDgm/@bld` token:
 *  - `asOne`        the whole diagram appears at once (`whole` / `allAtOnce`).
 *  - `byOne`        one node is revealed per stage (`one`, and the assorted
 *                   `depthBy*` / `breadthBy*` / directional traversals).
 *  - `byLvl`        levels are revealed one element at a time (`lvlOne`).
 *  - `byLvlAtOnce`  a whole level is revealed per stage (`lvlAtOnce`).
 */
declare type DiagramBuildMode = 'asOne' | 'byOne' | 'byLvl' | 'byLvlAtOnce';

/**
 * Playback-time SmartArt diagram reveal state derived from AUTHORED
 * `p:graphicEl/p:dgm/@id` indices (see `diagram-reveal-descriptor`'s
 * `resolveDiagramRevealDescriptor`), rather than from click-count/time
 * progress. Present on
 * {@link import('./animation-timeline-group').ElementAnimationState.diagramReveal}
 * only when every fired diagram-build step for the element carried
 * `p:graphicEl` data. A SmartArt renderer prefers this over the
 * progress-based `build` / {@link ElementBuildState} path when present, since
 * it reflects the real authored reveal set (correct even for a
 * reversed-order or by-branch build), and falls back to `build` when absent.
 */
declare interface DiagramRevealDescriptor {
    /**
     * Whether the diagram's background/connector chrome should currently be
     * visible: `true` once any node-revealing or background-revealing
     * (`bldStep="bg"`) step has fired.
     */
    background: boolean;
    /** Data-model point ids (`PptxSmartArtNode.id`) revealed so far. */
    nodeIds: ReadonlySet<string>;
}

declare type DisplayOptimization = 'appearance' | 'compatibility';

/** Axis along which {@link distributeElements} evenly spaces a selection. */
declare type DistributeAxis = 'horizontal' | 'vertical';

/**
 * Payload emitted on save. Mirrors the React `onSave(core, custom, app?)`
 * signature, collapsed into a single patch object so the host can apply it in
 * one call. `app` is only present when manager/company changed.
 */
declare interface DocumentPropertiesSavePatch {
    /** Full edited core-properties draft. */
    core: PptxCoreProperties;
    /** Full edited custom-properties list. */
    custom: PptxCustomProperty[];
    /** Edited app properties (manager/company); omitted when unchanged. */
    app?: Pick<PptxAppProperties, 'manager' | 'company'>;
}

/** Live document statistics derived from the editable slide model. */
export declare interface DocumentStatistics {
    slideCount: number;
    hiddenSlideCount: number;
    noteCount: number;
    elementCount: number;
    wordCount: number;
    paragraphCount: number;
    created: string | undefined;
    modified: string | undefined;
    revision: string | undefined;
    lastModifiedBy: string | undefined;
}

/** Active drawing/inking tool. Mirrors React `DrawingTool`. */
declare type DrawingTool = 'select' | 'pen' | 'highlighter' | 'eraser' | 'freeform';

/** Easing applied to every transition animation. */
export declare const EASE = "ease-in-out";

/** Which of the two behaviours a paragraph asks for. */
declare interface EastAsianBreakOptions {
    /** `a:pPr/@hangingPunct="1"`. */
    hangingPunctuation: boolean;
    /** `a:pPr/@eaLnBrk="0"`: break between any two East Asian characters. */
    breakAnywhere: boolean;
}

export declare interface EditorHistoryResult {
    /** True when there is at least one snapshot to undo to. */
    canUndo: ComputedRef<boolean>;
    /** True when there is at least one snapshot to redo to. */
    canRedo: ComputedRef<boolean>;
    /**
     * Snapshot the current `slides.value` onto the undo stack and clear the redo
     * stack. Call this immediately **before** committing a mutating change.
     */
    pushHistory: (label?: string) => void;
    /** Revert to the previous snapshot, pushing the current state onto redo. */
    undo: () => void;
    /** Re-apply the next snapshot, pushing the current state back onto undo. */
    redo: () => void;
    /** Drop all undo/redo history (e.g. when new content is loaded). */
    clearHistory: () => void;
    /**
     * Apply a new File > Options > Advanced > "Maximum number of undos" value
     * at runtime (`resolveHistoryDepth`). Trims the past stack immediately if
     * the new limit is smaller.
     */
    setMaxDepth: (depth: number) => void;
}

/** A logical editor command produced by one key press. */
declare type EditorKeyActionName = 'undo' | 'redo' | 'copy' | 'cut' | 'paste' | 'duplicate' | 'delete' | 'selectAll' | 'group' | 'ungroup' | 'nudge' | 'prevSlide' | 'nextSlide' | 'escape' | 'find' | 'findReplace' | 'toggleShortcuts' | 'alignLeft' | 'alignCenter' | 'alignRight' | 'alignJustify' | 'increaseFontSize' | 'decreaseFontSize' | 'copyFormat' | 'pasteFormat' | 'newSlide' | 'hyperlink' | 'clearFormatting' | 'cycleSelectionNext' | 'cycleSelectionPrev' | 'pasteSpecial';

export declare interface EditorOperations {
    /** Resolved active slide (or `undefined` when the index is out of range). */
    activeSlide: ComputedRef<PptxSlide | undefined>;
    /** Currently-selected element ids (owned internally if not supplied as input). */
    selectedElementIds: Ref<string[]>;
    /** Append an element to the active slide and select it. */
    addElement: (element: PptxElement) => void;
    /** Shallow-merge `updates` into the element with `elementId` on the active slide. */
    updateElement: (elementId: string, updates: Partial<PptxElement>) => void;
    /** Remove an element from the active slide and drop it from the selection. */
    removeElement: (elementId: string) => void;
    /** Patch an element's geometry (x/y/width/height/rotation). */
    transformElement: (elementId: string, transform: ElementTransform) => void;
    /** Alias of {@link transformElement}: mirrors the React "move" semantics. */
    moveElement: (elementId: string, transform: ElementTransform) => void;
    /**
     * Deep-clone an element (new ids via core `duplicateElement`), offset it
     * slightly, append it, and select the copy. Returns the new element's id.
     */
    duplicateElement: (elementId: string) => string | undefined;
    /** Swap an element one step later in z-order (towards the front). */
    bringForward: (elementId: string) => void;
    /** Swap an element one step earlier in z-order (towards the back). */
    sendBackward: (elementId: string) => void;
    /** Move an element in front of every sibling on its layer. */
    bringToFront: (elementId: string) => void;
    /** Move an element behind every sibling on its layer. */
    sendToBack: (elementId: string) => void;
    /** Move an element to an explicit index within the active slide's z-order. */
    reorder: (elementId: string, toIndex: number) => void;
    /**
     * Update an element's text. For `smartArt` elements a `nodeId` targets a
     * specific node via core `updateSmartArtNodeText`; for text/shape elements the
     * `text` field (and every text segment's text) is replaced.
     */
    updateElementText: (elementId: string, text: string, nodeId?: string) => void;
}

/** Every command the Edit Points right-click menu can offer. */
declare type EditPointsCommandId = 'add-point' | 'delete-point' | 'delete-segment' | 'open-path' | 'close-path' | 'smooth-point' | 'straight-point' | 'corner-point' | 'straight-segment' | 'curved-segment' | 'exit';

/** Typed CT_AlphaOutsetEffect with original XML retained for lossless edits. */
declare interface EffectDagAlphaOutset {
    kind: 'alphaOutset';
    radiusEmu?: number;
    xml: XmlObject;
}

declare interface EffectDagBlend {
    kind: 'blend';
    mode: EffectDagBlendMode;
    container: EffectDagContainer;
}

declare type EffectDagBlendMode = 'darken' | 'lighten' | 'mult' | 'over' | 'screen';

/** Typed CT_BlurEffect with its original payload retained for lossless edits. */
declare interface EffectDagBlur {
    kind: 'blur';
    radiusEmu?: number;
    grow?: boolean;
    xml: XmlObject;
}

declare interface EffectDagContainer {
    kind: 'cont';
    type: EffectDagContainerType;
    name?: string;
    children: EffectDagNode[];
}

declare type EffectDagContainerType = 'sib' | 'tree';

declare type EffectDagNode = EffectDagContainer | EffectDagBlend | EffectDagXfrm | EffectDagRelOff | EffectDagBlur | EffectDagAlphaOutset | EffectDagPresetShadow | EffectDagRawLeaf;

/** Typed CT_PresetShadowEffect with colour and extension XML retained verbatim. */
declare interface EffectDagPresetShadow {
    kind: 'prstShdw';
    preset?: `shdw${number}`;
    distanceEmu?: number;
    direction?: number;
    xml: XmlObject;
}

declare interface EffectDagRawLeaf {
    kind: 'raw';
    tag: string;
    xml: Record<string, unknown>;
}

declare interface EffectDagRelOff {
    kind: 'relOff';
    tx?: number;
    ty?: number;
}

declare interface EffectDagXfrm {
    kind: 'xfrmEffect';
    sx?: number;
    sy?: number;
    kx?: number;
    ky?: number;
    tx?: number;
    ty?: number;
}

/** Snapshot of a single element's animation state at a point in the timeline. */
declare interface ElementAnimationState {
    /** Whether the element should be visible. */
    visible: boolean;
    /** CSS animation shorthand to apply (undefined = no active animation). */
    cssAnimation: string | undefined;
    /**
     * Staged-build reveal state, present only when the active animation builds a
     * chart or SmartArt diagram in stages (`p:bldChart` / `p:bldDgm`) rather than
     * revealing the whole element at once. A staged renderer multiplies
     * `build.progress` (0..1) by its own series / category / level COUNT to
     * decide how many stages are revealed at the current playback time; see
     * {@link import('./animation-build').revealedStageCount}. Absent for ordinary
     * whole-element entrances, so existing renderers are unaffected.
     */
    build?: ElementBuildState;
    /**
     * Authored-index chart reveal state (see {@link ChartRevealDescriptor}),
     * present only when every fired chart-build step for this element carried
     * `p:graphicEl` index data. A chart renderer prefers this over `build` when
     * present; `chart-build`'s `resolveRevealedChartData` picks between the two.
     */
    chartReveal?: {
        mode: ChartBuildMode;
        descriptor: ChartRevealDescriptor;
    };
    /**
     * Authored-index SmartArt diagram reveal state (see
     * {@link DiagramRevealDescriptor}), present only when every fired
     * diagram-build step for this element carried `p:graphicEl` node-id data.
     * `diagram-build`'s `resolveRevealedSmartArtNodes` prefers this over `build`
     * when present.
     */
    diagramReveal?: {
        mode: DiagramBuildMode;
        descriptor: DiagramRevealDescriptor;
    };
    /**
     * True when an active `p:animClr` color animation targets this shape's fill.
     * A vector renderer should then paint the fill with `fill: inherit` so the
     * wrapper-level colour keyframes cascade to the SVG path. Absent/false means
     * no active fill-colour animation.
     */
    animatesFill?: boolean;
    /**
     * True when an active `p:animClr` color animation targets this shape's
     * stroke. A vector renderer should then paint the stroke with
     * `stroke: inherit`. Absent/false means no active stroke-colour animation.
     */
    animatesStroke?: boolean;
    /**
     * Active discrete font-style / colour / size override (see
     * {@link import('./animation-timeline-step').TimelineStep.textStyle}) a
     * font-style emphasis effect currently applies to this element's text,
     * OVERRIDING the runs' own inline bold/italic/underline/size/colour.
     * `animation-playback-engine.ts` writes this on step start and again on
     * cleanup (held in full when the effect's `p:cTn/@fill` holds its end
     * state, otherwise reverted); a text renderer maps it onto its run markup
     * via `buildTextStyleOverrideCss` (`animation-text-style-css.ts`). Absent
     * means no font-style emphasis effect is currently active on this element.
     */
    textStyle?: TextStyleAnimationDescriptor;
}

/**
 * Playback-time staged-build state surfaced on
 * {@link import('./animation-timeline-group').ElementAnimationState}.
 * `progress` is the 0..1 fraction of the build revealed at the current
 * playback time; a consumer maps it to its own item COUNT (see
 * `revealedStageCount`).
 */
declare type ElementBuildState = {
    kind: 'chart';
    mode: ChartBuildMode;
    progress: number;
} | {
    kind: 'diagram';
    mode: DiagramBuildMode;
    progress: number;
};

declare interface ElementChange {
    elementId: string;
    label: string;
    kind: ElementChangeKind;
    description: string;
}

declare type ElementChangeKind = 'added' | 'removed' | 'moved' | 'resized' | 'textChanged';

/** Opaque clipboard payload: only its presence gates the Paste button. */
declare type ElementClipboardPayload = Record<string, unknown>;

/** Position and size in pixels. Converted to EMU internally when needed. */
declare interface ElementPosition {
    x: number;
    y: number;
    width: number;
    height: number;
    rotation?: number;
}

/**
 * useEditorOperations: element CRUD + transform operations over the active
 * slide of a reactive `PptxSlide[]`.
 *
 * This is the Vue port of the editing foundation that lives across the React
 * `useElementOperations` / `useClipboardHandlers` / `useGroupAlignLayerHandlers`
 * hooks. It is deliberately PURE of DOM and component concerns: it operates only
 * on the reactive slide model plus a current-slide-index ref, and threads every
 * mutation through a `pushHistory` callback (typically `useEditorHistory`'s
 * `pushHistory`) so the change is undoable.
 *
 * Mutation strategy (immutable, snapshot-first):
 *  1. call `pushHistory()` to snapshot the pre-mutation state,
 *  2. build a brand-new `PptxSlide[]` (active slide rebuilt with new elements),
 *  3. assign it to `slides.value`.
 *
 * Element cloning / creation always defers to the core helpers (`cloneSlide`,
 * `cloneElement`, `duplicateElement`, `updateSmartArtNodeText`) rather than
 * re-implementing them.
 */
/** Geometry/transform fields that {@link EditorOperations.transformElement} can patch. */
export declare interface ElementTransform {
    x?: number;
    y?: number;
    width?: number;
    height?: number;
    rotation?: number;
}

/** Signature of the lazily-loaded GIF encoder (see `gif-encoder.ts`). */
export declare type EncodeGif = (frames: GifFrame[], delayCs: number) => Uint8Array;

/**
 * Type definitions for OOXML encryption and decryption.
 *
 * Contains all interfaces and type aliases used by the OOXML crypto modules.
 *
 * @module ooxml-crypto-types
 */
/** Supported encryption algorithms. */
declare type EncryptionAlgorithm = 'AES128' | 'AES256';

/** Encryption options for creating encrypted files. */
declare interface EncryptionOptions {
    /** The encryption algorithm to use (defaults to AES256). */
    algorithm?: EncryptionAlgorithm;
    /** Number of hash iterations for key derivation (defaults to 100000). Lower values speed up tests. */
    spinCount?: number;
    /**
     * Which encryption scheme to write (defaults to 'agile'). 'standard'
     * writes the ECMA-376 Standard scheme (Office 2007-compatible: a single
     * password-derived AES-CBC key with a zero IV over the whole package),
     * mirroring the scheme this library already knows how to decrypt.
     */
    encryptionScheme?: EncryptionScheme;
}

/**
 * Which OOXML encryption scheme to write when creating a password-protected
 * file. Real PowerPoint can write and open either scheme; this library
 * defaults to 'agile' (Office 2010+), matching PowerPoint's own default.
 */
declare type EncryptionScheme = 'agile' | 'standard';

export declare const ERASER_RADIUS = 16;

/**
 * Remove any stroke that passes within `radius` of `(x, y)`. Returns a new
 * array (never mutates the input); identity-equal to the input when nothing
 * was erased.
 */
export declare function eraseStrokesAtPoint(strokes: AnnotationStroke[], x: number, y: number, radius?: number): AnnotationStroke[];

/** Options for the multi-slide PDF export (progress + cooperative cancel). */
export declare interface ExportPdfOptions {
    /** Capture-phase progress callback: `(currentSlide, totalSlides)`. */
    onProgress?: ExportProgress;
    /** Abort the export early; the loop checks this between slides. */
    signal?: AbortSignal;
}

/** Per-slide progress callback: `(currentSlideIndex, totalSlides)`. */
export declare type ExportProgress = (current: number, total: number) => void;

/** The public y-protocols Awareness surface needed by a borrowed session. */
declare interface ExternalCollaborationAwareness extends AwarenessLike {
    clientID: number;
    getLocalState: () => Record<string, unknown> | null;
    setLocalState: (state: Record<string, unknown> | null) => void;
    off: (event: string, callback: () => void) => void;
}

/**
 * Host-owned Yjs resources. The host creates, connects and destroys them.
 * Keep this object and its resources stable for a session; report connection
 * changes through subscribe instead of replacing the collaboration config.
 */
declare interface ExternalCollaborationSession {
    readonly doc: Doc;
    /** Awareness must belong to doc. One viewer publishes slide presence at a time. */
    readonly awareness: ExternalCollaborationAwareness;
    getSnapshot: () => ExternalCollaborationSnapshot;
    /** Subscribe to status or synced changes; return an unsubscribe function. */
    subscribe: (listener: () => void) => () => void;
}

/** Connection state reported by the host, independent of the viewer lifetime. */
declare interface ExternalCollaborationSnapshot {
    status: ConnectionStatus;
    /**
     * The host has loaded the authoritative document and permits local edits.
     * Keep true while offline to allow ordinary Yjs offline edits, or set false
     * to suspend writes until a fresh sync. The viewer never infers this from
     * `status` and never opens it after a timeout.
     */
    synced: boolean;
}

declare type FeedbackSoundScheme = 'modern' | 'classic';

declare type FillInput = {
    type: 'solid';
    color: string;
    opacity?: number;
    /**
     * A theme colour to use instead of a plain hex. When set, the shape
     * saves as `<a:schemeClr>` (e.g. `{ scheme: 'accent1', lumMod: 0.8 }`
     * for "Accent 1, Lighter 80%") so it keeps following the theme after a
     * later theme change; `color` still supplies the immediate resolved
     * hex for renderers that read it directly.
     */
    themeColorRef?: PptxThemeColorRef;
} | {
    type: 'gradient';
    /**
     * Gradient direction in the OOXML `a:lin/@ang` convention: degrees
     * clockwise from the positive x-axis, pointing from the first stop
     * towards the last (`0` = left to right, `90` = top to bottom). This is
     * what lands in `ShapeStyle.fillGradientAngle` and what is written back
     * to the file, NOT a CSS `linear-gradient()` angle.
     */
    angle?: number;
    gradientType?: 'linear' | 'radial';
    stops: Array<{
        color: string;
        position: number;
        opacity?: number;
    }>;
} | {
    type: 'pattern';
    preset: string;
    foreground?: string;
    background?: string;
} | {
    type: 'image';
    url: string;
    mode?: 'stretch' | 'tile';
} | {
    type: 'none';
};

/** Identifies a single match of the find query at segment-level precision. */
export declare interface FindResult {
    /** Zero-based index of the slide in the slides array. */
    slideIndex: number;
    /** Id of the element that contains the match. */
    elementId: string;
    /** Zero-based index of the text segment within the element's `textSegments`. */
    segmentIndex: number;
    /** Character offset of the match start within the segment text. */
    startOffset: number;
    /** Number of characters matched (equals `query.length`). */
    length: number;
}

/** What the "Embed fonts in the file" toggle should look like and do. */
declare interface FontEmbeddingDescriptor {
    /** Distinct typeface names the loaded deck currently embeds. */
    embeddedFamilies: string[];
    /**
     * Whether the toggle accepts input. False when the deck embeds nothing,
     * because turning it on could not produce an embedded font.
     */
    interactive: boolean;
    /**
     * The position the toggle must START in so that it describes the file that
     * would be written right now. A deck that arrived with embedded fonts keeps
     * them on save, so the switch has to read "on" from the outset; the previous
     * hardcoded `false` said the opposite of what save actually did.
     */
    initialEnabled: boolean;
    /** Present only when `interactive` is false. */
    disabledReasonKey?: string;
}

/**
 * Format a millisecond duration as `M:SS` (minutes are not zero-padded, seconds
 * are). Matches the React `RehearseTimingsHud`/`RehearseTimingsSummary`
 * `formatMs` helper.
 */
export declare function formatRehearseMs(ms: number): string;

/** One layer (outgoing or incoming) rendered as N independent fragments. */
declare interface FragmentedLayer {
    /** Name of the shared `@keyframes` block every fragment in this layer runs. */
    keyframesName: string;
    /** Per-fragment `animation-duration`, in ms. */
    durationMs: number;
    /** Per-fragment `animation-timing-function`. */
    easing: string;
    fragments: readonly TransitionFragment[];
}

export declare const FragmentedTransitionLayer: typeof __VLS_export_3;

/** The two click-to-place drawing tools. */
declare type FreeformToolKind = 'freeformShape' | 'curve';

/** Generate a stable, collision-resistant comment id. */
export declare function generateCommentId(): string;

/**
 * Geometry types: adjustment handles, custom geometry points, segments,
 * paths, and custom path properties.
 *
 * @module pptx-types/geometry
 */
/**
 * Defines an adjustment handle position for a shape geometry.
 *
 * Adjustment handles allow users to interactively reshape preset shapes
 * (e.g. rounding a rectangle corner or adjusting arrow head width).
 *
 * @example
 * ```ts
 * const handle: GeometryAdjustmentHandle = {
 *   guideName: "adj",
 *   xFraction: 0.25,
 *   minValue: 0,
 *   maxValue: 50000,
 * };
 * // => satisfies GeometryAdjustmentHandle
 * ```
 */
declare interface GeometryAdjustmentHandle {
    /** Name of the adjustment guide this handle controls (e.g. "adj", "adj1"). */
    guideName: string;
    /** X position as a fraction of shape width (0..1), or undefined if the handle only moves vertically. */
    xFraction?: number;
    /** Y position as a fraction of shape height (0..1), or undefined if the handle only moves horizontally. */
    yFraction?: number;
    /** Minimum allowed value for the adjustment guide. */
    minValue?: number;
    /** Maximum allowed value for the adjustment guide. */
    maxValue?: number;
}

/**
 * Resolve a p15 cinematic transition to its CSS `animation` descriptors, or
 * `undefined` when the type is not a cinematic transition (so the caller can
 * fall through to the classic 2-D / p14 resolvers).
 */
export declare function getCinematicTransitionAnimations(type: PptxTransitionType, durationMs: number, direction: string | undefined, orient?: string | undefined): SlideTransitionAnimations | undefined;

/**
 * Return CSS animation descriptors for p14 transition types. Returns
 * `undefined` when the type is not a p14 transition.
 */
export declare function getP14TransitionAnimations(type: PptxTransitionType, durationMs: number, direction: string | undefined, orient?: string | undefined, pattern?: string | undefined): SlideTransitionAnimations | undefined;

/**
 * Map a {@link PptxTransitionType} (+ duration/direction/orient/spokes) to the
 * concrete CSS `animation` descriptors for the outgoing and incoming layers.
 *
 * Unknown types fall back to a symmetrical cross-fade.
 */
export declare function getSlideTransitionAnimations(type: PptxTransitionType, durationMs: number, direction: string | undefined, orient?: string | undefined, spokes?: number | undefined, pattern?: string | undefined): SlideTransitionAnimations;

/** GIF-only tuning, in addition to the shared `MediaExportOptions`. */
export declare interface GifExportOptions extends MediaExportOptions {
    /**
     * Longest allowed frame side in pixels after capture; a captured canvas
     * larger than this is downscaled before quantisation (GIF encoding cost
     * grows with pixel count). Defaults to the shared
     * `GIF_POST_CAPTURE_MAX_SIDE` (see `resolveExportCaptureDecision`'s
     * `postCaptureMaxSide` for the `'gif'` format).
     */
    maxSide?: number;
}

/** A single animated-GIF frame: raw RGBA pixels plus its dimensions. */
declare interface GifFrame {
    imageData: ImageData;
    width: number;
    height: number;
    /**
     * Optional per-frame delay in **centiseconds** (1 cs = 10 ms). When set it
     * overrides the encoder-level delay for this frame only, which is how
     * per-slide durations from {@link planGifFrames} flow into the encoder.
     */
    delayCs?: number;
}

declare interface GroupOptions extends Partial<ElementPosition> {}

/**
 * A group container that holds child elements.
 *
 * Children inherit the group’s transform, so moving/resizing the group
 * affects all children proportionally.
 *
 * @example
 * ```ts
 * const group: GroupPptxElement = {
 *   type: "group",
 *   id: "grp_1", x: 0, y: 0, width: 960, height: 540,
 *   children: [textEl, shapeEl],
 * };
 * // => satisfies GroupPptxElement
 * ```
 */
declare interface GroupPptxElement extends PptxElementBase {
    type: 'group';
    /** Child elements contained within this group. */
    children: PptxElement[];
    /** Fill style extracted from the group's `p:grpSpPr`, used for `a:grpFill` inheritance. */
    groupFill?: ShapeStyle;
    /**
     * The SAME `p:grpSpPr` extraction as {@link groupFill}, kept whenever the
     * group carries a `p:grpSpPr` at all, regardless of whether it resolved to
     * a paintable fill.
     *
     * `groupFill` is `undefined` unless the group has a real fill, because
     * `getGroupChildParentFill`/`groupChildInheritedFill` (the `a:grpFill`
     * inheritance chain) must keep chaining through an ancestor's fill when
     * THIS group has none of its own. A group whose `p:grpSpPr` authors only
     * `a:effectLst` (shadow/glow/soft-edge/reflection, no fill) needs those
     * effects to still reach the renderer, so they are kept here under a name
     * that carries no fill-inheritance meaning. Currently only reflection is
     * read from it (`getComputedEffectStyle`); the rest of `a:effectLst` on a
     * group remains unsupported.
     */
    groupEffectStyle?: ShapeStyle;
    /**
     * Exact EMU the group's own `a:chOff`/`a:chExt` (the coordinate space its
     * CHILDREN are authored in) were parsed from, alongside {@link
     * PptxElementBase.xEmu} etc for the group's own placement in its PARENT's
     * space. `undefined` when the source carried no usable `a:chOff`/`a:chExt`
     * (an SDK-created group, or one whose `a:xfrm` had no child-space data).
     *
     * Used by `group-xfrm-preservation.ts`'s `hasCapturedChildSpace` to decide
     * whether this group's original `a:chOff`/`a:chExt` can be re-emitted
     * verbatim (always true once captured, regardless of whether anything in
     * the subtree has moved or resized - only its DIRECT children's
     * `a:off`/`a:ext` are recomputed, via `invertChildIntoGroupSpace`, when
     * something changed), instead of the normalized `chOff 0,0` / `chExt ==
     * ext` space the writer falls back to when this is `undefined` (or
     * degenerate). See `group-shape-geometry.ts`'s module doc for why a group
     * needs two coordinate systems at all.
     */
    chOffXEmu?: number;
    /** See {@link chOffXEmu}. */
    chOffYEmu?: number;
    /** See {@link chOffXEmu}. */
    chExtWidthEmu?: number;
    /** See {@link chOffXEmu}. */
    chExtHeightEmu?: number;
}

/** Group the catalog for display (preserves the label order). */
export declare function groupShortcutCatalog(catalog?: readonly ShortcutDefinition[]): ShortcutCatalogGroup[];

/** A single alignment guide, positioned in authored slide pixels. */
declare interface Guide {
    id: string;
    axis: 'h' | 'v';
    position: number;
}

/**
 * Pure handout layout calculations, shared by every binding's print path.
 *
 * Handles distributing slides across pages, computing grid dimensions, and
 * positioning cells within A4 page space. No DOM/framework dependency: callers
 * render the resulting rectangles however their view layer prefers.
 */
/** Supported slides-per-page values. */
declare type HandoutSlidesPerPage = 1 | 2 | 3 | 4 | 6 | 9;

export declare const HIGHLIGHTER_OPACITY = 0.4;

export declare const HIGHLIGHTER_WIDTH = 14;

declare interface ImageOptions extends Partial<ElementPosition> {
    altText?: string;
    cropLeft?: number;
    cropTop?: number;
    cropRight?: number;
    cropBottom?: number;
    opacity?: number;
}

/**
 * An image element from an OOXML `<p:pic>` node with `type: "image"`.
 *
 * @example
 * ```ts
 * const img: ImagePptxElement = {
 *   type: "image",
 *   id: "img_1", x: 0, y: 0, width: 960, height: 540,
 *   imagePath: "ppt/media/image1.png",
 *   altText: "Background scenery",
 * };
 * // => satisfies ImagePptxElement
 * ```
 */
declare interface ImagePptxElement extends PptxElementBase, PptxShapeProperties, PptxCustomPathProperties, PptxImageProperties, PptxAccessibilityProperties, PptxPictureNonVisualProperties {
    type: 'image';
}

declare type ImageResolutionPreset = 'highFidelity' | 'ppi330' | 'ppi220' | 'ppi150' | 'ppi96';

/** Resolve the injected selection context, if any (read-only viewers omit it). */
export declare function injectTableSelection(): TableSelectionContext | undefined;

/** A 2D point in stage-local coordinates. */
declare interface InkPoint {
    x: number;
    y: number;
    /**
     * Pointer pressure at this point, from `PointerEvent.pressure` (0..1).
     * Optional: a binding that has not wired pressure capture simply omits
     * it, and {@link strokeToInkElement} falls back to
     * {@link DEFAULT_POINTER_PRESSURE}, the constant value mice and other
     * non-pressure-aware devices report, which reads as "no real pressure
     * data".
     */
    pressure?: number;
    /**
     * Pen-tilt lean, in degrees, from `PointerEvent.tiltX`/`tiltY` on
     * supporting hardware (a mouse, or a stylus with no tilt sensor, reports a
     * constant 0). Optional and always captured as a pair: a binding that has
     * not wired tilt capture simply omits both, and {@link strokeToInkElement}
     * treats a constant `(0, 0)` reading the same way it treats a constant
     * pressure, i.e. as "no real tilt data" rather than authoring a channel
     * for it.
     */
    tiltX?: number;
    tiltY?: number;
}

/**
 * A freehand ink / drawing stroke captured with a stylus or mouse.
 *
 * Ink strokes are stored as SVG path data strings. Each path may
 * have independent colour, width, and opacity.
 */
declare interface InkPptxElement extends PptxElementBase {
    type: 'ink';
    /** SVG path data for ink strokes. */
    inkPaths: string[];
    /** Per-path stroke colours. */
    inkColors?: string[];
    /** Per-path stroke widths. */
    inkWidths?: number[];
    /** Per-path opacities (0-1). */
    inkOpacities?: number[];
    /** Drawing tool used: pen, highlighter, or eraser. */
    inkTool?: 'pen' | 'highlighter' | 'eraser';
    /**
     * Per-path arrays of per-point pressure values (0-1).
     *
     * Each entry corresponds to the path at the same index in `inkPaths`.
     * Each inner array contains one pressure value per sampled point along
     * the stroke. When present, the renderer uses these values to produce
     * variable-width strokes that reflect stylus/pen pressure.
     */
    inkPointPressures?: number[][];
    /**
     * Per-path arrays of per-point pen-tilt lean direction (degrees, straight
     * from `PointerEvent.tiltX` on supporting hardware).
     *
     * Each entry corresponds to the path at the same index in `inkPaths`, and
     * is paired positionally with {@link inkPointTiltY}. Present only when at
     * least one point in the stroke reported a genuinely non-zero tilt: a
     * device that never reports tilt (a mouse, or a stylus with no tilt
     * sensor) leaves both arrays absent, the same way `inkPointPressures` is
     * omitted when pressure never varies. When present, the renderer converts
     * the raw `(tiltX, tiltY)` vector into a lean angle + magnitude (see
     * `pptx-viewer-shared`'s `tiltChannelsFromVectors`) and widens the stroke
     * perpendicular to the lean direction, approximating a chisel-tip
     * calligraphy nib.
     */
    inkPointTiltX?: number[][];
    /** Per-path, per-point pen-tilt lean direction (degrees), paired with {@link inkPointTiltX}. */
    inkPointTiltY?: number[][];
    /** Unrecognised graphicFrame extLst extensions, captured verbatim for round-trip. */
    extensionXml?: PptxGraphicFrameExtension[];
}

/** Project a node's on-screen rect into container-relative pixels for overlay. */
export declare function inlineEditorRect(nodeRect: InlineEditRect, containerRect: InlineEditRect): InlineEditRect;

/** A minimal rectangle (DOMRect-compatible) used for overlay positioning. */
declare interface InlineEditRect {
    left: number;
    top: number;
    width: number;
    height: number;
}

declare interface InlineListController {
    read(): InlineListReadResult;
    format(snapshot: InlineTextEditSnapshot): InlineListReadResult;
    readSelection(selection?: Selection | null): InlineListSelectionResult;
    refresh(): InlineListReadResult;
    dispose(): void;
}

declare type InlineListReadResult = {
    kind: 'supported';
    snapshot: InlineTextEditSnapshot;
    paragraphs: RenderParagraph[];
} | {
    kind: 'unsupported';
    reason: string;
    text: string;
};

declare type InlineListSelectionResult = {
    kind: 'supported';
    snapshot: InlineTextEditSnapshot;
    selection: InlineTextSelection | null;
    bodyRange?: {
        start: number;
        end: number;
    };
} | {
    kind: 'unsupported';
    reason: string;
};

/** Current editor payload. Missing segments explicitly denotes plain-text fallback. */
declare interface InlineTextEditSnapshot {
    elementId: string;
    text: string;
    textSegments?: TextSegment[];
}

/** Describes which segments (and offsets within them) are selected. */
declare interface InlineTextSelection {
    startSegIdx: number;
    startOffset: number;
    endSegIdx: number;
    endOffset: number;
}

/**
 * Dropdown ids for the insert-chart menu. Distinct from `PptxChartType`
 * because PowerPoint offers Column (vertical) and Bar (horizontal) as two
 * entries over the same underlying `'bar'` chart type, and because `'pareto'`
 * has no `PptxChartType` of its own: it is a dropdown entry that resolves to
 * `type: 'histogram'` (see docs/guide/limitations.md's ChartEx row) with a
 * frequency-plus-cumulative-percentage default shape. The other six ChartEx
 * ids (`histogram` through `regionMap`) map one-to-one onto their chart type.
 */
declare type InsertChartKind = 'column' | 'bar' | 'line' | 'pie' | 'doughnut' | 'area' | 'scatter' | 'histogram' | 'pareto' | 'funnel' | 'treemap' | 'sunburst' | 'boxWhisker' | 'regionMap';

/** No-animation sentinel — used for `none`/`cut` (instant slide swap). */
export declare const INSTANT: SlideTransitionAnimations;

declare interface IPptxHandlerRuntime {
    /**
     * Release all resources held by this runtime (Blob URLs, caches, ZIP).
     * After calling, the runtime cannot be used further.
     */
    dispose(): void;
    /**
     * Revoke all Blob URLs created during image loading.
     */
    revokeBlobUrls(): void;
    getCompatibilityWarnings(): PptxCompatibilityWarning[];
    getLayoutOptions(): PptxLayoutOption[];
    getLayoutPreview(layoutPath: string): Promise<PptxLayoutPreview | null>;
    getLayoutPreviews(layoutPaths?: readonly string[]): Promise<PptxLayoutPreview[]>;
    createXmlBuilder(data: PptxData): PptxXmlBuilder;
    Builder(data: PptxData): PptxXmlBuilder;
    setTemplateBackground(path: string, backgroundColor: string | undefined): void;
    setPresentationTheme(themePath: string, applyToAllMasters?: boolean): Promise<void>;
    getTemplateBackgroundColor(path: string): string | undefined;
    updateThemeColorScheme(colorScheme: PptxThemeColorScheme): Promise<void>;
    updateThemeFontScheme(fontScheme: PptxThemeFontScheme): Promise<void>;
    updateThemeName(name: string): Promise<void>;
    /** Resolve a `<p:style>` node against the loaded theme (see PptxHandlerRuntimeStyleMatrixResolve). */
    resolveStyleMatrixReferences(styleXml: XmlObject): ResolvedStyleMatrix;
    applyTheme(colorScheme: PptxThemeColorScheme, fontScheme: PptxThemeFontScheme, themeName?: string): Promise<void>;
    load(data: ArrayBuffer, options?: PptxHandlerLoadOptions): Promise<PptxData>;
    getChartDataForGraphicFrame(slidePath: string, graphicFrame: XmlObject | undefined): Promise<PptxChartData | undefined>;
    getSmartArtDataForGraphicFrame(slidePath: string, graphicFrame: XmlObject | undefined): Promise<PptxSmartArtData | undefined>;
    getImageData(imagePath: string): Promise<string | undefined>;
    /**
     * Extract a media file from the PPTX archive as an ArrayBuffer.
     * Returns undefined if the file is not found.
     */
    getMediaArrayBuffer(mediaPath: string): Promise<ArrayBuffer | undefined>;
    save(slides: PptxSlide[], options?: PptxHandlerSaveOptions): Promise<Uint8Array>;
    exportSlides(slides: PptxSlide[], options: PptxExportOptions): Promise<Map<number, Uint8Array>>;
    /**
     * Get the available slide layouts for a specific slide, based on the
     * slide's master. Scans the slide master's relationships to find all
     * layouts that belong to it.
     *
     * @param slideIndex - Zero-based slide index.
     * @param slides - Current slides array.
     * @returns Array of layout options belonging to the same slide master.
     */
    getAvailableLayoutsForSlide(slideIndex: number, slides: PptxSlide[]): Promise<PptxLayoutOption[]>;
    /**
     * Resolve the editable template (master + layout) elements a slide
     * inherits, each carrying a `master-` / `layout-` prefixed id. Excludes
     * placeholders; returns only decorative shapes/pictures/graphic frames.
     *
     * @param slideId - The slide's archive path (`PptxSlide.id`).
     */
    getTemplateElementsForSlide(slideId: string): Promise<PptxElement[]>;
    /**
     * Scan the loaded PPTX archive for all theme parts.
     */
    getAvailableThemes(): Promise<Array<{
        path: string;
        name?: string;
    }>>;
    /**
     * Apply a different layout to an existing slide by updating the slide's
     * relationship to point to the new layout and re-parsing layout
     * placeholders / background.
     *
     * @param slideIndex - Zero-based slide index.
     * @param layoutPath - Archive path of the target layout
     *                     (e.g. `ppt/slideLayouts/slideLayout2.xml`).
     * @param slides - Current slides array.
     * @returns The updated slide with new layout path, name, and background.
     */
    applyLayoutToSlide(slideIndex: number, layoutPath: string, slides: PptxSlide[]): Promise<PptxSlide>;
}

/**
 * Abstract factory contract for creating {@link IPptxHandlerRuntime}
 * instances.
 *
 * Implement this interface to supply a custom runtime (e.g. a
 * WASM-backed or test-double runtime) to {@link PptxHandlerCore}.
 */
declare interface IPptxHandlerRuntimeFactory {
    /** Instantiate and return a new runtime implementation. */
    createRuntime(): IPptxHandlerRuntime;
}

/**
 * Fluent interface for navigating and mutating a {@link PptxData} structure.
 * Provides method-chaining access to slides, elements, and notes.
 */
declare interface IPptxXmlBuilder {
    /** Navigate to a slide by zero-based index (Pascal-case alias). */
    Slides(index: number): PptxSlideBuilder;
    /** Navigate to a slide by zero-based index. */
    slide(index: number): PptxSlideBuilder;
    /** Navigate to a slide by zero-based index (plural alias). */
    slides(index: number): PptxSlideBuilder;
    /** Return the underlying presentation data. */
    project(): PptxData;
}

/**
 * Whether a viewport should use the mobile layout: a narrow viewport, OR a
 * short touch viewport below the tablet width (a landscape phone, which is wide
 * enough to look like a tablet but far too short for the desktop ribbon).
 *
 * @pure: no side effects, fully testable without a DOM.
 */
export declare function isMobileViewport(width: number, height: number, isTouch: boolean): boolean;

export declare interface LaserPosition {
    x: number;
    y: number;
}

/** A `{ path, name }` layout option for the New-Slide dropdown. */
declare interface LayoutOption {
    path: string;
    name: string;
}

/** Interim geometry for an element mid-gesture. All fields optional. */
declare interface LiveGeometryPatch {
    x?: number;
    y?: number;
    width?: number;
    height?: number;
    rotation?: number;
}

/** The element's pre-edit rich text, used to remap the interim plain text. */
declare interface LiveTextSource {
    textSegments?: TextSegment[];
    textStyle?: TextStyle;
}

declare type LocalTextEdit = LocalTextReplacement | TextSessionCorrespondence;

/** Browser edit range mapped to the editor's pre-input encoded coordinates. */
declare interface LocalTextReplacement {
    from: number;
    to: number;
}

/**
 * Active tab within the master view sidebar.
 *
 * @example
 * ```ts
 * const tab: MasterViewTab = "slides";
 * // => "slides" — one of: "slides" | "notes" | "handout"
 * ```
 */
declare type MasterViewTab = 'slides' | 'notes' | 'handout';

/** Which part the master view is currently pointed at. */
declare interface MasterViewTarget {
    tab: MasterViewTab;
    masterIndex: number;
    /** `null` selects the master itself rather than one of its layouts. */
    layoutIndex: number | null;
}

/** Result of matching a keyboard event against the catalog. */
export declare interface MatchedShortcut {
    /** The dispatched action, or `null` when the event matches nothing. */
    action: ShortcutActionName | null;
    /** Nudge delta (only set when `action === 'nudge'`). */
    dx?: number;
    /** Nudge delta (only set when `action === 'nudge'`). */
    dy?: number;
}

/**
 * Material preset type tokens from OOXML `a:sp3d/@prstMaterial`.
 *
 * @example
 * ```ts
 * const mat: MaterialPresetType = "plastic";
 * // => "plastic" — one of: "matte" | "warmMatte" | "plastic" | "metal" | "dkEdge" | …
 * ```
 */
declare type MaterialPresetType = 'matte' | 'warmMatte' | 'plastic' | 'metal' | 'dkEdge' | 'softEdge' | 'flat' | 'softmetal' | 'clear' | 'powder' | 'translucentPowder' | 'legacyMatte' | 'legacyPlastic' | 'legacyMetal' | 'legacyWireframe';

/**
 * A named bookmark within a media clip timeline.
 *
 * @example
 * ```ts
 * const bm: MediaBookmark = {
 *   id: "bm1",
 *   time: 12.5,
 *   label: "Intro ends",
 * };
 * // => satisfies MediaBookmark
 * ```
 */
declare interface MediaBookmark {
    id: string;
    /** Position in seconds from the start of the clip. */
    time: number;
    /** User-visible label for this bookmark. */
    label: string;
}

/**
 * A closed-caption / subtitle track associated with a media element.
 *
 * @example
 * ```ts
 * const track: MediaCaptionTrack = {
 *   id: "t1",
 *   label: "English",
 *   language: "en",
 *   kind: "subtitles",
 *   isDefault: true,
 * };
 * // => satisfies MediaCaptionTrack
 * ```
 */
declare interface MediaCaptionTrack {
    /** Unique ID for this track. */
    id: string;
    /** Human-readable label (e.g. "English", "Spanish"). */
    label: string;
    /** BCP-47 language code (e.g. "en", "es"). */
    language: string;
    /** Track kind: subtitles, captions, or descriptions. */
    kind: 'subtitles' | 'captions' | 'descriptions';
    /** Data URL or path to the VTT/SRT content within the PPTX archive. */
    src?: string;
    /** Inline VTT content (for embedded captions). */
    content?: string;
    /** Whether this track is the default/active one. */
    isDefault?: boolean;
}

/** Options accepted by both `exportGif` and `exportWebm`. */
export declare interface MediaExportOptions {
    /** Default display time per slide, in milliseconds. */
    slideDurationMs?: number;
    /** Per-slide duration overrides in ms (index maps to slide index). */
    slideTimingsMs?: number[];
    /** Capture-phase progress callback: `(currentSlide, totalSlides)`. */
    onProgress?: MediaExportProgress;
    /** Abort the export early. */
    signal?: AbortSignal;
}

/** Per-slide progress callback: `(currentSlideIndex, totalSlides)`. */
export declare type MediaExportProgress = (current: number, total: number) => void;

/**
 * Runtime-extracted metadata about a media clip (populated from HTMLMediaElement).
 *
 * @example
 * ```ts
 * const meta: MediaMetadata = {
 *   duration: 120.5,
 *   videoWidth: 1920,
 *   videoHeight: 1080,
 *   codecInfo: "video/mp4; codecs=\"avc1.640028\"",
 * };
 * // => satisfies MediaMetadata
 * ```
 */
declare interface MediaMetadata_2 {
    /** Duration in seconds. */
    duration?: number;
    /** Video width in pixels (video only). */
    videoWidth?: number;
    /** Video height in pixels (video only). */
    videoHeight?: number;
    /** MIME type / codec string reported by the browser. */
    codecInfo?: string;
}

declare interface MediaOptions extends Partial<ElementPosition> {
    autoPlay?: boolean;
    loop?: boolean;
    volume?: number;
    trimStartMs?: number;
    trimEndMs?: number;
    posterFrame?: string;
}

/**
 * An audio or video media element.
 *
 * Media elements reference files inside the PPTX archive
 * (`mediaPath`) and may include trim points, poster frames, and
 * playback settings for presentation mode.
 *
 * @example
 * ```ts
 * const video: MediaPptxElement = {
 *   type: "media",
 *   id: "vid_1", x: 50, y: 100, width: 640, height: 360,
 *   mediaType: "video",
 *   mediaPath: "ppt/media/media1.mp4",
 *   autoPlay: true,
 *   volume: 0.8,
 * };
 * // => satisfies MediaPptxElement
 * ```
 */
declare interface MediaPptxElement extends PptxElementBase {
    type: 'media';
    mediaType?: PptxMediaType;
    mediaPath?: string;
    mediaData?: string;
    mediaMimeType?: string;
    mediaReferenceKind?: PptxMediaReferenceKind;
    mediaReferenceName?: string;
    /** Explicit DrawingML `audioFile/@contentType` value when present. */
    mediaReferenceContentType?: string;
    audioCdStart?: PptxAudioCdPosition;
    audioCdEnd?: PptxAudioCdPosition;
    rawMediaReferenceXml?: XmlObject;
    /** Trim start in milliseconds (from p:cMediaNode p:cTn @st). */
    trimStartMs?: number;
    /** Trim end in milliseconds (from p:cMediaNode p:cTn @end). */
    trimEndMs?: number;
    /** Path to the poster/preview image inside the ZIP. */
    posterFramePath?: string;
    /** Base64 data-URL for the poster frame image. */
    posterFrameData?: string;
    /** Poster source crop from the left edge as a 0..1 fraction. */
    cropLeft?: number;
    /** Poster source crop from the top edge as a 0..1 fraction. */
    cropTop?: number;
    /** Poster source crop from the right edge as a 0..1 fraction. */
    cropRight?: number;
    /** Poster source crop from the bottom edge as a 0..1 fraction. */
    cropBottom?: number;
    /** Poster stretch-target inset from the left frame edge. */
    fillRectLeft?: number;
    /** Poster stretch-target inset from the top frame edge. */
    fillRectTop?: number;
    /** Poster stretch-target inset from the right frame edge. */
    fillRectRight?: number;
    /** Poster stretch-target inset from the bottom frame edge. */
    fillRectBottom?: number;
    /** Whether media should play full-screen during presentation. */
    fullScreen?: boolean;
    /** Whether media should loop continuously. */
    loop?: boolean;
    /** Fade-in duration in seconds. */
    fadeInDuration?: number;
    /** Fade-out duration in seconds. */
    fadeOutDuration?: number;
    /** Playback volume (0 to 1). */
    volume?: number;
    /** Whether media auto-plays on slide entry. */
    autoPlay?: boolean;
    /** Whether audio continues playing across slide transitions (presentation mode). */
    playAcrossSlides?: boolean;
    /** Hide the element when media is not actively playing. */
    hideWhenNotPlaying?: boolean;
    /** Named time bookmarks within the clip. */
    bookmarks?: MediaBookmark[];
    /** Playback speed multiplier (1 = normal, 2 = double, 0.5 = half). */
    playbackSpeed?: number;
    /** Runtime-extracted metadata (duration, resolution, codec). */
    metadata?: MediaMetadata_2;
    /** Closed caption / subtitle tracks. */
    captionTracks?: MediaCaptionTrack[];
    /** Whether the media source is missing/broken (file not found in archive). */
    mediaMissing?: boolean;
    /**
     * Whether the media is linked (external `r:link`) rather than embedded
     * (`r:embed`). Defaults to embedded when undefined.
     */
    isLinked?: boolean;
    /**
     * Accessibility description. Read from `p:nvGraphicFramePr/p:cNvPr/@descr`
     * for the `p:graphicFrame`-shaped (SDK-created) media form, or from
     * `p:nvPicPr/p:cNvPr/@descr` for the `p:pic`-shaped media form (real
     * PowerPoint's usual authoring shape for a video/audio placeholder); see
     * `PptxHandlerRuntimePictureParsing.ts`.
     */
    altText?: string;
    /** Accessibility title, from the same `@title` attribute on whichever `p:cNvPr` the media form uses. Same scope note as {@link altText}. */
    title?: string;
    /** Unrecognised graphicFrame extLst extensions, captured verbatim for round-trip. */
    extensionXml?: PptxGraphicFrameExtension[];
}

/**
 * Factory for a `MediaRecorder` over a canvas capture stream. Injectable so the
 * WebM path can be exercised in happy-dom (which ships no `MediaRecorder`).
 */
export declare type MediaRecorderFactory = (canvas: HTMLCanvasElement, fps: number, options: {
    mimeType: string;
    videoBitsPerSecond: number;
}) => MediaRecorder;

declare type MergeCropController = MergeShapesController & PictureCropController;

/** Supported merge shape operations (matching PowerPoint's Merge Shapes menu). */
declare type MergeShapeOperation = 'union' | 'intersect' | 'subtract' | 'fragment' | 'combine';

/** The right-click command id for each operation. */
declare type MergeShapesCommandId = 'merge-union' | 'merge-combine' | 'merge-fragment' | 'merge-intersect' | 'merge-subtract';

/** Merge Shapes: the ribbon dropdown and the context-menu entries. */
declare interface MergeShapesController {
    /** Editable deck and two or more mergeable shapes selected. */
    canMerge: ComputedRef<boolean>;
    /** Run `op` over the selection (in selection order) as one undo step. */
    merge: (op: MergeShapeOperation) => void;
}

/** Mobile breakpoint: below this width is considered mobile. */
export declare const MOBILE_BREAKPOINT = 768;

/**
 * Max viewport height (px) at which a *touch* device is treated as mobile
 * regardless of width. Catches landscape phones (e.g. 915x412), which are wide
 * enough to fall in the "tablet" width band but far too short for the desktop
 * ribbon + side panels, so they need the mobile chrome. Tablets in landscape
 * are taller (~760px+) so they stay on the desktop layout.
 */
export declare const MOBILE_LANDSCAPE_MAX_HEIGHT = 500;

/** Which mobile bottom-bar tab is highlighted (null = none open). */
export declare type MobileActiveSheet = MobileSheetKind | null;

export declare type MobileSheetKind = 'slides' | 'format' | 'comments' | 'notes';

/**
 * A 3D model object embedded via `p16:model3D` inside an
 * `mc:AlternateContent` block (PowerPoint 365+).
 *
 * The element carries the path to the `.glb`/`.gltf` binary inside
 * the ZIP and a poster/fallback image for rendering in viewers that
 * do not support interactive 3D.
 */
declare interface Model3DPptxElement extends PptxElementBase, PptxImageProperties {
    type: 'model3d';
    /** Path to the 3D model file inside the ZIP. */
    modelPath?: string;
    /** Base64 data URL of the 3D model binary. */
    modelData?: string;
    /** MIME type of the model (e.g. "model/gltf-binary"). */
    modelMimeType?: string;
    /** Poster/preview image shown when 3D rendering is unavailable. */
    posterImage?: string;
    /** Unrecognised graphicFrame extLst extensions, captured verbatim for round-trip. */
    extensionXml?: PptxGraphicFrameExtension[];
}

/** A matched pair whose two halves are both painted by the overlay. */
declare interface MorphCrossfadeGroup {
    /** The outgoing (ghost) half, rendered in the OUTGOING slide's context. */
    outgoing: PptxElement;
    /** The incoming half, rendered in the INCOMING slide's context. */
    incoming: PptxElement;
    /**
     * The dissolve to run on the outgoing half's own WRAPPER, not on the element.
     *
     * A pair that dissolves where it stands never moves, so its journey keyframes
     * are an identity transform and are dropped; what is left is the fade. Put
     * that fade on the element and the element becomes its own compositing layer,
     * whose raster the browser snaps to whole device pixels: the wording is
     * painted up to a third of a pixel from where the live stage paints it, so it
     * visibly twitches as the transition starts and again as it ends. Measured on
     * the wheel deck at four show sizes, moving the fade onto the slide-sized
     * wrapper takes the arriving half from 0.22-0.31px off to under 0.02px - a
     * mean pixel difference of 0.01/255 against the settled slide.
     *
     * Undefined when the pair MOVES: it needs its journey keyframes on the
     * element, and a shape that is travelling cannot be seen to snap.
     */
    outgoingAnimation?: string;
    /** The arriving half's dissolve. @see MorphCrossfadeGroup.outgoingAnimation */
    incomingAnimation?: string;
}

/** One entry of {@link useMorphTransitionOverlay}'s `morphCrossfadeGroups`. */
export declare type MorphCrossfadeGroupView = ReturnType<typeof useMorphTransitionOverlay>['morphCrossfadeGroups']['value'][number];

export declare const MorphExtraLayers: typeof __VLS_export_2;

/** Everything needed to play one morph transition. */
declare interface MorphTransitionPlan {
    /** All `@keyframes` blocks, to inject as a single stylesheet. */
    keyframesCss: string;
    /** Incoming-slide element id -> CSS `animation` shorthand. */
    incomingAnimations: Map<string, string>;
    /** Outgoing-slide element id -> CSS `animation` shorthand. */
    outgoingAnimations: Map<string, string>;
    /**
     * Incoming-slide element id -> CSS `animation` shorthand for the `<img>`
     * INSIDE that element, never for the element's own container.
     *
     * A picture's source crop (`a:srcRect`, which is what PowerPoint's "Scale
     * Height"/"Scale Width" writes) is painted by transforming the img within
     * its frame, and the frame itself is usually identical on both slides - so
     * this is a separate channel rather than another entry in
     * {@link MorphTransitionPlan.incomingAnimations}, which would collide on the
     * same element id. {@link buildMorphScopedCss} emits it as a descendant
     * rule; a binding that applies animations as inline props instead must
     * target the img itself (issue #148).
     */
    incomingImageAnimations: Map<string, string>;
    /** Outgoing (ghost) counterpart of {@link MorphTransitionPlan.incomingImageAnimations}. */
    outgoingImageAnimations: Map<string, string>;
    /**
     * Incoming-slide element id -> CSS `animation` shorthand for the copy the
     * overlay paints, above every ghost.
     *
     * These are the arriving shapes a ghost would otherwise hide for the whole
     * transition (see {@link MorphTransitionPlan.overlayIncomingElements}). Their
     * entry in {@link MorphTransitionPlan.incomingAnimations} has been replaced
     * by one that holds them invisible, so the stage copy stays out of the way
     * and only this one is seen.
     */
    overlayIncomingAnimations: Map<string, string>;
    /**
     * The incoming-slide elements to paint in the overlay ON TOP of
     * {@link MorphTransitionPlan.outgoingElements}, in document order.
     *
     * The overlay is one flat layer above the live stage, which is only faithful
     * while every ghost really does belong on top of everything the stage draws.
     * A shape arriving INSIDE a persisting one does not: the wheel deck's centre
     * disc is unchanged between slides, so its ghost is opaque for the whole
     * morph, and the title and body dissolving in within it were invisible until
     * the overlay came down (issue #146). Painting those here restores the order
     * PowerPoint composites in.
     *
     * Usually empty. A binding renders these with the INCOMING slide as their
     * context, applying {@link MorphTransitionPlan.overlayIncomingAnimations}.
     *
     * A lifted half that is one end of a cross-dissolve is NOT here: it moves
     * into {@link MorphTransitionPlan.crossfadeGroups} so it can be composited
     * with its own ghost.
     */
    overlayIncomingElements: PptxElement[];
    /**
     * Pairs the overlay paints BOTH halves of, to be rendered as one isolated
     * group blending additively (see `morph-crossfade-group`).
     *
     * Their elements are deliberately absent from
     * {@link MorphTransitionPlan.outgoingElements} and
     * {@link MorphTransitionPlan.overlayIncomingElements}: a binding that renders
     * the groups paints each half exactly once, and one that ignored them would
     * drop the pair rather than paint it twice.
     *
     * A pair that dissolves where it stands also has its dissolve moved OFF the
     * two elements and onto {@link MorphCrossfadeGroup.outgoingAnimation} /
     * {@link MorphCrossfadeGroup.incomingAnimation}, for the binding to put on
     * the wrapper it paints each half in; the elements are then absent from
     * `outgoingAnimations` / `overlayIncomingAnimations` too, so no scoped rule
     * animates them. One that MOVES keeps its animations where they were.
     *
     * Painted above {@link MorphTransitionPlan.overlayIncomingElements}, in the
     * incoming slide's document order.
     */
    crossfadeGroups: MorphCrossfadeGroup[];
    /**
     * The outgoing slide's elements, in document order, for the binding to
     * render in its transition overlay for the duration of the morph. Most carry
     * an entry in {@link MorphTransitionPlan.outgoingAnimations}: they either
     * fade out in place (no counterpart) or glide onto a counterpart, dissolving
     * into it when the appearance changed.
     *
     * A ghost standing in for an INERT pair deliberately has no entry there and
     * is painted statically. Its keyframes would run from itself to itself, and
     * a running animation would put it on its own compositing layer, whose
     * raster the browser snaps to whole device pixels - visibly shifting a shape
     * that is not supposed to move at all (issue #161).
     *
     * This is a SUBSET of the outgoing slide: a shape the live stage already
     * draws identically is left out, because the overlay is opaque above it and
     * would hide the incoming slide's own arrivals. See `resolveMorphGhostIds`.
     */
    outgoingElements: PptxElement[];
    /** Animation duration in ms, echoed for convenience. */
    durationMs: number;
}

/**
 * smartart-inline-edit (Vue): reactive state + node-id mapping for on-canvas
 * SmartArt node text editing. Kept out of the SFC so the component stays thin
 * (CLAUDE.md <= 300 LOC) and the mapping is unit-testable.
 *
 * Pure rect projection and the no-op-commit guard live in the framework-agnostic
 * `pptx-viewer-shared` (`computeInlineEditorRect`, `shouldCommitSmartArtNodeText`)
 * and are reused here rather than reimplemented. This module adds only the
 * Vue-reactive edit state and the rendered-node -> source-node-id mapping.
 */
/**
 * Pair each rendered fallback-layout node with its source node id by matching
 * `flattenNodes` order: the per-family layout functions iterate the flattened
 * tree in the same order, so index `i` of the rendered list corresponds to
 * index `i` of the flattened source tree.
 */
export declare function nodeIdsInRenderOrder(roots: readonly PptxSmartArtNode[]): string[];

/** Slide pixels a Shift+arrow moves the selection (ten small steps). */
export declare const NUDGE_LARGE = 10;

/**
 * Slide pixels an unmodified arrow key moves the selection.
 *
 * PowerPoint nudges by the smallest unit it can draw, and the ribbon's position
 * boxes are authored in the same slide-pixel space the renderer lays out in, so
 * one arrow press must equal one slide pixel or the numbers in the inspector
 * disagree with what the keyboard does.
 */
export declare const NUDGE_SMALL = 1;

/**
 * Recognised OLE object application types derived from `progId` / `clsId`.
 *
 * Used to show type-specific icons and previews in the editor.
 */
declare type OleObjectType = 'excel' | 'word' | 'powerpoint' | 'pdf' | 'visio' | 'mathtype' | 'package' | 'unknown';

/**
 * An OLE (Object Linking and Embedding) object.
 *
 * OLE objects can be embedded Excel sheets, Word documents, PDFs, Visio
 * diagrams, MathType equations, or generic "packages". They carry a
 * preview image for display and optional binary data for extraction.
 *
 * @example
 * ```ts
 * const ole: OlePptxElement = {
 *   type: "ole",
 *   id: "ole_1", x: 100, y: 200, width: 400, height: 300,
 *   oleObjectType: "excel",
 *   oleProgId: "Excel.Sheet.12",
 *   fileName: "budget.xlsx",
 * };
 * // => satisfies OlePptxElement
 * ```
 */
declare interface OlePptxElement extends PptxElementBase {
    type: 'ole';
    oleTarget?: string;
    oleProgId?: string;
    oleName?: string;
    /** CLSID of the OLE object (from `@_classid`). */
    oleClsId?: string;
    /** Detected application type (excel, word, pdf, etc.). */
    oleObjectType?: OleObjectType;
    /** File extension for the embedded binary (e.g. "xlsx", "docx"). */
    oleFileExtension?: string;
    /** Original file name when available. */
    fileName?: string;
    /** Whether this is a linked (vs. embedded) object. */
    isLinked?: boolean;
    /** External file path for linked OLE objects (TargetMode="External"). */
    externalPath?: string;
    /** Data-URL or path for the OLE preview image. */
    previewImage?: string;
    /** Decoded preview image as a data-URL. */
    previewImageData?: string;
    /** Whether the OLE object is shown as an icon (`p:oleObj/@showAsIcon`). */
    oleShowAsIcon?: boolean;
    /** Authored display width of the OLE object preview, in EMU (`@imgW`). */
    oleImgW?: number;
    /** Authored display height of the OLE object preview, in EMU (`@imgH`). */
    oleImgH?: number;
    /**
     * The recovered embedded payload as a data-URL (e.g.
     * `data:application/vnd...;base64,...`), suitable for download or
     * open-in-new-tab. For a generic "Package" OLE object this is the unwrapped
     * inner file; for a plain embedded file (e.g. `.xlsx`) it is that file
     * directly. Undefined when the embedding is missing or unreadable.
     *
     * Stored as a data-URL string to mirror how images store decoded bytes
     * ({@link ImagePptxElement.imageData}) and to stay serialization-safe.
     */
    oleEmbeddedData?: string;
    /** Original file name of the embedded payload when recoverable. */
    oleEmbeddedFileName?: string;
    /** MIME type of the embedded payload, derived from its extension/ProgID. */
    oleEmbeddedMimeType?: string;
    /** Size of the embedded payload in bytes. */
    oleEmbeddedByteSize?: number;
    /**
     * `p:link/@followColorScheme` (`ST_OleObjectFollowColorScheme`): whether a
     * LINKED OLE object's icon recolours to match the presentation theme.
     * Only meaningful when {@link isLinked} is `true`. ECMA-376 §19.3.1.28.
     */
    oleFollowColorScheme?: 'none' | 'full' | 'textAndBackground';
    /**
     * `p:link/@updateAutomatic` (`CT_OleObjectLink`, ECMA-376 §19.3.2.4):
     * whether a LINKED OLE object refreshes automatically from its source
     * (PowerPoint's Edit Links dialog "Automatic" vs. "Manual" radio buttons).
     * Only meaningful when {@link isLinked} is `true`. The schema default is
     * `false`; `undefined` means the source authored no explicit value.
     */
    oleUpdateAutomatic?: boolean;
    /**
     * Set by the in-viewer OLE content editors (`ole-edit-api.ts`) whenever
     * `oleEmbeddedData` and/or `previewImageData` have been changed in memory
     * and still need to be written back into the saved package. Never
     * authored from a parsed file; purely an in-memory save signal, mirroring
     * `PptxSlide.isDirty`. The save writer clears it once the pending write
     * has been queued.
     */
    oleContentDirty?: boolean;
    /** Accessibility description from `p:nvGraphicFramePr/p:cNvPr/@descr`. */
    altText?: string;
    /** Accessibility title from `p:nvGraphicFramePr/p:cNvPr/@title`. */
    title?: string;
    /** Unrecognised graphicFrame extLst extensions, captured verbatim for round-trip. */
    extensionXml?: PptxGraphicFrameExtension[];
}

declare type OpenDocumentsView = 'savedView' | 'normal' | 'outline' | 'slideSorter' | 'notes';

/**
 * Open a print window for a complete HTML document and trigger printing.
 * Returns `false` if the window was blocked (e.g. popup blocker).
 */
export declare type OpenPrintWindow = (htmlDocument: string) => boolean;

/**
 * A File > Options page: the ten PowerPoint categories plus `ai`, the AI
 * assistant page a binding adds when the host configured an assistant.
 */
declare type OptionsPageId = ViewerOptionsTabId | 'ai';

declare type OptionsPrintColorMode = 'color' | 'grayscale' | 'blackAndWhite';

declare type OptionsPrintWhat = 'slides' | 'handouts' | 'notes' | 'outline';

/**
 * One section of an Options page, addressed as `<page>.<section>`, for
 * example `general.personalize` or `advanced.print`. The full list is
 * `OPTIONS_SECTION_IDS` (derived from the schema at runtime).
 */
declare type OptionsSectionId = `${ViewerOptionsTabId}.${string}`;

/**
 * One File > Options setting, addressed as `<group>.<key>`, for example
 * `general.userName` or `advanced.showGrid`. The union is derived from the
 * `ViewerOptions` model itself, so a typo is a compile error.
 */
declare type OptionsSettingId = { [G in ViewerOptionsGroupId]: `${G}.${PrimitiveKeys<ViewerOptions[G]>}`; }[ViewerOptionsGroupId];

/** Values a host forces onto settings. */
declare type OptionsSettingValues = Partial<Record<OptionsSettingId, ViewerOptionPrimitive>>;

/**
 * Read-only digital-signature inspection composable for the Vue viewer.
 *
 * Digital signatures in OOXML packages live under `_xmlsignatures/`. The core
 * `PptxHandler` detects their presence at load time (it stores a
 * {@link import('pptx-viewer-core').SignatureDetectionResult} internally and
 * surfaces `hasDigitalSignatures` / `digitalSignatureCount` on `PptxData`), but
 * it does NOT expose the fully-parsed signatures. The host obtains the parsed
 * `ParsedSignature[]` itself, by reading each `_xmlsignatures/sig*.xml` part
 * and running the core `parseSignatureXml(...)` helper, then feeds the result
 * in here. This composable is purely presentational state derivation: it never
 * signs, strips, or mutates anything.
 *
 * Overall status precedence (worst-wins), mirroring how a signature panel
 * should warn the user:
 *   invalid  >  expired / unknownCA  >  unverified  >  valid
 */
/** Overall package signature status derived from all individual signatures. */
export declare type OverallSignatureStatus = 'signed' | 'invalid' | 'unsigned';

/** Part 1: conveyor / doors / ferris / flash / flythrough / gallery / glitter / honeycomb / pan. */
export declare const P14_TRANSITION_KEYFRAMES = "\n/* ── Conveyor (translate X with staggered timing) ──────────────────── */\n@keyframes pptx-tr-conveyor-in-from-right {\n\tfrom { transform: translateX(100%) rotateY(-30deg); }\n\t60%  { transform: translateX(20%) rotateY(-10deg); }\n\tto   { transform: translateX(0) rotateY(0deg); }\n}\n@keyframes pptx-tr-conveyor-out-to-left {\n\tfrom { transform: translateX(0) rotateY(0deg); }\n\t40%  { transform: translateX(-20%) rotateY(10deg); }\n\tto   { transform: translateX(-100%) rotateY(30deg); }\n}\n@keyframes pptx-tr-conveyor-in-from-left {\n\tfrom { transform: translateX(-100%) rotateY(30deg); }\n\t60%  { transform: translateX(-20%) rotateY(10deg); }\n\tto   { transform: translateX(0) rotateY(0deg); }\n}\n@keyframes pptx-tr-conveyor-out-to-right {\n\tfrom { transform: translateX(0) rotateY(0deg); }\n\t40%  { transform: translateX(20%) rotateY(-10deg); }\n\tto   { transform: translateX(100%) rotateY(-30deg); }\n}\n\n/* ── Doors (clip-path from center split) ──────────────────────────────\n   MEASURED via COM CreateVideo: PowerPoint's `dir=\"horz\"` names a\n   HORIZONTAL split line (two panels stacked top/bottom, opening upward and\n   downward), and `dir=\"vert\"` a VERTICAL split line (panels side by side,\n   opening left and right) - the opposite of what \"clips left/right\" vs\n   \"clips top/bottom\" would suggest at a glance. Keep the clip-path bodies\n   matched to the MEASURED direction, not the intuitive one. */\n@keyframes pptx-tr-doors-horz {\n\tfrom { clip-path: inset(50% 0); }\n\tto   { clip-path: inset(0 0); }\n}\n@keyframes pptx-tr-doors-vert {\n\tfrom { clip-path: inset(0 50%); }\n\tto   { clip-path: inset(0 0); }\n}\n\n/* ── Ferris (rotate elements around center) ───────────────────────── */\n@keyframes pptx-tr-ferris-in-from-right {\n\tfrom { transform: translateX(80%) rotate(45deg) scale(0.6); opacity: 0; }\n\tto   { transform: translateX(0) rotate(0deg) scale(1); opacity: 1; }\n}\n@keyframes pptx-tr-ferris-out-to-left {\n\tfrom { transform: translateX(0) rotate(0deg) scale(1); opacity: 1; }\n\tto   { transform: translateX(-80%) rotate(-45deg) scale(0.6); opacity: 0; }\n}\n@keyframes pptx-tr-ferris-in-from-left {\n\tfrom { transform: translateX(-80%) rotate(-45deg) scale(0.6); opacity: 0; }\n\tto   { transform: translateX(0) rotate(0deg) scale(1); opacity: 1; }\n}\n@keyframes pptx-tr-ferris-out-to-right {\n\tfrom { transform: translateX(0) rotate(0deg) scale(1); opacity: 1; }\n\tto   { transform: translateX(80%) rotate(45deg) scale(0.6); opacity: 0; }\n}\n\n/* ── Flash (bright flash opacity burst) ──────────────────────────── */\n@keyframes pptx-tr-flash-white {\n\t0%   { opacity: 1; }\n\t30%  { opacity: 0; }\n\t50%  { opacity: 0; }\n\t100% { opacity: 1; }\n}\n@keyframes pptx-tr-flash-in {\n\t0%   { opacity: 0; }\n\t50%  { opacity: 0; }\n\t70%  { opacity: 1; }\n\t100% { opacity: 1; }\n}\n\n/* ── Flythrough (scale + translate Z-axis feel) ──────────────────── */\n@keyframes pptx-tr-flythrough-in {\n\tfrom { transform: scale(4) translateZ(200px); opacity: 0; filter: blur(8px); }\n\tto   { transform: scale(1) translateZ(0); opacity: 1; filter: blur(0); }\n}\n@keyframes pptx-tr-flythrough-out {\n\tfrom { transform: scale(1) translateZ(0); opacity: 1; filter: blur(0); }\n\tto   { transform: scale(0.1) translateZ(-200px); opacity: 0; filter: blur(8px); }\n}\n@keyframes pptx-tr-flythrough-reverse-in {\n\tfrom { transform: scale(0.1) translateZ(-200px); opacity: 0; filter: blur(8px); }\n\tto   { transform: scale(1) translateZ(0); opacity: 1; filter: blur(0); }\n}\n@keyframes pptx-tr-flythrough-reverse-out {\n\tfrom { transform: scale(1) translateZ(0); opacity: 1; filter: blur(0); }\n\tto   { transform: scale(4) translateZ(200px); opacity: 0; filter: blur(8px); }\n}\n\n/* ── Gallery (translate with perspective) ─────────────────────────── */\n@keyframes pptx-tr-gallery-in-from-right {\n\tfrom { transform: perspective(800px) translateX(100%) rotateY(-45deg); opacity: 0.5; }\n\tto   { transform: perspective(800px) translateX(0) rotateY(0deg); opacity: 1; }\n}\n@keyframes pptx-tr-gallery-out-to-left {\n\tfrom { transform: perspective(800px) translateX(0) rotateY(0deg); opacity: 1; }\n\tto   { transform: perspective(800px) translateX(-100%) rotateY(45deg); opacity: 0.5; }\n}\n@keyframes pptx-tr-gallery-in-from-left {\n\tfrom { transform: perspective(800px) translateX(-100%) rotateY(45deg); opacity: 0.5; }\n\tto   { transform: perspective(800px) translateX(0) rotateY(0deg); opacity: 1; }\n}\n@keyframes pptx-tr-gallery-out-to-right {\n\tfrom { transform: perspective(800px) translateX(0) rotateY(0deg); opacity: 1; }\n\tto   { transform: perspective(800px) translateX(100%) rotateY(-45deg); opacity: 0.5; }\n}\n\n/* ── Glitter (particle dissolve effect) ──────────────────────────── */\n@keyframes pptx-tr-glitter-in {\n\tfrom { opacity: 0; filter: brightness(1.5) contrast(1.3) blur(2px); }\n\t60%  { opacity: 0.7; filter: brightness(1.2) contrast(1.1) blur(1px); }\n\tto   { opacity: 1; filter: brightness(1) contrast(1) blur(0); }\n}\n\n/* ── Honeycomb (hexagonal reveal) ────────────────────────────────── */\n@keyframes pptx-tr-honeycomb-in {\n\tfrom {\n\t\tclip-path: polygon(50% 50%, 50% 50%, 50% 50%, 50% 50%, 50% 50%, 50% 50%);\n\t\topacity: 0;\n\t}\n\tto {\n\t\tclip-path: polygon(50% 0%, 100% 25%, 100% 75%, 50% 100%, 0% 75%, 0% 25%);\n\t\topacity: 1;\n\t}\n}\n@keyframes pptx-tr-honeycomb-out {\n\tfrom { opacity: 1; }\n\tto   { opacity: 0; filter: blur(2px); }\n}\n\n/* ── Pan (large-scale translate) ─────────────────────────────────── */\n@keyframes pptx-tr-pan-from-right {\n\tfrom { transform: translateX(100%); }\n\tto   { transform: translateX(0); }\n}\n@keyframes pptx-tr-pan-to-left {\n\tfrom { transform: translateX(0); }\n\tto   { transform: translateX(-100%); }\n}\n@keyframes pptx-tr-pan-from-left {\n\tfrom { transform: translateX(-100%); }\n\tto   { transform: translateX(0); }\n}\n@keyframes pptx-tr-pan-to-right {\n\tfrom { transform: translateX(0); }\n\tto   { transform: translateX(100%); }\n}\n@keyframes pptx-tr-pan-from-bottom {\n\tfrom { transform: translateY(100%); }\n\tto   { transform: translateY(0); }\n}\n@keyframes pptx-tr-pan-to-top {\n\tfrom { transform: translateY(0); }\n\tto   { transform: translateY(-100%); }\n}\n@keyframes pptx-tr-pan-from-top {\n\tfrom { transform: translateY(-100%); }\n\tto   { transform: translateY(0); }\n}\n@keyframes pptx-tr-pan-to-bottom {\n\tfrom { transform: translateY(0); }\n\tto   { transform: translateY(100%); }\n}\n";

/** Part 2: prism / reveal / ripple / shred / switch / vortex / warp / wheelReverse / window. */
export declare const P14_TRANSITION_KEYFRAMES_2 = "\n/* ── Prism: see `slide-transition-prism` (split out to keep this module\n   under the per-file LOC budget) ─────────────────────────────────────── */\n\n@keyframes pptx-tr-prism-in-from-right {\n\tfrom { transform: perspective(800px) rotateY(-90deg) translateX(50%); opacity: 0; }\n\tto   { transform: perspective(800px) rotateY(0deg) translateX(0); opacity: 1; }\n}\n@keyframes pptx-tr-prism-out-to-left {\n\tfrom { transform: perspective(800px) rotateY(0deg) translateX(0); opacity: 1; }\n\tto   { transform: perspective(800px) rotateY(90deg) translateX(-50%); opacity: 0; }\n}\n@keyframes pptx-tr-prism-in-from-left {\n\tfrom { transform: perspective(800px) rotateY(90deg) translateX(-50%); opacity: 0; }\n\tto   { transform: perspective(800px) rotateY(0deg) translateX(0); opacity: 1; }\n}\n@keyframes pptx-tr-prism-out-to-right {\n\tfrom { transform: perspective(800px) rotateY(0deg) translateX(0); opacity: 1; }\n\tto   { transform: perspective(800px) rotateY(-90deg) translateX(50%); opacity: 0; }\n}\n@keyframes pptx-tr-prism-in-from-bottom {\n\tfrom { transform: perspective(800px) rotateX(90deg) translateY(50%); opacity: 0; }\n\tto   { transform: perspective(800px) rotateX(0deg) translateY(0); opacity: 1; }\n}\n@keyframes pptx-tr-prism-out-to-top {\n\tfrom { transform: perspective(800px) rotateX(0deg) translateY(0); opacity: 1; }\n\tto   { transform: perspective(800px) rotateX(-90deg) translateY(-50%); opacity: 0; }\n}\n@keyframes pptx-tr-prism-in-from-top {\n\tfrom { transform: perspective(800px) rotateX(-90deg) translateY(-50%); opacity: 0; }\n\tto   { transform: perspective(800px) rotateX(0deg) translateY(0); opacity: 1; }\n}\n@keyframes pptx-tr-prism-out-to-bottom {\n\tfrom { transform: perspective(800px) rotateX(0deg) translateY(0); opacity: 1; }\n\tto   { transform: perspective(800px) rotateX(90deg) translateY(50%); opacity: 0; }\n}\n\n/* ── Reveal (slide away reveal) ──────────────────────────────────── */\n@keyframes pptx-tr-reveal-out-to-right {\n\tfrom { transform: translateX(0); }\n\tto   { transform: translateX(100%); }\n}\n@keyframes pptx-tr-reveal-out-to-left {\n\tfrom { transform: translateX(0); }\n\tto   { transform: translateX(-100%); }\n}\n/* MEASURED: the incoming layer stays hidden for roughly the first half of the\n   transition (a real black/background gap shows through), then fades in -\n   not a flat 0.5->1 fade running the whole duration. */\n@keyframes pptx-tr-reveal-in {\n\t0%   { opacity: 0; }\n\t50%  { opacity: 0; }\n\t100% { opacity: 1; }\n}\n\n/* ── Ripple (expanding ring clip-path) ───────────────────────────── */\n@keyframes pptx-tr-ripple-in {\n\tfrom { clip-path: circle(0% at 50% 50%); opacity: 0.5; }\n\t30%  { clip-path: circle(20% at 50% 50%); opacity: 0.7; }\n\t60%  { clip-path: circle(50% at 50% 50%); opacity: 0.9; }\n\tto   { clip-path: circle(75% at 50% 50%); opacity: 1; }\n}\n\n/* ── Shred (fragmented clip-path pieces) ─────────────────────────── */\n@keyframes pptx-tr-shred-strips-in {\n\tfrom { clip-path: inset(0 100% 0 0); opacity: 0; }\n\t30%  { clip-path: inset(0 60% 0 0); opacity: 0.5; }\n\tto   { clip-path: inset(0); opacity: 1; }\n}\n@keyframes pptx-tr-shred-rectangles-in {\n\tfrom { clip-path: inset(50%); opacity: 0; }\n\t40%  { clip-path: inset(20%); opacity: 0.6; }\n\tto   { clip-path: inset(0); opacity: 1; }\n}\n@keyframes pptx-tr-shred-out {\n\tfrom { opacity: 1; }\n\tto   { opacity: 0; filter: blur(2px); }\n}\n\n/* ── Switch (flip/rotate swap) ───────────────────────────────────── */\n@keyframes pptx-tr-switch-in-from-right {\n\tfrom { transform: perspective(800px) rotateY(-180deg); opacity: 0; }\n\tto   { transform: perspective(800px) rotateY(0deg); opacity: 1; }\n}\n@keyframes pptx-tr-switch-out-to-left {\n\tfrom { transform: perspective(800px) rotateY(0deg); opacity: 1; }\n\tto   { transform: perspective(800px) rotateY(180deg); opacity: 0; }\n}\n@keyframes pptx-tr-switch-in-from-left {\n\tfrom { transform: perspective(800px) rotateY(180deg); opacity: 0; }\n\tto   { transform: perspective(800px) rotateY(0deg); opacity: 1; }\n}\n@keyframes pptx-tr-switch-out-to-right {\n\tfrom { transform: perspective(800px) rotateY(0deg); opacity: 1; }\n\tto   { transform: perspective(800px) rotateY(-180deg); opacity: 0; }\n}\n\n/* ── Vortex (rotate + scale spiral) ──────────────────────────────── */\n@keyframes pptx-tr-vortex-in {\n\tfrom { transform: rotate(720deg) scale(0); opacity: 0; }\n\tto   { transform: rotate(0deg) scale(1); opacity: 1; }\n}\n@keyframes pptx-tr-vortex-out {\n\tfrom { transform: rotate(0deg) scale(1); opacity: 1; }\n\tto   { transform: rotate(-720deg) scale(0); opacity: 0; }\n}\n\n/* ── Warp: see `slide-transition-warp` (COM-measured radial zoom blur,\n   split out to keep this module under the per-file LOC budget) ────────── */\n\n@keyframes pptx-tr-warp-in {\n\t0%   { transform: scale(0.25); opacity: 0; filter: blur(10px) brightness(1.8); }\n\t50%  { transform: scale(0.85); opacity: 0.7; filter: blur(3px) brightness(1.3); }\n\t100% { transform: scale(1); opacity: 1; filter: blur(0) brightness(1); }\n}\n@keyframes pptx-tr-warp-out {\n\t0%   { transform: scale(1); opacity: 1; filter: blur(0) brightness(1); }\n\t50%  { transform: scale(0.85); opacity: 0.7; filter: blur(3px) brightness(1.3); }\n\t100% { transform: scale(0.25); opacity: 0; filter: blur(10px) brightness(1.8); }\n}\n@keyframes pptx-tr-warp-reverse-in {\n\t0%   { transform: scale(3.2); opacity: 0; filter: blur(14px) brightness(2.2); }\n\t50%  { transform: scale(1.7); opacity: 0.7; filter: blur(6px) brightness(1.5); }\n\t100% { transform: scale(1); opacity: 1; filter: blur(0) brightness(1); }\n}\n@keyframes pptx-tr-warp-reverse-out {\n\t0%   { transform: scale(1); opacity: 1; filter: blur(0) brightness(1); }\n\t50%  { transform: scale(1.7); opacity: 0.7; filter: blur(6px) brightness(1.5); }\n\t100% { transform: scale(3.2); opacity: 0; filter: blur(14px) brightness(2.2); }\n}\n\n\n/* ── WheelReverse (reverse wheel rotation) ───────────────────────── */\n@keyframes pptx-tr-wheel-reverse-in {\n\tfrom { clip-path: circle(0% at 50% 50%); transform: rotate(180deg); }\n\tto   { clip-path: circle(75% at 50% 50%); transform: rotate(0deg); }\n}\n\n/* ── Window (scale from center with border) ──────────────────────────\n   Same measured horz/vert meaning as Doors above (horz = horizontal split\n   line opening vertically; vert = vertical split line opening horizontally). */\n@keyframes pptx-tr-window-horz {\n\tfrom { clip-path: inset(50% 0); }\n\tto   { clip-path: inset(0 0); }\n}\n@keyframes pptx-tr-window-vert {\n\tfrom { clip-path: inset(0 50%); }\n\tto   { clip-path: inset(0 0); }\n}\n@keyframes pptx-tr-window-out {\n\tfrom { opacity: 1; transform: scale(1); }\n\tto   { opacity: 0; transform: scale(0.9); }\n}\n";

/** Both p14 keyframe blocks concatenated, for single `<style>` injection. */
export declare const P14_TRANSITION_KEYFRAMES_ALL = "\n/* ── Conveyor (translate X with staggered timing) ──────────────────── */\n@keyframes pptx-tr-conveyor-in-from-right {\n\tfrom { transform: translateX(100%) rotateY(-30deg); }\n\t60%  { transform: translateX(20%) rotateY(-10deg); }\n\tto   { transform: translateX(0) rotateY(0deg); }\n}\n@keyframes pptx-tr-conveyor-out-to-left {\n\tfrom { transform: translateX(0) rotateY(0deg); }\n\t40%  { transform: translateX(-20%) rotateY(10deg); }\n\tto   { transform: translateX(-100%) rotateY(30deg); }\n}\n@keyframes pptx-tr-conveyor-in-from-left {\n\tfrom { transform: translateX(-100%) rotateY(30deg); }\n\t60%  { transform: translateX(-20%) rotateY(10deg); }\n\tto   { transform: translateX(0) rotateY(0deg); }\n}\n@keyframes pptx-tr-conveyor-out-to-right {\n\tfrom { transform: translateX(0) rotateY(0deg); }\n\t40%  { transform: translateX(20%) rotateY(-10deg); }\n\tto   { transform: translateX(100%) rotateY(-30deg); }\n}\n\n/* ── Doors (clip-path from center split) ──────────────────────────────\n   MEASURED via COM CreateVideo: PowerPoint's `dir=\"horz\"` names a\n   HORIZONTAL split line (two panels stacked top/bottom, opening upward and\n   downward), and `dir=\"vert\"` a VERTICAL split line (panels side by side,\n   opening left and right) - the opposite of what \"clips left/right\" vs\n   \"clips top/bottom\" would suggest at a glance. Keep the clip-path bodies\n   matched to the MEASURED direction, not the intuitive one. */\n@keyframes pptx-tr-doors-horz {\n\tfrom { clip-path: inset(50% 0); }\n\tto   { clip-path: inset(0 0); }\n}\n@keyframes pptx-tr-doors-vert {\n\tfrom { clip-path: inset(0 50%); }\n\tto   { clip-path: inset(0 0); }\n}\n\n/* ── Ferris (rotate elements around center) ───────────────────────── */\n@keyframes pptx-tr-ferris-in-from-right {\n\tfrom { transform: translateX(80%) rotate(45deg) scale(0.6); opacity: 0; }\n\tto   { transform: translateX(0) rotate(0deg) scale(1); opacity: 1; }\n}\n@keyframes pptx-tr-ferris-out-to-left {\n\tfrom { transform: translateX(0) rotate(0deg) scale(1); opacity: 1; }\n\tto   { transform: translateX(-80%) rotate(-45deg) scale(0.6); opacity: 0; }\n}\n@keyframes pptx-tr-ferris-in-from-left {\n\tfrom { transform: translateX(-80%) rotate(-45deg) scale(0.6); opacity: 0; }\n\tto   { transform: translateX(0) rotate(0deg) scale(1); opacity: 1; }\n}\n@keyframes pptx-tr-ferris-out-to-right {\n\tfrom { transform: translateX(0) rotate(0deg) scale(1); opacity: 1; }\n\tto   { transform: translateX(80%) rotate(45deg) scale(0.6); opacity: 0; }\n}\n\n/* ── Flash (bright flash opacity burst) ──────────────────────────── */\n@keyframes pptx-tr-flash-white {\n\t0%   { opacity: 1; }\n\t30%  { opacity: 0; }\n\t50%  { opacity: 0; }\n\t100% { opacity: 1; }\n}\n@keyframes pptx-tr-flash-in {\n\t0%   { opacity: 0; }\n\t50%  { opacity: 0; }\n\t70%  { opacity: 1; }\n\t100% { opacity: 1; }\n}\n\n/* ── Flythrough (scale + translate Z-axis feel) ──────────────────── */\n@keyframes pptx-tr-flythrough-in {\n\tfrom { transform: scale(4) translateZ(200px); opacity: 0; filter: blur(8px); }\n\tto   { transform: scale(1) translateZ(0); opacity: 1; filter: blur(0); }\n}\n@keyframes pptx-tr-flythrough-out {\n\tfrom { transform: scale(1) translateZ(0); opacity: 1; filter: blur(0); }\n\tto   { transform: scale(0.1) translateZ(-200px); opacity: 0; filter: blur(8px); }\n}\n@keyframes pptx-tr-flythrough-reverse-in {\n\tfrom { transform: scale(0.1) translateZ(-200px); opacity: 0; filter: blur(8px); }\n\tto   { transform: scale(1) translateZ(0); opacity: 1; filter: blur(0); }\n}\n@keyframes pptx-tr-flythrough-reverse-out {\n\tfrom { transform: scale(1) translateZ(0); opacity: 1; filter: blur(0); }\n\tto   { transform: scale(4) translateZ(200px); opacity: 0; filter: blur(8px); }\n}\n\n/* ── Gallery (translate with perspective) ─────────────────────────── */\n@keyframes pptx-tr-gallery-in-from-right {\n\tfrom { transform: perspective(800px) translateX(100%) rotateY(-45deg); opacity: 0.5; }\n\tto   { transform: perspective(800px) translateX(0) rotateY(0deg); opacity: 1; }\n}\n@keyframes pptx-tr-gallery-out-to-left {\n\tfrom { transform: perspective(800px) translateX(0) rotateY(0deg); opacity: 1; }\n\tto   { transform: perspective(800px) translateX(-100%) rotateY(45deg); opacity: 0.5; }\n}\n@keyframes pptx-tr-gallery-in-from-left {\n\tfrom { transform: perspective(800px) translateX(-100%) rotateY(45deg); opacity: 0.5; }\n\tto   { transform: perspective(800px) translateX(0) rotateY(0deg); opacity: 1; }\n}\n@keyframes pptx-tr-gallery-out-to-right {\n\tfrom { transform: perspective(800px) translateX(0) rotateY(0deg); opacity: 1; }\n\tto   { transform: perspective(800px) translateX(100%) rotateY(-45deg); opacity: 0.5; }\n}\n\n/* ── Glitter (particle dissolve effect) ──────────────────────────── */\n@keyframes pptx-tr-glitter-in {\n\tfrom { opacity: 0; filter: brightness(1.5) contrast(1.3) blur(2px); }\n\t60%  { opacity: 0.7; filter: brightness(1.2) contrast(1.1) blur(1px); }\n\tto   { opacity: 1; filter: brightness(1) contrast(1) blur(0); }\n}\n\n/* ── Honeycomb (hexagonal reveal) ────────────────────────────────── */\n@keyframes pptx-tr-honeycomb-in {\n\tfrom {\n\t\tclip-path: polygon(50% 50%, 50% 50%, 50% 50%, 50% 50%, 50% 50%, 50% 50%);\n\t\topacity: 0;\n\t}\n\tto {\n\t\tclip-path: polygon(50% 0%, 100% 25%, 100% 75%, 50% 100%, 0% 75%, 0% 25%);\n\t\topacity: 1;\n\t}\n}\n@keyframes pptx-tr-honeycomb-out {\n\tfrom { opacity: 1; }\n\tto   { opacity: 0; filter: blur(2px); }\n}\n\n/* ── Pan (large-scale translate) ─────────────────────────────────── */\n@keyframes pptx-tr-pan-from-right {\n\tfrom { transform: translateX(100%); }\n\tto   { transform: translateX(0); }\n}\n@keyframes pptx-tr-pan-to-left {\n\tfrom { transform: translateX(0); }\n\tto   { transform: translateX(-100%); }\n}\n@keyframes pptx-tr-pan-from-left {\n\tfrom { transform: translateX(-100%); }\n\tto   { transform: translateX(0); }\n}\n@keyframes pptx-tr-pan-to-right {\n\tfrom { transform: translateX(0); }\n\tto   { transform: translateX(100%); }\n}\n@keyframes pptx-tr-pan-from-bottom {\n\tfrom { transform: translateY(100%); }\n\tto   { transform: translateY(0); }\n}\n@keyframes pptx-tr-pan-to-top {\n\tfrom { transform: translateY(0); }\n\tto   { transform: translateY(-100%); }\n}\n@keyframes pptx-tr-pan-from-top {\n\tfrom { transform: translateY(-100%); }\n\tto   { transform: translateY(0); }\n}\n@keyframes pptx-tr-pan-to-bottom {\n\tfrom { transform: translateY(0); }\n\tto   { transform: translateY(100%); }\n}\n\n\n/* ── Prism: see `slide-transition-prism` (split out to keep this module\n   under the per-file LOC budget) ─────────────────────────────────────── */\n\n@keyframes pptx-tr-prism-in-from-right {\n\tfrom { transform: perspective(800px) rotateY(-90deg) translateX(50%); opacity: 0; }\n\tto   { transform: perspective(800px) rotateY(0deg) translateX(0); opacity: 1; }\n}\n@keyframes pptx-tr-prism-out-to-left {\n\tfrom { transform: perspective(800px) rotateY(0deg) translateX(0); opacity: 1; }\n\tto   { transform: perspective(800px) rotateY(90deg) translateX(-50%); opacity: 0; }\n}\n@keyframes pptx-tr-prism-in-from-left {\n\tfrom { transform: perspective(800px) rotateY(90deg) translateX(-50%); opacity: 0; }\n\tto   { transform: perspective(800px) rotateY(0deg) translateX(0); opacity: 1; }\n}\n@keyframes pptx-tr-prism-out-to-right {\n\tfrom { transform: perspective(800px) rotateY(0deg) translateX(0); opacity: 1; }\n\tto   { transform: perspective(800px) rotateY(-90deg) translateX(50%); opacity: 0; }\n}\n@keyframes pptx-tr-prism-in-from-bottom {\n\tfrom { transform: perspective(800px) rotateX(90deg) translateY(50%); opacity: 0; }\n\tto   { transform: perspective(800px) rotateX(0deg) translateY(0); opacity: 1; }\n}\n@keyframes pptx-tr-prism-out-to-top {\n\tfrom { transform: perspective(800px) rotateX(0deg) translateY(0); opacity: 1; }\n\tto   { transform: perspective(800px) rotateX(-90deg) translateY(-50%); opacity: 0; }\n}\n@keyframes pptx-tr-prism-in-from-top {\n\tfrom { transform: perspective(800px) rotateX(-90deg) translateY(-50%); opacity: 0; }\n\tto   { transform: perspective(800px) rotateX(0deg) translateY(0); opacity: 1; }\n}\n@keyframes pptx-tr-prism-out-to-bottom {\n\tfrom { transform: perspective(800px) rotateX(0deg) translateY(0); opacity: 1; }\n\tto   { transform: perspective(800px) rotateX(90deg) translateY(50%); opacity: 0; }\n}\n\n/* ── Reveal (slide away reveal) ──────────────────────────────────── */\n@keyframes pptx-tr-reveal-out-to-right {\n\tfrom { transform: translateX(0); }\n\tto   { transform: translateX(100%); }\n}\n@keyframes pptx-tr-reveal-out-to-left {\n\tfrom { transform: translateX(0); }\n\tto   { transform: translateX(-100%); }\n}\n/* MEASURED: the incoming layer stays hidden for roughly the first half of the\n   transition (a real black/background gap shows through), then fades in -\n   not a flat 0.5->1 fade running the whole duration. */\n@keyframes pptx-tr-reveal-in {\n\t0%   { opacity: 0; }\n\t50%  { opacity: 0; }\n\t100% { opacity: 1; }\n}\n\n/* ── Ripple (expanding ring clip-path) ───────────────────────────── */\n@keyframes pptx-tr-ripple-in {\n\tfrom { clip-path: circle(0% at 50% 50%); opacity: 0.5; }\n\t30%  { clip-path: circle(20% at 50% 50%); opacity: 0.7; }\n\t60%  { clip-path: circle(50% at 50% 50%); opacity: 0.9; }\n\tto   { clip-path: circle(75% at 50% 50%); opacity: 1; }\n}\n\n/* ── Shred (fragmented clip-path pieces) ─────────────────────────── */\n@keyframes pptx-tr-shred-strips-in {\n\tfrom { clip-path: inset(0 100% 0 0); opacity: 0; }\n\t30%  { clip-path: inset(0 60% 0 0); opacity: 0.5; }\n\tto   { clip-path: inset(0); opacity: 1; }\n}\n@keyframes pptx-tr-shred-rectangles-in {\n\tfrom { clip-path: inset(50%); opacity: 0; }\n\t40%  { clip-path: inset(20%); opacity: 0.6; }\n\tto   { clip-path: inset(0); opacity: 1; }\n}\n@keyframes pptx-tr-shred-out {\n\tfrom { opacity: 1; }\n\tto   { opacity: 0; filter: blur(2px); }\n}\n\n/* ── Switch (flip/rotate swap) ───────────────────────────────────── */\n@keyframes pptx-tr-switch-in-from-right {\n\tfrom { transform: perspective(800px) rotateY(-180deg); opacity: 0; }\n\tto   { transform: perspective(800px) rotateY(0deg); opacity: 1; }\n}\n@keyframes pptx-tr-switch-out-to-left {\n\tfrom { transform: perspective(800px) rotateY(0deg); opacity: 1; }\n\tto   { transform: perspective(800px) rotateY(180deg); opacity: 0; }\n}\n@keyframes pptx-tr-switch-in-from-left {\n\tfrom { transform: perspective(800px) rotateY(180deg); opacity: 0; }\n\tto   { transform: perspective(800px) rotateY(0deg); opacity: 1; }\n}\n@keyframes pptx-tr-switch-out-to-right {\n\tfrom { transform: perspective(800px) rotateY(0deg); opacity: 1; }\n\tto   { transform: perspective(800px) rotateY(-180deg); opacity: 0; }\n}\n\n/* ── Vortex (rotate + scale spiral) ──────────────────────────────── */\n@keyframes pptx-tr-vortex-in {\n\tfrom { transform: rotate(720deg) scale(0); opacity: 0; }\n\tto   { transform: rotate(0deg) scale(1); opacity: 1; }\n}\n@keyframes pptx-tr-vortex-out {\n\tfrom { transform: rotate(0deg) scale(1); opacity: 1; }\n\tto   { transform: rotate(-720deg) scale(0); opacity: 0; }\n}\n\n/* ── Warp: see `slide-transition-warp` (COM-measured radial zoom blur,\n   split out to keep this module under the per-file LOC budget) ────────── */\n\n@keyframes pptx-tr-warp-in {\n\t0%   { transform: scale(0.25); opacity: 0; filter: blur(10px) brightness(1.8); }\n\t50%  { transform: scale(0.85); opacity: 0.7; filter: blur(3px) brightness(1.3); }\n\t100% { transform: scale(1); opacity: 1; filter: blur(0) brightness(1); }\n}\n@keyframes pptx-tr-warp-out {\n\t0%   { transform: scale(1); opacity: 1; filter: blur(0) brightness(1); }\n\t50%  { transform: scale(0.85); opacity: 0.7; filter: blur(3px) brightness(1.3); }\n\t100% { transform: scale(0.25); opacity: 0; filter: blur(10px) brightness(1.8); }\n}\n@keyframes pptx-tr-warp-reverse-in {\n\t0%   { transform: scale(3.2); opacity: 0; filter: blur(14px) brightness(2.2); }\n\t50%  { transform: scale(1.7); opacity: 0.7; filter: blur(6px) brightness(1.5); }\n\t100% { transform: scale(1); opacity: 1; filter: blur(0) brightness(1); }\n}\n@keyframes pptx-tr-warp-reverse-out {\n\t0%   { transform: scale(1); opacity: 1; filter: blur(0) brightness(1); }\n\t50%  { transform: scale(1.7); opacity: 0.7; filter: blur(6px) brightness(1.5); }\n\t100% { transform: scale(3.2); opacity: 0; filter: blur(14px) brightness(2.2); }\n}\n\n\n/* ── WheelReverse (reverse wheel rotation) ───────────────────────── */\n@keyframes pptx-tr-wheel-reverse-in {\n\tfrom { clip-path: circle(0% at 50% 50%); transform: rotate(180deg); }\n\tto   { clip-path: circle(75% at 50% 50%); transform: rotate(0deg); }\n}\n\n/* ── Window (scale from center with border) ──────────────────────────\n   Same measured horz/vert meaning as Doors above (horz = horizontal split\n   line opening vertically; vert = vertical split line opening horizontally). */\n@keyframes pptx-tr-window-horz {\n\tfrom { clip-path: inset(50% 0); }\n\tto   { clip-path: inset(0 0); }\n}\n@keyframes pptx-tr-window-vert {\n\tfrom { clip-path: inset(0 50%); }\n\tto   { clip-path: inset(0 0); }\n}\n@keyframes pptx-tr-window-out {\n\tfrom { opacity: 1; transform: scale(1); }\n\tto   { opacity: 0; transform: scale(0.9); }\n}\n\n\n@keyframes pptx-tr-vortex-in-left { from { transform: translateX(-40%) rotate(720deg) scale(0); opacity: 0; } to { transform: translateX(0) rotate(0deg) scale(1); opacity: 1; } }\n@keyframes pptx-tr-vortex-out-left { from { transform: translateX(0) rotate(0deg) scale(1); opacity: 1; } to { transform: translateX(-40%) rotate(-720deg) scale(0); opacity: 0; } }\n@keyframes pptx-tr-vortex-in-right { from { transform: translateX(40%) rotate(-720deg) scale(0); opacity: 0; } to { transform: translateX(0) rotate(0deg) scale(1); opacity: 1; } }\n@keyframes pptx-tr-vortex-out-right { from { transform: translateX(0) rotate(0deg) scale(1); opacity: 1; } to { transform: translateX(40%) rotate(720deg) scale(0); opacity: 0; } }\n@keyframes pptx-tr-vortex-in-up { from { transform: translateY(-40%) rotate(720deg) scale(0); opacity: 0; } to { transform: translateY(0) rotate(0deg) scale(1); opacity: 1; } }\n@keyframes pptx-tr-vortex-out-up { from { transform: translateY(0) rotate(0deg) scale(1); opacity: 1; } to { transform: translateY(-40%) rotate(-720deg) scale(0); opacity: 0; } }\n@keyframes pptx-tr-vortex-in-down { from { transform: translateY(40%) rotate(-720deg) scale(0); opacity: 0; } to { transform: translateY(0) rotate(0deg) scale(1); opacity: 1; } }\n@keyframes pptx-tr-vortex-out-down { from { transform: translateY(0) rotate(0deg) scale(1); opacity: 1; } to { transform: translateY(40%) rotate(720deg) scale(0); opacity: 0; } }\n\n\n@keyframes pptx-tr-ripple-in-lu { from { clip-path: circle(0% at 0% 0%); opacity: 0.5; } 30% { clip-path: circle(20% at 0% 0%); opacity: 0.7; } 60% { clip-path: circle(55% at 0% 0%); opacity: 0.9; } to { clip-path: circle(150% at 0% 0%); opacity: 1; } }\n@keyframes pptx-tr-ripple-in-ru { from { clip-path: circle(0% at 100% 0%); opacity: 0.5; } 30% { clip-path: circle(20% at 100% 0%); opacity: 0.7; } 60% { clip-path: circle(55% at 100% 0%); opacity: 0.9; } to { clip-path: circle(150% at 100% 0%); opacity: 1; } }\n@keyframes pptx-tr-ripple-in-ld { from { clip-path: circle(0% at 0% 100%); opacity: 0.5; } 30% { clip-path: circle(20% at 0% 100%); opacity: 0.7; } 60% { clip-path: circle(55% at 0% 100%); opacity: 0.9; } to { clip-path: circle(150% at 0% 100%); opacity: 1; } }\n@keyframes pptx-tr-ripple-in-rd { from { clip-path: circle(0% at 100% 100%); opacity: 0.5; } 30% { clip-path: circle(20% at 100% 100%); opacity: 0.7; } 60% { clip-path: circle(55% at 100% 100%); opacity: 0.9; } to { clip-path: circle(150% at 100% 100%); opacity: 1; } }\n\n\n@keyframes pptx-tr-glitter-diamond-in-l { from { opacity: 0; transform: translateX(-6%); filter: brightness(1.5) contrast(1.3) blur(2px); } 60% { opacity: 0.7; transform: translateX(-2%); filter: brightness(1.2) contrast(1.1) blur(1px); } to { opacity: 1; transform: translateX(0); filter: brightness(1) contrast(1) blur(0); } }\n@keyframes pptx-tr-glitter-diamond-in-r { from { opacity: 0; transform: translateX(6%); filter: brightness(1.5) contrast(1.3) blur(2px); } 60% { opacity: 0.7; transform: translateX(2%); filter: brightness(1.2) contrast(1.1) blur(1px); } to { opacity: 1; transform: translateX(0); filter: brightness(1) contrast(1) blur(0); } }\n@keyframes pptx-tr-glitter-diamond-in-u { from { opacity: 0; transform: translateY(-6%); filter: brightness(1.5) contrast(1.3) blur(2px); } 60% { opacity: 0.7; transform: translateY(-2%); filter: brightness(1.2) contrast(1.1) blur(1px); } to { opacity: 1; transform: translateY(0); filter: brightness(1) contrast(1) blur(0); } }\n@keyframes pptx-tr-glitter-diamond-in-d { from { opacity: 0; transform: translateY(6%); filter: brightness(1.5) contrast(1.3) blur(2px); } 60% { opacity: 0.7; transform: translateY(2%); filter: brightness(1.2) contrast(1.1) blur(1px); } to { opacity: 1; transform: translateY(0); filter: brightness(1) contrast(1) blur(0); } }\n@keyframes pptx-tr-glitter-hexagon-in-l { from { opacity: 0; transform: translateX(-6%); filter: brightness(1.5) contrast(1.3) blur(2px) hue-rotate(20deg); } 60% { opacity: 0.7; transform: translateX(-2%); filter: brightness(1.2) contrast(1.1) blur(1px) hue-rotate(8deg); } to { opacity: 1; transform: translateX(0); filter: brightness(1) contrast(1) blur(0) hue-rotate(0deg); } }\n@keyframes pptx-tr-glitter-hexagon-in-r { from { opacity: 0; transform: translateX(6%); filter: brightness(1.5) contrast(1.3) blur(2px) hue-rotate(20deg); } 60% { opacity: 0.7; transform: translateX(2%); filter: brightness(1.2) contrast(1.1) blur(1px) hue-rotate(8deg); } to { opacity: 1; transform: translateX(0); filter: brightness(1) contrast(1) blur(0) hue-rotate(0deg); } }\n@keyframes pptx-tr-glitter-hexagon-in-u { from { opacity: 0; transform: translateY(-6%); filter: brightness(1.5) contrast(1.3) blur(2px) hue-rotate(20deg); } 60% { opacity: 0.7; transform: translateY(-2%); filter: brightness(1.2) contrast(1.1) blur(1px) hue-rotate(8deg); } to { opacity: 1; transform: translateY(0); filter: brightness(1) contrast(1) blur(0) hue-rotate(0deg); } }\n@keyframes pptx-tr-glitter-hexagon-in-d { from { opacity: 0; transform: translateY(6%); filter: brightness(1.5) contrast(1.3) blur(2px) hue-rotate(20deg); } 60% { opacity: 0.7; transform: translateY(2%); filter: brightness(1.2) contrast(1.1) blur(1px) hue-rotate(8deg); } to { opacity: 1; transform: translateY(0); filter: brightness(1) contrast(1) blur(0) hue-rotate(0deg); } }\n";

/** A single rendered run within a paragraph. */
declare interface ParagraphRun {
    text: string;
    style: RunStyle;
    /**
     * The run's hyperlink (`a:hlinkClick` / `a:hlinkMouseOver`), when it has one.
     * A binding renders the run inside an `<a href>` when {@link RunHyperlink.href}
     * is set, and routes {@link RunHyperlink.url} to its click handler otherwise
     * (internal `ppaction://` slide jumps).
     */
    hyperlink?: RunHyperlink;
    /**
     * An inline equation (`m:oMath`) this run renders INSTEAD of `text`, which is
     * empty for it. Emitted in the run sequence so the maths lands at its
     * authored position between the runs around it.
     */
    equation?: RunEquation;
    /**
     * The run's phonetic guide (`a:ruby`: furigana, pinyin, bopomofo), when it
     * has one. A binding renders `<ruby>{text}<rt style>{ruby.text}</rt></ruby>`;
     * a run carrying one is never split per word, so the annotation appears once
     * over the whole base run.
     *
     * Core parsed and saved ruby from the start, but `buildParagraphs` never read
     * it, so the annotation rendered in React alone.
     */
    ruby?: RunRuby;
    /**
     * Index of the `textSegments` entry (of the override list when one was
     * supplied) this run was built from.
     *
     * Shared splits one authored run into several per-word runs for PowerPoint's
     * metric tracking, so this is many-to-one. It is the seam a binding uses to
     * reach the facts the neutral model does not carry - React's find-match
     * highlights, per-script font spans, tab stops and ruby all key off the
     * originating segment - without regrouping the segments itself and drifting
     * from the grouping here.
     */
    segmentIndex?: number;
    /**
     * Offset of this run's `text` within its segment's RENDERED text (after field
     * substitution), so a caller holding per-segment character offsets can map
     * them onto the split runs.
     */
    charStart?: number;
    /**
     * Per-script (`a:ea`/`a:cs`/`a:sym`) font-fallback pieces for this run's
     * text, when a script it contains needs a font distinct from its own. A
     * binding renders these as nested spans in place of `text` (see
     * `text-script-fonts.ts`); absent for the common single-font case.
     */
    scriptRuns?: ScriptFontPiece[];
    /**
     * Measured tab-stop layout for this run's text, present when it contains an
     * authored `\t` and the paragraph declares explicit tab stops. A binding
     * renders these lines/pieces in place of `text`, honouring per-stop
     * alignment and leader glyphs a plain CSS `tab-size` cannot express (see
     * `text-tab-run-build.ts`). Absent for the common no-tab case.
     */
    tabLines?: TabbedLineRun[];
    /**
     * `a:rPr/@u="words"` word/gap pieces of a RUBY run's base text, present only
     * when such a run's underline is `words` (the ordinary per-word split emits
     * sibling runs instead; a tab piece carries its own `words`). Same shape as
     * `scriptRuns` and rendered the same way, in place of `text`: a word entry
     * carries the decoration for its own span, a gap entry is bare text. The
     * run's own `style` has the underline stripped when this is set (see
     * `paragraph-run-build.ts`).
     */
    underlineWordPieces?: ScriptFontPiece[];
    /** The advance-carrying space after a hanging `、`/`。` (`text-east-asian-breaks`). */
    hangingSpace?: true;
    /**
     * `a:reflection` mirrored-sibling wrapper style for this run (the text-run
     * counterpart of a shape/picture's `ComputedEffectStyle.reflection`), or
     * `undefined` for the common no-reflection case. A binding renders a sibling
     * node just below the run's own, painted with the same text, positioned and
     * masked by this style - see `render/reflection.ts`'s
     * `getTextReflectionWrapperStyle`.
     */
    reflection?: ReflectionWrapperStyle;
}

/** A parsed `Mod+Shift+D` chord. */
declare interface ParsedShortcutChord {
    key: string;
    mod: boolean;
    ctrl: boolean;
    meta: boolean;
    alt: boolean;
    shift: boolean;
}

/** Parsed digital signature with certificate info and validation status. */
declare interface ParsedSignature {
    /** Path to the signature XML in the ZIP. */
    signaturePath: string;
    /** The canonicalized signing method algorithm URI. */
    signatureMethod?: string;
    /** The digest method algorithm URI from the first reference. */
    digestMethod?: string;
    /** Base64-encoded signature value. */
    signatureValue?: string;
    /** Certificate information, if X.509 data was found. */
    certificate?: SignatureCertificateInfo;
    /** Signature validation status. */
    status: SignatureStatus;
    /** Reference URIs and their digest values. */
    references: SignatureReference[];
}

/**
 * Table background style (CT_TableBackgroundStyle, ECMA-376 §21.1.3.7).
 *
 * Corresponds to the `<a:tblBg>` child of `<a:tblStyle>`. Captures the
 * resolved scheme-fill colour, an unresolved style-matrix `a:fillRef`, and a
 * presence flag for effects (verbatim XML for the effect list is preserved
 * separately by the save path).
 */
declare interface ParsedTableBackground {
    /** Solid fill (resolved from `a:fill > a:solidFill > a:schemeClr`). */
    fill?: ParsedTableStyleFill;
    /**
     * Style-matrix fill reference (`<a:fillRef idx="N">...</a:fillRef>`),
     * mutually exclusive with {@link fill} (`a:fill` is the choice sibling of
     * `a:fillRef` in `CT_TableBackgroundStyle`).
     */
    fillRef?: ParsedTableFillRef;
    /** Has an `a:effectLst` child that should be round-tripped. */
    hasEffectLst?: boolean;
}

/**
 * A `a:fillRef`/`a:lnRef`/`a:effectRef`-style style-matrix reference: an
 * index into the theme's format scheme (`a:fmtScheme/a:fillStyleLst`, 1-based
 * per ECMA-376 §20.1.4.1.12) plus an optional colour transform child.
 *
 * Distinct from an already-resolved {@link ParsedTableStyleFill}: a fill ref
 * points AT a theme style-matrix entry rather than carrying a colour choice
 * directly, though the two commonly appear together (`<a:fillRef idx="2">
 * <a:schemeClr val="accent1"/></a:fillRef>`).
 *
 * @example
 * ```ts
 * const ref: ParsedTableFillRef = { idx: 2, color: { schemeColor: 'accent1' } };
 * // => satisfies ParsedTableFillRef
 * ```
 */
declare interface ParsedTableFillRef {
    /** 1-based index into the theme format scheme's fill style list. */
    idx: number;
    /** Colour transform child (`a:schemeClr`/`a:srgbClr`) applied to the referenced style. */
    color?: ParsedTableStyleFill;
}

/**
 * A single border side within a table style's `a:tcStyle/a:tcBdr`.
 *
 * Corresponds to one of `a:left`, `a:right`, `a:top`, `a:bottom`,
 * `a:insideH`, `a:insideV`, `a:tl2br`, `a:tr2bl` (each a
 * `CT_ThemeableLineStyle` wrapping an `a:ln`).
 *
 * @example
 * ```ts
 * const side: ParsedTableStyleBorder = {
 *   width: 1,
 *   dash: 'solid',
 *   fill: { schemeColor: 'lt1' },
 * };
 * // => satisfies ParsedTableStyleBorder
 * ```
 */
declare interface ParsedTableStyleBorder {
    /** Line width in px (converted from the `a:ln@w` EMU value). */
    width?: number;
    /** OOXML `a:prstDash@val` (e.g. `solid`, `dash`, `sysDot`). */
    dash?: string;
    /** Border colour as a theme scheme fill (from `a:ln/a:solidFill/a:schemeClr`). */
    fill?: ParsedTableStyleFill;
    /** Explicit hex colour when the line used `a:srgbClr` (e.g. `#808080`). */
    color?: string;
    /** The line was `a:noFill` - an explicit "no border" that clears lower layers. */
    noFill?: boolean;
}

/**
 * The set of border sides parsed from a table style section's
 * `a:tcStyle/a:tcBdr` element.
 */
declare interface ParsedTableStyleBorders {
    left?: ParsedTableStyleBorder;
    right?: ParsedTableStyleBorder;
    top?: ParsedTableStyleBorder;
    bottom?: ParsedTableStyleBorder;
    /** Interior horizontal borders between rows in the region. */
    insideH?: ParsedTableStyleBorder;
    /** Interior vertical borders between columns in the region. */
    insideV?: ParsedTableStyleBorder;
    /** Top-left to bottom-right diagonal. */
    tl2br?: ParsedTableStyleBorder;
    /**
     * Top-right to bottom-left diagonal (`a:tr2bl`, ECMA-376's
     * `CT_TableCellBorderStyle` sequence: left/right/top/bottom/insideH/
     * insideV/tl2br/tr2bl). The field keeps its historical `bl2tr` spelling
     * only in the sense that it names the same geometric anti-diagonal line
     * (top-right-to-bottom-left and bottom-left-to-top-right describe one
     * undirected diagonal); the parser accepts the real `a:tr2bl` element and,
     * leniently, a legacy `a:bl2tr` this app previously wrote (issue G4).
     */
    tr2bl?: ParsedTableStyleBorder;
}

/**
 * One leaf (or `effectDag`-wrapped) node of an `a:effectLst`/`a:effectDag`
 * effect chain, kept mostly opaque: {@link kind} names the OOXML element so a
 * consumer can recognise common effects (`outerShdw`, `glow`, `softEdge`,
 * `reflection`, `blur`, `innerShdw`, `prstShdw`, `fillOverlay`, `alphaModFix`,
 * `alphaInv`, `grayscl`, `biLevel`, `duotone`, `hsl`, `lum`, `tint`) without
 * this module re-deriving the full shape-effect taxonomy already modelled on
 * `ShapeStyle`; {@link xml} preserves the node verbatim for lossless re-emit.
 *
 * @example
 * ```ts
 * const effect: ParsedTableStyleEffect = {
 *   kind: 'outerShdw',
 *   xml: { '@_blurRad': '40000', '@_dist': '20000', '@_dir': '5400000' },
 * };
 * // => satisfies ParsedTableStyleEffect
 * ```
 */
declare interface ParsedTableStyleEffect {
    /** The OOXML element's local name, e.g. `outerShdw`, `glow`, `softEdge`. */
    kind: string;
    /** Verbatim XML node (attributes + children) for lossless round-trip. */
    xml: XmlObject;
}

declare interface ParsedTableStyleEntry {
    styleId: string;
    styleName?: string;
    /** Dominant accent key derived from fills (e.g. `accent1`). */
    accentKey?: string;
    /** Table-level background (`<a:tblBg>`). */
    tableBackground?: ParsedTableBackground;
    wholeTblFill?: ParsedTableStyleFill;
    band1HFill?: ParsedTableStyleFill;
    band2HFill?: ParsedTableStyleFill;
    band1VFill?: ParsedTableStyleFill;
    band2VFill?: ParsedTableStyleFill;
    firstRowFill?: ParsedTableStyleFill;
    lastRowFill?: ParsedTableStyleFill;
    firstColFill?: ParsedTableStyleFill;
    lastColFill?: ParsedTableStyleFill;
    /** Corner cell fills (`<a:seCell>`, `<a:swCell>`, `<a:neCell>`, `<a:nwCell>`). */
    seCellFill?: ParsedTableStyleFill;
    swCellFill?: ParsedTableStyleFill;
    neCellFill?: ParsedTableStyleFill;
    nwCellFill?: ParsedTableStyleFill;
    /**
     * Per-role border styling from `a:tcStyle/a:tcBdr`. These supply the
     * gridlines/edges a styled table inherits from its table style when the
     * cells carry no explicit per-cell `a:lnX` overrides.
     */
    wholeTblBorders?: ParsedTableStyleBorders;
    firstRowBorders?: ParsedTableStyleBorders;
    lastRowBorders?: ParsedTableStyleBorders;
    firstColBorders?: ParsedTableStyleBorders;
    lastColBorders?: ParsedTableStyleBorders;
    band1HBorders?: ParsedTableStyleBorders;
    band2HBorders?: ParsedTableStyleBorders;
    band1VBorders?: ParsedTableStyleBorders;
    band2VBorders?: ParsedTableStyleBorders;
    seCellBorders?: ParsedTableStyleBorders;
    swCellBorders?: ParsedTableStyleBorders;
    neCellBorders?: ParsedTableStyleBorders;
    nwCellBorders?: ParsedTableStyleBorders;
    /** Per-role text styling from a:tcTxStyle. */
    wholeTblText?: ParsedTableStyleText;
    firstRowText?: ParsedTableStyleText;
    lastRowText?: ParsedTableStyleText;
    firstColText?: ParsedTableStyleText;
    lastColText?: ParsedTableStyleText;
    band1HText?: ParsedTableStyleText;
    band2HText?: ParsedTableStyleText;
    band1VText?: ParsedTableStyleText;
    band2VText?: ParsedTableStyleText;
    seCellText?: ParsedTableStyleText;
    swCellText?: ParsedTableStyleText;
    neCellText?: ParsedTableStyleText;
    nwCellText?: ParsedTableStyleText;
    /**
     * Per-role 3D bevel + lighting from `a:tcStyle/a:cell3D` (CT_Cell3D),
     * distinct from the per-cell `a:tcPr/a:cell3D` {@link PptxTableCellStyle}
     * already supports. None of PowerPoint's 74 built-in gallery styles use
     * this (0 hits in the built-in catalogue), so it only matters for a
     * hand-authored or third-party table style.
     */
    wholeTblCell3D?: PptxTableCell3D;
    firstRowCell3D?: PptxTableCell3D;
    lastRowCell3D?: PptxTableCell3D;
    firstColCell3D?: PptxTableCell3D;
    lastColCell3D?: PptxTableCell3D;
    band1HCell3D?: PptxTableCell3D;
    band2HCell3D?: PptxTableCell3D;
    band1VCell3D?: PptxTableCell3D;
    band2VCell3D?: PptxTableCell3D;
    seCellCell3D?: PptxTableCell3D;
    swCellCell3D?: PptxTableCell3D;
    neCellCell3D?: PptxTableCell3D;
    nwCellCell3D?: PptxTableCell3D;
}

/**
 * A single fill reference within a table style section.
 *
 * @example
 * ```ts
 * const fill: ParsedTableStyleFill = {
 *   schemeColor: "accent1",
 *   tint: 40000,   // 40% tint
 * };
 * // => satisfies ParsedTableStyleFill
 * ```
 */
declare interface ParsedTableStyleFill {
    /**
     * Theme colour key (e.g. `accent1`, `dk1`). Empty string when the fill is a
     * non-scheme fill (explicit sRGB, gradient, pattern, or none) that carries
     * no theme colour reference; the renderer then resolves {@link color},
     * {@link gradient}, {@link pattern}, or {@link noFill} instead.
     */
    schemeColor: string;
    /** Tint value (0-100 000). */
    tint?: number;
    /** Shade value (0-100 000). */
    shade?: number;
    /**
     * Alpha (opacity) value (0-100 000, where 100 000 is fully opaque) from an
     * `a:alpha` child of `a:schemeClr`/`a:srgbClr`. Several built-in table
     * styles (e.g. "Light Style 1/3", "Themed Style 1/2") band their rows with
     * a partially transparent tint of the theme colour rather than a tint/shade
     * blend.
     */
    alpha?: number;
    /** Explicit sRGB hex colour (e.g. `#FF8800`) from `a:srgbClr`. */
    color?: string;
    /** The fill was `a:noFill`: renders transparent and clears lower layers. */
    noFill?: boolean;
    /** Gradient fill parsed from `a:gradFill`. */
    gradient?: ParsedTableStyleGradient;
    /** Preset pattern fill parsed from `a:pattFill`. */
    pattern?: ParsedTableStylePattern;
    /** Image texture fill parsed from `a:blipFill`. */
    image?: ParsedTableStyleImage;
}

/** A gradient fill parsed from a table style section's `a:gradFill`. */
declare interface ParsedTableStyleGradient {
    /** Ordered colour stops. */
    stops: ParsedTableStyleGradientStop[];
    /** Linear gradient angle in degrees (from `a:lin@ang`, 60000ths -> deg). */
    angle?: number;
    /** Gradient family: linear (`a:lin`) or radial (`a:path`). */
    type: 'linear' | 'radial';
}

/** A single colour stop within a {@link ParsedTableStyleGradient}. */
declare interface ParsedTableStyleGradientStop {
    /** Stop position as a percentage (0-100). */
    position: number;
    /** Stop colour (scheme or explicit sRGB). */
    fill: ParsedTableStyleFill;
}

/**
 * An image texture fill parsed from a table style section's `a:blipFill`.
 *
 * `ppt/tableStyles.xml` is a presentation-level part parsed once (not
 * per-slide), so this mirrors the per-CELL `a:tcPr/a:blipFill` two-field lazy
 * pattern (`PptxTableCellStyle.backgroundImageFillPath` /
 * `backgroundImageFillData`): `path` starts out as a raw archive-relative
 * path (or an already-external `http(s):`/`data:` URL), and a load pipeline
 * patches it to a displayable URL in `data` once resolved.
 */
declare interface ParsedTableStyleImage {
    /** Archive-relative path, or an already-displayable external/data URL. */
    path?: string;
    /** Displayable URL once a load pipeline has resolved `path`. */
    data?: string;
}

/**
 * Map of GUID → table style entry.
 *
 * Parsed from `ppt/tableStyles.xml` and indexed by the style GUID
 * referenced in `a:tblPr@tblStyle`.
 *
 * @example
 * ```ts
 * const styles: ParsedTableStyleMap = {
 *   "{5C22544A-7EE6-4342-B048-85BDC9FD1C3A}": {
 *     styleId: "{5C22544A-7EE6-4342-B048-85BDC9FD1C3A}",
 *     styleName: "Medium Style 2 - Accent 1",
 *     accentKey: "accent1",
 *   },
 * };
 * // => satisfies ParsedTableStyleMap
 * ```
 */
declare type ParsedTableStyleMap = Record<string, ParsedTableStyleEntry>;

/** A preset pattern fill parsed from a table style section's `a:pattFill`. */
declare interface ParsedTableStylePattern {
    /** OOXML preset name (e.g. `ltDnDiag`) from `a:pattFill@prst`. */
    preset: string;
    /** Foreground colour (`a:fgClr`). */
    foreground?: ParsedTableStyleFill;
    /** Background colour (`a:bgClr`). */
    background?: ParsedTableStyleFill;
}

/**
 * A single entry in the parsed table style map.
 *
 * Contains fill colours for whole-table, banded rows/columns, first/last
 * row, and first/last column sections.
 *
 * @example
 * ```ts
 * const entry: ParsedTableStyleEntry = {
 *   styleId: "{5C22544A-7EE6-4342-B048-85BDC9FD1C3A}",
 *   styleName: "Medium Style 2 - Accent 1",
 *   accentKey: "accent1",
 *   wholeTblFill: { schemeColor: "accent1", tint: 20000 },
 *   band1HFill:   { schemeColor: "accent1", tint: 40000 },
 *   firstRowFill: { schemeColor: "accent1" },
 * };
 * // => satisfies ParsedTableStyleEntry
 * ```
 */
/** Text properties from a:tcTxStyle in a table style section. */
declare interface ParsedTableStyleText {
    /** Font bold. */
    bold?: boolean;
    /** Font italic. */
    italic?: boolean;
    /** Font underline (from `a:tcTxStyle@u`, any value other than `none`). */
    underline?: boolean;
    /** Font colour as theme scheme key. */
    fontSchemeColor?: string;
    /** Font colour tint (0-100 000). */
    fontTint?: number;
    /** Font colour shade (0-100 000). */
    fontShade?: number;
    /** Explicit sRGB hex font colour (e.g. `#FF0000`) from `a:srgbClr`. */
    fontColor?: string;
    /** Typeface from `a:font@typeface` (latin font). */
    fontFace?: string;
    /** Font-collection index from `a:fontRef@idx` (`minor`, `major`, `none`). */
    fontRefIdx?: string;
}

/**
 * Parse digital signatures from a `.pptx` ZIP buffer (best-effort; returns an
 * empty array when there are none or parsing fails).
 *
 * `jszip`/`fast-xml-parser` are imported statically on purpose: `PptxHandler`
 * (imported above) already pulls both into the same chunk, so a dynamic import
 * here cannot move them anywhere. It only made bundlers emit
 * INEFFECTIVE_DYNAMIC_IMPORT.
 *
 * The parser options mirror core's loader parser rather than taking
 * fast-xml-parser's defaults, and `packages/angular` carries the identical
 * copy of this function (see the note there). Two reasons, one cosmetic and
 * one structural:
 *
 * - fast-xml-parser decodes the five predefined entities but NOT numeric
 *   character references, so a certificate DN written
 *   `CN=M&#xFC;ller CA` was rendered verbatim in the signatures panel instead
 *   of `CN=Müller CA`. Non-ASCII signer names are exactly the ones a producer
 *   is most likely to escape that way, so the panel garbled the names it most
 *   needed to get right. `decodeXmlEntities` is the same helper core's parser
 *   uses, so both now agree on what a DN says.
 * - `processEntities: false` removes DTD handling from a path that reads
 *   attacker-supplied bytes. fast-xml-parser 5.9.2 expands no entities and
 *   rejects external ones outright, so nothing here was exploitable; this is
 *   forward-stability, and it also stops a package with a large DTD entity
 *   (which the default rejects with a size-cap throw) from silently
 *   collapsing every signature to "none found" via the catch below.
 */
export declare function parseSignaturesFromBuffer(buffer: ArrayBuffer): Promise<ParsedSignature[]>;

export declare const PEN_WIDTH = 2.5;

/** The viewer-owned edit session identifies the part to overlay, never just a global element ID. */
declare interface PendingInlineTextEdit {
    snapshot: InlineTextEditSnapshot;
    text?: string;
    target: {
        slideId: string;
    } | {
        masterView: MasterViewTarget;
    };
}

/** Framework-neutral picture-bullet source, sizing, and accessible fallback. */
declare interface PictureBulletMarker {
    src?: string;
    sizePx: number;
    fallbackMarker: string;
    accessibleLabel: string;
    imageRelId?: string;
}

/** On-canvas picture crop mode. */
declare interface PictureCropController {
    /** Editable deck and a single croppable picture selected. */
    canCrop: ComputedRef<boolean>;
    /** Whether crop mode is active. */
    cropActive: ComputedRef<boolean>;
    /** The picture being cropped (live), or null outside crop mode. */
    cropElement: ComputedRef<PptxElement | null>;
    /** The image source the picture renders, for the overlay's ghost. */
    cropImageSrc: ComputedRef<string | undefined>;
    /** Enter crop mode on `id` (defaults to the single selected picture). */
    enterCrop: (id?: string) => void;
    /** Ribbon Crop button: enter, or commit when already cropping. */
    toggleCrop: () => void;
    /** Commit the session (one undo step when anything changed). */
    commitCrop: () => void;
    /** Cancel the session, restoring the pre-crop picture with no undo step. */
    cancelCrop: () => void;
    /** Apply a live (history-free) update to the picture being cropped. */
    applyLive: (update: CropElementUpdate) => void;
    /** Crop to Aspect Ratio, Fill and Fit (one undoable update each). */
    applyAspect: (presetId: string) => void;
    applyFill: () => void;
    applyFit: () => void;
}

/**
 * A picture element from an OOXML `<p:pic>` node with `type: "picture"`.
 *
 * Functionally identical to {@link ImagePptxElement} but distinguished by
 * the `type` discriminant for semantic clarity.
 */
declare interface PicturePptxElement extends PptxElementBase, PptxShapeProperties, PptxCustomPathProperties, PptxImageProperties, PptxAccessibilityProperties, PptxPictureNonVisualProperties {
    type: 'picture';
}

/**
 * Text styling for a single indent level (0–8) inside a placeholder’s
 * `a:lstStyle`.
 *
 * Used during placeholder inheritance to fill in defaults for font,
 * bullet, and spacing properties the slide element does not override.
 *
 * @example
 * ```ts
 * const level0: PlaceholderTextLevelStyle = {
 *   fontSize: 32,
 *   bold: true,
 *   bulletChar: "•",
 * };
 * // => satisfies PlaceholderTextLevelStyle
 * ```
 */
declare interface PlaceholderTextLevelStyle {
    fontFamily?: string;
    /**
     * The RAW `a:defRPr/a:latin/@typeface` string (verbatim: a theme alias
     * such as `+mj-lt`/`+mn-lt`, or a literal face name) {@link fontFamily}
     * was resolved from. Master/layout text styles are parsed once and
     * cached, so `fontFamily` is a resolved-for-display snapshot; re-emitting
     * it as the literal name on every save (the master-level analogue of
     * `colorChoiceXml` below) flattens the theme alias the moment ANYTHING
     * about the deck is rewritten, even when this level was never touched.
     * Absent when the level declares no `a:latin`.
     */
    fontTypefaceXml?: string;
    /**
     * Snapshot of {@link fontFamily} exactly as parsed, before any edit. The
     * save path diffs the live value against this: unchanged means re-emit
     * {@link fontTypefaceXml} verbatim (preserve the alias); different means
     * a genuine edit, so the new literal name is written instead.
     */
    resolvedFontFamily?: string;
    fontSize?: number;
    bold?: boolean;
    italic?: boolean;
    color?: string;
    /**
     * The `a:defRPr/a:solidFill` node this level's {@link color} came from.
     *
     * Master and layout text styles are parsed and cached before any slide is,
     * so a scheme alias such as `tx1` was resolved through the map that was
     * active then. A slide carrying `p:clrMapOvr` routes the same alias
     * somewhere else, so the alias has to be resolved again against the slide
     * that is inheriting it; {@link color} is only the reading taken at parse
     * time. Absent when the level declares no colour, or declares a literal one.
     */
    colorChoiceXml?: XmlObject;
    bulletChar?: string;
    bulletAutoNumType?: string;
    bulletFontFamily?: string;
    bulletSizePercent?: number;
    /** Bullet colour from `a:buClr` as hex string. */
    bulletColor?: string;
    /**
     * The colour-choice node inside `a:buClr` this level's {@link bulletColor}
     * resolved from (`a:schemeClr` / `a:sysClr` / `a:prstClr` / `a:srgbClr`,
     * transforms included), mirroring `BulletInfo.colorXml`. Re-emitted
     * verbatim on save so a themed bullet is not downgraded to a literal
     * `a:srgbClr`. Absent when the level declares no bullet colour.
     */
    bulletColorXml?: XmlObject;
    /** Bullet size in points from `a:buSzPts`. */
    bulletSizePts?: number;
    /** True when `a:buNone` is present at this level. */
    bulletNone?: boolean;
    marginLeft?: number;
    /** Paragraph right margin in px (from `@_marR` EMU). */
    marginRight?: number;
    indent?: number;
    /**
     * Paragraph alignment as a `TextStyle['align']` token (`left`, `center`,
     * `right`, `justify`, `justLow`, `dist`, `thaiDist`), never the raw OOXML
     * `@algn` value.
     */
    alignment?: string;
    /** Right-to-left paragraph direction (`@rtl`). */
    rtl?: boolean;
    /** Tab stops from `a:tabLst/a:tab` (positions in px). */
    tabStops?: TextStyle['tabStops'];
    lineSpacing?: number;
    lineSpacingExactPt?: number;
    /**
     * Space before the paragraph in px, resolved from EITHER `a:spcPts`
     * (absolute) or `a:spcPct` (a percentage of this level's own `a:defRPr`
     * font size) - the OOXML source is not distinguishable from this field
     * alone. See {@link spaceBeforePercent} / {@link resolvedSpaceBefore}.
     */
    spaceBefore?: number;
    spaceAfter?: number;
    /**
     * Snapshot of {@link spaceBefore} / {@link spaceAfter} exactly as parsed.
     * Diffed the same way as {@link resolvedFontFamily}: unchanged means the
     * writer re-emits the ORIGINAL form (`a:spcPct` when
     * {@link spaceBeforePercent} / {@link spaceAfterPercent} is set); a value
     * that has since moved away from the snapshot is a genuine edit and is
     * always written as `a:spcPts`, since an editor works in absolute units.
     */
    resolvedSpaceBefore?: number;
    resolvedSpaceAfter?: number;
    /**
     * The raw `a:spcPct` fraction (e.g. `0.2` for 20%) {@link spaceBefore} /
     * {@link spaceAfter} was resolved from, when the source used percentage
     * spacing rather than `a:spcPts`. Absent when the source used `a:spcPts`
     * (or authored no spacing at all).
     */
    spaceBeforePercent?: number;
    spaceAfterPercent?: number;
    /** Default tab interval in CSS pixels (`a:lvlXpPr/@defTabSz`). */
    defaultTabSize?: number;
    /** Whether East Asian line-breaking rules are enabled. */
    eaLineBreak?: boolean;
    /** Whether Latin line-breaking rules are enabled. */
    latinLineBreak?: boolean;
    /** Font vertical alignment within the text line. */
    fontAlignment?: string;
    /** Whether end punctuation may hang outside the text frame. */
    hangingPunctuation?: boolean;
}

/**
 * 3D scene/camera properties from `a:scene3d`.
 *
 * @example
 * ```ts
 * const scene: Pptx3DScene = {
 *   cameraPreset: "perspectiveFront",
 *   lightRigType: "threePt",
 *   lightRigDirection: "t",
 * };
 * // => satisfies Pptx3DScene
 * ```
 */
declare interface Pptx3DScene {
    /** Camera preset type, e.g. "orthographicFront", "perspectiveFront". */
    cameraPreset?: string;
    /** Camera field of view in 1/60000 degrees (`a:camera/@fov`). */
    cameraFieldOfView?: number;
    /** Camera zoom as an OOXML percentage fraction (`a:camera/@zoom`, 1 = 100%). */
    cameraZoom?: number;
    /** Camera rotation around X axis in 1/60000 degrees. */
    cameraRotX?: number;
    /** Camera rotation around Y axis in 1/60000 degrees. */
    cameraRotY?: number;
    /** Camera rotation around Z axis in 1/60000 degrees. */
    cameraRotZ?: number;
    /** Light rig type, e.g. "threePt", "balanced", "harsh". */
    lightRigType?: string;
    /** Light rig direction, e.g. "t", "b", "l", "r", "tl". */
    lightRigDirection?: string;
    /** Light-rig rotation latitude in 1/60000 degrees. */
    lightRigRotX?: number;
    /** Light-rig rotation longitude in 1/60000 degrees. */
    lightRigRotY?: number;
    /** Light-rig rotation revolution in 1/60000 degrees. */
    lightRigRotZ?: number;
    /** Whether a 3D backdrop plane is present (`a:backdrop`). */
    hasBackdrop?: boolean;
    /** Backdrop plane anchor X in EMU. */
    backdropAnchorX?: number;
    /** Backdrop plane anchor Y in EMU. */
    backdropAnchorY?: number;
    /** Backdrop plane anchor Z in EMU. */
    backdropAnchorZ?: number;
    /** Backdrop normal vector X component. */
    backdropNormalX?: number;
    /** Backdrop normal vector Y component. */
    backdropNormalY?: number;
    /** Backdrop normal vector Z component. */
    backdropNormalZ?: number;
    /** Backdrop up vector X component. */
    backdropUpX?: number;
    /** Backdrop up vector Y component. */
    backdropUpY?: number;
    /** Backdrop up vector Z component. */
    backdropUpZ?: number;
}

/**
 * 3D shape extrusion/bevel from `a:sp3d`.
 *
 * @example
 * ```ts
 * const shape3d: Pptx3DShape = {
 *   extrusionHeight: 76200,
 *   extrusionColor: "#4F81BD",
 *   presetMaterial: "metal",
 *   bevelTopType: "circle",
 *   bevelTopWidth: 12700,
 *   bevelTopHeight: 12700,
 * };
 * // => satisfies Pptx3DShape
 * ```
 */
declare interface Pptx3DShape {
    /**
     * Position of the shape along the Z axis, in EMU (`a:sp3d/@z`, default 0).
     * Independent of {@link extrusionHeight}: it moves the whole shape forward
     * or back in 3D space rather than adding depth to it, most commonly used to
     * stack several shapes at different depths under one `a:scene3d` camera.
     */
    positionZ?: number;
    /** Extrusion height in EMU. */
    extrusionHeight?: number;
    /** Extrusion colour. */
    extrusionColor?: string;
    /** Contour width in EMU. */
    contourWidth?: number;
    /** Contour colour. */
    contourColor?: string;
    /** Preset material, e.g. "matte", "warmMatte", "metal". */
    presetMaterial?: string;
    /** Top bevel type, e.g. "circle", "relaxedInset". */
    bevelTopType?: string;
    /** Top bevel width in EMU. */
    bevelTopWidth?: number;
    /** Top bevel height in EMU. */
    bevelTopHeight?: number;
    /** Bottom bevel type, e.g. "circle", "relaxedInset". */
    bevelBottomType?: string;
    /** Bottom bevel width in EMU. */
    bevelBottomWidth?: number;
    /** Bottom bevel height in EMU. */
    bevelBottomHeight?: number;
}

/**
 * Accessibility metadata from `p:cNvPr/a:extLst`'s "Mark as decorative"
 * vendor extension (issue G16). PowerPoint's Alt Text pane writes
 * `a:ext[@uri='{C183D7F6-B498-43B3-948B-1728B52AA6E4}']/adec:decorative
 * val="1"` when a shape or image is marked decorative; mixed into the
 * element variants whose `p:cNvPr` that pane covers.
 */
declare interface PptxAccessibilityProperties {
    /**
     * Whether the element is marked decorative. When true, alt text /
     * aria-label / Markdown export should skip describing the element even
     * when {@link PptxImageProperties.altText} (or similar) is present.
     */
    isDecorative?: boolean;
}

/**
 * Action types: hyperlinks, slide jumps, macros, and action buttons.
 *
 * @module pptx-types/actions
 */
/**
 * A parsed shape-level action from `a:hlinkClick` or `a:hlinkHover`.
 *
 * @example
 * ```ts
 * const link: PptxAction = {
 *   url: "https://example.com",
 *   tooltip: "Visit Example",
 *   highlightClick: true,
 * };
 *
 * const slideJump: PptxAction = {
 *   action: "ppaction://hlinksldjump",
 *   targetSlideIndex: 3,
 * };
 * // => satisfies PptxAction
 * ```
 */
declare interface PptxAction {
    /** Relationship ID referencing the action target. */
    rId?: string;
    /** OOXML action string (e.g. `ppaction://hlinksldjump`). */
    action?: string;
    /** Tooltip text shown on hover. */
    tooltip?: string;
    /** Whether the shape should highlight on click. */
    highlightClick?: boolean;
    /** Resolved URL or file path from the slide relationship map. */
    url?: string;
    /** Zero-based index into the slides array for internal slide jumps. */
    targetSlideIndex?: number;
    /** Relationship ID of an optional click sound (`a:snd/@r:embed`). */
    soundRId?: string;
    /** Resolved media target path for the optional click sound. */
    soundPath?: string;
    /**
     * `CT_Hyperlink/@endSnd` (ECMA-376 20.1.2.2.23): PowerPoint's Action
     * Settings "Stop previous sound" checkbox. Round-tripped for now (issue
     * G14); not yet wired into playback.
     */
    endSnd?: boolean;
}

/**
 * An ActiveX control reference from `p:controls / p:control`.
 *
 * ActiveX form controls (buttons, text boxes, check boxes, combo boxes, etc.)
 * are embedded via OLE parts and referenced by relationship ID in the slide XML.
 *
 * @see ECMA-376 Part 1, §19.3.1.3 (controls), §19.3.1.2 (control)
 */
declare interface PptxActiveXControl {
    /** Relationship ID referencing the ActiveX binary part. */
    relId: string;
    /** Control name from @name attribute. */
    name?: string;
    /** Shape ID this control is linked to (from @spid). */
    shapeId?: string;
    /**
     * `p:control/@showAsIcon` (CT_Control, ECMA-376 S19.3.1.2): whether the
     * control renders as its static icon rather than its live appearance.
     * `undefined` when the source authored no explicit value (schema default
     * `false`).
     */
    showAsIcon?: boolean;
    /**
     * `p:control/@imgW` in EMU (ST_PositiveCoordinate32): the width the host
     * reserves for the control's icon/preview image. Distinct from
     * {@link width}, which is the fallback `p:pic`'s own `a:ext/@cx` in px;
     * `imgW`/`imgH` are direct attributes on `p:control` itself.
     */
    imgWidthEmu?: number;
    /** `p:control/@imgH` in EMU (ST_PositiveCoordinate32). @see imgWidthEmu */
    imgHeightEmu?: number;
    /** X position (px) of the control's fallback picture, if present. */
    x?: number;
    /** Y position (px) of the control's fallback picture, if present. */
    y?: number;
    /** Width (px) of the control's fallback picture, if present. */
    width?: number;
    /** Height (px) of the control's fallback picture, if present. */
    height?: number;
    /**
     * Relationship ID of the control's static fallback picture
     * (`mc:AlternateContent > mc:Fallback > p:pic > p:blipFill > a:blip@r:embed`).
     * Renderers resolve this to an image so a control shows its last static
     * frame instead of a blank area (the live ActiveX cannot run in a viewer).
     */
    fallbackImageRelId?: string;
    /** Raw XML for round-trip preservation. */
    rawXml?: XmlObject;
}

/** Behavior after animation finishes. */
declare type PptxAfterAnimationAction = 'none' | 'hideOnNextClick' | 'hideAfterAnimation' | 'dimToColor';

/** One behaviour child of an effect, tagged by its OOXML element. */
declare type PptxAnimationBehavior = PptxSetBehavior | PptxAnimBehavior | PptxAnimEffectBehavior | PptxAnimScaleBehavior | PptxAnimRotBehavior | PptxAnimMotionBehavior;

/** Timing of one behaviour, from its own `p:cBhvr/p:cTn`. */
declare interface PptxAnimationBehaviorTiming {
    /** `p:cTn/@dur` in ms; absent when `indefinite` or unset. */
    durationMs?: number;
    /** Start offset in ms from `p:stCondLst/p:cond/@delay`, relative to the effect start. */
    delayMs?: number;
    /** `p:cTn/@accel` as a 0..1 fraction of the behaviour's duration. */
    accel?: number;
    /** `p:cTn/@decel` as a 0..1 fraction of the behaviour's duration. */
    decel?: number;
    /** `p:cTn/@autoRev`: play forward, then backward, doubling the active time. */
    autoReverse?: boolean;
    /** `p:cTn/@repeatCount` in plain iterations (OOXML stores thousandths). */
    repeatCount?: number;
    /** `p:cTn/@tmFilter`: the raw `"t,v; t,v; ..."` time remapping list. */
    tmFilter?: string;
}

/** Direction for fly-in / fly-out / wipe effects. */
declare type PptxAnimationDirection = 'fromLeft' | 'fromRight' | 'fromTop' | 'fromBottom' | 'fromTopLeft' | 'fromTopRight' | 'fromBottomLeft' | 'fromBottomRight';

/**
 * Parsed `p:animEffect/@filter` (+ `@transition`) descriptor. ECMA-376
 * describes `@filter` as a free-form string of the form `family(subtype)`,
 * optionally followed by `;`-separated fallback candidates (only the first
 * is honoured, per ECMA-376 S19.5.3's "first supported filter wins" rule).
 *
 * @example
 * ```ts
 * const f: PptxAnimationEffectFilter = { family: 'wipe', subtype: 'up', transition: 'in', raw: 'wipe(up)' };
 * ```
 */
declare interface PptxAnimationEffectFilter {
    /** Filter family name (e.g. `"wipe"`, `"barn"`, `"checkerboard"`), lowercased. */
    family: string;
    /**
     * Parenthesised subtype/direction token verbatim (e.g. `"up"`,
     * `"inVertical"`, `"across"`, `"4"`). Absent when the filter has no
     * subtype (e.g. bare `"dissolve"`).
     */
    subtype?: string;
    /**
     * `p:animEffect/@transition`: `"in"` reveals the target (the OOXML
     * default when the attribute is omitted), `"out"` conceals it, `"none"`
     * applies the filter without a visibility change (a static filter pass).
     */
    transition?: 'in' | 'out' | 'none';
    /** Raw filter string exactly as authored, for round-trip/debugging. */
    raw: string;
}

/**
 * `p:spTgt/p:graphicEl` (CT_TLGraphicalObjectBuildElement, ECMA-376 S19.5.34):
 * identifies exactly which series/category/element of a chart or diagram
 * build a per-stage effect reveals, when a deck authors one effect per stage
 * instead of a single staged `p:bldGraphic` reveal.
 */
declare interface PptxAnimationGraphicElementTarget {
    /** Which graphic kind: `p:dgm` (diagram) or `p:chart`. */
    kind: 'dgm' | 'chart';
    /** `@_seriesIdx`, 0-based series index, when the target is series-scoped. */
    seriesIdx?: number;
    /** `@_categoryIdx`, 0-based category index, when the target is category-scoped. */
    categoryIdx?: number;
    /**
     * `p:dgm/@_id` (CT_TLBuildDiagram, ECMA-376 S19.5.10): the diagram DATA MODEL
     * point id (`dgm:pt/@modelId`) this per-stage effect reveals, when a
     * `p:bldDgm` build authors one effect per node instead of a single staged
     * reveal. `dgm`-kind targets only; a `chart`-kind target never carries this.
     * Matches `PptxSmartArtNode.id` (parsed from the same `@modelId`), so a
     * diagram renderer can reveal the exact authored node.
     */
    id?: string;
    /**
     * `@_bldStep`: `ST_TLChartBuildStep` (`category` / `categoryEl` / `series` /
     * `seriesEl`) for a `chart`-kind target, or `ST_TLDiagramBuildStep`
     * (`sp` / `bg`) for a `dgm`-kind target.
     */
    bldStep?: string;
}

/** Iteration configuration from `p:iterate`. */
declare interface PptxAnimationIterate {
    /** Iteration type: el (element), lt (letter), wd (word). */
    type: 'el' | 'lt' | 'wd';
    /** Whether to iterate backwards. */
    backwards?: boolean;
    /** Timing interval (percentage of total duration, in 1000ths). */
    tmPct?: number;
    /** Absolute timing interval in ms. */
    tmAbs?: number;
}

/**
 * Single keyframe parsed from a `p:tav` element (CT_TLTimeAnimateValue).
 *
 * Each entry in a `p:tavLst` has a time fraction (`@_tm`, in 1000ths of the
 * total duration; or the literal "indefinite" / "large") and a typed value
 * child under `p:val/p:strVal|p:boolVal|p:intVal|p:fltVal|p:clrVal`.
 *
 * @see ECMA-376 §19.5.30 CT_TLAnimVariantList / §19.5.92 CT_TLTimeAnimateValue
 */
declare interface PptxAnimationKeyframe {
    /**
     * Time fraction. A finite number is the OOXML `@_tm` integer (0–100000
     * for percentage, where 100000 = 100% of duration). A string preserves
     * special tokens ("indefinite", "large").
     */
    tm: number | string;
    /** Decoded keyframe value. */
    value: string | boolean | number;
    /** Discriminant indicating which `p:val` child carried the value. */
    valueType: 'str' | 'bool' | 'int' | 'flt' | 'clr';
    /**
     * Optional formula carried on `p:tav/@_fmla`. Preserved for round-trip
     * fidelity; consumers may use it to drive computed animation values.
     */
    fmla?: string;
    /**
     * The typed theme reference when a `p:val/p:clrVal` stop is an
     * `a:schemeClr` (e.g. `accent1`), including any `tint`/`shade`/`lumMod`/
     * `lumOff`/`alpha` children. {@link value} keeps the bare scheme name for
     * round-trip; a playback consumer needs this ref (resolved against the
     * deck's theme colour map) to turn the stop into a real CSS colour, which
     * the bare name alone cannot do. Absent for an `a:srgbClr` stop, whose
     * {@link value} is already a resolved `#rrggbb` hex string.
     */
    colorRef?: PptxThemeColorRef;
}

/**
 * `p:spTgt/p:oleChartEl` (CT_TLOleChartTargetElement, ECMA-376 S19.5.44):
 * legacy pre-DrawingML OLE Graph chart sub-element targeting.
 */
declare interface PptxAnimationOleChartElementTarget {
    /** `@_type` (ST_TLOleChartSubelementType): entireChart / series / category / ... */
    subelementType: string;
    /** `@_lvl`, optional sub-element level. */
    level?: number;
}

/**
 * Built-in animation preset names used for entrance, exit, and emphasis effects.
 *
 * @example
 * ```ts
 * const preset: PptxAnimationPreset = "fadeIn";
 * // => "fadeIn" — one of: none | fadeIn | flyIn | zoomIn | fadeOut | flyOut | zoomOut | spin | pulse | ...
 * ```
 */
declare type PptxAnimationPreset = 'none' | 'appear' | 'fadeIn' | 'flyIn' | 'zoomIn' | 'bounceIn' | 'wipeIn' | 'splitIn' | 'dissolveIn' | 'wheelIn' | 'blindsIn' | 'boxIn' | 'floatIn' | 'riseUp' | 'swivel' | 'expandIn' | 'checkerboardIn' | 'flashIn' | 'peekIn' | 'randomBarsIn' | 'spinnerIn' | 'growTurnIn' | 'fadeOut' | 'flyOut' | 'zoomOut' | 'bounceOut' | 'wipeOut' | 'shrinkOut' | 'dissolveOut' | 'disappear' | 'spin' | 'pulse' | 'colorWave' | 'bounce' | 'flash' | 'growShrink' | 'teeter' | 'transparency' | 'boldFlash' | 'wave';

/** Repeat mode for animations. */
declare type PptxAnimationRepeatMode = 'untilNextClick' | 'untilEndOfSlide';

/** Sequence mode for paragraph-level animations. */
declare type PptxAnimationSequence = 'asOne' | 'byParagraph' | 'byWord' | 'byLetter';

/** A target selected by `p:tgtEl` in the PresentationML timing model. */
declare type PptxAnimationTarget = {
    type: 'shape';
    shapeId: string;
    /** Whether `p:spTgt/p:bg` limits the effect to the shape background. */
    backgroundOnly?: boolean;
    /**
     * `p:spTgt/p:subSp/@_spid`: the id of a shape NESTED inside the group
     * named by {@link shapeId} (CT_TLSubShapeId, ECMA-376 S19.5.71).
     * PowerPoint authors this when a user animates one member of a group
     * without ungrouping it: `shapeId` stays the outer group's id for
     * round-trip, but this sub-shape is the real playback target.
     */
    subShapeId?: string;
    /** `p:spTgt/p:graphicEl`: chart/diagram series/category/element target. */
    graphicElement?: PptxAnimationGraphicElementTarget;
    /** `p:spTgt/p:oleChartEl`: legacy OLE chart sub-element target. */
    oleChartElement?: PptxAnimationOleChartElementTarget;
    rawXml?: XmlObject;
} | {
    type: 'slide';
    rawXml?: XmlObject;
} | {
    type: 'sound';
    relationshipId: string;
    name?: string;
    rawXml?: XmlObject;
} | {
    type: 'ink';
    shapeId: string;
    rawXml?: XmlObject;
} | {
    type: 'unknown';
    rawXml: XmlObject;
};

/**
 * A read-only anchor representing one of the deck's own effect groups: a
 * top-level click group (`p:par` under `p:timing`'s main sequence) that this
 * app did not author, so it is never exposed as an editable
 * {@link PptxElementAnimation}.
 *
 * The authoring UI merges these anchors alongside `PptxSlide.animations` to
 * render the FULL animation sequence (editor-authored and deck-native
 * effects together) and lets an editor-authored entry be dragged to any
 * position relative to them. `order` is the anchor's position among ALL
 * top-level click groups (editor-owned and native) at load time, in the same
 * numbering space as {@link PptxElementAnimation.order}, so the two
 * populations sort into one coherent timeline.
 *
 * Anchors are never written back: on save, an untouched anchor's own click
 * group is repositioned (if an editor-authored effect was dragged past it)
 * but never mutated, so the deck's own effect stays byte-identical apart
 * from its position in the sequence.
 */
declare interface PptxAnimationTimelineAnchor {
    /**
     * Position of this group among all top-level click groups in the main
     * animation sequence at load time (dense, shared with editor entries'
     * `order`).
     */
    order: number;
    /** Shape id(s) this group's effects target, for a readable UI label. */
    targetIds: string[];
    /** Effect preset classes present in the group (entr/exit/emph/path). */
    presetClasses: Array<'entr' | 'exit' | 'emph' | 'path'>;
}

/** Animation timing curve. */
declare type PptxAnimationTimingCurve = 'ease' | 'ease-in' | 'ease-out' | 'linear';

/** Animation trigger type from OOXML `p:cTn`. */
declare type PptxAnimationTrigger = 'onClick' | 'onShapeClick' | 'onHover' | 'afterPrevious' | 'withPrevious' | 'afterDelay' |
/**
* Starts when a media element's playback reaches a named bookmark
* (PowerPoint's "Trigger > On Bookmark"). The media element is
* {@link PptxElementAnimation.triggerShapeId} and the bookmark
* {@link PptxElementAnimation.triggerBookmark}; saved as an interactive
* sequence gated on `p:cond evt="onMediaBookmark"` with a `p14:bmkTgt`.
*/
'onMediaBookmark';

/** `p:anim`: a `p:tavLst` ramp or a `from`/`to`/`by` formula ramp. */
declare interface PptxAnimBehavior extends BehaviorBase {
    kind: 'anim';
    calcMode?: 'discrete' | 'lin' | 'fmla';
    valueType?: string;
    from?: string;
    to?: string;
    by?: string;
    keyframes: PptxAnimationKeyframe[];
}

/** `p:animEffect`: a filter transition (`fade`, `wipe(down)`...). */
declare interface PptxAnimEffectBehavior extends BehaviorBase {
    kind: 'animEffect';
    filter?: string;
    transition?: 'in' | 'out' | 'none';
}

/** `p:animMotion`: a path (slide fractions) or a `from`/`to`/`by` offset. */
declare interface PptxAnimMotionBehavior extends BehaviorBase {
    kind: 'animMotion';
    path?: string;
    origin?: string;
    from?: PptxBehaviorPoint;
    to?: PptxBehaviorPoint;
    by?: PptxBehaviorPoint;
}

/** `p:animRot`: rotation in degrees (OOXML stores 60000ths). */
declare interface PptxAnimRotBehavior extends BehaviorBase {
    kind: 'animRot';
    from?: number;
    to?: number;
    by?: number;
}

/** `p:animScale`: scale factors as fractions (OOXML stores percent*1000, so `100000` = 1). */
declare interface PptxAnimScaleBehavior extends BehaviorBase {
    kind: 'animScale';
    from?: PptxBehaviorPoint;
    to?: PptxBehaviorPoint;
    by?: PptxBehaviorPoint;
    zoomContents?: boolean;
}

/**
 * Extended (application) properties from `docProps/app.xml`.
 *
 * @example
 * ```ts
 * const app: PptxAppProperties = {
 *   application: "Microsoft Office PowerPoint",
 *   appVersion: "16.0000",
 *   slides: 24,
 *   words: 1500,
 *   company: "Acme Corp",
 * };
 * // => satisfies PptxAppProperties
 * ```
 */
declare interface PptxAppProperties {
    /** Application name (e.g. "Microsoft Office PowerPoint"). */
    application?: string;
    /** Application version string. */
    appVersion?: string;
    /** Presentation format (e.g. "On-screen Show (16:9)"). */
    presentationFormat?: string;
    /** Total number of slides. */
    slides?: number;
    /** Number of hidden slides. */
    hiddenSlides?: number;
    /** Number of notes slides. */
    notes?: number;
    /** Total editing time in minutes. */
    totalTime?: number;
    /** Number of words. */
    words?: number;
    /** Number of paragraphs. */
    paragraphs?: number;
    /** Company name. */
    company?: string;
    /** Manager name. */
    manager?: string;
    /** Template name. */
    template?: string;
    /** Hyperlink base URL. */
    hyperlinkBase?: string;
    /** Document security bitmask (`<DocSecurity>`). */
    docSecurity?: number;
    /** Number of multimedia clips (`<MMClips>`). */
    mmClips?: number;
    /** Whether thumbnail images were scaled to fit (`<ScaleCrop>`). */
    scaleCrop?: boolean;
    /** Whether hyperlinks are current (`<LinksUpToDate>`). */
    linksUpToDate?: boolean;
    /** Whether the document is shared (`<SharedDoc>`). */
    sharedDoc?: boolean;
    /** Whether hyperlinks changed since last save (`<HyperlinksChanged>`). */
    hyperlinksChanged?: boolean;
}

/** One generic `p:anim` behaviour inside a composed PowerPoint effect. */
declare interface PptxAttributeAnimation {
    /** Lowercased target attribute from `p:attrNameLst`. */
    attrName: string;
    /**
     * Authored value stops from this behaviour's `p:tavLst`. Empty when the
     * behaviour instead uses the simpler `from`/`to`/`by` attribute form (see
     * below); at least one of `keyframes`, `from`/`to`, or `by` is present.
     */
    keyframes: PptxAnimationKeyframe[];
    /**
     * `p:anim/@_from` (a formula string, ECMA-376 S19.5.4 CT_TLAnimateBehavior):
     * the absolute starting value, used instead of `p:tavLst` when the
     * behaviour only has two endpoints. PowerPoint writes this form for some
     * built-in presets (e.g. "Grow And Turn"'s `ppt_x` fly-in): a bare
     * `p:anim from="..." to="..."` with no `p:tavLst` child at all. See
     * `animation-ppt-formula-ground-truth.md` in `pptx-viewer-shared` for the
     * real-PowerPoint sample this was found in.
     */
    from?: string;
    /** `p:anim/@_to`: the absolute ending value. See {@link from}. */
    to?: string;
    /**
     * `p:anim/@_by`: a DELTA formula added to wherever the attribute already
     * stands (as opposed to `from`/`to`'s absolute values), typically paired
     * with `p:cBhvr/@_additive="sum"` so it composites with a sibling
     * behaviour driving the same attribute instead of replacing it.
     */
    by?: string;
    /** Duration from this behaviour's nested `p:cTn/@dur`. */
    durationMs?: number;
    /** Start offset from this behaviour's nested `p:stCondLst`. */
    delayMs?: number;
    /**
     * Interpolation mode from this behaviour's own `@_calcmode`
     * (ST_TLAnimateBehaviorCalcMode, ECMA-376 S19.5.2): `discrete` snaps to
     * each `p:tav` stop with no interpolation, `lin` (the OOXML default)
     * interpolates linearly. `fmla` as the WHOLE behaviour's calc mode has
     * never been observed in a real PowerPoint file and is not consulted at
     * playback; what PowerPoint actually writes is `calcmode="lin"` with a
     * per-stop `p:tav/@fmla` (see {@link PptxAnimationKeyframe.fmla}), which
     * IS consulted regardless of this field's value. Absent means `lin`.
     */
    calcMode?: 'discrete' | 'lin' | 'fmla';
    /**
     * `p:anim/@_p14:bounceEnd` (Office 2010 `p14` extension attribute,
     * MS-OI29500), normalized to a 0-1 fraction of this behaviour's own
     * duration. PowerPoint's "Bounce End" effect option (COM:
     * `Effect.Timing.BounceEnd` + `BounceEndIntensity`) writes this on the
     * position-ramp `p:anim` node(s): the share of the duration spent
     * BOUNCING at the end. Measured from PowerPoint's own CreateVideo frames,
     * the travel completes at `1 - bounceEnd` and the rest is a damped
     * oscillation about the final value (see shared's `animation-bounce-end`).
     * Mirrored verbatim by PowerPoint onto the enclosing
     * `p:cTn/@_p14:presetBounceEnd`. Absent for every animation that doesn't
     * use this effect option (the overwhelming majority).
     */
    bounceEnd?: number;
}

declare interface PptxAudioCdPosition {
    track: number;
    time?: number;
    /** Original `st` or `end` node, retained for lossless edits. */
    rawXml?: XmlObject;
}

declare interface PptxBackgroundRemoval {
    /** Top edge of the retained rectangle (0..1 fraction of the image height). */
    top: number;
    /** Bottom edge of the retained rectangle (0..1 fraction of the image height). */
    bottom: number;
    /** Left edge of the retained rectangle (0..1 fraction of the image width). */
    left: number;
    /** Right edge of the retained rectangle (0..1 fraction of the image width). */
    right: number;
    /** Strokes marking regions the user forced to be foreground. */
    foregroundMarks?: PptxBackgroundRemovalMark[];
    /** Strokes marking regions the user forced to be background. */
    backgroundMarks?: PptxBackgroundRemovalMark[];
    /** Original effect XML, retained for lossless re-emission. */
    rawXml?: XmlObject;
}

/**
 * Image recolour/adjustment properties parsed from blip extensions.
 *
 * These effects are stored in the OpenXML `<a:blip>` extension list
 * and applied non-destructively to the original image data.
 *
 * @example
 * ```ts
 * const fx: PptxImageEffects = {
 *   brightness: 20,
 *   contrast: -10,
 *   grayscale: true,
 * };
 * // => { brightness: 20, contrast: -10, grayscale: true } satisfies PptxImageEffects
 * ```
 */
/**
 * One `a14:foregroundMark` / `a14:backgroundMark` polyline hint recorded while
 * the user painted over the picture in PowerPoint's "Remove Background" mode.
 * Coordinates are 0..1 fractions of the image.
 */
declare interface PptxBackgroundRemovalMark {
    x1: number;
    y1: number;
    x2: number;
    y2: number;
}

/**
 * 3-D bar/column shape (OOXML `ST_Shape`, `c:bar3DChart/c:shape/@val` or a
 * per-series `c:ser/c:shape` override). `coneToMax` / `pyramidToMax` scale
 * the cone/pyramid so it reaches full height at the value axis maximum,
 * appearing truncated below it; the plain `cone`/`pyramid` always come to a
 * full point at the bar's own value.
 *
 * @example
 * ```ts
 * const shape: PptxBar3DShape = "cylinder";
 * // => "cylinder", one of: "box" | "cone" | "coneToMax" | "cylinder" | "pyramid" | "pyramidToMax"
 * ```
 */
declare type PptxBar3DShape = 'box' | 'cone' | 'coneToMax' | 'cylinder' | 'pyramid' | 'pyramidToMax';

/** A `p:animScale` factor pair (1 = unscaled) or a `p:animMotion` offset (slide fractions). */
declare interface PptxBehaviorPoint {
    x: number;
    y: number;
}

/** Classic `c:bubbleChart` options from CT_BubbleChart. */
declare interface PptxBubbleChartOptions {
    bubble3D?: boolean;
    /** Bubble diameter scale in percent, constrained to 0 through 300. */
    bubbleScale?: number;
    showNegativeBubbles?: boolean;
    sizeRepresents?: 'area' | 'w';
}

/** 3D wall or floor element formatting. */
declare interface PptxChart3DSurface {
    thickness?: number;
    spPr?: PptxChartShapeProps;
}

/** Axis formatting for category, value, or date axes. */
declare interface PptxChartAxisFormatting extends PptxChartAxisLabelFormatting {
    axisType: 'catAx' | 'valAx' | 'dateAx' | 'serAx';
    /** Axis position: "b" (bottom), "l" (left), "r" (right), "t" (top). */
    axPos?: 'b' | 'l' | 'r' | 't';
    /** Unique axis identifier (c:axId/@val) used to link series to axes. */
    axisId?: number;
    /** Cross-axis identifier: the axis this axis crosses. */
    crossAxisId?: number;
    /** Automatic crossing mode (`c:crosses`). Mutually exclusive with `crossesAt`. */
    crosses?: 'autoZero' | 'min' | 'max';
    /** Explicit crossing value (`c:crossesAt`). Units depend on the axis type. */
    crossesAt?: number;
    /** Whether a value axis crosses between or at category tick marks. */
    crossBetween?: 'between' | 'midCat';
    numFmt?: PptxChartAxisNumFmt;
    titleText?: string;
    spPr?: PptxChartShapeProps;
    fontFamily?: string;
    fontSize?: number;
    fontBold?: boolean;
    fontColor?: string;
    /** Whether major gridlines are present (`c:majorGridlines`). */
    majorGridlines?: boolean;
    /** Whether minor gridlines are present (`c:minorGridlines`). */
    minorGridlines?: boolean;
    majorGridlinesSpPr?: PptxChartShapeProps;
    minorGridlinesSpPr?: PptxChartShapeProps;
    /** Minimum axis value override (c:min/@val). */
    min?: number;
    /** Maximum axis value override (c:max/@val). */
    max?: number;
    /** Axis value direction (`c:scaling/c:orientation/@val`). */
    orientation?: 'minMax' | 'maxMin';
    /** Whether the axis is deleted/hidden (c:delete/@val). */
    deleted?: boolean;
    /**
     * Display units for value axis (c:dispUnits/c:builtInUnit/@val).
     * When set to 'custom', the actual divisor is in {@link displayUnitsValue}.
     */
    displayUnits?: 'hundreds' | 'thousands' | 'tenThousands' | 'hundredThousands' | 'millions' | 'tenMillions' | 'hundredMillions' | 'billions' | 'trillions' | 'custom';
    /** Custom display unit divisor value (c:dispUnits/c:custUnit/@val). Only used when displayUnits is 'custom'. */
    displayUnitsValue?: number;
    /**
     * Display-unit label contents (`c:dispUnits/c:dispUnitsLbl`). A string is
     * retained as a compatibility shorthand for `{ text: string }`; `null`
     * explicitly removes the label.
     */
    displayUnitsLabel?: string | PptxChartDisplayUnitsLabel | null;
    /** Whether logarithmic scaling is enabled (presence of c:scaling/c:logBase). */
    logScale?: boolean;
    /** Logarithmic base value (c:scaling/c:logBase/@val), typically 10 or e. */
    logBase?: number;
    /** Major-unit interval between primary tick marks (c:majorUnit/@val). */
    majorUnit?: number;
    /** Minor-unit interval between secondary tick marks (c:minorUnit/@val). */
    minorUnit?: number;
    /** Calendar unit used to interpret date-axis serial values. */
    baseTimeUnit?: 'days' | 'months' | 'years';
    majorTimeUnit?: 'days' | 'months' | 'years';
    minorTimeUnit?: 'days' | 'months' | 'years';
}

/** Typed axis tick and category/date label controls. */
declare interface PptxChartAxisLabelFormatting {
    /** Primary and secondary tick-mark placement. */
    majorTickMark?: PptxChartTickMark;
    minorTickMark?: PptxChartTickMark;
    /** Tick-label position from ChartML `ST_TickLblPos`. */
    tickLblPos?: 'high' | 'low' | 'nextTo' | 'none';
    /** Automatic category/date axis behavior (`c:auto`). */
    auto?: boolean;
    /** Category-axis label alignment (`c:lblAlgn`). */
    labelAlignment?: 'ctr' | 'l' | 'r';
    /** Category/date label distance, from 0 through 1000 percent. */
    labelOffset?: number;
    /** Number of category/date labels between rendered labels. */
    tickLabelSkip?: number;
    /** Number of category/date tick positions between major tick marks. */
    tickMarkSkip?: number;
    /** Suppress multi-level category labels (`c:noMultiLvlLbl`). */
    noMultiLevelLabels?: boolean;
}

/** Axis number format. */
declare interface PptxChartAxisNumFmt {
    formatCode: string;
    sourceLinked?: boolean;
}

/**
 * One colour band for a surface chart (`c:bandFmts/c:bandFmt`,
 * ECMA-376 §21.2.2.19 / CT_BandFmt). `index` is the band's position
 * (`c:idx/@val`) among the value axis's major-unit bands, in authored order.
 */
declare interface PptxChartBandFmt {
    index: number;
    spPr?: PptxChartShapeProps;
}

/**
 * Bar series direction (OOXML `ST_BarDir`): `"col"` is a vertical column
 * chart, `"bar"` a horizontal bar chart.
 *
 * @example
 * ```ts
 * const dir: PptxChartBarDirection = "col";
 * // => "col" - one of: "col" | "bar"
 * ```
 */
declare type PptxChartBarDirection = 'col' | 'bar';

/** Office 2016 ChartEx box-and-whisker series layout options. */
declare interface PptxChartBoxWhiskerOptions {
    quartileMethod?: 'inclusive' | 'exclusive';
    showMeanLine?: boolean;
    showMeanMarker?: boolean;
    /** Show non-outlier (inner) data points. */
    showInnerPoints?: boolean;
    showOutlierPoints?: boolean;
}

/**
 * Chart "chrome" flags from `c:chart` that round-trip cleanly even when
 * rendering ignores them.
 *
 * - {@link autoTitleDeleted}: `c:autoTitleDeleted/@val`. Suppresses the
 *   auto-generated title for single-series charts.
 * - {@link dispBlanksAs}: `c:dispBlanksAs/@val`. How blank cells
 *   render: `"gap"`, `"zero"`, or `"span"`.
 * - {@link showDLblsOverMax}: `c:showDLblsOverMax/@val`. Keeps data
 *   labels visible for points exceeding the value-axis maximum.
 * - {@link dispNaAsBlank}: the Office 2017+ chart extension
 *   `c:extLst/c:ext/c16r3:dataDisplayOptions16/c16r3:dispNaAsBlank/@val`
 *   (uri `{56B9EC1D-385E-4148-901F-78D8002777C0}`), PowerPoint's "Show #N/A
 *   as an empty cell" chart option. Confirmed against real corpus markup
 *   (`e2e/fixtures/chart-data-fidelity.pptx`).
 *
 * `c:plotVisOnly` lives on {@link PptxChartData.plotVisibleOnly} and is
 * intentionally not duplicated here.
 */
declare interface PptxChartChrome {
    autoTitleDeleted?: boolean;
    dispBlanksAs?: 'gap' | 'zero' | 'span';
    showDLblsOverMax?: boolean;
    dispNaAsBlank?: boolean;
}

/**
 * Complete parsed chart data for a {@link ChartPptxElement}.
 *
 * @example
 * ```ts
 * const chart: PptxChartData = {
 *   title: "Q4 Sales",
 *   chartType: "bar",
 *   categories: ["Jan", "Feb", "Mar"],
 *   series: [
 *     { name: "Revenue", values: [100, 120, 140] },
 *   ],
 *   grouping: "clustered",
 *   style: { hasLegend: true, legendPosition: "b" },
 * };
 * // => satisfies PptxChartData
 * ```
 */
declare interface PptxChartData {
    title?: string;
    /**
     * Rich-text runs of the title, parsed from `c:title/c:tx/c:rich` (issue:
     * chart title rich text). Lossless multi-run alternative to the flat
     * {@link title}: when present, the writer serialises every run's own
     * bold/italic/size/color; when absent, save falls back to the flat
     * `title` path as before. Only populated for a classic (`c:`) chart's
     * rich (typed) title, not a ChartEx (`cx:`) title or one authored as a
     * linked-cell reference.
     */
    titleRuns?: PptxChartTitleRun[];
    chartType: PptxChartType;
    categories: string[];
    /**
     * Hierarchical category levels in source XML order, for both ChartEx
     * hierarchy charts (`cx:multiLvlStrRef`) and classic multi-level category
     * axes (`c:cat/c:multiLvlStrRef`, e.g. a PowerPoint Quarter > Month
     * grouping). Level 0 contains the leaf labels and remains mirrored by
     * {@link categories} for consumers that only understand a flat category
     * axis. Parent (grouping) levels are forward-filled: a blank cache slot
     * continues the previous group's label, matching how the source stores a
     * merged category header sparsely.
     */
    categoryLevels?: string[][];
    dateCategories?: PptxChartDateCategories;
    series: PptxChartSeries[];
    /**
     * Series hidden from the plot by PowerPoint's "Chart Filters" feature
     * (Series tab) but still present in the workbook, aggregated across every
     * chart-type container (combo charts can carry more than one). Absent
     * when the chart has no such extension. See {@link PptxChartFilteredSeries}.
     */
    filteredSeries?: PptxChartFilteredSeries[];
    /**
     * `c15:filteredSeriesTitle`: the auto-generated series title text (e.g.
     * "Series 3") PowerPoint preserved when the chart filter hid the series
     * whose data would otherwise have supplied it. See
     * `utils/chart-ext-titles.ts`. Read-mostly like {@link filteredSeries}.
     */
    filteredSeriesTitle?: string;
    /**
     * `c15:filteredCategoryTitle`: the auto-numbered category labels ("1",
     * "2", "3", ...) PowerPoint preserved when the chart filter hid the
     * category axis source entirely. See `utils/chart-ext-titles.ts`.
     */
    filteredCategoryTitle?: string[];
    /** Chart style/formatting metadata. */
    style?: PptxChartStyle;
    /** Grouping mode for bar/area/line charts: 'clustered' | 'stacked' | 'percentStacked' */
    grouping?: 'clustered' | 'stacked' | 'percentStacked';
    /**
     * The source `c:grouping` was `standard`, which {@link grouping} folds into
     * `'clustered'` (a 2D bar chart draws the two the same). A 3D chart draws
     * `standard` differently: each series on its own depth row. The writer
     * emits `standard` again while `grouping` is still `'clustered'`, so the
     * chart round-trips unchanged.
     */
    groupingStandard?: boolean;
    /**
     * Whether the first (or only) series varies its point colours
     * (`c:varyColors/@val`). Pie/doughnut default this on; single-series
     * bar/column honour it by giving each point a distinct palette colour.
     * Absent when the source XML omits `c:varyColors`.
     */
    varyColors?: boolean;
    /**
     * Pie/doughnut start angle in degrees clockwise from 12 o'clock
     * (`c:firstSliceAng/@val`, 0 through 360). Absent uses the default 0.
     */
    firstSliceAngle?: number;
    /**
     * Doughnut hole diameter as a percentage of the outer diameter
     * (`c:holeSize/@val`, 10 through 90). Absent uses the renderer default.
     */
    doughnutHoleSize?: number;
    /**
     * Bar series direction (`c:barDir/@val`): `"col"` draws vertical columns,
     * `"bar"` draws horizontal bars. Absent means `"col"` (PowerPoint's own
     * default), so only horizontal bar charts need to carry the field.
     */
    barDirection?: PptxChartBarDirection;
    /**
     * 3-D bar/column shape (`c:bar3DChart/c:shape/@val`). Bar3D only; a plain
     * bar chart has no `c:shape` element. A per-series `c:ser/c:shape`
     * ({@link PptxChartSeries.shape}) overrides this for that series.
     */
    barShape?: PptxBar3DShape;
    /**
     * Radar chart drawing style (`c:radarChart/c:radarStyle/@val`). `standard`
     * draws an outline only, `marker` adds markers at each vertex (PowerPoint's
     * own default for every radar chart it authors), and `filled` paints the
     * enclosed polygon with the series fill and omits markers. Radar only.
     */
    radarStyle?: 'standard' | 'marker' | 'filled';
    /**
     * Whether a surface chart renders as a wireframe grid rather than a solid
     * coloured surface (`c:surfaceChart/c:wireframe/@val` or
     * `c:surface3DChart/c:wireframe/@val`, both modeled as chart type
     * `"surface"`). A `CT_Boolean` element: absent from the source XML
     * defaults to `true` per schema, so `undefined` here means "not present in
     * the source" and callers should treat it as `true`. Surface only.
     */
    wireframe?: boolean;
    /**
     * Whether the surface chart is the 2-D "top view" projection
     * (`c:surfaceChart`, PowerPoint's "Contour" / "Wireframe Contour" types)
     * rather than the 3-D isometric one (`c:surface3DChart`, "3-D Surface" /
     * "3-D Surface (Wireframe)"). Both element names map to chart type
     * `"surface"`; this bit is the only thing that tells the renderer which
     * of the two projections PowerPoint actually drew, since a top-view
     * surface has no Z-axis at all (only category and series axes) while the
     * 3-D one draws all three. Surface only; `undefined` for every other
     * chart type.
     */
    surfaceTopView?: boolean;
    /**
     * Scatter presentation mode (`c:scatterChart/c:scatterStyle/@val`).
     *
     * `lineMarker` (PowerPoint's own default for every scatter it writes) and
     * `smoothMarker` draw a connecting line; `marker` and `none` do not. Whether
     * the MARKERS appear is decided separately by `c:marker/c:symbol`, and
     * whether the LINE appears is further gated by
     * {@link PptxChartSeries.lineNoFill} - PowerPoint expresses "markers only" as
     * `lineMarker` plus an `a:ln/a:noFill`, not as `marker`.
     */
    scatterStyle?: PptxChartScatterStyle;
    /**
     * Bar/column gap between category clusters as a percentage of bar width
     * (`c:gapWidth/@val`, 0 through 500). Absent uses the renderer default.
     */
    barGapWidth?: number;
    /**
     * Clustered bar/column overlap between series within a category as a
     * percentage (`c:overlap/@val`, -100 through 100). Absent uses 0.
     */
    barOverlap?: number;
    /** Internal: path to the chart XML part in the PPTX archive (for round-trip save). */
    chartPartPath?: string;
    /** Internal: relationship ID linking the graphic frame to the chart part. */
    chartRelationshipId?: string;
    /** `null` explicitly removes an existing ChartML data table. */
    dataTable?: PptxChartDataTable | null;
    /** `null` explicitly removes an existing `c:dropLines` element. */
    dropLines?: PptxChartLineStyle | null;
    /** `null` explicitly removes an existing `c:hiLowLines` element. */
    hiLowLines?: PptxChartLineStyle | null;
    /** `null` explicitly removes an existing up/down-bars container. */
    upDownBars?: PptxChartUpDownBars | null;
    axes?: PptxChartAxisFormatting[];
    floor?: PptxChart3DSurface;
    sideWall?: PptxChart3DSurface;
    backWall?: PptxChart3DSurface;
    /** Per-band surface-chart colour overrides (`c:surfaceChart/c:bandFmts`). */
    bandFmts?: PptxChartBandFmt[];
    /** External data source reference (c:externalData) linking to an external workbook. */
    externalData?: PptxExternalData;
    /**
     * Parsed data from the embedded xlsx workbook (from ppt/embeddings/).
     *
     * When a chart references an embedded Excel workbook via `c:externalData`,
     * the xlsx is parsed to extract categories and series. This data serves as
     * a fallback when the chart XML's cached series data is empty or incomplete.
     */
    embeddedWorkbookData?: PptxEmbeddedWorkbookData;
    /**
     * Pivot table data source reference (c:pivotSource).
     *
     * When present, the chart's data originates from a PivotTable.
     * The chart still renders using its cached series data; this field
     * is metadata about the data origin, preserved for round-trip fidelity.
     */
    pivotSource?: PptxChartPivotSource | null;
    /**
     * Whether only visible cells are plotted (c:plotVisOnly).
     * When `true` (the default), hidden cells are excluded from the chart.
     * When `false`, hidden data IS plotted.
     */
    plotVisibleOnly?: boolean;
    /**
     * Color palette extracted from the chart's Office 2013+ color style part
     * (`chartColorStyle*.xml`). When present, this palette takes priority over
     * the `c:style/@val`-derived palette in `getChartStylePalette`.
     *
     * Each entry is a resolved hex colour string (e.g. `"#4472C4"`).
     */
    colorPalette?: string[];
    /**
     * Color cycling method from the chart color style part's `meth` attribute.
     *
     * - `"cycle"`: repeat the palette colours in order (default)
     * - `"withinLinear"`: gradient within each series
     * - `"acrossLinear"`: gradient across series
     */
    colorMethod?: 'cycle' | 'withinLinear' | 'acrossLinear';
    /** Internal source color-style part path used for lossless dirty saves. */
    colorStylePartPath?: string;
    /** Internal parsed palette snapshot used to detect actual edits. */
    colorStyleOriginalPalette?: string[];
    /** Internal parsed method snapshot used to detect actual edits. */
    colorStyleOriginalMethod?: 'cycle' | 'withinLinear' | 'acrossLinear';
    /**
     * Pie-of-pie / Bar-of-pie options (`c:ofPieChart`, CT_OfPieChart).
     *
     * Present only when {@link chartType} is `"ofPie"`. Carries the split
     * configuration, secondary plot size, and serLines flag so that an
     * `ofPieChart` element can be re-emitted on save with full fidelity.
     */
    ofPieOptions?: PptxChartOfPieOptions;
    /** Classic bubble-chart display options (`c:bubbleChart`). */
    bubbleOptions?: PptxBubbleChartOptions;
    /**
     * 3D viewing parameters (`c:view3D`, CT_View3D).
     *
     * Parsed from and emitted to `c:chart/c:view3D`. Absent when the
     * chart XML has no `c:view3D` element.
     */
    view3D?: PptxChartView3D;
    /**
     * Top-level chart chrome flags (`c:autoTitleDeleted`,
     * `c:dispBlanksAs`, `c:showDLblsOverMax`).
     *
     * Each flag is omitted from the emitted XML when absent on the
     * source data, so absence does not produce empty `<c:…/>` placeholders.
     */
    chartChrome?: PptxChartChrome;
    /** `c:chartSpace/c:printSettings`; `null` removes the container on save. */
    printSettings?: PptxChartPrintSettings | null;
    /** `c:chartSpace/c:protection`; `null` removes the container on save. */
    protection?: PptxChartProtection | null;
    /** Editable manual placement for the title, plot area, and legend. */
    layouts?: PptxChartLayouts;
    /**
     * Raw `c:userShapes` XML subtree (a drawing tree) preserved verbatim.
     *
     * `c:userShapes` references a separate drawing part containing
     * shapes drawn over the chart. The reference is preserved as-is so
     * that round-trip save re-emits the original element without
     * attempting to parse the nested drawing tree.
     */
    userShapesXml?: unknown;
    /**
     * Parsed, renderable drawing-overlay shapes resolved from the separate
     * drawing part referenced by `c:userShapes/@r:id`
     * (`ppt/drawings/drawingN.xml`). Each entry carries chart-relative anchor
     * geometry plus light shape/text formatting so the viewer can render an
     * overlay on top of the chart plot. Render-only: {@link userShapesXml}
     * remains the source of truth for round-trip save.
     */
    userShapes?: PptxChartUserShape[];
    /**
     * Raw `c:pivotFmts` XML subtree preserved verbatim.
     *
     * `c:pivotFmts` carries a list of `c:pivotFmt` formatting overrides
     * for charts whose data originates from a PivotTable. Preserved
     * verbatim for round-trip fidelity.
     */
    /** Typed pivot-chart format persistence; `null` removes `c:pivotFmts`. */
    pivotFormats?: PptxChartPivotFormats | null;
    /**
     * Color-map override (`c:clrMapOvr`) carrying 12 attributes that
     * remap theme colour roles for this chart only. Modeled as a flat
     * `attribute -> value` map (e.g. `{ bg1: 'lt1', accent1: 'accent2' }`)
     * so unknown/future attributes round-trip without code changes.
     * `null` explicitly removes an existing `c:clrMapOvr`; an empty object
     * is treated the same as `null` on save.
     */
    clrMapOvr?: Record<string, string> | null;
    /**
     * Whether the chart's own cached numeric values use the 1904 date epoch
     * (`c:chartSpace/c:date1904/@val`). Independent of, and authoritative over,
     * any embedded workbook's `workbookPr/@date1904` (a chart can lack an
     * embedded workbook entirely, or its cache can legitimately differ from the
     * workbook's current setting). Absent when the source XML omits the
     * element, in which case the 1900 system applies (the schema default).
     */
    date1904?: boolean;
    /**
     * PowerPoint's "Rounded corners" chart-area option
     * (`c:chartSpace/c:roundedCorners/@val`, default `false`). Absent when the
     * source XML omits the element.
     */
    roundedCorners?: boolean;
    /**
     * 3-D chart depth/spacing along the series axis, as a percentage
     * (`c:gapDepth/@val`, `ST_GapAmount`, 0 through 500). Legal on
     * `bar3D`/`area3D`/`line3D`/`surface` chart-type containers only. Read-only
     * for rendering, matching {@link barGapWidth}/{@link barOverlap}: save
     * round-trips it via the preserved chart XML rather than a typed edit path.
     */
    gapDepth?: number;
    /**
     * Parsed Office 2013+ chart-style part (`ppt/charts/style#.xml`,
     * `cs:chartStyle`), providing per-element font/line/fill defaults for
     * whichever built-in "Chart Styles" gallery entry ({@link PptxChartStyle.styleId})
     * is active. Absent when the chart has no such part (common for
     * automation-authored charts, where PowerPoint still implies style 2's
     * look via its own bundled defaults).
     */
    chartStyleDefinition?: PptxChartStyleDefinition;
}

/** Individual data label override (c:dLbl). */
declare interface PptxChartDataLabel {
    idx: number;
    /** Suppress this data point's automatically generated label. */
    deleted?: boolean;
    showVal?: boolean;
    showCatName?: boolean;
    showSerName?: boolean;
    showPercent?: boolean;
    showLegendKey?: boolean;
    showBubbleSize?: boolean;
    position?: PptxChartDataLabelPosition;
    text?: string;
    separator?: string;
    showLeaderLines?: boolean;
    /**
     * Per-label number-format override (`c:dLbl/c:numFmt/@formatCode`), taking
     * precedence over the chart-level {@link PptxChartDataLabelOptions.numberFormat}
     * and the series' own {@link PptxChartSeries.numberFormat} when set.
     */
    numberFormat?: string;
    /**
     * Manually dragged label position (`c:dLbl/c:layout/c:manualLayout`), the
     * same CT_ManualLayout shape used for title/legend/plotArea. `null`
     * explicitly clears a drag back to the automatic position.
     */
    layout?: PptxChartManualLayout | null;
    /**
     * This label's own font (`c:dLbl/c:txPr/a:p/a:pPr/a:defRPr`, or ChartEx
     * `cx:dataLabel/cx:txPr`), taking precedence over the chart/series-level
     * {@link PptxChartDataLabelOptions.txPr} when set. Reuses the legend
     * entry's flat text-style shape since both are the same
     * `.../a:p/a:pPr/a:defRPr` default-run-property style.
     */
    txPr?: PptxChartLegendTextStyle;
    /**
     * This label's own shape formatting (`c:dLbl/c:spPr`): fill/line colour,
     * width, and dash style for the label's callout box, taking precedence
     * over any chart/series-level default when set.
     */
    spPr?: PptxChartShapeProps;
    /**
     * `c15:xForSave`: this override exists only so its properties survive a
     * save/reload round trip; PowerPoint merges it back onto the series'
     * default label on load. Round-tripped as-is (an edited chart keeps an
     * existing point's whole `extLst`, this flag included); introspection
     * only otherwise. See `utils/chart-data-labels-range.ts`.
     */
    savedForCompatibilityOnly?: boolean;
}

/**
 * Chart-level data-label options (`c:dLbls` directly under a chart-type
 * container, applying to every series). Mirrors the OOXML `c:show*` flags
 * and `c:dLblPos`.
 */
declare interface PptxChartDataLabelOptions {
    /** Label box fill/outline (`c:dLbls/c:spPr`), see `chart-data-label-box.ts`. */
    labelShape?: PptxChartShapeProps;
    /** Callout geometry of the label box (`c15:spPr/a:prstGeom/@prst`, e.g. `wedgeRectCallout`). */
    calloutShape?: string;
    /** The chart15 extension's `c15:showLeaderLines`, which wins for a moved label's leader line. */
    extLeaderLines?: boolean;
    /** Show the numeric value (`c:showVal`). */
    showValue?: boolean;
    /** Show the category name (`c:showCatName`). */
    showCategory?: boolean;
    /** Show the series name (`c:showSerName`). */
    showSeriesName?: boolean;
    /** Show the percentage (`c:showPercent`, pie/doughnut). */
    showPercent?: boolean;
    /** Show the legend key swatch (`c:showLegendKey`). */
    showLegendKey?: boolean;
    /** Show bubble size (`c:showBubbleSize`). */
    showBubbleSize?: boolean;
    /** Text placed between combined label components (`c:separator`). */
    separator?: string;
    /** Show leader lines where supported (`c:showLeaderLines`). */
    showLeaderLines?: boolean;
    /**
     * Leader-line stroke styling for offset (pie/doughnut `outEnd`/`bestFit`)
     * labels. Resolved from the base `c:leaderLines/c:spPr` when present, else
     * falling back to the Office 2013+ chart15 extension's mirror
     * (`c:extLst/c:ext/c15:leaderLines/c:spPr`, uri
     * `{CE6537A1-D6FC-4f65-9D91-7224C49458BB}`), which is the one PowerPoint
     * itself treats as authoritative when both are present. Confirmed against
     * `e2e/fixtures/issue-132-gradient-fill.pptx` and
     * `e2e/fixtures/issue-132-hr-deck.pptx`, both of which write only the
     * extension form. `undefined` leaves the renderer's own default leader-line
     * stroke.
     */
    leaderLineStyle?: PptxChartShapeProps;
    /**
     * Label position (`c:dLblPos`). Valid values depend on the chart type
     * (`ctr`, `inEnd`, `inBase`, `outEnd`, `bestFit`, `l`, `r`, `t`, `b`).
     * Omit to let PowerPoint use the type default.
     */
    position?: PptxChartDataLabelPosition;
    /**
     * Chart-level number-format override (`c:dLbls/c:numFmt/@formatCode`),
     * applied to every label of the series/chart-type unless a per-point
     * {@link PptxChartDataLabel.numberFormat} overrides it.
     */
    numberFormat?: string;
    /**
     * Default font for every label at this level (`c:dLbls/c:txPr`, or
     * ChartEx `cx:dataLabels/cx:txPr`), overridden by a per-point
     * {@link PptxChartDataLabel.txPr} when set. `c:dLbls` at the chart-type
     * level and the series level cascade the same way the show flags do
     * (point > series > chart-type).
     */
    txPr?: PptxChartLegendTextStyle;
    /**
     * PowerPoint 2013+ "Value From Cells", series-wide form
     * (`c15:datalabelsRange`, chart15 uri `{CE6537A1-...}`): one cell range
     * supplies every label in this group, aligned by point index. A
     * SERIES-WIDE alternative to the per-point `c15:dlblFieldTable` mechanism
     * (already resolved into {@link PptxChartDataLabel.text} at parse time).
     * See `utils/chart-data-labels-range.ts`.
     */
    dataLabelsRange?: PptxChartDataLabelsRange;
    /**
     * `c15:showDataLabelsRange` at the SAME level as {@link dataLabelsRange}:
     * whether every label in this group resolves through the range's cache.
     * Distinct from the per-point {@link PptxChartDataLabel} flag of the same
     * XML name. Only meaningful when {@link dataLabelsRange} is set.
     */
    showDataLabelsRange?: boolean;
}

/** Schema values accepted by `c:dLblPos`. */
declare type PptxChartDataLabelPosition = 'bestFit' | 'b' | 'ctr' | 'inBase' | 'inEnd' | 'l' | 'outEnd' | 'r' | 't';

/**
 * `c15:dlblRangeCache`/`c15:datalabelsRange` (CT_SeriesDataLabelsRange):
 * PowerPoint 2013+'s "Value From Cells" custom label source, one cell range
 * supplying every label in a group (chart-type or series `c:dLbls`), with a
 * cache aligned to point order. See `utils/chart-data-labels-range.ts`.
 */
declare interface PptxChartDataLabelsRange {
    /** `c15:f`: the cell range formula (e.g. `Sheet1!$D$2:$D$5`). */
    formula: string;
    /** `c15:dlblRangeCache`: cached label text, index-aligned with data points. */
    cache: string[];
}

/** Per-data-point formatting override (c:dPt). */
declare interface PptxChartDataPoint {
    idx: number;
    spPr?: PptxChartShapeProps;
    explosion?: number;
    invertIfNegative?: boolean;
    marker?: PptxChartMarker;
    /** Render a bubble-chart point with a 3-D appearance. */
    bubble3D?: boolean;
    /** Per-point picture-fill flags (`c:dPt/c:pictureOptions`). */
    picture?: PptxChartDataPointPicture;
    /**
     * A picture fill implied by a bare `c:dPt/c:spPr/a:blipFill` with NO
     * sibling `c:pictureOptions` at all: still a fully legal "stretch, no
     * stack" picture fill, just one PowerPoint's format pane never touched the
     * stack settings for. Render-derived only: unlike {@link picture}, this is
     * never written back on save (the original, untouched `c:spPr` already
     * round-trips verbatim), so populating it can never desync the saved file
     * from what was authored. See `chart-datapoint-picture.ts`'s
     * `parseImplicitBlipPictureFill`.
     */
    impliedPicture?: PptxChartDataPointPicture;
    /**
     * This point's identity GUID (`c:dPt/c:extLst/c:ext/c16:uniqueId/@val`,
     * the Office 2014+ `{C3380CC4-5D6E-409C-BE32-E72D297353CC}` chart
     * extension), read-only here: an edited point keeps its existing
     * `c:extLst` as passthrough (see `chart-datapoint-serializer.ts`), so this
     * field exists for introspection rather than round-trip.
     */
    uniqueId?: string;
}

/**
 * Per-data-point picture-fill flags (`c:dPt/c:pictureOptions`): PowerPoint's
 * "Picture or texture fill" with "Stack"/"Stretch" semantics on a bar/column
 * data point, distinct from the point's plain `c:spPr` solid/gradient fill.
 *
 * `c:pictureOptions` is optional: a point/series whose `c:spPr` carries a bare
 * `a:blipFill` with NO `c:pictureOptions` sibling at all is still a fully
 * legal, common picture fill (PowerPoint's own default "stretch, no stack"
 * when the format pane never touched the stack settings); `parseChartDataPointPicture`
 * synthesizes this descriptor (`pictureFormat: 'stretch'`) in that case so the
 * SAME render pipeline resolves it, rather than silently dropping the fill.
 *
 * The flags parse purely (`parseChartDataPointPicture` in
 * `utils/chart-datapoint-serializer.ts`); {@link imageUrl} is a separate,
 * later addition populated by the runtime (`PptxHandlerRuntimeChartParsing.ts`)
 * once the sibling `c:spPr/a:blipFill/a:blip`'s `r:embed`/`r:link` is resolved
 * against the chart part's relationships, since that resolution needs zip/file
 * access the pure parser does not have.
 */
declare interface PptxChartDataPointPicture {
    /** Apply the picture to the front face of a 3-D bar/column (`c:applyToFront`). */
    applyToFront?: boolean;
    /** Apply the picture to the side faces of a 3-D bar/column (`c:applyToSides`). */
    applyToSides?: boolean;
    /** Apply the picture to the end face of a 3-D bar/column (`c:applyToEnd`). */
    applyToEnd?: boolean;
    /** Stretch, or stack repeated tiles at their natural size (or scaled). */
    pictureFormat?: PptxChartPictureFormat;
    /** Height, in points, of one repeated picture tile for "stack"/"stackScale" (`c:pictureStackUnit/@val`). */
    pictureStackUnit?: number;
    /**
     * Resolved picture source (a `data:`/`blob:` URL) for the point's sibling
     * `c:spPr/a:blipFill/a:blip`. Populated by the runtime after relationship
     * resolution (C2-G9 render half); absent until then, and absent entirely
     * when the point has no picture fill or the image could not be resolved.
     */
    imageUrl?: string;
    /**
     * Effective opacity (0-1) from the blip's `a:alphaModFix/@amt` (a
     * thousandths-of-a-percent value, so `amt="60000"` is `0.6`). `undefined`
     * when the blip carries no `alphaModFix`, meaning fully opaque.
     */
    opacity?: number;
}

/**
 * Visibility flags for the chart data table (axes + legend keys).
 *
 * @example
 * ```ts
 * const dt: PptxChartDataTable = {
 *   showHorzBorder: true,
 *   showVertBorder: true,
 *   showOutline: true,
 *   showKeys: true,
 * };
 * // => satisfies PptxChartDataTable
 * ```
 */
declare interface PptxChartDataTable {
    showHorzBorder?: boolean;
    showVertBorder?: boolean;
    showOutline?: boolean;
    showKeys?: boolean;
    /** Table border/fill formatting (`c:dTable/c:spPr`). */
    spPr?: PptxChartShapeProps;
    /**
     * Cell text defaults (`c:dTable/c:txPr/a:p/a:pPr/a:defRPr`). Reuses the same
     * shape as a legend entry's text override since both are a flat paragraph
     * default-run-property style (size/bold/italic/font/colour).
     */
    txPr?: PptxChartLegendTextStyle;
}

/** Raw numeric category cache used by a classic ChartML date axis. */
declare interface PptxChartDateCategories {
    values: number[];
    /** False/default uses Excel's 1900 date system; true uses the 1904 system. */
    date1904?: boolean;
    /** Number format copied from the numeric category cache. */
    formatCode?: string;
}

/** Typed contents of a value-axis display-unit label (`c:dispUnitsLbl`). */
declare interface PptxChartDisplayUnitsLabel {
    /** Literal label text. Omit to preserve the source text subtree. */
    text?: string;
    /** Manual label placement. `null` removes only the manual layout. */
    layout?: PptxChartManualLayout | null;
    /** Label shape formatting. `null` removes `c:spPr`. */
    spPr?: PptxChartShapeProps | null;
    /**
     * The label's own run font, when it carries a distinct `txPr` from the
     * axis's own (ChartEx `cx:unitsLabel/cx:txPr`; classic `c:dispUnitsLbl`
     * has no equivalent child, so this is only ever populated from a ChartEx
     * axis).
     */
    fontFamily?: string;
    fontSize?: number;
    fontBold?: boolean;
    fontColor?: string;
}

/** Error-bar direction axis. */
declare type PptxChartErrBarDir = 'x' | 'y';

/**
 * Error bars for a chart series.
 *
 * @example
 * ```ts
 * const bars: PptxChartErrBars = {
 *   direction: "y",
 *   barType: "both",
 *   valType: "percentage",
 *   val: 5,
 * };
 * // => satisfies PptxChartErrBars
 * ```
 */
declare interface PptxChartErrBars {
    direction: PptxChartErrBarDir;
    barType: PptxChartErrBarType;
    valType: PptxChartErrValType;
    val?: number;
    customPlus?: number[];
    customMinus?: number[];
    noEndCap?: boolean;
    color?: string;
    /** Error-bar line width in points (`c:errBars/c:spPr/a:ln/@w`, EMU / 12700). */
    width?: number;
    /** Error-bar line dash style (`c:errBars/c:spPr/a:ln/a:prstDash/@val`). */
    dashStyle?: string;
}

/** Error-bar display type (both sides, negative only, or positive only). */
declare type PptxChartErrBarType = 'both' | 'minus' | 'plus';

/**
 * How the error-bar value is calculated.
 *
 * @example
 * ```ts
 * const valType: PptxChartErrValType = "percentage";
 * // => "percentage": one of: "cust" | "fixedVal" | "percentage" | "stdDev" | "stdErr"
 * ```
 */
declare type PptxChartErrValType = 'cust' | 'fixedVal' | 'percentage' | 'stdDev' | 'stdErr';

/**
 * A series PowerPoint's "Chart Filters" feature hid from the plot while
 * keeping it in the workbook (`c:<type>Chart/c:extLst/c:ext
 * [@uri={02D57815-91ED-43cb-92C2-25804820EDAC}]/c15:filtered<Type>Series
 * /c15:ser`). Read-mostly: {@link PptxChartData.filteredSeries} exists for
 * introspection (AI tools, "unhide filtered series" UI) and round-trips as
 * passthrough through the preserved chart XML when untouched. See
 * `utils/chart-filtered-series.ts` for the parse rules and the idx-collision
 * fix this modelling enables on save.
 */
declare interface PptxChartFilteredSeries {
    /** `c15:ser/c:idx/@val`, the workbook column position this series still occupies. */
    idx: number;
    /** `c15:ser/c:order/@val`, defaulting to {@link idx} when absent. */
    order: number;
    /** Series name, from the hidden series' own `c:tx` cache. */
    name?: string;
    /** Category labels, from the hidden series' own `c:cat` cache. */
    categories?: string[];
    /** Data values, from the hidden series' own `c:val` cache. */
    values?: number[];
    /** This hidden series' own identity GUID (`c16:uniqueId`), when present. */
    uniqueId?: string;
    /**
     * A full snapshot of the series as it looked the moment it was hidden
     * (`render/chart-ext-editor-actions.ts`'s `hideChartSeries`), so
     * `restoreFilteredSeries` can bring it back exactly as it was: full fill/
     * line formatting, marker, data-label options, everything, not just the
     * bare name/values/idx the other fields above capture.
     *
     * NOT derived from XML and NEVER written to disk (the save writer,
     * `chart-filtered-series-writer.ts`, only reads the named fields above):
     * this exists purely for the live "Chart Filters" hide/show round-trip
     * within one editing session. A filtered series read from an actually
     * parsed file (one that was already hidden when opened) has no snapshot
     * to draw on, since real PowerPoint's `c15:ser` node is parsed only for
     * the fields above (`chart-filtered-series.ts`'s `parseOneFilteredSeries`);
     * `restoreFilteredSeries` falls back to reconstructing a bare series from
     * those for that case, same as before this field existed.
     */
    originalSeries?: PptxChartSeries;
}

/** Shape properties extracted from c:spPr for chart formatting. */
/**
 * A render-ready gradient fill from a chart `c:spPr/a:gradFill` (chart area,
 * plot area or series). Positions are 0..100; a linear gradient's `angle` is
 * in degrees clockwise from left-to-right (`a:lin/@ang`); a radial (`a:path`)
 * gradient centres on `focalPoint` (0..1 fractions of the box), the middle
 * when absent.
 */
declare interface PptxChartGradientFill {
    type: 'linear' | 'radial';
    stops: Array<{
        color: string;
        position: number;
        opacity?: number;
    }>;
    angle?: number;
    focalPoint?: {
        x: number;
        y: number;
    };
}

/** Office 2016 ChartEx histogram and Pareto series layout options. */
declare interface PptxChartHistogramOptions {
    /** Maps to `clusteredColumn` for histogram columns or `paretoLine`. */
    layout?: 'histogram' | 'pareto';
    /** Exactly one of binSize and binCount is emitted by the ChartEx writer. */
    binSize?: number;
    binCount?: number;
    intervalClosed?: 'l' | 'r';
    underflow?: number | 'auto';
    overflow?: number | 'auto';
    /**
     * `c:layoutPr/cx:aggregation` was authored instead of `cx:binning`: the
     * raw rows are CATEGORICAL (a Pareto chart's `clusteredColumn` series
     * counting occurrences of each authored category, COM-verified against
     * charts-com.pptx slide 31 / chartEx6.xml), not a numeric range to bin.
     * Mutually exclusive with `binSize`/`binCount`/`intervalClosed`, which
     * only apply to a true numeric-value histogram.
     */
    aggregateByCategory?: boolean;
}

/**
 * Typed manual layouts for chart regions that accept `c:layout`.
 * A `null` region removes its manual layout without removing extensions.
 */
declare interface PptxChartLayouts {
    title?: PptxChartManualLayout | null;
    plotArea?: PptxChartManualLayout | null;
    legend?: PptxChartManualLayout | null;
}

/** Per-series legend entry override (`c:legendEntry`). */
declare interface PptxChartLegendEntry {
    index: number;
    deleted?: boolean;
    textStyle?: PptxChartLegendTextStyle;
}

/** Typed text defaults for a single chart legend entry. */
declare interface PptxChartLegendTextStyle {
    fontFamily?: string;
    fontSize?: number;
    bold?: boolean;
    italic?: boolean;
    color?: string;
}

/**
 * Line appearance for chart helper lines (drop lines, hi-low lines).
 *
 * @example
 * ```ts
 * const style: PptxChartLineStyle = {
 *   color: "#AAAAAA",
 *   width: 1,
 *   dashStyle: "dash",
 * };
 * // => satisfies PptxChartLineStyle
 * ```
 */
declare interface PptxChartLineStyle {
    color?: string;
    width?: number;
    dashStyle?: string;
}

/** Manual chart placement from `c:layout/c:manualLayout` (CT_ManualLayout). */
declare interface PptxChartManualLayout {
    layoutTarget?: 'inner' | 'outer';
    xMode?: 'edge' | 'factor';
    yMode?: 'edge' | 'factor';
    widthMode?: 'edge' | 'factor';
    heightMode?: 'edge' | 'factor';
    x?: number;
    y?: number;
    width?: number;
    height?: number;
    /**
     * Raw `c:extLst` (CT_ExtensionList) of the `c:manualLayout`, captured
     * verbatim so it round-trips through the typed model. Without this, a dirty
     * write of an edited layout would drop the extension list (the manual node
     * is rebuilt from the typed fields). Emitted as the trailing child, matching
     * the CT_ManualLayout schema order.
     */
    ext?: XmlObject;
}

/** Marker appearance on a chart series or data point. */
declare interface PptxChartMarker {
    symbol: PptxChartMarkerSymbol;
    /** Marker size in points, constrained by ST_MarkerSize to 2 through 72. */
    size?: number;
    spPr?: PptxChartShapeProps;
}

/** Marker symbol types for line/scatter chart data points. */
declare type PptxChartMarkerSymbol = 'circle' | 'dash' | 'diamond' | 'dot' | 'none' | 'picture' | 'plus' | 'square' | 'star' | 'triangle' | 'x' | 'auto';

/**
 * Options specific to the OOXML "Pie of Pie" / "Bar of Pie" chart
 * (`c:ofPieChart`, ECMA-376 §21.2.2.126 / CT_OfPieChart).
 *
 * The primary discriminator is {@link ofPieType}: `"pie"` produces a
 * pie-of-pie chart whose secondary plot is itself a pie, while `"bar"`
 * produces a bar-of-pie chart whose secondary plot is a horizontal bar.
 *
 * - {@link splitType} chooses the split rule.
 * - {@link splitPos} is the threshold value used by `pos`/`val`/`percent`.
 * - {@link secondPieSize} controls the secondary plot's size (5–200%).
 * - {@link serLines} toggles the leader lines connecting the plots.
 * - {@link gapWidth} is the gap between the plots in percent (0–500).
 */
declare interface PptxChartOfPieOptions {
    ofPieType: 'pie' | 'bar';
    splitType?: 'auto' | 'cust' | 'percent' | 'pos' | 'val';
    splitPos?: number;
    custSplit?: number[];
    secondPieSize?: number;
    serLines?: boolean;
    gapWidth?: number;
}

/** Required page margins from ChartML `c:pageMargins`, measured in inches. */
declare interface PptxChartPageMargins {
    left: number;
    right: number;
    top: number;
    bottom: number;
    header: number;
    footer: number;
    /** Original leaf retained for foreign attributes. */
    rawXml?: unknown;
}

/** Printer page configuration from ChartML `c:pageSetup`. */
declare interface PptxChartPageSetup {
    paperSize?: number;
    firstPageNumber?: number;
    orientation?: 'default' | 'portrait' | 'landscape';
    blackAndWhite?: boolean;
    draft?: boolean;
    useFirstPageNumber?: boolean;
    horizontalDpi?: number;
    verticalDpi?: number;
    copies?: number;
    /**
     * Custom paper height, used when {@link paperSize} is `0`
     * (`c:pageSetup/@paperHeight`, ST_PositiveUniversalMeasure, e.g. `"297mm"`).
     * Kept as the raw measure string rather than converted, matching how the
     * schema stores it.
     */
    paperHeight?: string;
    /** Custom paper width, used when {@link paperSize} is `0` (`@paperWidth`). */
    paperWidth?: string;
    /** Original leaf retained for foreign attributes. */
    rawXml?: unknown;
}

/** Layout for parent category labels in a hierarchical ChartEx treemap. */
declare type PptxChartParentLabelLayout = 'none' | 'banner' | 'overlapping';

/**
 * Chart-formatting types that don't fit an existing, owned type module for
 * this wave (`types/chart.ts` is owned elsewhere; see its own module doc).
 * Despite the file name, `PptxChartDataPointPicture` is a CLASSIC (`c:`)
 * construct, not ChartEx (`cx:`) - it landed here only because it needs a
 * home outside `chart.ts`.
 *
 * @module pptx-types/chart-ex
 */
/** `c:dPt/c:pictureOptions/c:pictureFormat/@val` (ST_PictureFormat). */
declare type PptxChartPictureFormat = 'stretch' | 'stack' | 'stackScale';

declare interface PptxChartPivotFormat {
    index: number;
    /**
     * Typed projection of `spPr` (fill/stroke colour, stroke width, dash
     * style). When the parser is given a colour resolver (the normal case: the
     * runtime always supplies one), both a literal `a:srgbClr` and an
     * `a:schemeClr` theme reference (with its `lumMod`/`lumOff`/`tint`/`shade`
     * modifiers) resolve to a hex colour here, the same theme +
     * `c:clrMapOvr` chain the rest of chart parsing uses. Without a resolver
     * (e.g. a hand-built `PptxChartPivotFormat` with no theme to resolve
     * against), only the literal case resolves. Either way the authored node
     * is byte-preserved through {@link shapePropertiesXml} until this field is
     * set to something that no longer matches what re-parses off the current
     * XML; setting it then re-derives `shapePropertiesXml` on save (merged
     * onto whatever was already authored, keeping an unrelated schemeClr
     * reference alive when the colour itself is unchanged) unless
     * `shapePropertiesXml` is set explicitly, which wins.
     */
    shapeProperties?: PptxChartShapeProps;
    /**
     * Typed projection of `txPr`'s `a:p/a:pPr/a:defRPr` (size/bold/italic/
     * colour/family), the same shape a legend entry or data-table's text
     * override models. Colour resolution mirrors {@link shapeProperties}
     * (theme-resolved `schemeClr` when a colour resolver is supplied, literal
     * `srgbClr` otherwise). See {@link txPrXml} for the raw fallback.
     */
    textStyle?: PptxChartLegendTextStyle;
    /**
     * Typed projection of `marker` (symbol/size/spPr). See {@link markerXml}
     * for the raw fallback.
     */
    marker?: PptxChartMarker;
    shapePropertiesXml?: XmlObject | null;
    txPrXml?: XmlObject | null;
    markerXml?: XmlObject | null;
    dataLabelXml?: XmlObject | null;
    extensionListXml?: XmlObject | null;
    rawXml?: XmlObject;
}

/** Editable classic ChartML `c:pivotFmts` collection. */
declare interface PptxChartPivotFormats {
    formats: PptxChartPivotFormat[];
    rawXml?: XmlObject;
}

/** Editable classic ChartML `c:pivotSource` metadata. */
declare interface PptxChartPivotSource {
    /** Pivot table reference stored as `c:name` text. */
    name: string;
    /** Required unsigned format identifier stored in `c:fmtId/@val`. */
    formatId: number;
    /** Internal source subtree used to preserve extensions and foreign markup. */
    rawXml?: XmlObject;
}

/** Headers and footers used when a classic ChartML chart is printed. */
declare interface PptxChartPrintHeaderFooter {
    oddHeader?: string;
    oddFooter?: string;
    evenHeader?: string;
    evenFooter?: string;
    firstHeader?: string;
    firstFooter?: string;
    alignWithMargins?: boolean;
    differentOddEven?: boolean;
    differentFirst?: boolean;
    /** Original subtree retained for foreign attributes and extension children. */
    rawXml?: unknown;
}

/** Editable `c:printSettings` content from a classic ChartML chart space. */
declare interface PptxChartPrintSettings {
    headerFooter?: PptxChartPrintHeaderFooter | null;
    pageMargins?: PptxChartPageMargins | null;
    pageSetup?: PptxChartPageSetup | null;
    /** `null` removes the legacy header/footer drawing relationship element. */
    legacyDrawingHeaderFooterRelationshipId?: string | null;
    /** Original subtree retained for unknown and extension content. */
    rawXml?: unknown;
}

/** Editable classic ChartML `c:protection` settings. */
declare interface PptxChartProtection {
    /** Prevent editing the chart object. */
    chartObject?: boolean | null;
    /** Prevent editing the chart data. */
    data?: boolean | null;
    /** Prevent editing chart formatting. */
    formatting?: boolean | null;
    /** Prevent selecting chart elements. */
    selection?: boolean | null;
    /** Prevent chart user-interface operations. */
    userInterface?: boolean | null;
    /** Internal source subtree used to preserve foreign markup during edits. */
    rawXml?: XmlObject;
}

/** Office 2016 ChartEx geographic series dimensions and layout options. */
declare interface PptxChartRegionMapOptions {
    /**
     * Colour-by-value gradient stops (`cx:valueColors/cx:colors/cx:color`),
     * resolved to hex, 2 or 3 entries (matching PowerPoint's two- and
     * three-colour scale UI). Paired index-for-index with
     * {@link valueColorPositions} when both are present.
     */
    valueColors?: string[];
    /** Gradient breakpoints for {@link valueColors} (`cx:valueColorPositions`). */
    valueColorPositions?: PptxCxValueColorPosition[];
    /** Optional provider entity identifiers aligned with categories and values. */
    entityIds?: string[];
    /** Original `cx:pt/@idx` values for category points. */
    categorySourceIndices?: number[];
    /** Original `cx:pt/@idx` values for colour-value points. */
    valueSourceIndices?: number[];
    /** Original `cx:pt/@idx` values for entity-ID points. */
    entityIdSourceIndices?: number[];
    regionLabelLayout?: 'none' | 'bestFitOnly' | 'showAll';
    projectionType?: 'mercator' | 'miller' | 'robinson' | 'albers';
    viewedRegionType?: 'dataOnly' | 'postalCode' | 'county' | 'state' | 'countryRegion' | 'countryRegionList' | 'world';
    cultureLanguage?: string;
    /** ISO-3166-1 alpha-2 region code. */
    cultureRegion?: string;
    attribution?: string;
    /** Opaque authored provider cache under `cx:geography/cx:geoCache`. */
    geographyCache?: XmlObject;
}

/**
 * `ST_ScatterStyle` (ECMA-376 §21.2.3.40): how a scatter chart joins its points.
 * `line`/`lineMarker` connect them with straight segments, `smooth`/
 * `smoothMarker` with a bezier, `marker`/`none` not at all.
 */
declare type PptxChartScatterStyle = 'none' | 'line' | 'lineMarker' | 'marker' | 'smooth' | 'smoothMarker';

/**
 * A single data series within a chart.
 *
 * @example
 * ```ts
 * const series: PptxChartSeries = {
 *   name: "Revenue",
 *   values: [100, 120, 140],
 *   color: "#4F81BD",
 *   trendlines: [{ trendlineType: "linear" }],
 * };
 * // => satisfies PptxChartSeries
 * ```
 */
declare interface PptxChartSeries {
    name: string;
    /**
     * This series' own `c:ser/c:idx/@val`. PowerPoint keys per-series identity
     * (data-point picking, and the automatic marker-symbol cycle when no
     * `c:marker/c:symbol` is authored) off this value, NOT off the series'
     * position in this array: a series can be reordered (`c:order`) without its
     * `idx` changing, and a chart with a deleted/filtered series leaves a gap
     * (e.g. idx 1, 2 with no idx 0). Absent only for chart kinds this parser
     * does not tag (rare); render code that needs it should fall back to the
     * array position.
     */
    idx?: number;
    values: number[];
    /**
     * Series gradient fill (`c:ser/c:spPr/a:gradFill`), painted on every mark
     * of the series that has no per-point override. Render-only: the series'
     * own `c:spPr` round-trips untouched.
     */
    gradientFill?: PptxChartGradientFill;
    /**
     * Per-series x values from `c:ser/c:xVal` (scatter and bubble series only).
     *
     * Every `CT_ScatterSer` / `CT_BubbleSer` carries its OWN `c:xVal`, so two
     * series in one scatter chart routinely plot against different x ranges (the
     * normal case for measurement data). Reading the x values off the first
     * series and reusing them everywhere plotted every series against series 1's
     * x axis. Absent for category-axis chart kinds, where
     * {@link PptxChartData.categories} is the x axis.
     */
    xValues?: number[];
    /**
     * Per-series bubble sizes from `c:ser/c:bubbleSize` (bubble series only),
     * aligned index-for-index with {@link values}.
     *
     * `CT_BubbleSer` carries x, y AND size, so a one-series bubble chart is fully
     * specified. Absent when the source omits `c:bubbleSize`.
     */
    bubbleSizes?: number[];
    /**
     * Series-level data-label content flags from `c:ser/c:dLbls`.
     *
     * PowerPoint writes the flags a user picks in "Format Data Labels" onto the
     * SERIES, and leaves the chart-type-level `c:dLbls` all-zero, so reading only
     * the chart-level group reports "show nothing" for a chart that visibly shows
     * percentages. These override {@link PptxChartStyle.dataLabels}.
     */
    dataLabelOptions?: PptxChartDataLabelOptions;
    /**
     * Whether the series line is explicitly suppressed
     * (`c:ser/c:spPr/a:ln/a:noFill`). Line-drawn kinds (line, scatter, radar)
     * use this to decide whether to draw a connecting line at all; a marker-only
     * scatter is authored as `scatterStyle="lineMarker"` PLUS this flag, never by
     * changing the scatter style.
     */
    lineNoFill?: boolean;
    /**
     * Blank-value mask aligned index-for-index with {@link values}: `true` marks
     * a category whose numeric cache point (`c:numCache/c:pt`) was absent or
     * empty, i.e. a genuine blank rather than a real `0`. Present only when the
     * source series actually contains blanks; when set, blank slots in
     * {@link values} carry `0` as a placeholder. Renderers honour
     * `c:dispBlanksAs` (gap / zero / span) using this mask.
     */
    blanks?: boolean[];
    /**
     * ECMA-376 number-format code for this series' values, resolved from
     * `c:ser/c:dLbls/c:numFmt/@formatCode` and falling back to the value cache's
     * own `c:numCache/c:formatCode` (which is what `@sourceLinked="1"` means).
     * Data labels render through it: a percentage series caches fractions, so
     * without the code `0.52` reaches the label where PowerPoint shows `52%`.
     */
    numberFormat?: string;
    color?: string;
    trendlines?: PptxChartTrendline[];
    errBars?: PptxChartErrBars[];
    dataPoints?: PptxChartDataPoint[];
    marker?: PptxChartMarker;
    dataLabels?: PptxChartDataLabel[];
    explosion?: number;
    /**
     * Series-level `c:invertIfNegative`: when true, bar/column data points with a
     * negative value are drawn with an inverted (lightened) fill. A per-point
     * `c:dPt/c:invertIfNegative` overrides this for that point. Absent when the
     * source XML omits the flag.
     */
    invertIfNegative?: boolean;
    /**
     * Whether this line/scatter series is drawn with bezier smoothing
     * (`c:ser/c:smooth/@val`). Absent when the source XML omits `c:smooth`.
     */
    smooth?: boolean;
    /** Axis ID this series is plotted against (links to PptxChartAxisFormatting.axisId). */
    axisId?: number;
    /**
     * Per-series chart type, used for combo charts where individual series are
     * plotted with different chart types (e.g. a bar series and a line series in
     * the same chart). Maps to the OOXML chart-type container that holds the
     * series (`c:barChart`, `c:lineChart`, etc.). Omitted for single-type charts,
     * where the chart-level {@link PptxChartData.chartType} applies to every
     * series.
     */
    seriesChartType?: PptxChartType;
    /**
     * Per-series 3-D bar/column shape override (`c:ser/c:shape`), legal only
     * inside a bar3D chart-type container. Overrides {@link PptxChartData.barShape}
     * for this series alone.
     */
    shape?: PptxBar3DShape;
    boxWhiskerOptions?: PptxChartBoxWhiskerOptions;
    histogramOptions?: PptxChartHistogramOptions;
    waterfallOptions?: PptxChartWaterfallOptions;
    regionMapOptions?: PptxChartRegionMapOptions;
    treemapOptions?: PptxChartTreemapOptions;
    /**
     * Series-level picture-fill flags (`c:ser/c:pictureOptions`), legal
     * wherever a per-point `c:dPt/c:pictureOptions` is (CT_BarSer): paints
     * EVERY point in the series with one picture unless a `c:dPt` overrides it
     * for that point alone. A point's own {@link PptxChartDataPoint.picture}
     * takes precedence entirely (not merged field-by-field) when it resolves
     * its own image; renderers fall back to this series-level picture only
     * when the point has none of its own.
     */
    picture?: PptxChartDataPointPicture;
    /**
     * A picture fill implied by a bare `c:ser/c:spPr/a:blipFill` with NO
     * sibling `c:pictureOptions` at all. See
     * {@link PptxChartDataPoint.impliedPicture}'s doc comment: same
     * render-only, never-serialized-back convention, at the series level.
     */
    impliedPicture?: PptxChartDataPointPicture;
    /**
     * This series' identity GUID (`c:ser/c:extLst/c:ext/c16:uniqueId/@val`,
     * the Office 2014+ `{C3380CC4-5D6E-409C-BE32-E72D297353CC}` chart
     * extension). PowerPoint uses it to track a series across edits and
     * collaborators independent of its `c:idx`/`c:order` position (the same
     * role animation targeting and CRDT reconciliation need). An edited
     * existing series keeps its own `c:extLst` as passthrough; a NEW series
     * added by cloning an existing one as a template is given a freshly
     * generated id rather than duplicating the template's (see
     * `regenerateClonedUniqueId` in `chart-series-identity.ts`), since two
     * series sharing one identity is exactly what this extension exists to
     * prevent.
     */
    uniqueId?: string;
}

declare interface PptxChartShapeProps {
    fillColor?: string;
    strokeColor?: string;
    strokeWidth?: number;
    /** Line dash style (a:prstDash/@val), e.g. 'solid', 'dash', 'dot', 'lgDash'. */
    strokeDashStyle?: string;
}

/**
 * Style / formatting metadata for a chart.
 *
 * @example
 * ```ts
 * const style: PptxChartStyle = {
 *   styleId: 2,
 *   hasLegend: true,
 *   legendPosition: "b",
 *   hasDataLabels: true,
 * };
 * // => satisfies PptxChartStyle
 * ```
 */
declare interface PptxChartStyle {
    /** Chart style index from `c:style/@val`. */
    styleId?: number;
    /** Whether the chart has a visible legend. */
    hasLegend?: boolean;
    /** Legend position (t, b, l, r, tr). */
    legendPosition?: string;
    /** Per-series visibility and text-style overrides. */
    legendEntries?: PptxChartLegendEntry[];
    /**
     * The legend's own default text style (`c:legend/c:txPr`), falling back to
     * the chart-wide default (`c:chartSpace/c:txPr`) when the legend has none
     * of its own. Applies to every legend entry that has no per-entry
     * `c:legendEntry/c:txPr` override (see {@link PptxChartLegendEntry.textStyle}),
     * which always wins over this chart-level default.
     */
    legendTextStyle?: PptxChartLegendTextStyle;
    /** Whether the chart has a title. */
    hasTitle?: boolean;
    /** Whether gridlines are visible. */
    hasGridlines?: boolean;
    /**
     * Chart-area fill from `c:chartSpace/c:spPr`: a resolved colour, or the
     * literal `'none'` when the source declares `<a:noFill/>`. Absent when the
     * chart says nothing, in which case the renderer picks its own default.
     * PowerPoint decks routinely set `a:noFill` so the chart floats on the slide
     * background; painting a panel behind it boxes the chart in.
     */
    chartAreaFill?: string;
    /** Plot-area fill from `c:plotArea/c:spPr`. See {@link chartAreaFill}. */
    plotAreaFill?: string;
    /** Chart-area gradient (`c:chartSpace/c:spPr/a:gradFill`); wins over {@link chartAreaFill}. */
    chartAreaGradient?: PptxChartGradientFill;
    /** Plot-area gradient (`c:plotArea/c:spPr/a:gradFill`); wins over {@link plotAreaFill}. */
    plotAreaGradient?: PptxChartGradientFill;
    /** Whether data labels are shown. */
    hasDataLabels?: boolean;
    /** Chart-level data-label content/position options (when `hasDataLabels`). */
    dataLabels?: PptxChartDataLabelOptions;
    /**
     * Font styling for the chart's own title (`c:title/c:txPr`), edited via
     * `applyChartTitleStyleToXml` (chart-title-style-serializer.ts). Distinct
     * from an axis title's styling (`PptxChartAxisFormatting.fontFamily` etc.).
     */
    titleFontFamily?: string;
    titleFontSize?: number;
    titleFontBold?: boolean;
    titleFontColor?: string;
    /** Title text-box fill/border (`c:title/c:spPr`). `null` removes it. */
    titleSpPr?: PptxChartShapeProps | null;
}

/**
 * Parsed per-element style defaults from a chart-style part. Only the
 * elements this viewer actually renders distinct defaults for are modeled;
 * elements PowerPoint's style gallery also styles (data table, trendlines,
 * up/down bars, ...) are out of scope until a renderer needs them.
 */
declare interface PptxChartStyleDefinition {
    title?: PptxChartStylePartEntry;
    axisTitle?: PptxChartStylePartEntry;
    categoryAxis?: PptxChartStylePartEntry;
    valueAxis?: PptxChartStylePartEntry;
    legend?: PptxChartStylePartEntry;
    dataLabel?: PptxChartStylePartEntry;
    dataPoint?: PptxChartStylePartEntry;
    dataPointLine?: PptxChartStylePartEntry;
    gridlineMajor?: PptxChartStylePartEntry;
    gridlineMinor?: PptxChartStylePartEntry;
    chartArea?: PptxChartStylePartEntry;
    plotArea?: PptxChartStylePartEntry;
}

/**
 * Typed subset of an Office 2013+ chart-style part (`ppt/charts/style#.xml`,
 * root element `cs:chartStyle`, relationship type
 * `.../2012/relationships/chartStyle`).
 *
 * PowerPoint's Design-tab "Chart Styles" gallery (1-48) writes `c:style/@val`
 * on the chart part itself (already modeled as `PptxChartStyle.styleId`) and,
 * for most styles, this SEPARATE part spelling out the per-element
 * `cs:lnRef`/`cs:fillRef`/`cs:effectRef`/`cs:fontRef`/`cs:defRPr` defaults a
 * chart element falls back to when its own XML leaves it unstyled. Without
 * parsing this part, styles beyond the one PowerPoint happens to have baked
 * inline are visually inert.
 *
 * @module pptx-types/chart-style-definition
 */
/**
 * One styled chart-element entry (`cs:title`, `cs:axisTitle`,
 * `cs:categoryAxis`, ...). Colours are resolved to hex at parse time (scheme
 * colour references via `cs:fontRef`/`cs:lnRef`/`cs:fillRef` are already
 * flattened against the theme, matching how classic chart colours resolve
 * elsewhere in this codebase). Fields are present only when the source XML
 * carried a value for them.
 */
declare interface PptxChartStylePartEntry {
    /** Text size in points, from `cs:defRPr/@sz` (hundredths of a point). */
    fontSize?: number;
    bold?: boolean;
    italic?: boolean;
    /** Resolved text colour: `cs:defRPr/a:solidFill`, or `cs:fontRef`'s scheme colour. */
    color?: string;
    /** Resolved line colour from `cs:lnRef`'s scheme colour reference. */
    lineColor?: string;
    /** Line width in points, when directly authored (rare; most styles reference a theme line style by index only). */
    lineWidth?: number;
    /** Resolved fill colour from `cs:fillRef`'s scheme colour reference. */
    fillColor?: string;
}

/** Tick-mark placement from ChartML `ST_TickMark`. */
declare type PptxChartTickMark = 'cross' | 'in' | 'none' | 'out';

/**
 * Chart title rich-text run type, split out of `types/chart.ts` (already at
 * the repo's file-size limit) to keep that module from growing further.
 *
 * @module pptx-types/chart-title
 */
/**
 * One run of a chart title's rich text (`c:title/c:tx/c:rich/a:p/a:r`).
 *
 * The flat `PptxChartData.title` field only ever captured the FIRST run's
 * text with no per-run formatting; `titleRuns` (when present) is the
 * lossless, multi-run replacement parsed from the same `c:rich` body. Absent
 * when the title has no rich text at all (an empty/auto title, or one
 * authored as a linked-cell reference).
 */
declare interface PptxChartTitleRun {
    /** This run's text (`a:t`). */
    text: string;
    /** `a:rPr/@_b`. */
    bold?: boolean;
    /** `a:rPr/@_i`. */
    italic?: boolean;
    /**
     * Font size in POINTS (`a:rPr/@_sz`, hundredths of a point / 100), matching
     * `PptxChartLegendTextStyle.fontSize`'s convention rather than the pixel
     * convention `TextStyle.fontSize` uses for slide text.
     */
    fontSize?: number;
    /** Resolved hex colour (e.g. `"#FF0000"`) from `a:rPr/a:solidFill`. */
    color?: string;
}

/** Per-series layout options for an Office 2016+ ChartEx treemap. */
declare interface PptxChartTreemapOptions {
    parentLabelLayout?: PptxChartParentLabelLayout;
}

/**
 * Configuration for a chart trendline (regression line).
 *
 * @example
 * ```ts
 * const trendline: PptxChartTrendline = {
 *   trendlineType: "linear",
 *   displayEq: true,
 *   displayRSq: true,
 *   color: "#FF0000",
 * };
 * // => satisfies PptxChartTrendline
 * ```
 */
declare interface PptxChartTrendline {
    trendlineType: PptxChartTrendlineType;
    name?: string;
    order?: number;
    period?: number;
    forward?: number;
    backward?: number;
    intercept?: number;
    displayRSq?: boolean;
    displayEq?: boolean;
    color?: string;
    /** Trendline width in points (`c:trendline/c:spPr/a:ln/@w`, EMU / 12700). */
    lineWidth?: number;
    /** Trendline dash style (`c:trendline/c:spPr/a:ln/a:prstDash/@val`). */
    lineDashStyle?: string;
    label?: PptxChartTrendlineLabel | null;
}

/** Typed, commonly edited properties of `c:trendlineLbl`. */
declare interface PptxChartTrendlineLabel {
    layout?: PptxChartManualLayout;
    numberFormatCode?: string;
    sourceLinked?: boolean;
}

/**
 * Supported trendline regression types.
 *
 * @example
 * ```ts
 * const type: PptxChartTrendlineType = "linear";
 * // => "linear": one of: "linear" | "exponential" | "logarithmic" | "polynomial" | "power" | "movingAvg"
 * ```
 */
declare type PptxChartTrendlineType = 'linear' | 'exponential' | 'logarithmic' | 'polynomial' | 'power' | 'movingAvg';

/**
 * Supported chart type discriminators.
 *
 * @example
 * ```ts
 * const type: PptxChartType = "bar";
 * // => "bar": one of: "bar" | "line" | "pie" | "doughnut" | "area" | "scatter" | …
 * ```
 */
declare type PptxChartType = 'bar' | 'line' | 'pie' | 'ofPie' | 'doughnut' | 'area' | 'scatter' | 'bubble' | 'radar' | 'stock' | 'bar3D' | 'line3D' | 'pie3D' | 'area3D' | 'surface' | 'histogram' | 'waterfall' | 'funnel' | 'treemap' | 'sunburst' | 'boxWhisker' | 'regionMap' | 'combo' | 'unknown';

/** Up/down bar formatting on line and stock charts (`c:upDownBars`). */
declare interface PptxChartUpDownBars {
    /** Gap between bars as a percentage, constrained to 0 through 500. */
    gapWidth?: number;
    upBars?: PptxChartShapeProps;
    downBars?: PptxChartShapeProps;
}

/**
 * A parsed chart-overlay shape positioned by a drawing anchor.
 *
 * Position is expressed as chart-relative fractions in {@link from}. For a
 * `relSizeAnchor` the opposite corner is {@link to} (also fractional); for an
 * `absSizeAnchor` the extent is {@link ext} in EMU.
 */
declare interface PptxChartUserShape {
    /**
     * Shape kind: text/preset shape, connector, picture, a group of the
     * above (`grpSp`, with its own {@link transform} and {@link children},
     * nested arbitrarily; use `flattenChartUserShapes` from
     * `chart-user-shapes-parser.ts` to get a flat, render-ready leaf list
     * with the group transform already applied), or a bare placeholder for
     * a `graphicFrame` anchor child (deep content such as a nested chart or
     * table is out of scope; it only keeps the anchor's space accounted for
     * instead of the whole overlay disappearing).
     */
    kind: 'sp' | 'cxnSp' | 'pic' | 'grpSp' | 'graphicFrame';
    /** Anchor kind that positioned the shape. */
    anchor: 'rel' | 'abs';
    /** Top-left corner as chart-relative fractions (0-1). */
    from: {
        x: number;
        y: number;
    };
    /** Bottom-right corner as chart-relative fractions (0-1); relSizeAnchor only. */
    to?: {
        x: number;
        y: number;
    };
    /** Extent in EMU (cx, cy); absSizeAnchor only. */
    ext?: {
        cx: number;
        cy: number;
    };
    /** Preset geometry name (`a:prstGeom/@prst`), defaulting to `"rect"`. */
    prst?: string;
    /** Resolved solid-fill hex colour, when present. */
    fill?: string;
    /** Resolved line/stroke hex colour, when present. */
    stroke?: string;
    /** Line width in points (`a:ln/@w` divided by 12700), when present. */
    strokeWidth?: number;
    /** Text paragraphs of the shape's `txBody`, when present. */
    paragraphs?: PptxChartUserShapeParagraph[];
    /**
     * A `pic` anchor's alt text (`cdr:nvPicPr/cdr:cNvPr/@descr`), when
     * present. Editable independently of {@link rawXml}'s otherwise-verbatim
     * content: the serializer patches only this attribute onto the cloned
     * raw node, so a picture's blip and other markup are untouched.
     */
    altText?: string;
    /**
     * This shape's OWN rotation in degrees (`a:xfrm/@rot`, on `spPr/a:xfrm`
     * for `sp`/`cxnSp`/`pic`, or directly on a top-level `graphicFrame`'s own
     * `a:xfrm`), when present. A top-level anchor's position/size is governed
     * by {@link from}/{@link to}/{@link ext}, never by this `a:xfrm`'s own
     * `off`/`ext` (see {@link rawXml}'s doc), but `rot`/`flipH`/`flipV` on that
     * same `a:xfrm` DO apply visually: verified against real PowerPoint (COM),
     * which writes e.g. `<a:xfrm rot="1800000"><a:off .../><a:ext .../></a:xfrm>`
     * on a rotated overlay shape's `spPr`, with the `off`/`ext` values
     * unrelated to the anchor's own `cdr:from`/`cdr:to`.
     */
    rotation?: number;
    /** This shape's OWN horizontal flip (`a:xfrm/@flipH`); see {@link rotation}'s doc. */
    flipH?: boolean;
    /** This shape's OWN vertical flip (`a:xfrm/@flipV`); see {@link rotation}'s doc. */
    flipV?: boolean;
    /**
     * Verbatim source XML of a `pic` or `graphicFrame` anchor child (the
     * `cdr:pic` / `cdr:graphicFrame` node itself, not the enclosing anchor),
     * or of the `cdr:grpSp` node itself when `kind === 'grpSp'` and the
     * group is untouched since parse (byte-identical passthrough). None of
     * these three kinds have a reconstructable typed representation that is
     * guaranteed lossless (a picture's blip reference, a nested chart/table's
     * graphic content, or a group's exact child ordering/ids), so the
     * serializer re-emits this verbatim when present instead of a lossy
     * rebuild. Editing a shape inside a group (via the SDK's path-based
     * overlay operations) clears the group's `rawXml` so the serializer
     * regenerates it from {@link transform}/{@link children} instead. Absent
     * for `sp`/`cxnSp`, which round-trip losslessly through their typed
     * fields above.
     */
    rawXml?: XmlObject;
    /** Present when `kind === 'grpSp'`: the group's own transform. */
    transform?: PptxChartUserShapeGroupTransform;
    /** Present when `kind === 'grpSp'`: the grouped children, nested arbitrarily. */
    children?: PptxChartUserShapeGroupChild[];
}

/**
 * One shape grouped inside a `cdr:grpSp` (or a nested `cdr:grpSp` itself).
 * Unlike a top-level {@link PptxChartUserShape}, a group child has no
 * drawing anchor of its own: its position is expressed in its parent
 * group's child coordinate space via {@link off}/{@link ext} (EMU, read
 * from the child's own `a:xfrm`), not as a chart-relative fraction.
 */
declare interface PptxChartUserShapeGroupChild {
    /** Shape kind, same vocabulary as {@link PptxChartUserShape.kind}. */
    kind: 'sp' | 'cxnSp' | 'pic' | 'grpSp' | 'graphicFrame';
    /** Position within the parent group's child coordinate space, in EMU. */
    off: {
        x: number;
        y: number;
    };
    /** Size within the parent group's child coordinate space, in EMU. */
    ext: {
        cx: number;
        cy: number;
    };
    /** Preset geometry name (`a:prstGeom/@prst`), defaulting to `"rect"`. */
    prst?: string;
    /** Resolved solid-fill hex colour, when present. */
    fill?: string;
    /** Resolved line/stroke hex colour, when present. */
    stroke?: string;
    /** Line width in points (`a:ln/@w` divided by 12700), when present. */
    strokeWidth?: number;
    /** Text paragraphs of the shape's `txBody`, when present. */
    paragraphs?: PptxChartUserShapeParagraph[];
    /**
     * A `pic` child's alt text (`cdr:nvPicPr/cdr:cNvPr/@descr`), when present.
     * Editable independently of {@link rawXml}'s otherwise-verbatim content:
     * the serializer patches only this attribute onto the cloned raw node.
     */
    altText?: string;
    /**
     * This child's OWN rotation in degrees (`a:xfrm/@rot`), when present.
     * Composes with every enclosing group's own
     * {@link PptxChartUserShapeGroupTransform.rotation} (added) to produce the
     * leaf's final on-screen rotation; see `flattenChartUserShapes`.
     */
    rotation?: number;
    /** This child's OWN horizontal flip (`a:xfrm/@flipH`); composes with an ancestor group's flip by XOR. */
    flipH?: boolean;
    /** This child's OWN vertical flip (`a:xfrm/@flipV`); composes with an ancestor group's flip by XOR. */
    flipV?: boolean;
    /**
     * Verbatim source XML of a `pic`/`graphicFrame` child, or of this node
     * itself when `kind === 'grpSp'` and the nested group is untouched since
     * parse. See {@link PptxChartUserShape.rawXml}'s doc for the same
     * contract one level up.
     */
    rawXml?: XmlObject;
    /** Present when `kind === 'grpSp'`: this nested group's own transform. */
    transform?: PptxChartUserShapeGroupTransform;
    /** Present when `kind === 'grpSp'`: this nested group's own children. */
    children?: PptxChartUserShapeGroupChild[];
}

/**
 * The DrawingML 2D group transform (`a:xfrm` inside `cdr:grpSpPr`) that
 * anchors a `grpSp`'s own box ({@link off}/{@link ext}) and establishes the
 * coordinate space its children are expressed in ({@link chOff}/{@link
 * chExt}), all in EMU. A child's position within the group is mapped into
 * the group's own box via
 * `frac = (child.off - chOff) / chExt`, then applied to the enclosing
 * anchor's box; see `flattenChartUserShapes` in
 * `chart-user-shapes-parser.ts`.
 */
declare interface PptxChartUserShapeGroupTransform {
    /** The group's own position in its parent's coordinate space, in EMU. */
    off: {
        x: number;
        y: number;
    };
    /** The group's own size in its parent's coordinate space, in EMU. */
    ext: {
        cx: number;
        cy: number;
    };
    /** Origin of the child coordinate space (`a:chOff`), in EMU. */
    chOff: {
        x: number;
        y: number;
    };
    /** Size of the child coordinate space (`a:chExt`), in EMU. */
    chExt: {
        cx: number;
        cy: number;
    };
    /**
     * The group's own rotation in degrees (`a:xfrm/@rot`, stored in 60,000ths
     * of a degree), when present. Rotates the whole group, and everything
     * grouped inside it, as a rigid body about the CENTRE of the group's own
     * box ({@link off}/{@link ext}); see `flattenChartUserShapes` in
     * `chart-user-shapes-parser.ts` for how this composes onto each contained
     * leaf's own {@link PptxChartUserShapeGroupChild.rotation}. Verified
     * against real PowerPoint (COM): a `cdr:grpSp`'s `cdr:grpSpPr/a:xfrm` does
     * carry `rot` the same way an ordinary shape's does.
     */
    rotation?: number;
    /** The group's own horizontal flip (`a:xfrm/@flipH`), when present; composes onto children by XOR, see {@link rotation}'s doc. */
    flipH?: boolean;
    /** The group's own vertical flip (`a:xfrm/@flipV`), when present; composes onto children by XOR, see {@link rotation}'s doc. */
    flipV?: boolean;
}

/** A single paragraph of overlay-shape text with light formatting. */
declare interface PptxChartUserShapeParagraph {
    /** Joined run text of the paragraph. */
    text: string;
    /** Font size in points (`a:rPr/@sz` divided by 100), when present. */
    fontSize?: number;
    /** Whether the first run is bold (`a:rPr/@b`). */
    bold?: boolean;
    /** Whether the first run is italic (`a:rPr/@i`). */
    italic?: boolean;
    /** Resolved run colour hex (e.g. `"#FF0000"`), when present. */
    color?: string;
    /** Paragraph alignment (`a:pPr/@algn`): left / centre / right. */
    align?: 'l' | 'ctr' | 'r';
}

/**
 * 3D viewing parameters for a chart (`c:view3D`, ECMA-376 §21.2.2.228 /
 * CT_View3D).
 *
 * All fields are optional and round-trip verbatim.
 *
 * - {@link rotX}: X-axis rotation in degrees (-90…90).
 * - {@link rotY}: Y-axis rotation in degrees (0…360).
 * - {@link depthPercent}: chart depth as a percentage of base width.
 * - {@link rAngAx}: `true` if axes meet at right angles.
 * - {@link perspective}: perspective angle in degrees (0…240).
 * - {@link hPercent}: height as a percentage of chart width.
 */
declare interface PptxChartView3D {
    rotX?: number;
    rotY?: number;
    depthPercent?: number;
    rAngAx?: boolean;
    perspective?: number;
    hPercent?: number;
}

/** Office 2016 ChartEx waterfall series layout options. */
declare interface PptxChartWaterfallOptions {
    /** Zero-based data point indexes rendered as absolute subtotal or total bars. */
    subtotalIndices?: number[];
    /** Whether connector lines are visible between adjacent bars. */
    connectorLines?: boolean;
}

/** Color animation data parsed from `p:animClr`. */
declare interface PptxColorAnimation {
    /** Color interpolation space: "hsl" or "rgb". */
    colorSpace: 'hsl' | 'rgb';
    /** Direction for HSL interpolation: "cw" (clockwise) or "ccw". */
    direction?: 'cw' | 'ccw';
    /**
     * Optional `p:animClr/@path` value preserved for round-trip. When set,
     * the colour sweep follows a path-based interpolation rather than the
     * straight cw/ccw arc. ECMA-376 §19.5.13 documents this attribute as a
     * companion to `@dir` for HSL colour-space animations.
     */
    path?: string;
    /** Starting color as hex string, or the bare scheme name (e.g. `accent1`) for a theme colour; see {@link fromColorRef}. */
    fromColor?: string;
    /** Ending color as hex string, or the bare scheme name; see {@link toColorRef}. */
    toColor?: string;
    /**
     * Color delta (for "by" animations) as hex string, or the bare scheme name;
     * see {@link byColorRef}. For HSL colour-space animations this retains the
     * historical byte-packed compatibility value; consumers should prefer
     * {@link hslDelta}, which preserves signed values.
     */
    byColor?: string;
    /**
     * The typed theme reference when {@link fromColor} is an `a:schemeClr`
     * (including `tint`/`shade`/`lumMod`/`lumOff`/`alpha`), so playback can
     * resolve it against the deck's theme colour map. Absent when `fromColor`
     * is already a resolved `#rrggbb` hex (an `a:srgbClr` stop).
     */
    fromColorRef?: PptxThemeColorRef;
    /** The typed theme reference for {@link toColor}; see {@link fromColorRef}. */
    toColorRef?: PptxThemeColorRef;
    /**
     * The typed theme reference for {@link byColor} (RGB colour space only; an
     * HSL `by` is a signed delta, never a theme colour). See {@link fromColorRef}.
     */
    byColorRef?: PptxThemeColorRef;
    /**
     * Typed HSL delta from `p:by/p:hsl`. This preserves signed values and their
     * OOXML units without forcing them through the legacy byte-packed `byColor`
     * representation.
     */
    hslDelta?: PptxHslColorDelta;
    /**
     * Target attribute from `p:attrNameLst` (e.g. "fillcolor", "style.color",
     * "stroke.color"). Used to determine which CSS property to animate.
     */
    targetAttribute?: string;
    /**
     * All sibling `p:animClr` behaviours authored for the same timing node.
     * The top-level fields continue to mirror the first behaviour for backwards
     * compatibility; this list is present only when there is more than one.
     */
    components?: readonly PptxColorAnimation[];
}

/**
 * A slide comment — may be a legacy positional comment or a modern
 * threaded comment with replies.
 *
 * @example
 * ```ts
 * const comment: PptxComment = {
 *   id: "c1",
 *   text: "Please update this chart.",
 *   author: "Alice",
 *   createdAt: "2024-06-01T10:00:00Z",
 *   resolved: false,
 * };
 * // => satisfies PptxComment
 * ```
 */
declare interface PptxComment {
    id: string;
    text: string;
    /** Storage vocabulary used by this comment. Omitted means legacy PresentationML. */
    format?: 'legacy' | 'modern';
    /** Stable GUID author identifier used by Office 2021 modern comments. */
    authorId?: string;
    /** Optional parent comment id for reply threading metadata. */
    parentId?: string;
    author?: string;
    createdAt?: string;
    x?: number;
    y?: number;
    /** Whether this comment has been resolved/marked done. */
    resolved?: boolean;
    /** Native p188 status token. */
    status?: 'active' | 'resolved' | 'closed';
    /** Modern comment classification tags and author IDs that liked the comment. */
    tags?: string[];
    likes?: string[];
    startDate?: string;
    dueDate?: string;
    assignedTo?: string[];
    /** Task completion in thousandths of a percent, from 0 through 100000. */
    complete?: number;
    priority?: number;
    title?: string;
    /** Modern threaded comment support (p15:threadingInfo). */
    threadId?: string;
    /** `@`-mentions, indexed into `text` (see {@link PptxCommentMention}). */
    mentions?: PptxCommentMention[];
    /** Replies to this comment (for modern threaded comments). */
    replies?: PptxComment[];
    /** ID of the element this comment is associated with (if any). */
    elementId?: string;
    /** Original `p:cm` subtree, retained for unknown child and extension preservation. */
    rawXml?: XmlObject;
}

/**
 * A comment author from `ppt/commentAuthors.xml`.
 *
 * Stores all attributes needed for lossless round-trip serialization
 * of the `p:cmAuthor` element (id, name, initials, lastIdx, clrIdx).
 *
 * @see ECMA-376 Part 1, §19.4.2 (cmAuthor)
 *
 * @example
 * ```ts
 * const author: PptxCommentAuthor = {
 *   id: "0",
 *   name: "John Doe",
 *   initials: "JD",
 *   lastIdx: 3,
 *   clrIdx: 0,
 * };
 * // => satisfies PptxCommentAuthor
 * ```
 */
declare interface PptxCommentAuthor {
    /** Unique numeric author identifier (`@_id`). */
    id: string;
    /** Author display name (`@_name`). */
    name: string;
    /** Author initials (`@_initials`). */
    initials: string;
    /** Last comment index used by this author (`@_lastIdx`). */
    lastIdx: number;
    /** Colour index assigned to this author (`@_clrIdx`). */
    clrIdx: number;
    /** Original `p:cmAuthor` subtree, retained for unknown attribute preservation. */
    rawXml?: XmlObject;
}

/**
 * A single `@`-mention inside a modern comment body.
 *
 * Offsets index into the comment's FLATTENED plain text: every `a:t` value
 * below `p188:txBody` concatenated, with paragraphs joined by `\n`. That is the
 * same string `PptxComment.text` carries, so an edit to `text` invalidates
 * every offset after the edit point and the serializer re-bases them.
 *
 * The markup Office uses for a mention is `CT_Mention` (documented for the
 * SpreadsheetML `2018/threadedcomments` part): `mentionpersonId`, `mentionId`,
 * `startIndex` and `length`. The PowerPoint `2018/8/main` schema does not
 * publish a mention element at all, so `rawXml` is retained and re-emitted
 * attribute-for-attribute: a producer that spells the attributes differently
 * still round-trips.
 *
 * @example
 * ```ts
 * const mention: PptxCommentMention = {
 *   personId: "{2CB2E9D0-D392-EB21-5D46-FBA34C1295E6}",
 *   authorName: "Bob Example",
 *   startIndex: 3,
 *   length: 11,
 * };
 * // => "Hi Bob Example can you check this".slice(3, 14) === "Bob Example"
 * ```
 */
declare interface PptxCommentMention {
    /** `mentionId`: GUID identifying this mention instance. */
    id?: string;
    /** `mentionpersonId`: the `p188:author` id of the mentioned person. */
    personId: string;
    /** Display name resolved from the author list at parse time, when known. */
    authorName?: string;
    /** Character offset of the mentioned span in the flattened plain text. */
    startIndex: number;
    /** Character length of the mentioned span. */
    length: number;
    /**
     * `uri` of the `p188:ext` this mention list was read from. Undefined means
     * the list is a direct child of `p188:cm`, which is where it is written for
     * newly authored mentions.
     */
    containerUri?: string;
    /** Original `p188:mention` node, retained for unknown-attribute preservation. */
    rawXml?: XmlObject;
}

/**
 * Common slide view properties shared by slideViewPr, outlineViewPr,
 * notesTextViewPr, and notesViewPr.
 */
declare interface PptxCommonSlideViewProperties {
    /** Whether snap-to-grid is enabled. */
    snapToGrid?: boolean;
    /** Whether snap-to-objects is enabled. */
    snapToObjects?: boolean;
    /** Whether drawing guides are shown. */
    showGuides?: boolean;
    /** Whether the application may vary the scale automatically. */
    variableScale?: boolean;
    /** Drawing guides shown in this slide view. */
    guides?: PptxViewGuide[];
    /** View origin (scroll position). */
    origin?: PptxViewOrigin;
    /** View scale. */
    scale?: PptxViewScale;
}

/**
 * A compatibility warning generated during parse or save when the
 * file uses features not fully supported by the editor.
 *
 * @example
 * ```ts
 * const warning: PptxCompatibilityWarning = {
 *   code: "UNSUPPORTED_3D",
 *   message: "3D rotation effects may not render accurately.",
 *   severity: "warning",
 *   scope: "element",
 *   slideId: "slide-1",
 *   elementId: "elem-42",
 * };
 * // => satisfies PptxCompatibilityWarning
 * ```
 */
declare interface PptxCompatibilityWarning {
    code: string;
    message: string;
    severity: 'info' | 'warning';
    scope: 'presentation' | 'slide' | 'element' | 'save';
    slideId?: string;
    elementId?: string;
    xmlPath?: string;
}

/**
 * Core document properties from `docProps/core.xml` (Dublin Core + OOXML).
 *
 * @example
 * ```ts
 * const core: PptxCoreProperties = {
 *   title: "Q4 Business Review",
 *   creator: "Alice",
 *   created: "2024-01-15T08:00:00Z",
 *   modified: "2024-06-01T12:30:00Z",
 *   lastModifiedBy: "Bob",
 * };
 * // => satisfies PptxCoreProperties
 * ```
 */
declare interface PptxCoreProperties {
    /** dc:title */
    title?: string;
    /** dc:subject */
    subject?: string;
    /** dc:creator */
    creator?: string;
    /** cp:keywords */
    keywords?: string;
    /** dc:description */
    description?: string;
    /** cp:lastModifiedBy */
    lastModifiedBy?: string;
    /** cp:revision */
    revision?: string;
    /** dcterms:created (ISO 8601) */
    created?: string;
    /** dcterms:modified (ISO 8601) */
    modified?: string;
    /** cp:category */
    category?: string;
    /** cp:contentStatus */
    contentStatus?: string;
}

/**
 * Shape names used for crop-to-shape (CSS `clip-path` equivalent).
 *
 * @example
 * ```ts
 * const shape: PptxCropShape = "ellipse";
 * // => "ellipse": one of: none | ellipse | roundedRect | triangle | diamond | pentagon | hexagon | star
 * ```
 */
declare type PptxCropShape = 'none' | 'ellipse' | 'roundedRect' | 'triangle' | 'diamond' | 'pentagon' | 'hexagon' | 'star';

declare interface PptxCustomDashSegment {
    /** Dash length as a non-negative percentage in thousandths of one percent. */
    dash: number;
    /** Space length as a non-negative percentage in thousandths of one percent. */
    space: number;
}

/**
 * A customer data reference from `p:custDataLst / p:custData`.
 *
 * Enterprise add-ins and integrations store custom data parts in the
 * package and reference them via relationship IDs in the slide or
 * presentation XML.
 *
 * @see ECMA-376 Part 1, §19.2.1.3 (custDataLst), §19.3.1.6 (custData)
 */
declare interface PptxCustomerData {
    /** Resolved part path inside the package (e.g. `customXml/item1.xml`). */
    id?: string;
    /** Relationship ID referencing the custom data part. */
    relId?: string;
    /** Raw string content of the custom data part (if resolvable). */
    data?: string;
    /** OPC content type for the custom data part. */
    contentType?: string;
    /** Raw `p:custData` XML retained for unknown-node preservation. */
    rawXml?: XmlObject;
}

/**
 * Custom (non-preset) geometry path — only on shapes and pictures.
 *
 * Contains SVG path data and/or structured custom geometry paths
 * parsed from `a:custGeom/a:pathLst`.
 *
 * @example
 * ```ts
 * const custom: PptxCustomPathProperties = {
 *   pathData: "M 0 0 L 100 0 L 100 100 Z",
 *   pathWidth: 100,
 *   pathHeight: 100,
 * };
 * // => satisfies PptxCustomPathProperties
 * ```
 */
declare interface PptxCustomPathProperties {
    /** SVG path data for custom shapes. */
    pathData?: string;
    /** Coordinate-space width for the custom path. */
    pathWidth?: number;
    /** Coordinate-space height for the custom path. */
    pathHeight?: number;
    /** Structured custom geometry paths for editing (maps to a:custGeom/a:pathLst). */
    customGeometryPaths?: CustomGeometryPath[];
    /** Raw adjustment/guide/handle/connection/text-rectangle XML preserved for serialization. */
    customGeometryRawData?: CustomGeometryRawData;
    /**
     * Typed XY adjustment handles parsed from `a:custGeom/a:ahLst/a:ahXY`.
     * SDK-built shapes can populate this and the writer will emit `<a:ahXY>` entries
     * even when no raw XML was preserved.
     */
    customGeometryAdjustHandlesXY?: AdjustHandleXY[];
    /**
     * Typed polar adjustment handles parsed from `a:custGeom/a:ahLst/a:ahPolar`.
     */
    customGeometryAdjustHandlesPolar?: AdjustHandlePolar[];
    /**
     * Typed connection sites parsed from `a:custGeom/a:cxnLst/a:cxn`.
     */
    customGeometryConnectionSites?: ConnectionSite[];
    /**
     * Typed text rectangle parsed from `a:custGeom/a:rect`. When present this is
     * preferred over {@link customGeometryRawData}'s `rectXml` on save.
     */
    customGeometryTextRect?: CustomGeometryTextRect;
}

/**
 * A custom document property from `docProps/custom.xml`.
 *
 * @example
 * ```ts
 * const prop: PptxCustomProperty = {
 *   name: "Project",
 *   value: "pptx",
 *   type: "lpwstr",
 * };
 * // => satisfies PptxCustomProperty
 * ```
 */
declare interface PptxCustomProperty {
    /** Property name. */
    name: string;
    /** Property value (always stringified). */
    value: string;
    /** Original VT type (e.g. "lpwstr", "i4", "bool", "filetime"). */
    type: string;
}

/**
 * A named custom slide show (`p:custShowLst / p:custShow`).
 *
 * Custom shows define ordered subsets of slides that can be presented
 * independently of the full deck.
 *
 * @example
 * ```ts
 * const show: PptxCustomShow = {
 *   name: "Executive Summary",
 *   id: "0",
 *   slideRIds: ["rId2", "rId5", "rId8"],
 * };
 * // => satisfies PptxCustomShow
 * ```
 */
declare interface PptxCustomShow {
    /** Custom show name. */
    name: string;
    /** Custom show id. */
    id: string;
    /** Ordered list of slide relationship IDs included in this custom show. */
    slideRIds: string[];
    /** Original `p:custShow` subtree used to preserve unmodelled attributes and extensions. */
    rawXml?: XmlObject;
}

/**
 * Embedded font data extracted from a PPTX file.
 *
 * Used to register `@font-face` rules so the renderer can display
 * the correct typeface even when the system font is missing.
 *
 * @example
 * ```ts
 * const font: PptxEmbeddedFont = {
 *   name: "CustomSans",
 *   dataUrl: "data:font/truetype;base64,AAEAK...",
 *   format: "truetype",
 * };
 * // => satisfies PptxEmbeddedFont
 * ```
 */
/**
 * A single Custom XML Data Part stored in `customXml/` within the OPC package.
 *
 * These parts are used by add-ins, data-binding, and enterprise templates
 * to store structured data alongside the presentation.
 *
 * @see ECMA-376 Part 1, §15.2.5
 */
declare interface PptxCustomXmlPart {
    /** Item number (e.g. "1" for `customXml/item1.xml`). */
    id: string;
    /** Raw XML string content of the custom XML item. */
    data: string;
    /** Schema target namespace URI from `itemProps` (ds:schemaRef/@ds:uri). */
    schemaUri?: string;
    /** Raw XML string content of the associated `itemProps` file. */
    properties?: string;
    /** Raw XML string content of the OPC relationship file (`customXml/_rels/item{id}.xml.rels`). */
    rels?: string;
}

/**
 * A single breakpoint in a ChartEx colour-by-value scale
 * (`cx:valueColorPositions/cx:colorPosition`). `kind` selects which of
 * CT_ColorPosition's union members was authored; `value` is absent for
 * `min`/`max` (they are implicit endpoints) and required otherwise.
 */
declare interface PptxCxValueColorPosition {
    kind: 'min' | 'max' | 'number' | 'percent';
    value?: number;
}

/**
 * Root data structure returned by {@link PptxHandlerCore.load}.
 *
 * Contains every slide, canvas dimensions, theme data, layout options,
 * metadata, and optional features (custom shows, sections, macros,
 * digital signatures, embedded fonts).
 *
 * @example
 * ```ts
 * const data: PptxData = await handler.load(buffer);
 * console.log(`${data.slides.length} slides, ${data.width}×${data.height}`);
 * // => e.g. "24 slides, 960×540"
 * ```
 */
declare interface PptxData {
    slides: PptxSlide[];
    width: number;
    height: number;
    /** Slide width in EMU (for save round-trip). */
    widthEmu?: number;
    /** Slide height in EMU (for save round-trip). */
    heightEmu?: number;
    /** Slide size type from `p:sldSz/@type` (e.g. "screen4x3", "screen16x9", "custom"). */
    slideSizeType?: string;
    /** Notes page width in EMU (from `p:notesSz`). */
    notesWidthEmu?: number;
    /** Notes page height in EMU (from `p:notesSz`). */
    notesHeightEmu?: number;
    layoutOptions?: PptxLayoutOption[];
    headerFooter?: PptxHeaderFooter;
    /** Presentation-level properties parsed from `presentationPr.xml`. */
    presentationProperties?: PptxPresentationProperties;
    /** Named custom slide shows from `p:custShowLst`. */
    customShows?: PptxCustomShow[];
    /** Ordered presentation sections from `p:sectionLst` / `p14:sectionLst`. */
    sections?: PptxSection[];
    warnings?: PptxCompatibilityWarning[];
    /** Map of theme colour scheme keys to resolved hex values. */
    themeColorMap?: Record<string, string>;
    /** Full parsed theme object with colours, fonts, and name. */
    theme?: PptxTheme;
    /** Available theme parts discovered in `ppt/theme/`. */
    themeOptions?: PptxThemeOption[];
    /** Parsed table style definitions from `ppt/tableStyles.xml`. */
    tableStyleMap?: ParsedTableStyleMap;
    /**
     * The current default table style GUID (`ppt/tableStyles.xml`'s
     * `a:tblStyleLst/@def`): the style PowerPoint applies to a newly inserted
     * table. Matches `PptxSaveOptions.tableStylesDefaultId` so a save call
     * that omits it can fall back to what was loaded.
     */
    tableStylesDefaultId?: string;
    /** Whether the presentation is password-protected. */
    isPasswordProtected?: boolean;
    /** Embedded font data (name + binary data URL) extracted from the presentation. */
    embeddedFonts?: PptxEmbeddedFont[];
    /** Typed `p:embeddedFontLst` package metadata, including unresolved variants. */
    embeddedFontList?: PptxEmbeddedFontList;
    /**
     * `p:presentation/@embedTrueTypeFonts` (ECMA-376 §19.2.1.26): the author's
     * saved preference that TrueType fonts referenced by the deck be embedded.
     * `undefined` when the attribute is absent (spec default `false`).
     *
     * This is purely declarative in this library: fonts are only ever embedded
     * when the caller explicitly supplies `embeddedFontList`/`embeddedFonts`
     * (there is no automatic embed-on-save), so toggling this flag does not
     * gate any embedding behaviour of its own here - it only round-trips the
     * author's stated preference, the same way real PowerPoint reads it back
     * as a checkbox state rather than a trigger. See `@saveSubsetFonts`,
     * which is a separate, deliberately unimplemented flag (no glyph
     * subsetting) that does not interact with this one.
     */
    embedTrueTypeFonts?: boolean;
    /**
     * Presentation-level default text style (`p:defaultTextStyle`): the
     * last-resort paragraph/run-property fallback for every shape (placeholder
     * or not) whose local and inherited cascade leaves a field undefined.
     * Keyed the same way as {@link PptxMasterTextStyles} categories: `-1` is
     * `a:defPPr`, `0`-`8` are `a:lvl1pPr`-`a:lvl9pPr`.
     */
    defaultTextStyle?: PptxTextStyleLevels;
    /** Most-recently-used colour list from presentation properties. */
    mruColors?: string[];
    /** Parsed notes master data if present in the PPTX. */
    notesMaster?: PptxNotesMaster;
    /** Parsed handout master data if present in the PPTX. */
    handoutMaster?: PptxHandoutMaster;
    /** Structured slide master data for each master in the presentation. */
    slideMasters?: PptxSlideMaster[];
    /** Parsed tag collections attached to the presentation or slides. */
    tags?: PptxTagCollection[];
    /** Custom document properties from `docProps/custom.xml`. */
    customProperties?: PptxCustomProperty[];
    /** Core document properties from `docProps/core.xml`. */
    coreProperties?: PptxCoreProperties;
    /** Extended (application) properties from `docProps/app.xml`. */
    appProperties?: PptxAppProperties;
    /** Whether the presentation contains VBA macros (is a .pptm file). */
    hasMacros?: boolean;
    /** Whether the presentation contains digital signatures (`_xmlsignatures/` parts). */
    hasDigitalSignatures?: boolean;
    /** Number of digital signatures found. */
    digitalSignatureCount?: number;
    /** Presentation-level drawing guides from `p:extLst`. */
    presentationGuides?: PptxDrawingGuide[];
    /** View properties from `ppt/viewProps.xml`. */
    viewProperties?: PptxViewProperties;
    /** Write-protection verifier from `p:modifyVerifier` in `presentation.xml`. */
    modifyVerifier?: PptxModifyVerifier;
    /** Photo album metadata from `p:photoAlbum` in `presentation.xml`. */
    photoAlbum?: PptxPhotoAlbum;
    /**
     * Legacy Smart Tags recognizer reference from `p:smartTags` in
     * `presentation.xml`. Read-only: there is no data model for the
     * recognizer part's own content, so this exists to make the reference
     * inspectable and to prove it survives a save (the owning part and its
     * relationship are preserved passively, like any other unmodelled part).
     */
    smartTags?: PptxSmartTagsReference;
    /** East Asian line-break settings from `p:kinsoku` in `presentation.xml`. */
    kinsoku?: PptxKinsoku;
    /** Custom XML data parts from `customXml/` in the OPC package. */
    customXmlParts?: PptxCustomXmlPart[];
    /** Customer data references from `p:custDataLst` in `presentation.xml`. */
    customerData?: PptxCustomerData[];
    /** Thumbnail image binary data from `docProps/thumbnail.{jpeg,png}`. */
    thumbnailData?: Uint8Array;
    /** Comment authors parsed from `ppt/commentAuthors.xml` for round-trip preservation. */
    commentAuthors?: PptxCommentAuthor[];
    /** Office 2021 p188 authors from the modern Author part. */
    modernCommentAuthors?: PptxModernCommentAuthor[];
    /**
     * OOXML conformance class of the loaded file.
     * - `'strict'` -- ISO/IEC 29500 Strict (uses `purl.oclc.org` namespace URIs)
     * - `'transitional'` -- ECMA-376 Transitional (uses `schemas.openxmlformats.org` URIs)
     *
     * When saving, if the save option `conformance` is `'preserve'` (default),
     * the file will be saved using the same conformance class as the original.
     */
    conformance?: 'strict' | 'transitional';
}

/**
 * A drawing guide parsed from OOXML extension lists.
 *
 * Slide-level and presentation-level guides are shown as thin coloured
 * lines that help users align elements.
 *
 * @example
 * ```ts
 * const guide: PptxDrawingGuide = {
 *   id: "g1",
 *   orientation: "horz",
 *   positionEmu: 457200,
 *   color: "#FF0000",
 * };
 * // => { id: "g1", orientation: "horz", positionEmu: 457200, color: "#FF0000" } satisfies PptxDrawingGuide
 * ```
 */
declare interface PptxDrawingGuide {
    /** Unique identifier (from `@_id` attribute or generated). */
    id: string;
    /** Orientation: horizontal or vertical. */
    orientation: 'horz' | 'vert';
    /** Position in EMU (converted from pos attribute). */
    positionEmu: number;
    /** Optional guide colour as hex string (e.g. "#FF0000"). */
    color?: string;
}

/**
 * A single element on a PPTX slide.
 *
 * This is a **discriminated union**: narrow on `element.type` to access
 * variant-specific properties like `imageData` (image/picture), `pathData`
 * (shape), or `textSegments` (text/shape).
 */
declare type PptxElement = TextPptxElement | ShapePptxElement | ConnectorPptxElement | ImagePptxElement | PicturePptxElement | TablePptxElement | ChartPptxElement | SmartArtPptxElement | OlePptxElement | MediaPptxElement | GroupPptxElement | InkPptxElement | ContentPartPptxElement | ZoomPptxElement | Model3DPptxElement | UnknownPptxElement;

/**
 * High-level animation data associated with a slide element.
 *
 * Combines entrance, exit, and emphasis presets with timing and
 * trigger configuration. Used by the editor’s animation panel
 * and the `setPptxElementAnimation` tool.
 *
 * @example
 * ```ts
 * const anim: PptxElementAnimation = {
 *   elementId: "title_1",
 *   entrance: "fadeIn",
 *   durationMs: 600,
 *   order: 1,
 *   trigger: "afterPrevious",
 * };
 * // => { elementId: "title_1", entrance: "fadeIn", durationMs: 600, order: 1, trigger: "afterPrevious" }
 * ```
 */
declare interface PptxElementAnimation {
    elementId: string;
    entrance?: PptxAnimationPreset;
    exit?: PptxAnimationPreset;
    emphasis?: PptxAnimationPreset;
    durationMs?: number;
    delayMs?: number;
    order?: number;
    /**
     * The {@link order} the loader derived from the slide's `p:timing` tree for
     * an entry whose `pptx:editorMeta` record authored no `@order`. The tree
     * already expresses that position (and every load re-derives it), so the
     * writer omits `@order` while `order` still equals this value; a reorder
     * changes `order` and the attribute is written again. Load-time bookkeeping
     * only; never set it by hand.
     */
    orderFromTimeline?: number;
    trigger?: PptxAnimationTrigger;
    /**
     * Shape ID that triggers this animation: the shape clicked for
     * `onShapeClick`, or the media element whose bookmark fires it for
     * `onMediaBookmark`.
     */
    triggerShapeId?: string;
    /** Bookmark name (`p14:bmk/@name`) an `onMediaBookmark` trigger waits for. */
    triggerBookmark?: string;
    timingCurve?: PptxAnimationTimingCurve;
    repeatCount?: number;
    repeatMode?: PptxAnimationRepeatMode;
    /** Direction for directional effects (fly in/out, wipe, etc.). */
    direction?: PptxAnimationDirection;
    /** Sequence mode — animate as one object or by paragraph/word/letter. */
    sequence?: PptxAnimationSequence;
    /** What happens after the animation finishes playing. */
    afterAnimation?: PptxAfterAnimationAction;
    /** Dim-to color hex (used when afterAnimation is "dimToColor"). */
    afterAnimationColor?: string;
    /** SVG motion path string for custom motion path animations. */
    motionPath?: string;
    /**
     * Path edit mode for `p:animMotion/@pathEditMode`. Defaults to "relative"
     * when emitted without an explicit value.
     */
    motionPathEditMode?: string;
    /** Comma-separated point-types string for `p:animMotion/@ptsTypes`. */
    motionPtsTypes?: string;
    /** Authored path rotation in degrees from `p:animMotion/@rAng`. */
    motionPathRotationAngle?: number;
    /** Motion-path rotation centre X in slide percentage units (`p:rCtr/@x`). */
    motionPathRotationCenterX?: number;
    /** Motion-path rotation centre Y in slide percentage units (`p:rCtr/@y`). */
    motionPathRotationCenterY?: number;
    /**
     * Sound relationship ID to play when animation triggers. Written on save
     * as a `p:audio/p:cMediaNode` sibling of the effect's own `p:childTnLst`
     * (see `PptxNativeAnimation.soundRId` for the COM-verified detail).
     */
    soundRId?: string;
    /** Resolved sound file path from relationship. */
    soundPath?: string;
    /**
     * The `@_name` to write on the embedded sound (`p:sndTgt`). For a stock
     * gallery pick this is the exact PowerPoint file name (e.g.
     * `"CHIMES.WAV"`), which is what makes PowerPoint itself recognise the
     * sound as that built-in entry when it reopens the saved deck (there is no
     * separate "built-in" flag anywhere in the schema). Set by
     * `pptx-viewer-shared`'s `setEffectSound` when the pick carries a
     * `soundName`; absent for a custom file with no meaningful name.
     */
    soundName?: string;
    /** Whether to stop any currently playing sound (`p:endSnd`). */
    stopSound?: boolean;
    /**
     * Pending, not-yet-embedded sound chosen in the authoring UI, as a
     * `data:audio/...;base64,...` URL. Mirrors the `imageData` /
     * `mediaData` pending-embed convention used elsewhere in the typed model:
     * on save, the writer converts this to real bytes under `ppt/media/`,
     * mints a relationship, and replaces this field with the resolved
     * {@link soundRId} / {@link soundPath}. Cleared once embedded.
     */
    soundData?: string;
    /**
     * Display name for the chosen sound (e.g. the uploaded file's name),
     * shown by the authoring UI's sound picker. Purely cosmetic; has no
     * OOXML equivalent and is not required for playback. For a stock gallery
     * pick, the UI derives its label from {@link soundName} via the catalogue
     * instead of this field.
     */
    soundFileName?: string;
    /**
     * Per-build-level timing template(s) from the {@link sequence}'s own
     * `p:bldP/p:tmplLst` (ECMA-376 §19.5.84), carried over from the loaded
     * `PptxNativeAnimation.buildTemplates` this element animation was derived
     * from so a full timing-tree rebuild (`PptxAnimationWriteService`'s
     * `buildTimingXml`, when the slide had no prior `p:timing`) can re-emit
     * them instead of silently dropping the deck's authored per-level
     * defaults. Absent when {@link sequence} carries no such template.
     */
    buildTemplates?: PptxTimingTemplate[];
}

/**
 * Properties shared by **every** element on a slide.
 *
 * Position and size are in pixels (converted from EMU at parse time).
 * Optional properties apply to subsets of elements or may be absent in
 * the original OOXML.
 *
 * @example
 * ```ts
 * const base: PptxElementBase = {
 *   id: "el_001",
 *   x: 100, y: 50,
 *   width: 400, height: 200,
 *   rotation: 15,
 *   opacity: 0.9,
 * };
 * // => satisfies PptxElementBase
 * ```
 */
declare interface PptxElementBase {
    id: string;
    /**
     * The shape's native OOXML id from `p:cNvPr/@id` (an unsigned integer, as a
     * string), captured on load. Distinct from {@link id}, which is a synthetic
     * positional identity (`${slidePath}-shape-${index}`) the loader assigns for
     * selection / undo / template tracking. Animations target shapes by this
     * native id (`p:spTgt/@spid`), so it is the stable key used to reconcile an
     * animation to the element it animates across a save/reload round trip.
     * Absent on SDK-created elements until one is minted at save time.
     */
    shapeId?: string;
    /** Element name from `cNvPr/@name`. Used for morph transition matching via the `!!` naming convention. */
    name?: string;
    /**
     * `p:nvSpPr/p:nvPr/p:ph/@type` (lower-cased) when the shape is a placeholder:
     * `title`, `ctrtitle`, `body`, `subtitle`, `ftr`, `dt`, `sldnum`, ...
     *
     * Captured on load so consumers can tell a footer placeholder from a text box
     * without re-walking `rawXml`. Absent on non-placeholder shapes and on
     * SDK-created elements.
     */
    placeholderType?: string;
    /**
     * `p:nvSpPr/p:nvPr/p:ph/@sz` (lower-cased): `"full"`, `"half"`, or
     * `"quarter"`. Captured on load for round-trip completeness. Per
     * ECMA-376 §19.3.1.36 (CT_Placeholder) this size hint is only meaningful
     * when NO `a:xfrm` exists anywhere in the placeholder's inheritance
     * chain (slide -> layout -> master); every real-world corpus placeholder
     * that carries `@sz` already has an explicit `a:xfrm` at the master
     * level, so no renderer currently derives a size from this field.
     */
    placeholderSz?: string;
    /**
     * `p:nvSpPr/p:nvPr/p:ph/@orient` (only `"vert"` is meaningful per
     * `ST_Direction`). Captured on load for round-trip completeness. In
     * practice every placeholder observed with `orient="vert"` also carries
     * an explicit `a:bodyPr/@vert`, which already drives vertical-text
     * rendering, so this field is not currently read by any renderer.
     */
    placeholderOrient?: 'vert';
    x: number;
    y: number;
    width: number;
    height: number;
    /**
     * The exact EMU integer `x` was parsed from (the `a:off/@_x` this
     * element's own `a:xfrm` carried on load), when the parser could resolve
     * one. `x` itself is always `Math.round(xEmu / EMU_PER_PX)` at parse
     * time, but that rounding is lossy: re-deriving EMU from `x` on save
     * (`Math.round(x * EMU_PER_PX)`) can drift from the original value by up
     * to half a pixel's worth of EMU on every load/save cycle even when
     * nothing touched this element. Kept alongside `x` (not instead of it) so
     * every consumer that only cares about on-screen position is unaffected;
     * only the save-side xfrm writer (`resolveXfrmEmu` in
     * `xfrm-emu-resolution.ts`) reads this, and only when `x` still equals
     * `Math.round(xEmu / EMU_PER_PX)` (i.e. nothing moved this element since
     * load) does it re-emit `xEmu` verbatim instead of re-quantizing `x`.
     * `undefined` for an SDK-created element or one whose transform could not
     * be resolved to a usable `a:off` on load.
     */
    xEmu?: number;
    /** The exact EMU integer `y` was parsed from (`a:off/@_y`). See {@link xEmu}. */
    yEmu?: number;
    /** The exact EMU integer `width` was parsed from (`a:ext/@_cx`). See {@link xEmu}. */
    widthEmu?: number;
    /** The exact EMU integer `height` was parsed from (`a:ext/@_cy`). See {@link xEmu}. */
    heightEmu?: number;
    /** Resolved load-time transform for a shape with no own a:xfrm. Used only to detect edits. */
    inheritedTransform?: Pick<PptxElementBase, 'x' | 'y' | 'width' | 'height' | 'rotation' | 'skewX' | 'skewY' | 'flipHorizontal' | 'flipVertical'>;
    rotation?: number;
    /** Skew along the X axis in degrees (parsed from `@_skewX` in 1/60000ths of a degree). */
    skewX?: number;
    /** Skew along the Y axis in degrees (parsed from `@_skewY` in 1/60000ths of a degree). */
    skewY?: number;
    flipHorizontal?: boolean;
    flipVertical?: boolean;
    /** Whether this element is hidden (used by the Elements Panel visibility toggle). */
    hidden?: boolean;
    /** Element-level opacity (0-1). */
    opacity?: number;
    rawXml?: XmlObject;
    /** Shape-level click action (from `a:hlinkClick` on `p:cNvPr`). */
    actionClick?: PptxAction;
    /** Shape-level hover action (from `a:hlinkHover` on `p:cNvPr`). */
    actionHover?: PptxAction;
    /** Shape lock attributes parsed from `p:cNvSpPr/a:spLocks`. */
    locks?: PptxShapeLocks;
    /**
     * Opaque `<a:ext>` children captured from the shape's `<a:extLst>` whose
     * URI is not recognised by a typed extractor (hidden fill/line, image
     * effects, …). Preserved verbatim and re-emitted on save so unknown
     * vendor extensions survive a round-trip.
     *
     * Mirrors the existing `effectDagXml` / `endParaRunProperties` raw-XML
     * preservation pattern.
     */
    extLstXml?: XmlObject[];
}

declare interface PptxEmbeddedFont {
    name: string;
    dataUrl: string;
    bold?: boolean;
    italic?: boolean;
    /** CSS font format hint (e.g. "truetype", "opentype"). */
    format?: 'truetype' | 'opentype' | 'woff' | 'woff2';
    /**
     * Deobfuscated (clear-text) font binary data preserved from load
     * for round-trip re-embedding on save. When present, the save
     * pipeline will re-obfuscate and write this data back into the ZIP.
     */
    rawFontData?: Uint8Array;
    /**
     * Original ZIP path of the font part (e.g. `ppt/fonts/{GUID}.fntdata`).
     * Preserved from load for round-trip.
     */
    partPath?: string;
    /**
     * The GUID used for obfuscation, either from the `fontKey` attribute
     * or extracted from the part path. Preserved from load for round-trip.
     */
    fontGuid?: string;
    /**
     * Relationship ID (e.g. `rId21`) of the font part in
     * `ppt/_rels/presentation.xml.rels`. Preserved from load so the save
     * pipeline can reuse the original part/rel instead of minting a new
     * GUID-named copy alongside the stale original.
     */
    originalRId?: string;
    /**
     * Raw bytes of the original obfuscated font part exactly as they were
     * stored in the source ZIP. When the loader could not determine a
     * usable GUID (e.g. EOT extraction path), the save pipeline preserves
     * these bytes verbatim under the original path/rel.
     */
    originalPartBytes?: Uint8Array;
}

declare interface PptxEmbeddedFontDataId {
    /** Required relationship identifier from `r:id`. */
    relationshipId?: string | null;
    /** Original leaf retained for unknown attribute preservation. */
    rawXml?: XmlObject;
}

declare interface PptxEmbeddedFontDescriptor {
    typeface?: string | null;
    panose?: string | null;
    pitchFamily?: string | null;
    charset?: string | null;
    rawXml?: XmlObject;
}

declare interface PptxEmbeddedFontList {
    fonts: PptxEmbeddedFontListEntry[];
    /** Original list retained for unknown attribute and child preservation. */
    rawXml?: XmlObject;
}

declare interface PptxEmbeddedFontListEntry {
    font: PptxEmbeddedFontDescriptor;
    regular?: PptxEmbeddedFontDataId | null;
    bold?: PptxEmbeddedFontDataId | null;
    italic?: PptxEmbeddedFontDataId | null;
    boldItalic?: PptxEmbeddedFontDataId | null;
    rawXml?: XmlObject;
}

/** Parsed data extracted from an embedded xlsx workbook. */
declare interface PptxEmbeddedWorkbookData {
    /** Category labels from the first column/row. */
    categories: string[];
    /** Data series extracted from worksheet cells. */
    series: Array<{
        name: string;
        values: number[];
    }>;
    /** Whether the workbook uses the 1904 date system. */
    date1904?: boolean;
}

/**
 * Target format for slide export.
 *
 * @see {@link PptxExportOptions}
 */
declare type PptxExportFormat = 'pdf' | 'png' | 'svg';

/**
 * Options controlling slide export to raster or vector formats.
 *
 * @example
 * ```ts
 * const opts: PptxExportOptions = {
 *   format: "png",
 *   slideIndices: [0, 2, 4],
 *   dpi: 300,
 * };
 * // => satisfies PptxExportOptions
 * ```
 */
declare interface PptxExportOptions {
    /** Target format. */
    format: PptxExportFormat;
    /** Slide indices to export (0-based). If omitted, all slides are exported. */
    slideIndices?: number[];
    /** Output width in pixels (for PNG). Height is derived from aspect ratio. */
    width?: number;
    /** DPI for raster export (default 150). */
    dpi?: number;
    /** Whether to include hidden slides. */
    includeHidden?: boolean;
}

/**
 * External data source reference for a chart (c:externalData).
 *
 * Charts can reference an external Excel workbook via a relationship ID
 * that points to an external file (TargetMode="External"). The
 * `autoUpdate` flag indicates whether the chart should refresh its
 * cached data from the external source on open.
 *
 * @example
 * ```ts
 * const ext: PptxExternalData = {
 *   relId: "rId2",
 *   targetPath: "file:///C:/Data/budget.xlsx",
 *   autoUpdate: true,
 * };
 * // => satisfies PptxExternalData
 * ```
 */
declare interface PptxExternalData {
    /** Relationship ID referencing the external data source in the chart .rels. */
    relId: string;
    /** Resolved external file path or URL from the relationship target. */
    targetPath?: string;
    /** Whether to auto-update data from the external source on open. */
    autoUpdate?: boolean;
    /** Raw binary data of the embedded xlsx workbook (from ppt/embeddings/). */
    embeddedWorkbookData?: Uint8Array;
}

/** Nested build choice carried by `p:bldGraphic`. */
declare type PptxGraphicBuild = {
    mode: 'asOne';
    rawXml?: XmlObject;
} | {
    mode: 'sub';
    kind: 'diagram';
    build: string;
    reverse: boolean;
    rawXml?: XmlObject;
} | {
    mode: 'sub';
    kind: 'chart';
    build: string;
    animateBackground: boolean;
    rawXml?: XmlObject;
};

/**
 * A single unrecognised `<a:graphicData>/<a:extLst>/<a:ext>` extension on a
 * graphicFrame, captured verbatim so the round-trip can preserve future or
 * vendor-specific markup that the parser doesn't yet understand.
 *
 * The XML is preserved as a fast-xml-parser object tree (the same shape as
 * `rawXml` on other elements) so the save layer can re-emit it through the
 * existing builder without lossy string manipulation.
 */
declare interface PptxGraphicFrameExtension {
    /** The `@_uri` attribute identifying the extension (e.g. `{C3CD43...}`). */
    uri: string;
    /** Parsed XML payload of the extension, suitable for re-serialization. */
    xml: XmlObject;
}

/** Positive grid spacing from `p:gridSpacing`. */
declare interface PptxGridSpacing {
    cx: number;
    cy: number;
}

/**
 * Public facade for the PPTX editor handler.
 *
 * The implementation lives in `PptxHandlerCore` so this surface can stay small,
 * stable, and easy to replace with alternate implementations in the future.
 */
declare class PptxHandler extends PptxHandlerCore {
    /**
     * Create a new blank PPTX presentation from scratch.
     *
     * This is a convenience static method that delegates to
     * {@link PresentationBuilder.create}. The returned handler is fully
     * initialized and ready for editing, adding slides, and saving.
     *
     * @param options - Optional slide dimensions, theme, and metadata.
     * @returns Handler, parsed data, and a slide builder factory.
     *
     * @example
     * ```ts
     * const { handler, data, createSlide } = await PptxHandler.createBlank({
     *   title: "My Deck",
     *   theme: { colors: { accent1: "#FF6B6B" } },
     * });
     *
     * data.slides.push(
     *   createSlide("Blank")
     *     .addText("Hello", { fontSize: 36 })
     *     .build()
     * );
     *
     * const bytes = await handler.save(data.slides);
     * ```
     */
    static createBlank(options?: PresentationOptions): Promise<PresentationBuilderResult>;
    /**
     * Create a new PPTX presentation from scratch.
     *
     * Alias for {@link createBlank}. Generates a valid minimal OpenXML
     * package and returns a fully initialized handler ready for editing,
     * adding slides, and saving.
     *
     * @param options - Optional slide dimensions, theme, metadata,
     *   and initial slide count.
     * @returns Handler, parsed data, and a slide builder factory.
     *
     * @example
     * ```ts
     * const { handler, data, createSlide } = await PptxHandler.create({
     *   title: "Q4 Report",
     *   initialSlideCount: 3,
     *   theme: { colors: { accent1: "#FF6B6B" } },
     * });
     *
     * // The presentation already has 3 blank slides
     * console.log(data.slides.length); // => 3
     *
     * // Add more slides with content
     * data.slides.push(
     *   createSlide("Blank")
     *     .addText("Hello", { fontSize: 36 })
     *     .build()
     * );
     *
     * const bytes = await handler.save(data.slides);
     * ```
     */
    static create(options?: PresentationOptions): Promise<PresentationBuilderResult>;
    /**
     * Parse a presentation from an `ArrayBuffer`, accepting both `.pptx`
     * archives and portable `pptx-viewer-json` documents.
     *
     * The buffer is sniffed first: JSON documents (leading `{` plus the
     * `"pptx-viewer-json"` format marker) are routed to {@link loadFromJson};
     * everything else goes through the regular ZIP/OLE2 pipeline.
     */
    load(data: ArrayBuffer, options?: PptxHandlerLoadOptions): Promise<PptxData>;
    /**
     * Load a presentation from `pptx-viewer-json` text.
     *
     * A minimal blank package is generated and loaded first so that the
     * handler keeps a valid in-memory archive (editing and {@link save} keep
     * working), then the imported model is overlaid on top: imported
     * presentation fields win, and the slide array is replaced wholesale.
     */
    loadFromJson(text: string, options?: PptxHandlerLoadOptions): Promise<PptxData>;
}

/**
 * Thin facade over the PPTX runtime implementation.
 *
 * All heavy parsing, serialisation, and XML manipulation is delegated to an
 * {@link IPptxHandlerRuntime}. This surface stays stable and small so that
 * callers remain decoupled from the runtime internals and host-specific
 * runtime swaps (e.g. WASM vs Node) can be done transparently.
 *
 * @remarks
 * - Constructed once per open document.
 * - Errors from encrypted files are caught at `load()` time via
 *   {@link EncryptedFileError}.
 * - `PptxXmlBuilder` instances returned by `createXmlBuilder()` / `Builder()`
 *   operate directly on the runtime’s in-memory ZIP.
 *
 * @example
 * ```ts
 * const handler = new PptxHandlerCore();
 * const data    = await handler.load(arrayBuffer);
 * // ... mutate slides ...
 * const out     = await handler.save(data.slides);
 * // => Uint8Array of the modified .pptx file
 * ```
 */
declare class PptxHandlerCore {
    private readonly runtime;
    /**
     * Create a new handler, optionally injecting a custom runtime.
     *
     * Resolution order:
     * 1. `dependencies.runtime` — use as-is.
     * 2. `dependencies.runtimeFactory` — call `createRuntime()` once.
     * 3. Fall back to {@link createDefaultPptxHandlerRuntime}.
     *
     * @param dependencies - Optional runtime or factory override.
     *
     * @example
     * ```ts
     * const core = new PptxHandlerCore();
     * // => PptxHandlerCore instance with default runtime
     * ```
     */
    constructor(dependencies?: PptxHandlerCoreDependencies);
    /**
     * Release all resources held by this handler instance.
     *
     * Revokes every Blob URL created for images/media, clears all
     * in-memory caches, and releases the in-memory ZIP archive.
     *
     * Call this when the handler is no longer needed (e.g. component
     * unmount) to free memory immediately rather than waiting for GC.
     *
     * After calling `dispose()`, do not call any other methods — create
     * a new `PptxHandler` instance instead.
     */
    dispose(): void;
    /**
     * Return any compatibility warnings detected during the most recent load.
     *
     * Warnings indicate features the editor cannot fully represent (e.g.
     * SmartArt, 3-D effects, embedded OLE objects).
     *
     * @returns Array of {@link PptxCompatibilityWarning} objects.
     */
    getCompatibilityWarnings(): PptxCompatibilityWarning[];
    /**
     * Get the slide layout options available in the loaded presentation.
     *
     * Each option maps to a `<p:sldLayout>` inside the PPTX archive.
     *
     * @returns Array of {@link PptxLayoutOption} entries.
     */
    getLayoutOptions(): PptxLayoutOption[];
    /**
     * Build the artwork thumbnails backing the New Slide / Layout galleries.
     *
     * Parsing happens on first request and is memoised afterwards, so opening
     * the gallery costs one pass over the layout parts and reopening it costs
     * nothing. Callers that only need one entry should prefer
     * {@link getLayoutPreview}.
     *
     * @param layoutPaths - Restrict the result to these layouts; defaults to
     *   every layout in the presentation.
     * @returns One {@link PptxLayoutPreview} per resolvable layout.
     */
    getLayoutPreviews(layoutPaths?: readonly string[]): Promise<PptxLayoutPreview[]>;
    /**
     * Build the artwork thumbnail for a single layout.
     *
     * @param layoutPath - Archive path of the `p:sldLayout` part.
     * @returns The preview, or `null` when the presentation has no such layout.
     */
    getLayoutPreview(layoutPath: string): Promise<PptxLayoutPreview | null>;
    /**
     * Create a fluent XML builder scoped to the given presentation data.
     *
     * The builder provides a chainable API for constructing and inserting
     * OpenXML nodes directly into the runtime’s in-memory ZIP.
     *
     * @param data - The parsed {@link PptxData} to bind the builder to.
     * @returns A new {@link PptxXmlBuilder} instance.
     */
    createXmlBuilder(data: PptxData): PptxXmlBuilder;
    /**
     * Shorthand alias for {@link createXmlBuilder}.
     *
     * @param data - Parsed presentation data.
     * @returns A {@link PptxXmlBuilder} instance.
     */
    Builder(data: PptxData): PptxXmlBuilder;
    /**
     * Register a background image for a specific template layout path.
     *
     * @param path - The internal PPTX path (e.g. `ppt/slideLayouts/slideLayout1.xml`).
     * @param backgroundColor - Optional hex colour to render behind the image.
     */
    setTemplateBackground(path: string, backgroundColor: string | undefined): void;
    /**
     * Retrieve the background colour previously set for a template layout.
     *
     * @param path - The internal PPTX layout path.
     * @returns Hex colour string, or `undefined` if none was set.
     */
    getTemplateBackgroundColor(path: string): string | undefined;
    /**
     * Replace the presentation’s theme by loading an external `.thmx` file.
     *
     * @param themePath - Absolute or relative path to the `.thmx` file.
     * @param applyToAllMasters - Apply to every slide master (default `true`).
     *
     * @example
     * ```ts
     * await handler.setPresentationTheme("./themes/corporate.thmx");
     * // => void — theme XML replaced in the in-memory ZIP
     * ```
     */
    setPresentationTheme(themePath: string, applyToAllMasters?: boolean): Promise<void>;
    /**
     * Modify the theme’s colour scheme (accent colours, background, text, etc.).
     *
     * @param colorScheme - A {@link PptxThemeColorScheme} with hex colour values.
     *
     * @example
     * ```ts
     * await handler.updateThemeColorScheme({
     *   dk1: "#1A1A2E", dk2: "#16213E",
     *   lt1: "#FFFFFF", lt2: "#E8E8E8",
     *   accent1: "#0F3460", accent2: "#533483",
     *   accent3: "#E94560", accent4: "#F0A500",
     * });
     * // => void — colour scheme updated in the in-memory theme XML
     * ```
     */
    updateThemeColorScheme(colorScheme: PptxThemeColorScheme): Promise<void>;
    /**
     * Update the theme’s font scheme (heading + body typefaces).
     *
     * @param fontScheme - A {@link PptxThemeFontScheme} with font family names.
     *
     * @example
     * ```ts
     * await handler.updateThemeFontScheme({
     *   majorFont: "Montserrat",
     *   minorFont: "Open Sans",
     * });
     * // => void — font scheme updated in the in-memory theme XML
     * ```
     */
    updateThemeFontScheme(fontScheme: PptxThemeFontScheme): Promise<void>;
    /**
     * Rename the presentation theme.
     *
     * @param name - New display name for the theme.
     */
    updateThemeName(name: string): Promise<void>;
    /**
     * Resolve a `<p:style>` block (`a:lnRef` / `a:fillRef` / `a:effectRef` /
     * `a:fontRef`) against the loaded theme, exactly as the load path would for
     * a shape whose `spPr` authors nothing. Apply the returned `shapeStyle` to a
     * shape and it renders like PowerPoint's Shape Styles entry and saves as a
     * bare `<p:style>` with an empty `spPr`, which is what PowerPoint writes.
     */
    resolveStyleMatrixReferences(styleXml: XmlObject): ResolvedStyleMatrix;
    /**
     * Apply a complete theme in one call (colour scheme + font scheme + optional name).
     *
     * This is a convenience wrapper over {@link updateThemeColorScheme},
     * {@link updateThemeFontScheme}, and {@link updateThemeName}.
     *
     * @param colorScheme - Colour definitions.
     * @param fontScheme  - Font definitions.
     * @param themeName   - Optional theme display name.
     *
     * @example
     * ```ts
     * await handler.applyTheme(
     *   { dk1: "#000", lt1: "#FFF", accent1: "#0066CC", /* … *\/ },
     *   { majorFont: "Helvetica", minorFont: "Arial" },
     *   "Corporate 2025",
     * );
     * // => void — colour scheme, font scheme, and name applied atomically
     * ```
     */
    applyTheme(colorScheme: PptxThemeColorScheme, fontScheme: PptxThemeFontScheme, themeName?: string): Promise<void>;
    /**
     * Switch the presentation's theme, updating both the underlying XML and
     * re-resolving all element colours in-place.
     *
     * This is the high-level API for theme switching: it updates the theme
     * data in the ZIP, then patches all resolved colours in the provided
     * `PptxData` so that elements immediately reflect the new colour scheme
     * without requiring a re-parse.
     *
     * @param data - The current parsed presentation data (mutated in-place for
     *   convenience, but a new `PptxData` object is also returned).
     * @param colorScheme - New colour scheme (12 colours).
     * @param fontScheme - Optional new font scheme.
     * @param themeName - Optional theme display name.
     * @returns The updated PptxData with re-resolved colours.
     *
     * @example
     * ```ts
     * import { THEME_PRESETS } from "pptx-viewer-core";
     *
     * const ion = THEME_PRESETS.find(p => p.id === "ion")!;
     * const newData = await handler.switchTheme(
     *   data,
     *   ion.colorScheme,
     *   ion.fontScheme,
     *   ion.name,
     * );
     * // => PptxData with all colours updated to the Ion theme
     * ```
     */
    switchTheme(data: PptxData, colorScheme: PptxThemeColorScheme, fontScheme?: PptxThemeFontScheme, themeName?: string): Promise<PptxData>;
    /**
     * Apply a built-in theme preset to the presentation.
     *
     * Convenience wrapper around {@link switchTheme} that accepts a
     * {@link PptxThemePreset} directly.
     *
     * @param data - The current parsed presentation data.
     * @param preset - One of the built-in presets from {@link THEME_PRESETS}.
     * @returns The updated PptxData.
     *
     * @example
     * ```ts
     * import { THEME_PRESETS } from "pptx-viewer-core";
     *
     * const preset = THEME_PRESETS.find(p => p.id === "facet")!;
     * const newData = await handler.switchThemePreset(data, preset);
     * ```
     */
    switchThemePreset(data: PptxData, preset: PptxThemePreset): Promise<PptxData>;
    /**
     * Parse a PPTX file from an `ArrayBuffer` and return structured data.
     *
     * If the file is encrypted and a `password` is provided in `options`,
     * the file will be decrypted before parsing. If no password is provided
     * for an encrypted file, throws {@link EncryptedFileError}.
     *
     * @param data    - Raw bytes of the `.pptx` file (may be encrypted OLE2).
     * @param options - Optional load-time settings, including `password`.
     * @returns Parsed {@link PptxData} containing slides, theme, layouts, etc.
     *
     * @example
     * ```ts
     * // Load an unencrypted file:
     * const pptx = await handler.load(buf.buffer);
     *
     * // Load a password-protected file:
     * const pptx = await handler.load(buf.buffer, { password: "secret" });
     * console.log(`${pptx.slides.length} slides loaded`);
     * ```
     */
    load(data: ArrayBuffer, options?: PptxHandlerLoadOptions): Promise<PptxData>;
    /**
     * Extract chart data from a graphic-frame XML node.
     *
     * @param slidePath    - Internal archive path of the slide (e.g. `ppt/slides/slide1.xml`).
     * @param graphicFrame - Parsed XML object for the `<p:graphicFrame>` node.
     * @returns Chart data, or `undefined` if the frame is not a chart.
     */
    getChartDataForGraphicFrame(slidePath: string, graphicFrame: XmlObject | undefined): Promise<PptxChartData | undefined>;
    /**
     * Extract SmartArt data from a graphic-frame XML node.
     *
     * @param slidePath    - Internal archive path of the slide.
     * @param graphicFrame - Parsed XML object for the `<p:graphicFrame>` node.
     * @returns SmartArt data, or `undefined` if the frame is not SmartArt.
     */
    getSmartArtDataForGraphicFrame(slidePath: string, graphicFrame: XmlObject | undefined): Promise<PptxSmartArtData | undefined>;
    /**
     * Get the base64-encoded data URL for an embedded image.
     *
     * @param imagePath - Archive-relative path (e.g. `ppt/media/image1.png`).
     * @returns A `data:image/...;base64,...` string, or `undefined` if not found.
     */
    getImageData(imagePath: string): Promise<string | undefined>;
    /**
     * Extract a media file from the PPTX archive as an ArrayBuffer.
     * Avoids the 33% base64 overhead of getImageData — prefer this for
     * audio/video media that will be played via Blob URLs.
     */
    getMediaArrayBuffer(mediaPath: string): Promise<ArrayBuffer | undefined>;
    /**
     * Serialise current slides back into a PPTX byte array.
     *
     * @param slides  - The (possibly mutated) slide array.
     * @param options - Optional save-time settings (e.g. thumbnail generation).
     * @returns `Uint8Array` of the complete `.pptx` file.
     *
     * @example
     * ```ts
     * const bytes = await handler.save(data.slides);
     * await fs.writeFile("output.pptx", Buffer.from(bytes));
     * // => Uint8Array written to disk as a valid .pptx file
     * ```
     */
    save(slides: PptxSlide[], options?: PptxHandlerSaveOptions): Promise<Uint8Array>;
    /**
     * Serialise slides and then encrypt the output with a password.
     *
     * This is a convenience method that calls {@link save} followed by
     * {@link encryptPptx}. The result is an OLE2 container suitable for
     * opening in Microsoft PowerPoint with a password prompt.
     *
     * @param slides   - The (possibly mutated) slide array.
     * @param password - The password to encrypt with.
     * @param options  - Optional save-time and encryption settings.
     * @returns `Uint8Array` of the encrypted OLE2 file.
     *
     * @example
     * ```ts
     * const bytes = await handler.saveEncrypted(data.slides, "secret");
     * await fs.writeFile("protected.pptx", Buffer.from(bytes));
     * // => Encrypted OLE2 file requiring password to open
     * ```
     */
    saveEncrypted(slides: PptxSlide[], password: string, options?: PptxHandlerSaveOptions & {
        encryption?: EncryptionOptions;
    }): Promise<Uint8Array>;
    /**
     * Get the slide layouts available for a specific slide.
     *
     * Returns layouts belonging to the same slide master as the given slide.
     * This is useful for building a layout picker UI scoped to the current
     * slide's master.
     *
     * @param slideIndex - Zero-based slide index.
     * @param slides     - Current slides array.
     * @returns Array of {@link PptxLayoutOption} entries for the slide's master.
     *
     * @example
     * ```ts
     * const layouts = await handler.getAvailableLayoutsForSlide(0, data.slides);
     * console.log(layouts.map(l => l.name));
     * // => ["Title Slide", "Title and Content", "Blank", ...]
     * ```
     */
    getAvailableLayoutsForSlide(slideIndex: number, slides: PptxSlide[]): Promise<PptxLayoutOption[]>;
    /**
     * Resolve the editable template (master + layout) elements a slide
     * inherits, each carrying a `master-` / `layout-` prefixed id.
     *
     * This is the foundation for an "edit template/master" feature. The
     * returned elements are the decorative master/layout shapes the loader
     * already merges behind slide-authored content (master shapes behind,
     * layout shapes on top); placeholders are excluded. The same elements are
     * shared by every slide inheriting the layout/master, so editing one and
     * saving updates the shared part.
     *
     * To persist an edit, keep the mutated template element inside the
     * `slide.elements` array passed to {@link save}; the save writer reads
     * template elements from there and writes their shape XML back into the
     * owning layout/master `p:spTree`.
     *
     * @param slideId - The slide's archive path (the `PptxSlide.id`).
     * @returns Master + layout elements with prefixed ids (may be empty).
     *
     * @example
     * ```ts
     * const templateEls = await handler.getTemplateElementsForSlide(slide.id);
     * const logo = templateEls.find((e) => e.id.startsWith("master-"));
     * if (logo) {
     *   logo.x += 10;
     *   slide.elements = [...slide.elements, logo];
     *   await handler.save(data.slides);
     * }
     * ```
     */
    getTemplateElementsForSlide(slideId: string): Promise<PptxElement[]>;
    /**
     * Apply a different layout to an existing slide.
     *
     * Updates the slide's relationship to point to the new layout and
     * refreshes layout-derived properties (background, layout name).
     * The slide's own content elements are preserved.
     *
     * @param slideIndex - Zero-based slide index.
     * @param layoutPath - Archive path of the target layout
     *                     (e.g. `ppt/slideLayouts/slideLayout2.xml`).
     * @param slides     - Current slides array (the slide at `slideIndex`
     *                     is replaced in-place).
     * @returns The updated {@link PptxSlide} with new layout metadata.
     *
     * @example
     * ```ts
     * const updated = await handler.applyLayoutToSlide(
     *   0,
     *   "ppt/slideLayouts/slideLayout3.xml",
     *   data.slides,
     * );
     * console.log(updated.layoutName);
     * // => "Two Content"
     * ```
     */
    applyLayoutToSlide(slideIndex: number, layoutPath: string, slides: PptxSlide[]): Promise<PptxSlide>;
    /**
     * Scan the loaded PPTX archive for all theme parts (`ppt/theme/theme*.xml`)
     * and return their paths and display names.
     */
    getAvailableThemes(): Promise<Array<{
        path: string;
        name?: string;
    }>>;
    /**
     * Export selected slides to a vector or raster format, keyed by slide index.
     *
     * **This does not produce PPTX files.** The previous version of this comment
     * said each entry was "a standalone PPTX with only that slide", named the
     * option `slideIndexes` (the real field is `slideIndices`), and wrote the
     * bytes to `slide_N.pptx`. None of that was ever true: the runtime has
     * always taken a `format` of `svg` / `png` / `pdf`. Per-slide PPTX
     * extraction is a different operation and is not implemented here.
     *
     * Only `svg` works without a host-supplied backend, and it works fully:
     * the headless {@link SvgExporter} renders it with no DOM. `png` and `pdf`
     * THROW, because this package carries no rasteriser; use a viewer binding's
     * browser export pipeline, or override `exportSlides` on the runtime with
     * your own backend.
     *
     * @param slides  - Full slide array.
     * @param options - Export options (`format`, `slideIndices`, `width`, ...).
     * @returns A `Map<slideIndex, Uint8Array>` of exported files. Hidden slides
     *   are omitted unless `options.includeHidden` is set, so the map can be
     *   smaller than `options.slideIndices`.
     * @throws {Error} when `options.format` is `png` or `pdf`.
     *
     * @example
     * ```ts
     * const exports = await handler.exportSlides(data.slides, {
     *   format: 'svg',
     *   slideIndices: [0, 2],
     * });
     * for (const [idx, bytes] of exports) {
     *   await fs.writeFile(`slide_${idx}.svg`, Buffer.from(bytes));
     * }
     * // => Map<number, Uint8Array>: one SVG document per exported slide
     * ```
     */
    exportSlides(slides: PptxSlide[], options: PptxExportOptions): Promise<Map<number, Uint8Array>>;
}

/**
 * Dependency injection options for {@link PptxHandlerCore}.
 *
 * Provide either `runtime` (an already-constructed runtime) or
 * `runtimeFactory` (a factory that will be called once). When neither
 * is supplied the default runtime is created automatically.
 *
 * @example
 * ```ts
 * // Use the default runtime:
 * const core = new PptxHandlerCore();
 *
 * // Inject a custom runtime:
 * const core = new PptxHandlerCore({ runtime: myRuntime });
 *
 * // Supply a factory for lazy creation:
 * const core = new PptxHandlerCore({ runtimeFactory: myFactory });
 * // => PptxHandlerCore instance with injected runtime
 * ```
 */
declare interface PptxHandlerCoreDependencies {
    runtime?: IPptxHandlerRuntime;
    runtimeFactory?: IPptxHandlerRuntimeFactory;
}

declare interface PptxHandlerLoadOptions {
    eagerDecodeImages?: boolean;
    password?: string;
    /**
     * Maximum total uncompressed bytes accepted from the input ZIP archive.
     * Defaults to 500 MiB. When the sum of `_data.uncompressedSize` across
     * all archive entries exceeds this cap, `load()` rejects with a
     * {@link ZipBombError}. A hard cap of 65 536 archive entries also
     * applies.
     */
    maxUncompressedBytes?: number;
    /**
     * When `false` (default), relationship targets that resolve to
     * `http://` or `https://` URLs are dropped from rendered slides
     * (image, picture, background). Set to `true` to allow external image
     * URLs to flow through to `<img src>`.
     *
     * Disabled by default to mitigate SSRF / privacy-leak vectors in
     * server-side rendering and headless export pipelines.
     */
    allowExternalImages?: boolean;
}

declare interface PptxHandlerSaveOptions {
    headerFooter?: PptxHeaderFooter;
    presentationProperties?: PptxPresentationProperties;
    customShows?: PptxCustomShow[];
    sections?: PptxSection[];
    coreProperties?: PptxCoreProperties;
    appProperties?: PptxAppProperties;
    customProperties?: PptxCustomProperty[];
    /** Updated notes master data to save back to notesMaster1.xml. */
    notesMaster?: PptxNotesMaster;
    /** Updated handout master data to save back to handoutMaster1.xml. */
    handoutMaster?: PptxHandoutMaster;
    /**
     * Updated slide masters to save back to ppt/slideMasters/slideMaster*.xml.
     * Each entry in the array applies typed mutations (clrMap, hf flags,
     * background) to the master at its `path`. Masters not listed here pass
     * through verbatim from the original load.
     */
    slideMasters?: PptxSlideMaster[];
    /**
     * Updated slide layouts to save back to ppt/slideLayouts/slideLayout*.xml.
     * Each entry applies typed mutations (clrMapOverride, attrs, hf flags,
     * background) to the layout at its `path`. Layouts not listed here pass
     * through verbatim from the original load.
     */
    slideLayouts?: PptxSlideLayout[];
    /** Updated tag collections to save back to ppt/tags/tag*.xml. */
    tags?: PptxTagCollection[];
    /** Presentation-level customer data references to author or update. */
    customerData?: PptxCustomerData[];
    /** Photo album metadata to save back to `p:photoAlbum`. */
    photoAlbum?: PptxPhotoAlbum;
    /**
     * Slide dimensions to write back to `p:sldSz`.
     *
     * Omitting the option preserves the load-time dimensions verbatim, which
     * is why an edit made through a viewer's Slide Size control has to reach
     * the save call: nothing else in the pipeline can observe it.
     *
     * PowerPoint derives `Presentation.PageSetup.SlideSize` from `@cx`/`@cy`
     * alone (verified by COM: an A4-typed `p:sldSz` carrying 4:3 dimensions
     * still reports `ppSlideSizeCustom`), so `type` is written for fidelity
     * but the dimensions are what actually decide the reported preset.
     */
    slideSize?: PptxSlideSize;
    /** East Asian line-break settings to save back to `p:kinsoku`. */
    kinsoku?: PptxKinsoku | null;
    /** Write-protection verifier. Set to `null` to remove, `undefined` to preserve existing. */
    modifyVerifier?: PptxModifyVerifier | null;
    /**
     * `p:presentation/@embedTrueTypeFonts` to write. `undefined` preserves
     * whatever was loaded (or omits the attribute for a brand-new deck);
     * purely declarative here, see {@link PptxData.embedTrueTypeFonts}.
     */
    embedTrueTypeFonts?: boolean;
    /**
     * Presentation-level default text style edits to save back to
     * `p:defaultTextStyle`. Only the levels present in the map are touched;
     * omitted levels and any unmodelled XML on an edited level survive
     * untouched. See {@link PptxData.defaultTextStyle}.
     */
    defaultTextStyle?: PptxTextStyleLevels;
    /** View properties to save back to ppt/viewProps.xml. */
    viewProperties?: PptxViewProperties;
    /**
     * Table style edits to save back to `ppt/tableStyles.xml`. Pass the
     * `tableStyleMap` from `PptxData` (optionally with edited entries)
     * to persist user edits. The `def` GUID and any unmodelled XML are
     * preserved verbatim. Omitting the option round-trips the original
     * part untouched.
     */
    tableStyles?: ParsedTableStyleMap;
    /**
     * Set `ppt/tableStyles.xml`'s `<a:tblStyleLst @def>` to this style GUID
     * (normalised to uppercase-with-braces). `undefined` preserves the
     * existing default; there is no removal form (`@def` is required by the
     * schema and PowerPoint always points it at a real style). No-op when the
     * archive has no `ppt/tableStyles.xml`, same as {@link tableStyles}.
     */
    tableStylesDefaultId?: string;
    /**
     * Style GUIDs to remove from `ppt/tableStyles.xml` entirely, kept as a
     * separate opt-in list rather than inferred from omission on
     * {@link tableStyles}: that map is documented as safe to pass a PARTIAL
     * edit (only the entries a caller actually touched), so treating every
     * GUID missing from it as "delete this" would silently destroy untouched
     * styles on an ordinary targeted edit. A GUID here that is also the
     * current (or newly requested) default is left in place and skipped.
     */
    tableStylesToDelete?: string[];
    /**
     * Target output format.
     * - `'pptx'` (default): Standard presentation.
     * - `'ppsx'`: Slide-show file (opens in presentation mode).
     * - `'pptm'`: Macro-enabled presentation (requires VBA data).
     * - `'ppt'`: Legacy binary PowerPoint 97-2003 presentation. Bypasses the
     *   OOXML ZIP pipeline entirely; see `PptxHandlerRuntimeSaveLegacyPpt`.
     *   Elements with no binary equivalent (charts, SmartArt, media, OLE, ink,
     *   3D models) are degraded to a rasterised preview picture or a labelled
     *   placeholder, each reported via a `scope: 'save'`-adjacent
     *   `PptxCompatibilityWarning`.
     */
    outputFormat?: PptxSaveFormat;
    /**
     * Password for RC4 CryptoAPI encryption of a `'ppt'`-format save. Ignored
     * for every other {@link outputFormat}; encrypting a `.pptx`/`.ppsx`/`.pptm`
     * save uses {@link IPptxHandlerRuntime.saveEncrypted}'s separate AES/Agile
     * OLE2 wrapping instead, since the legacy binary format's own encryption
     * scheme is embedded directly in the `.ppt` stream rather than wrapping an
     * already-produced package.
     */
    pptPassword?: string;
    /**
     * Embedded fonts to write back (or add) to the saved PPTX.
     *
     * Pass the `embeddedFonts` array from `PptxData` to preserve existing
     * embedded fonts during save. You can also add new fonts by including
     * entries with `rawFontData` populated.
     *
     * When omitted, the save pipeline will automatically re-embed any
     * fonts that were loaded from the original PPTX and have `rawFontData`
     * preserved (i.e. the default is lossless round-trip).
     */
    embeddedFonts?: PptxEmbeddedFont[];
    /** Typed embedded-font list metadata. Set to null to remove fonts and relationships. */
    embeddedFontList?: PptxEmbeddedFontList | null;
    /**
     * OOXML conformance class for the saved output.
     * - `'preserve'` (default): use the same conformance as the loaded file.
     * - `'strict'`: force Strict Open XML (ISO/IEC 29500) namespace URIs.
     * - `'transitional'`: force Transitional (ECMA-376) namespace URIs.
     */
    conformance?: 'strict' | 'transitional' | 'preserve';
}

/**
 * Parsed handout master from `ppt/handoutMasters/handoutMaster1.xml`.
 *
 * @example
 * ```ts
 * const handout: PptxHandoutMaster = {
 *   path: "ppt/handoutMasters/handoutMaster1.xml",
 *   slidesPerPage: 6,
 * };
 * // => satisfies PptxHandoutMaster
 * ```
 */
declare interface PptxHandoutMaster {
    /** File path within the PPTX archive. */
    path: string;
    /** Background colour of the handout master. */
    backgroundColor?: string;
    /** Background image data URL. */
    backgroundImage?: string;
    /** Crop, tiling and image effects authored on the background blip fill. */
    backgroundImageProperties?: PptxImageProperties;
    /** Placeholder shapes found on the handout master. */
    placeholders?: PptxPlaceholderFrame[];
    /** Editable elements on the handout master (header, footer, date, page number, slide placeholders). */
    elements?: PptxElement[];
    /** Number of slides per page for handout print layout (1, 2, 3, 4, 6, or 9). */
    slidesPerPage?: number;
    /** Header/footer flags from `<p:hf>` on the handout master (P-H3). */
    headerFooter?: PptxHeaderFooterFlags;
    /** Colour map from `<p:clrMap>` (12 alias attributes). Applied at save time. */
    clrMap?: Record<string, string>;
}

/**
 * Header, footer, date-time, and slide-number placeholders.
 *
 * Parsed from `ppt/presProps.xml` and individual slide layouts.
 *
 * @example
 * ```ts
 * const hf: PptxHeaderFooter = {
 *   hasFooter: true,
 *   footerText: "Confidential",
 *   hasSlideNumber: true,
 * };
 * // => satisfies PptxHeaderFooter
 * ```
 */
declare interface PptxHeaderFooter {
    hasHeader?: boolean;
    headerText?: string;
    hasFooter?: boolean;
    footerText?: string;
    hasDateTime?: boolean;
    dateTimeText?: string;
    dateTimeAuto?: boolean;
    /**
     * The master date placeholder's own `a:fld/@type` (e.g. "datetime2"), NOT a
     * format pattern. It is one of the predefined OOXML datetime field types
     * (`datetime1`-`datetime13`); the display pattern for each is resolved by
     * `resolveFieldDateText` in `packages/shared/src/render/text-field-substitution.ts`.
     */
    dateFormat?: string;
    hasSlideNumber?: boolean;
}

/**
 * Per-part header/footer flags from `<p:hf>` (CT_HeaderFooter, ECMA-376
 * §19.3.1.21). Defaults are "all true" — fields are only set on the typed
 * model when they were explicitly read, so callers can distinguish "unset"
 * (preserve original XML) from "false" (override).
 */
declare interface PptxHeaderFooterFlags {
    /** `@hdr` — show header placeholder. Spec default: `true`. */
    hasHeader?: boolean;
    /** `@ftr` — show footer placeholder. Spec default: `true`. */
    hasFooter?: boolean;
    /** `@dt` — show date/time placeholder. Spec default: `true`. */
    hasDateTime?: boolean;
    /** `@sldNum` — show slide-number placeholder. Spec default: `true`. */
    hasSlideNumber?: boolean;
}

/** Signed HSL channel deltas parsed from `p:animClr/p:by/p:hsl`. */
declare interface PptxHslColorDelta {
    /** Hue offset in degrees. OOXML stores this in 60000ths of a degree. */
    hue: number;
    /** Saturation offset in percentage points. */
    saturation: number;
    /** Lightness offset in percentage points. */
    lightness: number;
}

declare interface PptxImageEffects {
    /** Brightness adjustment (-100 to 100). */
    brightness?: number;
    /** Contrast adjustment (-100 to 100). */
    contrast?: number;
    /** Duotone colour pair. */
    duotone?: {
        color1: string;
        color2: string;
        /** Original effect XML, retained while the resolved colours are unchanged. */
        rawXml?: XmlObject;
    };
    /** Grayscale flag. */
    grayscale?: boolean;
    /** Saturation adjustment (-100 to 100). */
    saturation?: number;
    /** Color wash overlay. */
    colorWash?: {
        color: string;
        opacity: number;
    };
    /** Artistic effect name (blur, pencilGrayscale, paintStrokes, etc.). */
    artisticEffect?: string;
    /** Artistic effect radius/amount, normalised to 0..100. */
    artisticRadius?: number;
    /**
     * Every numeric attribute of the source `a14:artistic*` element, raw and
     * un-normalised (`trans`, `pencilSize`, `crackSpacing`, …). The attribute set
     * differs per effect, so this is the lossless companion to the single
     * {@link PptxImageEffects.artisticRadius} number.
     */
    artisticParams?: Record<string, number>;
    /**
     * Name of the artistic effect ALREADY baked into the image data, which a
     * renderer must not apply a second time. Set from the `a14` blip extension,
     * which PowerPoint writes alongside a pre-rendered bitmap (see
     * {@link PptxBackgroundRemoval}), and normally equal to
     * {@link PptxImageEffects.artisticEffect}.
     *
     * It records the NAME rather than a boolean so that picking a different
     * effect in this library's inspector (which patches `artisticEffect` alone)
     * still renders: the two names then differ.
     */
    artisticPrerenderedEffect?: string;
    /**
     * PowerPoint "Remove Background" state (`a14:backgroundRemoval`). Edit-time
     * metadata: the removal is already baked into the image data.
     */
    backgroundRemoval?: PptxBackgroundRemoval;
    /**
     * `a14:imgLayer/@r:embed`: relationship id of the PRISTINE original image
     * the baked effects were derived from (PowerPoint stores it as an HD Photo
     * `.wdp` part, which browsers cannot decode).
     */
    originalImageRelId?: string;
    /**
     * PowerPoint 2010+ Corrections panel "Sharpen/Soften"
     * (`a14:sharpenSoften/@amount`). Raw as the XML carries it: 1/1000ths of a
     * percent, `-100000` (fully softened) .. `100000` (fully sharpened).
     * Edit-time metadata like the artistic effects: PowerPoint bakes the result
     * into the stored bitmap.
     */
    sharpenSoften?: {
        amount: number;
    };
    /**
     * PowerPoint 2010+ Corrections panel "Brightness/Contrast"
     * (`a14:brightnessContrast/@bright`, `@contrast`). Raw 1/1000ths of a
     * percent, `-100000` .. `100000`. Distinct from the legacy `a:blip/@bright`
     * + `@contrast` pair in {@link PptxImageEffects.brightness} /
     * {@link PptxImageEffects.contrast}, which PowerPoint 2007 wrote and which
     * a renderer still applies.
     */
    brightnessContrast?: {
        bright?: number;
        contrast?: number;
    };
    /**
     * PowerPoint 2010+ Color panel "Color Tone"
     * (`a14:colorTemperature/@colorTemp`). Raw Kelvin value, `1500` .. `11500`;
     * `6500` is neutral.
     */
    colorTemperature?: {
        colorTemp: number;
    };
    /**
     * PowerPoint 2010+ Color panel "Color Saturation" (`a14:saturation/@sat`).
     * Raw 1/1000ths of a percent: `100000` is unchanged, `0` is grayscale,
     * `400000` the maximum. Named `colorSaturation` because
     * {@link PptxImageEffects.saturation} is the viewer-side -100..100 knob
     * that has no OOXML counterpart.
     */
    colorSaturation?: {
        sat: number;
    };
    /**
     * The Corrections / Color panel values ALREADY baked into the image data,
     * which a renderer must not apply a second time. The a14 counterpart of
     * {@link PptxImageEffects.artisticPrerenderedEffect}: PowerPoint writes the
     * corrected bitmap to the main `a:blip` and keeps the pristine original in
     * `a14:imgLayer` (measured on a real deck: the stored PNG is a monotone tonal
     * transform of the `.wdp` original, slope 0.7 for `contrast="-40000"`).
     *
     * Holds the VALUES rather than a boolean so that changing one of the four
     * fields in this library's inspector still renders: a field that differs
     * from its snapshot is applied, one that matches is skipped.
     */
    prerenderedCorrections?: PptxImagePrerenderedCorrections;
    /** Alpha modulation fixed: non-negative percentage (100 means unchanged opacity). */
    alphaModFix?: number;
    /** Original alpha modulation fixed node, including foreign attributes. */
    alphaModFixRawXml?: XmlObject;
    /** Bi-level threshold: converts to 1-bit black/white (0-100). */
    biLevel?: number;
    /** Colour change: swap one colour range for another (used for transparency keying). */
    clrChange?: {
        clrFrom: string;
        clrTo: string;
        /** Whether the target colour is fully transparent (alpha = 0). */
        clrToTransparent?: boolean;
        /** Original effect XML, including colour transforms and extensions. */
        rawXml?: XmlObject;
    };
    /** Original grayscale node, including extension or foreign attributes. */
    grayscaleRawXml?: XmlObject;
    /** Original bi-level node, including extension or foreign attributes. */
    biLevelRawXml?: XmlObject;
    /**
     * Alpha inverse effect (`a:alphaInv`). Inverts the alpha channel; an optional
     * colour child shifts the inversion baseline.
     */
    alphaInv?: {
        /** Optional baseline colour (hex). */
        color?: string;
        /** Original effect XML, including colour transforms and foreign attributes. */
        rawXml?: XmlObject;
    };
    /** Alpha ceiling (`a:alphaCeiling`): clamps any non-zero alpha to fully opaque. Boolean flag. */
    alphaCeiling?: boolean;
    /** Original alpha ceiling node, including foreign attributes. */
    alphaCeilingRawXml?: XmlObject;
    /** Alpha floor (`a:alphaFloor`): clamps any non-fully-opaque alpha to fully transparent. Boolean flag. */
    alphaFloor?: boolean;
    /** Original alpha floor node, including foreign attributes. */
    alphaFloorRawXml?: XmlObject;
    /**
     * Alpha modulate (`a:alphaMod`). The schema requires a single `cont` (effect
     * container) child; we preserve the inner XML opaquely for round-trip.
     */
    alphaMod?: {
        /** Raw opaque XML for the `a:cont` child to preserve on save. */
        contRawXml?: Record<string, unknown>;
        /** Original effect XML, including foreign attributes. */
        rawXml?: XmlObject;
        /**
         * Multiplicative alpha percentage (0..100+), read from a nested
         * `<a:alphaModFix>` inside `contRawXml` when present - the common
         * real-world shape of `a:alphaMod` (`<a:cont><a:alphaModFix amt="…"/>
         * </a:cont>`). Derived/read-only: a renderer multiplies the source alpha
         * by this, distinct from the top-level {@link alphaModFix} sibling
         * effect. Not written back independently on save; `contRawXml` is what
         * round-trips.
         */
        amt?: number;
    };
    /** Alpha replace (`a:alphaRepl`): replaces alpha with the given fixed-percent value (0..100). */
    alphaRepl?: number;
    /** Original alpha replace node, including foreign attributes. */
    alphaReplRawXml?: XmlObject;
    /** Alpha bi-level (`a:alphaBiLevel`): threshold (0..100) above which alpha becomes fully opaque. */
    alphaBiLevel?: number;
    /** Original alpha bi-level node, including foreign attributes. */
    alphaBiLevelRawXml?: XmlObject;
    /**
     * Colour replace (`a:clrRepl`): replaces all colour information in an image
     * with the given solid colour. Stores the raw colour child to preserve scheme
     * colour references and modifiers.
     */
    clrRepl?: {
        /** Resolved hex colour. */
        color: string;
        /** Raw opaque colour XML for round-trip. */
        rawXml?: Record<string, unknown>;
    };
    /** Luminance modulation (`a:lum`): bright/contrast as fixed percentages (0..100). */
    lum?: {
        bright?: number;
        contrast?: number;
    };
    /** HSL modulation (`a:hsl`): hue (0..360 degrees), saturation/luminance (-100..100). */
    hsl?: {
        hue?: number;
        sat?: number;
        lum?: number;
    };
    /** Image-effect tint (`a:tint` inside blip): hue (0..360), amount (-100..100). */
    tint?: {
        hue?: number;
        amt?: number;
    };
    /**
     * Fill overlay (`a:fillOverlay`): overlays a fill on top of the blip.
     * Stores blend mode and the raw inner fill XML for round-trip.
     */
    fillOverlay?: {
        blend: 'over' | 'mult' | 'screen' | 'darken' | 'lighten';
        /** Raw opaque fill XML preserved for round-trip. */
        fillRawXml?: Record<string, unknown>;
        /**
         * Resolved hex colour, when the overlay fill is a plain `a:solidFill`
         * (the common case for a picture-style colour overlay). `undefined` for
         * a gradient/pattern/picture overlay fill - see {@link resolvedGradient} /
         * {@link resolvedPattern} instead. `fillRawXml` still round-trips
         * losslessly regardless of which of the three resolved.
         */
        resolvedColor?: string;
        /** Resolved opacity (0-1) of the `a:solidFill` overlay colour, when resolved. */
        resolvedOpacity?: number;
        /**
         * Resolved gradient, when the overlay fill is `a:gradFill`. A renderer
         * composites this as an SVG paint server (`<linearGradient>` /
         * `<radialGradient>`) rather than a flat flood colour.
         */
        resolvedGradient?: {
            type: 'linear' | 'radial';
            /** Gradient angle in degrees (`a:lin/@ang`), for a linear gradient. */
            angle?: number;
            stops: Array<{
                color: string;
                position: number;
                opacity?: number;
            }>;
        };
        /**
         * Resolved preset pattern, when the overlay fill is `a:pattFill`. A
         * renderer composites this as a tiled SVG paint server.
         */
        resolvedPattern?: {
            preset: string;
            foreground?: string;
            background?: string;
        };
    };
    /** Blur (`a:blur`): radius in EMU and grow flag. */
    blur?: {
        rad?: number;
        grow?: boolean;
    };
}

/**
 * PowerPoint "Remove Background" state (`a14:backgroundRemoval`).
 *
 * The four edges are the RETAINED rectangle as 0..1 fractions of the image
 * (OOXML stores them as per-100000 relative units), and the mark lists are the
 * segmentation hints the user painted.
 *
 * **This is edit-time metadata, not a render instruction.** PowerPoint bakes the
 * removal into the bitmap referenced by the main `a:blip/@r:embed` and keeps the
 * pristine original in `a14:imgLayer/@r:embed`. Verified against PowerPoint COM:
 * a slide exported with and without this element is byte-identical. A renderer
 * that clips to the retained rectangle would clip an image whose background has
 * already been removed.
 *
 * @example
 * ```ts
 * const removal: PptxBackgroundRemoval = { top: 0.12, bottom: 0.88, left: 0.07, right: 0.93 };
 * // => retains the middle of the image; the marks list stays empty
 * ```
 */
/**
 * Snapshot of the a14 Corrections / Color panel values as they were read from
 * the file, kept on {@link PptxImageEffects.prerenderedCorrections} so a
 * renderer can tell a baked-in value from one changed in this library.
 */
declare interface PptxImagePrerenderedCorrections {
    sharpenSoften?: {
        amount: number;
    };
    brightnessContrast?: {
        bright?: number;
        contrast?: number;
    };
    colorTemperature?: {
        colorTemp: number;
    };
    colorSaturation?: {
        sat: number;
    };
}

/**
 * Image content mixin: present on image and picture elements.
 *
 * Contains the decoded image data (base64 data URL or archive path),
 * alt text, crop insets, tiling settings, and image effects.
 *
 * @example
 * ```ts
 * const props: PptxImageProperties = {
 *   imagePath: "ppt/media/image1.png",
 *   altText: "Company logo",
 *   cropLeft: 0.05,
 *   cropRight: 0.05,
 * };
 * // => { imagePath: "ppt/media/image1.png", altText: "Company logo", cropLeft: 0.05, cropRight: 0.05 }
 * ```
 */
declare interface PptxImageProperties {
    /** Base64 data-URL for the decoded image. */
    imageData?: string;
    /** Path within the PPTX ZIP archive. */
    imagePath?: string;
    /** Base64 data-URL for an SVG variant (from blip extension asvg:svgBlip). Preferred over raster when available. */
    svgData?: string;
    /** Path to the SVG file within the PPTX ZIP archive. */
    svgPath?: string;
    /** Alt text / description from `p:cNvPr/@descr`. */
    altText?: string;
    /** Crop from left edge as 0..1 fraction (OOXML `a:srcRect/@l`). */
    cropLeft?: number;
    /** Crop from top edge as 0..1 fraction (OOXML `a:srcRect/@t`). */
    cropTop?: number;
    /** Crop from right edge as 0..1 fraction (OOXML `a:srcRect/@r`). */
    cropRight?: number;
    /** Crop from bottom edge as 0..1 fraction (OOXML `a:srcRect/@b`). */
    cropBottom?: number;
    /**
     * Stretch target inset from the left frame edge as a signed fraction
     * (OOXML `a:stretch/a:fillRect/@l`). Unlike `cropLeft` (which selects a
     * region of the SOURCE bitmap), a fill-rect selects the region of the
     * FRAME the whole image is stretched into; negative values push the
     * image beyond the frame edge, and the overflow is clipped.
     */
    fillRectLeft?: number;
    /** Stretch target inset from the top frame edge (`a:fillRect/@t`). */
    fillRectTop?: number;
    /** Stretch target inset from the right frame edge (`a:fillRect/@r`). */
    fillRectRight?: number;
    /** Stretch target inset from the bottom frame edge (`a:fillRect/@b`). */
    fillRectBottom?: number;
    /** Image tiling offset X in px. */
    tileOffsetX?: number;
    /** Image tiling offset Y in px. */
    tileOffsetY?: number;
    /** Image tiling scale X as percentage (100 = 100%). */
    tileScaleX?: number;
    /** Image tiling scale Y as percentage (100 = 100%). */
    tileScaleY?: number;
    /** Image tiling flip mode. */
    tileFlip?: 'none' | 'x' | 'y' | 'xy';
    /** Image tiling alignment. */
    tileAlignment?: string;
    /**
     * Print-resolution hint in DPI (`a:blipFill/@dpi`). PowerPoint records this
     * when it downsamples an embedded image for a target print quality; it has
     * no on-screen rendering effect (a `0`/absent value means "use the source
     * image's native resolution"). Parsed for round-trip / API fidelity only.
     */
    dpi?: number;
    /** Image recolour/artistic effect properties. */
    imageEffects?: PptxImageEffects;
    /**
     * Crop-to-shape (CSS clip-path shape name).
     *
     * PowerPoint implements "Crop to Shape" by writing the picture's own
     * `a:prstGeom`, so this is a typed view over `shapeType`: on load it is
     * derived from the preset (`ellipse` -> `'ellipse'`, `roundRect` ->
     * `'roundedRect'`, `star5` -> `'star'`, ...; see
     * `utils/crop-shape-geometry`), and on save a changed value rewrites the
     * preset. `'none'` / `undefined` leaves the geometry alone.
     */
    cropShape?: PptxCropShape;
}

/**
 * East Asian line-break (kinsoku) settings from `p:kinsoku` in `presentation.xml`.
 *
 * Defines forbidden start/end characters for a given language so that
 * line-breaking follows East Asian typographic rules.
 *
 * @see ECMA-376 Part 1, §19.2.1.17
 */
declare interface PptxKinsoku {
    /** Language code (e.g. "ja-JP", "zh-CN"). */
    lang?: string | null;
    /** Characters that cannot begin a line. */
    invalStChars?: string;
    /** Characters that cannot end a line. */
    invalEndChars?: string;
    /** Original leaf retained for unknown attribute preservation. */
    rawXml?: XmlObject;
}

/**
 * A slide layout available in the loaded presentation.
 *
 * Each entry maps to a `<p:sldLayout>` inside `ppt/slideLayouts/`.
 *
 * @example
 * ```ts
 * const layout: PptxLayoutOption = {
 *   path: "ppt/slideLayouts/slideLayout2.xml",
 *   name: "Title and Content",
 * };
 * // => satisfies PptxLayoutOption
 * ```
 */
declare interface PptxLayoutOption {
    path: string;
    name: string;
    /** Standard layout type from `p:sldLayout/@type` (e.g. "obj", "twoColTx", "blank"). */
    type?: string;
    /** ZIP path of the slide master this layout belongs to. */
    masterPath?: string;
}

/**
 * Rendered content of a single layout, used to draw gallery thumbnails.
 *
 * Produced on demand rather than during load: materialising every layout's
 * artwork (and decoding its images) up front costs a noticeable amount of time
 * on decks with many masters, and most sessions never open the layout gallery
 * at all.
 *
 * @example
 * ```ts
 * const preview: PptxLayoutPreview = {
 *   path: "ppt/slideLayouts/slideLayout2.xml",
 *   width: 960,
 *   height: 540,
 *   elements: [],
 *   placeholders: [{ type: "title" }],
 * };
 * // => satisfies PptxLayoutPreview
 * ```
 */
declare interface PptxLayoutPreview {
    /** ZIP path of the layout this preview belongs to. */
    path: string;
    /** Slide width in CSS pixels, so a thumbnail can compute its own scale. */
    width: number;
    /** Slide height in CSS pixels. */
    height: number;
    /** Background resolved from the layout, falling back to its master's. */
    backgroundColor?: string;
    /** Background image data URL, when the layout or master declares one. */
    backgroundImage?: string;
    /** Crop, tiling and image effects authored on the resolved background image. */
    backgroundImageProperties?: PptxImageProperties;
    /** The layout's own artwork (pictures, shapes and static text). */
    elements: PptxElement[];
    /** Placeholder slots, drawn as outlined frames in the gallery. */
    placeholders: PptxPlaceholderFrame[];
}

/**
 * Text styles parsed from `p:txStyles` on a slide master.
 * Provides cascading defaults for title, body, and other text.
 */
declare interface PptxMasterTextStyles {
    /** Title text style (`p:titleStyle`). */
    titleStyle?: PptxTextStyleLevels;
    /** Body text style (`p:bodyStyle`). */
    bodyStyle?: PptxTextStyleLevels;
    /** Other text style (`p:otherStyle`). */
    otherStyle?: PptxTextStyleLevels;
}

/**
 * `p14:bmkTgt` (Office 2010 `p14` extension, MS-OI29500): names the specific
 * media element and bookmark an `evt="onMediaBookmark"` condition fires for.
 * `bookmarkName` matches a `p14:bmk/@_name` on that media element's own
 * `p14:bmkLst` (see `MediaBookmark.label` in `core/types/elements.ts`).
 */
declare interface PptxMediaBookmarkTarget {
    /** `p14:bmkTgt/@_spid`: the media element's shape id. */
    shapeId: string;
    /** `p14:bmkTgt/@_bmkName`: the bookmark's name. */
    bookmarkName: string;
}

declare type PptxMediaReferenceKind = 'audioCd' | 'wavAudioFile' | 'audioFile' | 'videoFile' | 'quickTimeFile';

/**
 * Discriminator for embedded media element types.
 *
 * @example
 * ```ts
 * const kind: PptxMediaType = "video";
 * // => "video" — one of: "video" | "audio" | "unknown"
 * ```
 */
declare type PptxMediaType = 'video' | 'audio' | 'unknown';

/** Office 2021 comment author from the p188 Author part. */
declare interface PptxModernCommentAuthor {
    id: string;
    name: string;
    initials?: string;
    userId: string;
    providerId: string;
    rawXml?: XmlObject;
}

declare interface PptxModernCommentPart {
    path: string;
    relationshipId: string;
    /** Original p188:cmLst root, including unknown attributes and extensions. */
    rawXml?: XmlObject;
}

/**
 * Write-protection hash data parsed from `p:modifyVerifier` in `presentation.xml`.
 *
 * When present, the presentation is marked as "read-only recommended" or
 * write-protected with a password hash.  The hash parameters follow the
 * ECMA-376 Part 1, section 19.2.1.22 specification.
 *
 * @example
 * ```ts
 * const verifier: PptxModifyVerifier = {
 *   algorithmName: "SHA-512",
 *   hashData: "base64EncodedHash==",
 *   saltData: "base64EncodedSalt==",
 *   spinValue: 100000,
 * };
 * // => satisfies PptxModifyVerifier
 * ```
 */
declare interface PptxModifyVerifier {
    /** Hash algorithm name (e.g. "SHA-512", "SHA-1"). */
    algorithmName?: string;
    /** Base64-encoded hash value. */
    hashData?: string;
    /** Base64-encoded salt value. */
    saltData?: string;
    /** Number of hash iterations (spin count). */
    spinValue?: number;
    /** Legacy algorithm ID extension. */
    algIdExt?: string;
    /** Legacy algorithm ID. */
    cryptAlgorithmSid?: number;
    /** Cryptographic algorithm type (e.g. "typeAny"). */
    cryptAlgorithmType?: string;
    /** Cryptographic provider name. */
    cryptProvider?: string;
    /** Cryptographic provider type (e.g. "providerTypeRsaFull"). */
    cryptProviderType?: string;
    /** Cryptographic algorithm class (e.g. "hash"). */
    cryptAlgorithmClass?: string;
}

/**
 * Slide transition configuration.
 *
 * @example
 * ```ts
 * const transition: PptxSlideTransition = {
 *   type: "fade",
 *   durationMs: 700,
 *   advanceOnClick: true,
 *   advanceAfterMs: 5000,
 * };
 * // => { type: "fade", durationMs: 700, advanceOnClick: true, advanceAfterMs: 5000 }
 * ```
 */
/**
 * Morph granularity (`<p159:morph @option>`).
 *
 * - `byObject`  - match whole shapes (PowerPoint's default)
 * - `byWord`    - additionally morph text word by word
 * - `byChar`    - additionally morph text character by character
 */
declare type PptxMorphOption = 'byObject' | 'byWord' | 'byChar';

/**
 * Parsed native animation record from `p:timing / p:tnLst`.
 *
 * Represents a single animation node in the OOXML timing tree,
 * including motion paths, scale transforms, and text build settings.
 *
 * @example
 * ```ts
 * const anim: PptxNativeAnimation = {
 *   targetId: "shape_1",
 *   presetClass: "entr",
 *   presetId: 10,
 *   trigger: "afterPrevious",
 *   durationMs: 500,
 * };
 * // => { targetId: "shape_1", presetClass: "entr", presetId: 10, trigger: "afterPrevious", durationMs: 500 }
 * ```
 */
declare interface PptxNativeAnimation {
    /** Target element/shape ID. */
    targetId?: string;
    /** Full timing target, including sound and ink target variants. */
    target?: PptxAnimationTarget;
    /** Trigger type. */
    trigger?: PptxAnimationTrigger;
    /**
     * Shape ID that triggers this animation: the clicked shape of an
     * interactive sequence, or the media element of an `onMediaBookmark` one.
     */
    triggerShapeId?: string;
    /** Bookmark name an `onMediaBookmark` interactive sequence waits for. */
    triggerBookmark?: string;
    /** Whether this effect belongs to an OOXML `interactiveSeq`. */
    interactiveSequence?: boolean;
    /** Whether `p:endSync/p:rtn[@val="all"]` makes that sequence replayable. */
    interactiveRestart?: boolean;
    /** Effect preset class (entr, exit, emph, path). */
    presetClass?: 'entr' | 'exit' | 'emph' | 'path';
    /** Effect preset sub-type identifier. */
    presetId?: number;
    /**
     * Effect preset direction/variant code from `p:cTn/@presetSubtype`
     * (ECMA-376 CT_TLCommonTimeNodeData). For Fly In/Out this encodes the
     * edge/corner the object travels from as a bitmask (1=top, 2=right,
     * 4=bottom, 8=left; corners combine bits). Absent means the preset default.
     */
    presetSubtype?: number;
    /** Duration in milliseconds. */
    durationMs?: number;
    /** Delay in milliseconds. */
    delayMs?: number;
    /**
     * Acceleration fraction in the range 0..1, parsed from `p:cTn/@accel`
     * (ST_PositiveFixedPercentage, stored as 1000ths of a percent). A non-zero
     * value means the effect eases in (starts slow). Absent means no easing-in.
     */
    accel?: number;
    /**
     * Deceleration fraction in the range 0..1, parsed from `p:cTn/@decel`.
     * A non-zero value means the effect eases out (ends slow). Absent means no
     * easing-out. When both {@link accel} and {@link decel} are set, the effect
     * eases in and out.
     */
    decel?: number;
    /** Trigger delay in milliseconds (for afterDelay). */
    triggerDelayMs?: number;
    /** SVG path string for motion path animations (`p:animMotion/@path`). */
    motionPath?: string;
    /** Motion origin: "layout" or "parent". */
    motionOrigin?: string;
    /**
     * Whether the element auto-rotates to follow the motion path tangent.
     * Viewer-authoring-only hint: OOXML has no such flag (`p:animMotion/@rAng`
     * is a plain rotation angle that PowerPoint writes as "0" on every path),
     * so the parser never sets this.
     */
    motionPathRotateAuto?: boolean;
    /** Path edit mode from `p:animMotion/@pathEditMode` (e.g. "relative", "fixed"). */
    motionPathEditMode?: string;
    /** Comma-separated point-types string from `p:animMotion/@ptsTypes`. */
    motionPtsTypes?: string;
    /** Authored path rotation in degrees from `p:animMotion/@rAng`. */
    motionPathRotationAngle?: number;
    /** Motion-path rotation centre X in slide percentage units (`p:rCtr/@x`). */
    motionPathRotationCenterX?: number;
    /** Motion-path rotation centre Y in slide percentage units (`p:rCtr/@y`). */
    motionPathRotationCenterY?: number;
    /** Rotation angle in degrees for `p:animRot/@by` (converted from 60000ths). */
    rotationBy?: number;
    /** Starting rotation angle in degrees for `p:animRot/@from` (converted from 60000ths). */
    rotationFrom?: number;
    /** Ending rotation angle in degrees for `p:animRot/@to` (converted from 60000ths). */
    rotationTo?: number;
    /** X scale factor (percentage / 100) for `p:animScale/p:by/@x`. */
    scaleByX?: number;
    /** Y scale factor (percentage / 100) for `p:animScale/p:by/@y`. */
    scaleByY?: number;
    /** Starting X scale factor for `p:animScale/p:from/@x`. */
    scaleFromX?: number;
    /** Starting Y scale factor for `p:animScale/p:from/@y`. */
    scaleFromY?: number;
    /** Ending X scale factor for `p:animScale/p:to/@x`. */
    scaleToX?: number;
    /** Ending Y scale factor for `p:animScale/p:to/@y`. */
    scaleToY?: number;
    /** Whether `p:animScale/@zoomContents` was set ("1"/"true"). */
    scaleZoomContents?: boolean;
    /** Parsed `p:tav` keyframes from `p:tavLst` (CT_TLAnimVariantList). */
    keyframes?: PptxAnimationKeyframe[];
    /**
     * The attribute {@link keyframes} drives, from the SAME node's
     * `p:cBhvr/p:attrNameLst/p:attrName` (ECMA-376 S19.5.4). `p:tavLst` is
     * schema-generic: without this, playback could see a numeric ramp but not
     * know whether it targeted opacity, position, colour, or something with
     * no CSS mapping. Lowercased and trimmed; common values seen in the wild
     * (and written by this codebase's own animation writer) include
     * `"style.opacity"`, `"style.color"`, `"style.visibility"`, `"fillcolor"`,
     * `"stroke.color"`, `"r"` (rotation, only meaningful on `p:animRot`), and
     * `"ppt_x"` / `"ppt_y"` (position, normally driven via `p:animMotion`
     * instead). Absent when the behaviour carries no `p:attrNameLst`.
     */
    attrName?: string;
    /** Every generic `p:anim` sibling composed by the authored effect. */
    attributeAnimations?: PptxAttributeAnimation[];
    /** Repeat count (e.g. `2`, `Infinity` for indefinite). */
    repeatCount?: number;
    /** Whether the animation plays in reverse after completion. */
    autoReverse?: boolean;
    /** Text build type from `p:bldP/@build` in `p:bldLst`. */
    buildType?: PptxTextBuildType;
    /** Build level for multi-level lists from `p:bldP/@bldLvl`. */
    buildLevel?: number;
    /** Group ID linking a `p:bldP` entry to its timing animation node. */
    groupId?: string;
    /**
     * Sound relationship ID to play when animation triggers. Modern PowerPoint
     * (COM-verified against 2016) writes this as a `p:audio/p:cMediaNode`
     * sibling of the effect's own `p:childTnLst`, targeting `p:sndTgt` rather
     * than a shape; the legacy `p:stSnd` form (directly on `p:cTn`) is still
     * accepted on load for round-trip of older-authored decks, but PowerPoint
     * itself no longer writes it and does not recognise it back
     * (`Effect.EffectInformation.SoundEffect` reads empty against it).
     */
    soundRId?: string;
    /** Resolved sound file path from relationship. */
    soundPath?: string;
    /**
     * The embedded sound's `@_name` (from `p:snd`/`p:sndTgt`). For one of
     * PowerPoint's 19 built-in stock sounds this is the exact upper-case file
     * name PowerPoint itself writes (e.g. `"CHIMES.WAV"`); see
     * `pptx-viewer-shared`'s `effect-sound-catalogue.ts`, which matches this
     * value back to a gallery entry. Absent for a custom sound with no name,
     * or when unresolved.
     */
    soundName?: string;
    /** Whether to stop any currently playing sound (`p:endSnd`). */
    stopSound?: boolean;
    /**
     * End-state behaviour from `p:cTn/@fill` (ST_TLTimeNodeFillType, ECMA-376
     * §19.5.27). `hold`/`freeze` mean the effect's final frame persists after
     * it finishes; `remove` (the default when absent) means the target reverts
     * to its pre-effect appearance. `transition` behaves like `hold` until the
     * next time node starts. Absent means the OOXML default (`remove`).
     */
    fill?: 'remove' | 'freeze' | 'hold' | 'transition';
    /**
     * Restart behaviour from `p:cTn/@restart` (ST_TLTimeNodeRestartType).
     * Absent means the OOXML default (`always`).
     */
    restart?: 'always' | 'whenNotActive' | 'never';
    /**
     * Repeat duration in milliseconds from `p:cTn/@repeatDur`. `Infinity`
     * represents the literal `"indefinite"` token.
     */
    repeatDurMs?: number;
    /**
     * Playback speed multiplier from `p:cTn/@spd` (ST_Percentage, normalized
     * from OOXML's 1000ths-of-a-percent storage to a plain percentage, e.g.
     * `150` for 150% / double speed). Absent means normal (100%) speed.
     */
    speedPct?: number;
    /**
     * Reverse the paragraph build order from `p:bldP/@rev` (TEXT build only).
     * Not to be confused with {@link PptxGraphicBuild}'s `reverse` field, which
     * carries the unrelated `p:bldDgm`/`@rev` DIAGRAM-build reverse flag.
     */
    buildReverse?: boolean;
    /**
     * Auto-advance time in milliseconds from `p:bldP/@advAuto`. `Infinity`
     * represents the literal `"indefinite"` token. Absent means the build
     * step waits for a click.
     */
    buildAdvAutoMs?: number;
    /**
     * Per-build-level timing templates from a TEXT `p:bldP/p:tmplLst`
     * (ECMA-376 §19.5.84 CT_TLTemplateList). Parsed for round-trip only; see
     * {@link PptxTimingTemplate} for why they are not consulted at playback.
     */
    buildTemplates?: PptxTimingTemplate[];
    /**
     * Whether the enclosing `p:seq` allows concurrent play with its siblings,
     * from `p:seq/@concurrent`. Parsed for round-trip; not yet honoured by
     * playback (see `docs/guide/limitations.md`).
     */
    seqConcurrent?: boolean;
    /** Next-action behaviour from `p:seq/@nextAc` (ST_TLNextActionType). */
    seqNextAction?: 'none' | 'seek';
    /** Previous-action behaviour from `p:seq/@prevAc` (ST_TLPreviousActionType). */
    seqPrevAction?: 'none' | 'skipTimeNode';
    /**
     * Whether the enclosing click-level group (a direct `p:par` child of the
     * `mainSeq`) begins automatically when the slide appears, rather than waiting
     * for a click.
     *
     * PowerPoint gates a click step with a lone `<p:cond delay="indefinite"/>`;
     * a group that also carries a time-node condition (`onBegin`/`onEnd` with a
     * `@tn`) or a finite delay starts on slide entry ("With/After Previous" as the
     * first effect on the slide). The flat animation list cannot express that on
     * its own, so the parse layer stamps it here.
     */
    groupAutoStart?: boolean;
    /**
     * Index of the enclosing effect-wrapper `p:par` inside the click-level group.
     *
     * Effects that share a wrapper are OOXML siblings: they all start when that
     * wrapper starts, and each `p:cond/@delay` is measured from the wrapper's
     * start, NOT chained off the effect before it. Playback uses this to place
     * simultaneous effects at their true offsets instead of accumulating delays.
     */
    parGroupIndex?: number;
    /**
     * Absolute start offset of the enclosing effect-wrapper from its click group.
     *
     * Structural `p:par` wrappers can carry their own start conditions. Keeping
     * this offset separate from the effect's delay prevents playback from
     * replacing an authored absolute start with a duration-based approximation.
     */
    parGroupDelayMs?: number;
    /** Structured start conditions parsed from `p:stCondLst`. */
    startConditions?: AnimationCondition[];
    /** Structured end conditions parsed from `p:endCondLst`. */
    endConditions?: AnimationCondition[];
    /** Preserved raw `p:endCondLst` XML node for lossless round-trip. */
    rawEndCondLst?: XmlObject;
    /** Color animation data from `p:animClr`. */
    colorAnimation?: PptxColorAnimation;
    /** Text-level target: character range or paragraph range from `p:txEl`. */
    textTarget?: PptxTextAnimationTarget;
    /** Whether this animation is inside an exclusive container (`p:excl`). */
    exclusive?: boolean;
    /**
     * Identifies which `p:excl` container this animation belongs to, when
     * {@link exclusive} is set. ECMA-376 S19.5.24 CT_TLExclusiveTimeNode: at
     * most one direct child of an exclusive container may be active at a
     * time, so starting one child stops any other currently-playing child of
     * the SAME container. Two different `p:excl` containers on the same slide
     * are independent groups; this id (assigned per container encountered
     * during parsing, stable only within one parse's animation list) lets
     * playback tell them apart. Absent when {@link exclusive} is unset.
     */
    exclGroupId?: number;
    /** Command type from `p:cmd` (@_type: call/evt/verb). */
    commandType?: string;
    /** Command string from `p:cmd` (@_cmd). */
    commandString?: string;
    /** Iteration configuration from `p:iterate`. */
    iterate?: PptxAnimationIterate;
    /**
     * Discriminator for non-preset animation kinds. When `undefined`, the
     * entry represents the default shape-effect animation. The `'media'`
     * kind represents a `p:audio` / `p:video` timing node, captured here so
     * playback order in the timeline is preserved alongside other animations.
     */
    kind?: PptxNativeAnimationKind;
    /**
     * For `kind === 'media'`, identifies whether this is an audio or video
     * media node so writers know which OOXML element to re-emit.
     */
    mediaType?: 'audio' | 'video';
    /**
     * SmartArt build attribute (`p:bldDgm/@bld`) when this animation is
     * associated with a SmartArt diagram build. Common values include
     * `whole`, `one`, `lvlOne`, `lvlAtOnce`.
     */
    smartArtBuild?: string;
    /**
     * Graphic-frame build attribute (`p:bldGraphic/@bld`) when this animation
     * is associated with a generic graphic frame build (charts, tables, etc.
     * that aren't OLE charts).
     */
    graphicBuild?: string;
    /**
     * OLE-embedded chart build attribute (`p:bldOleChart/@bld`) when this
     * animation stages an OLE chart graphic frame. Values follow
     * ST_TLOleChartBuildType: `allAtOnce`, `series`, `category`, `seriesEl`,
     * `categoryEl`. Lets a staged-reveal renderer build the chart by series /
     * category / element to match PowerPoint, rather than as one whole element.
     */
    oleChartBuild?: string;
    /** Schema-accurate `p:bldGraphic/p:bldAsOne|p:bldSub` representation. */
    graphicBuildProperties?: PptxGraphicBuild;
    /**
     * Opaque map of `p:cTn` attributes that don't have a typed home on this
     * interface but must round-trip through parse → save. Keys are stored
     * verbatim including the `@_` prefix used by the underlying XML parser
     * (e.g. `@_evtFilter`, `@_display`, `@_masterRel`, `@_nodePh`,
     * `@_endSync`, `@_progress`). The `subTnLst` child element is also
     * preserved here under the literal key `p:subTnLst`. The `afterEffect`
     * attribute is surfaced separately as a typed boolean ({@link afterEffect})
     * because it changes write semantics for subsequent timing nodes.
     */
    cTnAttributes?: Record<string, unknown>;
    /**
     * Whether the OOXML `p:cTn/@afterEffect` flag is set. Indicates this node
     * runs after the parent effect's main body has completed; affects how
     * subsequent peer nodes are sequenced when serialised back to OOXML.
     */
    afterEffect?: boolean;
    /**
     * "After animation" end-state behaviour: dim-to-colour, hide-after-
     * animation, or hide-on-next-click. Populated directly by the
     * native-timing parser (`native-animation-after-effect.ts`) when the
     * effect's `p:cTn/p:subTnLst` carries PowerPoint's genuine after-effect
     * shape, so a real-world deck's build shows up here even with no
     * `pptx:editorMeta`. `applyAfterAnimationFromEditorList` in
     * `pptx-viewer-shared` overrides this from the matching
     * {@link PptxElementAnimation.afterAnimation} entry when the editor's
     * per-element animation list has one (the model the animation panel
     * writes `afterAnimation` into), so an edit through our own UI always wins.
     */
    afterAnimationAction?: PptxAfterAnimationAction;
    /** Dim-to color hex, present when {@link afterAnimationAction} is `dimToColor` AND the dim target is an already-resolved `a:srgbClr`. */
    afterAnimationColor?: string;
    /**
     * The typed theme reference when a `dimToColor` target is an `a:schemeClr`
     * (e.g. `accent2`) instead of `a:srgbClr`: this parse layer has no theme to
     * resolve it to sRGB with (see {@link afterAnimationColor}'s doc), so a
     * playback consumer resolves this against the deck's theme colour map.
     * Mutually exclusive with {@link afterAnimationColor} being set.
     */
    afterAnimationColorRef?: PptxThemeColorRef;
    /**
     * Parsed `p:animEffect` filter descriptor. `presetId`/`presetClass` remain
     * the primary effect selector (see `resolveEffect` in `pptx-viewer-shared`);
     * this is the fallback used when a preset table lookup misses (unmapped or
     * absent `presetId`), which happens for decks authored by tools other than
     * PowerPoint that only emit the SMIL-style filter string.
     */
    effectFilter?: PptxAnimationEffectFilter;
    /**
     * This effect's own `p:cTn/@_id` (a raw OOXML time-node id, not a shape
     * id). Lets playback resolve a `p:cond/@tn` dependency (see
     * {@link AnimationCondition.targetTimeNodeId}) against the SPECIFIC node
     * it names rather than assuming it is always the positionally-previous
     * effect. Absent when the node carried no `@_id`.
     */
    nodeId?: number;
    /**
     * Interpolation mode for this effect's PRIMARY `p:anim`-family behaviour
     * (the same node {@link keyframes}/{@link attrName} were read from), from
     * `@_calcmode` (ST_TLAnimateBehaviorCalcMode, ECMA-376 S19.5.2). See
     * {@link PptxAttributeAnimation.calcMode} for the per-component version.
     */
    calcMode?: 'discrete' | 'lin' | 'fmla';
    /**
     * `p:cBhvr/@_additive` (ST_TLBehaviorAdditiveType, ECMA-376 S19.5.4):
     * controls how this behaviour's value composites with sibling behaviours
     * driving the same attribute on the same target. `sum` accumulates
     * (e.g. a combined scale+rotate), `repl`/`base`/`none`/`mult` replace or
     * otherwise combine. Absent means the OOXML default (`base`).
     */
    cBhvrAdditive?: 'base' | 'sum' | 'repl' | 'mult' | 'none';
    /**
     * `p:cBhvr/@_accumulate` (ST_TLBehaviorAccumulateType): `always` means
     * each `p:cTn/@repeatCount` repeat starts from the PREVIOUS repeat's end
     * value (e.g. a 3x Spin totals 1080deg instead of replaying 0-360 three
     * times); `none` (the OOXML default) resets every repeat.
     */
    cBhvrAccumulate?: 'none' | 'always';
    /**
     * `p:cBhvr/@_xfrmType` (only meaningful on `p:animMotion`): `point`
     * (default) or `img`, a legacy compatibility hint. Round-tripped only.
     */
    cBhvrXfrmType?: 'point' | 'img';
    /**
     * `p:cBhvr/@_override` (ST_TLBehaviorOverrideType): `normal` (default) or
     * `childStyle`, a legacy compatibility hint. Round-tripped only.
     */
    cBhvrOverride?: 'normal' | 'childStyle';
    /**
     * `p:set` discrete attribute assignments composed alongside this effect
     * (ECMA-376 S19.5.79 CT_TLSetBehavior): an instantaneous (non-interpolated)
     * value change, as opposed to {@link attributeAnimations}'s `p:anim`
     * keyframe ramps. PowerPoint authors several font-style emphasis effects
     * this way (Bold Reveal, Underline, Bold Flash, Change Font Size), since
     * "on/off" or "size N" has nothing to interpolate. Not yet consulted by
     * shared playback (round-trip/typed-model only so far).
     */
    setAnimations?: PptxSetAnimation[];
    /**
     * Every behaviour child of this effect (`p:set`, `p:anim`, `p:animEffect`,
     * `p:animScale`, `p:animRot`, `p:animMotion`) with its own timing, as
     * authored. The single-valued fields above flatten a composed preset;
     * this keeps the whole tree so playback can follow what PowerPoint wrote
     * (see `animation-behavior-player` in `pptx-viewer-shared`).
     */
    behaviors?: PptxAnimationBehavior[];
}

/**
 * Native animation kind. The historic shape-targeted preset animations are
 * implicitly the default kind (`undefined`). Media animations (`p:audio`,
 * `p:video`) emit dedicated entries so playback order on the slide timeline
 * is preserved alongside other animations.
 */
declare type PptxNativeAnimationKind = 'media';

/**
 * Accessibility description/title from `p:cNvPr/@descr` / `@title` on a
 * plain shape, text box or connector (`p:sp` / `p:cxnSp`). The same pair of
 * attributes already round-trips for a graphic frame (see
 * {@link TablePptxElement.altText}) and, `descr` only, for a picture
 * ({@link PptxImageProperties.altText}); this mixin extends it to the three
 * element kinds whose PowerPoint Alt Text pane data was previously dropped
 * on load because neither field existed on the model.
 */
declare interface PptxNonVisualDescription {
    /** `p:cNvPr/@descr`. */
    altText?: string;
    /** `p:cNvPr/@title`. */
    title?: string;
}

/**
 * Normal view properties (`p:normalViewPr`).
 * Controls the splitter positions in normal (editing) view.
 */
declare interface PptxNormalViewProperties {
    /** Whether to show outline icons in the slide panel. */
    showOutlineIcons?: boolean;
    /** Whether the outline/slide panel is snapped closed. */
    snapVertSplitter?: boolean;
    /** Vertical splitter bar state: 'minimized' | 'maximized' | 'restored'. */
    vertBarState?: string;
    /** Horizontal splitter bar state. */
    horzBarState?: string;
    /** Whether to prefer single-slide view in the panel. */
    preferSingleView?: boolean;
    /** Restored left region (slide panel width). */
    restoredLeft?: PptxRestoredRegion;
    /** Restored top region (notes panel height). */
    restoredTop?: PptxRestoredRegion;
}

/**
 * Parsed notes master from `ppt/notesMasters/notesMaster1.xml`.
 *
 * @example
 * ```ts
 * const notes: PptxNotesMaster = {
 *   path: "ppt/notesMasters/notesMaster1.xml",
 *   backgroundColor: "#FFFFFF",
 *   placeholders: [{ type: "body" }, { type: "sldImg" }],
 * };
 * // => satisfies PptxNotesMaster
 * ```
 */
declare interface PptxNotesMaster {
    /** File path within the PPTX archive. */
    path: string;
    /** Background colour of the notes master. */
    backgroundColor?: string;
    /** Background image data URL. */
    backgroundImage?: string;
    /** Crop, tiling and image effects authored on the background blip fill. */
    backgroundImageProperties?: PptxImageProperties;
    /** Placeholder shapes found on the notes master. */
    placeholders?: PptxPlaceholderFrame[];
    /** Editable elements on the notes master (header, footer, date, page number, slide image, notes body). */
    elements?: PptxElement[];
    /** Header/footer flags from `<p:hf>` on the notes master (P-H3). */
    headerFooter?: PptxHeaderFooterFlags;
    /** Colour map from `<p:clrMap>` (12 alias attributes). Applied at save time. */
    clrMap?: Record<string, string>;
    /**
     * Notes text defaults from `<p:notesStyle>` (`CT_TextListStyle`, ECMA-376
     * §19.3.1.34): the same `a:defPPr` + `a:lvl1pPr`..`a:lvl9pPr` shape as
     * {@link PptxMasterTextStyles}'s per-category styles, keyed 0-8 with the
     * default at `-1`. Governs the notes body placeholder's font size, indent
     * levels, and bullet style wherever a notes slide does not override them.
     * Parsed read-only for the render cascade; the save side preserves the
     * original `<p:notesStyle>` XML verbatim rather than re-serialising this.
     */
    notesStyle?: PptxTextStyleLevels;
}

/**
 * Photo album metadata from `p:photoAlbum` in `presentation.xml`.
 *
 * Stores settings for presentations created via Insert > Photo Album.
 *
 * @see ECMA-376 Part 1, §19.2.1.27
 */
declare interface PptxPhotoAlbum {
    /** Whether photos are displayed in black-and-white. */
    bw?: boolean;
    /** Whether captions are shown below each photo. */
    showCaptions?: boolean;
    /** Photo album layout (e.g. "1pic", "2pic", "4pic", "fitToSlide"). */
    layout?: string;
    /** Frame style applied to each photo (e.g. "frameStyle1"). */
    frame?: string;
    /**
     * `p:photoAlbum/@isPhoto` (ECMA-376 S19.2.1.27, CT_PhotoAlbum): whether
     * the pictures placed by the album wizard are real photographs, as
     * opposed to clip art or other embedded images. `undefined` when the
     * source authored no explicit value (schema default `false`); this is a
     * purely declarative wizard-provenance flag, not something this library
     * gates any layout/frame behaviour on.
     */
    isPhoto?: boolean;
}

/**
 * `a:cNvPicPr/@preferRelativeResize` (issue G13), a picture-only non-visual
 * property distinct from `a:picLocks`.
 */
declare interface PptxPictureNonVisualProperties {
    /**
     * `a:cNvPicPr/@preferRelativeResize` (ST_Boolean, defaults to `true` when
     * absent). Controls whether a picture's crop rectangle is reinterpreted
     * relative to the picture's ORIGINAL dimensions or its CURRENT
     * (already-resized) dimensions when it is resized again after being
     * cropped. Parsed and round-tripped for now; not yet wired into
     * resize-after-crop arithmetic (this app always uses current-size
     * semantics, which only diverges from `preferRelativeResize="0"` on a
     * second resize after a crop).
     */
    preferRelativeResize?: boolean;
}

/**
 * A placeholder slot declared on a master or layout.
 *
 * The geometry fields are in CSS pixels (EMU / {@link EMU_PER_PX}) and are only
 * present when the shape carried an explicit `a:xfrm`. Placeholders that
 * inherit their frame from the master leave them undefined, so consumers that
 * draw placeholder outlines (the layout gallery) must skip those entries
 * rather than assume a zero-sized box at the origin.
 *
 * @example
 * ```ts
 * const frame: PptxPlaceholderFrame = { type: "body", idx: "1", x: 63, y: 130 };
 * // => satisfies PptxPlaceholderFrame
 * ```
 */
declare interface PptxPlaceholderFrame {
    /** `p:ph/@type`, lower-cased by the parser; defaults to `body` when omitted. */
    type: string;
    /** `p:ph/@idx`, when present. */
    idx?: string;
    /** Left offset in CSS pixels, when the shape declares `a:off`. */
    x?: number;
    /** Top offset in CSS pixels, when the shape declares `a:off`. */
    y?: number;
    /** Width in CSS pixels, when the shape declares `a:ext`. */
    width?: number;
    /** Height in CSS pixels, when the shape declares `a:ext`. */
    height?: number;
}

/** PresentationML `CT_PrintProperties` (`p:prnPr`). */
declare interface PptxPresentationPrintProperties {
    printWhat?: PptxPrintOutput | null;
    colorMode?: PptxPrintColorMode | null;
    hiddenSlides?: boolean | null;
    scaleToFitPaper?: boolean | null;
    frameSlides?: boolean | null;
    /** Original subtree retained for unknown attributes and `p:extLst`. */
    rawXml?: XmlObject;
}

/**
 * Presentation-level properties parsed from `presentationPr.xml`.
 *
 * Controls slideshow behaviour, print settings, custom colours, and grid.
 *
 * @example
 * ```ts
 * const props: PptxPresentationProperties = {
 *   showType: "presented",
 *   loopContinuously: false,
 *   advanceMode: "useTimings",
 * };
 * // => satisfies PptxPresentationProperties
 * ```
 */
declare interface PptxPresentationProperties {
    /** Show type: presented, browsed, kiosk. */
    showType?: 'presented' | 'browsed' | 'kiosk';
    /** Whether to loop the slideshow continuously. */
    loopContinuously?: boolean;
    /** Whether to show without narration. */
    showWithNarration?: boolean;
    /** Whether to show without animation. */
    showWithAnimation?: boolean;
    /** Advance slides mode: manual click or use stored timings. */
    advanceMode?: 'manual' | 'useTimings';
    /** Show slides: 'all', a custom show id, or a from-to range. */
    showSlidesMode?: 'all' | 'customShow' | 'range';
    /** Custom show id to use when showSlidesMode is 'customShow'. */
    showSlidesCustomShowId?: string;
    /** Slide range start (1-based) when showSlidesMode is 'range'. */
    showSlidesFrom?: number;
    /** Slide range end (1-based) when showSlidesMode is 'range'. */
    showSlidesTo?: number;
    /** Whether to show subtitles/captions during presentation mode. */
    showSubtitles?: boolean;
    /** Typed `p:prnPr` settings. Set to null during save to remove the element. */
    printProperties?: PptxPresentationPrintProperties | null;
    /** Most-recently-used colours from the presentation palette. */
    mruColors?: string[];
    /**
     * Pen colour for presentation mode annotations (from `p:showPr/p:penClr`).
     * `p:penClr` is a full `EG_ColorChoice` (P1-G2): a scheme/preset/system
     * swatch resolves to a hex string here just like a direct `a:srgbClr`.
     */
    penColor?: string;
    /**
     * The resolved hex value {@link penColor} had at parse time, and the
     * original `p:penClr` colour-choice XML node, preserved so a save that
     * never touches the pen colour re-emits the original scheme/preset
     * reference verbatim instead of flattening it to a baked `a:srgbClr`.
     * Internal round-trip bookkeeping; not meant to be set by API callers.
     */
    penColorOriginal?: string;
    /** @see penColorOriginal */
    penColorXml?: XmlObject;
    /** Kiosk auto-restart interval in milliseconds (from `p:kiosk/@restart`). Only meaningful when showType is "kiosk". */
    kioskRestartTime?: number;
    /**
     * `p:showPr/p:browse/@showScrollbar` (CT_ShowInfoBrowse §19.2.1.10 /
     * §19.3.1.43), the "Show scrollbar" checkbox in PowerPoint's Set Up Show
     * dialog. Only meaningful when `showType` is `"browsed"`; the schema
     * default is `true`. `undefined` means the source authored no explicit
     * value (or `showType` is not `"browsed"`).
     */
    showScrollbar?: boolean;
}

declare type PptxPrintColorMode = 'bw' | 'gray' | 'clr';

declare type PptxPrintOutput = 'slides' | 'handouts1' | 'handouts2' | 'handouts3' | 'handouts4' | 'handouts6' | 'handouts9' | 'notes' | 'outline';

/**
 * Restored region dimensions for normal view splitter.
 * Represents `p:restoredLeft` or `p:restoredTop`.
 */
declare interface PptxRestoredRegion {
    /** Size as a percentage of the available space (thousandths of a percent). */
    sz: number;
    /** Whether auto-adjust is enabled. */
    autoAdjust?: boolean;
}

/** Output format for the save pipeline. */
declare type PptxSaveFormat = 'pptx' | 'ppsx' | 'pptm' | 'ppt';

/**
 * An ordered section in the presentation (from `p:sectionLst` / `p14:sectionLst`).
 *
 * Sections group consecutive slides under a named heading (visible
 * in the PowerPoint slide sorter).
 *
 * @example
 * ```ts
 * const section: PptxSection = {
 *   id: "sec_1",
 *   name: "Introduction",
 *   slideIds: ["256", "257"],
 * };
 * // => satisfies PptxSection
 * ```
 */
declare interface PptxSection {
    /** Section unique identifier (GUID or synthetic). */
    id: string;
    /** Human-readable section name. */
    name: string;
    /** Ordered list of numeric slide IDs that belong to this section. */
    slideIds: string[];
    /** Whether the section is collapsed in the slide sorter (from p15:sectionPr). */
    collapsed?: boolean;
    /** Section highlight color hex (from p15:sectionPr/@clr). */
    color?: string;
    /** Original section subtree used to preserve unmodelled attributes and extensions. */
    rawXml?: XmlObject;
}

/**
 * One `p:set` discrete (non-interpolated) attribute assignment composed
 * alongside an authored effect. See {@link PptxNativeAnimation.setAnimations}.
 *
 * @see ECMA-376 S19.5.79 CT_TLSetBehavior
 */
declare interface PptxSetAnimation {
    /** Lowercased target attribute from `p:cBhvr/p:attrNameLst/p:attrName`. */
    attrName: string;
    /** Decoded value from `p:to` (same variant shape as a `p:tav/p:val`). */
    value: string | boolean | number;
    /** Discriminant indicating which `p:to` child carried the value. */
    valueType: 'str' | 'bool' | 'int' | 'flt' | 'clr';
    /** Duration from this behaviour's nested `p:cTn/@dur`. */
    durationMs?: number;
    /** Start offset from this behaviour's nested `p:stCondLst`. */
    delayMs?: number;
}

/** `p:set`: a discrete value held from the behaviour's start. */
declare interface PptxSetBehavior extends BehaviorBase {
    kind: 'set';
    value: string | number | boolean;
}

/**
 * Lock attributes from an element's non-visual properties node.
 *
 * When a flag is `true` the corresponding user interaction is disabled
 * in the editor (e.g. `noRotation` prevents free rotation of the shape).
 *
 * One bag covers every family, but the families are NOT interchangeable in
 * the file: `a:spLocks` (`CT_ShapeLocking`), `a:picLocks`, `a:cxnSpLocks`,
 * `a:grpSpLocks` (`CT_GroupLocking`) and `a:graphicFrameLocks`
 * (`CT_GraphicalObjectFrameLocking`) each declare their own attribute subset.
 * `runtime/shape-lock-containers` holds that table and is what decides which
 * of these fields may be written for a given element.
 *
 * @example
 * ```ts
 * const locks: PptxShapeLocks = { noMove: true, noResize: true };
 * // => { noMove: true, noResize: true } satisfies PptxShapeLocks
 * ```
 */
declare interface PptxShapeLocks {
    noGrouping?: boolean;
    noRotation?: boolean;
    noMove?: boolean;
    noResize?: boolean;
    noTextEdit?: boolean;
    noSelect?: boolean;
    noChangeAspect?: boolean;
    noEditPoints?: boolean;
    noAdjustHandles?: boolean;
    noChangeArrowheads?: boolean;
    noChangeShapeType?: boolean;
    /**
     * `a:graphicFrameLocks/@noDrilldown`: forbids selecting the individual
     * parts inside a graphic frame (a chart series, a SmartArt node). Declared
     * ONLY by `CT_GraphicalObjectFrameLocking`, so it is written for tables,
     * charts, SmartArt, OLE objects and graphic-frame media, and never onto
     * `a:spLocks` / `a:picLocks` / `a:cxnSpLocks` / `a:grpSpLocks`.
     */
    noDrilldown?: boolean;
    /**
     * `a:picLocks/@noCrop`: forbids cropping the picture. Declared ONLY by
     * `CT_PictureLocking`, so it is written for pictures (and media authored as
     * a `p:pic`) and never onto the other lock elements.
     */
    noCrop?: boolean;
    /**
     * Text-box flag from `p:cNvSpPr/@txBox`. Not a lock in the strict sense,
     * but it lives on the same non-visual-properties node as `a:spLocks`, so
     * it is captured here to round-trip through the model. When `true` the
     * shape is a plain text box (no fill/line by default).
     */
    txBox?: boolean;
}

/**
 * Shape styling & geometry mixin — present on shapes, connectors, and images.
 *
 * @example
 * ```ts
 * const props: PptxShapeProperties = {
 *   shapeType: "roundRect",
 *   shapeStyle: { fillColor: "#0055AA", strokeWidth: 2 },
 *   shapeAdjustments: { adj: 16667 },
 * };
 * // => satisfies PptxShapeProperties
 * ```
 */
declare interface PptxShapeProperties {
    shapeStyle?: ShapeStyle;
    /** Preset geometry name, e.g. "rect", "ellipse", "roundRect". */
    shapeType?: string;
    /** Geometry adjustment values, e.g. `{ adj: 16667 }`. */
    shapeAdjustments?: Record<string, number>;
    /** Adjustment handles for interactive shape modification (yellow diamond handles). */
    adjustmentHandles?: GeometryAdjustmentHandle[];
}

/**
 * A single slide in a parsed PPTX presentation.
 *
 * Contains the element tree, background settings, notes, comments,
 * transition / animation data, and metadata like layout path and section.
 *
 * @example
 * ```ts
 * const slide: PptxSlide = {
 *   id: "slide1",
 *   rId: "rId2",
 *   slideNumber: 1,
 *   elements: [titleTextBox, subtitleTextBox],
 *   backgroundColor: "#FFFFFF",
 *   notes: "Remember to mention quarterly goals.",
 * };
 * // => satisfies PptxSlide
 * ```
 */
declare interface PptxSlide {
    id: string;
    rId: string;
    /**
     * `p:sldIdLst/p:sldId/@id` (ST_SlideId, 256..2147483647): the numeric key
     * that sections (`p14:sldIdLst/p14:sldId/@id`) and section/summary zooms
     * name slides by.
     *
     * It lives in `presentation.xml`, NOT in the slide part, so it cannot be
     * recovered from `rawXml`. Without it on the model, code that writes a
     * section's membership has nothing correct to write and falls back to the
     * slide NUMBER, which is 1-based and therefore never matches a real deck's
     * ids: the section reloads with no slides in it.
     */
    slideId?: string;
    sourceSlideId?: string;
    /**
     * The slide name, `p:cSld/@name`: loaded from the part, written back on
     * save (an empty string clears the attribute), and settable via
     * `SlideBuilder.setName`.
     */
    name?: string;
    layoutPath?: string;
    layoutName?: string;
    slideNumber: number;
    hidden?: boolean;
    sectionName?: string;
    sectionId?: string;
    elements: PptxElement[];
    backgroundColor?: string;
    backgroundImage?: string;
    /** Crop, tiling and image effects authored on the background blip fill. */
    backgroundImageProperties?: PptxImageProperties;
    backgroundGradient?: string;
    /**
     * Pattern fill on the slide background (`<a:pattFill>` inside `<p:bgPr>`).
     *
     * When present, renderers should draw a real two-colour pattern using
     * the named DrawingML preset (e.g. `"ltDnDiag"`, `"pct50"`). The flat
     * `backgroundColor` field is left set to the foreground colour for
     * fallback rendering paths that don't understand patterns.
     *
     * ECMA-376 §20.1.8.47.
     */
    backgroundPattern?: PptxSlideBackgroundPattern;
    /**
     * `<p:bgPr/@shadeToTitle>`: boolean flag instructing the renderer to
     * anchor the background gradient on the title placeholder as a
     * rectangular path gradient (COM-measured against real PowerPoint;
     * it does NOT recolour toward the title's text colour, despite the
     * attribute's name). Parsed and round-tripped here on the core model;
     * the actual visual effect is applied by `pptx-viewer-shared`'s
     * `getSlideBackgroundStyle` (see `render/background-shade-to-title.ts`),
     * consumed by all five bindings, not by core itself. Legacy PowerPoint
     * 97-2003 hint, not observed in any real-world corpus file this project
     * has collected and not settable from any modern PowerPoint UI; see
     * `docs/guide/limitations.md`.
     *
     * ECMA-376 §19.3.1.2 (CT_BackgroundProperties).
     */
    backgroundShadeToTitle?: boolean;
    transition?: PptxSlideTransition;
    animations?: PptxElementAnimation[];
    /**
     * Read-only anchors for the deck's own (non-editor-authored) effect
     * groups, merged with `animations` by the authoring UI so drag-to-reorder
     * can target any position in the full sequence. See
     * {@link PptxAnimationTimelineAnchor}.
     */
    animationTimelineAnchors?: PptxAnimationTimelineAnchor[];
    /** Native OOXML animation data parsed from `p:timing`. */
    nativeAnimations?: PptxNativeAnimation[];
    /** Preserved raw `p:timing` XML for lossless round-trip of native animations. */
    rawTiming?: XmlObject;
    notes?: string;
    /** Rich text segments for the slide notes (preserves formatting). */
    notesSegments?: TextSegment[];
    /**
     * Parsed shapes from the notes slide's `<p:cSld>/<p:spTree>` so the full
     * notes-page shape tree can be inspected and mutated, not just the body
     * placeholder text. When undefined, the existing notes XML is left
     * untouched on save and only `notes` / `notesSegments` are written.
     */
    notesShapes?: PptxElement[];
    /**
     * Per-notes-slide colour map override parsed from `<p:notes>/<p:clrMapOvr>`.
     * Captured for lossless round-trip of the notes-slide's colour scheme.
     */
    notesClrMapOverride?: Record<string, string>;
    /** Optional `<p:cSld @name>` value of the notes slide, for round-trip. */
    notesCSldName?: string;
    comments?: PptxComment[];
    /** Source package metadata for an Office 2021 p188 comment part. */
    modernCommentPart?: PptxModernCommentPart;
    warnings?: PptxCompatibilityWarning[];
    rawXml?: XmlObject;
    /** Per-slide colour map override parsed from `p:clrMapOvr`. */
    clrMapOverride?: Record<string, string>;
    /** Whether background animations should play (`p:bg/@showAnimation`). */
    backgroundShowAnimation?: boolean;
    /** Whether master slide shapes should be shown on this slide (`p:sld/@showMasterSp`). */
    showMasterShapes?: boolean;
    /**
     * Whether inherited master placeholder animations should replay on this
     * slide (`p:sld/@showMasterPhAnim`). Distinct from {@link showMasterShapes}:
     * this governs animation timing, not shape visibility. Mirrors
     * `p:sldLayout/@showMasterPhAnim`, ECMA-376 §19.3.1.38.
     */
    showMasterPhAnim?: boolean;
    /** Drawing guides parsed from slide extension list. */
    guides?: PptxDrawingGuide[];
    /** When explicitly `false`, the slide is unmodified and save can skip re-serialization. */
    isDirty?: boolean;
    /** Customer data references from `p:custDataLst` on this slide. */
    customerData?: PptxCustomerData[];
    /** ActiveX control references from `p:controls` on this slide. */
    activeXControls?: PptxActiveXControl[];
    /**
     * Shapes parsed from a referenced legacy VML drawing part
     * (`ppt/drawings/vmlDrawing*.vml`, linked via a `legacyDrawing`
     * relationship). These are read-only render hints: the VML part itself is
     * preserved verbatim on save, so this field is not re-serialized.
     */
    legacyVmlElements?: PptxElement[];
    /** Per-slide header/footer flags from `<p:hf>` (P-H3). */
    headerFooterFlags?: PptxHeaderFooterFlags;
    /** Server-backed slide synchronization metadata stored in a related OPC part. */
    slideSynchronization?: PptxSlideSyncProperties;
}

/**
 * Pattern fill on a slide background.
 *
 * Mirrors the `<a:pattFill>` choice inside `<p:bgPr>`. Renderers should
 * draw a 2-colour preset pattern (e.g. `dkDnDiag`, `pct50`).
 *
 * ECMA-376 §20.1.8.47.
 *
 * @example
 * ```ts
 * const pattern: PptxSlideBackgroundPattern = {
 *   preset: "ltDnDiag",
 *   fgColor: "#4472C4",
 *   bgColor: "#FFFFFF",
 * };
 * // => satisfies PptxSlideBackgroundPattern
 * ```
 */
declare interface PptxSlideBackgroundPattern {
    /** DrawingML preset pattern token (`@_prst`). */
    preset: string;
    /** Foreground colour resolved to `#RRGGBB`. */
    fgColor?: string;
    /** Background colour resolved to `#RRGGBB`. */
    bgColor?: string;
}

/**
 * Fluent builder scoped to a single slide.
 * Provides navigation to the slide's elements and notes.
 */
declare class PptxSlideBuilder {
    /** The slide being operated on. */
    private readonly slideValue;
    /** Reference back to the root builder for chaining. */
    private readonly rootBuilder;
    /**
     * @param slideValue - The slide data.
     * @param rootBuilder - The parent builder.
     */
    constructor(slideValue: PptxSlide, rootBuilder: PptxXmlBuilder);
    /** Navigate to the slide's notes builder (getter). */
    get Notes(): PptxSlideNotesBuilder;
    /** Navigate to the slide's notes builder. */
    notes(): PptxSlideNotesBuilder;
    /** Navigate to the slide's elements builder. */
    elements(): PptxSlideElementsBuilder;
    /** Return the underlying slide data. */
    project(): PptxSlide;
    /** Pascal-case alias for {@link project}. */
    Project(): PptxSlide;
    /** Navigate back to the root builder. */
    done(): PptxXmlBuilder;
    /** Pascal-case alias for {@link done}. */
    Done(): PptxXmlBuilder;
}

/**
 * Fluent builder for manipulating the elements array of a single slide.
 * Supports adding, removing, and updating elements by ID.
 */
declare class PptxSlideElementsBuilder {
    private readonly slideValue;
    private readonly slideBuilder;
    /**
     * @param slideValue - The slide whose elements are being modified.
     * @param slideBuilder - The parent slide builder for chaining.
     */
    constructor(slideValue: PptxSlide, slideBuilder: PptxSlideBuilder);
    /**
     * Append an element to the slide's element list.
     * @param element - The element to add.
     * @returns This builder for chaining.
     */
    add(element: PptxElement): this;
    /**
     * Remove an element from the slide by its ID.
     * @param elementId - The ID of the element to remove.
     * @returns This builder for chaining.
     */
    removeById(elementId: string): this;
    /**
     * Update an element in-place by ID using a transform function.
     * @param elementId - The ID of the element to update.
     * @param updater - A function that receives the current element and returns the replacement.
     * @returns This builder for chaining.
     */
    updateById(elementId: string, updater: (current: PptxElement) => PptxElement): this;
    /** Return the current elements array. */
    project(): PptxElement[];
    /** Navigate back to the slide builder. */
    done(): PptxSlideBuilder;
}

/**
 * A slide layout associated with a slide master.
 *
 * @example
 * ```ts
 * const layout: PptxSlideLayout = {
 *   path: "ppt/slideLayouts/slideLayout2.xml",
 *   name: "Title and Content",
 * };
 * // => satisfies PptxSlideLayout
 * ```
 */
declare interface PptxSlideLayout {
    /** File path within the PPTX archive. */
    path: string;
    /** Human-readable layout name. */
    name?: string;
    /** Background colour of the layout. */
    backgroundColor?: string;
    /** Background image data URL for the layout. */
    backgroundImage?: string;
    /** Crop, tiling and image effects authored on the background blip fill. */
    backgroundImageProperties?: PptxImageProperties;
    /** Parsed element shapes on the layout. */
    elements?: PptxElement[];
    /** Placeholder shapes on the layout. */
    placeholders?: PptxPlaceholderFrame[];
    /** Matching name attribute for layout identification (`@matchingName`). */
    matchingName?: string;
    /** Whether the layout is marked as preserved (prevent deletion, `@preserve`). */
    preserve?: boolean;
    /** Whether master placeholder animations should play (`@showMasterPhAnim`). */
    showMasterPhAnim?: boolean;
    /** Whether this layout is user-drawn (`@userDrawn`). */
    userDrawn?: boolean;
    /** Colour map override from `p:clrMapOvr`. */
    clrMapOverride?: Record<string, string>;
    /** Header/footer flags from `<p:hf>` on this layout (P-H3). */
    headerFooter?: PptxHeaderFooterFlags;
}

/**
 * Structured slide master data.
 *
 * @example
 * ```ts
 * const master: PptxSlideMaster = {
 *   path: "ppt/slideMasters/slideMaster1.xml",
 *   name: "Office Theme",
 *   backgroundColor: "#FFFFFF",
 *   themePath: "ppt/theme/theme1.xml",
 * };
 * // => satisfies PptxSlideMaster
 * ```
 */
declare interface PptxSlideMaster {
    /** File path within the PPTX archive. */
    path: string;
    /** Human-readable name if available. */
    name?: string;
    /** Background colour of the slide master. */
    backgroundColor?: string;
    /** Background image data URL for the slide master. */
    backgroundImage?: string;
    /** Crop, tiling and image effects authored on the background blip fill. */
    backgroundImageProperties?: PptxImageProperties;
    /** Theme file path this master references. */
    themePath?: string;
    /** Layout paths associated with this master. */
    layoutPaths?: string[];
    /** Placeholder shapes on the master. */
    placeholders?: PptxPlaceholderFrame[];
    /** Parsed element shapes on the master slide (for master view rendering). */
    elements?: PptxElement[];
    /** Parsed slide layout objects associated with this master. */
    layouts?: PptxSlideLayout[];
    /** Text styles from `p:txStyles` — title, body, and other text defaults. */
    txStyles?: PptxMasterTextStyles;
    /** Header/footer flags from `<p:hf>` on this master (P-H3). */
    headerFooter?: PptxHeaderFooterFlags;
    /**
     * Colour map from `<p:clrMap>` (12 alias attributes: bg1/tx1/bg2/tx2,
     * accent1-6, hlink, folHlink). Applied at save time when present.
     */
    clrMap?: Record<string, string>;
    /**
     * Whether the master is marked as preserved (prevent auto-deletion,
     * `@preserve`). Mirrors {@link PptxSlideLayout.preserve}: PowerPoint
     * silently drops an unused master unless this is set.
     *
     * ECMA-376 §19.3.1.38 (CT_SlideMaster).
     */
    preserve?: boolean;
}

/**
 * Fluent builder for manipulating speaker notes on a single slide.
 * Supports adding, setting, clearing, and retrieving notes text.
 */
declare class PptxSlideNotesBuilder {
    private readonly slideValue;
    private readonly slideBuilder;
    /**
     * @param slideValue - The slide whose notes are being modified.
     * @param slideBuilder - The parent slide builder for chaining.
     */
    constructor(slideValue: PptxSlide, slideBuilder: PptxSlideBuilder);
    /**
     * Append text to existing notes (separated by newline).
     * @param text - The text to append.
     * @returns This builder for chaining.
     */
    add(text: string): this;
    /** Pascal-case alias for {@link add}. */
    Add(text: string): this;
    /**
     * Replace all notes with the given text.
     * @param text - The replacement notes text. Empty string clears notes.
     * @returns This builder for chaining.
     */
    set(text: string): this;
    /** Pascal-case alias for {@link set}. */
    Set(text: string): this;
    /** Remove all notes from the slide. */
    clear(): this;
    /** Pascal-case alias for {@link clear}. */
    Clear(): this;
    /** Return the current notes text, or `undefined` if none. */
    get(): string | undefined;
    /** Pascal-case alias for {@link get}. */
    Get(): string | undefined;
    /** Navigate back to the slide builder. */
    done(): PptxSlideBuilder;
    /** Pascal-case alias for {@link done}. */
    Done(): PptxSlideBuilder;
    /**
     * Synchronize the `notesSegments` array from the plain-text notes string.
     * Splits text on newlines and creates corresponding {@link TextSegment} entries
     * with paragraph break markers between lines.
     */
    private syncSegmentsFromNotes;
}

/**
 * Slide dimensions from `p:sldSz` (CT_SlideSize, ECMA-376 §19.2.1.39).
 *
 * @example
 * ```ts
 * const size: PptxSlideSize = { widthEmu: 9144000, heightEmu: 6858000, type: 'screen4x3' };
 * // => satisfies PptxSlideSize
 * ```
 */
declare interface PptxSlideSize {
    /** `@cx` in EMU. Omitted or non-positive values leave the loaded width alone. */
    widthEmu?: number;
    /** `@cy` in EMU. Omitted or non-positive values leave the loaded height alone. */
    heightEmu?: number;
    /**
     * `@type` (ST_SlideSizeType). The schema default is `custom`, which is
     * why PowerPoint omits the attribute for a non-preset size.
     */
    type?: string;
}

/** Metadata from a `p:sldSyncPr` slide synchronization data part. */
declare interface PptxSlideSyncProperties {
    serverSlideId: string;
    serverSlideModifiedTime: string;
    clientInsertedTime: string;
    extensionList?: XmlObject;
    rawXml?: XmlObject;
    partPath?: string;
    relationshipId?: string;
}

declare interface PptxSlideTransition {
    type: PptxTransitionType;
    /** Schema-defined transition speed. Defaults to `fast` when omitted. */
    speed?: PptxTransitionSpeed;
    durationMs?: number;
    direction?: string;
    advanceOnClick?: boolean;
    advanceAfterMs?: number;
    /** Number of spokes for wheel transition (1-8). */
    spokes?: number;
    /** Pattern type for shred transition. */
    pattern?: string;
    /**
     * Through-black flag (OOXML `@_thruBlk`). COM-verified to actually apply to
     * `cut` and `fade` (see {@link TRANSITION_THRUBLK_TYPES}); parsed generically
     * off any standard transition child so an unexpected authored value still
     * round-trips.
     */
    thruBlk?: boolean;
    /** Split orientation (horz/vert) parsed from `@_orient`. */
    orient?: PptxSplitOrientation;
    /**
     * Morph granularity from `<p159:morph @option>`: how finely PowerPoint
     * matches content between the two slides. Only meaningful when
     * {@link type} is `morph`; defaults to `byObject` when the attribute is
     * absent, matching PowerPoint's own default.
     */
    morphOption?: PptxMorphOption;
    /** Relationship ID of transition sound from `p:sndAc/p:stSnd/@r:embed` when present. */
    soundRId?: string;
    /** Embedded WAV display name from `p:stSnd/p:snd/@name`. */
    soundName?: string;
    /** Whether the transition sound repeats until another sound starts. */
    soundLoop?: boolean;
    /** Resolved transition sound media path within the package. */
    soundPath?: string;
    /** Human-readable sound file name (extracted from soundPath, or set by the
     * UI when a new file is picked, before it has a soundPath at all). */
    soundFileName?: string;
    /**
     * A newly-picked local sound file awaiting embedding, as a `data:` URL.
     * Set by the transitions ribbon's Sound picker (`applyTransitionSoundFile`
     * in `pptx-viewer-shared`) when the user chooses a file that is not yet
     * part of the package; mirrors `imageData`/`mediaData` on picture and media
     * elements. The save pipeline (`embedTransitionSound`) writes the bytes to
     * `ppt/media/`, mints a relationship, sets `soundRId`/`soundPath`, and
     * clears this field so a later save does not re-embed the same bytes.
     */
    soundData?: string;
    /**
     * When true, the transition stops the currently-playing sound (OOXML `p:sndAc/p:endSnd`).
     * Mutually exclusive with `soundRId`/`soundPath` (which use `p:stSnd`).
     */
    stopSound?: boolean;
    /** Preserved sound-action XML node from `p:sndAc` for lossless round-trip. */
    rawSoundAction?: XmlObject;
    /** Preserved extension-list XML node from `p:extLst` within the transition for lossless round-trip. */
    rawExtLst?: XmlObject;
    /** Original transition node, retained to preserve unknown attributes and children. */
    rawTransition?: XmlObject;
}

declare interface PptxSmartArtAlgorithmParameter {
    type: string;
    value?: string;
}

declare interface PptxSmartArtChoose {
    name?: string;
    when: PptxSmartArtWhen[];
    otherwise?: {
        name?: string;
        rawXml?: XmlObject;
    } | null;
    rawXml?: XmlObject;
}

/**
 * Background / outline extracted from `dgm:bg` and `dgm:whole`.
 *
 * @example
 * ```ts
 * const chrome: PptxSmartArtChrome = {
 *   backgroundColor: "#F0F0F0",
 *   outlineColor: "#333333",
 *   outlineWidth: 1,
 * };
 * // => satisfies PptxSmartArtChrome
 * ```
 */
declare interface PptxSmartArtChrome {
    /**
     * Background fill colour (hex). When the real `dgm:bg` fill is a gradient
     * or pattern (see {@link PptxSmartArtChrome.backgroundFillXml}), this is an
     * APPROXIMATION (the gradient's first stop, or the pattern's foreground
     * colour) for a consumer that only wants one display colour, not the full fill.
     */
    backgroundColor?: string;
    /**
     * Raw `dgm:bg` fill XML, present only when the background is a gradient or
     * pattern fill (a solid fill is fully captured by {@link PptxSmartArtChrome.backgroundColor}
     * alone). Round-trip only: `smartart-save-chrome.ts` re-emits this verbatim
     * instead of flattening the fill to a solid colour on save.
     */
    backgroundFillXml?: PptxSmartArtRawBackgroundFill;
    /** Outline stroke colour (hex). */
    outlineColor?: string;
    /** Outline stroke width in points. */
    outlineWidth?: number;
}

declare type PptxSmartArtColorApplicationMethod = 'span' | 'cycle' | 'repeat';

/** CT_Colors application metadata. Color-choice children remain preserved XML. */
declare interface PptxSmartArtColorListMetadata {
    method?: PptxSmartArtColorApplicationMethod;
    hueDirection?: PptxSmartArtHueDirection;
}

/** CT_CTStyleLabel metadata from a color-transform definition. */
declare interface PptxSmartArtColorStyleLabel {
    name: string;
    fill?: PptxSmartArtColorListMetadata;
    line?: PptxSmartArtColorListMetadata;
    effect?: PptxSmartArtColorListMetadata;
    textLine?: PptxSmartArtColorListMetadata;
    textFill?: PptxSmartArtColorListMetadata;
    textEffect?: PptxSmartArtColorListMetadata;
}

/** Typed CT_ColorTransform metadata and the resolved legacy color palette. */
declare interface PptxSmartArtColorTransform extends PptxSmartArtDefinitionMetadata {
    /** Legacy resolved display name. */
    name?: string;
    /** Ordered resolved fill colors for rendering. */
    fillColors: string[];
    /** Ordered resolved line colors for rendering. */
    lineColors: string[];
    /** Ordered resolved text-fill colors (primary styleLbl `txFillClrLst`). */
    textFillColors?: string[];
    /** Ordered resolved text-line colors (primary styleLbl `txLinClrLst`). */
    textLineColors?: string[];
    /** Ordered resolved effect colors (primary styleLbl `effectClrLst`). */
    effectColors?: string[];
    /** Ordered resolved text-effect colors (primary styleLbl `txEffectClrLst`). */
    textEffectColors?: string[];
    /** Fill-list span/cycle + hue-direction interpolation of the primary styleLbl. */
    fillInterpolation?: PptxSmartArtColorListMetadata;
    /** Line-list span/cycle + hue-direction interpolation of the primary styleLbl. */
    lineInterpolation?: PptxSmartArtColorListMetadata;
    /** Ordered CT_CTStyleLabel metadata. */
    labels?: PptxSmartArtColorStyleLabel[];
    /**
     * Every `styleLbl`'s own resolved fill/line colour list, keyed by name
     * (e.g. `node1`, `asst0`, `bgShp`, `revTx`). Unlike {@link fillColors} /
     * {@link lineColors} (which collapse to ONE "primary" node-role list),
     * this keeps every role so a node can be coloured from its OWN role's
     * palette (see `PptxSmartArtNode.styleRole` and `applySmartArtRoleColors`)
     * instead of a generic cycled colour.
     */
    roleColors?: Record<string, SmartArtRoleColorList>;
}

/**
 * A connection between two SmartArt data-model nodes.
 *
 * @example
 * ```ts
 * const conn: PptxSmartArtConnection = {
 *   sourceId: "1",
 *   destId: "2",
 *   type: "parOf",
 * };
 * // => satisfies PptxSmartArtConnection
 * ```
 */
declare interface PptxSmartArtConnection {
    /** Stable CT_Cxn model identifier. Required when serialized. */
    modelId?: string | null;
    /** Model ID of the source node. */
    sourceId: string;
    /** Model ID of the destination node. */
    destId: string;
    /** Connection type (e.g. "parOf", "presOf", "sibTrans"). */
    type?: string;
    /** Source index for ordering sibling connections. */
    srcOrd?: number;
    /** Destination index for ordering. */
    destOrd?: number;
    /** Model ID of the parent transition point associated with this edge. */
    parentTransitionId?: string | null;
    /** Model ID of the sibling transition point associated with this edge. */
    siblingTransitionId?: string | null;
    /** Layout presentation identifier used by presentation connections. */
    presentationId?: string | null;
    /**
     * Connector text, read from the linked `parTrans`/`sibTrans` transition
     * point's `dgm:t` (via {@link parentTransitionId} / {@link siblingTransitionId}).
     * PowerPoint's own diagram editor lets a user type text directly onto an
     * org-chart relationship connector; `undefined` when the transition point
     * carries no text. Written back to that point on save.
     */
    label?: string;
}

/** Editable DiagramML CT_Constraint. */
declare interface PptxSmartArtConstraint extends PptxSmartArtConstraintTarget {
    type: string;
    referenceType?: string;
    referenceFor?: PptxSmartArtConstraintRelationship;
    referenceForName?: string;
    referencePointType?: PptxSmartArtConstraintPointType;
    operator?: PptxSmartArtConstraintOperator;
    value?: number;
    factor?: number;
    /** Original constraint retained for foreign attributes and extension content. */
    rawXml?: XmlObject;
}

declare type PptxSmartArtConstraintOperator = 'none' | 'equ' | 'gte' | 'lte';

declare type PptxSmartArtConstraintPointType = 'all' | 'doc' | 'node' | 'norm' | 'nonNorm' | 'asst' | 'nonAsst' | 'parTrans' | 'pres' | 'sibTrans';

declare type PptxSmartArtConstraintRelationship = 'self' | 'ch' | 'des';

declare interface PptxSmartArtConstraintTarget {
    for?: PptxSmartArtConstraintRelationship;
    forName?: string;
    pointType?: PptxSmartArtConstraintPointType;
}

/**
 * Complete parsed SmartArt data for a {@link SmartArtPptxElement}.
 *
 * @example
 * ```ts
 * const data: PptxSmartArtData = {
 *   resolvedLayoutType: "hierarchy",
 *   layout: "hierarchy",
 *   colorScheme: "colorful1",
 *   style: "moderate",
 *   nodes: [
 *     { id: "1", text: "CEO", children: [
 *       { id: "2", text: "VP Marketing", parentId: "1" },
 *     ]},
 *   ],
 * };
 * // => satisfies PptxSmartArtData
 * ```
 */
declare interface PptxSmartArtData {
    layoutType?: string;
    resolvedLayoutType?: SmartArtLayoutType;
    /** Named layout preset (used when creating new SmartArt). */
    layout?: SmartArtLayout;
    /** Colour scheme for the SmartArt graphic. */
    colorScheme?: SmartArtColorScheme;
    /** Visual style intensity. */
    style?: SmartArtStyle;
    nodes: PptxSmartArtNode[];
    /** Connections between data-model nodes. */
    connections?: PptxSmartArtConnection[];
    /** Pre-computed shapes from `ppt/diagrams/drawing*.xml`. */
    drawingShapes?: PptxSmartArtDrawingShape[];
    /** Background and outline chrome from `dgm:bg` / `dgm:whole`. */
    chrome?: PptxSmartArtChrome;
    /** Colour transform from `ppt/diagrams/colors*.xml`. */
    colorTransform?: PptxSmartArtColorTransform;
    /** Quick style from `ppt/diagrams/quickStyles*.xml`. */
    quickStyle?: PptxSmartArtQuickStyle;
    /** Editable metadata from the related DiagramML layout definition. */
    layoutDefinition?: PptxSmartArtLayoutDefinition;
    /**
     * Presentation layout variables (direction, hierarchy branch, org-chart,
     * child limits, bullets) from `dgm:presLayoutVars` / layout `dgm:varLst`.
     * Consulted by the fallback layout engine for direction/org-chart hints.
     */
    presLayoutVars?: PptxSmartArtPresLayoutVars;
    /**
     * The deck's own theme minor-Latin font (`a:fontScheme/a:minorFont/a:latin/
     * @typeface`): what SmartArt text actually renders in when no per-run
     * `a:latin` override is present (the common case - see
     * `smartart-layout-item-font-size.ts`'s font-fit, the one consumer).
     * Undefined when the theme carries no font scheme at all.
     */
    themeMinorFont?: string;
    /** Relationship ID for the diagram data part (for round-trip save). */
    dataRelId?: string;
    /** Relationship ID for the diagram layout part. */
    layoutRelId?: string;
    /** Relationship ID for the drawing part. */
    drawingRelId?: string;
    /** Relationship ID for the colours part. */
    colorsRelId?: string;
    /** Relationship ID for the quick-styles part. */
    styleRelId?: string;
    /** Internal save hint: the layout definition changed in the editor. */
    layoutDirty?: boolean;
    /** Internal save hint: typed layout-definition metadata changed. */
    layoutDefinitionDirty?: boolean;
    /** Internal save hint: quick-style definition metadata changed. */
    quickStyleDirty?: boolean;
    /** Internal save hint: color-transform definition metadata changed. */
    colorTransformDirty?: boolean;
    /** Internal save hint: cached drawing geometry or text changed in the editor. */
    drawingDirty?: boolean;
}

declare interface PptxSmartArtDefinitionCategory {
    type: string;
    priority: number;
}

declare interface PptxSmartArtDefinitionMetadata {
    uniqueId?: string;
    minimumVersion?: string;
    titles?: PptxSmartArtDefinitionText[];
    descriptions?: PptxSmartArtDefinitionText[];
    categories?: PptxSmartArtDefinitionCategory[];
}

declare interface PptxSmartArtDefinitionText {
    value: string;
    language?: string;
}

/**
 * A pre-computed shape from `ppt/diagrams/drawing*.xml`.
 *
 * @example
 * ```ts
 * const shape: PptxSmartArtDrawingShape = {
 *   id: "s1",
 *   shapeType: "roundRect",
 *   x: 100, y: 50, width: 200, height: 80,
 *   fillColor: "#4F81BD",
 *   text: "CEO",
 * };
 * // => satisfies PptxSmartArtDrawingShape
 * ```
 */
declare interface PptxSmartArtDrawingShape extends PptxCustomPathProperties {
    /** Shape ID within the drawing. */
    id: string;
    /** Preset geometry type (e.g. "roundRect", "ellipse"). */
    shapeType?: string;
    /** Position and size in EMU-based pixels. */
    x: number;
    y: number;
    width: number;
    height: number;
    /** Rotation in degrees. */
    rotation?: number;
    /** Horizontal/vertical mirrors declared on the cached drawing transform. */
    flipHorizontal?: boolean;
    flipVertical?: boolean;
    /** Skew along the X axis in degrees. */
    skewX?: number;
    /** Skew along the Y axis in degrees. */
    skewY?: number;
    /** Preset-geometry adjustment values from `a:prstGeom/a:avLst`. */
    shapeAdjustments?: Record<string, number>;
    /**
     * The cached shape declares `a:noFill`. Renderers must leave it unpainted
     * rather than substituting a palette colour, because these shapes usually sit
     * on top of a painted shape whose fill has to stay visible.
     */
    fillNone?: boolean;
    /** Solid fill colour (hex). */
    fillColor?: string;
    /**
     * Opacity (0..1) of the solid fill, from the colour's `a:alpha` (Basic Venn
     * paints its circles at 50% so overlaps blend). Absent when opaque.
     */
    fillOpacity?: number;
    /**
     * Gradient fill stops when the cached shape uses `a:gradFill`. Positions are
     * 0..100 (percent). Renderers emit an SVG/CSS gradient instead of a flat box.
     */
    fillGradientStops?: Array<{
        color: string;
        position: number;
        opacity?: number;
    }>;
    /** Gradient geometry type (`linear` for `a:lin`, `radial` for `a:path`). */
    fillGradientType?: 'linear' | 'radial';
    /** Linear gradient angle in degrees (0..360). */
    fillGradientAngle?: number;
    /** Pattern fill preset name from `a:pattFill/@prst` (e.g. "pct50", "cross"). */
    fillPatternPreset?: string;
    /** Pattern fill foreground colour (hex) from `a:pattFill/a:fgClr`. */
    fillPatternForegroundColor?: string;
    /** Pattern fill background colour (hex) from `a:pattFill/a:bgClr`. */
    fillPatternBackgroundColor?: string;
    /**
     * Relationship id of a picture (blip) fill's embedded image, from
     * `a:blipFill/a:blip/@r:embed`. The image bytes are resolved separately; see
     * {@link fillImageUrl}.
     */
    fillBlipEmbedId?: string;
    /**
     * Resolved data-URI/URL for a picture (blip) fill, when the embedded image
     * part could be resolved. Absent when only {@link fillBlipEmbedId} is known.
     */
    fillImageUrl?: string;
    /** Whether the cached shape carries an outer-shadow effect (`a:effectLst`). */
    hasShadow?: boolean;
    /** Resolved outer-shadow colour (hex), when present. */
    shadowColor?: string;
    /** Stroke colour (hex). */
    strokeColor?: string;
    /** Stroke width in points. */
    strokeWidth?: number;
    /** Text content of the shape. */
    text?: string;
    /** Standard rich-text segments projected from the associated SmartArt node. */
    textSegments?: TextSegment[];
    /** Font size in CSS pixels. */
    fontSize?: number;
    /** Font colour (hex). */
    fontColor?: string;
    /** Authored font family from the first styled run. */
    fontFamily?: string;
    /** Authored font weight (400 or 700). */
    fontWeight?: number;
    /** Authored font style. */
    fontStyle?: 'normal' | 'italic';
    /** Absolute line height in CSS pixels from `a:spcPts`. */
    lineHeight?: number;
    /** Relative line height from `a:spcPct`. */
    lineHeightRatio?: number;
    /** Absolute spacing after a paragraph in CSS pixels. */
    lineSpacingAfter?: number;
    /** Relative spacing after a paragraph. */
    lineSpacingAfterRatio?: number;
    /** Text-body insets in CSS pixels. */
    textInsetLeft?: number;
    textInsetTop?: number;
    textInsetRight?: number;
    textInsetBottom?: number;
    /** DiagramML text vertical anchor (`t`, `ctr`, or `b`). */
    textVerticalAnchor?: string;
    /** Independent DiagramML text-frame geometry from `dsp:txXfrm`. */
    textFrameX?: number;
    textFrameY?: number;
    textFrameWidth?: number;
    textFrameHeight?: number;
    /**
     * 3D scene (camera/light rig/backdrop) from `dsp:spPr/a:scene3d`, when this
     * cached shape carries its own per-shape camera. Bevel quick styles
     * (Polished, Inset, Cartoon, Powder) cache one per shape (always
     * `orthographicFront`, so the 2D layout stays undistorted). Scene quick
     * styles (Brick, Flat, Metallic, Sunset, Bird's Eye) instead put ONE camera
     * on the whole diagram (see `PptxSmartArtQuickStyle.scene3d`) and leave this
     * undefined on every shape.
     */
    scene3d?: Pptx3DScene;
    /**
     * 3D extrusion/bevel/contour/material from `dsp:spPr/a:sp3d`. PowerPoint
     * caches this fully resolved (from the quick style's per-label `dgm:sp3d`)
     * on every shape for every non-flat quick style, bevel or scene alike.
     */
    shape3d?: Pptx3DShape;
    /**
     * Text-body 3D extrusion/bevel from `dsp:txBody/a:bodyPr/a:sp3d`. Rare:
     * present when a quick style extrudes the label text itself off the shape
     * face (e.g. Bird's Eye Scene: `extrusionH="28000"`), rather than only the
     * shape body.
     */
    text3d?: Text3DStyle;
    /**
     * The presentation style label (`presStyleLbl`: `node1`, `revTx`,
     * `sibTrans2D1`, ...) of the layout node a REGENERATED shape was laid out
     * from, when the layout engine reports it. Picks the quick-style label
     * whose 3D the shape takes; `undefined` on cached (parsed) shapes.
     */
    styleLabel?: string;
}

declare interface PptxSmartArtForEach extends PptxSmartArtIteratorAttributes {
    rawXml?: XmlObject;
}

declare type PptxSmartArtHueDirection = 'cw' | 'ccw';

declare interface PptxSmartArtIteratorAttributes {
    name?: string;
    reference?: string;
    axis?: string[];
    pointTypes?: string[];
    hideLastTransition?: boolean[];
    start?: number[];
    count?: number[];
    step?: number[];
}

/** Typed DiagramML CT_Algorithm data attached to a layout node. */
declare interface PptxSmartArtLayoutAlgorithm {
    type: string;
    revision?: number;
    parameters?: PptxSmartArtAlgorithmParameter[];
}

declare interface PptxSmartArtLayoutCategory {
    type: string;
    priority: number;
}

/** Metadata and root node from DiagramML CT_DiagramDefinition. */
declare interface PptxSmartArtLayoutDefinition {
    uniqueId?: string;
    minimumVersion?: string;
    defaultStyle?: string;
    titles?: PptxSmartArtLocalizedText[];
    descriptions?: PptxSmartArtLocalizedText[];
    categories?: PptxSmartArtLayoutCategory[];
    rootNode: PptxSmartArtLayoutNode;
    /** Original definition retained for constraint evaluation and foreign rules. */
    rawXml?: XmlObject;
    /**
     * The un-parsed layout-definition part text (starting at `<dgm:layoutDef>`,
     * XML declaration included). `rawXml` above loses the document order of
     * differently-named siblings (the package-wide `fast-xml-parser`
     * configuration groups children into one array per tag), which the
     * per-point DiagramML engine (`core/utils/smartart-engine/`) needs to
     * execute a `layoutNode` body's `forEach`/`choose`/`constrLst` statements
     * in their real declared sequence - see that package's `ordered-xml.ts`.
     * `undefined` when the part could not be read (matches `rawXml`'s own
     * optionality); the engine falls back to the legacy interpreter then.
     */
    rawXmlText?: string;
}

/** Identity and ordering metadata from DiagramML CT_LayoutNode. */
declare interface PptxSmartArtLayoutNode {
    name?: string;
    styleLabel?: string;
    childOrder?: 'b' | 't';
    moveWith?: string;
    algorithm?: PptxSmartArtLayoutAlgorithm;
    forEach?: PptxSmartArtForEach[];
    choose?: PptxSmartArtChoose[];
    constraints?: PptxSmartArtConstraint[];
    rules?: PptxSmartArtNumericRule[];
    /** `dgm:shape`: this node's own preset geometry override, when present. */
    shape?: PptxSmartArtLayoutNodeShape;
    /**
     * `dgm:presOf` (CT_PresentationOf, same iterator shape as `dgm:forEach`):
     * which data-model point(s) this node's OWN text/geometry binds to -
     * `axis: ['self']` the point currently being iterated, `['des']` all of
     * its descendants, `['ch']` its direct children, and so on. Absent or
     * empty `axis` (including a bare `<dgm:presOf/>`) means the node carries
     * no text of its own (a pure positioning/decoration wrapper - `composite`,
     * `sp` spacer, connector cap). See `smartart-layout-interpreter-item-
     * roles.ts`, the one consumer: it is what lets the interpreter tell a
     * text-bearing per-item role (a list layout's `childText`, a card
     * layout's `roleText`/`bodyText`) apart from a same-generation sibling
     * that positions or decorates instead.
     */
    presentationOf?: PptxSmartArtIteratorAttributes;
    /**
     * EVERY `dgm:constr` reachable from this node, including ones declared
     * inside a `dgm:choose`/`dgm:if`/`dgm:else` that wraps THIS layoutNode's
     * `constrLst` (a genuinely conditional constraint set, e.g. one branch
     * per data-point count - `gear`'s composite positions its `gear1`/
     * `gear2`/`gear3` slots this way, so its plain, direct-child-only
     * `constraints` above is empty for it). Stops at a nested `dgm:layoutNode`
     * boundary: that child's own conditional constrLst becomes ITS
     * `allConstraints`, not folded into the parent's. Read-only /
     * interpretation-only - `constraints` above (this node's own DIRECT
     * constrLst) remains the one `applySmartArtLayoutDefinition` round-trips,
     * so editing an unrelated property can never collapse a genuinely
     * conditional constrLst into a single branch. `undefined` when this node
     * declares no constrLst at all, in or out of a choose (the common case);
     * otherwise a superset of `constraints` (every branch, blindly unioned -
     * this interpreter does not evaluate `dgm:choose` conditions when
     * indexing constraints, matching the same "flatten both branches"
     * convention `nestedLayoutNodes` already uses for `children`). See
     * `smartart-constraint-solver.ts`'s `buildConstraintIndex`, the only
     * consumer.
     */
    allConstraints?: PptxSmartArtConstraint[];
    children?: PptxSmartArtLayoutNode[];
    /**
     * The iterator attributes of the ENCLOSING `dgm:forEach` this node was
     * found through, when `nestedLayoutNodes` (`smartart-layout-definition
     * .ts`) reached it by walking one - as opposed to being a direct child of
     * its parent layoutNode, or reached only through a `dgm:choose` wrapper
     * (a condition, not an iteration, leaves this `undefined`).
     *
     * `forEach` above records a node's OWN direct `dgm:forEach` children
     * (which wrap ITS descendants); this is the opposite direction - the
     * forEach that wraps the node ITSELF, one level up. A layoutNode can sit
     * inside more than one enclosing forEach only via nesting, so this is
     * always the SINGLE nearest one, not a list.
     *
     * This is what tells a genuinely repeated per-child template
     * (`axis="ch"`, `ptType` absent or `"node"`) apart from a once-only or
     * transition-only sibling that merely happens to sit inside SOME
     * `dgm:forEach` (a `ptType="parTrans"`/`"sibTrans"` connector, or
     * `axis="followSib" cnt="1"`) - both can be direct siblings under the
     * SAME parent layoutNode (`lProcess1`'s `vertFlow` has one forEach for
     * its `parTrans` connector and a SEPARATE one, `axis="ch"`, for its
     * repeated `child` items; `vertFlow.forEach` bundles both, but only
     * `child.forEachOrigin` says which ONE produced it). See
     * `smartart-layout-interpreter-item-roles-recursive.ts`, the one
     * consumer. Read-only / interpretation-only, like `allConstraints`:
     * never round-tripped by `applySmartArtLayoutDefinition`.
     */
    forEachOrigin?: PptxSmartArtIteratorAttributes;
    /**
     * The conditions of EVERY enclosing `dgm:if` this node was found through,
     * outermost first, when `nestedLayoutNodes` (`smartart-layout-
     * definition.ts`) reached it via one or more `dgm:choose`'s `if` branches
     * (as opposed to a direct child, a `dgm:else` branch contributing no
     * condition of its own - see below - or a `dgm:forEach`, which sets
     * {@link forEachOrigin} instead). ALL must hold (evaluate `!== false`,
     * per {@link chooseGuard}'s own AND semantics - see `evaluateWhen`) for
     * this node's branch to be genuinely live. A caller that already has the
     * data-model node list can use this instead of treating every
     * choose-flattened branch as unconditionally present
     * (`nestedLayoutNodes`' pre-existing "flatten every branch" convention,
     * still the default when this is absent or a caller does not evaluate
     * it) - e.g. `cycle-matrix--fallback-n2.pptx`'s `child1group`..
     * `child4group`, each gated on a DIFFERENT top-level point existing and
     * having its own child (`axis="ch ch" st="N 1" cnt="1 0" func="cnt"
     * op="gte" val="1"`).
     *
     * A CHAIN, not a single condition, because a node can sit inside NESTED
     * `dgm:choose`s whose OWN conditions are each individually necessary -
     * `sub-step-process--hier5.pptx`'s `chLin1`..`chLin7` each sit inside
     * BOTH an outer `dgm:if func="pos" op="equ" val="N"` (which one of the
     * 7 hand-duplicated per-position templates this is) AND an inner,
     * nearly-vacuous `dgm:if func="cnt" op="gte" val="1"` (has >= 1 point at
     * all) - keeping only the NEAREST (inner) one, as an earlier single-
     * condition design did, loses the ONE piece of information (the outer
     * `pos` guard) that actually discriminates `chLin1` from `chLin2`.
     *
     * A `dgm:else` branch contributes NO condition of its own (ECMA-376
     * defines it as "none of the sibling ifs matched", which would need the
     * FULL sibling list's conditions negated and ANDed together, not a
     * single condition - no gallery fixture measured needs an else branch's
     * own guard yet, so it is left unconditional, matching the pre-existing
     * flatten-everything behaviour) but does NOT clear any OUTER ancestor
     * guard already accumulated before it. Evaluate with `smartart-layout-
     * interpreter-when.ts`'s `evaluateWhen`, once per entry, ANDed.
     */
    chooseGuard?: PptxSmartArtWhen[];
    /**
     * ROUND 42: the forEach iterator active WHEN EACH ENTRY of {@link
     * chooseGuard} was declared (index-parallel with it, `undefined` per
     * entry when no forEach was active at that point) - NOT the same as
     * {@link forEachOrigin}, which is always this NODE's own single nearest
     * enclosing forEach, however deep. A `dgm:if` declared ABOVE a `dgm:forEach`
     * that this node's own branch happens to descend through afterwards needs
     * ITS OWN, SHALLOWER anchor for a `func="cnt"`/`"maxDepth"`-family
     * `@axis` condition, not this node's deeper one - `funnel--flat3.pptx`'s
     * `item1`/`item2`/`item3` (`chooseGuard: [Name5's axis="ch" func="cnt"
     * op="gte" val="1"]`, declared directly under the composite root, BEFORE
     * each item's own per-item `dgm:forEach axis="ch" st="2"/"3"/"4" cnt="1"`)
     * is exactly this shape: evaluating Name5's condition anchored to item1's
     * OWN forEach binding (one specific data point, with no children of its
     * own in a flat dataset) wrongly resolves its `axis="ch"` child count to
     * 0 instead of the diagram's real top-level count, dropping the item
     * entirely - `chooseGuardOrigins[i]` for that entry is `undefined`
     * (Name5 sits above ANY forEach), so the guard correctly stays
     * root-relative. See `smartart-layout-interpreter-composite-
     * candidates.ts`'s `guardAllows`, the one production consumer.
     * `undefined` whenever {@link chooseGuard} itself is (no enclosing
     * choose at all).
     */
    chooseGuardOrigins?: (PptxSmartArtIteratorAttributes | undefined)[];
    /**
     * The chain of every enclosing `dgm:choose`'s own GROUP identity + this
     * node's ordinal position within it + THAT branch's own condition,
     * outermost first - identifies WHICH `dgm:choose` instance and WHERE
     * within its own `dgm:if`/`dgm:else` list this node's branch sits, unlike
     * {@link chooseGuard} (a flat AND-chain of every condition with no group/
     * position identity, and no entry at all for a `dgm:else` branch, which
     * has no condition of its own - see that field's doc comment). `id` is a
     * synthetic, process-unique identifier assigned per `dgm:choose` instance
     * during flattening (`smartart-layout-definition-nesting.ts`'s
     * `nestedLayoutNodes`, a monotonic counter - NOT round-tripped, NOT the
     * choose's own `@_name`, which is not guaranteed unique across a whole
     * layoutDef); `ordinal` is 0-based document order within that ONE choose
     * (every `dgm:if` in order, then `dgm:else` last, if present); `guard` is
     * that branch's OWN condition (`undefined` for a `dgm:else` entry, which
     * has none - deliberately kept PER-ENTRY rather than cross-referenced by
     * index against {@link chooseGuard}, whose own length can diverge from
     * this chain's whenever an ancestor `dgm:else` contributed a group
     * position but no guard).
     *
     * Lets a consumer recover ECMA-376's real `dgm:choose` semantics - "the
     * FIRST branch whose condition holds wins, siblings never coexist" -
     * from the flattened `.children` array, where that grouping would
     * otherwise be lost: `balance--hier5.pptx`'s `balance_NN`/`left_NN_M`/
     * `right_NN_M` family (127 members across ~30 NESTED `dgm:choose`
     * instances, not one flat 127-branch choose) needs first-match-wins
     * WITHIN each individual choose to resolve to the single genuinely-live
     * arrangement, not the "every guard-true node is an independent
     * candidate" reading `smartart-layout-interpreter-composite-choose.ts`'s
     * `collectRawCandidates` used before this field existed - see that
     * module's own consumer of this field for the actual selection rule.
     * `undefined` (or an empty array) for a node reached without any
     * enclosing choose (a direct child, or a `dgm:forEach`-only path) -
     * every PRE-EXISTING caller that does not consult this field is
     * unaffected by its mere presence.
     *
     * ROUND 42: `origin` is the forEach iterator active when THIS branch's
     * own `dgm:if`/`dgm:else` was declared (the SAME "declaration time, not
     * whatever descendant ends up carrying it" concept {@link
     * chooseGuardOrigins} exists for) - the anchor a `func="cnt"`/`"maxDepth"`
     * -family condition in `guard` needs, NOT a representative member's own
     * (possibly deeper) `forEachOrigin`. See `smartart-layout-interpreter-
     * composite-choose-groups.ts`'s `winningOrdinalFor`, the one consumer.
     */
    chooseGroups?: {
        id: string;
        ordinal: number;
        guard?: PptxSmartArtWhen;
        origin?: PptxSmartArtIteratorAttributes;
    }[];
    /**
     * Every `dgm:presOf` candidate reachable through a `dgm:choose`/`dgm:if`/
     * `dgm:else` wrapping THIS node's OWN presOf (as opposed to
     * {@link chooseGuard}, which gates the layoutNode's own EXISTENCE), each
     * tagged with the FULL chain of enclosing `dgm:if` conditions that select
     * it (`guard`, empty for an unconditional or `dgm:else`-reached
     * candidate), in document order (every `dgm:if` then `dgm:else` last).
     * `undefined` when this node's presOf is not choose-guarded at all (the
     * overwhelmingly common case) - {@link presentationOf} already carries
     * the one-and-only value then. Exists for a genuinely conditional presOf
     * where TWO OR MORE branches each declare a real, DIFFERENT axis
     * (`funnel--flat3.pptx`'s `item1`/`item2`/`item3`, one literal axis per
     * data-point count): `smartart-layout-definition-constraints.ts`'s
     * `choosePresentationOf` (feeding {@link presentationOf}) can only ever
     * guess ONE branch statically, at parse time, with no diagram to
     * evaluate against; this field lets an interpret-time caller with the
     * actual diagram (`smartart-layout-interpreter-when.ts`'s
     * `resolvePresentationOf`, the one consumer) pick the branch PowerPoint's
     * own runtime would, first-match-wins.
     */
    presentationOfCandidates?: {
        guard: PptxSmartArtWhen[];
        presentationOf: PptxSmartArtIteratorAttributes;
    }[];
    /**
     * SESSION 17: every `dgm:rule` reachable through a `dgm:choose`/`dgm:if`/
     * `dgm:else` wrapping THIS node's `ruleLst` (a genuinely count-gated rule
     * set, e.g. `diverging-radial`'s own `w for="ch" forName="node"` ceiling:
     * 6 `dgm:if cnt<=N` branches, each its own `fact`), tagged with its guard
     * chain - the SAME shape {@link presentationOfCandidates} uses for
     * choose-guarded `presOf`, applied to `dgm:rule`. `undefined` when not
     * choose-guarded (`rules` above then carries the one set, the common
     * case). See `smartart-layout-interpreter-cycle-hub-ratio.ts`'s
     * `resolveHubToNodeRatio` (COM-verified live mechanism, not a guess) for
     * how the guard is evaluated against the real satellite count.
     */
    ruleCandidates?: {
        guard: PptxSmartArtWhen[];
        rule: PptxSmartArtNumericRule;
    }[];
    /**
     * ROUND 39: every `dgm:constr` reachable through a `dgm:choose`/`dgm:if`/
     * `dgm:else` wrapping THIS node's `constrLst` (a genuinely count/position
     * -branched constraint set, e.g. `basic-venn--flat3.pptx`'s composite
     * `Name9` choose, one `ctrX`/`ctrY`/`w`/`h` per data-point-count branch
     * for `circ1`/`circ1Tx`/...), each tagged with its guard chain - the SAME
     * shape {@link presentationOfCandidates}/{@link ruleCandidates} use,
     * applied to `dgm:constr`. `undefined` when not choose-guarded
     * (`allConstraints`/`constraints` above then carry the one set, the
     * common case). See `smartart-constraint-branch-index.ts`'s
     * `selectConstraints` for how the guard is evaluated against the real
     * diagram, and that module's own doc comment for why `allConstraints`'s
     * pre-existing blind union of every branch is not enough on its own.
     */
    constraintCandidates?: {
        guard: PptxSmartArtWhen[];
        constraint: PptxSmartArtConstraint;
    }[];
}

/**
 * Typed DiagramML CT_Shape data (`dgm:shape`) attached to a layout node: the
 * per-node preset geometry override real (and third-party/custom) layout
 * definitions use so a layoutNode can be e.g. an ellipse or a chevron instead
 * of the arranger family's hardcoded default shape.
 */
declare interface PptxSmartArtLayoutNodeShape {
    /** `dgm:shape/@type`: a preset geometry name (`roundRect`, `ellipse`, `chevron`, `conn`, ...). */
    presetGeometry?: string;
    /** `dgm:adjLst/dgm:adj` entries (adjustment index -> value, as authored). */
    adjustments?: PptxSmartArtShapeAdjustment[];
    /** `dgm:shape/@hideGeom`: the shape is present only to size text, never painted. */
    hideGeometry?: boolean;
    /**
     * `dgm:shape/@lkTxEntry` (CT_Shape, boolean, default false): this node is a
     * decorative shape that should mirror its paired content node's text
     * rather than always rendering blank. See `smartart-layout-interpreter-
     * pyramid.ts`'s `arrangePyramid`, the interpreter's one existing
     * synthesized-decorative-shape call site.
     */
    lkTxEntry?: boolean;
}

declare interface PptxSmartArtLocalizedText {
    value: string;
    language?: string;
}

/**
 * A single node in the SmartArt data model.
 *
 * @example
 * ```ts
 * const node: PptxSmartArtNode = {
 *   id: "1",
 *   text: "CEO",
 *   children: [
 *     { id: "2", text: "VP Marketing", parentId: "1" },
 *     { id: "3", text: "VP Engineering", parentId: "1" },
 *   ],
 * };
 * // => satisfies PptxSmartArtNode
 * ```
 */
declare interface PptxSmartArtNode {
    id: string;
    text: string;
    /** CT_Pt connection identifier, when the point references a connection. */
    connectionId?: string | null;
    parentId?: string;
    children?: PptxSmartArtNode[];
    /** Node type from `@_type` attribute (e.g. "doc", "node", "asst", "pres"). */
    nodeType?: string;
    /**
     * The node's own quick-style role (`dgm:prSet/@presStyleLbl` from its
     * paired `type="pres"` presentation point, resolved via a `presOf`
     * connection back to this content point). Structural names like `node1`,
     * `asst2`, `bgShp`, `revTx`; distinct from {@link nodeType}, which is the
     * data-model `@_type` ("node"/"asst"/...). Used to pick this node's own
     * colour list from a colour transform's per-role palettes instead of the
     * generic cycled palette (see `applySmartArtRoleColors`).
     */
    styleRole?: string;
    /**
     * `dgm:prSet/@coherent3DOff` (`CT_ElemPropSet`) resolved from the node's
     * paired presentation point: when true, this node opts out of the
     * diagram's overall coherent-3D scene rotation (a `dgm:scene3d`/`dgm:sp3d`
     * quick-style variation) applied to every other node.
     */
    coherent3DOff?: boolean;
    /**
     * The layout variables PowerPoint recorded for each presentation node
     * this point drives (`dgm:prSet/@presName` -> `dgm:presLayoutVars`
     * variable -> `@val`), e.g. `{ hierRoot1: { hierBranch: 'l' } }` for an
     * org-chart manager set to "Left Hanging". Read-only: the presentation
     * points themselves round-trip verbatim.
     */
    presLayoutVarsByName?: Record<string, Record<string, string>>;
    /**
     * Per-run text + run-properties for the node's first paragraph, captured at
     * parse time. When the joined run text still equals {@link text} (the node
     * was not edited, or was edited only in ways that preserve the run split),
     * the save path rebuilds the paragraph from these runs so per-run rich text
     * is not flattened. When {@link text} diverges, the runs are ignored.
     */
    runs?: PptxSmartArtTextRun[];
    /**
     * Complete typed paragraph model. Unlike {@link runs}, this retains every
     * paragraph and the ordered run, field, break, and tab children within it.
     */
    paragraphs?: PptxSmartArtTextParagraph[];
    /**
     * Optional per-node visual override (fill / line / font colour, bold /
     * italic). Read at parse time from the point's `spPr` / first-run `rPr`, set
     * by the editing op, honoured by the render path, and written back on save so
     * it round-trips.
     */
    style?: PptxSmartArtNodeStyle;
    /**
     * Manual layout override read from the node's `dgm:prSet` `cust*`
     * attributes (drag/resize/rotate/flip performed in PowerPoint's own diagram
     * editor). Applied as a final transform after algorithmic layout by
     * {@link module:smartart-layout-interpreter-custom} so it survives even
     * when there is no cached `dsp:` drawing to fall back on.
     */
    customLayout?: SmartArtNodeCustomLayout;
}

/**
 * Per-node visual override for a SmartArt node.
 *
 * Captures the individual fill / line / font colour and the bold / italic
 * emphasis a user has set on one specific node, independent of the diagram's
 * colour scheme and quick style. All colours are hex strings (e.g. "#FF0000").
 * Every field is optional: only the overridden aspects are carried, so an
 * empty object means "no per-node override".
 *
 * The parser reads these from the data point's `spPr` solid fill / line colour
 * and the first run's `rPr` (b / i / solidFill) when present, and the save path
 * writes them back so the override survives a load -> edit -> save round-trip.
 *
 * @example
 * ```ts
 * const style: PptxSmartArtNodeStyle = {
 *   fillColor: "#FF0000",
 *   fontColor: "#FFFFFF",
 *   bold: true,
 * };
 * // => satisfies PptxSmartArtNodeStyle
 * ```
 */
declare interface PptxSmartArtNodeStyle {
    /** Solid fill colour override (hex, e.g. "#4F81BD"). */
    fillColor?: string;
    /** Outline / line colour override (hex). */
    lineColor?: string;
    /** Text (font) colour override (hex). */
    fontColor?: string;
    /** Bold emphasis override for the node's runs. */
    bold?: boolean;
    /** Italic emphasis override for the node's runs. */
    italic?: boolean;
}

/** Editable DiagramML CT_NumericRule. */
declare interface PptxSmartArtNumericRule extends PptxSmartArtConstraintTarget {
    type: string;
    value?: number;
    factor?: number;
    max?: number;
    /** Original rule retained for foreign attributes and extension content. */
    rawXml?: XmlObject;
}

/**
 * Presentation layout variables from `dgm:prSet/dgm:presLayoutVars` (data model)
 * or `dgm:varLst` (layout definition defaults).
 *
 * These drive how the DiagramML layout interpreter arranges points: flow
 * direction, hierarchy branch style, org-chart mode, and child count limits.
 * The fallback layout engine can consult them for direction/org-chart hints.
 *
 * @example
 * ```ts
 * const vars: PptxSmartArtPresLayoutVars = { direction: "rev", orgChart: true };
 * // => satisfies PptxSmartArtPresLayoutVars
 * ```
 */
declare interface PptxSmartArtPresLayoutVars {
    /** Flow direction (`dgm:dir`): "norm" (default) or "rev" (reversed/RTL). */
    direction?: 'norm' | 'rev';
    /** Hierarchy branch style (`dgm:hierBranch`): std/init/l/r/hang. */
    hierarchyBranch?: 'std' | 'init' | 'l' | 'r' | 'hang';
    /** Org-chart mode enabled (`dgm:orgChart`). */
    orgChart?: boolean;
    /** Maximum children per node (`dgm:chMax`, -1 = unbounded). */
    childMax?: number;
    /** Preferred children per node (`dgm:chPref`, -1 = unbounded). */
    childPreferred?: number;
    /** Whether bullets are enabled (`dgm:bulletEnabled`). */
    bulletEnabled?: boolean;
    /** Animation-by-level setting (`dgm:animLvl`). */
    animationLevel?: string;
    /** Animate-one setting (`dgm:animOne`). */
    animateOne?: string;
    /** Allowed resize handles (`dgm:resizeHandles`). */
    resizeHandles?: string;
}

/** Typed CT_StyleDefinition metadata and legacy rendering hint. */
declare interface PptxSmartArtQuickStyle extends PptxSmartArtDefinitionMetadata {
    /** Legacy resolved display name. */
    name?: string;
    /** Legacy effect-intensity rendering hint. */
    effectIntensity?: string;
    /** Ordered CT_StyleLabel metadata. Complex style payload remains preserved XML. */
    labels?: PptxSmartArtQuickStyleLabel[];
    /**
     * Whole-diagram 3D scene (camera preset/rotation/zoom/fov, light rig,
     * backdrop) from the quick style's own `dgm:styleDef/dgm:scene3d`, present
     * for the "Scene" quick styles (Brick, Flat, Metallic, Sunset, Bird's Eye
     * Scene). One camera renders the whole diagram; per-shape `a:scene3d` is
     * absent for those styles (see `PptxSmartArtDrawingShape.scene3d`). Each
     * `dgm:styleLbl` also carries its own per-label `dgm:scene3d`/`dgm:sp3d`
     * ({@link PptxSmartArtQuickStyleLabel.scene3d} / `shape3d` / `text3d`),
     * which PowerPoint bakes onto each cached shape; they are re-applied when a
     * structural edit regenerates the shapes.
     */
    scene3d?: Pptx3DScene;
}

/** CT_StyleLabel metadata from a quick-style definition. */
declare interface PptxSmartArtQuickStyleLabel {
    name: string;
    /** Theme-resolved `dgm:style` refs for this label's role, when available. */
    resolvedStyle?: PptxSmartArtResolvedStyleRef;
    /**
     * The label's own `dgm:scene3d` (per-shape camera + light rig). PowerPoint
     * copies it onto a shape's cached `a:scene3d` unless it is the default
     * front camera with a `threePt` light (see `applySmartArtQuickStyle3d`).
     */
    scene3d?: Pptx3DScene;
    /** The label's own `dgm:sp3d` (bevel / extrusion / contour / material); absent when empty. */
    shape3d?: Pptx3DShape;
    /** The label's `dgm:txPr/a:sp3d` label-text extrusion (Bird's Eye Scene). */
    text3d?: Text3DStyle;
}

/**
 * A `dgm:bg` fill this viewer doesn't fully model as first-class chrome
 * (gradient or pattern), preserved verbatim for round-trip. See
 * {@link PptxSmartArtChrome.backgroundFillXml}.
 */
declare interface PptxSmartArtRawBackgroundFill {
    /** Local element name of the fill under `dgm:bg` (`gradFill` or `pattFill`). */
    localName: 'gradFill' | 'pattFill';
    /** The fill element's own attributes/children, as parsed. */
    xml: XmlObject;
}

/**
 * A quick-style label's `a:lnRef`/`a:fillRef`/`a:effectRef`/`a:fontRef`
 * (`CT_ShapeStyle`, the same complex type an ordinary shape's `p:style`
 * uses), resolved against the theme's `fmtScheme` at parse time instead of
 * the coarse subtle/moderate/intense enum ({@link PptxSmartArtQuickStyle.effectIntensity}).
 * Only populated when a theme format scheme was available when the quick
 * style was parsed. See G13 in the 2026-09 diagram audit.
 */
declare interface PptxSmartArtResolvedStyleRef {
    fillColor?: string;
    fillMode?: 'solid' | 'gradient' | 'pattern' | 'none' | 'theme';
    strokeColor?: string;
    strokeWidth?: number;
    /** `a:effectRef`'s theme-resolved outer shadow colour, when the style has one. */
    shadowColor?: string;
    /** `a:fontRef`'s theme-resolved typeface (`+mn-lt`/`+mj-lt` -> the theme's actual font). */
    fontTypeface?: string;
}

/** A single `dgm:adj/@val` adjustment, keyed by its `@idx` (1-based, like `a:gd`). */
declare interface PptxSmartArtShapeAdjustment {
    index: number;
    value: number;
}

/** A complete `a:p` paragraph in a SmartArt data-model text body. */
declare interface PptxSmartArtTextParagraph {
    /** Paragraph properties (`a:pPr`) preserved verbatim. */
    pPr?: Record<string, unknown>;
    /** Text children in source order. */
    items: PptxSmartArtTextParagraphItem[];
    /** End-paragraph run properties (`a:endParaRPr`) preserved verbatim. */
    endParaRPr?: Record<string, unknown>;
    /** Resolved style for the paragraph terminator. */
    endParaStyle?: TextStyle;
    /** Raw paragraph XML used to retain unmodelled extension children on save. */
    rawXml?: Record<string, unknown>;
}

/** An ordered item within a SmartArt text paragraph. */
declare type PptxSmartArtTextParagraphItem = {
    kind: 'run';
    run: PptxSmartArtTextRun;
} | {
    kind: 'break';
    rPr?: Record<string, unknown>;
    style?: TextStyle;
    rawXml?: Record<string, unknown>;
    childOrder?: string[];
} | {
    kind: 'field';
    id?: string;
    fieldType?: string;
    text: string;
    rPr?: Record<string, unknown>;
    style?: TextStyle;
    pPr?: Record<string, unknown>;
    rawXml?: Record<string, unknown>;
    childOrder?: string[];
} | {
    kind: 'tab';
    rawXml?: Record<string, unknown>;
    childOrder?: string[];
} | {
    kind: 'raw';
    name: string;
    value: unknown;
};

/**
 * A single run of text inside a SmartArt node, capturing the run text and the
 * raw `a:rPr` run-properties object verbatim so per-run formatting (bold,
 * colour, size, etc.) survives a load -> edit -> save round-trip instead of
 * collapsing to a single unstyled run.
 *
 * @example
 * ```ts
 * const run: PptxSmartArtTextRun = {
 *   text: "Bold",
 *   rPr: { "@_b": "1", "@_lang": "en-US" },
 * };
 * // => satisfies PptxSmartArtTextRun
 * ```
 */
declare interface PptxSmartArtTextRun {
    /** Run text content. */
    text: string;
    /**
     * Raw parsed `a:rPr` run-properties object, preserved verbatim for
     * round-trip. Untyped XML, hence the loose record shape.
     */
    rPr?: Record<string, unknown>;
    /** Resolved standard shape-text style derived from {@link rPr}. */
    style?: TextStyle;
    /** Raw run XML used to retain unmodelled extension children on save. */
    rawXml?: Record<string, unknown>;
    /** Original direct-child order, including unmodelled extension children. */
    childOrder?: string[];
}

declare interface PptxSmartArtWhen extends PptxSmartArtIteratorAttributes {
    function: string;
    argument?: string;
    operator: string;
    value: string;
    rawXml?: XmlObject;
}

/**
 * A recognizer-owned `p:smartTags` reference from `presentation.xml`
 * (CT_SmartTags, ECMA-376 S19.2.1.42): a bare relationship id pointing at a
 * legacy Office "Smart Tags" recognizer part, distinct from the
 * user-authored `p:tags` construct (see {@link PptxTagCollection}).
 *
 * This library has no data model for recognizer part CONTENT (there is no
 * way to create, inspect, or edit one through the public API), so this type
 * only captures enough to preserve an authored reference losslessly: the
 * relationship id and, when resolvable, the target part path.
 */
declare interface PptxSmartTagsReference {
    /** Relationship id from `p:smartTags/@r:id`. */
    relId: string;
    /** Resolved ZIP path of the referenced recognizer part, when resolvable. */
    targetPath?: string;
    /** Raw `p:smartTags` XML retained for lossless round-trip. */
    rawXml?: XmlObject;
}

/** Split orientation from OOXML `@_orient`. */
declare type PptxSplitOrientation = 'horz' | 'vert';

/**
 * A single table cell with text content, optional style, and merge info.
 *
 * @example
 * ```ts
 * const cell: PptxTableCell = {
 *   text: "$1.5M",
 *   style: { bold: true, align: "right" },
 *   gridSpan: 1,
 * };
 * // => satisfies PptxTableCell
 * ```
 */
declare interface PptxTableCell {
    text: string;
    style?: PptxTableCellStyle;
    /**
     * Per-run formatting for the cell's text, when it has any beyond what
     * {@link style} can express. Present only for cells whose `a:txBody`
     * actually carries runs; renderers fall back to {@link text} when absent.
     *
     * Editing a cell's text invalidates these (the editor produces a plain
     * string), so an edit path must clear them alongside setting `text`.
     */
    textRuns?: PptxTableCellTextRun[];
    /** Column span (defaults to 1). */
    gridSpan?: number;
    /** Row span (defaults to 1). */
    rowSpan?: number;
    /** Whether this cell is merged vertically with the cell above. */
    vMerge?: boolean;
    /** Whether this cell is horizontally merged with the cell to the left (gridSpan continuation). */
    hMerge?: boolean;
    /**
     * Opaque round-trip storage for `a:tcPr` attributes that don't yet have
     * typed equivalents on {@link PptxTableCellStyle} (e.g. `horzOverflow`,
     * `anchorCtr`, `headers`, `hideSlicers`, `slicerCacheId`). Keys are the
     * raw XML attribute names without the `@_` prefix used by
     * fast-xml-parser. Re-emitted verbatim by the save writer when present.
     */
    extraAttributes?: Record<string, string>;
}

/**
 * Cell 3D bevel + lighting parsed from `a:tcPr/a:cell3D` (CT_Cell3D).
 *
 * Only the fields needed to render a plausible bevel treatment are captured;
 * verbatim round-trip of the full node is handled separately by the save path.
 *
 * @example
 * ```ts
 * const c3d: PptxTableCell3D = {
 *   bevelWidth: 8,
 *   bevelHeight: 8,
 *   bevelPreset: 'circle',
 *   material: 'plastic',
 * };
 * // => satisfies PptxTableCell3D
 * ```
 */
declare interface PptxTableCell3D {
    /** Bevel width in px (from `a:bevel@w`, EMU converted). */
    bevelWidth?: number;
    /** Bevel height in px (from `a:bevel@h`, EMU converted). */
    bevelHeight?: number;
    /** Bevel preset name (`a:bevel@prst`, e.g. `circle`, `relaxedInset`). */
    bevelPreset?: string;
    /** Preset material (`a:cell3D@prstMaterial`, e.g. `plastic`, `metal`). */
    material?: string;
    /** Light rig type (`a:lightRig@rig`, e.g. `threePt`, `soft`). */
    lightRig?: string;
    /** Light rig direction (`a:lightRig@dir`, e.g. `tl`, `t`, `tr`). */
    lightRigDirection?: string;
}

/**
 * Per-cell visual style for a table cell.
 *
 * All fields are optional - unset values inherit from the table style.
 *
 * @example
 * ```ts
 * const header: PptxTableCellStyle = {
 *   bold: true,
 *   fontSize: 14,
 *   color: "#FFFFFF",
 *   backgroundColor: "#0055AA",
 *   align: "center",
 * };
 * // => satisfies PptxTableCellStyle
 * ```
 */
declare interface PptxTableCellStyle {
    /** Font size in points (`a:rPr@sz / 100`). */
    fontSize?: number;
    bold?: boolean;
    italic?: boolean;
    underline?: boolean;
    color?: string;
    /**
     * Font family from the first run's `a:rPr/a:latin@typeface` (falling back to
     * `a:ea` / `a:cs`). Per-run families live on {@link PptxTableCellTextRun}.
     */
    fontFamily?: string;
    /**
     * Raw XML colour-choice node preserved from `a:tc/a:txBody/.../a:rPr/a:solidFill`
     * for round-trip serialisation. Currently unused by the cell-level writer
     * (cell text colour falls through `writeCellTextFormatting`), reserved for
     * future expansion alongside the run-properties round-trip path.
     */
    colorXml?: XmlObject;
    /**
     * Typed theme colour reference for the cell text colour, set when
     * {@link colorXml} is a plain `a:schemeClr`. Wins on save, mirroring
     * `TextStyle.colorRef`. Distinct from {@link ParsedTableStyleFill.schemeColor},
     * which describes a `ppt/tableStyles.xml` section fill rather than an
     * individual cell override.
     */
    colorRef?: PptxThemeColorRef;
    backgroundColor?: string;
    /**
     * Raw XML colour-choice node preserved from cell `a:tcPr/a:solidFill` for
     * round-trip serialisation. Re-emitted verbatim when the resolved
     * {@link backgroundColor} still matches the original colour.
     */
    backgroundColorXml?: XmlObject;
    /**
     * Typed theme colour reference for the cell fill, set when
     * {@link backgroundColorXml} is a plain `a:schemeClr`. Wins on save,
     * mirroring `ShapeStyle.fillColorRef`.
     */
    backgroundColorRef?: PptxThemeColorRef;
    borderColor?: string;
    /** Top border width in px. */
    borderTopWidth?: number;
    /** Bottom border width in px. */
    borderBottomWidth?: number;
    /** Left border width in px. */
    borderLeftWidth?: number;
    /** Right border width in px. */
    borderRightWidth?: number;
    /** Top border color as hex. */
    borderTopColor?: string;
    /** Bottom border color as hex. */
    borderBottomColor?: string;
    /** Left border color as hex. */
    borderLeftColor?: string;
    /** Right border color as hex. */
    borderRightColor?: string;
    align?: 'left' | 'center' | 'right' | 'justify';
    vAlign?: 'top' | 'middle' | 'bottom';
    /** Text direction from `a:tcPr/@vert` (spec values from CT_TextVerticalType). */
    textDirection?: 'vert' | 'vert270' | 'eaVert' | 'wordArtVert' | 'wordArtVertRtl' | 'mongolianVert';
    /** Cell left margin in px (from a:tcPr > a:tcMar > a:marL). */
    marginLeft?: number;
    /** Cell right margin in px. */
    marginRight?: number;
    /** Cell top margin in px. */
    marginTop?: number;
    /** Cell bottom margin in px. */
    marginBottom?: number;
    /** Diagonal border top-left to bottom-right color. */
    borderDiagDownColor?: string;
    /** Diagonal border top-left to bottom-right width in px. */
    borderDiagDownWidth?: number;
    /** Diagonal border bottom-left to top-right color. */
    borderDiagUpColor?: string;
    /** Diagonal border bottom-left to top-right width in px. */
    borderDiagUpWidth?: number;
    /** Table cell border dash style (legacy single value). */
    borderDash?: string;
    /** Per-edge border dash styles. */
    borderTopDash?: string;
    borderBottomDash?: string;
    borderLeftDash?: string;
    borderRightDash?: string;
    /** Cell text shadow colour. */
    textShadowColor?: string;
    /** Cell text shadow blur radius in px. */
    textShadowBlur?: number;
    /** Cell text shadow horizontal offset in px. */
    textShadowOffsetX?: number;
    /** Cell text shadow vertical offset in px. */
    textShadowOffsetY?: number;
    /** Cell text shadow opacity (0-1). */
    textShadowOpacity?: number;
    /** Cell text glow colour. */
    textGlowColor?: string;
    /** Cell text glow radius in px. */
    textGlowRadius?: number;
    /** Cell text glow opacity (0-1). */
    textGlowOpacity?: number;
    /** Cell fill mode: solid, gradient, pattern, image, or none. */
    fillMode?: 'solid' | 'gradient' | 'pattern' | 'image' | 'none';
    /** Gradient fill stops (colours with positions). */
    gradientFillStops?: Array<{
        color: string;
        position: number;
        opacity?: number;
    }>;
    /** Gradient angle in degrees. */
    gradientFillAngle?: number;
    /** Gradient type: linear or radial. */
    gradientFillType?: 'linear' | 'radial';
    /** Path gradient sub-type. */
    gradientFillPathType?: 'circle' | 'rect' | 'shape';
    /** Focal point for radial gradients (0–1 fractions). */
    gradientFillFocalPoint?: {
        x: number;
        y: number;
    };
    /** Raw fillToRect LTRB values (0–1 fractions) for gradient sizing. */
    gradientFillFillToRect?: {
        l: number;
        t: number;
        r: number;
        b: number;
    };
    /** Pre-computed CSS gradient string for rendering. */
    gradientFillCss?: string;
    /** Pattern fill preset name (e.g. "ltDnDiag"). */
    patternFillPreset?: string;
    /** Pattern fill foreground colour. */
    patternFillForeground?: string;
    /** Pattern fill background colour. */
    patternFillBackground?: string;
    /**
     * Image fill (`a:tcPr/a:blipFill`, CT_TableCellProperties). Resolved
     * archive-relative path (or external `http(s):`/`data:` URL) for the
     * cell's background image, from `a:blipFill/a:blip/@r:embed` (or
     * `@r:link`). Present when `fillMode` is `'image'`.
     *
     * The parser resolves this synchronously (path only, no binary read);
     * a viewer's load pipeline resolves it further to a displayable
     * `data:`/`blob:` URL, written back to {@link backgroundImageFillData}.
     */
    backgroundImageFillPath?: string;
    /**
     * Displayable image data (`data:` or `blob:` URL) for an image cell
     * fill, once resolved by the load pipeline. Renderers should prefer
     * this over {@link backgroundImageFillPath} when both are present.
     */
    backgroundImageFillData?: string;
    /**
     * Cell 3D bevel + lighting from `a:tcPr/a:cell3D` (CT_Cell3D,
     * ECMA-376 §21.1.3.1). Rendered as a CSS bevel treatment.
     */
    cell3D?: PptxTableCell3D;
    /**
     * `a:tcPr/@anchorCtr` - centre the text block in the direction
     * perpendicular to the text flow (horizontal centring for horizontal text).
     */
    anchorCtr?: boolean;
    /**
     * `a:tcPr/@horzOverflow` (ST_TextHorzOverflowType): `clip` clips text at
     * the cell edge, `overflow` (the default) lets it spill.
     */
    horzOverflow?: 'clip' | 'overflow';
}

/**
 * One styled text run inside a table cell's `a:txBody`.
 *
 * `PptxTableCell.text` is a flat string and `PptxTableCell.style` describes
 * only the FIRST run, so a cell mixing formats ("Revenue **grew 42%** last
 * year") cannot be represented by those two alone. {@link PptxTableCell.runs}
 * carries the full sequence, with paragraph and line breaks as marker entries
 * so a renderer can walk it linearly.
 *
 * Structurally identical to `pptx-viewer-shared`'s `CellTextRun`, which every
 * binding's table renderer already consumes.
 *
 * @example
 * ```ts
 * const runs: PptxTableCellTextRun[] = [
 *   { text: "Revenue " },
 *   { text: "grew 42%", bold: true, color: "#C00000" },
 * ];
 * // => satisfies PptxTableCellTextRun[]
 * ```
 */
declare interface PptxTableCellTextRun {
    /** Run text. Empty for the break markers below. */
    text: string;
    /** This entry starts a new paragraph (`a:p` boundary) rather than carrying text. */
    isParagraphBreak?: boolean;
    /** This entry is a soft line break (`a:br`) rather than carrying text. */
    isLineBreak?: boolean;
    /** This entry carries an `a:fld` value rather than a literal `a:r`. */
    isField?: true;
    bold?: boolean;
    italic?: boolean;
    underline?: boolean;
    strikethrough?: boolean;
    /** Resolved run colour as a CSS colour string. */
    color?: string;
    /** Run font size in points (`a:rPr@sz` / 100). */
    fontSize?: number;
    /** Run font family from `a:rPr/a:latin@typeface` (or `a:ea` / `a:cs`). */
    fontFamily?: string;
}

/**
 * Complete parsed table data for a {@link TablePptxElement}.
 *
 * Includes row/cell data, column widths, banding flags, and the applied
 * table style ID.
 *
 * @example
 * ```ts
 * const data: PptxTableData = {
 *   rows: [
 *     { cells: [{ text: "Product" }, { text: "Revenue" }] },
 *     { cells: [{ text: "Widget A" }, { text: "$3.4M" }] },
 *   ],
 *   columnWidths: [0.6, 0.4],
 *   firstRowHeader: true,
 *   bandedRows: true,
 * };
 * // => satisfies PptxTableData
 * ```
 */
declare interface PptxTableData {
    rows: PptxTableRow[];
    /** Column widths as proportion of total (summing to 1). */
    columnWidths: number[];
    /** Whether the table has banded rows. */
    bandedRows?: boolean;
    /** Whether the first row is a header. */
    firstRowHeader?: boolean;
    /** Whether banded columns are enabled. */
    bandedColumns?: boolean;
    /** Whether the last row is styled as a total row. */
    lastRow?: boolean;
    /** Whether the first column is styled as a header column. */
    firstCol?: boolean;
    /** Whether the last column is styled specially. */
    lastCol?: boolean;
    /** Table style ID from `a:tblPr/a:tblStyle@val` or `a:tblPr@tblStyle`. */
    tableStyleId?: string;
    /** Number of rows per banding group (default 1). */
    bandRowCycle?: number;
    /** Number of columns per banding group (default 1). */
    bandColCycle?: number;
    /** Right-to-left table layout from `a:tblPr/@rtl`. */
    rtl?: boolean;
    /**
     * `a:tblPr`'s OWN fill (`CT_TableProperties` §21.1.3.15's
     * `EG_FillProperties`), independent of any `a:tblStyleLst`-referenced style
     * or that style's `a:tblBg`. Applied as the lowest-priority fill layer,
     * beneath the table style's `wholeTbl` fill. Real PowerPoint decks route
     * table appearance through `tableStyleId` instead, so this mainly matters
     * for non-PowerPoint authoring tools (issue G6).
     */
    tableFill?: ParsedTableStyleFill;
    /**
     * `a:tblPr`'s own `a:effectLst` (or `a:effectDag`) effect chain,
     * independent of the referenced table style, decomposed into a typed
     * sequence of {@link ParsedTableStyleEffect} nodes (issue G6). Each node
     * keeps its own XML verbatim for lossless round-trip; empty array is
     * normalised to `undefined` by the parser so `tableEffects` is only ever
     * present when there is at least one effect.
     */
    tableEffects?: ParsedTableStyleEffect[];
    /**
     * Table-cell-context default text size in points, resolved from the
     * slide's master `p:otherStyle` (ECMA-376 §19.3.1.42 CT_TextListStyle,
     * §19.3.1.52 for `p:txStyles`). PowerPoint sizes a table cell's text off
     * this master default (commonly 18pt) whenever neither the run nor the
     * (size-less) table style provides one; without it, cell text without an
     * explicit `a:rPr@sz` fell back to the browser's own default font size
     * (16px / 12pt) instead. A render-only hint: it is not part of any
     * individual cell's parsed style and is never written back on save, so
     * resaving an unstyled cell does not bake in an explicit size that was
     * never authored. `undefined` when no master/otherStyle size resolves
     * (renderers should leave the browser default in place in that case).
     */
    defaultCellFontSize?: number;
}

/**
 * A single table row with an optional height and an array of cells.
 *
 * @example
 * ```ts
 * const row: PptxTableRow = {
 *   height: 40,
 *   cells: [
 *     { text: "Name" },
 *     { text: "Score" },
 *   ],
 * };
 * // => satisfies PptxTableRow
 * ```
 */
declare interface PptxTableRow {
    /** Row height in px. */
    height?: number;
    cells: PptxTableCell[];
}

/**
 * A single name–value tag from `ppt/tags/*.xml`.
 *
 * @example
 * ```ts
 * const tag: PptxTag = { name: "CUSTOM_ID", value: "12345" };
 * // => satisfies PptxTag
 * ```
 */
declare interface PptxTag {
    name: string;
    value: string;
}

/**
 * A collection of tags from a single tags XML part.
 *
 * @example
 * ```ts
 * const coll: PptxTagCollection = {
 *   path: "ppt/tags/tag1.xml",
 *   tags: [{ name: "CUSTOM_ID", value: "12345" }],
 * };
 * // => satisfies PptxTagCollection
 * ```
 */
declare interface PptxTagCollection {
    /** File path within the PPTX archive. */
    path?: string;
    /** Package owner of the tags relationship. New collections default to presentation. */
    owner?: 'presentation' | 'slide' | 'part';
    /** Source OPC part that owns the relationship, e.g. ppt/slides/slide1.xml. */
    sourcePartPath?: string;
    /** Durable relationship identifier from the owning part. */
    relationshipId?: string;
    /** Tags in this collection. */
    tags: PptxTag[];
    /** Parsed tag-list XML retained for unknown-node preservation. */
    rawXml?: XmlObject;
}

/** Text-level animation target from `p:txEl`. */
declare interface PptxTextAnimationTarget {
    /** Target type: character range or paragraph range. */
    type: 'charRg' | 'pRg';
    /** Start index (0-based). */
    start: number;
    /** End index (exclusive). */
    end: number;
}

/** Build type for text build (paragraph/word/letter) animations from `p:bldP/@build`. */
declare type PptxTextBuildType = 'allAtOnce' | 'byParagraph' | 'byWord' | 'byChar';

/**
 * Text content mixin — present on text boxes and shapes.
 *
 * Shapes can contain text overlaid on the shape geometry, so both
 * `TextPptxElement` and `ShapePptxElement` extend this interface.
 *
 * @example
 * ```ts
 * const props: PptxTextProperties = {
 *   text: "Hello World",
 *   textStyle: { fontSize: 24, bold: true, color: "#333333" },
 * };
 * // => satisfies PptxTextProperties
 * ```
 */
declare interface PptxTextProperties {
    text?: string;
    textStyle?: TextStyle;
    /** Rich text segments with individual styling. */
    textSegments?: TextSegment[];
    /** Per-paragraph indentation (marginLeft, indent) for multi-level bullet support. */
    paragraphIndents?: Array<{
        marginLeft?: number;
        indent?: number;
    }>;
    /** Placeholder prompt text inherited from layout/master (e.g. "Click to add title"). Shown as a greyed-out hint when the shape has no user-entered text. */
    promptText?: string;
    /**
     * The string {@link text} was INHERITED from, when this is a header / footer /
     * date / slide-number placeholder whose own body the file leaves empty.
     *
     * PowerPoint keeps the footer string on the slide master and writes each
     * slide's copy of the `ftr` placeholder empty, so the empty body means
     * "render the master's footer here". Rendering needs the resolved string, but
     * SAVING it into the slide would pin that slide to today's master text and
     * silently detach it from the Header & Footer dialog. The save writer
     * therefore leaves the authored empty body alone while `text` still equals
     * this value, and writes a genuine per-slide override once it does not.
     */
    inheritedPlaceholderText?: string;
    /** Linked text box chain ID from `a:bodyPr > a:linkedTxbx/@id` or `a:txbx > a:linkedTxbx/@id`. Text overflows from one linked frame to the next. */
    linkedTxbxId?: number;
    /** Sequence number within a linked text box chain (0-based). */
    linkedTxbxSeq?: number;
}

/**
 * Per-level paragraph properties for a text style category.
 * Each entry maps a 0-based level index to its style defaults.
 */
declare type PptxTextStyleLevels = Record<number, PlaceholderTextLevelStyle>;

/**
 * Known OOXML preset text warp types (WordArt transforms).
 *
 * Falls back to `string` for unknown presets not yet catalogued.
 *
 * @example
 * ```ts
 * const warp: PptxTextWarpPreset = "textArchUp";
 * // => "textArchUp" — one of: "textNoShape" | "textPlain" | "textStop" | "textArchUp" | …
 * ```
 */
declare type PptxTextWarpPreset = 'textNoShape' | 'textPlain' | 'textStop' | 'textTriangle' | 'textTriangleInverted' | 'textChevron' | 'textChevronInverted' | 'textRingInside' | 'textRingOutside' | 'textArchUp' | 'textArchDown' | 'textCircle' | 'textButton' | 'textArchUpPour' | 'textArchDownPour' | 'textCirclePour' | 'textButtonPour' | 'textCurveUp' | 'textCurveDown' | 'textCanUp' | 'textCanDown' | 'textWave1' | 'textWave2' | 'textWave4' | 'textDoubleWave1' | 'textInflate' | 'textDeflate' | 'textInflateBottom' | 'textDeflateBottom' | 'textInflateTop' | 'textDeflateTop' | 'textFadeRight' | 'textFadeLeft' | 'textFadeUp' | 'textFadeDown' | 'textSlantUp' | 'textSlantDown' | 'textCascadeUp' | 'textCascadeDown' | 'textDeflateInflate' | 'textDeflateInflateDeflate' | string;

/**
 * Full parsed theme object available to renderers.
 *
 * @example
 * ```ts
 * const theme: PptxTheme = {
 *   name: "Office Theme",
 *   colorScheme: { dk1: "#000", lt1: "#FFF", /* … *\/ },
 *   fontScheme: {
 *     majorFont: { latin: "Calibri Light" },
 *     minorFont: { latin: "Calibri" },
 *   },
 * };
 * // => satisfies PptxTheme
 * ```
 */
declare interface PptxTheme {
    /** Theme name from `a:theme @name`. */
    name?: string;
    /** Resolved colour scheme. */
    colorScheme?: PptxThemeColorScheme;
    /** Resolved font scheme. */
    fontScheme?: PptxThemeFontScheme;
    /** Format scheme — fill, line, effect and background fill style matrices. */
    formatScheme?: PptxThemeFormatScheme;
}

/**
 * A theme colour choice. Every transform is a 0..1 fraction of the OOXML
 * percentage (`lumMod val="20000"` is `lumMod: 0.2`), matching how the parser
 * reads them, and is applied in the order `a:schemeClr` children are written:
 * `tint`, `shade`, `lumMod`, `lumOff`, `alpha`.
 */
declare interface PptxThemeColorRef {
    scheme: PptxThemeColorSchemeName;
    /** `a:lumMod`: multiply HSL luminance (PowerPoint's "Lighter/Darker" rows). */
    lumMod?: number;
    /** `a:lumOff`: add to HSL luminance after `lumMod` ("Lighter N%" rows). */
    lumOff?: number;
    /** `a:tint`: blend towards white. */
    tint?: number;
    /** `a:shade`: blend towards black. */
    shade?: number;
    /** `a:alpha`: opacity fraction (1 = opaque). */
    alpha?: number;
}

/**
 * Resolved hex values for the 12 theme colour slots.
 *
 * @example
 * ```ts
 * const scheme: PptxThemeColorScheme = {
 *   dk1: "#000000", lt1: "#FFFFFF",
 *   dk2: "#1F497D", lt2: "#EEECE1",
 *   accent1: "#4F81BD", accent2: "#C0504D",
 *   accent3: "#9BBB59", accent4: "#8064A2",
 *   accent5: "#4BACC6", accent6: "#F79646",
 *   hlink: "#0000FF", folHlink: "#800080",
 * };
 * // => satisfies PptxThemeColorScheme
 * ```
 */
declare interface PptxThemeColorScheme {
    dk1: string;
    lt1: string;
    dk2: string;
    lt2: string;
    accent1: string;
    accent2: string;
    accent3: string;
    accent4: string;
    accent5: string;
    accent6: string;
    hlink: string;
    folHlink: string;
}

/**
 * Theme colour references: the typed counterpart of `<a:schemeClr>`.
 *
 * A colour picked from the theme palette is remembered as a scheme slot plus
 * PowerPoint's luminance variants rather than as the sRGB it currently
 * resolves to, so a later theme change re-colours the shape (and a saved file
 * keeps `<a:schemeClr>` instead of a canonical `<a:srgbClr>`).
 *
 * @module types/color-ref
 */
/**
 * The scheme slot names `a:schemeClr/@val` accepts (ECMA-376 `ST_SchemeColorIndex`).
 * `bg1`/`tx1`/`bg2`/`tx2` are the colour-map aliases a slide resolves through
 * `p:clrMap`; `phClr` is the placeholder colour used inside a theme's style
 * matrix and is never chosen from a picker.
 */
declare type PptxThemeColorSchemeName = 'dk1' | 'lt1' | 'dk2' | 'lt2' | 'accent1' | 'accent2' | 'accent3' | 'accent4' | 'accent5' | 'accent6' | 'hlink' | 'folHlink' | 'bg1' | 'tx1' | 'bg2' | 'tx2' | 'phClr';

/**
 * A single effect style entry from `a:effectStyleLst`.
 * Each entry may define shadow, glow, soft-edge, reflection, blur,
 * and optionally a 3-D scene/shape.
 *
 * @example
 * ```ts
 * const dropShadow: PptxThemeEffectStyle = {
 *   shadowColor: "#000000",
 *   shadowBlur: 4,
 *   shadowOffsetX: 2,
 *   shadowOffsetY: 3,
 *   shadowOpacity: 0.4,
 * };
 * // => satisfies PptxThemeEffectStyle
 * ```
 */
declare interface PptxThemeEffectStyle {
    shadowColor?: string;
    shadowBlur?: number;
    shadowOffsetX?: number;
    shadowOffsetY?: number;
    shadowOpacity?: number;
    glowColor?: string;
    glowRadius?: number;
    glowOpacity?: number;
    softEdgeRadius?: number;
    innerShadowColor?: string;
    innerShadowOpacity?: number;
    innerShadowBlur?: number;
    innerShadowOffsetX?: number;
    innerShadowOffsetY?: number;
    reflectionBlurRadius?: number;
    reflectionStartOpacity?: number;
    reflectionEndOpacity?: number;
    reflectionEndPosition?: number;
    reflectionDirection?: number;
    reflectionRotation?: number;
    reflectionDistance?: number;
    /** 3D scene/camera from `a:scene3d` on the effect style (idx 3 typically). */
    scene3d?: Pptx3DScene;
    /** 3D shape extrusion/bevel from `a:sp3d` on the effect style (idx 3 typically). */
    shape3d?: Pptx3DShape;
    /** Raw XML node preserved for `phClr` re-resolution. */
    rawNode?: unknown;
}

/**
 * A single fill style entry from the theme format scheme.
 * Each entry is one of: solid, gradient, pattern, or no fill.
 * The raw XML node is also stored so that `phClr` substitution can happen
 * at resolution time.
 *
 * @example
 * ```ts
 * const solidFill: PptxThemeFillStyle = {
 *   kind: "solid",
 *   color: "#4F81BD",
 *   opacity: 1,
 * };
 *
 * const gradientFill: PptxThemeFillStyle = {
 *   kind: "gradient",
 *   gradientAngle: 90,
 *   gradientType: "linear",
 *   gradientStops: [
 *     { color: "#4F81BD", position: 0 },
 *     { color: "#1F497D", position: 1 },
 *   ],
 * };
 * // => satisfies PptxThemeFillStyle
 * ```
 */
declare interface PptxThemeFillStyle {
    /**
     * Discriminator for the fill type.
     *
     * `'group'` corresponds to `<a:grpFill/>` — a fill that inherits the
     * containing group shape's fill at render time. Captured for round-trip
     * preservation in `fmtScheme/fillStyleLst`.
     */
    kind: 'solid' | 'gradient' | 'pattern' | 'none' | 'group';
    /** Pre-resolved colour (may be `undefined` when `phClr`-dependent). */
    color?: string;
    opacity?: number;
    /** Gradient-specific fields (only present when `kind === "gradient"`). */
    gradientStops?: Array<{
        color: string;
        position: number;
        opacity?: number;
    }>;
    gradientAngle?: number;
    gradientType?: 'linear' | 'radial';
    gradientCss?: string;
    /** Pattern-specific fields (only present when `kind === "pattern"`). */
    patternPreset?: string;
    patternBackgroundColor?: string;
    /** Raw XML node preserved for `phClr` re-resolution. */
    rawNode?: unknown;
}

/**
 * A font-family triplet for major or minor theme fonts.
 *
 * Supports Latin, East Asian, and Complex Script font families.
 *
 * @example
 * ```ts
 * const fonts: PptxThemeFontGroup = {
 *   latin: "Calibri Light",
 *   eastAsia: "MS PGothic",
 *   complexScript: "Arial",
 * };
 * // => satisfies PptxThemeFontGroup
 * ```
 */
declare interface PptxThemeFontGroup {
    latin?: string;
    eastAsia?: string;
    complexScript?: string;
    /**
     * Per-script typeface overrides (`<a:font script="Hans|Hant|Arab|Hebr|
     * Thai|Beng|Gujr|Khmr|Knda|…"/>` per ECMA-376 §20.1.4.1.16). Keyed by
     * the four-letter ISO 15924 script tag from the `script` attribute.
     *
     * Phase 4 Stream A / M4.
     */
    byScript?: Record<string, string>;
}

/**
 * Theme font scheme — major (headings) and minor (body) font families.
 *
 * @example
 * ```ts
 * const scheme: PptxThemeFontScheme = {
 *   majorFont: { latin: "Calibri Light" },
 *   minorFont: { latin: "Calibri", eastAsia: "MS PGothic" },
 * };
 * // => satisfies PptxThemeFontScheme
 * ```
 */
declare interface PptxThemeFontScheme {
    majorFont?: PptxThemeFontGroup;
    minorFont?: PptxThemeFontGroup;
}

/**
 * The full parsed format scheme from `a:fmtScheme` inside `a:themeElements`.
 * Contains three fill style lists and one line/effect style list each,
 * at three intensity levels: subtle (idx 1), moderate (idx 2), intense (idx 3).
 *
 * OOXML reference indices:
 * - fillStyleLst:   idx 1-3  (used by `a:fillRef @idx` 1-3)
 * - lnStyleLst:     idx 1-3  (used by `a:lnRef @idx` 1-3)
 * - effectStyleLst:  idx 1-3  (used by `a:effectRef @idx` 1-3)
 * - bgFillStyleLst:  idx 1-3  (used by `a:fillRef @idx` 1001-1003)
 *
 * @example
 * ```ts
 * const fmt: PptxThemeFormatScheme = {
 *   name: "Office",
 *   fillStyles: [solidFill, gradientFill, intenseFill],
 *   lineStyles: [thinLine, mediumLine, thickLine],
 *   effectStyles: [subtle, moderate, intense],
 *   backgroundFillStyles: [solidBg, gradientBg, intenseBg],
 * };
 * // => satisfies PptxThemeFormatScheme
 * ```
 */
declare interface PptxThemeFormatScheme {
    /** The `@name` attribute of the format scheme. */
    name?: string;
    /** Fill styles at indices 1-3 (subtle, moderate, intense). */
    fillStyles: PptxThemeFillStyle[];
    /** Line styles at indices 1-3. */
    lineStyles: PptxThemeLineStyle[];
    /** Effect styles at indices 1-3. */
    effectStyles: PptxThemeEffectStyle[];
    /** Background fill styles at indices 1-3 (referenced via idx 1001-1003). */
    backgroundFillStyles: PptxThemeFillStyle[];
}

/**
 * A single line style entry from `a:lnStyleLst`.
 * Provides width, dash, join, cap, and optional fill colour.
 *
 * @example
 * ```ts
 * const line: PptxThemeLineStyle = {
 *   width: 1.5,
 *   color: "#4F81BD",
 *   dash: "solid",
 *   lineJoin: "round",
 *   lineCap: "flat",
 * };
 * // => satisfies PptxThemeLineStyle
 * ```
 */
declare interface PptxThemeLineStyle {
    /** Line width in pixels (converted from EMU). */
    width?: number;
    color?: string;
    opacity?: number;
    dash?: string;
    lineJoin?: 'round' | 'bevel' | 'miter';
    lineCap?: 'flat' | 'rnd' | 'sq';
    compoundLine?: 'sng' | 'dbl' | 'thickThin' | 'thinThick' | 'tri';
    /** Raw XML node preserved for `phClr` re-resolution. */
    rawNode?: unknown;
}

/**
 * A theme part available in the presentation package.
 *
 * @example
 * ```ts
 * const opt: PptxThemeOption = {
 *   path: "ppt/theme/theme1.xml",
 *   name: "Office Theme",
 * };
 * // => satisfies PptxThemeOption
 * ```
 */
declare interface PptxThemeOption {
    /** File path within the PPTX archive (e.g. `ppt/theme/theme2.xml`). */
    path: string;
    /** Human-readable theme name from `a:theme/@name`, when present. */
    name?: string;
}

/**
 * A complete theme preset that can be applied to a presentation.
 *
 * @example
 * ```ts
 * import { THEME_PRESETS } from "pptx-viewer-core";
 *
 * const office = THEME_PRESETS.find(p => p.id === "office");
 * await handler.switchTheme(office.colorScheme, office.fontScheme, office.name);
 * ```
 */
declare interface PptxThemePreset {
    /** Unique identifier for the preset. */
    id: string;
    /** Human-readable display name. */
    name: string;
    /** The 12-colour scheme. */
    colorScheme: PptxThemeColorScheme;
    /** Heading and body font families. */
    fontScheme: PptxThemeFontScheme;
}

/**
 * A single `p:tmpl` timing template parsed from a TEXT `p:bldP/p:tmplLst`
 * (CT_TLTemplate, ECMA-376 §19.5.85; the list itself is CT_TLTemplateList,
 * §19.5.84).
 *
 * PowerPoint writes these as the timing PowerPoint would apply to a build
 * level that does not yet have an instantiated effect, so that promoting or
 * demoting an outline paragraph, or adding a new bullet at a level with no
 * prior animation, has a default to clone. They are not consulted at
 * playback: the animation actually shown for every paragraph level already
 * visible on the slide is the real, instantiated `p:tnLst` under
 * `p:timing/p:tnLst`, which the rest of this parser already models in full.
 *
 * The nested time-node tree under each template's own `p:tnLst` is kept as
 * a preserved `XmlObject` rather than deep-parsed into
 * {@link PptxNativeAnimation} records: it is schema-identical to the
 * top-level timing tree but scoped to a template that is never itself
 * executed, so structurally modelling it would stand up a second, unused
 * parallel animation model. Parsing stops at typed round-trip; see
 * `docs/guide/limitations.md`.
 */
declare interface PptxTimingTemplate {
    /** Build level this template targets, from `p:tmpl/@lvl` (ST_TLLevel, default 0). */
    level: number;
    /** Preserved `p:tnLst` (CT_TimeNodeList) subtree, verbatim. */
    timeNodeList: XmlObject;
    /** Preserved `p:tmpl` XML node (its attributes plus any unmodelled children). */
    rawXml?: XmlObject;
}

/** Schema-defined `ST_TransitionSpeed` values. */
declare type PptxTransitionSpeed = 'slow' | 'med' | 'fast';

/**
 * Available slide transition effects.
 *
 * Maps to the OOXML child element names under `<p:transition>` / `<p14:transition>`.
 *
 * @example
 * ```ts
 * const t: PptxTransitionType = "morph";
 * // => "morph" — one of 40+ transition effects
 * ```
 */
declare type PptxTransitionType = 'none' | 'cut' | 'fade' | 'push' | 'wipe' | 'split' | 'randomBar' | 'blinds' | 'checker' | 'circle' | 'comb' | 'cover' | 'diamond' | 'dissolve' | 'plus' | 'pull' | 'random' | 'strips' | 'uncover' | 'wedge' | 'wheel' | 'zoom' | 'newsflash' | 'morph' | 'conveyor' | 'doors' | 'ferris' | 'flash' | 'flythrough' | 'gallery' | 'glitter' | 'honeycomb' | 'pan' | 'prism' | 'reveal' | 'ripple' | 'shred' | 'switch' | 'vortex' | 'warp' | 'wheelReverse' | 'window' | 'cube' | 'flip' | 'rotate' | 'box' | 'orbit' | 'fallOver' | 'drape' | 'curtains' | 'wind' | 'prestige' | 'fracture' | 'crush' | 'peelOff' | 'pageCurlDouble' | 'pageCurlSingle' | 'airplane' | 'origami';

/** A horizontal or vertical drawing guide in slide coordinates. */
declare interface PptxViewGuide {
    orientation?: 'horz' | 'vert';
    position?: number;
}

/**
 * Origin point for a view (x, y in twips or EMU).
 */
declare interface PptxViewOrigin {
    x: number;
    y: number;
}

/**
 * Full view properties from `ppt/viewProps.xml`.
 */
declare interface PptxViewProperties {
    /** Last used view type (`p:viewPr/@lastView`). */
    lastView?: string;
    /** Whether comments are shown (`p:viewPr/@showComments`). */
    showComments?: boolean;
    /** Normal view properties (splitter positions). */
    normalViewPr?: PptxNormalViewProperties;
    /** Slide view properties. */
    slideViewPr?: PptxCommonSlideViewProperties;
    /** Outline view properties. */
    outlineViewPr?: PptxCommonSlideViewProperties;
    /** Notes text view properties. */
    notesTextViewPr?: PptxCommonSlideViewProperties;
    /** Sorter view scale. */
    sorterViewPr?: {
        scale?: PptxViewScale;
    };
    /** Notes view properties. */
    notesViewPr?: PptxCommonSlideViewProperties;
    /** Grid spacing in positive DrawingML coordinates. */
    gridSpacing?: PptxGridSpacing;
    /** Raw XML preserved for lossless round-trip of unparsed attributes. */
    rawXml?: Record<string, unknown>;
}

/**
 * View properties types parsed from `ppt/viewProps.xml`.
 *
 * Models the `p:viewPr` element and its child views:
 * normalViewPr, slideViewPr, outlineViewPr, notesTextViewPr,
 * sorterViewPr, notesViewPr.
 *
 * @module pptx-types/view-properties
 */
/**
 * Scale factor for a view (numerator / denominator percentage).
 */
declare interface PptxViewScale {
    /** Numerator of the scale percentage (e.g. 100 for 100%). */
    n: number;
    /** Denominator of the scale percentage (e.g. 100 for 100%). */
    d: number;
    /** Optional independent vertical scale. When absent, the X scale is used. */
    sy?: {
        n: number;
        d: number;
    };
}

/**
 * Root builder of the fluent PPTX editing API.
 *
 * Wraps a {@link PptxData} object and provides chainable accessors
 * to navigate into slides, elements, and notes for in-place mutation.
 */
declare class PptxXmlBuilder implements IPptxXmlBuilder {
    /** The presentation data being mutated. */
    private readonly data;
    /** @param data - The presentation data to wrap. */
    constructor(data: PptxData);
    /**
     * Factory method to create a builder from presentation data.
     * @param data - The presentation data to wrap.
     * @returns A new {@link PptxXmlBuilder} instance.
     */
    static from(data: PptxData): PptxXmlBuilder;
    /** @inheritdoc */
    Slides(index: number): PptxSlideBuilder;
    /**
     * Navigate to a slide by zero-based index.
     * @param index - Zero-based slide index.
     * @returns A {@link PptxSlideBuilder} for the requested slide.
     * @throws Error if index is not an integer or is out of range.
     */
    slide(index: number): PptxSlideBuilder;
    /** @inheritdoc */
    slides(index: number): PptxSlideBuilder;
    /** Return the underlying {@link PptxData}. */
    project(): PptxData;
    /** Pascal-case alias for {@link project}. */
    Project(): PptxData;
}

/** Result returned by {@link PresentationBuilder.create}. */
declare interface PresentationBuilderResult {
    /** Initialized handler ready for editing and saving. */
    handler: PptxHandler;
    /** Parsed presentation data. */
    data: PptxData;
    /** Convenience slide builder factory. */
    createSlide: (layoutName?: string) => SlideBuilder;
}

declare interface PresentationOptions {
    /** Slide width in EMU. Default: 12192000 (16:9 widescreen). */
    width?: number;
    /** Slide height in EMU. Default: 6858000 (16:9 widescreen). */
    height?: number;
    /** Theme configuration. */
    theme?: PresentationThemeInput;
    /** Presentation title (stored in docProps/core.xml). */
    title?: string;
    /** Presentation author. */
    creator?: string;
    /**
     * Number of blank slides to include in the initial presentation.
     * Default: 0 (no slides). Slides use the "Blank" layout.
     */
    initialSlideCount?: number;
}

declare interface PresentationThemeInput {
    name?: string;
    colors?: {
        dk1?: string;
        lt1?: string;
        dk2?: string;
        lt2?: string;
        accent1?: string;
        accent2?: string;
        accent3?: string;
        accent4?: string;
        accent5?: string;
        accent6?: string;
        hlink?: string;
        folHlink?: string;
    };
    fonts?: {
        majorFont?: string;
        minorFont?: string;
    };
}

export declare type PresentationTool = 'none' | 'laser' | 'pen' | 'highlighter' | 'eraser';

export declare const PresentationTransitionOverlay: typeof __VLS_export;

/** Keys of an options group whose value is a primitive (not an array). */
declare type PrimitiveKeys<T> = { [K in keyof T]: T[K] extends ViewerOptionPrimitive ? K : never; }[keyof T] & string;

/** Colour mode for the printed output. */
declare type PrintColorMode = 'color' | 'grayscale' | 'blackAndWhite';

/** Page orientation for the printed output. */
declare type PrintOrientation = 'portrait' | 'landscape';

/** Resolved print settings emitted on confirm. */
declare interface PrintSettings {
    printWhat: PrintWhat;
    orientation: PrintOrientation;
    colorMode: PrintColorMode;
    frameSlides: boolean;
    slidesPerPage: HandoutSlidesPerPage;
    slideRange: PrintSlideRange;
    customRangeFrom: number;
    customRangeTo: number;
    /**
     * PowerPoint's Print > "Scale to Fit Paper". `true` (the default, and the
     * only behavior this printed output ever had before this field existed)
     * shrinks/grows each slide image to fill its page/cell while preserving
     * aspect ratio. `false` prints at the slide's native pixel size instead,
     * which may overflow or under-fill the page, exactly like PowerPoint with
     * the option off. Optional so existing `Partial<PrintSettings>` literals
     * across every binding keep compiling; `validatePrintSettings` defaults it
     * to `true`.
     */
    scaleToFit?: boolean;
}

/** Slide range mode. */
declare type PrintSlideRange = 'all' | 'current' | 'custom';

/** What to print. */
declare type PrintWhat = 'slides' | 'handouts' | 'notes' | 'outline';

/** Provide the selection context at the viewer root. */
export declare function provideTableSelection(ctx: TableSelectionContext): void;

declare type QuickAccessPosition = 'above' | 'below';

/** Transition types eligible for `random` selection (kept deterministic-light). */
export declare const RANDOM_ELIGIBLE_TYPES: readonly PptxTransitionType[];

/** One rasterised tile: its full-raster position/size plus the canvas and strategy that produced it. */
declare interface RasterizedTile {
    /** 0-based column index (tiles in the same row share increasing `col`). */
    col: number;
    /** 0-based row index. */
    row: number;
    /** Left edge, in full-raster device pixels. */
    x: number;
    /** Top edge, in full-raster device pixels. */
    y: number;
    width: number;
    height: number;
    canvas: HTMLCanvasElement;
    strategy: RasterStrategy;
}

/** The common case: a normal canvas any `toBlob`/`toDataURL` caller can use directly. */
declare interface RasterizeElementCanvasResult {
    kind: 'canvas';
    canvas: HTMLCanvasElement;
    strategy: RasterStrategy;
    width: number;
    height: number;
}

/** The tiled case: pre-encoded PNG bytes, since no single canvas held the full image. */
declare interface RasterizeElementPngBytesResult {
    kind: 'png-bytes';
    bytes: Uint8Array;
    width: number;
    height: number;
    /** Strategy used per tile, in row-major order, for diagnostics/tests. */
    strategies: RasterStrategy[];
}

declare type RasterizeElementResult = RasterizeElementCanvasResult | RasterizeElementPngBytesResult;

/** The full set of tiles covering one element's export, tiled or not. */
declare interface RasterizeElementTilesResult {
    /** Full raster width in device pixels (sum of every column's width). */
    fullWidth: number;
    /** Full raster height in device pixels (sum of every row's height). */
    fullHeight: number;
    /** `false` when a single tile already covers the whole export. */
    tiled: boolean;
    /** Every tile, row-major order. Exactly one entry when `tiled` is `false`. */
    tiles: RasterizedTile[];
}

/**
 * Rasterise the slide at `index` to an `HTMLCanvasElement`. The host supplies
 * this (it owns the DOM + the `html2canvas-pro` integration); keeping it
 * injected makes `useExport` DOM-free and unit-testable.
 */
export declare type RasterizeSlide = (index: number) => Promise<HTMLCanvasElement>;

/**
 * Rasterise the slide at `index` to an `HTMLCanvasElement`. Supplied by the host
 * (it owns the DOM + `html2canvas-pro` integration over an off-screen
 * `SlideStage`); keeping it injected makes `useMediaExport` DOM-free and
 * unit-testable: exactly the contract `useExport` uses for PNG/PDF.
 */
declare type RasterizeSlide_2 = (index: number) => Promise<HTMLCanvasElement>;

/**
 * usePrint: print-dialog state + the print-with-settings flow for the Vue
 * viewer. Direct slide printing uses core SVG output; composed notes and
 * handouts retain the DOM raster path.
 *
 * The DOM-touching pieces are injected so the composable is unit-testable with
 * mocks, exactly like `useExport` injects `rasterizeSlide`:
 *  - `rasterizeSlide(index)` rasterises one slide to a canvas (the host owns the
 *    off-screen `SlideStage` + `html2canvas-pro` integration).
 *  - `openPrintWindow(html)` opens a print window for a full HTML document. A
 *    default implementation (`window.open` → write → print) is supplied.
 *
 * Slide titles for outline mode reuse the shared `buildOutlineHtml`.
 */
/**
 * Rasterise the slide at `index` to a canvas. Host-supplied (DOM-coupled).
 * `scaleMultiplier` (default 1) is an extra factor the Print dialog's
 * notes/handouts raster path applies on top of the host's own baseline scale
 * when Options > Advanced > "High quality" is on.
 */
declare type RasterizeSlide_3 = (index: number, scaleMultiplier?: number) => Promise<HTMLCanvasElement>;

/** Which path actually produced the tile, for telemetry/tests. */
declare type RasterStrategy = 'foreignObject' | 'vectorSvg' | 'html2canvas';

/**
 * CSS `mask-image`/`-webkit-mask-image` value plus the raw `transform` for a
 * mirrored reflection sibling. Every value is a ready-to-apply CSS string (or
 * `'none'` sentinel avoided - fields are omitted when the browser default
 * already matches), so a binding can spread this directly onto its own style
 * object with no further per-framework logic.
 */
declare interface ReflectionWrapperStyle {
    position: 'absolute';
    left: string;
    /** `calc(100% + <dist>px)`: sits `@dist` px below the source element's box. */
    top: string;
    width: string;
    height: string;
    /** `scale(@sx, @sy)` (the sign of `@sy` IS the mirror) composed with `@kx`/`@ky`/`@rot`. */
    transform: string;
    /** Anchor point for the transform above, from `@algn` (default `center top`). */
    transformOrigin: string;
    maskImage: string;
    WebkitMaskImage: string;
    pointerEvents: 'none';
}

/**
 * CollaborationCursors: presentational overlay that renders remote
 * collaborators' cursors above the slide canvas.
 *
 * This component is purely visual: it owns no network/Yjs logic. The
 * integrator supplies a reactive list of {@link RemoteCursor} entries (via the
 * collaboration composable). Each entry is drawn as an absolutely-positioned
 * pointer SVG plus a name-label chip in the user's colour, placed at `(x, y)`.
 *
 * `x`/`y` are *unscaled* slide coordinates (px) and are used as-is: the
 * overlay is mounted inside the scaled slide-stage host (like the local
 * selection overlay), so the stage's CSS `transform: scale()` applies the zoom
 * exactly once. Multiplying by zoom here as well would double-apply the scale
 * and misplace cursors at any zoom other than 100%.
 *
 * The overlay sets `pointer-events: none` so it never intercepts canvas input.
 */
/** A single remote collaborator's cursor, in unscaled slide coordinates. */
declare interface RemoteCursor {
    /** Stable id for the remote client (awareness clientId or peer id). */
    clientId: number | string;
    /** Display name shown in the label chip. */
    userName: string;
    /** Cursor + chip colour (any CSS colour string). */
    color: string;
    /** Unscaled slide-space X coordinate (px). */
    x: number;
    /** Unscaled slide-space Y coordinate (px). */
    y: number;
    /** Optional ids of elements this user has selected. */
    selectionIds?: string[];
}

/**
 * A remote peer's full presence: identity plus the live cursor, selection and
 * active slide they have published over awareness.
 */
export declare interface RemotePresence {
    clientId: number;
    userName: string;
    color: string;
    cursor?: {
        x: number;
        y: number;
    };
    selectionIds: string[];
    activeSlide: number;
    role?: CollaborationRole;
}

/** The six opt-in interactive-3D scene flags every binding exposes as host props. */
declare interface Rendering3DFlags {
    smartArt3D: boolean;
    surfaceChart3D: boolean;
    barChart3D: boolean;
    lineChart3D: boolean;
    areaChart3D: boolean;
    pieChart3D: boolean;
}

/** Injection key for the resolved flags; a computed ref so a live Options change reaches every injector. */
export declare const Rendering3DFlagsKey: InjectionKey<ComputedRef<Rendering3DFlags>>;

/** A rendered paragraph: runs plus resolved bullet + hanging-indent metadata. */
declare interface RenderParagraph {
    runs: ParagraphRun[];
    /** Bullet glyph / number to render before the runs (or `undefined`). */
    bulletMarker?: string;
    /** Picture marker rendered before runs, or fallback metadata when unresolved. */
    bulletPicture?: PictureBulletMarker;
    /** Inline style for the bullet marker (font / size / colour). */
    bulletStyle: RunStyle;
    /** `margin-left` in px for the whole paragraph (hanging-indent layout). */
    marginLeftPx?: number;
    /** `text-indent` in px (first-line / hanging indent). */
    textIndentPx?: number;
    /**
     * Per-paragraph `line-height` from this paragraph's own `a:pPr > a:lnSpc`.
     * A unitless multiplier for proportional spacing (`a:spcPct`) or a `"<n>pt"`
     * string for exact spacing (`a:spcPts`). Undefined when the paragraph does
     * not override spacing (binding keeps the body-level line-height).
     */
    lineHeight?: number | string;
    /** `margin-top` in px from this paragraph's `a:pPr > a:spcBef` (space before). */
    spaceBeforePx?: number;
    /** `margin-bottom` in px from this paragraph's `a:pPr > a:spcAft` (space after). */
    spaceAfterPx?: number;
    /**
     * `font-size` in px to set on the paragraph element so its CSS line boxes
     * are built from its OWN runs rather than the text body's default size.
     * Undefined when the paragraph already matches the body default.
     *
     * See `resolveParagraphStrutFontSize` for why this is needed: without it a
     * paragraph of small runs inside a larger-defaulting body is laid out on
     * too-tall lines and overflows its shape.
     */
    strutFontSizePx?: number;
    /**
     * True when the paragraph has no runs and no bullet: an authored blank line
     * (`<a:p><a:endParaRPr/></a:p>`).
     *
     * PowerPoint gives such a paragraph a full line box, which is how decks
     * space a heading away from the bullet list under it. A binding must render
     * something with height for it (a `<br>`), or the gap disappears and the
     * block reads as one dense run of text (issue #131, slides 13-14).
     */
    isEmpty?: boolean;
    /**
     * Indices of this paragraph's segments in the rendered segment list (the
     * override list when one was supplied), in authored order and INCLUDING the
     * bullet-marker segment the runs drop.
     *
     * The seam a binding uses to reach paragraph facts the neutral model does not
     * carry, without regrouping the segments itself and drifting from the
     * grouping here - which is exactly how React ended up splitting on every
     * `"\n"` and treating a soft `a:br` as a paragraph break.
     */
    segmentIndices: number[];
    /**
     * True when this paragraph resolves right-to-left (`a:pPr/@rtl`, or the text
     * body's default). A binding that mirrors its hanging indent for RTL reads
     * this; the direction itself is already in {@link paragraphStyle}.
     */
    rtl?: boolean;
    /**
     * Extra CSS for the paragraph box, beyond the margin / indent / spacing
     * fields above: this paragraph's own `text-align` (`a:pPr/@algn`), its BiDi
     * `direction`, and the kinsoku line-breaking rules (`@eaLnBrk`,
     * `@latinLnBrk`, `@hangingPunct`). Absent when the paragraph overrides none
     * of them, which is the common case.
     *
     * All three used to be resolved in React's private paragraph renderer only,
     * so a deck that centred one paragraph of a left-aligned body, or set CJK
     * break rules, rendered differently in the other four bindings.
     */
    paragraphStyle?: RunStyle;
    /**
     * `@hangingPunct` / `@eaLnBrk="0"` as resolved for this paragraph. The runs
     * above already carry their pieces; React, which rebuilds each segment's
     * pieces inside one span, re-applies `splitEastAsianBreaks` from this.
     */
    eastAsianBreaks?: EastAsianBreakOptions;
}

/** The normalised, set-based view of a customisation. Treat as immutable. */
declare interface ResolvedCustomization {
    hiddenActions: ReadonlySet<ToolbarActionId>;
    /** Contextual tabs (`shapeFormat`, ...) the host never wants shown. */
    hiddenContextualTabs: ReadonlySet<RibbonContextualTabId>;
    /** Catalogued ribbon groups to hide (`ribbon.hiddenGroups`). */
    hiddenRibbonGroups: ReadonlySet<RibbonGroupId>;
    /** Catalogued ribbon controls to hide (the `<tab>.<group>.<control>` part of `ribbon.hiddenButtons`). */
    hiddenRibbonControls: ReadonlySet<RibbonControlId>;
    hiddenOptionsPages: ReadonlySet<OptionsPageId>;
    hiddenOptionsSections: ReadonlySet<OptionsSectionId>;
    hiddenSettings: ReadonlySet<OptionsSettingId>;
    lockedSettings: OptionsSettingValues;
    defaultSettings: OptionsSettingValues;
    hiddenBackstagePages: ReadonlySet<BackstagePage>;
    hiddenBackstageCards: ReadonlySet<BackstageCardId>;
    hiddenElementCommands: ReadonlySet<ContextMenuCommandId>;
    hiddenCanvasCommands: ReadonlySet<CanvasContextMenuCommandId>;
    hiddenEditPointsCommands: ReadonlySet<EditPointsCommandId>;
    hiddenDrawingTools: ReadonlySet<ViewerDrawingToolId>;
    elementMenuEnabled: boolean;
    canvasMenuEnabled: boolean;
    hiddenPanels: ReadonlySet<ViewerPanelId>;
    disabledFeatures: ReadonlySet<ViewerFeatureId>;
    hiddenDialogs: ReadonlySet<ViewerDialogId>;
    keyboard: ResolvedKeyboardCustomization;
}

/** The four cardinal directions a transition can resolve to. */
export declare type ResolvedDirection = 'left' | 'right' | 'up' | 'down';

/** Cardinal directions plus the four diagonals (for cover/uncover/strips). */
export declare type ResolvedDirection8 = ResolvedDirection | 'lu' | 'ld' | 'ru' | 'rd';

/** Map an OOXML `dir` token (`l`/`r`/`u`/`d`) to a cardinal direction. */
export declare function resolveDirection(direction: string | undefined, defaultDir: ResolvedDirection): ResolvedDirection;

/** Map an OOXML `dir` token to a cardinal **or diagonal** direction. */
export declare function resolveDirection8(direction: string | undefined, defaultDir: ResolvedDirection): ResolvedDirection8;

/** The normalised keyboard slice of a resolved customisation. */
declare interface ResolvedKeyboardCustomization {
    disableAll: boolean;
    disabled: ReadonlySet<EditorKeyActionName>;
    remap: ReadonlyMap<EditorKeyActionName, readonly ParsedShortcutChord[]>;
}

/**
 * The result of resolving a `<p:style>` block against the loaded theme.
 *
 * `shapeStyle` is exactly what the load pipeline would have produced for a
 * shape whose `spPr` authors nothing and whose `<p:style>` is `styleXml`:
 * the flat fill/outline/effect values a renderer needs, the reference indices
 * and colours the writer re-emits, and the inheritance baselines that tell the
 * writer to leave `spPr` empty while the flat values still agree with them.
 */
declare interface ResolvedStyleMatrix {
    shapeStyle: ShapeStyle;
    /** The text colour `<a:fontRef>` names, resolved to hex. */
    fontColor?: string;
}

/** Resolve an orientation from the `orient` or `direction` attribute. */
export declare function resolveOrientation(direction: string | undefined, orient: string | undefined): 'horz' | 'vert';

/**
 * Pure dispatch logic: a thin translation of Vue's guard shape onto the shared
 * `mapEditorKey`, which is the one keymap every binding resolves against. DOM-
 * free and side-effect-free, so it can be unit-tested with synthetic inputs.
 *
 * Keeping the signature (rather than exposing `mapEditorKey` directly) means the
 * existing shell wiring and tests carry on working while the decision table has
 * only one copy left in the repo.
 */
export declare function resolveShortcutAction(key: string, mod: boolean, shiftKey: boolean, guard: ShortcutGuardState, altKey?: boolean, keyboard?: ResolvedKeyboardCustomization): MatchedShortcut;

/**
 * Convenience wrapper that reads everything off a {@link PptxSlideTransition},
 * applying the React/Vue default duration when none is set. `none`/`cut` and a
 * transition with a non-positive duration resolve to {@link INSTANT}.
 */
export declare function resolveSlideTransition(transition: PptxSlideTransition | undefined): SlideTransitionAnimations;

/**
 * The effective duration (ms) for a transition under the React/Vue policy — the
 * configured `durationMs`, or {@link DEFAULT_TRANSITION_DURATION_MS} when
 * unset/invalid. `none`/`cut` resolve to `0` (instant).
 */
export declare function resolveTransitionDurationMs(transition: PptxSlideTransition | undefined): number;

/** Resolve an authored `spokes` count to the nearest PowerPoint-offered value. */
export declare function resolveWheelSpokeCount(spokes: number | undefined): number;

/** Ribbon `align` key → shared `AlignEdge`. */
export declare const RIBBON_ALIGN: Record<string, AlignEdge>;

declare const RIBBON_CONTROL_CATALOG: {
    readonly home: {
        readonly clipboard: {
            readonly label: 'Clipboard';
            readonly controls: {
                readonly paste: 'Paste';
                readonly cut: 'Cut';
                readonly copy: 'Copy';
                readonly formatPainter: 'Format Painter';
            };
        };
        readonly slides: {
            readonly label: 'Slides';
            readonly controls: {
                readonly newSlide: 'New Slide';
                readonly layout: 'Layout';
                readonly reset: 'Reset';
                readonly section: 'Section';
                readonly slideTemplates: 'Slide templates';
            };
        };
        readonly font: {
            readonly label: 'Font';
            readonly controls: {
                readonly fontFamily: 'Font';
                readonly fontSize: 'Font Size';
                readonly increaseFontSize: 'Increase Font Size';
                readonly decreaseFontSize: 'Decrease Font Size';
                readonly clearFormatting: 'Clear All Formatting';
                readonly bold: 'Bold';
                readonly italic: 'Italic';
                readonly underline: 'Underline';
                readonly strikethrough: 'Strikethrough';
                readonly shadow: 'Text Shadow';
                readonly characterSpacing: 'Character Spacing';
                readonly changeCase: 'Change Case';
                readonly fontColor: 'Font Color';
                readonly highlightColor: 'Text Highlight Color';
                readonly superscript: 'Superscript';
                readonly subscript: 'Subscript';
            };
        };
        readonly paragraph: {
            readonly label: 'Paragraph';
            readonly controls: {
                readonly bullets: 'Bullets (toggle and gallery)';
                readonly numbering: 'Numbering (toggle and gallery)';
                readonly decreaseIndent: 'Decrease List Level';
                readonly increaseIndent: 'Increase List Level';
                readonly lineSpacing: 'Line Spacing';
                readonly alignLeft: 'Align Left';
                readonly alignCenter: 'Center';
                readonly alignRight: 'Align Right';
                readonly justify: 'Justify';
                readonly columns: 'Columns';
                readonly textDirection: 'Text Direction';
                readonly alignText: 'Align Text';
            };
        };
        readonly drawing: {
            readonly label: 'Drawing';
            readonly controls: {
                readonly shapes: 'Shapes';
                readonly arrange: 'Arrange';
                readonly quickStyles: 'Quick Styles (Shape Styles gallery)';
                readonly shapeFill: 'Shape Fill';
                readonly shapeOutline: 'Shape Outline';
                readonly shapeEffects: 'Shape Effects gallery';
            };
        };
        readonly arrange: {
            readonly label: 'Arrange';
            readonly controls: {
                readonly bringForward: 'Bring Forward';
                readonly sendBackward: 'Send Backward';
                readonly bringToFront: 'Bring to Front';
                readonly sendToBack: 'Send to Back';
                readonly flipHorizontal: 'Flip Horizontal';
                readonly flipVertical: 'Flip Vertical';
                readonly duplicate: 'Duplicate';
                readonly delete: 'Delete';
                readonly group: 'Group';
                readonly ungroup: 'Ungroup';
                readonly align: 'Align';
                readonly mergeShapes: 'Merge Shapes';
                readonly crop: 'Crop';
                readonly outlineWidth: 'Outline width';
            };
        };
        readonly editing: {
            readonly label: 'Editing';
            readonly controls: {
                readonly find: 'Find';
                readonly replace: 'Replace';
                readonly select: 'Select';
            };
        };
    };
    readonly insert: {
        readonly slides: {
            readonly label: 'Slides';
            readonly controls: {
                readonly newSlide: 'New Slide';
            };
        };
        readonly tables: {
            readonly label: 'Tables';
            readonly controls: {
                readonly table: 'Table';
            };
        };
        readonly images: {
            readonly label: 'Images';
            readonly controls: {
                readonly pictures: 'Pictures';
            };
        };
        readonly illustrations: {
            readonly label: 'Illustrations';
            readonly controls: {
                readonly shapes: 'Shapes';
                readonly smartArt: 'SmartArt';
                readonly chart: 'Chart';
            };
        };
        readonly links: {
            readonly label: 'Links';
            readonly controls: {
                readonly link: 'Link';
                readonly action: 'Action button';
            };
        };
        readonly comments: {
            readonly label: 'Comments';
            readonly controls: {
                readonly comment: 'Comment';
            };
        };
        readonly text: {
            readonly label: 'Text';
            readonly controls: {
                readonly textBox: 'Text Box';
                readonly field: 'Header, date, slide number field';
            };
        };
        readonly symbols: {
            readonly label: 'Symbols';
            readonly controls: {
                readonly equation: 'Equation';
                readonly symbol: 'Symbol';
            };
        };
        readonly media: {
            readonly label: 'Media';
            readonly controls: {
                readonly media: 'Video / Audio';
            };
        };
    };
    readonly draw: {
        readonly tools: {
            readonly label: 'Drawing Tools';
            readonly controls: {
                readonly select: 'Select';
                readonly pen: 'Pen';
                readonly highlighter: 'Highlighter';
                readonly eraser: 'Eraser';
                readonly penColor: 'Pen colour';
                readonly penWidth: 'Pen width';
            };
        };
        readonly convert: {
            readonly label: 'Convert';
            readonly controls: {
                readonly inkToShape: 'Ink to Shape';
            };
        };
    };
    readonly design: {
        readonly themes: {
            readonly label: 'Themes';
            readonly controls: {
                readonly browseThemes: 'Themes gallery';
                readonly editTheme: 'Edit theme';
            };
        };
        readonly variants: {
            readonly label: 'Variants';
            readonly controls: {
                readonly colors: 'Variants: Colors gallery';
                readonly fonts: 'Variants: Fonts gallery';
            };
        };
        readonly customize: {
            readonly label: 'Customize';
            readonly controls: {
                readonly slideSize: 'Slide Size';
                readonly formatBackground: 'Format Background';
            };
        };
    };
    readonly transitions: {
        readonly preview: {
            readonly label: 'Preview';
            readonly controls: {
                readonly preview: 'Preview';
            };
        };
        readonly transitionToThisSlide: {
            readonly label: 'Transition to This Slide';
            readonly controls: {
                readonly gallery: 'Transition gallery';
                readonly effectOptions: 'Effect Options';
            };
        };
        readonly timing: {
            readonly label: 'Timing';
            readonly controls: {
                readonly sound: 'Sound';
                readonly duration: 'Duration';
                readonly applyToAll: 'Apply To All';
                readonly advanceOnClick: 'On Mouse Click';
                readonly advanceAfter: 'After';
            };
        };
    };
    readonly animations: {
        readonly preview: {
            readonly label: 'Preview';
            readonly controls: {
                readonly preview: 'Preview';
            };
        };
        readonly animation: {
            readonly label: 'Animation';
            readonly controls: {
                readonly gallery: 'Animation gallery';
                readonly effectOptions: 'Effect Options';
            };
        };
        readonly motionPath: {
            readonly label: 'Motion Paths';
            readonly controls: {
                readonly gallery: 'Motion path gallery';
            };
        };
        readonly advancedAnimation: {
            readonly label: 'Advanced Animation';
            readonly controls: {
                readonly addAnimation: 'Add Animation';
                readonly animationPane: 'Animation Pane';
                readonly trigger: 'Trigger';
                readonly animationPainter: 'Animation Painter';
                readonly remove: 'Remove animation';
            };
        };
        readonly timing: {
            readonly label: 'Timing';
            readonly controls: {
                readonly start: 'Start';
                readonly duration: 'Duration';
                readonly delay: 'Delay';
                readonly reorder: 'Reorder';
            };
        };
    };
    readonly slideShow: {
        readonly startSlideShow: {
            readonly label: 'Start Slide Show';
            readonly controls: {
                readonly fromBeginning: 'From Beginning';
                readonly fromCurrent: 'From Current Slide';
                readonly customShow: 'Custom Slide Show';
            };
        };
        readonly present: {
            readonly label: 'Present';
            readonly controls: {
                readonly presenterView: 'Presenter View';
                readonly broadcast: 'Present Online';
            };
        };
        readonly setUp: {
            readonly label: 'Set Up';
            readonly controls: {
                readonly setUpSlideShow: 'Set Up Slide Show';
                readonly hideSlide: 'Hide Slide';
                readonly rehearseTimings: 'Rehearse Timings';
                readonly record: 'Record';
                readonly rehearseWithCoach: 'Rehearse with Coach';
            };
        };
        readonly captions: {
            readonly label: 'Captions & Subtitles';
            readonly controls: {
                readonly subtitles: 'Always Use Subtitles';
                readonly subtitleSettings: 'Subtitle Settings';
            };
        };
    };
    readonly record: {
        readonly camera: {
            readonly label: 'Camera';
            readonly controls: {
                readonly cameo: 'Cameo';
            };
        };
        readonly record: {
            readonly label: 'Record';
            readonly controls: {
                readonly fromBeginning: 'From Beginning';
                readonly fromCurrent: 'From Current Slide';
            };
        };
        readonly manage: {
            readonly label: 'Manage';
            readonly controls: {
                readonly clear: 'Clear';
                readonly reset: 'Reset to Cameo';
            };
        };
        readonly help: {
            readonly label: 'Help';
            readonly controls: {
                readonly learnMore: 'Learn more';
            };
        };
    };
    readonly review: {
        readonly proofing: {
            readonly label: 'Proofing';
            readonly controls: {
                readonly spelling: 'Spelling';
                readonly thesaurus: 'Thesaurus';
            };
        };
        readonly accessibility: {
            readonly label: 'Accessibility';
            readonly controls: {
                readonly check: 'Check Accessibility';
            };
        };
        readonly language: {
            readonly label: 'Language';
            readonly controls: {
                readonly translate: 'Translate';
            };
        };
        readonly comments: {
            readonly label: 'Comments';
            readonly controls: {
                readonly newComment: 'New Comment';
                readonly delete: 'Delete';
                readonly previous: 'Previous';
                readonly next: 'Next';
                readonly showComments: 'Show Comments';
            };
        };
        readonly compare: {
            readonly label: 'Compare';
            readonly controls: {
                readonly compare: 'Compare';
                readonly markAllRead: 'Mark all read';
            };
        };
        readonly protect: {
            readonly label: 'Protect';
            readonly controls: {
                readonly readOnly: 'Read-only';
                readonly restrictPermission: 'Restrict Permission';
            };
        };
        readonly ink: {
            readonly label: 'Ink';
            readonly controls: {
                readonly hideInk: 'Hide Ink';
            };
        };
    };
    readonly view: {
        readonly presentationViews: {
            readonly label: 'Presentation Views';
            readonly controls: {
                readonly normal: 'Normal';
                readonly outline: 'Outline View';
                readonly slideSorter: 'Slide Sorter';
                readonly notesPage: 'Notes Page';
                readonly readingView: 'Reading View';
            };
        };
        readonly masterViews: {
            readonly label: 'Master Views';
            readonly controls: {
                readonly slideMaster: 'Slide Master';
                readonly handoutMaster: 'Handout Master';
                readonly notesMaster: 'Notes Master';
            };
        };
        readonly show: {
            readonly label: 'Show';
            readonly controls: {
                readonly ruler: 'Ruler';
                readonly gridlines: 'Gridlines';
                readonly guides: 'Guides';
                readonly snapToGrid: 'Snap to Grid';
                readonly snapToShape: 'Snap to Shape';
                readonly addGuide: 'Add horizontal / vertical guide';
                readonly selectionPane: 'Selection Pane';
                readonly eyedropper: 'Eyedropper';
                readonly notes: 'Notes';
            };
        };
        readonly zoom: {
            readonly label: 'Zoom';
            readonly controls: {
                readonly zoom: 'Zoom';
                readonly fitToWindow: 'Fit to Window';
            };
        };
        readonly window: {
            readonly label: 'Window';
            readonly controls: {
                readonly templateEditing: 'Edit template elements';
                readonly macros: 'Macros';
            };
        };
    };
    readonly help: {
        readonly help: {
            readonly label: 'Help';
            readonly controls: {
                readonly options: 'Options';
                readonly keyboardShortcuts: 'Keyboard shortcuts';
                readonly accessibility: 'Accessibility checker';
            };
        };
    };
    readonly shapeFormat: {
        readonly shapeStyles: {
            readonly label: 'Shape Styles';
            readonly controls: {
                readonly gallery: 'Shape Styles gallery';
                readonly shapeEffects: 'Shape Effects gallery';
            };
        };
        readonly wordArtStyles: {
            readonly label: 'WordArt Styles';
            readonly controls: {
                readonly gallery: 'WordArt Styles gallery';
            };
        };
    };
    readonly pictureFormat: {
        readonly pictureStyles: {
            readonly label: 'Picture Styles';
            readonly controls: {
                readonly gallery: 'Picture Styles gallery';
                readonly pictureEffects: 'Picture Effects gallery';
            };
        };
    };
    readonly tableDesign: {
        readonly tableStyles: {
            readonly label: 'Table Styles';
            readonly controls: {
                readonly gallery: 'Table Styles gallery';
            };
        };
    };
    readonly chartDesign: {
        readonly chartLayouts: {
            readonly label: 'Chart Layouts';
            readonly controls: {
                readonly quickLayout: 'Quick Layout gallery';
            };
        };
        readonly chartStyles: {
            readonly label: 'Chart Styles';
            readonly controls: {
                readonly changeColors: 'Change Colors gallery';
                readonly gallery: 'Chart Styles gallery';
            };
        };
    };
    readonly smartArtDesign: {
        readonly smartArtStyles: {
            readonly label: 'SmartArt Styles';
            readonly controls: {
                readonly changeColors: 'Change Colors gallery';
                readonly gallery: 'SmartArt Styles gallery';
            };
        };
    };
};

/**
 * PowerPoint's contextual tabs: they join the tab row only while the
 * selection is of their kind (see `contextualTabsForElement` in
 * `ribbon-galleries/`). Kept apart from `ToolbarTabId` because they are not
 * part of the fixed tab order every binding renders.
 */
declare type RibbonContextualTabId = 'shapeFormat' | 'pictureFormat' | 'tableDesign' | 'chartDesign' | 'smartArtDesign';

/** `<tab>.<group>.<control>`, for example `home.font.bold`. */
declare type RibbonControlId = { [T in keyof Catalog]: { [G in keyof Catalog[T]]: Catalog[T][G] extends {
            controls: infer C;
        } ? `${T & string}.${G & string}.${keyof C & string}` : never; }[keyof Catalog[T]]; }[keyof Catalog];

/** `<tab>.<group>`, for example `home.font`. */
declare type RibbonGroupId = { [T in keyof Catalog]: { [G in keyof Catalog[T]]: `${T & string}.${G & string}`; }[keyof Catalog[T]]; }[keyof Catalog];

/**
 * Aggregate ribbon contract (state + callbacks). Mirrors React `ToolbarProps`.
 * The shell (`RibbonToolbar.vue`) passes the relevant subset to each section.
 */
declare interface RibbonProps {
    fileName?: string;
    mode: ViewerMode;
    canEdit: boolean;
    isNarrowViewport: boolean;
    isSidebarCollapsed: boolean;
    isInspectorPaneOpen: boolean;
    isCompactToolbarOpen: boolean;
    toolbarSection: ToolbarSection;
    scale: number;
    canUndo: boolean;
    canRedo: boolean;
    undoLabel?: string;
    redoLabel?: string;
    findReplaceOpen: boolean;
    selectedElement: PptxElement | null;
    /** How many elements the multi-select holds; Group needs two. */
    selectedCount: number;
    /** Whether every selected element allows `a:spLocks/@noGrp` grouping. */
    selectionGroupable: boolean;
    tableEditorState?: TableCellEditorState | null;
    editTemplateMode: boolean;
    newShapeType: SupportedShapeType;
    activeTool: DrawingTool;
    drawingColor: string;
    drawingWidth: number;
    clipboardPayload: ElementClipboardPayload | null;
    spellCheckEnabled: boolean;
    showGrid: boolean;
    showRulers: boolean;
    /**
     * Guide-overlay visibility. Separate from `snapToShape`: hiding the guides
     * must not stop the editor snapping, and the guides stay in the model either
     * way so snapping and save still see the full list.
     */
    showGuides: boolean;
    snapToGrid: boolean;
    snapToShape: boolean;
    isOverflowMenuOpen: boolean;
    layoutOptions: LayoutOption[];
    /** `layoutPath` of the active slide, marking the current gallery tile. */
    currentLayoutPath?: string;
    /** Builds the New Slide / Layout gallery artwork on first menu open. */
    loadLayoutPreviews?: () => Promise<PptxLayoutPreview[]>;
    /** Theme major/minor latin faces, leading the font dropdown. */
    themeFonts?: {
        heading?: string;
        body?: string;
    };
    /** Families the deck embeds, offered as their own dropdown group. */
    embeddedFontFamilies?: readonly string[];
    /** Families registered this session via File > Options > Fonts. */
    customFontFamilies?: readonly string[];
    customShows: PptxCustomShow[];
    activeCustomShowId: string | null;
    isCurrentSlideInActiveShow: boolean;
    hasMacros: boolean;
    isThemeEditorOpen: boolean;
    isThemeGalleryOpen: boolean;
    isCommentsPanelOpen?: boolean;
    slideCommentCount?: number;
    formatPainterActive?: boolean;
    canActivateFormatPainter?: boolean;
    isSelectionPaneOpen?: boolean;
    eyedropperActive?: boolean;
    showSubtitles?: boolean;
    activeSlide?: PptxSlide;
    /** True when a collaboration session is connected (Share button turns green). */
    isCollaborating?: boolean;
    /** Connected collaborator count, shown on the Share button while collaborating. */
    collaboratorCount?: number;
    /** Toolbar buttons / ribbon tabs the host has asked to hide. Undefined/empty hides nothing. */
    hiddenActions?: ToolbarActionId[];
    /** File > Options > Advanced > "Quickly access this number of Recent Documents". */
    recentPresentationsCount?: number;
    /** True when the host opted into the AI assistant (the `ai` prop is set). */
    aiEnabled?: boolean;
    /** Whether the AI chat panel is currently open (drives the toggle's active state). */
    isAiPanelOpen?: boolean;
    /** Toggle the AI chat panel open/closed. */
    onToggleAiPanel?: () => void;
    onSetMode: (mode: ViewerMode) => void;
    /** Slide Show > Start > From Beginning: the show's first slide, unconditionally. */
    onPresentFromBeginning: () => void;
    onToggleSidebar: () => void;
    onToggleInspector: () => void;
    onOpenAnimationPanel: () => void;
    /** `motionPath` carries a motion-path catalogue id in `preset`, not a preset name. */
    onAddAnimation?: (preset: string, group: AnimationApplyGroup) => void;
    onRemoveAnimation?: () => void;
    onToggleCompactToolbar: () => void;
    onSetToolbarSection: (section: ToolbarSection) => void;
    onZoomIn: () => void;
    onZoomOut: () => void;
    onZoomToFit: () => void;
    onUndo: () => void;
    onRedo: () => void;
    onToggleFindReplace: () => void;
    onSelectAll?: () => void;
    onSetNewShapeType: (type: SupportedShapeType) => void;
    onAddTextBox: () => void;
    onAddShape: () => void;
    onAddTable: () => void;
    onAddChart?: (chartKind: InsertChartKind) => void;
    onAddSmartArt: () => void;
    onAddEquation: () => void;
    onAddActionButton: (shapeType: string) => void;
    onInsertField?: (fieldType: string, value?: string) => void;
    onOpenHeaderFooter?: () => void;
    onOpenImagePicker: () => void;
    onOpenMediaPicker: () => void;
    onSetActiveTool: (tool: DrawingTool) => void;
    onSetDrawingColor: (color: string) => void;
    onSetDrawingWidth: (width: number) => void;
    onSetEditTemplateMode: (mode: boolean) => void;
    onSetSpellCheckEnabled: (enabled: boolean) => void;
    onSetShowGrid: (enabled: boolean) => void;
    onSetShowRulers: (enabled: boolean) => void;
    onSetShowGuides: (enabled: boolean) => void;
    onSetSnapToGrid: (enabled: boolean) => void;
    onSetSnapToShape: (enabled: boolean) => void;
    onAddGuide: (axis: 'h' | 'v') => void;
    onAlignElements: (align: string) => void;
    onDistributeElements: (axis: string) => void;
    canDistribute: boolean;
    onCopy: () => void;
    onCut: () => void;
    onPaste: () => void;
    onFlip: (direction: 'horizontal' | 'vertical') => void;
    onMoveLayer: (direction: string) => void;
    onMoveLayerToEdge: (direction: string) => void;
    onGroupElements: () => void;
    onUngroupElement: () => void;
    /** Patch the selection's `shapeStyle` (the Arrange group's outline width). */
    onUpdateElementStyle: (updates: Partial<ShapeStyle>) => void;
    /** Open the hyperlink editor for the selection (Insert > Link). */
    onOpenHyperlinkDialog: () => void;
    onDuplicate: () => void;
    onDelete: () => void;
    /** Open another presentation (File ▸ Open). Hidden when not provided. */
    onOpenFile?: () => void;
    onOpenRecentFile?: (key: string) => void;
    onCreatePresentation: (templateId: string) => void;
    onExportPng: () => void;
    onExportPdf: () => void;
    onExportVideo: () => void;
    onExportGif: () => void;
    /** Serialise the deck to pptx-viewer-json and download it (Export page card). */
    onExportJson: () => void;
    onOpenShareDialog?: () => void;
    onSaveAsPptx: () => void;
    onSaveAsPpsx: () => void;
    onSaveAsPptm: () => void;
    onSaveAsPpt: () => void;
    onCopySlideAsImage: () => void;
    onPrint: () => void;
    onToggleShortcuts: () => void;
    onOpenSettings?: () => void;
    onRunAccessibilityCheck: () => void;
    onToggleSlideSorter: () => void;
    /**
     * View > Normal: leave whichever alternate view (slide sorter, reading,
     * outline, master) is open and return to the ordinary editing canvas.
     */
    onGoToNormalView?: () => void;
    /** Open the windowed Reading View (NOT the fullscreen slide show). */
    onOpenReadingView: () => void;
    /** Enter PowerPoint's Outline view: the deck as editable indented text. */
    onOpenOutlineView: () => void;
    onUpdateTextStyle: (updates: Partial<TextStyle>) => void;
    /** Rewrite the selected text's characters (PowerPoint's Aa "Change Case" dropdown). */
    onTransformTextCase: (mode: ChangeCaseMode) => void;
    onSetOverflowMenuOpen: (open: boolean) => void;
    onInsertSlideFromLayout: (path: string, name?: string) => void;
    /** Insert a pre-designed slide template after the active slide (Home ▸ Slide Templates). */
    onInsertSlideFromTemplate?: (templateId: SlideTemplateId) => void;
    /** Deck scheme map so template gallery previews show the deck's theme colours. */
    templateScheme?: Record<string, string>;
    onApplyLayout?: (path: string) => void;
    onResetSlide?: () => void;
    onAddSection?: () => void;
    onSetActiveCustomShowId: (id: string | null) => void;
    onCreateCustomShow: () => void;
    onRenameActiveCustomShow: () => void;
    onDeleteActiveCustomShow: () => void;
    onToggleCurrentSlideInActiveShow: () => void;
    onToggleVersionHistory?: () => void;
    onOpenPasswordProtection?: () => void;
    onOpenDocumentProperties?: () => void;
    /** Design > Slide Size: reveal the inspector card that owns the size. */
    onOpenSlideSize?: () => void;
    onOpenFontEmbedding?: () => void;
    onOpenDigitalSignatures?: () => void;
    onEnterMasterView: () => void;
    onCloseMasterView: () => void;
    onEnterPresenterView?: () => void;
    onEnterRehearsalMode?: () => void;
    onToggleThemeEditor: () => void;
    onToggleThemeGallery: () => void;
    onCompare?: () => void;
    onToggleComments?: () => void;
    onToggleFormatPainter?: () => void;
    onToggleSelectionPane?: () => void;
    onToggleEyedropper?: () => void;
    onOpenSetUpSlideShow?: () => void;
    /** PowerPoint's Hide Slide toggle for the active slide (Slide Show tab). */
    onToggleHideSlide?: () => void;
    /** Whether the active slide is hidden, for Hide Slide's pressed state. */
    activeSlideHidden?: boolean;
    onOpenBroadcastDialog?: () => void;
    onToggleSubtitles?: () => void;
    onTransitionChange: (updates: Partial<PptxSlideTransition>) => void;
    onApplyTransitionToAll: () => void;
    /** Deck presentation properties backing the Slide Show tab's Options checkboxes. */
    presentationProperties?: PptxPresentationProperties;
    /** Commit an Options checkbox onto the deck's presentation properties. */
    onPresentationPropertiesChange?: (updates: Partial<PptxPresentationProperties>) => void;
}

/** An inline equation run (`m:oMath`), rendered as MathML rather than text. */
declare interface RunEquation {
    /** The raw OMML node, for `convertOmmlToMathMl`. */
    xml: Record<string, unknown>;
    /** Display number for a numbered equation, without its parentheses. */
    number?: string;
}

/** A run's resolved hyperlink target. */
declare interface RunHyperlink {
    /**
     * The URL to hand a click handler. For an internal `ppaction://hlinksldjump`
     * the resolved slide index is appended as a `slideIndex` query parameter, so
     * the target survives a callback whose only argument is the URL (see
     * `parsePpactionUrl`, which reads it back off).
     */
    url: string;
    /**
     * A safe, renderable `href` for a plain `<a>`, or `undefined` when the target
     * is an internal `ppaction://` action or fails the URL safety check. A
     * binding with no click handler renders the run as text in that case, which
     * is what every binding did for every link before this field existed.
     */
    href?: string;
    /** `a:hlinkClick/@tooltip`, for the anchor's `title`. */
    tooltip?: string;
    /**
     * `<a target>` for a real (non-`ppaction://`) hyperlink, from
     * `a:hlinkClick/@tgtFrame` when authored, else `_blank` (every binding's
     * pre-existing hardcoded default). Only meaningful alongside {@link href}.
     */
    target?: string;
    /** `<a rel>` paired with {@link target} (see `resolveHyperlinkTargetAttrs`). */
    rel?: string;
    /** Resolved target slide for an internal slide jump. */
    targetSlideIndex?: number;
    /**
     * True when the target came from `a:hlinkMouseOver` rather than
     * `a:hlinkClick`: PowerPoint follows it on hover, not on click, so a binding
     * that renders a plain anchor should not make it look clickable.
     */
    onHover?: boolean;
}

/** A run's phonetic guide, ready to render as `<rt>` above the base text. */
declare interface RunRuby {
    /** The annotation itself (`a:ruby/a:rt`), e.g. the furigana reading. */
    text: string;
    /** Inline style for the `<rt>` element (size, family, alignment, colour). */
    style: RunStyle;
}

/** A plain CSS style map (keys are CSS properties; binding-agnostic). */
declare type RunStyle = Record<string, string | number>;

/**
 * Presence data for a remote collaborator, sanitised from the awareness
 * protocol. Returned by {@link sanitizePresence}; coordinates are in unscaled
 * slide pixels, clamped to the supplied canvas bounds.
 */
declare interface SanitizedPresence {
    clientId: number;
    userName: string;
    userAvatar?: string;
    userColor: string;
    activeSlideIndex: number;
    cursorX: number;
    cursorY: number;
    lastUpdated: string;
    selectedElementId?: string;
    role?: CollaborationRole;
}

/**
 * Full PowerPoint "File > Options" parity model.
 *
 * Groups mirror the ten categories of PowerPoint's Options dialog. Values are
 * flat primitives per group so the dialog panes can be rendered generically
 * from `VIEWER_OPTIONS_SCHEMA` in every binding. The legacy six-toggle
 * `ViewerPreferences` surface stays supported via the mapping helpers below.
 */
declare type ScreenTipStyle = 'descriptions' | 'plain' | 'off';

/** One script-tagged piece of a run's text, ready for a binding's nested span. */
declare interface ScriptFontPiece {
    text: string;
    /**
     * CSS for a nested span wrapping `text`, or `undefined` when this piece
     * needs no span at all (its script's font equals the run's own, so plain
     * text renders identically). When present it carries the `fontFamily`
     * override plus the run's own decoration subset, repeated because
     * `text-decoration-*` does not inherit into a nested span (see
     * `nestedTextDecorationStyle`).
     */
    style?: RunStyle;
}

/** A section paired with the ordered slides that belong to it. */
export declare type SectionGroup = SectionSlideGroup<PptxSection>;

/** Minimum section metadata needed to build sidebar groups. */
declare interface SectionGroupDescriptor {
    id: string;
    name: string;
    collapsed?: boolean;
    color?: string;
}

/** A declared section paired with its slides, or the trailing ungrouped slides. */
declare interface SectionSlideGroup<TSection extends SectionGroupDescriptor = PptxSection> {
    section: TSection | undefined;
    slides: PptxSlide[];
    slideIndexes: number[];
}

/**
 * Shadow effect properties for a single shadow layer.
 *
 * Represents parsed values from an `<a:outerShdw>` node. Multiple instances
 * can be stored in {@link ShapeStyle.shadows} for compound shadow effects.
 *
 * @example
 * ```ts
 * const shadow: ShadowEffect = {
 *   color: "#000000",
 *   opacity: 0.4,
 *   blur: 6,
 *   angle: 315,
 *   distance: 4,
 * };
 * // => { color: "#000000", opacity: 0.4, blur: 6, angle: 315, distance: 4 } satisfies ShadowEffect
 * ```
 */
declare interface ShadowEffect {
    /** Shadow color as hex string. */
    color: string;
    /** Shadow opacity (0-1). */
    opacity: number;
    /** Blur radius in pixels. */
    blur: number;
    /** Shadow angle in degrees (0-360). */
    angle: number;
    /** Shadow distance in pixels. */
    distance: number;
    /** Whether shadow rotates with shape. */
    rotateWithShape?: boolean;
}

declare interface ShadowInput {
    color?: string;
    blur?: number;
    offsetX?: number;
    offsetY?: number;
    opacity?: number;
}

declare interface ShapeOptions extends Partial<ElementPosition> {
    fill?: FillInput;
    stroke?: StrokeInput;
    text?: string;
    textStyle?: Partial<TextStyleInput>;
    adjustments?: Record<string, number>;
    shadow?: ShadowInput;
    opacity?: number;
}

/**
 * A shape — may contain text and custom geometry (preset or freeform).
 *
 * @example
 * ```ts
 * const rect: ShapePptxElement = {
 *   type: "shape",
 *   id: "shp_1", x: 100, y: 200, width: 300, height: 150,
 *   shapeType: "roundRect",
 *   shapeStyle: { fillColor: "#00AA55" },
 *   text: "OK",
 * };
 * // => satisfies ShapePptxElement
 * ```
 */
declare interface ShapePptxElement extends PptxElementBase, PptxTextProperties, PptxShapeProperties, PptxCustomPathProperties, PptxAccessibilityProperties, PptxNonVisualDescription {
    type: 'shape';
}

/** Shape presets offered by the Insert group. Mirrors React's `newShapeType`. */
declare type ShapePreset = 'rect' | 'ellipse' | 'roundRect' | 'triangle';

/**
 * Comprehensive visual style for a shape, connector, or image element.
 *
 * All fields are optional. When absent, the element inherits from theme
 * or layout defaults. The interface models both simple styling (solid fill +
 * basic stroke) and advanced effects (multiple shadow layers, gradient
 * fills, 3-D extrusion).
 *
 * @example
 * ```ts
 * // Simple blue filled shape with a thin black outline:
 * const simple: ShapeStyle = {
 *   fillColor: "#0055AA",
 *   fillMode: "solid",
 *   strokeColor: "#000000",
 *   strokeWidth: 1,
 * };
 *
 * // Gradient fill with a soft shadow:
 * const fancy: ShapeStyle = {
 *   fillMode: "gradient",
 *   fillGradientType: "linear",
 *   fillGradientAngle: 135,
 *   fillGradientStops: [
 *     { color: "#FF6B6B", position: 0 },
 *     { color: "#556270", position: 1 },
 *   ],
 *   shadowColor: "#000000",
 *   shadowBlur: 10,
 *   shadowOffsetX: 4,
 *   shadowOffsetY: 4,
 *   shadowOpacity: 0.3,
 * };
 * // => both satisfy the ShapeStyle interface
 * ```
 */
declare interface ShapeStyle {
    fillColor?: string;
    /**
     * Raw XML colour-choice node preserved from `a:solidFill` for round-trip
     * serialisation. Captures `a:schemeClr` / `a:sysClr` / `a:prstClr` /
     * `a:srgbClr` plus colour transforms (`lumMod`, `lumOff`, `tint`,
     * `shade`, `satMod`, `alpha`, …). On save we re-emit verbatim when the
     * resolved {@link fillColor} still matches this node, otherwise we fall
     * back to canonical `<a:srgbClr>`.
     */
    fillColorXml?: XmlObject;
    /**
     * Typed theme colour reference for the fill, set when {@link fillColorXml}
     * is a plain `a:schemeClr` (see `themeColorRefFromColorChoice`). When
     * present it WINS on save: the writer emits `<a:schemeClr>` from this ref
     * instead of the resolved {@link fillColor}, so the fill keeps following
     * the theme palette after a later theme change. `undefined` means the fill
     * is a plain hex (or a colour kind a ref cannot express).
     */
    fillColorRef?: PptxThemeColorRef;
    fillGradient?: string;
    /** Original `gradFill` XML retained for unknown-child and extension round-tripping. */
    fillGradientXml?: XmlObject;
    fillMode?: 'solid' | 'gradient' | 'pattern' | 'none' | 'image' | 'theme' | 'group';
    /**
     * `<p:sp useBgFill="1">`: the shape paints with the SLIDE BACKGROUND's fill
     * rather than its own or its theme style's.
     *
     * PowerPoint's designer emits full-bleed rectangles this way, and they also
     * carry an `a:fillRef` pointing at `accent1`. Ignoring the attribute painted
     * those panels in the accent colour, so a black-and-white title slide came out
     * black-and-blue. The load pipeline copies the resolved slide background onto
     * the fill fields; the flag stays for round-trip and for renderers that want
     * to re-resolve against a changed background.
     */
    useBackgroundFill?: boolean;
    fillPatternPreset?: string;
    fillPatternBackgroundColor?: string;
    /** Original `pattFill` XML retained for unknown-child round-tripping. */
    fillPatternXml?: XmlObject;
    /** Raw XML node for pattern fill foreground colour (preserves color transforms). */
    fillPatternFgClrXml?: XmlObject;
    /** Raw XML node for pattern fill background colour (preserves color transforms). */
    fillPatternBgClrXml?: XmlObject;
    /** Data-URI or URL for image fill (when fillMode === "image"). */
    fillImageUrl?: string;
    /** How the image is sized within the shape: stretch to fill, or tile/repeat. */
    fillImageMode?: 'stretch' | 'tile';
    /** Whether the image fill rotates/flips with the shape (`a:blipFill/@rotWithShape`).
     *  Defaults to true per the schema; preserved for round-trip when the source
     *  authored the attribute explicitly. When false, the shape's own geometry
     *  (clip-path/outline) still carries the shape's rotation/flip, but the
     *  picture content inside stays fixed to the page frame (upright), matching
     *  PowerPoint. See `pptx-viewer-shared`'s `getImageFillCounterTransform`. */
    fillImageRotWithShape?: boolean;
    fillGradientStops?: Array<{
        color: string;
        position: number;
        opacity?: number;
        /** Raw XML colour node preserved for round-trip (e.g. a:schemeClr with transforms). */
        originalColorXml?: XmlObject;
        /**
         * Typed theme colour reference for this stop, set when
         * {@link originalColorXml} is a plain `a:schemeClr`. Wins on save, same
         * as {@link ShapeStyle.fillColorRef}.
         */
        colorRef?: PptxThemeColorRef;
    }>;
    fillGradientAngle?: number;
    fillGradientType?: 'linear' | 'radial';
    /** Path gradient sub-type from `a:path/@path` (e.g. "circle", "rect", "shape"). */
    fillGradientPathType?: 'circle' | 'rect' | 'shape';
    /** Focal point for path (radial) gradients, derived from `a:fillToRect`.
     *  Values are 0..1 fractions relative to shape bounds. */
    fillGradientFocalPoint?: {
        x: number;
        y: number;
    };
    /** Raw fillToRect LTRB values (0..1 fractions) from `a:fillToRect`.
     *  Defines the inner rectangle where the gradient reaches its final stop.
     *  l/t are insets from left/top edges; r/b are insets from right/bottom edges. */
    fillGradientFillToRect?: {
        l: number;
        t: number;
        r: number;
        b: number;
    };
    /** Raw tileRect LTRB values (0..1 fractions, may be negative) from
     *  `a:gradFill/a:tileRect`. Defines the rectangle the gradient tile occupies
     *  before any flip/tiling is applied. */
    fillGradientTileRect?: {
        l: number;
        t: number;
        r: number;
        b: number;
    };
    /** Gradient tile flip mode (`a:gradFill/@flip`).
     *  `none` = no tiling flip (default), `x|y|xy` = mirror in the named axis. */
    fillGradientFlip?: 'none' | 'x' | 'y' | 'xy';
    /** Whether the gradient rotates with the shape (`a:gradFill/@rotWithShape`).
     *  Defaults to true per the schema; preserved for round-trip when the source
     *  authored the attribute explicitly. */
    fillGradientRotWithShape?: boolean;
    /** Whether the linear gradient is scaled to the shape (`a:lin/@scaled`).
     *  Defaults to true per the schema; preserved for round-trip. */
    fillGradientScaled?: boolean;
    fillOpacity?: number;
    strokeColor?: string;
    /**
     * Raw XML colour-choice node preserved from `a:ln/a:solidFill` for
     * round-trip serialisation. See {@link fillColorXml} for the rationale.
     */
    strokeColorXml?: XmlObject;
    /**
     * Typed theme colour reference for the outline, mirroring
     * {@link fillColorRef}: set when {@link strokeColorXml} is a plain
     * `a:schemeClr`, and wins on save.
     */
    strokeColorRef?: PptxThemeColorRef;
    /**
     * Kind of fill painted on the outline (`a:ln` child). Distinguishes a solid
     * outline from a gradient/pattern/none outline so save can emit the correct
     * single line fill instead of collapsing every outline to `a:solidFill`
     * (which, alongside a preserved `a:gradFill`/`a:pattFill`, produces an
     * invalid dual-fill `<a:ln>`).
     */
    strokeFillMode?: 'solid' | 'gradient' | 'pattern' | 'none';
    /** Raw `a:ln/a:gradFill` XML preserved for round-trip when the outline is
     *  gradient-filled. Re-emitted verbatim as the line's single fill on save. */
    strokeGradientXml?: XmlObject;
    /** Raw `a:ln/a:pattFill` XML preserved for round-trip when the outline is
     *  pattern-filled. Re-emitted verbatim as the line's single fill on save. */
    strokePatternXml?: XmlObject;
    /**
     * Structured stops of a gradient outline (`a:ln/a:gradFill/a:gsLst`), in the
     * same shape as {@link fillGradientStops}.
     *
     * The raw XML above round-trips a gradient outline on save, but a renderer
     * cannot paint from it: it needs resolved colours and positions. Without
     * these, every binding fell back to {@link strokeColor} - a single averaged
     * colour - so a two-tone outline painted flat and a fade-to-transparent
     * outline painted fully opaque.
     */
    strokeGradientStops?: ShapeStyle['fillGradientStops'];
    /** Gradient outline angle in OOXML degrees (`a:lin/@ang`), 0 = left to right. */
    strokeGradientAngle?: number;
    /** Gradient outline kind: `linear` (`a:lin`) or `radial` (`a:path`). */
    strokeGradientType?: ShapeStyle['fillGradientType'];
    /** Path-gradient shape for a radial outline (`a:path/@path`). */
    strokeGradientPathType?: ShapeStyle['fillGradientPathType'];
    /** Preset name of a pattern outline (`a:ln/a:pattFill/@prst`). */
    strokePatternPreset?: string;
    /** Background colour of a pattern outline (`a:ln/a:pattFill/a:bgClr`). */
    strokePatternBackgroundColor?: string;
    strokeWidth?: number;
    strokeOpacity?: number;
    strokeDash?: StrokeDashType;
    /** Line join style (`a:ln/@join`): round, bevel, or miter. */
    lineJoin?: 'round' | 'bevel' | 'miter';
    /** Miter limit (`a:miter/@lim`) in EMU-percent units (default 800000 = 8.0). Only meaningful when lineJoin is 'miter'. */
    miterLimit?: number;
    /** Line cap style (`a:ln/@cap`): flat, rnd, or sq. */
    lineCap?: 'flat' | 'rnd' | 'sq';
    /** Compound line type (`a:ln/@cmpd`). */
    compoundLine?: 'sng' | 'dbl' | 'thickThin' | 'thinThick' | 'tri';
    /** Pen line alignment (`a:ln/@algn`): `ctr` (centre, default) or `in` (inside). */
    lineAlignment?: 'ctr' | 'in';
    shadowColor?: string;
    /** Preserved source `a:effectLst`, including unknown effects and extensions. */
    effectListXml?: XmlObject;
    /** Original outer-shadow node used for lossless surgical updates. */
    outerShadowXml?: XmlObject;
    /** Resolved source shadow colour used to detect colour edits. */
    outerShadowOriginalColor?: string;
    /** Source shadow opacity used to detect alpha edits. */
    outerShadowOriginalOpacity?: number;
    shadowBlur?: number;
    shadowOffsetX?: number;
    shadowOffsetY?: number;
    shadowOpacity?: number;
    /** Preset shadow name from `a:prstShdw/@prst` (e.g. "shdw1"..."shdw20"). */
    presetShadowName?: string;
    /** Shadow angle in degrees (0-360). Parsed from `@_dir` (60000ths of a degree). */
    shadowAngle?: number;
    /** Shadow distance in pixels. Parsed from `@_dist` (EMUs). */
    shadowDistance?: number;
    /** Whether shadow rotates with shape. Parsed from `@_rotWithShape`. */
    shadowRotateWithShape?: boolean;
    /** Outer-shadow horizontal scaling (`a:outerShdw/@sx`) in 1000ths of a percent (default 100000 = 100%). */
    shadowScaleX?: number;
    /** Outer-shadow vertical scaling (`a:outerShdw/@sy`). */
    shadowScaleY?: number;
    /** Outer-shadow horizontal skew (`a:outerShdw/@kx`) in 60000ths of a degree. */
    shadowSkewX?: number;
    /** Outer-shadow vertical skew (`a:outerShdw/@ky`). */
    shadowSkewY?: number;
    /** Outer-shadow alignment (`a:outerShdw/@algn`). */
    shadowAlignment?: 'tl' | 't' | 'tr' | 'l' | 'ctr' | 'r' | 'bl' | 'b' | 'br';
    /** Inner-shadow rotateWithShape (`a:innerShdw/@rotWithShape`). */
    innerShadowRotateWithShape?: boolean;
    /** Reflection fade direction (`a:reflection/@fadeDir`) in 60000ths of a degree. */
    reflectionFadeDirection?: number;
    /** Reflection horizontal scaling (`a:reflection/@sx`). */
    reflectionScaleX?: number;
    /** Reflection vertical scaling (`a:reflection/@sy`). */
    reflectionScaleY?: number;
    /** Reflection horizontal skew (`a:reflection/@kx`). */
    reflectionSkewX?: number;
    /** Reflection vertical skew (`a:reflection/@ky`). */
    reflectionSkewY?: number;
    /** Reflection alignment (`a:reflection/@algn`). */
    reflectionAlignment?: 'tl' | 't' | 'tr' | 'l' | 'ctr' | 'r' | 'bl' | 'b' | 'br';
    /** Reflection rotateWithShape (`a:reflection/@rotWithShape`). */
    reflectionRotateWithShape?: boolean;
    /** Reflection start position (`a:reflection/@stPos`) as 0-1 fraction. */
    reflectionStartPosition?: number;
    /** Multiple shadow layers (for advanced effects). */
    shadows?: ShadowEffect[];
    glowColor?: string;
    /** Original glow node used for lossless surgical updates. */
    glowXml?: XmlObject;
    /** Resolved source glow colour used to detect colour edits. */
    glowOriginalColor?: string;
    /** Source glow opacity used to detect alpha edits. */
    glowOriginalOpacity?: number;
    glowRadius?: number;
    glowOpacity?: number;
    softEdgeRadius?: number;
    /** Inner shadow colour (`a:innerShdw`). */
    innerShadowColor?: string;
    /** Original inner-shadow node used for lossless surgical updates. */
    innerShadowXml?: XmlObject;
    /** Resolved source inner-shadow colour used to detect colour edits. */
    innerShadowOriginalColor?: string;
    /** Source inner-shadow opacity used to detect alpha edits. */
    innerShadowOriginalOpacity?: number;
    /** Inner shadow opacity (0-1). */
    innerShadowOpacity?: number;
    /** Inner shadow blur radius in px. */
    innerShadowBlur?: number;
    /** Inner shadow horizontal offset in px. */
    innerShadowOffsetX?: number;
    /** Inner shadow vertical offset in px. */
    innerShadowOffsetY?: number;
    /** Original soft-edge node, including vendor attributes and extensions. */
    softEdgeXml?: XmlObject;
    /** Reflection effect — distance from shape bottom in px. */
    reflectionBlurRadius?: number;
    /** Original reflection node, including vendor attributes and extensions. */
    reflectionXml?: XmlObject;
    /** Reflection start opacity (0-1). */
    reflectionStartOpacity?: number;
    /** Reflection end opacity (0-1). */
    reflectionEndOpacity?: number;
    /** Reflection end position (0-1 fraction of shape height). */
    reflectionEndPosition?: number;
    /** Reflection direction in degrees. */
    reflectionDirection?: number;
    /** Reflection rotation in degrees (`a:reflection/@rot` in 60000ths). */
    reflectionRotation?: number;
    /** Reflection distance in px. */
    reflectionDistance?: number;
    /** Standalone blur effect radius in px (`a:effectLst > a:blur`). */
    blurRadius?: number;
    /** Whether the blur effect grows the bounds of the shape (`a:blur/@grow`). */
    blurGrow?: boolean;
    connectorStartArrow?: ConnectorArrowType;
    /** Start arrow width size ('sm' | 'med' | 'lg'). */
    connectorStartArrowWidth?: 'sm' | 'med' | 'lg';
    /** Start arrow length size ('sm' | 'med' | 'lg'). */
    connectorStartArrowLength?: 'sm' | 'med' | 'lg';
    connectorEndArrow?: ConnectorArrowType;
    /** End arrow width size ('sm' | 'med' | 'lg'). */
    connectorEndArrowWidth?: 'sm' | 'med' | 'lg';
    /** End arrow length size ('sm' | 'med' | 'lg'). */
    connectorEndArrowLength?: 'sm' | 'med' | 'lg';
    /** Connection point for the start of a connector. */
    connectorStartConnection?: ConnectorConnectionPoint;
    /** Connection point for the end of a connector. */
    connectorEndConnection?: ConnectorConnectionPoint;
    /** Custom dash pattern, measured relative to line width in thousandths of one percent. */
    customDashSegments?: PptxCustomDashSegment[];
    /** Original `a:ds` payloads retained by index for lossless edits. */
    customDashSegmentXml?: XmlObject[];
    /** Original `a:custDash` payload retained for lossless edits. */
    customDashXml?: XmlObject;
    /** 3D scene/camera settings from `a:scene3d`. */
    scene3d?: Pptx3DScene;
    /** 3D shape extrusion/bevel from `a:sp3d`. */
    shape3d?: Pptx3DShape;
    /** Line-level shadow colour from `a:ln/a:effectLst/a:outerShdw`. */
    lineShadowColor?: string;
    /** Line-level shadow opacity (0-1). */
    lineShadowOpacity?: number;
    /** Line-level shadow blur radius in px. */
    lineShadowBlur?: number;
    /** Line-level shadow horizontal offset in px. */
    lineShadowOffsetX?: number;
    /** Line-level shadow vertical offset in px. */
    lineShadowOffsetY?: number;
    /** Line-level glow colour from `a:ln/a:effectLst/a:glow`. */
    lineGlowColor?: string;
    /** Line-level glow radius in px. */
    lineGlowRadius?: number;
    /** Line-level glow opacity (0-1). */
    lineGlowOpacity?: number;
    /** Raw `a:effectDag` XML node preserved for round-trip serialisation. */
    effectDagXml?: XmlObject;
    /**
     * Typed effect graph parsed from {@link ShapeStyle.effectDagXml}. The four
     * structural container nodes (`a:cont`, `a:blend`, `a:xfrmEffect`,
     * `a:relOff`) are fully typed; any other leaf effect (e.g. `a:outerShdw`,
     * `a:glow`, `a:alphaInv`) is captured as
     * {@link import('./effect-dag').EffectDagRawLeaf} so we never have to
     * recurse into the full effect taxonomy.
     */
    effectDagTree?: EffectDagContainer;
    /** Grayscale flag from effectDag `a:grayscl`. */
    dagGrayscale?: boolean;
    /** Bi-level threshold (0-100) from effectDag `a:biLevel`. */
    dagBiLevel?: number;
    /** Brightness adjustment (-100 to 100) from effectDag `a:lum/@bright`. */
    dagLumBrightness?: number;
    /** Contrast adjustment (-100 to 100) from effectDag `a:lum/@contrast`. */
    dagLumContrast?: number;
    /** Hue rotation in degrees (0-360) from effectDag `a:hsl/@hue`. */
    dagHslHue?: number;
    /** Saturation adjustment from effectDag `a:hsl/@sat`. */
    dagHslSaturation?: number;
    /** Luminance adjustment from effectDag `a:hsl/@lum`. */
    dagHslLuminance?: number;
    /** Alpha modulation fixed (0-100) from effectDag `a:alphaModFix`. */
    dagAlphaModFix?: number;
    /** Tint hue in degrees from effectDag `a:tint/@hue`. */
    dagTintHue?: number;
    /** Tint amount (0-100) from effectDag `a:tint/@amt`. */
    dagTintAmount?: number;
    /** Duotone colour pair from effectDag `a:duotone`. */
    dagDuotone?: {
        color1: string;
        color2: string;
    };
    /** Fill overlay blend mode from effectDag `a:fillOverlay/@blend`. */
    dagFillOverlayBlend?: 'over' | 'mult' | 'screen' | 'darken' | 'lighten';
    /**
     * Fill overlay tint colour (hex `#RRGGBB`) from effectDag `a:fillOverlay`'s
     * `a:solidFill`/`a:gradFill`. Painted as a blended overlay layer over the
     * element; the blend mode comes from {@link dagFillOverlayBlend}.
     */
    dagFillOverlayColor?: string;
    /** Fill overlay tint opacity (0-1), from the overlay fill colour's alpha. */
    dagFillOverlayOpacity?: number;
    /** Fill overlay blend mode from a direct `a:effectLst/a:fillOverlay/@blend`. */
    shapeFillOverlayBlend?: 'over' | 'mult' | 'screen' | 'darken' | 'lighten';
    /**
     * Fill overlay tint colour (hex `#RRGGBB`) from a direct
     * `a:effectLst/a:fillOverlay`'s `a:solidFill`/`a:gradFill`.
     */
    shapeFillOverlayColor?: string;
    /** Fill overlay tint opacity (0-1), from the overlay fill colour's alpha. */
    shapeFillOverlayOpacity?: number;
    /** Original source `a:fillOverlay` node, preserved for lossless surgical updates. */
    fillOverlayXml?: XmlObject;
    /** Resolved source fill-overlay colour used to detect colour edits. */
    shapeFillOverlayOriginalColor?: string;
    /** Source fill-overlay opacity used to detect alpha edits. */
    shapeFillOverlayOriginalOpacity?: number;
    /** `<a:lnRef @idx>` — 1-based index into the theme's lnStyleLst. */
    lnRefIdx?: number;
    /** Raw XML colour child of `<a:lnRef>` (e.g. `<a:schemeClr>` with transforms). */
    lnRefColorXml?: XmlObject;
    /** `<a:fillRef @idx>` — 1-based index into fillStyleLst (1-3) or bgFillStyleLst (1001-1003). */
    fillRefIdx?: number;
    /** Raw XML colour child of `<a:fillRef>`. */
    fillRefColorXml?: XmlObject;
    /** `<a:effectRef @idx>` — 1-based index into the theme's effectStyleLst. */
    effectRefIdx?: number;
    /** Raw XML colour child of `<a:effectRef>`. */
    effectRefColorXml?: XmlObject;
    /** `<a:fontRef @idx>` — typically `major`, `minor`, or `none`. */
    fontRefIdx?: string;
    /** Raw XML colour child of `<a:fontRef>`. */
    fontRefColorXml?: XmlObject;
    /**
     * The fill `<a:fillRef>` resolved to, recorded ONLY when the shape's own
     * `spPr` authored no fill at all, so the reference is what paints it.
     *
     * Its absence therefore means "the fill is the shape's own", and its
     * presence plus an unchanged flat fill means "still purely inherited": see
     * `authored-shape-style.ts`, the shape-scope twin of `TextStyle`'s
     * `inheritedRunStyle`.
     */
    inheritedFillStyle?: ShapeStyle;
    /**
     * The outline `<a:lnRef>` resolved to, recorded before `spPr/a:ln` was
     * layered on top. A property that still equals this baseline was never
     * authored on the shape and must not be written back as if it were.
     */
    inheritedLineStyle?: ShapeStyle;
    /**
     * The shadow/glow/reflection/soft-edge/3D properties `<a:effectRef>`
     * resolved from the theme's `effectStyleLst`, recorded ONLY for the
     * properties the shape had not already authored itself. A shape whose
     * effects still match this baseline was never given its own effects and
     * must not have them written back as a literal `spPr/a:effectLst`; see
     * `authored-shape-style.ts`'s `effectIsPurelyStyleMatrix`.
     */
    inheritedEffectStyle?: ShapeStyle;
    /**
     * Set by a style-matrix pick (the Shape Styles gallery): the shape's own
     * `spPr` fill, outline and effects were replaced by `<p:style>`, so the
     * writer clears whatever the retained `spPr` still authored before it
     * writes the (now reference-owned) style. Never parsed; editor state only.
     */
    styleMatrixReset?: boolean;
}

export declare interface SheetDismissDrag {
    /** Current downward drag offset in px (0 when not dragging). */
    dragY: Ref<number>;
    /** True while a pointer drag is in progress (suppresses the snap-back transition). */
    dragging: Ref<boolean>;
    onPointerDown: (e: PointerEvent) => void;
    onPointerMove: (e: PointerEvent) => void;
    onPointerUp: (e: PointerEvent) => void;
}

/**
 * The full catalog of shortcuts, grouped for the help overlay. The `combo`
 * strings use `Mod` as a platform-neutral Ctrl/Cmd token (rendered per-platform
 * by `ShortcutPanel.vue`). This is the single source of truth for the help UI.
 */
export declare const SHORTCUT_CATALOG: readonly ShortcutDefinition[];

/** i18n keys for each group's label, in display order. */
export declare const SHORTCUT_GROUP_LABEL_KEYS: Record<ShortcutGroup, string>;

/**
 * The set of action identifiers the registry can dispatch: an alias of the
 * shared keymap's own action union, not a hand-copied one, so a new shared
 * action can never silently fall through the dispatcher.
 */
export declare type ShortcutActionName = EditorKeyActionName;

/**
 * Action callbacks the registry dispatches to. All are optional; a missing
 * callback simply means the corresponding shortcut is a no-op (but it is still
 * matched/suppressed, so the browser default is still prevented).
 */
export declare interface ShortcutActions {
    /** Undo the last edit (Ctrl/Cmd+Z). */
    undo?: () => void;
    /** Redo (Ctrl/Cmd+Shift+Z or Ctrl/Cmd+Y). */
    redo?: () => void;
    /** Copy the selection (Ctrl/Cmd+C). */
    copy?: () => void;
    /** Cut the selection (Ctrl/Cmd+X). */
    cut?: () => void;
    /** Paste (Ctrl/Cmd+V). */
    paste?: () => void;
    /** Duplicate the selection (Ctrl/Cmd+D). */
    duplicate?: () => void;
    /** Delete the selection (Delete / Backspace). */
    delete?: () => void;
    /** Select all elements on the active slide (Ctrl/Cmd+A). */
    selectAll?: () => void;
    /** Group the selection into one group element (Ctrl/Cmd+G). */
    group?: () => void;
    /** Ungroup the selected group (Ctrl/Cmd+Shift+G). */
    ungroup?: () => void;
    /** Show or hide the keyboard-shortcut reference ("?"). */
    toggleShortcuts?: () => void;
    /** Nudge the selection by (dx, dy) pixels (Arrow keys / Shift+Arrow). */
    nudge?: (dx: number, dy: number) => void;
    /** Navigate to the previous slide (ArrowLeft, no selection). */
    prevSlide?: () => void;
    /** Navigate to the next slide (ArrowRight, no selection). */
    nextSlide?: () => void;
    /** Escape: clear selection / close menus / cancel inline edit. */
    escape?: () => void;
    /** Open or close the find bar (Ctrl/Cmd+F). */
    find?: () => void;
    /** Open Find & Replace (Ctrl/Cmd+H). */
    findReplace?: () => void;
    /** Left-align the current paragraph (Ctrl/Cmd+L). */
    alignLeft?: () => void;
    /** Centre-align the current paragraph (Ctrl/Cmd+E). */
    alignCenter?: () => void;
    /** Right-align the current paragraph (Ctrl/Cmd+R). */
    alignRight?: () => void;
    /** Justify the current paragraph (Ctrl/Cmd+J). */
    alignJustify?: () => void;
    /** Step the font size up PowerPoint's size ladder (Ctrl/Cmd+Shift+> or +]). */
    increaseFontSize?: () => void;
    /** Step the font size down PowerPoint's size ladder (Ctrl/Cmd+Shift+< or +[). */
    decreaseFontSize?: () => void;
    /** Copy the selection's formatting (Ctrl/Cmd+Shift+C). */
    copyFormat?: () => void;
    /** Apply the copied formatting to the selection (Ctrl/Cmd+Shift+V). */
    pasteFormat?: () => void;
    /** Insert a new slide (Ctrl/Cmd+M). */
    newSlide?: () => void;
    /** Open the hyperlink dialog (Ctrl/Cmd+K). */
    hyperlink?: () => void;
    /** Clear direct character formatting on the selection (Ctrl/Cmd+Space). */
    clearFormatting?: () => void;
    /** Select the next element on the slide (Tab). */
    cycleSelectionNext?: () => void;
    /** Select the previous element on the slide (Shift+Tab). */
    cycleSelectionPrev?: () => void;
    /** Open the Paste Special dialog (Ctrl/Cmd+Alt+V). */
    pasteSpecial?: () => void;
}

/** The catalog grouped by `group`, in `SHORTCUT_GROUP_LABEL_KEYS` order. */
export declare interface ShortcutCatalogGroup {
    group: ShortcutGroup;
    labelKey: string;
    shortcuts: ShortcutDefinition[];
}

/** A single entry in the shortcut catalog (drives the help UI). */
export declare interface ShortcutDefinition {
    /** Stable identifier (also the action name where 1:1). */
    id: string;
    /**
     * Human-readable, platform-neutral key combo (e.g. `'Mod+Z'`, `'Mod+Shift+Z'`,
     * `'Delete'`, `'ArrowUp'`). `Mod` renders as ⌘ on macOS, Ctrl elsewhere.
     */
    combo: string;
    /** Logical group for the help overlay. */
    group: ShortcutGroup;
    /** i18n key for the help-panel description. */
    descriptionKey: string;
}

/**
 * The keyboard-shortcut help catalog: data for `ShortcutPanel.vue`.
 *
 * Split out of `useKeyboardShortcuts.ts` to keep that file under this repo's
 * file-size limit; the catalog is presentation data for the "?" help overlay,
 * not dispatch logic, so it stands on its own.
 *
 * @module composables/shortcut-catalog
 */
/** Logical grouping for the help overlay. */
export declare type ShortcutGroup = 'history' | 'clipboard' | 'editing' | 'navigation' | 'general';

/** Resolved guard state: the plain (de-reffed) snapshot the matcher reads. */
export declare interface ShortcutGuardState {
    canEdit: boolean;
    canPaste?: boolean;
    isPresenting: boolean;
    hasSelection: boolean;
    inlineEditingElementId: string | null;
    tableEditorIsEditing: boolean;
    activeTool: string;
    isTextInput: boolean;
    /** The event came from a focusable chrome control (Tab stays focus navigation). */
    isControl?: boolean;
}

/** X.509 certificate information extracted from a signature. */
declare interface SignatureCertificateInfo {
    /** Base64-encoded DER certificate data. */
    certificateBase64: string;
    /** Issuer distinguished name (CN, O, etc.) if parseable. */
    issuer?: string;
    /** Subject distinguished name (CN, O, etc.) if parseable. */
    subject?: string;
    /** Certificate serial number as hex string. */
    serialNumber?: string;
    /** Not-before validity date (ISO string). */
    validFrom?: string;
    /** Not-after validity date (ISO string). */
    validTo?: string;
}

/** A single ds:Reference in the SignedInfo. */
declare interface SignatureReference {
    /** The URI identifying the signed part. */
    uri: string;
    /** The digest method algorithm. */
    digestMethod?: string;
    /** Base64-encoded digest value. */
    digestValue?: string;
}

/** Status of a digital signature. */
declare type SignatureStatus = 'valid' | 'invalid' | 'expired' | 'unknownCA' | 'unverified';

/**
 * The full slide-transition `@keyframes` block: the classic set plus the
 * faithful Office 2010 (`p14`) keyframes, so both the classic and exotic / 3-D
 * transitions animate wherever this single string is injected.
 */
export declare const SLIDE_TRANSITION_KEYFRAMES: string;

/**
 * Alias of {@link SLIDE_TRANSITION_KEYFRAMES} under the `_CSS` name the Vue
 * binding historically exported.
 */
export declare const SLIDE_TRANSITION_KEYFRAMES_CSS: string;

/** Annotations grouped by slide index. */
export declare type SlideAnnotationMap = Map<number, AnnotationStroke[]>;

/**
 * Fluent builder for a single slide.
 *
 * @example
 * ```ts
 * const slide = new SlideBuilder(1)
 *   .addText("Hello World", { fontSize: 36, bold: true, x: 100, y: 50 })
 *   .addShape("roundRect", { fill: { type: "solid", color: "#4472C4" } })
 *   .setNotes("Remember to mention key points")
 *   .setBackground({ type: "solid", color: "#F5F5F5" })
 *   .build();
 * ```
 */
declare class SlideBuilder {
    private readonly slide;
    /**
     * @param slideNumber - 1-based slide number.
     * @param layoutPath - Optional layout archive path.
     * @param layoutName - Optional layout display name.
     */
    constructor(slideNumber: number, layoutPath?: string, layoutName?: string);
    /** Add a text box to the slide. */
    addText(text: string | TextSegmentInput[], options?: TextOptions): this;
    /** Add a shape to the slide. */
    addShape(shapeType: string, options?: ShapeOptions): this;
    /** Add a connector (line) to the slide. */
    addConnector(options?: ConnectorOptions): this;
    /** Add an image to the slide. */
    addImage(source: string, options?: ImageOptions): this;
    /** Add a table to the slide. */
    addTable(input: TableInput, options?: TableOptions): this;
    /** Add a chart to the slide. */
    addChart(chartType: PptxChartType, input: ChartInput, options?: ChartOptions): this;
    /** Add a media element (video or audio) to the slide. */
    addMedia(mediaType: 'video' | 'audio', source: string, options?: MediaOptions): this;
    /** Add a group of elements to the slide. */
    addGroup(children: PptxElement[], options?: GroupOptions): this;
    /** Add a pre-built element directly. */
    addElement(element: PptxElement): this;
    /** Set slide background. */
    setBackground(bg: BackgroundInput): this;
    /** Set slide transition. */
    setTransition(input: TransitionInput): this;
    /** Add an animation to an element on this slide. */
    addAnimation(elementId: string, input: AnimationInput): this;
    /** Set speaker notes. */
    setNotes(text: string): this;
    /** Mark the slide as hidden. */
    setHidden(hidden: boolean): this;
    /** Assign the slide to a section. */
    setSection(name: string, id?: string): this;
    /**
     * Add a freeform shape from SVG path data.
     *
     * Creates a custom-geometry shape element using the provided SVG path
     * string and appends it to the slide's element list.
     *
     * @param pathData - An SVG path data string (e.g. `"M 0 0 L 100 50 L 50 100 Z"`).
     * @param options - Optional position, styling, and size overrides.
     * @returns The builder instance for chaining.
     *
     * @example
     * ```ts
     * new SlideBuilder(1)
     *   .addFreeform("M 0 0 C 33 0 66 100 100 100", {
     *     stroke: { color: "#FF0000", width: 2 },
     *   })
     *   .build();
     * ```
     */
    addFreeform(pathData: string, options?: ShapeOptions): this;
    /**
     * Add a pre-built element from any element builder (calls `.build()` for you).
     *
     * Accepts any object with a `build()` method that returns a {@link PptxElement},
     * such as {@link TextBuilder}, {@link ShapeBuilder}, {@link ImageBuilder}, etc.
     *
     * @param builder - An element builder with a `.build()` method.
     * @returns The builder instance for chaining.
     *
     * @example
     * ```ts
     * const title = TextBuilder.create("Hello").fontSize(36).bold();
     * new SlideBuilder(1).addBuilderElement(title).build();
     * ```
     */
    addBuilderElement(builder: {
        build(): PptxElement;
    }): this;
    /**
     * Remove an element by its ID.
     *
     * Filters out the element with the given ID from the slide's element list.
     * If no element matches, the slide is left unchanged.
     *
     * @param elementId - The unique ID of the element to remove.
     * @returns The builder instance for chaining.
     *
     * @example
     * ```ts
     * const slide = new SlideBuilder(1)
     *   .addText("temp", { x: 0, y: 0 })
     *   .removeElement("txt_abc123_1")
     *   .build();
     * ```
     */
    removeElement(elementId: string): this;
    /**
     * Get the current list of elements on this slide.
     *
     * Returns a readonly view of the elements array. Useful for inspecting
     * what has been added so far during the build process.
     *
     * @returns A readonly array of the slide's current elements.
     *
     * @example
     * ```ts
     * const builder = new SlideBuilder(1).addText("Hi");
     * console.log(builder.getElements().length); // 1
     * ```
     */
    getElements(): readonly PptxElement[];
    /**
     * Get the number of elements on this slide.
     *
     * @returns The count of elements currently added to the slide.
     *
     * @example
     * ```ts
     * const builder = new SlideBuilder(1)
     *   .addText("A").addText("B");
     * console.log(builder.elementCount); // 2
     * ```
     */
    get elementCount(): number;
    /**
     * Get the last added element (useful for getting its ID for animations).
     *
     * Returns `undefined` if the slide has no elements yet.
     *
     * @returns The most recently added element, or `undefined`.
     *
     * @example
     * ```ts
     * const builder = new SlideBuilder(1).addShape("rect");
     * const shape = builder.getLastElement();
     * if (shape) {
     *   builder.addAnimation(shape.id, { preset: "fadeIn" });
     * }
     * ```
     */
    getLastElement(): PptxElement | undefined;
    /**
     * Set the slide name/title for organizational purposes.
     *
     * Stores an arbitrary name string on the slide object. This is useful
     * for labeling slides in tooling or custom workflows.
     *
     * @param name - The display name to assign to the slide.
     * @returns The builder instance for chaining.
     *
     * @example
     * ```ts
     * new SlideBuilder(1)
     *   .setName("Introduction")
     *   .addText("Welcome!")
     *   .build();
     * ```
     */
    setName(name: string): this;
    /** Return the built {@link PptxSlide}. */
    build(): PptxSlide;
}

declare interface SlideDiff {
    status: SlideDiffStatus;
    /** Index in the base (current) presentation, or -1 for added slides. */
    baseIndex: number;
    /** Index in the compare (other) presentation, or -1 for removed slides. */
    compareIndex: number;
    /** The base slide data (undefined for added slides). */
    baseSlide?: PptxSlide;
    /** The compare slide data (undefined for removed slides). */
    compareSlide?: PptxSlide;
    /** Per-element changes when status is `changed`. */
    changes: ElementChange[];
}

declare type SlideDiffStatus = 'added' | 'removed' | 'changed' | 'unchanged';

declare interface SlideSizeEmu {
    widthEmu: number;
    heightEmu: number;
    /** ST_SlideSizeType token, or `''` for a size with no preset. */
    type: string;
}

/** Discriminated id for every built-in slide template. */
declare type SlideTemplateId = 'title' | 'titleAndContent' | 'sectionHeader' | 'agenda' | 'twoContent' | 'comparison' | 'quote' | 'timeline' | 'keyMetrics' | 'titleOnly' | 'blank' | 'closing';

/** Resolved CSS `animation` shorthands for the two transition layers. */
export declare interface SlideTransitionAnimations {
    /** CSS `animation` value for the outgoing (old) slide layer, or `'none'`. */
    outgoing: string;
    /** CSS `animation` value for the incoming (new) slide layer, or `'none'`. */
    incoming: string;
    /** Whether the outgoing layer should render above the incoming layer. */
    outgoingOnTop: boolean;
}

/** A single captured version: a deep-cloned slide array + metadata. */
export declare interface SlideVersion {
    /** Stable, collision-resistant identifier. */
    id: string;
    /** Human-readable label supplied at capture time. */
    label: string;
    /** Capture time in epoch milliseconds, supplied by the caller. */
    timestamp: number;
    /** Number of slides in the snapshot (cheap summary for the UI). */
    slideCount: number;
    /** The deep-cloned slide snapshot. */
    slides: PptxSlide[];
}

/**
 * Static option lists and layout-label helper for the SmartArt inspector.
 *
 * Extracted from `useSmartArtEditing` so that composable stays within the
 * per-file line budget. Re-exported from the composable barrel for callers that
 * import them from there.
 *
 * @module smartart-editing-constants
 */
export declare const SMARTART_COLOR_SCHEMES: readonly SmartArtColorScheme[];

export declare const SMARTART_STYLE_OPTIONS: readonly SmartArtStyle[];

/**
 * SmartArt colour scheme presets.
 *
 * @example
 * ```ts
 * const scheme: SmartArtColorScheme = "colorful1";
 * // => "colorful1" — one of: "colorful1" | "colorful2" | "colorful3" | "monochromatic1" | "monochromatic2"
 * ```
 */
declare type SmartArtColorScheme = 'colorful1' | 'colorful2' | 'colorful3' | 'monochromatic1' | 'monochromatic2';

export declare interface SmartArtEditingApi {
    nodes: ComputedRef<readonly PptxSmartArtNode[]>;
    rows: ComputedRef<readonly SmartArtNodeRow[]>;
    colorScheme: ComputedRef<SmartArtColorScheme>;
    style: ComputedRef<SmartArtStyle>;
    currentLayout: ComputedRef<SmartArtLayoutType>;
    /** Number of top-level (parent-less) nodes. */
    topLevelCount: ComputedRef<number>;
    /** Whether the layout's max allows another top-level node. */
    canAdd: ComputedRef<boolean>;
    /** Human bounds hint for the active layout, or `undefined`. */
    boundsHint: ComputedRef<string | undefined>;
    /** Count of non-tree connections (read-only awareness note). */
    extraConnections: ComputedRef<number>;
    /** Id of the node input to focus after a structural edit (via input ref + nextTick). */
    pendingFocusId: Ref<string | null>;
    /** Register / unregister a node's `<input>` element for focus management. */
    setInputEl: (nodeId: string, el: HTMLInputElement | null) => void;
    updateNodeText: (nodeId: string, text: string) => void;
    setNodeStyle: (nodeId: string, style: Partial<PptxSmartArtNodeStyle>) => void;
    addItem: () => void;
    addSubItem: (parentId: string) => void;
    removeNode: (nodeId: string) => void;
    promote: (nodeId: string) => void;
    demote: (nodeId: string) => void;
    moveUp: (nodeId: string) => void;
    moveDown: (nodeId: string) => void;
    /** Keyboard handler for a node input (Enter/Backspace/Delete/Tab). */
    onNodeKeyDown: (event: KeyboardEvent, nodeId: string) => void;
    setColorScheme: (scheme: SmartArtColorScheme) => void;
    setStyle: (style: SmartArtStyle) => void;
    switchLayout: (layout: SmartArtLayoutType) => void;
}

/**
 * Focus management for the SmartArt text-pane node inputs.
 *
 * The SFC registers each node's `<input>` element via {@link SmartArtFocusApi.setInputEl};
 * after a structural edit (add / remove / move / promote / demote) the composable
 * sets `pendingFocusId` and focuses the matching input on the next tick. This is
 * the Vue equivalent of the React `pendingFocusId` ref + `useEffect` pattern.
 *
 * @module useSmartArtFocus
 */
export declare interface SmartArtFocusApi {
    /** Id of the node input that should receive focus after the next render. */
    pendingFocusId: Ref<string | null>;
    /** Register / unregister a node's `<input>` element. */
    setInputEl: (nodeId: string, el: HTMLInputElement | null) => void;
    /** Request focus for `nodeId` (no-op when undefined). */
    focusNode: (nodeId: string | undefined) => void;
}

/** Reactive inline-edit state shared with the renderer template. */
export declare interface SmartArtInlineEditState {
    editingNodeId: Ref<string | null>;
    draft: Ref<string>;
    rect: Ref<InlineEditRect | null>;
    isEditing: ComputedRef<boolean>;
    begin: (nodeId: string, text: string, rect: InlineEditRect) => void;
    cancel: () => void;
}

/**
 * Named SmartArt layout presets for creation (subset of PowerPoint layouts).
 *
 * @example
 * ```ts
 * const layout: SmartArtLayout = "hierarchy";
 * // => "hierarchy" — one of: "basicBlockList" | "alternatingHexagons" | "hierarchy" | …
 * ```
 */
declare type SmartArtLayout = 'basicBlockList' | 'alternatingHexagons' | 'basicChevronProcess' | 'basicCycle' | 'basicPie' | 'basicRadial' | 'basicVenn' | 'continuousBlockProcess' | 'convergingRadial' | 'hierarchy' | 'horizontalBulletList' | 'linearVenn' | 'segmentedProcess' | 'stackedList' | 'tableList' | 'trapezoidList' | 'upwardArrow' | 'basicFunnel' | 'basicTarget' | 'interlockingGears' | 'basicTimeline' | 'basicMatrix' | 'basicPyramid' | 'invertedPyramid' | 'bendingProcess' | 'stepDownProcess' | 'alternatingFlow' | 'descendingProcess' | 'pictureAccentList' | 'verticalBlockList' | 'groupedList' | 'pyramidList' | 'horizontalPictureList' | 'accentProcess' | 'verticalChevronList';

/**
 * Translate a SmartArt layout category for display.
 *
 * WHY the `translate` argument: this used to hold a private English map with a
 * title-case fallback (`layout.charAt(0).toUpperCase() + ...`), so an unmapped
 * type rendered its wire token capitalised and no mapped type could ever be
 * translated. React resolves `pptx.smartart.category.<type>` for the same tiles;
 * routing through the shared `SMARTART_LAYOUT_LABEL_KEYS` catalogue makes the
 * two bindings spell every category identically, in every locale.
 *
 * The layout SET is unchanged: callers still iterate core's
 * `SWITCHABLE_LAYOUT_TYPES`, and an unmapped type still falls back to its raw
 * token rather than being hidden.
 */
export declare function smartArtLayoutLabel(layout: SmartArtLayoutType, translate: (key: string) => string): string;

/**
 * Resolved SmartArt layout category.
 *
 * @example
 * ```ts
 * const cat: SmartArtLayoutType = "hierarchy";
 * // => "hierarchy" — one of: "list" | "process" | "cycle" | "hierarchy" | "relationship" | …
 * ```
 */
declare type SmartArtLayoutType = 'list' | 'process' | 'cycle' | 'hierarchy' | 'relationship' | 'matrix' | 'pyramid' | 'funnel' | 'gear' | 'target' | 'timeline' | 'venn' | 'chevron' | 'bending' | 'unknown';

/**
 * Manual layout override for a `type="pres"` presentation point, read from its
 * `dgm:prSet` attributes. PowerPoint writes these when the user drags, resizes,
 * rotates, or flips a SmartArt node by hand in its own diagram editor; without
 * them the node silently reverts to its algorithmic position whenever there is
 * no cached `dsp:` drawing part to fall back on.
 *
 * Every field is optional: only the attributes actually present on `prSet` are
 * populated. Angle and scale/factor units are already normalised to degrees and
 * plain ratios (a `custScaleX="150000"` becomes `scaleX: 1.5`), so a consumer
 * never has to know the raw `60000ths-of-a-degree` / `100000ths-of-a-percent`
 * XML encodings.
 *
 * @example
 * ```ts
 * const custom: SmartArtNodeCustomLayout = { angle: 15, scaleX: 1.2 };
 * // => a node manually rotated 15 degrees and widened 20% in PowerPoint
 * ```
 */
declare interface SmartArtNodeCustomLayout {
    /** `custAng`: additional rotation in degrees. */
    angle?: number;
    /** `custScaleX`: horizontal scale ratio (1 = no change). */
    scaleX?: number;
    /** `custScaleY`: vertical scale ratio (1 = no change). */
    scaleY?: number;
    /** `custSzX`: horizontal size ratio, layered on top of {@link scaleX}. */
    sizeX?: number;
    /** `custSzY`: vertical size ratio, layered on top of {@link scaleY}. */
    sizeY?: number;
    /** `custFlipHor`: the node was manually mirrored horizontally. */
    flipHorizontal?: boolean;
    /** `custFlipVert`: the node was manually mirrored vertically. */
    flipVertical?: boolean;
    /** `custLinFactX`: manual position nudge along X, as a fraction of the container width. */
    linearFactorX?: number;
    /** `custLinFactY`: manual position nudge along Y, as a fraction of the container height. */
    linearFactorY?: number;
    /**
     * `custLinFactNeighborX`: spacing compensation applied to a NEIGHBOURING
     * node when this one is resized. Parsed for round-trip completeness; not
     * applied by the per-node final transform (it has no effect on this node's
     * own geometry; folding it into a neighbour's geometry would require
     * whole-layout awareness the final transform pass does not have).
     */
    linearFactorNeighborX?: number;
    /** `custLinFactNeighborY`: see {@link linearFactorNeighborX} (Y axis). */
    linearFactorNeighborY?: number;
    /** `custRadScaleRad`: manual radius scale ratio for a radial/cycle node. */
    radialScaleRadius?: number;
    /** `custRadScaleInc`: manual angular-position nudge for a radial/cycle node. */
    radialScaleIncrement?: number;
    /** `custT`: whether `prSet` declares a custom transform is present at all. */
    hasCustomTransform?: boolean;
}

/** A node enriched with display metadata for the text-pane list. */
export declare interface SmartArtNodeRow {
    node: PptxSmartArtNode;
    /** Zero-based position in the flat node list. */
    index: number;
    /** 1-based display number among top-level nodes (0 for child rows). */
    displayIndex: number;
    isChild: boolean;
    /** Disable the move-up control (already first among siblings). */
    moveUpDisabled: boolean;
    /** Disable the move-down control (already last among siblings). */
    moveDownDisabled: boolean;
    /** Disable the remove control (last node, or layout minimum reached). */
    removeDisabled: boolean;
}

/**
 * A SmartArt diagram embedded via a `<p:graphicFrame>`.
 *
 * SmartArt data is extracted from `dgm:dataModel` parts. The editor
 * supports real structural editing (adding, removing and reordering nodes,
 * editing node text, and switching layout presets) with a lossless
 * `ptLst` round-trip. When the file carries PowerPoint's own pre-computed
 * drawing part, that exact layout is used; otherwise an algorithmic layout
 * engine approximates it, so complex custom layouts may not match
 * PowerPoint pixel-for-pixel.
 */
declare interface SmartArtPptxElement extends PptxElementBase {
    type: 'smartArt';
    smartArtData?: PptxSmartArtData;
    /** Accessibility description from `p:nvGraphicFramePr/p:cNvPr/@descr`. */
    altText?: string;
    /** Accessibility title from `p:nvGraphicFramePr/p:cNvPr/@title`. */
    title?: string;
    /** Unrecognised graphicFrame extLst extensions, captured verbatim for round-trip. */
    extensionXml?: PptxGraphicFrameExtension[];
}

/** One colour-transform `styleLbl`'s resolved colour lists. */
declare interface SmartArtRoleColorList {
    fill: string[];
    line: string[];
    /**
     * `txFillClrLst`, when the label declares one (`revTx` -> `tx1`). A text
     * node's colour comes from here; see `smartart-merged-text-label`.
     */
    textFill?: string[];
}

/**
 * SmartArt visual style intensity.
 *
 * @example
 * ```ts
 * const style: SmartArtStyle = "moderate";
 * // => "moderate" — one of: "flat" | "moderate" | "intense"
 * ```
 */
declare type SmartArtStyle = 'flat' | 'moderate' | 'intense';

/** One transient red alignment line drawn while a snap is active. */
declare interface SnapLine {
    axis: 'x' | 'y';
    position: number;
}

/**
 * Stroke dash pattern types for lines and shape outlines.
 *
 * Maps to `a:ln/a:prstDash/@val` in OOXML. Use `"custom"` for
 * user-defined dash/space arrays.
 *
 * @example
 * ```ts
 * const dash: StrokeDashType = "dashDot";
 * // => "dashDot" — one of: solid | dot | dash | lgDash | dashDot | custom | ...
 * ```
 */
declare type StrokeDashType = 'solid' | 'dot' | 'dash' | 'lgDash' | 'dashDot' | 'lgDashDot' | 'lgDashDotDot' | 'sysDot' | 'sysDash' | 'sysDashDot' | 'sysDashDotDot' | 'custom';

declare interface StrokeInput {
    color?: string;
    width?: number;
    dash?: StrokeDashType;
    opacity?: number;
    join?: 'round' | 'bevel' | 'miter';
    cap?: 'flat' | 'rnd' | 'sq';
    /** A theme colour for the outline; see {@link FillInput}'s `themeColorRef`. */
    themeColorRef?: PptxThemeColorRef;
}

/** A single section tile within a PowerPoint Summary Zoom container. */
declare interface SummaryZoomTarget extends PptxImageProperties {
    sectionId: string;
    targetSlideIndex: number;
    x: number;
    y: number;
    width: number;
    height: number;
    title?: string;
    description?: string;
    offsetFactorX?: number;
    offsetFactorY?: number;
    scaleFactorX?: number;
    scaleFactorY?: number;
    /** This tile's own `zmPr/@returnToParent`; see {@link ZoomPptxElement.returnToParent}. */
    returnToParent?: boolean;
    /** This tile's own `zmPr/@transitionDur` in milliseconds; see {@link ZoomPptxElement.transitionDurationMs}. */
    transitionDurationMs?: number;
    rawXml?: XmlObject;
}

/** Shape preset the Insert tab inserts. Mirrors React `SupportedShapeType`. */
declare type SupportedShapeType = 'rect' | 'roundRect' | 'ellipse' | 'triangle' | 'rtTriangle' | 'diamond' | 'cylinder' | 'parallelogram' | 'trapezoid' | 'pentagon' | 'hexagon' | 'octagon' | 'chevron' | 'star5' | 'star6' | 'star8' | 'plus' | 'heart' | 'cloud' | 'sun' | 'moon' | 'pie' | 'plaque' | 'teardrop' | 'line' | 'rtArrow' | 'leftArrow' | 'upArrow' | 'downArrow' | 'connector' | 'freeform';

/** One `\n`-split line of a run's tabbed text. */
declare interface TabbedLineRun {
    pieces: TabbedRunPiece[];
}

/** One tabbed-line piece, ready to spread onto a binding's own span element. */
declare interface TabbedRunPiece {
    text: string;
    /**
     * CSS for the span that wraps `text`: inline-block layout, this run's own
     * decoration repeated, and this piece's own PowerPoint advance-width
     * correction as `letter-spacing` (see `buildTabbedLine`). The piece is
     * nested inside the run's own span, and neither property inherits the way a
     * caller would want: `text-decoration-*` does not inherit into a nested
     * element at all (an ancestor's underline is drawn *through* its
     * descendants, but each descendant still computes `none` of its own), so a
     * caller passes the run's decoration subset (`nestedTextDecorationStyle`) to
     * have it repeated here; `letter-spacing` DOES inherit, which is exactly why
     * this piece sets it explicitly rather than only when non-zero - the run's
     * container span carries its own (wrong, whole-text) correction that would
     * otherwise leak in.
     */
    style: RunStyle;
    /** CSS for the leader-fill span preceding this piece, or `undefined` when there is no gap to fill. */
    leaderStyle?: RunStyle;
    /** Leader glyphs sized to fill `leaderStyle`'s width. Present only alongside `leaderStyle`. */
    leaderText?: string;
    /**
     * `a:rPr/@u="words"` per-word/gap sub-pieces of THIS tab piece's own text
     * (see `splitWordsForUnderline`), present only when the run's underline is
     * `words`. A tab-separated piece is otherwise rendered as a single span
     * (`text` + `style`), which underlines it continuously - correct for a
     * one-word piece, but wrong for a piece like `"Hello World"` between two tab
     * stops, which needs a gap under the space. A binding renders one SIBLING
     * span per entry IN PLACE OF the piece's single `text` span: each entry's
     * `style` is the piece's own `style` (the same inline-block layout and
     * advance-width correction, so the line measures exactly as before), with
     * the underline stripped on a gap entry. They must be siblings, not spans
     * nested inside the piece span: an ancestor's underline is drawn through
     * every inline descendant, so a nested gap could not lose it. `text`/`style`
     * stay the continuous-underline fallback for a binding that does not
     * render this field.
     */
    words?: Array<{
        text: string;
        style: RunStyle;
    }>;
}

/** Table inline-edit state: present while a table cell is being edited. */
declare interface TableCellEditorState {
    elementId: string;
    rowIndex: number;
    columnIndex: number;
}

declare interface TableCellInput {
    text: string;
    style?: Partial<TextStyleInput>;
    fill?: FillInput;
    gridSpan?: number;
    rowSpan?: number;
}

export declare interface TableCellSelectionApi {
    /** The selection restricted to this table element (else `null`). */
    activeSelection: ComputedRef<TableSelectionState | null>;
    /** The multi-cell bounding rect when >= 2 cells are selected. */
    selectionRect: ComputedRef<CellRect | undefined>;
    /** Whether `(row, col)` is the anchor (single) selected cell. */
    isCellSelected: (rowIndex: number, columnIndex: number) => boolean;
    /** Whether `(row, col)` falls inside the multi-cell selection rect. */
    isCellInSelection: (rowIndex: number, columnIndex: number) => boolean;
    /** Apply a click at `(row, col)` (single or Shift+range). */
    selectCell: (rowIndex: number, columnIndex: number, shiftKey: boolean) => void;
    /** Whether a selection context is available (edit-capable viewer). */
    hasContext: boolean;
}

declare interface TableInput {
    rows: TableRowInput[];
    columnWidths?: number[];
    style?: string;
    bandRows?: boolean;
    bandColumns?: boolean;
    firstRow?: boolean;
    lastRow?: boolean;
    firstCol?: boolean;
    lastCol?: boolean;
}

declare interface TableOptions extends Partial<ElementPosition> {}

/**
 * A table embedded via a `<p:graphicFrame>`.
 *
 * @example
 * ```ts
 * const tbl: TablePptxElement = {
 *   type: "table",
 *   id: "tbl_1", x: 50, y: 200, width: 860, height: 300,
 *   tableData: {
 *     rows: [
 *       { cells: [{ text: "Name" }, { text: "Score" }] },
 *       { cells: [{ text: "Alice" }, { text: "95" }] },
 *     ],
 *   },
 * };
 * // => satisfies TablePptxElement
 * ```
 */
declare interface TablePptxElement extends PptxElementBase {
    type: 'table';
    /** Parsed table cell data for editing. */
    tableData?: PptxTableData;
    /**
     * Accessibility description from `p:nvGraphicFramePr/p:cNvPr/@descr`, the
     * same non-visual-properties attribute a picture's alt text comes from.
     */
    altText?: string;
    /** Accessibility title from `p:nvGraphicFramePr/p:cNvPr/@title`. */
    title?: string;
    /**
     * Unrecognised extensions captured from `a:graphicData/a:extLst` so they
     * round-trip losslessly. See {@link PptxGraphicFrameExtension}.
     */
    extensionXml?: PptxGraphicFrameExtension[];
}

declare interface TableRowInput {
    cells: TableCellInput[];
    height?: number;
}

export declare interface TableSelectionContext {
    /** The current selection, or `null` when no cell is selected. */
    selection: Ref<TableSelectionState | null>;
    /** Replace (or clear) the current selection. */
    select: (next: TableSelectionState | null) => void;
    /** Commit new column widths (proportions summing to 1) for a table. */
    resizeColumns: (elementId: string, widths: number[]) => void;
    /** Commit a new pixel height for a single row of a table. */
    resizeRow: (elementId: string, rowIndex: number, height: number) => void;
}

/** Typed injection key for the table selection context. */
export declare const TableSelectionKey: InjectionKey<TableSelectionContext>;

/**
 * Table cell selection + resize context.
 *
 * Mirrors React's `tableEditorState` (`viewer/types-ui.ts`) but, following the
 * Vue viewer's provide/inject convention (see `table-edit` / `table-theme`), the
 * reactive selection is provided once at the viewer root and injected by both
 * `TableRenderer` (writes selection from cell clicks, reads it for the highlight
 * + drives resize) and the inspector `TablePanel` (reads the selected cell to
 * key structural / merge / cell-style edits). Absent in a read-only viewer, in
 * which case tables render without any selection affordance.
 */
export declare interface TableSelectionState {
    /** The table element the selection belongs to. */
    elementId: string;
    /** Anchor cell row (original grid coords). */
    rowIndex: number;
    /** Anchor cell column (original grid coords). */
    columnIndex: number;
    /** Rectangular multi-cell selection (Shift+Click range), row-major. */
    selectedCells?: CellCoord[];
}

/** Tablet breakpoint: below this width (but >= MOBILE) is tablet. */
export declare const TABLET_BREAKPOINT = 1024;

declare type TemplateElementMap = Record<string, PptxElement[]>;

/**
 * 3D text body extrusion/bevel from `a:bodyPr/a:sp3d`.
 *
 * @example
 * ```ts
 * const text3d: Text3DStyle = {
 *   extrusionHeight: 57150,
 *   presetMaterial: "plastic",
 *   bevelTopType: "circle",
 *   bevelTopWidth: 25400,
 *   bevelTopHeight: 25400,
 * };
 * // => satisfies Text3DStyle
 * ```
 */
declare interface Text3DStyle {
    /** Extrusion height (depth) in EMU. */
    extrusionHeight?: number;
    /** Extrusion colour as hex string. */
    extrusionColor?: string;
    /** Preset material, e.g. "matte", "plastic", "metal". */
    presetMaterial?: MaterialPresetType;
    /** Top bevel preset type. */
    bevelTopType?: BevelPresetType;
    /** Top bevel width in EMU. */
    bevelTopWidth?: number;
    /** Top bevel height in EMU. */
    bevelTopHeight?: number;
    /** Bottom bevel preset type. */
    bevelBottomType?: BevelPresetType;
    /** Bottom bevel width in EMU. */
    bevelBottomWidth?: number;
    /** Bottom bevel height in EMU. */
    bevelBottomHeight?: number;
}

/**
 * Ids of flattened nodes that carry text, in order. Used by the drawing-shape
 * path, where each text-bearing shape corresponds positionally to a text-bearing
 * node (decoration shapes such as connectors carry no text and are skipped).
 */
export declare function textNodeIdsInRenderOrder(roots: readonly PptxSmartArtNode[]): string[];

declare interface TextOptions extends Partial<ElementPosition> {
    fontSize?: number;
    fontFamily?: string;
    bold?: boolean;
    italic?: boolean;
    underline?: boolean;
    strikethrough?: boolean;
    color?: string;
    alignment?: 'left' | 'center' | 'right' | 'justify';
    verticalAlignment?: 'top' | 'middle' | 'bottom';
    lineSpacing?: number;
    fill?: FillInput;
    stroke?: StrokeInput;
    shadow?: ShadowInput;
    opacity?: number;
}

/**
 * Rich text style properties for a text run or paragraph.
 *
 * Combines character-level formatting (font, bold, colour …),
 * paragraph-level controls (alignment, spacing, indentation), and
 * body-level properties (autofit, insets, text direction). All
 * fields are optional — unset properties inherit from layout/master
 * placeholders or theme defaults.
 *
 * @remarks
 * Font sizes are stored in **points**. Spatial measurements (insets,
 * margins) are in **pixels** (pre-converted from EMU during parsing).
 *
 * @example
 * ```ts
 * const heading: TextStyle = {
 *   fontFamily: "Montserrat",
 *   fontSize: 36,
 *   bold: true,
 *   color: "#1A1A2E",
 *   align: "center",
 *   lineSpacing: 1.15,
 * };
 *
 * const body: TextStyle = {
 *   fontFamily: "Open Sans",
 *   fontSize: 14,
 *   color: "#444444",
 *   align: "left",
 *   paragraphSpacingAfter: 8,
 * };
 * // => both satisfy the TextStyle interface
 * ```
 */
/** 2D linear transform matrix `[a, b, c, d]` for inherited group orientation. */
declare type TextOrientationMatrix = [number, number, number, number];

declare interface TextPositionCell {
    index: number;
    left?: TextPositionCell;
    right?: TextPositionCell;
}

/**
 * A text box — a plain rectangle containing text, typically with no
 * visible fill or stroke.
 *
 * @example
 * ```ts
 * const title: TextPptxElement = {
 *   type: "text",
 *   id: "txt_1", x: 50, y: 30, width: 800, height: 60,
 *   text: "Welcome",
 *   textStyle: { fontSize: 36, bold: true },
 * };
 * // => satisfies TextPptxElement
 * ```
 */
declare interface TextPptxElement extends PptxElementBase, PptxTextProperties, PptxShapeProperties, PptxNonVisualDescription {
    type: 'text';
}

/**
 * A single text run within a paragraph.
 *
 * A text body is decomposed into an array of `TextSegment` objects,
 * each with its own style. Paragraph breaks are represented as
 * segments with `isParagraphBreak: true`.
 *
 * @example
 * ```ts
 * const segments: TextSegment[] = [
 *   { text: "Bold intro ", style: { bold: true, fontSize: 16 } },
 *   { text: "and normal text.", style: { fontSize: 16 } },
 *   { text: "", style: {}, isParagraphBreak: true },
 *   { text: "Second paragraph.", style: { fontSize: 14 } },
 * ];
 * // => 4 segments: 2 styled runs, 1 paragraph break, 1 normal run
 * ```
 */
declare interface TextSegment {
    text: string;
    style: TextStyle;
    /** When this segment originated from an `a:fld` element, stores the field type (e.g. "slidenum", "datetime"). */
    fieldType?: string;
    /** When this segment originated from an `a:fld` element, stores the field GUID. */
    fieldGuid?: string;
    /**
     * Original attribute name used to author the field GUID — `'uuid'` for the
     * `a:fld/@uuid` form authored by some legacy producers, `'id'` for the
     * canonical `a:fld/@id` form. Preserved so the writer round-trips whichever
     * spelling the source used (PowerPoint accepts both). Defaults to `'id'`
     * on save when undefined.
     */
    fieldGuidAttr?: 'uuid' | 'id';
    /**
     * Raw per-field paragraph properties (`a:fld > a:pPr`). The schema permits
     * `pPr` inside an `a:fld` so the field can carry its own paragraph-level
     * formatting; preserved verbatim on save when present.
     */
    fieldParagraphPropertiesXml?: XmlObject;
    /** Raw OMML XML node for equation segments (from `a14:m` / `m:oMathPara`). */
    equationXml?: Record<string, unknown>;
    /**
     * The ORIGINAL top-level paragraph child that carried this equation,
     * captured verbatim at parse time and keyed by its own tag: `{ 'a14:m':
     * ... }`, `{ 'm:oMathPara': ... }`, `{ 'm:oMath': ... }`, or `{
     * 'mc:AlternateContent': ... }` for an equation authored behind a
     * Choice/Fallback switch. `equationXml` above is the resolved math content
     * used for rendering (unwrapped one level for `a14:m`/`mc:AlternateContent`
     * sources); this field exists solely so the writer can re-emit an UNTOUCHED
     * equation byte-for-byte, Choice and Fallback both, instead of collapsing
     * it to a bare math element PowerPoint's own writer never produces.
     * `undefined` for a freshly inserted or edited equation, which the writer
     * instead reconstructs from `equationXml` (always `{ 'm:oMathPara': ... }`
     * or `{ 'm:oMath': ... }` for those cases). Any code that replaces
     * `equationXml` on an existing segment must drop this field, or the writer
     * would keep re-emitting the equation's OLD XML instead of the edit.
     */
    equationSourceXml?: Record<string, unknown>;
    /**
     * Optional equation number for numbered equations (e.g. "(1)", "(2.3)").
     * When present, the equation is rendered centered with the number right-aligned.
     */
    equationNumber?: string;
    /** Whether this segment represents a paragraph break rather than renderable text. */
    isParagraphBreak?: boolean;
    /**
     * Whether this segment represents a soft line break (`a:br`) rather than
     * a paragraph terminator. Soft line breaks remain inside the same paragraph
     * but force a line wrap and may carry their own run properties.
     *
     * The renderer should treat the segment text as `"\n"` when present.
     */
    isLineBreak?: true;
    /**
     * Raw `a:rPr` XML for an `a:br` (soft line break) segment, captured verbatim
     * during parse so the writer can re-emit attributes/colours/fonts that the
     * typed model doesn't represent. Only meaningful when {@link isLineBreak}
     * is `true`.
     */
    breakRunProperties?: Record<string, unknown>;
    /** Structured bullet info for the first segment of a paragraph. */
    bulletInfo?: BulletInfo;
    /**
     * Outline level for the paragraph this segment starts (`a:p/@lvl`).
     *
     * Only meaningful on the first segment of a paragraph (matching the
     * convention used for {@link bulletInfo}). Stored as the raw OOXML
     * value (0 = top level, 1-8 = nested) and serialised back when non-zero.
     */
    paragraphLevel?: number;
    /**
     * Raw `a:endParaRPr` XML node for the paragraph this segment starts.
     *
     * Captured verbatim on parse so attributes and child colours/fonts that
     * the typed model doesn't represent survive a round-trip. Only meaningful
     * on the first segment of a paragraph.
     */
    endParaRunProperties?: Record<string, unknown>;
    /**
     * Resolved body defaults and optional `a:endParaRPr` of a runless paragraph.
     * Carried on its first segment (or terminator), separately from marker
     * styling. Absent when the source contains an authored run or field.
     */
    paragraphInsertionStyle?: TextStyle;
    /**
     * Per-paragraph properties (alignment, spacing, margins, indent, tab stops,
     * rtl) authored on this paragraph's own `a:pPr` (#69). Only meaningful on
     * the first segment of a paragraph. When present, the writer emits these
     * per paragraph instead of collapsing one shape-level pPr onto every
     * paragraph. Only the paragraph-geometry keys of {@link TextStyle} are
     * populated; unrelated fields fall back to the shape-level style.
     */
    paragraphProperties?: TextStyle;
    /**
     * The paragraph this segment starts authored an EMPTY `<a:pPr/>`. Only
     * meaningful on the first segment of a paragraph. The writer re-emits the
     * empty element when it has no paragraph property of its own to write, so
     * a rewritten slide keeps the markup PowerPoint wrote.
     */
    emptyParagraphPropertiesAuthored?: boolean;
    /**
     * The paragraph this segment starts has no run content and authored no
     * `a:endParaRPr` (a bare `<a:p/>`, possibly with an `a:pPr`). Only
     * meaningful on the first segment of a paragraph. It stops the writer
     * inventing an empty run or an `<a:endParaRPr lang="en-US"/>` stub for a
     * paragraph that still has no content when saved.
     */
    bareParagraph?: boolean;
    /**
     * Phonetic annotation text from `a:ruby > a:rt` (e.g. furigana, pinyin).
     * When present, the renderer should wrap the base text with an HTML `<ruby>` tag.
     */
    rubyText?: string;
    /**
     * Ruby text alignment from `a:rubyPr > @val` attribute.
     * Values: "ctr" (center), "l" (left), "r" (right), "dist" (distribute), "distCat", "distLetter".
     * @default "ctr"
     */
    rubyAlignment?: string;
    /**
     * Ruby text font size as a percentage of the base text font size
     * from `a:rubyPr/@hps` (half-point size) or inferred from rt run font size.
     * Stored in **points** for consistency with `TextStyle.fontSize`.
     */
    rubyFontSize?: number;
    /**
     * Style for the ruby (phonetic) text run, parsed from `a:rt > a:r > a:rPr`.
     * Used by the renderer to apply font family, colour, etc. to the `<rt>` element.
     */
    rubyStyle?: TextStyle;
    /**
     * The parsed `a:rubyPr` node, kept verbatim so its attributes (`hps`,
     * `hpsRaise`, `hpsBaseText`, `lid`, ...) round-trip exactly; only an
     * edited {@link rubyAlignment} is written over it on save.
     */
    rubyPropertiesXml?: XmlObject;
    /**
     * What each of a ruby run's two base-side `a:rPr`s authored on its own:
     * `outer` is the containing `a:r`'s, `base` the `a:rubyBase` run's. The
     * flat {@link style} merges both for rendering; these let the writer give
     * each `a:rPr` back only its own properties (plus any later edit).
     */
    rubyRunAuthoredStyles?: {
        outer?: TextStyle;
        base?: TextStyle;
    };
}

declare interface TextSegmentInput {
    text: string;
    style?: Partial<TextStyleInput>;
}

/** Desired UTF-16 units mapped to the editor's previously observed identities. */
declare interface TextSessionCorrespondence {
    readonly retainedIndices: readonly (number | null)[];
    /** Old carriers for known paragraph attributes, independently of character identity. */
    readonly paragraphSources?: readonly (number | null)[];
}

/** Supplied by the binding's existing Yjs runtime, bound to this exact Y.Text. */
declare interface TextSessionPositions<Position> {
    capture: (index: number, association: number) => Position;
    resolve: (position: Position) => number | null;
    /** Synchronize tracked positions once per batch, including in-transaction writes. */
    refresh?: () => boolean | void;
    /** Release only resources created for this session. */
    dispose?: () => void;
}

declare interface TextStyle {
    /**
     * Combined rotation/flip matrix inherited from ancestor groups.
     * Used only to keep descendant text readable after nested group mirrors.
     */
    ancestorGroupTransform?: TextOrientationMatrix;
    /** Original `a:rPr` XML retained by projections that share the shape-text model. */
    runPropertiesXml?: XmlObject;
    /**
     * The properties this run's OWN `a:rPr` authored, and nothing else.
     *
     * A run style is assembled as
     * `{...inheritedRunStyle, ...authoredRunStyle}`, so the flat style is a
     * fully RESOLVED view: it cannot say whether `fontSize: 60` came from the
     * run, from the shape's `a:lstStyle`, from the layout placeholder, from the
     * master `p:txStyles` or from the theme. Omission is meaningful in OOXML
     * (§21.1.2.3), so a writer that re-emits the resolved view converts every
     * inherited value into an authored one and the deck stops being
     * theme-driven after one save.
     *
     * This is the run-scope twin of {@link TextSegment.paragraphProperties},
     * which is parsed strictly from the paragraph's own `a:pPr` for the same
     * reason. Present only for runs that came from a parsed deck; absent for
     * SDK-built text, where the flat style IS the only description and must be
     * written out in full.
     */
    authoredRunStyle?: TextStyle;
    /**
     * The resolved inheritance baseline {@link authoredRunStyle} was layered
     * on top of (shape `a:lstStyle` -> placeholder -> layout -> master
     * `p:txStyles` -> theme -> `p:defaultTextStyle`).
     *
     * Kept alongside the authored half because the two answer different
     * questions. The authored half says "the source pinned this"; the baseline
     * says "this value is what inheritance already produces", which is how an
     * EDIT is told apart from an inherited value: an editor mutates the flat
     * style without knowing about either field, so a property that now differs
     * from the baseline was either authored or edited and must be written,
     * while one that still matches can be left to inherit.
     *
     * Holds a reference to the per-paragraph baseline object rather than a
     * copy, so carrying it costs one pointer per run.
     */
    inheritedRunStyle?: TextStyle;
    /**
     * Snapshot of the ELEMENT-scope paragraph geometry (alignment, margins,
     * indent, line and paragraph spacing, tab stops, rtl, line-break flags) as
     * the load pipeline resolved it.
     *
     * Present only on an `element.textStyle` that came from a parsed deck, and
     * populated only with the geometry keys. It exists so the save path can
     * answer one question it otherwise cannot: has the user CHANGED the body's
     * alignment or indent, or is the value simply what the shape's
     * `a:lstStyle`, its layout placeholder and the master already produce?
     * Element-level text panels (`textAdvancedPatch`, `alignPatch` and friends
     * in `pptx-viewer-shared`) write `element.textStyle` and never touch
     * `segment.paragraphProperties`, so a diff against this snapshot is the
     * only way to tell an edit from an inheritance artefact.
     *
     * @see element-paragraph-geometry.ts
     */
    resolvedParagraphGeometry?: TextStyle;
    /**
     * Snapshot of the ELEMENT-scope `a:bodyPr` properties (vertical anchor,
     * text direction, columns, overflow, autofit, body insets, text wrap, and
     * the boolean/rotation attributes) as the load pipeline resolved them.
     *
     * A shape's own `a:bodyPr` is parsed first, then whatever it left
     * `undefined` is back-filled from the placeholder / layout / master
     * defaults (`applyPlaceholderBodyDefaults`), and a placeholder shape with
     * no `a:bodyPr` of its own has the INHERITED one parsed as if it were its
     * own. None of those three sources is distinguishable at
     * `element.textStyle` once the cascade finishes, so a writer that
     * re-emits every defined field turns an inherited anchor, inset, autofit
     * mode or `rtlCol` into a value pinned on the slide forever (and an
     * inherited `a:normAutofit` with no scale gets written back as
     * `a:spAutoFit`, flipping AutoSize from "shrink text" to "resize shape").
     *
     * Present only on an `element.textStyle` that came from a parsed deck.
     * The save path diffs the live style against this snapshot: a field that
     * still matches is an inheritance artefact and the writer leaves the
     * underlying `a:bodyPr` attribute untouched (whatever it already is,
     * present or absent); a field that differs was authored or has since
     * been edited and is written out.
     *
     * @see element-body-properties.ts
     */
    resolvedBodyProperties?: TextStyle;
    fontFamily?: string;
    fontSize?: number;
    /** When true, some form of autofit is in effect; see {@link autoFitMode} for which. */
    autoFit?: boolean;
    /** Explicit autofit mode from OOXML body properties.
     * - 'shrink': `a:spAutoFit` - resize the SHAPE to fit the text (never the font)
     * - 'normal': `a:normAutofit` - shrink the TEXT to fit the shape (via `fontScale`/`lnSpcReduction`)
     * - 'none': `a:noAutofit` - explicitly no auto-fit (text overflows)
     * - undefined: no autofit element present (inherit from layout/master)
     */
    autoFitMode?: 'shrink' | 'normal' | 'none';
    /** Font scale percentage for normAutofit (e.g. 0.9 = 90%). Only meaningful when autoFit is true. */
    autoFitFontScale?: number;
    /** Line spacing reduction for normAutofit (e.g. 0.2 = reduce by 20%). Only meaningful when autoFit is true. */
    autoFitLineSpacingReduction?: number;
    bold?: boolean;
    italic?: boolean;
    underline?: boolean;
    /** Specific underline style (e.g. "sng", "dbl", "wavy"). Falls back to "sng" when `underline` is true. */
    underlineStyle?: UnderlineStyle;
    /** Underline colour as hex string (`a:uFill` / `a:uLn`). When absent, inherits text colour. */
    underlineColor?: string;
    /**
     * When true, the source authored `<a:u val="none"/>` to explicitly suppress
     * underline (rather than omitting the attribute entirely). Preserved so the
     * writer can re-emit the explicit `none` token instead of dropping it.
     */
    underlineExplicitNone?: boolean;
    /**
     * Underline line properties parsed from `<a:rPr><a:uLn>` — width, dash
     * preset, and end caps. Captured as a typed object so the writer can
     * round-trip the line styling that previously was dropped (only the
     * solidFill colour was carried before).
     */
    underlineLine?: {
        /** Line width in EMU (raw OOXML) for `a:uLn/@w`. */
        widthEmu?: number;
        /** Compound line type (`a:uLn/@cmpd`). */
        compound?: string;
        /** Cap style (`a:uLn/@cap`). */
        cap?: string;
        /** Pen alignment (`a:uLn/@algn`). */
        algn?: string;
        /** Preset dash value (`a:uLn/a:prstDash/@val`). */
        prstDash?: string;
        /** Raw `a:uLn/a:headEnd` XML preserved verbatim. */
        headEndXml?: XmlObject;
        /** Raw `a:uLn/a:tailEnd` XML preserved verbatim. */
        tailEndXml?: XmlObject;
    };
    /** When `<a:uLnTx/>` is present — underline line follows the text run line. */
    underlineLineFollowsText?: boolean;
    /** When `<a:uFillTx/>` is present — underline fill follows the text run fill. */
    underlineFillFollowsText?: boolean;
    strikethrough?: boolean;
    /** Specific strike type: single or double from `a:rPr/@strike`. */
    strikeType?: 'sngStrike' | 'dblStrike';
    /** Text outline width in px (`a:rPr > a:ln/@w` in EMU). */
    textOutlineWidth?: number;
    /** Text outline colour as hex string (`a:rPr > a:ln > a:solidFill`). */
    textOutlineColor?: string;
    /** Text outline dash preset (`a:rPr > a:ln > a:prstDash/@val`), e.g. `dash`; absent for solid. */
    textOutlineDash?: string;
    /** When true, the text body has no fill (`a:rPr > a:noFill`), producing hollow/outline-only text. */
    textFillNone?: boolean;
    /**
     * When true, the run authored an EMPTY `<a:effectLst/>`: an explicit "no
     * effects" override that blocks an inherited shadow or glow. Kept so a
     * rewrite re-emits it instead of letting the inherited effect return.
     */
    textEffectsExplicitNone?: boolean;
    /** Superscript/subscript baseline shift as percentage (`a:rPr/@baseline`). Positive = super, negative = sub. */
    baseline?: number;
    /** Character spacing in hundredths of a point (`a:rPr/@spc`). */
    characterSpacing?: number;
    /** Kerning threshold in hundredths of a point (`a:rPr/@kern`). 0 = none. */
    kerning?: number;
    /** Text highlight colour as hex string (`a:highlight`). */
    highlightColor?: string;
    /**
     * Raw colour-choice XML preserved from `a:highlight` so a themed highlight
     * (`a:schemeClr` / `a:sysClr` / `a:prstClr`) re-emits with its original
     * identity rather than being flattened to `<a:srgbClr/>` on save. On save we
     * re-emit verbatim when the resolved {@link highlightColor} still matches.
     */
    highlightColorXml?: XmlObject;
    /** Text-level gradient fill CSS string (from `a:rPr > a:gradFill`). */
    textFillGradient?: string;
    /** Structured gradient stops for text fill round-trip serialization. */
    textFillGradientStops?: Array<{
        color: string;
        position: number;
        opacity?: number;
    }>;
    /** Gradient angle in degrees for text fill round-trip. */
    textFillGradientAngle?: number;
    /** Gradient type for text fill round-trip ('linear' | 'radial'). */
    textFillGradientType?: 'linear' | 'radial';
    /** Text-level pattern fill preset (from `a:rPr > a:pattFill`). */
    textFillPattern?: string;
    /** Text-level pattern foreground colour. */
    textFillPatternForeground?: string;
    /** Text-level pattern background colour. */
    textFillPatternBackground?: string;
    /**
     * Raw `a:rPr > a:blipFill` XML, preserved verbatim for round-trip
     * serialization AND as the input to the image resolution pass that fills
     * in {@link textFillBlipUrl} (parsing a run's fill happens synchronously,
     * with no zip/relationship access at that point; resolving the blip to a
     * displayable URL needs both, so it happens in a later async pass over
     * the slide's parsed elements, mirroring how a shape's OWN image fill is
     * resolved). A picture-filled text run (`a:rPr > a:blipFill`) was
     * documented as handled ("Handles gradient fills, pattern fills, and
     * image fills on text runs") but never actually parsed, so it silently
     * fell through to the run's plain `color` and rendered solid black
     * (COM-verified: `audit-text` slide 13's "PICTURE FILL" run shows the
     * fill image through the glyphs in PowerPoint).
     */
    textFillBlipXml?: XmlObject;
    /** Resolved displayable URL for {@link textFillBlipXml}, or the archive-relative path when unresolved (lazy decode). */
    textFillBlipUrl?: string;
    /** Tiling mode for {@link textFillBlipUrl} (`a:blipFill/a:tile` present -> 'tile', else 'stretch'). */
    textFillBlipMode?: 'stretch' | 'tile';
    hyperlink?: string;
    /** Relationship ID for the hyperlink (`a:hlinkClick/@r:id`) — preserved for round-trip serialization. */
    hyperlinkRId?: string;
    /** Hyperlink tooltip text (`a:hlinkClick/@tooltip`). */
    hyperlinkTooltip?: string;
    /** Hyperlink action type (`a:hlinkClick/@action`). */
    hyperlinkAction?: string;
    /** Whether the hyperlink target is an internal slide jump (targetSlideIndex style). */
    hyperlinkTargetSlideIndex?: number;
    color?: string;
    /**
     * Raw XML colour-choice node preserved from `a:rPr/a:solidFill` for
     * round-trip serialisation. Captures `a:schemeClr` / `a:sysClr` /
     * `a:prstClr` / `a:srgbClr` plus colour transforms. On save we re-emit
     * verbatim when the resolved {@link color} still matches this node.
     */
    colorXml?: XmlObject;
    /**
     * Typed theme colour reference for the run's text colour, set when
     * {@link colorXml} is a plain `a:schemeClr` (see
     * `themeColorRefFromColorChoice`). When present it WINS on save: the
     * writer emits `<a:schemeClr>` from this ref instead of the resolved
     * {@link color}, so the text keeps following the theme palette after a
     * later theme change.
     */
    colorRef?: PptxThemeColorRef;
    align?: 'left' | 'center' | 'right' | 'justify' | 'justLow' | 'dist' | 'thaiDist';
    /**
     * Vertical text-box anchor (`a:bodyPr/@anchor`, `ST_TextAnchoringType`).
     * `distributed`/`justified` (`dist`/`just`) stretch line spacing so the
     * paragraph block fills the box's full vertical extent, distinct from true
     * centering (`middle`/`ctr`); both approximate to a middle-anchored render
     * (see `text-body-layout.ts`) since CSS has no native vertical-justify
     * primitive, but round-trip losslessly through parse/save.
     */
    vAlign?: 'top' | 'middle' | 'bottom' | 'distributed' | 'justified';
    /** Right-to-left paragraph/run direction (`a:pPr/@rtl`, `a:rPr/@rtl`). */
    rtl?: boolean;
    /** Body text direction (`a:bodyPr/@vert`).
     *
     * Values map to OOXML `a:bodyPr/@vert` attribute values:
     * - `"horizontal"` — default horizontal text (`horz`)
     * - `"vertical"` — standard vertical text, right-to-left columns (`vert`)
     * - `"vertical270"` — text rotated 270 degrees (`vert270`)
     * - `"eaVert"` — East Asian vertical text with CJK glyphs upright (`eaVert`)
     * - `"wordArtVert"` — WordArt vertical, each character upright stacked (`wordArtVert`)
     * - `"wordArtVertRtl"` — WordArt vertical, right-to-left direction (`wordArtVertRtl`)
     * - `"mongolianVert"` — Mongolian vertical text, left-to-right columns (`mongolianVert`)
     */
    textDirection?: 'horizontal' | 'vertical' | 'vertical270' | 'eaVert' | 'wordArtVert' | 'wordArtVertRtl' | 'mongolianVert';
    /** Body column count (`a:bodyPr/@numCol`). */
    columnCount?: number;
    /** Column spacing in px (`a:bodyPr/@spcCol` in EMU). */
    columnSpacing?: number;
    /** Horizontal overflow mode from `a:bodyPr/@hOverflow`. */
    hOverflow?: 'overflow' | 'clip';
    /** Vertical overflow mode from `a:bodyPr/@vertOverflow`. */
    vertOverflow?: 'overflow' | 'clip' | 'ellipsis';
    /** Body text left inset in px (`a:bodyPr/@lIns` in EMU). */
    bodyInsetLeft?: number;
    /** Body text top inset in px (`a:bodyPr/@tIns` in EMU). */
    bodyInsetTop?: number;
    /** Body text right inset in px (`a:bodyPr/@rIns` in EMU). */
    bodyInsetRight?: number;
    /** Body text bottom inset in px (`a:bodyPr/@bIns` in EMU). */
    bodyInsetBottom?: number;
    /** Paragraph spacing before in px. */
    paragraphSpacingBefore?: number;
    /** Paragraph spacing after in px. */
    paragraphSpacingAfter?: number;
    /** Line spacing multiplier (e.g. 1.2 = 120%). Used when mode is proportional (spcPct). */
    lineSpacing?: number;
    /** Exact line spacing in points (from `a:lnSpc > a:spcPts`). Takes priority over `lineSpacing` when set. */
    lineSpacingExactPt?: number;
    /** Paragraph left margin in px (`a:pPr/@marL` in EMU). */
    paragraphMarginLeft?: number;
    /** Paragraph right margin in px (`a:pPr/@marR` in EMU). */
    paragraphMarginRight?: number;
    /** Paragraph first-line indent in px (`a:pPr/@indent` in EMU). */
    paragraphIndent?: number;
    /** Tab stop positions and alignments (`a:pPr/a:tabLst/a:tab`). */
    tabStops?: Array<{
        position: number;
        align: 'l' | 'ctr' | 'r' | 'dec';
        leader?: 'none' | 'dot' | 'hyphen' | 'underscore';
        /**
         * True when the source spelled out the schema-default `@algn="l"`, so the
         * writer re-emits it instead of treating it as an omitted default.
         */
        alignAuthored?: boolean;
        /** True when the source spelled out the schema-default `@leader="none"`. */
        leaderAuthored?: boolean;
    }>;
    /**
     * True when the paragraph's own `a:pPr` authored an EMPTY `<a:tabLst/>`
     * (explicitly "no tab stops", overriding whatever the cascade would
     * otherwise supply) rather than omitting the element entirely (inherit).
     * fast-xml-parser gives a childless element as the empty string, so
     * `tabLst` and no-`tabLst` are otherwise indistinguishable once `tabStops`
     * comes back empty either way. Paragraph-scope only; not part of the
     * element-level geometry cascade.
     */
    tabStopsExplicitEmpty?: boolean;
    /** Body text wrapping mode from `a:bodyPr/@wrap`. */
    textWrap?: 'square' | 'none';
    /** Preset text warp type from `a:bodyPr/a:prstTxWarp`. */
    textWarpPreset?: PptxTextWarpPreset;
    /** Primary adjustment value for text warp (from `a:prstTxWarp/a:avLst/a:gd` with name "adj").
     *  Stored as raw OOXML 1/60000th units (e.g. 50000 = default for many presets). */
    textWarpAdj?: number;
    /** Secondary adjustment value for text warp (from `a:prstTxWarp/a:avLst/a:gd` with name "adj2").
     *  Stored as raw OOXML 1/60000th units. */
    textWarpAdj2?: number;
    /** Text capitalization style from `a:rPr/@cap`. */
    textCaps?: 'all' | 'small' | 'none';
    /**
     * When true, the source authored `<a:rPr cap="none"/>` explicitly. This
     * differs from {@link textCaps} = `"none"` only because the writer must
     * preserve the explicit token rather than collapse it to omission.
     */
    textCapsExplicitNone?: boolean;
    /** Symbol font family from `a:sym`. */
    symbolFont?: string;
    /** East Asian font family from `a:ea`. */
    eastAsiaFont?: string;
    /** Complex Script font family from `a:cs`. */
    complexScriptFont?: string;
    /**
     * Theme-font token (`+mj-lt` / `+mn-lt` / ...) authored on `a:latin`, when
     * present. {@link fontFamily} holds the resolved concrete face for
     * rendering; this preserves the token linkage so the writer re-emits the
     * token rather than the flattened face (see #84).
     */
    latinFontThemeToken?: string;
    /** Theme-font token authored on `a:ea` (e.g. `+mn-ea`), when present. */
    eastAsiaFontThemeToken?: string;
    /** Theme-font token authored on `a:cs` (e.g. `+mn-cs`), when present. */
    complexScriptFontThemeToken?: string;
    /**
     * Automatic per-script fallback face resolved from the theme's
     * `<a:font script="...">` overrides for a run whose text is dominantly
     * CJK / Arabic / Hebrew / Thai (see #83). A rendering hint only: it is not
     * serialised back on save, so it never disturbs the round-trip typefaces.
     */
    scriptFallbackFont?: string;
    /**
     * Set alongside {@link scriptFallbackFont} when the resolved {@link fontFamily}
     * came only from the paragraph/list-style/theme CASCADE (the run's own
     * `a:rPr` authored no `a:latin`/`a:ea`/`a:cs` of its own). A run always
     * inherits SOME font this way (typically the theme's `+mn-lt`), so without
     * this flag `fontFamily` was indistinguishable from a run that genuinely
     * chose that font itself, and the renderer never applied the theme's
     * per-script override (see #83): `+mn-lt` names only the LATIN member of
     * the font scheme and was never meant to cover text in a different
     * dominant script. An explicit `a:latin`/`a:ea`/`a:cs` authored on the run
     * itself still always wins; only the cascade default yields to the
     * script-specific override.
     */
    fontFamilyIsCascadeDefault?: boolean;
    /** Text language from `a:rPr/@lang`. */
    language?: string;
    /** Hyperlink mouse-over target from `a:hlinkMouseOver`. */
    hyperlinkMouseOver?: string;
    /**
     * Raw `a:snd` (embedded WAV audio) child of `a:hlinkClick`, preserved
     * verbatim (carries `@r:embed` + `@name`). Round-tripped on save so the
     * click sound survives instead of being dropped.
     */
    hyperlinkSoundXml?: XmlObject;
    /** Raw `a:snd` child of `a:hlinkMouseOver`, preserved verbatim for round-trip. */
    hyperlinkMouseOverSoundXml?: XmlObject;
    /** Hyperlink invalidUrl attribute (`a:hlinkClick/@invalidUrl`). */
    hyperlinkInvalidUrl?: string;
    /** Hyperlink target frame (`a:hlinkClick/@tgtFrame`). */
    hyperlinkTargetFrame?: string;
    /** Whether hyperlink history is tracked (`a:hlinkClick/@history`). */
    hyperlinkHistory?: boolean;
    /** Whether hyperlink uses highlight-click effect (`a:hlinkClick/@highlightClick`). */
    hyperlinkHighlightClick?: boolean;
    /** Whether hyperlink ends a sound (`a:hlinkClick/@endSnd`). */
    hyperlinkEndSound?: boolean;
    /**
     * Raw `a:hlinkClick/a:extLst` child, preserved verbatim for round-trip.
     * Carries vendor extensions this engine does not interpret, most commonly
     * `ahyp:hlinkClr` (Microsoft's "hyperlink color" extension,
     * `{A12FA001-AC4F-418D-AE19-62706E023703}`), which records whether a
     * hyperlink run should paint with the theme's text colour instead of the
     * hyperlink colour. Dropping the whole `a:extLst` silently reverted such a
     * run to the default (themed) hyperlink colour on save.
     */
    hyperlinkExtensionXml?: XmlObject;
    /** Kumimoji (ideographic text combining) flag for vertical CJK text (`a:rPr/@kumimoji`). */
    kumimoji?: boolean;
    /** Normalize height flag (`a:rPr/@normalizeH`). */
    normalizeHeight?: boolean;
    /** No proofing flag (`a:rPr/@noProof`). */
    noProof?: boolean;
    /** Dirty flag indicating run has been edited (`a:rPr/@dirty`). */
    dirty?: boolean;
    /** Error flag indicating spelling error (`a:rPr/@err`). */
    spellingError?: boolean;
    /** Smart tag clean flag (`a:rPr/@smtClean`). */
    smartTagClean?: boolean;
    /** Bookmark link target (`a:rPr/@bmk`). */
    bookmark?: string;
    /** Alternative language for the run (`a:rPr/@altLang`). Populated for runs
     *  authored in mixed-script documents (e.g. Asian/Latin combined). */
    altLanguage?: string;
    /** SmartTag (Office grammar tag) GUID id (`a:rPr/@smtId`). Round-tripped
     *  verbatim — the engine doesn't interpret it. */
    smartTagId?: number;
    /** Latin font PANOSE classification string from `a:rPr > a:latin/@panose`. */
    latinFontPanose?: string;
    /** Latin font pitch + family flag from `a:rPr > a:latin/@pitchFamily`. */
    latinFontPitchFamily?: number;
    /** Latin font character set id from `a:rPr > a:latin/@charset`. */
    latinFontCharset?: number;
    /** East-Asian font PANOSE from `a:rPr > a:ea/@panose`. */
    eastAsiaFontPanose?: string;
    /** East-Asian font pitch + family flag from `a:rPr > a:ea/@pitchFamily`. */
    eastAsiaFontPitchFamily?: number;
    /** East-Asian font character set id from `a:rPr > a:ea/@charset`. */
    eastAsiaFontCharset?: number;
    /** Complex-script font PANOSE from `a:rPr > a:cs/@panose`. */
    complexScriptFontPanose?: string;
    /** Complex-script font pitch + family flag from `a:rPr > a:cs/@pitchFamily`. */
    complexScriptFontPitchFamily?: number;
    /** Complex-script font character set id from `a:rPr > a:cs/@charset`. */
    complexScriptFontCharset?: number;
    /** Symbol-font PANOSE from `a:rPr > a:sym/@panose`. */
    symbolFontPanose?: string;
    /** Symbol-font pitch + family flag from `a:rPr > a:sym/@pitchFamily`. */
    symbolFontPitchFamily?: number;
    /** Symbol-font character set id from `a:rPr > a:sym/@charset`. */
    symbolFontCharset?: number;
    /** Paragraph list type for toggling bullet / numbered lists via the toolbar.
     * - `'bullet'` — character bullet (default "•")
     * - `'numbered'` — auto-numbered list (arabicPeriod)
     * - `'none'` — explicitly no list
     */
    listType?: 'bullet' | 'numbered' | 'none';
    /** Default tab size in px (`a:pPr/@defTabSz` in EMU). */
    defaultTabSize?: number;
    /** East Asian line break flag (`a:pPr/@eaLnBrk`). */
    eaLineBreak?: boolean;
    /** Latin line break flag (`a:pPr/@latinLnBrk`). */
    latinLineBreak?: boolean;
    /** Font alignment (`a:pPr/@fontAlgn`): 'auto' | 'base' | 'ctr' | 't' | 'b'. */
    fontAlignment?: string;
    /** Hanging punctuation flag (`a:pPr/@hangingPunct`). */
    hangingPunctuation?: boolean;
    /** Whether to space first and last paragraph from body edges (`a:bodyPr/@spcFirstLastPara`). */
    spaceFirstLastParagraph?: boolean;
    /** Right-to-left column flow (`a:bodyPr/@rtlCol`). */
    rtlColumns?: boolean;
    /** Whether text originates from WordArt (`a:bodyPr/@fromWordArt`). */
    fromWordArt?: boolean;
    /** Whether text anchoring is centered (`a:bodyPr/@anchorCtr`). */
    anchorCenter?: boolean;
    /** Force anti-aliasing (`a:bodyPr/@forceAA`). */
    forceAntiAlias?: boolean;
    /** Upright text in 3D views (`a:bodyPr/@upright`). */
    upright?: boolean;
    /** Compatible line spacing flag (`a:bodyPr/@compatLnSpc`). */
    compatibleLineSpacing?: boolean;
    /**
     * Text body rotation in **degrees** (`a:bodyPr/@rot`).
     *
     * OOXML stores the value as 60000ths of a degree. Positive values rotate
     * the body clockwise. When undefined, the attribute is omitted on save
     * (PowerPoint treats absent `rot` as inherit/none).
     */
    textBodyRotation?: number;
    /** Text shadow colour as hex string (`a:outerShdw`). */
    textShadowColor?: string;
    /** Text shadow blur radius in px. */
    textShadowBlur?: number;
    /** Text shadow horizontal offset in px. */
    textShadowOffsetX?: number;
    /** Text shadow vertical offset in px. */
    textShadowOffsetY?: number;
    /** Text shadow opacity (0-1). */
    textShadowOpacity?: number;
    /** Text inner shadow colour (`a:innerShdw`). */
    textInnerShadowColor?: string;
    /** Text inner shadow opacity (0-1). */
    textInnerShadowOpacity?: number;
    /** Text inner shadow blur radius in px. */
    textInnerShadowBlur?: number;
    /** Text inner shadow horizontal offset in px. */
    textInnerShadowOffsetX?: number;
    /** Text inner shadow vertical offset in px. */
    textInnerShadowOffsetY?: number;
    /**
     * Original inner-shadow colour-choice XML (`a:innerShdw`'s
     * `a:prstClr`/`a:schemeClr`/`a:srgbClr`/… child), preserved verbatim so an
     * authored preset or theme colour round-trips instead of always being
     * re-serialized as a resolved `a:srgbClr`. Mirrors {@link textGlowColorXml}.
     */
    textInnerShadowColorXml?: XmlObject;
    /** Theme colour slot the inner shadow colour resolved from, when it is `a:schemeClr`. */
    textInnerShadowColorRef?: PptxThemeColorRef;
    /** Preset shadow type from `a:prstShdw/@prst` (e.g. "shdw1"..."shdw20"). */
    textPresetShadowName?: string;
    /** Preset shadow colour as hex string. */
    textPresetShadowColor?: string;
    /** Preset shadow opacity (0-1). */
    textPresetShadowOpacity?: number;
    /** Preset shadow distance in px. */
    textPresetShadowDistance?: number;
    /** Preset shadow direction in degrees. */
    textPresetShadowDirection?: number;
    /** Text blur effect radius in px (`a:blur`). */
    textBlurRadius?: number;
    /**
     * Text soft-edge radius in px (`a:softEdge/@rad`).
     *
     * Feathers the glyph's own edges (a uniform blur of the alpha silhouette,
     * the same effect a shape's `a:softEdge` gives its fill), unrelated to
     * `a:blur` (which blurs the whole run, colour included) or a shadow. Never
     * parsed before this field existed, so `a:softEdge` on a run was silently
     * dropped: PowerPoint fades the glyphs to near-transparent at their
     * outline (COM-verified, `audit-text` slide 14's "SOFTEDGE" run), while
     * the viewer painted them fully crisp.
     */
    textSoftEdgeRadius?: number;
    /**
     * Raw `a:effectDag` XML node from `a:rPr`, preserved verbatim for
     * round-trip serialisation. Mirrors the shape-level
     * {@link import('./shape-style').ShapeStyle.effectDagXml} field.
     */
    textEffectDagXml?: XmlObject;
    /**
     * Typed effect graph parsed from `textEffectDagXml`. The four structural
     * container nodes (`a:cont`, `a:blend`, `a:xfrmEffect`, `a:relOff`) are
     * fully typed; any other leaf effect is captured as
     * {@link import('./effect-dag').EffectDagRawLeaf} so we never have to
     * recurse into the full effect taxonomy.
     */
    textEffectDagTree?: EffectDagContainer;
    /** Text alpha modulation fixed (0-100) from `a:alphaModFix`. */
    textAlphaModFix?: number;
    /** Text alpha modulation from `a:alphaMod` (0-100 percentage). */
    textAlphaMod?: number;
    /** Text hue shift in degrees from `a:hsl/@hue`. */
    textHslHue?: number;
    /** Text saturation adjustment from `a:hsl/@sat`. */
    textHslSaturation?: number;
    /** Text luminance adjustment from `a:hsl/@lum`. */
    textHslLuminance?: number;
    /** Text colour change from colour as hex string (`a:clrChange`). */
    textClrChangeFrom?: string;
    /** Text colour change to colour as hex string. */
    textClrChangeTo?: string;
    /** Text duotone colour pair (`a:duotone`). */
    textDuotone?: {
        color1: string;
        color2: string;
    };
    /** Text glow colour as hex string (`a:glow`). */
    textGlowColor?: string;
    /** Text glow radius in px. */
    textGlowRadius?: number;
    /** Text glow opacity (0-1). */
    textGlowOpacity?: number;
    /**
     * Original glow colour-choice XML (`a:glow`'s `a:schemeClr`/`a:srgbClr`/…
     * child), preserved verbatim so a theme colour reference round-trips
     * instead of always being re-serialized as a resolved `a:srgbClr` (which
     * cuts the glow off from theme/Recolor changes).
     */
    textGlowColorXml?: XmlObject;
    /** Theme colour slot the glow colour resolved from, when it is `a:schemeClr`. */
    textGlowColorRef?: PptxThemeColorRef;
    /** Text reflection enabled flag. */
    textReflection?: boolean;
    /** Text reflection blur radius in px. */
    textReflectionBlur?: number;
    /** Text reflection start opacity (0-1). */
    textReflectionStartOpacity?: number;
    /** Text reflection end opacity (0-1). */
    textReflectionEndOpacity?: number;
    /** Text reflection offset distance in px. */
    textReflectionOffset?: number;
    /**
     * Text reflection end position (`@endPos`) as a 0-1 fraction of the text
     * height the fade reaches. Mirrors `ShapeStyle.reflectionEndPosition`.
     */
    textReflectionEndPosition?: number;
    /**
     * Text reflection offset direction (`@dir`) in degrees. Mirrors
     * `ShapeStyle.reflectionDirection`.
     */
    textReflectionDirection?: number;
    /**
     * Text reflection fade direction (`a:rPr/a:effectLst/a:reflection/@fadeDir`)
     * in degrees. Mirrors `ShapeStyle.reflectionFadeDirection`.
     */
    textReflectionFadeDirection?: number;
    /**
     * Text reflection horizontal scaling (`@sx`), same units as
     * `ShapeStyle.reflectionScaleX` (1000ths of a percent, e.g. 100000 = 100%).
     */
    textReflectionScaleX?: number;
    /** Text reflection vertical scaling (`@sy`). See `ShapeStyle.reflectionScaleY`. */
    textReflectionScaleY?: number;
    /**
     * Text reflection horizontal skew (`@kx`) in 60000ths of a degree. See
     * `ShapeStyle.reflectionSkewX`.
     */
    textReflectionSkewX?: number;
    /** Text reflection vertical skew (`@ky`). See `ShapeStyle.reflectionSkewY`. */
    textReflectionSkewY?: number;
    /**
     * Text reflection independent rotation (`@rot`) in degrees. See
     * `ShapeStyle.reflectionRotation`.
     */
    textReflectionRotation?: number;
    /** Text reflection anchor (`@algn`). See `ShapeStyle.reflectionAlignment`. */
    textReflectionAlignment?: 'tl' | 't' | 'tr' | 'l' | 'ctr' | 'r' | 'bl' | 'b' | 'br';
    /** 3D extrusion/bevel settings on the text body. */
    text3d?: Text3DStyle;
    /** 3D scene (camera + light rig) settings on the text body (`a:bodyPr/a:scene3d`). */
    textBodyScene3d?: Pptx3DScene;
    /** Raw `a:scene3d` subtree used to preserve extensions and unmodelled children. */
    textBodyScene3dXml?: XmlObject;
    /**
     * `a:bodyPr/a:flatTx` - an explicit "render this text flat" marker. `sp3d`
     * and `flatTx` are a mutually exclusive OOXML choice (`EG_Text3D`), so a
     * shape/run that overrides an inherited 3D text body with `<a:flatTx/>`
     * carries no `text3d` of its own; without this explicit flag a later
     * inheritance merge has no signal to stop `text3d`/`textBodyScene3d` from
     * an ancestor (layout/master) leaking back in, the way `noFill` stops an
     * inherited fill. A renderer must short-circuit 3D-text application
     * whenever this is `true`, regardless of what `text3d`/`textBodyScene3d`
     * otherwise hold.
     */
    flatText?: boolean;
    /**
     * Raw `<a:extLst>` subtree captured from `<a:bodyPr>`. Preserved verbatim so
     * authored extensions (e.g. content placeholders, custom application data)
     * survive a round-trip even though the engine doesn't interpret them.
     */
    bodyPropertiesExtLstXml?: XmlObject;
    /**
     * Raw `<a:extLst>` subtree captured from `<a:pPr>`. Only meaningful on the
     * paragraph-level style (paragraphs propagate this via the first segment).
     */
    paragraphPropertiesExtLstXml?: XmlObject;
    /**
     * Raw `<a:extLst>` subtree captured from `<a:rPr>`. Persisted verbatim on
     * save when present — covers run-level extensions the typed model doesn't
     * model (e.g. `a14:hiddenFill` and similar).
     */
    runPropertiesExtLstXml?: XmlObject;
    /**
     * Raw `<a:defRPr>` XML node captured from `<a:pPr>`. The schema permits
     * `defRPr` directly inside `pPr` so that paragraph defaults can specify the
     * end-paragraph run formatting; previously this was dropped on save. We
     * persist the parsed XML object so it round-trips verbatim.
     *
     * Only meaningful on the *first* segment of each paragraph (matches the
     * convention used for {@link bulletInfo} / {@link endParaRunProperties}).
     */
    paragraphDefaultRunPropertiesXml?: XmlObject;
    /**
     * The bullet colour / size / typeface children (`a:buClrTx`, `a:buClr`,
     * `a:buSzTx`, `a:buSzPct`, `a:buSzPts`, `a:buFontTx`, `a:buFont`) a
     * paragraph authored in its own `<a:pPr>` WITHOUT a bullet type
     * (`a:buNone` / `a:buChar` / `a:buAutoNum` / `a:buBlip`), captured
     * verbatim in source order. Such a paragraph restyles an inherited bullet
     * rather than declaring one, so its {@link BulletInfo} resolves from the
     * cascade and is (correctly) not written back; without this capture the
     * paragraph's own override vanished on every rewrite.
     *
     * Only meaningful on a paragraph's own authored properties.
     */
    paragraphBulletPropertiesXml?: XmlObject;
}

/**
 * Framework-neutral text-style override a font-style emphasis effect applies
 * on top of its target's own authored per-run bold/italic/underline/size/
 * colour. Every binding maps this onto its own text container so it OVERRIDES
 * the runs' inline styles (the runs carry explicit inline styles of their
 * own, so plain CSS inheritance cannot reach them).
 */
declare interface TextStyleAnimationDescriptor {
    bold?: boolean;
    italic?: boolean;
    underline?: boolean;
    /** Relative multiplier against each run's own authored font size. */
    fontScale?: number;
    color?: string;
}

declare interface TextStyleInput {
    fontSize?: number;
    fontFamily?: string;
    bold?: boolean;
    italic?: boolean;
    underline?: boolean;
    strikethrough?: boolean;
    color?: string;
    /** A theme colour for the run; see {@link FillInput}'s `themeColorRef`. */
    themeColorRef?: PptxThemeColorRef;
    alignment?: 'left' | 'center' | 'right' | 'justify';
    verticalAlignment?: 'top' | 'middle' | 'bottom';
    lineSpacing?: number;
    spaceBefore?: number;
    spaceAfter?: number;
}

declare type ToolbarActionId = ToolbarButtonId | ToolbarTabId;

/**
 * Toolbar action / ribbon-tab visibility: a single, framework-agnostic
 * catalogue of every top-level toolbar button and ribbon tab a host app can
 * independently hide. Each binding exposes a `hiddenActions?: ToolbarActionId[]`
 * prop, threads it down to the relevant render sites, and gates them with
 * `isActionHidden`. Default (`undefined` / `[]`) hides nothing, matching
 * today's always-visible behaviour.
 *
 * `TOOLBAR_TABS` is also the canonical ribbon-tab list/order, replacing the
 * copy hand-duplicated in each binding (React's `TOOLBAR_SECTIONS`, Vue's
 * `ribbon-constants.ts`, Angular's `RIBBON_TABS`, etc.) so the tab set can't
 * drift between bindings. Per-tab icons stay in each binding (icon libraries
 * differ per framework); only id + i18n key + order are shared here.
 */
/**
 * A single toolbar button/control that can be hidden independently of the
 * ribbon tab it may also appear inside. `zoom` and `navigation` each cover a
 * whole control cluster (zoom in/out/fit, prev/next) rather than each button
 * in it, matching how hosts actually want to hide/keep them as a unit.
 */
declare type ToolbarButtonId = 'share' | 'broadcast' | 'export' | 'undo' | 'redo' | 'record' | 'notes' | 'fullscreen' | 'zoom' | 'navigation' | 'mergeShapes' | 'crop';

/**
 * Ribbon tab id. Mirrors React `ToolbarSection`, plus the contextual tabs
 * (Shape Format, Picture Format, ...) a selection brings up.
 */
declare type ToolbarSection = 'file' | 'home' | 'insert' | 'text' | 'arrange' | 'draw' | 'design' | 'transitions' | 'animations' | 'slideShow' | 'record' | 'review' | 'view' | 'help' | RibbonContextualTabId;

declare interface ToolbarTabDefinition {
    id: ToolbarTabId;
    labelKey: string;
}

/** A top-level ribbon tab. `record` intentionally shares its id with the quick-access Record button above: both surface the same recording feature, so hiding one hides the other. */
declare type ToolbarTabId = 'file' | 'home' | 'insert' | 'draw' | 'design' | 'transitions' | 'animations' | 'slideShow' | 'record' | 'review' | 'view' | 'help';

/** Narrow a ribbon `SupportedShapeType` to the EditorToolbar's `ShapePreset`. */
export declare function toShapePreset(t: SupportedShapeType): ShapePreset;

declare interface TouchGestureCallbacks {
    /** Called continuously during a pinch gesture with the new (clamped) scale. */
    onPinchZoom?: (newScale: number) => void;
    /** Called when a horizontal swipe is detected. direction: -1 = left, 1 = right. */
    onSwipe?: (direction: -1 | 1) => void;
    /** Called when a long-press is detected, with the press coordinates. */
    onLongPress?: (clientX: number, clientY: number) => void;
}

declare interface TrackedTextPosition {
    /** Internal identity, shared by snapshots that observed the same character. */
    readonly cell: TextPositionCell;
    readonly association: number;
}

/** Geometry patch emitted by the selection overlay during a drag/resize/rotate. */
export declare interface TransformPayload {
    id: string;
    x: number;
    y: number;
    width: number;
    height: number;
    rotation: number;
}

/**
 * Duration (ms) for each legacy `p:transition/@spd` speed.
 *
 * Measured against PowerPoint itself: the issue #131 deck's morph slides carry
 * `spd="slow"` and no `p14:dur`, and PowerPoint reports
 * `SlideShowTransition.Duration = 1.0`. Re-authoring that attribute and
 * re-reading it through COM gives fast=0.5s, med=0.75s, slow=1.0s - and the
 * same values for Morph as for every other effect, contradicting the earlier
 * assumption that Morph ignores `spd`.
 */
export declare const TRANSITION_SPEED_DURATION_MS: Readonly<Record<string, number>>;

/**
 * `slide-transition-fragment-types` - shared types and small pure helpers for
 * the multi-fragment cinematic transitions (`vortex`, `honeycomb`, `glitter`,
 * `shred`, `fracture`, `curtains`, `airplane`).
 *
 * These seven presets render in real PowerPoint as many independent
 * fragments, tiles, particles, or (for `airplane`) folded panels, not a
 * single animated layer - see `slide-transition-fragments.ts` for the
 * COM `CreateVideo` measurement writeup. A `FragmentedTransitionDescriptor`
 * is the pure, framework-neutral output every binding maps onto N clipped
 * copies of its own `SlideLayer`/`SlideCanvas` component: each fragment is a
 * full-size copy of the outgoing or incoming slide, clipped with `clip-path`
 * to its slice and animated with a shared `@keyframes` block (from
 * {@link FRAGMENT_TRANSITION_KEYFRAMES}) parameterised per fragment via CSS
 * custom properties, so the whole set is transform/opacity-only and
 * GPU-composited with no per-frame JS.
 *
 * @module render/slide-transition-fragment-types
 */
/** One fragment: a clipped, independently-animated copy of a slide layer. */
declare interface TransitionFragment {
    /** Stable id for keys / `data-*` attributes; unique within its layer. */
    id: string;
    /** `clip-path` value, in percentages of the full (unscaled) slide box. */
    clipPath: string;
    /**
     * CSS custom properties consumed by the shared `@keyframes` named by the
     * owning {@link FragmentedLayer.keyframesName}. Values are pre-formatted
     * (already unit-suffixed, e.g. `'34deg'`, `'-120%'`) so bindings can copy
     * them verbatim into an inline `style` object.
     */
    vars: Readonly<Record<string, string>>;
    /** `animation-delay`, in ms. */
    delayMs: number;
    /** `transform-origin`, e.g. `'50% 50%'`, so rotate/scale pivot correctly. */
    transformOrigin: string;
}

declare interface TransitionInput {
    type: PptxTransitionType;
    duration?: number;
    direction?: string;
    advanceAfterMs?: number;
}

/**
 * Shared value types used across the entire PPTX editor type system.
 *
 * Contains primitive enums, small interfaces, and the XML object alias
 * that almost every other type file imports.
 *
 * @module pptx-types/common
 */
/**
 * Underline style tokens from OOXML `a:rPr/@u`.
 *
 * These map directly to the OpenXML `ST_TextUnderlineType` simple type.
 *
 * @example
 * ```ts
 * const style: UnderlineStyle = "wavy";
 * // => "wavy" — one of: sng | dbl | heavy | dotted | dash | wavy | none | ...
 * ```
 */
declare type UnderlineStyle = 'sng' | 'dbl' | 'heavy' | 'dotted' | 'dottedHeavy' | 'dash' | 'dashHeavy' | 'dashLong' | 'dashLongHeavy' | 'dotDash' | 'dotDashHeavy' | 'dotDotDash' | 'dotDotDashHeavy' | 'wavy' | 'wavyHeavy' | 'wavyDbl' | 'words' | 'none';

/** An element whose type is not recognised by the parser. */
declare interface UnknownPptxElement extends PptxElementBase {
    type: 'unknown';
    /** Unrecognised graphicFrame extLst extensions, captured verbatim for round-trip. */
    extensionXml?: PptxGraphicFrameExtension[];
}

export declare function useAccessibility(slides: MaybeRefOrGetter<PptxSlide[]>, options?: MaybeRefOrGetter<AccessibilityCheckOptions>): UseAccessibilityResult;

/**
 * `useAccessibility`: reactive WCAG / PowerPoint-style accessibility checker
 * for the Vue viewer/editor.
 *
 * Mirrors `pptx-viewer-core`'s {@link checkPresentation} entry point, but
 * `checkPresentation` consumes a full `PptxData` object (it reads
 * `data.slides`). The composable only has the slide array to hand, so it
 * re-implements the same aggregation by calling the individual exported
 * `check*` functions over the slides and sorting the result identically
 * (by slide index, then severity: error → warning → tip).
 *
 * The result is fully reactive: whenever the `slides` source changes the
 * issue list and count recompute.
 *
 * @param slides - Reactive source of parsed slides (ref, getter, or value).
 * @param options - Optional check configuration mirroring
 *   {@link AccessibilityCheckOptions}.
 */
export declare interface UseAccessibilityResult {
    /** All detected issues, sorted by slide index then severity. */
    issues: ComputedRef<AccessibilityIssue[]>;
    /** Total number of detected issues. */
    issueCount: ComputedRef<number>;
}

/**
 * useAlignGroup: multi-selection alignment / distribution and group / ungroup
 * for the Vue editor. Each change is a single history entry. Extracted verbatim
 * from `PowerPointViewer.vue`.
 */
export declare function useAlignGroup(input: UseAlignGroupInput): {
    canGroup: ComputedRef<boolean>;
    canUngroup: ComputedRef<boolean>;
    canDistribute: ComputedRef<boolean>;
    selectionGroupable: ComputedRef<boolean>;
    onAlign: (edge: AlignEdge) => void;
    onDistribute: (axis: DistributeAxis) => void;
    onGroup: () => void;
    onUngroup: () => void;
};

export declare interface UseAlignGroupInput {
    selectedElements: ComputedRef<PptxElement[]>;
    selectedElementIds: Ref<string[]>;
    activeSlideIndex: Ref<number>;
    slides: Ref<PptxSlide[]>;
    /** Slide bounds in px; a lone element aligns against these (Align to Slide). */
    canvasSize?: Ref<{
        width: number;
        height: number;
    }>;
    pushHistory: () => void;
}

export declare function useAnimationPlayback(options: UseAnimationPlaybackOptions): UseAnimationPlaybackResult;

export declare interface UseAnimationPlaybackOptions {
    /** The active slide to build the native-animation timeline for. */
    slide: MaybeRefOrGetter<PptxSlide | undefined>;
    /** Presentation-level switch parsed from `p:showPr`. */
    showWithAnimation?: MaybeRefOrGetter<boolean | undefined>;
    /** Host-provided action-sound player (resolves + plays embedded sounds). */
    onPlayActionSound?: (soundPath: string) => void;
    /** Root element to scope media-command (`p:cmd`) target lookups to. */
    frameRoot?: () => HTMLElement | null;
    /**
     * The slide canvas size (px), in the same unit the elements' own
     * `x`/`y`/`width`/`height` are authored in. Lets `PresentationAnimationController
     * .fromSlide` resolve a `p:anim` formula that needs the animated shape's real
     * box (e.g. Grow And Turn's `-#ppt_w/2` fly-in) instead of falling back.
     */
    canvasSize?: MaybeRefOrGetter<{
        width: number;
        height: number;
    } | undefined>;
    /** The deck's resolved theme colour map, for a scheme-colour (`a:schemeClr`) animation stop. */
    themeColorMap?: MaybeRefOrGetter<Readonly<Record<string, string>> | undefined>;
    /**
     * `viewerOptions.advanced.pixelateMosaicAnimation`. `true` plays the
     * blocky mosaic reveal for `p:animEffect/@filter="pixelate"`; omitted or
     * `false` (the default, matching PowerPoint's own behaviour) snaps the
     * element to its end state. See `resolveFilterEffect`'s doc in
     * `pptx-viewer-shared`'s `animation-filter-effects.ts`.
     */
    pixelateMosaicAnimation?: MaybeRefOrGetter<boolean | undefined>;
}

export declare interface UseAnimationPlaybackResult {
    /** Reactive per-element native-animation state, keyed by element id. */
    presentationElementStates: Ref<Map<string, ElementAnimationState>>;
    /** The `@keyframes` CSS to inject once per slide. */
    presentationKeyframesCss: Ref<string>;
    /** Shape ids that trigger an interactive (`onShapeClick`) sequence. */
    interactiveTriggerShapeIds: Ref<ReadonlySet<string>>;
    /** Shape ids that trigger a hover (`onHover`) sequence. */
    hoverTriggerShapeIds: Ref<ReadonlySet<string>>;
    /** True when the main timeline has no more click-groups to reveal. */
    isComplete: Ref<boolean>;
    /**
     * True while the active slide shows its builds as already complete because
     * the presenter stepped BACKWARD onto it. The next back press replays the
     * slide instead of leaving it (PowerPoint's behaviour).
     */
    seededCompleted: Ref<boolean>;
    /** Seed the NEXT slide change as fully built (a backward step). */
    markNextEntryCompleted: () => void;
    /**
     * Reveal the next click-group. Returns `true` if a group was revealed, `false`
     * when playback is complete or animations are disabled (so the caller can fall
     * through to slide navigation).
     */
    advance: () => boolean;
    /** Rebuild the controller for the current slide and replay from the start. */
    reset: () => void;
    /** Play an interactive shape's sequence; `true` when it triggered one. */
    handleInteractiveShapeClick: (shapeId: string) => boolean;
    /** Play a hover shape's sequence; `true` when it triggered one. */
    handleHoverStart: (shapeId: string) => boolean;
    /** Reset a hover shape's sequence so the next hover replays it. */
    handleHoverEnd: (shapeId: string) => void;
    /** Clear all pending timers + the in-flight staged-build RAF. */
    clearTimers: () => void;
}

/**
 * `useAutosave`: debounced autosave for the Vue editor.
 *
 * Watches `slides`; on each change it marks the document dirty and
 * (re)arms a debounce timer. When the timer fires (and autosave is
 * enabled) it runs `onSave()`, transitioning `status`
 * `saving → saved | error`, stamping `lastSavedAt`, and clearing the
 * dirty flag. `saveNow()` performs the same save synchronously, cancelling
 * any pending debounce. The timer is torn down on scope dispose.
 */
export declare function useAutosave(options: UseAutosaveOptions): UseAutosaveResult;

export declare interface UseAutosaveOptions {
    /**
     * The editor's reactive slide array. Because the editor reassigns this
     * array immutably on every edit, a shallow `watch(slides, …)` fires per
     * edit, no `deep` needed.
     */
    slides: Ref<PptxSlide[]>;
    /**
     * The separate per-slide store of master/layout (template) elements.
     *
     * An edit made in edit-template mode rebuilds ONLY this map: it never
     * reassigns `slides`, because a template element does not live in
     * `slide.elements`. Watching `slides` alone therefore missed every
     * template-mode edit, and a user editing a master or layout got no crash
     * recovery at all. Svelte never had the bug because its equivalent effect
     * reads a value that already folds the template map in; watching the map
     * here reaches the same shape, and covers any FUTURE template mutation path
     * without that path having to remember to announce itself.
     */
    templateElements?: Ref<unknown>;
    /** Master on/off switch. When falsy the debounce timer never fires. */
    enabled?: Ref<boolean> | boolean;
    /**
     * Debounce window in milliseconds (e.g. `2000`). A `Ref` is re-read each
     * time the timer is armed, so File > Options > Save > AutoRecover cadence
     * changes apply to the next edit without re-mounting.
     */
    intervalMs: number | Ref<number>;
    /**
     * Host save callback: typically calls `getContent()` and persists/emits
     * the resulting bytes. May be sync or async; rejections flip status to
     * `'error'`.
     */
    onSave: () => void | Promise<void>;
    /** Injectable timer API for testing. Defaults to the global timers. */
    timers?: AutosaveTimerApi;
}

export declare interface UseAutosaveResult {
    /** Current autosave lifecycle status. */
    status: Ref<AutosaveStatus>;
    /** Epoch ms of the last successful save, or `null`. */
    lastSavedAt: Ref<number | null>;
    /** Force an immediate save, bypassing the debounce window. */
    saveNow: () => Promise<void>;
    /** True when there are unsaved edits pending. */
    isDirty: Ref<boolean>;
}

/**
 * Build the chart-editing helper bundle.
 *
 * @param element    reactive accessor for the selected chart element (or null).
 * @param chartData  reactive accessor for that element's chart data (or null).
 * @param emitUpdate emits the shallow `{ chartData }` patch up to the host.
 * @param getFollowDataPoint File > Options > Advanced > "Properties follow
 *   chart data point for current workbook", read fresh on every category
 *   removal. Defaults to PowerPoint's own default (`true`) when omitted.
 */
export declare function useChartEditing(element: ComputedRef<ChartPptxElement | null>, chartData: ComputedRef<PptxChartData | null>, emitUpdate: (next: PptxChartData) => void, getFollowDataPoint?: () => boolean): ChartEditing;

export declare function useCollaboration(options: UseCollaborationOptions): UseCollaborationResult;

export declare interface UseCollaborationOptions {
    /** Optional reactive configuration; replacing or clearing it starts or stops the session. */
    collaboration?: MaybeRefOrGetter<CollaborationConfig | undefined>;
    /** Host authorization, combined with the session's canonical read-only state. */
    canEdit?: MaybeRefOrGetter<boolean>;
    /** Whether an actual source file is still loading or failed to load. */
    sourcePending?: MaybeRefOrGetter<boolean>;
    sourceError?: MaybeRefOrGetter<boolean>;
    /** Optional retained serializer for elected-owner write-back; the scheduler guards stale results. */
    serialize?: (isCurrent: () => boolean) => Promise<Uint8Array | null> | Uint8Array | null;
    /** The editor's reactive slides ref (broadcast on local change). */
    slides: Ref< PptxSlide[]>;
    /** Called when a remote peer broadcasts a newer slide set. */
    onRemoteSlides: (slides: PptxSlide[]) => void;
    /** This user's cursor/label colour. */
    userColor?: string;
    /**
     * Slide canvas width/height (unscaled px) used to clamp incoming cursor
     * coordinates. Defaults to a generous bound when omitted.
     */
    canvasWidth?: Ref<number> | number;
    canvasHeight?: Ref<number> | number;
    /**
     * Return the source PPTX bytes for elected-writer write-back. Only called
     * when role === 'owner' and config.onWriteBack is provided.
     */
    getSourceBytes?: () => Uint8Array | null;
    /**
     * Return the separate per-slide master/layout (template) element store so the
     * elected-writer write-back can merge template edits back into the saved file.
     */
    getTemplateElements?: () => Record<string, PptxElement[]>;
    /**
     * Session-level save options (view properties, table styles, tags, deck
     * properties, ...), built the same way as the Save/Export path
     * (`buildDeckSaveOptions`). Without this the elected-writer write-back
     * called `handler.save(slides)` with NO options, so an owner's write-back
     * file dropped every session-level edit outside `slides`.
     */
    getSaveOptions?: () => PptxHandlerSaveOptions;
    /**
     * Monotonic counter bumped each time the content-load pipeline finishes
     * applying a parsed deck to viewer state. A local load that lands while the
     * shared doc already holds slides (a late joiner's bootstrap deck parsing
     * after the room state arrived) would silently clobber the synced slides;
     * each bump re-adopts the doc's slides when the room has content.
     */
    loadVersion?: Ref<number>;
    /** Why the last content load ran; see `shouldRoomSlidesReplaceLoad`. */
    getLoadOrigin?: () => CollabLoadOrigin;
}

export declare interface UseCollaborationResult {
    /** Shared custom-shell permissions, connection status and sanitized presence. */
    shellState: ComputedRef<CollaborationShellState>;
    /** The configuration attached by start() or the reactive collaboration option. */
    activeCollaboration: Ref<CollaborationConfig | null>;
    status: Ref< ConnectionStatus>;
    connected: Ref<boolean>;
    cursors: Ref<RemoteCursor[]>;
    remotePresences: Ref<RemotePresence[]>;
    connectedCount: ComputedRef<number>;
    active: Ref<boolean>;
    /** Blocks edits only while a session is read-only or awaiting host sync. */
    readOnly: Ref<boolean>;
    /** The local user's role in the active session (undefined when stopped). */
    activeRole: Ref<CollaborationRole | undefined>;
    followedClientId: Ref<number | null>;
    followedSlideIndex: ComputedRef<number | null>;
    broadcasterSlideIndex: ComputedRef<number | null>;
    start: (config: CollaborationConfig) => Promise<void>;
    stop: () => void;
    retry: () => Promise<void>;
    setCursor: (x: number, y: number) => void;
    setSelection: (ids: string[]) => void;
    setActiveSlide: (index: number) => void;
    followUser: (clientId: number | null) => void;
    /**
     * Interim ("live preview") Y.Doc write channel: publishes in-flight inline
     * editor text (and any other mid-gesture state) that has not yet reached
     * `slides`, so peers see typing as it happens instead of on commit. Dormant
     * until a session starts.
     */
    livePatcher: CollaborationLivePatcher;
}

/**
 * useCollaborationWiring: the real-time collaboration session lifecycle
 * (Share dialog two-way collaboration, one-way Broadcast, auto-start/stop from
 * a host-supplied `collaboration` prop, and local cursor/selection/active-slide
 * publishing), layered on top of the underlying `useCollaboration` Yjs
 * composable. Extracted verbatim from `PowerPointViewer.vue`.
 */
export declare function useCollaborationWiring(input: UseCollaborationWiringInput): UseCollaborationWiringResult;

export declare interface UseCollaborationWiringInput {
    slides: Ref<PptxSlide[]>;
    /**
     * Bumped by the load pipeline each time a parsed deck is applied to viewer
     * state; the session re-adopts the doc's slides on each bump so a slow local
     * load cannot clobber remotely-synced content.
     */
    loadVersion?: Ref<number>;
    /** Why the last content load ran; see `shouldRoomSlidesReplaceLoad`. */
    getLoadOrigin?: () => CollabLoadOrigin;
    getTemplateElements: () => Record<string, PptxElement[]>;
    /** Retain the loaded source bytes for elected-writer (role 'owner') write-back. */
    getSourceBytes: () => Uint8Array | null;
    /**
     * Session-level save options (view properties, table styles, tags, deck
     * properties, ...), built the same way as the Save/Export path. Without
     * this the elected-writer write-back dropped every session-level edit
     * outside `slides`.
     */
    getSaveOptions: () => PptxHandlerSaveOptions;
    /** This user's initial cursor/label colour (read once, matching `useCollaboration`'s own option). */
    initialUserColor: string | undefined;
    canvasWidth: ComputedRef<number>;
    canvasHeight: ComputedRef<number>;
    /** Live `props.collaboration`, watched to auto-start/stop a session. */
    collaborationProp: () => CollaborationConfig | undefined;
    selectedElementIds: Ref<string[]>;
    activeSlideIndex: Ref<number>;
    goTo: (index: number) => void;
    effectiveZoom: ComputedRef<number>;
    /** Display name used for the presenter role when starting a broadcast. */
    authorName: () => string | undefined;
    onStartCollaboration: (config: CollaborationConfig) => void;
    onStopCollaboration: () => void;
}

export declare interface UseCollaborationWiringResult {
    collab: UseCollaborationResult;
    collabActive: Ref<boolean>;
    /** The config the active session was started with (null when stopped); the
     * Share dialog's active view reads the local user's name/colour from this. */
    activeCollaboration: Ref<CollaborationConfig | null>;
    shareOpen: Ref<boolean>;
    onShareStart: (config: CollaborationConfig) => void;
    onShareStop: () => void;
    onCollabPointerMove: (event: PointerEvent) => void;
    broadcastOpen: Ref<boolean>;
    broadcastViewerUrl: ComputedRef<string>;
    onBroadcastStart: (config: {
        roomId: string;
        serverUrl: string;
        transport?: CollaborationTransport;
    }) => void;
    onBroadcastStop: () => void;
}

/**
 * Compute the recoloured image source for a clrChange effect.
 *
 * @returns `displaySrc` - the processed data-URL once ready, otherwise the
 *   original `src` (so the image is always visible during/after processing).
 */
export declare function useColorChangeImage(options: UseColorChangeImageOptions): {
    displaySrc: ComputedRef<string | undefined>;
};

/** Reactive inputs accepted by {@link useColorChangeImage}. */
export declare interface UseColorChangeImageOptions {
    /** Original image source (data-URL or blob URL); may be `undefined`. */
    src: Ref<string | undefined> | ComputedRef<string | undefined>;
    /** The parsed clrChange effect, or `undefined` when the effect is absent. */
    clrChange: Ref<ClrChangeEffect | undefined> | ComputedRef<ClrChangeEffect | undefined>;
    /** Optional tolerance override (0-100); falls back to the shared default. */
    tolerancePct?: Ref<number | undefined> | ComputedRef<number | undefined>;
}

export declare function useComments(options: UseCommentsOptions): UseCommentsResult;

/**
 * `useComments`: Vue composable backing the comments panel/editor.
 *
 * ## Data model & how comments link to slides
 *
 * In `pptx-viewer-core`, comments are stored **per slide** on
 * `PptxSlide.comments?: PptxComment[]`. The {@link PptxComment} interface itself
 * carries **no** slide-reference field (no `slideId`/`slideIndex`); a comment's
 * owning slide is implied purely by which slide's `comments` array it lives in.
 *
 * Because of that, the "deck-wide list filtered to the active slide" is realised
 * by the **host**: it slices `slides[activeSlideIndex].comments` into the
 * `comments` ref passed here. This composable therefore treats `comments` as the
 * active slide's comment list (the deck slice for `activeSlideIndex`) and the
 * mutators return the **new full comment array** for that slide, which the host
 * writes back history-aware (e.g. `slides[i].comments = next`).
 *
 * `activeSlideIndex` is retained in the options for symmetry and so callers /
 * marker-positioning can reason about which slide is active.
 *
 * No `any`; all regexes use the `/u` flag; framework-agnostic core types only.
 */
export declare interface UseCommentsOptions {
    /**
     * The active slide's comments (the deck slice for `activeSlideIndex`).
     * `PptxComment` has no slide field, so the host slices the per-slide
     * `PptxSlide.comments` into this ref.
     */
    comments: MaybeRefOrGetter<PptxComment[]>;
    /** Index of the slide whose comments these are. */
    activeSlideIndex: MaybeRefOrGetter<number>;
    /** Display name written as the `author` of newly-created comments. */
    authorName: MaybeRefOrGetter<string>;
}

export declare interface UseCommentsResult {
    /** The active slide's comments (mirrors the input ref reactively). */
    slideComments: ComputedRef<PptxComment[]>;
    /**
     * Append a new comment to the active slide. `mentions` (from the `@`-mention
     * typeahead; `insertCommentMention`, `pptx-viewer-shared`) is stitched onto
     * the created comment locally: `addCommentToList` (shared) has no `mentions`
     * parameter, so this patches the comment it appends (always the last array
     * entry - see `addCommentToList`) after the fact rather than duplicating its
     * id-generation and array-shape logic here.
     * @returns the NEW full comment array for the active slide, or `null` when
     *   `text` is blank.
     */
    addComment: (text: string, x?: number, y?: number, mentions?: PptxCommentMention[]) => PptxComment[] | null;
    /**
     * Remove a comment (by id) from the active slide.
     * @returns the NEW full comment array, or `null` when nothing changed.
     */
    removeComment: (id: string) => PptxComment[] | null;
    /**
     * Toggle the `resolved` flag of a comment (by id) on the active slide.
     * @returns the NEW full comment array, or `null` when nothing changed.
     */
    resolveComment: (id: string) => PptxComment[] | null;
    /**
     * Append a threaded reply to the comment `parentId` on the active slide. The
     * reply is nested inside the parent's `replies` array and stamped with
     * `threadId = parentId` (mirroring React's `handleSubmitReply`). `mentions`
     * is stitched onto the created reply the same way {@link addComment} does.
     * @returns the NEW full comment array, or `null` when the text is blank or
     *   the parent is not found.
     */
    replyToComment: (parentId: string, text: string, mentions?: PptxCommentMention[]) => PptxComment[] | null;
}

/**
 * useCommentsWiring: the comments panel, its numbered on-canvas markers, and
 * the history-aware commit path that writes a new comment array back onto the
 * active slide. Layered on top of the underlying `useComments` composable.
 * Extracted verbatim from `PowerPointViewer.vue`.
 */
export declare function useCommentsWiring(input: UseCommentsWiringInput): UseCommentsWiringResult;

export declare interface UseCommentsWiringInput {
    activeSlide: ComputedRef<PptxSlide | undefined>;
    activeSlideIndex: Ref<number>;
    slides: Ref<PptxSlide[]>;
    authorName: ComputedRef<string>;
    pushHistory: () => void;
}

export declare interface UseCommentsWiringResult {
    showComments: Ref<boolean>;
    activeComments: ComputedRef<PptxComment[]>;
    commentsApi: UseCommentsResult;
    onCommentMarkerClick: (id: string) => void;
    commitComments: (next: PptxComment[] | null) => void;
}

/**
 * useContextMenu: right-click / long-press element context menu for the Vue
 * editor. Owns the open/position state, derives the item list (including the
 * table row/column/merge entries gated on the current cell selection), and
 * dispatches each action. Extracted verbatim from `PowerPointViewer.vue`.
 */
export declare function useContextMenu(input: UseContextMenuInput): UseContextMenuResult;

export declare interface UseContextMenuInput {
    canEdit: () => boolean;
    findActiveElement: (id: string) => PptxElement | undefined;
    tableSelection: Ref<TableSelectionState | null>;
    hasClipboard: ComputedRef<boolean>;
    /**
     * Two or more elements are selected. Ungroup needs no equivalent flag: the
     * shared list derives it from the right-clicked element's own type, which is
     * how React decides it too.
     */
    canGroup: ComputedRef<boolean>;
    /** Lock-only half of Group/Ungroup gating (`a:spLocks`/`a:grpSpLocks` `@noGrp`); disables, not hides. */
    selectionGroupable: ComputedRef<boolean>;
    editTemplateMode: Ref<boolean>;
    selectedElementIds: Ref<string[]>;
    /**
     * The element whose inline text editor is open, if any. The editor is a
     * sibling overlay rather than a child of the element, so a right-click inside
     * it hit-tests to nothing; this is what the menu falls back to.
     */
    inlineEditingElementId: Ref<string | null>;
    /** Whether the properties inspector is open; the format-object trio opens it. */
    inspectorOpen: Ref<boolean>;
    /** "Edit Text": the same effect as double-clicking the element. */
    enterInlineEdit: (id: string) => void;
    ops: EditorOperations;
    cutElement: (id: string) => void;
    copyElement: (id: string) => void;
    pasteElement: () => void;
    onGroup: () => void;
    onUngroup: () => void;
    openHyperlinkDialog: (id: string) => void;
    /** "Add Comment": open the comments panel, as React's menu does. */
    onAddComment?: () => void;
    /** Whether the AI assistant is enabled (adds the "Ask AI" / "Fix with AI" entries). */
    aiEnabled?: () => boolean;
    /** Open the AI panel scoped to the current element (empty composer). */
    onAskAi?: () => void;
    /** Open the AI panel with a prefilled "fix this element" directive (not sent). */
    onFixAi?: () => void;
    /**
     * Right-click landed on empty canvas (no interactive element under the
     * cursor). Wired to `useCanvasContextMenu`'s opener; when omitted the
     * click is left unhandled (browser's own menu), matching the old behaviour.
     */
    onEmptyCanvasContextMenu?: (x: number, y: number) => void;
    /** The host's resolved UI customisation (hidden commands / disabled menu). */
    customization?: () => ResolvedCustomization;
    /** "Edit Points": offered (per the shared lock / type rules) only when wired. */
    onEditPoints?: (element: PptxElement) => void;
    /** Merge Shapes + picture Crop (the `merge-*` and `crop` entries). */
    mergeCrop?: MergeCropController;
}

export declare interface UseContextMenuResult {
    contextMenu: Ref<ContextMenuState>;
    contextItems: ComputedRef<ContextMenuItem[]>;
    onCanvasContextMenu: (event: MouseEvent) => void;
    onContextSelect: (actionId: string) => void;
}

export declare function useCustomShows(input: UseCustomShowsInput): UseCustomShowsResult;

/**
 * `useCustomShows`: list/create/rename/delete custom slide shows plus editing
 * the ordered slide-id list of a show.
 *
 * Vue port of the React `useDialogCustomShows` hook (`packages/react/src/
 * viewer/hooks/useDialogCustomShows.ts`). A {@link PptxCustomShow} names an
 * ordered subset of slides (by relationship id) that can be presented
 * independently of the full deck.
 *
 * The composable is DOM-free and unit-testable: it never prompts. Names are
 * supplied by the caller (the React hook used `window.prompt`; in Vue that
 * lives in the component). Each mutating operation snapshots undo/redo history
 * *first* (via `pushHistory`) and reassigns `customShows.value` with a fresh
 * array so `shallowRef`-backed state stays reactive.
 */
export declare interface UseCustomShowsInput {
    /** Reactive custom-show list (typically a `shallowRef<PptxCustomShow[]>`). */
    customShows: Ref<PptxCustomShow[]>;
    /** Reactive slide list, used to resolve slide relationship ids. */
    slides: Ref<PptxSlide[]>;
    /** Index of the currently focused slide. */
    activeSlideIndex: Ref<number>;
    /** Snapshot current state onto the undo stack before mutating. */
    pushHistory: () => void;
}

export declare interface UseCustomShowsResult {
    /**
     * Create a new custom show. When `seedWithActiveSlide` (default `true`) and
     * the active slide carries an `rId`, that slide seeds the show. Returns the
     * id of the created show.
     */
    createCustomShow: (name: string, seedWithActiveSlide?: boolean) => string;
    /** Rename the custom show with id `showId`. No-op when the show is missing. */
    renameCustomShow: (showId: string, newName: string) => void;
    /** Delete the custom show with id `showId`. */
    deleteCustomShow: (showId: string) => void;
    /** Toggle whether the slide (by relationship id) is in the show. */
    toggleSlideInShow: (showId: string, slideRId: string) => void;
    /** Replace a show's ordered slide-relationship-id list wholesale. */
    setShowSlides: (showId: string, slideRIds: string[]) => void;
    /** Move a slide within a show's order from `from` to `to`. */
    moveSlideInShow: (showId: string, from: number, to: number) => void;
    /** Whether the active slide is currently part of the given show. */
    isActiveSlideInShow: (showId: string) => boolean;
    /** The relationship id of the active slide, if any. */
    activeSlideRId: ComputedRef<string | undefined>;
}

/**
 * useCustomShowsWiring: Slide Show ▸ Custom Shows panel and ribbon toggle
 * state, layered on top of the underlying `useCustomShows` CRUD composable.
 * Owns which show is "active" for the ribbon's create/rename/delete/toggle
 * actions. Extracted verbatim from `PowerPointViewer.vue`.
 */
export declare function useCustomShowsWiring(input: UseCustomShowsWiringInput): UseCustomShowsWiringResult;

export declare interface UseCustomShowsWiringInput {
    customShows: Ref<PptxCustomShow[]>;
    slides: Ref<PptxSlide[]>;
    activeSlideIndex: Ref<number>;
    activeSlide: ComputedRef<PptxSlide | undefined>;
    /**
     * `p:showPr`, which carries the show the deck was AUTHORED to open into
     * ("Set Up Slide Show > Custom show"). Optional so existing call sites and
     * tests keep working; without it the deck always opens in full.
     */
    presentationProperties?: Ref<PptxPresentationProperties>;
    pushHistory: () => void;
}

export declare interface UseCustomShowsWiringResult {
    showCustomShows: Ref<boolean>;
    activeCustomShowId: Ref<string | null>;
    customShowOps: UseCustomShowsResult;
    isCurrentSlideInActiveShow: ComputedRef<boolean>;
    onCreateCustomShow: (name: string) => void;
    onDeleteCustomShow: (showId: string) => void;
    onRenameActiveCustomShow: () => void;
    onDeleteActiveCustomShow: () => void;
    onToggleCurrentSlideInActiveShow: () => void;
}

/**
 * Wrap `callback` so it only fires once calls stop for `delay` ms.
 *
 * @param callback the function to debounce.
 * @param delay    quiet-period in milliseconds (defaults to 180ms).
 */
export declare function useDebouncedCallback<A extends readonly unknown[]>(callback: (...args: A) => void, delay?: number): DebouncedCallback<A>;

/**
 * useDocumentPropertiesDialog: File ▸ Document Properties (General /
 * Statistics / Custom tabs). Extracted verbatim from `PowerPointViewer.vue`.
 */
export declare function useDocumentPropertiesDialog(input: UseDocumentPropertiesDialogInput): UseDocumentPropertiesDialogResult;

export declare interface UseDocumentPropertiesDialogInput {
    coreProperties: Ref<PptxCoreProperties | undefined>;
    customProperties: Ref<PptxCustomProperty[]>;
    appProperties: Ref<PptxAppProperties | undefined>;
}

export declare interface UseDocumentPropertiesDialogResult {
    propertiesOpen: Ref<boolean>;
    onPropertiesSave: (patch: DocumentPropertiesSavePatch) => void;
}

/** Reactive Vue adapter around the shared live document-statistics computation. */
export declare function useDocumentStatistics(slides: MaybeRefOrGetter<PptxSlide[]>, coreProperties: MaybeRefOrGetter<PptxCoreProperties | undefined>): ComputedRef<DocumentStatistics>;

/**
 * @param slides Reactive reference to the live slide array the editor mutates.
 *               A `shallowRef` is recommended for large decks.
 * @param templateElementsBySlideId Optional reactive store of the per-slide
 *               master/layout (template) elements, snapshotted alongside slides
 *               so edits in `editTemplateMode` are undoable.
 * @param options Optional tuning knobs (undo depth).
 */
export declare function useEditorHistory(slides: Ref<PptxSlide[]>, templateElementsBySlideId?: Ref<TemplateElementMap>, options?: UseEditorHistoryOptions): EditorHistoryResult;

/** Optional tuning knobs for the history stack. */
export declare interface UseEditorHistoryOptions {
    /**
     * Maximum undo depth. Defaults to `MAX_HISTORY_ENTRIES`; File > Options >
     * Advanced > "Maximum number of undos" threads `resolveHistoryDepth` here.
     */
    maxDepth?: number;
}

/**
 * useEditorKeyboard: the root keydown handler plus the config-driven shortcut
 * registry it delegates to (undo/redo/copy/cut/paste/duplicate/delete/select-
 * all/nudge/slide-nav/escape). Find (Ctrl+F) and the shortcut-help overlay
 * ("?" or Ctrl+/) resolve inside the shared keymap, so nothing is intercepted
 * ahead of the registry any more. Extracted from `PowerPointViewer.vue`.
 */
export declare function useEditorKeyboard(input: UseEditorKeyboardInput): UseEditorKeyboardResult;

export declare interface UseEditorKeyboardInput {
    canEdit: () => boolean;
    canPaste?: () => boolean;
    hasSelection: ComputedRef<boolean>;
    /** A slide show (or rehearsal) is actually running, not merely previewing. */
    presenting: Ref<boolean>;
    findOpen: Ref<boolean>;
    selectedElementIds: Ref<string[]>;
    activeSlide: ComputedRef<PptxSlide | undefined>;
    activeSlideIndex: Ref<number>;
    slides: Ref<PptxSlide[]>;
    templateElementsBySlideId: Ref<TemplateElementMap>;
    pushHistory: () => void;
    undo: () => void;
    redo: () => void;
    copyElement: (id: string) => void;
    cutElement: (id: string) => void;
    pasteElement: () => void;
    /** Open the Paste Special dialog (Ctrl/Cmd+Alt+V). */
    onPasteSpecial: () => void;
    duplicateSelected: () => void;
    deleteSelected: () => void;
    goPrev: () => void;
    goNext: () => void;
    onEscape: () => void;
    /** Group the multi-selection into one group element (Ctrl/Cmd+G). */
    onGroup?: () => void;
    /** Ungroup the selected group (Ctrl/Cmd+Shift+G). */
    onUngroup?: () => void;
    /** F5: start the show from its first slide (same as the ribbon's "From Beginning"). */
    presentFromBeginning: () => void;
    /** Shift+F5: start the show from the active slide (same as "From Current Slide"). */
    startPresenting: () => void;
    /** Id of the element under active inline edit, or `null`. Lets live-format chords survive the typing gate. */
    inlineEditingElementId: Ref<string | null>;
    /** Whether a table cell is actively being edited. Same purpose as `inlineEditingElementId`. */
    tableEditorIsEditing: () => boolean;
    /** The armed drawing tool; shortcuts stand down unless it is `'select'`. */
    activeTool: () => string;
    /** The current selection's elements, for reading the effective font size. */
    selectedElements: ComputedRef<PptxElement[]>;
    /** Select one element non-additively (Tab / Shift+Tab cycling). */
    selectElement: (id: string, additive: boolean) => void;
    /** Apply a text-style delta to the selection (Home ▸ Text section's own path). */
    ribbonUpdateTextStyle: (updates: Partial<TextStyle>) => void;
    /** Insert a new slide after the active one (Ctrl/Cmd+M). */
    addSlide: () => void;
    /** Open the hyperlink dialog for the current selection (Ctrl/Cmd+K). */
    openHyperlinkForSelection: () => void;
    /** Arm the format painter from the current selection (Ctrl/Cmd+Shift+C). */
    toggleFormatPainter: () => void;
    /** Apply the copied format to one element (used by `pasteFormat`). */
    applyFormatToTarget: (id: string) => void;
    /** Disarm the format painter without applying (used after `pasteFormat`). */
    cancelFormatPainter: () => void;
    /** The host's resolved UI customisation (keyboard remaps, `presentMode`). */
    customization?: () => ResolvedCustomization;
}

export declare interface UseEditorKeyboardResult {
    showShortcuts: Ref<boolean>;
    shortcuts: UseKeyboardShortcutsResult;
    onEditorKeydown: (event: KeyboardEvent) => void;
    /** Copy the first selected element to the in-memory clipboard (also used by the ribbon). */
    copySelected: () => void;
    /** Cut the first selected element to the in-memory clipboard (also used by the ribbon). */
    cutSelected: () => void;
    /** Select every element on the active slide (Ctrl+A, and Home > Editing > Select All). */
    selectAllElements: () => void;
}

export declare function useEditorOperations(input: UseEditorOperationsInput): EditorOperations;

export declare interface UseEditorOperationsInput {
    /** Live slide array. A `shallowRef` is recommended for large decks. */
    slides: Ref<PptxSlide[]>;
    /** Index of the slide CRUD/transform operations act upon. */
    activeSlideIndex: Ref<number>;
    /**
     * Snapshot-before-mutate hook. Called immediately before each committed
     * change. Pass `useEditorHistory(slides).pushHistory`.
     */
    pushHistory: () => void;
    /**
     * Optional selection state (element ids). When provided, operations keep it
     * in sync: newly added/duplicated elements become selected, removed ones are
     * deselected. When omitted, an internally-owned selection ref is used.
     */
    selectedElementIds?: Ref<string[]>;
    /**
     * Optional separate store of the per-slide master/layout (template) elements.
     * When provided, id-routed operations (update / remove / transform / text /
     * z-order) targeting a template id (`master-` / `layout-` prefix) mutate this
     * store for the active slide instead of `slides`.
     */
    templateElementsBySlideId?: Ref<TemplateElementMap>;
}

export declare function useElementDrag(input: UseElementDragInput): {
    hasActivePointerInteraction: () => boolean;
    startElementDrag: (id: string, event: PointerEvent, wasSelected: boolean) => void;
    /** Stop window listeners when a custom shell detaches or becomes read-only. */
    cancelElementDrag: () => void;
    onTransformStart: (payload?: {
        id: string;
    }) => void;
    onTransform: (payload: TransformPayload) => void;
    onTransformEnd: (payload: TransformPayload) => void;
    onAdjustStart: () => void;
    onAdjust: (payload: {
        id: string;
        adjustments: Record<string, number>;
    }) => void;
    onAdjustEnd: (payload: {
        id: string;
        adjustments: Record<string, number>;
    }) => void;
    onConnectorEndpoint: (payload: {
        id: string;
        element: PptxElement;
    }) => void;
    snapToShape: Ref<boolean>;
    snapToGrid: Ref<boolean>;
    snapLines: Ref< SnapLine[]>;
    guides: Ref< Guide[]>;
    addGuide: (axis: "h" | "v", position?: number) => void;
    onMoveGuide: (payload: {
        id: string;
        position: number;
    }) => void;
    onRemoveGuide: (id: string) => void;
};

export declare interface UseElementDragInput {
    findActiveElement: (id: string) => PptxElement | undefined;
    pushHistory: () => void;
    effectiveZoom: ComputedRef<number>;
    activeTemplateElements: ComputedRef<PptxElement[]>;
    activeSlide: ComputedRef<PptxSlide | undefined>;
    activeSlideIndex: Ref<number>;
    slides: Ref<PptxSlide[]>;
    templateElementsBySlideId: Ref<TemplateElementMap>;
    canvasSize: Ref<{
        width: number;
        height: number;
    }>;
    enterInlineEdit: (id: string) => void;
    /**
     * Grid spacing in CSS px, derived from the deck's authored
     * `viewProperties.gridSpacing` via the shared `computeGridSpacingPx`
     * (falls back to `DEFAULT_GRID_SIZE` when the deck has none or hasn't
     * loaded yet). A `ComputedRef` like `effectiveZoom`, so a later deck load
     * is picked up without re-creating this composable.
     */
    gridSpacingPx?: ComputedRef<number>;
}

/**
 * useElementDrag: canvas pointer-drag-to-move, resize/rotate transform, shape
 * adjustment, plus the View-tab snap + alignment-guide state that those gestures
 * consume. One history entry is snapshotted at gesture start; live patches during
 * the gesture bypass history. Extracted verbatim from `PowerPointViewer.vue`.
 */
/** The drag/transform/adjust surface, inferred so it cannot drift from the impl. */
export declare type UseElementDragResult = ReturnType<typeof useElementDrag>;

/**
 * useElementInsertion: Insert-tab element creation for the Vue editor.
 *
 * Owns the hidden image/media `<input>` refs and every "add a new element"
 * handler (text / shape / table / chart / image / media / action button /
 * new slide from layout). Each newly-created element is centred on the slide
 * and selected. Extracted verbatim from `PowerPointViewer.vue`.
 */
export declare function useElementInsertion(input: UseElementInsertionInput): UseElementInsertionResult;

export declare interface UseElementInsertionInput {
    canvasSize: Ref<{
        width: number;
        height: number;
    }>;
    ops: EditorOperations;
    selectedElementIds: Ref<string[]>;
    slides: Ref<PptxSlide[]>;
    activeSlideIndex: Ref<number>;
    pushHistory: () => void;
    handler: ShallowRef<PptxHandler | null>;
    /**
     * The per-slide store of inherited layout / master artwork, refreshed when a
     * slide is re-mapped onto a different layout. Optional so callers that never
     * switch layouts (tests, read-only hosts) need not thread it through.
     */
    templateElementsBySlideId?: Ref<TemplateElementMap>;
}

export declare interface UseElementInsertionResult {
    imageInputRef: Ref<HTMLInputElement | null>;
    mediaInputRef: Ref<HTMLInputElement | null>;
    addText: () => void;
    addShape: (preset: ShapePreset) => void;
    addTable: () => void;
    addChart: (chartKind: InsertChartKind) => void;
    addField: (fieldType: string, value?: string) => void;
    openImagePicker: () => void;
    onImageFileSelected: (e: Event) => void;
    openMediaPicker: () => void;
    onMediaFileSelected: (e: Event) => void;
    addActionButton: (shapeType: string) => void;
    insertSlideFromLayout: (layoutPath: string, layoutName?: string) => Promise<void>;
    /** Re-map the active slide onto another layout of its master. */
    applyLayoutToActiveSlide: (layoutPath: string) => Promise<void>;
    /**
     * Build the artwork thumbnails the New Slide / Layout galleries draw.
     *
     * A callback rather than state: parsing every layout is only worth doing
     * once the user opens one of those menus, and core memoises the result.
     */
    loadLayoutPreviews: () => Promise<PptxLayoutPreview[]>;
}

export declare function useEmbeddedFonts(fonts: MaybeRefOrGetter<PptxEmbeddedFont[]>): UseEmbeddedFontsResult;

/**
 * `useEmbeddedFonts`: Vue port of the embedded-font injection logic in the
 * React `useFontInjection` hook (the `@font-face` half).
 *
 * Given the embedded fonts parsed out of a `.pptx` by `pptx-viewer-core`, this
 * composable builds `@font-face` CSS rules and injects them into the document
 * so that slides render with the typefaces the author embedded. The injected
 * `<style>` element is appended to `<head>` and removed on scope dispose.
 *
 * The core load pipeline (`PptxHandlerRuntimeEmbeddedFonts`) already
 * de-obfuscates the OOXML XOR layer and produces a ready-to-use `dataUrl` for
 * each style variant. One {@link PptxEmbeddedFont} therefore corresponds to a
 * single style variant (regular / bold / italic / boldItalic), distinguished by
 * its `bold` and `italic` flags: a font with regular + bold data yields two
 * entries and two `@font-face` rules.
 *
 * As a defence-in-depth fallback, if an entry arrives without a usable
 * `dataUrl` but carries the obfuscated `originalPartBytes` plus a `fontGuid`,
 * this composable de-obfuscates the bytes itself (via core's `deobfuscateFont`)
 * and mints an object URL so the variant can still be registered.
 *
 * @param fonts - Reactive source of the parsed embedded fonts (the host feeds
 *   these from `PptxData.embeddedFonts`).
 * @returns Reactive `fontFaceCss` (the generated stylesheet text) and
 *   `fontFamilies` (the distinct embedded family names, with substitution
 *   fallbacks resolved for downstream `font-family` use).
 */
export declare interface UseEmbeddedFontsResult {
    /** The generated `@font-face` stylesheet text (also injected into `<head>`). */
    fontFaceCss: ComputedRef<string>;
    /**
     * Distinct CSS `font-family` strings for the embedded families, each with
     * substitution fallbacks resolved (e.g. `'"Calibri", "Carlito", …'`).
     */
    fontFamilies: ComputedRef<string[]>;
}

/**
 * Export composable: render slides to PNG / PDF.
 *
 * Rasterisation is delegated to the injected `rasterizeSlide` (the host wires
 * `html2canvas-pro` over an off-screen slide stage). `jspdf` is loaded lazily so
 * it stays out of the main chunk. Vue port of the React `useExportHandlers`
 * (viewer-first subset: PNG + PDF; GIF/video deferred).
 */
export declare function useExport(options: UseExportOptions): UseExportResult;

export declare interface UseExportOptions {
    slides: Ref<PptxSlide[]>;
    canvasSize: Ref<CanvasSize>;
    rasterizeSlide: RasterizeSlide;
    /**
     * PNG-export only: returns the full `RasterizeElementResult` (tiled
     * `png-bytes` included) instead of a plain canvas. Optional so existing
     * test fixtures that only configure `rasterizeSlide` keep working;
     * `exportSlidePng` falls back to wrapping `rasterizeSlide`'s canvas when
     * omitted.
     */
    rasterizeSlideToRaster?: (index: number) => Promise<RasterizeElementResult>;
    /**
     * PDF export only: returns the slide's raw per-tile canvases (never
     * stitched) instead of a plain canvas. Optional so existing test fixtures
     * that only configure `rasterizeSlide` keep working; `exportPdf` falls
     * back to `rasterizeSlide`'s single canvas (unchanged, one `addImage`
     * per page) when omitted.
     */
    rasterizeSlideToTiles?: (index: number) => Promise<RasterizeElementTilesResult>;
    /** Base file name (without extension) for downloads. Defaults to `presentation`. */
    fileName?: Ref<string> | string;
}

export declare function useExportProgress(options: UseExportProgressOptions): UseExportProgressResult;

/**
 * useExportProgress: drives the `ExportProgressModal` while a multi-slide export
 * (PDF / GIF / WebM) runs. Vue counterpart of the React `useExportHandlers`
 * modal lifecycle.
 *
 * It owns the modal's reactive state (open / title / progress / status) plus the
 * `AbortController` the export loops check between slides, and wraps each export
 * in a `begin → run → end` envelope so the orchestrator only has to call
 * `onExportPdf()` / `onExportGif()` / `onExportWebm()` and render the modal.
 *
 * All percentage maths + status labels come from `pptx-viewer-shared`
 * (`export-progress.ts`) so React, Vue, and Angular show identical progress.
 */
export declare interface UseExportProgressOptions {
    /** PNG/PDF export composable (its `exportPdf` accepts progress + signal). */
    exporter: UseExportResult;
    /** GIF/WebM export composable (its exporters accept progress + signal). */
    mediaExport: UseMediaExportResult;
}

export declare interface UseExportProgressResult {
    /** Whether the progress modal is visible. */
    exportModalOpen: Ref<boolean>;
    /** Modal heading (e.g. "Export as PDF"). */
    exportModalTitle: Ref<string>;
    /** Current progress, 0-100. */
    exportProgress: Ref<number>;
    /** Status line under the bar (e.g. "Rendering slide 3 of 10..."). */
    exportStatusMessage: Ref<string>;
    /** Run the PDF export with the progress modal wired. */
    runPdf: () => Promise<void>;
    /** Run the GIF export with the progress modal wired. */
    runGif: () => Promise<void>;
    /** Run the WebM video export with the progress modal wired. */
    runWebm: () => Promise<void>;
    /** Cancel the in-flight export (aborts the loop, closes the modal). */
    cancelExport: () => void;
}

export declare interface UseExportResult {
    /** True while an export is running (disable UI / show a spinner). */
    exporting: Ref<boolean>;
    /** Export a single slide as a PNG download. Defaults to the given index. */
    exportSlidePng: (index: number) => Promise<void>;
    /** Export every slide as a multi-page PDF (one slide per page). */
    exportPdf: (options?: ExportPdfOptions) => Promise<void>;
}

/**
 * useExportWiring: PNG/PDF/GIF/WebM export plus Save-As download and
 * copy-slide-as-image, all driven off one off-screen `rasterizeSlide` stage
 * (also reused by the Print dialog). Extracted verbatim from
 * `PowerPointViewer.vue`.
 */
export declare function useExportWiring(input: UseExportWiringInput): UseExportWiringResult;

export declare interface UseExportWiringInput {
    /** The merged (template-inclusive) slides; the off-screen stage renders one at a time. */
    mergedSlides: Ref<PptxSlide[]> | ComputedRef<PptxSlide[]>;
    slides: Ref<PptxSlide[]>;
    slideCount: ComputedRef<number>;
    canvasSize: Ref<CanvasSize>;
    activeSlideIndex: Ref<number>;
    saveAs: (format: PptxSaveFormat) => Promise<Uint8Array>;
    fileName?: () => string | undefined;
    /** Snapshot the live deck (slides + presentation-level state) for JSON export. */
    getDeckData: () => PptxData;
    /**
     * File > Options > Advanced > "Image Size and Quality"
     * (`resolveImageResolutionScale`), read fresh on every `rasterizeSlide()`
     * call so a mid-session change applies without reconstructing this
     * composable. A getter (not a `Ref`) so it can be wired in even though
     * `viewerOptions` is not available yet at this composable's call site.
     * The raw multiplier (default preset = 1), applied on top of the baseline
     * 2x capture scale; see the `rasterizeSlide` body.
     */
    imageExportScale?: () => number;
    /**
     * Live File > Options getter, read only once a Save-As download actually
     * completes (feedback sound, AutoRecover-snapshot discard). Omitted in
     * tests that don't exercise those behaviors.
     */
    getOptions?: () => ViewerOptions;
    /** IndexedDB key for this deck's AutoRecover snapshot, read at the same time. */
    filePath?: () => string | undefined;
}

export declare interface UseExportWiringResult {
    exportStageRef: Ref<HTMLElement | null>;
    exportSlide: ComputedRef<PptxSlide | undefined>;
    rasterizeSlide: (index: number, scaleMultiplier?: number) => Promise<HTMLCanvasElement>;
    rasterizeSlideToRaster: (index: number, scaleMultiplier?: number) => Promise<RasterizeElementResult>;
    rasterizeSlideToTiles: (index: number, scaleMultiplier?: number) => Promise<RasterizeElementTilesResult>;
    exporter: UseExportResult;
    mediaExport: UseMediaExportResult;
    exportProgressCtl: UseExportProgressResult;
    isExporting: ComputedRef<boolean>;
    onExportPng: () => void;
    onExportPdf: () => void;
    onExportGif: () => void;
    onExportWebm: () => void;
    onExportJson: () => void;
    downloadAs: (format: PptxSaveFormat) => Promise<void>;
    onCopySlideAsImage: () => Promise<void>;
}

/**
 * Find-and-replace logic for the Vue editor.
 *
 * Mirrors the React `useFindReplace` hook: the match descriptor and the
 * search/replace algorithms live in `pptx-viewer-shared` (`findInSlides`,
 * `applyFindReplacements`, `replaceMatch`), at segment-level, per-occurrence
 * precision, so the "N of M" match count and Replace All result count agree
 * with every other binding on the same document. This composable is only the
 * Vue idiom around that shared engine: state is exposed as refs (so the bar
 * can `v-model` them) and the match list is a `computed` over the live
 * slides. Replacements snapshot history first, then reassign `slides.value`
 * to the shared engine's immutable result.
 */
export declare function useFindReplace({ slides, activeSlideIndex, pushHistory, }: UseFindReplaceInput): UseFindReplaceResult;

export declare interface UseFindReplaceInput {
    /** Reactive list of slides being edited. */
    slides: Ref<PptxSlide[]>;
    /** The currently active slide index (mutated when navigating matches). */
    activeSlideIndex: Ref<number>;
    /** Snapshot the current document onto the undo/redo history stack. */
    pushHistory: () => void;
}

export declare interface UseFindReplaceResult {
    query: Ref<string>;
    replacement: Ref<string>;
    matchCase: Ref<boolean>;
    matches: ComputedRef<FindResult[]>;
    matchCount: ComputedRef<number>;
    currentMatch: Ref<number>;
    next: () => void;
    prev: () => void;
    replaceCurrent: () => void;
    replaceAll: () => void;
}

/**
 * useFontEmbedding: File ▸ Embed Fonts panel. Derives the set of font
 * families actually used across the deck (recursing into groups) so the panel
 * can flag which ones are missing from the embedded set. Extracted verbatim
 * from `PowerPointViewer.vue`.
 *
 * `embedFontsEnabled` is now read at save time (`useLoadContent` spreads
 * `embeddedFontSaveOptions` into the save options), so it must START in the
 * position that describes what save would do right now: ON for a deck that
 * arrived with embedded fonts, because core re-embeds them by default. The
 * hardcoded `false` this replaces would have stripped the embedded fonts of
 * every such deck the moment the flag was wired up.
 */
export declare function useFontEmbedding(input: UseFontEmbeddingInput): UseFontEmbeddingResult;

export declare interface UseFontEmbeddingInput {
    slides: Ref<PptxSlide[]>;
    embeddedFonts: Ref<PptxEmbeddedFont[]>;
}

export declare interface UseFontEmbeddingResult {
    showFontEmbedding: Ref<boolean>;
    embedFontsEnabled: Ref<boolean>;
    /** Unique font families used across every slide, sorted (mirrors React collectUsedFonts). */
    usedFontFamilies: ComputedRef<string[]>;
    embeddedFontNames: ComputedRef<string[]>;
    /**
     * Shared decision behind the toggle: whether it accepts input at all, and
     * the position it must sit in for the deck that is currently loaded.
     */
    fontEmbedding: ComputedRef<FontEmbeddingDescriptor>;
}

/**
 * useFormatPainter: Home ▸ Format Painter. Arm by copying the selected
 * element's format; the next element click applies it (or, on an
 * empty-canvas click, is simply disarmed). Extracted verbatim from
 * `PowerPointViewer.vue`.
 */
export declare function useFormatPainter(input: UseFormatPainterInput): UseFormatPainterResult;

export declare interface UseFormatPainterInput {
    selectedElements: ComputedRef<PptxElement[]>;
    findActiveElement: (id: string) => PptxElement | undefined;
    ops: EditorOperations;
}

export declare interface UseFormatPainterResult {
    formatPainterActive: Ref<boolean>;
    canActivateFormatPainter: ComputedRef<boolean>;
    toggleFormatPainter: () => void;
    cancelFormatPainter: () => void;
    applyFormatToTarget: (id: string) => void;
}

/**
 * useHeaderFooterDialog: Insert ▸ Header & Footer dialog. Extracted verbatim
 * from `PowerPointViewer.vue`.
 */
export declare function useHeaderFooterDialog(input: UseHeaderFooterDialogInput): UseHeaderFooterDialogResult;

export declare interface UseHeaderFooterDialogInput {
    headerFooter: Ref<PptxHeaderFooter | undefined>;
}

export declare interface UseHeaderFooterDialogResult {
    showHeaderFooter: Ref<boolean>;
    onHeaderFooterUpdate: (next: PptxHeaderFooter) => void;
}

/**
 * useInkDrawing: Draw-tab ink capture. Owns the "is a pen/highlighter/eraser
 * tool armed" derivation and turns a captured stroke into an `ink` element (or,
 * for the eraser, removes the top-most ink element under the point). Extracted
 * verbatim from `PowerPointViewer.vue`.
 */
export declare function useInkDrawing(input: UseInkDrawingInput): UseInkDrawingResult;

export declare interface UseInkDrawingInput {
    canEdit: () => boolean;
    presenting: Ref<boolean>;
    activeTool: Ref<DrawingTool>;
    activeSlide: ComputedRef<PptxSlide | undefined>;
    selectedElementIds: Ref<string[]>;
    ops: EditorOperations;
}

export declare interface UseInkDrawingResult {
    drawingActive: ComputedRef<boolean>;
    addInkStroke: (payload: {
        points: InkPoint[];
        color: string;
        width: number;
        tool: string;
    }) => void;
    eraseInkAt: (point: {
        x: number;
        y: number;
    }) => void;
}

/**
 * useInlineEditing: element-level inline text editing (entered by tapping an
 * already-selected element) plus the inline table-cell commit path. Both
 * commit through `ops.updateElement` so undo/redo works. Extracted verbatim
 * from `PowerPointViewer.vue`.
 */
export declare function useInlineEditing(input: UseInlineEditingInput): UseInlineEditingResult;

export declare interface UseInlineEditingInput {
    canEdit: () => boolean;
    findActiveElement: (id: string) => PptxElement | undefined;
    ops: EditorOperations;
    /**
     * File > Options > Proofing values. When supplied, AutoCorrect runs over the
     * typed text on commit (inline element edits and table-cell edits only, so
     * loaded content is never rewritten).
     */
    proofing?: () => ViewerProofingOptions | undefined;
    /**
     * Collaboration live-preview channel. Typed text only reaches `slides` (and
     * therefore the Y.Doc reconcile) on commit, so peers saw nothing while a
     * peer typed; `updateInlineText` publishes each keystroke through this.
     */
    livePatcher?: () => CollaborationLivePatcher | undefined;
    /** The slide the edited element belongs to (needed by the live channel). */
    activeSlide?: () => PptxSlide | undefined;
    /** Adopt already-published connected text locally before a host disables editing. */
    onConnectedSuspend?: (snapshot: InlineTextEditSnapshot) => void;
}

export declare interface UseInlineEditingResult {
    inlineEditingElementId: Ref<string | null>;
    inlineEditingText: Ref<string>;
    inlineEditingElement: ComputedRef<PptxElement | undefined>;
    /** Set the in-progress text and mirror it to collaborators. */
    updateInlineText: (text: string, snapshot?: InlineTextEditSnapshot) => void;
    readInlineSnapshot: () => InlineTextEditSnapshot | undefined;
    isInlineInputPending: () => boolean;
    onListSession: (event: {
        controller: InlineListController;
        active: boolean;
    }) => void;
    formatInlineSnapshot: (snapshot: InlineTextEditSnapshot) => boolean;
    endInlineListSession: () => void;
    enterInlineEdit: (id: string) => void;
    commitInlineEdit: () => void;
    cancelInlineEdit: () => void;
    commitTableCell: (elementId: string, rowIndex: number, colIndex: number, text: string) => void;
}

/**
 * useInsertElementDialogs: Insert ▸ SmartArt / Equation dialogs. SmartArt and a
 * fresh equation hand back a fully-built element to add and select; an existing
 * equation is instead re-opened in edit mode (`editingEquationOmml` set) and its
 * segment patched in place via `onApplyEquation`, never routed through plain-text
 * inline editing (which would drop the OMML). Mirrors React's
 * `openEquationEditorForElement` / `handleUpdateEquation` split.
 */
export declare function useInsertElementDialogs(input: UseInsertElementDialogsInput): UseInsertElementDialogsResult;

export declare interface UseInsertElementDialogsInput {
    ops: EditorOperations;
    selectedElementIds: Ref<string[]>;
    findActiveElement: (id: string) => PptxElement | undefined;
}

export declare interface UseInsertElementDialogsResult {
    showInsertSmartArt: Ref<boolean>;
    showEquationEditor: Ref<boolean>;
    /** The OMML being edited, or null when the dialog is in "insert" mode. */
    editingEquationOmml: Ref<Record<string, unknown> | null>;
    onInsertElement: (element: PptxElement) => void;
    /** Open the equation editor seeded from an existing equation element; returns
     *  false when `el` carries no equation segment (so the caller can fall back to
     *  ordinary inline text editing). */
    openEquationEditorForElement: (el: PptxElement) => boolean;
    /** Apply an edited equation segment back onto the element being edited. */
    onApplyEquation: (segment: TextSegment) => void;
    /** Close the equation editor and drop any edit-mode state. */
    closeEquationEditor: () => void;
}

export declare function useIsMobile(breakpoint?: number, container?: ContainerSource): UseIsMobileResult;

/**
 * `useIsMobile`: reactive viewport predicate for switching between the desktop
 * chrome and the compact mobile bottom bar, plus the touch / orientation /
 * virtual-keyboard signals the mobile chrome needs.
 *
 * Breakpoints are driven by the observed *container* width when a `container`
 * source is supplied (via `ResizeObserver`), so an embedded viewer in a narrow
 * sidebar is classified by its own box rather than the full viewport. When no
 * container is given (or `ResizeObserver` is unavailable) it falls back to the
 * `window.matchMedia` viewport path. Either way:
 *   - mobile when narrow (< 768px) OR a short touch viewport below the tablet
 *     width (a landscape phone),
 *   - tablet when 768..1023px and not mobile,
 *   - desktop when >= 1024px and not mobile.
 *
 * Additive signals (mirroring the React `useIsMobile` return shape):
 *   - `isTouchDevice`: whether the device reports touch capability.
 *   - `orientation`: `'portrait'` or `'landscape'`, updated on resize /
 *     `screen.orientation` change.
 *   - `isVirtualKeyboardOpen`: true when the visual viewport height shrinks by
 *     more than 30% on a touch device (the on-screen keyboard is likely up).
 *   - `isTablet` / `isDesktop`: derived breakpoint flags.
 *   - `containerWidth`: the measured container (or viewport) width in px.
 *
 * SSR / test safety: `window`, `matchMedia` and `ResizeObserver` are
 * feature-detected. When none is available the predicate stays `false` and no
 * listener is wired, so the composable is safe during server render or in a
 * bare unit test. All observers/listeners are torn down on `onScopeDispose`.
 *
 * @param breakpoint - Max viewport width (px) considered "mobile" for the
 *   matchMedia fallback path. Defaults to 768 to match the React `md:`
 *   Tailwind breakpoint used by the mobile chrome.
 * @param container - Optional container element source. When provided and
 *   `ResizeObserver` exists, breakpoints + `containerWidth` are driven from the
 *   container's box instead of the viewport.
 * @returns reactive read-only refs; existing `{ isMobile }` (and the touch /
 *   orientation / virtual-keyboard) consumers keep working unchanged.
 */
export declare interface UseIsMobileResult {
    /** `true` while the container/viewport is at or below `breakpoint` px wide. */
    isMobile: Readonly<Ref<boolean>>;
    /** `true` while the container/viewport is 768..1023px wide. */
    isTablet: Readonly<Ref<boolean>>;
    /** `true` while the container/viewport is >= 1024px wide. */
    isDesktop: Readonly<Ref<boolean>>;
    /** `true` on devices that report touch capability. */
    isTouchDevice: Readonly<Ref<boolean>>;
    /** Current device orientation (portrait or landscape). */
    orientation: Readonly<Ref<DeviceOrientation>>;
    /** `true` when the on-screen keyboard is likely visible. */
    isVirtualKeyboardOpen: Readonly<Ref<boolean>>;
    /** The measured container (or viewport) width in pixels. */
    containerWidth: Readonly<Ref<number>>;
    /**
     * Raw BROWSER viewport width (px), always `window.innerWidth` regardless of
     * any `container` source. Dense-panel layout decisions
     * (`pptx-viewer-shared`'s `render/responsive/*`, e.g.
     * `getDensePanelTouchTargetPx`) must key off the real viewport per that
     * module's own contract, not an embedding container's box, so this is kept
     * separate from `containerWidth`.
     */
    viewportWidth: Readonly<Ref<number>>;
    /** Raw BROWSER viewport height (px), always `window.innerHeight`. */
    viewportHeight: Readonly<Ref<number>>;
}

export declare function useKeyboardInsets(): UseKeyboardInsetsResult;

/**
 * `useKeyboardInsets`: track the on-screen-keyboard inset on touch devices and
 * keep the focused editable visible when the keyboard opens.
 *
 * The virtual keyboard shrinks the `VisualViewport` without changing the layout
 * viewport. This composable listens to `visualViewport` resize/scroll, derives
 * the covered pixels via the shared {@link computeKeyboardInset}, and:
 *   - exposes `keyboardInset` / `isKeyboardOpen` so the fixed mobile bottom bar
 *     can lift above the keyboard, and
 *   - scrolls the focused input / textarea / contenteditable into the area above
 *     the keyboard via the shared {@link computeScrollDelta}.
 *
 * SSR / desktop safe: with no `VisualViewport` no listener is wired and
 * `keyboardInset` stays 0 (nothing scrolls, the bar is not offset).
 *
 * @returns `{ keyboardInset, isKeyboardOpen }` as read-only refs.
 */
export declare interface UseKeyboardInsetsResult {
    /** CSS pixels the on-screen keyboard currently covers (0 when closed). */
    keyboardInset: Readonly<Ref<number>>;
    /** True while the inset is large enough to count as an open keyboard. */
    isKeyboardOpen: Readonly<Ref<boolean>>;
}

export declare function useKeyboardShortcuts(options: UseKeyboardShortcutsOptions): UseKeyboardShortcutsResult;

/**
 * Reactive guard flags + action callbacks. Flags accept a ref, getter, or plain
 * value (`MaybeRefOrGetter`) so the shell can pass `computed`s directly.
 */
export declare interface UseKeyboardShortcutsOptions {
    /** Action callbacks the registry dispatches to. */
    actions: ShortcutActions;
    /** Whether editing is enabled (React `canEdit`). Defaults to `true`. */
    canEdit?: MaybeRefOrGetter<boolean>;
    /** Whether the viewer is in presentation mode (React `mode !== 'edit'`). */
    isPresenting?: MaybeRefOrGetter<boolean>;
    /** Whether at least one element is selected. */
    hasSelection?: MaybeRefOrGetter<boolean>;
    /** False leaves native paste unclaimed; omitted preserves custom callbacks. */
    canPaste?: MaybeRefOrGetter<boolean>;
    /** Id of the element being inline-edited, or `null`. Suppresses shortcuts. */
    inlineEditingElementId?: MaybeRefOrGetter<string | null>;
    /** Whether a table cell is actively being edited. Suppresses shortcuts. */
    tableEditorIsEditing?: MaybeRefOrGetter<boolean>;
    /** Active drawing tool; shortcuts are suppressed unless `'select'`. */
    activeTool?: MaybeRefOrGetter<string>;
    /** The host's keyboard customisation (disabled / remapped shortcuts). */
    keyboard?: () => ResolvedKeyboardCustomization | undefined;
    /**
     * Self-attach the handler to `window` on mount (and detach on scope dispose).
     * When omitted/false, the caller wires `handleKeyDown` itself.
     */
    autoAttach?: boolean;
}

export declare interface UseKeyboardShortcutsResult {
    /**
     * Pure matcher: resolve a keyboard event to an action (respecting the guard
     * flags) **without** invoking any callback or touching the DOM. Returns
     * `{ action: null }` when the event should be ignored.
     */
    matchShortcut: (event: KeyboardEvent) => MatchedShortcut;
    /**
     * Dispatcher: match the event, call `preventDefault()` when an action fires,
     * and invoke the corresponding callback. Safe to wire directly to `keydown`.
     */
    handleKeyDown: (event: KeyboardEvent) => void;
    /** Manually attach the handler to `window`. Returns a detach function. */
    attach: () => () => void;
}

export declare function useLoadContent(content: MaybeRefOrGetter<Uint8Array | ArrayBuffer | null | undefined>, options?: UseLoadContentOptions): UseLoadContentResult;

export declare interface UseLoadContentOptions {
    /** Current list edit only; serialization does not blur or commit the editor. */
    getPendingInlineEdit?: () => PendingInlineTextEdit | undefined;
    /**
     * Called after a parse fully applies to viewer state (slides & co.).
     * Collaboration uses this to re-adopt the shared doc's slides when a local
     * load lands mid-session and would otherwise clobber remotely-synced state.
     */
    onContentApplied?: () => void;
    /**
     * The File > Info > Protect Presentation state, read at save time. When it
     * yields a password the deck is serialised through `saveEncrypted` (an OLE2
     * container), not `save` (a plain ZIP). A getter rather than a value so the
     * secret is always the current one, no matter when the dialog set it.
     */
    getSaveIntent?: () => DeckSaveIntent;
    /**
     * The File > Fonts "Embed fonts in the file" toggle, read at save time.
     * `false` strips `p:embeddedFontLst`, the `/font` relationships and the
     * `.fntdata` parts; the default (omitted, or `true`) keeps whatever the deck
     * arrived with. A getter, not a value, for the same reason as
     * {@link getSaveIntent}: the composable is created before the panel that
     * owns the flag, and the answer must be the current one.
     */
    getEmbedFonts?: () => boolean;
    /**
     * Trust Center > "Allow external content (remote images and media)", read
     * at load time. `false` (core's own default) makes `getImageData` drop any
     * `http://`/`https://` image URL instead of fetching it; omitted defaults to
     * `true` (fetch them), matching this option's own default. A getter, not a
     * value, so a later options-store change is picked up on the next load
     * without re-wiring this composable, the same convention as
     * {@link getSaveIntent} and {@link getEmbedFonts}.
     */
    getAllowExternalImages?: () => boolean;
}

/**
 * `useLoadContent`: Vue port of the React hook of the same name.
 *
 * Watches a reactive `content` source and parses it into reactive viewer
 * state via the framework-agnostic `PptxHandler` from `pptx-viewer-core`.
 * The heavy lifting (ZIP, XML parse, theme/master/layout resolution, media
 * extraction) all lives in core; this composable only wires the async load
 * into Vue reactivity and manages Blob-URL / handler lifecycle.
 *
 * Differences vs. React:
 *  - The `useEffect(..., [content])` cleanup pattern becomes a `watch` with a
 *    cancellation token plus `onScopeDispose` for unmount cleanup.
 *  - State setters become returned `ref`s mutated in place.
 *
 * Originally the viewer-first subset of the React hook; the extra pieces of
 * presentation metadata (sections, custom shows, embedded fonts, digital
 * signatures, etc.) were added alongside the corresponding features.
 */
export declare interface UseLoadContentResult {
    /** Parsed slides (with image Blob URLs patched in), template elements removed. */
    slides: ShallowRef<PptxSlide[]>;
    /**
     * Master/layout (template) elements pulled out of each slide at load time,
     * keyed by `slide.id`. Edited in `editTemplateMode` and merged back (behind the
     * slide content) by every save path via {@link buildSaveSlides}.
     */
    templateElementsBySlideId: ShallowRef<TemplateElementMap>;
    /** Slide canvas size in pixels. */
    canvasSize: Ref<CanvasSize>;
    /**
     * The slide size in EMU (`p:sldSz`), seeded from the loaded deck and updated
     * by the inspector's preset / orientation controls.
     *
     * Held ALONGSIDE {@link canvasSize} rather than derived from it because the
     * pixel round-trip is lossy: Ledger is 12179300 EMU = 1278.5px, and rounding
     * that to an integer pixel and back moves it far enough to lose the deck's
     * `ppSlideSizeLedgerPaper` identity. `resolveSlideSizeSelection` decides
     * which of the two wins whenever they disagree.
     */
    slideSize: Ref<SlideSizeEmu | undefined>;
    /** Resolved presentation theme. */
    theme: ShallowRef<PptxTheme | undefined>;
    /** Theme colour map (`accent1`→hex, …) used to re-resolve colours on theme switch. */
    themeColorMap: ShallowRef<Record<string, string> | undefined>;
    /** Slide masters (for placeholder/background resolution). */
    slideMasters: ShallowRef<PptxSlideMaster[]>;
    /** Slide-layout choices for the New-Slide gallery (`{ path, name }`). */
    layoutOptions: ShallowRef<PptxLayoutOption[]>;
    /** Archive-path → displayable URL map for media + poster frames. */
    mediaDataUrls: ShallowRef<Map<string, string>>;
    /** True while a load is in flight. */
    loading: Ref<boolean>;
    /** Error message from the last failed load, or null. */
    error: Ref<string | null>;
    /** True when the file is password-protected and could not be opened. */
    isEncrypted: Ref<boolean>;
    /** The live `PptxHandler` for the loaded file (or null). */
    handler: ShallowRef<PptxHandler | null>;
    /** Parsed document core properties (title/author/subject/…). */
    coreProperties: ShallowRef<PptxCoreProperties | undefined>;
    /** Parsed custom document properties (name/type/value), empty when none. */
    customProperties: ShallowRef<PptxCustomProperty[]>;
    /** Parsed application properties (manager/company/…), or undefined. */
    appProperties: ShallowRef<PptxAppProperties | undefined>;
    /** Parsed `ppt/tags/tag*.xml` collections (name/value pairs), empty when none. */
    tagCollections: ShallowRef<PptxTagCollection[]>;
    /** Embedded fonts (for `@font-face` injection). */
    embeddedFonts: ShallowRef<PptxEmbeddedFont[]>;
    /** Parsed digital signatures (empty when unsigned). */
    signatures: ShallowRef<ParsedSignature[]>;
    /**
     * Parsed `ppt/tableStyles.xml` map (GUID → style entry), or `undefined`
     * when the presentation has no table styles part. Feeds table banding /
     * header colour resolution by table-style GUID.
     */
    tableStyleMap: ShallowRef<ParsedTableStyleMap | undefined>;
    /** `ppt/tableStyles.xml`'s `<a:tblStyleLst @def>` default style GUID. */
    tableStylesDefaultId: ShallowRef<string | undefined>;
    /**
     * Style GUIDs deleted from `tableStyleMap` via the table style editor,
     * pending removal from `ppt/tableStyles.xml` on the next save. See
     * `tableStyleSaveOptions` / `applyTableStyleDelete` in `pptx-viewer-shared`.
     */
    tableStylesToDelete: ShallowRef<string[]>;
    /** Ordered presentation sections (`p:sectionLst`), empty when none. */
    sections: ShallowRef<PptxSection[]>;
    /** Named custom slide shows (`p:custShowLst`), empty when none. */
    customShows: ShallowRef<PptxCustomShow[]>;
    /**
     * Modern comment authors (`ppt/commentAuthors.xml`'s `p188:` schema), used
     * to seed the `@`-mention typeahead (`matchCommentMentionAuthors`,
     * `pptx-viewer-shared`). Empty when the deck has no modern comments.
     */
    modernCommentAuthors: ShallowRef<PptxModernCommentAuthor[]>;
    /** Legacy comment authors (`p:cm`'s original `ppt/commentAuthors.xml` schema), empty when none. */
    commentAuthors: ShallowRef<PptxCommentAuthor[]>;
    /** Presentation-level slide-show properties (`presentationPr.xml`); reactive so Set Up Slide Show persists. */
    presentationProperties: ShallowRef<PptxPresentationProperties>;
    /**
     * View properties (`ppt/viewProps.xml`, `p:viewPr`): grid spacing, snap /
     * guide toggles, last view, splitter state, etc. `gridSpacing` lives here,
     * NOT on `presentationProperties` -- `p:gridSpacing` is a child of
     * `p:viewPr`, and a real PowerPoint file never populates it under
     * `p:presentationPr`.
     */
    viewProperties: ShallowRef<PptxViewProperties | undefined>;
    /** Presentation-level header/footer settings, or `undefined`. */
    headerFooter: ShallowRef<PptxHeaderFooter | undefined>;
    /** Parsed notes master, or `undefined` when absent. */
    notesMaster: ShallowRef<PptxNotesMaster | undefined>;
    /** Parsed handout master, or `undefined` when absent. */
    handoutMaster: ShallowRef<PptxHandoutMaster | undefined>;
    /** Theme parts discovered in the package (`{ path, name }`), empty when none. */
    themeOptions: ShallowRef<PptxThemeOption[]>;
    /** Notes page size in pixels (`p:notesSz`), or `undefined` when absent. */
    notesCanvasSize: Ref<CanvasSize | undefined>;
    /**
     * Write-protection verifier from `p:modifyVerifier` (`presentationPr.xml`),
     * or `undefined` when the deck carries none. Feeds
     * `readOnlyRecommendation` (`pptx-viewer-shared`), which the read-only
     * banner uses to default a password-protected deck open read-only.
     */
    modifyVerifier: ShallowRef<PptxModifyVerifier | undefined>;
    /**
     * `handler.getCompatibilityWarnings()` right after this load: every
     * warning the parse reported, deck-scoped and slide-scoped alike (the
     * same list `attachSlideWarnings` partitions per slide, read back whole).
     * Feeds `compatibilityWarningToasts` (`pptx-viewer-shared`) for the
     * compat-warning toast stack.
     */
    compatibilityWarnings: ShallowRef<PptxCompatibilityWarning[]>;
    /** Serialise the current presentation back to `.pptx` bytes. */
    getContent: () => Promise<Uint8Array>;
    /**
     * Serialise for bytes this viewer will read back itself: the autosave
     * crash-recovery snapshot, and the re-serialise-then-reload cycle behind
     * "apply theme". Always a plain ZIP even when the deck is password
     * protected, because neither reader can supply the password (see
     * `deck-save-encryption` in `pptx-viewer-shared` for the rationale and the
     * privacy tradeoff it accepts).
     */
    getRecoverySnapshot: () => Promise<Uint8Array>;
    /** Serialise to a specific OpenXML format (pptx / ppsx / pptm). */
    saveAs: (format: PptxSaveFormat) => Promise<Uint8Array>;
}

/**
 * useMasterViewState: View ▸ Master Views overlay (slide / notes / handout
 * masters). Extracted verbatim from `PowerPointViewer.vue`.
 */
export declare function useMasterViewState(): UseMasterViewStateResult;

export declare interface UseMasterViewStateResult {
    showMasterView: Ref<boolean>;
    masterViewTab: Ref<MasterViewTab>;
    activeMasterIndex: Ref<number>;
    activeLayoutIndex: Ref<number | null>;
    handoutSlidesPerPage: Ref<number>;
    onSelectMaster: (index: number) => void;
    onSelectLayout: (masterIndex: number, layoutIndex: number) => void;
}

/**
 * Media-export composable: render slides to an animated **GIF** or a **WebM**
 * video. Vue port of the React `useExportHandlers` GIF/video paths
 * (`export-gif.ts` / `export-video.ts`).
 *
 * Rasterisation is delegated to the injected `rasterizeSlide` (the host wires
 * `html2canvas-pro` over an off-screen slide stage, the same injection
 * `useExport` uses for PNG/PDF). The GIF encoder is a self-contained pure-JS
 * GIF89a implementation loaded via a dynamic `import()` so it stays out of the
 * main chunk; WebM is recorded with the browser-built-in `MediaRecorder`. Both
 * the encoder and the recorder factory are injectable for unit testing.
 */
export declare function useMediaExport(options: UseMediaExportOptions): UseMediaExportResult;

export declare interface UseMediaExportOptions {
    /** Total slide count (the export iterates `0 … count - 1`). */
    slideCount: Ref<number>;
    /** Host-supplied off-screen rasteriser. */
    rasterizeSlide: RasterizeSlide_2;
    /** Base file name (without extension) for downloads. Defaults to `presentation`. */
    fileName?: Ref<string> | string;
    /**
     * Lazy loader for the GIF encoder. Defaults to a dynamic `import()` of
     * `./gif-encoder` so the ~9 kB encoder stays out of the main chunk (mirrors
     * how `useExport` lazy-loads `jspdf`). Overridable in tests.
     */
    loadGifEncoder?: () => Promise<EncodeGif>;
    /**
     * `MediaRecorder` factory. Defaults to constructing a recorder over
     * `canvas.captureStream(fps)`. Overridable in tests / non-browser hosts.
     */
    createRecorder?: MediaRecorderFactory;
    /**
     * Off-screen compositing-canvas factory for WebM recording. Defaults to
     * `document.createElement('canvas')`. Overridable in tests (happy-dom's
     * canvas has no 2D context).
     */
    createCanvas?: () => HTMLCanvasElement;
    /** Trigger a browser download for a blob. Overridable in tests. */
    downloadBlob?: (blob: Blob, fileName: string) => void;
}

export declare interface UseMediaExportResult {
    /** True while a GIF or WebM export is running. */
    exporting: Ref<boolean>;
    /** 0–100 progress for the in-flight export (0 when idle). */
    progress: Ref<number>;
    /** Export every slide as an animated GIF download. Resolves to the blob. */
    exportGif: (options?: GifExportOptions) => Promise<Blob | undefined>;
    /** Export every slide as a WebM video download. Resolves to the blob. */
    exportWebm: (options?: WebmExportOptions) => Promise<Blob | undefined>;
}

/**
 * useMobileChrome: the mobile bottom-bar's sheet toggles (slides / format /
 * comments / notes, mutually exclusive), its quick-insert shortcut, and the
 * mobile Present action. Extracted verbatim from `PowerPointViewer.vue`.
 */
export declare function useMobileChrome(input: UseMobileChromeInput): UseMobileChromeResult;

export declare interface UseMobileChromeInput {
    presenting: Ref<boolean>;
    /** Quick-insert action fired from the mobile bottom bar (a text box). */
    addText: () => void;
}

export declare interface UseMobileChromeResult {
    /** Mobile-only slide-rail sheet (the slides panel is a left rail on desktop). */
    mobileSlidesOpen: Ref<boolean>;
    /** Mobile-only bottom sheets for panels that are right-rail sidebars on desktop. */
    mobileInspectorOpen: Ref<boolean>;
    mobileCommentsOpen: Ref<boolean>;
    mobileNotesOpen: Ref<boolean>;
    /** Open one mobile sheet at a time so they don't stack over each other. */
    openMobileSheet: (which: MobileSheetKind) => void;
    /**
     * Toggle a bottom-bar tab's sheet: tapping the open sheet closes it,
     * tapping a different one switches to it. The decision itself comes from
     * shared's `toggleSheet` (via the `SHARED_KEY` translation above); this
     * only maps the result back onto the four exclusive refs.
     */
    toggleMobileSheet: (which: MobileSheetKind) => void;
    /** The currently-open sheet, for highlighting its bottom-bar tab. */
    activeSheet: ComputedRef<MobileActiveSheet>;
    mobileQuickInsert: () => void;
    present: () => void;
}

/**
 * Mount and manage the shared 3D scene for a model element. See module doc.
 */
export declare function useModel3dScene(options: UseModel3dSceneOptions): UseModel3dSceneResult;

/** Reactive inputs to {@link useModel3dScene}. */
export declare interface UseModel3dSceneOptions {
    /** Container the scene's canvas is appended into; may be null pre-mount. */
    container: Ref<HTMLElement | null>;
    /** The 3D model element (or undefined when the element is not a model3d). */
    element: Ref<Model3DPptxElement | undefined>;
    /** CSS-pixel view width. */
    width: Ref<number>;
    /** CSS-pixel view height. */
    height: Ref<number>;
    /** Enable orbit controls (rotate + zoom). Default true. */
    interactive: Ref<boolean>;
}

/** Result of {@link useModel3dScene}. */
export declare interface UseModel3dSceneResult {
    /** True once an interactive scene has actually mounted (three available). */
    mounted: Ref<boolean>;
}

/**
 * Morph-specific reactive state for `PresentationTransitionOverlay.vue`,
 * split out to keep that file under the project's per-file LOC budget.
 *
 * Morph is not a whole-slide wipe: individual shapes travel from where they
 * sat on the outgoing slide to where they sit on the incoming one, so when
 * the transition is `morph` the overlay's two stacked layers are re-purposed
 * - the incoming layer plays per-element keyframes (scoped by
 * `data-pptx-morph-incoming`), and the outgoing layer paints a moving copy of
 * the outgoing slide, each shape gliding onto its counterpart (dissolving
 * into it when its appearance changed) or fading out in place when it has
 * none.
 *
 * Inputs are getters (not raw values) so the returned `computed`s stay
 * reactive to the host component's own props.
 */
export declare function useMorphTransitionOverlay(options: {
    transition: () => PptxSlideTransition | undefined;
    outgoingSlide: () => PptxSlide | undefined;
    incomingSlide: () => PptxSlide | undefined;
    durationMs: () => number;
}): {
    morphPlan: ComputedRef< MorphTransitionPlan | undefined>;
    morphOutgoingSlide: ComputedRef<PptxSlide | undefined>;
    morphLiftedSlide: ComputedRef<PptxSlide | undefined>;
    morphCrossfadeGroups: ComputedRef<{
        key: string;
        style: CSSProperties_2;
        outgoingStyle: CSSProperties_2;
        incomingStyle: CSSProperties_2;
        outgoingSlide: {
            elements: PptxElement[];
            id: string;
            rId: string;
            slideId?: string;
            sourceSlideId?: string;
            name?: string;
            layoutPath?: string;
            layoutName?: string;
            slideNumber: number;
            hidden?: boolean;
            sectionName?: string;
            sectionId?: string;
            backgroundColor?: string;
            backgroundImage?: string;
            backgroundImageProperties?: PptxImageProperties;
            backgroundGradient?: string;
            backgroundPattern?: PptxSlideBackgroundPattern;
            backgroundShadeToTitle?: boolean;
            transition?: PptxSlideTransition;
            animations?: PptxElementAnimation[];
            animationTimelineAnchors?: PptxAnimationTimelineAnchor[];
            nativeAnimations?: PptxNativeAnimation[];
            rawTiming?: XmlObject;
            notes?: string;
            notesSegments?: TextSegment[];
            notesShapes?: PptxElement[];
            notesClrMapOverride?: Record<string, string>;
            notesCSldName?: string;
            comments?: PptxComment[];
            modernCommentPart?: PptxModernCommentPart;
            warnings?: PptxCompatibilityWarning[];
            rawXml?: XmlObject;
            clrMapOverride?: Record<string, string>;
            backgroundShowAnimation?: boolean;
            showMasterShapes?: boolean;
            showMasterPhAnim?: boolean;
            guides?: PptxDrawingGuide[];
            isDirty?: boolean;
            customerData?: PptxCustomerData[];
            activeXControls?: PptxActiveXControl[];
            legacyVmlElements?: PptxElement[];
            headerFooterFlags?: PptxHeaderFooterFlags;
            slideSynchronization?: PptxSlideSyncProperties;
        };
        incomingSlide: {
            elements: PptxElement[];
            id: string;
            rId: string;
            slideId?: string;
            sourceSlideId?: string;
            name?: string;
            layoutPath?: string;
            layoutName?: string;
            slideNumber: number;
            hidden?: boolean;
            sectionName?: string;
            sectionId?: string;
            backgroundColor?: string;
            backgroundImage?: string;
            backgroundImageProperties?: PptxImageProperties;
            backgroundGradient?: string;
            backgroundPattern?: PptxSlideBackgroundPattern;
            backgroundShadeToTitle?: boolean;
            transition?: PptxSlideTransition;
            animations?: PptxElementAnimation[];
            animationTimelineAnchors?: PptxAnimationTimelineAnchor[];
            nativeAnimations?: PptxNativeAnimation[];
            rawTiming?: XmlObject;
            notes?: string;
            notesSegments?: TextSegment[];
            notesShapes?: PptxElement[];
            notesClrMapOverride?: Record<string, string>;
            notesCSldName?: string;
            comments?: PptxComment[];
            modernCommentPart?: PptxModernCommentPart;
            warnings?: PptxCompatibilityWarning[];
            rawXml?: XmlObject;
            clrMapOverride?: Record<string, string>;
            backgroundShowAnimation?: boolean;
            showMasterShapes?: boolean;
            showMasterPhAnim?: boolean;
            guides?: PptxDrawingGuide[];
            isDirty?: boolean;
            customerData?: PptxCustomerData[];
            activeXControls?: PptxActiveXControl[];
            legacyVmlElements?: PptxElement[];
            headerFooterFlags?: PptxHeaderFooterFlags;
            slideSynchronization?: PptxSlideSyncProperties;
        };
    }[]>;
    morphCss: ComputedRef<string>;
};

/**
 * useMultiSelectOps: apply a single-element editor op (delete / duplicate /
 * bring-forward / send-backward) across every currently selected element as
 * one batch. Extracted verbatim from `PowerPointViewer.vue`.
 */
export declare function useMultiSelectOps(input: UseMultiSelectOpsInput): UseMultiSelectOpsResult;

export declare interface UseMultiSelectOpsInput {
    selectedElementIds: Ref<string[]>;
    ops: EditorOperations;
    clearSelection: () => void;
}

export declare interface UseMultiSelectOpsResult {
    deleteSelected: () => void;
    duplicateSelected: () => void;
    bringForward: () => void;
    sendBackward: () => void;
}

/**
 * usePasswordProtection: File ▸ Protect Presentation dialog. Mirrors React:
 * the password lives in host state and the save path reads it through the
 * shared `planDeckSave`/`saveDeckWithPassword` decision, so a protected deck
 * serialises to an encrypted OLE2 container instead of a plain ZIP. The
 * viewer creates this composable ahead of `useLoadContent` and hands it in as
 * `getSaveIntent`.
 */
export declare function usePasswordProtection(): UsePasswordProtectionResult;

export declare interface UsePasswordProtectionResult {
    showPasswordDialog: Ref<boolean>;
    isPasswordProtected: Ref<boolean>;
    presentationPassword: Ref<string | null>;
    onSetPassword: (password: string) => void;
    onRemovePassword: () => void;
}

export declare function usePresentationAnnotations(options: UsePresentationAnnotationsOptions): UsePresentationAnnotationsResult;

export declare interface UsePresentationAnnotationsOptions {
    /** Whether presentation mode (and thus annotation capture) is active. */
    isActive: MaybeRefOrGetter<boolean>;
    /** Current slide index, used to track which slide annotations belong to. */
    activeSlideIndex: MaybeRefOrGetter<number>;
}

export declare interface UsePresentationAnnotationsResult {
    presentationTool: Ref<PresentationTool>;
    setPresentationTool: (tool: PresentationTool) => void;
    penColor: Ref<string>;
    setPenColor: (color: string) => void;
    highlighterColor: Ref<string>;
    setHighlighterColor: (color: string) => void;
    /** Completed strokes on the active slide. */
    annotationStrokes: Ref<AnnotationStroke[]>;
    /** The in-progress stroke (pen/highlighter), or `null`. */
    currentStroke: Ref<AnnotationStroke | null>;
    /** The current laser-pointer position, or `null`. */
    laserPosition: Ref<LaserPosition | null>;
    handlePointerDown: (x: number, y: number) => void;
    handlePointerMove: (x: number, y: number) => void;
    handlePointerUp: () => void;
    handleLaserMove: (x: number, y: number) => void;
    handleLaserLeave: () => void;
    eraseAtPoint: (x: number, y: number) => void;
    /** Clear the active slide's annotations. */
    clearAnnotations: () => void;
    /** Clear annotations on every slide. */
    clearAllAnnotations: () => void;
    /** All annotations across all slides (for persistence on exit). */
    allSlideAnnotations: ComputedRef<SlideAnnotationMap>;
    /** Whether any annotations exist across all slides. */
    hasAnyAnnotations: ComputedRef<boolean>;
}

/**
 * usePresentationModeWiring: the slideshow presentation-mode lifecycle,
 * including persisting kept ink annotations (drawn during presentation) back
 * onto their slides as real `ink` elements on close. Extracted verbatim from
 * `PowerPointViewer.vue`.
 */
export declare function usePresentationModeWiring(input: UsePresentationModeWiringInput): UsePresentationModeWiringResult;

export declare interface UsePresentationModeWiringInput {
    slides: Ref<PptxSlide[]>;
    activeSlideIndex: Ref<number>;
    pushHistory: () => void;
}

export declare interface UsePresentationModeWiringResult {
    presenting: Ref<boolean>;
    startPresenting: () => void;
    onPresentClose: (payload?: {
        annotations: SlideAnnotationMap;
    }) => void;
    onPresentSlideChange: (index: number) => void;
}

export declare function usePrint(options: UsePrintOptions): UsePrintResult;

export declare interface UsePrintOptions {
    slides: Ref<PptxSlide[]>;
    activeSlideIndex: Ref<number>;
    rasterizeSlide: RasterizeSlide_3;
    /** Native presentation dimensions used for vector slide printing. */
    slideSize?: Ref<CanvasSize>;
    /** Override the print-window opener (defaults to a `window.open` impl). */
    openPrintWindow?: OpenPrintWindow;
    /**
     * The deck's handout master, consumed for its background, header/footer/
     * date/page-number placeholders, and (when authored) positioned slide
     * rects, in the `handouts` print mode.
     */
    handoutMaster?: Ref<PptxHandoutMaster | undefined>;
    /** False while the host removed the Print dialog (UI customisation); opening is a no-op. */
    canOpen?: () => boolean;
}

export declare interface UsePrintResult {
    /** Whether the print dialog is open. */
    isPrintDialogOpen: Ref<boolean>;
    /** Open the print dialog (the toolbar print button). */
    openPrintDialog: () => void;
    /** Close the print dialog without printing. */
    closePrintDialog: () => void;
    /** Run the print flow for the confirmed settings (closes the dialog first). */
    print: (settings: PrintSettings) => Promise<void>;
}

export declare function useRehearseTimings(options?: UseRehearseTimingsOptions): UseRehearseTimingsResult;

export declare interface UseRehearseTimingsOptions {
    /** Called with the recorded per-slide timings (ms) when the user saves. */
    onSave?: (timings: Record<number, number>) => void;
    /** How often (ms) to tick the live display. Defaults to 250. */
    tickIntervalMs?: number;
    /** Injectable clock for testing. Defaults to `Date.now`. */
    now?: () => number;
}

export declare interface UseRehearseTimingsResult {
    /** Whether a rehearsal session is in progress. */
    rehearsing: Ref<boolean>;
    /** Whether the rehearsal timer is paused. */
    paused: Ref<boolean>;
    /** Whether the post-rehearsal summary should be shown. */
    showSummary: Ref<boolean>;
    /** Recorded per-slide timings (slide index → ms). */
    recordedTimings: Ref<Record<number, number>>;
    /** Live elapsed time (ms) on the current slide. */
    slideElapsedMs: ComputedRef<number>;
    /** Live total elapsed time (ms) since the presentation started. */
    totalElapsedMs: ComputedRef<number>;
    /** Sum (ms) of all recorded slide timings. */
    totalRecordedMs: ComputedRef<number>;
    /** Begin a rehearsal session, resetting all timing state. */
    start: () => void;
    /**
     * Record the time spent on `slideIndex` and reset the per-slide timer for the
     * next slide. No-op if the slide timer hasn't started.
     */
    recordCurrentSlideTime: (slideIndex: number) => void;
    /** Toggle the paused state, accumulating paused time on resume. */
    togglePause: () => void;
    /** End capture and open the post-rehearsal summary. */
    finish: () => void;
    /** Persist the recorded timings (via `onSave`) and end the session. */
    saveTimings: () => void;
    /** Discard the recorded timings and end the session. */
    dismissSummary: () => void;
}

/** Read the resolved 3D flags; all off when not provided. */
export declare function useRendering3DFlags(): ComputedRef<Rendering3DFlags>;

export declare function useRibbonActions(input: UseRibbonActionsInput): {
    ribbonMode: ComputedRef<ViewerMode>;
    activeTableSelection: ComputedRef<TableCellEditorState | null>;
    ribbonUpdateTextStyle: (updates: Partial<TextStyle>) => void;
    ribbonUpdateTextCase: (mode: ChangeCaseMode) => void;
    ribbonFlip: (direction: "horizontal" | "vertical") => void;
    ribbonMoveToEdge: (dir: string) => void;
};

export declare interface UseRibbonActionsInput {
    readInlineSnapshot?: () => InlineTextEditSnapshot | undefined;
    formatInlineSnapshot?: (snapshot: InlineTextEditSnapshot) => boolean;
    endInlineListSession?: () => void;
    canEdit: () => boolean;
    presenting: Ref<boolean>;
    showMasterView: Ref<boolean>;
    tableSelection: Ref<TableSelectionState | null>;
    selectedElements: ComputedRef<PptxElement[]>;
    selectedElementIds: Ref<string[]>;
    activeSlide: ComputedRef<PptxSlide | undefined>;
    activeSlideIndex: Ref<number>;
    slides: Ref<PptxSlide[]>;
    pushHistory: () => void;
    ops: EditorOperations;
}

/**
 * The ribbon-facing action surface. Inferred from the implementation so the two
 * cannot drift; `useViewerRibbonProps` refers to this rather than restating it.
 */
export declare type UseRibbonActionsResult = ReturnType<typeof useRibbonActions>;

/**
 * useRibbonProps: adapts the editor's state and handlers into the `RibbonProps`
 * contract consumed by `RibbonToolbar` / `MobileToolbar`. State and actions
 * remain in the editor composables while this adapter keeps the ribbon views
 * presentation-only.
 *
 * The state fields and the callback fields are built by
 * `buildRibbonPropsState` / `buildRibbonPropsActions` respectively (split out
 * to keep every ribbon-props file under the repo's ~300 LOC convention);
 * this composable just merges them into the `computed<RibbonProps>` the
 * template binds with `v-bind`. Extracted verbatim from
 * `PowerPointViewer.vue`.
 */
export declare function useRibbonProps(input: UseRibbonPropsInput): ComputedRef<RibbonProps>;

/** Action callbacks the ribbon adapter dispatches. */
export declare interface UseRibbonPropsActionsInput {
    startPresenting: () => void;
    /** "From Beginning": the show's first slide, unconditionally. */
    presentFromBeginning: () => void;
    startPresenterView: () => void;
    startRehearsal: () => void;
    compareWithPresentation: () => Promise<void>;
    onAddAnimation: RibbonProps['onAddAnimation'];
    onRemoveAnimation: RibbonProps['onRemoveAnimation'];
    zoomIn: () => void;
    zoomOut: () => void;
    zoomReset: () => void;
    undo: () => void;
    redo: () => void;
    addText: () => void;
    addShape: (preset: ShapePreset) => void;
    addTable: () => void;
    addChart: (chartKind: InsertChartKind) => void;
    addField: (fieldType: string, value?: string) => void;
    addActionButton: (shapeType: string) => void;
    openImagePicker: () => void;
    openMediaPicker: () => void;
    addGuide: (axis: 'h' | 'v') => void;
    onAlign: (edge: AlignEdge) => void;
    onDistribute: (axis: DistributeAxis) => void;
    copySelected: () => void;
    cutSelected: () => void;
    pasteElement: () => void;
    ribbonFlip: (direction: 'horizontal' | 'vertical') => void;
    bringForward: () => void;
    sendBackward: () => void;
    ribbonMoveToEdge: (dir: string) => void;
    onGroup: () => void;
    onUngroup: () => void;
    /** Patch the selection's `shapeStyle` (the Arrange group's outline width). */
    updateSelectedShapeStyle: RibbonProps['onUpdateElementStyle'];
    /** Open the hyperlink editor on the current selection (Insert ▸ Link). */
    openHyperlinkForSelection: () => void;
    duplicateSelected: () => void;
    deleteSelected: () => void;
    handleOpenFile: () => void;
    handleOpenRecentFile: (key: string) => void;
    createPresentation: (templateId: string) => void;
    onExportPng: () => void;
    onExportPdf: () => void;
    onExportWebm: () => void;
    onExportGif: () => void;
    onExportJson: () => void;
    downloadAs: (format: PptxSaveFormat) => Promise<void>;
    onCopySlideAsImage: () => Promise<void>;
    openPrintDialog: () => void;
    ribbonUpdateTextStyle: RibbonProps['onUpdateTextStyle'];
    ribbonUpdateTextCase: RibbonProps['onTransformTextCase'];
    insertSlideFromLayout: (layoutPath: string, layoutName?: string) => Promise<void>;
    applyLayoutToActiveSlide: (layoutPath: string) => Promise<void>;
    /** Builds the New Slide / Layout gallery artwork on first menu open. */
    loadLayoutPreviews: () => Promise<PptxLayoutPreview[]>;
    insertSlideFromTemplate: (templateId: SlideTemplateId) => void;
    onRenameActiveCustomShow: () => void;
    onDeleteActiveCustomShow: () => void;
    onToggleCurrentSlideInActiveShow: () => void;
    toggleFormatPainter: () => void;
    onToggleSubtitles: () => void;
    onTransitionChange: RibbonProps['onTransitionChange'];
    onApplyTransitionToAll: () => void;
    /** Start a new deck section (Home > Slides > Section), from `useSectionOperations`. */
    addSection: (name: string, afterSlideIndex: number) => void;
    /** The localised name a ribbon-created section gets. */
    defaultSectionName: () => string;
    /** Select every element on the active slide (Home > Editing > Select All). */
    selectAllElements: () => void;
    /** Drop the element selection (Design > Slide Size shows the deck panel). */
    clearSelection: () => void;
    /** Commit a Slide Show Options checkbox, from `useSlideShowSettings`. */
    onPresentationPropertiesUpdate: (patch: Partial<PptxPresentationProperties>) => void;
}

export declare type UseRibbonPropsInput = UseRibbonPropsStateInput & UseRibbonPropsActionsInput;

/**
 * Input types for `useRibbonProps` (split out to keep every ribbon-props file
 * under the repo's ~300 LOC convention). See `useRibbonProps.ts` for the
 * composable itself and `ribbon-props-state.ts` / `ribbon-props-actions.ts`
 * for the two halves of the `RibbonProps` object it builds.
 */
/** State refs the ribbon adapter reads. */
export declare interface UseRibbonPropsStateInput {
    ribbonMode: ComputedRef<ViewerMode>;
    canEdit: () => boolean;
    isMobile: Ref<boolean>;
    sidebarCollapsed: Ref<boolean>;
    inspectorOpen: Ref<boolean>;
    ribbonExpanded: Ref<boolean>;
    toolbarSection: Ref<ToolbarSection>;
    zoom: Ref<number>;
    canUndo: ComputedRef<boolean>;
    canRedo: ComputedRef<boolean>;
    findOpen: Ref<boolean>;
    selectedElements: ComputedRef<PptxElement[]>;
    activeTableSelection: ComputedRef<TableCellEditorState | null>;
    editTemplateMode: Ref<boolean>;
    newShapeType: Ref<SupportedShapeType>;
    activeTool: Ref<DrawingTool>;
    drawingColor: Ref<string>;
    drawingWidth: Ref<number>;
    clipboard: Ref<PptxElement | null>;
    spellCheckEnabled: Ref<boolean>;
    showGrid: Ref<boolean>;
    showRulers: Ref<boolean>;
    /** Guide-overlay visibility; independent of snapping (see `useRibbonUiState`). */
    showGuides: Ref<boolean>;
    snapToGrid: Ref<boolean>;
    snapToShape: Ref<boolean>;
    overflowOpen: Ref<boolean>;
    layoutOptions: Ref<PptxLayoutOption[]>;
    /** Families the deck embeds, offered as their own font-dropdown group. */
    embeddedFontFamilies: Ref<string[]> | ComputedRef<string[]>;
    /** Families registered this session via File > Options > Fonts. */
    customFontFamilies: Ref<string[]>;
    /** Loaded deck theme; template gallery previews resolve scheme colours against it. */
    theme: ShallowRef<PptxTheme | undefined>;
    customShows: Ref<PptxCustomShow[]>;
    activeCustomShowId: Ref<string | null>;
    isCurrentSlideInActiveShow: ComputedRef<boolean>;
    themeEditorOpen: Ref<boolean>;
    themeGalleryOpen: Ref<boolean>;
    eyedropperActive: Ref<boolean>;
    showComments: Ref<boolean>;
    activeComments: ComputedRef<PptxComment[]>;
    formatPainterActive: Ref<boolean>;
    canActivateFormatPainter: ComputedRef<boolean>;
    showSelectionPane: Ref<boolean>;
    showSubtitles: Ref<boolean>;
    activeSlide: ComputedRef<PptxSlide | undefined>;
    /** Index of the active slide, for per-slide ribbon commands (Hide Slide). */
    activeSlideIndex: Ref<number>;
    /** Toggle a slide's `hidden` flag (one undo step), from `useSlideMutations`. */
    toggleSlideHidden: (index: number) => void;
    /** Deck presentation properties, backing the Slide Show tab's Options checkboxes. */
    presentationProperties: Ref<PptxPresentationProperties>;
    presenting: Ref<boolean>;
    canDistribute: ComputedRef<boolean>;
    shareOpen: Ref<boolean>;
    showShortcuts: Ref<boolean>;
    showSettings: Ref<boolean>;
    showHeaderFooter: Ref<boolean>;
    showA11y: Ref<boolean>;
    showSorter: Ref<boolean>;
    showReadingView: Ref<boolean>;
    showOutlineView: Ref<boolean>;
    showCustomShows: Ref<boolean>;
    showVersionHistory: Ref<boolean>;
    showPasswordDialog: Ref<boolean>;
    propertiesOpen: Ref<boolean>;
    showFontEmbedding: Ref<boolean>;
    showSignatures: Ref<boolean>;
    showMasterView: Ref<boolean>;
    showSetUpSlideShow: Ref<boolean>;
    broadcastOpen: Ref<boolean>;
    showInsertSmartArt: Ref<boolean>;
    showEquationEditor: Ref<boolean>;
    /** Collaboration session, for the tab-row Share button's connected state. */
    collab: UseCollaborationResult;
}

/**
 * useRibbonUiState: the plain view-state toggles the Office-style ribbon reads
 * and writes (active tab/tool, panel visibility, grid/ruler/spell-check
 * toggles, theme overlays). No derived logic; a home for the ribbon's flat
 * UI-state refs so `PowerPointViewer.vue` doesn't declare them inline.
 * Extracted verbatim from `PowerPointViewer.vue`.
 */
export declare function useRibbonUiState(): UseRibbonUiStateResult;

export declare interface UseRibbonUiStateResult {
    toolbarSection: Ref<ToolbarSection>;
    newShapeType: Ref<SupportedShapeType>;
    activeTool: Ref<DrawingTool>;
    drawingColor: Ref<string>;
    drawingWidth: Ref<number>;
    /** Right-rail inspector visibility (desktop). */
    inspectorOpen: Ref<boolean>;
    /** Left slides-rail collapse (Quick-Access sidebar toggle). */
    sidebarCollapsed: Ref<boolean>;
    /** Ribbon content expanded (true) vs collapsed to just the tab bar (false). */
    ribbonExpanded: Ref<boolean>;
    overflowOpen: Ref<boolean>;
    /** Status-bar Notes toggle: expands/collapses the desktop notes panel. */
    notesExpanded: Ref<boolean>;
    /** View-tab dot-grid overlay (snap-to-grid state lives in useElementDrag). */
    showGrid: Ref<boolean>;
    /** View ▸ Rulers: horizontal/vertical rulers along the slide edges. */
    showRulers: Ref<boolean>;
    /**
     * View ▸ Guides: whether the draggable H/V guides are DRAWN.
     *
     * Visibility only. The guides stay in the model when this is off, so
     * snapping to them and the save round-trip are unaffected; this used to be
     * conflated with `snapToShape`, which left the two settings unable to be
     * expressed independently.
     */
    showGuides: Ref<boolean>;
    /** View ▸ Spell: draw the browser's native spell-check squiggles while editing. */
    spellCheckEnabled: Ref<boolean>;
    /** Design ▸ Themes gallery overlay. */
    themeGalleryOpen: Ref<boolean>;
    /** Design ▸ Theme editor overlay. */
    themeEditorOpen: Ref<boolean>;
    /** View ▸ Eyedropper: active ribbon tool state. */
    eyedropperActive: Ref<boolean>;
}

export declare function useSectionOperations(input: UseSectionOperationsInput): UseSectionOperationsResult;

/**
 * `useSectionOperations`: CRUD + grouping for slide sections in the Vue editor.
 *
 * Vue port of the React `useSectionOperations` hook (`packages/react/src/
 * viewer/hooks/useSectionOperations.ts`). It mirrors that hook's operation set
 * and semantics:
 *
 *  - `addSection`: insert a new section after a slide, claiming the run of
 *    contiguous slides that share the slide's current section.
 *  - `renameSection`: rename a section and propagate the name to its slides.
 *  - `deleteSection`: remove a section, merging its slides into the previous
 *    section (or clearing the section on its slides when it was the first).
 *  - `moveSectionUp` / `moveSectionDown`: reorder a section by one position.
 *  - `moveSlidesToSection`: reassign a set of slides (by index) to a section.
 *  - `toggleSectionCollapse`: flip the `collapsed` flag on a section.
 *  - `slidesBySection`: a computed grouping of slides keyed by their section.
 *
 * The composable is DOM-free and operates purely on the reactive model so it is
 * unit-testable in isolation. Each mutating operation snapshots undo/redo
 * history *first* (via the supplied `pushHistory`, the Vue equivalent of the
 * React hook's `markDirty`) and then reassigns `sections.value` / `slides.value`
 * with fresh arrays so `shallowRef`-backed state triggers reactivity.
 */
export declare interface UseSectionOperationsInput {
    /** Reactive section list (typically a `shallowRef<PptxSection[]>`). */
    sections: Ref<PptxSection[]>;
    /** Reactive slide list (typically a `shallowRef<PptxSlide[]>`). */
    slides: Ref<PptxSlide[]>;
    /** Index of the currently focused slide. */
    activeSlideIndex: Ref<number>;
    /** Snapshot current state onto the undo stack before mutating. */
    pushHistory: () => void;
}

export declare interface UseSectionOperationsResult {
    /**
     * Insert a new section after the slide at `afterSlideIndex`, claiming that
     * slide and the following contiguous run that shares its current section.
     */
    addSection: (name: string, afterSlideIndex: number) => void;
    /** Rename a section and propagate the name to its slides. */
    renameSection: (sectionId: string, newName: string) => void;
    /** Remove a section, merging its slides into the previous section. */
    deleteSection: (sectionId: string) => void;
    /** Move a section one position earlier in the list. */
    moveSectionUp: (sectionId: string) => void;
    /** Move a section one position later in the list. */
    moveSectionDown: (sectionId: string) => void;
    /** Reassign the slides at `slideIndexes` to the target section. */
    moveSlidesToSection: (slideIndexes: number[], targetSectionId: string) => void;
    /** Flip the `collapsed` flag on a section. */
    toggleSectionCollapse: (sectionId: string) => void;
    /** Slides grouped by section, in deck order (leading no-section group first). */
    slidesBySection: ComputedRef<SectionGroup[]>;
}

/**
 * useSelectionPaneWiring: View ▸ Selection Pane (object list + z-order +
 * visibility + rename over the active slide's elements). Extracted verbatim
 * from `PowerPointViewer.vue`.
 */
export declare function useSelectionPaneWiring(input: UseSelectionPaneWiringInput): UseSelectionPaneWiringResult;

export declare interface UseSelectionPaneWiringInput {
    findActiveElement: (id: string) => PptxElement | undefined;
    activeSlide: ComputedRef<PptxSlide | undefined>;
    selectedElementIds: Ref<string[]>;
    ops: EditorOperations;
}

export declare interface UseSelectionPaneWiringResult {
    showSelectionPane: Ref<boolean>;
    onSelectionPaneSelect: (id: string) => void;
    onSelectionPaneToggleVisibility: (id: string) => void;
    onSelectionPaneReorder: (payload: {
        from: number;
        to: number;
    }) => void;
    onSelectionPaneRename: (payload: {
        id: string;
        name: string;
    }) => void;
}

/**
 * Drag-to-dismiss logic for mobile bottom sheets. Dragging the grab region down
 * past `threshold` px invokes `onClose`; a shorter drag snaps back.
 *
 * Vue port of the React `useSheetDismissDrag` hook; keeps every Vue mobile
 * sheet (notes / format / comments) consistent with the React viewer.
 */
export declare function useSheetDismissDrag(onClose: () => void, threshold?: number): SheetDismissDrag;

/**
 * Derive reactive signature status from a (possibly reactive) list of parsed
 * signatures. The host runs detection/parsing and supplies the array.
 */
export declare function useSignatures(signaturesInput: MaybeRefOrGetter<ParsedSignature[]>): UseSignaturesResult;

export declare interface UseSignaturesResult {
    /** The signatures currently being inspected (reactive passthrough). */
    signatures: ComputedRef<ParsedSignature[]>;
    /** True when the package carries at least one signature part. */
    isSigned: ComputedRef<boolean>;
    /**
     * The single worst per-signature status across the package, or `undefined`
     * when the package is unsigned. Useful for badge colouring.
     */
    status: ComputedRef<SignatureStatus | undefined>;
    /** Coarse-grained "Signed / Invalid / Not signed" classification. */
    overall: ComputedRef<OverallSignatureStatus>;
}

/**
 * useSignatureWorkflow: File ▸ Digital Signatures panel plus the "saving a
 * signed deck strips signatures" first-edit warning (mirrors React's
 * `useViewerDialogs` signature-strip effect). Extracted verbatim from
 * `PowerPointViewer.vue`.
 */
export declare function useSignatureWorkflow(input: UseSignatureWorkflowInput): UseSignatureWorkflowResult;

export declare interface UseSignatureWorkflowInput {
    signatures: Ref<ParsedSignature[]>;
    /** Autosave dirty flag; a signed deck warns once on its first dirtying edit. */
    isDirty: ComputedRef<boolean> | Ref<boolean>;
}

export declare interface UseSignatureWorkflowResult {
    showSignatures: Ref<boolean>;
    signaturesApi: UseSignaturesResult;
    hasDigitalSignatures: ComputedRef<boolean>;
    showSignatureStripped: Ref<boolean>;
    onAckSignatureStripped: () => void;
}

/**
 * useSlideMutations: history-tracked mutations that live on the slide rather
 * than an element (speaker notes, hidden flag, transition, background patch,
 * per-slide animation list). Each rebuilds a fresh `slides` array after
 * snapshotting history. Extracted verbatim from `PowerPointViewer.vue`.
 */
export declare function useSlideMutations(input: UseSlideMutationsInput): {
    onNotesUpdate: (notes: string) => void;
    toggleSlideHidden: (index: number) => void;
    applySlideTransition: (transition: PptxSlideTransition | undefined) => void;
    applySlideBackgroundPatch: (patch: Partial<PptxSlide>) => void;
    onTransitionChange: (updates: Partial<PptxSlideTransition>) => void;
    onApplyTransitionToAll: () => void;
    onAddAnimation: (preset: string, group: AnimationApplyGroup) => void;
    onRemoveAnimation: () => void;
};

export declare interface UseSlideMutationsInput {
    slides: Ref<PptxSlide[]>;
    activeSlideIndex: Ref<number>;
    activeSlide: ComputedRef<PptxSlide | undefined>;
    pushHistory: () => void;
    selectedElements: ComputedRef<PptxElement[]>;
}

export declare function useSlideOperations(input: UseSlideOperationsInput): UseSlideOperationsResult;

/**
 * `useSlideOperations`: slide-level CRUD for the Vue editor.
 *
 * Vue port of the slide-management subset of the React
 * `useSlideManagement` hook. Each operation snapshots undo/redo history
 * *first* (via the supplied `pushHistory`) and then reassigns
 * `slides.value` with a fresh array so that `shallowRef`-backed slide
 * state triggers reactivity. `activeSlideIndex` is adjusted to keep a
 * sensible slide focused after the mutation.
 *
 * Blank slides are created via a minimal object literal matching the
 * `PptxSlide` shape (the same approach the React `handleAddSlide` uses):
 * a fresh `id`, empty `rId`, `slideNumber` and an empty `elements` array.
 * Duplication reuses the framework-agnostic `cloneSlide` helper from
 * `pptx-viewer-core` for a deep, reference-independent copy.
 */
export declare interface UseSlideOperationsInput {
    /** Reactive slide list (typically a `shallowRef<PptxSlide[]>`). */
    slides: Ref<PptxSlide[]>;
    /** Index of the currently focused slide. */
    activeSlideIndex: Ref<number>;
    /** Snapshot current state onto the undo stack before mutating. */
    pushHistory: () => void;
}

export declare interface UseSlideOperationsResult {
    /** Insert after the given index, or after the active slide when omitted. */
    addSlide: (afterIndex?: number) => void;
    /** Remove the slide at `index` (no-op when only one slide remains). */
    deleteSlide: (index: number) => void;
    /** Deep-clone the slide at `index` and insert the copy right after it. */
    duplicateSlide: (index: number) => void;
    /** Reorder the slide at `from` to position `to`. */
    moveSlide: (from: number, to: number) => void;
}

/**
 * useSlideShowSettings: Slide Show ▸ Set Up Slide Show dialog plus the
 * Subtitles ribbon toggle, both of which read/write the shared
 * `presentationProperties` draft. Extracted verbatim from
 * `PowerPointViewer.vue`.
 */
export declare function useSlideShowSettings(input: UseSlideShowSettingsInput): UseSlideShowSettingsResult;

export declare interface UseSlideShowSettingsInput {
    presentationProperties: Ref<PptxPresentationProperties>;
}

export declare interface UseSlideShowSettingsResult {
    showSetUpSlideShow: Ref<boolean>;
    showSubtitles: Ref<boolean>;
    onSaveSlideShowSettings: (next: PptxPresentationProperties) => void;
    onPresentationPropertiesUpdate: (patch: Partial<PptxPresentationProperties>) => void;
    onToggleSubtitles: () => void;
}

/**
 * useSlideTemplateInsertion: Home-tab "Slide Templates" gallery insert path.
 *
 * Builds the complete draft slide via the shared catalogue
 * (`buildSlideTemplateSlide`), themed with the deck's colour scheme, and
 * splices it after the active slide. Mirrors React's
 * `handleInsertSlideFromTemplate` and follows the same history contract as
 * `useElementInsertion.insertSlideFromLayout`: `pushHistory()` BEFORE the
 * mutation, so the insert is undoable through the normal history path.
 */
export declare function useSlideTemplateInsertion(input: UseSlideTemplateInsertionInput): UseSlideTemplateInsertionResult;

export declare interface UseSlideTemplateInsertionInput {
    canvasSize: Ref<{
        width: number;
        height: number;
    }>;
    slides: Ref<PptxSlide[]>;
    activeSlideIndex: Ref<number>;
    pushHistory: () => void;
    /** Loaded deck theme; template colours resolve against its colour scheme. */
    theme: ShallowRef<PptxTheme | undefined>;
}

export declare interface UseSlideTemplateInsertionResult {
    /** Insert the given slide template directly after the active slide. */
    insertSlideFromTemplate: (templateId: SlideTemplateId) => void;
}

export declare function useSmartArtEditing(input: UseSmartArtEditingInput): SmartArtEditingApi;

export declare interface UseSmartArtEditingInput {
    /** Current SmartArt data for the selected element. */
    smartArtData: ComputedRef<PptxSmartArtData>;
    /** Apply a shallow element patch (typically `ops.updateElement`-backed). */
    apply: (patch: Partial<PptxElement>) => void;
    /**
     * Owning element id + pixel box, used to reflow `drawingShapes` back from the
     * layout engine whenever an edit clears them (see `rebuildDrawingShapesIfCleared`).
     * Omit only in tests that don't care about post-edit rendering.
     */
    elementId?: string;
    box?: ComputedRef<BoundingBox | undefined>;
}

export declare function useSmartArtFocus(): SmartArtFocusApi;

export declare function useSmartArtHoverRect(containerRef: Ref<HTMLElement | null>): {
    hoveredNodeId: Ref<string | null, string | null>;
    hoveredNodeRect: Ref<{
        left: number;
        top: number;
        width: number;
        height: number;
    } | null, InlineEditRect | {
        left: number;
        top: number;
        width: number;
        height: number;
    } | null>;
    onMouseMove: (e: MouseEvent, ignoreEl?: HTMLElement | null) => void;
    onMouseLeave: () => void;
};

/** Construct the reactive edit-state container (no commit policy here). */
export declare function useSmartArtInlineEditState(): SmartArtInlineEditState;

/**
 * useSmartArtNodeEditContext: provides the inline SmartArt node-text and
 * per-node fill editing context (`SmartArtNodeEditKey`, injected by
 * `SmartArtRenderer`), routing every commit through the same
 * history-tracked `updateElement` op the inspector uses. Mirrors the
 * `TableCellEditKey` pattern in `useTableCellEditingContext`. Extracted
 * verbatim from `PowerPointViewer.vue`.
 *
 * Both commit paths reflow `drawingShapes` back from the layout engine when
 * the edit op clears them (every text/style edit does) via
 * `rebuildDrawingShapesIfCleared` -- otherwise the renderer falls back to the
 * generic SVG layout for every node (not just the edited one) the moment any
 * single node is edited.
 */
export declare function useSmartArtNodeEditContext(input: UseSmartArtNodeEditContextInput): void;

export declare interface UseSmartArtNodeEditContextInput {
    /** Plain "editing enabled" flag; both the text-commit and style-commit gates use it. */
    canEdit: () => boolean;
    findActiveElement: (id: string) => PptxElement | undefined;
    /** Wraps `ops.updateElement`; a plain function so this composable can be called before `ops` exists. */
    updateElement: (id: string, patch: Partial<PptxElement>) => void;
    /** Whether inline node editing is currently allowed (edit mode + not presenting). */
    canEditInline: () => boolean;
}

/**
 * useTableCellEditingContext: provides the inline table-cell editing context
 * (`TableCellEditKey`, injected by `TableRenderer`) and the table cell
 * selection + drag-resize context (`provideTableSelection`, injected by
 * `TableRenderer` / `TablePanel`). Both are provided once at the viewer root
 * so the hot `SlideStage` -> `ElementRenderer` chain doesn't thread an
 * `editable` flag and commit callbacks through every element. Extracted
 * verbatim from `PowerPointViewer.vue`.
 */
export declare function useTableCellEditingContext(input: UseTableCellEditingContextInput): UseTableCellEditingContextResult;

export declare interface UseTableCellEditingContextInput {
    /** Plain "editing enabled" flag; gates the column/row resize handlers. */
    canEdit: () => boolean;
    /** Whether inline cell editing is currently allowed (edit mode + not presenting); gates `TableCellEditKey`. */
    canEditInline: () => boolean;
    findActiveElement: (id: string) => PptxElement | undefined;
    /** Wraps `ops.updateElement`; a plain function so this composable can be called before `ops` exists. */
    updateElement: (id: string, patch: Partial<PptxElement>) => void;
    /** Commit a single cell's new text (element-level inline table-cell edit). */
    commitTableCell: (elementId: string, rowIndex: number, colIndex: number, text: string) => void;
}

export declare interface UseTableCellEditingContextResult {
    tableSelection: Ref<TableSelectionState | null>;
}

/**
 * Cell-selection helpers for `TableRenderer`. Injects the shared selection
 * context and derives per-cell highlight state plus the click handler, keeping
 * the SFC script thin.
 */
export declare function useTableCellSelection(elementId: () => string, tableData: () => PptxTableData | undefined): TableCellSelectionApi;

/**
 * useThemeEditing: Design ▸ Themes gallery / Edit theme. Re-themes the whole
 * deck via core's pure `applyThemeToData` (re-resolves slide colours against
 * the new scheme) and writes the new slides/theme/colour-map back
 * (history-aware). Extracted verbatim from `PowerPointViewer.vue`.
 */
export declare function useThemeEditing(input: UseThemeEditingInput): UseThemeEditingResult;

export declare interface UseThemeEditingInput {
    slides: Ref<PptxSlide[]>;
    pptxTheme: Ref<PptxTheme | undefined>;
    themeColorMap: Ref<Record<string, string> | undefined>;
    pushHistory: () => void;
    themeGalleryOpen: Ref<boolean>;
    themeEditorOpen: Ref<boolean>;
    /**
     * Master/layout elements rendered as a separate per-slide overlay layer
     * (not part of `slide.elements`), re-coloured alongside `slides` so an
     * applied theme doesn't leave inherited background shapes painted with
     * the old scheme.
     */
    templateElementsBySlideId: ShallowRef<Record<string, PptxElement[]>>;
}

export declare interface UseThemeEditingResult {
    applyTheme: (colorScheme: PptxThemeColorScheme, fontScheme: PptxThemeFontScheme | undefined, name: string) => void;
    applyThemePreset: (preset: PptxThemePreset) => void;
    applyThemeEdit: (payload: {
        colorScheme: PptxThemeColorScheme;
        fontScheme: PptxThemeFontScheme;
        name: string;
    }) => void;
}

export declare function useToolbarAutoHide(options?: UseToolbarAutoHideOptions): UseToolbarAutoHideResult;

export declare interface UseToolbarAutoHideOptions {
    /**
     * File > Options > Advanced > "Show popup toolbar" (default true). When
     * `false`, `mousemove` never auto-reveals the bar; `setToolbarVisible`
     * (PowerPoint's Ctrl+H) still works, matching React's `popupToolbarEnabled`.
     */
    enabled?: () => boolean;
}

/**
 * useToolbarAutoHide: mouse-idle visibility for the floating presentation
 * toolbar.
 *
 * Vue port of the auto-hide half of React's `usePresentationAnnotations`
 * (`toolbarVisible` state): the toolbar starts hidden, becomes visible on any
 * `mousemove`, and hides again after `AUTO_HIDE_DELAY_MS` of no further
 * movement. Real touch interactions do not dispatch `mousemove`, so on a
 * touch-only device the toolbar simply never appears, which matters: the
 * bar sits directly over `PresentationTouchControls`' fixed prev/next
 * buttons, and without gating `pointer-events` off while hidden it silently
 * swallows taps meant for those buttons.
 *
 * The host is expected to bind both `opacity` and `pointer-events` to
 * `toolbarVisible` (not just `opacity`), exactly like React's wrapping div in
 * `ViewerCanvasArea.tsx`.
 */
export declare interface UseToolbarAutoHideResult {
    /** Whether the toolbar should currently be shown (and clickable). */
    toolbarVisible: Readonly<Ref<boolean>>;
    /**
     * Show or hide the toolbar explicitly, for PowerPoint's Ctrl+H. Any later
     * mouse movement resumes the normal auto-hide cycle.
     */
    setToolbarVisible: (visible: boolean) => void;
}

/**
 * useToolbarVisibility: turns a host's `hiddenActions?: ToolbarActionId[]` prop
 * (and, optionally, File > Options > Customize Ribbon's `hiddenTabIds`) into
 * per-button visibility checks and a filtered ribbon-tab list, keeping that
 * matching logic out of the toolbar/ribbon component files themselves. All of
 * the actual matching lives in `pptx-viewer-shared` (`isActionHidden` /
 * `filterVisibleTabs` / `resolveVisibleRibbonTabs` / `TOOLBAR_TABS`); this
 * composable just adapts it to Vue's reactivity so callers can read both
 * inputs through getters, the same convention as the other ribbon-props
 * composables (see `useRibbonProps.ts`).
 *
 * The two hiding mechanisms are independent and both apply: a host can hide a
 * tab via `hiddenActions` regardless of the user's own Customize Ribbon
 * choice, and a user's Customize Ribbon choice hides a tab regardless of what
 * the host passed. The File tab always survives (`resolveVisibleRibbonTabs`).
 *
 * @param hiddenActions getter for the host's `hiddenActions` prop (undefined or empty = hide nothing).
 * @param viewerOptions getter for the live File > Options snapshot; omit (or
 *   return `undefined`) to skip the Customize Ribbon filter, e.g. for a caller
 *   that only needs `isHidden` and has no options store in scope.
 */
export declare function useToolbarVisibility(hiddenActions: () => readonly ToolbarActionId[] | undefined, viewerOptions?: () => ViewerOptions | undefined): UseToolbarVisibilityResult;

export declare interface UseToolbarVisibilityResult {
    /** True when `id` is in the host's `hiddenActions` list (a button/tab to hide). */
    isHidden: (id: ToolbarActionId) => boolean;
    /**
     * The canonical ribbon-tab list, filtered down to the ones the host has not
     * hidden AND the ones the user has not unticked in File > Options >
     * Customize Ribbon (when `viewerOptions` is supplied).
     */
    visibleTabs: ComputedRef<ToolbarTabDefinition[]>;
}

export declare function useTouchGestures(input: UseTouchGesturesInput): void;

/**
 * `useTouchGestures`: attach the shared multi-touch gesture recogniser to a
 * canvas element on touch devices.
 *
 * The gesture state machine itself is framework-agnostic and lives in
 * `pptx-viewer-shared` (`createTouchGestureRecognizer`); this composable only
 * owns the Vue lifecycle: attaching native `touch*` listeners with
 * `{ passive: false }` for `touchstart` / `touchmove` so the recogniser can call
 * `preventDefault()` to suppress the browser's default pinch-zoom, attaching
 * `touchend` / `touchcancel` passively, and re-attaching when the target node
 * identity changes. Mirrors the React `useTouchGestures` hook wiring.
 *
 * Supports:
 *   - Pinch-to-zoom: two-finger spread/pinch to zoom in/out.
 *   - Swipe: single-finger horizontal swipe (slide navigation in present mode).
 *   - Long-press: single-finger hold for 500ms (context-menu trigger).
 *
 * @module useTouchGestures
 */
export declare interface UseTouchGesturesInput {
    /** The element to attach touch listeners to (reactive ref). */
    targetRef: Ref<HTMLElement | null>;
    /** Current zoom scale: used as the baseline for pinch gestures (reactive). */
    currentScale: Ref<number>;
    /** Minimum zoom scale for clamping. */
    minScale: number;
    /** Maximum zoom scale for clamping. */
    maxScale: number;
    /** Callbacks for gesture events. */
    callbacks: TouchGestureCallbacks;
    /** Set to a falsey ref/value to disable all gesture handling. Default: enabled. */
    enabled?: Ref<boolean> | boolean;
}

export declare function useVersionHistory(options: UseVersionHistoryOptions): UseVersionHistoryResult;

export declare interface UseVersionHistoryOptions {
    /** The live editor slide list (typically a `shallowRef<PptxSlide[]>`). */
    slides: Ref<PptxSlide[]>;
    /**
     * Snapshot the current live state onto the editor undo stack before a
     * restore reassigns `slides.value`, so a restore is one undoable step.
     */
    pushHistory: () => void;
    /** Maximum number of retained versions. Defaults to {@link DEFAULT_MAX_VERSIONS}. */
    maxVersions?: number;
}

export declare interface UseVersionHistoryResult {
    /** Reactive, newest-last list of captured versions. */
    versions: Ref<SlideVersion[]>;
    /** True when at least one version has been captured. */
    hasVersions: ComputedRef<boolean>;
    /**
     * Capture the current `slides.value` as a new named version.
     *
     * @param label A human-readable label (e.g. "Before edit", a filename).
     * @param now   Capture timestamp in epoch ms (caller supplies `Date.now()`).
     * @returns The created {@link SlideVersion}.
     */
    capture: (label: string, now: number) => SlideVersion;
    /**
     * Restore the version with the given id into the live slide ref. Snapshots
     * the current state onto the undo stack first (history-aware). No-op when the
     * id is unknown. Returns `true` when a restore occurred.
     */
    restore: (id: string) => boolean;
    /** Remove the version with the given id. Returns `true` when one was removed. */
    remove: (id: string) => boolean;
    /** Drop every captured version. */
    clear: () => void;
}

/**
 * useVersionHistoryWiring: File ▸ Version History panel plus the
 * restore-vs-current compare view, layered on top of the underlying
 * `useVersionHistory` snapshot store. Extracted verbatim from
 * `PowerPointViewer.vue`.
 */
export declare function useVersionHistoryWiring(input: UseVersionHistoryWiringInput): UseVersionHistoryWiringResult;

export declare interface UseVersionHistoryWiringInput {
    slides: Ref<PptxSlide[]>;
    pushHistory: () => void;
}

export declare interface UseVersionHistoryWiringResult {
    versionHistory: UseVersionHistoryResult;
    showVersionHistory: Ref<boolean>;
    compareResult: Ref<CompareResult | null>;
    compareVersionId: Ref<string | null>;
    showCompare: ComputedRef<boolean>;
    onVersionRestore: (id: string) => void;
    onVersionDelete: (id: string) => void;
    onVersionCompare: (id: string) => void;
    compareWithSlides: (incoming: PptxSlide[]) => void;
    onCompareClose: () => void;
    onCompareAcceptAll: () => void;
}

/**
 * useViewerSettingsDialog: File > Options dialog state plus the two-way sync
 * between the full options model and the scattered legacy viewer state (the
 * six `ViewerSettings` toggles the ribbon / title bar drive directly).
 */
export declare function useViewerSettingsDialog(input: UseViewerSettingsDialogInput): UseViewerSettingsDialogResult;

export declare interface UseViewerSettingsDialogInput {
    autoSave: Ref<boolean>;
    spellCheck: Ref<boolean>;
    showGrid: Ref<boolean>;
    showRulers: Ref<boolean>;
    snapToGrid: Ref<boolean>;
    reducedMotion: Ref<boolean>;
    /**
     * The File > Options store (see `useViewerOptionsStore`). When provided, the
     * six legacy `ViewerSettings` toggles stay the behavior source and are kept
     * in sync with the options model both ways, mirroring React's guarded
     * bidirectional sync in `PowerPointViewer.tsx`.
     */
    optionsStore?: ViewerOptionsStore;
    /** Reactive snapshot of `optionsStore` (from `useViewerOptionsStore`). */
    viewerOptions?: Ref<ViewerOptions>;
}

export declare interface UseViewerSettingsDialogResult {
    showSettings: Ref<boolean>;
    viewerSettings: Ref<ViewerSettings>;
    onSettingsUpdate: (next: ViewerSettings) => void;
}

declare interface ViewerAccessibilityOptions {
    showAccessibilityStatus: boolean;
    feedbackWithSound: boolean;
    soundScheme: FeedbackSoundScheme;
    showShortcutKeysInScreenTips: boolean;
    reducedMotion: boolean;
}

declare interface ViewerAdvancedOptions {
    autoSelectEntireWord: boolean;
    allowTextDragAndDrop: boolean;
    maximumUndoSteps: number;
    useSmartCutAndPaste: boolean;
    showPasteOptionsButton: boolean;
    imageDefaultResolution: ImageResolutionPreset;
    doNotCompressImages: boolean;
    chartPropertiesFollowDataPoint: boolean;
    recentPresentationsCount: number;
    showVerticalRuler: boolean;
    showGrid: boolean;
    snapToGrid: boolean;
    disableHardwareAcceleration: boolean;
    /**
     * Force every opt-in interactive 3D scene (SmartArt, bar/line/area/pie/
     * surface charts) to fall back to its flat 2D rendering, even when the
     * host has enabled that scene via its own `smartArt3D`/`*Chart3D` prop.
     * A host opting in says "this deck may want 3D"; this is the viewer
     * user's own override for when the WebGL scenes it renders are too much
     * for their machine. See `resolve3DRenderingFlags`.
     */
    disable3DRendering: boolean;
    /**
     * `p:animEffect/@filter="pixelate"` defaults to snapping the element to
     * its end state (`cutIn`/`cutOut`), matching PowerPoint's own behaviour
     * (COM `CreateVideo` frame-diffing shows PowerPoint performs no animation
     * at all for this filter value). This turns on the blocky mosaic reveal
     * this renderer can build instead, for a viewer that would rather show
     * something animating than PowerPoint's own instant swap. See
     * `resolveFilterEffect` in `animation-filter-effects.ts` and
     * `docs/guide/visual-effects.md`.
     */
    pixelateMosaicAnimation: boolean;
    openDocumentsView: OpenDocumentsView;
    slideShowShowMenuOnRightClick: boolean;
    slideShowShowPopupToolbar: boolean;
    slideShowPromptKeepInkAnnotations: boolean;
    slideShowEndWithBlackSlide: boolean;
    printInBackground: boolean;
    printHighQuality: boolean;
    printUseMostRecentSettings: boolean;
    printWhat: OptionsPrintWhat;
    printColorMode: OptionsPrintColorMode;
    printHiddenSlides: boolean;
    printScaleToFit: boolean;
    printFrameSlides: boolean;
}

/** Dialogs (and the entry points that open them) a host can remove. */
declare type ViewerDialogId = 'options' | 'share' | 'broadcast' | 'print' | 'export';

/**
 * The click-to-place drawing tools of Insert > Shapes > Lines: Freeform:
 * Shape and Curve.
 */
declare type ViewerDrawingToolId = FreeformToolKind;

/** Feature areas that can be switched off as a whole. */
declare type ViewerFeatureId = 'ai' | 'collaboration' | 'comments' | 'presentMode' | 'editPoints';

declare interface ViewerGeneralOptions {
    displayOptimization: DisplayOptimization;
    showMiniToolbar: boolean;
    enableLivePreview: boolean;
    collapseRibbonAutomatically: boolean;
    collapseSearchByDefault: boolean;
    screenTipStyle: ScreenTipStyle;
    userName: string;
    userInitials: string;
    showStartScreen: boolean;
    /**
     * Lets the user hand a local font file to the viewer so decks authored
     * with a font the browser lacks render with the real face.
     *
     * Off by default. The registration reads a file the user picks and adds it
     * to the page's font set for the session, which is a capability a host
     * embedding the viewer should opt into rather than inherit.
     */
    enableCustomFontUpload: boolean;
}

/** Viewer interaction mode. Mirrors React `ViewerMode`. */
declare type ViewerMode = 'preview' | 'edit' | 'present' | 'master';

declare type ViewerOptionPrimitive = boolean | number | string;

declare interface ViewerOptions {
    general: ViewerGeneralOptions;
    proofing: ViewerProofingOptions;
    save: ViewerSaveOptions;
    accessibility: ViewerAccessibilityOptions;
    advanced: ViewerAdvancedOptions;
    ribbon: ViewerRibbonOptions;
    quickAccess: ViewerQuickAccessOptions;
    trust: ViewerTrustOptions;
}

/** Locks and host defaults, both keyed `<group>.<key>`. */
declare interface ViewerOptionsConstraints {
    locked?: OptionsSettingValues;
    defaults?: OptionsSettingValues;
}

declare type ViewerOptionsGroupId = keyof ViewerOptions;

/**
 * Framework-neutral store behind the File > Options dialog.
 *
 * Holds a `ViewerOptions` snapshot, notifies subscribers on change, and
 * persists a sparse diff into the shared `pptx-viewer-prefs` localStorage
 * entry so choices survive reloads in every binding.
 */
declare type ViewerOptionsListener = (options: ViewerOptions) => void;

declare interface ViewerOptionsStore {
    getOptions(): ViewerOptions;
    /** Replace the whole snapshot (e.g. hydrating from a host prop). */
    setOptions(next: ViewerOptions): void;
    /** Set one primitive value; ignores unknown keys and mismatched types. */
    setValue(group: ViewerOptionsGroupId, key: string, value: ViewerOptionPrimitive): void;
    getValue(group: ViewerOptionsGroupId, key: string): ViewerOptionPrimitive | undefined;
    /** Toggle a ribbon tab's visibility. The File tab is always kept visible. */
    setRibbonTabHidden(tabId: ToolbarTabId, hidden: boolean): void;
    setQuickAccessCommands(commandIds: readonly string[]): void;
    /** Reset every option (or one tab-group) back to defaults. */
    reset(group?: ViewerOptionsGroupId): void;
    subscribe(listener: ViewerOptionsListener): () => void;
    /**
     * Subscribe to ONE projection of the options, woken only when that
     * projection changes.
     *
     * `subscribe` above wakes on every option change, which in a binding means
     * the whole options consumer re-renders because the user toggled something
     * unrelated. A ribbon control that reads `ribbon.hiddenTabIds` should not
     * care that an autosave interval moved (issue #145).
     *
     * IMPORTANT for array/object slices: every write here deep-clones the whole
     * options object (`cloneViewerOptions`), so a nested array is a NEW array
     * after ANY change, even one that did not touch it. Under the default
     * `Object.is` such a selector would fire on every write and buy nothing.
     * Pass a value equality for those, e.g. the shared `sameArray`.
     */
    subscribeSelector<T>(selector: (options: ViewerOptions) => T, listener: (value: T, previous: T) => void, isEqual?: (a: T, b: T) => boolean): () => void;
    /**
     * Apply several option writes as ONE notification, so a multi-field
     * operation costs a single render instead of one per field.
     */
    batch(write: () => void): void;
    /**
     * Apply host constraints (see `ViewerOptionsConstraints`): `locked` values
     * are forced in and every later write to them is ignored; `defaults`
     * replace the built-in defaults for settings the user never saved, and
     * become what `reset` returns to. Replaces any previous constraints.
     */
    setConstraints(constraints: ViewerOptionsConstraints): void;
    /** True when the host locked `<group>.<key>`. */
    isLocked(group: ViewerOptionsGroupId, key: string): boolean;
}

/**
 * Control/section/tab descriptor types for the File > Options schema, plus
 * the terse constructors the tab-definition modules build panes with.
 */
declare type ViewerOptionsTabId = 'general' | 'proofing' | 'save' | 'language' | 'accessibility' | 'advanced' | 'ribbon' | 'quickAccess' | 'addIns' | 'trust';

/**
 * Chrome regions a host can remove. Each id maps onto one region in every
 * binding; see `VIEWER_PANEL_IDS` for the catalogue.
 */
declare type ViewerPanelId = 'statusBar' | 'slidesPane' | 'inspector' | 'notes' | 'quickAccessToolbar' | 'titleBar';

/**
 * Framework-neutral viewer preferences surfaced by Settings dialogs.
 *
 * Every field is a boolean toggle on purpose: the bindings iterate
 * `keyof ViewerPreferences` and hand each value to a `(key, boolean)` setter,
 * so the deck-authored view properties (grid spacing is a number) live on the
 * extending {@link DeckViewPreferences} instead.
 */
declare interface ViewerPreferences {
    autoSave: boolean;
    spellCheck: boolean;
    showGrid: boolean;
    showRulers: boolean;
    snapToGrid: boolean;
    reducedMotion: boolean;
}

declare interface ViewerProofingOptions {
    autoCorrectTwoInitialCapitals: boolean;
    autoCorrectCapitalizeFirstLetter: boolean;
    autoCorrectCapitalizeDayNames: boolean;
    autoCorrectSmartQuotes: boolean;
    autoCorrectHyphensToDash: boolean;
    autoCorrectFractions: boolean;
    autoCorrectOrdinals: boolean;
    ignoreUppercase: boolean;
    ignoreWordsWithNumbers: boolean;
    ignoreInternetAddresses: boolean;
    flagRepeatedWords: boolean;
    checkSpellingAsYouType: boolean;
    hideSpellingErrors: boolean;
}

declare interface ViewerQuickAccessOptions {
    visible: boolean;
    position: QuickAccessPosition;
    showCommandLabels: boolean;
    /** Ordered ids from `QUICK_ACCESS_COMMAND_CATALOG`. */
    commandIds: string[];
}

declare interface ViewerRibbonOptions {
    /** Ribbon tabs unticked in Customize Ribbon. The File tab can never be hidden. */
    hiddenTabIds: ToolbarTabId[];
}

/**
 * File > Options > Save.
 *
 * Font embedding deliberately has NO entry here. It is owned by the File >
 * Fonts panel, whose toggle is the one the save path reads (see
 * `render/font-embedding`: `describeFontEmbedding` decides the toggle's start
 * position and whether it can do anything at all, `embeddedFontSaveOptions`
 * turns it into the `PptxHandler.save()` slice). This group used to carry a
 * second `embedFonts` boolean, plus an `embedAllFontCharacters` companion, and
 * neither was read by anything: the pane moved a switch that changed no saved
 * byte, while the panel next door moved the real one. Two switches for one
 * setting, one of them lying, is worse than one switch in a less
 * PowerPoint-shaped place.
 */
declare interface ViewerSaveOptions {
    autoSave: boolean;
    autoRecoverIntervalMinutes: number;
    keepLastAutoRecoveredVersion: boolean;
    defaultExportFormat: DefaultExportFormat;
    cacheRetentionDays: number;
    clearCacheOnClose: boolean;
}

declare type ViewerSettings = ViewerPreferences;

declare interface ViewerTrustOptions {
    openInProtectedView: boolean;
    allowExternalContent: boolean;
    confirmExternalHyperlinks: boolean;
}

/** WebM-only tuning. */
export declare interface WebmExportOptions extends MediaExportOptions {
    /** Capture frame rate fed to `captureStream` (default 30). */
    fps?: number;
    /** Video bit rate in bits/s (default 5_000_000 = 5 Mbps, matching React). */
    videoBitsPerSecond?: number;
    /** Recording-phase progress callback: `(currentSlide, totalSlides)`. */
    onRecordProgress?: MediaExportProgress;
}

/**
 * `p:wheel/@spokes` (CT_WheelTransition): PowerPoint's Wheel dialog offers
 * exactly these five spoke counts. Any other authored value (or absence, the
 * schema default) snaps to the nearest one so the keyframe lookup always
 * resolves to a real `pptx-tr-wheel-in-N` block.
 */
export declare const WHEEL_SPOKE_COUNTS: readonly number[];

/**
 * Strongly-typed parsed XML node from fast-xml-parser.
 *
 * The parser is configured with `attributeNamePrefix: '@_'`,
 * `parseAttributeValue: false`, and `parseTagValue: false`, so attribute and
 * text values are always strings at runtime. This type encodes that:
 *
 * - **Attributes** — keys matching `` `@_${string}` `` return
 *   `string | undefined` directly.
 * - **Text content** — `#text` returns `string | undefined`.
 * - **Child elements** — any other string key returns
 *   `XmlObject | XmlObject[] | string | undefined`. The union reflects that
 *   fast-xml-parser may emit an object (single child), an array (repeated
 *   children), or a bare string (text-only element collapsed by the parser).
 *
 * For traversal, prefer the helpers in {@link ./../utils/xml-access} —
 * `xmlChild` / `xmlChildren` / `xmlAttr` / `xmlText` / `xmlPath` — which
 * narrow the union and normalize the single-vs-array duality. Direct
 * indexing works for attributes (typed as string) but chained child access
 * (`obj['p:spPr']?.['a:xfrm']`) requires the helpers or a narrowing cast
 * because TypeScript cannot index into the `XmlObject[] | string` part of
 * the union.
 */
declare interface XmlObject {
    /** Attributes (`@_`-prefixed keys) are always strings at runtime. */
    [attr: `@_${string}`]: string | undefined;
    /** Element text content surfaces under `#text` when present. */
    '#text'?: string;
    /**
     * Child elements keyed by their (namespaced) tag name. fast-xml-parser
     * emits a single object for unique elements, an array for repeated ones,
     * and a bare string for elements collapsed to their text content. Use
     * the helpers in `utils/xml-access` to narrow this union.
     */
    [child: string]: XmlObject | XmlObject[] | string | undefined;
}

declare interface YArrayLike {
    readonly length: number;
    get: (index: number) => unknown;
    push: (items: unknown[]) => void;
    delete: (index: number, length?: number) => void;
    insert: (index: number, items: unknown[]) => void;
    toArray: () => unknown[];
    observe: (handler: () => void) => void;
    unobserve: (handler: () => void) => void;
    observeDeep: (handler: YDeepObserver) => void;
    unobserveDeep: (handler: YDeepObserver) => void;
}

declare type YDeepObserver = (events?: unknown, transaction?: YTransactionLike) => void;

declare interface YDocLike {
    getMap: (name: string) => YMapLike;
    getArray: (name: string) => YArrayLike;
    transact: (fn: () => void, origin?: unknown) => void;
}

declare interface YjsFactories {
    createMap: () => YMapLike;
    createArray: () => YArrayLike;
    createText: () => YTextLike;
    /** Track character identities using the binding's existing Yjs runtime. */
    createTextPositions?: (text: YTextEditableLike) => TextSessionPositions<TrackedTextPosition>;
}

declare interface YMapLike {
    get: (key: string) => unknown;
    set: (key: string, value: unknown) => void;
    delete: (key: string) => void;
    forEach: (cb: (value: unknown, key: string) => void) => void;
}

/** Y.Text surface needed for in-place edits (delete/format on top of insert). */
declare interface YTextEditableLike extends YTextLike {
    delete: (index: number, length: number) => void;
    format: (index: number, length: number, attributes: Record<string, string | null>) => void;
}

declare interface YTextLike {
    insert: (index: number, text: string, attrs?: Record<string, string>) => void;
    toDelta: () => DeltaOp[];
    toString: () => string;
}

/** Shape of the Yjs transaction passed to (deep) observers. */
declare interface YTransactionLike {
    origin?: unknown;
}

/**
 * A Slide Zoom or Section Zoom element (PowerPoint Zoom Object).
 *
 * Zoom elements display a live thumbnail of the target slide and
 * navigate to it on click during presentation mode.
 *
 * @example
 * ```ts
 * const zoom: ZoomPptxElement = {
 *   type: "zoom",
 *   id: "zm_1", x: 300, y: 200, width: 200, height: 120,
 *   zoomType: "slide",
 *   targetSlideIndex: 5,
 * };
 * // => satisfies ZoomPptxElement
 * ```
 */
declare interface ZoomPptxElement extends PptxElementBase, PptxImageProperties {
    type: 'zoom';
    /** Type of zoom: slide-level, section-level, or a multi-section summary. */
    zoomType: 'slide' | 'section' | 'summary';
    /** Zero-based index of the target slide. */
    targetSlideIndex: number;
    /** Section ID for section zoom. */
    targetSectionId?: string;
    /** Ordered section tiles in a Summary Zoom container. */
    summaryTargets?: SummaryZoomTarget[];
    /** Layout mode authored on the Summary Zoom container. */
    summaryLayout?: 'grid' | 'fixed';
    /**
     * `zmPr/@returnToParent` (MS-PPTX `CT_ZoomObjectProperties`, shared by all
     * three Zoom kinds): whether continuing forward from the destination slide
     * during a live show returns to this Zoom's origin slide instead of
     * advancing linearly through the deck. The schema declares `<xsd:attribute
     * name="returnToParent" type="xsd:boolean" use="optional" default="true"/>`,
     * so an ABSENT attribute means `true`, not `false`. This codebase still
     * leaves the field `undefined` (rather than fabricating `true`) when the
     * source XML omits it, so a round-trip never invents an attribute the
     * source never had; a CONSUMER of this field (playback, e.g.
     * `pptx-viewer-shared`'s `resolveZoomNavigationTarget`) must read
     * `returnToParent !== false`, not `Boolean(returnToParent)`, to get the
     * spec-correct effective value. For `zoomType: 'summary'`, this mirrors the
     * first tile's own value; see {@link SummaryZoomTarget.returnToParent} for
     * the per-tile value.
     */
    returnToParent?: boolean;
    /**
     * `zmPr/@transitionDur` (MS-PPTX `CT_ZoomObjectProperties`): the
     * zoom-transition length in milliseconds. PowerPoint's own writer emits a
     * unitless decimal-millisecond value for every OOXML `ST_UniversalTimeOffset`
     * this codebase has observed (see the media-trim/-fade parsers), so this
     * follows the same convention rather than the full TIMEOFFSET grammar's
     * unit suffixes. Undefined uses the destination slide's own transition.
     * For `zoomType: 'summary'`, this mirrors the first tile's own value; see
     * {@link SummaryZoomTarget.transitionDurationMs} for the per-tile value.
     */
    transitionDurationMs?: number;
}

export { }