/**
 * WordprocessingML high-level API — a LENS over the document.xml DOM.
 *
 * `Document`, `Paragraph`, and `Run` hold references into the live
 * XmlElement tree owned by the underlying {@link OfficeDocument}; they
 * never copy content into separate structures. Mutating methods edit the
 * DOM in place and mark the main part dirty, so everything not touched
 * (themes, settings, numbering, embedded parts, unknown markup) round-
 * trips byte-identically (L3).
 *
 * Reading is MCE-aware: text extraction and paragraph/run enumeration see
 * the view a current-Office Word reader would see — `mc:AlternateContent`
 * collapsed to its winning branch, ignorable markup skipped — without
 * ever touching the tree (the mce module is strictly non-destructive).
 *
 * `Document.create()` produces a minimal file that Word opens with no
 * repair prompt — see CONTRACTS.md §7 for the exact part list.
 *
 * Phase 4 (DESIGN-P4.md): shared helpers live in `internal.ts`; this file
 * additionally implements the {@link DocumentInternal} capability contract
 * that the resolver/tables/images/sections feature modules code against.
 */
import { OfficeDocument } from '../document/index.js';
import { XmlElement, type XmlDocument } from '../xml/index.js';
import { type DocumentInternal } from './internal.js';
import { type EffectiveRunFormat, type EffectiveParagraphFormat, type ListInfo } from './resolver.js';
import { Table, type TableCreateOptions } from './tables.js';
import { type AddImageOptions, type ImageInfo } from './images.js';
import { type HeaderFooterInfo, type SetHeaderFooterOptions, type ListItem, type NumberedListOptions } from './sections.js';
export { WML_NAMESPACE } from './internal.js';
export type { PartDom, DocumentInternal, HeaderFooterKind, HeaderFooterPartRef } from './internal.js';
export { Table, TableRow, TableCell } from './tables.js';
export type { TableCreateOptions } from './tables.js';
export { pxToEmu, emuToPx, EMU_PER_PIXEL } from './images.js';
export type { AddImageOptions, ImageInfo, ImageFormat } from './images.js';
export type { EffectiveRunFormat, EffectiveParagraphFormat, ListInfo, ParagraphAlignment, LineSpacing, ListNumberFormat, } from './resolver.js';
export type { HeaderFooterType, HeaderFooterInfo, SetHeaderFooterOptions, ListItem, NumberedListOptions, } from './sections.js';
/** Options for {@link Document.addParagraph}. */
export interface ParagraphOptions {
    /** Paragraph style id (w:pStyle w:val), e.g. 'Heading1'. Not validated. */
    style?: string;
    /** Apply bold run formatting (w:b) to the inserted run. */
    bold?: boolean;
    /** Apply italic run formatting (w:i) to the inserted run. */
    italic?: boolean;
}
/**
 * Lens over one `w:r` element. Valid as long as the element remains in
 * the document; removing the element orphans the lens.
 */
export declare class Run {
    #private;
    /** @internal Constructed by {@link Paragraph.runs} only. */
    constructor(guard: symbol, doc: Document, el: XmlElement);
    /**
     * The underlying `w:r` element. Direct DOM edits are allowed but the
     * caller must then mark the main part dirty via
     * `document.office.markDirty()`; the lens methods do this automatically.
     */
    get element(): XmlElement;
    /** Plain text of the run (w:t + w:tab → '\t' + w:br/w:cr → '\n'). */
    text(): string;
    /**
     * True when the run carries direct bold formatting (w:rPr/w:b, honoring
     * w:val toggles). For style-cascade-resolved formatting use the Phase-4
     * `format()` method (resolver.ts); this reads direct formatting only.
     */
    bold(): boolean;
    /** True when the run carries direct italic formatting (w:rPr/w:i). */
    italic(): boolean;
    /**
     * The run's fully resolved (effective) formatting — what Word actually
     * renders, after docDefaults, the paragraph- and character-style chains
     * (w:basedOn recursion), the numbering level's w:rPr, and direct w:rPr.
     * Toggle properties (bold/italic/caps/smallCaps/strike/doubleStrike/
     * hidden) follow ECMA-376 §17.7.3 XOR semantics; colors read as
     * 'RRGGBB' ('auto' → null), w:u 'none' → null. Theme-indirected fonts
     * (w:asciiTheme) resolve to literal names because `Document.open` loads
     * the theme part. A pure read: mutates nothing, marks nothing dirty —
     * safe to call in tight per-run loops. Contrast {@link Run.bold} /
     * {@link Run.italic}, which read DIRECT formatting only.
     *
     * @example
     * const doc = await Document.open(await readFile('report.docx'));
     * const rf = doc.paragraphs()[0].runs()[0].format();
     * rf.bold;   // true — even when bold comes from the style, not the run
     * rf.sizePt; // 11
     */
    format(): EffectiveRunFormat;
    /**
     * Replace the run's content with a single `w:t` containing `text`,
     * PRESERVING the run properties (`w:rPr`) exactly as they are. All
     * other run content (previous w:t/w:tab/w:br/…) is removed. Sets
     * `xml:space="preserve"` on the new w:t when `text` has leading or
     * trailing whitespace. Marks the main part dirty.
     */
    setText(text: string): void;
}
/**
 * Lens over one `w:p` element. Valid as long as the element remains in
 * the document; removing the element orphans the lens.
 */
