Document API Reference

Document API Reference

This page is the lookup for the document-session API: handle creation, the headless document hook, schema helpers, policies, limits, and errors. Components consume a handle; they do not create one.

Create a document handle

createNativeEditorDocumentHandle(config) returns an opaque NativeEditorDocumentHandle. Create it once per local document or room lifetime and call destroy when that owner unmounts.

const handle = createNativeEditorDocumentHandle({
  initialization: { type: 'localHtml', html: '<p>Draft</p>' },
  policy: { maxLength: 10_000 },
  limits: { resource: { maxInputBytes: 8 * 1024 * 1024 } },
});

NativeEditorCreateConfig

Field	Type	Meaning
initialization	NativeEditorInitialization	Required. Selects the first local document or a collaboration room.
schema	SchemaDefinition	Optional; defaultSchema is used when omitted. This is fixed for the handle lifetime.
fragmentName	string	Optional document-fragment identity. It participates in room snapshot compatibility.
policy	object	Optional engine policy: maxLength?, readOnly?, inputFilter?, allowBase64Images?.
limits	object	Optional creation-time limits: resource?, editing?, collaboration?.

NativeEditorInitialization is a discriminated union:

type	Fields	Use
localEmpty	none	Start with the active schema's valid empty document.
localJson	json: DocumentJSON	Start with schema-valid JSON.
localHtml	html: string	Start by parsing HTML with the handle schema and policy.
room	documentId, lineageId, snapshot?	Start a Yjs room. Without a snapshot it stays AwaitRemote until the server's accepted document arrives.

NativeEditorRoomSnapshot is metadata: NativeEditorSnapshotMetadata and encodedState: Uint8Array. Metadata contains formatVersion, documentId, lineageId, fragmentName, and schemaFingerprint. All five must match the receiving room when a snapshot is restored or used at creation.

NativeEditorDocumentHandle

The factory is the only way to obtain an authentic handle. Its public members are:

Member	Behavior
editorId	Read-only decimal-string session ID.
isDestroyed	Read-only lifecycle flag.
destroy()	Ends the native session; repeating it is safe.
addErrorListener(listener)	Observes autonomous typed document API errors and returns an unsubscribe.
configureCollaborationTransport(config)	Attaches, changes, or detaches a room transport. A room handle is required.
setLocalAwareness(intent)	Publishes local awareness, or null to withdraw it.
addCollaborationTransportListener(listener)	Subscribes to state, error, and protocol-adapter events; returns an unsubscribe.
bridge	The handle-bound imperative bridge. It is a property of the handle, but its implementation class is not a separate root export. Use the high-level editor ref or useNativeEditorDocument unless you need snapshot or transport recovery operations.

The bridge can get current state/content/snapshots, produce a render snapshot, replace a document, apply low-level input/commands/local API operations, set selection, undo/redo, export or restore a snapshot, configure transport, and publish awareness. Low-level request record types are intentionally not package-root exports; high-level UI should use Content and State, RichTextEditor Reference, and Collaboration instead.

NativeEditorState contains documentState, transportState, renderState, documentRevision, documentOrigin, stateRevision, canUndo, and canRedo. Revisions are decimal strings. documentOrigin is nativeView, jsApi, remoteCollaboration, history, restore, or import. documentState is LocalReady, AwaitRemote, or RoomReady. transportState is Detached, Disconnected, Connecting, Handshaking, Synchronized, Incompatible, Destroying, or Destroyed. renderState is Loading or Ready.

useNativeEditorDocument

useNativeEditorDocument(options) is the headless binding for an existing handle. It never creates or destroys one.

UseNativeEditorDocumentOptions field	Meaning
handle	Required shared NativeEditorDocumentHandle.
value, valueJSON	Optional controlled HTML or JSON. HTML wins when both exist.
valueJSONUpdateMode	replace (default) or reset. replace is undoable; reset discards pending native input/composition and clears history.
revisionSignal	Optional string or null that forces an engine refresh, commonly a collaboration documentRevision.
onContentChange, onContentChangeJSON	Content callbacks for externally observed changes.
onHistoryStateChange	Undo/redo capability callback.
onLocalCommit	Application notification after a successful local mutation.

