superdoc 2.4.0-next.9 → 2.5.0

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

@@ -1,13 +1,13 @@
-import { ChartModel, DrawingGeometry } from '../../../contracts/src/index.js';
+import { ChartModel, DrawingGeometry, RenderPlaceholder } from '../../../contracts/src/index.js';
 /**
  * Create a chart element from a ChartDrawing block.
  * Routes to the correct renderer based on chart type, with placeholder fallback.
  */
-export declare function createChartElement(doc: Document, chartData: ChartModel | undefined, geometry: DrawingGeometry): HTMLElement;
+export declare function createChartElement(doc: Document, chartData: ChartModel | undefined, geometry: DrawingGeometry, placeholder?: RenderPlaceholder): HTMLElement;
 /**
  * Create a placeholder for charts with missing data or unsupported types.
  * Preserves layout dimensions and is print-visible.
  */
-export declare function createChartPlaceholder(doc: Document, container: HTMLElement, label: string): HTMLElement;
+export declare function createChartPlaceholder(doc: Document, container: HTMLElement, label: string, placeholder?: RenderPlaceholder): HTMLElement;
 /** Format a numeric tick value for chart axis labels. */
 export declare function formatTickValue(value: number): string;

package/dist/layout-engine/painters/dom/src/images/image-outline.d.ts

@@ -0,0 +1,7 @@
+import { ImageOutline } from '../../../../contracts/src/index.js';
+/**
+ * Paint a DrawingML picture frame without changing the image's layout box.
+ * `a:ln` is centered on the picture geometry; a negatively offset CSS outline
+ * reproduces that geometry while keeping width/height authoritative.
+ */
+export declare const applyImageOutline: (target: HTMLElement, outline?: ImageOutline) => void;

package/dist/layout-engine/painters/dom/src/images/render-placeholder.d.ts

@@ -0,0 +1,12 @@
+import { RenderPlaceholder } from '../../../../contracts/src/index.js';
+export type CreateRenderPlaceholderOptions = {
+    doc: Document;
+    placeholder: RenderPlaceholder;
+};
+/** Stamp the shared diagnostic and accessibility contract on a placeholder. */
+export declare const applyRenderPlaceholderSemantics: (element: HTMLElement, placeholder: RenderPlaceholder) => void;
+/**
+ * Paint an observable, print-visible replacement for content that the
+ * projection layer deliberately kept fail-closed.
+ */
+export declare const createRenderPlaceholder: ({ doc, placeholder }: CreateRenderPlaceholderOptions) => HTMLSpanElement;

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

