@xom11/whiteboard 0.10.1 → 0.11.0

package/dist/index.d.mts

@@ -79,8 +79,24 @@ interface WhiteboardProps {
      * `STABLE_STAMPS` để chỉ bật stamp ổn định.
      */
     stamps?: ReadonlyArray<StampType>;
+    /**
+     * Snapshot từ server. Precedence: `initialScene` > localStorage > blank.
+     * - `undefined` (default) → đọc từ localStorage qua `storageKey`
+     * - `null` → explicit blank, bỏ qua localStorage
+     * - object → dùng làm initialData của Excalidraw, bỏ qua localStorage
+     *
+     * Dùng để load board từ server. Thường đi cùng `storageKey={null}` để
+     * tránh localStorage stale override server data.
+     */
+    initialScene?: ExcalidrawSceneSnapshot | null;
+    /**
+     * Binary files (raster, base64) từ server. Add vào Excalidraw đúng 1 lần
+     * khi api ready. Dùng kèm `initialScene` cho flow load-from-server.
+     * Nếu cần inject files động về sau, dùng `onApi` rồi gọi `api.addFiles`.
+     */
+    initialFiles?: BinaryFiles;
 }
-declare function Whiteboard({ storageKey, readOnly, onSceneChange, onFilesChange, onApi, langCode, stamps, }: WhiteboardProps): react_jsx_runtime.JSX.Element;
+declare function Whiteboard({ storageKey, readOnly, onSceneChange, onFilesChange, onApi, langCode, stamps, initialScene, initialFiles, }: WhiteboardProps): react_jsx_runtime.JSX.Element;
 
 declare function pickSyncableAppState(s: AppState): SyncableAppState;
 

package/dist/index.d.ts

@@ -79,8 +79,24 @@ interface WhiteboardProps {
      * `STABLE_STAMPS` để chỉ bật stamp ổn định.
      */
     stamps?: ReadonlyArray<StampType>;
+    /**
+     * Snapshot từ server. Precedence: `initialScene` > localStorage > blank.
+     * - `undefined` (default) → đọc từ localStorage qua `storageKey`
+     * - `null` → explicit blank, bỏ qua localStorage
+     * - object → dùng làm initialData của Excalidraw, bỏ qua localStorage
+     *
+     * Dùng để load board từ server. Thường đi cùng `storageKey={null}` để
+     * tránh localStorage stale override server data.
+     */
+    initialScene?: ExcalidrawSceneSnapshot | null;
+    /**
+     * Binary files (raster, base64) từ server. Add vào Excalidraw đúng 1 lần
+     * khi api ready. Dùng kèm `initialScene` cho flow load-from-server.
+     * Nếu cần inject files động về sau, dùng `onApi` rồi gọi `api.addFiles`.
+     */
+    initialFiles?: BinaryFiles;
 }
-declare function Whiteboard({ storageKey, readOnly, onSceneChange, onFilesChange, onApi, langCode, stamps, }: WhiteboardProps): react_jsx_runtime.JSX.Element;
+declare function Whiteboard({ storageKey, readOnly, onSceneChange, onFilesChange, onApi, langCode, stamps, initialScene, initialFiles, }: WhiteboardProps): react_jsx_runtime.JSX.Element;
 
 declare function pickSyncableAppState(s: AppState): SyncableAppState;
 

package/dist/index.js

@@ -11429,7 +11429,9 @@ function Whiteboard({
   onFilesChange,
   onApi,
   langCode = "vi-VN",
-  stamps = DEFAULT_STAMPS
+  stamps = DEFAULT_STAMPS,
+  initialScene,
+  initialFiles
 }) {
   const [api, setApi] = React8.useState(null);
   const apiRef = React8.useRef(null);
@@ -11458,7 +11460,7 @@ function Whiteboard({
     () => persistEnabled ? readScene(storageKey) : null,
     [persistEnabled, storageKey]
   );
-  const effectiveInitialScene = persistedInitial ? {
+  const effectiveInitialScene = initialScene !== void 0 ? initialScene : persistedInitial ? {
     elements: persistedInitial.elements,
     appState: persistedInitial.appState
   } : null;
@@ -11633,6 +11635,30 @@ function Whiteboard({
       console.warn("[whiteboard] flushPrune th\u1EA5t b\u1EA1i:", err);
     }
   };
+  const initialFilesAddedRef = React8.useRef(false);
+  React8.useEffect(() => {
+    if (!api || initialFilesAddedRef.current) return;
+    initialFilesAddedRef.current = true;
+    if (!initialFiles) return;
+    const entries = Object.entries(initialFiles);
+    if (entries.length === 0) return;
+    try {
+      api.addFiles(
+        entries.map(([id, f]) => ({
+          id,
+          // eslint-disable-next-line @typescript-eslint/no-explicit-any
+          dataURL: f.dataURL,
+          // eslint-disable-next-line @typescript-eslint/no-explicit-any
+          mimeType: f.mimeType,
+          // eslint-disable-next-line @typescript-eslint/no-explicit-any
+          created: f.created ?? Date.now()
+        }))
+      );
+      entries.forEach(([id]) => knownFileIdsRef.current.add(id));
+    } catch (err) {
+      console.warn("[whiteboard] addFiles initialFiles th\u1EA5t b\u1EA1i:", err);
+    }
+  }, [api]);
   React8.useEffect(() => {
     if (!api || !persistEnabled) return;
     let cancelled = false;