@q9labsai/chalk-whiteboard 5.0.1 → 5.2.0

package/CHANGELOG.md

@@ -0,0 +1,28 @@
+# Changelog
+
+## 5.2.0
+
+### follow-view-owner
+
+Converge Follow views on one Episode owner, recover from its canonical snapshot,
+and preserve real camera moves during recovery and tab switches. Zoom controls
+and keyboard moves now consistently leave Follow and lead the person's view.
+
+Keep all 500 active people's views using internal schema-generated limits in the client and React caches. The client's public bounds, event unions and decoded-frame unions are unchanged. The client now exports `ChalkWhiteboardViewVersions`, which the React SDK uses to order view moves, and whiteboard view events now carry `ownerId`, `ownerSequence` and `originEpoch`, so both releases are minor.
+
+## 5.1.0
+
+- Add headless mode for hosts that draw their own board controls: `WhiteboardCanvas` accepts `headless`, `inkColor` and `onEngineReady`, and the React entry exports `WhiteboardEngineHandle` (clear, clear with undo, place math), `CANONICAL_INK`, and `observeEngineHistory` with `EngineHistoryState`.
+- Add shared board view events, so collaborators can follow a person's view or bring everyone to theirs.
+- Keep Clear and Undo bound to the scene they were taken from. Redo brings back undone text, and small drawings open at 100% zoom at most.
+
+See the [project changelog](../../CHANGELOG.md) for the coordinated v5.1 release.
+
+## 5.0.0
+
+- Export `preloadWhiteboardStylesheet` from the React entry point.
+- Keep element order stable across board loads and reconnects.
+- Keep the rest of a board syncing when an element exceeds the wire size limit.
+- BREAKING: remove the retired local image-upload queue and import path. Remote file downloads remain available.
+
+See the [project changelog](../../CHANGELOG.md) for the coordinated v5 release.

package/dist/chunk-IVFWOYSW.js

@@ -0,0 +1,10 @@
+// src/collab/ink.ts
+var CANONICAL_INK = "#1b1c1f";
+function withInk(element, from, to) {
+  return from !== to && element.strokeColor.toLowerCase() === from.toLowerCase() ? { ...element, strokeColor: to } : element;
+}
+
+export {
+  CANONICAL_INK,
+  withInk
+};

package/dist/{chunk-W4FLPXAX.js → chunk-MPNIDZHM.js}