export declare class Paragraph {
    #private;
    /** @internal Constructed by {@link Document} lens methods only. */
    constructor(guard: symbol, doc: Document, el: XmlElement);
    /**
     * The underlying `w:p` element. Direct DOM edits are allowed but the
     * caller must then call `document.office.markDirty()` for the main
     * part; the lens methods do this automatically.
     */
    get element(): XmlElement;
    /**
     * Plain text of the paragraph: concatenated `w:t` content of all runs
     * in order (including runs inside hyperlinks and other inline
     * containers), with `w:tab` as '\t' and `w:br`/`w:cr` as '\n'. Text
     * inside mc:AlternateContent is taken from the branch a current-Office
     * reader would select (via the mce module), never from both branches.
     */
    text(): string;
    /** The paragraph style id (w:pPr/w:pStyle/@w:val), when present. */
    styleId(): string | undefined;
    /**
     * The paragraph's runs in document order (including runs inside inline
     * containers such as hyperlinks), MCE-resolved. A fresh array of lenses
     * per call.
     */
    runs(): readonly Run[];
    /**
     * The paragraph's fully resolved (effective) formatting — what Word
     * renders after docDefaults, the paragraph-style chain (w:basedOn
     * recursion), the numbering level's w:pPr, and direct w:pPr. Returns
     * resolved facts: normalized alignment (w:jc start→'left', end→'right',
     * both→'justify'; null when unset), left/right/first-line indents in
     * twips (a hanging indent reads as a negative first-line value),
     * before/after spacing in twips, `lineSpacing` {value, rule}, and the
     * resolved styleId + display styleName. A pure read — mutates nothing.
     *
     * @example
     * const doc = await Document.open(await readFile('report.docx'));
     * const pf = doc.paragraphs()[0].format();
     * pf.styleName; // 'heading 1'
     * pf.alignment; // 'center' | null
     */
    format(): EffectiveParagraphFormat;
    /**
     * The paragraph's resolved list membership, or null when it is not in a
     * list. Follows direct w:pPr/w:numPr and numbering inherited through the
     * paragraph-style chain, honoring w:num → w:abstractNum indirection
     * (incl. single-level w:numStyleLink) and w:lvlOverride/w:startOverride;
     * numId 0 and dangling references resolve to null (never a throw). The
     * result carries numId, 0-based level, the level's numFmt (`format`),
     * verbatim lvlText (`text`, e.g. '%1.'), start, and `isBullet`.
     *
     * @example
     * const doc = await Document.open(await readFile('report.docx'));
     * const li = doc.paragraphs()[0].list();
     * li?.isBullet; // false
     * li?.format;   // 'decimal'
     */
    list(): ListInfo | null;
    /** @internal Wrap an element in a Paragraph lens (Integrate agent use). */
    static _wrap(doc: Document, el: XmlElement): Paragraph;
}
/**
 * A Word document (docx/docm/dotx/dotm).
 */
