@agent-factory-platform/docs-react

Product-neutral rich document editor and repository bindings.

Install

npm install @agent-factory-platform/docs-react

Use the exact Agent Factory version across packages in one application.

Scope

Owns the rich-document editor, durable JSON serialization, transient image projection, and the shared CAS autosave coordinator. Storage, authentication and provider credentials belong to the consuming product; the editor does not upload directly to a cloud account.

Import the public styles before generating the application's Tailwind utilities, so component utility defaults cannot override application responsive variants:

@layer theme, base, components, utilities;
@import "@agent-factory-platform/docs-react/styles.css";
@import "tailwindcss";
@import "@agent-factory-platform/ui-kit/styles.css";

Render RichDocument with value, editable, placeholder, ariaLabel, and onChange. Save the emitted RichDocumentContent through the Docs client with the expected revision, retaining the local draft on conflict.

For images, onImageUpload(file) is a product callback: complete the Docs asset lifecycle and return { assetId, url } with a short-lived view URL. Supply resolveImage(assetId) to resolve existing revision-bound assets and refresh their URLs; return { url, expiresAt }. The callback closes over the authorized revision context. URL refreshes do not invoke autosave; only Asset IDs persist. Products without a signed object provider should omit image upload rather than return permanent or credential-bearing URLs.

Document Assistant uses the existing Agent session and v2 durable payloads. When supplying assistant, also supply onAssistantCommit so apply/rollback is committed with revision CAS before it is presented as saved.

DocsWorkbenchController and DocsWorkbench compose Space/tree/trash, revision, ACL/invite, indexing, translation and publication management around the generated Docs client. PublishedDocs renders only immutable anonymous release projections. Navigation generations fence late autosave responses so an old document cannot overwrite or reopen the current selection. Product routes, CDN and domains remain in the host.

DocsCollaborationController and DocsCollaboration open, follow, push and catch up durable opaque CRDT updates through browser-compatible unary/server-streaming RPCs. Presence stays transient while its latest shared snapshot supports cross-replica delivery. Capped exponential reconnect continues until explicit disconnect, authorization revocation or a permanent RPC rejection and uses the durable server sequence. The adapter coalesces offline Yjs transactions into update-sized chunks and replays each unacknowledged chunk with the same clock and bytes. Catch-up and live updates advance only as one contiguous sequence. Each editor instance keeps a distinct, reconnect-stable clock namespace scoped by the authenticated subject. The service replaces caller-supplied awareness client IDs and clocks, while the adapter renders names from authenticated presence metadata. YjsDocsCollaborationAdapter binds that transport to a Y.Doc and Yjs awareness; pass adapter.editorCollaboration to RichDocument to render remote selections and carets. checkpoint(expectedRevision, persist) first drains durable updates and gives persist both the document revision and collaboration sequence. Forward both to SaveRevision; the service atomically rejects either stale token. Pending edits remain queued across transient failures; explicit disconnect makes flush and checkpoint fail until that adapter reconnects. Use disconnect for a temporary React unmount and destroy only when the editor session is finished.

DocsAutosaveController debounces a host-supplied CAS persist callback, serializes checkpoints, and immediately follows an in-flight save when newer edits exist. It retains dirty state across offline and failed saves, exposes retry and observable dirty/saving/saved/offline/error/denied states, and only carries a server-returned updatedAt value into the saved snapshot.

One collaboration update is limited to 65,536 bytes. An oversized local Yjs update fails flush/checkpoint without sending partial state, keeps the local document, and can recover after the document is reduced below the limit. Invalid input and clock conflicts are terminal for the current connection instead of reconnecting forever.

Documentation

API and package documentation: https://www.npmjs.com/package/@agent-factory-platform/docs-react

Reconnect preserves rejected oversized state: checkpoint remains blocked until the local document can be reconstructed from acknowledged updates. Retried updates keep their original clock and bytes; later edits cannot merge into an assigned clock. Native Yjs Awareness renews idle presence approximately every 15 seconds. The shared repository expires it after 30 seconds without a client update; reconnect preserves edit authorization and the editor's durable clock namespace.

Resource permissions and bounded lists

getResourcePermissions({ spaceId }) or { resource: { target: { case: "nodeId", value: nodeId } } } returns current caller presentation hints. write edits the resource (Space metadata requires ownership); writeTree permits structural commands; manage manages that resource's grants; manageSpace manages Space metadata/archive; leave permits leaving the containing Space. Node grants do not imply Space management. All writes still authorize on the server.

The controller keeps spacePermissions and nodePermissions; refresh/open rechecks them. Authorization or request failures clear hints. Content does not depend on owner-only management endpoints; managementError reports their failure independently. Hosts should refresh after ACL changes and on focus.

Lists load 50 items per request. Inspect nextPageTokens[list] and call loadMore(list) for spaces, nodes (root children), documents, trash, revisions, acl, or invites. The reference view exposes continuation buttons. An absent token is exhausted; account/navigation changes discard late responses.

Supply resolvePublishedAsset to PublishedDocsController for public images. The controller pins the loaded release version, node, and revision; Factory signs only an asset in that immutable projection. Unsaved uploads can use local Blob previews; authenticated resolveAsset requires a saved revision reference.