pptx-vanilla-viewer 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,1766 @@
+import { n, o, m, l, P, d, e, X, p, q, r, s, t, u, v, w, x, y, z, A, B, D, E, F, G, H, J, K, L, h, i, k, j, f, g } from './presentation-CLc4eS3z.js';
+export { P as PptxElement, l as PptxSlide } from './presentation-CLc4eS3z.js';
+import { ViewerTheme } from './theme/index.js';
+export { ViewerTheme, ViewerThemeColors, defaultCssVars, defaultRadius, defaultThemeColors, themeToCssVars, vermilionDarkTheme, vermilionLightTheme } from './theme/index.js';
+export { TranslationKey, keyToLabel, translationsEn } from 'pptx-viewer-shared/i18n';
+
+/**
+ * Built-in theme presets modelled after common PowerPoint themes.
+ *
+ * Each preset provides:
+ * - A display name
+ * - A 12-colour scheme (dk1, dk2, lt1, lt2, accent1-6, hlink, folHlink)
+ * - A font scheme (major/heading + minor/body font families)
+ *
+ * These presets can be passed directly to
+ * {@link PptxHandlerCore.switchTheme} or the React `useThemeSwitching` hook
+ * to apply a complete theme in one step.
+ *
+ * @module pptx-types/theme-presets
+ */
+
+/**
+ * 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);
+ * ```
+ */
+interface PptxThemePreset {
+    /** Unique identifier for the preset. */
+    id: string;
+    /** Human-readable display name. */
+    name: string;
+    /** The 12-colour scheme. */
+    colorScheme: d;
+    /** Heading and body font families. */
+    fontScheme: e;
+}
+
+/**
+ * SDK input types for the headless PPTX builder API.
+ *
+ * These types provide a simplified, ergonomic interface for creating
+ * presentation elements programmatically. Internal types (PptxElement,
+ * ShapeStyle, TextStyle) are the canonical model; these types are
+ * convenience wrappers that get mapped to the internal model by
+ * the builder functions.
+ *
+ * @module sdk/types
+ */
+
+/** Position and size in pixels. Converted to EMU internally when needed. */
+interface ElementPosition {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    rotation?: number;
+}
+type FillInput = {
+    type: 'solid';
+    color: string;
+    opacity?: number;
+} | {
+    type: 'gradient';
+    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';
+};
+interface StrokeInput {
+    color?: string;
+    width?: number;
+    dash?: h;
+    opacity?: number;
+    join?: 'round' | 'bevel' | 'miter';
+    cap?: 'flat' | 'rnd' | 'sq';
+}
+interface ShadowInput {
+    color?: string;
+    blur?: number;
+    offsetX?: number;
+    offsetY?: number;
+    opacity?: number;
+}
+interface TextStyleInput {
+    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;
+    spaceBefore?: number;
+    spaceAfter?: number;
+}
+interface TextSegmentInput {
+    text: string;
+    style?: Partial<TextStyleInput>;
+}
+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;
+}
+interface ShapeOptions extends Partial<ElementPosition> {
+    fill?: FillInput;
+    stroke?: StrokeInput;
+    text?: string;
+    textStyle?: Partial<TextStyleInput>;
+    adjustments?: Record<string, number>;
+    shadow?: ShadowInput;
+    opacity?: number;
+}
+interface ImageOptions extends Partial<ElementPosition> {
+    altText?: string;
+    cropLeft?: number;
+    cropTop?: number;
+    cropRight?: number;
+    cropBottom?: number;
+    opacity?: number;
+}
+interface TableInput {
+    rows: TableRowInput[];
+    columnWidths?: number[];
+    style?: string;
+    bandRows?: boolean;
+    bandColumns?: boolean;
+    firstRow?: boolean;
+    lastRow?: boolean;
+    firstCol?: boolean;
+    lastCol?: boolean;
+}
+interface TableRowInput {
+    cells: TableCellInput[];
+    height?: number;
+}
+interface TableCellInput {
+    text: string;
+    style?: Partial<TextStyleInput>;
+    fill?: FillInput;
+    gridSpan?: number;
+    rowSpan?: number;
+}
+interface TableOptions extends Partial<ElementPosition> {
+}
+interface ChartSeriesInput {
+    name: string;
+    values: number[];
+    color?: string;
+}
+interface ChartInput {
+    series: ChartSeriesInput[];
+    categories: string[];
+    title?: string;
+    hasLegend?: boolean;
+    legendPosition?: 't' | 'b' | 'l' | 'r' | 'tr';
+    grouping?: 'clustered' | 'stacked' | 'percentStacked';
+}
+interface ChartOptions extends Partial<ElementPosition> {
+}
+interface ConnectorOptions extends Partial<ElementPosition> {
+    type?: 'straight' | 'bent' | 'curved';
+    stroke?: StrokeInput;
+    startArrow?: i;
+    endArrow?: i;
+    from?: {
+        elementId: string;
+        site: number;
+    };
+    to?: {
+        elementId: string;
+        site: number;
+    };
+}
+interface MediaOptions extends Partial<ElementPosition> {
+    autoPlay?: boolean;
+    loop?: boolean;
+    volume?: number;
+    trimStartMs?: number;
+    trimEndMs?: number;
+    posterFrame?: string;
+}
+interface GroupOptions extends Partial<ElementPosition> {
+}
+type BackgroundInput = {
+    type: 'solid';
+    color: string;
+} | {
+    type: 'gradient';
+    angle?: number;
+    stops: Array<{
+        color: string;
+        position: number;
+    }>;
+} | {
+    type: 'image';
+    source: string;
+};
+interface TransitionInput {
+    type: j;
+    duration?: number;
+    direction?: string;
+    advanceAfterMs?: number;
+}
+interface AnimationInput {
+    preset: f;
+    trigger?: g;
+    duration?: number;
+    delay?: number;
+}
+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;
+}
+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;
+    };
+}
+
+/**
+ * Fluent builder for constructing slides with elements.
+ *
+ * Provides a chainable API for adding elements, setting slide properties,
+ * and building a complete {@link PptxSlide}.
+ *
+ * @module sdk/SlideBuilder
+ */
+
+/**
+ * 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: k, 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: P[], options?: GroupOptions): this;
+    /** Add a pre-built element directly. */
+    addElement(element: P): 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(): P;
+    }): 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 P[];
+    /**
+     * 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(): P | 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(): l;
+}
+
+/**
+ * Factory for creating PPTX presentations from scratch.
+ *
+ * Generates a minimal valid OpenXML package (ZIP) containing all
+ * required parts (presentation.xml, theme, slide master, layouts,
+ * content types, relationships, and document properties). The
+ * generated package is then loaded by {@link PptxHandler} so that
+ * all existing editing and save operations work transparently.
+ *
+ * @module sdk/PresentationBuilder
+ */
+
+/** Result returned by {@link PresentationBuilder.create}. */
+interface PresentationBuilderResult {
+    /** Initialized handler ready for editing and saving. */
+    handler: PptxHandler;
+    /** Parsed presentation data. */
+    data: m;
+    /** Convenience slide builder factory. */
+    createSlide: (layoutName?: string) => SlideBuilder;
+}
+
+/**
+ * Fluent interface for navigating and mutating a {@link PptxData} structure.
+ * Provides method-chaining access to slides, elements, and notes.
+ */
+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(): m;
+}
+/**
+ * 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: m);
+    /**
+     * 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: m): 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(): m;
+    /** Pascal-case alias for {@link project}. */
+    Project(): m;
+}
+/**
+ * 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: l, 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(): l;
+    /** Pascal-case alias for {@link project}. */
+    Project(): l;
+    /** 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: l, slideBuilder: PptxSlideBuilder);
+    /**
+     * Append an element to the slide's element list.
+     * @param element - The element to add.
+     * @returns This builder for chaining.
+     */
+    add(element: P): 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: P) => P): this;
+    /** Return the current elements array. */
+    project(): P[];
+    /** Navigate back to the slide builder. */
+    done(): PptxSlideBuilder;
+}
+/**
+ * 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: l, 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;
+}
+
+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;
+}
+/** Output format for the save pipeline. */
+type PptxSaveFormat = 'pptx' | 'ppsx' | 'pptm';
+interface PptxHandlerSaveOptions {
+    headerFooter?: r;
+    presentationProperties?: s;
+    customShows?: t[];
+    sections?: u[];
+    coreProperties?: v;
+    appProperties?: w;
+    customProperties?: x[];
+    /** Updated notes master data to save back to notesMaster1.xml. */
+    notesMaster?: y;
+    /** Updated handout master data to save back to handoutMaster1.xml. */
+    handoutMaster?: z;
+    /**
+     * 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?: A[];
+    /**
+     * 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?: B[];
+    /** Updated tag collections to save back to ppt/tags/tag*.xml. */
+    tags?: D[];
+    /** Photo album metadata to save back to `p:photoAlbum`. */
+    photoAlbum?: E;
+    /** East Asian line-break settings to save back to `p:kinsoku`. */
+    kinsoku?: F;
+    /** Write-protection verifier. Set to `null` to remove, `undefined` to preserve existing. */
+    modifyVerifier?: G | null;
+    /** View properties to save back to ppt/viewProps.xml. */
+    viewProperties?: H;
+    /**
+     * 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?: J;
+    /**
+     * Target output format.
+     * - `'pptx'` (default): Standard presentation.
+     * - `'ppsx'`: Slide-show file (opens in presentation mode).
+     * - `'pptm'`: Macro-enabled presentation (requires VBA data).
+     */
+    outputFormat?: PptxSaveFormat;
+    /**
+     * 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?: K[];
+    /**
+     * 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';
+}
+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(): n[];
+    getLayoutOptions(): o[];
+    createXmlBuilder(data: m): PptxXmlBuilder;
+    Builder(data: m): PptxXmlBuilder;
+    setTemplateBackground(path: string, backgroundColor: string | undefined): void;
+    setPresentationTheme(themePath: string, applyToAllMasters?: boolean): Promise<void>;
+    getTemplateBackgroundColor(path: string): string | undefined;
+    updateThemeColorScheme(colorScheme: d): Promise<void>;
+    updateThemeFontScheme(fontScheme: e): Promise<void>;
+    updateThemeName(name: string): Promise<void>;
+    applyTheme(colorScheme: d, fontScheme: e, themeName?: string): Promise<void>;
+    load(data: ArrayBuffer, options?: PptxHandlerLoadOptions): Promise<m>;
+    getChartDataForGraphicFrame(slidePath: string, graphicFrame: X | undefined): Promise<p | undefined>;
+    getSmartArtDataForGraphicFrame(slidePath: string, graphicFrame: X | undefined): Promise<q | 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: l[], options?: PptxHandlerSaveOptions): Promise<Uint8Array>;
+    exportSlides(slides: l[], options: L): 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: l[]): Promise<o[]>;
+    /**
+     * 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<P[]>;
+    /**
+     * 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: l[]): Promise<l>;
+}
+
+/**
+ * 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}.
+ */
+interface IPptxHandlerRuntimeFactory {
+    /** Instantiate and return a new runtime implementation. */
+    createRuntime(): IPptxHandlerRuntime;
+}
+
+/**
+ * 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. */
+type EncryptionAlgorithm = 'AES128' | 'AES256';
+/** Encryption options for creating encrypted files. */
+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;
+}
+
+/**
+ * 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
+ * ```
+ */
+interface PptxHandlerCoreDependencies {
+    runtime?: IPptxHandlerRuntime;
+    runtimeFactory?: IPptxHandlerRuntimeFactory;
+}
+/**
+ * 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(): n[];
+    /**
+     * 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(): o[];
+    /**
+     * 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: m): PptxXmlBuilder;
+    /**
+     * Shorthand alias for {@link createXmlBuilder}.
+     *
+     * @param data - Parsed presentation data.
+     * @returns A {@link PptxXmlBuilder} instance.
+     */
+    Builder(data: m): 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: d): 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: e): Promise<void>;
+    /**
+     * Rename the presentation theme.
+     *
+     * @param name - New display name for the theme.
+     */
+    updateThemeName(name: string): Promise<void>;
+    /**
+     * 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: d, fontScheme: e, 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: m, colorScheme: d, fontScheme?: e, themeName?: string): Promise<m>;
+    /**
+     * 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: m, preset: PptxThemePreset): Promise<m>;
+    /**
+     * 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<m>;
+    /**
+     * 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: X | undefined): Promise<p | 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: X | undefined): Promise<q | 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: l[], 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: l[], 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: l[]): Promise<o[]>;
+    /**
+     * 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<P[]>;
+    /**
+     * 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: l[]): Promise<l>;
+    /**
+     * 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 as individual PPTX files.
+     *
+     * Each entry in the returned map is keyed by slide index and contains a
+     * standalone `Uint8Array` PPTX with only that slide.
+     *
+     * @param slides  - Full slide array.
+     * @param options - Export options (slide indexes, format, etc.).
+     * @returns A `Map<slideIndex, Uint8Array>` of exported files.
+     *
+     * @example
+     * ```ts
+     * const exports = await handler.exportSlides(data.slides, {
+     *   slideIndexes: [0, 2],
+     * });
+     * for (const [idx, bytes] of exports) {
+     *   await fs.writeFile(`slide_${idx}.pptx`, Buffer.from(bytes));
+     * }
+     * // => Map<number, Uint8Array> — one standalone .pptx per exported slide
+     * ```
+     */
+    exportSlides(slides: l[], options: L): Promise<Map<number, Uint8Array>>;
+}
+
+/**
+ * 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>;
+}
+
+/**
+ * Framework-agnostic public types shared by the viewer bindings.
+ *
+ * These were duplicated in the React (`types-ui.ts`) and Vue (`viewer/types.ts`)
+ * packages; this is the canonical copy. Each binding layers its own
+ * framework-specific prop/event/handle types on top of these.
+ */
+
+/** Canvas dimensions in pixels. */
+interface CanvasSize {
+    width: number;
+    height: number;
+}
+/** A neutral CSS map (framework `CSSProperties` are structurally compatible). */
+type CssStyleMap = Record<string, string | number>;
+
+/**
+ * Minimal i18n for the vanilla binding.
+ *
+ * The other bindings delegate to their framework's i18n runtime (react-i18next,
+ * vue-i18n, ngx-translate) fed by the shared `pptx.*` dictionary. The vanilla
+ * binding has no framework, so this module provides the one missing piece: a
+ * `t(key, params)` lookup with `{{param}}` interpolation over the same shared
+ * English dictionary, plus per-locale overrides supplied by the host.
+ *
+ * Resolution order: host dictionary for the active locale, then the built-in
+ * English dictionary, then a humanised fallback derived from the key (shared
+ * `keyToLabel`), so a missing key never renders as a raw `pptx.*` string.
+ */
+/** Translate a dotted `pptx.*` key with optional `{{param}}` interpolation. */
+type Translator = (key: string, params?: Record<string, string | number>) => string;
+/** Locale to flat `key: message` dictionary map supplied by the host. */
+type TranslationMessages = Record<string, Record<string, string>>;
+/**
+ * Build a {@link Translator} for a locale. `messages[locale]` (when provided)
+ * wins over the built-in English dictionary; English is always the fallback.
+ */
+declare function createTranslator(locale?: string, messages?: TranslationMessages): Translator;
+
+/** Discriminant values of the {@link PptxElement} union (`'text'`, `'chart'`, ...). */
+type PptxElementType = P['type'];
+/**
+ * Everything an element renderer may need, passed to every renderer call.
+ *
+ * The context is immutable per slide render. Renderers must create DOM through
+ * `context.document` (never the global `document`) so slides can render into
+ * detached documents (tests, export pipelines).
+ */
+interface ElementRenderContext {
+    /** Document used for all DOM creation. */
+    readonly document: Document;
+    /** The slide being rendered. */
+    readonly slide: l;
+    /** Full slide canvas size in CSS px (elements are positioned in this space). */
+    readonly canvasSize: CanvasSize;
+    /**
+     * The scale the stage is rendered at (1 = 100%). The stage applies it via a
+     * CSS transform, so renderers should lay out in unscaled canvas px; `scale`
+     * is informational (e.g. for raster density decisions).
+     */
+    readonly scale: number;
+    /** Archive-path to displayable URL map for media + poster frames. */
+    readonly mediaDataUrls: ReadonlyMap<string, string>;
+    /** Shared-dictionary translator (`pptx.*` keys). */
+    readonly t: Translator;
+    /** The registry in effect, for renderers that need to inspect it. */
+    readonly registry: ElementRendererRegistry;
+    /**
+     * Render a child element through the registry (used by the group renderer
+     * for recursion; custom renderers may nest elements the same way).
+     */
+    renderElement(element: P, zIndex: number): HTMLElement | SVGElement | null;
+}
+/**
+ * Renders one slide element to a DOM node (or `null` to render nothing).
+ *
+ * Contract:
+ * - Position absolutely within the stage: apply the shared
+ *   `getContainerStyle(element, zIndex)` map (or equivalent) to the returned
+ *   root node.
+ * - Set `dataset.elementId = element.id` on the root node.
+ * - Create all DOM via `context.document`.
+ * - Never mutate `element` or anything on the context.
+ */
+type ElementRenderer = (element: P, zIndex: number, context: ElementRenderContext) => HTMLElement | SVGElement | null;
+/**
+ * Registry dispatching elements to renderers by their `type` discriminant.
+ *
+ * Additional element types are supported by registering a renderer for the
+ * type; unregistered types fall through to the fallback renderer (a typed
+ * placeholder box by default). See `render/elements/README.md` for the
+ * step-by-step contract.
+ */
+interface ElementRendererRegistry {
+    /** Register (or replace) the renderer for an element type. */
+    register(type: PptxElementType, renderer: ElementRenderer): void;
+    /** Remove the renderer for an element type (falls back afterwards). */
+    unregister(type: PptxElementType): void;
+    /** The renderer registered for a type, or `undefined`. */
+    get(type: PptxElementType): ElementRenderer | undefined;
+    /** True when a dedicated (non-fallback) renderer is registered. */
+    has(type: PptxElementType): boolean;
+    /** Replace the fallback renderer used for unregistered types. */
+    setFallback(renderer: ElementRenderer): void;
+    /** The renderer to use for a type: registered renderer or fallback. */
+    resolve(type: PptxElementType): ElementRenderer;
+    /** All types with a dedicated renderer (sorted, for tests/debugging). */
+    registeredTypes(): PptxElementType[];
+}
+
+/**
+ * Create an empty {@link ElementRendererRegistry}.
+ *
+ * The default fallback renders nothing; `createDefaultRegistry()` (in
+ * `./elements`) installs the built-in renderers plus the typed placeholder
+ * fallback.
+ */
+declare function createElementRendererRegistry(): ElementRendererRegistry;
+
+/**
+ * Apply a shared `CssStyleMap` to an element. The shared builders emit a mix
+ * of camelCase (`backgroundColor`) and kebab-case (`background-color`) keys;
+ * both are normalised to `style.setProperty` calls.
+ */
+declare function applyStyleMap(el: HTMLElement | SVGElement, style: CssStyleMap): void;
+/** Create an element with an optional class and style map. */
+declare function createEl<K extends keyof HTMLElementTagNameMap>(doc: Document, tag: K, className?: string, style?: CssStyleMap): HTMLElementTagNameMap[K];
+/** Create a namespaced SVG element with optional attributes. */
+declare function createSvgEl<K extends keyof SVGElementTagNameMap>(doc: Document, tag: K, attrs?: Record<string, string | number | undefined>): SVGElementTagNameMap[K];
+
+interface SlideStageOptions {
+    document: Document;
+    slide: l;
+    canvasSize: CanvasSize;
+    mediaDataUrls: ReadonlyMap<string, string>;
+    registry: ElementRendererRegistry;
+    t: Translator;
+    /** Scale applied via CSS transform (default 1). */
+    scale?: number;
+}
+/**
+ * Render one slide as a fixed-size stage: the resolved slide background plus
+ * every element dispatched through the registry, scaled with a CSS transform
+ * (`transform-origin: top left`), exactly like the other bindings' stages.
+ *
+ * The returned node is `canvasSize * scale` ON SCREEN but laid out at the
+ * unscaled canvas size, so the caller should wrap it in a box sized to
+ * `canvasSize * scale` (the viewer's stage host and thumbnails both do).
+ */
+declare function renderSlideStage(options: SlideStageOptions): HTMLElement;
+
+/**
+ * The registry the viewer uses by default.
+ *
+ * Dedicated renderers: `text`, `shape`, `image`, `picture`, `group`,
+ * `connector`, `table`, `chart`, `smartArt`, `media`, `ink`, `ole`. The
+ * remaining types (`contentPart`, `zoom`, `model3d`, `unknown`) fall through
+ * to the typed placeholder fallback until their renderers land; see
+ * `./README.md` for the contract to add one.
+ */
+declare function createDefaultRegistry(): ElementRendererRegistry;
+
+/** `zoom` is either an explicit scale factor (1 = 100%) or fit-to-viewport. */
+type ZoomLevel = number | 'fit';
+/**
+ * The vanilla viewer's reactive view state. Kept intentionally flat and small;
+ * everything here is what the DOM render layer consumes.
+ */
+interface ViewerState {
+    /** Parsed slides (image/media URLs already patched in by the load pipeline). */
+    slides: l[];
+    /** Slide canvas size in CSS pixels. */
+    canvasSize: CanvasSize;
+    /** Archive-path to displayable URL map for media + poster frames. */
+    mediaDataUrls: Map<string, string>;
+    /** Zero-based index of the visible slide. */
+    currentSlide: number;
+    /** Requested zoom (explicit factor or fit-to-viewport). */
+    zoom: ZoomLevel;
+    /** True while a load is in flight. */
+    loading: boolean;
+    /** Error message from the last failed load, or null. */
+    error: string | null;
+    /** True while presentation (fullscreen) mode is active. */
+    presenting: boolean;
+    /** True when editing interactions (select/move/resize/...) are enabled. */
+    editable: boolean;
+    /** Id of the selected element on the current slide, or null. */
+    selectedElementId: string | null;
+    /** True when the document has unsaved edits (cleared by a save). */
+    dirty: boolean;
+    /**
+     * True while a pointer gesture (drag/resize/rotate) is in flight. Thumbnail
+     * re-renders are deferred until the gesture ends.
+     */
+    interactionActive: boolean;
+}
+
+/**
+ * Content sources accepted by the vanilla viewer: raw bytes, a Blob/File, or
+ * a URL string to fetch.
+ */
+type PptxViewerSource = ArrayBuffer | Uint8Array | Blob | string;
+
+/**
+ * Public API types for the vanilla (zero-framework) PowerPoint viewer.
+ *
+ * Derived from the Vue binding's `PowerPointViewerProps` / emits, translated
+ * to plain options + callback functions (there is no framework event system
+ * to emit through).
+ */
+/** Callbacks mirroring the Vue component's emits. */
+interface PptxViewerCallbacks {
+    /** Fired after a presentation loads successfully. */
+    onLoad?: (info: {
+        slideCount: number;
+        canvasSize: CanvasSize;
+    }) => void;
+    /** Fired when a load fails (message is already localised/best-effort). */
+    onError?: (message: string, error: unknown) => void;
+    /** Fired when the active slide changes (zero-based index). */
+    onSlideChange?: (index: number) => void;
+    /** Fired when the effective zoom scale changes (1 = 100%). */
+    onZoomChange?: (scale: number) => void;
+    /** Fired when presentation (fullscreen) mode is entered or exited. */
+    onPresentationChange?: (presenting: boolean) => void;
+    /** Fired after any document mutation (move, resize, edit, undo, ...). */
+    onChange?: () => void;
+    /** Fired when the unsaved-edits flag flips (a save resets it). */
+    onDirtyChange?: (dirty: boolean) => void;
+    /** Fired when the selected element changes (`null` = no selection). */
+    onSelectionChange?: (elementId: string | null) => void;
+}
+interface PptxViewerOptions extends PptxViewerCallbacks {
+    /**
+     * The presentation to open: raw `.pptx` bytes (ArrayBuffer / Uint8Array),
+     * a Blob/File, or a URL string to fetch. Omit to start empty and call
+     * `loadFile` / `loadUrl` later.
+     */
+    source?: PptxViewerSource;
+    /** Viewer chrome theme (shared `ViewerTheme`: colors, radius, CSS vars). */
+    theme?: ViewerTheme;
+    /** UI locale (default `'en'`). Dictionaries come from `messages`. */
+    locale?: string;
+    /**
+     * Per-locale `pptx.*` message dictionaries. English falls back to the
+     * built-in shared dictionary; other locales fall back to English.
+     */
+    messages?: TranslationMessages;
+    /** Zero-based slide to show after load (default 0). */
+    initialSlide?: number;
+    /**
+     * Enable editing (default `false`): click to select, drag/resize/rotate,
+     * inline text editing, keyboard shortcuts, undo/redo, and the toolbar
+     * Save button. Toggle later via `setEditable`.
+     */
+    editable?: boolean;
+    /**
+     * Legacy flag superseded by {@link editable}; kept so existing option
+     * objects stay type-valid. It has no effect.
+     */
+    readOnly?: boolean;
+    /** Show the toolbar (default `true`). */
+    showToolbar?: boolean;
+    /** Show the thumbnail sidebar (default `true`). */
+    showThumbnails?: boolean;
+    /**
+     * Custom element-renderer registry. Defaults to `createDefaultRegistry()`;
+     * pass your own (or mutate the default via `getRegistry()`) to add or
+     * override element renderers.
+     */
+    registry?: ElementRendererRegistry;
+}
+/** The viewer handle returned by `createPptxViewer`. */
+interface PptxViewerInstance {
+    /** Load a presentation from bytes or a Blob/File (replaces the current one). */
+    loadFile(file: Blob | ArrayBuffer | Uint8Array): Promise<void>;
+    /** Fetch and load a presentation from a URL. */
+    loadUrl(url: string): Promise<void>;
+    /** Go to the next slide (no-op on the last slide). */
+    next(): void;
+    /** Go to the previous slide (no-op on the first slide). */
+    prev(): void;
+    /** Jump to a zero-based slide index (clamped). */
+    goToSlide(index: number): void;
+    /** Number of slides in the loaded presentation (0 when none). */
+    getSlideCount(): number;
+    /** Zero-based index of the visible slide. */
+    getCurrentSlide(): number;
+    /** Effective zoom scale (1 = 100%), after fit resolution. */
+    getZoom(): number;
+    /** Set an explicit zoom scale, or `'fit'` for fit-to-viewport. */
+    setZoom(zoom: ZoomLevel): void;
+    zoomIn(): void;
+    zoomOut(): void;
+    zoomToFit(): void;
+    /** Apply a new viewer theme (pass `undefined` to reset to defaults). */
+    setTheme(theme: ViewerTheme | undefined): void;
+    /** Switch the UI locale (rebuilds the chrome labels). */
+    setLocale(locale: string): void;
+    /** Enter presentation mode (real Fullscreen API). */
+    enterPresentation(): Promise<void>;
+    /** Exit presentation mode. */
+    exitPresentation(): Promise<void>;
+    /** Enable or disable editing at runtime (disabling clears the selection). */
+    setEditable(editable: boolean): void;
+    /** Undo the last edit (no-op when the undo stack is empty). */
+    undo(): void;
+    /** Redo the last undone edit (no-op when the redo stack is empty). */
+    redo(): void;
+    canUndo(): boolean;
+    canRedo(): boolean;
+    /** Serialise the (edited) presentation to `.pptx` bytes and clear dirty. */
+    save(): Promise<Uint8Array>;
+    /** `save()` + trigger a browser download (default `presentation.pptx`). */
+    downloadPptx(fileName?: string): Promise<void>;
+    /** Delete the selected element (no-op without a selection). */
+    deleteSelected(): void;
+    /** Id of the selected element, or `null`. */
+    getSelectedElementId(): string | null;
+    /** The element-renderer registry in effect (extension point). */
+    getRegistry(): ElementRendererRegistry;
+    /**
+     * Escape hatch: the live `pptx-viewer-core` handler for the loaded file
+     * (or `null`). Enables advanced operations (save, markdown conversion,
+     * archive access) without extra APIs here.
+     */
+    getHandler(): PptxHandler | null;
+    /** Tear down DOM, listeners, Blob URLs, and the core handler. */
+    destroy(): void;
+}
+
+/**
+ * The zero-framework PowerPoint viewer. Construct via {@link createPptxViewer}
+ * (or `new PptxViewer(container, options)`): builds its chrome inside
+ * `container`, loads `options.source` when given, and re-renders through a
+ * tiny reactive store. All parsing lives in `pptx-viewer-core`; all pure
+ * render logic in `pptx-viewer-shared`.
+ */
+declare class PptxViewer implements PptxViewerInstance {
+    private readonly container;
+    private readonly doc;
+    private readonly options;
+    private readonly store;
+    private readonly registry;
+    private readonly renderer;
+    private t;
+    private chrome;
+    private presentation;
+    private detachKeyboard;
+    private resizeObserver;
+    private handler;
+    private blobUrls;
+    private appliedThemeVars;
+    private loadToken;
+    private destroyed;
+    private editor;
+    constructor(container: HTMLElement, options?: PptxViewerOptions);
+    loadFile(file: Blob | ArrayBuffer | Uint8Array): Promise<void>;
+    loadUrl(url: string): Promise<void>;
+    private load;
+    /** Dispose the previous handler + Blob URLs (before replacing or on destroy). */
+    private releaseLoaded;
+    next(): void;
+    prev(): void;
+    goToSlide(index: number): void;
+    getSlideCount(): number;
+    getCurrentSlide(): number;
+    getZoom(): number;
+    setZoom(zoom: ZoomLevel): void;
+    zoomIn(): void;
+    zoomOut(): void;
+    zoomToFit(): void;
+    setTheme(theme: ViewerTheme | undefined): void;
+    setLocale(locale: string): void;
+    setEditable(editable: boolean): void;
+    undo(): void;
+    redo(): void;
+    canUndo(): boolean;
+    canRedo(): boolean;
+    save(): Promise<Uint8Array>;
+    downloadPptx(fileName?: string): Promise<void>;
+    deleteSelected(): void;
+    getSelectedElementId(): string | null;
+    enterPresentation(): Promise<void>;
+    exitPresentation(): Promise<void>;
+    getRegistry(): ElementRendererRegistry;
+    getHandler(): PptxHandler | null;
+    destroy(): void;
+    private mountChrome;
+    private unmountChrome;
+}
+/**
+ * Create a PowerPoint viewer inside `container`.
+ *
+ * ```ts
+ * import { createPptxViewer } from 'pptx-vanilla-viewer';
+ * const viewer = createPptxViewer(document.querySelector('#host')!, {
+ * 	source: '/deck.pptx',
+ * 	onSlideChange: (i) => console.log('slide', i + 1),
+ * });
+ * ```
+ */
+declare function createPptxViewer(container: HTMLElement, options?: PptxViewerOptions): PptxViewerInstance;
+
+/** The complete viewer stylesheet text (for hosts that self-manage CSS). */
+declare function getViewerCss(): string;
+
+export { type CssStyleMap, type ElementRenderContext, type ElementRenderer, type ElementRendererRegistry, type PptxElementType, PptxHandler, PptxViewer, type PptxViewerCallbacks, type PptxViewerInstance, type PptxViewerOptions, type PptxViewerSource, type SlideStageOptions, type TranslationMessages, type Translator, type ViewerState, type ZoomLevel, applyStyleMap, createDefaultRegistry, createEl, createElementRendererRegistry, createPptxViewer, createSvgEl, createTranslator, getViewerCss, renderSlideStage };