@sobree/core 0.1.0

package/dist/doc/walk.d.ts

@@ -0,0 +1,30 @@
+import { Block, InlineRun, Paragraph, SobreeDocument, Table } from './types';
+/**
+ * Visitor pattern over the document tree.
+ *
+ * Every visitor key is optional — implement only the nodes you care about.
+ * Return `false` from any handler to skip descending into children of that
+ * node; return anything else (or omit the return) to continue.
+ *
+ * Why not exhaustive? Because the AST will gain shapes over time (comments,
+ * tracked changes, equations) and existing visitors shouldn't break when we
+ * add a new node kind. Skipped nodes log nothing — silent traversal.
+ */
+export interface DocVisitor {
+    document?: (doc: SobreeDocument) => void | false;
+    block?: (block: Block) => void | false;
+    paragraph?: (p: Paragraph) => void | false;
+    table?: (t: Table) => void | false;
+    run?: (r: InlineRun) => void | false;
+}
+export declare function walk(doc: SobreeDocument, v: DocVisitor): void;
+export declare function walkBlock(block: Block, v: DocVisitor): void;
+export declare function walkRun(run: InlineRun, v: DocVisitor): void;
+/**
+ * Collect every text run's text into a single flat string. Useful for
+ * search, outline extraction, and "give me the plain text" callers.
+ */
+export declare function plainText(doc: SobreeDocument): string;
+export declare function runsToText(runs: readonly InlineRun[]): string;
+/** Derive the heading level from a paragraph's styleId, if any. */
+export declare function headingLevelOf(p: Paragraph): number | null;

package/dist/docx/export/contentTypes.d.ts

@@ -0,0 +1,35 @@
+declare const REL_TYPES: {
+    readonly header: "http://schemas.openxmlformats.org/officeDocument/2006/relationships/header";
+    readonly footer: "http://schemas.openxmlformats.org/officeDocument/2006/relationships/footer";
+    readonly image: "http://schemas.openxmlformats.org/officeDocument/2006/relationships/image";
+    readonly hyperlink: "http://schemas.openxmlformats.org/officeDocument/2006/relationships/hyperlink";
+    readonly fontTable: "http://schemas.openxmlformats.org/officeDocument/2006/relationships/fontTable";
+    readonly font: "http://schemas.openxmlformats.org/officeDocument/2006/relationships/font";
+};
+type RelKind = keyof typeof REL_TYPES;
+/**
+ * `[Content_Types].xml` tells Office which content-type handler to use for
+ * each part. `overrides` are appended to the baseline; `imageExtensions`
+ * become `<Default>` content-type entries so embedded media round-trips.
+ */
+export declare function renderContentTypesXml(overrides?: Array<{
+    partName: string;
+    contentType: string;
+}>, imageExtensions?: readonly string[]): string;
+/**
+ * `_rels/.rels` — the package-level relationships, pointing at the main
+ * document part.
+ */
+export declare function renderRootRelsXml(): string;
+/**
+ * `word/_rels/document.xml.rels` — relationships originating from
+ * `document.xml`. Always includes the styles relationship (`rId1`);
+ * callers pass additional header/footer/image relationships to append.
+ */
+export declare function renderDocumentRelsXml(extras?: Array<{
+    id: string;
+    type: RelKind;
+    target: string;
+    external?: boolean;
+}>): string;
+export {};

package/dist/docx/export/context.d.ts

