@docx-editor.dev/core 2.7.0 → 2.9.0

package/dist/{index-QsE1xXyT.d.cts → index-DGPSeLI0.d.cts}

@@ -1,17 +1,17 @@
-import { T as TreeDocOp, d as DrawingPositionInput, l as DrawingTransform, h as DrawingTreeDocOp } from './tree-op-types-QujrzgCz.cjs';
-import { b as ImageDecodePort, S as SupportedImageMime } from './image-resources-Bkmu1Jei.cjs';
-import './review-support-oQrX6Xu3.cjs';
+import { T as TreeDocOp, d as DrawingPositionInput, l as DrawingTransform, h as DrawingTreeDocOp } from './tree-op-types-B0-sCtw-.cjs';
+import { b as ImageDecodePort, S as SupportedImageMime } from './image-resources-DQOiwOuE.cjs';
+import { g as ReviewRevisionKind } from './review-items-DpsqTHio.cjs';
 import { EditorModule, ReviewModuleContribution } from './contracts/modules.cjs';
-import { j as FontSource, k as FontSourceSubstitution, F as FontConfiguration, l as FontFaceRequest, I as ImageContext, D as DocumentSource, Z as ZoomMode, E as EditorFontError, m as Editor, b as EditorCommand, C as CanResult, S as SelectedImageState, V as ViewScope, T as TableBorderEdgeTarget, n as TableBorderSpec, o as TableBorderStyle, p as TableContext } from './editor-CXaGlcUa.cjs';
-import { R as RevisionDisplayMode } from './revision-projection-WzlQGBJx.cjs';
-import { a as SemanticSelection, S as SemanticPosition, N as NavigationCommand } from './semantic-interaction-f4GyBQ_1.cjs';
-import { R as ResolvedFootnoteProperties, a as ResolvedEndnoteProperties, A as AuthoredNoteProperties, l as ReviewRevisionKind } from './review-reads-ChgUq41I.cjs';
-import { S as SemanticLayout, C as ContentControlBoundaryRecord, T as TextMeasurer } from './semantic-records-CuT3Wsd-.cjs';
-import { S as StoryScope, A as ApplyImagePropertiesInput, d as ImageIntentResult, c as InsertImageInput, B as BookmarkIndex } from './custom-node-writes-C_AlNvds.cjs';
-import { C as CellSelection, S as SectionProperties } from './semantic-cell-selection-CQOgvtbT.cjs';
-import { c as RevisionStyles, R as ReviewAuthorInfo, b as RevisionAuthorStyle, F as FieldShadingMode, d as DrawingPaintStrings } from './semantic-paint-BUt0ePEW.cjs';
-import { Unsubscribe, ExecResult, IndentFormatting, SelectionPin } from './contracts/types.cjs';
-import { c as TreeDocxSessionView, a as TreeApplyResult } from './tree-session-5UWKAQ41.cjs';
+import { j as FontSource, k as FontSourceSubstitution, F as FontConfiguration, D as DocumentSource, Z as ZoomMode, E as EditorFontError, l as Editor, b as EditorCommand, C as CanResult, S as SelectedImageState, V as ViewScope, m as FontFaceRequest, I as ImageContext, T as TableBorderEdgeTarget, n as TableBorderSpec, o as TableBorderStyle, p as TableContext } from './editor-CojjwMmF.cjs';
+import { R as RevisionDisplayMode } from './revision-projection-Cc4wz30g.cjs';
+import { S as SemanticPosition, a as SemanticSelection, N as NavigationCommand } from './semantic-interaction-BjOcDB06.cjs';
+import { c as RevisionStyles, R as ReviewAuthorInfo, b as RevisionAuthorStyle, F as FieldShadingMode, d as DrawingPaintStrings } from './semantic-paint-Ur7pAINj.cjs';
+import { R as ResolvedFootnoteProperties, a as ResolvedEndnoteProperties, A as AuthoredNoteProperties } from './note-properties-CQlxjic_.cjs';
+import { S as SemanticLayout, C as ContentControlBoundaryRecord, T as TextMeasurer } from './semantic-records-C3Z76KeN.cjs';
+import { S as StoryScope, A as ApplyImagePropertiesInput, d as ImageIntentResult, c as InsertImageInput, B as BookmarkIndex } from './custom-node-writes-7ERv0f_X.cjs';
+import { C as CellSelection, S as SectionProperties } from './semantic-cell-selection-DJPjBWzf.cjs';
+import { Unsubscribe, ExecResult, ParagraphTabStop, IndentFormatting, ParagraphFlags, ParagraphDisagreements, SelectionPin } from './contracts/types.cjs';
+import { c as TreeDocxSessionView, a as TreeApplyResult } from './tree-session-D945D43B.cjs';
 import './contracts/document.cjs';
 
 /**
@@ -104,1116 +104,330 @@ declare function composeFontConfiguration(base: FontConfigurationBase, ...fragme
 /**
  * A Word-faithful blank document, freshly zipped per call (the caller may hand the
  * bytes to a loader that takes ownership). Calibri 11pt and Word's Normal paragraph
- * spacing are authored in `w:docDefaults`, US Letter geometry in the section — a New
- * document behaves like Word's, and saving it produces a file Word opens identically.
+ * spacing are authored in `w:docDefaults`, Word's built-in style gallery in `styles.xml`,
+ * US Letter geometry in the section — a New document behaves like Word's, and saving it
+ * produces a file Word opens identically.
  *
  * @public
  */
 declare function blankDocumentBytes(): Uint8Array;
 
-/** One URL to fetch and the face it claims to be. */
-interface FontUrlSource {
-    readonly url: string;
-    readonly family: string;
-    readonly weight: number;
-    readonly style: 'normal' | 'italic';
-    /**
-     * Expected `sha256:` content hash. When present, mismatching bytes are REFUSED —
-     * pin this for any URL not under the app's sole control.
-     */
-    readonly hash?: string;
-    readonly faceIndex?: number;
-}
+type TableCommandSelectionPolicy = {
+    readonly kind: 'preserveSelection';
+} | {
+    readonly kind: 'adoptCommittedCaret';
+};
+type TableCommandPlan = {
+    readonly ok: true;
+    readonly ops: readonly TreeDocOp[];
+    readonly selection: TableCommandSelectionPolicy;
+} | {
+    readonly ok: false;
+    readonly code: 'unsupported' | 'invalidArgs' | 'locked';
+    readonly reason: string;
+};
+
+type NotePropertiesSlice = {
+    readonly resolved: ResolvedFootnoteProperties | ResolvedEndnoteProperties;
+    readonly documentAuthored?: AuthoredNoteProperties;
+    readonly sectionAuthored?: AuthoredNoteProperties;
+};
+type NotePropertiesStateSnapshot = {
+    readonly sectionIndex: number;
+    readonly footnote: NotePropertiesSlice;
+    readonly endnote: NotePropertiesSlice;
+};
+
 /**
- * What to fetch, and under what limits.
- *
- * Only `sources` is required. Each carries its own expected hash, so bytes are trusted by
- * CONTENT rather than by origin — a swapped asset fails admission even from a trusted host.
+ * A hyperlink as the surface reports it: its identity, where it sits, and the SANITIZED
+ * target. `href: null` is an inert link — a refused scheme or a dangling relationship — which
+ * a UI shows and offers to edit but must never offer to open.
  */
