@100mslive/hms-whiteboard 0.0.6-alpha.0 → 0.0.6-alpha.2

package/src/hooks/StoreClient.ts

@@ -0,0 +1,136 @@
+import { GrpcWebFetchTransport } from '@protobuf-ts/grpcweb-transport';
+import { Value_Type } from '../grpc/sessionstore';
+import { StoreClient } from '../grpc/sessionstore.client';
+
+interface OpenCallbacks<T> {
+  handleOpen: (values: T[]) => void;
+  handleChange: (key: string, value?: T) => void;
+  handleError: (error: Error, isTerminal?: boolean) => void;
+}
+
+const WHITEBOARD_CLOSE_MESSAGE = 'client whiteboard abort';
+const RETRY_ERROR_MESSAGES = ['network error', 'failed to fetch'];
+
+export class SessionStore<T> {
+  private storeClient: StoreClient;
+
+  constructor(endpoint: string, token: string) {
+    const transport = new GrpcWebFetchTransport({
+      baseUrl: endpoint,
+      meta: { Authorization: `Bearer ${token}` },
+    });
+
+    this.storeClient = new StoreClient(transport);
+  }
+
+  async open({ handleOpen, handleChange, handleError }: OpenCallbacks<T>) {
+    const abortController = new AbortController();
+    const call = this.storeClient.open(
+      {
+        changeId: '',
+        select: [],
+      },
+      { abort: abortController.signal },
+    );
+    let count: number | undefined = undefined;
+    const initialValues: T[] = [];
+
+    call.responses.onMessage(message => {
+      if (message.value) {
+        if (message.value?.data.oneofKind === 'str') {
+          const record = JSON.parse(message.value.data.str) as T;
+          if (initialValues.length === count) {
+            handleChange(message.key, record);
+          } else {
+            initialValues.push(record);
+            if (initialValues.length === count) {
+              handleOpen(initialValues);
+            }
+          }
+        }
+      } else {
+        handleChange(message.key);
+      }
+    });
+
+    call.responses.onError(error => {
+      const canRecover = RETRY_ERROR_MESSAGES.includes(error.message.toLowerCase());
+      const shouldRetryInstantly = error.message.toLowerCase() === 'network error';
+
+      const openCallback = () => {
+        abortController.abort(`closing to open new conn`);
+        this.open({ handleOpen, handleChange, handleError });
+        window.removeEventListener('online', openCallback);
+      };
+      if (canRecover) {
+        shouldRetryInstantly && openCallback();
+        window.addEventListener('online', openCallback);
+      }
+
+      if (!error.message.includes('abort')) {
+        handleError(error, !canRecover);
+      }
+    });
+
+    try {
+      count = await this.getKeysCountWithDelay();
+      handleOpen(count ? initialValues : []);
+    } catch (error) {
+      const canRecover = RETRY_ERROR_MESSAGES.includes((error as unknown as Error).message.toLowerCase());
+      handleError(error as unknown as Error, canRecover);
+    }
+
+    return () => {
+      abortController.abort(WHITEBOARD_CLOSE_MESSAGE);
+    };
+  }
+
+  set(key: string, value?: T) {
+    const valueStr = value ? JSON.stringify(value) : undefined;
+    return this.storeClient.set({
+      key,
+      value: valueStr
+        ? {
+            data: { str: valueStr, oneofKind: 'str' },
+            type: Value_Type.STRING,
+          }
+        : {
+            data: { oneofKind: undefined },
+            type: Value_Type.NONE,
+          },
+    });
+  }
+
+  async get(key: string) {
+    const { response } = await this.storeClient.get({ key });
+
+    if (response.value?.data.oneofKind === 'str') {
+      return JSON.parse(response.value.data.str) as T;
+    }
+  }
+
+  async getKeysCount() {
+    const { response } = await this.storeClient.count({});
+    return Number(response.count);
+  }
+
+  delete(key: string) {
+    return this.storeClient.delete({ key });
+  }
+
+  private async getKeysCountWithDelay() {
+    const MAX_RETRIES = 3;
+    const DELAY = 200;
+    for (let i = 0; i < MAX_RETRIES; i++) {
+      try {
+        await new Promise(resolve => setTimeout(resolve, DELAY));
+        return await this.getKeysCount();
+      } catch (error) {
+        console.warn(error);
+        if ((error as unknown as Error).message !== 'peer not found' || i === MAX_RETRIES - 1) {
+          throw error;
+        }
+      }
+    }
+  }
+}