@@ -0,0 +1,59 @@
+import { SobreeDocument } from '../../doc/types';
+/**
+ * Mutable per-export bookkeeping: tracks which image `partPath`s have
+ * been allocated rIds, which new parts to add to the ZIP, and which
+ * content-type overrides the package manifest needs to declare.
+ *
+ * Constructed once in `exportDocx`, threaded through document + runs
+ * emission, then folded into the final relationships / manifest.
+ */
+export interface ExportContext {
+    /** Next rId to hand out via `allocRel`. Mutated as rIds are allocated. */
+    nextRid: number;
+    /** Rels to append to `word/_rels/document.xml.rels`. */
+    relationships: Array<{
+        id: string;
+        type: "header" | "footer" | "image" | "hyperlink" | "fontTable";
+        target: string;
+        /** External targets (URLs) need `TargetMode="External"`. */
+        external?: boolean;
+    }>;
+    /** New ZIP parts to include in the output package (e.g. `word/media/image1.png`). */
+    parts: Record<string, Uint8Array | string>;
+    /** Content-type overrides to declare in `[Content_Types].xml`. */
+    contentTypeOverrides: Array<{
+        partName: string;
+        contentType: string;
+    }>;
+    /** Media extensions seen (for content-type Default entries). */
+    mediaExtensions: Set<string>;
+    /** Cached path → rId so repeated DrawingRuns share one relationship. */
+    imageRelByPartPath: Map<string, string>;
+    /** Cached href → rId so repeated hyperlinks share one relationship. */
+    hyperlinkRelByHref: Map<string, string>;
+    /** Running docPr id counter — Word wants unique per-drawing ids. */
+    nextDocPrId: number;
+    /**
+     * Running revision id counter — Word requires `w:id="N"` on each
+     * `<w:ins>` / `<w:del>` / `<w:rPrChange>` / paragraph-mark revision
+     * element, unique within the document. We share one counter across
+     * all revision kinds to keep the IDs simple and contiguous.
+     */
+    nextRevisionId: number;
+}
+export declare function makeExportContext(startRid: number): ExportContext;
+/** Allocate the next w:id for a tracked-revision element. */
+export declare function nextRevisionId(ctx: ExportContext): number;
+/**
+ * Ensure an image relationship exists for the given `partPath`. Copies the
+ * bytes into `ctx.parts` on first encounter and returns the allocated rId.
+ */
+export declare function allocImageRel(ctx: ExportContext, partPath: string, doc: SobreeDocument): string | null;
+/** Next unique `docPr id` for a drawing. */
+export declare function nextDocPr(ctx: ExportContext): number;
+/**
+ * Ensure a hyperlink relationship exists for the given external `href`.
+ * Hyperlinks are external-target rels (TargetMode="External"), so the
+ * URL itself is the rel's `Target` and no part is added to the ZIP.
+ */
+export declare function allocHyperlinkRel(ctx: ExportContext, href: string): string;

package/dist/docx/export/document.d.ts

@@ -0,0 +1,19 @@
+import { ExportContext } from './context';
+import { Block, SobreeDocument } from '../../doc/types';
+/**
+ * Render the SobreeDocument body into `word/document.xml` (string form).
+ *
+ * `sectPrXmls` is the parallel array from `emitHeadersAndFooters` —
+ * one per section. Non-final sections' sectPr is spliced into the
+ * `<w:pPr>` of the LAST PARAGRAPH of that section's body range (OOXML
+ * convention; ECMA-376 §17.6.18). The final section's sectPr lands at
+ * body level after the last block. `SectionBreak` blocks themselves
+ * produce no output — they're delimiters whose semantics are carried
+ * by the spliced sectPr.
+ *
+ * `ctx` is mutated as drawings are encountered — each image registers
+ * a relationship and a ZIP media part.
+ */
+export declare function renderDocumentXml(doc: SobreeDocument, sectPrXmls: readonly string[], ctx: ExportContext): string;
+/** Also used for header/footer part bodies. */
+export declare function renderBlocks(blocks: readonly Block[], ctx: ExportContext, doc: SobreeDocument): string[];

package/dist/docx/export/drawings.d.ts

@@ -0,0 +1,10 @@
+import { DrawingRun } from '../../doc/types';
+/**
+ * Emit a `<w:drawing>` XML fragment for an inline image. Consumes an
+ * `rId` allocated elsewhere (via `ExportContext.allocImageRel`) and
+ * writes the OOXML shape Word expects for a single inline picture.
+ *
+ * Anchored / floating drawings are out of scope for Phase 5 — all images
+ * render inline.
+ */
+export declare function renderDrawing(run: DrawingRun, rId: string, docPrId: number): string;

package/dist/docx/export/headers.d.ts

