9dce9fdcbc
* fix: stop ancestor walks from hanging on a parent cycle A collaborator's concurrent reparent can leave two layers as each other's parent. isDescendant, the design check's pageOf, and component sync walked parentId without a bound, so applying such a change froze the editor. Add SceneGraph.closest(), a bounded nearest-ancestor lookup, and use it for these walks so bad data ends the walk instead of the tab. * fix(collab): sync layer moves without parent cycles or stale child lists Remote changes assigned each layer's synced parentId and childIds as plain properties. Two peers moving layers into each other made them each other's parent, a moved layer stayed listed under its old parent, reorders never synced, and concurrent additions ended up in different orders or missing from the parent's list. Apply the tree after a change's properties: move layers to their synced parents, skip a move that would make a layer its own ancestor and write the layer's current parent and position back so every peer settles on it, and derive each touched parent's childIds from its synced order followed by unlisted children by id. Locally, a parent's child list syncs once after each edit that adds, removes, moves, or reorders its children. Fixes #888 Fixes #889 * refactor(scene-graph)!: move sibling order keys to scene-graph Collaboration needs the same fractional keys as .fig export to order siblings, and the app must not depend on @open-pencil/fig for them. Move fractionalPosition, orderKeyBetween, and siblingOrderKeys to @open-pencil/scene-graph/order-keys. orderKeyBetween now always returns a key: when no printable key fits it returns one above lo, which hasOrderKeyBetween detects, so callers no longer branch on null. It takes an optional suffix, and siblingOrderKeys can request one per key, so two peers inserting at one spot get distinct keys. .fig export keeps its keys. * fix(scene-graph): report instance child reorders as graph events Instance sync sorted an instance's children in place, so nothing that listens to graph events saw the new order; in a shared room the order never reached other peers. Move each child that changes position with insertChildAt, which reports the reorder. * feat(collab): resolve the layer tree from each layer's parent history Add a pure LayerTree for the shared document: each layer records every parent it was moved under with a move counter and an order key. A layer sits under its newest parent, ties broken by parent id; when concurrent moves close a loop, the latest move in the loop falls back to the layer's next entry until none is left, and a layer no parent can take goes to its page (Evan Wallace's mutable tree hierarchy CRDT). The result depends only on the entries, and resolution revisits only changed, orphaned, and displaced layers. Seeded random runs check that peers converge and that the incremental result matches a full one. * fix(collab): sync layer moves as parent history and order keys Each layer's shared map now records every parent it was moved under with a move counter from a document-wide Lamport clock, and its order key among siblings, instead of parentId and childIds. Every peer derives parentId and childIds from these with LayerTree, so concurrent moves, reorders, and additions merge, a loop from concurrent moves undoes its latest move, and a layer whose new parent was deleted meanwhile returns to its previous one. A local edit's graph events are written once after the edit, in one transaction. It records a parent entry for each layer whose parent changed, a new entry for displaced layers on the touched paths so a move cannot pull them back, and keys between the moved layers' neighbours with a random suffix, so concurrent inserts at one spot get distinct keys. Remote changes find their layers through each event's path, resolve only what they touch, and move and sort layers through insertChildAt. This replaces the childIds merge and the write-back of rejected moves: a rejected move now resolves the same way on every peer from the shared history, so nothing needs to be written back. Fixes #888 Fixes #889 * feat(collab)!: convert saved rooms and keep mismatched builds apart A room saved by an earlier build records parentId and childIds. When a change brings in such layers, from this browser's storage or a peer, convert them in one transaction: each layer's synced parent becomes its only entry with counter 0, its position in the parent's synced childIds becomes an order key, and the old fields go. The result depends only on the document, so two peers converting at once write the same values, and converting again writes nothing. The document's meta map records treeFormat 2. Builds that record the tree differently would corrupt each other's rooms, so the collaboration namespace becomes openpencil/2 for Trystero and the test relay alike, and each peer publishes its treeFormat in awareness for future version messages. * fix(collab): send a layer whose parents were all deleted back to its own page Each layer's shared map records the page it was last placed on, and the layers under a frame moved to another page are re-recorded. A layer whose parent chain was deleted goes back to that page, falling back to the first page only when the recorded one is gone. Saved rooms record pages when they are converted. * fix(collab): keep one root per room when peers edit their own documents Joining a room keeps the joiner's earlier document in its graph, and an undo or an edit made before the room arrived could still reach it. That edit shared the joiner's root, every peer adopted it, and the room's pages disappeared. The room now records its root as claims in meta, each with the time it was made, and every peer follows the earliest. Sharing claims the room, and so does the first edit in a room nobody has shared, which now shares the whole document as Share does. A peer shares only layers under the room's root. Converted rooms claim the root with the most children. Move counters must also be safe integers, so an oversized counter from another peer cannot stop the move clock from advancing. * fix(collab): rank root claims by how they were made, not by clocks Root claims carried the claiming peer's wall-clock time, so a guest whose clock ran behind the sharer's could still win the room with an edit made before the room reached them. A claim now records whether it came from Share or a converted room, or from the first edit in an unshared room; a shared root outranks an edited one, and the lower id breaks a tie. A claim also replaces an invalid value already stored for its root. * fix(collab): keep every root claim through concurrent writes A root claim was one key per root holding its kind, so two peers claiming the same root by Share and by an edit at once kept only one of the two values, and the shared claim could be lost. Each kind of claim on a root is now its own key. Converting a saved room also claims its root unless a shared claim exists, so a guest's earlier edited claim no longer keeps the converted room from outranking it. * fix(collab): mint layer IDs under a session of each editor window Every editor window started its IDs at 0:1 from the same counter, so two people adding layers to a shared room at once could mint the same IDs, and one person's layers replaced the other's in the room. A joiner's starting page also took the sharer's page ID and stayed in their list. SceneGraph's default IDs now carry a session set with setIdSession, as in Figma's sessionID:localID GUIDs. The editor picks a random 32-bit session at startup, as Yjs does for each document's clientID; headless tools keep session 0, so the CLI and MCP server give a file's layers the same IDs on every run. * fix(collab): let only Share set a room's root A guest's first edit in a room whose contents had not arrived claimed the room and wrote the guest's whole open document into it, images included, and adopting the sharer's root later only hid it. Every room starts with someone sharing a document, so a guest has nothing to claim: only Share, or converting a saved room, now sets the room's root, as a single value in meta, and a peer writes nothing until the root is known. Unbinding a room also writes an edit still waiting to be sent, so a move or deletion made just before leaving reaches the room. * feat(collab)!: open each room in a tab of its own Joining a room bound it to whatever tab was active, so a pasted link could turn a saved file into the room's document, and a share link first showed an editable blank document. A room is now a document: joining always opens it in a new tab, or switches to the tab already showing it, and only Share puts an existing tab's document into a room. Every room tab owns its session (src/app/collab/rooms.ts and session.ts), so several rooms can be live at once and keep syncing in the background. The collaboration panel, presence, following, and the /share/<id> address follow the active tab, and a canvas publishes its cursor and selection only to its own tab's room. A room tab derives its state: joining while its saved copy loads, then waiting, with an explanation, while nobody who has the file is online; live with others, or alone on this device's copy. Until the document arrives the room's screen replaces the editor. Reloading a share link rejoins it; leaving a room you joined keeps its file as a local unsaved copy. "Connected" now means another peer answered. Pasted links and IDs are normalised and validated, and invalid ones say so. People join right away under a generated name such as "Teal Fox", with a hint to set one; the one app-wide name is set in the share panel or in Settings. On a phone, Share copies the room's link instead of making a new room, and the presence popover shows the room's state. * feat(desktop): open rooms from openpencil://join links and Home The desktop app could not receive a share link: links point at the web app, and openpencil:// only opened files. openpencil://join?room=<id> now opens the room in a tab of its own. The native parser refuses anything but a room ID, queues rooms for the frontend through take_pending_rooms, and a second launch on Windows and Linux forwards its link through the single-instance handler. In a browser on a computer, the room's screen and the share panel offer Open in desktop app, a link the browser hands to the app on click; it never opens the app by itself. Home gains Join room…, which takes a pasted room link or ID and opens the room in a new tab. * feat(collab): set your name on the room screen The room screen told someone joining under a generated name to set their name but offered nowhere to do it before the file arrived. It now has the same name field as the room panel. * feat(collab): offer the desktop download beside Open in desktop app A browser on a computer offers a room's openpencil://join link, which does nothing where the app is not installed. The room screen and panel now link to the latest release beside it. * docs: describe joining rooms in the German, Polish, and Russian guides Bring the translated collaboration pages up to the English one: Share as the only way into a room, joining in a tab of its own, the waiting screen, leaving with a local copy, and how layer moves merge. The English page now names the panel's Leave room button. * fix(collab): lay out the room screens like the app's empty states The joining and waiting screens were a left-aligned card with a stray spinner, a primary Copy link button beside an outline button and a bare link, and a name field on a screen that lasts seconds. They now use AppPlaceholder, centred over the tab: a heading, the explanation, the two hints, secondary Copy link and Leave, a 'You'll appear as' line whose Change opens a small rename popover, and the desktop handoff on one muted line. The room panel lines its status dot up with wrapped text, no longer selects the room link when it opens, and puts the desktop links and Leave room on one footer line. * fix(collab): show what a room tab is doing instead of a timed guess A joined tab said nobody with the file was online five seconds after it opened, whether or not it had reached the signaling service or met the people already in the room. Its state now follows what the tab can observe: connecting until the service answers, looking for people for as long as that transport takes to introduce everyone, getting the file from someone who says they have it, waiting when nobody who has it showed up (naming other guests waiting too), and a can't-connect screen when the service cannot be reached. Each peer says in its presence whether it has the room's file. * fix(collab): list other waiting guests with the explanation The line naming other guests who are waiting too is information, not an action, so it follows the hints above the buttons. Peers' hasFile flag is optional, as older builds do not send it. * fix(collab): send a canvas's cursor and selection to its tab's room again Canvases read the editor through a proxy that follows the active tab, and the room lookup by store never matched it, so pointer moves and selections stopped reaching the room: collaborators lost each other's cursors, selections, and page markers. The canvas now looks up its room by its tab's own store, and its selection listener ends when the canvas unmounts instead of piling up across tab switches. * feat(collab): one avatar stack for the toolbar, the mobile pill, and pages The toolbar, the page list, and the mobile HUD each drew the people in a room their own way, and the mobile pill read 'Online: 3' in hard-coded English beside a status dot too small to render. AvatarStack now draws people overlapping with their agent counts and '+N', and every place uses it: the toolbar wraps each avatar in its menu or hover card, the mobile pill shows the room's state dot and the stack with a translated name, and hovering a page with people on it opens a card with the stack and who is there, with their agents, to follow. The mobile list is the shared presence list, so it is translated and can follow agents too. * docs: note the page hover card and mobile avatars in the changelog * fix(collab): stop listening to a room once its tab leaves it A session left its Yjs observers and its awareness listener attached after dispose, relying on destroy() and the order of teardown not to touch the tab again. It now removes them explicitly and clears its peer list. Also fix a missing comma in the Polish collaboration guide.
58 lines
4.7 KiB
Markdown
58 lines
4.7 KiB
Markdown
---
|
|
title: Collaboration
|
|
description: Real-time collaborative editing via P2P WebRTC — no server, no account.
|
|
---
|
|
|
|
# Collaboration
|
|
|
|
Edit designs together in real time. Peers connect directly — no server relays your data, no account required.
|
|
|
|
## Sharing a Room
|
|
|
|
1. Click the share button in the top-right corner
|
|
2. Click **Share this file** — the link (`app.openpencil.dev/share/<room-id>`) is copied
|
|
3. Send it to your collaborators
|
|
|
|
Only Share puts a document into a room: the tab you share from becomes the room's tab and stays tied to its file. Anyone with the link can join.
|
|
|
|
## Joining a Room
|
|
|
|
Open the link, or paste it (or just the room ID) into **Join** in the share panel or **Join room…** on Home. The room opens in a tab of its own, so the documents you already have open are never changed. On a computer, a browser also offers **Open in desktop app**, which opens the room in OpenPencil through an `openpencil://join` link.
|
|
|
|
You join right away under a generated name such as *Teal Fox*; set your own in the share panel or in Settings, and it is used in every room.
|
|
|
|
Rooms are not stored on a server: the file lives on the devices of the people who have been in the room, so a room tab opens its document only while one of them is online. Until then it says it is waiting, explains why, and opens the file as soon as someone who has it joins. A room you have been in before opens from this device's copy right away and syncs your changes when others return.
|
|
|
|
**Leave room** in the share panel ends your part in the room. A tab that shared its document goes back to being that document; a tab that joined keeps the room's file as a local unsaved copy you can save. Each room tab keeps its own connection, so you can be in several rooms at once.
|
|
|
|
## What Syncs
|
|
|
|
- **Document changes** — every edit (shapes, text, properties, layout) syncs instantly
|
|
- **Cursors** — see where each collaborator is pointing, with their name and color
|
|
- **Selections** — highlighted selections are visible to everyone
|
|
- **Agents** — the built-in AI chat appears as a cursor at the layers it is editing, its outlined label showing a sparkle and a callsign such as *Fern*. The cursor and outline have the color of the person running it, so you can tell whose agent it is. Only its name, kind, model, status, page, position, and edited layers are shared, never prompts or replies.
|
|
|
|
## Follow Mode
|
|
|
|
Click a collaborator's avatar in the top bar to follow their viewport. Your canvas pans and zooms to match their view, and a frame in their color with a “Following …” bar shows whom you follow. Click the avatar again, press <kbd>Esc</kbd>, or click, scroll, zoom, or switch pages yourself to stop.
|
|
|
|
An avatar counts the agents that person runs. Hover over it to see each agent, what it is doing, and on which page, and click **Follow** next to an agent to keep the page and layers it is editing in view; following continues between its replies and stops when it leaves. The button after the avatars lists everyone in the room with their agents, and works from the keyboard. Your own avatar lists your agents — click one to rename it — and has **Leave room**.
|
|
|
|
The share panel lists everyone in the room with the agents they run, what each agent is doing, and on which page. Follow an agent the same way to keep the page and layers it is editing in view; following continues between its replies and stops when it leaves. Double-click one of your own agents to rename it.
|
|
|
|
## How It Works
|
|
|
|
Peers connect directly via WebRTC — your design data goes straight from browser to browser, never through a central server. The document state uses a CRDT (conflict-free replicated data type), so concurrent edits merge automatically without conflicts.
|
|
|
|
Moving and reordering layers merges too. Each layer remembers every parent it has been moved into and its position among its siblings, and every peer works out the same layer tree from that history ([Evan Wallace's tree CRDT](https://madebyevan.com/algos/crdt-mutable-tree-hierarchy/)). Moves, reorders, and new layers from different people all apply; if two people move the same layer at once, one move wins on every peer. When moves made at the same time would put two layers inside each other, the later move is undone, and a layer whose new parent was deleted meanwhile returns to where it was.
|
|
|
|
Everyone in a room needs a version of OpenPencil that records the layer tree the same way; versions that record it differently do not see each other's rooms.
|
|
|
|
The room persists locally — if you refresh the page, you rejoin it automatically with the same state.
|
|
|
|
## Tips
|
|
|
|
- Works in the browser and the desktop app
|
|
- Room IDs are cryptographically random — only people with the link can join
|
|
- Stale cursors are cleaned up automatically when someone disconnects
|