package/src/hooks/default_store.ts

@@ -0,0 +1,141 @@
+export const DEFAULT_STORE = {
+  store: {
+    'document:document': {
+      gridSize: 10,
+      name: '',
+      meta: {},
+      id: 'document:document',
+      typeName: 'document',
+    },
+    'pointer:pointer': {
+      id: 'pointer:pointer',
+      typeName: 'pointer',
+      x: 0,
+      y: 0,
+      lastActivityTimestamp: 0,
+      meta: {},
+    },
+    'page:page': {
+      meta: {},
+      id: 'page:page',
+      name: 'Page 1',
+      index: 'a1',
+      typeName: 'page',
+    },
+    'camera:page:page': {
+      x: 0,
+      y: 0,
+      z: 1,
+      meta: {},
+      id: 'camera:page:page',
+      typeName: 'camera',
+    },
+    'instance_page_state:page:page': {
+      editingShapeId: null,
+      croppingShapeId: null,
+      selectedShapeIds: [],
+      hoveredShapeId: null,
+      erasingShapeIds: [],
+      hintingShapeIds: [],
+      focusedGroupId: null,
+      meta: {},
+      id: 'instance_page_state:page:page',
+      pageId: 'page:page',
+      typeName: 'instance_page_state',
+    },
+    'instance:instance': {
+      followingUserId: null,
+      opacityForNextShape: 1,
+      stylesForNextShape: {},
+      brush: null,
+      scribble: null,
+      cursor: {
+        type: 'default',
+        rotation: 0,
+      },
+      isFocusMode: false,
+      exportBackground: true,
+      isDebugMode: false,
+      isToolLocked: false,
+      screenBounds: {
+        x: 0,
+        y: 0,
+        w: 720,
+        h: 400,
+      },
+      zoomBrush: null,
+      isGridMode: false,
+      isPenMode: false,
+      chatMessage: '',
+      isChatting: false,
+      highlightedUserIds: [],
+      canMoveCamera: true,
+      isFocused: true,
+      devicePixelRatio: 2,
+      isCoarsePointer: false,
+      isHoveringCanvas: false,
+      openMenus: [],
+      isChangingStyle: false,
+      isReadonly: false,
+      meta: {},
+      id: 'instance:instance',
+      currentPageId: 'page:page',
+      typeName: 'instance',
+    },
+  },
+  schema: {
+    schemaVersion: 1,
+    storeVersion: 4,
+    recordVersions: {
+      asset: {
+        version: 1,
+        subTypeKey: 'type',
+        subTypeVersions: {
+          image: 2,
+          video: 2,
+          bookmark: 0,
+        },
+      },
+      camera: {
+        version: 1,
+      },
+      document: {
+        version: 2,
+      },
+      instance: {
+        version: 21,
+      },
+      instance_page_state: {
+        version: 5,
+      },
+      page: {
+        version: 1,
+      },
+      shape: {
+        version: 3,
+        subTypeKey: 'type',
+        subTypeVersions: {
+          group: 0,
+          text: 1,
+          bookmark: 1,
+          draw: 1,
+          geo: 7,
+          note: 4,
+          line: 1,
+          frame: 0,
+          arrow: 1,
+          highlight: 0,
+          embed: 4,
+          image: 2,
+          video: 1,
+        },
+      },
+      instance_presence: {
+        version: 5,
+      },
+      pointer: {
+        version: 1,
+      },
+    },
+  },
+};

package/src/hooks/useCollaboration.ts