@@ -0,0 +1,19 @@
+import { ExportContext } from './context';
+import { SectionProperties, SobreeDocument } from '../../doc/types';
+/**
+ * Build the OOXML scaffolding for every section in `doc`: header/footer
+ * XML parts, relationships, content-type overrides — and a parallel
+ * array of `<w:sectPr>` XML strings, one per section.
+ *
+ * Mutates `ctx`. Each referenced header/footer appends to `ctx.parts`,
+ * `ctx.relationships`, and `ctx.contentTypeOverrides`. Returns the
+ * sectPr XMLs in section order so the body renderer can splice the
+ * non-final ones into the last paragraph of each section's range and
+ * place the final one at body level.
+ *
+ * Header/footer parts are deduped across sections by their `partId`:
+ * the same `header1.xml` referenced from two sections only emits one
+ * part, with one `rId`. Subsequent references reuse the existing rId.
+ */
+export declare function emitHeadersAndFooters(doc: SobreeDocument, ctx: ExportContext): string[];
+export declare function renderSectPr(section: SectionProperties, headerRefs: string[], footerRefs: string[]): string;

package/dist/docx/export/index.d.ts

@@ -0,0 +1,14 @@
+import { SobreeDocument } from '../../doc/types';
+import { DocxExportResult } from '../types';
+/**
+ * Export a SobreeDocument as a .docx Blob + raw bytes.
+ *
+ * Emits the OOXML package:
+ *   - `[Content_Types].xml`, `_rels/.rels`,
+ *     `word/_rels/document.xml.rels`
+ *   - `word/styles.xml`, `word/document.xml`
+ *   - `word/header*.xml` / `word/footer*.xml` (per header/footer reference)
+ *   - `word/media/*` (per referenced image) — copied verbatim from
+ *     `doc.rawParts` and declared as image relationships.
+ */
+export declare function exportDocx(doc: SobreeDocument): DocxExportResult;

package/dist/docx/export/runs.d.ts

@@ -0,0 +1,8 @@
+import { ExportContext } from './context';
+import { InlineRun, SobreeDocument } from '../../doc/types';
+/**
+ * Render a list of InlineRuns into concatenated `<w:r>` / `<w:fldSimple>`
+ * / `<w:drawing>` XML. Drawings use `ctx` to allocate a relationship id
+ * and register the underlying media part.
+ */
+export declare function inlinesToRuns(inlines: readonly InlineRun[], ctx: ExportContext, doc: SobreeDocument): string;

package/dist/docx/export/styles.d.ts

@@ -0,0 +1,8 @@
+import { NamedStyle } from '../../doc/types';
+/**
+ * Render the document's named styles into `word/styles.xml`. Word needs a
+ * style-definition entry for every `w:pStyle` referenced in the body.
+ * Missing entries make Word fall back to Normal, stripping the visual
+ * hierarchy.
+ */
+export declare function renderStylesXml(styles: readonly NamedStyle[]): string;

package/dist/docx/export/zip.d.ts

@@ -0,0 +1,13 @@
+/** Map of part-path → contents (string parts auto-encoded to UTF-8). */
+export type DocxParts = Record<string, string | Uint8Array>;
+export interface DocxPackage {
+    blob: Blob;
+    bytes: Uint8Array;
+}
+/**
+ * Build a `.docx` package from a parts map. fflate's `zipSync` is plenty
+ * fast for the sizes we care about. We return both a Blob (for downloads)
+ * and the raw bytes (for node/jsdom environments where Blob.arrayBuffer()
+ * isn't implemented).
+ */
+export declare function packageDocx(parts: DocxParts): DocxPackage;

package/dist/docx/import/anchoredFrames.d.ts

