@domternal-pro/extension-collaboration

Real-time collaboration for Domternal: binds the editor to a shared Yjs document and provides collaboration-aware undo/redo, which must be used instead of the regular History extension so each user undoes only their own edits.

Links

Documentation    •    Live examples

Licensing

This is a commercial package distributed through the public npm registry. A DOM-connected editor surface remains fully featured without a key for internal evaluation and shows a small evaluation badge. Guarded headless, standalone, server and worker operations have no badge surface, so they require an explicit evaluation mode or production mode with a covered DMP2 Commercial Key. Evaluation does not permit production use.

Keyless headless evaluation is explicit and remains fully functional:

import { configureProLicense } from '@domternal-pro/core';

configureProLicense({ mode: 'evaluation' });

Production uses the signed Commercial Key from the Order confirmation:

import { configureProLicense } from '@domternal-pro/core';

configureProLicense({
  mode: 'production',
  key: 'DMP2...',
});

A Commercial DMP2 Key carries exactly one signed Product Line. Every registered commercial package in an ordinary release must carry that same Product Line. A security-only release must carry it in both package metadata and its separate DMS1 certificate. Missing, conflicting or mismatched Product Line metadata remains uncovered and does not activate production. DMS1 never changes the key or grants another Product Line. Evaluation, Internal and legacy DMP1 keys do not use this Commercial Product Line field.

The signed key payload is not encrypted and may be readable in delivered browser code. Permitted embedding is expected, but the raw key must remain within the Customer scope allowed by the license. DMP2 omits Customer identity, contact details, Order reference, plan, price, separate payment and paid-through fields, and Developer limits. Commercial entitlement and per-key identifiers are random and opaque; the public status API does not expose them.

License validation runs entirely offline and never contacts Domternal: there is no online activation, license telemetry, metering, seat-counting or revocation request. A DMP2 Evaluation Key can remove visible evaluation notices only in explicitly selected evaluation mode and only through its signed UTC expiry day; it can never activate production mode. In production mode it remains visibly badged or marked. A DMP1 key is recognized only for legacy diagnostics: it leaves editor badges and marked-output notices in place and never authorizes guarded production use. A DMP2 Commercial Key does not activate before its signed not-before day. For ordinary and renewal keys that day is the Subscription start; an exceptional surviving-rights or remedy key can use the later decision or issuance day required by the license. During its paid Subscription and 14-day grace period, ordinary package coverage stops at its signed ordinaryReleaseThrough day; grace does not extend that boundary. After grace, a key without signed technical post-grace eligibility reports subscription-expired. A technically eligible key can continue coverage through ordinaryReleaseThrough, qualifying DMS1 releases and exact Section 10 remedy days, while the public status exposes a compatible derived fallbackThrough equal to ordinaryReleaseThrough. That technical marker does not prove 12 paid months or define the surviving legal scope: the Agreement and accepted Order define the legal scope, while the key and minimum durable entitlement state support later recognition of that scope, including whether it covers Qualified Builds, discontinuation final retained builds or another express surviving right. Post-expiry use is runtime-only for the exact permitted artifacts. Development, modification, rebuilding and new Applications require an active Subscription, subject only to the Agreement's narrow security, intellectual-property and replacement-key exceptions. A key-only reproduction changes no other code, dependency or feature and inherits the original build status. The contractual post-expiry Developer limit remains as a final derived value in the minimum durable entitlement state while it is relevant; supporting Order, payment and calculation records follow their separate retention periods; the runtime does not count people or expose that limit. Rights from different expiries remain attached to their own Commercial Keys. Coverage therefore uses both baked package release dates and the current UTC day reported by the runtime. Guarded headless production activates only when that Commercial Key covers every registered Pro package. Each JavaScript context that runs guarded headless work needs its own configuration. Activation is technical, not the license itself: permitted use is defined by LICENSE.md. See Installation and licensing for the complete setup.

Security-only releases use a separate signed DMS1 Security Release Certificate embedded in the package set; DMS1 does not add fields to or modify the Customer's DMP2 key. During the paid Subscription and grace, DMS1 requires a signed feature-baseline Release Date on or before ordinaryReleaseThrough; after grace, the key must also have technical post-grace eligibility. An exact Section 10 replacement date does not establish DMS1 baseline eligibility. A key without post-grace eligibility is never revived after grace. DMS1 does not renew a Subscription, move an ordinary-release boundary, change a Developer limit, unlock features or grant another Product Line. Post-expiry use is limited to the narrow security replacement of an eligible artifact, with no unrelated code, dependency or feature change, and the result inherits that artifact's status. The fixed Product Line Security Support End Date ends the obligation to issue further Security Updates, subject to mandatory law. An eligible DMS1 update signed and released during that period may remain usable afterward only within the same existing or surviving production right and limits; continued use does not make the Product Line supported or create, restore, renew or expand a right. The controlling terms are in Section 8 of LICENSE.md and the public security policy.