@@ -0,0 +1,257 @@
+import { useCallback, useEffect, useState } from 'react';
+import {
+  createTLStore,
+  debounce,
+  defaultShapeUtils,
+  Editor,
+  HistoryEntry,
+  throttle,
+  TLAnyShapeUtilConstructor,
+  TLInstance,
+  TLINSTANCE_ID,
+  TLPage,
+  TLRecord,
+  TLStoreWithStatus,
+  transact,
+} from '@tldraw/tldraw';
+import { DEFAULT_STORE } from './default_store';
+import { useSessionStore } from './useSessionStore';
+import { useSetEditorPermissions } from './useSetEditorPermissions';
+import { CURRENT_PAGE_KEY, PAGES_DEBOUNCE_TIME, SHAPES_THROTTLE_TIME } from '../utils';
+
+// mandatory record types required for initialisation of the whiteboard and for a full remote sync
+const FULL_SYNC_REQUIRED_RECORD_TYPES: TLRecord['typeName'][] = [
+  'camera',
+  'document',
+  'instance',
+  'instance_page_state',
+  'page',
+];
+
+export function useCollaboration({
+  endpoint,
+  token,
+  editor,
+  shapeUtils = [],
+  zoomToContent = false,
+}: {
+  endpoint?: string;
+  token?: string;
+  editor?: Editor;
+  shapeUtils?: TLAnyShapeUtilConstructor[];
+  zoomToContent?: boolean;
+}) {
+  const [store] = useState(() => {
+    const store = createTLStore({
+      shapeUtils: [...defaultShapeUtils, ...shapeUtils],
+    });
+    store.loadSnapshot(DEFAULT_STORE);
+    return store;
+  });
+
+  const [currentPage, setCurrentPage] = useState<TLPage | undefined>(editor?.getCurrentPage());
+
+  const [storeWithStatus, setStoreWithStatus] = useState<TLStoreWithStatus>({
+    status: 'loading',
+  });
+
+  const handleError = useCallback(
+    (error: Error, isTerminal?: boolean) => {
+      setStoreWithStatus(
+        isTerminal
+          ? {
+              error,
+              status: 'error',
+            }
+          : {
+              store,
+              status: 'synced-remote',
+              connectionStatus: 'offline',
+            },
+      );
+    },
+    [store],
+  );
+
+  const sessionStore = useSessionStore({ token, endpoint, handleError });
+  const permissions = useSetEditorPermissions({ token, editor, zoomToContent, handleError });
+
+  const handleOpen = useCallback(
+    (initialRecords: TLRecord[]) => {
+      if (!sessionStore) {
+        return;
+      }
+
+      // Initialize the tldraw store with the session store server records—or, if the session store
+      // is empty, initialize the session store server with the default tldraw store records.
+      const shouldUseServerRecords = FULL_SYNC_REQUIRED_RECORD_TYPES.every(
+        type => initialRecords.filter(record => record.typeName === type).length > 0,
+      );
+      if (shouldUseServerRecords) {
+        // Replace the tldraw store records with session store
+        store.mergeRemoteChanges(() => {
+          // The records here should be compatible with what's in the store
+          store.clear();
+          store.put(initialRecords);
+        });
+      } else {
+        // Create the initial store records
+        // Sync the local tldraw store records to session store
+        for (const record of store.allRecords()) {
+          sessionStore.set(record.id, record);
+        }
+      }
+      setStoreWithStatus({
+        store,
+        status: 'synced-remote',
+        connectionStatus: 'online',
+      });
+    },
+    [store, sessionStore],
+  );
+
+  const handleChange = useCallback(
+    (key: string, value?: TLRecord) => {
+      // put / remove the records in the store
+      store.mergeRemoteChanges(() => {
+        if (!value) {
+          return store.remove([key as TLRecord['id']]);
+        }
+        if (key === CURRENT_PAGE_KEY) {
+          setCurrentPage(value as TLPage);
+        } else {
+          transact(() => {
+            store.put([value]);
+            if (key === TLINSTANCE_ID) {
+              store.put([
+                { ...value, canMoveCamera: !!zoomToContent, isReadonly: !permissions.includes('write') } as TLInstance,
+              ]);
+            }
+          });
+        }
+      });
+    },
+    [store, permissions, zoomToContent],
+  );
+
+  useEffect(() => {
+    if (!sessionStore) return;
+
+    setStoreWithStatus({ status: 'loading' });
+
+    const unsubs: (() => void)[] = [];
+
+    // Open session and sync the session store changes to the store
+    sessionStore
+      .open({
+        handleOpen,
+        handleChange,
+        handleError,
+      })
+      .then(unsub => unsubs.push(unsub));
+
+    // Sync store changes to the yjs doc
+    unsubs.push(
+      store.listen(
+        throttle(function syncStoreChangesToYjsDoc({ changes }: HistoryEntry<TLRecord>) {
+          Object.values(changes.added).forEach(record => {
+            sessionStore.set(record.id, record);
+          });
+
+          Object.values(changes.updated).forEach(([, record]) => {
+            sessionStore.set(record.id, record);
+          });
+
+          Object.values(changes.removed).forEach(record => {
+            sessionStore.delete(record.id);
+          });
+        }, SHAPES_THROTTLE_TIME),
+        { source: 'user', scope: 'document' }, // only sync user's document changes
+      ),
+    );
+
+    // let hasConnectedBefore = false;
+
+    // function handleStatusChange({
+    //   status,
+    // }: {
+    //   status: "disconnected" | "connected";
+    // }) {
+    //   // If we're disconnected, set the store status to 'synced-remote' and the connection status to 'offline'
+    //   if (status === "disconnected") {
+    //     setStoreWithStatus({
+    //       store,
+    //       status: "synced-remote",
+    //       connectionStatus: "offline",
+    //     });
+    //     return;
+    //   }
+
+    //   room.off("synced", handleSync);
+
+    //   if (status === "connected") {
+    //     if (hasConnectedBefore) return;
+    //     hasConnectedBefore = true;
+    //     room.on("synced", handleSync);
+    //     unsubs.push(() => room.off("synced", handleSync));
+    //   }
+    // }
+
+    // room.on("status", handleStatusChange);
+    // unsubs.push(() => room.off("status", handleStatusChange));
+
+    return () => {
+      unsubs.forEach(fn => fn());
+      unsubs.length = 0;
+    };
+  }, [store, sessionStore, handleChange, handleOpen, handleError]);
+
+  useEffect(() => {
+    if (!editor || !sessionStore) return;
+
+    const unsubs: (() => void)[] = [];
+
+    unsubs.push(
+      store.listen(
+        debounce(({ changes }) => {
+          Object.keys(changes.updated).forEach(key => {
+            // Only update the current page id from the instance changes, ignore pointer changes
+            if (!key.includes('instance')) {
+              return;
+            }
+            const newPage = editor?.getCurrentPage();
+
+            if (newPage?.id !== currentPage?.id) {
+              sessionStore.get(TLINSTANCE_ID).then(instance => {
+                if (instance) {
+                  sessionStore?.set(instance.id, { ...instance, currentPageId: newPage?.id } as TLInstance);
+                }
+              });
+              setCurrentPage(newPage);
+            }
+          });
+        }, PAGES_DEBOUNCE_TIME),
+        { source: 'user', scope: 'session' },
+      ),
+    );
+
+    return () => {
+      unsubs.forEach(fn => fn());
+      unsubs.length = 0;
+    };
+  }, [currentPage, editor, sessionStore, store]);
+
+  // zoom to fit on remote changes for hls viewer
+  useEffect(() => {
+    if (!editor || !editor.getInstanceState()?.isReadonly || !zoomToContent) return;
+
+    store.listen(
+      () => {
+        editor.zoomToFit();
+      },
+      { source: 'remote', scope: 'document' },
+    );
+  }, [editor, store, zoomToContent]);
+
+  return storeWithStatus;
+}