@@ -0,0 +1,34 @@
+import { AnchoredFrame, Block } from '../../doc/types';
+export interface AnchoredFramesContext {
+    /** RelationshipId → part path lookup, e.g. `"rId4" → "media/image1.png"`. */
+    rels: Map<string, string>;
+    /**
+     * Importer's body-block list AT THE TIME this function runs. Used to
+     * resolve `paragraphIndex` for the AnchorOrigin: each frame is
+     * attributed to the body paragraph that contained its `<w:drawing>`,
+     * so the renderer knows which page receives the frame after
+     * pagination. May be empty during early-pass parsing; callers can
+     * pass `[]` and the renderer will treat all frames as section-relative.
+     */
+    bodyParagraphIndexByElement?: Map<Element, number>;
+    /**
+     * Recursive body walker for `<w:txbxContent>`, injected by the caller
+     * to avoid an `anchoredFrames ↔ document` import cycle. When present,
+     * textbox bodies parse through the SAME pipeline as the document body
+     * — real run formatting, paragraph spacing, lists, tables — so a
+     * frame whose content flows into the body (see `flowFrames`) keeps
+     * its true layout. When absent, falls back to flat text (tests).
+     */
+    parseBlockBody?: (txbxContent: Element) => Block[];
+}
+/**
+ * Walk every `<w:drawing>/<wp:anchor>` in the document and return one
+ * `AnchoredFrame` per top-level anchored drawing. The returned list is
+ * in document order, which matters for z-stacking when frames
+ * overlap (later siblings paint on top).
+ *
+ * The frame's `id` is deterministic: `"anchor-{N}"` where N is its
+ * document-order index. Selection / persistence rely on this being
+ * stable across re-imports of the same source.
+ */
+export declare function parseAnchoredFrames(xmlDoc: Document, ctx: AnchoredFramesContext, claim?: boolean): AnchoredFrame[];

package/dist/docx/import/comments.d.ts

@@ -0,0 +1,3 @@
+import { ConvertContext } from './paragraph';
+import { Comment } from '../../doc/types';
+export declare function parseCommentsXml(xml: string | undefined, ctx: ConvertContext, extendedXml?: string | undefined): Record<number, Comment>;

package/dist/docx/import/document.d.ts

@@ -0,0 +1,57 @@
+import { ConvertContext } from './paragraph';
+import { Block } from '../../doc/types';
+export { type ConvertContext, convertParagraph } from './paragraph';
+export interface DocumentImport {
+    body: Block[];
+    warnings: string[];
+    /**
+     * `<w:sectPr>` elements collected in document order, for the import
+     * pipeline to convert into `SectionProperties[]`. Includes both
+     * inline (paragraph-pPr) and body-level sectPrs.
+     *
+     * Length equals the number of sections in the resulting document.
+     * Inline sectPrs end non-final sections; the body-level one (always
+     * last) is the document-final section.
+     */
+    sectPrEls: Element[];
+}
+/**
+ * Convert a parsed `word/document.xml` into the SobreeDocument body — a
+ * flat list of `Block`s (Paragraphs, Tables, SectionBreaks).
+ *
+ * Multi-section detection: any paragraph whose `<w:pPr>` carries an
+ * inline `<w:sectPr>` is the last paragraph of a non-final section.
+ * The walker emits a `SectionBreak` block immediately after such a
+ * paragraph, and stashes the sectPr Element for the import pipeline
+ * to convert into `SectionProperties`. The body-level `<w:sectPr>` is
+ * stashed last as the document-final section's properties.
+ */
+/**
+ * Optional per-paragraph block replacements. When the body walker
+ * encounters a `<w:p>` element that's a key in `replaceParagraphs`,
+ * it emits the mapped Block *instead of* calling `convertParagraph`
+ * on it (and does NOT consume the paragraph's text content as a
+ * Paragraph block).
+ *
+ * Used by the `InlineFrame` import path to swap out section-heading
+ * paragraphs for first-class `InlineFrame` blocks at their original
+ * document-order position — without resorting to DOM-attribute
+ * markers or a post-walk splice. The contract is a typed map; the
+ * caller owns key identity.
+ */
+export interface ConvertOptions {
+    replaceParagraphs?: Map<Element, Block>;
+}
+export declare function convertDocumentXml(xmlDoc: Document, ctx: ConvertContext, opts?: ConvertOptions): DocumentImport;
+/**
+ * Walk a container element (`<w:body>` for `document.xml`, `<w:hdr>` /
+ * `<w:ftr>` for header/footer parts) and turn its direct paragraph +
+ * table children into `Block[]`. Extracted from `convertDocumentXml`
+ * so header/footer parts get the same rich-content import — drawings,
+ * comment ranges, revisions, formatted runs — instead of being
+ * collapsed to flat text by `flattenZone`.
+ *
+ * Header / footer parts never carry inline `<w:sectPr>` elements, so
+ * for those the returned `sectPrEls` is always empty.
+ */
+export declare function convertBlocksFromContainer(container: Element, ctx: ConvertContext, opts?: ConvertOptions): DocumentImport;

