@docx-editor.dev/core 0.0.1-placeholder → 2.0.1

package/dist/contracts/types.d.ts

@@ -0,0 +1,452 @@
+/**
+ * Shared types for the `@docx-editor.dev/core` contract. Type-only, zero runtime.
+ *
+ * `@docx-editor.dev/core/contracts/types` re-exports this module verbatim, through
+ * `types-barrel.ts`. There is no `@docx-editor.dev/core/types` subpath.
+ */
+/**
+ * The LLM- and JSON-facing address for a piece of a document.
+ *
+ * `paraId` is the 8-hex `w14:paraId`, matched case-insensitively. `search` is a
+ * phrase that must match EXACTLY ONCE inside that paragraph; ambiguous or
+ * missing matches fail with `'ambiguous'` / `'notFound'` rather than falling
+ * back to first-match.
+ *
+ * Offset-based addressing was tried and abandoned: an agent cannot compute a
+ * character offset it has not seen, and offsets do not survive concurrent
+ * edits. Do not reintroduce `{ blockId, offset }`.
+ */
+interface DocAnchor {
+    paraId: string;
+    search?: string;
+    /** Opt-in disambiguation. Omit to require uniqueness. */
+    occurrence?: number;
+}
+/** Structural addressing for content the paraId map cannot reach. */
+interface DocLocation {
+    container: ContainerRef;
+    /** Block indices, descending into tables and content controls. */
+    path: number[];
+    offset?: number;
+}
+/**
+ * Which STORY a location belongs to.
+ *
+ * The body is one container; every header, footer and note is another. A path alone is
+ * ambiguous without it, because block index 0 exists in every story a document has.
+ */
+type ContainerRef = {
+    part: 'body';
+} | {
+    part: 'header' | 'footer';
+    rId: string;
+} | {
+    part: 'footnote' | 'endnote';
+    noteId: number;
+};
+/**
+ * Anything an operation can be pointed at: a paragraph-relative {@link DocAnchor}, a structural
+ * {@link DocLocation}, or a {@link DocRange} spanning two of them.
+ */
+type DocTarget = DocAnchor | DocLocation | DocRange;
+/** A span between two positions. The endpoints may be addressed either way, independently. */
+interface DocRange {
+    from: DocAnchor | DocLocation;
+    to: DocAnchor | DocLocation;
+}
+/**
+ * Every write returns this rather than `boolean`.
+ *
+ * A bare boolean cannot distinguish "no-op" from "target not found" from
+ * "content control is locked", and the editor layer already throws eight
+ * distinct ContentControl error classes that a boolean would flatten.
+ */
+type ExecResult = {
+    ok: true;
+    changed: boolean;
+} | {
+    ok: false;
+    code: ExecErrorCode;
+    reason: string;
+    target?: DocTarget;
+};
+/**
+ * Why a write was refused, as a value to branch on.
+ *
+ * Deliberately finer-grained than a boolean: "no-op", "target not found" and "content control is
+ * locked" are different outcomes, and a caller retrying the first should not retry the third.
+ */
+type ExecErrorCode = 'notFound' | 'ambiguous' | 'locked' | 'bound' | 'typeMismatch' | 'kindMismatch' | 'outOfBounds' | 'unsupported' | 'invalidArgs';
+/**
+ * A parsed .docx.
+ *
+ * NOT JSON-round-trippable: it holds `Map`s and `Date`s, plus an internal
+ * side-table of verbatim XML used for lossless round-tripping. Use `toJSON` /
+ * `fromJSON` before sending it over JSON-RPC or handing it to a model.
+ */
+interface DocxDocument {
+    readonly body: DocumentBody;
+    readonly styles: StyleDefinitions;
+    readonly theme?: Theme;
+    readonly comments: readonly DocComment[];
+    readonly revisions: readonly Revision[];
+}
+/** The main story: its blocks in reading order, plus the sections derived from them. */
+interface DocumentBody {
+    readonly content: readonly Block[];
+    /**
+     * Derived, not stored: recomputed on read from section-break markers and
+     * section inheritance. Never treat it as a spreadable field.
+     */
+    readonly sections: readonly Section[];
+}
+/** The JSON-safe projection of a document. */
+interface DocxDocumentJSON {
+    readonly [key: string]: unknown;
+}
+/** One section: the page it lays out on, and the header/footer stories it declares. */
+interface Section {
+    readonly properties: SectionProperties;
+    readonly headers: HeaderFooterSet;
+    readonly footers: HeaderFooterSet;
+}
+/**
+ * A section's three header (or footer) variants, each a relationship id.
+ *
+ * All optional: a variant a section does not declare inherits the previous section's, and one
+ * absent everywhere means the document simply has none.
+ */
+interface HeaderFooterSet {
+    readonly default?: string;
+    readonly first?: string;
+    readonly even?: string;
+}
+/** Anything that can sit at block level in a story. Discriminate on `kind`. */
+type Block = Paragraph | Table | ContentControl;
+/** One paragraph: its runs, the style it names, and its list membership. */
+interface Paragraph {
+    readonly kind: 'paragraph';
+    /** `w14:paraId`. The stable handle `DocAnchor` addresses. */
+    readonly paraId?: string;
+    readonly runs: readonly Run[];
+    readonly styleId?: string;
+    readonly numbering?: NumberingRef;
+}
+/** A stretch of text sharing one set of character properties. */
+interface Run {
+    readonly text: string;
+    readonly formatting?: RunFormatting;
+    /** Set when the run carries a tracked change. Unique only within its part. */
+    readonly revisionId?: number;
+}
+/**
+ * Character formatting, and — at selection level — the paragraph properties a toolbar reads
+ * alongside it.
+ *
+ * One type serves both roles so a toolbar reads alignment, style and script state from the same
+ * object as bold and italic. On a {@link Run} the selection-level fields stay absent: a run has
+ * no alignment or paragraph style of its own.
+ */
+interface RunFormatting {
+    readonly bold?: boolean;
+    readonly italic?: boolean;
+    readonly underline?: boolean;
+    readonly strike?: boolean;
+    readonly color?: ColorValue;
+    readonly highlight?: string;
+    readonly fontFamily?: string;
+    readonly fontSizePt?: number;
+    readonly superscript?: boolean;
+    readonly subscript?: boolean;
+    /** Paragraph alignment at the selection. `both` is OOXML's spelling of justify. */
+    readonly alignment?: 'left' | 'center' | 'right' | 'both';
+    /** Paragraph style id (`w:pStyle`) at the selection. */
+    readonly styleId?: string;
+    /**
+     * Line spacing at the selection, in the unit its rule implies — LINES for `multiple`,
+     * points for `exact` and `atLeast`. The same vocabulary `setLineSpacing` takes, so a
+     * control can show what it reads and send back what it shows. Absent when the
+     * selection's paragraphs disagree or state no line spacing.
+     */
+    readonly lineSpacing?: {
+        readonly rule: 'multiple' | 'exact' | 'atLeast';
+        readonly value: number;
+    };
+    /** Space above and below the paragraph at the selection, in points. */
+    readonly spaceBeforePt?: number;
+    readonly spaceAfterPt?: number;
+    /**
+     * The EFFECTIVE paragraph indent at the selection — cascade and numbering merge
+     * included, so a numbered item that authors no `w:ind` reports the indent its list
+     * definition gives it. Absent when nothing is loaded, or when the selection is inside a
+     * table (see {@link IndentFormatting}).
+     */
+    readonly indent?: IndentFormatting;
+}
+/**
+ * Indent at the selection, in twips.
+ *
+ * Unlike every other field here, this does NOT go absent when the selection's paragraphs
+ * disagree. A ruler has to draw its handles somewhere, and Word draws them at the FIRST
+ * selected paragraph's values — Select All is the commonest indent gesture, and hiding the
+ * handles for it would be worse than showing one paragraph's truth. The values are
+ * therefore always the first touched paragraph's, and {@link mixed} records per field
+ * whether the rest agree.
+ *
+ * `firstLine` is ONE SIGNED offset: negative is a hanging indent. OOXML spells it as two
+ * mutually exclusive attributes and this collapses them hanging-wins (§17.3.1.12), which
+ * is the model Word itself keeps.
+ *
+ * Absent inside a table. The value would be correct there, but it is measured from the
+ * cell's content edge while a ruler is drawn against the page's margin, and the ruler does
+ * not know the cell.
+ */
+interface IndentFormatting {
+    /** Left indent, signed. Negative pulls text into the margin, as Word allows. */
+    readonly left: number;
+    /** Right indent, signed. */
+    readonly right: number;
+    /** First-line offset from {@link left}, signed. Negative is a hanging indent. */
+    readonly firstLine: number;
+    /** Per field, whether the selection's paragraphs disagree about it. */
+    readonly mixed: {
+        readonly left: boolean;
+        readonly right: boolean;
+        readonly firstLine: boolean;
+    };
+}
+/** A table: its rows, and the table style they resolve through. */
+interface Table {
+    readonly kind: 'table';
+    readonly rows: readonly TableRow[];
+    readonly styleId?: string;
+}
+/** One table row. Cell count may vary between rows: `colSpan` and vertical merges reshape it. */
+interface TableRow {
+    readonly cells: readonly TableCell[];
+}
+/**
+ * One cell. Its `content` is ordinary blocks, so a cell may hold paragraphs, nested tables and
+ * content controls alike.
+ */
+interface TableCell {
+    readonly content: readonly Block[];
+    /** Vertical merge span. Absent means 1. */
+    readonly rowSpan?: number;
+    /** `w:gridSpan`. Absent means 1. */
+    readonly colSpan?: number;
+}
+/** Structured document tag (`w:sdt`). */
+interface ContentControl {
+    readonly kind: 'contentControl';
+    readonly id: string;
+    readonly tag?: string;
+    readonly alias?: string;
+    readonly controlType: ContentControlType;
+    readonly locked?: boolean;
+    readonly content: readonly Block[];
+}
+/** Which kind of control a `w:sdt` is, and therefore what a value written into it must be. */
+type ContentControlType = 'richText' | 'plainText' | 'checkbox' | 'dropdown' | 'comboBox' | 'date' | 'picture' | 'repeatingSection';
+/**
+ * Narrows a content-control query. Fields combine with AND; an empty filter matches every
+ * control.
+ */
+interface ContentControlFilter {
+    readonly tag?: string;
+    readonly alias?: string;
+    readonly controlType?: ContentControlType;
+}
+/**
+ * A position in one story: a paragraph and a UTF-16 offset inside it.
+ *
+ * The same offset space the ops and the caret use, so an anchor read here can be handed
+ * straight back to a selection without re-deriving anything.
+ */
+interface DocAnchorRange {
+    /** Canonical part name of the story the range lives in, e.g. `/word/document.xml`. */
+    readonly part: string;
+    readonly startParagraphId: string;
+    readonly startOffset: number;
+    /** May sit in a later paragraph: the range markers are independent elements. */
+    readonly endParagraphId: string;
+    readonly endOffset: number;
+}
+/**
+ * One comment or reply, as `comments.xml` records it.
+ *
+ * A reply is a comment with a `parentId`; OOXML gives replies no separate element, so the thread
+ * is reconstructed from that link rather than from nesting.
+ */
+interface DocComment {
+    readonly id: string;
+    readonly author: string;
+    /**
+     * OPTIONAL, because `CT_Comment` makes `@w:date` optional and files omit it. A comment
+     * with no date is a comment, not a defect, and fabricating one is a content change.
+     */
+    readonly date?: string;
+    readonly text: string;
+    readonly parentId?: string;
+    readonly resolved?: boolean;
+    /**
+     * Where the comment is anchored, absent when the file gave it no usable range.
+     *
+     * A comment lives in `comments.xml` and is placed by markers in a STORY, so the story is
+     * part of the address: a comment anchored in a header belongs to a part the body never saw.
+     */
+    readonly anchor?: DocAnchorRange;
+    /**
+     * True when the file gave this comment no usable range — a reference with no markers, or a
+     * start with no end. Reported rather than dropped: a reviewer's remark vanishing silently
+     * is worse than one that says it lost its text.
+     */
+    readonly orphaned?: boolean;
+}
+/**
+ * What kind of decision a revision represents.
+ *
+ * Wider than insert/delete/format, and it has to be. `w:moveFrom`/`w:moveTo` are not a
+ * deletion and an insertion — resolving one half alone duplicates or loses the content;
+ * `w:pPr/w:rPr/w:ins|w:del` decorates no characters at all and merges paragraphs when
+ * resolved; a row or cell revision is structural. A reviewer shown only three kinds is a
+ * reviewer who never learns about the rest.
+ */
+type RevisionType = 'insert' | 'delete'
+/** A deletion and an insertion that are one edit: text typed over a selection. */
+ | 'replace' | 'moveFrom' | 'moveTo'
+/** `w:rPrChange` / `w:pPrChange` — the words are unchanged, their formatting is not. */
+ | 'format'
+/** `w:pPr/w:rPr/w:ins|w:del` — a paragraph split or merge. */
+ | 'paragraphMark'
+/** A row, cell, section or grid revision. */
+ | 'structural';
+/**
+ * One tracked change.
+ *
+ * Addressing needs BOTH `id` and `part`: `@w:id` is unique only within a part, so an id alone
+ * names two revisions in any package that has a header or a comments part.
+ */
+interface Revision {
+    /** Numeric, and unique only WITHIN a part. Pair with `part` to address one. */
+    readonly id: number;
+    readonly type: RevisionType;
+    readonly author: string;
+    /**
+     * OPTIONAL. `CT_TrackChange` requires `@w:id` and `@w:author` and makes `@w:date`
+     * optional, and producers that omit it are ordinary. Requiring it here forced either a
+     * fabricated date — a content change — or dropping the revision from the list.
+     */
+    readonly date?: string;
+    /**
+     * REQUIRED, and a canonical PART NAME rather than a three-value enum.
+     *
+     * `@w:id` is unique only within a part, so an address without one names two revisions in a
+     * package that has both. The enum could not express the parts revisions actually occur in:
+     * `header3.xml`, `footer1.xml`, `comments.xml`, and `styles.xml`, which carries
+     * `w:pPrChange` inside style definitions with ids that collide with `document.xml`.
+     */
+    readonly part: string;
+}
+/** `w:sectPr`: the page a section lays out on. Twips throughout, as the file stores them. */
+interface SectionProperties {
+    readonly pageSize: {
+        widthTwips: number;
+        heightTwips: number;
+    };
+    readonly margins: PageMargins;
+    readonly columns?: {
+        count: number;
+        gapTwips: number;
+    };
+    /** `w:titlePg` — whether the section's first page takes the `first` header/footer variant. */
+    readonly titlePage?: boolean;
+}
+/** Page margins in twips. */
+interface PageMargins {
+    readonly topTwips: number;
+    readonly rightTwips: number;
+    readonly bottomTwips: number;
+    readonly leftTwips: number;
+}
+/**
+ * `styles.xml`, split by the three style families that address separately.
+ *
+ * Keyed by style ID rather than by the name a reader sees, because the ID is what a paragraph or
+ * run actually references.
+ */
+interface StyleDefinitions {
+    readonly paragraph: ReadonlyMap<string, StyleDefinition>;
+    readonly character: ReadonlyMap<string, StyleDefinition>;
+    readonly table: ReadonlyMap<string, StyleDefinition>;
+}
+/** One style: the ID content references, the name a reader sees, and its inheritance link. */
+interface StyleDefinition {
+    readonly id: string;
+    readonly name: string;
+    /** `w:basedOn` — the style this one inherits from. Absent at the root of a chain. */
+    readonly basedOn?: string;
+}
+/** A paragraph's list membership: which `numbering.xml` definition, and at which level. */
+interface NumberingRef {
+    readonly numId: string;
+    /** Zero-based. OOXML numbering has nine levels, 0 through 8. */
+    readonly level: number;
+}
+/**
+ * A colour as the FILE expresses it, not as a resolved RGB string.
+ *
+ * A theme colour stays a theme reference — slot plus tint or shade — so that changing the theme
+ * repaints the document the way Word does. Flattening to hex at read time would freeze the
+ * resolved value and break that link. `auto` is Word's "let the renderer decide", usually black
+ * on white.
+ */
+type ColorValue = {
+    readonly kind: 'hex';
+    readonly value: string;
+} | {
+    readonly kind: 'theme';
+    readonly slot: string;
+    readonly tint?: number;
+    readonly shade?: number;
+} | {
+    readonly kind: 'auto';
+};
+/** `theme1.xml` — what a {@link ColorValue} of kind `theme` resolves against. */
+interface Theme {
+    readonly colorScheme: ThemeColorScheme;
+    readonly fontScheme?: Record<string, string>;
+}
+/** Theme colour slots (`accent1`, `dk1`, `lt2`, …) to hex. */
+type ThemeColorScheme = Readonly<Record<string, string>>;
+/** A watermark, which OOXML expresses as either text or an image — never both meaningfully. */
+interface Watermark {
+    readonly text?: string;
+    readonly imageData?: Uint8Array;
+}
+/** A size in EMUs, the unit DrawingML stores extents in. 914400 EMU = 1 inch. */
+interface Extent {
+    readonly widthEmu: number;
+    readonly heightEmu: number;
+}
+/** A font the document names, and whether its bytes travel inside the package. */
+interface FontDefinition {
+    readonly family: string;
+    readonly embedded: boolean;
+}
+/** An axis-aligned rectangle in points, the unit layout works in throughout. */
+interface Rect {
+    readonly x: number;
+    readonly y: number;
+    readonly width: number;
+    readonly height: number;
+}
+/** A position in points. */
+interface Point {
+    readonly x: number;
+    readonly y: number;
+}
+/** What every subscription returns. Calling it twice is safe. */
+type Unsubscribe = () => void;
+
+export type { Block, ColorValue, ContainerRef, ContentControl, ContentControlFilter, ContentControlType, DocAnchor, DocAnchorRange, DocComment, DocLocation, DocRange, DocTarget, DocumentBody, DocxDocument, DocxDocumentJSON, ExecErrorCode, ExecResult, Extent, FontDefinition, HeaderFooterSet, IndentFormatting, NumberingRef, PageMargins, Paragraph, Point, Rect, Revision, RevisionType, Run, RunFormatting, Section, SectionProperties, StyleDefinition, StyleDefinitions, Table, TableCell, TableRow, Theme, ThemeColorScheme, Unsubscribe, Watermark };