Constructing Collaboration without an element, or with element: null, is guarded as true headless initialization. An explicitly supplied detached HTMLElement is accepted as a pending framework-wrapper mount. Local document transactions and undo or redo still reclassify the live DOM immediately before mutation, so a pending editor that never connects and an editor detached later cannot keep authoring in unactivated production mode. Inbound Yjs synchronization remains readable while detached. If another editor plugin derives a local appendTransaction mutation from an inbound update, that derived mutation is skipped while detached production use is blocked, so it cannot reject the received root update. A future derived mutation can run after connection or explicit activation; the skipped mutation is not queued or replayed. seedOnFirstSync keeps its own mutation guard. The Vite configuration entry, document-position adapter, status reads, teardown and data-recovery operations remain import-safe and available without a production assertion.

Install

pnpm add @domternal-pro/core @domternal-pro/extension-collaboration yjs@^13.6.8 y-prosemirror@~1.3.7 prosemirror-model@^1.25.11

@domternal-pro/core, yjs, y-prosemirror, @domternal/core and @domternal/pm are peer dependencies: they must resolve to a single instance each in your app. @domternal/pm ships prosemirror-model as a dependency while y-prosemirror declares it as a peer, so the two can settle on different copies, and ProseMirror compares classes by identity: the binding then fails on the very first, empty document with "Can not convert <> to a Fragment (looks like multiple versions of prosemirror-model were loaded)".

The extension checks for that before it builds a plugin and throws an error naming both packages and the fix, rather than letting y-prosemirror report it without either. A duplicated y-prosemirror is checked too: collaboration, the caret and version history all look the binding up by the object identity of ySyncPluginKey, so a second copy does not error, it silently finds nothing.

Keep y-prosemirror inside ~1.3.7; that is the range all three packages declare, and an unsatisfied peer is how npm and yarn end up nesting a second copy. Full dedupe recipe per package manager and bundler: https://domternal.dev/v1/guides/single-prosemirror-copy/

Vite

The package ships the maintained Vite dedupe list on a config-only subpath:

import { defineConfig } from 'vite';
import { collaborationViteDedupe } from '@domternal-pro/extension-collaboration/vite';

export default defineConfig({
  resolve: {
    dedupe: collaborationViteDedupe,
  },
});

Every id in the list must be reachable from the application root. The full guide above lists the direct ProseMirror dependencies for pnpm's strict layout. Importing this helper in vite.config.ts does not add Collaboration code to the browser bundle.

Usage

import { Editor, StarterKit } from '@domternal/core';
import { Collaboration } from '@domternal-pro/extension-collaboration';
import * as Y from 'yjs';

const ydoc = new Y.Doc(); // connect it via Hocuspocus, y-websocket, ...

const editor = new Editor({
  element: document.querySelector('#editor'),
  extensions: [
    StarterKit.configure({ history: false }),
    Collaboration.configure({ document: ydoc }),
  ],
});

Collaboration cannot run next to the History extension (the editor refuses to construct with a configuration error). Do not pass initial content to a collaborative editor: the shared document is the source of truth.

Options

| Option | Default | Description | | --- | --- | --- | | document | null | The shared Y.Doc. The editor binds to the fragment named by field. | | field | 'default' | Name of the Y.XmlFragment inside document. Keep server seeding in sync with it. | | fragment | null | Bind to a Y.XmlFragment directly (multiple editors on one document). Provide either document or fragment, never both. | | ySyncOptions | null | Passed through to y-prosemirror's ySyncPlugin. | | yUndoOptions | null | Passed through to y-prosemirror's yUndoPlugin (for example a shared UndoManager). |

The exported DEFAULT_COLLAB_FIELD constant ('default') is the field default; pass it explicitly to y-prosemirror helpers such as prosemirrorJSONToYDoc, whose own default is 'prosemirror'.

Storage

editor.storage.collaboration exposes document, fragment, undoManager and docAdapter (the document-position adapter other pro extensions consume; the AI overlay anchors its review through it). The undo/redo commands, toolbar buttons and Mod-Z/Mod-Shift-Z/Mod-Y shortcuts are registered by the extension.

Connection status: @domternal-pro/extension-collaboration/status

The subpath entry ships CollaborationStatus, a small companion extension publishing the provider's connection and sync state, so apps stop hand-rolling provider event plumbing for a status pill:

import { CollaborationStatus } from '@domternal-pro/extension-collaboration/status';

CollaborationStatus.configure({
  provider,                                  // HocuspocusProvider or y-websocket out of the box
  onStatusChange: (status) => { ... },       // 'connecting' | 'connected' | 'disconnected' | 'auth-failed'
  onSyncedChange: (isSynced) => { ... },
});
// current values: editor.storage.collaborationStatus.{status,isSynced}

auth-failed is its own status because the websocket opens before the server checks the token, so a pill keyed on the socket alone briefly lies about a rejected client. Providers with a different event vocabulary plug in via the adapter option.

The same subpath exports seedOnFirstSync(provider, fragment, build): runs build exactly once, after the provider's first successful sync, and only if the fragment is still empty then, in a transaction that stays out of every user's undo history. Server-side seeding remains the recommended default. This is the safe version of the client-side pattern.

Remote carets and presence live in @domternal-pro/extension-collaboration-caret.

Support

Report a defect that reproduces with synthetic content on the public tracker, using the Pro bug report template. Anything involving your own documents, your data or a collaboration update goes to email instead, and security vulnerabilities go to email only.

The Support and reporting issues policy explains where confirmed defects may be documented and how material notices are handled. Public channels are not a complete record of internal reports, investigations or other issues. Security vulnerabilities are handled through coordinated private disclosure.