superdoc 2.4.0-next.5 → 2.4.0-next.51

package/dist/layout-engine/layout-engine/src/floating-objects.d.ts

@@ -1,4 +1,4 @@
-import { ImageBlock, ImageMeasure, ExclusionZone, DrawingBlock, DrawingMeasure, TableBlock, TableMeasure, ColumnLayoutForAnchor } from '../../contracts/src/index.js';
+import { ImageBlock, ImageMeasure, ExclusionZone, DrawingBlock, DrawingMeasure, TableBlock, TableMeasure, ColumnLayoutForAnchor, ResolveAnchoredGraphicXContext } from '../../contracts/src/index.js';
 type FloatBlock = ImageBlock | DrawingBlock;
 type FloatMeasure = ImageMeasure | DrawingMeasure;
 export type FloatingObjectManager = {
@@ -31,6 +31,19 @@ export type FloatingObjectManager = {
         width: number;
         offsetX: number;
     };
+    /**
+     * Compute every contiguous horizontal region available to a line.
+     * Unlike computeAvailableWidth, this preserves both sides of a centered
+     * `wrapText="bothSides"` object instead of collapsing them to one side.
+     */
+    computeAvailableRegions(lineY: number, lineHeight: number, baseWidth: number, columnIndex: number, pageNumber: number): Array<{
+        offsetX: number;
+        width: number;
+    }>;
+    /**
+     * Return the first Y coordinate below every overlapping TopAndBottom float.
+     */
+    computeVerticalClearance(lineY: number, lineHeight: number, columnIndex: number, pageNumber: number): number | null;
     /**
      * Get all floating images for a page (for debugging/painting).
      */
@@ -56,5 +69,5 @@ export declare function createFloatingObjectManager(columns: ColumnLayout, margi
 export declare function computeAnchorX(anchor: NonNullable<ImageBlock['anchor']>, columnIndex: number, columns: ColumnLayout, imageWidth: number, margins?: {
     left?: number;
     right?: number;
-}, pageWidth?: number): number;
+}, pageWidth?: number, context?: ResolveAnchoredGraphicXContext): number;
 export {};

package/dist/layout-engine/layout-engine/src/floating-table-anchor.d.ts

@@ -1,4 +1,5 @@
 import { FlowBlock, Measure, TableBlock, TableMeasure } from '../../contracts/src/index.js';
