@q9labsai/chalk-whiteboard 5.0.1 → 5.2.0

package/dist/embedded/controller.d.ts

@@ -33,7 +33,23 @@ export type ChalkEmbeddedWhiteboardTransportEvent = {
     readonly type: "reset_required";
     readonly sceneId: string;
     readonly reason: "scene_changed" | "cursor_expired" | "gap";
-};
+} | ({
+    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 originParticipantId?: never;
+    readonly originSequence?: never;
+}));
 export interface ChalkEmbeddedWhiteboardFileTransport {
     readonly getDownloadUrl: (fileId: string) => Promise<{
         readonly downloadUrl: string;

package/dist/embedded/index.js

@@ -415,6 +415,8 @@ var ChalkWhiteboardController = class {
       case "cursor":
         this.#send({ type: "apply_cursor", payload: event });
         return;
+      case "view":
+        return;
       case "reset_required":
         this.#sceneGeneration = null;
         this.#send({ type: "reset_required", payload: event });

package/dist/{engine-BIJ57YN3.js → engine-MERF7RL3.js}

@@ -1,6 +1,7 @@
 import {
   ExcalidrawCollabEngine
-} from "./chunk-6ZV7GBAC.js";
+} from "./chunk-X3WDTGPQ.js";
+import "./chunk-IVFWOYSW.js";
 export {
   ExcalidrawCollabEngine
 };

package/dist/index.js

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

package/dist/react/WhiteboardCanvas.d.ts

@@ -1,6 +1,7 @@
 import { type ReactNode } from "react";
 import type { ExcalidrawImperativeAPI } from "@excalidraw/excalidraw/types";
 import type { ExcalidrawCollabEngineOptions } from "../collab/engine.js";
+type ExcalidrawModule = typeof import("@excalidraw/excalidraw");
 export interface WhiteboardCollaborationOptions extends Omit<ExcalidrawCollabEngineOptions, "excalidrawAPI" | "canDraw"> {
     canDraw?: boolean;
 }
@@ -29,8 +30,24 @@ export interface WhiteboardCanvasIcons {
     submit?: ReactNode;
     submitting?: ReactNode;
 }
+/** What a host that draws its own controls needs from the loaded engine. */
+export interface WhiteboardEngineHandle {
+    api: ExcalidrawImperativeAPI;
+    excalidraw: ExcalidrawModule;
+    /** Clears the shared board; resolves once the new empty scene is committed. */
+    clear: () => Promise<void>;
+    /** Clears and returns a restore bound to that committed scene and this engine lifetime. */
+    clearWithUndo: () => Promise<() => boolean>;
+    /** Renders LaTeX and places it on the board, or replaces the selected formula. */
+    placeMath: (latex: string) => Promise<void>;
+}
 export interface WhiteboardCanvasProps {
     className?: string;
+    /** Hides every engine control; the host draws its own and drives the engine through `onEngineReady`. */
+    headless?: boolean;
+    /** The colour this viewer sees for Ink. Ink travels as one canonical colour. */
+    inkColor?: string;
+    onEngineReady?: (engine: WhiteboardEngineHandle) => void;
     isVisible?: boolean;
     canDraw?: boolean;
     theme?: "light" | "dark";

package/dist/react/engine-history.d.ts

@@ -0,0 +1,7 @@
+import type { ExcalidrawImperativeAPI } from "@excalidraw/excalidraw/types";
+export type EngineHistoryState = {
+    readonly canUndo: boolean;
+    readonly canRedo: boolean;
+};
+/** 0.18.1 exposes clear, but not the history reader/emitter, on its imperative API. */
+export declare function observeEngineHistory(api: ExcalidrawImperativeAPI, canvas: HTMLElement, onChange: (state: EngineHistoryState) => void): () => void;

package/dist/react/index.d.ts

@@ -1,7 +1,9 @@
 export { WhiteboardCanvas, preloadWhiteboardStylesheet } from "./WhiteboardCanvas.js";
-export type { WhiteboardCanvasClassNames, WhiteboardCanvasIcons, WhiteboardCanvasProps, WhiteboardCollaborationOptions } from "./WhiteboardCanvas.js";
+export type { WhiteboardCanvasClassNames, WhiteboardCanvasIcons, WhiteboardCanvasProps, WhiteboardCollaborationOptions, WhiteboardEngineHandle } from "./WhiteboardCanvas.js";
 export { appendOrReplaceMathElement, CHALK_MATH_CUSTOM_DATA_KEY, CHALK_MATH_RENDERER, createMathFileId, createMathImageAsset, getChalkMathData, getInsertionPoint, getSelectedMathElement, isChalkMathElement, svgToDataUrl } from "./math-elements.js";
 export type { ChalkMathCustomData, MathImageAsset } from "./math-elements.js";
 export { getRenderedSvgSize, renderLatexToSvg } from "./mathjax-renderer.js";
 export type { RenderedMathSvg } from "./mathjax-renderer.js";
 export type { AppState, BinaryFileData, BinaryFiles, Collaborator, CollaboratorPointer, ExcalidrawElement, ExcalidrawImperativeAPI, OrderedExcalidrawElement } from "../collab/index.js";
+export { CANONICAL_INK } from "../collab/ink.js";
+export { observeEngineHistory, type EngineHistoryState } from "./engine-history.js";

package/dist/react/index.js

@@ -1,3 +1,7 @@
+import {
+  CANONICAL_INK
+} from "../chunk-IVFWOYSW.js";
+
 // src/react/WhiteboardCanvas.tsx
 import { memo, useCallback, useEffect, useMemo, useRef, useState as useState2 } from "react";
 
@@ -282,6 +286,7 @@ function useWhiteboardCanvasConfiguration(props) {
   const rootClassName = [classNames.root, valueOr(props.className, "")].filter(Boolean).join(" ");
   return {
     canDraw,
+    headless: props.headless === true,
     classNames,
     excalidrawCssPath: valueOr(props.excalidrawCssPath, DEFAULT_EXCALIDRAW_CSS),
     icons: valueOr(props.icons, {}),
@@ -355,67 +360,71 @@ function useExcalidrawModule(onLoadError, setLoadError) {
   }, [onLoadError, setLoadError]);
   return excalidraw;
 }
-function useWhiteboardInitialData(theme, localParticipantColor) {
+var TRANSPARENT = "transparent";
+function useWhiteboardInitialData(theme, headless, localParticipantColor, inkColor) {
+  const initialInk = useRef(inkColor);
   return useMemo(
     () => ({
       appState: {
-        viewBackgroundColor: theme === "dark" ? "#000000" : "#ffffff",
-        currentItemStrokeColor: localParticipantColor ?? "#4CB9FF",
+        viewBackgroundColor: headless ? TRANSPARENT : theme === "dark" ? "#000000" : "#ffffff",
+        currentItemStrokeColor: (headless ? initialInk.current : localParticipantColor) ?? "#4CB9FF",
         theme
       }
     }),
-    [localParticipantColor, theme]
-  );
-}
-function useWhiteboardUiOptions() {
-  return useMemo(
-    () => ({
-      canvasActions: {
-        changeViewBackgroundColor: false,
-        clearCanvas: false,
-        export: false,
-        loadScene: false,
-        saveAsImage: false,
-        saveToActiveFile: false,
-        toggleTheme: false
-      },
-      tools: { image: false },
-      welcomeScreen: false
-    }),
-    []
+    [headless, localParticipantColor, theme]
   );
 }
+var UI_OPTIONS = {
+  canvasActions: {
+    changeViewBackgroundColor: false,
+    clearCanvas: false,
+    export: false,
+    loadScene: false,
+    saveAsImage: false,
+    saveToActiveFile: false,
+    toggleTheme: false
+  },
+  tools: { image: false },
+  welcomeScreen: false
+};
 function useWhiteboardCollaboration(options) {
   const apiRef = useRef(null);
-  const refs = useCollaborationRefs(options.collab, options.canDraw);
-  const initializeEngine = useCollaborationEngineLoader(refs, apiRef, options.onLoadError, options.setLoadError);
+  const refs = useCollaborationRefs(options.collab, options.canDraw, options.inkColor);
+  const [engineReady, setEngineReady] = useState2(false);
+  const initializeEngine = useCollaborationEngineLoader(refs, apiRef, options.headless, options.onLoadError, options.setLoadError, setEngineReady);
   const handleApiReady = useExcalidrawApiReady(apiRef, initializeEngine, options.onExcalidrawApiReady);
   const handlers = useExcalidrawSceneHandlers(apiRef, refs.engineRef, options.onSelectedLatexChange);
-  useCollaborationCanDraw(refs.engineRef, options.canDraw);
+  useCollaborationPermissions(refs.engineRef, options.canDraw, options.collab?.canManage);
+  useCollaborationInk(refs.engineRef, options.inkColor);
   useCollaborationDisposal(refs.engineRef, refs.isMountedRef);
   useCollaborationInitialization(options.collab, apiRef, refs.engineRef, initializeEngine);
-  return { apiRef, handleApiReady, ...handlers };
+  return { ready: !options.collab || engineReady, apiRef, engineRef: refs.engineRef, handleApiReady, ...handlers };
 }
-function useCollaborationRefs(collab, canDraw) {
+function useCollaborationRefs(collab, canDraw, inkColor) {
   const canDrawRef = useRef(canDraw);
+  const inkColorRef = useRef(inkColor);
   const collabOptionsRef = useRef(collab);
   const enginePromiseRef = useRef(null);
   const engineRef = useRef(null);
   const isMountedRef = useRef(true);
   canDrawRef.current = canDraw;
+  inkColorRef.current = inkColor;
   collabOptionsRef.current = collab;
-  return useMemo(() => ({ canDrawRef, collabOptionsRef, enginePromiseRef, engineRef, isMountedRef }), [canDrawRef, collabOptionsRef, enginePromiseRef, engineRef, isMountedRef]);
+  return useMemo(() => ({ canDrawRef, inkColorRef, collabOptionsRef, enginePromiseRef, engineRef, isMountedRef }), [canDrawRef, inkColorRef, collabOptionsRef, enginePromiseRef, engineRef, isMountedRef]);
 }
-function useCollaborationEngineLoader(refs, apiRef, onLoadError, setLoadError) {
+function useCollaborationEngineLoader(refs, apiRef, headless, onLoadError, setLoadError, setEngineReady) {
   return useCallback(() => {
     if (!refs.collabOptionsRef.current || refs.engineRef.current || refs.enginePromiseRef.current) return;
-    refs.enginePromiseRef.current = import("../engine-BIJ57YN3.js").then(({ ExcalidrawCollabEngine }) => {
+    refs.enginePromiseRef.current = import("../engine-MERF7RL3.js").then(({ ExcalidrawCollabEngine }) => {
       const api = apiRef.current;
       const collab = refs.collabOptionsRef.current;
       if (!refs.isMountedRef.current || !api || !collab) return;
       refs.engineRef.current = new ExcalidrawCollabEngine({
         excalidrawAPI: api,
         canDraw: refs.canDrawRef.current,
+        canManage: collab.canManage,
+        renderCursors: !headless,
+        ...refs.inkColorRef.current ? { inkColor: refs.inkColorRef.current } : {},
         submitUpdate: collab.submitUpdate,
         sendCursor: collab.sendCursor,
         requestSnapshot: collab.requestSnapshot,
@@ -426,6 +435,7 @@ function useCollaborationEngineLoader(refs, apiRef, onLoadError, setLoadError) {
         onFileSyncStateChange: collab.onFileSyncStateChange,
         onSubmissionError: collab.onSubmissionError
       });
+      setEngineReady(true);
     }).catch((reason) => {
       if (!refs.isMountedRef.current) return;
       const error = reason instanceof Error ? reason : new Error("Failed to load whiteboard collaboration");
@@ -434,7 +444,7 @@ function useCollaborationEngineLoader(refs, apiRef, onLoadError, setLoadError) {
     }).finally(() => {
       refs.enginePromiseRef.current = null;
     });
-  }, [apiRef, onLoadError, refs, setLoadError]);
+  }, [apiRef, headless, onLoadError, refs, setLoadError, setEngineReady]);
 }
 function useExcalidrawApiReady(apiRef, initializeEngine, onExcalidrawApiReady) {
   const didReportApiRef = useRef(false);
@@ -478,10 +488,16 @@ function selectedMathLatex(api) {
   const math = getChalkMathData(selected);
   return math ? math.latex : null;
 }
-function useCollaborationCanDraw(engineRef, canDraw) {
+function useCollaborationPermissions(engineRef, canDraw, canManage) {
   useEffect(() => {
     engineRef.current?.setCanDraw(canDraw);
-  }, [canDraw, engineRef]);
+    engineRef.current?.setCanManage(canManage);
+  }, [canDraw, canManage, engineRef]);
+}
+function useCollaborationInk(engineRef, inkColor) {
+  useEffect(() => {
+    if (inkColor) engineRef.current?.setInkColor(inkColor);
+  }, [engineRef, inkColor]);
 }
 function useCollaborationDisposal(engineRef, isMountedRef) {
   useEffect(() => {
@@ -537,6 +553,8 @@ function useWhiteboardCanvasState(props) {
   const stylesheet = useExternalStylesheet(configuration.excalidrawCssPath);
   const collaboration = useWhiteboardCollaboration({
     canDraw: configuration.canDraw,
+    headless: configuration.headless,
+    inkColor: props.inkColor,
     collab: props.collab,
     onExcalidrawApiReady: props.onExcalidrawApiReady,
     onLoadError: props.onLoadError,
@@ -552,39 +570,87 @@ function useWhiteboardCanvasState(props) {
     setSelectedLatex,
     syncScene: collaboration.syncScene
   });
-  const initialData = useWhiteboardInitialData(configuration.theme, props.localParticipantColor);
-  const uiOptions = useWhiteboardUiOptions();
+  const initialData = useWhiteboardInitialData(configuration.theme, configuration.headless, props.localParticipantColor, props.inkColor);
   const resolvedLoadError = loadError ?? stylesheet.error;
+  const isReady = Boolean(excalidraw && stylesheet.loaded && !resolvedLoadError);
+  const engine = useEngineHandle(props.onEngineReady, excalidraw, collaboration, math.handleSubmitMath, configuration.headless, isReady);
   return {
     collaboration,
     configuration,
     excalidraw,
     initialData,
-    isReady: Boolean(excalidraw && stylesheet.loaded && !resolvedLoadError),
+    isReady,
     math,
     resolvedLoadError,
-    uiOptions
+    uiOptions: UI_OPTIONS,
+    ...engine
   };
 }
+function useEngineHandle(onEngineReady, excalidraw, collaboration, placeMath, headless, isReady) {
+  const [api, setApi] = useState2(null);
+  const [loaded, setLoaded] = useState2(false);
+  const { handleApiReady, handleChange } = collaboration;
+  const onApiReady = useCallback(
+    (next) => {
+      handleApiReady(next);
+      setApi(next);
+    },
+    [handleApiReady]
+  );
+  const onChange = useCallback(
+    (elements, appState, files) => {
+      handleChange(elements, appState, files);
+      if (!appState.isLoading) setLoaded(true);
+      if (headless && appState.viewBackgroundColor !== TRANSPARENT) api?.updateScene({ appState: { viewBackgroundColor: TRANSPARENT } });
+    },
+    [api, handleChange, headless]
+  );
+  const placeMathRef = useRef(placeMath);
+  placeMathRef.current = placeMath;
+  const liveApi = useRef(api);
+  useEffect(() => {
+    liveApi.current = api;
+    return () => {
+      liveApi.current = null;
+    };
+  }, [api]);
+  const { engineRef } = collaboration;
+  useEffect(() => {
+    if (!api || !excalidraw || !loaded || !isReady || !collaboration.ready || !onEngineReady) return;
+    onEngineReady({
+      api,
+      excalidraw,
+      clear: async () => {
+        const engine = engineRef.current;
+        if (engine) await engine.clear();
+        else {
+          api.updateScene({ elements: [], captureUpdate: excalidraw.CaptureUpdateAction.NEVER });
+          api.history.clear();
+        }
+      },
+      clearWithUndo: async () => {
+        const engine = engineRef.current;
+        if (engine) return engine.clearWithUndo();
+        const before = api.getSceneElements();
+        api.updateScene({ elements: [], captureUpdate: excalidraw.CaptureUpdateAction.NEVER });
+        api.history.clear();
+        return () => {
+          if (liveApi.current !== api || api.getSceneElementsIncludingDeleted().length > 0) return false;
+          api.updateScene({ elements: before.map((element) => excalidraw.newElementWith(element, {})), captureUpdate: excalidraw.CaptureUpdateAction.IMMEDIATELY });
+          return true;
+        };
+      },
+      placeMath: (latex) => placeMathRef.current(latex)
+    });
+  }, [api, engineRef, excalidraw, isReady, loaded, collaboration.ready, onEngineReady]);
+  return { onApiReady, onChange };
+}
 function WhiteboardCanvasView({ state }) {
-  const { collaboration, configuration, excalidraw, initialData, isReady, math, resolvedLoadError, uiOptions } = state;
+  const { configuration, excalidraw, initialData, isReady, math, onApiReady, onChange, collaboration, resolvedLoadError, uiOptions } = state;
   return /* @__PURE__ */ jsxs2("div", { className: configuration.rootClassName, hidden: !configuration.isVisible, children: [
-    /* @__PURE__ */ jsx2(WhiteboardMathToolbar, { canDraw: configuration.canDraw && !configuration.isCollaborating, classNames: configuration.classNames, isReady, onOpenMath: math.openMath, selectedLatex: math.selectedLatex }),
-    /* @__PURE__ */ jsx2(WhiteboardCanvasStatus, { classNames: configuration.classNames, error: resolvedLoadError, icons: configuration.icons, isReady }),
-    excalidraw && /* @__PURE__ */ jsx2(
-      WhiteboardScene,
-      {
-        canDraw: configuration.canDraw,
-        collab: configuration.isCollaborating,
-        excalidraw,
-        initialData,
-        onApiReady: collaboration.handleApiReady,
-        onChange: collaboration.handleChange,
-        onPointerUpdate: collaboration.handlePointerUpdate,
-        theme: configuration.theme,
-        uiOptions
-      }
-    ),
+    /* @__PURE__ */ jsx2(WhiteboardMathToolbar, { canDraw: configuration.canDraw && !configuration.isCollaborating && !configuration.headless, classNames: configuration.classNames, isReady, onOpenMath: math.openMath, selectedLatex: math.selectedLatex }),
+    /* @__PURE__ */ jsx2(WhiteboardCanvasStatus, { classNames: configuration.classNames, error: resolvedLoadError, icons: configuration.icons, isReady: isReady || configuration.headless }),
+    excalidraw && /* @__PURE__ */ jsx2(WhiteboardScene, { canDraw: configuration.canDraw, collab: configuration.isCollaborating, excalidraw, initialData, onApiReady, onChange, onPointerUpdate: collaboration.handlePointerUpdate, theme: configuration.theme, uiOptions }),
     math.isMathOpen && /* @__PURE__ */ jsx2(MathEditor, { initialLatex: math.initialLatex, isEditing: Boolean(math.selectedLatex), classNames: configuration.classNames, icons: configuration.icons, onClose: math.closeMath, onSubmit: math.handleSubmitMath })
   ] });
 }
@@ -605,7 +671,7 @@ function WhiteboardLoading({ classNames, loadingIcon }) {
   ] }) });
 }
 function WhiteboardLoadError({ className, error }) {
-  return /* @__PURE__ */ jsx2("div", { className, style: { position: "absolute", inset: 0, zIndex: 30, display: "flex", alignItems: "center", justifyContent: "center" }, children: /* @__PURE__ */ jsx2("div", { children: error }) });
+  return /* @__PURE__ */ jsx2("div", { role: "alert", className, style: { position: "absolute", inset: 0, zIndex: 30, display: "flex", alignItems: "center", justifyContent: "center" }, children: /* @__PURE__ */ jsx2("div", { children: error }) });
 }
 function WhiteboardScene({
   canDraw,
@@ -625,7 +691,49 @@ function WhiteboardCanvasBase(props) {
 }
 var WhiteboardCanvas = memo(WhiteboardCanvasBase);
 WhiteboardCanvas.displayName = "WhiteboardCanvas";
+
+// src/react/engine-history.ts
+function observeEngineHistory(api, canvas, onChange) {
+  let connected = false;
+  let dispose = () => {
+  };
+  api.registerAction({
+    name: "stats",
+    label: "Stats",
+    trackEvent: false,
+    perform: () => false,
+    keyTest: (_event, _state, _elements, app) => {
+      if (connected) return false;
+      connected = true;
+      const history = app.history;
+      const read = () => ({ isUndoStackEmpty: history.isUndoStackEmpty, isRedoStackEmpty: history.isRedoStackEmpty });
+      const originalClear = history.clear;
+      const clear = () => {
+        originalClear.call(history);
+        history.onHistoryChangedEmitter.trigger(read());
+      };
+      history.clear = clear;
+      const update = () => {
+        const state = read();
+        onChange({ canUndo: !state.isUndoStackEmpty, canRedo: !state.isRedoStackEmpty });
+      };
+      const off = history.onHistoryChangedEmitter.on(update);
+      update();
+      dispose = () => {
+        off();
+        history.clear = originalClear;
+      };
+      return false;
+    }
+  });
+  canvas.dispatchEvent(new KeyboardEvent("keydown", { key: "Shift", bubbles: true }));
+  return () => {
+    connected = true;
+    dispose();
+  };
+}
 export {
+  CANONICAL_INK,
   CHALK_MATH_CUSTOM_DATA_KEY,
   CHALK_MATH_RENDERER,
   WhiteboardCanvas,
@@ -637,6 +745,7 @@ export {
   getRenderedSvgSize,
   getSelectedMathElement,
   isChalkMathElement,
+  observeEngineHistory,
   preloadWhiteboardStylesheet,
   renderLatexToSvg,
   svgToDataUrl

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@q9labsai/chalk-whiteboard",
-  "version": "5.0.1",
+  "version": "5.2.0",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -8,7 +8,8 @@
     "directory": "packages/whiteboard"
   },
   "files": [
-    "dist"
+    "dist",
+    "CHANGELOG.md"
   ],
   "type": "module",
   "sideEffects": false,
@@ -70,7 +71,7 @@
     "@types/react": "^19.0.0",
     "@types/react-dom": "^19.2.3",
     "esbuild": "0.28.2",
-    "happy-dom": "^20.11.2",
+    "happy-dom": "^21.0.4",
     "react": "19.2.7",
     "react-dom": "19.2.7",
     "typescript": "^5.7.2"