@sobree/core 0.1.27 → 0.1.29

package/dist/doc/mutations/blocks.d.ts

@@ -0,0 +1,14 @@
+import { BlockRef } from '../api';
+import { Block } from '../types';
+import { DocumentMutationResult, MutationInput } from './types';
+/** Replace the block at `target`'s index with `block`. If a section_break
+ *  is replaced by a non-break, the two sections it delimited merge (the
+ *  earlier section's properties survive). */
+export declare function replaceBlockMutation(input: MutationInput, target: BlockRef, block: Block): DocumentMutationResult<BlockRef>;
+/** Insert `block` before the target block. */
+export declare function insertBlockBeforeMutation(input: MutationInput, target: BlockRef, block: Block): DocumentMutationResult<BlockRef>;
+/** Insert `block` after the target block. */
+export declare function insertBlockAfterMutation(input: MutationInput, target: BlockRef, block: Block): DocumentMutationResult<BlockRef>;
+/** Delete the target block. Deleting the only block leaves one empty
+ *  paragraph. Deleting a section_break merges the sections it delimited. */
+export declare function deleteBlockMutation(input: MutationInput, target: BlockRef): DocumentMutationResult<void>;

package/dist/doc/mutations/index.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Pure document mutation engine — the single source of truth for the
+ * AST-level edits both Sobree peers perform.
+ *
+ * # Why this exists
+ *
+ * The browser `Editor` (DOM-backed) and `HeadlessSobree` (no-DOM peer for
+ * LLM agents / MCP / automation) used to implement the same block,
+ * paragraph, section, style, and numbering mutations independently. That
+ * is silent-drift risk: change one path and the other — hence MCP, hence
+ * every collaborating peer — keeps the old behavior, and Y.Doc parity or
+ * block-version semantics diverge with nothing failing loudly. These
+ * functions are that shared logic, called by both adapters.
+ *
+ * # The contract
+ *
+ * A mutation function is **pure**: given a {@link MutationInput} it returns
+ * a {@link DocumentMutationResult} — a document patch plus the
+ * registry-level {@link Mutation}s to apply — and nothing else.
+ *
+ * Strictly NO:
+ *   - DOM / `HTMLElement` / selection APIs
+ *   - `Y.Doc` / Yjs
+ *   - renderer / paginator calls
+ *   - command bus / plugin / editor-instance access
+ *
+ * The adapter owns commit, optimistic-lock application, Y.Doc mirroring,
+ * history, rendering, and events. If a mutation seems to need any of the
+ * above, the boundary is wrong — the engine should only know document
+ * structure, block references, optimistic-lock metadata, and pure AST
+ * transformations.
+ */
+export * from './blocks';
+export * from './numbering';
+export * from './paragraphs';
+export * from './sections';
+export * from './styles';
+export * from './types';

package/dist/doc/mutations/numbering.d.ts

@@ -0,0 +1,8 @@
+import { NumberingDefinition, NumberingLevel } from '../types';
+import { DocumentMutationResult, MutationInput } from './types';
+/** Add a new numbering definition. Fails if `def.numId` already exists. */
+export declare function defineNumberingMutation(input: MutationInput, def: NumberingDefinition): DocumentMutationResult<void>;
+/** Replace the levels of the definition with `numId`. Fails if missing. */
+export declare function updateNumberingMutation(input: MutationInput, numId: number, levels: NumberingLevel[]): DocumentMutationResult<void>;
+/** Remove the definition with `numId`. Fails if missing. */
+export declare function removeNumberingMutation(input: MutationInput, numId: number): DocumentMutationResult<void>;

package/dist/doc/mutations/paragraphs.d.ts

@@ -0,0 +1,13 @@
+import { ParagraphPropertiesPatch } from '../../editor/types';
+import { BlockRef } from '../api';
+import { ParagraphProperties } from '../types';
+import { DocumentMutationResult, MutationInput } from './types';
+/**
+ * Merge a `ParagraphPropertiesPatch` into existing properties.
+ * `undefined` in the patch removes a field; everything else
+ * overwrites.
+ */
+export declare function mergeParagraphProps(prev: ParagraphProperties, patch: ParagraphPropertiesPatch): ParagraphProperties;
+/** Merge a patch into each target paragraph's properties. Bumps each
+ *  paragraph's version; fails if any target is not a paragraph. */
+export declare function applyBlockPropertiesMutation(input: MutationInput, targets: readonly BlockRef[], patch: ParagraphPropertiesPatch): DocumentMutationResult<void>;

