@docx-editor.dev/pro/react

activatedCustomNodeOffunctionSource ↗

The activation every host hook receives: identity, POST-fromDocx attrs, and — when the review module derived a card for the node — its literal text and canonical node id.

One enrichment step for every surface (click, hover, edit, context-menu card), so a hook written against the review rail's attrs shape sees the SAME shape from the chip. Without a review module the definition's fromDocx runs over the raw decode with text: ''; its veto (null) drops the activation, exactly as recognition would have.

declare function activatedCustomNodeOf(resolved: ResolvedCustomNodeActivation, editor: Editor | null | undefined): ActivatedCustomNode | null;

collaborationModulefunctionSource ↗

Build the collaboration module. Construction never validates the key and never touches the network.

declare function collaborationModule(options: CollaborationModuleOptions): EditorModule;

CustomNodeChromefunctionSource ↗

Paints custom-node chips and dispatches pointer activation on them.

Renders nothing itself — it installs the chip styles and the activation listeners, so mount it once anywhere inside the editor provider. Chip colours come from each definition's chrome, which is host-authored and never file data.

declare function CustomNodeChrome(props: CustomNodeChromeProps): null;

```tsx
<DocxEditor.Root>
  <CustomNodeChrome onNodeClick={(node) => setPopover(node)} />
  <DocxEditor.Viewport><DocxEditor.Content /></DocxEditor.Viewport>
</DocxEditor.Root>
```

CustomNodeContextMenufunctionSource ↗

Renders the pointed-at node's card data plus its "Edit label" row, or nothing when the right-click landed elsewhere. Carries docxRowPlacement: 'start', so the context menu mounts it above the packaged rows.

declare function CustomNodeContextMenu(props: CustomNodeContextMenuProps): react.JSX.Element | null;

DocxEditorCollaborationRootfunctionSource ↗

A DocxEditor.Root wired to a collaboration room.

```tsx const collaboration = useHocuspocusCollaboration({ modules: MODULES, room });

<DocxEditorCollaborationRoot collaboration={collaboration} fallback={<p>Connecting…</p>}> <DocxEditor.Toolbar /> <DocxEditor.Viewport> <DocxEditor.Content /> <DocxEditorCollaboration.CaretLabels /> </DocxEditor.Viewport> </DocxEditorCollaborationRoot> ```

The presence parts take no session: they read it from the editor this mounts.

declare function DocxEditorCollaborationRoot(input: DocxEditorCollaborationRootProps): react.JSX.Element;

resolveCustomNodeActivationfunctionSource ↗

The recognized custom node a pointer target sits on, or null.

Walks up from target to the painted control boundary, reads its data-tag, and matches the decoded identity against nodes. Returns null for anything that is not a recognized chip — ordinary text, an unclaimed SDT, a tag no definition owns.

Every input is DOM the engine painted from FILE DATA. The tag is attacker-controlled and goes through the codec's guards; it never reaches markup.

declare function resolveCustomNodeActivation(target: EventTarget | null, nodes: readonly AnyCustomNodeDefinition[]): ResolvedCustomNodeActivation | null;

reviewModulefunctionSource ↗

Build the review module. Construction never validates the key and never touches the network. It installs the drawing renderers process-wide, so charts, SmartArt layout, drawing effects, WordArt, and metafile pictures render without a separate drawingModule().

declare function reviewModule(options?: ReviewModuleOptions): EditorModule;

useCollaborationParticipantsfunctionSource ↗

Reactive participant roster for the collaboration session.

Omit session and it reads the one the editor above holds. Returns the same array reference until the roster actually changes, so a memoized consumer does not re-render on unrelated awareness traffic. No session yields a stable empty array.

declare function useCollaborationParticipants(session?: CollaborationSession | null): readonly CollaborationParticipant[];

useCollaborationSessionfunctionSource ↗

The live collaboration session of the editor above this component, or null.

The editor already holds the session a collaborationModule contributed, so presence chrome reads it from here instead of being handed it: every part and hook in this package takes session as an OPTIONAL prop and falls back to this. A host that has one Root and one room never passes it at all.

Pass it explicitly when a component sits outside the Root that owns the room, or when one page renders two.

declare function useCollaborationSession(): CollaborationSession | null;