-interface LoadFontsRequest {
-    readonly sources: readonly FontUrlSource[];
-    /** Cache API bucket name; default `docx-editor-fonts`. */
-    readonly cacheName?: string;
-    /** Injectable for tests and CSP-constrained hosts; defaults to global `fetch`. */
-    readonly fetcher?: typeof fetch;
-    /** Per-font byte ceiling; defaults to the engine hard maximum. */
-    readonly maxFontBytes?: number;
+interface SurfaceHyperlink {
+    /** Canonical node id of the `w:hyperlink`. */
+    readonly id: string;
+    readonly paragraphId: string;
+    /** UTF-16 range of the link's display text within its paragraph. */
+    readonly start: number;
+    readonly end: number;
+    readonly text: string;
+    readonly kind: 'external' | 'internal' | 'unresolved';
+    /** Sanitized projection: an absolute URL, `#anchor`, or null when inert. */
+    readonly href: string | null;
+    /** The authored target, for an editor to seed its input with. */
+    readonly authored: string;
+    readonly anchor?: string;
+    readonly tooltip?: string;
 }
 /**
- * Why one font did not load.
- *
- * Distinguished rather than collapsed to "failed" because the responses differ: `networkError`
- * and `httpError` are worth retrying, while `hashMismatch` and `malformed` mean the bytes were
- * not what the source claimed and retrying will fetch the same wrong thing.
- */
-type FontLoadFailureReason = 'networkError' | 'httpError' | 'hashMismatch' | 'overLimit' | 'emptyResponse'
-/** The declared face itself is unusable (empty family, out-of-range weight); nothing was fetched. */
- | 'invalidRequest'
-/** The bytes are not a font at all — most often an HTML error page served with 200. */
- | 'malformed';
-/**
- * One face that did not load, with whatever evidence the failure produced.
+ * Reading and writing hyperlinks on the surface.
  *
- * Non-fatal: {@link LoadFontsResult} still carries every source that succeeded, and the affected
- * family falls back to the engine's fixed measurement.
+ * Every href that leaves here has already been through `sanitizeHref` — targets come from files,
+ * so `javascript:`, `data:` and `vbscript:` are dropped at the parse boundary rather than trusted
+ * to be filtered by whoever renders them.
  */
-interface FontLoadFailure {
-    readonly url: string;
-    readonly request: FontFaceRequest;
-    readonly reason: FontLoadFailureReason;
-    /** HTTP status for `httpError`; hashes for `hashMismatch`. */
-    readonly status?: number;
-    readonly expectedHash?: string;
-    readonly actualHash?: string;
-    readonly diagnostic?: string;
+interface HyperlinkOps {
+    /** Every link in the paragraph the caret is in. */
+    linksInCaretParagraph(): SurfaceHyperlink[];
+    /** The link the caret sits in, or null. */
+    linkAtCaret(): SurfaceHyperlink | null;
+    /**
+     * The FIELD link whose painted atom the caret sits on, or null.
+     *
+     * Separate from {@link linkAtCaret} on purpose: a `HYPERLINK` field is not a tree node, so
+     * the typed lane never returns one, and link-create must not mistake a field atom for an
+     * editable link. Resolved from the layout projection, boundary-inclusive.
+     */
+    fieldLinkAtCaret(): SurfaceHyperlink | null;
+    /** The link with this node id, or null. */
+    linkById(linkId: string): SurfaceHyperlink | null;
+    /**
+     * Apply a link to the selection, or retarget the one the caret is already in.
+     *
+     * `text` replaces the display text when supplied. Returns whether anything committed;
+     * a refusal leaves the document exactly as it was.
+     */
+    applyHyperlink(input: {
+        readonly url?: string;
+        readonly anchor?: string;
+        readonly text?: string;
+        readonly tooltip?: string;
+    }): boolean;
+    /** Take the link off the one at the caret (or a named one). Returns whether it committed. */
+    removeHyperlink(linkId?: string): boolean;
 }
-/**
- * What one `loadFonts` call produced: the faces that arrived, plus the ones that did not.
- *
- * A `FontConfigurationFragment`, so it composes straight into `composeFontConfiguration`
- * alongside other font sources. Partial success is the normal case — compose it even with
- * failures present.
- */
-interface LoadFontsResult extends FontConfigurationFragment {
-    readonly sources: readonly FontSource[];
-    readonly failures: readonly FontLoadFailure[];
+
+/** A click on a painted link, after native navigation was refused. */
+interface HyperlinkActivation {
+    readonly link: SurfaceHyperlink;
+    /** The clicked line fragment's viewport rect, so a popover can be placed under it. */
+    readonly rect: {
+        readonly left: number;
+        readonly top: number;
+        readonly bottom: number;
+        readonly right: number;
+    };
 }
 /**
- * Fetch app-specified font URLs into verified, cache-backed `FontSource`s.
- *
- * Fetches ONLY the URLs listed — never a default host or engine-chosen CDN — and never
- * rejects for a per-source failure: the result carries every admitted source and a
- * typed entry for every drop. Compose the result with `composeFontConfiguration`.
- */
-declare function loadFonts(request: LoadFontsRequest): Promise<LoadFontsResult>;
-/**
- * Turn font bytes you ALREADY hold into a `FontSource` — a file input, IndexedDB, a
- * bundler import. `loadFonts` covers URLs; this covers everything else, so no caller has
- * to hand-assemble the record or reach for a hashing helper.
+ * Moving the caret and the viewport: to a position, to a bookmark, or out to an external target.
  *
- * Returns a typed failure instead of throwing when the descriptor or the bytes are
- * unusable, matching `loadFonts`: one bad face degrades itself, never its neighbours.
+ * {@link SurfaceNavigation.openExternal} is THE external-activation call site, and it refuses
+ * anything but an already-sanitized href. Routing an authored target through some other path is
+ * how a document gets to choose where a click goes.
  */
-declare function createFontSource(bytes: Uint8Array, request: FontFaceRequest & {
-    readonly faceIndex?: number;
-}, options?: {
-    readonly id?: string;
-    readonly maxFontBytes?: number;
-}): {
-    readonly source: FontSource;
+interface SurfaceNavigation {
+    /** Snap to a semantic position using layout geometry, then place the caret there. */
+    goToPosition(position: {
+        paragraphId: string;
+        offset: number;
+    }): boolean;
+    /**
+     * Scroll a bookmark into view and place the caret at it. Answers false for a name no
+     * bookmark declares — an inert click, which is what Word does with a dangling anchor.
+     */
+    goToBookmark(name: string): boolean;
+    /**
+     * THE external-activation call site. Refuses anything but a sanitized projection, so a
+     * caller cannot route an authored target through it by mistake.
+     */
+    openExternal(href: string | null): boolean;
+    destroy(): void;
+}
+
+/** One addressable inline equation and its compact editable projection. */
+interface SurfaceEquation {
+    readonly id: string;
+    readonly paragraphId: string;
+    readonly start: number;
+    readonly end: number;
+    readonly linear: string;
+    readonly fallbackText: string;
+    /** True when every source construct belongs to the editable subset. */
+    readonly supported: boolean;
+}
+/** A user click on one painted equation. */
+interface EquationActivation {
+    readonly equation: SurfaceEquation;
+    readonly rect: {
+        readonly left: number;
+        readonly top: number;
+        readonly right: number;
+        readonly bottom: number;
+    };
+}
+/** Boundary-inclusive lookup, matching the hyperlink and field atom popovers. */
+declare function equationAtPosition(equations: readonly SurfaceEquation[], position: SemanticPosition): SurfaceEquation | null;
+type EquationAction = 'replace' | 'remove';
+/** Engine-owned capability result for equation editing chrome. */
+type EquationCanResult = {
+    readonly ok: true;
 } | {
-    readonly failure: FontLoadFailure;
+    readonly ok: false;
+    readonly code: 'locked' | 'notFound' | 'unsupported';
+    readonly reason: string;
 };
+/** Surface equation reads and atomic replace/remove writes. */
+interface EquationOps {
+    equationsInCaretParagraph(): SurfaceEquation[];
+    equationAtCaret(): SurfaceEquation | null;
+    equationById(equationId: string): SurfaceEquation | null;
+    /** Whether equation chrome can run an action, with the engine-owned refusal reason. */
+    can(equationId: string, action: EquationAction): EquationCanResult;
+    applyEquation(equationId: string, linear: string): boolean;
+    removeEquation(equationId: string): boolean;
+}
 
 /**
- * HOW a control reaches the engine — never WHETHER it is enabled.
- *
- * Enabled state has exactly one source: `toolbarCommandState(editor, slot)`, which
- * asks `Editor.can`. The registry is static data and cannot know what the engine
- * will honour at this selection, in this document, at this moment.
+ * Everything {@link createDocxEditor} accepts. Every field is optional.
  *
- * There used to be a fourth member, `parityOnly`, meaning "visible but permanently
- * disabled". It was a second, static answer to the question `Editor.can` already
- * answers, and it went stale the moment the engine wired underline, strike, the four
- * alignments, the list commands and the four value slots: the registry still said
- * parity-only, React ignored it and ran them, and Vue believed it and rendered twelve
- * WORKING commands permanently disabled. A slot the engine has not wired needs no
- * registry flag — `commandForSlot` answers null and `toolbarCommandState` disables the
- * control with the engine's own words ("not wired to an editor command").
- */
-type ChromeControlState = 
-/**
- * Dispatched as one fixed engine command: enabled when
- * `Editor.can(commandForSlot(slot))` succeeds, a click runs
- * `runToolbarCommand(editor, slot)`. The command is resolved from the SLOT id
- * through `commandForSlot` in toolbar-commands.ts — the one command table both
- * adapters share. A slot with no row there is simply not wired YET, and says so
- * through the engine rather than through this descriptor.
- */
-{
-    readonly kind: 'command';
-}
-/**
- * Dispatched with a PICKED value: `commandForSlotValue(slot, value)`. Enabled when
- * the engine would honour a well-formed value right now (`toolbarCommandState`
- * probes for exactly that), so the control needs chrome that produces a value — a
- * font list, a size, a colour — before a click means anything.
+ * `container` is the one that changes the shape of the whole lifecycle: omitting it produces an
+ * instance that does no DOM work until `attach(el)`, which is what lets a provider own the editor
+ * before any component has rendered a mount point.
  *
- * A distinct kind because 'command' cannot describe it: there is no fixed command
- * to hand `Editor.can`, and a bare click has nothing to send.
+ * @public
  */
- | {
-    readonly kind: 'value';
-}
-/** `Editor.save()` — not a command (see `runSave`). */
- | {
-    readonly kind: 'save';
-}
-/**
- * `Editor.load()` — not a command either, and the exact twin of `save`: bytes cross the
- * boundary between the host and the engine, and only the host can produce them. The
- * control needs chrome that reads a file (a picker, a drop target) before a click means
- * anything, so a bare click has nothing to send — the same reason `save` is not `command`.
- *
- * A fourth kind rather than reusing `save` because the two dispatch in opposite
- * directions, and an adapter branching on `kind` must be able to tell them apart. Unlike
- * the deleted `parityOnly`, this one IS named by a control (`file.open`).
- */
- | {
-    readonly kind: 'load';
-};
+interface DocxEditorConfig {
+    /**
+     * The element the paginated surface mounts into. The surface owns this subtree.
+     *
+     * Optional: an instance created WITHOUT a container stashes its document bytes and does
+     * no DOM work until `attach(el)` — the provider-first shape, where the editor exists
+     * before any component has rendered a mount point. With a container, the document mounts
+     * immediately at construction, exactly as before.
+     */
+    container?: HTMLElement;
+    /**
+     * A document to load at construction: DOCX bytes, or `'blank'` for Word's blank
+     * template. A `DocumentHandle` cannot be re-opened (the handle is identity, not
+     * content), so passing one emits a typed `error` event rather than silently loading
+     * nothing. Omitting this mounts NO document, which is not the same as an empty one.
+     */
+    document?: DocumentSource;
+    /**
+     * Font bytes for Word-accurate (HarfBuzz-shaped) line wrap and pagination. Omitted,
+     * layout falls back to a fixed-width estimate; fonts embedded in the document are
+     * wired in automatically either way. For Word's default faces (Calibri, Times New
+     * Roman, …) pass `await loadDefaultFonts()` from `@docx-editor.dev/fonts` — a bare
+     * fragment (`{ sources, substitutions }`) is accepted and composed with defaults, or
+     * merge several origins yourself with `composeFontConfiguration`. Sampled per load;
+     * failures degrade to the fixed measurer and report through `onFontError`.
+     *
+     * Pass a {@link FontResolver} instead to resolve ON DEMAND: the function is called once
+     * per load, after the document is parsed, with the families it actually declares, and
+     * only what it returns is loaded. A document naming nothing the resolver covers costs
+     * nothing. Note that a fetching resolver makes opening a document perform network
+     * requests — the engine never supplies one, so that stays your call.
+     */
+    fonts?: FontConfiguration | FontConfigurationFragment | FontResolver;
+    author?: string;
+    locale?: string;
+    /** Localized drawing refusal labels; defaults to English when omitted. */
+    translate?: (key: string, params?: Record<string, string | number>) => string;
+    /**
+     * Capability modules to register — the seam `@docx-editor.dev/pro` plugs in
+     * through. Omitted, the editor runs the free tier: lossless round-trip,
+     * final-state revision rendering, review chrome disabled with the engine's
+     * reason. See {@link EditorModule}.
+     */
+    modules?: readonly EditorModule[];
+    /**
+     * The mode the editor opens in — one prop, matching the toolbar's three-state pill.
+     *
+     * - `'edit'` — opens in editing, even when the document's `w:trackRevisions` asks for
+     *   tracked changes; the reader still moves between modes from the toolbar.
+     * - `'suggesting'` — opens in suggesting. It needs what suggesting always needs — a
+     *   review module and an {@link DocxEditorConfig.author} — and falls back to editing
+     *   with the reason published when either is missing.
+     * - `'view'` — read-only: every mutating command through the facade is refused, and
+     *   the toolbar cannot leave viewing.
+     * - Omitted — the DOCUMENT decides: a package carrying `w:trackRevisions` opens in
+     *   suggesting, everything else in editing.
+     */
+    mode?: 'edit' | 'view' | 'suggesting';
+    /**
+     * How painted tracked changes are coloured. Presentation only — nothing is serialised.
+     *
+     * - `'author'` (the DEFAULT) — every change takes its author's colour from the
+     *   `--doc-review-author-N` ramp, by order of first appearance, as Word does. Restyle a
+     *   slot under `.docx-editor` to change the ramp.
+     * - `'kind'` — insertions green, deletions red, so "added" and "removed" are what a
+     *   glance tells apart, whoever proposed them.
+     * - {@link RevisionAuthorAssignments} — style the named authors; `others` decides
+     *   whether the rest take the ramp (the default) or the kind colours.
+     *
+     * The opening value. In React this is authored declaratively — `DocxEditor.ColorByChangeType`
+     * and `DocxEditor.AuthorStyle` compose and apply it, seeding this config for the first
+     * paint — so React hosts never pass it by hand; it is the entry for headless hosts. Read
+     * the document's resolved roster with `getReviewAuthors`. Applies wherever revision
+     * markup paints: the full all-markup view needs a review module registered; without one
+     * the proposed view still marks surviving insertions.
+     */
+    revisionStyles?: RevisionStyles;
+    /** Override raster decode for insert/replace image commands; defaults to browser/headless. */
+    imageDecodePort?: ImageDecodePort;
+    /**
+     * The scale to open at, as a fixed number.
+     *
+     * Supplying one also picks the mode: an editor given a `zoom` and no `zoomMode` opens
+     * FIXED at that value and stays there. An embedder that pinned 100% keeps 100%.
+     */
+    zoom?: number;
+    /**
+     * Where the scale comes from. Defaults to `'auto'` — fit the page width, between 50% and
+     * 100% — unless {@link DocxEditorConfig.zoom} is supplied, which means fixed.
+     *
+     * `'auto'` leaves a window wide enough for the sheet exactly where it is today and shrinks
+     * a narrower one instead of growing a horizontal scrollbar. Pass `{ type: 'fixed' }` for
+     * the old unconditional behaviour.
+     */
+    zoomMode?: ZoomMode | 'auto';
+    onFontError?: (error: EditorFontError) => void;
+    /** Localized labels for table insertion furniture on the painted surface. */
+    tableInteractionLabel?: (key: 'table.insertRowBelow' | 'table.insertColumnRight') => string;
+}
 /**
- * The SHAPE a control renders as (task M6V.1).
- *
- * The legacy toolbar is not a row of uniform icon buttons: it mixes labelled dropdowns
- * (`Normal`, `Arial`, alignment, line spacing), numeric steppers with visible values
- * (zoom `- 100% +`, size `- 26 +`), split colour controls (a glyph over a colour swatch
- * with its own caret), and a mode pill (`Editing`). Rendering all of them as icon
- * buttons is the difference an owner review called out as "not visual parity" — the
- * regions were all present and it still did not look like the product.
+ * Which measurer the current document's layout runs on, and whether shaped resolution is
+ * still in flight. Returned by {@link DocxEditorInstance.fontMeasurement}.
  */
-/** `modePill` is deliberately absent. It was declared, never used by any control, and
- *  rendered nothing — the editing-mode control below is a `dropdown`, which is what the
- *  legacy product shows. A shape no descriptor names is a branch adapters must implement
- *  and can never exercise. */
-type ChromeControlShape = 'icon' | 'stepper' | 'dropdown' | 'colorSplit';
+interface FontMeasurementState {
+    /** `fixed` estimates advance widths; `shaped` measures real font bytes with HarfBuzz. */
+    readonly measurer: 'fixed' | 'shaped';
+    /** True while font resolution for the current document is still running. */
+    readonly resolving: boolean;
+    /** The shaped measurer's identity (admitted face hashes); absent while fixed. */
+    readonly producer?: string;
+}
 /**
- * One toolbar control as the registry describes it — what it renders as, never whether it is
- * enabled.
- *
- * Enabled state has exactly ONE source, `toolbarCommandState`, which asks the engine. A
- * descriptor carrying its own disabled flag would be a second answer that goes stale the moment
- * the engine wires the slot.
+ * The host chrome that answers the engine's hyperlink gestures.
  *
- * @public
+ * A CLICK on an external link and Ctrl/Cmd+K both mean "the user wants the link UI", and the
+ * engine deliberately does not know what that looks like. Registered rather than passed at
+ * construction because the chrome mounts after the editor does, and it survives a document
+ * reload — the surface is rebuilt, the handlers are not.
  */
-interface ChromeControl<Id extends string = string> {
-    /** Stable control id, unique WITHIN its group. Public API; renames are breaking. */
-    readonly id: Id;
-    /** How it renders. Defaults to `icon`. */
-    readonly shape?: ChromeControlShape;
-    /** Displayed value for a stepper or dropdown (an i18n key, or a literal for numbers). */
-    readonly valueText?: string;
-    /** Swatch colour for a `colorSplit` control. */
-    readonly swatch?: string;
-    /** i18n key for the accessible name and tooltip. Never hardcoded English. */
-    readonly labelKey: string;
-    /** Material Symbols path data, or null for a non-icon control (a picker). */
-    readonly paths: readonly string[] | null;
-    /** For pickers: the i18n key of the placeholder value shown. */
-    readonly valueKey?: string;
-    readonly state: ChromeControlState;
+interface HyperlinkChromeHandlers {
+    /** A plain click on an external or inert link: show the popover at `activation.rect`. */
+    readonly onPopover?: (activation: HyperlinkActivation) => void;
+    /** Ctrl/Cmd+K: open insert-or-edit for the selection. */
+    readonly onRequest?: () => void;
+}
+/** Host chrome that edits a clicked Office Math equation. */
+interface EquationChromeHandlers {
+    readonly onPopover?: (activation: EquationActivation) => void;
 }
 /**
- * One toolbar group: the taxonomy both adapters derive their default arrangement FROM.
- *
- * Never hand-list controls in an adapter — a default toolbar is built by walking `CHROME_GROUPS`,
- * so a slot added here appears in React and Vue without either being edited.
+ * The concrete facade type: the full `Editor` contract plus the instance-only surface.
  *
- * @public
+ * `surface`, `stateVersion`, `attach` and `detach` live HERE rather than on `Editor`:
+ * they are what a store binding and a mounting host need, not what document commands
+ * need. Production adapters program against `Editor` for everything else.
  */
-interface ChromeGroup<Id extends string = string, ControlId extends string = string> {
-    /** Stable group id. Public API; renames are breaking. */
-    readonly id: Id;
-    readonly labelKey: string;
+interface DocxEditorInstance extends Editor {
+    /** Bumps on mount, detach, destroy, and document reload — guards async image intents. */
+    readonly mountGeneration: number;
     /**
-     * Not part of the DEFAULT toolbar arrangement. The chrome spec shows these
-     * controls only in a context the engine does not model yet (an image or table
-     * selection), or not at all (save belongs in the host's File menu, never in the
-     * bar). Their slots stay public for composition — a host can still place
-     * `image.insert` or `file.save` explicitly — but the default chrome is the
-     * registry's default bar, which ends at the editing-mode picker.
-     */
-    readonly contextual?: true;
-    readonly controls: readonly ChromeControl<ControlId>[];
-}
-/**
- * The complete chrome, in bar order. Literal-typed (`as const`) so the slot-id
- * vocabulary below is derived from the data and cannot drift from it.
- *
- * Taxonomy taste: ids are short, lowercaseCamel, and never repeat their group's name
- * (`alignment.left`, not `alignment.alignLeft`; `font.family`, not `font.fontFamily`).
- */
-declare const CHROME_GROUPS: readonly [{
-    readonly id: "history";
-    readonly labelKey: "formattingBar.groups.history";
-    readonly controls: readonly [{
-        readonly id: "undo";
-        readonly labelKey: "formattingBar.undoShortcut";
-        readonly paths: readonly string[];
-        readonly state: {
-            readonly kind: "command";
-        };
-    }, {
-        readonly id: "redo";
-        readonly labelKey: "formattingBar.redoShortcut";
-        readonly paths: readonly string[];
-        readonly state: {
-            readonly kind: "command";
-        };
-    }];
-}, {
-    readonly id: "zoom";
-    readonly labelKey: "formattingBar.groups.zoom";
-    readonly controls: readonly [{
-        readonly id: "level";
-        readonly shape: "stepper";
-        readonly valueText: "100%";
-        readonly labelKey: "formattingBar.groups.zoom";
-        readonly paths: null;
-        readonly valueKey: "zoom.zoomLevel";
-        readonly state: {
-            readonly kind: "command";
-        };
-    }];
-}, {
-    readonly id: "styles";
-    readonly labelKey: "formattingBar.groups.styles";
-    readonly controls: readonly [{
-        readonly id: "style";
-        readonly shape: "dropdown";
-        readonly labelKey: "styles.selectAriaLabel";
-        readonly paths: null;
-        readonly valueKey: "styles.normalText";
-        readonly state: {
-            readonly kind: "value";
-        };
-    }];
-}, {
-    readonly id: "font";
-    readonly labelKey: "formattingBar.groups.font";
-    readonly controls: readonly [{
-        readonly id: "family";
-        readonly shape: "dropdown";
-        readonly labelKey: "font.selectAriaLabel";
-        readonly paths: null;
-        readonly valueKey: "font.sansSerif";
-        readonly state: {
-            readonly kind: "value";
-        };
-    }, {
-        readonly id: "size";
-        readonly shape: "stepper";
-        readonly valueText: "11";
-        readonly labelKey: "fontSize.listLabel";
-        readonly paths: null;
-        readonly valueKey: "fontSize.label";
-        readonly state: {
-            readonly kind: "value";
-        };
-    }];
-}, {
-    readonly id: "text";
-    readonly labelKey: "formattingBar.groups.textFormatting";
-    readonly controls: readonly [{
-        readonly id: "bold";
-        readonly labelKey: "formattingBar.boldShortcut";
-        readonly paths: readonly string[];
-        readonly state: {
-            readonly kind: "command";
-        };
-    }, {
-        readonly id: "italic";
-        readonly labelKey: "formattingBar.italicShortcut";
-        readonly paths: readonly string[];
-        readonly state: {
-            readonly kind: "command";
-        };
-    }, {
-        readonly id: "underline";
-        readonly labelKey: "formattingBar.underlineShortcut";
-        readonly paths: readonly string[];
-        readonly state: {
-            readonly kind: "command";
-        };
-    }, {
-        readonly id: "strike";
-        readonly labelKey: "formattingBar.strikethrough";
-        readonly paths: readonly string[];
-        readonly state: {
-            readonly kind: "command";
-        };
-    }, {
-        readonly id: "color";
-        readonly shape: "colorSplit";
-        readonly swatch: "#ff0000";
-        readonly labelKey: "formattingBar.fontColor";
-        readonly paths: readonly string[];
-        readonly state: {
-            readonly kind: "value";
-        };
-    }, {
-        readonly id: "highlight";
-        readonly shape: "colorSplit";
-        readonly swatch: "#ffff00";
-        readonly labelKey: "formattingBar.highlightColor";
-        readonly paths: readonly string[];
-        readonly state: {
-            readonly kind: "value";
-        };
-    }, {
-        readonly id: "link";
-        readonly labelKey: "formattingBar.insertLinkShortcut";
-        readonly paths: readonly string[];
-        readonly state: {
-            readonly kind: "command";
-        };
-    }];
-}, {
-    readonly id: "script";
-    readonly labelKey: "formattingBar.groups.script";
-    readonly controls: readonly [{
-        readonly id: "super";
-        readonly labelKey: "formattingBar.superscript";
-        readonly paths: readonly string[];
-        readonly state: {
-            readonly kind: "command";
-        };
-    }, {
-        readonly id: "sub";
-        readonly labelKey: "formattingBar.subscript";
-        readonly paths: readonly string[];
-        readonly state: {
-            readonly kind: "command";
-        };
-    }];
-}, {
-    readonly id: "alignment";
-    readonly labelKey: "formattingBar.groups.alignment";
-    readonly controls: readonly [{
-        readonly id: "left";
-        readonly labelKey: "alignment.alignLeft";
-        readonly paths: readonly string[];
-        readonly state: {
-            readonly kind: "command";
-        };
-    }, {
-        readonly id: "center";
-        readonly labelKey: "alignment.center";
-        readonly paths: readonly string[];
-        readonly state: {
-            readonly kind: "command";
-        };
-    }, {
-        readonly id: "right";
-        readonly labelKey: "alignment.alignRight";
-        readonly paths: readonly string[];
-        readonly state: {
-            readonly kind: "command";
-        };
-    }, {
-        readonly id: "justify";
-        readonly labelKey: "alignment.justify";
-        readonly paths: readonly string[];
-        readonly state: {
-            readonly kind: "command";
-        };
-    }];
-}, {
-    readonly id: "list";
-    readonly labelKey: "formattingBar.groups.listFormatting";
-    readonly controls: readonly [{
-        readonly id: "bullet";
-        readonly labelKey: "lists.bulletList";
-        readonly paths: readonly string[];
-        readonly state: {
-            readonly kind: "command";
-        };
-    }, {
-        readonly id: "numbered";
-        readonly labelKey: "lists.numberedList";
-        readonly paths: readonly string[];
-        readonly state: {
-            readonly kind: "command";
-        };
-    }, {
-        readonly id: "outdent";
-        readonly labelKey: "lists.decreaseIndent";
-        readonly paths: readonly string[];
-        readonly state: {
-            readonly kind: "command";
-        };
-    }, {
-        readonly id: "indent";
-        readonly labelKey: "lists.increaseIndent";
-        readonly paths: readonly string[];
-        readonly state: {
-            readonly kind: "command";
-        };
-    }, {
-        readonly id: "lineSpacing";
-        readonly shape: "dropdown";
-        readonly labelKey: "lineSpacing.label";
-        readonly paths: readonly string[];
-        readonly state: {
-            readonly kind: "command";
-        };
-    }];
-}, {
-    readonly id: "format";
-    readonly labelKey: "formattingBar.clearFormatting";
-    readonly controls: readonly [{
-        readonly id: "clear";
-        readonly labelKey: "formattingBar.clearFormatting";
-        readonly paths: readonly string[];
-        readonly state: {
-            readonly kind: "command";
-        };
-    }];
-}, {
-    readonly id: "review";
-    readonly labelKey: "formattingBar.commentsAndChanges";
-    readonly controls: readonly [{
-        readonly id: "comments";
-        readonly shape: "icon";
-        readonly labelKey: "formattingBar.commentsAndChanges";
-        readonly paths: readonly string[];
-        readonly state: {
-            readonly kind: "command";
-        };
-    }, {
-        readonly id: "editingMode";
-        readonly shape: "dropdown";
-        readonly labelKey: "editingMode.label";
-        readonly valueKey: "editingMode.editing";
-        readonly paths: readonly string[];
-        readonly state: {
-            readonly kind: "command";
-        };
-    }];
-}, {
-    readonly id: "contentControl";
-    readonly labelKey: "contentControl.group";
-    readonly contextual: true;
-    readonly controls: readonly [{
-        readonly id: "showAll";
-        readonly labelKey: "contentControl.showAll";
-        readonly paths: readonly string[];
-        readonly state: {
-            readonly kind: "command";
-        };
-    }, {
-        readonly id: "formFill";
-        readonly labelKey: "contentControl.formFill";
-        readonly paths: readonly string[];
-        readonly state: {
-            readonly kind: "command";
-        };
-    }, {
-        readonly id: "inspector";
-        readonly labelKey: "contentControl.inspector";
-        readonly paths: readonly string[];
-        readonly state: {
-            readonly kind: "command";
-        };
-    }, {
-        readonly id: "remove";
-        readonly labelKey: "contentControl.remove";
-        readonly paths: readonly string[];
-        readonly state: {
-            readonly kind: "command";
-        };
-    }];
-}, {
-    readonly id: "image";
-    readonly labelKey: "formattingBar.groups.image";
-    readonly contextual: true;
-    readonly controls: readonly [{
-        readonly id: "insert";
-        readonly labelKey: "toolbar.image";
-        readonly paths: readonly string[];
-        readonly state: {
-            readonly kind: "command";
-        };
-    }, {
-        readonly id: "properties";
-        readonly labelKey: "formattingBar.imagePropertiesShortcut";
-        readonly paths: readonly string[];
-        readonly state: {
-            readonly kind: "command";
-        };
-    }, {
-        readonly id: "wrap";
-        readonly shape: "dropdown";
-        readonly labelKey: "formattingBar.imageWrap";
-        readonly paths: readonly string[];
-        readonly valueKey: "imageWrap.inline";
-        readonly state: {
-            readonly kind: "value";
-        };
-    }, {
-        readonly id: "altText";
-        readonly shape: "dropdown";
-        readonly labelKey: "formattingBar.altText";
-        readonly paths: null;
-        readonly valueKey: "imageProperties.altText";
-        readonly state: {
-            readonly kind: "value";
-        };
-    }];
-}, {
-    readonly id: "table";
-    readonly labelKey: "formattingBar.groups.table";
-    readonly contextual: true;
-    readonly controls: readonly [{
-        readonly id: "insert";
-        readonly labelKey: "toolbar.table";
-        readonly paths: readonly string[];
-        readonly state: {
-            readonly kind: "command";
-        };
-    }, {
-        readonly id: "borderTarget";
-        readonly shape: "dropdown";
-        readonly labelKey: "table.borders.tooltip";
-        readonly paths: readonly string[];
-        readonly state: {
-            readonly kind: "value";
-        };
-    }, {
-        readonly id: "borderColor";
-        readonly shape: "colorSplit";
-        readonly swatch: "#000000";
-        readonly labelKey: "table.borderColor";
-        readonly paths: readonly string[];
-        readonly state: {
-            readonly kind: "value";
-        };
-    }, {
-        readonly id: "borderStyle";
-        readonly shape: "dropdown";
-        readonly labelKey: "table.borders.styleAriaLabel";
-        readonly paths: readonly string[];
-        readonly state: {
-            readonly kind: "value";
-        };
-    }, {
-        readonly id: "borderWidth";
-        readonly shape: "dropdown";
-        readonly labelKey: "table.borderWidth";
-        readonly paths: readonly string[];
-        readonly state: {
-            readonly kind: "value";
-        };
-    }, {
-        readonly id: "cellFill";
-        readonly shape: "colorSplit";
-        readonly swatch: "#ffffff";
-        readonly labelKey: "table.cellFillColor";
-        readonly paths: readonly string[];
-        readonly state: {
-            readonly kind: "value";
-        };
-    }];
-}, {
-    readonly id: "file";
-    readonly labelKey: "toolbar.file";
-    readonly contextual: true;
-    readonly controls: readonly [{
-        readonly id: "open";
-        readonly labelKey: "toolbar.open";
-        readonly paths: readonly string[];
-        readonly state: {
-            readonly kind: "load";
-        };
-    }, {
-        readonly id: "save";
-        readonly labelKey: "toolbar.saveShortcut";
-        readonly paths: readonly string[];
-        readonly state: {
-            readonly kind: "save";
-        };
-    }, {
-        readonly id: "pageSetup";
-        readonly labelKey: "toolbar.pageSetup";
-        readonly paths: readonly string[];
-        readonly state: {
-            readonly kind: "command";
-        };
-    }];
-}, {
-    readonly id: "insert";
-    readonly labelKey: "toolbar.insert";
-    readonly contextual: true;
-    readonly controls: readonly [{
-        readonly id: "footnote";
-        readonly labelKey: "toolbar.insertFootnote";
-        readonly paths: readonly string[];
-        readonly state: {
-            readonly kind: "command";
-        };
-    }, {
-        readonly id: "endnote";
-        readonly labelKey: "toolbar.insertEndnote";
-        readonly paths: readonly string[];
-        readonly state: {
-            readonly kind: "command";
-        };
-    }, {
-        readonly id: "pageNumber";
-        readonly labelKey: "headerFooter.insertPageNumber";
-        readonly paths: readonly string[];
-        readonly state: {
-            readonly kind: "command";
-        };
-    }, {
-        readonly id: "totalPages";
-        readonly labelKey: "headerFooter.insertTotalPages";
-        readonly paths: readonly string[];
-        readonly state: {
-            readonly kind: "command";
-        };
-    }, {
-        readonly id: "sectionPages";
-        readonly labelKey: "headerFooter.insertSectionPages";
-        readonly paths: readonly string[];
-        readonly state: {
-            readonly kind: "command";
-        };
-    }, {
-        readonly id: "pageXofY";
-        readonly labelKey: "headerFooter.insertPageXofY";
-        readonly paths: readonly string[];
-        readonly state: {
-            readonly kind: "command";
-        };
-    }, {
-        readonly id: "pageBreak";
-        readonly labelKey: "toolbar.pageBreak";
-        readonly paths: readonly string[];
-        readonly state: {
-            readonly kind: "command";
-        };
-    }, {
-        readonly id: "sectionBreakNextPage";
-        readonly labelKey: "toolbar.sectionBreakNextPage";
-        readonly paths: readonly string[];
-        readonly state: {
-            readonly kind: "command";
-        };
-    }, {
-        readonly id: "sectionBreakContinuous";
-        readonly labelKey: "toolbar.sectionBreakContinuous";
-        readonly paths: readonly string[];
-        readonly state: {
-            readonly kind: "command";
-        };
-    }, {
-        readonly id: "toc";
-        readonly labelKey: "toolbar.tableOfContents";
-        readonly paths: readonly string[];
-        readonly state: {
-            readonly kind: "command";
-        };
-    }];
-}];
-/**
- * Every group id in the chrome, as a literal union. Stable public API; renaming a group
- * id is a breaking change.
- *
- * @public
- */
-type ChromeGroupId = 'history' | 'zoom' | 'styles' | 'font' | 'text' | 'script' | 'alignment' | 'list' | 'format' | 'review' | 'contentControl' | 'image' | 'table' | 'file' | 'insert';
-/**
- * The public slot vocabulary: `${groupId}.${controlId}` for every control that actually
- * exists — `text.bold`, `font.family`, `alignment.left`. THE stable contract a host
- * composes against and `commandForSlot` resolves; renaming a slot is a breaking change.
- *
- * @public
- */
-type ChromeSlotId = 'history.undo' | 'history.redo' | 'zoom.level' | 'styles.style' | 'font.family' | 'font.size' | 'text.bold' | 'text.italic' | 'text.underline' | 'text.strike' | 'text.color' | 'text.highlight' | 'text.link' | 'script.super' | 'script.sub' | 'alignment.left' | 'alignment.center' | 'alignment.right' | 'alignment.justify' | 'list.bullet' | 'list.numbered' | 'list.outdent' | 'list.indent' | 'list.lineSpacing' | 'format.clear' | 'review.comments' | 'review.editingMode' | 'contentControl.showAll' | 'contentControl.formFill' | 'contentControl.inspector' | 'contentControl.remove' | 'image.insert' | 'image.properties' | 'image.wrap' | 'image.altText' | 'table.insert' | 'table.borderTarget' | 'table.borderColor' | 'table.borderStyle' | 'table.borderWidth' | 'table.cellFill' | 'file.open' | 'file.save' | 'file.pageSetup' | 'insert.footnote' | 'insert.endnote' | 'insert.pageNumber' | 'insert.totalPages' | 'insert.sectionPages' | 'insert.pageXofY' | 'insert.pageBreak' | 'insert.sectionBreakNextPage' | 'insert.sectionBreakContinuous' | 'insert.toc';
-/**
- * Every control id in the chrome, as a literal union. Unique WITHIN a group, not
- * globally (`image.insert` / `table.insert`) — key consumers on {@link ChromeSlotId}.
- *
- * @public
- */
-type ChromeControlId = ChromeSlotId extends `${string}.${infer C}` ? C : never;
-/**
- * The slot id of one control within its group. Only meaningful for entries of
- * `CHROME_GROUPS` — the cast is sound because every group/control pair in the registry
- * is, by construction, a member of the `ChromeSlotId` union.
- *
- * @public
- */
-declare function chromeSlotId(group: {
-    readonly id: string;
-}, control: {
-    readonly id: string;
-}): ChromeSlotId;
-/**
- * The groups of the DEFAULT toolbar arrangement, in bar order: every group that is
- * not `contextual`. This is the registry's default bar — undo/redo through the
- * editing-mode picker — and what both adapters render when the host composes
- * nothing. Contextual slots (`image.*`, `table.insert`, `file.save`) remain
- * available for explicit composition.
- *
- * @public
- */
-declare function defaultChromeGroups(): readonly ChromeGroup[];
-/**
- * The formatting-bar groups for one editor snapshot: the default bar, plus the
- * contextual `image` group when a drawing is selected. Insertion without a selection is
- * not in the packaged chrome at all — a host that wants it places `image.insert` itself,
- * through `DocxEditor.Toolbar.ImageInsert` or `DocxEditor.Menu.ImageInsert`.
- *
- * @public
- */
-declare function formattingBarChromeGroups(image: ImageContext | null): readonly ChromeGroup[];
-/**
- * A row that runs one chrome slot.
- *
- * @public
- */
-interface ChromeMenuItemEntry {
-    readonly kind: 'item';
-    readonly slot: ChromeSlotId;
-    /**
-     * Plain-label override for this row.
-     *
-     * A slot's own `labelKey` is a TOOLTIP key, and several of them fold the shortcut into
-     * the text (`formattingBar.boldShortcut` is "Bold (Ctrl+B)"). A menu puts the shortcut
-     * in its own right-hand column, so the row needs the bare noun. Both keys already exist
-     * in the catalogue — this points at the plain one rather than minting a duplicate.
-     */
-    readonly labelKey?: string;
-    /** i18n key of the shortcut shown right-aligned on the row (`toolbar.saveShortcut`). */
-    readonly shortcutKey?: string;
-    /**
-     * The row opens a size PICKER instead of firing on click — Word's insert-table grid.
-     * The slot still owns the label, the icon and the enabled state; only the dispatch
-     * differs, and the picked size is what the host sends.
-     */
-    readonly picker?: 'tableGrid';
-}
-/**
- * A row that opens a nested panel of rows (Insert › Break).
- *
- * It carries its own label and icon rather than a slot, because a submenu PARENT has no
- * command: clicking it opens the panel. Giving it a slot would mint a public id for a
- * control that can never be enabled, and `toolbarCommandState` would have to invent an
- * answer about it.
- *
- * @public
- */
-interface ChromeMenuSubmenuEntry {
-    readonly kind: 'submenu';
-    readonly labelKey: string;
-    readonly paths: readonly string[] | null;
-    readonly items: readonly ChromeMenuEntry[];
-}
-/** A horizontal rule between groups of rows. @public */
-interface ChromeMenuSeparatorEntry {
-    readonly kind: 'separator';
-}
-/** One row of a chrome menu. @public */
-type ChromeMenuEntry = ChromeMenuItemEntry | ChromeMenuSubmenuEntry | ChromeMenuSeparatorEntry;
-/**
- * Every menu id, as a literal union. Stable public API; renaming one is a breaking change,
- * exactly like a group or slot id.
- *
- * @public
- */
-type ChromeMenuId = 'file' | 'format' | 'insert' | 'help';
-/** One menu of the menu bar. @public */
-interface ChromeMenu {
-    readonly id: ChromeMenuId;
-    readonly labelKey: string;
-    readonly entries: readonly ChromeMenuEntry[];
-}
-/**
- * The menu bar the chrome shows above the toolbar, in bar order: File, Format, Insert,
- * Help.
- *
- * @public
- */
-declare const CHROME_MENUS: readonly ChromeMenu[];
-/**
- * Every slot a menu places, in menu order, submenus flattened. What a parity test asserts
- * against, and what a host enumerates to know which capabilities the menu bar reaches.
- *
- * @public
- */
-declare function chromeMenuSlots(): readonly ChromeSlotId[];
-/** Total controls, so a parity test can assert none were dropped. */
-declare function chromeControlCount(): number;
-/**
- * i18n key for the tooltip on a control an ADAPTER renders but cannot drive yet — a
- * value slot in a toolbar that has grown no picker for it, say. It is never the reason
- * a control is disabled: when the ENGINE refuses, the tooltip is the engine's own
- * `disabledReason`, never an adapter paraphrase.
- */
-declare const CHROME_UNAVAILABLE_KEY = "formattingBar.unavailableInPreview";
-
-type TableCommandSelectionPolicy = {
-    readonly kind: 'preserveSelection';
-} | {
-    readonly kind: 'adoptCommittedCaret';
-};
-type TableCommandPlan = {
-    readonly ok: true;
-    readonly ops: readonly TreeDocOp[];
-    readonly selection: TableCommandSelectionPolicy;
-} | {
-    readonly ok: false;
-    readonly code: 'unsupported' | 'invalidArgs' | 'locked';
-    readonly reason: string;
-};
-
-type NotePropertiesSlice = {
-    readonly resolved: ResolvedFootnoteProperties | ResolvedEndnoteProperties;
-    readonly documentAuthored?: AuthoredNoteProperties;
-    readonly sectionAuthored?: AuthoredNoteProperties;
-};
-type NotePropertiesStateSnapshot = {
-    readonly sectionIndex: number;
-    readonly footnote: NotePropertiesSlice;
-    readonly endnote: NotePropertiesSlice;
-};
-
-/**
- * A hyperlink as the surface reports it: its identity, where it sits, and the SANITIZED
- * target. `href: null` is an inert link — a refused scheme or a dangling relationship — which
- * a UI shows and offers to edit but must never offer to open.
- */
-interface SurfaceHyperlink {
-    /** Canonical node id of the `w:hyperlink`. */
-    readonly id: string;
-    readonly paragraphId: string;
-    /** UTF-16 range of the link's display text within its paragraph. */
-    readonly start: number;
-    readonly end: number;
-    readonly text: string;
-    readonly kind: 'external' | 'internal' | 'unresolved';
-    /** Sanitized projection: an absolute URL, `#anchor`, or null when inert. */
-    readonly href: string | null;
-    /** The authored target, for an editor to seed its input with. */
-    readonly authored: string;
-    readonly anchor?: string;
-    readonly tooltip?: string;
-}
-/**
- * Reading and writing hyperlinks on the surface.
- *
- * Every href that leaves here has already been through `sanitizeHref` — targets come from files,
- * so `javascript:`, `data:` and `vbscript:` are dropped at the parse boundary rather than trusted
- * to be filtered by whoever renders them.
- */
-interface HyperlinkOps {
-    /** Every link in the paragraph the caret is in. */
-    linksInCaretParagraph(): SurfaceHyperlink[];
-    /** The link the caret sits in, or null. */
-    linkAtCaret(): SurfaceHyperlink | null;
-    /**
-     * The FIELD link whose painted atom the caret sits on, or null.
-     *
-     * Separate from {@link linkAtCaret} on purpose: a `HYPERLINK` field is not a tree node, so
-     * the typed lane never returns one, and link-create must not mistake a field atom for an
-     * editable link. Resolved from the layout projection, boundary-inclusive.
-     */
-    fieldLinkAtCaret(): SurfaceHyperlink | null;
-    /** The link with this node id, or null. */
-    linkById(linkId: string): SurfaceHyperlink | null;
-    /**
-     * Apply a link to the selection, or retarget the one the caret is already in.
-     *
-     * `text` replaces the display text when supplied. Returns whether anything committed;
-     * a refusal leaves the document exactly as it was.
-     */
-    applyHyperlink(input: {
-        readonly url?: string;
-        readonly anchor?: string;
-        readonly text?: string;
-        readonly tooltip?: string;
-    }): boolean;
-    /** Take the link off the one at the caret (or a named one). Returns whether it committed. */
-    removeHyperlink(linkId?: string): boolean;
-}
-
-/** A click on a painted link, after native navigation was refused. */
-interface HyperlinkActivation {
-    readonly link: SurfaceHyperlink;
-    /** The clicked line fragment's viewport rect, so a popover can be placed under it. */
-    readonly rect: {
-        readonly left: number;
-        readonly top: number;
-        readonly bottom: number;
-        readonly right: number;
-    };
-}
-/**
- * Moving the caret and the viewport: to a position, to a bookmark, or out to an external target.
- *
- * {@link SurfaceNavigation.openExternal} is THE external-activation call site, and it refuses
- * anything but an already-sanitized href. Routing an authored target through some other path is
- * how a document gets to choose where a click goes.
- */
-interface SurfaceNavigation {
-    /** Snap to a semantic position using layout geometry, then place the caret there. */
-    goToPosition(position: {
-        paragraphId: string;
-        offset: number;
-    }): boolean;
-    /**
-     * Scroll a bookmark into view and place the caret at it. Answers false for a name no
-     * bookmark declares — an inert click, which is what Word does with a dangling anchor.
-     */
-    goToBookmark(name: string): boolean;
-    /**
-     * THE external-activation call site. Refuses anything but a sanitized projection, so a
-     * caller cannot route an authored target through it by mistake.
-     */
-    openExternal(href: string | null): boolean;
-    destroy(): void;
-}
-
-/**
- * Everything {@link createDocxEditor} accepts. Every field is optional.
- *
- * `container` is the one that changes the shape of the whole lifecycle: omitting it produces an
- * instance that does no DOM work until `attach(el)`, which is what lets a provider own the editor
- * before any component has rendered a mount point.
- *
- * @public
- */
-interface DocxEditorConfig {
-    /**
-     * The element the paginated surface mounts into. The surface owns this subtree.
-     *
-     * Optional: an instance created WITHOUT a container stashes its document bytes and does
-     * no DOM work until `attach(el)` — the provider-first shape, where the editor exists
-     * before any component has rendered a mount point. With a container, the document mounts
-     * immediately at construction, exactly as before.
-     */
-    container?: HTMLElement;
-    /**
-     * A document to load at construction: DOCX bytes, or `'blank'` for Word's blank
-     * template. A `DocumentHandle` cannot be re-opened (the handle is identity, not
-     * content), so passing one emits a typed `error` event rather than silently loading
-     * nothing. Omitting this mounts NO document, which is not the same as an empty one.
-     */
-    document?: DocumentSource;
-    /**
-     * Font bytes for Word-accurate (HarfBuzz-shaped) line wrap and pagination. Omitted,
-     * layout falls back to a fixed-width estimate; fonts embedded in the document are
-     * wired in automatically either way. For Word's default faces (Calibri, Times New
-     * Roman, …) pass `await loadDefaultFonts()` from `@docx-editor.dev/fonts` — a bare
-     * fragment (`{ sources, substitutions }`) is accepted and composed with defaults, or
-     * merge several origins yourself with `composeFontConfiguration`. Sampled per load;
-     * failures degrade to the fixed measurer and report through `onFontError`.
-     *
-     * Pass a {@link FontResolver} instead to resolve ON DEMAND: the function is called once
-     * per load, after the document is parsed, with the families it actually declares, and
-     * only what it returns is loaded. A document naming nothing the resolver covers costs
-     * nothing. Note that a fetching resolver makes opening a document perform network
-     * requests — the engine never supplies one, so that stays your call.
-     */
-    fonts?: FontConfiguration | FontConfigurationFragment | FontResolver;
-    author?: string;
-    locale?: string;
-    /** Localized drawing refusal labels; defaults to English when omitted. */
-    translate?: (key: string, params?: Record<string, string | number>) => string;
-    /**
-     * Capability modules to register — the seam `@docx-editor.dev/pro` plugs in
-     * through. Omitted, the editor runs the free tier: lossless round-trip,
-     * final-state revision rendering, review chrome disabled with the engine's
-     * reason. See {@link EditorModule}.
-     */
-    modules?: readonly EditorModule[];
-    /**
-     * The mode the editor opens in — one prop, matching the toolbar's three-state pill.
-     *
-     * - `'edit'` — opens in editing, even when the document's `w:trackRevisions` asks for
-     *   tracked changes; the reader still moves between modes from the toolbar.
-     * - `'suggesting'` — opens in suggesting. It needs what suggesting always needs — a
-     *   review module and an {@link DocxEditorConfig.author} — and falls back to editing
-     *   with the reason published when either is missing.
-     * - `'view'` — read-only: every mutating command through the facade is refused, and
-     *   the toolbar cannot leave viewing.
-     * - Omitted — the DOCUMENT decides: a package carrying `w:trackRevisions` opens in
-     *   suggesting, everything else in editing.
-     */
-    mode?: 'edit' | 'view' | 'suggesting';
-    /**
-     * How painted tracked changes are coloured. Presentation only — nothing is serialised.
-     *
-     * - `'author'` (the DEFAULT) — every change takes its author's colour from the
-     *   `--doc-review-author-N` ramp, by order of first appearance, as Word does. Restyle a
-     *   slot under `.docx-editor` to change the ramp.
-     * - `'kind'` — insertions green, deletions red, so "added" and "removed" are what a
-     *   glance tells apart, whoever proposed them.
-     * - {@link RevisionAuthorAssignments} — style the named authors; `others` decides
-     *   whether the rest take the ramp (the default) or the kind colours.
-     *
-     * The opening value. In React this is authored declaratively — `DocxEditor.ColorByChangeType`
-     * and `DocxEditor.AuthorStyle` compose and apply it, seeding this config for the first
-     * paint — so React hosts never pass it by hand; it is the entry for headless hosts. Read
-     * the document's resolved roster with `getReviewAuthors`. Applies wherever revision
-     * markup paints: the full all-markup view needs a review module registered; without one
-     * the proposed view still marks surviving insertions.
-     */
-    revisionStyles?: RevisionStyles;
-    /** Override raster decode for insert/replace image commands; defaults to browser/headless. */
-    imageDecodePort?: ImageDecodePort;
-    /**
-     * The scale to open at, as a fixed number.
-     *
-     * Supplying one also picks the mode: an editor given a `zoom` and no `zoomMode` opens
-     * FIXED at that value and stays there. An embedder that pinned 100% keeps 100%.
-     */
-    zoom?: number;
-    /**
-     * Where the scale comes from. Defaults to `'auto'` — fit the page width, between 50% and
-     * 100% — unless {@link DocxEditorConfig.zoom} is supplied, which means fixed.
-     *
-     * `'auto'` leaves a window wide enough for the sheet exactly where it is today and shrinks
-     * a narrower one instead of growing a horizontal scrollbar. Pass `{ type: 'fixed' }` for
-     * the old unconditional behaviour.
-     */
-    zoomMode?: ZoomMode | 'auto';
-    onFontError?: (error: EditorFontError) => void;
-    /** Localized labels for table insertion furniture on the painted surface. */
-    tableInteractionLabel?: (key: 'table.insertRowBelow' | 'table.insertColumnRight') => string;
-}
-/**
- * Which measurer the current document's layout runs on, and whether shaped resolution is
- * still in flight. Returned by {@link DocxEditorInstance.fontMeasurement}.
- */
-interface FontMeasurementState {
-    /** `fixed` estimates advance widths; `shaped` measures real font bytes with HarfBuzz. */
-    readonly measurer: 'fixed' | 'shaped';
-    /** True while font resolution for the current document is still running. */
-    readonly resolving: boolean;
-    /** The shaped measurer's identity (admitted face hashes); absent while fixed. */
-    readonly producer?: string;
-}
-/**
- * The host chrome that answers the engine's hyperlink gestures.
- *
- * A CLICK on an external link and Ctrl/Cmd+K both mean "the user wants the link UI", and the
- * engine deliberately does not know what that looks like. Registered rather than passed at
- * construction because the chrome mounts after the editor does, and it survives a document
- * reload — the surface is rebuilt, the handlers are not.
- */
-interface HyperlinkChromeHandlers {
-    /** A plain click on an external or inert link: show the popover at `activation.rect`. */
-    readonly onPopover?: (activation: HyperlinkActivation) => void;
-    /** Ctrl/Cmd+K: open insert-or-edit for the selection. */
-    readonly onRequest?: () => void;
-}
-/**
- * The concrete facade type: the full `Editor` contract plus the instance-only surface.
- *
- * `surface`, `stateVersion`, `attach` and `detach` live HERE rather than on `Editor`:
- * they are what a store binding and a mounting host need, not what document commands
- * need. Production adapters program against `Editor` for everything else.
- */
-interface DocxEditorInstance extends Editor {
-    /** Bumps on mount, detach, destroy, and document reload — guards async image intents. */
-    readonly mountGeneration: number;
-    /**
-     * The underlying paginated surface for harnesses and tests that need capabilities the
-     * contract does not carry yet (select-all, node-id addressed selection).
+     * The underlying paginated surface for harnesses and tests that need capabilities the
+     * contract does not carry yet (select-all, node-id addressed selection).
      */
     readonly surface: PaginatedSurface | null;
     /**
@@ -1225,6 +439,8 @@ interface DocxEditorInstance extends Editor {
      * command needs.
      */
     setHyperlinkChrome(handlers: HyperlinkChromeHandlers): Unsubscribe;
+    /** Wire the host equation popover to painted equation clicks. */
+    setEquationChrome(handlers: EquationChromeHandlers): Unsubscribe;
     /**
      * Monotonic version of the observable editor state. Bumps whenever anything
      * `snapshot()` reports could have moved — a committed change, a selection move, zoom,
@@ -1592,6 +808,76 @@ declare function finalizeImageOverlayInteraction(options: {
     readonly anchorFrameOrigin: AnchorFrameOrigin | null;
 }): FinalizedImageOverlayInteraction;
 
+/**
+ * How a section-addressed op should name the section a caret is in.
+ *
+ * `w:sectPr` lives on the body story, so the op can only name BODY content — and a caret in a
+ * header or a note is not body content. The three answers are genuinely different, and
+ * collapsing them to "a paragraph or `null`" is what let an unaddressable section quietly
+ * become a document-wide write.
+ */
+type SectionAnchor = 
+/** Name this body paragraph. Its section is the one the caret is in. */
+{
+    readonly kind: 'anchor';
+    readonly paragraphId: string;
+}
+/** One section: an anchor names nothing extra, so the op may omit it. */
+ | {
+    readonly kind: 'whole-document';
+}
+/**
+ * Several sections, and the caret's holds no paragraph to name.
+ *
+ * An omitted anchor here would write EVERY section, which is what `scope: 'document'` is
+ * for — so answering it to a `scope: 'section'` request changes sections nobody asked
+ * about. There is no anchor that reaches an empty final section: one exists only when every
+ * paragraph already closes an earlier section, so nothing sits at or after it.
+ */
+ | {
+    readonly kind: 'unaddressable';
+};
+
+/**
+ * Every field of the Paragraph dialog, in the units the rest of this contract uses:
+ * points for spacing, TWIPS for indents.
+ *
+ * An omitted field is left as authored. Where `null` is allowed it REMOVES the setting,
+ * which is not the same as writing a zero — a zero blocks the cascade, a removal lets the
+ * style through again.
+ */
+interface SurfaceParagraphFormat {
+    readonly alignment?: 'left' | 'center' | 'right' | 'both';
+    readonly spaceBeforePt?: number | null;
+    readonly spaceAfterPt?: number | null;
+    readonly lineSpacing?: {
+        readonly rule: 'multiple' | 'exact' | 'atLeast';
+        readonly value: number;
+    } | null;
+    readonly indentLeftTwips?: number | null;
+    readonly indentRightTwips?: number | null;
+    /** ONE signed first-line offset: negative is a hanging indent (§17.3.1.12). */
+    readonly indentFirstLineTwips?: number | null;
+    readonly contextualSpacing?: boolean;
+    readonly keepNext?: boolean;
+    readonly keepLines?: boolean;
+    readonly widowControl?: boolean;
+    readonly pageBreakBefore?: boolean;
+    /**
+     * Replace the paragraph's custom tab stops. An empty list CLEARS them, which is what Word's
+     * "Clear All" does; omit the field to leave them as authored.
+     */
+    readonly tabStops?: readonly ParagraphTabStop[];
+}
+/** One property in a batched paragraph write. */
+interface ParagraphPropertyEdit {
+    readonly localName: string;
+    /** A null-valued attribute REMOVES that attribute; see `setParagraphProperty`. */
+    readonly attributes?: Record<string, string | null>;
+    /** Keep the attributes this entry does not name, for multi-setting elements. */
+    readonly mergeAttributes?: boolean;
+}
+
 /**
  * How an edit is written.
  *
@@ -1723,6 +1009,7 @@ interface PaginatedSurfaceOptions {
      * activation (see the navigation module's single `window.open` gate).
      */
     readonly onHyperlinkPopover?: (activation: HyperlinkActivation) => void;
+    readonly onEquationPopover?: (activation: EquationActivation) => void;
     /**
      * Ctrl/Cmd+K — Word's Insert Hyperlink. The engine reports the request; the host's chrome
      * decides what a link dialog looks like. A host that passes nothing leaves the key alone
@@ -1789,7 +1076,27 @@ interface SurfaceFormatting {
      * touched paragraph's and `mixed` reports the disagreement per field, because a ruler
      * must draw its handles somewhere and Word draws them at the first selected paragraph.
      */
-    readonly indent: IndentFormatting | null;
+    readonly indent: IndentFormatting | null;
+    /**
+     * The paragraph flags the Paragraph dialog shows as checkboxes, or null when the
+     * selection's paragraphs disagree about that one.
+     *
+     * `contextualSpacing` is "Don't add space between paragraphs of the same style"; the
+     * other four are its Pagination block. Each is read from the cascade, so a flag a STYLE
+     * sets reads as on — which is what a checkbox has to show.
+     */
+    readonly paragraphFlags: ParagraphFlags;
+    /**
+     * The paragraph's resolved custom tab stops, cascade included, or null when the selection
+     * disagrees or nothing is loaded. Positions in TWIPS, like every other measurement a
+     * control writes back.
+     */
+    readonly tabStops: readonly ParagraphTabStop[] | null;
+    /**
+     * Which of the paragraph-level reads above are `null` because the selection DISAGREES,
+     * as opposed to because nothing states them. See {@link ParagraphDisagreements}.
+     */
+    readonly disagrees: ParagraphDisagreements;
 }
 /**
  * Where the last pass spent its time, and how much work it actually did.
@@ -1926,6 +1233,8 @@ interface PaginatedSurface {
     /** One-based page at the caret, or at the centre of the mounted viewport. */
     currentPage(mode?: 'viewport' | 'caret'): number;
     type(text: string): void;
+    /** Author one explicit tracked text change without changing the editing mode. */
+    proposeTextChange(kind: 'insertion' | 'deletion' | 'replacement', text: string, author?: string): boolean;
     /**
      * Queue plain typed text for a batched commit at the caret.
      *
@@ -2099,374 +1408,1262 @@ interface PaginatedSurface {
         readonly mergeAttributes?: boolean;
     }): void;
     /**
-     * Word's Clear All Formatting: direct run properties off the selected text, and every
-     * paragraph the selection touches back to the default style with its direct paragraph
-     * properties and mark dropped.
+     * Several paragraph properties in ONE transaction, so a dialog is one undo step.
+     *
+     * `setParagraphProperty` is this with a single entry. A dialog that fired one call per
+     * field would leave the user pressing Ctrl+Z five times to undo one OK, and would paint
+     * four intermediate layouts on the way.
+     */
+    setParagraphProperties(entries: readonly ParagraphPropertyEdit[]): void;
+    /**
+     * The Paragraph dialog as ONE write: alignment, indents, spacing, line spacing and the
+     * five paragraph flags, over every paragraph the selection touches.
+     *
+     * One transaction, so pressing OK is one undo step and the page repaints once. An omitted
+     * field is left as authored; `null` where the type allows it REMOVES the setting so the
+     * style supplies it again. Returns whether anything was written.
+     */
+    setParagraphFormat(update: SurfaceParagraphFormat): boolean;
+    /**
+     * Word's Clear All Formatting: direct run properties off the selected text, and every
+     * paragraph the selection touches back to the default style with its direct paragraph
+     * properties and mark dropped.
+     *
+     * Only what the document states DIRECTLY — formatting inherited from a style survives, so
+     * the text falls back to its style rather than to nothing. Properties an op cannot name
+     * (`w:rStyle`, `w:lang`, `w:sectPr`, `w:pBdr`) are preserved for the same reason every
+     * other write preserves them.
+     */
+    clearFormatting(): void;
+    /**
+     * Formatting as it stands at the selection, for a toolbar to reflect.
+     *
+     * With a typing format armed at the caret this reports what the NEXT characters typed
+     * will look like, not what the document holds — which is the answer a toolbar wants and
+     * the one Word gives.
+     */
+    formatting(): SurfaceFormatting;
+    /**
+     * The section the document declares: page size, margins, columns, orientation.
+     *
+     * What a ruler is made of, and what pagination is measured against.
+     */
+    sectionProperties(): SectionProperties;
+    /**
+     * The section GOVERNING one paragraph — what a ruler or dialog reflects when the caret sits
+     * in a multi-section document.
+     *
+     * Body content answers for itself, whatever story is open. A header or footer belongs to the
+     * section that names its relationship, and a note to the section holding its reference mark.
+     * An id nothing settles falls back to the FIRST section: the tail is the document-wide answer
+     * and is wrong for everything not on the last page.
+     */
+    sectionPropertiesAt(paragraphId: string): SectionProperties;
+    /**
+     * How a section-addressed op should name the section `paragraphId` is in.
+     *
+     * `w:sectPr` lives on the body story, so such an op can only name body content — and a caret
+     * in a header or a note is not body content. Passing that caret straight through made every
+     * section write from furniture fail `unknown-paragraph`.
+     */
+    sectionAnchorParagraphAt(paragraphId: string): SectionAnchor;
+    /**
+     * Write section page-setup fields — size, orientation, margins — as ONE undoable
+     * transaction. Twips throughout; omitted fields are left as authored. With
+     * `anchorParagraphId` only that paragraph's governing section is written (Word's
+     * "Apply to: This section"); without it, every section. Returns whether the write
+     * committed (a hostile value is refused by the op layer).
+     */
+    setSectionProperties(update: {
+        readonly pageWidthTwips?: number;
+        readonly pageHeightTwips?: number;
+        readonly orientation?: 'portrait' | 'landscape';
+        readonly marginTopTwips?: number;
+        readonly marginRightTwips?: number;
+        readonly marginBottomTwips?: number;
+        readonly marginLeftTwips?: number;
+        readonly anchorParagraphId?: string;
+    }): boolean;
+    /**
+     * Insert a next-page section break at the caret: the paragraph splits, and the head
+     * ends a new section cloning the governing section's page setup — Word's Layout >
+     * Breaks > Next Page. One undoable step. Returns whether the break committed.
+     */
+    insertSectionBreak(): boolean;
+    /** The layout session, so a host or a test can see how much work a pass actually did. */
+    layoutSession(): {
+        readonly stats: {
+            readonly placed: number;
+            readonly total: number;
+            readonly reusedPages: number;
+        };
+    };
+    /**
+     * The hyperlink lane: what link the caret is in, and the insert / retarget / unlink verbs.
+     *
+     * Every verb is one `transact`, so it is one undo step. Targets going IN are host-supplied
+     * and pass the package's own URL allowlist; targets coming OUT are the sanitized
+     * projection, so a caller cannot accidentally hand a refused scheme to a sink.
+     */
+    readonly hyperlinks: HyperlinkOps;
+    readonly equations: EquationOps;
+    /**
+     * Content-control chrome, form-fill navigation, and value / remove verbs.
+     *
+     * Value and remove commit through `session.applyTreeOps` — the same write path as typing.
+     * Show-all and form-fill are surface chrome and never reflow layout.
+     */
+    readonly contentControls: ContentControlOps;
+    /** Whether a `rows`×`cols` table can be inserted at the caret. */
+    canInsertTable(rows: number, cols: number): boolean;
+    /**
+     * Insert an empty `rows`×`cols` table at the caret, columns evenly dividing the content
+     * width of the caret's section, and leave the caret in the first cell.
+     */
+    insertTable(rows: number, cols: number): boolean;
+    /** Whether the addressed (or caret-local) body TOC can be refreshed. */
+    canRefreshToc(tocId?: string): boolean;
+    /** Whether a generated body TOC can be inserted before the caret paragraph. */
+    canInsertToc(): boolean;
+    /** Insert and populate a generated body TOC before the caret paragraph. */
+    insertToc(): boolean;
+    /** Refresh cached TOC entries and/or page numbers through the two-pass layout pipeline. */
+    refreshToc(tocId?: string, mode?: 'entire' | 'pageNumbers'): boolean;
+    /** Whether a body paragraph belongs to a detected TOC boundary or cached result. */
+    isInsideToc(paragraphId: string): boolean;
+    /**
+     * Bookmark jumps and the ONE external-activation gate. A host's popover "open" action
+     * calls `openExternal`; nothing else in the engine may call `window.open`.
+     */
+    readonly navigation: SurfaceNavigation;
+    /**
+     * Pin the current selection so it stays VISIBLY selected while focus is elsewhere.
+     *
+     * A document has one selection: the moment a panel focuses an input of its own the browser
+     * takes the highlight off the text, which is when the user most needs to see what the panel
+     * is about to act on. This draws the range on the engine's own overlay instead, so it
+     * survives the focus move. The MODEL selection is untouched — the op the panel finally runs
+     * addresses the same characters it always would.
+     *
+     * The pin releases itself when the caret leaves the range (either edge counts as inside),
+     * which is what lets a host close its panel on "the user clicked somewhere else" without
+     * every adapter reimplementing that comparison.
+     */
+    retainSelection(): SelectionPin;
+    /** Drop one owned pin. Another owner's pin remains visible. */
+    releaseSelection(pin: SelectionPin): void;
+    /** The pinned range, or null once it was released or escaped. */
+    retainedSelection(): SemanticSelection | null;
+    /**
+     * How edits are written right now.
+     *
+     * Lives on the SURFACE, not on the store. The store's write vocabulary stays explicit —
+     * an op says whether it is tracked — and the surface is the one thing that knows a
+     * keystroke happened, so it is the right place to decide what that keystroke becomes.
+     */
+    editingMode(): SurfaceEditingMode;
+    setEditingMode(mode: SurfaceEditingMode): void;
+    /**
+     * Every author with a revision in the CURRENT layout, mapped to Word's colour slot by
+     * order of first appearance. One map instance per layout, so a caller can key caches on
+     * its identity.
+     */
+    revisionAuthors(): ReadonlyMap<string, number>;
+    /**
+     * Replace how tracked changes are coloured, live. Paint-level: the pages repaint without
+     * remeasuring a line, and the caret, selection and undo history stay where they are.
+     */
+    setRevisionStyles(colors: RevisionStyles | undefined): void;
+    /**
+     * Commit ops that came from automation, through the gate a keystroke goes through.
+     *
+     * The narrow entry an automation host writes with, and the reason it needs one: reaching
+     * `session.applyTreeOps` past this skips the editing-mode gate entirely — a document open for
+     * viewing accepts a scripted edit, and a suggesting document records one as a permanent
+     * change with no proposal and no author. Here, viewing refuses, suggesting attributes, the
+     * refusal reason is reported like any other, and the pages repaint from the commit.
+     *
+     * The ops address the story the CALLER named, whatever story the reader is in: the caller
+     * identified its target before calling, so following the caret into a header would write
+     * somewhere else entirely. They default to the body rather than to the reader's story.
+     *
+     * They arrive as a BUILDER, given a way to mint the relationship an external hyperlink names.
+     * That mint changes the package outside the transaction and outside the undo stack, so it must not
+     * happen until the mode has allowed the write — a link minted while the batch was still being
+     * planned left its target in a read-only document's `.rels`. A builder answering null means the
+     * target is one this engine will not author, and the write is refused having changed nothing.
+     */
+    applyAutomationOps(staged: (relate: (url: string) => string | null) => readonly TreeDocOp[] | null, scope?: StoryScope): TreeApplyResult;
+    /**
+     * Commit review ops — accept, reject, a new comment — through the SAME path a keystroke
+     * takes: layout, paint, and a caret clamped to what the document now holds.
+     *
+     * Applying them straight to the session skipped all three. Rejecting an insertion left the
+     * pages painting text the tree no longer had, every card anchored where it used to be, and
+     * the caret past the end of the paragraph — after which every keystroke was refused with
+     * `offset-out-of-range` until the user happened to click somewhere else.
+     */
+    commitReviewOps(run: () => {
+        readonly committed: boolean;
+        readonly reason?: unknown;
+    }): void;
+    /**
+     * The layout as last PUBLISHED, without forcing pending work.
+     *
+     * `layout()` flushes first, which is right for a caller that is about to act on geometry
+     * and wrong for one that merely decorates it. The review rail read through `layout()` and
+     * so forced a synchronous full pass on every keystroke — eleven seconds per read on a
+     * 2432-block document. A card whose anchor is one frame stale is invisible; the paint that
+     * follows the flush republishes it.
+     */
+    publishedLayout(): SemanticLayout;
+    /**
+     * Paint-scale coordinate context for overlay chrome.
+     *
+     * Internal seam — not part of the public editor contract. Image overlay uses the same
+     * `zoom * 96/72` scale and per-page horizontal offsets the painter applied.
+     */
+    overlayCoordinates(): SurfaceOverlayCoordinates;
+    /**
+     * The comment or tracked change the caret is in, as the painted bands report it.
+     *
+     * ONE source for "which item is open". The band under the text and the card beside it are
+     * two views of the same answer, and deriving it twice let them disagree — the card closed
+     * while the text stayed highlighted.
+     */
+    activeReviewKey(): string | null;
+    /**
+     * Open THIS item, named by key, for as long as `selection` stays the live one.
+     *
+     * Without it the caret is the only evidence of which card is open, and a caret cannot name a
+     * card when two cards cover exactly the same characters: `w:ins` wrapping `w:del` — content
+     * one reviewer added and another struck — gives the insertion and the deletion one identical
+     * range, and every click on either card classified back to whichever the queue happened to
+     * list first. The reader clicked "Deleted" and watched "Added" light up.
+     *
+     * A key, not a position, because the position is precisely what is ambiguous. It holds only
+     * while the selection matches; a pointer or keyboard move hands the answer back to the caret,
+     * which is what lets the reader step out of a card by clicking away from it.
+     *
+     * `selection` is what activation wants installed, and it is installed HERE rather than by a
+     * `setSelection` of the caller's own so that the pin is up before anything is published. The
+     * other order repainted the bands and reported state while the caret was still the only
+     * evidence, so a host saw the wrong twin active for one frame and then a correction. Omit it
+     * to pin against the live selection, which is what a header or note scope has already set.
+     */
+    activateReview(key: string, selection?: SemanticSelection): void;
+    /**
+     * The key {@link activateReview} pinned, or null once its selection is no longer live.
+     *
+     * Exists so nothing outside the surface keeps its own copy of "the selection came from
+     * opening a card". `selectionPlacement` needs that fact to stay quiet about offering a
+     * comment on text the reader only selected by opening a card over it, and the copy it used to
+     * keep was set on one of activation's three branches, so a header card offered to comment on
+     * itself.
+     */
+    activatedReviewKey(): string | null;
+    /**
+     * Close the open item until the caret next moves.
+     *
+     * What a click on the canvas means. The caret does not move when someone clicks the grey
+     * around the page, so nothing else would ever put the item away.
+     */
+    dismissActiveReview(): void;
+    /**
+     * Revision kinds the CARET must not activate, or null for none.
+     *
+     * The review rail filters what it renders (structural and format cards are hidden by
+     * default), but {@link activeReviewKey} used to compute over the unfiltered queue — a
+     * click on tracked text under a format change activated a card the rail does not draw,
+     * and nothing on screen lit up. A host that filters its list tells the surface, so the
+     * band and the visible cards stay one answer.
+     */
+    setReviewActivationExclusions(kinds: readonly ReviewRevisionKind[] | null): void;
+    /**
+     * `bookmarkName -> position` over the current revision, for resolving an internal link.
+     * First in document order wins a duplicate name, matching Word.
+     */
+    bookmarks(): BookmarkIndex;
+    /** The selected text, for copy and cut. */
+    selectedText(): string;
+    /** Remove the selection, if any. Returns whether anything was deleted. */
+    deleteSelection(): boolean;
+    navigate(command: NavigationCommand, extend?: boolean): void;
+    /** Reverse the last history entry and put the caret back where it was made. */
+    undo(): void;
+    redo(): void;
+    /**
+     * Refresh table insertion furniture labels without remounting or relayout.
      *
-     * Only what the document states DIRECTLY — formatting inherited from a style survives, so
-     * the text falls back to its style rather than to nothing. Properties an op cannot name
-     * (`w:rStyle`, `w:lang`, `w:sectPr`, `w:pBdr`) are preserved for the same reason every
-     * other write preserves them.
+     * @public
      */
-    clearFormatting(): void;
+    refreshTableInteractionLabels(): void;
+    focus(): void;
     /**
-     * Formatting as it stands at the selection, for a toolbar to reflect.
+     * Refresh table insertion furniture labels without remounting the surface.
      *
-     * With a typing format armed at the caret this reports what the NEXT characters typed
-     * will look like, not what the document holds — which is the answer a toolbar wants and
-     * the one Word gives.
+     * @public
      */
-    formatting(): SurfaceFormatting;
+    setTableInteractionLabel(resolver: (key: 'table.insertRowBelow' | 'table.insertColumnRight') => string): void;
+    destroy(): void;
     /**
-     * The section the document declares: page size, margins, columns, orientation.
+     * The section a painted page belongs to, and the page that section starts on.
      *
-     * What a ruler is made of, and what pagination is measured against.
+     * Published because opening a furniture story without a page opens it without a section, and
+     * the section is what the ruler clamps to and what a new table's grid is divided from. One
+     * header part can serve several sections, so only the page settles which one the reader is
+     * looking at.
      */
-    sectionProperties(): SectionProperties;
+    sectionAtPage(pageIndex: number): {
+        sectionIndex: number;
+        sectionStart: number;
+    };
+    /** Active editing view — body, or an open header/footer story by rId. */
+    activeScope(): ViewScope;
+    /** Activate a view scope. Returns false when a header/footer rId cannot be opened. */
+    setActiveScope(scope: ViewScope): boolean;
     /**
-     * The section GOVERNING one paragraph — what a ruler or dialog reflects when the
-     * caret sits in a multi-section document. Falls back to the body-level section for
-     * an unknown id.
+     * Open a header/footer story for editing on the painted surface.
+     * Refuses dangling / unknown relationship ids.
      */
-    sectionPropertiesAt(paragraphId: string): SectionProperties;
+    enterHeaderFooter(args: {
+        readonly rId: string;
+        readonly pageIndex?: number;
+        readonly sectionIndex?: number;
+        readonly kind?: 'header' | 'footer';
+        readonly variant?: 'default' | 'first' | 'even';
+        readonly position?: SemanticPosition;
+    }): boolean;
+    /** Leave furniture editing and restore the prior body selection. */
+    exitHeaderFooter(): void;
+    /** Chrome read-model for the open furniture scope, or null when editing the body. */
+    headerFooterState(): {
+        readonly editing: 'header' | 'footer' | null;
+        readonly sectionIndex: number;
+        readonly variant?: 'default' | 'first' | 'even';
+        readonly rId?: string;
+        readonly partName?: string;
+        readonly inherited?: boolean;
+        readonly titlePage?: boolean;
+        readonly evenAndOddHeaders?: boolean;
+        readonly headerDistanceTwips?: number;
+        readonly footerDistanceTwips?: number;
+    } | null;
     /**
-     * Write section page-setup fields — size, orientation, margins — as ONE undoable
-     * transaction. Twips throughout; omitted fields are left as authored. With
-     * `anchorParagraphId` only that paragraph's governing section is written (Word's
-     * "Apply to: This section"); without it, every section. Returns whether the write
-     * committed (a hostile value is refused by the op layer).
+     * Commit one package-level furniture lifecycle op (create/delete/link/unlink/options).
+     * Flushes layout so the next enter/rebind sees the new resolution.
      */
-    setSectionProperties(update: {
-        readonly pageWidthTwips?: number;
-        readonly pageHeightTwips?: number;
-        readonly orientation?: 'portrait' | 'landscape';
-        readonly marginTopTwips?: number;
-        readonly marginRightTwips?: number;
-        readonly marginBottomTwips?: number;
-        readonly marginLeftTwips?: number;
-        readonly anchorParagraphId?: string;
+    applyHeaderFooterLifecycle(op: {
+        readonly op: 'createHeaderFooter' | 'deleteHeaderFooter' | 'linkToPrevious' | 'unlinkFromPrevious' | 'setSectionFurnitureOptions';
+        readonly sectionIndex?: number;
+        readonly kind?: 'header' | 'footer';
+        readonly variant?: 'default' | 'first' | 'even';
+        readonly titlePage?: boolean;
+        readonly evenAndOddHeaders?: boolean;
+        readonly headerDistanceTwips?: number;
+        readonly footerDistanceTwips?: number;
+    }): {
+        readonly ok: true;
+    } | {
+        readonly ok: false;
+        readonly reason: string;
+    };
+    /** Insert an allowlisted page field at the caret in the open HF story. */
+    insertPageField(field: 'PAGE' | 'NUMPAGES' | 'SECTIONPAGES' | 'PAGE_X_OF_Y'): boolean;
+    /** Insert a footnote/endnote at the body caret. */
+    insertNote(noteKind: 'footnote' | 'endnote'): boolean;
+    deleteNote(noteKind: 'footnote' | 'endnote', noteId: number): boolean;
+    convertNote(fromKind: 'footnote' | 'endnote', noteId: number): boolean;
+    convertAllNotes(fromKind: 'footnote' | 'endnote'): boolean;
+    setNoteProperties(args: {
+        readonly scope: 'document' | 'section';
+        readonly sectionIndex?: number;
+        readonly footnote?: {
+            readonly numFmt?: string;
+            readonly numRestart?: string;
+            readonly position?: string;
+            readonly numStart?: number;
+        };
+        readonly endnote?: {
+            readonly numFmt?: string;
+            readonly numRestart?: string;
+            readonly position?: string;
+            readonly numStart?: number;
+        };
+    }): boolean;
+    enterNote(scopeId: string, position?: {
+        paragraphId: string;
+        offset: number;
     }): boolean;
+    exitNote(): void;
+    /** Resolved/authored note properties for the caret section — chrome read-model. */
+    notePropertiesState(): NotePropertiesStateSnapshot | null;
+    /** Plain-text preview for hover chrome — never returns markup. */
+    notePreviewText(scopeId: string): string | null;
+    /** Commit one table-command plan as a single store transaction. */
+    applyTableCommandPlan(plan: TableCommandPlan): ExecResult;
+}
+/**
+ * What opening a document produced: a mounted surface, or a refusal.
+ *
+ * A result rather than a throw, because every refusal here comes from FILE input — a package the
+ * bounded reader rejected, a part that exceeded a limit — and a malformed upload should surface
+ * as a message the host can show rather than an exception it has to catch.
+ */
+type OpenPaginatedResult = {
+    readonly ok: true;
+    readonly surface: PaginatedSurface;
+} | {
+    readonly ok: false;
+    readonly reason: string;
+    readonly detail?: string;
+};
+
+/** One URL to fetch and the face it claims to be. */
+interface FontUrlSource {
+    readonly url: string;
+    readonly family: string;
+    readonly weight: number;
+    readonly style: 'normal' | 'italic';
+    /**
+     * Expected `sha256:` content hash. When present, mismatching bytes are REFUSED —
+     * pin this for any URL not under the app's sole control.
+     */
+    readonly hash?: string;
+    readonly faceIndex?: number;
+}
+/**
+ * What to fetch, and under what limits.
+ *
+ * Only `sources` is required. Each carries its own expected hash, so bytes are trusted by
+ * CONTENT rather than by origin — a swapped asset fails admission even from a trusted host.
+ */
+interface LoadFontsRequest {
+    readonly sources: readonly FontUrlSource[];
+    /** Cache API bucket name; default `docx-editor-fonts`. */
+    readonly cacheName?: string;
+    /** Injectable for tests and CSP-constrained hosts; defaults to global `fetch`. */
+    readonly fetcher?: typeof fetch;
+    /** Per-font byte ceiling; defaults to the engine hard maximum. */
+    readonly maxFontBytes?: number;
+}
+/**
+ * Why one font did not load.
+ *
+ * Distinguished rather than collapsed to "failed" because the responses differ: `networkError`
+ * and `httpError` are worth retrying, while `hashMismatch` and `malformed` mean the bytes were
+ * not what the source claimed and retrying will fetch the same wrong thing.
+ */
+type FontLoadFailureReason = 'networkError' | 'httpError' | 'hashMismatch' | 'overLimit' | 'emptyResponse'
+/** The declared face itself is unusable (empty family, out-of-range weight); nothing was fetched. */
+ | 'invalidRequest'
+/** The bytes are not a font at all — most often an HTML error page served with 200. */
+ | 'malformed';
+/**
+ * One face that did not load, with whatever evidence the failure produced.
+ *
+ * Non-fatal: {@link LoadFontsResult} still carries every source that succeeded, and the affected
+ * family falls back to the engine's fixed measurement.
+ */
+interface FontLoadFailure {
+    readonly url: string;
+    readonly request: FontFaceRequest;
+    readonly reason: FontLoadFailureReason;
+    /** HTTP status for `httpError`; hashes for `hashMismatch`. */
+    readonly status?: number;
+    readonly expectedHash?: string;
+    readonly actualHash?: string;
+    readonly diagnostic?: string;
+}
+/**
+ * What one `loadFonts` call produced: the faces that arrived, plus the ones that did not.
+ *
+ * A `FontConfigurationFragment`, so it composes straight into `composeFontConfiguration`
+ * alongside other font sources. Partial success is the normal case — compose it even with
+ * failures present.
+ */
+interface LoadFontsResult extends FontConfigurationFragment {
+    readonly sources: readonly FontSource[];
+    readonly failures: readonly FontLoadFailure[];
+}
+/**
+ * Fetch app-specified font URLs into verified, cache-backed `FontSource`s.
+ *
+ * Fetches ONLY the URLs listed — never a default host or engine-chosen CDN — and never
+ * rejects for a per-source failure: the result carries every admitted source and a
+ * typed entry for every drop. Compose the result with `composeFontConfiguration`.
+ */
+declare function loadFonts(request: LoadFontsRequest): Promise<LoadFontsResult>;
+/**
+ * Turn font bytes you ALREADY hold into a `FontSource` — a file input, IndexedDB, a
+ * bundler import. `loadFonts` covers URLs; this covers everything else, so no caller has
+ * to hand-assemble the record or reach for a hashing helper.
+ *
+ * Returns a typed failure instead of throwing when the descriptor or the bytes are
+ * unusable, matching `loadFonts`: one bad face degrades itself, never its neighbours.
+ */
+declare function createFontSource(bytes: Uint8Array, request: FontFaceRequest & {
+    readonly faceIndex?: number;
+}, options?: {
+    readonly id?: string;
+    readonly maxFontBytes?: number;
+}): {
+    readonly source: FontSource;
+} | {
+    readonly failure: FontLoadFailure;
+};
+
+/**
+ * HOW a control reaches the engine — never WHETHER it is enabled.
+ *
+ * Enabled state has exactly one source: `toolbarCommandState(editor, slot)`, which
+ * asks `Editor.can`. The registry is static data and cannot know what the engine
+ * will honour at this selection, in this document, at this moment.
+ *
+ * There used to be a fourth member, `parityOnly`, meaning "visible but permanently
+ * disabled". It was a second, static answer to the question `Editor.can` already
+ * answers, and it went stale the moment the engine wired underline, strike, the four
+ * alignments, the list commands and the four value slots: the registry still said
+ * parity-only, React ignored it and ran them, and Vue believed it and rendered twelve
+ * WORKING commands permanently disabled. A slot the engine has not wired needs no
+ * registry flag — `commandForSlot` answers null and `toolbarCommandState` disables the
+ * control with the engine's own words ("not wired to an editor command").
+ */
+type ChromeControlState = 
+/**
+ * Dispatched as one fixed engine command: enabled when
+ * `Editor.can(commandForSlot(slot))` succeeds, a click runs
+ * `runToolbarCommand(editor, slot)`. The command is resolved from the SLOT id
+ * through `commandForSlot` in toolbar-commands.ts — the one command table both
+ * adapters share. A slot with no row there is simply not wired YET, and says so
+ * through the engine rather than through this descriptor.
+ */
+{
+    readonly kind: 'command';
+}
+/**
+ * Dispatched with a PICKED value: `commandForSlotValue(slot, value)`. Enabled when
+ * the engine would honour a well-formed value right now (`toolbarCommandState`
+ * probes for exactly that), so the control needs chrome that produces a value — a
+ * font list, a size, a colour — before a click means anything.
+ *
+ * A distinct kind because 'command' cannot describe it: there is no fixed command
+ * to hand `Editor.can`, and a bare click has nothing to send.
+ */
+ | {
+    readonly kind: 'value';
+}
+/** `Editor.save()` — not a command (see `runSave`). */
+ | {
+    readonly kind: 'save';
+}
+/**
+ * `Editor.load()` — not a command either, and the exact twin of `save`: bytes cross the
+ * boundary between the host and the engine, and only the host can produce them. The
+ * control needs chrome that reads a file (a picker, a drop target) before a click means
+ * anything, so a bare click has nothing to send — the same reason `save` is not `command`.
+ *
+ * A fourth kind rather than reusing `save` because the two dispatch in opposite
+ * directions, and an adapter branching on `kind` must be able to tell them apart. Unlike
+ * the deleted `parityOnly`, this one IS named by a control (`file.open`).
+ */
+ | {
+    readonly kind: 'load';
+};
+/**
+ * The SHAPE a control renders as (task M6V.1).
+ *
+ * The legacy toolbar is not a row of uniform icon buttons: it mixes labelled dropdowns
+ * (`Normal`, `Arial`, alignment, line spacing), numeric steppers with visible values
+ * (zoom `- 100% +`, size `- 26 +`), split colour controls (a glyph over a colour swatch
+ * with its own caret), and a mode pill (`Editing`). Rendering all of them as icon
+ * buttons is the difference an owner review called out as "not visual parity" — the
+ * regions were all present and it still did not look like the product.
+ */
+/** `modePill` is deliberately absent. It was declared, never used by any control, and
+ *  rendered nothing — the editing-mode control below is a `dropdown`, which is what the
+ *  legacy product shows. A shape no descriptor names is a branch adapters must implement
+ *  and can never exercise. */
+type ChromeControlShape = 'icon' | 'stepper' | 'dropdown' | 'colorSplit';
+/**
+ * One toolbar control as the registry describes it — what it renders as, never whether it is
+ * enabled.
+ *
+ * Enabled state has exactly ONE source, `toolbarCommandState`, which asks the engine. A
+ * descriptor carrying its own disabled flag would be a second answer that goes stale the moment
+ * the engine wires the slot.
+ *
+ * @public
+ */
+interface ChromeControl<Id extends string = string> {
+    /** Stable control id, unique WITHIN its group. Public API; renames are breaking. */
+    readonly id: Id;
+    /** How it renders. Defaults to `icon`. */
+    readonly shape?: ChromeControlShape;
+    /** Displayed value for a stepper or dropdown (an i18n key, or a literal for numbers). */
+    readonly valueText?: string;
+    /** Swatch colour for a `colorSplit` control. */
+    readonly swatch?: string;
+    /** i18n key for the accessible name and tooltip. Never hardcoded English. */
+    readonly labelKey: string;
+    /** Material Symbols path data, or null for a non-icon control (a picker). */
+    readonly paths: readonly string[] | null;
+    /** For pickers: the i18n key of the placeholder value shown. */
+    readonly valueKey?: string;
+    readonly state: ChromeControlState;
+}
+/**
+ * One toolbar group: the taxonomy both adapters derive their default arrangement FROM.
+ *
+ * Never hand-list controls in an adapter — a default toolbar is built by walking `CHROME_GROUPS`,
+ * so a slot added here appears in React and Vue without either being edited.
+ *
+ * @public
+ */
+interface ChromeGroup<Id extends string = string, ControlId extends string = string> {
+    /** Stable group id. Public API; renames are breaking. */
+    readonly id: Id;
+    readonly labelKey: string;
     /**
-     * Insert a next-page section break at the caret: the paragraph splits, and the head
-     * ends a new section cloning the governing section's page setup — Word's Layout >
-     * Breaks > Next Page. One undoable step. Returns whether the break committed.
+     * Not part of the DEFAULT toolbar arrangement. The chrome spec shows these
+     * controls only in a context the engine does not model yet (an image or table
+     * selection), or not at all (save belongs in the host's File menu, never in the
+     * bar). Their slots stay public for composition — a host can still place
+     * `image.insert` or `file.save` explicitly — but the default chrome is the
+     * registry's default bar, which ends at the editing-mode picker.
      */
-    insertSectionBreak(): boolean;
-    /** The layout session, so a host or a test can see how much work a pass actually did. */
-    layoutSession(): {
-        readonly stats: {
-            readonly placed: number;
-            readonly total: number;
-            readonly reusedPages: number;
+    readonly contextual?: true;
+    readonly controls: readonly ChromeControl<ControlId>[];
+}
+/**
+ * The complete chrome, in bar order. Literal-typed (`as const`) so the slot-id
+ * vocabulary below is derived from the data and cannot drift from it.
+ *
+ * Taxonomy taste: ids are short, lowercaseCamel, and never repeat their group's name
+ * (`alignment.left`, not `alignment.alignLeft`; `font.family`, not `font.fontFamily`).
+ */
+declare const CHROME_GROUPS: readonly [{
+    readonly id: "history";
+    readonly labelKey: "formattingBar.groups.history";
+    readonly controls: readonly [{
+        readonly id: "undo";
+        readonly labelKey: "formattingBar.undoShortcut";
+        readonly paths: readonly string[];
+        readonly state: {
+            readonly kind: "command";
+        };
+    }, {
+        readonly id: "redo";
+        readonly labelKey: "formattingBar.redoShortcut";
+        readonly paths: readonly string[];
+        readonly state: {
+            readonly kind: "command";
+        };
+    }];
+}, {
+    readonly id: "zoom";
+    readonly labelKey: "formattingBar.groups.zoom";
+    readonly controls: readonly [{
+        readonly id: "level";
+        readonly shape: "stepper";
+        readonly valueText: "100%";
+        readonly labelKey: "formattingBar.groups.zoom";
+        readonly paths: null;
+        readonly valueKey: "zoom.zoomLevel";
+        readonly state: {
+            readonly kind: "command";
+        };
+    }];
+}, {
+    readonly id: "styles";
+    readonly labelKey: "formattingBar.groups.styles";
+    readonly controls: readonly [{
+        readonly id: "style";
+        readonly shape: "dropdown";
+        readonly labelKey: "styles.selectAriaLabel";
+        readonly paths: null;
+        readonly valueKey: "styles.normalText";
+        readonly state: {
+            readonly kind: "value";
+        };
+    }];
+}, {
+    readonly id: "font";
+    readonly labelKey: "formattingBar.groups.font";
+    readonly controls: readonly [{
+        readonly id: "family";
+        readonly shape: "dropdown";
+        readonly labelKey: "font.selectAriaLabel";
+        readonly paths: null;
+        readonly valueKey: "font.sansSerif";
+        readonly state: {
+            readonly kind: "value";
+        };
+    }, {
+        readonly id: "size";
+        readonly shape: "stepper";
+        readonly valueText: "11";
+        readonly labelKey: "fontSize.listLabel";
+        readonly paths: null;
+        readonly valueKey: "fontSize.label";
+        readonly state: {
+            readonly kind: "value";
+        };
+    }];
+}, {
+    readonly id: "text";
+    readonly labelKey: "formattingBar.groups.textFormatting";
+    readonly controls: readonly [{
+        readonly id: "bold";
+        readonly labelKey: "formattingBar.boldShortcut";
+        readonly paths: readonly string[];
+        readonly state: {
+            readonly kind: "command";
+        };
+    }, {
+        readonly id: "italic";
+        readonly labelKey: "formattingBar.italicShortcut";
+        readonly paths: readonly string[];
+        readonly state: {
+            readonly kind: "command";
+        };
+    }, {
+        readonly id: "underline";
+        readonly labelKey: "formattingBar.underlineShortcut";
+        readonly paths: readonly string[];
+        readonly state: {
+            readonly kind: "command";
+        };
+    }, {
+        readonly id: "strike";
+        readonly labelKey: "formattingBar.strikethrough";
+        readonly paths: readonly string[];
+        readonly state: {
+            readonly kind: "command";
+        };
+    }, {
+        readonly id: "color";
+        readonly shape: "colorSplit";
+        readonly swatch: "#ff0000";
+        readonly labelKey: "formattingBar.fontColor";
+        readonly paths: readonly string[];
+        readonly state: {
+            readonly kind: "value";
+        };
+    }, {
+        readonly id: "highlight";
+        readonly shape: "colorSplit";
+        readonly swatch: "#ffff00";
+        readonly labelKey: "formattingBar.highlightColor";
+        readonly paths: readonly string[];
+        readonly state: {
+            readonly kind: "value";
+        };
+    }, {
+        readonly id: "link";
+        readonly labelKey: "formattingBar.insertLinkShortcut";
+        readonly paths: readonly string[];
+        readonly state: {
+            readonly kind: "command";
+        };
+    }];
+}, {
+    readonly id: "script";
+    readonly labelKey: "formattingBar.groups.script";
+    readonly controls: readonly [{
+        readonly id: "super";
+        readonly labelKey: "formattingBar.superscript";
+        readonly paths: readonly string[];
+        readonly state: {
+            readonly kind: "command";
+        };
+    }, {
+        readonly id: "sub";
+        readonly labelKey: "formattingBar.subscript";
+        readonly paths: readonly string[];
+        readonly state: {
+            readonly kind: "command";
+        };
+    }];
+}, {
+    readonly id: "alignment";
+    readonly labelKey: "formattingBar.groups.alignment";
+    readonly controls: readonly [{
+        readonly id: "left";
+        readonly labelKey: "alignment.alignLeft";
+        readonly paths: readonly string[];
+        readonly state: {
+            readonly kind: "command";
+        };
+    }, {
+        readonly id: "center";
+        readonly labelKey: "alignment.center";
+        readonly paths: readonly string[];
+        readonly state: {
+            readonly kind: "command";
+        };
+    }, {
+        readonly id: "right";
+        readonly labelKey: "alignment.alignRight";
+        readonly paths: readonly string[];
+        readonly state: {
+            readonly kind: "command";
+        };
+    }, {
+        readonly id: "justify";
+        readonly labelKey: "alignment.justify";
+        readonly paths: readonly string[];
+        readonly state: {
+            readonly kind: "command";
+        };
+    }];
+}, {
+    readonly id: "list";
+    readonly labelKey: "formattingBar.groups.listFormatting";
+    readonly controls: readonly [{
+        readonly id: "bullet";
+        readonly labelKey: "lists.bulletList";
+        readonly paths: readonly string[];
+        readonly state: {
+            readonly kind: "command";
+        };
+    }, {
+        readonly id: "numbered";
+        readonly labelKey: "lists.numberedList";
+        readonly paths: readonly string[];
+        readonly state: {
+            readonly kind: "command";
+        };
+    }, {
+        readonly id: "outdent";
+        readonly labelKey: "lists.decreaseIndent";
+        readonly paths: readonly string[];
+        readonly state: {
+            readonly kind: "command";
+        };
+    }, {
+        readonly id: "indent";
+        readonly labelKey: "lists.increaseIndent";
+        readonly paths: readonly string[];
+        readonly state: {
+            readonly kind: "command";
+        };
+    }, {
+        readonly id: "lineSpacing";
+        readonly shape: "dropdown";
+        readonly labelKey: "lineSpacing.label";
+        readonly paths: readonly string[];
+        readonly state: {
+            readonly kind: "command";
+        };
+    }];
+}, {
+    readonly id: "format";
+    readonly labelKey: "formattingBar.clearFormatting";
+    readonly controls: readonly [{
+        readonly id: "clear";
+        readonly labelKey: "formattingBar.clearFormatting";
+        readonly paths: readonly string[];
+        readonly state: {
+            readonly kind: "command";
+        };
+    }];
+}, {
+    readonly id: "review";
+    readonly labelKey: "formattingBar.commentsAndChanges";
+    readonly controls: readonly [{
+        readonly id: "comments";
+        readonly shape: "icon";
+        readonly labelKey: "formattingBar.commentsAndChanges";
+        readonly paths: readonly string[];
+        readonly state: {
+            readonly kind: "command";
+        };
+    }, {
+        readonly id: "editingMode";
+        readonly shape: "dropdown";
+        readonly labelKey: "editingMode.label";
+        readonly valueKey: "editingMode.editing";
+        readonly paths: readonly string[];
+        readonly state: {
+            readonly kind: "command";
+        };
+    }];
+}, {
+    readonly id: "contentControl";
+    readonly labelKey: "contentControl.group";
+    readonly contextual: true;
+    readonly controls: readonly [{
+        readonly id: "showAll";
+        readonly labelKey: "contentControl.showAll";
+        readonly paths: readonly string[];
+        readonly state: {
+            readonly kind: "command";
+        };
+    }, {
+        readonly id: "formFill";
+        readonly labelKey: "contentControl.formFill";
+        readonly paths: readonly string[];
+        readonly state: {
+            readonly kind: "command";
+        };
+    }, {
+        readonly id: "inspector";
+        readonly labelKey: "contentControl.inspector";
+        readonly paths: readonly string[];
+        readonly state: {
+            readonly kind: "command";
+        };
+    }, {
+        readonly id: "remove";
+        readonly labelKey: "contentControl.remove";
+        readonly paths: readonly string[];
+        readonly state: {
+            readonly kind: "command";
+        };
+    }];
+}, {
+    readonly id: "image";
+    readonly labelKey: "formattingBar.groups.image";
+    readonly contextual: true;
+    readonly controls: readonly [{
+        readonly id: "insert";
+        readonly labelKey: "toolbar.image";
+        readonly paths: readonly string[];
+        readonly state: {
+            readonly kind: "command";
+        };
+    }, {
+        readonly id: "properties";
+        readonly labelKey: "formattingBar.imagePropertiesShortcut";
+        readonly paths: readonly string[];
+        readonly state: {
+            readonly kind: "command";
+        };
+    }, {
+        readonly id: "wrap";
+        readonly shape: "dropdown";
+        readonly labelKey: "formattingBar.imageWrap";
+        readonly paths: readonly string[];
+        readonly valueKey: "imageWrap.inline";
+        readonly state: {
+            readonly kind: "value";
+        };
+    }, {
+        readonly id: "altText";
+        readonly shape: "dropdown";
+        readonly labelKey: "formattingBar.altText";
+        readonly paths: null;
+        readonly valueKey: "imageProperties.altText";
+        readonly state: {
+            readonly kind: "value";
+        };
+    }];
+}, {
+    readonly id: "table";
+    readonly labelKey: "formattingBar.groups.table";
+    readonly contextual: true;
+    readonly controls: readonly [{
+        readonly id: "insert";
+        readonly labelKey: "toolbar.table";
+        readonly paths: readonly string[];
+        readonly state: {
+            readonly kind: "command";
+        };
+    }, {
+        readonly id: "borderTarget";
+        readonly shape: "dropdown";
+        readonly labelKey: "table.borders.tooltip";
+        readonly paths: readonly string[];
+        readonly state: {
+            readonly kind: "value";
+        };
+    }, {
+        readonly id: "borderColor";
+        readonly shape: "colorSplit";
+        readonly swatch: "#000000";
+        readonly labelKey: "table.borderColor";
+        readonly paths: readonly string[];
+        readonly state: {
+            readonly kind: "value";
+        };
+    }, {
+        readonly id: "borderStyle";
+        readonly shape: "dropdown";
+        readonly labelKey: "table.borders.styleAriaLabel";
+        readonly paths: readonly string[];
+        readonly state: {
+            readonly kind: "value";
+        };
+    }, {
+        readonly id: "borderWidth";
+        readonly shape: "dropdown";
+        readonly labelKey: "table.borderWidth";
+        readonly paths: readonly string[];
+        readonly state: {
+            readonly kind: "value";
+        };
+    }, {
+        readonly id: "cellFill";
+        readonly shape: "colorSplit";
+        readonly swatch: "#ffffff";
+        readonly labelKey: "table.cellFillColor";
+        readonly paths: readonly string[];
+        readonly state: {
+            readonly kind: "value";
+        };
+    }];
+}, {
+    readonly id: "paragraph";
+    readonly labelKey: "dialogs.paragraph.title";
+    readonly contextual: true;
+    readonly controls: readonly [{
+        readonly id: "dialog";
+        readonly labelKey: "lineSpacing.options";
+        readonly paths: readonly string[];
+        readonly state: {
+            readonly kind: "command";
+        };
+    }];
+}, {
+    readonly id: "file";
+    readonly labelKey: "toolbar.file";
+    readonly contextual: true;
+    readonly controls: readonly [{
+        readonly id: "open";
+        readonly labelKey: "toolbar.open";
+        readonly paths: readonly string[];
+        readonly state: {
+            readonly kind: "load";
+        };
+    }, {
+        readonly id: "save";
+        readonly labelKey: "toolbar.saveShortcut";
+        readonly paths: readonly string[];
+        readonly state: {
+            readonly kind: "save";
         };
-    };
-    /**
-     * The hyperlink lane: what link the caret is in, and the insert / retarget / unlink verbs.
-     *
-     * Every verb is one `transact`, so it is one undo step. Targets going IN are host-supplied
-     * and pass the package's own URL allowlist; targets coming OUT are the sanitized
-     * projection, so a caller cannot accidentally hand a refused scheme to a sink.
-     */
-    readonly hyperlinks: HyperlinkOps;
-    /**
-     * Content-control chrome, form-fill navigation, and value / remove verbs.
-     *
-     * Value and remove commit through `session.applyTreeOps` — the same write path as typing.
-     * Show-all and form-fill are surface chrome and never reflow layout.
-     */
-    readonly contentControls: ContentControlOps;
-    /** Whether a `rows`×`cols` table can be inserted at the caret. */
-    canInsertTable(rows: number, cols: number): boolean;
-    /**
-     * Insert an empty `rows`×`cols` table at the caret, columns evenly dividing the content
-     * width of the caret's section, and leave the caret in the first cell.
-     */
-    insertTable(rows: number, cols: number): boolean;
-    /** Whether the addressed (or caret-local) body TOC can be refreshed. */
-    canRefreshToc(tocId?: string): boolean;
-    /** Whether a generated body TOC can be inserted before the caret paragraph. */
-    canInsertToc(): boolean;
-    /** Insert and populate a generated body TOC before the caret paragraph. */
-    insertToc(): boolean;
-    /** Refresh cached TOC entries and/or page numbers through the two-pass layout pipeline. */
-    refreshToc(tocId?: string, mode?: 'entire' | 'pageNumbers'): boolean;
-    /** Whether a body paragraph belongs to a detected TOC boundary or cached result. */
-    isInsideToc(paragraphId: string): boolean;
-    /**
-     * Bookmark jumps and the ONE external-activation gate. A host's popover "open" action
-     * calls `openExternal`; nothing else in the engine may call `window.open`.
-     */
-    readonly navigation: SurfaceNavigation;
-    /**
-     * Pin the current selection so it stays VISIBLY selected while focus is elsewhere.
-     *
-     * A document has one selection: the moment a panel focuses an input of its own the browser
-     * takes the highlight off the text, which is when the user most needs to see what the panel
-     * is about to act on. This draws the range on the engine's own overlay instead, so it
-     * survives the focus move. The MODEL selection is untouched — the op the panel finally runs
-     * addresses the same characters it always would.
-     *
-     * The pin releases itself when the caret leaves the range (either edge counts as inside),
-     * which is what lets a host close its panel on "the user clicked somewhere else" without
-     * every adapter reimplementing that comparison.
-     */
-    retainSelection(): SelectionPin;
-    /** Drop one owned pin. Another owner's pin remains visible. */
-    releaseSelection(pin: SelectionPin): void;
-    /** The pinned range, or null once it was released or escaped. */
-    retainedSelection(): SemanticSelection | null;
-    /**
-     * How edits are written right now.
-     *
-     * Lives on the SURFACE, not on the store. The store's write vocabulary stays explicit —
-     * an op says whether it is tracked — and the surface is the one thing that knows a
-     * keystroke happened, so it is the right place to decide what that keystroke becomes.
-     */
-    editingMode(): SurfaceEditingMode;
-    setEditingMode(mode: SurfaceEditingMode): void;
-    /**
-     * Every author with a revision in the CURRENT layout, mapped to Word's colour slot by
-     * order of first appearance. One map instance per layout, so a caller can key caches on
-     * its identity.
-     */
-    revisionAuthors(): ReadonlyMap<string, number>;
-    /**
-     * Replace how tracked changes are coloured, live. Paint-level: the pages repaint without
-     * remeasuring a line, and the caret, selection and undo history stay where they are.
-     */
-    setRevisionStyles(colors: RevisionStyles | undefined): void;
-    /**
-     * Commit ops that came from automation, through the gate a keystroke goes through.
-     *
-     * The narrow entry an automation host writes with, and the reason it needs one: reaching
-     * `session.applyTreeOps` past this skips the editing-mode gate entirely — a document open for
-     * viewing accepts a scripted edit, and a suggesting document records one as a permanent
-     * change with no proposal and no author. Here, viewing refuses, suggesting attributes, the
-     * refusal reason is reported like any other, and the pages repaint from the commit.
-     *
-     * The ops address the story the CALLER named, whatever story the reader is in: the caller
-     * identified its target before calling, so following the caret into a header would write
-     * somewhere else entirely. They default to the body rather than to the reader's story.
-     *
-     * They arrive as a BUILDER, given a way to mint the relationship an external hyperlink names.
-     * That mint changes the package outside the transaction and outside the undo stack, so it must not
-     * happen until the mode has allowed the write — a link minted while the batch was still being
-     * planned left its target in a read-only document's `.rels`. A builder answering null means the
-     * target is one this engine will not author, and the write is refused having changed nothing.
-     */
-    applyAutomationOps(staged: (relate: (url: string) => string | null) => readonly TreeDocOp[] | null, scope?: StoryScope): TreeApplyResult;
-    /**
-     * Commit review ops — accept, reject, a new comment — through the SAME path a keystroke
-     * takes: layout, paint, and a caret clamped to what the document now holds.
-     *
-     * Applying them straight to the session skipped all three. Rejecting an insertion left the
-     * pages painting text the tree no longer had, every card anchored where it used to be, and
-     * the caret past the end of the paragraph — after which every keystroke was refused with
-     * `offset-out-of-range` until the user happened to click somewhere else.
-     */
-    commitReviewOps(run: () => {
-        readonly committed: boolean;
-        readonly reason?: unknown;
-    }): void;
-    /**
-     * The layout as last PUBLISHED, without forcing pending work.
-     *
-     * `layout()` flushes first, which is right for a caller that is about to act on geometry
-     * and wrong for one that merely decorates it. The review rail read through `layout()` and
-     * so forced a synchronous full pass on every keystroke — eleven seconds per read on a
-     * 2432-block document. A card whose anchor is one frame stale is invisible; the paint that
-     * follows the flush republishes it.
-     */
-    publishedLayout(): SemanticLayout;
-    /**
-     * Paint-scale coordinate context for overlay chrome.
-     *
-     * Internal seam — not part of the public editor contract. Image overlay uses the same
-     * `zoom * 96/72` scale and per-page horizontal offsets the painter applied.
-     */
-    overlayCoordinates(): SurfaceOverlayCoordinates;
-    /**
-     * The comment or tracked change the caret is in, as the painted bands report it.
-     *
-     * ONE source for "which item is open". The band under the text and the card beside it are
-     * two views of the same answer, and deriving it twice let them disagree — the card closed
-     * while the text stayed highlighted.
-     */
-    activeReviewKey(): string | null;
-    /**
-     * Open THIS item, named by key, for as long as `selection` stays the live one.
-     *
-     * Without it the caret is the only evidence of which card is open, and a caret cannot name a
-     * card when two cards cover exactly the same characters: `w:ins` wrapping `w:del` — content
-     * one reviewer added and another struck — gives the insertion and the deletion one identical
-     * range, and every click on either card classified back to whichever the queue happened to
-     * list first. The reader clicked "Deleted" and watched "Added" light up.
-     *
-     * A key, not a position, because the position is precisely what is ambiguous. It holds only
-     * while the selection matches; a pointer or keyboard move hands the answer back to the caret,
-     * which is what lets the reader step out of a card by clicking away from it.
-     *
-     * `selection` is what activation wants installed, and it is installed HERE rather than by a
-     * `setSelection` of the caller's own so that the pin is up before anything is published. The
-     * other order repainted the bands and reported state while the caret was still the only
-     * evidence, so a host saw the wrong twin active for one frame and then a correction. Omit it
-     * to pin against the live selection, which is what a header or note scope has already set.
-     */
-    activateReview(key: string, selection?: SemanticSelection): void;
-    /**
-     * The key {@link activateReview} pinned, or null once its selection is no longer live.
-     *
-     * Exists so nothing outside the surface keeps its own copy of "the selection came from
-     * opening a card". `selectionPlacement` needs that fact to stay quiet about offering a
-     * comment on text the reader only selected by opening a card over it, and the copy it used to
-     * keep was set on one of activation's three branches, so a header card offered to comment on
-     * itself.
-     */
-    activatedReviewKey(): string | null;
-    /**
-     * Close the open item until the caret next moves.
-     *
-     * What a click on the canvas means. The caret does not move when someone clicks the grey
-     * around the page, so nothing else would ever put the item away.
-     */
-    dismissActiveReview(): void;
-    /**
-     * Revision kinds the CARET must not activate, or null for none.
-     *
-     * The review rail filters what it renders (structural and format cards are hidden by
-     * default), but {@link activeReviewKey} used to compute over the unfiltered queue — a
-     * click on tracked text under a format change activated a card the rail does not draw,
-     * and nothing on screen lit up. A host that filters its list tells the surface, so the
-     * band and the visible cards stay one answer.
-     */
-    setReviewActivationExclusions(kinds: readonly ReviewRevisionKind[] | null): void;
-    /**
-     * `bookmarkName -> position` over the current revision, for resolving an internal link.
-     * First in document order wins a duplicate name, matching Word.
-     */
-    bookmarks(): BookmarkIndex;
-    /** The selected text, for copy and cut. */
-    selectedText(): string;
-    /** Remove the selection, if any. Returns whether anything was deleted. */
-    deleteSelection(): boolean;
-    navigate(command: NavigationCommand, extend?: boolean): void;
-    /** Reverse the last history entry and put the caret back where it was made. */
-    undo(): void;
-    redo(): void;
-    /**
-     * Refresh table insertion furniture labels without remounting or relayout.
-     *
-     * @public
-     */
-    refreshTableInteractionLabels(): void;
-    focus(): void;
+    }, {
+        readonly id: "pageSetup";
+        readonly labelKey: "toolbar.pageSetup";
+        readonly paths: readonly string[];
+        readonly state: {
+            readonly kind: "command";
+        };
+    }];
+}, {
+    readonly id: "insert";
+    readonly labelKey: "toolbar.insert";
+    readonly contextual: true;
+    readonly controls: readonly [{
+        readonly id: "footnote";
+        readonly labelKey: "toolbar.insertFootnote";
+        readonly paths: readonly string[];
+        readonly state: {
+            readonly kind: "command";
+        };
+    }, {
+        readonly id: "endnote";
+        readonly labelKey: "toolbar.insertEndnote";
+        readonly paths: readonly string[];
+        readonly state: {
+            readonly kind: "command";
+        };
+    }, {
+        readonly id: "pageNumber";
+        readonly labelKey: "headerFooter.insertPageNumber";
+        readonly paths: readonly string[];
+        readonly state: {
+            readonly kind: "command";
+        };
+    }, {
+        readonly id: "totalPages";
+        readonly labelKey: "headerFooter.insertTotalPages";
+        readonly paths: readonly string[];
+        readonly state: {
+            readonly kind: "command";
+        };
+    }, {
+        readonly id: "sectionPages";
+        readonly labelKey: "headerFooter.insertSectionPages";
+        readonly paths: readonly string[];
+        readonly state: {
+            readonly kind: "command";
+        };
+    }, {
+        readonly id: "pageXofY";
+        readonly labelKey: "headerFooter.insertPageXofY";
+        readonly paths: readonly string[];
+        readonly state: {
+            readonly kind: "command";
+        };
+    }, {
+        readonly id: "pageBreak";
+        readonly labelKey: "toolbar.pageBreak";
+        readonly paths: readonly string[];
+        readonly state: {
+            readonly kind: "command";
+        };
+    }, {
+        readonly id: "sectionBreakNextPage";
+        readonly labelKey: "toolbar.sectionBreakNextPage";
+        readonly paths: readonly string[];
+        readonly state: {
+            readonly kind: "command";
+        };
+    }, {
+        readonly id: "sectionBreakContinuous";
+        readonly labelKey: "toolbar.sectionBreakContinuous";
+        readonly paths: readonly string[];
+        readonly state: {
+            readonly kind: "command";
+        };
+    }, {
+        readonly id: "toc";
+        readonly labelKey: "toolbar.tableOfContents";
+        readonly paths: readonly string[];
+        readonly state: {
+            readonly kind: "command";
+        };
+    }];
+}];
+/**
+ * Every group id in the chrome, as a literal union. Stable public API; renaming a group
+ * id is a breaking change.
+ *
+ * @public
+ */
+type ChromeGroupId = 'history' | 'zoom' | 'styles' | 'font' | 'text' | 'script' | 'alignment' | 'list' | 'format' | 'review' | 'contentControl' | 'image' | 'table' | 'paragraph' | 'file' | 'insert';
+/**
+ * The public slot vocabulary: `${groupId}.${controlId}` for every control that actually
+ * exists — `text.bold`, `font.family`, `alignment.left`. THE stable contract a host
+ * composes against and `commandForSlot` resolves; renaming a slot is a breaking change.
+ *
+ * @public
+ */
+type ChromeSlotId = 'history.undo' | 'history.redo' | 'zoom.level' | 'styles.style' | 'font.family' | 'font.size' | 'text.bold' | 'text.italic' | 'text.underline' | 'text.strike' | 'text.color' | 'text.highlight' | 'text.link' | 'script.super' | 'script.sub' | 'alignment.left' | 'alignment.center' | 'alignment.right' | 'alignment.justify' | 'list.bullet' | 'list.numbered' | 'list.outdent' | 'list.indent' | 'list.lineSpacing' | 'format.clear' | 'review.comments' | 'review.editingMode' | 'contentControl.showAll' | 'contentControl.formFill' | 'contentControl.inspector' | 'contentControl.remove' | 'image.insert' | 'image.properties' | 'image.wrap' | 'image.altText' | 'table.insert' | 'table.borderTarget' | 'table.borderColor' | 'table.borderStyle' | 'table.borderWidth' | 'table.cellFill' | 'file.open' | 'file.save' | 'paragraph.dialog' | 'file.pageSetup' | 'insert.footnote' | 'insert.endnote' | 'insert.pageNumber' | 'insert.totalPages' | 'insert.sectionPages' | 'insert.pageXofY' | 'insert.pageBreak' | 'insert.sectionBreakNextPage' | 'insert.sectionBreakContinuous' | 'insert.toc';
+/**
+ * Every control id in the chrome, as a literal union. Unique WITHIN a group, not
+ * globally (`image.insert` / `table.insert`) — key consumers on {@link ChromeSlotId}.
+ *
+ * @public
+ */
+type ChromeControlId = ChromeSlotId extends `${string}.${infer C}` ? C : never;
+/**
+ * The slot id of one control within its group. Only meaningful for entries of
+ * `CHROME_GROUPS` — the cast is sound because every group/control pair in the registry
+ * is, by construction, a member of the `ChromeSlotId` union.
+ *
+ * @public
+ */
+declare function chromeSlotId(group: {
+    readonly id: string;
+}, control: {
+    readonly id: string;
+}): ChromeSlotId;
+/**
+ * The groups of the DEFAULT toolbar arrangement, in bar order: every group that is
+ * not `contextual`. This is the registry's default bar — undo/redo through the
+ * editing-mode picker — and what both adapters render when the host composes
+ * nothing. Contextual slots (`image.*`, `table.insert`, `file.save`) remain
+ * available for explicit composition.
+ *
+ * @public
+ */
+declare function defaultChromeGroups(): readonly ChromeGroup[];
+/**
+ * The formatting-bar groups for one editor snapshot: the default bar, plus the
+ * contextual `image` group when a drawing is selected. Insertion without a selection is
+ * not in the packaged chrome at all — a host that wants it places `image.insert` itself,
+ * through `DocxEditor.Toolbar.ImageInsert` or `DocxEditor.Menu.ImageInsert`.
+ *
+ * @public
+ */
+declare function formattingBarChromeGroups(image: ImageContext | null): readonly ChromeGroup[];
+/**
+ * A row that runs one chrome slot.
+ *
+ * @public
+ */
+interface ChromeMenuItemEntry {
+    readonly kind: 'item';
+    readonly slot: ChromeSlotId;
     /**
-     * Refresh table insertion furniture labels without remounting the surface.
+     * Plain-label override for this row.
      *
-     * @public
-     */
-    setTableInteractionLabel(resolver: (key: 'table.insertRowBelow' | 'table.insertColumnRight') => string): void;
-    destroy(): void;
-    /** Active editing view — body, or an open header/footer story by rId. */
-    activeScope(): ViewScope;
-    /** Activate a view scope. Returns false when a header/footer rId cannot be opened. */
-    setActiveScope(scope: ViewScope): boolean;
-    /**
-     * Open a header/footer story for editing on the painted surface.
-     * Refuses dangling / unknown relationship ids.
+     * A slot's own `labelKey` is a TOOLTIP key, and several of them fold the shortcut into
+     * the text (`formattingBar.boldShortcut` is "Bold (Ctrl+B)"). A menu puts the shortcut
+     * in its own right-hand column, so the row needs the bare noun. Both keys already exist
+     * in the catalogue — this points at the plain one rather than minting a duplicate.
      */
-    enterHeaderFooter(args: {
-        readonly rId: string;
-        readonly pageIndex?: number;
-        readonly sectionIndex?: number;
-        readonly kind?: 'header' | 'footer';
-        readonly variant?: 'default' | 'first' | 'even';
-        readonly position?: SemanticPosition;
-    }): boolean;
-    /** Leave furniture editing and restore the prior body selection. */
-    exitHeaderFooter(): void;
-    /** Chrome read-model for the open furniture scope, or null when editing the body. */
-    headerFooterState(): {
-        readonly editing: 'header' | 'footer' | null;
-        readonly sectionIndex: number;
-        readonly variant?: 'default' | 'first' | 'even';
-        readonly rId?: string;
-        readonly partName?: string;
-        readonly inherited?: boolean;
-        readonly titlePage?: boolean;
-        readonly evenAndOddHeaders?: boolean;
-        readonly headerDistanceTwips?: number;
-        readonly footerDistanceTwips?: number;
-    } | null;
+    readonly labelKey?: string;
+    /** i18n key of the shortcut shown right-aligned on the row (`toolbar.saveShortcut`). */
+    readonly shortcutKey?: string;
     /**
-     * Commit one package-level furniture lifecycle op (create/delete/link/unlink/options).
-     * Flushes layout so the next enter/rebind sees the new resolution.
+     * The row opens a size PICKER instead of firing on click — Word's insert-table grid.
+     * The slot still owns the label, the icon and the enabled state; only the dispatch
+     * differs, and the picked size is what the host sends.
      */
-    applyHeaderFooterLifecycle(op: {
-        readonly op: 'createHeaderFooter' | 'deleteHeaderFooter' | 'linkToPrevious' | 'unlinkFromPrevious' | 'setSectionFurnitureOptions';
-        readonly sectionIndex?: number;
-        readonly kind?: 'header' | 'footer';
-        readonly variant?: 'default' | 'first' | 'even';
-        readonly titlePage?: boolean;
-        readonly evenAndOddHeaders?: boolean;
-        readonly headerDistanceTwips?: number;
-        readonly footerDistanceTwips?: number;
-    }): {
-        readonly ok: true;
-    } | {
-        readonly ok: false;
-        readonly reason: string;
-    };
-    /** Insert an allowlisted page field at the caret in the open HF story. */
-    insertPageField(field: 'PAGE' | 'NUMPAGES' | 'SECTIONPAGES' | 'PAGE_X_OF_Y'): boolean;
-    /** Insert a footnote/endnote at the body caret. */
-    insertNote(noteKind: 'footnote' | 'endnote'): boolean;
-    deleteNote(noteKind: 'footnote' | 'endnote', noteId: number): boolean;
-    convertNote(fromKind: 'footnote' | 'endnote', noteId: number): boolean;
-    convertAllNotes(fromKind: 'footnote' | 'endnote'): boolean;
-    setNoteProperties(args: {
-        readonly scope: 'document' | 'section';
-        readonly sectionIndex?: number;
-        readonly footnote?: {
-            readonly numFmt?: string;
-            readonly numRestart?: string;
-            readonly position?: string;
-            readonly numStart?: number;
-        };
-        readonly endnote?: {
-            readonly numFmt?: string;
-            readonly numRestart?: string;
-            readonly position?: string;
-            readonly numStart?: number;
-        };
-    }): boolean;
-    enterNote(scopeId: string, position?: {
-        paragraphId: string;
-        offset: number;
-    }): boolean;
-    exitNote(): void;
-    /** Resolved/authored note properties for the caret section — chrome read-model. */
-    notePropertiesState(): NotePropertiesStateSnapshot | null;
-    /** Plain-text preview for hover chrome — never returns markup. */
-    notePreviewText(scopeId: string): string | null;
-    /** Commit one table-command plan as a single store transaction. */
-    applyTableCommandPlan(plan: TableCommandPlan): ExecResult;
+    readonly picker?: 'tableGrid';
 }
 /**
- * What opening a document produced: a mounted surface, or a refusal.
+ * A row that opens a nested panel of rows (Insert › Break).
  *
- * A result rather than a throw, because every refusal here comes from FILE input — a package the
- * bounded reader rejected, a part that exceeded a limit — and a malformed upload should surface
- * as a message the host can show rather than an exception it has to catch.
+ * It carries its own label and icon rather than a slot, because a submenu PARENT has no
+ * command: clicking it opens the panel. Giving it a slot would mint a public id for a
+ * control that can never be enabled, and `toolbarCommandState` would have to invent an
+ * answer about it.
+ *
+ * @public
  */
-type OpenPaginatedResult = {
-    readonly ok: true;
-    readonly surface: PaginatedSurface;
-} | {
-    readonly ok: false;
-    readonly reason: string;
-    readonly detail?: string;
-};
+interface ChromeMenuSubmenuEntry {
+    readonly kind: 'submenu';
+    readonly labelKey: string;
+    readonly paths: readonly string[] | null;
+    readonly items: readonly ChromeMenuEntry[];
+}
+/** A horizontal rule between groups of rows. @public */
+interface ChromeMenuSeparatorEntry {
+    readonly kind: 'separator';
+}
+/** One row of a chrome menu. @public */
+type ChromeMenuEntry = ChromeMenuItemEntry | ChromeMenuSubmenuEntry | ChromeMenuSeparatorEntry;
+/**
+ * Every menu id, as a literal union. Stable public API; renaming one is a breaking change,
+ * exactly like a group or slot id.
+ *
+ * @public
+ */
+type ChromeMenuId = 'file' | 'format' | 'insert' | 'help';
+/** One menu of the menu bar. @public */
+interface ChromeMenu {
+    readonly id: ChromeMenuId;
+    readonly labelKey: string;
+    readonly entries: readonly ChromeMenuEntry[];
+}
+/**
+ * The menu bar the chrome shows above the toolbar, in bar order: File, Format, Insert,
+ * Help.
+ *
+ * @public
+ */
+declare const CHROME_MENUS: readonly ChromeMenu[];
+/**
+ * Every slot a menu places, in menu order, submenus flattened. What a parity test asserts
+ * against, and what a host enumerates to know which capabilities the menu bar reaches.
+ *
+ * @public
+ */
+declare function chromeMenuSlots(): readonly ChromeSlotId[];
+/** Total controls, so a parity test can assert none were dropped. */
+declare function chromeControlCount(): number;
+/**
+ * i18n key for the tooltip on a control an ADAPTER renders but cannot drive yet — a
+ * value slot in a toolbar that has grown no picker for it, say. It is never the reason
+ * a control is disabled: when the ENGINE refuses, the tooltip is the engine's own
+ * `disabledReason`, never an adapter paraphrase.
+ */
+declare const CHROME_UNAVAILABLE_KEY = "formattingBar.unavailableInPreview";
 
 /** Material Symbol name → SVG path data (viewBox "0 -960 960 960"). */
 declare const GENERATED_ICON_PATHS: Readonly<Record<string, readonly string[]>>;
@@ -2715,4 +2912,4 @@ declare function runTableCommand(editor: Editor | null, command: EditorCommand):
  */
 declare function createDocxEditor(config: DocxEditorConfig): DocxEditorInstance;
 
-export { TABLE_BORDER_STYLE_OPTIONS as $, type AnchorFrameOrigin as A, type HyperlinkOps as B, CHROME_GROUPS as C, type DocxEditorInstance as D, EMU_PER_POINT as E, type FinalizedImageOverlayInteraction as F, IMAGE_OVERLAY_NUDGE_SHIFT_PT as G, type HyperlinkActivation as H, IMAGE_OVERLAY_NUDGE_PT as I, type ImageInteractionSession as J, type ImageOverlayScrollPort as K, type ImageResizeHandle as L, type ImageResizeResult as M, type LoadFontsRequest as N, type OpenPaginatedResult as O, type PaginatedSurfaceOptions as P, type LoadFontsResult as Q, MAX_RESOLVER_FAMILIES as R, type OverlayFrameRect as S, type TableCommandPlan as T, type PaginatedSurfaceState as U, type RunTableChromeCommandResult as V, type SelectedDrawingOverlayTarget as W, type SurfaceFormatting as X, type SurfaceHyperlink as Y, type SurfaceNavigation as Z, type SurfaceOverlayCoordinates as _, type PaginatedSurface as a, TABLE_BORDER_TARGET_OPTIONS as a0, TABLE_BORDER_WIDTH_OPTIONS as a1, TABLE_CHROME_SLOT_IDS as a2, type TableBorderStyleOption as a3, type TableBorderTargetOption as a4, type TableBorderTargetValue as a5, type TableBorderWidthOption as a6, type TableChromeDraft as a7, type TableChromePick as a8, type TableChromeSlotId as a9, finalizeImageOverlayInteraction as aA, formattingBarChromeGroups as aB, isStaleImageInteractionCommit as aC, isTableChromeSlot as aD, layoutPointsToCssPixels as aE, loadFonts as aF, overlayFrameToSheetCssPixels as aG, pointsToEmu as aH, probeTableChromeCommand as aI, resizePreservesAspect as aJ, runSave as aK, runTableChromeCommand as aL, runTableCommand as aM, runToolbarCommand as aN, selectedDrawingOverlayTargetOf as aO, selectedImageStateOf as aP, surfacePaintScale as aQ, tableChromeIconPaths as aR, tableChromeLabelKeyForTarget as aS, tableChromeToolbarState as aT, tableChromeVisible as aU, tableCommandToolbarState as aV, toolbarCommandState as aW, toolbarCommandStates as aX, type TableInteractionLabelKey as aa, type ToolbarCommandState as ab, WORD_DEFAULT_FONT as ac, applyTableChromePick as ad, blankDocumentBytes as ae, canExecuteImageCommand as af, captureImageMutationPreconditions as ag, chromeControlCount as ah, chromeMenuSlots as ai, chromeProbeForSlot as aj, chromeSlotId as ak, commandForSlot as al, commandForSlotValue as am, commandForTableChromeSlotValue as an, composeFontConfiguration as ao, computeImageResizeResult as ap, computeMovedImagePosition as aq, computeResizedImageExtentEmu as ar, createDocxEditor as as, createFontSource as at, createImageOverlayScrollPort as au, cssPixelsToLayoutPoints as av, defaultChromeGroups as aw, defaultTableLabel as ax, emuToOverlayPoints as ay, executeImageCommand as az, CHROME_MENUS as b, CHROME_UNAVAILABLE_KEY as c, type ChromeControl as d, type ChromeControlId as e, type ChromeControlState as f, type ChromeGroup as g, type ChromeGroupId as h, type ChromeMenu as i, type ChromeMenuEntry as j, type ChromeMenuId as k, type ChromeMenuItemEntry as l, type ChromeMenuSeparatorEntry as m, type ChromeMenuSubmenuEntry as n, type ChromeSlotId as o, DEFAULT_TABLE_CHROME_DRAFT as p, type DocxEditorConfig as q, type FontConfigurationBase as r, type FontConfigurationFragment as s, type FontLoadFailure as t, type FontLoadFailureReason as u, type FontMeasurementState as v, type FontResolutionRequest as w, type FontResolver as x, type FontUrlSource as y, type HyperlinkChromeHandlers as z };
+export { type SelectedDrawingOverlayTarget as $, type AnchorFrameOrigin as A, type FontResolver as B, CHROME_GROUPS as C, type DocxEditorInstance as D, EMU_PER_POINT as E, type FinalizedImageOverlayInteraction as F, type FontUrlSource as G, type HyperlinkActivation as H, type HyperlinkChromeHandlers as I, type HyperlinkOps as J, IMAGE_OVERLAY_NUDGE_PT as K, IMAGE_OVERLAY_NUDGE_SHIFT_PT as L, type ImageInteractionSession as M, type ImageOverlayScrollPort as N, type OpenPaginatedResult as O, type PaginatedSurfaceOptions as P, type ImageResizeHandle as Q, type ImageResizeResult as R, type LoadFontsRequest as S, type TableCommandPlan as T, type LoadFontsResult as U, MAX_RESOLVER_FAMILIES as V, type OverlayFrameRect as W, type PaginatedSurfaceState as X, type ParagraphPropertyEdit as Y, type RunTableChromeCommandResult as Z, type SectionAnchor as _, type PaginatedSurface as a, tableChromeToolbarState as a$, type SurfaceEquation as a0, type SurfaceFormatting as a1, type SurfaceHyperlink as a2, type SurfaceNavigation as a3, type SurfaceOverlayCoordinates as a4, type SurfaceParagraphFormat as a5, TABLE_BORDER_STYLE_OPTIONS as a6, TABLE_BORDER_TARGET_OPTIONS as a7, TABLE_BORDER_WIDTH_OPTIONS as a8, TABLE_CHROME_SLOT_IDS as a9, createFontSource as aA, createImageOverlayScrollPort as aB, cssPixelsToLayoutPoints as aC, defaultChromeGroups as aD, defaultTableLabel as aE, emuToOverlayPoints as aF, equationAtPosition as aG, executeImageCommand as aH, finalizeImageOverlayInteraction as aI, formattingBarChromeGroups as aJ, isStaleImageInteractionCommit as aK, isTableChromeSlot as aL, layoutPointsToCssPixels as aM, loadFonts as aN, overlayFrameToSheetCssPixels as aO, pointsToEmu as aP, probeTableChromeCommand as aQ, resizePreservesAspect as aR, runSave as aS, runTableChromeCommand as aT, runTableCommand as aU, runToolbarCommand as aV, selectedDrawingOverlayTargetOf as aW, selectedImageStateOf as aX, surfacePaintScale as aY, tableChromeIconPaths as aZ, tableChromeLabelKeyForTarget as a_, type TableBorderStyleOption as aa, type TableBorderTargetOption as ab, type TableBorderTargetValue as ac, type TableBorderWidthOption as ad, type TableChromeDraft as ae, type TableChromePick as af, type TableChromeSlotId as ag, type TableInteractionLabelKey as ah, type ToolbarCommandState as ai, WORD_DEFAULT_FONT as aj, applyTableChromePick as ak, blankDocumentBytes as al, canExecuteImageCommand as am, captureImageMutationPreconditions as an, chromeControlCount as ao, chromeMenuSlots as ap, chromeProbeForSlot as aq, chromeSlotId as ar, commandForSlot as as, commandForSlotValue as at, commandForTableChromeSlotValue as au, composeFontConfiguration as av, computeImageResizeResult as aw, computeMovedImagePosition as ax, computeResizedImageExtentEmu as ay, createDocxEditor as az, CHROME_MENUS as b, tableChromeVisible as b0, tableCommandToolbarState as b1, toolbarCommandState as b2, toolbarCommandStates as b3, CHROME_UNAVAILABLE_KEY as c, type ChromeControl as d, type ChromeControlId as e, type ChromeControlState as f, type ChromeGroup as g, type ChromeGroupId as h, type ChromeMenu as i, type ChromeMenuEntry as j, type ChromeMenuId as k, type ChromeMenuItemEntry as l, type ChromeMenuSeparatorEntry as m, type ChromeMenuSubmenuEntry as n, type ChromeSlotId as o, DEFAULT_TABLE_CHROME_DRAFT as p, type DocxEditorConfig as q, type EquationActivation as r, type EquationChromeHandlers as s, type EquationOps as t, type FontConfigurationBase as u, type FontConfigurationFragment as v, type FontLoadFailure as w, type FontLoadFailureReason as x, type FontMeasurementState as y, type FontResolutionRequest as z };