package/dist/doc/mutations/sections.d.ts

@@ -0,0 +1,40 @@
+import { SectionPropertiesPatch } from '../../editor/types';
+import { Block, SectionProperties } from '../types';
+import { DocumentMutationResult, MutationInput } from './types';
+/**
+ * Index in `sections` of the section that ENDS at the section_break at
+ * `breakIndex`. Sections are 1:1 with section_breaks; the first
+ * section ends at the first break (or at the end of `body` if there's
+ * no break).
+ *
+ *   body = [p, p, break, p, break, p]
+ *   sections = [s0, s1, s2]
+ *
+ *   breakIndex = 2 → 0 (the first break ends section 0)
+ *   breakIndex = 4 → 1 (the second break ends section 1)
+ */
+export declare function removedSectionIndex(body: readonly Block[], breakIndex: number): number;
+/**
+ * Drop the section at `endingIndex + 1` from `sections` — that's the
+ * section the now-removed break STARTED. The section ENDED by the
+ * removed break (at `endingIndex`) absorbs whatever content used to
+ * belong to its successor. Properties of the surviving section are
+ * preserved verbatim; nothing about the removed section's settings is
+ * carried over.
+ *
+ * If `sections` doesn't have a successor (the removed break was the
+ * last one and there's only one section), the array is returned
+ * unchanged.
+ */
+export declare function mergeSectionsAcross(sections: readonly SectionProperties[], endingIndex: number): SectionProperties[];
+/**
+ * Merge a {@link SectionPropertiesPatch} onto existing section properties.
+ * `pageSize` / `pageMargins` are FIELD-merged (a partial stays valid); the
+ * other fields replace wholesale. For the optional fields (`columns`,
+ * `titlePage`, `type`, `vAlign`) an explicit `undefined` clears them, while
+ * the required `headerRefs` / `footerRefs` only replace when present.
+ */
+export declare function mergeSectionProps(prev: SectionProperties, patch: SectionPropertiesPatch): SectionProperties;
+/** Merge a patch into the section at `sectionIndex`. No block versions
+ *  bump — a section is not a block. Fails if the index is out of range. */
+export declare function applySectionPropertiesMutation(input: MutationInput, sectionIndex: number, patch: SectionPropertiesPatch): DocumentMutationResult<void>;

package/dist/doc/mutations/styles.d.ts

@@ -0,0 +1,14 @@
+import { NamedStylePatch } from '../../editor/types';
+import { NamedStyle } from '../types';
+import { DocumentMutationResult, MutationInput } from './types';
+/** Merge a {@link NamedStylePatch} onto an existing style. Each present
+ *  field replaces the style's field wholesale; an explicit `undefined`
+ *  clears an OPTIONAL field. The required `type` / `displayName` are never
+ *  cleared (an undefined for them is ignored). */
+export declare function mergeNamedStyle(prev: NamedStyle, patch: NamedStylePatch): NamedStyle;
+/** Add a new named style. Fails if `style.id` already exists. */
+export declare function defineStyleMutation(input: MutationInput, style: NamedStyle): DocumentMutationResult<void>;
+/** Merge a patch into the style with `id`. Fails if no such style. */
+export declare function updateStyleMutation(input: MutationInput, id: string, patch: NamedStylePatch): DocumentMutationResult<void>;
+/** Remove the style with `id`. Fails if no such style. */
+export declare function removeStyleMutation(input: MutationInput, id: string): DocumentMutationResult<void>;

package/dist/doc/mutations/types.d.ts