useCollaborationStatusfunctionSource ↗

Reactive status for the collaboration session, with live and diverged derived.

Omit session and it reads the one the editor above holds. Pass it explicitly for a session this Root does not own.

declare function useCollaborationStatus(session?: CollaborationSession | null): UseCollaborationStatusReturn;

useCustomNodeDefinitionsfunctionSource ↗

The definitions a chrome surface should act on: the nodes prop when given, else the definitions registered on the editor (customNodesModule). Registering once and letting every surface default to it is the intended shape; the prop exists for a host that wants one surface scoped narrower.

declare function useCustomNodeDefinitions(nodes: readonly AnyCustomNodeDefinition[] | undefined): readonly AnyCustomNodeDefinition[];

useDocumentCollaborationfunctionSource ↗

Own a provider-agnostic collaboration session for a React host.

The consumer creates the ydoc, the awareness, and whatever provider replicates them (WebSocket, WebRTC, offline persistence); this hook owns only the document session over them, with the same StrictMode-safe lifecycle as useWebrtcCollaboration. It imports no network provider.

declare function useDocumentCollaboration(options?: UseDocumentCollaborationOptions): UseDocumentCollaborationReturn;

useReviewfunctionSource ↗

Read the review queue and act on it.

Subscribes to the editor's own change stream, so the list re-derives when the document does and not on every render.

This is the browser review API: comment, reply, accept, reject, and open items from your own UI. For headless, server, or agent pipelines, use @docx-editor.dev/editor-api instead.

declare function useReview(query?: ReviewItemQuery): UseReviewReturn;

useReviewAuthorfunctionSource ↗

The resolved presentation of one author — colour, ramp slot, and any declared style — or undefined when no argument is given, or when the author is in neither the document's roster nor the review queue.

COMMENT AUTHORS INCLUDED. The document's revision roster does not carry someone who only left comments, so this resolves their declaration directly; their card draws in the colour the host declared, exactly as a reviewer's does.

The link between a CUSTOM card and the author styling system: a List render callback or card child reads the item's author here and draws with the same colours the painted document and the packaged cards use. Live: a setRevisionStyles call re-renders the rail, and this answer with it. Outside the rail it reads the editor's author roster.

tsx function MyCard({ item }: { item: ReviewItemView }) { const author = useReviewAuthor(item.author); return <div style={{ borderColor: author?.color }}>…</div>; } <DocxEditorReview.List>{(item) => <MyCard item={item} />}</DocxEditorReview.List>;

declare function useReviewAuthor(author: string | undefined): ReviewAuthorInfo | undefined;

useReviewItemfunctionSource ↗

The review item the surrounding card (or balloon) renders, or null outside one.

The hook a host's own card content is built from: children passed into the rail's cards — extra actions, a custom body — read the CURRENT item here rather than receiving props, exactly the way the packaged parts do.

declare function useReviewItem(): ReviewItemView | null;

useReviewOffunctionSource ↗

The same hook against an explicit editor, for hosts that hold their own.

declare function useReviewOf(editor: Editor | null, query?: ReviewItemQuery): UseReviewReturn;

useReviewRailMetricsfunctionSource ↗

The review column's geometry in CSS pixels: what converts review anchors and stacked positions, which are layout points from the top of the first page, into a card's top.

Call it without arguments inside DocxEditorReview, for example in children of <DocxEditorReview preset={false}>, to read the packaged rail's own measurement. Those children render inside the rail element, which already sits at left.

Pass railRef to measure your own column instead. Attach the ref to an element that the calling component renders, give it position: absolute, and render it directly inside DocxEditor.Viewport with no positioned element in between: its offset parent must be the scroll container that holds the pages. Development builds warn once when it is not. The column reserves the review gutter unless reserveGutter is false.

While useReview().paneOpen is false the viewport reserves only a marker strip, so render no cards then. compact is true when the pane is open but too narrow for a column.

The value updates when the zoom, the window size, the page count, the document load, content above the pages, or the reserved review gutter changes. It works in a pop-out window or an iframe, because it observes the element's own window.

declare function useReviewRailMetrics(railRef?: RefObject<HTMLElement | null> | null, options?: UseReviewRailMetricsOptions): ReviewRailMetrics;