package/dist/docx/import/flowFrames.d.ts

@@ -0,0 +1,11 @@
+import { AnchoredFrame, Block } from '../../doc/types';
+/**
+ * Splice flowable frames' content into `body` at their anchor
+ * paragraph and drop them from the overlay set. Returns the rebuilt
+ * body and the frames that remain overlays (with `paragraphIndex`
+ * remapped to the new body positions). Pure — no mutation of inputs.
+ */
+export declare function flowDisplacingTextboxes(body: readonly Block[], frames: readonly AnchoredFrame[]): {
+    body: Block[];
+    frames: AnchoredFrame[];
+};

package/dist/docx/import/footnotes.d.ts

@@ -0,0 +1,3 @@
+import { ConvertContext } from './paragraph';
+import { Block } from '../../doc/types';
+export declare function parseFootnotesXml(xml: string | undefined, ctx: ConvertContext): Record<number, Block[]>;

package/dist/docx/import/headers.d.ts

@@ -0,0 +1,50 @@
+import { wVal } from '../shared/xml';
+import { PageZoneText } from '../../paperStack/pageSetup';
+import { SectionProperties } from '../../doc/types';
+/** Zone text extracted from the docx, with `{page}`/`{pages}` placeholders. */
+export interface ImportedZones {
+    header: PageZoneText;
+    footer: PageZoneText;
+}
+/**
+ * Resolve header/footer references in the body's first `<w:sectPr>`, load
+ * each referenced part, and flatten to plain text with `{page}` / `{pages}`
+ * substituted. Returns Sobree's `PageZoneText` model.
+ *
+ * Phase 2 ignores "even" references and keeps only "default" and "first".
+ * "Different last page" has no native Word equivalent; we leave
+ * `differentLast` off.
+ */
+export declare function readHeadersAndFooters(bodyXml: Document, relsXml: string | undefined, textParts: Record<string, string>): ImportedZones;
+/**
+ * `header*.xml` / `footer*.xml` → plain text with `{page}` / `{pages}`
+ * substituted for Word field codes. Flat text only; paragraph breaks
+ * become `\n`, inline formatting is dropped. Paired with
+ * `templateToBlocks` for the AST round-trip — the bridge converts the
+ * `{page}` tokens back into native `FieldRun` nodes.
+ */
+export declare function flattenZone(xml: string): string;
+/** Read a twip-valued attribute off `<w:pgSz>` / `<w:pgMar>`. */
+export declare function readTwipsAttr(el: Element | null, name: string): number | null;
+/**
+ * Convert a `<w:sectPr>` Element into a fully-populated `SectionProperties`.
+ *
+ * Reads pgSz / pgMar / vAlign / titlePg / type plus header and footer
+ * references (resolved through `rels` to partIds). Falls back to A4
+ * portrait + 1" margins when geometry is missing — matches Word's
+ * behaviour when an imported sectPr is sparse.
+ */
+export declare function readSection(sectPr: Element, rels: Map<string, string>): SectionProperties;
+/** Shared helper: parse `<w:sectPr>` for pgSz/pgMar/vAlign. */
+export declare function readPageGeometry(xmlDoc: Document): {
+    widthTwips: number | null;
+    heightTwips: number | null;
+    margins: {
+        top: number | null;
+        right: number | null;
+        bottom: number | null;
+        left: number | null;
+    };
+    vAlign: "top" | "center" | "bottom" | "both" | null;
+} | null;
+export { wVal };

package/dist/docx/import/index.d.ts