UseNativeEditorDocumentReturn contains isReady, documentState, documentRevision, documentOrigin, historyState, refresh, getContent, getContentJson, getTextContent, setContent, setContentJson, clearContent, undo, redo, canUndo, and canRedo.

The hook returns empty getters and false history capability while a room is AwaitRemote. A controlled apply that loses a revision race refreshes and re-applies against the fresh engine revision; it never retries against guessed positions.

Schemas and fragments

Export	Contract
defaultSchema / defaultSchemaSpec	Default compiled and keyed schemas. They use canonical ProseMirror snake_case node names; defaultSchema is the same object as prosemirrorSchema.
prosemirrorSchema / prosemirrorSchemaSpec	Compiled and keyed schemas with snake_case list and void-node names.
tiptapCompatibleSchema / tiptapCompatibleSchemaSpec	Compiled and keyed compatibility schemas with camelCase list and void-node names.
defineSchema(spec)	Compiles a keyed, ProseMirror-shaped SchemaSpec into a serializable SchemaDefinition, including attribute-driven node projections and optional atoms.
SchemaSpec	Keyed nodes, optional keyed marks, and optional AtomNodeDefinition array.
SchemaNodeSpec / SchemaMarkSpec	Public authoring specs with attrs, DOM rules, roles/content, and schema options.
ParseDOMRule / DOMOutputSpec / AttributeDOMOutputSpec	Declarative HTML parsing, static output, and attribute-driven output types.
SchemaDefinition	nodes: NodeSpec[]; marks: MarkSpec[].
NodeSpec	Compiled name, content, role; optional group, attrs, htmlTag, html, json, isVoid, allowUndeclaredAttrs.
MarkSpec	name; optional attrs, excludes, htmlTag, allowUndeclaredAttrs.
NodeHtmlRules	Void-node HTML tag plus optional staticAttrs and attrMap.
NodeJSONProjection	Public JSON type and optional fixed attrs for a compiled native node variant.
AttrSpec	Optional default, type, enum, min, and max. An attribute without a default is required. Constraints participate in schema validation and fingerprints; see Schema Customization.
ResolvedDocumentSchema	schema, documentNodeName, emptyDocument. Returned by resolveDocumentDescriptor.
resolveDocumentDescriptor(schema?, limits?)	Validates a supplied schema and returns its root name and schema-valid empty document.
IMAGE_NODE_NAME	The literal image node name: image.
ImageNodeAttributes	src required; alt, title, width, height optional and nullable.
imageNodeSpec(name?)	Returns the standard void block image specification; name defaults to image.
withImagesSchema(schema)	Appends the standard image node only when one named image is absent.
buildDocumentFragmentJson(content, descriptor?)	Creates a fragment root using the resolved document node name, doc by default.
buildImageFragmentJson(attrs, descriptor?)	Creates a one-image fragment for insertContentJson.

The previous tiptapSchema root export was replaced by tiptapCompatibleSchema. New handles use snake_case names by default; pass the compatibility schema explicitly when reading existing camelCase documents.

Schema identity is persistence and collaboration identity. Keep schema, fragmentName, and resource policy compatible for every writer, viewer, and saved room snapshot. See Schema Customization and Custom Atom Nodes.

Image policy and resource limits

EditorImageLoadingPolicy has optional positive-safe-integer fields maxSourceBytes, connectTimeoutMs, readTimeoutMs, requestTimeoutMs, maxConcurrentRequests, maxPendingRequests, maxDecodeDimensionPx, and maxDecodedBytes.

Export	Purpose
DEFAULT_EDITOR_IMAGE_LOADING_POLICY	10 MiB source; 10s connect; 20s read; 60s request; 2 concurrent; 64 pending; 2048 px decode; 32 MiB retained decoded pixels.
HARD_EDITOR_IMAGE_LOADING_POLICY	64 MiB source; 10 min connect/read/request; 16 concurrent; 512 pending; 8192 px decode; 256 MiB retained decoded pixels.
resolveEditorImageLoadingPolicy(policy?)	Applies defaults or throws NativeEditorBoundaryError IMAGE_POLICY_INVALID for a non-positive, unsafe, or over-ceiling value.
ResolvedEditorImageLoadingPolicy	The required, validated version of the image policy.