+import { LayoutWorkCheckpoint } from './execution.js';
 export type FloatingTableAnchorResolution = {
     paragraphIndex: number;
     offsetV: number;
@@ -18,4 +19,5 @@ export declare function isAnchoredTableFullWidth(block: TableBlock, measure: Tab
 /**
  * Resolve anchor paragraph + vertical offset for a block-level floating table.
  */
+export declare function resolveFloatingTableAnchorResolutionSteps(blocks: FlowBlock[], measures: Measure[], len: number, tableIndex: number, tableBlock: TableBlock, paragraphIndexById: Map<string, number>, checkpointEveryBlocks?: number | null): Generator<LayoutWorkCheckpoint, FloatingTableAnchorResolution | null, void>;
 export declare function resolveFloatingTableAnchorResolution(blocks: FlowBlock[], measures: Measure[], len: number, tableIndex: number, tableBlock: TableBlock, paragraphIndexById: Map<string, number>): FloatingTableAnchorResolution | null;

package/dist/layout-engine/layout-engine/src/footnote-anchor-index.d.ts

@@ -0,0 +1,17 @@
+import { FlowBlock } from '../../contracts/src/index.js';
+import { LayoutWorkCheckpoint } from './execution.js';
+import { FootnoteAnchorRef } from './layout-paragraph.js';
+export type FootnoteAnchorIndexInput = {
+    refs?: Array<{
+        id: string;
+        pos: number;
+    }>;
+    bodyHeightById?: Map<string, number>;
+    firstLineHeightById?: Map<string, number>;
+};
+export type FootnoteAnchorIndexDiagnostics = {
+    rangeComparisons: number;
+    lowerBoundComparisons: number;
+    legacyComparisons: number;
+};
+export declare function buildFootnoteAnchorIndexSteps(blocks: FlowBlock[], footnotes: FootnoteAnchorIndexInput | undefined, checkpointEveryBlocks: number | null, diagnostics?: FootnoteAnchorIndexDiagnostics): Generator<LayoutWorkCheckpoint, Map<string, FootnoteAnchorRef[]>, void>;

package/dist/layout-engine/layout-engine/src/index.d.ts

@@ -1,5 +1,6 @@
-import { ColumnLayout, FlowBlock, HeaderFooterLayout, Layout, Measure, Page, ParagraphBlock, ParagraphMeasure, SectionMetadata, FlowMode, DocumentBackground } from '../../contracts/src/index.js';
+import { ColumnLayout, FlowBlock, HeaderFooterLayout, Layout, Measure, Page, ParagraphBlock, ParagraphMeasure, SectionMetadata, FlowMode, DocumentBackground, ParagraphLineRegion } from '../../contracts/src/index.js';
 import { PageState, ConstraintBoundary } from './paginator.js';
+import { LayoutExecutionControl } from './execution.js';
 type PageSize = {
     w: number;
     h: number;
@@ -30,7 +31,7 @@ export type LayoutOptions = {
         marginTop?: number;
         marginBottom?: number;
     };
-    remeasureParagraph?: (block: ParagraphBlock, maxWidth: number, firstLineIndent?: number) => ParagraphMeasure;
+    remeasureParagraph?: (block: ParagraphBlock, maxWidth: number, firstLineIndent?: number, lineRegions?: readonly (readonly ParagraphLineRegion[])[]) => ParagraphMeasure;
     /** @internal Positioned paragraph frames that render without advancing the story cursor. */
     nonFlowPositionedParagraphFrameIds?: ReadonlySet<string>;
     sectionMetadata?: SectionMetadata[];
@@ -258,13 +259,12 @@ export type HeaderFooterConstraints = {
     overflowBaseHeight?: number;
 };
 /**
- * Layout FlowBlocks into paginated fragments using measured line data.
- *
- * The function is intentionally deterministic: it walks the provided
- * FlowBlocks in order, consumes their Measure objects (same index),
- * and greedily stacks fragments inside the content box of each page/column.
+ * The synchronous API drains the same resumable state machine without host
+ * turns. Mounted orchestration uses `layoutDocumentCooperatively`; keeping one
+ * algorithm prevents cancellation support from becoming a second paginator.
  */
 export declare function layoutDocument(blocks: FlowBlock[], measures: Measure[], options?: LayoutOptions): Layout;
+export declare function layoutDocumentCooperatively(blocks: FlowBlock[], measures: Measure[], options?: LayoutOptions, execution?: LayoutExecutionControl): Promise<Layout>;
 export type LayoutRangeBoundaryPolicy = 'conservative-context' | 'overscan' | 'degraded-on-incomplete-state';
 export type LayoutRangeExactness = 'exact' | 'pending-layout' | 'degraded-unsupported' | 'stale';
 export type LayoutRangeSourceRange = {
@@ -337,13 +337,16 @@ export declare function layoutDocumentRange(input: LayoutRangeInput): LayoutRang
  * Returns separate measurement bounds (for pagination) and render bounds
  * (for overlay shift). See the Coordinate Contract in the fix plan for details.
  */
-export declare function layoutHeaderFooter(blocks: FlowBlock[], measures: Measure[], constraints: HeaderFooterConstraints, kind?: 'header' | 'footer', remeasureParagraph?: (block: ParagraphBlock, maxWidth: number, firstLineIndent?: number) => ParagraphMeasure): HeaderFooterLayout;
+export declare function layoutHeaderFooter(blocks: FlowBlock[], measures: Measure[], constraints: HeaderFooterConstraints, kind?: 'header' | 'footer', remeasureParagraph?: LayoutOptions['remeasureParagraph']): HeaderFooterLayout;
+export declare function layoutHeaderFooterCooperatively(blocks: FlowBlock[], measures: Measure[], constraints: HeaderFooterConstraints, kind?: 'header' | 'footer', remeasureParagraph?: LayoutOptions['remeasureParagraph'], execution?: LayoutExecutionControl): Promise<HeaderFooterLayout>;
 export { buildAnchorMap, resolvePageRefTokens, getTocBlocksForRemeasurement } from './resolvePageRefs.js';
-export { buildChapterContextByPage, computeDisplayPageNumber, formatPageNumber, formatPageNumberFieldValue, formatSectionPageNumberText, normalizeChapterMarkerText, } from './pageNumbering.js';
+export { buildChapterContextByPage, buildChapterContextByPageCooperatively, computeDisplayPageNumber, computeDisplayPageNumberCooperatively, formatPageNumber, formatPageNumberFieldValue, formatSectionPageNumberText, normalizeChapterMarkerText, } from './pageNumbering.js';
 export type { ChapterPageInfo, DisplayPageInfo, PageNumberFormat } from './pageNumbering.js';
-export { resolvePageNumberTokens } from './resolvePageTokens.js';
+export { resolvePageNumberTokens, resolvePageNumberTokensCooperatively } from './resolvePageTokens.js';
 export type { NumberingContext, ResolvePageTokensResult, ResolvePageTokensOptions } from './resolvePageTokens.js';
 export { getCellLines, getEmbeddedRowLines, resolveTableFrame, resolveRenderedTableWidth } from './layout-table.js';
 export { describeCellRenderBlocks, computeCellSliceContentHeight } from './table-cell-slice.js';
 export { layoutTextboxContent, resolveTextboxContentMeasures } from './layout-textbox.js';
 export { SINGLE_COLUMN_DEFAULT } from './section-breaks.js';
+export { checkpointLayoutExecution, throwIfLayoutExecutionAborted } from './execution.js';
+export type { LayoutExecutionCheckpoint, LayoutExecutionControl, LayoutExecutionPhase } from './execution.js';

package/dist/layout-engine/layout-engine/src/inline-drawing-alignment.d.ts

@@ -0,0 +1,9 @@
+import { FlowBlock, Measure, Page } from '../../contracts/src/index.js';
+/**
+ * Word baseline-aligns an inline zero-height connector with the run that owns
+ * it. Projection keeps vector drawings as sibling blocks, so the connector has
+ * already reserved its authored flow height before the empty carrier paragraph
+ * is laid out. Reposition only its paint fragment once that carrier's measured
+ * baseline is known; later flow remains untouched.
+ */
+export declare function alignInlineZeroHeightDrawingFragments(pages: Page[], blocks: FlowBlock[], measures: Measure[]): void;

package/dist/layout-engine/layout-engine/src/layout-paragraph.d.ts

@@ -1,6 +1,6 @@
 import { FloatingObjectManager } from './floating-objects.js';
 import { PageState } from './paginator.js';
-import { PageMargins, ParagraphBlock, ParagraphMeasure, ImageBlock, ImageMeasure, DrawingBlock, DrawingMeasure } from '../../contracts/src/index.js';
+import { PageMargins, ParagraphBlock, ParagraphMeasure, ImageBlock, ImageMeasure, DrawingBlock, DrawingMeasure, ParagraphLineRegion } from '../../contracts/src/index.js';
 import { AnchoredTable } from './anchors.js';
 /**
  * SD-2656: ordered footnote anchor entry. The body slicer reads the candidate
@@ -21,7 +21,7 @@ export type ParagraphLayoutContext = {
     advanceColumn: (state: PageState) => PageState;
     columnX: (state: PageState, columnIndex?: number) => number;
     floatManager: FloatingObjectManager;
-    remeasureParagraph?: (block: ParagraphBlock, maxWidth: number, firstLineIndent?: number) => ParagraphMeasure;
+    remeasureParagraph?: (block: ParagraphBlock, maxWidth: number, firstLineIndent?: number, lineRegions?: readonly (readonly ParagraphLineRegion[])[]) => ParagraphMeasure;
     /**
      * Override the paragraph's spacing-after value. Used when contextual spacing
      * should suppress spacing between this paragraph and the next (same-style) paragraph.

package/dist/layout-engine/layout-engine/src/pageNumbering.d.ts

@@ -1,4 +1,5 @@
 import { formatPageNumber, formatPageNumberFieldValue, formatSectionPageNumberText, FlowBlock, Layout, Page, PageNumberChapterSeparator, PageNumberFormat, SectionMetadata } from '../../contracts/src/index.js';
+import { LayoutExecutionControl } from './execution.js';
 export { formatPageNumber, formatPageNumberFieldValue, formatSectionPageNumberText };
 export type { PageNumberFormat };
 export interface ChapterPageInfo {
@@ -29,45 +30,6 @@ export interface DisplayPageInfo {
 }
 export declare function normalizeChapterMarkerText(markerText: unknown): string | undefined;
 export declare function buildChapterContextByPage(layout: Layout, blocks: FlowBlock[] | ReadonlyMap<string, FlowBlock>, sections: SectionMetadata[]): Map<number, ChapterPageInfo>;
-/**
- * Computes section-aware display page numbers for all pages in a document.
- *
- * This function implements MS Word's section numbering behavior:
- * - Each section can have its own page number format
- * - Sections can restart numbering at a specific value
- * - Continuous sections inherit the previous section's running count unless restart is set
- * - Display numbers are calculated as: pageIndexWithinSection + offset (or restart value)
- * - Display numbers are never less than 1
- *
- * Algorithm:
- * 1. Map each page to its owning section
- * 2. For each section:
- *    - If restart/start is set, begin counting from that value
- *    - Otherwise, continue from previous section's count
- * 3. For each page within a section:
- *    - Calculate displayIndex = pageIndexWithinSection + offset
- *    - Clamp displayNumber = max(1, displayIndex)
- *    - Format displayText using the section's number format
- *
- * @param pages - Array of pages from the layout (with page.number 1-indexed)
- * @param sections - Array of section metadata (aligned by sectionIndex)
- * @returns Array of display page information for each page
- *
- * @example
- * ```typescript
- * const pages = [
- *   { number: 1, ... },
- *   { number: 2, ... },
- *   { number: 3, ... },
- * ];
- * const sections = [
- *   { sectionIndex: 0, numbering: { format: 'lowerRoman', start: 1 } },
- *   { sectionIndex: 1, numbering: { format: 'decimal', start: 1 } },
- * ];
- * const displayInfo = computeDisplayPageNumber(pages, sections);
- * // displayInfo[0]: { physicalPage: 1, displayNumber: 1, displayText: "i", sectionIndex: 0 }
- * // displayInfo[1]: { physicalPage: 2, displayNumber: 2, displayText: "ii", sectionIndex: 0 }
- * // displayInfo[2]: { physicalPage: 3, displayNumber: 1, displayText: "1", sectionIndex: 1 }
- * ```
- */
+export declare function buildChapterContextByPageCooperatively(layout: Layout, blocks: FlowBlock[] | ReadonlyMap<string, FlowBlock>, sections: SectionMetadata[], execution?: LayoutExecutionControl): Promise<Map<number, ChapterPageInfo>>;
 export declare function computeDisplayPageNumber(pages: Page[], sections: SectionMetadata[], chapterInfoByPage?: ReadonlyMap<number, ChapterPageInfo>): DisplayPageInfo[];
+export declare function computeDisplayPageNumberCooperatively(pages: Page[], sections: SectionMetadata[], chapterInfoByPage: ReadonlyMap<number, ChapterPageInfo> | undefined, execution?: LayoutExecutionControl): Promise<DisplayPageInfo[]>;

package/dist/layout-engine/layout-engine/src/resolvePageTokens.d.ts

@@ -1,5 +1,6 @@
 import { Layout, FlowBlock, ParagraphBlock, Measure } from '../../contracts/src/index.js';
 import { DisplayPageInfo } from './pageNumbering.js';
+import { LayoutExecutionControl } from './execution.js';
 /**
  * Numbering context for page token resolution.
  * Contains display page information for each physical page in the document.
@@ -59,6 +60,7 @@ export interface ResolvePageTokensOptions {
     pageCountFieldsExact?: boolean;
 }
 export declare function resolvePageNumberTokens(layout: Layout, blocks: FlowBlock[], measures: Measure[], numberingCtx: NumberingContext, options?: ResolvePageTokensOptions): ResolvePageTokensResult;
+export declare function resolvePageNumberTokensCooperatively(layout: Layout, blocks: FlowBlock[], measures: Measure[], numberingCtx: NumberingContext, options?: ResolvePageTokensOptions, execution?: LayoutExecutionControl): Promise<ResolvePageTokensResult>;
 /**
  * Resolves page number tokens in paragraph blocks.
  *

package/dist/layout-engine/layout-engine/src/section-props.d.ts

@@ -62,4 +62,9 @@ export type SectionProps = {
  * }
  * ```
  */
+export type SectionPropsScanCheckpoint = {
+    index: number;
+    total: number;
+};
+export declare function computeNextSectionPropsAtBreakSteps(blocks: FlowBlock[], checkpointEveryBlocks?: number | null): Generator<SectionPropsScanCheckpoint, Map<number, SectionProps>, void>;
 export declare function computeNextSectionPropsAtBreak(blocks: FlowBlock[]): Map<number, SectionProps>;

package/dist/layout-engine/painters/dom/src/renderer.d.ts

@@ -600,6 +600,12 @@ export declare class DomPainter {
      * Uses resolved data for spatial properties and delegates PM attributes to the legacy path.
      */
     private isAnchoredMediaFragment;
+    /**
+     * Marks fragments whose paint coordinates are independent from body flow.
+     * DOM consumers such as header/footer hit-testing must not infer page margins
+     * from floating objects that happen to paint above the first flow block.
+     */
+    private applyFragmentFlowClass;
     private shouldRenderBehindPageContent;
     private isHeaderWordArtWatermark;
     private isVmlTextWatermarkImage;

package/dist/layout-engine/painters/dom/src/runs/inline-box.d.ts

@@ -0,0 +1,8 @@
+import { Line, LineInlineBox, ParagraphBlock, Run, TextRun } from '../../../../contracts/src/index.js';
+export declare const markInlineBoxRun: (run: TextRun, lineFrom: number, lineTo: number) => TextRun;
+/** Splits text runs at the segment boundaries emitted for inline-box edges. */
+export declare const splitInlineBoxRuns: (block: ParagraphBlock, line: Line) => Run[] | null;
+/** Returns the resolved inline advance preceding an explicitly positioned text segment. */
+export declare const inlineBoxAdvanceBeforeOffset: (boxes: readonly LineInlineBox[] | undefined, offset: number) => number;
+/** Paints measured LTR inline-box slices on the canonical text leaves. */
+export declare const paintInlineBoxes: (boxes: readonly LineInlineBox[] | undefined, lineElement: HTMLElement, isRtl: boolean) => void;

package/dist/layout-engine/painters/dom/src/runs/text-run.d.ts

@@ -15,6 +15,11 @@ import { RunRenderContext, TrackedChangesRenderConfig } from './types.js';
  * makes the tab border and the text underline rasterize to the same line weight.
  */
 export declare const underlineThicknessPx: (fontSize: number) => number;
+type ResolvePhysicalFont = (cssFontFamily: string, face: {
+    weight: '400' | '700';
+    style: 'normal' | 'italic';
+}) => string;
+export declare const applyRunTypographyStyles: (element: HTMLElement, run: TextRun, resolvePhysical?: ResolvePhysicalFont) => void;
 /**
  * Applies run styling properties to a DOM element.
  *
@@ -25,10 +30,7 @@ export declare const underlineThicknessPx: (fontSize: number) => number;
  *                  inline colors are now applied to all runs (including links) to
  *                  ensure OOXML hyperlink character styles appear correctly.
  */
-export declare const applyRunStyles: (element: HTMLElement, run: Run, _isLink?: boolean, resolvePhysical?: (cssFontFamily: string, face: {
-    weight: "400" | "700";
-    style: "normal" | "italic";
-}) => string) => void;
+export declare const applyRunStyles: (element: HTMLElement, run: Run, _isLink?: boolean, resolvePhysical?: ResolvePhysicalFont) => void;
 export declare const resolveRunText: (run: Run, context: FragmentRenderContext) => string;
 export declare const extractLinkData: (run: Run) => import('./types.js').LinkRenderData | null;
 export declare const renderTextRun: (run: TextRun, context: FragmentRenderContext, renderContext: RunRenderContext, trackedConfig?: TrackedChangesRenderConfig) => HTMLElement | null;

package/dist/layout-engine/painters/dom/src/table/border-utils.d.ts

@@ -1,5 +1,20 @@
 import { BorderSpec, CellBorders, TableBorderValue, TableBorders, TableFragment } from '../../../../contracts/src/index.js';
 import { TableCellGridPosition } from './grid-geometry.js';
+type BorderSide = 'Top' | 'Right' | 'Bottom' | 'Left';
+type ThinDoubleBorderOverlayGeometry = {
+    left: string;
+    top: string;
+    width: string;
+    height: string;
+};
+/**
+ * Paints thin double borders in an unclipped sibling SVG. CSS gradients are
+ * clipped at cell seams and cannot form Word's continuous rectangular rings.
+ * The SVG preserves authored geometry once it is large enough, while the V2
+ * wrapper's inverse-zoom variable keeps sub-pixel components at Word's
+ * one-screen-pixel minimum across editor zoom levels.
+ */
+export declare const createThinDoubleBorderOverlay: (doc: Document, source: HTMLElement, geometry: ThinDoubleBorderOverlayGeometry) => SVGSVGElement | null;
 /**
  * Applies a border specification to one side of an HTML element.
  *
@@ -18,7 +33,7 @@ import { TableCellGridPosition } from './grid-geometry.js';
  * // Sets cell.style.borderTop = '2px solid #FF0000'
  * ```
  */
-export declare const applyBorder: (element: HTMLElement, side: "Top" | "Right" | "Bottom" | "Left", border?: BorderSpec) => void;
+export declare const applyBorder: (element: HTMLElement, side: BorderSide, border?: BorderSpec) => void;
 /**
  * Applies border specifications to all four sides of a table cell element.
  *
@@ -79,32 +94,9 @@ export declare const borderValueToSpec: (value?: TableBorderValue | null) => Bor
  * ```
  */
 export declare const resolveTableBorderValue: (explicit: TableBorderValue | undefined | null, fallback?: TableBorderValue | undefined | null) => BorderSpec | undefined;
-export declare const isPresentBorder: (b?: BorderSpec) => b is BorderSpec;
-/**
- * True when a border is EXPLICITLY set to none/nil (`w:val="nil"`/`"none"`), as opposed to
- * simply unset/absent. The distinction matters for shared interior edges (§17.4.66): an
- * explicit none on BOTH adjacent cells suppresses the divider, while an unset side inherits
- * the table's insideH/insideV. Accepts either a CellBorders BorderSpec (`{style:'none'}`) or
- * a TableBorderValue (`{none:true}`).
- */
-export declare const isExplicitNoneBorder: (b?: unknown) => boolean;
-/**
- * OOXML cell-border conflict resolution (ECMA-376 §17.4.66).
- *
- * With zero cell spacing, two cells sharing an edge each specify a border; the spec
- * collapses them to a SINGLE displayed border:
- *  1. If either side is nil/none/absent, the opposing (present) border is displayed.
- *  2. Otherwise the border with greater weight wins, where
- *     weight = (#lines in the style) × (style number).
- *  3. Equal weight → the style higher on the precedence list (single first) wins.
- *  4. Identical style → the color with the smaller brightness (R+B+2G, then B+2G, then
- *     G) wins; finally the first border (reading order) wins.
- *
- * @param a - One side's border (the owning cell's, e.g. the lower/right cell)
- * @param b - The opposing side's border (e.g. the upper/left neighbor)
- * @returns The single BorderSpec to display, or undefined if neither is present.
- */
-export declare const resolveBorderConflict: (a?: BorderSpec, b?: BorderSpec) => BorderSpec | undefined;
+export declare const isPresentBorder: (border?: BorderSpec) => border is BorderSpec;
+export declare const isExplicitNoneBorder: (border?: unknown) => boolean;
+export declare const resolveBorderConflict: (first?: BorderSpec, second?: BorderSpec) => BorderSpec | undefined;
 /**
  * Creates a border overlay element for a table fragment.
  *
@@ -183,3 +175,4 @@ export declare const swapTableBordersLR: (borders: TableBorders | undefined) =>
  * Swap left↔right on cell borders for RTL tables (ECMA-376 Part 4 §14.3.1, §14.3.5).
  */
 export declare const swapCellBordersLR: (borders: CellBorders | undefined) => CellBorders | undefined;
+export {};

package/dist/layout-engine/style-engine/src/ooxml/word-style-model/parse-theme.d.ts

@@ -11,11 +11,17 @@ export interface WordThemeFontFamily {
     readonly ea?: string;
     readonly cs?: string;
 }
+/** Authored DrawingML fill definitions, indexed by `a:fillRef/@idx`. */
+export interface WordThemeFormatScheme {
+    readonly fillStyles: readonly string[];
+    readonly backgroundFillStyles: readonly string[];
+}
 export declare const DEFAULT_WORD_THEME_PALETTE: WordThemeColorPalette;
 export declare const DEFAULT_WORD_THEME_FONT_SCHEME: WordThemeFontScheme;
 export interface ThemeParseResult {
     palette?: WordThemeColorPalette;
     fontScheme?: WordThemeFontScheme;
+    formatScheme?: WordThemeFormatScheme;
 }
 /**
  * Parse the theme root (`a:theme`) into colors + font scheme. Returns an

package/dist/public/ui-react.cjs

@@ -1,17 +1,45 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_rolldown_runtime = require("../chunks/rolldown-runtime-1Y-nnZJ3.cjs");
-const require_create_super_doc_ui = require("../chunks/create-super-doc-ui-sMXbYzhs.cjs");
+const require_create_super_doc_ui = require("../chunks/create-super-doc-ui-DNtHxzz_.cjs");
 let react = require("react");
+//#region src/public/ui/react.ts
+/**
+* v2-native React bindings for the `superdoc/ui` controller.
+*
+* Provider + hooks over the SuperDoc-owned controller (`superdoc.ui`). For a
+* real `SuperDoc` this layer never creates or destroys a controller; it binds
+* to the one the instance already owns. It falls back to building (and then
+* owning) one only for a structural host that carries no `ui`, since
+* `SuperDocHost` leaves that property optional. Authored with
+* `React.createElement` (no JSX) so the
+* library build needs no JSX transform, and `react` stays an external/optional
+* peer. No v1 editor or private v2 runtime imports.
+*/
 var SuperDocUIContext = (0, react.createContext)(null);
+/**
+* Destroy a controller this provider built itself. Controllers read off
+* `superdoc.ui` are never passed here: the instance owns those.
+*/
 function disposeOwnedUi(ref) {
 	const ui = ref.current;
 	if (!ui) return;
 	ui.destroy();
 	ref.current = null;
 }
+/**
+* Root provider. Call {@link useSetSuperDoc} from your editor-mount
+* component's ready callback to bind a running SuperDoc instance; the hooks
+* below then read that instance's own controller (`superdoc.ui`).
+*
+* The provider is a consumer, not an owner. SuperDoc creates the controller
+* and destroys it in `superdoc.destroy()`, so unmounting or rebinding the
+* provider leaves it running for the built-in toolbar and any other consumer
+* of the same instance. Every React hook therefore observes the same command
+* state the rest of the application sees.
+*/
 function SuperDocUIProvider(props) {
 	const [ui, setUi] = (0, react.useState)(null);
 	const [host, setHost] = (0, react.useState)(null);
+	/** Only ever holds a controller this provider created for a host lacking one. */
 	const ownedUiRef = (0, react.useRef)(null);
 	const setSuperDoc = (0, react.useCallback)((superdoc) => {
 		const hostUi = superdoc.ui;
@@ -37,15 +65,33 @@ function useContextValue() {
 	if (!value) throw new Error("[superdoc/ui/react] hooks must be used within <SuperDocUIProvider>.");
 	return value;
 }
+/**
+* Read the controller, or `null` until a SuperDoc instance is bound.
+*
+* Borrowed: the bound instance owns teardown, so the returned type omits
+* `destroy()`. A provider-built fallback controller is disposed by the provider.
+*/
 function useSuperDocUI() {
 	return useContextValue().ui;
 }
+/** Read the raw bound SuperDoc host, or `null` until one is bound. */
 function useSuperDocHost() {
 	return useContextValue().host;
 }
+/** Get the stable callback used to bind a running SuperDoc instance. */
 function useSetSuperDoc() {
 	return useContextValue().setSuperDoc;
 }
+/**
+* Normalize a `pick` result into a {@link SliceSource}. Domain handles and the
+* command/font hooks already expose the snapshot-shaped contract
+* (`getSnapshot` + `observe`) and pass through unchanged. A raw `ui.select(...)`
+* {@link Subscribable} (`get` + `subscribe`) is adapted: it `subscribe`s FIRST,
+* then emits the current value, so a synchronous recompute triggered by the
+* first listener is not missed (the substrate's `subscribe` does not emit on
+* attach). Exported for unit tests; not re-exported by the `superdoc/ui/react`
+* facade, so it stays off the public surface.
+*/
 function toSliceSource(source) {
 	const candidate = source;
 	if (typeof candidate.getSnapshot === "function" && typeof candidate.observe === "function") return source;
@@ -59,6 +105,13 @@ function toSliceSource(source) {
 		}
 	};
 }
+/**
+* Subscribe to a derived slice of controller state. `pick` selects a value
+* source from the controller: a domain handle / snapshot source
+* ({@link SliceSource}) or a raw `ui.select(...)` {@link Subscribable}, both
+* normalized via {@link toSliceSource}. `initial` is returned until the
+* controller is bound.
+*/
 function useSuperDocSlice(pick, initial) {
 	const ui = useSuperDocUI();
 	const [value, setValue] = (0, react.useState)(() => ui ? toSliceSource(pick(ui)).getSnapshot() : initial);
@@ -83,9 +136,11 @@ var EMPTY_SELECTION = {
 	activeChangeIds: [],
 	quotedText: ""
 };
+/** Subscribe to the selection slice. */
 function useSuperDocSelection() {
 	return useSuperDocSlice((ui) => ui.selection, EMPTY_SELECTION);
 }
+/** Subscribe to the comments slice. */
 function useSuperDocComments() {
 	return useSuperDocSlice((ui) => ui.comments, {
 		status: "pending",
@@ -96,6 +151,7 @@ function useSuperDocComments() {
 		activeId: null
 	});
 }
+/** Subscribe to the content-controls slice. */
 function useSuperDocContentControls() {
 	return useSuperDocSlice((ui) => ui.contentControls, {
 		status: "pending",
@@ -105,6 +161,7 @@ function useSuperDocContentControls() {
 		activeIds: []
 	});
 }
+/** Subscribe to the track-changes slice. */
 function useSuperDocTrackChanges() {
 	return useSuperDocSlice((ui) => ui.trackChanges, {
 		status: "pending",
@@ -114,6 +171,7 @@ function useSuperDocTrackChanges() {
 		authors: []
 	});
 }
+/** Subscribe to the toolbar snapshot slice. */
 function useSuperDocToolbar() {
 	return useSuperDocSlice((ui) => ui.toolbar, {
 		context: null,
@@ -121,6 +179,7 @@ function useSuperDocToolbar() {
 		copyFormatActive: false
 	});
 }
+/** Subscribe to a single command's enable/active state. */
 function useSuperDocCommand(id) {
 	return useSuperDocSlice((ui) => ({
 		getSnapshot: () => ui.commands.get(id).getState(),
@@ -131,6 +190,7 @@ function useSuperDocCommand(id) {
 		supported: false
 	});
 }
+/** Subscribe to the document slice. */
 function useSuperDocDocument() {
 	return useSuperDocSlice((ui) => ui.document, {
 		ready: false,
@@ -138,18 +198,21 @@ function useSuperDocDocument() {
 		dirty: false
 	});
 }
+/** Subscribe to available font-family options. */
 function useSuperDocFontOptions() {
 	return useSuperDocSlice((ui) => ({
 		getSnapshot: () => ui.fonts.getFamilyOptions(),
 		observe: (cb) => ui.fonts.observe((slice) => cb(slice.options))
 	}), []);
 }
+/** Subscribe to available font-size options. */
 function useSuperDocFontSizeOptions() {
 	return useSuperDocSlice((ui) => ({
 		getSnapshot: () => ui.fonts.getSizeOptions(),
 		observe: (cb) => ui.fonts.observe((slice) => cb(slice.sizeOptions))
 	}), []);
 }
+/** Subscribe to the zoom slice. */
 function useSuperDocZoom() {
 	return useSuperDocSlice((ui) => ui.zoom, {
 		mode: null,
@@ -158,6 +221,7 @@ function useSuperDocZoom() {
 		max: 100
 	});
 }
+//#endregion
 exports.SuperDocUIProvider = SuperDocUIProvider;
 exports.useSetSuperDoc = useSetSuperDoc;
 exports.useSuperDocCommand = useSuperDocCommand;