Position custom cards 


```tsx
function MyColumn({ heights }: { heights: ReadonlyMap<string, number> }) {
  const railRef = useRef<HTMLDivElement>(null);
  const metrics = useReviewRailMetrics(railRef);
  const { items } = useReview();
  const positions = useStackedReviewPositions(items, heights, { scale: metrics.scale });
  return (
    <div
      ref={railRef}
      style={{
        position: 'absolute',
        top: 0,
        left: metrics.left ?? 0,
        // The column's width places it when `metrics.side` is 'left'.
        width: 300,
        visibility: metrics.left === null ? 'hidden' : 'visible',
      }}
    >
      {items.map((item) => (
        <MyCard
          key={item.key}
          item={item}
          style={{
            position: 'absolute',
            top: metrics.top + (positions.get(item.key) ?? 0) * metrics.scale,
          }}
        />
      ))}
    </div>
  );
}
```

useReviewRefusalMessagefunctionSource ↗

The packaged sentence for a refused review write, in the reader's language, for a host's own card or balloon. It honors the review pane's t overrides, as the packaged cards do.

declare function useReviewRefusalMessage(): (refusal: ReviewWriteRefusal) => string;

```tsx
const { lastRefusal } = useReview();
const refusalMessage = useReviewRefusalMessage();
return lastRefusal?.key === item.key ? <p role="alert">{refusalMessage(lastRefusal)}</p> : null;
```

useStackedReviewPositionsfunctionSource ↗

Non-overlapping Y positions for cards you have measured.

Separate from useReview because only the CALLER knows how tall its cards are — a host rendering its own markup can be told where each anchor is, but not how much room its card needs. Pass the measured heights back and get positions that do not collide; skip it entirely and cards sit on their raw anchors, which is correct for a rail that does not stack.

Takes anything with a key and an anchor, not only cards: a compose box competes for the same column and has to be stacked WITH them or it lands on top of the card whose text was just re-selected. Entries must arrive in document order.

An entry with isActive: true, as a review placement has while its card is open, stays at its own anchor. The entries before it move up to make room, so Next Change never leaves the open card below the visible rail. Pass placements through as they are to keep this.

UNITS. Anchors are in layout POINTS, because that is what the engine publishes; measured heights are in CSS PIXELS, because that is what the DOM reports. Pass scale so the two can be added. Without it a 330px card advanced the run by 330 POINTS — 440px — and two comments on adjacent lines of one paragraph sat a third of a page apart.

Returns each card's top in layout points. useReviewRailMetrics supplies scale and the pixel offset of the first page: a card's CSS top is metrics.top + position * metrics.scale.

declare function useStackedReviewPositions(items: readonly {
    readonly key: string;
    readonly anchorY: number | null;
    readonly isActive?: boolean;
}[], heights: ReadonlyMap<string, number>, options?: {
    readonly gap?: number;
    readonly scale?: number;
    readonly defaultHeight?: number;
}): ReadonlyMap<string, number>;

CollaborationAvatarPropsinterfaceSource ↗

Props for [DocxEditorCollaboration](DocxEditorCollaboration).Avatar.

interface CollaborationAvatarProps

CollaborationAvatarRenderPropsinterfaceSource ↗

Render props for [DocxEditorCollaboration](DocxEditorCollaboration).Avatars' per-participant override.

interface CollaborationAvatarRenderProps

CollaborationAvatarsPropsinterfaceSource ↗

Props for [DocxEditorCollaboration](DocxEditorCollaboration).Avatars.

interface CollaborationAvatarsProps

CollaborationCaretLabelRenderPropsinterfaceSource ↗

What a custom remote-caret label renders with.

The renderer mounts inside the adapter's provider tree, so every hook works in it — useDocxEditor, useEditorState, the review hooks. It has the opened document, not only the collaborator.

interface CollaborationCaretLabelRenderProps

CollaborationCaretLabelsPropsinterfaceSource ↗

Props for [DocxEditorCollaboration](DocxEditorCollaboration).CaretLabels.

The rendered content lands in the engine's label layer, which is furniture: the layer is aria-hidden and takes no pointer events. Assistive technology does not read a label, and nothing inside one is clickable or focusable. Keep interactive or announced presence UI in your own chrome, such as the avatar stack.

