@namahapdf/pptx 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,897 @@
+/**
+ * Resolved presentation model produced by PptxParser and consumed by
+ * SlideRenderer / pdfBuilder. Geometry is normalized to **PDF points**
+ * (top-left origin) and colors are fully resolved to RGBA (theme lookups and
+ * lumMod/shade/tint/alpha transforms already applied).
+ */
+/** 0..255 channels, alpha 0..1. */
+type Rgba = {
+    r: number;
+    g: number;
+    b: number;
+    a: number;
+};
+type GradientStop = {
+    pos: number;
+    color: Rgba;
+};
+type Fill = {
+    kind: 'none';
+} | {
+    kind: 'solid';
+    color: Rgba;
+} | {
+    kind: 'gradient';
+    stops: GradientStop[];
+    angleDeg: number;
+    radial: boolean;
+} | {
+    kind: 'image';
+    dataUrl: string;
+    alpha: number;
+};
+type Stroke = {
+    fill: Fill;
+    widthPt: number;
+    dash: number[];
+    cap: 'butt' | 'round' | 'square';
+};
+/** Box in PDF points, top-left origin, plus rotation/flip about the box center. */
+type Transform = {
+    xPt: number;
+    yPt: number;
+    wPt: number;
+    hPt: number;
+    rotDeg: number;
+    flipH: boolean;
+    flipV: boolean;
+};
+type Geometry = {
+    /** DrawingML preset name (e.g. 'rect', 'roundRect', 'ellipse'); '' for custom. */
+    preset: string;
+    /** Custom geometry path segments in EMU within the shape box (Phase 2+). */
+    custom?: PathSeg[];
+    /** Adjust values (a:avLst) by name, e.g. 'adj' → fraction. */
+    adjust?: Record<string, number>;
+};
+type PathSeg = {
+    c: 'M';
+    x: number;
+    y: number;
+} | {
+    c: 'L';
+    x: number;
+    y: number;
+} | {
+    c: 'C';
+    x1: number;
+    y1: number;
+    x2: number;
+    y2: number;
+    x: number;
+    y: number;
+} | {
+    c: 'Z';
+};
+type Run = {
+    text: string;
+    fontSizePt: number;
+    bold: boolean;
+    italic: boolean;
+    underline: boolean;
+    color: Rgba;
+    /** Resolved typeface family name (theme +mj-lt/+mn-lt already resolved). */
+    typeface: string;
+    /** Hyperlink target (a:hlinkClick), resolved via slide rels. Semantic only. */
+    hyperlink?: string;
+};
+type BulletKind = 'none' | 'char' | 'number';
+type Paragraph = {
+    runs: Run[];
+    align: 'l' | 'ctr' | 'r' | 'just';
+    /** Indent level 0..8. */
+    level: number;
+    bullet: {
+        kind: BulletKind;
+        char?: string;
+        color?: Rgba;
+        numType?: string;
+        startAt?: number;
+    };
+    /** Left margin / first-line indent, points. */
+    marLPt: number;
+    indentPt: number;
+    /** Line spacing: multiple of line height when `linePct`, else exact points. */
+    linePct?: number;
+    lineExactPt?: number;
+    spaceBeforePt: number;
+    spaceAfterPt: number;
+    /** Fallback run props for empty paragraphs (end-paragraph run props). */
+    defaultSizePt: number;
+    defaultColor: Rgba;
+    defaultTypeface: string;
+};
+type TextBody = {
+    paragraphs: Paragraph[];
+    anchor: 't' | 'ctr' | 'b';
+    insL: number;
+    insT: number;
+    insR: number;
+    insB: number;
+    wrap: boolean;
+    /** normAutofit font scale (1 = none). */
+    fontScale: number;
+    /** normAutofit line-spacing reduction as a fraction (0 = none). */
+    lnSpcReduction: number;
+    /**
+     * Autofit mode: 'norm' shrinks text to fit the box (we compute the scale
+     * ourselves when PowerPoint didn't persist one), 'shape' means the shape was
+     * sized to the text (no shrink), 'none' clips overflow.
+     */
+    autofit: 'norm' | 'shape' | 'none';
+};
+type ShapeNode = ShapeEl | PictureEl | GroupEl | GraphicFrameEl;
+/** Semantic metadata carried alongside the render model (for structure export). */
+type ShapeMeta = {
+    /** cNvPr id — the stable shape locator inside its part (PptxAnchor.shapeId). */
+    id?: string;
+    /** cNvPr name, e.g. "Title 1". */
+    name?: string;
+    /** Placeholder type (title/ctrTitle/subTitle/body/...) when this is a placeholder. */
+    phType?: string;
+    /** Placeholder index. */
+    phIdx?: string;
+    /** Alt text (cNvPr descr/title). */
+    altText?: string;
+    /** Which part the shape came from — only 'slide' shapes are editable in place. */
+    source?: 'slide' | 'layout' | 'master';
+};
+/** Outer drop shadow (a:outerShdw). Offsets/blur in points. */
+type Shadow = {
+    color: Rgba;
+    blurPt: number;
+    offsetXPt: number;
+    offsetYPt: number;
+};
+/** Source-rect crop as edge fractions (0..1) of the image (a:srcRect). */
+type SrcRect = {
+    l: number;
+    t: number;
+    r: number;
+    b: number;
+};
+type ShapeEl = {
+    kind: 'shape';
+    transform: Transform;
+    geometry: Geometry;
+    fill: Fill;
+    stroke: Stroke | null;
+    textBody: TextBody | null;
+    shadow: Shadow | null;
+    meta: ShapeMeta;
+};
+type PictureEl = {
+    kind: 'picture';
+    transform: Transform;
+    dataUrl: string | null;
+    /** Stable id for the underlying media (rel target), for enrichment/dedupe. */
+    assetId?: string;
+    /** Optional outline. */
+    stroke: Stroke | null;
+    shadow: Shadow | null;
+    /** Crop applied to the source image, if any. */
+    srcRect: SrcRect | null;
+    meta: ShapeMeta;
+};
+type GroupEl = {
+    kind: 'group';
+    transform: Transform;
+    /** Child coordinate space (chOff/chExt) → lets us map child EMU into the group box. */
+    chOffXEmu: number;
+    chOffYEmu: number;
+    chExtWEmu: number;
+    chExtHEmu: number;
+    children: ShapeNode[];
+};
+type TableCell = {
+    rowSpan: number;
+    gridSpan: number;
+    /** True when covered by a merge (skip drawing). */
+    merged: boolean;
+    fill: Fill;
+    borders: {
+        l?: Stroke;
+        t?: Stroke;
+        r?: Stroke;
+        b?: Stroke;
+    };
+    textBody: TextBody | null;
+};
+type Table = {
+    colWidthsPt: number[];
+    rowHeightsPt: number[];
+    rows: TableCell[][];
+    /** tblPr firstRow flag — first row is a styled header. */
+    firstRow: boolean;
+    /** tblPr bandRow flag — alternating row banding. */
+    bandRow: boolean;
+};
+type GraphicFrameEl = {
+    kind: 'graphicFrame';
+    transform: Transform;
+    table: Table | null;
+    /** Extracted chart data (categories/series) when this frame holds a chart. */
+    chart: ChartData | null;
+    /** Cached fallback raster (charts/SmartArt), if any. */
+    fallbackImage: string | null;
+    meta: ShapeMeta;
+};
+/** Chart data extracted from ppt/charts/chartN.xml (structure, not visuals). */
+type ChartSeries = {
+    name?: string;
+    values: number[];
+};
+type ChartData = {
+    kind: string;
+    title?: string;
+    categories: string[];
+    series: ChartSeries[];
+};
+type Slide = {
+    /** 0-based slide index. */
+    index: number;
+    /** OPC part path (e.g. "ppt/slides/slide1.xml") — the PptxAnchor.slidePart. */
+    part?: string;
+    /** cSld name attribute, if any. */
+    name?: string;
+    /** Layout name (cSld/@name of the slide layout). */
+    layoutName?: string;
+    /** Derived from the title placeholder text, if present. */
+    title?: string;
+    /** Speaker notes plain text, if present. */
+    notes?: string;
+    background: Fill;
+    shapes: ShapeNode[];
+};
+/** Document-level metadata from docProps/core.xml + app.xml. */
+type DocMeta = {
+    title?: string;
+    author?: string;
+    lastModifiedBy?: string;
+    created?: string;
+    modified?: string;
+    company?: string;
+    app?: string;
+    slideCount: number;
+    slideWidthPt: number;
+    slideHeightPt: number;
+};
+type ParsedPresentation = {
+    widthEmu: number;
+    heightEmu: number;
+    widthPt: number;
+    heightPt: number;
+    slides: Slide[];
+    meta: DocMeta;
+};
+declare const BLACK: Rgba;
+declare const WHITE: Rgba;
+declare const rgbaCss: (c: Rgba) => string;
+declare const rgbaToHex: (c: Rgba) => string;
+
+/** Parse options. `skipImageData` avoids embedding image bytes (structure-only runs). */
+type ParseOptions = {
+    skipImageData?: boolean;
+};
+declare class PptxParser {
+    private pkg;
+    private opts;
+    private constructor();
+    static parse(data: ArrayBuffer | Uint8Array, opts?: ParseOptions): Promise<ParsedPresentation>;
+    private run;
+    /** Document metadata from docProps/core.xml + app.xml. */
+    private parseMeta;
+    /** Resolve the layout/master/theme parts for a slide. */
+    private resolveChain;
+    private loadSlide;
+    /** Title = text of the first title/ctrTitle placeholder shape, if any. */
+    private deriveTitle;
+    /** Speaker notes plain text from the linked notesSlide part, if present. */
+    private loadNotes;
+    private getSpTree;
+    private indexPlaceholders;
+    /** Parse a slide/layout/master's spTree. When `bgOnly`, skip placeholders. */
+    private parseTree;
+    /** Read semantic metadata (name/alt-text/placeholder) from an sp/pic/graphicFrame. */
+    private buildMeta;
+    private parseShape;
+    /** Parse an outer drop shadow from spPr/effectLst/outerShdw. */
+    private parseShadow;
+    private parsePicture;
+    private parseGroup;
+    private parseGraphicFrame;
+    private parseTable;
+    private parseTransform;
+    private parseGeometry;
+    private firstFillEl;
+    private parseFill;
+    /** Synchronous fill parse (everything except blip images). */
+    private parseFillSync;
+    private parseLine;
+    private parseBackground;
+    private parseTextBody;
+    private parseParagraph;
+    private parseRun;
+    private parseTxStyles;
+    private parseOneTxStyle;
+}
+/** Flatten a parsed text body to plain text (paragraphs joined by newlines). */
+declare const textBodyToString: (tb: TextBody) => string;
+
+/**
+ * Text layout for a DrawingML text body.
+ *
+ * Produces positioned text segments (top-left origin, PDF points) by wrapping
+ * runs within the shape's content box. Because the same segments feed both the
+ * (fallback) raster pass and the real-text PDF overlay, the on-screen and
+ * selectable text stay perfectly consistent — there is a single source of truth
+ * for where each line sits.
+ *
+ * Phase-1 scope: left/center/right alignment, top/center/bottom vertical anchor,
+ * body insets, multi-run lines, bullets (char), line spacing, space before/after.
+ * Justify is approximated as left; numbered bullets render as a bullet dot.
+ */
+
+type TextSegment = {
+    text: string;
+    xPt: number;
+    /** Baseline Y from the top of the slide, in points. */
+    baselineYPt: number;
+    widthPt: number;
+    fontSizePt: number;
+    bold: boolean;
+    italic: boolean;
+    underline: boolean;
+    color: Rgba;
+    typeface: string;
+};
+
+/**
+ * SlideRenderer: a resolved `Slide` → a high-DPI background raster (graphics
+ * only, **no glyphs**) plus the positioned text segments for the PDF overlay.
+ *
+ * Everything is drawn in PDF points (the context is pre-scaled by `scale`), so
+ * geometry from the parser is used directly. Text is never painted into the
+ * raster on the normal path — pdfBuilder draws it as crisp, selectable vectors.
+ * The one exception is rotated text shapes, whose glyphs are baked into the
+ * raster (so they rotate correctly) while the overlay text is emitted invisible
+ * for selection — mirroring the `textBaked` fallback in pptxExport.
+ */
+
+type RenderedSegment = TextSegment & {
+    invisible: boolean;
+    rotateDeg: number;
+};
+type RenderedSlide = {
+    widthPt: number;
+    heightPt: number;
+    backgroundPng: string;
+    segments: RenderedSegment[];
+};
+declare function renderSlide(slide: Slide, widthPt: number, heightPt: number, scale: number): Promise<RenderedSlide>;
+
+/**
+ * Structured / semantic projection of a parsed presentation.
+ *
+ * This is the *business asset*: a clean, render-free representation designed for
+ * AI / RAG consumption. `toStructure` maps the render model
+ * (`ParsedPresentation`) to a semantic tree (roles, text, bbox, hyperlinks,
+ * notes, tables, chart data); `toMarkdown` projects that to LLM-friendly text;
+ * `toChunks` produces embedding-ready segments with metadata.
+ *
+ * The schema is deliberately format-neutral so PDF/DOCX can normalize into the
+ * same shape later (the unified DocumentModel).
+ */
+
+type BBox$1 = {
+    xPt: number;
+    yPt: number;
+    wPt: number;
+    hPt: number;
+};
+type StructuredRun = {
+    text: string;
+    bold?: boolean;
+    italic?: boolean;
+    underline?: boolean;
+    colorHex?: string;
+    hyperlink?: string;
+};
+type StructuredParagraph = {
+    level: number;
+    bullet: 'none' | 'bullet' | 'number';
+    runs: StructuredRun[];
+    text: string;
+};
+type TextRole = 'title' | 'subtitle' | 'body' | 'other';
+type StructuredElement = {
+    type: 'text';
+    role: TextRole;
+    name?: string;
+    bbox: BBox$1;
+    paragraphs: StructuredParagraph[];
+    text: string;
+} | {
+    type: 'image';
+    name?: string;
+    altText?: string;
+    bbox: BBox$1;
+    assetId?: string;
+} | {
+    type: 'table';
+    name?: string;
+    bbox: BBox$1;
+    headerRow: boolean;
+    rows: string[][];
+} | {
+    type: 'chart';
+    name?: string;
+    bbox: BBox$1;
+    chart: ChartData;
+    summary: string;
+} | {
+    type: 'shape';
+    name?: string;
+    bbox: BBox$1;
+    text?: string;
+} | {
+    type: 'group';
+    bbox: BBox$1;
+    children: StructuredElement[];
+};
+type StructuredSlide = {
+    index: number;
+    name?: string;
+    layout?: string;
+    title?: string;
+    notes?: string;
+    elements: StructuredElement[];
+};
+type PresentationStructure = {
+    meta: DocMeta;
+    slides: StructuredSlide[];
+};
+type Chunk = {
+    id: string;
+    text: string;
+    meta: {
+        slide: number;
+        role?: string;
+        bbox?: BBox$1;
+    };
+};
+declare const toStructure: (pres: ParsedPresentation) => PresentationStructure;
+declare const toMarkdown: (structure: PresentationStructure) => string;
+declare const toChunks: (structure: PresentationStructure) => Chunk[];
+
+/**
+ * Canonical, format-neutral document model.
+ *
+ * Both PPTX (via the existing structure projector) and PDF normalize into this
+ * shape so one set of projectors (Markdown / chunks) and the knowledge base feed
+ * off a single representation. Designed to also accept DOCX later.
+ *
+ * Geometry is optional `BBox` in PDF points, top-left origin. Image/chart
+ * elements carry KB-enrichment fields (`ocrText`, `caption`, `summary`) that the
+ * vision pipeline fills in (Track 5).
+ */
+
+type BBox = {
+    xPt: number;
+    yPt: number;
+    wPt: number;
+    hPt: number;
+};
+
+/**
+ * Edit anchors — serializable locators that tie a structural element back to a
+ * concrete editable location in the native file.
+ *
+ * Anchors deliberately carry no live object references and no byte offsets:
+ * they cross the API boundary as plain JSON, and the writer/dispatcher
+ * re-derives the concrete operators (PDF content-stream indices, OOXML nodes)
+ * fresh at apply time by re-rendering / re-parsing. This mirrors how PDF edits
+ * already work (operator indices captured at render time) and how the PPTX
+ * writer will re-open the raw XML rather than trust the lossy parsed tree.
+ */
+
+/** Locator into a .pptx part. Built in Track C; consumed by the writer in Track D. */
+type PptxAnchor = {
+    fmt: 'pptx';
+    /** e.g. "ppt/slides/slide3.xml" */
+    slidePart: string;
+    /** cNvPr/@id — stable within a slide part. */
+    shapeId?: string;
+    /** Fallback locator: 0-based shape index in p:spTree. */
+    spTreeIndex?: number;
+    /** Text edits: paragraph index within the shape's txBody. */
+    paraIndex?: number;
+    /** ...then run index within that paragraph. */
+    runIndex?: number;
+    /** Table cell. */
+    cell?: {
+        row: number;
+        col: number;
+    };
+    /** Image: the blip r:embed relationship id. */
+    relId?: string;
+    /** Image: resolved media part path (e.g. "ppt/media/image2.png"). */
+    mediaPart?: string;
+};
+/**
+ * Locator into a PDF. The dispatcher re-renders the page at apply time and
+ * relocates the run by text (operator indices are never carried across the
+ * boundary, so they can't go stale).
+ */
+type PdfAnchor = {
+    fmt: 'pdf';
+    pageIndex: number;
+    /** Element/run text used to relocate the target run at apply time. */
+    text?: string;
+    /** Geometry in PDF points, top-left origin (informational / planner hints). */
+    bbox?: BBox;
+};
+/**
+ * Locator into a .xlsx workbook. Rows/cols are 0-based; the writer resolves the
+ * A1-style cell reference (`<c r="B3">`) inside the worksheet part at apply time.
+ */
+type XlsxAnchor = {
+    fmt: 'xlsx';
+    /** e.g. "xl/worksheets/sheet1.xml" */
+    sheetPart: string;
+    /** Display name of the sheet (informational / planner hint). */
+    sheetName?: string;
+    /** 0-based row index. */
+    row: number;
+    /** 0-based column index. */
+    col: number;
+    /** Optional 0-based inclusive range for region-level intents. */
+    range?: {
+        r1: number;
+        c1: number;
+        r2: number;
+        c2: number;
+    };
+};
+type EditAnchor = PptxAnchor | PdfAnchor | XlsxAnchor;
+
+/**
+ * Format-neutral edit intents — the stable middle of the editing pipeline.
+ *
+ * Everything above the dispatcher (planner, API, bulk runner, UI) speaks only
+ * `EditIntent` / `EditPlan`. `dispatch.ts` is the only place that knows how to
+ * route an intent to a concrete engine (PDFEditSession for PDF, PptxWriter for
+ * PPTX). Intents are JSON-serializable so they cross the API boundary; the
+ * `find-replace` intent is anchor-free (located per file at apply time).
+ */
+
+type EditIntent = {
+    op: 'replace-text';
+    anchor: EditAnchor;
+    newText: string;
+} | {
+    op: 'replace-image';
+    anchor: EditAnchor;
+    bytes: Uint8Array;
+    format: 'png' | 'jpeg';
+    mode?: 'swap-part' | 'repoint';
+} | {
+    op: 'set-cell';
+    anchor: EditAnchor;
+    row: number;
+    col: number;
+    newText: string;
+} | {
+    op: 'find-replace';
+    find: string;
+    replace: string;
+    scope?: 'all' | number[];
+} | {
+    op: 'move-shape';
+    anchor: EditAnchor;
+    xPt?: number;
+    yPt?: number;
+} | {
+    op: 'resize-shape';
+    anchor: EditAnchor;
+    wPt?: number;
+    hPt?: number;
+} | {
+    op: 'add-slide';
+    afterIndex?: number;
+} | {
+    op: 'delete-slide';
+    index: number;
+} | {
+    op: 'reorder-slide';
+    from: number;
+    to: number;
+} | {
+    op: 'add-text-box';
+    anchor: EditAnchor;
+    xPt: number;
+    yPt: number;
+    wPt: number;
+    hPt: number;
+    text: string;
+    sizePt?: number;
+} | {
+    op: 'clear-cell';
+    anchor: EditAnchor;
+    row: number;
+    col: number;
+} | {
+    op: 'format-cell';
+    anchor: EditAnchor;
+    row: number;
+    col: number;
+    format: CellFormatPatch;
+} | {
+    op: 'set-column-width';
+    anchor: EditAnchor;
+    col: number;
+    widthChars: number;
+};
+/**
+ * Partial formatting for `format-cell` — unset fields inherit the cell's
+ * current style. The writer never mutates a shared style entry; it appends.
+ */
+type CellFormatPatch = {
+    bold?: boolean;
+    italic?: boolean;
+    /** Number-format code, e.g. '0.00', '#,##0', 'm/d/yyyy'. */
+    numFmt?: string;
+    /** Solid fill as CSS hex '#RRGGBB'. */
+    fill?: string;
+};
+type EditPlan = {
+    source: {
+        fileName: string;
+        format: 'pptx' | 'pdf' | 'xlsx';
+    };
+    intents: EditIntent[];
+};
+/** Per-intent outcome reported back from the dispatcher. */
+type IntentResult = {
+    op: EditIntent['op'];
+    ok: boolean;
+    applied: number;
+    error?: string;
+    /** Op-specific payload, e.g. the new slide part path from `add-slide` (for anchoring follow-up intents). */
+    detail?: string;
+};
+type EditResult = {
+    bytes: Uint8Array;
+    results: IntentResult[];
+};
+
+type NewRelationship = {
+    /** Explicit id (e.g. "rId7"); omitted = next free rIdN is assigned. */
+    id?: string;
+    type: string;
+    /** Target as it should appear in the rels file (usually part-relative, e.g. "../media/image2.png"). */
+    target: string;
+    external?: boolean;
+};
+declare class PkgWriter {
+    private zip;
+    private constructor();
+    static load(data: ArrayBuffer | Uint8Array): Promise<PkgWriter>;
+    has(path: string): boolean;
+    /** All part paths in the package (no directory entries). */
+    paths(): string[];
+    readText(path: string): Promise<string | null>;
+    readBinary(path: string): Promise<Uint8Array | null>;
+    setText(path: string, xml: string): void;
+    setBinary(path: string, bytes: Uint8Array): void;
+    /** Add (or overwrite) a part. Content types are managed separately. */
+    addPart(path: string, content: string | Uint8Array): void;
+    /** Remove a part and its own rels file, if any. */
+    removePart(path: string): void;
+    /**
+     * Add a relationship to `partPath`'s rels file (created when absent).
+     * Returns the relationship id.
+     */
+    addRel(partPath: string, rel: NewRelationship): Promise<string>;
+    /** Remove a relationship by id from `partPath`'s rels file. Returns true when found. */
+    removeRel(partPath: string, relId: string): Promise<boolean>;
+    /** Ensure a `<Default Extension=.../>` mapping exists (no-op when present). */
+    ensureDefaultContentType(extension: string, contentType: string): Promise<void>;
+    /** Add or replace an `<Override PartName=.../>` for a part (leading slash added). */
+    setContentTypeOverride(partPath: string, contentType: string): Promise<void>;
+    /** Remove a part's `<Override>`. Returns true when found. */
+    removeContentTypeOverride(partPath: string): Promise<boolean>;
+    private contentTypesXml;
+    save(): Promise<Uint8Array>;
+}
+
+/**
+ * Slide-level PPTX operations — the only edits that touch multiple parts:
+ * add/delete/reorder slides (slide part + rels + `[Content_Types].xml` +
+ * `p:sldIdLst` in `ppt/presentation.xml`) and inserting new text boxes.
+ *
+ * Existing parts are mutated by positional splices only; brand-new parts
+ * (slides we create) are fully ours, so they're written whole. Namespace
+ * prefixes for splices into *existing* XML are read from the document's own
+ * declarations — never assumed.
+ */
+
+/** Slide parts in presentation order (via `p:sldIdLst` + the presentation rels). */
+declare function slidePartsInOrder(writer: PkgWriter): Promise<string[]>;
+
+/**
+ * Apply an edit plan to a `.pptx`. Returns the edited bytes (the unchanged
+ * input when nothing applied) plus a per-intent result log.
+ */
+declare function applyPptxPlan(bytes: Uint8Array, plan: EditPlan): Promise<EditResult>;
+
+/**
+ * PptxEditSession — the framework-free editing session behind the slide editor
+ * UI (and any other host: React today, mobile shells later).
+ *
+ * Intent-sourced: the UI never mutates a live model. It calls `apply(intents)`;
+ * the writer splices the current bytes (`applyPptxPlan`), the session snapshots
+ * the result, re-parses, and notifies subscribers, which re-render from the
+ * *saved* truth — WYSIWYG can't drift from what's actually in the file. Undo /
+ * redo replay byte snapshots (bounded), so they're trivially correct.
+ */
+
+type SessionListener = () => void;
+declare class PptxEditSession {
+    readonly fileName: string;
+    /** Byte snapshots; `cursor` points at the current state, entries after it are redo states. */
+    private snapshots;
+    private cursor;
+    private parsed;
+    private listeners;
+    /** Every intent ever applied, in order (serializable audit / AI parity log). */
+    readonly intentLog: EditIntent[];
+    private constructor();
+    static load(fileName: string, bytes: Uint8Array): Promise<PptxEditSession>;
+    /** Current file bytes (the saved truth). */
+    get bytes(): Uint8Array;
+    /** Current parsed render model. */
+    get presentation(): ParsedPresentation;
+    get canUndo(): boolean;
+    get canRedo(): boolean;
+    subscribe(listener: SessionListener): () => void;
+    private notify;
+    /**
+     * Apply intents to the current bytes. When anything lands, a new snapshot
+     * becomes current, redo is cleared, and the model is re-parsed. Failed
+     * intents are reported per-intent, never thrown.
+     */
+    apply(intents: EditIntent[]): Promise<IntentResult[]>;
+    undo(): Promise<boolean>;
+    redo(): Promise<boolean>;
+    /** Current bytes as a downloadable Blob. */
+    toBlob(): Blob;
+}
+
+/**
+ * Zod schemas for the edit contract — the validation boundary between an
+ * (untrusted) LLM-emitted `EditPlan` and the dispatcher (PLATFORM_PLAN.md
+ * Phase 5). Two consumers:
+ *
+ * 1. **Runtime validation** — `validateEditPlan(json)` at `/api/edit/apply`
+ *    (and any agent host) rejects malformed plans with readable errors before
+ *    a single intent runs.
+ * 2. **Tool definitions** — `editPlanJsonSchema()` emits a JSON Schema an agent
+ *    framework can hand an LLM verbatim as the arguments schema for an
+ *    "apply document edits" tool. The model then emits plans that validate.
+ *
+ * The schemas mirror the `EditIntent` / `EditAnchor` unions in this directory
+ * exactly; keep them in lockstep when the unions change (the round-trip test
+ * asserts every op is covered). `replace-image` carries binary bytes, so it is
+ * `z.any()` here — image replacement uses a binary channel, not pure JSON.
+ */
+
+type ValidatedPlan = {
+    ok: true;
+    plan: EditPlan;
+} | {
+    ok: false;
+    errors: string[];
+};
+/**
+ * Validate an untrusted value as an `EditPlan`. On success returns the typed
+ * plan; on failure a flat list of `path: message` strings (safe to surface to
+ * the caller / feed back to the model).
+ */
+declare function validateEditPlan(input: unknown): ValidatedPlan;
+/**
+ * JSON Schema for the whole `EditPlan` — hand this to an agent framework as the
+ * arguments schema of an "apply document edits" tool. Binary/unrepresentable
+ * fields (`replace-image.bytes`) render as permissive `{}`.
+ */
+declare function editPlanJsonSchema(): Record<string, unknown>;
+
+type ProgressFn = (done: number, total: number) => void;
+declare function pptxToPdf(blob: Blob, onProgress?: ProgressFn): Promise<Blob>;
+
+/** Shared license/activation contracts used by both the engine gate and the server. */
+/** Capabilities a license can unlock. `view`/`annotate` are the always-available base. */
+type LicenseFeature = 'view' | 'annotate' | 'edit-text' | 'sign' | 'redact' | 'forms' | 'export-clean' | 'pptx-edit' | 'sheets-view' | 'sheets-edit';
+type LicenseEdition = 'trial' | 'pro' | 'enterprise';
+type LicenseStatus = 'UNLICENSED' | 'INVALID' | 'LICENSED' | 'GRACE' | 'DEGRADED';
+interface LicenseState {
+    status: LicenseStatus;
+    edition: LicenseEdition | null;
+    features: LicenseFeature[];
+    /** True when render/export should be watermarked. */
+    watermark: boolean;
+    /** Human-readable reason (for diagnostics; never user-facing copy). */
+    reason: string;
+}
+
+/**
+ * Client-side license gate for the NamahaPDF engine.
+ *
+ * Flow (see configureLicense):
+ *   1. Verify the license key OFFLINE (signature, expiry, domain) — instant, no network.
+ *   2. If a cached activation token is still valid → LICENSED immediately.
+ *   3. Kick a NON-BLOCKING background activation that exchanges the key for a fresh,
+ *      short-TTL activation token (which is also what the server can revoke).
+ *
+ * Offline grace is weighted heavily on purpose: transient network/server failures
+ * never punish a paying customer. We tolerate up to MAX_FAILURES (5) attempts AND a
+ * BOOTSTRAP_GRACE window before degrading — the SDK degrades immediately ONLY on an
+ * explicit signed `revoked`/`invalid` from the server.
+ *
+ * Everything is injectable (storage / fetch / clock / public key) so it is unit-testable
+ * without a browser or a server.
+ */
+
+interface StorageLike {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+}
+interface LicenseConfig {
+    /** The signed license key the developer received. */
+    licenseKey?: string;
+    /** Activation endpoint. Defaults to a same-origin `/api/license/activate`. */
+    activationUrl?: string;
+    /** Stable per-install id; auto-generated + persisted when omitted. */
+    deviceId?: string;
+    /** First-party bypass — our own app passes this so it never watermarks itself. */
+    owner?: boolean;
+    /** Override the embedded public key (tests only). */
+    publicKeyHex?: string;
+    /** Injected clock (tests). */
+    now?: () => number;
+    /** Injected storage (tests / Node). */
+    storage?: StorageLike;
+    /** Injected fetch (tests / Node). */
+    fetchImpl?: typeof fetch;
+    /** Host to domain-check against; defaults to location.hostname in the browser. */
+    host?: string;
+    /** Background retry backoff in ms (tests can shorten). */
+    retryDelays?: number[];
+}
+type Listener = (s: LicenseState) => void;
+/**
+ * Configure (or reconfigure) the license gate. Verifies the key synchronously and
+ * starts a background activation. Returns the immediate state; subscribe with
+ * `onLicenseChange` for updates as activation completes.
+ */
+declare function configureLicense(config?: LicenseConfig): LicenseState;
+/** Current license state (synchronous, cheap). */
+declare function getLicenseState(): LicenseState;
+declare function isFeatureEnabled(feature: LicenseFeature): boolean;
+/** Throws if a feature is not licensed — use to guard gated engine operations. */
+declare function assertFeature(feature: LicenseFeature): void;
+declare function shouldWatermark(): boolean;
+/** Subscribe to state changes (activation success/failure). Returns an unsubscribe. */
+declare function onLicenseChange(cb: Listener): () => void;
+
+export { BLACK, type BulletKind, type CellFormatPatch, type ChartData, type ChartSeries, type Chunk, type DocMeta, type EditAnchor, type EditIntent, type EditPlan, type EditResult, type Fill, type Geometry, type GradientStop, type GraphicFrameEl, type GroupEl, type IntentResult, type LicenseConfig, type LicenseEdition, type LicenseFeature, type LicenseState, type LicenseStatus, type Paragraph, type ParsedPresentation, type PathSeg, type PictureEl, type PptxAnchor, PptxEditSession, PptxParser, type PresentationStructure, type ProgressFn, type RenderedSegment, type RenderedSlide, type Rgba, type Run, type SessionListener, type Shadow, type ShapeEl, type ShapeMeta, type ShapeNode, type Slide, type SrcRect, type Stroke, type StructuredElement, type StructuredParagraph, type StructuredRun, type StructuredSlide, type Table, type TableCell, type TextBody, type TextRole, type Transform, WHITE, applyPptxPlan, assertFeature, configureLicense, editPlanJsonSchema, getLicenseState, isFeatureEnabled, onLicenseChange, pptxToPdf, renderSlide, rgbaCss, rgbaToHex, shouldWatermark, slidePartsInOrder, textBodyToString, toChunks, toMarkdown, toStructure, validateEditPlan };