AI-native design editor. Open-source Figma alternative.
import { isEmptyObject, isEqual, omit, pickBy } from 'es-toolkit'
import * as Y from 'yjs'
import type { SceneGraph } from '@open-pencil/scene-graph'
import { siblingOrderKeys } from '@open-pencil/scene-graph/order-keys'
import type { CollabEditor } from './editor'
import { decodeNodeFromYjs, DOCUMENT_NODE_FIELDS, syncEncodedNodeToYMap } from './node-codec'
import {
claimRoot,
markTreeFormat,
readRoot,
writeOrderKey,
writePage,
writeParentEntry,
writeRootEntries,
type YNodes
} from './shared-tree/fields'
import {
applySharedTree,
createLocalEdit,
createSharedTree,
isLocalEditEmpty,
keepSharedLayers,
mergeLocalEdit,
pageOf,
recordLocalLayers,
writeLocalPlacement,
type LocalEdit,
type SharedTree
} from './shared-tree/sync'
type YImages = Y.Map<Uint8Array>
type GraphBindingOptions = {
editor: CollabEditor
getYdoc: () => Y.Doc | null
getYnodes: () => YNodes | null
getSuppressGraphSync: () => boolean
syncLocalEdit: (edit: LocalEdit) => void
}
type YjsObserverOptions = {
editor: CollabEditor
ynodes: YNodes
yimages: YImages
/** Whether the room names an image by reference, which keeps it when its bytes leave. */
hasImageRef?: (name: string) => boolean
getSuppressYjsEvents: () => boolean
setSuppressGraphSync: (value: boolean) => void
applyYjsToGraph: (events: Y.YEvent<Y.Map<unknown>>[]) => void
}
type YjsGraphSyncOptions = {
getEditor: () => CollabEditor
getYdoc: () => Y.Doc | null
getYnodes: () => YNodes | null
getYimages: () => YImages | null
/** Takes an image a layer uses to share some other way; false writes its bytes into the room. */
shareImage?: (name: string, bytes: Uint8Array) => boolean
setSuppressYjsEvents: (value: boolean) => void
/**
* Called after the room's layers reach the graph, which may have removed some, such as the page
* the editor shows.
*/
onApplied?: () => void
}
function logCollabSyncError(context: string, error: unknown) {
console.error(`[Collab] ${context}:`, error)
}
/**
* Collects the graph events of one edit and syncs them once, after the edit, in one Yjs
* transaction, so a move writes its parent entry and order key against the final layer order.
*/
export function bindCollabGraphEvents({
editor,
getYdoc,
getYnodes,
getSuppressGraphSync,
syncLocalEdit
}: GraphBindingOptions) {
let edit = createLocalEdit()
let bound = true
function record(update: (pending: LocalEdit) => void) {
// A read-only document makes no edits of its own; what changes it is the room's.
if (editor.isReadOnly() || getSuppressGraphSync() || !getYdoc() || !getYnodes()) return
if (isLocalEditEmpty(edit)) queueMicrotask(flush)
update(edit)
}
function flush() {
const pending = edit
edit = createLocalEdit()
if (bound && getYdoc() && getYnodes()) syncLocalEdit(pending)
}
const unbinds = [
editor.onEditorEvent('node:updated', (id, changes) =>
record((pending) => {
// A direct parentId write, as a checkpoint restore makes, syncs as a move when it
// differs from the shared tree; a childIds write re-keys the children out of order.
pending.changed.add(id)
if ('childIds' in changes) pending.reordered.add(id)
})
),
editor.onEditorEvent('node:created', (node) =>
record((pending) => {
pending.changed.add(node.id)
pending.placed.add(node.id)
})
),
editor.onEditorEvent('node:reparented', (nodeId, oldParentId) =>
record((pending) => {
pending.changed.add(nodeId)
pending.placed.add(nodeId)
if (oldParentId) pending.previousParents.add(oldParentId)
})
),
editor.onEditorEvent('node:reordered', (nodeId, _parentId, _index, previousParentId) =>
record((pending) => {
pending.placed.add(nodeId)
if (previousParentId) pending.previousParents.add(previousParentId)
})
),
editor.onEditorEvent('node:deleted', (id) => record((pending) => pending.deleted.add(id)))
]
return () => {
// An edit made just before leaving still reaches the room.
if (!isLocalEditEmpty(edit)) flush()
bound = false
for (const unbind of unbinds) unbind()
}
}
export function registerYjsObservers({
editor,
ynodes,
yimages,
hasImageRef,
getSuppressYjsEvents,
setSuppressGraphSync,
applyYjsToGraph
}: YjsObserverOptions): () => void {
function onNodes(events: Y.YEvent<Y.Map<unknown>>[]) {
if (getSuppressYjsEvents()) return
setSuppressGraphSync(true)
try {
applyYjsToGraph(events)
editor.requestRender()
} catch (error) {
logCollabSyncError('Failed to apply remote graph changes', error)
} finally {
setSuppressGraphSync(false)
}
}
function onImages(event: Y.YMapEvent<Uint8Array>) {
if (getSuppressYjsEvents()) return
try {
for (const [key, change] of event.changes.keys) {
if (change.action === 'add' || change.action === 'update') {
const data = yimages.get(key)
if (data) editor.graph.images.set(key, new Uint8Array(data))
} else if (!hasImageRef?.(key)) {
editor.graph.images.delete(key)
}
}
editor.requestRender()
} catch (error) {
logCollabSyncError('Failed to apply remote image changes', error)
}
}
ynodes.observeDeep(onNodes)
yimages.observe(onImages)
return () => {
ynodes.unobserveDeep(onNodes)
yimages.unobserve(onImages)
}
}
export function createYjsGraphSync({
getEditor,
getYdoc,
getYnodes,
getYimages,
shareImage,
setSuppressYjsEvents,
onApplied
}: YjsGraphSyncOptions) {
let shared: SharedTree | null = null
/** Edits made before this peer knew the room's root, which the room did not take. */
let heldBack = createLocalEdit()
function sharedTreeOf(ydoc: Y.Doc): SharedTree {
if (shared?.ydoc !== ydoc) {
shared = createSharedTree(ydoc, () => getEditor().graph, getYnodes)
}
return shared
}
function writeNode(graph: SceneGraph, ynodes: YNodes, nodeId: string): void {
const node = graph.getNode(nodeId)
if (!node) return
let ynode = ynodes.get(nodeId)
if (!ynode) {
ynode = new Y.Map()
ynodes.set(nodeId, ynode)
}
syncEncodedNodeToYMap(node, ynode, nodeId === graph.rootId ? DOCUMENT_NODE_FIELDS : [])
const localYimages = getYimages()
if (!localYimages) return
for (const fill of node.fills) {
if (!fill.imageHash || localYimages.has(fill.imageHash)) continue
const data = graph.images.get(fill.imageHash)
if (data && !shareImage?.(fill.imageHash, data)) localYimages.set(fill.imageHash, data)
}
}
/** Writes one local edit: changed layers' fields, deletions, and where layers now sit. */
function syncLocalEdit(edit: LocalEdit) {
const graph = getEditor().graph
const ydoc = getYdoc()
const ynodes = getYnodes()
if (!ydoc || !ynodes) return
const tree = sharedTreeOf(ydoc)
if (tree.rootId === null) mergeLocalEdit(heldBack, edit)
setSuppressYjsEvents(true)
try {
ydoc.transact(() => {
for (const id of edit.deleted) {
if (graph.getNode(id)) {
// Deleted and restored within the edit, as an undo can.
edit.changed.add(id)
edit.placed.add(id)
continue
}
ynodes.delete(id)
tree.tree.deleteLayer(id)
}
keepSharedLayers(tree, graph, edit)
for (const id of edit.changed) writeNode(graph, ynodes, id)
for (const id of edit.placed) if (!ynodes.has(id)) writeNode(graph, ynodes, id)
writeLocalPlacement(tree, graph, ynodes, ydoc.getMap('meta'), edit)
})
} catch (error) {
logCollabSyncError('Failed to sync local edit', error)
} finally {
setSuppressYjsEvents(false)
}
}
function syncNodeToYjs(nodeId: string) {
const edit = createLocalEdit()
edit.changed.add(nodeId)
syncLocalEdit(edit)
}
/**
* Shares this peer's whole document, as Share does: every layer, its parent with counter 0, its
* order, and its page, with its root as the room's.
*/
function syncAllNodesToYjs() {
const graph = getEditor().graph
const ydoc = getYdoc()
const ynodes = getYnodes()
if (!ydoc || !ynodes) return
setSuppressYjsEvents(true)
try {
ydoc.transact(() => {
for (const node of graph.getAllNodes()) writeNode(graph, ynodes, node.id)
for (const node of graph.getAllNodes()) {
const ynode = ynodes.get(node.id)
if (!ynode) continue
if (node.parentId === null) writeRootEntries(ynode)
const pageId = pageOf(graph, node.id)
if (pageId !== undefined) writePage(ynode, pageId)
const children = node.childIds.filter((id) => graph.getNode(id)?.parentId === node.id)
const keys = siblingOrderKeys(children.map(() => undefined))
children.forEach((childId, index) => {
const child = ynodes.get(childId)
if (!child) return
writeParentEntry(child, node.id, 0)
writeOrderKey(child, keys[index])
})
}
claimRoot(ydoc.getMap('meta'), graph.rootId)
markTreeFormat(ydoc.getMap('meta'))
})
heldBack = createLocalEdit()
recordLocalLayers(sharedTreeOf(ydoc), ynodes, ydoc.getMap('meta'), ynodes.keys())
} catch (error) {
logCollabSyncError('Failed to sync document', error)
} finally {
setSuppressYjsEvents(false)
}
}
function applyYjsToGraph(events: Y.YEvent<Y.Map<unknown>>[]) {
const editor = getEditor()
const ydoc = getYdoc()
const ynodes = getYnodes()
if (!ydoc || !ynodes) return
const changed = new Set<string>()
const deleted = new Set<string>()
for (const event of events) {
if (event.target === ynodes) {
for (const [key, change] of event.changes.keys) {
if (change.action === 'delete') deleted.add(key)
else changed.add(key)
}
continue
}
// The path from the nodes map starts with the layer's id, whether its own field changed
// or an entry of its nested parents map did.
const [nodeId] = event.path
if (typeof nodeId === 'string') changed.add(nodeId)
}
const roomRoot = readRoot(ydoc.getMap('meta'))
for (const nodeId of changed) {
const ynode = ynodes.get(nodeId)
if (ynode) applyYnodeToGraph(editor.graph, nodeId, ynode, roomRoot)
}
const gone = [...deleted].filter((nodeId) => !ynodes.has(nodeId))
// Moves go first, so a layer moved out of a deleted parent survives the deletion.
applySharedTree(sharedTreeOf(ydoc), editor.graph, ynodes, ydoc.getMap('meta'), changed, gone)
for (const nodeId of gone) editor.graph.deleteNode(nodeId)
onApplied?.()
}
/** Applies a layer's own fields; `applySharedTree` places it in the tree afterwards. */
function applyYnodeToGraph(
graph: SceneGraph,
nodeId: string,
ynode: Y.Map<unknown>,
roomRoot: string | undefined
) {
const decoded = decodeNodeFromYjs(ynode)
// The document node's plugin data arrives entry by entry (`document/sync.ts`).
const props: ReturnType<typeof decodeNodeFromYjs> =
nodeId === roomRoot || nodeId === graph.rootId ? omit(decoded, DOCUMENT_NODE_FIELDS) : decoded
const node = graph.getNode(nodeId)
if (node) {
// Only what differs: joining a room replays every layer, and a layer that already reads the
// same is no change, so it neither marks the document unsaved nor costs a redraw. The text
// picture is a cache the decoder clears, so it goes along only with a real change.
const { textPicture, ...fields } = props
const changes = pickBy(fields, (value, key) => !isEqual(Reflect.get(node, key), value))
if (!isEmptyObject(changes)) graph.updateNode(nodeId, { ...changes, textPicture })
return
}
const type = props.type
if (type) graph.createNodeWithId(nodeId, type, null, { ...props, childIds: [] })
}
/**
* Writes the edits made before the room's root was known, once this peer's document follows
* that root, as a stored document's tab does: what was drawn while the room loaded joins it.
*/
function syncHeldBackEdits() {
const ydoc = getYdoc()
const rootId = ydoc ? readRoot(ydoc.getMap('meta')) : undefined
if (!ydoc || rootId === undefined || isLocalEditEmpty(heldBack)) return
const tree = sharedTreeOf(ydoc)
if (tree.rootId === null) tree.setRoot(rootId)
const edit = heldBack
heldBack = createLocalEdit()
syncLocalEdit(edit)
}
/**
* Removes the layers under the document's root that the room does not hold. A stored document
* opened in several tabs numbers its layers afresh each time, so its copies of layers the room
* already has would otherwise sit beside the room's own.
*/
function dropLayersOutsideRoom() {
const graph = getEditor().graph
const ynodes = getYnodes()
if (!ynodes) return
const outside: string[] = []
const visit = (id: string) => {
for (const childId of graph.getNode(id)?.childIds ?? []) {
if (ynodes.has(childId)) visit(childId)
else outside.push(childId)
}
}
visit(graph.rootId)
for (const id of outside) graph.deleteNode(id)
// The page the tab was on may have been the file's own; it moves to one of the room's.
if (outside.length > 0) onApplied?.()
}
return {
syncNodeToYjs,
syncLocalEdit,
syncAllNodesToYjs,
applyYjsToGraph,
syncHeldBackEdits,
dropLayersOutsideRoom
}
}