package/src/hooks/useSessionStore.ts

@@ -0,0 +1,32 @@
+import { useMemo } from 'react';
+import { TLRecord } from '@tldraw/tldraw';
+import { SessionStore } from './StoreClient';
+import decodeJWT from '../utils';
+
+export const useSessionStore = ({
+  token,
+  endpoint = 'https://store-prod-in3-grpc.100ms.live',
+  handleError,
+}: {
+  token?: string;
+  endpoint?: string;
+  handleError: (error: Error) => void;
+}) => {
+  const sessionStore = useMemo(() => {
+    try {
+      decodeJWT(token);
+    } catch (err) {
+      return handleError(err as Error);
+    }
+    if (!endpoint || !token) {
+      return handleError(new Error('Missing GRPC endpoint or token'));
+    }
+
+    const sessionStore = new SessionStore<TLRecord>(endpoint, token);
+    // @ts-expect-error - for debugging
+    window.sessionStore = sessionStore;
+    return sessionStore;
+  }, [endpoint, token, handleError]);
+
+  return sessionStore;
+};

package/src/hooks/useSetEditorPermissions.tsx

@@ -0,0 +1,38 @@
+import { useEffect, useMemo } from 'react';
+import { Editor } from '@tldraw/tldraw';
+import decodeJWT from '../utils';
+
+export const useSetEditorPermissions = ({
+  token,
+  editor,
+  zoomToContent = false,
+  handleError,
+}: {
+  token?: string;
+  editor?: Editor;
+  zoomToContent?: boolean;
+  handleError: (error: Error) => void;
+}) => {
+  const { permissions } = useMemo(() => {
+    try {
+      return decodeJWT(token);
+    } catch (err) {
+      handleError(err as Error);
+      return {};
+    }
+  }, [token, handleError]);
+
+  useEffect(() => {
+    // disable scroll and zoom
+    editor?.updateInstanceState({ canMoveCamera: !!zoomToContent });
+
+    if (!permissions) {
+      return;
+    }
+
+    const isReadonly = !permissions.includes('write');
+    editor?.updateInstanceState({ isReadonly });
+  }, [permissions, zoomToContent, editor]);
+
+  return permissions;
+};