@@ -0,0 +1,57 @@
+import { BlockRef, EditResult } from '../api';
+import { SobreeDocument } from '../types';
+/**
+ * One registry-level operation produced by a mutation. The adapter
+ * applies these to its BlockRegistry after committing the new doc:
+ * `insert` adds an id, `remove` drops one, `bump` keeps the same id
+ * but increments its version.
+ */
+export type Mutation = {
+    type: "bump";
+    index: number;
+} | {
+    type: "insert";
+    index: number;
+} | {
+    type: "remove";
+    index: number;
+};
+/**
+ * The read-only slice of a block registry the engine depends on. Both
+ * the browser `Editor`'s registry and `HeadlessSobree`'s satisfy this
+ * directly — the engine stays unaware of how ids/versions are stored or
+ * mutated.
+ */
+export interface BlockRegistryView {
+    indexOf(id: string): number;
+    refAt(index: number): BlockRef;
+    refById(id: string): BlockRef | null;
+    documentVersion(): number;
+}
+export interface MutationInput {
+    doc: SobreeDocument;
+    registry: BlockRegistryView;
+}
+/**
+ * The result of a successful mutation: the document fields to merge, the
+ * registry mutations to apply, and the value the public method returns
+ * (e.g. the new `BlockRef` for an insert). The adapter's `commit` applies
+ * `update` + `mutations` and surfaces `value`.
+ */
+export interface MutationPatch<T = void> {
+    update: Partial<SobreeDocument>;
+    mutations: readonly Mutation[];
+    value: T;
+}
+export type DocumentMutationResult<T = void> = EditResult<MutationPatch<T>>;
+/** Wrap a computed patch in a successful {@link DocumentMutationResult}.
+ *  Affected refs are left empty — the adapter's `commit` computes them when
+ *  it applies the registry mutations. */
+export declare function okPatch<T = void>(update: Partial<SobreeDocument>, mutations: readonly Mutation[], value?: T): DocumentMutationResult<T>;
+/**
+ * Optimistic-lock check shared by both adapters. Aggregates every stale
+ * or missing ref into a single lock conflict: a ref whose id no longer
+ * exists is reported with `actual: null`; a version mismatch with the
+ * live version. Returns `null` when every ref is current.
+ */
+export declare function checkRefs(registry: BlockRegistryView, refs: readonly BlockRef[]): EditResult<never> | null;

package/dist/doc/types/block.d.ts

