@sobree/core 0.1.14 → 0.1.16

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

@@ -0,0 +1,8 @@
+import { InlineRun, Paragraph, ParagraphProperties, SectionBreak } from '../types';
+/** A paragraph with the given runs and properties (both optional). */
+export declare function paragraph(runs?: InlineRun[], properties?: ParagraphProperties): Paragraph;
+/** Heading paragraph (`Heading{level}` style, level clamped to 1..6). */
+export declare function heading(level: number, runs?: InlineRun[], properties?: ParagraphProperties): Paragraph;
+/** A section break that switches to `toSectionIndex` in the document's
+ *  `sections` array for the content that follows. */
+export declare function sectionBreak(toSectionIndex: number): SectionBreak;

package/dist/doc/{builders.d.ts → builders/document.d.ts}

@@ -1,20 +1,9 @@
-import { Block, HeaderFooterRef, InlineRun, NamedStyle, PageMargins, PageSize, Paragraph, ParagraphProperties, RunProperties, SectionProperties, SobreeDocument, Table, TextRun } from './types';
+import { Block, HeaderFooterRef, NamedStyle, PageMargins, PageSize, Paragraph, SectionProperties, SobreeDocument, Table } from '../types';
 /** A new, blank document with an A4 portrait section and the standard styles. */
 export declare function emptyDocument(): SobreeDocument;
 export declare function defaultSection(): SectionProperties;
 export declare function defaultPageSize(): PageSize;
 export declare function defaultMargins(): PageMargins;
-/** A paragraph with no runs and no properties beyond the defaults. */
-export declare function paragraph(runs?: InlineRun[], properties?: ParagraphProperties): Paragraph;
-/** Heading paragraph (`Heading{level}` style, level clamped to 1..6). */
-export declare function heading(level: number, runs?: InlineRun[], extra?: ParagraphProperties): Paragraph;
-/** Plain text run with optional formatting. */
-export declare function text(value: string, properties?: RunProperties): TextRun;
-/** Convenience: emphasised (bold + italic) text run. */
-export declare function emphasis(value: string, properties?: RunProperties): TextRun;
-export declare function strong(value: string, properties?: RunProperties): TextRun;
-export declare function softBreak(): InlineRun;
-export declare function pageBreak(): InlineRun;
 /** Default Word styles every doc declares so headings render correctly.
  *
  *  Carries WORD-HARDCODED-DEFAULT typography — i.e. what Word uses

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

@@ -0,0 +1,26 @@
+/**
+ * Constructors for AST nodes. Two reasons these exist as helpers instead
+ * of object literals at every call site:
+ *   1. Defaults — A4 paper, an empty cell's placeholder paragraph, equal
+ *      column widths — without sprinkling magic numbers into caller code.
+ *   2. Future schema migration — when a new required field is added, all
+ *      construction goes through here and the migration is one diff.
+ *
+ * Conventions across the layer:
+ *   - The factory is named for the node it builds (`text`, `table`,
+ *     `tableCell`, `hyperlink`, `sectionBreak`).
+ *   - Required content is positional; optional formatting is a trailing
+ *     `properties` argument (a leaf's `RunProperties`, a container's
+ *     `*Properties`). Many-field nodes (`image`, `table`, `namedStyle`)
+ *     take a single trailing options object instead.
+ *   - Measurements keep their native OOXML unit, suffixed (`widthEmu`,
+ *     `…Twips`), matching the AST.
+ *
+ * Organised by node category: document / block / inline / table / style.
+ */
+export { appendBlock, defaultMargins, defaultPageSize, defaultSection, defaultStyles, emptyDocument, isParagraph, isTable, makeHeaderFooterRef, } from './document';
+export { heading, paragraph, sectionBreak } from './block';
+export { columnBreak, commentRef, emphasis, field, footnoteRef, hyperlink, image, type ImageOptions, pageBreak, softBreak, strong, tab, text, } from './inline';
+export { type CellProperties, type TableOptions, table, tableCell, tableRow } from './table';
+export { type NamedStyleOptions, namedStyle } from './style';
+export { type NumberingLevelOptions, bulletDefinition, numberingDefinition, numberingLevel, orderedDefinition, } from './numbering';