interface CollaborationCaretLabelsProps

CollaborationFailureinterface

One collaboration failure: a typed code plus optional free-form detail.

interface CollaborationFailure

CollaborationIdentityinterface

Human or automation identity attached to authored collaboration transactions.

interface CollaborationIdentity

CollaborationIdentityUpdateinterfaceSource ↗

Display-identity fields a live session can update.

actorId and role are attribution and stay immutable for the session lifetime, so this type cannot name them.

interface CollaborationIdentityUpdate

CollaborationModuleOptionsinterfaceSource ↗

How [collaborationModule](collaborationModule) is configured. The session is required; the licence key is optional and never validated.

interface CollaborationModuleOptions extends ProLicenseOptions

CollaborationParticipantinterface

One validated identity visible through ephemeral collaboration presence.

interface CollaborationParticipant extends CollaborationIdentity

CollaborationRemoteSelectioninterface

Stable remote selection resolved into this replica's canonical paragraph addresses.

Anchor and head may name different paragraphs. A collapsed caret is the same address twice.

interface CollaborationRemoteSelection

CollaborationRemoteSelectionAddressinterface

One endpoint of a remote selection resolved into this replica's canonical addresses.

paragraphId is the stable w14:paraId. nodeId is replica-local and is used to paint.

interface CollaborationRemoteSelectionAddress

CollaborationRootSourceinterfaceSource ↗

What this component needs from a room, which every collaboration hook already returns.

Structural on purpose: useHocuspocusCollaboration, useWebrtcCollaboration and useDocumentCollaboration all satisfy it, and so does a host that owns its own resources.

interface CollaborationRootSource

CollaborationSessioninterfaceSource ↗

Host-facing collaboration session.

A host reads identity, status, presence, and undo. The editor attaches [EditorCollaborationSession](EditorCollaborationSession) internally and never through this type.

interface CollaborationSession

CollaborationStatusNoticePropsinterfaceSource ↗

Props for [DocxEditorCollaboration](DocxEditorCollaboration).Status.

interface CollaborationStatusNoticeProps

CollaborationStatusNoticeRenderPropsinterfaceSource ↗

What a custom [DocxEditorCollaboration](DocxEditorCollaboration).Status renders with.

interface CollaborationStatusNoticeRenderProps

CollaborationStatusSnapshotinterface

Cached status read. Same reference until one of its fields changes.

interface CollaborationStatusSnapshot

CreateDocumentCollaborationOptionsinterfaceSource ↗

Options for one full-document collaboration replica.

The caller owns ydoc.

interface CreateDocumentCollaborationOptions

CustomNodeChromePropsinterfaceSource ↗

Props for [CustomNodeChrome](CustomNodeChrome): which definitions to paint, and where activation goes.

The two hooks are the component-level twins of a definition's own onClick/onHover. Host UI state belongs here rather than on the definition, which every surface shares and which has no React context to close over.

interface CustomNodeChromeProps

CustomNodeContextMenuPropsinterfaceSource ↗

Props for [CustomNodeContextMenu](CustomNodeContextMenu): which definitions get menu sections, and which rows those sections offer.

The Edit row renders when either the definition's own onEdit or this component's onEditNode is present; the Remove row is on by default but only where the node's canonical id can be resolved.

interface CustomNodeContextMenuProps

DocxEditorCollaborationNamespaceinterfaceSource ↗

The collaboration presence compound.

interface DocxEditorCollaborationNamespace

DocxEditorCollaborationRootPropsinterfaceSource ↗

Props for [DocxEditorCollaborationRoot](DocxEditorCollaborationRoot).

Everything DocxEditor.Root takes except the three this component owns.

interface DocxEditorCollaborationRootProps extends Omit<DocxEditorRootProps, 'document' | 'modules'>

DocxEditorReviewNamespaceinterfaceSource ↗

The review rail compound.

interface DocxEditorReviewNamespace

ProLicenseOptionsinterfaceSource ↗

Accepted by every pro entry point.

interface ProLicenseOptions

ResolvedCustomNodeActivationinterfaceSource ↗

What [resolveCustomNodeActivation](resolveCustomNodeActivation) found under a pointer target.