@@ -0,0 +1,182 @@
+import { Shading, TableBorders, TableCellBorders, TableCellMargins } from '../formatting.types';
+import { TableLook } from '../tableStyle.types';
+import { ParagraphAlignment, ParagraphProperties } from './paragraph';
+import { InlineRun } from './runs';
+export type Block = Paragraph | Table | SectionBreak | InlineFrame;
+export interface Paragraph {
+    kind: "paragraph";
+    properties: ParagraphProperties;
+    /** Inline runs in document order. May be empty (a blank paragraph). */
+    runs: InlineRun[];
+}
+/** Explicit page-break or section-break marker emitted between paragraphs. */
+export interface SectionBreak {
+    kind: "section_break";
+    /** Which section in `SobreeDocument.sections` continues after this point. */
+    toSectionIndex: number;
+}
+export interface Table {
+    kind: "table";
+    /** Column widths in twips. Length = number of columns. */
+    grid: number[];
+    rows: TableRow[];
+    properties: TableProperties;
+}
+export interface TableProperties {
+    /** Total table width in twips, or "auto" for content-driven. */
+    widthTwips?: number;
+    alignment?: ParagraphAlignment;
+    borders?: TableBorders;
+    /** Style reference (e.g. "TableGrid"). */
+    styleId?: string;
+    /** `<w:tblLook>` — which of the table style's conditional formats are
+     *  active (first row / column, last row / column, row / column
+     *  banding). Gates {@link TableStyleDefinition} resolution. */
+    look?: TableLook;
+    /** `<w:tblCellMar>` — default inner padding for every cell (the table's
+     *  own value wins over the style's). Word's stock default is ~108 twips
+     *  left / right and 0 top / bottom when omitted. */
+    cellMargins?: TableCellMargins;
+}
+export interface TableRow {
+    cells: TableCell[];
+    /** True if this row is a header row repeated on each page. */
+    isHeader?: boolean;
+}
+export interface TableCell {
+    /** Number of grid columns this cell spans horizontally. */
+    gridSpan?: number;
+    /** Vertical merge state — `restart` begins a merge, `continue` continues. */
+    vMerge?: "restart" | "continue";
+    verticalAlign?: "top" | "center" | "bottom";
+    shading?: Shading;
+    borders?: TableCellBorders;
+    /** Cell content — paragraphs and (rare) nested tables. */
+    content: Block[];
+}
+/**
+ * A rectangular drawing region that flows inline with body blocks
+ * (NOT absolutely positioned — that's `AnchoredFrame`). Owns its own
+ * picture decoration(s), its own textbox body (recursive `Block[]`),
+ * and its own break / keep-with-next directives. Maps 1:1 to
+ * `<w:drawing><wp:inline>` with a `<wpg:wgp>` payload that wraps a
+ * `<wps:txbx>` textbox shape + decorative `<pic:pic>` / `<wps:wsp>`
+ * siblings.
+ *
+ * Replaces the legacy lifter's "split into N body paragraphs with
+ * `liftedFromTextBox` + `framePictures` + `textboxShape` glued on"
+ * approach. One frame = one block. The page-break directive that
+ * belonged to the containing paragraph in the source OOXML moves
+ * here (`pageBreakBefore`), where the paginator's top-level-child
+ * inspection actually finds it.
+ *
+ * See `packages/core/docs/INLINE_FRAME_DESIGN.md` for the full
+ * design and migration plan.
+ *
+ * **Status**: type declared (Phase 1.0). Importer does not yet emit
+ * this; renderer treats it as a no-op. Wiring lands in Phase 1.1-1.2.
+ */
+/** One textbox shape inside an inline-frame group: its intra-group
+ *  position + size and recursive body, plus optional chrome (fill /
+ *  border / text insets) and vertical text anchor. */
+export interface InlineFrameTextbox {
+    offsetEmu: {
+        xEmu: number;
+        yEmu: number;
+    };
+    sizeEmu: {
+        wEmu: number;
+        hEmu: number;
+    };
+    body: Block[];
+    fill?: string;
+    border?: FrameBorder;
+    /** `<wps:bodyPr>` text insets (lIns/tIns/rIns/bIns) → CSS padding. */
+    padding?: {
+        topEmu: number;
+        rightEmu: number;
+        bottomEmu: number;
+        leftEmu: number;
+    };
+    /** Vertical text anchor from `<wps:bodyPr anchor>`; defaults to "top". */
+    vAlign?: "top" | "center" | "bottom";
+}
+export interface InlineFrame {
+    kind: "inline_frame";
+    /** From the containing `<w:p>`'s `<w:pPr>`. The paginator emits a
+     *  `Penalty(-Infinity)` before the frame when set. */
+    pageBreakBefore?: boolean;
+    /** From the containing `<w:p>`'s `<w:pPr>`. Keep with the next
+     *  block to avoid widowing a section heading from its body. */
+    keepNext?: boolean;
+    /** The containing `<w:p>`'s resolved paragraph properties. An inline
+     *  drawing lives inside a host paragraph; that paragraph carries
+     *  spacing (before/after), alignment, etc. from its style cascade
+     *  (commonly `Normal`'s `<w:spacing w:after>`). The renderer applies
+     *  these to the frame wrapper so the band reserves the SAME vertical
+     *  box (drawing height + paragraph spacing) Word does — without it
+     *  the band is short by the spacing-after, which compounds down the
+     *  page and shifts pagination. Absent → wrapper uses bare defaults. */
+    hostProps?: ParagraphProperties;
+    /** The drawing group's intrinsic coordinate-system extent. Every
+     *  child's `offsetEmu` / `sizeEmu` below is expressed in this
+     *  space; the renderer scales them by `sizeEmu / groupExtentEmu`
+     *  when painting at the final rendered size. */
+    groupExtentEmu: {
+        wEmu: number;
+        hEmu: number;
+    };
+    /** The frame's rendered display dimensions. Usually equal to
+     *  `groupExtentEmu` for inline drawings (no scaling) but kept
+     *  separate so a future "render at half-size" / scaling case
+     *  doesn't require touching every child. */
+    sizeEmu: {
+        wEmu: number;
+        hEmu: number;
+    };
+    /** The group's textbox SHAPES, in document (child) order. Most groups
+     *  have one (a section "pill" heading: a centred line over a background
+     *  picture), but a "Project: X" entry has two — a title textbox and a
+     *  details textbox — and the renderer must show BOTH. Empty when the
+     *  group carries only pictures / shapes (no textbox content). */
+    textboxes: InlineFrameTextbox[];
+    /** Decorative pictures inside the group. Each carries its own
+     *  intra-group position. The renderer paints them as
+     *  absolute-positioned `<img>` children of the frame wrapper,
+     *  scaled by the same `sizeEmu / groupExtentEmu` ratio. */
+    pictures: ReadonlyArray<{
+        partPath: string;
+        offsetEmu: {
+            xEmu: number;
+            yEmu: number;
+        };
+        sizeEmu: {
+            wEmu: number;
+            hEmu: number;
+        };
+        altText?: string;
+    }>;
+    /** Non-picture decorative shapes (rect / ellipse / line) inside
+     *  the group. Same positioning model as `pictures`. */
+    shapes: ReadonlyArray<{
+        geometry: "rect" | "ellipse" | "roundedRect" | "line";
+        offsetEmu: {
+            xEmu: number;
+            yEmu: number;
+        };
+        sizeEmu: {
+            wEmu: number;
+            hEmu: number;
+        };
+        fill?: string;
+        border?: FrameBorder;
+    }>;
+}
+/** Shared border descriptor for inline / anchored frame chrome.
+ *  Distinct from `BorderSpec` (used for paragraph / table borders
+ *  whose OOXML `w:val` covers a different vocabulary). */
+export interface FrameBorder {
+    color: string;
+    widthEmu: number;
+    style: "solid" | "dashed" | "dotted" | "double";
+}