package/dist/doc/builders/inline.d.ts

@@ -0,0 +1,38 @@
+import { BreakRun, CommentRefRun, DrawingRun, FieldRun, FootnoteRefRun, HyperlinkRun, InlineRun, RunProperties, TabRun, TextRun } from '../types';
+/** Plain text run with optional formatting. */
+export declare function text(value: string, properties?: RunProperties): TextRun;
+/** Convenience: italic text run. */
+export declare function emphasis(value: string, properties?: RunProperties): TextRun;
+/** Convenience: bold text run. */
+export declare function strong(value: string, properties?: RunProperties): TextRun;
+/** Soft line break inside a paragraph (Shift-Enter). */
+export declare function softBreak(): BreakRun;
+/** Explicit page break. */
+export declare function pageBreak(): BreakRun;
+/** Column break (advances to the next column in a multi-column section). */
+export declare function columnBreak(): BreakRun;
+/** A tab character — advances to the next tab stop. */
+export declare function tab(properties?: RunProperties): TabRun;
+/** A hyperlink wrapping inline children. `href` is an external URL or an
+ *  internal anchor id (`#bookmark`). */
+export declare function hyperlink(href: string, children: InlineRun[], properties?: RunProperties): HyperlinkRun;
+/** A field run (`PAGE`, `NUMPAGES`, `DATE`, …). `cached` is the preview
+ *  text shown until a viewer recalculates the field. */
+export declare function field(instruction: string, cached?: string, properties?: RunProperties): FieldRun;
+/** Options for {@link image}. `partPath` references a binary in the
+ *  document's `rawParts`; the caller is responsible for registering the
+ *  bytes there (or use the editor's `insertImage`, which does both). */
+export interface ImageOptions {
+    widthEmu: number;
+    heightEmu: number;
+    altText?: string;
+    /** Layout mode — defaults to `"inline"` (flows like a tall character). */
+    placement?: DrawingRun["placement"];
+    verticalAlign?: DrawingRun["verticalAlign"];
+}
+/** An image / drawing run referencing a part in `rawParts`. */
+export declare function image(partPath: string, opts: ImageOptions): DrawingRun;
+/** A footnote reference — `id` keys into `SobreeDocument.footnotes`. */
+export declare function footnoteRef(id: number, properties?: RunProperties): FootnoteRefRun;
+/** A comment reference — `id` keys into `SobreeDocument.comments`. */
+export declare function commentRef(id: number, properties?: RunProperties): CommentRefRun;

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

@@ -0,0 +1,19 @@
+import { NumberingDefinition, NumberingLevel, ParagraphIndent, RunProperties } from '../types';
+export interface NumberingLevelOptions {
+    restart?: number;
+    paragraphIndent?: ParagraphIndent;
+    /** Run properties for the marker glyph/number itself. */
+    runDefaults?: RunProperties;
+}
+/** One indent level of a list. `format` is `bullet` / `decimal` /
+ *  `lowerRoman` / `upperLetter` / …; `text` is the marker template
+ *  (`%1.`, `(%1)`, or a literal bullet glyph). */
+export declare function numberingLevel(level: number, format: string, text: string, options?: NumberingLevelOptions): NumberingLevel;
+/** A numbering definition: a `numId` (referenced from paragraphs) plus its
+ *  level formats. */
+export declare function numberingDefinition(numId: number, levels: NumberingLevel[]): NumberingDefinition;
+/** A bullet list of `levels` levels (default 3), cycling • ◦ ▪. */
+export declare function bulletDefinition(numId: number, levels?: number): NumberingDefinition;
+/** An ordered list of `levels` levels (default 3), each `%1.` decimal,
+ *  restarting at the level above. */
+export declare function orderedDefinition(numId: number, levels?: number): NumberingDefinition;

package/dist/doc/builders/style.d.ts

@@ -0,0 +1,7 @@
+import { NamedStyle } from '../types';
+/** Everything on {@link NamedStyle} except `id` (the positional argument);
+ *  `type` defaults to `"paragraph"` and `displayName` to the id. */
+export type NamedStyleOptions = Partial<Omit<NamedStyle, "id">>;
+/** A named style. `id` is required; `type` defaults to `"paragraph"` and
+ *  `displayName` to `id` when not given. */
+export declare function namedStyle(id: string, options?: NamedStyleOptions): NamedStyle;