The RAW decode, before the definition's fromDocx has had its say — use activatedCustomNodeOf for the enriched form every host hook receives.

interface ResolvedCustomNodeActivation

ResolvedReviewPaneinterface

The review pane settings in force, with every field resolved.

interface ResolvedReviewPane

ReviewActionPropsinterfaceSource ↗

Props for the action parts, which also take an icon.

interface ReviewActionProps extends ReviewPartProps

ReviewActivationOptionsinterface

How activating a review item places it in the viewport, and whether it announces the reveal.

interface ReviewActivationOptions

ReviewAdoptOptionsinterfaceSource ↗

Who and when an adopted change records.

interface ReviewAdoptOptions

ReviewBalloonPropsinterfaceSource ↗

Props for DocxEditorReview.Balloon, the balloon that opens a review item at its text: each tracked change under revisionsIn: 'balloons', and format and structural changes in every mode.

interface ReviewBalloonProps

ReviewDraftPropsinterfaceSource ↗

Props of DocxEditorReview.Draft.

interface ReviewDraftProps extends ReviewPartProps

ReviewItemRevealEventinterface

The payload of the reviewItemReveal event.

interface ReviewItemRevealEvent

ReviewMarkersPropsinterfaceSource ↗

Props for the collapsed rail's gutter markers.

scale, offset and window are the rail's own geometry and are supplied for you — an override inherits them, so a host passes only what it wants to change.

interface ReviewMarkersProps

ReviewModuleOptionsinterfaceSource ↗

How [reviewModule](reviewModule) is configured. Every field is optional, so reviewModule() with no argument is the ordinary call.

interface ReviewModuleOptions extends ProLicenseOptions

ReviewPaneOptionsinterface

Review pane settings to change. Every field is optional, and an omitted field keeps its current value.

interface ReviewPaneOptions

ReviewPartPropsinterfaceSource ↗

Shared props for every part.

interface ReviewPartProps

ReviewPropsinterfaceSource ↗

Props for DocxEditor.Review.

interface ReviewProps extends Omit<ReviewPartProps, 'children'>

ReviewRailMetricsinterfaceSource ↗

Where a review column sits, in the coordinates of the editor's scroll container.

Review anchors (item.anchorY) and stacked positions (useStackedReviewPositions) are in layout points from the top of the first page. These values convert them to CSS pixels.

interface ReviewRailMetrics

Position a card at its stacked anchor 


```ts
const top = metrics.top + positions.get(item.key)! * metrics.scale;
```

ReviewWriteRefusalinterfaceSource ↗

A review write the editor refused.

interface ReviewWriteRefusal

UseCollaborationStatusReturninterfaceSource ↗

Status returned by [useCollaborationStatus](useCollaborationStatus).

interface UseCollaborationStatusReturn

UseDocumentCollaborationOptionsinterfaceSource ↗

Input for [useDocumentCollaboration](useDocumentCollaboration).

interface UseDocumentCollaborationOptions

UseDocumentCollaborationReturninterfaceSource ↗

Values [useDocumentCollaboration](useDocumentCollaboration) returns.

interface UseDocumentCollaborationReturn

UseReviewRailMetricsOptionsinterfaceSource ↗

Options for [useReviewRailMetrics](useReviewRailMetrics).

interface UseReviewRailMetricsOptions

UseReviewReturninterfaceSource ↗

What [useReview](useReview) returns: the review rail's data and the things a card can do.

interface UseReviewReturn

CollaborationBootstraptypeSource ↗

Create or join bootstrap for one collaboration replica.

The document and WebRTC factories share this union.

create-or-join removes the out-of-band decision about which peer creates a room. The replica probes for an initialized room and joins it when one appears. Otherwise it runs a short awareness election and only the winning candidate seeds from document. A room that two peers seeded concurrently reports the terminal failure code concurrent-seed on every replica.

type CollaborationBootstrap = {
    readonly kind: 'create';
    readonly document: Uint8Array;
} | {
    readonly kind: 'join';
    readonly timeoutMs?: number;
    readonly signal?: AbortSignal;
} | {
    readonly kind: 'create-or-join';
    readonly document: Uint8Array;
    readonly probeTimeoutMs?: number;
    readonly electionWindowMs?: number;
    readonly timeoutMs?: number;
    readonly signal?: AbortSignal;
};