@@ -261,6 +261,8 @@ export declare class DomPainter {
     private totalPages;
     private sectionPageCounts;
     private linkIdCounter;
+    private shapeImageFillCounter;
+    private wordArtPathCounter;
     private sdtLabelsRendered;
     /**
      * WeakMap storing tooltip data for hyperlink elements before DOM insertion.
@@ -520,11 +522,52 @@ export declare class DomPainter {
      * Apply fill and stroke styles to a fallback shape container
      */
     private applyFallbackShapeStyle;
+    /**
+     * Shape stroke widths reach the painter in physical CSS pixels. Preset SVGs
+     * use a normalized 100 × 100 viewBox while VML custom geometry often uses a
+     * coordsize in the thousands. In both cases allowing the viewBox transform to
+     * scale the stroke changes the authored line weight, sometimes by orders of
+     * magnitude. Keep geometry scalable and paint the resolved width verbatim.
+     */
+    private applyPhysicalStrokeSemantics;
+    /**
+     * Produce a stable 8-bit preview color for inactive header/footer graphics.
+     * CSS color-mix() retains fractional sRGB channels and Chromium floors some
+     * half-channel values during rasterization; Word rounds those channels. Keep
+     * the authored color separate and expose the rounded blend as a paint hint.
+     */
+    private mixResolvedHexColorWithWhite;
+    /** Paint a DrawingML picture fill through the existing SVG geometry. */
+    private applyShapeImageFill;
+    private appendShapeFillImage;
+    private resolveShapeTileOrigin;
     private hasShapeTextContent;
     private createShapeTextElement;
     private createTextboxContentElement;
     private shouldUseWordArtTextRenderer;
     private createWordArtTextElement;
+    private createWordArtEnvelopeGroup;
+    /**
+     * Approximates DrawingML's point-wise text-envelope transform with narrow
+     * vector strips. Each strip maps a slice of the unwarped text block between
+     * the authored upper and lower guide paths. Unlike a per-glyph affine
+     * transform, this bends the glyph outlines themselves while preserving SVG
+     * text paint (fills, outlines, glow and shadow) and browser font shaping.
+     */
+    private createWordArtEnvelopeMesh;
+    /**
+     * DrawingML composes glow and shadow after the text outline has been
+     * deformed by the warp. The envelope renderer repeats a clipped source
+     * through many transformed `<use>` elements; leaving a CSS filter on that
+     * source clips and transforms the effect independently in every mesh strip.
+     * Promote a shared run filter to the completed mesh so the browser paints
+     * one effect around the final warped silhouette. Mixed run effects remain on
+     * their source runs because collapsing them would change authored styling.
+     */
+    private promoteUniformWordArtEnvelopeFilter;
+    private measureWordArtLineMetrics;
+    private measureWordArtLineWidth;
+    private createWordArtReflection;
     private buildWordArtLines;
     private resolveShapeTextPartText;
     private getWordArtTextAnchor;
@@ -540,6 +583,8 @@ export declare class DomPainter {
      * @param _groupScaleY - Reserved parent-group scale factor
      */
     private createFallbackTextElement;
+    private shapeTextAllowsOverflow;
+    private applyShapeTextFlow;
     private tryCreatePresetSvg;
     /**
      * Creates an SVG string from custom geometry path data (a:custGeom).
@@ -566,6 +611,9 @@ export declare class DomPainter {
      */
     private createChartElement;
     private resolveTableRenderData;
+    private createTableCellLineRenderer;
+    /** Render drawing content nested in any canonical table, including a textbox-owned table. */
+    private renderDrawingContentForTable;
     private renderTableFragment;
     private renderLine;
     private createRunRenderContext;
@@ -600,6 +648,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-effects.d.ts

@@ -0,0 +1,30 @@
+import { TextEffects } from '../../../../contracts/src/index.js';
+type TextInkBounds = {
+    left: number;
+    top: number;
+    right: number;
+    bottom: number;
+};
+export declare function reflectionDirection(direction: number): 'above' | 'below' | 'left' | 'right';
+export declare function resolveTextReflectionTransform(reflection: NonNullable<TextEffects['reflection']>, ink: TextInkBounds): {
+    transform: string;
+    maskDirection: 'top' | 'bottom' | 'left' | 'right';
+};
+/**
+ * Resolve reflection geometry without choosing a DOM or SVG transform syntax.
+ * Both ordinary HTML runs and SVG WordArt use the same DrawingML direction,
+ * distance, scale, and ink-edge anchoring contract.
+ */
+export declare function resolveTextReflectionPlacement(reflection: NonNullable<TextEffects['reflection']>, ink: TextInkBounds): {
+    translateX: number;
+    translateY: number;
+    maskDirection: 'top' | 'bottom' | 'left' | 'right';
+};
+/** Resolve authored reflection opacity stops against visible glyph ink, not CSS leading. */
+export declare function resolveTextReflectionMask(reflection: NonNullable<TextEffects['reflection']>, ink: TextInkBounds, box: {
+    width: number;
+    height: number;
+}): string;
+/** Apply paint-only Word text effects without changing glyph metrics. */
+export declare function applyTextEffects(element: HTMLElement, effects: TextEffects | undefined): void;
+export {};

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/shapes/preset-text-warp-data.d.ts

@@ -0,0 +1,32 @@
+/**
+ * ECMA-376 preset text-warp geometry data.
+ *
+ * Generated from the standard's accompanying
+ * OfficeOpenXML-DrawingMLGeometries.zip / presetTextWarpDefinitions.xml.
+ * Do not hand-edit; regenerate through the evidence-plan script.
+ */
+export type PresetTextWarpCommand = {
+    kind: 'moveTo' | 'lnTo' | 'quadBezTo' | 'cubicBezTo';
+    points: Array<{
+        x: string;
+        y: string;
+    }>;
+} | {
+    kind: 'arc';
+    wR: string;
+    hR: string;
+    stAng: string;
+    swAng: string;
+};
+export type PresetTextWarpDefinition = {
+    adjustments: Array<{
+        name: string;
+        fmla: string;
+    }>;
+    guides: Array<{
+        name: string;
+        fmla: string;
+    }>;
+    paths: PresetTextWarpCommand[][];
+};
+export declare const PRESET_TEXT_WARP_DEFINITIONS: Record<string, PresetTextWarpDefinition>;

package/dist/layout-engine/painters/dom/src/shapes/wordart-warp.d.ts

@@ -0,0 +1,39 @@
+import { ShapeTextWarp } from '../../../../contracts/src/index.js';
+export type WordArtWarpPoint = {
+    x: number;
+    y: number;
+};
+export type WordArtWarpGeometry = {
+    paths: WordArtWarpPoint[][];
+    /** One boundary bends a baseline; two or more boundaries define a glyph envelope. */
+    kind: 'baseline' | 'envelope';
+};
+export type WordArtWarpPath = {
+    d: string;
+    fidelity: 'baseline' | 'envelope';
+    /** Polyline length of the evaluated preset path in layout coordinates. */
+    length: number;
+};
+export type WordArtBaselineBand = {
+    geometry: WordArtWarpGeometry;
+    path: WordArtWarpPath;
+};
+export declare function resolveWordArtWarpGeometry(warp: ShapeTextWarp, width: number, height: number, top?: number): WordArtWarpGeometry | null;
+/**
+ * Resolve the centerline between two adjacent authored warp boundaries.
+ *
+ * A small family of DrawingML presets uses shared boundaries to compose
+ * successive text bands (for example textButton's upper/center/lower paths).
+ * Word lays each line on the corresponding band centerline and preserves the
+ * glyph outlines instead of stretching the ink through the whole envelope.
+ */
+export declare function resolveWordArtAdjacentBandBaseline(geometry: WordArtWarpGeometry, bandIndex: number): WordArtBaselineBand | null;
+/** Baseline compatibility surface used by the SVG textPath renderer and diagnostics. */
+export declare function resolveWordArtWarpPath(warp: ShapeTextWarp, width: number, height: number, top?: number): WordArtWarpPath | null;
+export declare function pointAtPath(points: readonly WordArtWarpPoint[], progress: number): WordArtWarpPoint;
+/**
+ * Resolve the DrawingML text-warp percentage on a flattened boundary path.
+ * ECMA-376 §20.1.9.19 steps 6–8 require travelled distance after flattening,
+ * not the curve's command, sample, or angle parameter.
+ */
+export declare function pointAtWarpParameter(points: readonly WordArtWarpPoint[], progress: number): WordArtWarpPoint;

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/painters/dom/src/table/renderTableFragment.d.ts

@@ -39,7 +39,7 @@ export type TableRenderDependencies = {
     /** Built-in SDT chrome rendering mode. */
     chrome?: 'default' | 'none';
     /** Function to render a line of paragraph content */
-    renderLine: (block: ParagraphBlock, line: Line, context: FragmentRenderContext, lineIndex: number, isLastLine: boolean) => HTMLElement;
+    renderLine: (block: ParagraphBlock, line: Line, context: FragmentRenderContext, lineIndex: number, isLastLine: boolean, resolvedListTextStartPx?: number) => HTMLElement;
     /** Optional callback invoked after a table line's final styles/markers are applied. */
     captureLineSnapshot?: (lineEl: HTMLElement, context: FragmentRenderContext, options?: {
         inTableParagraph?: boolean;

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

@@ -11,11 +11,18 @@ export interface WordThemeFontFamily {
     readonly ea?: string;
     readonly cs?: string;
 }
+/** Authored DrawingML format definitions, indexed by the matching style reference. */
+export interface WordThemeFormatScheme {
+    readonly fillStyles: readonly string[];
+    readonly backgroundFillStyles: readonly string[];
+    readonly lineStyles?: 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-ByvmsAAG.cjs");
+const require_create_super_doc_ui = require("../chunks/create-super-doc-ui-Bom7oDPv.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;