package/dist/doc/types/document.d.ts

@@ -0,0 +1,122 @@
+import { FontDeclaration } from '../../fonts/types';
+import { Block, InlineFrame } from './block';
+import { AnchoredFrame } from './drawing';
+import { NumberingDefinition } from './numbering';
+import { SectionProperties } from './sections';
+import { NamedStyle } from './styles';
+export interface SobreeDocument {
+    /** Top-level body content, in document order. */
+    body: Block[];
+    /**
+     * One section per body slice. The simplest doc has exactly one section
+     * spanning the whole body. Phase N1 supports a single-section model.
+     */
+    sections: SectionProperties[];
+    /**
+     * Header and footer bodies keyed by `HeaderFooterRef.partId`. The partId
+     * is the ZIP target name (`header1.xml`, `footer2.xml`, …). Rendering
+     * emits each body to its own OOXML part at export time.
+     */
+    headerFooterBodies: Record<string, Block[]>;
+    /**
+     * Floating objects that live inside a header/footer part, keyed by the
+     * SAME `HeaderFooterRef.partId` as `headerFooterBodies`. A header part
+     * is a self-contained sub-document: its flow blocks live in
+     * `headerFooterBodies[partId]`, its anchored frames here. The renderer
+     * paints these into a per-zone overlay exactly like body `anchoredFrames`.
+     * Empty/absent for the common header-without-floats case.
+     */
+    headerFooterFrames?: Record<string, AnchoredFrame[]>;
+    /** Named styles (Heading1, Quote, Body Text, …) defined at the doc level. */
+    styles: NamedStyle[];
+    /** List/numbering definitions referenced by `Paragraph.properties.numbering`. */
+    numbering: NumberingDefinition[];
+    /**
+     * Embedded binary parts keyed by ZIP path (e.g. `word/media/image1.png`).
+     * Images, fonts, custom XML — anything not represented in body XML.
+     */
+    rawParts: Record<string, Uint8Array>;
+    /**
+     * Font declarations from `word/fontTable.xml`. Empty for new docs.
+     * Embedded faces reference parts inside `rawParts`.
+     */
+    fonts: FontDeclaration[];
+    /**
+     * Footnote bodies keyed by id. Body inline runs use `FootnoteRefRun`
+     * with the matching `id` to reference them. Empty for docs without
+     * footnotes (the common case).
+     */
+    footnotes?: Record<number, Block[]>;
+    /**
+     * Comments keyed by id. Body inline runs whose properties carry a
+     * matching `commentIds` mark the range each comment annotates.
+     * Empty for docs without comments (the common case).
+     */
+    comments?: Record<number, Comment>;
+    /**
+     * Document-wide layout settings parsed from `word/settings.xml`.
+     * Currently only `defaultTabStopTwips` — Word's default interval for
+     * tab advances in paragraphs that don't declare their own `<w:tabs>`
+     * stops. Word's factory default is 720 twips (0.5"). Without
+     * respecting this, the browser falls back to the CSS `tab-size`
+     * default of 8 characters which is much narrower than what Word
+     * shows, and tab-aligned content (e.g. label/value columns in
+     * letterheads) ends up cramped.
+     */
+    settings?: {
+        defaultTabStopTwips?: number;
+    };
+    /**
+     * NOTE: inline-drawing frames are emitted as `InlineFrame` BLOCKS
+     * directly in `body` (the importer splices them in at their source
+     * paragraph's position via `ConvertOptions.replaceParagraphs`), so
+     * they paginate in document flow. This optional top-level list is
+     * a secondary handle kept for tooling/inspection; the renderer
+     * consumes the body blocks, not this list.
+     *
+     * The first-class model replaced the old `liftTextBoxContent`
+     * machinery that exploded section-heading textboxes into body
+     * paragraphs with synthetic `framePictures` / `liftedFromTextBox`
+     * metadata. See `packages/core/docs/INLINE_FRAME_DESIGN.md`.
+     */
+    inlineFrames?: InlineFrame[];
+    /**
+     * Floating objects (`<w:drawing>/<wp:anchor>`, `<w:pict>` VML) that
+     * live in their own layer above the body. Each frame carries its
+     * own coordinates + dimensions in EMU and is independent of
+     * pagination — the paginator only sees `body` blocks. The renderer
+     * places each frame on the page its anchor resolves to and paints
+     * it into a per-page `<div class="paper-anchors">` overlay.
+     *
+     * Replaces the pre-AnchoredFrame "lifter" architecture where the
+     * importer exploded each `<w:txbxContent>` into N body paragraphs
+     * with synthetic `liftedFromTextBox` metadata. The flat list here
+     * is simpler, makes selection / resize / move trivial (each frame
+     * is one DOM element), and frees the paginator from having to
+     * route around absolute-positioned ghosts.
+     */
+    anchoredFrames?: AnchoredFrame[];
+}
+export interface Comment {
+    id: number;
+    author?: string;
+    /** Author initials as recorded in the docx — Word uses them in the
+     *  comment sidebar header. */
+    initials?: string;
+    /** ISO-8601 date string. */
+    date?: string;
+    /** Comment body — typically one or more paragraphs. */
+    body: Block[];
+    /**
+     * Resolved / "Done" flag from `word/commentsExtended.xml`
+     * (`<w15:commentEx w15:done="1">`). Absent or false → open.
+     */
+    done?: boolean;
+    /**
+     * Id of the parent comment when this is a reply in a thread.
+     * Resolved from `<w15:commentEx w15:paraIdParent="…">` by matching
+     * the parent's body-paragraph paraId back to its comment id.
+     * Absent → top-level comment.
+     */
+    replyToId?: number;
+}