CollaborationFailureCodetype

Why a replica refused work, left ready, or failed a schema check.

Free-form extras (a transport phrase, a blob key, a store refusal) travel in [CollaborationFailure.detail](CollaborationFailure.detail), not here. Branch on the code; log the detail.

Codes are grouped by cause, and each group comment names the host action. In error, only a remote update that is not applied yet, or one refused local edit, heals on its own. The failure codes table in the collaboration reference lists every code. transport-disconnected and authentication-failed need opposite answers: wait for the first; refresh the credential and rejoin for the second. room-generation-changed means the server compacted the room while this replica was away: save a copy if it holds unsent changes, then rejoin.

type CollaborationFailureCode = 
/** Edit refused by the session gate. The status does not change. Wait for `ready`. */
'collaboration-session-destroyed' | 'collaboration-session-not-attached' | 'collaboration-session-not-ready' | 'collaboration-text-limit' | 'experimental-collaboration-body-text-only'
/** Factory input rejected before joining. Fix the value the host passed. */
 | 'invalid-document-id' | 'invalid-identity' | 'invalid-identity-color' | 'invalid-session-id'
/** Join or seed did not complete. Connect the provider, check the room id, and retry. */
 | 'already-initialized' | 'document-id-mismatch' | 'initialization-aborted' | 'initialization-timeout' | 'not-initialized'
/** The seed document cannot seed a room. Fix the file. */
 | 'baseline-too-large' | 'blob-read' | 'invalid-baseline' | 'missing-local-blob' | 'no-main-document-part'
/** This client and the room have different formats. Terminal. Save local work. */
 | 'collaboration-format-mismatch' | 'protocol-version-mismatch' | 'schema-version-mismatch'
/** The room is unusable. Terminal. Create a new room from saved bytes. */
 | 'blob-digest-mismatch' | 'concurrent-seed' | 'port-already-attached'
/** A remote update is not applied yet. Heals when a later update arrives. Wait. */
 | 'duplicate-paragraph-id' | 'invalid-relationships' | 'materialize-dropped-content' | 'missing-blob' | 'missing-root' | 'remote-apply-failed' | 'unknown-paragraph-id'
/** Over a resource limit. A local edit realigns; shared state over a limit is terminal. */
 | 'blob-store-full' | 'blob-too-large' | 'invalid-blob-descriptor' | 'invalid-bound' | 'invalid-logical-id' | 'invalid-string' | 'prototype-key' | 'text-too-long' | 'too-many-attributes' | 'too-many-children' | 'too-many-nodes' | 'too-many-parts' | 'too-many-relationships' | 'tree-too-deep' | 'unknown-logical-id' | 'unsafe-part-name'
/** Transport state. Only `transport-disconnected` recovers on its own. */
 | 'authentication-failed' | 'room-generation-changed' | 'transport' | 'transport-disconnected'
/** Reserved for a room server that refuses a saved room. Passed through, never emitted. */
 | 'invalid-saved-room' | 'saved-room-unavailable'
/** @deprecated Emitted by nothing. Kept for compatibility; do not branch on these. */
 | 'baseline-digest-mismatch' | 'experimental-collaboration-existing-paragraphs-only' | 'experimental-collaboration-text-only' | 'experimental-collaboration-untracked-text-only' | 'immutable-baseline-changed' | 'immutable-metadata-changed' | 'invalid-shared-metadata' | 'local-mirror-failed' | 'paragraph-set-mismatch' | 'shared-schema-invalid' | 'unsupported-root-key';

CollaborationNoticeKindtypeSource ↗

The notice the status part shows, or none while everything is in order.

- connecting: the session is joining the room. - offline: the transport is down and edits continue; they sync on reconnect. - offlinePaused: the transport is down and the session refuses edits until reconnect (offlineEditing: false). - syncing: the session hit an update it could not apply yet and heals on the next one. - waiting: edits wait until an update the room sent can apply. - stalled: edits have waited longer than STALLED_AFTER_MS; rejoining loads the room. - editRefused: the room refused the last edit, and the editor undid it. - outOfSync: this copy no longer agrees with the room; rejoining loads the room's copy. - upgradeRequired: this client and the room use different collaboration formats, and either side can be the older one. A rejoin cannot fix it; an upgrade of the older side can. - newRoomRequired: the room itself cannot continue (two seeds merged, a damaged blob, or a resource limit); a rejoin cannot fix it. Save a copy and share it in a new room.