export declare class Document {
    #private;
    /** @internal Construct via {@link Document.open} / {@link Document.create}. */
    constructor(guard: symbol, office: OfficeDocument, dom: XmlDocument);
    /**
     * Open an existing Word-family file (docx/docm/dotx/dotm — the check is
     * on the detected family, never the file extension). Eagerly loads the
     * main part's DOM plus the styles/numbering/settings parts and every
     * header/footer part referenced from the main part (when present), so
     * formatting resolution and header/footer reads are synchronous.
     * Dangling relationships are tolerated (the part reads as absent).
     * Throws `Error` when the bytes are not a Word-family package.
     */
    static open(bytes: Uint8Array): Promise<Document>;
    /**
     * Create a new, empty docx that real Word opens without repair (L2):
     * [Content_Types].xml, /_rels/.rels, /word/document.xml (empty body with
     * w:sectPr), /word/styles.xml (docDefaults + Normal),
     * /word/_rels/document.xml.rels, and docProps/core.xml + docProps/app.xml.
     * See CONTRACTS.md §7.4.
     */
    static create(): Document;
    /** The underlying office document (escape hatch to package and parts). */
    get office(): OfficeDocument;
    /** @internal Flag the main part's DOM dirty (lens mutations call this). */
    _markMainDirty(): void;
    /**
     * @internal The Phase-4 internals contract (DESIGN-P4.md): the stable
     * capability object feature modules (resolver/tables/images/sections)
     * code against. Same instance per Document.
     */
    _internal(): DocumentInternal;
    /**
     * The `w:body` element of the main part — the root for direct DOM work.
     * Callers mutating it directly must mark the main part dirty
     * (`office.markDirty(office.mainPart.name)`).
     */
    body(): XmlElement;
    /**
     * All paragraphs in the body in document order, including paragraphs
     * inside tables (depth-first) and inside block-level containers,
     * MCE-resolved. Paragraphs nested in run content (e.g. text boxes) are
     * not included. A fresh array of lenses per call.
     */
    paragraphs(): readonly Paragraph[];
    /**
     * Plain text of the whole document: every paragraph's text (in
     * {@link Document.paragraphs} order, table cell paragraphs included),
     * joined with '\n'.
     */
    text(): string;
    /**
     * Append a paragraph containing a single run with `text`, inserted in
     * CT_Body schema order (i.e. before the body-final `w:sectPr` when
     * present, else appended — the generated ordering tables replace the
     * old hand-coded insert-before-sectPr rule). Applies
     * {@link ParagraphOptions} as w:pPr/w:rPr children (schema order:
     * pStyle first inside pPr; b before i inside rPr). Sets
     * `xml:space="preserve"` on the w:t when `text` has leading or
     * trailing whitespace. Marks the main part dirty. Returns the lens
     * for the new paragraph.
     */
    addParagraph(text: string, options?: ParagraphOptions): Paragraph;
    /**
     * Every `w:tbl` in the body in document order, DEPTH-FIRST — a nested
     * table follows its containing table, with {@link Table.depth}
     * recording the nesting level (0 = body-level). MCE-resolved; a fresh
     * array of lenses per call. Reading mutates nothing (L3 intact).
     *
     * @example
     * const doc = await Document.open(await readFile('report.docx'));
     * for (const t of doc.tables()) {
     *   console.log(t.rowCount(), t.columnCount(), t.cell(0, 0).text());
     * }
     */
    tables(): readonly Table[];
    /**
     * Append a `rows` × `cols` table at the end of the body (before the
     * body-final w:sectPr). With a `style` the table references it (no
     * direct borders); without one it gets direct single-line borders so it
     * is visible. Columns fill the printable page width equally unless
     * `widthsTwips` (whose length must equal `cols`) is given. Each cell
     * holds one empty paragraph. Marks the main part dirty. Throws when
     * rows/cols < 1. Returns the new table's lens.
     *
     * @example
     * const doc = Document.create();
     * const t = doc.addTable(3, 4, { style: 'TableGrid' });
     * t.cell(0, 0).setText('Q1');
     * t.addRow().cells()[0].setText('Total');
     */
    addTable(rows: number, cols: number, options?: TableCreateOptions): Table;
    /**
     * Every image in the body in document order, inline and anchored,
     * resolved through a:blip/@r:embed to its media part. Dangling embeds
     * and non-PNG/JPEG media (WMF/EMF) are skipped, never a throw. A fresh
     * array per call; reading mutates nothing (L3 intact).
     * `ImageInfo.data()` is async (media may need decompressing).
     *
     * @example
     * const doc = await Document.open(await readFile('report.docx'));
     * for (const im of doc.images()) {
     *   console.log(im.partName, im.placement, im.widthEmu);
     *   const bytes = await im.data();
     * }
     */
    images(): readonly ImageInfo[];
    /**
     * Append a paragraph containing one inline image. The format is sniffed
     * from the magic bytes (PNG/JPEG; anything else throws), the intrinsic
     * pixel size from the header gives the default display size at 96 DPI,
     * and one given axis (widthPx/heightPx or widthEmu/heightEmu) preserves
     * aspect ratio. Stores the bytes as a new /word/media part, adds the
     * image relationship, and builds w:drawing > wp:inline. Marks the main
     * part dirty. Returns the new image's {@link ImageInfo}.
     *
     * @example
     * const doc = Document.create();
     * const img = doc.addImage(pngBytes, { widthPx: 300, altText: 'Q3 chart' });
     * img.partName; // '/word/media/image1.png'
     * img.format;   // 'png'
     */
    addImage(bytes: Uint8Array, options?: AddImageOptions): ImageInfo;
    /**
     * Every header referenced by any `w:sectPr` (body-final or mid-document
     * pPr/sectPr), de-duplicated by part, in first-reference document order.
     * Each carries kind, `type` ('default'/'first'/'even'), partName, and
     * `text()`. A fresh array per call; reading mutates nothing.
     *
     * @example
     * const doc = await Document.open(await readFile('report.docx'));
     * doc.headers().map((h) => `${h.type}: ${h.text()}`);
     */
    headers(): readonly HeaderFooterInfo[];
    /**
     * Every footer referenced by any `w:sectPr` — see {@link Document.headers}.
     *
     * @example
     * const doc = await Document.open(await readFile('report.docx'));
     * doc.footers().map((f) => f.text());
     */
    footers(): readonly HeaderFooterInfo[];
    /**
     * Set the document's header of the given type (default 'default' = all
     * pages): creates a /word/headerN.xml part with one paragraph of `text`
     * plus its content type and relationship, and writes a
     * `w:headerReference` of that type into EVERY `w:sectPr`, replacing an
     * existing same-type reference (a part left unreferenced is removed).
     * type 'first' also sets w:titlePg; 'even' also sets
     * w:evenAndOddHeaders in settings.xml. Marks every touched part dirty.
     *
     * @example
     * const doc = Document.create();
     * doc.setHeader('ACME Corp — Confidential');
     * doc.setHeader('Cover page only', { type: 'first' });
     */
    setHeader(text: string, options?: SetHeaderFooterOptions): void;
    /**
     * Set the document's footer of the given type — see
     * {@link Document.setHeader}.
     *
     * @example
     * const doc = Document.create();
     * doc.setFooter('Page footer', { type: 'first' });
     */
    setFooter(text: string, options?: SetHeaderFooterOptions): void;
    /**
     * Append one bullet-list paragraph per item, all sharing ONE new bullet
     * numbering definition created in numbering.xml on demand (Word's
     * standard bullet glyphs for levels 0–8). A plain string is a level-0
     * item; `{ text, level }` (0–8) nests it. Marks main + numbering dirty.
     * Returns the new paragraphs as lenses (empty array for empty input).
     *
     * @example
     * const doc = Document.create();
     * doc.addBulletList(['Alpha', { text: 'Nested', level: 1 }, 'Beta']);
     */
    addBulletList(items: readonly ListItem[]): readonly Paragraph[];
    /**
     * Append one numbered-list paragraph per item, sharing ONE new
     * numbering definition per call — so consecutive calls each restart at
     * 1. Level formats follow `options.format` (default Word's
     * decimal/lowerLetter/lowerRoman rotation). Marks main + numbering
     * dirty. Returns the new paragraphs as lenses (empty array for empty
     * input).
     *
     * @example
     * const doc = Document.create();
     * const [first] = doc.addNumberedList(['Prepare', 'Execute', 'Verify']);
     * first.list()?.format; // 'decimal'
     */
    addNumberedList(items: readonly ListItem[], options?: NumberedListOptions): readonly Paragraph[];
    /** Serialize to file bytes — a pure delegate to `office.save()`. */
    save(): Promise<Uint8Array>;
}
//# sourceMappingURL=index.d.ts.map