package/dist/doc/builders/table.d.ts

@@ -0,0 +1,20 @@
+import { Block, Table, TableCell, TableProperties, TableRow } from '../types';
+/** A cell's properties — everything on {@link TableCell} except `content`
+ *  (which is the positional argument). */
+export type CellProperties = Partial<Omit<TableCell, "content">>;
+/** A table cell. `content` defaults to a single empty paragraph (Word
+ *  requires every cell to hold at least one paragraph). */
+export declare function tableCell(content?: Block[], properties?: CellProperties): TableCell;
+/** A table row. */
+export declare function tableRow(cells: TableCell[], opts?: {
+    isHeader?: boolean;
+}): TableRow;
+export interface TableOptions {
+    /** Column widths in twips (length = column count). Derived as equal
+     *  columns from {@link DEFAULT_TABLE_WIDTH_TWIPS} when omitted. */
+    grid?: number[];
+    properties?: TableProperties;
+}
+/** A table. The column `grid` is taken from `opts.grid`, else derived as
+ *  equal-width columns from the widest row's column count. */
+export declare function table(rows: TableRow[], opts?: TableOptions): Table;

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

@@ -1,12 +1,11 @@
 /**
- * Formatting value-types: borders, shading, and table-style conditional
- * formatting.
+ * Visual formatting primitives: borders, shading, and cell spacing.
  *
- * Split out from `types.ts` (the core AST module) as a dependency-free
- * LEAF — none of these reference the recursive `Block` document graph, so
- * they import nothing from `types.ts`. Keeping them here avoids a circular
- * dependency: `types.ts` imports + re-exports them, so consumers still get
- * every AST type from `./types`.
+ * Low-level value-types shared across the AST — paragraphs, runs, and
+ * tables all paint with these. A dependency-free LEAF: none reference the
+ * recursive `Block` document graph, so keeping them here (out of
+ * `types.ts`) avoids a circular dependency. `types.ts` imports +
+ * re-exports them, so consumers still get every AST type from `./types`.
  */
 export interface BorderSpec {
     style: "single" | "double" | "dashed" | "dotted" | "thick" | "none";
@@ -25,6 +24,8 @@ export interface Shading {
     /** Pattern foreground `#rrggbb` or `auto`. */
     color?: string;
 }
+/** A table's outer edges plus the inside-horizontal / inside-vertical
+ *  separators (`<w:tblBorders>`). */
 export interface TableBorders {
     top?: BorderSpec;
     right?: BorderSpec;
@@ -33,6 +34,7 @@ export interface TableBorders {
     insideH?: BorderSpec;
     insideV?: BorderSpec;
 }
+/** A single cell's four edges (`<w:tcBorders>`). */
 export interface TableCellBorders {
     top?: BorderSpec;
     right?: BorderSpec;
@@ -47,45 +49,3 @@ export interface TableCellMargins {
     bottomTwips?: number;
     leftTwips?: number;
 }
-/** `<w:tblLook>` flags. A flag absent ⇒ that conditional format is OFF. */
-export interface TableLook {
-    firstRow?: boolean;
-    lastRow?: boolean;
-    firstColumn?: boolean;
-    lastColumn?: boolean;
-    /** Row (horizontal) banding active. */
-    hBand?: boolean;
-    /** Column (vertical) banding active. */
-    vBand?: boolean;
-}
-/**
- * A table style's conditional-format regions (`<w:tblStylePr w:type>`).
- * Each names a slice of the table whose cells get extra formatting when
- * the table's `<w:tblLook>` enables it. Resolution precedence (low→high,
- * ECMA-376 §17.7.6): wholeTable → vBands → hBands → first/last column →
- * first/last row → corner cells, then direct cell formatting wins.
- */
-export type TableConditionalType = "firstRow" | "lastRow" | "firstCol" | "lastCol" | "band1Horz" | "band2Horz" | "band1Vert" | "band2Vert" | "nwCell" | "neCell" | "swCell" | "seCell";
-/** The formatting one region (or the whole-table base) contributes. */
-export interface TableStyleCellFormat {
-    shading?: Shading;
-    borders?: TableCellBorders;
-}
-/**
- * A `<w:style w:type="table">` definition: whole-table base formatting +
- * per-region conditional formatting + band sizes. Resolved per cell at
- * render time against the table's `look`.
- */
-export interface TableStyleDefinition {
-    /** Whole-table borders (`<w:tblBorders>` — incl. `insideH`/`insideV`). */
-    borders?: TableBorders;
-    /** Whole-table base cell shading. */
-    shading?: Shading;
-    /** Rows per horizontal band (`<w:tblStyleRowBandSize>`, default 1). */
-    rowBandSize?: number;
-    /** Columns per vertical band (`<w:tblStyleColBandSize>`, default 1). */
-    colBandSize?: number;
-    /** Whole-table default cell padding (`<w:tblCellMar>` in the style). */
-    cellMargins?: TableCellMargins;
-    conditional?: Partial<Record<TableConditionalType, TableStyleCellFormat>>;
-}

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

@@ -0,0 +1,43 @@
+import { Shading, TableBorders, TableCellBorders, TableCellMargins } from './formatting.types';
+/** `<w:tblLook>` flags. A flag absent ⇒ that conditional format is OFF. */
+export interface TableLook {
+    firstRow?: boolean;
+    lastRow?: boolean;
+    firstColumn?: boolean;
+    lastColumn?: boolean;
+    /** Row (horizontal) banding active. */
+    hBand?: boolean;
+    /** Column (vertical) banding active. */
+    vBand?: boolean;
+}
+/**
+ * A table style's conditional-format regions (`<w:tblStylePr w:type>`).
+ * Each names a slice of the table whose cells get extra formatting when
+ * the table's `<w:tblLook>` enables it. Resolution precedence (low→high,
+ * ECMA-376 §17.7.6): wholeTable → vBands → hBands → first/last column →
+ * first/last row → corner cells, then direct cell formatting wins.
+ */
+export type TableConditionalType = "firstRow" | "lastRow" | "firstCol" | "lastCol" | "band1Horz" | "band2Horz" | "band1Vert" | "band2Vert" | "nwCell" | "neCell" | "swCell" | "seCell";
+/** The formatting one region (or the whole-table base) contributes. */
+export interface TableStyleCellFormat {
+    shading?: Shading;
+    borders?: TableCellBorders;
+}
+/**
+ * A `<w:style w:type="table">` definition: whole-table base formatting +
+ * per-region conditional formatting + band sizes. Resolved per cell at
+ * render time against the table's `look`.
+ */
+export interface TableStyleDefinition {
+    /** Whole-table borders (`<w:tblBorders>` — incl. `insideH`/`insideV`). */
+    borders?: TableBorders;
+    /** Whole-table base cell shading. */
+    shading?: Shading;
+    /** Rows per horizontal band (`<w:tblStyleRowBandSize>`, default 1). */
+    rowBandSize?: number;
+    /** Columns per vertical band (`<w:tblStyleColBandSize>`, default 1). */
+    colBandSize?: number;
+    /** Whole-table default cell padding (`<w:tblCellMar>` in the style). */
+    cellMargins?: TableCellMargins;
+    conditional?: Partial<Record<TableConditionalType, TableStyleCellFormat>>;
+}

package/dist/doc/types.d.ts

@@ -1,6 +1,8 @@
-import { BorderSpec, Shading, TableBorders, TableCellBorders, TableCellMargins, TableLook, TableStyleDefinition } from './formatting.types';
+import { BorderSpec, Shading, TableBorders, TableCellBorders, TableCellMargins } from './formatting.types';
+import { TableLook, TableStyleDefinition } from './tableStyle.types';
 import { FontDeclaration as _FontDeclaration } from '../fonts/types';
-export type { BorderSpec, Shading, TableBorders, TableCellBorders, TableCellMargins, TableConditionalType, TableLook, TableStyleCellFormat, TableStyleDefinition, } from './formatting.types';
+export type { BorderSpec, Shading, TableBorders, TableCellBorders, TableCellMargins, } from './formatting.types';
+export type { TableConditionalType, TableLook, TableStyleCellFormat, TableStyleDefinition, } from './tableStyle.types';
 export interface SobreeDocument {
     /** Top-level body content, in document order. */
     body: Block[];

package/dist/editor/index.d.ts

@@ -6,14 +6,17 @@ import { EmbedFontFaces, EmbedFontOptions } from '../fonts';
 import { History } from '../history';
 import { BlockRegistry } from './internal/blockRegistry';
 import { countBlocks } from './internal/positionMap';
+import { EditorNumbering } from './numbering';
+import { EditorSections } from './sections';
 import { EditorSelection } from './selection';
+import { EditorStyles } from './styles';
 import { EditorTable } from './table';
-import { ApiRangeType, BlockInfo, ChangePayload, CommandBus, CommandDefinition, CommandSnapshot, EditorEvent, EditorEventPayload, EditorOptions, KeyDownPayload, OutlineItem, ParagraphPropertiesPatch, RevisionSpan, SelectionPayload, TrackChangesState, Unsubscribe, WrapTag } from './types';
+import { ApiRangeType, BlockInfo, ChangePayload, CommandBus, CommandDefinition, CommandSnapshot, EditorEvent, EditorEventPayload, EditorOptions, KeyDownPayload, NamedStylePatch, OutlineItem, ParagraphPropertiesPatch, RevisionSpan, SectionPropertiesPatch, SelectionPayload, TrackChangesState, Unsubscribe, WrapTag } from './types';
 import * as Y from "yjs";
 export { EditorCommands } from './commands';
 export { EditorSelection } from './selection';
 export type { BlockRef, EditError, EditResult, InlinePosition, Selection };
-export type { ApiRangeType, BlockInfo, ChangePayload, CommandBus, CommandDefinition, CommandSnapshot, EditorEvent, EditorEventPayload, EditorOptions, KeyDownPayload, OutlineItem, ParagraphPropertiesPatch, RevisionSpan, SelectionPayload, TrackChangesState, Unsubscribe, WrapTag, };
+export type { ApiRangeType, BlockInfo, ChangePayload, CommandBus, CommandDefinition, CommandSnapshot, EditorEvent, EditorEventPayload, EditorOptions, KeyDownPayload, NamedStylePatch, OutlineItem, ParagraphPropertiesPatch, RevisionSpan, SectionPropertiesPatch, SelectionPayload, TrackChangesState, Unsubscribe, WrapTag, };
 export type { CellRef, InsertAt, InsertColumnOpts, InsertRowOpts, MergeCellsOpts, } from './types';
 export { runsLength } from '../doc/runs';
 export type { RunPropertiesPatch };
@@ -42,6 +45,27 @@ export declare class Editor {
      * and inherits optimistic-lock checking via `replaceBlock`.
      */
     readonly table: EditorTable;
+    /**
+     * Section-level edit operations — page size / margins, columns,
+     * header/footer references, vertical alignment. Grouped here (rather
+     * than as flat `Editor` methods) so the facade stays thin as the
+     * edit-op surface grows. Every method returns an `EditResult`.
+     */
+    readonly sections: EditorSections;
+    /**
+     * Named-style edit operations — define / update / remove the style
+     * definitions content resolves through. Applying a `styleId` to content
+     * is `applyBlockProperties` / `applyRunProperties`; this manages the
+     * definitions themselves. Every method returns an `EditResult`.
+     */
+    readonly styles: EditorStyles;
+    /**
+     * Numbering / list-definition edit operations — define / update / remove
+     * the list formats paragraphs reference by `numId`. Pointing a paragraph
+     * at a list is `applyBlockProperties`; this manages the definitions.
+     * Every method returns an `EditResult`.
+     */
+    readonly numbering: EditorNumbering;
     /**
      * Named-command registry — the coordination point between plugins.
      * Plugins register commands on attach and unregister on detach;

package/dist/editor/internal/mutations.d.ts

@@ -1,6 +1,6 @@
 import { RunPropertiesPatch } from '../../doc/runs';
-import { Block, ParagraphProperties, RunProperties, SectionProperties, SobreeDocument } from '../../doc/types';
-import { ParagraphPropertiesPatch, WrapTag } from '../types';
+import { Block, NamedStyle, ParagraphProperties, RunProperties, SectionProperties, SobreeDocument } from '../../doc/types';
+import { NamedStylePatch, ParagraphPropertiesPatch, SectionPropertiesPatch, WrapTag } from '../types';
 /**
  * One registry-level operation produced by a mutation. The caller
  * applies these to the BlockRegistry after committing the new doc:
@@ -49,6 +49,19 @@ export declare function mergeSectionsAcross(sections: readonly SectionProperties
  * overwrites.
  */
 export declare function mergeParagraphProps(prev: ParagraphProperties, patch: ParagraphPropertiesPatch): ParagraphProperties;
+/**
+ * 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 {@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;
 /**
  * Map a semantic "wrap" tag to the run-property patch that achieves it.
  * Same mapping the browser editor uses for toolbar buttons.

package/dist/editor/numbering.d.ts

@@ -0,0 +1,14 @@
+import { EditResult } from '../doc/api';
+import { NumberingDefinition, NumberingLevel } from '../doc/types';
+import { EditorContext } from './context';
+export declare class EditorNumbering {
+    private readonly ctx;
+    constructor(ctx: EditorContext);
+    /** Add a new numbering definition. Fails if `def.numId` already exists. */
+    define(def: NumberingDefinition): EditResult<void>;
+    /** Replace the levels of the definition with `numId`. Fails if missing. */
+    update(numId: number, levels: NumberingLevel[]): EditResult<void>;
+    /** Remove the definition with `numId`. Fails if missing. Paragraphs that
+     *  still reference it render without a marker. */
+    remove(numId: number): EditResult<void>;
+}

package/dist/editor/sections.d.ts

@@ -0,0 +1,15 @@
+import { EditResult } from '../doc/api';
+import { EditorContext } from './context';
+import { SectionPropertiesPatch } from './types';
+export declare class EditorSections {
+    private readonly ctx;
+    constructor(ctx: EditorContext);
+    /**
+     * Merge a patch into the section at `index`: page size / margins,
+     * columns, header/footer refs, vertical alignment. `pageSize` /
+     * `pageMargins` are field-merged (a partial stays valid); other fields
+     * replace wholesale, and an explicit `undefined` clears an optional one.
+     * Re-renders page geometry; undo-integrated.
+     */
+    setProperties(index: number, patch: SectionPropertiesPatch): EditResult<void>;
+}

package/dist/editor/styles.d.ts

@@ -0,0 +1,16 @@
+import { EditResult } from '../doc/api';
+import { NamedStyle } from '../doc/types';
+import { EditorContext } from './context';
+import { NamedStylePatch } from './types';
+export declare class EditorStyles {
+    private readonly ctx;
+    constructor(ctx: EditorContext);
+    /** Add a new style. Fails if a style with the same `id` already exists
+     *  (use {@link update} to change one). */
+    define(style: NamedStyle): EditResult<void>;
+    /** Merge a patch into the style with `id`. Fails if no such style. */
+    update(id: string, patch: NamedStylePatch): EditResult<void>;
+    /** Remove the style with `id`. Fails if no such style. Content that
+     *  still references it falls back to the cascade's defaults. */
+    remove(id: string): EditResult<void>;
+}

package/dist/editor/types.d.ts

@@ -1,7 +1,7 @@
 import { BlobStore } from '../blob';
 import { Range as ApiRange, BlockRef, EditResult, InlinePosition, Selection } from '../doc/api';
 import { RunPropertiesPatch } from '../doc/runs';
-import { Block, ParagraphAlignment, ParagraphProperties, SobreeDocument } from '../doc/types';
+import { Block, HeaderFooterRef, NamedStyle, PageMargins, PageSize, ParagraphAlignment, ParagraphProperties, SectionColumns, SectionProperties, SobreeDocument } from '../doc/types';
 /**
  * Editor-surface types — the public type vocabulary of the `Editor`
  * façade (events, payloads, command bus, options, tracked-change spans).
@@ -121,6 +121,32 @@ export interface OutlineItem {
 export type ParagraphPropertiesPatch = {
     [K in keyof ParagraphProperties]?: ParagraphProperties[K] | undefined;
 };
+/**
+ * Patch for a section's properties (page geometry, columns, header/footer
+ * refs, vertical alignment). `pageSize` / `pageMargins` are FIELD-merged
+ * into the existing values (so a partial — e.g. just `orientation` or
+ * `topTwips` — stays valid); every other field REPLACES wholesale, and an
+ * explicit `undefined` on an optional field clears it.
+ */
+export interface SectionPropertiesPatch {
+    pageSize?: Partial<PageSize>;
+    pageMargins?: Partial<PageMargins>;
+    columns?: SectionColumns | undefined;
+    headerRefs?: HeaderFooterRef[];
+    footerRefs?: HeaderFooterRef[];
+    titlePage?: boolean | undefined;
+    type?: SectionProperties["type"];
+    vAlign?: SectionProperties["vAlign"];
+}
+/**
+ * Patch for an existing named style (everything except its `id`). Each
+ * present field replaces the style's corresponding field wholesale; an
+ * explicit `undefined` clears an optional one. The required `type` /
+ * `displayName` are never cleared.
+ */
+export type NamedStylePatch = {
+    [K in keyof Omit<NamedStyle, "id">]?: NamedStyle[K] | undefined;
+};
 export type WrapTag = "sup" | "sub" | "strong" | "em" | "u" | "s" | "mark";
 /** The slice of selection state plugins read (see {@link EditorLike}). */
 export interface EditorSelectionLike {

package/dist/headless.d.ts

@@ -1,7 +1,7 @@
 import { BlobCache, BlobStore } from './blob';
 import { BlockRef, EditError, EditResult, Selection } from './doc/api';
-import { Block, ParagraphAlignment, ParagraphProperties, SobreeDocument } from './doc/types';
-import { ParagraphPropertiesPatch, BlockInfo, CommandBus, OutlineItem } from './editor';
+import { Block, NamedStyle, NumberingDefinition, NumberingLevel, ParagraphAlignment, ParagraphProperties, SobreeDocument } from './doc/types';
+import { ParagraphPropertiesPatch, BlockInfo, CommandBus, NamedStylePatch, OutlineItem, SectionPropertiesPatch } from './editor';
 import { History } from './history';
 /**
  * HeadlessSobree — a no-DOM Sobree peer for LLM agents, automation,
@@ -148,6 +148,22 @@ export declare class HeadlessSobree {
     deleteBlock(target: BlockRef): EditResult<void>;
     /** Merge a patch into each target paragraph's properties. */
     applyBlockProperties(targets: BlockRef[], patch: ParagraphPropertiesPatch): EditResult<void>;
+    /** Merge a patch into a section's properties (page geometry, columns,
+     *  header/footer refs, vertical alignment). `sectionIndex` is the
+     *  section's position in the document's `sections` array. */
+    applySectionProperties(sectionIndex: number, patch: SectionPropertiesPatch): EditResult<void>;
+    /** Add a new named style. Fails if `style.id` already exists. */
+    defineStyle(style: NamedStyle): EditResult<void>;
+    /** Merge a patch into the style with `id`. Fails if no such style. */
+    updateStyle(id: string, patch: NamedStylePatch): EditResult<void>;
+    /** Remove the style with `id`. Fails if no such style. */
+    removeStyle(id: string): EditResult<void>;
+    /** Add a new numbering definition. Fails if `def.numId` already exists. */
+    defineNumbering(def: NumberingDefinition): EditResult<void>;
+    /** Replace the levels of the definition with `numId`. Fails if missing. */
+    updateNumbering(numId: number, levels: NumberingLevel[]): EditResult<void>;
+    /** Remove the definition with `numId`. Fails if missing. */
+    removeNumbering(numId: number): EditResult<void>;
     on<E extends HeadlessEvent>(event: E, cb: (payload: HeadlessChangePayload) => void): HeadlessUnsubscribe;
     destroy(): void;
     private allBlockIds;