@@ -0,0 +1,12 @@
+import { templateToBlocks } from '../../doc/pageSetupBridge';
+import { DocxImportResult } from '../types';
+import { emptyDocument } from '../../doc/builders';
+import { Block, SobreeDocument } from '../../doc/types';
+/**
+ * Top-level entry point for importing a .docx file. Returns a native
+ * `SobreeDocument` plus any warnings surfaced by the conversion.
+ */
+export declare function importDocx(src: File | Blob | ArrayBuffer | Uint8Array): Promise<DocxImportResult>;
+export type { Block, SobreeDocument };
+export { emptyDocument };
+export { templateToBlocks };

package/dist/docx/import/inlineFrames.d.ts

@@ -0,0 +1,62 @@
+import { Block, InlineFrame } from '../../doc/types';
+export interface InlineFramesContext {
+    /** RelationshipId → part path lookup. */
+    rels: Map<string, string>;
+    /**
+     * Recursive body parser supplied by the caller. The textbox content
+     * (`<w:txbxContent>`) is a body of `<w:p>` / `<w:tbl>` children
+     * that should parse with the same rules as the document body —
+     * paragraph properties, runs, tables, even nested inline frames.
+     * Phase 1.1: callers can pass a simple text-only stub; Phase 1.2+
+     * will pass the full body walker.
+     */
+    parseBlockBody: (txbxContent: Element) => Block[];
+    /**
+     * When true, `<w:lastRenderedPageBreak/>` HINTS inside the textbox
+     * content cascade up to set `InlineFrame.pageBreakBefore`. These
+     * are stale layout hints Word writes during save, not author-
+     * declared directives — ECMA-376 says consumers SHOULD ignore
+     * them for layout. We respect them in two cases:
+     *   1. The body walker already opted in (heavily-decorated CVs
+     *      where the hints reliably match LO's reference pagination —
+     *      threshold is `≥10` total LRPB elements in the doc, decided
+     *      by `convertDocumentXml` and threaded through here).
+     *   2. The frame contains an explicit `<w:pageBreakBefore/>` in
+     *      the outer paragraph's pPr (always honoured).
+     * Without this flag, only explicit directives count.
+     */
+    honorLastRenderedPageBreaks?: boolean;
+}
+/**
+ * One InlineFrame plus the source DOM nodes it came from.
+ *
+ * `drawingEl` is the `<w:drawing>` the importer should TREAT AS
+ * REMOVED (legacy lifter will skip it; renderer paints from `frame`).
+ *
+ * `hostParagraphEl` is the `<w:p>` that contained the drawing — its
+ * outer `<w:pPr>` props (pageBreakBefore, keepNext) flowed into the
+ * frame. After the new path takes over, this paragraph becomes
+ * empty in the source; the importer can treat the InlineFrame as
+ * REPLACING it in the body block stream.
+ */
+export interface ParsedInlineFrame {
+    frame: InlineFrame;
+    drawingEl: Element;
+    hostParagraphEl: Element;
+}
+/**
+ * Walk every `<w:drawing>/<wp:inline>` in the document. For drawings
+ * whose payload includes at least one `<wps:txbx>`, emit one
+ * `InlineFrame`. Returns the frames in document order.
+ *
+ * When `claim` is true (the default), each claimed `<w:drawing>` is
+ * REMOVED from the input XML so the legacy `liftTextBoxContent` pass
+ * downstream can't double-process it. The host paragraph stays in
+ * place (now empty) so the body walker still emits a paragraph
+ * block at the right position — which the importer then swaps for
+ * the corresponding `InlineFrame` via `ConvertOptions.replaceParagraphs`.
+ *
+ * Set `claim: false` to inspect frames without mutating the XML
+ * (used by unit tests).
+ */
+export declare function parseInlineFrames(xmlDoc: Document, ctx: InlineFramesContext, claim?: boolean): ParsedInlineFrame[];

package/dist/docx/import/numbering.d.ts

@@ -0,0 +1,2 @@
+import { NumberingDefinition } from '../../doc/types';
+export declare function parseNumberingXml(xml: string | undefined): NumberingDefinition[];

package/dist/docx/import/paragraph.d.ts