type CollaborationNoticeKind = 'connecting' | 'offline' | 'offlinePaused' | 'syncing' | 'waiting' | 'stalled' | 'editRefused' | 'outOfSync' | 'upgradeRequired' | 'newRoomRequired';

CollaborationSelectionKindtype

How a published selection covers the document.

Absent or omitted means a character range. cells means the table rectangle whose corner cells contain the two endpoints. The payload still carries only those endpoints, so a large table selection does not grow with the number of selected cells.

type CollaborationSelectionKind = 'cells';

CollaborationStatustype

Lifecycle state of one collaboration replica.

One axis, because the only question a host has to answer is whether to tell the reader to wait or to reload:

- initializing — joining. Edits are refused. Recovers on its own. - ready — replicating. Accepts edits. - disconnected — the transport dropped. The replica is intact and recovers on its own, so wait rather than reload. Edits continue by default, and the buffered updates merge on reconnect. A session created with offlineEditing: false refuses them until reconnect. - error — this replica does not agree with the room. Edits are refused. [CollaborationStatusSnapshot.reason](CollaborationStatusSnapshot.reason) says why. A remote update the replica could not apply yet heals when a later update completes shared state ([CollaborationStatusSnapshot.recovering](CollaborationStatusSnapshot.recovering)). A format or version mismatch needs an upgrade of this client or the room; every other cause needs a rejoin. - destroyed — torn down. Terminal.

type CollaborationStatus = 'initializing' | 'ready' | 'disconnected' | 'error' | 'destroyed';

CommentMarkerStyletype

How a collapsed comment marker looks.

- 'initials': a badge with the thread author's initials in the author's color, a reply count, and a check mark when the thread is resolved. - 'icon': the comment icon.

type CommentMarkerStyle = 'initials' | 'icon';

ReviewDiagnosticCodetype

Why accepting, rejecting or re-authoring a tracked change skipped an item.

type ReviewDiagnosticCode = 'review.revision-unsupported' | 'review.incomplete-group' | 'review.retained-structure' | 'review.locked-content' | 'review.bound-content' | 'review.stale-revision';

ReviewItemRevealSourcetype

What asked to reveal a review item. See [ReviewItemRevealEvent.source](ReviewItemRevealEvent.source).

type ReviewItemRevealSource = 'navigate' | 'host';

ReviewItemViewtypeSource ↗

One card's data plus where it belongs on screen.

The engine's own placement, unchanged. It is already presentation-ready — author, initials, date, text, thread — because deriving those from the canonical tree is engine work, and an adapter deriving them would be document derivation in a host and would have to be written once per framework.

type ReviewItemView = ReviewItemPlacement;

ReviewPaneOpeningtype

When the review pane opens by itself.

- 'auto': the pane opens when a document with review items loads, and when a tracked change is made while it is closed, in both cases when the pane has items to list. With revisionsIn: 'balloons' the pane lists no tracked change and no reply to one, so tracked changes and their replies alone do not open it. - 'manual': the pane stays closed until the host or the user opens it. Use it when the host shows review items its own way, such as in balloons or margin markers.

type ReviewPaneOpening = 'auto' | 'manual';

ReviewPaneOverflowtype

What the open review pane does when its full card column does not fit beside the page at the page's zoom.

- 'float': the pane shrinks to a strip of markers, and the open card floats over the page. - 'shrinkPage': under a fit zoom mode, the page may shrink down to the mode's minZoom (or 10%) so that the full column fits. The pane changes to the marker strip only when the column does not fit at that floor either. A fixed zoom behaves as 'float'. - 'scroll': the page keeps the size it has beside the closed pane's marker strip, and the full column stands beside it. The document and the column scroll together: the viewport scrolls sideways to reach the cards.

The setting applies to the review pane only. The navigation pane stays docked at its side in every mode: it never scrolls with the document, and it takes its room beside the page exactly as it does with no review pane.