EditorResourceLimits contains maxInputBytes, maxDocumentNodes, maxDocumentDepth, maxSchemaNodes, maxSchemaExpressionBytes, maxCollaborationMessageBytes, and maxEncodedStateBytes. DEFAULT_EDITOR_RESOURCE_LIMITS resolves to 20 MiB, 100000 nodes, depth 256, 1024 schema nodes, 64 KiB schema-expression bytes, 10 MiB collaboration-message bytes, and 50 MiB encoded-state bytes. HARD_EDITOR_RESOURCE_LIMITS is respectively 64 MiB, 1000000, 1024, 10000, 1 MiB, 64 MiB, and 256 MiB.

EditorEditingLimits offers maxOperationsPerTransaction, maxUndoGroups, maxUndoRetainedUnits, and maxDerivedOutputBytes. EditorCollaborationLimits offers maxFramesPerMessage, maxFrameBytes, maxAggregateResponseBytes, maxAwarenessPeers, maxAwarenessPeerBytes, maxAwarenessBytes, maxPendingOutboxMessages, maxPendingOutboxBytes, maxPendingDependencyUpdateBytes, and maxPendingDependencyUpdateWork.

resolveEditorResourceLimits(resource?) validates and fills resource defaults, returning ResolvedEditorResourceLimits with every resource field required. Creation validates every supplied resource, editing, and collaboration limit; invalid creation limits become NativeEditorEngineBoundaryError with code INVALID_RESOURCE_LIMIT. See Production Limits and Errors for ceilings and operational guidance.

Errors

Export	Contract
NATIVE_EDITOR_BOUNDARY_ERROR_CODES	Known legacy codes: INVALID_RESOURCE_LIMIT, CONFIG_INVALID, INPUT_LIMIT_EXCEEDED, CONFIG_PARSE_FAILED, DOCUMENT_PARSE_FAILED, DOCUMENT_INVALID, DOCUMENT_LIMIT_EXCEEDED, POSITION_LIMIT_EXCEEDED, SCHEMA_INVALID, REQUIRED_ATTRIBUTE_MISSING, UNKNOWN_MARK, MAX_LENGTH_EXCEEDED, MUTATION_REJECTED, COLLABORATION_DECODE_FAILED, COLLABORATION_APPLY_FAILED, SESSION_NOT_FOUND, IMAGE_POLICY_INVALID, IMAGE_REQUEST_TIMEOUT.
NativeEditorBoundaryErrorCode	Known code suggestion plus forward-compatible string.
NativeEditorBoundaryError	Legacy Error with code and optional numeric limit, actual, details.
parseNativeBoundaryError(value)	Parses only an envelope shaped like error: code/message/...; returns null when unrecognized.
NativeEditorErrorDomain	boundary, document, operation, lifecycle, snapshot, transport.
NativeEditorError	Normalized typed error fields: domain, code, message, requestId, operationIndex, limit, actual, details. Numeric-looking envelope fields are decimal strings or null.
NativeEditorErrorBase	Base Error class for typed document API failures.
NativeEditorEngineBoundaryError, NativeEditorDocumentError, NativeEditorOperationError, NativeEditorLifecycleError, NativeEditorSnapshotError, NativeEditorTransportError	Domain-specific subclasses.
NATIVE_EDITOR_NON_RETRYABLE_CODES	ENGINE_INVARIANT_FAILED, ENGINE_DESTROYING, ENGINE_DESTROYED.
NativeEditorNonRetryableError	Typed error for a failure that cannot succeed again on this handle.

Do not loop retries for non-retryable, document, policy, snapshot-scope, or configuration errors. For REVISION_MISMATCH, read fresh state and decide whether the user intent remains valid. See Production Limits and Errors.

Related pages

• Content and State
• Schema Customization
• Collaboration
• Types and Events Reference