Private, optional React 19 bindings. Supply one headless PresenceStore from
@barocss/doc-sync/presence and a projector from @barocss/doc-sync-presence-ui.
The shared DOM renderer owns avatar, cursor, selection, and draft visuals.
Names appear on hover. This package adds no transport or editor geometry.
This package is private, version 0.0.0, and not published to npm. Use the
repository workspaces or local tarballs, not a registry install of this name.
Node 22.18 or later is required for repository tooling. From the repository root:
npm ci
npm run build
npm run test --workspace @barocss/doc-sync-presence-reactFor a separate application, pack the required workspaces from this checkout:
mkdir -p artifacts
npm pack --workspace @barocss/doc-sync --pack-destination artifacts
npm pack --workspace @barocss/doc-sync-presence-ui --pack-destination artifacts
npm pack --workspace @barocss/doc-sync-presence-react --pack-destination artifactsInstall those generated .tgz files together in the consuming application. Required peers are
@barocss/doc-sync >=0.0.0 <0.1.0,
@barocss/doc-sync-presence-ui >=0.0.0 <0.1.0, and react ^19.2.0 (and react-dom in a browser application).
Use your framework’s normal build setup; these are ESM packages.
import {PresenceOverlay, PresenceProvider} from '@barocss/doc-sync-presence-react';
function EditorPresence({store, projector}) {
return <PresenceProvider store={store}>
<PresenceOverlay options={{projector}} style={{position: 'relative', height: 320}} />
</PresenceProvider>;
}PresenceOverlay accepts store directly, or gets it from PresenceProvider.
options is PresenceUIOptions; projection rectangles use viewport CSS pixels.
Place the host in your editor's overlay container and set className or style
as needed. AvatarStack, CursorLayer, SelectionLayer, and DraftPreview
accept the same props and enable only their own visual layer.
usePresence(store?) uses useSyncExternalStore and returns the stable store
snapshot. usePresenceStore(store?) resolves the explicit or provided store.
Imports and initial rendering do not read browser globals. Effects mount the DOM
renderer and dispose it on unmount or store replacement. React Strict Mode can
mount again without retaining the old subscription. The caller owns the store
and network client; these bindings never dispose or disconnect them.
Create the store once per client actor in your application, not on each render:
import {createPresenceStore} from '@barocss/doc-sync/presence';
import {createPresenceProjector} from '@barocss/doc-sync-presence-ui';
const store = createPresenceStore({actor: 'demo-replica', ttlMs: 30_000});
store.updateLocal({profile: {name: 'Demo'}, activity: 'active'});
// Avatar-only setup: deliberately no geometry adapters.
const projector = createPresenceProjector({});Pass this store and projector to the example above. This local example opens no
network connection. For real collaboration, use connectClientPresence from
@barocss/doc-sync/presence with your synchronized client. Give concurrently active
replicas distinct actor IDs. The store starts no expiry timer: the application
must call expire() if it needs time-based removal. Dispose the UI first, then
the bridge and store when their owning application closes. Never dispose a shared
store merely because one view unmounts.
The empty projector renders avatars but intentionally draws no document targets.
Supply document-anchor, canvas-object or sheet-cell adapters for cursors, selections
and drafts. Each adapter must return viewport CSS-pixel rectangles or null for
hidden, deleted, offscreen or unresolved targets. These geometry adapters belong
to your editor; they are not supplied by this package. Give the overlay a nonzero
size matching the editor viewport.
Presence is ephemeral display state, not document persistence, edit authorization or an acknowledgement protocol. Names and bot labels grant no authority. Draft text can reveal uncommitted input to other participants: publish it only when your application intends to share it. No wrapper commits text, installs an editor, or creates undo history. The shared renderer uses text nodes rather than interpreting participant names or drafts as HTML.
- Presence components, connection and projection guide
- Package composition and engine boundaries
- Source and tests
- Run
npm run dev:presencefrom the repository root for the five-framework playground.
Package tests exercise renderer or framework lifecycle/SSR behavior; they do not prove your editor’s coordinate mapping, network authorization, production deployment or real IME behavior. Validate those integrations separately.