type ReviewPaneOverflow = 'float' | 'shrinkPage' | 'scroll';

ReviewWriteActiontypeSource ↗

The review write a refusal answered.

type ReviewWriteAction = 'accept' | 'reject' | 'resolve' | 'reopen' | 'remove' | 'reply' | 'comment';

RevisionDisplaytype

Where tracked changes open.

- 'pane': the review pane lists tracked changes as cards beside the comments. - 'balloons': the pane lists comments only, except comments that reply to a tracked change: the change's balloon shows those. A tracked change opens in a balloon at its text when the reader clicks it, or when Next Change, Previous Change, or setActiveReviewItem(key, { announce: true }) reaches it. A replacement is one balloon. In both settings, Next Change and Previous Change stop on a replacement once.

type RevisionDisplay = 'pane' | 'balloons';

ScrollPlacementtype

Where a scroll places its target in the viewport.

- 'start': near the top, like a jump to a heading. - 'center': centred. - 'centerIfNeeded': still while the target is on screen, centred when it has to move. - 'nearest': the minimum scroll, which leaves the target at the edge it came in from.

Each method that takes a placement states its own default.

type ScrollPlacement = 'start' | 'center' | 'centerIfNeeded' | 'nearest';

UseDocumentCollaborationConnectOptionstypeSource ↗

Arguments for [UseDocumentCollaborationReturn.connect](UseDocumentCollaborationReturn.connect): the createDocumentCollaboration options. The consumer owns ydoc, awareness, and whatever provider replicates them.

type UseDocumentCollaborationConnectOptions = CreateDocumentCollaborationOptions;

DocxEditorCollaborationconstSource ↗

Presence chrome over a live collaboration session.

Compose the parts inside DocxEditor.Root with the collaboration module registered:

DocxEditorCollaboration: DocxEditorCollaborationNamespace

```tsx
<DocxEditorCollaboration.Avatars session={session} max={4} />
<DocxEditorCollaboration.Status session={session} onRejoin={rejoin} />
<DocxEditorCollaboration.CaretLabels session={session}>
  {({ selection, color }) => <MyLabel name={selection.name} color={color} />}
</DocxEditorCollaboration.CaretLabels>
```

DocxEditorReviewconstSource ↗

The review rail: comments and tracked changes as a compound component.

DocxEditorReview is itself the root; every part hangs off it, so a host arranges the pieces it wants rather than accepting one fixed layout. Requires the review module to be registered via createDocxEditor({ modules: [reviewModule()] }) — without it there is nothing to derive cards from.

PARTS AND SCOPES. The rail reads its parts from its own children, by element type. There are two scopes:

- Root parts: List, Markers, AddComment, Draft, and Balloon. Put them as DIRECT children of DocxEditorReview (fragments are transparent). The rail gives them the geometry only it can compute: the comment button's and the compose box's top, and the markers' scale and window. A root part inside a wrapper component is not seen as a part. It renders as ordinary content, without that wiring. - Card parts: Card, Empty, and the parts inside a card (Author, Summary, Accept, Reject, Reply, and the others). Put them inside DocxEditorReview.List, or as other direct children, which become the card template.

preset={false} drops the packaged defaults. Root parts you pass still get their wiring, and every other child renders as is inside the rail, where useReviewRailMetrics() reads the rail's own measurement. To render your own cards, use useReview().items, useStackedReviewPositions, and useReviewRailMetrics. Draft without top sits where the packaged card stack puts it, so pass top from your own stack.

In a browser host, this rail and useReview() are the way to build a review UI. For headless, server, or agent pipelines, use @docx-editor.dev/editor-api.

DocxEditorReview: DocxEditorReviewNamespace

```tsx
<DocxEditorReview>
  <DocxEditorReview.List>
    <DocxEditorReview.Card>
      <DocxEditorReview.Author />
      <DocxEditorReview.Summary />
      <DocxEditorReview.Accept />
      <DocxEditorReview.Reject />
    </DocxEditorReview.Card>
  </DocxEditorReview.List>
</DocxEditorReview>
```

CustomNodeContextMenunamespaceSource ↗

declare namespace CustomNodeContextMenu