UIBot document integration

@uibot/document-editor provides a rich editor, outline and Spec document pages. The host owns document storage, access checks, revisions and model services. Source availability does not confirm npm publication or production integration.

Choose a page

• document-writing: focused editing.
• document-reading: readonly content with an outline derived from current headings.
• document-library: document selection with unsaved-edit protection.
• document-assistant: document editor and an independently bound chat surface.

Read the resource's complete Spec, controls, dependencies and limitations. Compile with DOCUMENT_SPEC_CATALOG from @uibot/document-editor/catalog. The assistant page also needs CHAT_SPEC_CATALOG from @uibot/ai-chat/catalog and STUDIO_CATALOG_ENTRIES from @uibot/blocks-studio/catalog for its responsive Grid. Register Grid from @uibot/blocks-studio, createDocumentSpecEntries from @uibot/document-editor/spec, and createChatSpecEntries from @uibot/ai-chat/spec. Use the consumer's existing registry assembly rather than replacing its entries. Import @uibot/document-editor/style.css in the browser entry.

Spec document pages inherit the nearest host light/dark class or explicit data-theme / data-color-scheme marker, falling back to CSS color-scheme and then light. The editor and floating controls share that preference even when the operating system uses another theme. Switching appearance preserves the editor session and unsaved content. Direct DocumentEditor / BlockEditor consumers can still pass theme="light" for white paper and dark text or theme="dark", or provide their own theme object.

Host document binding

createDocumentSpecEntries({ resolveHost }) resolves each binding ID to a DocumentSpecBinding. For direct React use:

import { DocumentWorkspace, type DocumentSpecBinding } from "@uibot/document-editor/spec";
import "@uibot/document-editor/style.css";

export function WritingPage({ binding }: { binding: DocumentSpecBinding }) {
  return <DocumentWorkspace binding={binding} autoSaveMs={0} />;
}

The binding contains document: EditableDocument and client: DocumentEditorClient. Supply blocks when available; markdown is a lossy fallback for initial content. Opening another document requires a new document ID or remount. Switch binding ID or remount on tenant/authorization changes, even if host-local document IDs match. Preview state controls never replace an injected host draft.

The save client receives ID, title, blocks, markdown, expectedRevision and idempotencyKey. Authorize the document and fields, compare revisions and write atomically, then acknowledge the stored document and revision. A successful HTTP request alone is not a successful document save. Handle these outcomes explicitly:

• Success advances the next expected revision; edits made during the request stay dirty.
• Conflict preserves the draft. Supply the remote document to enable the explicit keep-local or load-remote actions. Loading an empty remote body clears the editor.
• Failure preserves input. Unknown results do not retry automatically; an explicit retry of identical content keeps the original idempotency key. Reconcile that operation in the host before attempting another write.

autoSaveMs: 0 enables manual save; positive values debounce dirty-document saves. Readonly documents disable editing and saving. Uploads require client.uploadFile.

Assistant context and write boundaries

The built-in assistant page has separate document and chat binding IDs. It does not automatically send editor content, selected text or unsaved drafts to a model, and a chat reply does not replace document blocks. Map approved context explicitly in the host; reauthorize every model request. Read package:uibot-ai-chat docs for transport, citation identity, stop and late-event behavior.

If current unsaved content is required, compose the lower-level BlockEditor with its onChange / getValue seam in the host. Make the chosen context and write action explicit, protect newer edits and use the normal revision/idempotency protocol. Do not mutate the editor DOM or infer authorization from a Spec binding ID.

Preview and adoption checks

Only a trusted host can enable demo: true; Spec cannot do so. Demo documents and chat state are session-local. Their “Saved” status is an in-memory acknowledgement, not persistence evidence. Recompilation may reset this data. Playground export saves configuration, including authored initial markdown, rather than runtime edits.

Verify strict compilation, declared controls, configuration undo/export/reopen, manual and automatic saves, failure/unknown/conflict outcomes, empty remote content, late acknowledgements, readonly behavior and mobile layout. Verify Studio artifact revision saves separately from document-client saves. Record local demonstrations, real host integration and distribution evidence separately.