@@ -0,0 +1,24 @@
+import { Paragraph } from '../../doc/types';
+/**
+ * Shared context for importing a body — rels + media lookup. Lives here
+ * (rather than in `document.ts`) so `tables.ts` can pull it without
+ * forming a `document.ts` ↔ `tables.ts` import cycle.
+ */
+export interface ConvertContext {
+    /** Rels map (`rId` → target path). Used for image embed resolution. */
+    rels: Map<string, string>;
+    /** When true, `<w:lastRenderedPageBreak/>` markers are honoured as
+     *  forced page breaks (i.e. translated to `pageBreakBefore: true`).
+     *  Caller sets this after counting hints per document: a meaningful
+     *  number of hints (≥3) indicates Word's layout produced reliable
+     *  page boundaries; a stray single hint is usually stale and
+     *  ignored. */
+    honorLastRenderedPageBreaks?: boolean;
+}
+/**
+ * Convert a single `<w:p>` element into a Paragraph block. Handles
+ * paragraph formatting (heading style, alignment, spacing, numbering),
+ * runs (text/hyperlink/drawing), and image embed resolution via the
+ * rels map carried in `ctx`.
+ */
+export declare function convertParagraph(p: Element, ctx: ConvertContext, activeComments?: Set<number>): Paragraph;

package/dist/docx/import/paragraphs.d.ts

@@ -0,0 +1,27 @@
+import { ImportedRun } from './runs';
+import { ParagraphFormat } from '../types';
+/** Source-order paragraph item: either a flat run or a hyperlink-wrapped group. */
+export type ImportedItem = {
+    kind: "run";
+    run: ImportedRun;
+} | {
+    kind: "hyperlink";
+    relId?: string;
+    runs: ImportedRun[];
+};
+export interface ImportedParagraph {
+    /** Items in document order. Hyperlinks contain inner runs. */
+    items: ImportedItem[];
+    format: ParagraphFormat;
+}
+/**
+ * Read a single `<w:p>` into an `ImportedParagraph`.
+ *
+ * `activeComments` is an *external* set the caller threads across
+ * paragraphs so comment ranges (`<w:commentRangeStart/End>`) that span
+ * multiple paragraphs tag the middle paragraphs' runs too. When
+ * omitted, a fresh empty set is used — fine for contexts where ranges
+ * shouldn't cross the paragraph (footnote bodies, comment bodies,
+ * table cells).
+ */
+export declare function readParagraph(p: Element, activeComments?: Set<number>): ImportedParagraph;

package/dist/docx/import/rels.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Parse a `_rels/*.rels` file into a map of `Id` → `Target`. The Target is
+ * relative to the .rels file's own directory (Word's convention).
+ */
+export declare function parseRels(xmlSrc: string): Map<string, string>;

package/dist/docx/import/runs.d.ts

@@ -0,0 +1,64 @@
+import { RunFormat } from '../types';
+/** Frame-of-reference choices the importer carries through; mapped 1:1 to
+ *  the `DrawingAnchor.relativeFromH` / `relativeFromV` AST values. */
+export interface ImportedAnchor {
+    offsetXEmu: number;
+    offsetYEmu: number;
+    relativeFromH: "page" | "margin" | "column" | "character";
+    relativeFromV: "page" | "margin" | "paragraph" | "line";
+    behindDoc?: boolean;
+}
+/** Drawing info extracted from a `<w:drawing>` inside a run. */
+export interface ImportedDrawing {
+    /** Relationship id of the embedded image (`<a:blip r:embed="rIdN"/>`). */
+    embedRelId?: string;
+    widthEmu?: number;
+    heightEmu?: number;
+    altText?: string;
+    /** Present when the drawing is a `<wp:anchor>` (floating) rather than
+     *  `<wp:inline>`. The renderer positions the image absolutely via
+     *  these coordinates. */
+    anchor?: ImportedAnchor;
+}
+/**
+ * Read a `<w:r>` element into a `{ text, format }` pair. The document
+ * converter maps the format flags onto the native `RunProperties` shape.
+ */
+export interface ImportedRun {
+    text: string;
+    format: RunFormat;
+    /** True if this run was `<w:br/>`; `text` is empty in that case. */
+    isHardBreak: boolean;
+    /** Type of break for `isHardBreak` runs — line (Shift-Enter), page
+     *  (force new page), or column (force next column in a multi-column
+     *  section). Defaults to "line" when omitted. */
+    breakType?: "line" | "page" | "column";
+    /** Set when the run wraps an inline `<w:drawing>` (image). */
+    drawing?: ImportedDrawing;
+    /** Set when the run wraps a `<w:footnoteReference w:id="N"/>`. */
+    footnoteRefId?: number;
+    /** Set when the run wraps a `<w:commentReference w:id="N"/>`. */
+    commentRefId?: number;
+    /** Set when the run is inside a `<w:ins>` / `<w:del>` wrapper. */
+    revision?: {
+        type: "ins" | "del";
+        author?: string;
+        date?: string;
+    };
+    /** Set when the run is between a `<w:commentRangeStart w:id="N"/>`
+     *  and matching `<w:commentRangeEnd>`. Multiple ids when nested /
+     *  overlapping comments cover the run. */
+    commentIds?: readonly number[];
+    /**
+     * Set when the source was a `<w:fldSimple w:instr="...">`. The
+     * paragraph converter emits a `FieldRun` from this — used for
+     * page-number tokens (`PAGE` / `NUMPAGES`) in headers and footers
+     * so the round-trip through `blocksToTemplate` preserves `{page}` /
+     * `{pages}`.
+     */
+    field?: {
+        instruction: string;
+        cached?: string;
+    };
+}
+export declare function readRun(r: Element): ImportedRun;