@@ -1,6 +1,6 @@
 import {
   compareElementOrder
-} from "./chunk-6ZV7GBAC.js";
+} from "./chunk-X3WDTGPQ.js";
 
 // src/collab/reducer.ts
 function mergeWhiteboardElements(current, incoming) {

package/dist/{chunk-6ZV7GBAC.js → chunk-X3WDTGPQ.js}

@@ -1,5 +1,10 @@
+import {
+  CANONICAL_INK,
+  withInk
+} from "./chunk-IVFWOYSW.js";
+
 // src/collab/engine.ts
-import { CaptureUpdateAction as CaptureUpdateAction2, reconcileElements, restoreElements } from "@excalidraw/excalidraw";
+import { CaptureUpdateAction as CaptureUpdateAction2, newElementWith as newElementWith2, reconcileElements, restoreElements } from "@excalidraw/excalidraw";
 
 // src/collab/camera.ts
 function getWhiteboardCamera(appState) {
@@ -193,7 +198,7 @@ var toSocketId = (value) => value;
 var WhiteboardPresence = class {
   constructor(opts) {
     this.opts = opts;
-    this.pruneInterval = setInterval(() => this.pruneStale(), 1e3);
+    if (opts.renderCursors) this.pruneInterval = setInterval(() => this.pruneStale(), 1e3);
   }
   opts;
   lastCursorSend = 0;
@@ -211,6 +216,7 @@ var WhiteboardPresence = class {
     this.opts.sendCursor(payload.pointer);
   }
   handleRemoteCursor(payload) {
+    if (!this.opts.renderCursors) return;
     const ts = payload.timestamp instanceof Date ? payload.timestamp.getTime() : Date.now();
     this.collaborators.set(payload.participantId, {
       pointer: { x: payload.x, y: payload.y, tool: "pointer", renderCursor: true },
@@ -399,6 +405,8 @@ var ExcalidrawCollabEngine = class {
   constructor(opts) {
     this.opts = opts;
     this.canDraw = opts.canDraw;
+    this.canManage = opts.canManage;
+    this.inkColor = opts.inkColor ?? CANONICAL_INK;
     this.filesSync = new WhiteboardFilesSync({
       excalidrawAPI: opts.excalidrawAPI,
       fileTransfer: opts.fileTransfer,
@@ -409,6 +417,7 @@ var ExcalidrawCollabEngine = class {
     this.presence = new WhiteboardPresence({
       excalidrawAPI: opts.excalidrawAPI,
       sendCursor: opts.sendCursor,
+      renderCursors: opts.renderCursors ?? true,
       throttleMs: CURSOR_THROTTLE_MS,
       staleMs: CURSOR_STALE_MS
     });
@@ -417,8 +426,11 @@ var ExcalidrawCollabEngine = class {
   }
   opts;
   sceneId = null;
+  sceneRevision = null;
   sceneGeneration = null;
   canDraw = true;
+  canManage;
+  inkColor;
   storedImageFileIds = /* @__PURE__ */ new Set();
   broadcastedElementVersions = /* @__PURE__ */ new Map();
   rejectedElementVersions = /* @__PURE__ */ new Map();
@@ -437,11 +449,24 @@ var ExcalidrawCollabEngine = class {
   setCanDraw(next) {
     this.canDraw = next;
   }
+  setCanManage(next) {
+    this.canManage = next;
+  }
+  /** Repaints Ink for a new surface without a new version, so nothing is sent. */
+  setInkColor(next) {
+    const previous = this.inkColor;
+    if (next === previous) return;
+    this.inkColor = next;
+    const api = this.opts.excalidrawAPI;
+    api.updateScene({ elements: api.getSceneElementsIncludingDeleted().map((element) => withInk(element, previous, next)), captureUpdate: CaptureUpdateAction2.NEVER });
+    api.history.clear();
+  }
   async clear() {
-    if (!this.canDraw) throw new Error("whiteboard drawing is not permitted");
+    if (!(this.canManage ?? this.canDraw)) throw new Error("whiteboard management is not permitted");
     const commit = await this.opts.clear();
     this.storedImageFileIds.clear();
     this.sceneId = commit.sceneId;
+    this.sceneRevision = commit.revision;
     this.sceneGeneration = commit.sceneGeneration ?? null;
     this.broadcastedElementVersions.clear();
     this.rejectedElementVersions.clear();
@@ -451,8 +476,20 @@ var ExcalidrawCollabEngine = class {
       elements: [],
       captureUpdate: CaptureUpdateAction2.NEVER
     });
+    this.opts.excalidrawAPI.history.clear();
     return commit;
   }
+  /** Restore only into the exact empty scene committed by this clear. */
+  async clearWithUndo() {
+    const api = this.opts.excalidrawAPI;
+    const before = api.getSceneElements();
+    const commit = await this.clear();
+    return () => {
+      if (this.disposed || !this.canDraw || this.sceneId !== commit.sceneId || this.sceneRevision !== commit.revision || this.sceneGeneration !== (commit.sceneGeneration ?? null) || api.getSceneElementsIncludingDeleted().length > 0) return false;
+      api.updateScene({ elements: before.map((element) => newElementWith2(element, {})), captureUpdate: CaptureUpdateAction2.IMMEDIATELY });
+      return true;
+    };
+  }
   dispose() {
     if (this.disposed) return;
     const hasPendingChange = this.changeDebounce !== null || this.dirtyDuringSubmission || this.submissionRetryTimer !== null;
@@ -497,6 +534,7 @@ var ExcalidrawCollabEngine = class {
       case "snapshot":
         this.handleRemoteSnapshot({
           sceneId: event.sceneId,
+          revision: event.revision,
           ...event.sceneGeneration ? { sceneGeneration: event.sceneGeneration } : {},
           elements: event.elements,
           appState: event.appState
@@ -505,6 +543,7 @@ var ExcalidrawCollabEngine = class {
       case "update":
         this.handleRemoteData({
           sceneId: event.sceneId,
+          revision: event.revision,
           ...event.sceneGeneration ? { sceneGeneration: event.sceneGeneration } : {},
           syncAll: false,
           elements: event.elements
@@ -519,25 +558,30 @@ var ExcalidrawCollabEngine = class {
           timestamp: new Date(event.occurredAt)
         });
         return;
+      case "view":
+        return;
       case "reset_required":
+        this.sceneRevision = null;
         this.requestSnapshot();
     }
   }
   handleRemoteData(payload) {
     this.applyRemoteElements({
       sceneId: payload.sceneId,
+      revision: payload.revision,
       ...payload.sceneGeneration ? { sceneGeneration: payload.sceneGeneration } : {},
       syncAll: payload.syncAll,
-      remoteElements: payload.elements.map(fromWireElement),
+      remoteElements: payload.elements.map((element) => withInk(fromWireElement(element), CANONICAL_INK, this.inkColor)),
       isSnapshot: false
     });
   }
   handleRemoteSnapshot(payload) {
     this.applyRemoteElements({
       sceneId: payload.sceneId,
+      revision: payload.revision,
       ...payload.sceneGeneration ? { sceneGeneration: payload.sceneGeneration } : {},
       syncAll: true,
-      remoteElements: payload.elements.map(fromWireElement),
+      remoteElements: payload.elements.map((element) => withInk(fromWireElement(element), CANONICAL_INK, this.inkColor)),
       appState: payload.appState,
       isSnapshot: true
     });
@@ -645,6 +689,7 @@ var ExcalidrawCollabEngine = class {
         this.requestSnapshot();
         return;
       }
+      this.sceneRevision = commit.revision;
       for (const element of submittedElements) {
         const previous = this.broadcastedElementVersions.get(element.id);
         const submittedVersion = { version: element.version, versionNonce: element.version_nonce };
@@ -685,7 +730,7 @@ var ExcalidrawCollabEngine = class {
     const submitted = [];
     for (const element of elements) {
       try {
-        submitted.push(toFittedWireElement(element));
+        submitted.push(toFittedWireElement(withInk(element, this.inkColor, CANONICAL_INK)));
         this.rejectedElementVersions.delete(element.id);
       } catch (cause) {
         const reported = this.rejectedElementVersions.has(element.id);
@@ -723,12 +768,17 @@ var ExcalidrawCollabEngine = class {
       this.deferredRemoteElements.clear();
       this.resetSubmissionRetries();
     }
+    this.sceneRevision = args.revision ?? null;
     if (args.sceneGeneration) this.sceneGeneration = args.sceneGeneration;
     const excalidrawAPI = this.opts.excalidrawAPI;
     if (replacingScene) excalidrawAPI.history.clear();
     const local = replacingScene ? [] : excalidrawAPI.getSceneElementsIncludingDeleted();
     const remoteElements = [...args.remoteElements].sort(compareElementOrder);
-    const restoredRemote = restoreElements(remoteElements, null);
+    const received = new Map(remoteElements.map((element) => [element.id, element]));
+    const restoredRemote = restoreElements(remoteElements, null).map((element) => {
+      const remote = received.get(element.id);
+      return remote && !remote.isDeleted && element.isDeleted ? { ...element, isDeleted: false, version: remote.version, versionNonce: remote.versionNonce } : element;
+    });
     this.storedImageFileIds = /* @__PURE__ */ new Set([...this.storedImageFileIds, ...remoteImageFileIds(restoredRemote)]);
     const remoteForReconcile = toReconcileRemoteElements(restoredRemote);
     const appState = excalidrawAPI.getAppState();

package/dist/collab/engine.d.ts

@@ -22,7 +22,31 @@ export type WhiteboardCollaborationEvent = {
     readonly x: number;
     readonly y: number;
     readonly occurredAt: string;
+} | ({
+    readonly type: "view";
+    readonly participantId: string;
+    readonly displayName: string;
+    readonly x: number;
+    readonly y: number;
+    readonly width: number;
+    readonly height: number;
+    readonly bring: boolean;
+    readonly occurredAt: string;
+} & ({
+    readonly originParticipantId: string;
+    readonly originSequence: number;
+    readonly originEpoch?: string;
+} | {
+    readonly originParticipantId?: never;
+    readonly originSequence?: never;
+    readonly originEpoch?: never;
+}) & ({
+    readonly ownerId: string;
+    readonly ownerSequence: number;
 } | {
+    readonly ownerId?: never;
+    readonly ownerSequence?: never;
+})) | {
     readonly type: "reset_required";
     readonly sceneId: string;
     readonly reason: "scene_changed" | "cursor_expired" | "gap";
@@ -30,8 +54,11 @@ export type WhiteboardCollaborationEvent = {
 export interface ExcalidrawCollabEngineOptions extends WhiteboardFileTransferOptions {
     excalidrawAPI: ExcalidrawImperativeAPI;
     canDraw: boolean;
+    /** Explicit management authority; omitted hosts keep the original draw-based behavior. */
+    canManage?: boolean;
     submitUpdate: (payload: {
         sceneId: string;
+        revision?: string;
         sceneGeneration?: string;
         syncAll: boolean;
         elements: readonly WhiteboardWireElement[];
@@ -45,12 +72,19 @@ export interface ExcalidrawCollabEngineOptions extends WhiteboardFileTransferOpt
     subscribe: (listener: (event: WhiteboardCollaborationEvent) => void) => () => void;
     onFileSyncStateChange?: (state: WhiteboardFileSyncState) => void;
     onSubmissionError?: (error: unknown) => void;
+    /** False when the host draws its own remote cursors. */
+    renderCursors?: boolean;
+    /** The colour this viewer sees for Ink, which travels as one canonical colour. */
+    inkColor?: string;
 }
 export declare class ExcalidrawCollabEngine {
     private readonly opts;
     private sceneId;
+    private sceneRevision;
     private sceneGeneration;
     private canDraw;
+    private canManage;
+    private inkColor;
     private storedImageFileIds;
     private broadcastedElementVersions;
     private rejectedElementVersions;
@@ -68,7 +102,12 @@ export declare class ExcalidrawCollabEngine {
     private readonly unsubscribe;
     constructor(opts: ExcalidrawCollabEngineOptions);
     setCanDraw(next: boolean): void;
+    setCanManage(next: boolean | undefined): void;
+    /** Repaints Ink for a new surface without a new version, so nothing is sent. */
+    setInkColor(next: string): void;
     clear(): Promise<WhiteboardCommit>;
+    /** Restore only into the exact empty scene committed by this clear. */
+    clearWithUndo(): Promise<() => boolean>;
     dispose(): void;
     handleChange(_elements: readonly OrderedExcalidrawElement[], _appState: AppState, _files: BinaryFiles): void;
     handlePointerUpdate(payload: {
@@ -87,12 +126,14 @@ export declare class ExcalidrawCollabEngine {
     handleRemoteEvent(event: WhiteboardCollaborationEvent): void;
     handleRemoteData(payload: {
         sceneId: string;
+        revision?: string;
         sceneGeneration?: string;
         syncAll: boolean;
         elements: readonly WhiteboardWireElement[];
     }): void;
     handleRemoteSnapshot(payload: {
         sceneId: string;
+        revision?: string;
         sceneGeneration?: string;
         elements: readonly WhiteboardWireElement[];
         appState?: SharedWhiteboardAppState;

package/dist/collab/index.js

@@ -1,12 +1,13 @@
 import {
   mergeWhiteboardElements
-} from "../chunk-W4FLPXAX.js";
+} from "../chunk-MPNIDZHM.js";
 import {
   ExcalidrawCollabEngine,
   fromWireElement,
   isWireElement,
   toWireElement
-} from "../chunk-6ZV7GBAC.js";
+} from "../chunk-X3WDTGPQ.js";
+import "../chunk-IVFWOYSW.js";
 export {
   ExcalidrawCollabEngine,
   fromWireElement,

package/dist/collab/ink.d.ts

@@ -0,0 +1,5 @@
+/** Ink travels and records as Paper's ink; each viewer paints it in their own surface's ink. */
+export declare const CANONICAL_INK = "#1b1c1f";
+export declare function withInk<T extends {
+    readonly strokeColor: string;
+}>(element: T, from: string, to: string): T;

package/dist/collab/presence.d.ts

@@ -10,6 +10,7 @@ export declare class WhiteboardPresence {
             x: number;
             y: number;
         }) => void;
+        renderCursors: boolean;
         throttleMs: number;
         staleMs: number;
     });

package/dist/embedded/chalk-whiteboard/asset-manifest.json

@@ -1216,8 +1216,8 @@
     },
     {
       "path": "renderer.js",
-      "bytes": 8497928,
-      "sha256": "7f754073f20cee4b3adceb40731faf75d94849f6ce01a0b2e30fdad10867a5d9"
+      "bytes": 8502340,
+      "sha256": "82afcc03b426364bcf0e83064452972ec6fc5b74f766fd024948ae866893ba68"
     },
     {
       "path": "THIRD_PARTY_NOTICES.json",