package/dist/doc/types/drawing.d.ts

@@ -0,0 +1,141 @@
+import { Block } from './block';
+/**
+ * A floating object pinned to a page or paragraph at an explicit
+ * coordinate. Sources: `<w:drawing>/<wp:anchor>` shapes,
+ * `<w:pict>` VML boxes.
+ *
+ * Coordinates use OOXML's EMU (914400 EMU = 1 inch). The renderer
+ * converts to CSS millimetres at paint time.
+ */
+export interface AnchoredFrame {
+    /** Stable id, deterministic from document import order. */
+    id: string;
+    /** What the offsets are measured from. */
+    anchor: AnchorOrigin;
+    offsetXEmu: number;
+    offsetYEmu: number;
+    widthEmu: number;
+    heightEmu: number;
+    /** Stacking order. Higher = on top. Default 0. */
+    zIndex?: number;
+    /** When true the frame paints BEHIND body text (z-index negative).
+     *  Maps to OOXML `<wp:anchor behindDoc="1">`. */
+    behindText?: boolean;
+    /** Text-wrap mode from the `<wp:wrap*>` child of `<wp:anchor>`.
+     *  Decides whether the frame DISPLACES body flow: `square` /
+     *  `topAndBottom` / `tight` / `through` reserve vertical space (the
+     *  paginator treats the anchor paragraph as that tall), while `none`
+     *  floats over text and reserves nothing. Absent ⇒ unknown (treated
+     *  as non-displacing). */
+    wrap?: "square" | "topAndBottom" | "tight" | "through" | "none";
+    /** `wrapText` side from `<wp:wrapSquare|Tight|Through wrapText="…">` —
+     *  which sides of the frame body text flows on. Default `bothSides`.
+     *  Only meaningful for the displacing wrap modes; drives whether a
+     *  floated image goes `float: left` (text on the right) or `right`. */
+    wrapText?: "bothSides" | "left" | "right" | "largest";
+    /** Text-distance insets — `distT/B/L/R` on `<wp:anchor>`, in EMU. The
+     *  gap Word keeps between the frame and the text wrapping around it;
+     *  rendered as margins on the floated frame. */
+    textDistancesEmu?: {
+        topEmu: number;
+        rightEmu: number;
+        bottomEmu: number;
+        leftEmu: number;
+    };
+    /** What this frame contains. */
+    content: AnchoredContent;
+}
+/**
+ * Where an anchored frame is positioned and which page receives it.
+ *
+ *   - `sectionIndex` decides which section's pages are candidates.
+ *   - `paragraphIndex` (optional) ties the frame to a specific body
+ *     paragraph — useful when `verticalFrom: "paragraph"` so the
+ *     frame floats to whichever page the paragraph paginates onto.
+ *     When absent, the frame is page-relative (lands on the first
+ *     page of its section).
+ *   - `horizontalFrom` / `verticalFrom` mirror OOXML's
+ *     `relativeFromH` / `relativeFromV` enums.
+ */
+export interface AnchorOrigin {
+    sectionIndex: number;
+    paragraphIndex?: number;
+    horizontalFrom: "page" | "margin" | "column";
+    verticalFrom: "page" | "margin" | "paragraph";
+}
+/**
+ * What an AnchoredFrame contains. Closed union — adding a new variant
+ * requires both importer and renderer support.
+ *
+ *   - "picture" — a single image from `rawParts`. The frame's
+ *     widthEmu / heightEmu give the display size; the picture
+ *     stretches to fill (matches Word's default sizing behaviour).
+ *
+ *   - "textbox" — rich body content. Renders recursively via
+ *     `renderBlocks` inside the frame, with `overflow: hidden` so
+ *     text that exceeds the frame's height clips (Word behaviour).
+ *     Optional fill / border / padding paint the textbox chrome.
+ *
+ *   - "shape" — a vector primitive (filled rectangle, ellipse,
+ *     rounded-rect). No text. Used for decorative backgrounds and
+ *     dividers (dotted lines, banner rectangles).
+ *
+ *   - "group" — wraps other frames at NESTED coordinates. The
+ *     children's offsets are interpreted in the group's local
+ *     coordinate system, scaled to fill `widthEmu × heightEmu`.
+ *     Maps to OOXML `<wpg:wgp>`. This is how a single project
+ *     heading carries its rounded-rect frame + atom icon + arrow
+ *     stripe as ONE selectable unit.
+ */
+export type AnchoredContent = {
+    kind: "picture";
+    partPath: string;
+    altText?: string;
+} | {
+    kind: "textbox";
+    body: Block[];
+    fill?: string;
+    border?: {
+        color: string;
+        widthEmu: number;
+        style: "solid" | "dashed" | "dotted" | "double";
+    };
+    padding?: {
+        topEmu: number;
+        rightEmu: number;
+        bottomEmu: number;
+        leftEmu: number;
+    };
+} | {
+    kind: "shape";
+    geometry: "rect" | "ellipse" | "roundedRect" | "line" | "custom";
+    fill?: string;
+    border?: {
+        color: string;
+        widthEmu: number;
+        style: "solid" | "dashed" | "dotted" | "double";
+    };
+    /** Present when `geometry === "custom"`: a DrawingML `<a:custGeom>`
+     *  outline as an SVG path in its own `widthEmu × heightEmu` box,
+     *  rendered as a scaled `<svg><path>`. Absent for preset geometry. */
+    path?: {
+        widthEmu: number;
+        heightEmu: number;
+        d: string;
+    };
+} | {
+    kind: "group";
+    children: AnchoredFrame[];
+    /** Local coordinate system extent (`<a:chExt>`). A child at offset
+     *  `P` maps into the group's rendered box as
+     *  `(P − childCoordOffset) × (size / childCoordSystem)` — the
+     *  extent gives the scale. */
+    childCoordSystemCx: number;
+    childCoordSystemCy: number;
+    /** Local coordinate system ORIGIN (`<a:chOff>`). Child offsets are
+     *  measured from this point, not from 0 — so it must be subtracted
+     *  before scaling, or the children shift by `chOff × scale`.
+     *  Absent ⇒ origin is `(0, 0)` (the common case). */
+    childCoordOffsetX?: number;
+    childCoordOffsetY?: number;
+};

package/dist/doc/types/headersFooters.d.ts

@@ -0,0 +1,7 @@
+export interface HeaderFooterRef {
+    type: "default" | "first" | "even";
+    /** Internal id pointing into `SobreeDocument.rawParts` /
+     *  `relationships`. We store the header/footer body itself as a
+     *  `Block[]` keyed in a side table at the SobreeDocument level. */
+    partId: string;
+}