@mocanvas/sync 4.0.1 → 4.1.0

package/README.md

@@ -48,6 +48,47 @@ const { status } = useSync(editor, { roomId, transport: () => createBroadcastCha
 selection outlines in screen space. It positions itself absolutely, so it goes
 anywhere inside the canvas container.
 
+That is the whole integration: nothing above pins a page, and nothing names a
+person. Two things make it work, and both are worth knowing because both used
+to have to be worked around by hand.
+
+### The page both replicas start on
+
+A blank document's first page has a **fixed id** — `DEFAULT_PAGE_ID`, i.e.
+`page:page` — so two `<Mocanvas />`s that each built their own store start on
+the *same* page. Shapes drawn in one tab land on the page the other is looking
+at, and `getCollaboratorsOnCurrentPage()` has something to return. (Creating
+the same record id on two peers is a field-by-field merge, and the two bodies
+are identical, so there is nothing to settle.) Pages created *after* that get
+random ids, so two people genuinely on different pages of one document stay
+independent.
+
+When a replica does end up alone on its page — someone moved to another page,
+or two apps built their documents separately — the client says so once, in
+development:
+
+> mocanvas/sync: this replica is on page `page:…`, and none of the 1 peer(s) in
+> room "…" is — they are on `page:…`. Their cursors and their shapes will not be
+> visible here.
+
+Everything is still `online` in that state, every message still arrives, and
+nothing is drawn. It is the failure with the least evidence, which is why it
+gets a sentence instead of silence.
+
+### A tab is not a person
+
+Presence is per **editor instance**, not per user. `editor.user.getId()` is per
+*browser* — the same in every tab, and the same on a phone and a laptop signed
+in as one person — so a person with three tabs open would otherwise discard
+their own other tabs as themselves. The identity that decides is
+`editor.getInstancePresenceId()`: every editor mints one, this package
+publishes the tab's presence record under it, and `editor.getCollaborators()`
+drops that one record and no other.
+
+So two tabs of one browser are two collaborators — which is the entire point of
+`createBroadcastChannelTransport` — and an app does not have to invent a fake
+per-tab identity to make its own demo work.
+
 ## Protocol
 
 Every message is one JSON object on the wire.
@@ -93,7 +134,13 @@ half-parsed. Nothing on the wire can crash this client.
 - Presence records are derived from the editor's camera,
   `inputs.currentPagePoint` and selection, throttled to at most 30 Hz, and
   re-sent on a heartbeat. A collaborator is dropped on `bye` or after 10s of
-  silence.
+  silence. The record is keyed on the sending editor's instance id (see
+  "A tab is not a person" above), so one person's tabs do not overwrite each
+  other's presence.
+- A `hello` makes every established peer **re-announce** its presence, even
+  when its own record has not changed — what changed is who is listening. A
+  peer that has been sitting still since before you joined is therefore visible
+  immediately rather than at its next heartbeat.
 
 ## Conflict policy: a CRDT over the record fields
 

package/UI.md

@@ -4,6 +4,27 @@
 style panel, an optional statistics chip, and the chrome the editor draws on the
 canvas itself. All of it is optional and all of it is themeable from CSS.
 
+## Loading the stylesheet
+
+The theme is published as `@mocanvas/mocanvas/mocanvas.css` and your app
+imports it:
+
+```ts
+import "@mocanvas/mocanvas/mocanvas.css"
+```
+
+The package's JavaScript entry does not import it. That is deliberate: Node has
+no loader for `.css`, so a CSS import inside `dist/index.js` makes
+`import "@mocanvas/mocanvas"` throw `ERR_UNKNOWN_FILE_EXTENSION` anywhere there
+is no bundler — vitest, SSR, a plain script. Up to and including 4.0.2 it did,
+and the emitted file was content-hashed (`dist/ui-4C5V5GYT.css`) so there was no
+stable name to import instead. Both are fixed; the cost is this one line in your
+app.
+
+`<Canvas />` from `@mocanvas/editor` carries fallback values for the canvas
+chrome tokens, so an editor mounted without the stylesheet still renders
+legibly — but the toolbar, panels, menus and dialogs need it.
+
 Source lives in `packages/mocanvas/src/ui/`:
 
 | File | What it holds |
@@ -122,8 +143,9 @@ so inline marks like the "mixed" badge keep the size they ask for.
 <Mocanvas hideUi />
 ```
 
-This drops the toolbar, zoom bar, style panel and stats chip. `ui.css` still
-loads, so the canvas chrome tokens above keep working. Default keyboard
+This drops the toolbar, zoom bar, style panel and stats chip. The stylesheet is
+imported by your app, not by the component, so the canvas chrome tokens above
+keep working. Default keyboard
 shortcuts are wired by `<Mocanvas />` itself and are unaffected; call
 `useKeyboardShortcuts(editor)` yourself if you build on `<Canvas />` directly.
 

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import { Signal } from '@mocanvas/state';
 import { Store, UnknownRecord, RecordsDiff } from '@mocanvas/store';
-import { UserId, InstancePresence, InstancePresenceId, Editor } from '@mocanvas/editor';
+import { UserId, InstancePresenceId, InstancePresence, Editor } from '@mocanvas/editor';
 import * as react from 'react';
 
 /** Presence is sent at most this often (30 Hz). */
@@ -47,6 +47,16 @@ interface PresenceEditor {
         scribbles: readonly unknown[];
         followingUserId: UserId | null;
     };
+    /**
+     * Optional: the id this instance's presence record is published under.
+     *
+     * A real `Editor` has one and it is the identity that matters here — a user
+     * id is per browser, so two tabs of one browser are one user and would
+     * discard each other's presence as their own. Structural stand-ins (tests,
+     * a headless participant) may omit it and fall back to
+     * {@link presenceIdForClient}.
+     */
+    getInstancePresenceId?(): InstancePresenceId;
     /** Optional: used to sample the cursor, which is not itself a signal. */
     on?(name: "event", fn: () => void): () => void;
 }
@@ -61,8 +71,17 @@ interface PresenceSyncOptions {
 interface PresenceSync {
     start(): void;
     stop(): void;
-    /** Ask for a send; collapses with any other request inside the throttle window. */
-    poke(): void;
+    /**
+     * Ask for a send; collapses with any other request inside the throttle
+     * window.
+     *
+     * `force` sends even when nothing about this client has changed, which is
+     * what a *re-announcement* is: somebody who was not listening when we last
+     * spoke has arrived, so the record has to go out again although it says the
+     * same thing. Without it a peer that has been sitting still since before the
+     * newcomer joined stays invisible until its next heartbeat.
+     */
+    poke(force?: boolean): void;
     /** The record last handed to `send`, for tests and debugging. */
     getLastSent(): InstancePresence | null;
     dispose(): void;
@@ -443,6 +462,11 @@ interface CollaboratorCursorsProps {
 /**
  * Other people's cursors and selections, drawn in screen space above the
  * canvas. Drop it inside `<Mocanvas>` or `<Canvas>`; it positions itself.
+ *
+ * The arrow below is the default. An app that supplies a
+ * {@link TLEditorComponents.CollaboratorCursor} component gets that instead —
+ * the slot was declared on two component maps and consulted by nothing, so an
+ * app that replaced the cursor silently kept seeing ours.
  */
 declare const CollaboratorCursors: ({ editor, showSelection, showNames, }: CollaboratorCursorsProps) => react.JSX.Element | null;
 interface UseSyncOptions {

package/dist/index.js

@@ -1,9 +1,9 @@
 import { react, atom } from '@mocanvas/state';
+import { useEditorComponents, InstancePresenceRecordType, warnOnce } from '@mocanvas/editor';
 import { uniqueId, isRecordsDiffEmpty, createEmptyRecordsDiff } from '@mocanvas/store';
-import { InstancePresenceRecordType } from '@mocanvas/editor';
 import { track, useValue } from '@mocanvas/state/react';
 import { useRef, useState, useEffect } from 'react';
-import { jsx, jsxs, Fragment } from 'react/jsx-runtime';
+import { jsxs, Fragment, jsx } from 'react/jsx-runtime';
 
 // src/SyncClient.ts
 var CRDT_STATE_VERSION = 1;
@@ -504,7 +504,7 @@ function createPresenceSync(options) {
   const { editor, clientId, send } = options;
   const throttleMs = options.throttleMs ?? DEFAULT_PRESENCE_THROTTLE_MS;
   const heartbeatMs = options.heartbeatMs ?? DEFAULT_PRESENCE_HEARTBEAT_MS;
-  const id = presenceIdForClient(clientId);
+  const id = editor.getInstancePresenceId?.() ?? presenceIdForClient(clientId);
   let timer = null;
   let heartbeat = null;
   let stopReactor = null;
@@ -538,11 +538,16 @@ function createPresenceSync(options) {
     last = next;
     send(next);
   };
-  const poke = () => {
-    if (!running || timer !== null) return;
+  let pendingForce = false;
+  const poke = (force = false) => {
+    if (!running) return;
+    if (force) pendingForce = true;
+    if (timer !== null) return;
     timer = setTimeout(() => {
       timer = null;
-      flush(false);
+      const forced = pendingForce;
+      pendingForce = false;
+      flush(forced);
     }, throttleMs);
   };
   return {
@@ -564,6 +569,7 @@ function createPresenceSync(options) {
     },
     stop() {
       running = false;
+      pendingForce = false;
       if (timer !== null) {
         clearTimeout(timer);
         timer = null;
@@ -736,6 +742,8 @@ function createSyncClient(options) {
   });
   const unsubscribes = [];
   const reportedVersions = /* @__PURE__ */ new Set();
+  const peerPages = /* @__PURE__ */ new Map();
+  let warnedAboutPages = false;
   let presence = null;
   let seq = 0;
   let awaitingSnapshot = false;
@@ -830,7 +838,7 @@ function createSyncClient(options) {
         }
         awaitingSnapshot = false;
         sendSnapshot();
-        presence?.poke();
+        presence?.poke(true);
         return;
       }
       case "snapshot": {
@@ -864,21 +872,38 @@ function createSyncClient(options) {
       case "presence": {
         if (message.clientId === clientId) return;
         room.receive(message.clientId, message.record);
+        notePeerPage(message.clientId, message.record);
         return;
       }
       case "bye": {
         if (message.clientId === clientId) return;
         room.remove(message.clientId);
+        peerPages.delete(message.clientId);
         return;
       }
     }
   };
+  const notePeerPage = (peerId, record) => {
+    const editor = options.presence?.editor;
+    if (!editor || warnedAboutPages) return;
+    const page = record.currentPageId;
+    if (typeof page !== "string") return;
+    peerPages.set(peerId, page);
+    const mine = editor.getCurrentPageId();
+    for (const peerPage of peerPages.values()) if (peerPage === mine) return;
+    warnedAboutPages = true;
+    const theirs = Array.from(new Set(peerPages.values())).join(", ");
+    warnOnce(
+      `sync.page:${roomId}:${clientId}`,
+      `mocanvas/sync: this replica is on page ${mine}, and none of the ${peerPages.size} peer(s) in room "${roomId}" is \u2014 they are on ${theirs}. Their cursors and their shapes will not be visible here. That is correct if you moved to another page on purpose; if you did not, the two replicas are on pages that were built separately. Every editor that starts from a blank document starts on the same default page, so check whether one side pinned, created or loaded a page of its own \u2014 and if so, call editor.setCurrentPage() with a page id both sides agree on.`
+    );
+  };
   const onOpen = () => {
     if (disposed || !connected) return;
     status.set("online");
     send({ type: "hello", clientId, version: PROTOCOL_VERSION });
     if (!awaitingSnapshot) sendSnapshot();
-    presence?.poke();
+    presence?.poke(true);
   };
   const onClose = () => {
     if (disposed || !connected) return;
@@ -1138,12 +1163,29 @@ var CollaboratorCursors = track(function CollaboratorCursors2({
   showSelection = true,
   showNames = true
 }) {
+  const components = useEditorComponents();
   const collaborators = editor.getCollaboratorsOnCurrentPage();
   if (collaborators.length === 0) return null;
-  return /* @__PURE__ */ jsx("svg", { className: "mocanvas-collaborators", style: layerStyle, children: collaborators.map((presence) => /* @__PURE__ */ jsxs("g", { children: [
-    showSelection ? /* @__PURE__ */ jsx(CollaboratorSelection, { editor, presence }) : null,
-    /* @__PURE__ */ jsx(CollaboratorCursor, { editor, presence, showName: showNames })
-  ] }, presence.id)) });
+  const Slot = components.CollaboratorCursor;
+  return /* @__PURE__ */ jsxs(Fragment, { children: [
+    /* @__PURE__ */ jsx("svg", { className: "mocanvas-collaborators", style: layerStyle, children: collaborators.map((presence) => /* @__PURE__ */ jsxs("g", { children: [
+      showSelection ? /* @__PURE__ */ jsx(CollaboratorSelection, { editor, presence }) : null,
+      Slot === void 0 ? /* @__PURE__ */ jsx(CollaboratorCursor, { editor, presence, showName: showNames }) : null
+    ] }, presence.id)) }),
+    Slot ? /* @__PURE__ */ jsx("div", { className: "mocanvas-collaborator-cursors", style: layerStyle, children: collaborators.map(
+      (presence) => presence.cursor === null ? null : /* @__PURE__ */ jsx(
+        Slot,
+        {
+          type: "default",
+          rotation: presence.cursor.rotation,
+          color: presence.color,
+          name: showNames ? presence.userName || "Anonymous" : null,
+          point: editor.pageToViewport(presence.cursor)
+        },
+        presence.id
+      )
+    ) }) : null
+  ] });
 });
 var CollaboratorCursor = track(function CollaboratorCursor2({
   editor,