package/src/index.css

@@ -0,0 +1,26 @@
+@import url('https://fonts.googleapis.com/css2?family=Inter:wght@400;500&display=swap');
+@import url('@tldraw/tldraw/tldraw.css');
+
+.tlui-navigation-zone,
+.tlui-navigation-panel {
+  display: none;
+}
+
+.transparent-canvas {
+  --color-background: rgba(0, 0, 0, 0);
+}
+
+.tl-container {
+  --layer-background: 4; /* 100 */
+  --layer-grid: 5; /* 150 */
+  --layer-canvas: 6; /* 200 */
+  --layer-shapes: 7; /* 300 */
+  --layer-overlays: 8; /* 400 */
+  --layer-following-indicator: 12; /* 1000 */
+
+  --layer-panels: 7;
+  --layer-menus: 8;
+  --layer-overlays: 9;
+  --layer-toasts: 10;
+  --layer-cursor: 11;
+}

package/src/index.ts

@@ -0,0 +1,2 @@
+export type { WhiteboardProps } from './Whiteboard';
+export { Whiteboard } from './Whiteboard';

package/src/utils.ts

@@ -0,0 +1,22 @@
+export default function decodeJWT(token?: string) {
+  if (!token || token.length === 0) {
+    throw Error('Token cannot be an empty string or undefined or null');
+  }
+
+  const parts = token.split('.');
+  if (parts.length !== 3) {
+    throw Error(`Expected 3 '.' separate fields - header, payload and signature respectively`);
+  }
+
+  const payloadStr = atob(parts[1]);
+  try {
+    return JSON.parse(payloadStr);
+  } catch (err) {
+    throw Error(`couldn't parse to json - ${(err as Error).message}`);
+  }
+}
+
+export const CURRENT_PAGE_KEY = 'currentPage';
+export const SHAPES_THROTTLE_TIME = 11;
+export const PAGES_DEBOUNCE_TIME = 200;
+export const OPEN_WAIT_TIMEOUT = 1000;