package/dist/docx/import/settings.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Parse the subset of `word/settings.xml` that affects rendering.
+ *
+ * The two flags we care about right now are the ones that decide
+ * whether Word applies its implicit "Word 2010+ Normal style" baseline
+ * (line ≈ 1.08, after = 8pt) at render time even when styles.xml
+ * leaves Normal empty:
+ *
+ *   - `<w:compatibilityMode w:val="14"/>` — Word's rendering era.
+ *      12+ = Word 2007+ with the modern Normal defaults.
+ *      <12 = legacy mode, no implicit spacing.
+ *   - `<w:doNotUseHTMLParagraphAutoSpacing/>` — when present, Word
+ *      explicitly opts out of the modern auto-spacing and renders
+ *      tight regardless of compatibilityMode.
+ *
+ * This is the missing piece that explains why a Word-authored docx
+ * with an empty `<w:style w:styleId="Normal">` renders with visible
+ * inter-paragraph breathing in Word (compatibilityMode 14, auto-
+ * spacing on), but a programmatically-generated docx with no
+ * `<w:compatibilityMode>` renders tight in Word too. Without this
+ * gate, Sobree's baseline-injection either over- or under-applies
+ * depending on the source.
+ */
+export interface DocSettings {
+    /** Numeric compatibility mode from `<w:compatibilityMode>`. Undefined
+     *  if the docx omits it (treat as legacy = pre-Word-2007). */
+    compatibilityMode?: number;
+    /** True when `<w:doNotUseHTMLParagraphAutoSpacing/>` is present. */
+    doNotUseHTMLParagraphAutoSpacing: boolean;
+    /** `<w:defaultTabStop w:val="N"/>` in twips. Used as the interval
+     *  for tab advances in paragraphs that don't declare their own
+     *  `<w:tabs>`. Word's factory default is 720 twips (0.5"). */
+    defaultTabStopTwips?: number;
+}
+export declare function parseSettingsXml(xml: string | undefined): DocSettings;
+/**
+ * Should we apply Word's implicit "Normal style" paragraph baseline
+ * (line ≈ 1.08, after = 8pt) for paragraphs whose explicit settings
+ * leave those fields undefined?
+ *
+ * Word's rule, distilled: yes when in Word 2007+ rendering mode
+ * (compatibilityMode >= 12) AND auto-spacing isn't explicitly turned
+ * off. Without this gate, Sobree either over-applies (on a docx-
+ * library-style doc that lacks compatibilityMode → renders tight in
+ * Word too) or under-applies (on a Word-authored doc whose Normal
+ * style is empty → Word fills in defaults, we don't).
+ */
+export declare function shouldApplyAutoSpacing(settings: DocSettings): boolean;