ENG-1403 create migration from local to real-time (#893)

* Enhance canvas synchronization features and migration handling

- Introduced new types and functions for managing canvas sync modes and migration states.
- Implemented migration of local canvas data to cloud sync, including user prompts for confirmation.
- Updated UI components to support cloud sync settings and actions.
- Refactored existing functions to improve clarity and maintainability, ensuring seamless integration with the new sync features.

* move posthog to onConfirm

* Implement canvas synchronization on block prop changes

Author: mdroidian

apps/roam/src/components/canvas/Tldraw.tsx

@@ -10,7 +10,7 @@ import { Icon } from "@blueprintjs/core";
 import ExtensionApiContextProvider, {
   useExtensionAPI,
 } from "roamjs-components/components/ExtensionApiContext";
-import { OnloadArgs } from "roamjs-components/types";
+import { OnloadArgs, PullBlock } from "roamjs-components/types";
 import renderWithUnmount from "roamjs-components/util/renderWithUnmount";
 
 import {
@@ -104,15 +104,19 @@ import { BLOCK_REF_REGEX } from "roamjs-components/dom";
 import { defaultHandleExternalTextContent } from "./defaultHandleExternalTextContent";
 import {
   CanvasSyncMode,
+  getCanvasSyncMigrationState,
+  getReadyCanvasStore,
   ensureCanvasSyncMode,
   getEffectiveCanvasSyncMode,
-  setCanvasSyncMode,
+  migrateLocalCanvasToCloud,
+  setCanvasSyncSettings,
 } from "./canvasSyncMode";
 import {
   CanvasStoreAdapterArgs,
   useCanvasStoreAdapterArgs,
 } from "./useCanvasStoreAdapterArgs";
 import posthog from "posthog-js";
+import { json, normalizeProps } from "~/utils/getBlockProps";
 
 declare global {
   // eslint-disable-next-line @typescript-eslint/consistent-type-definitions
@@ -171,9 +175,44 @@ const TldrawCanvas = ({ title }: { title: string }) => {
     setCanvasSyncModeState(ensureCanvasSyncMode({ pageUid }));
   }, [pageUid]);
 
+  // Convert from local to sync when the block props change
+  // EG: When UserA sets the canvas sync mode to sync
+  // UserB's canvas should be converted to sync
+  useEffect(() => {
+    if (!pageUid || canvasSyncMode !== "local") return;
+
+    const pullWatchProps = [
+      "[:block/props]",
+      `[:block/uid "${pageUid}"]`,
+      (_before: PullBlock | null, after: PullBlock | null) => {
+        const blockProps = normalizeProps(
+          (after?.[":block/props"] || {}) as json,
+        ) as Record<string, json>;
+        const rjsqb = blockProps?.["roamjs-query-builder"] as Record<
+          string,
+          unknown
+        >;
+        if (rjsqb?.canvasSyncMode !== "sync") return;
+        setCanvasSyncModeState("sync");
+      },
+    ] as const;
+
+    window.roamAlphaAPI.data.addPullWatch(...pullWatchProps);
+    return () => {
+      window.roamAlphaAPI.data.removePullWatch(...pullWatchProps);
+    };
+  }, [canvasSyncMode, pageUid]);
+
   const onCanvasSyncModeChange = useCallback(
     (mode: CanvasSyncMode) => {
-      setCanvasSyncMode({ pageUid, mode });
+      const currentMigrationState = getCanvasSyncMigrationState({ pageUid });
+      const nextMigrationState =
+        mode === "sync" && !currentMigrationState ? "pending" : undefined;
+      setCanvasSyncSettings({
+        pageUid,
+        mode,
+        migrationState: nextMigrationState,
+      });
       setCanvasSyncModeState(mode);
     },
     [pageUid],
@@ -254,6 +293,7 @@ const useCloudflareCanvasStore = ({
     performUpgrade: () => {},
   };
 };
+
 const TldrawCanvasRoam = ({
   title,
   pageUid,
@@ -632,7 +672,6 @@ const TldrawCanvasShared = ({
     allRelationNames,
     allAddReferencedNodeActions,
     canvasSyncMode,
-    onCanvasSyncModeChange,
   });
 
   const storeAdapterArgs = useCanvasStoreAdapterArgs({
@@ -643,6 +682,7 @@ const TldrawCanvasShared = ({
     allAddReferencedNodeByAction,
   });
   const {
+    migrations,
     customShapeUtils,
     customBindingUtils,
     customShapeTypes,
@@ -671,6 +711,8 @@ const TldrawCanvasShared = ({
     allNodes,
     allRelationNames,
     allAddReferencedNodeByAction,
+    canvasSyncMode,
+    onCanvasSyncModeChange,
     toggleMaximized: handleMaximizedChange,
     setConvertToDialogOpen,
     discourseContext,
@@ -685,6 +727,55 @@ const TldrawCanvasShared = ({
   }, [pageUid]);
   const { store, needsUpgrade, performUpgrade, error, isLoading } =
     useStoreAdapter(storeAdapterArgs);
+  const migratedCloudStoreRef = useRef<string | null>(null);
+
+  // Migrate local canvas to cloud sync
+  useEffect(() => {
+    if (!isCloudflareSync || canvasSyncMode !== "sync") return;
+    if (getCanvasSyncMigrationState({ pageUid }) !== "pending") return;
+
+    const readyStore = getReadyCanvasStore(store);
+    if (!readyStore) return;
+
+    const storeId = `${pageUid}:${readyStore.id}`;
+    if (migratedCloudStoreRef.current === storeId) return;
+    migratedCloudStoreRef.current = storeId;
+
+    try {
+      const { migrated } = migrateLocalCanvasToCloud({
+        pageUid,
+        store: readyStore,
+        migrations,
+        customShapeUtils,
+        customBindingUtils,
+      });
+      if (migrated)
+        renderToast({
+          id: "tldraw-cloud-migration",
+          intent: "success",
+          content: "Migrated local canvas to cloud sync.",
+        });
+    } catch (migrationError) {
+      migratedCloudStoreRef.current = null;
+      internalError({
+        error: migrationError,
+        type: "Canvas: Local to cloud migration failed",
+        context: {
+          pageUid,
+          title,
+        },
+      });
+    }
+  }, [
+    canvasSyncMode,
+    customBindingUtils,
+    customShapeUtils,
+    isCloudflareSync,
+    migrations,
+    pageUid,
+    store,
+    title,
+  ]);
 
   // ASSETS
   const assetLoading = usePreloadAssets(defaultEditorAssetUrls);

apps/roam/src/components/canvas/canvasSyncMode.ts

@@ -1,15 +1,30 @@
 import getBlockProps, { json } from "~/utils/getBlockProps";
 import setBlockProps from "~/utils/setBlockProps";
+import {
+  TLAnyBindingUtilConstructor,
+  TLAnyShapeUtilConstructor,
+  TLStore,
+  TLStoreWithStatus,
+  MigrationSequence,
+  loadSnapshot,
+} from "tldraw";
+import { getRoamCanvasSnapshot } from "./useRoamStore";
 
 export type CanvasSyncMode = "local" | "sync";
+export type CanvasSyncMigrationState = "pending" | "done";
 
 const QUERY_BUILDER_PROP_KEY = "roamjs-query-builder";
 const CANVAS_SYNC_MODE_KEY = "canvasSyncMode";
+const CANVAS_SYNC_MIGRATION_STATE_KEY = "canvasSyncMigrationState";
 const DEFAULT_CANVAS_SYNC_MODE: CanvasSyncMode = "local";
 
 const isCanvasSyncMode = (value: unknown): value is CanvasSyncMode =>
   value === "local" || value === "sync";
 
+const isCanvasSyncMigrationState = (
+  value: unknown,
+): value is CanvasSyncMigrationState => value === "pending" || value === "done";
+
 const getRoamJsQueryBuilderProps = (pageUid: string): Record<string, json> => {
   const props = getBlockProps(pageUid);
   const value = props[QUERY_BUILDER_PROP_KEY];
@@ -19,6 +34,40 @@ const getRoamJsQueryBuilderProps = (pageUid: string): Record<string, json> => {
   return {};
 };
 
+const setRoamJsQueryBuilderProps = ({
+  pageUid,
+  nextRjsqb,
+}: {
+  pageUid: string;
+  nextRjsqb: Record<string, json>;
+}): void => {
+  setBlockProps(pageUid, {
+    [QUERY_BUILDER_PROP_KEY]: nextRjsqb,
+  });
+};
+
+const updateCanvasSyncProps = ({
+  pageUid,
+  updates,
+}: {
+  pageUid: string;
+  updates: Partial<
+    Record<
+      typeof CANVAS_SYNC_MODE_KEY | typeof CANVAS_SYNC_MIGRATION_STATE_KEY,
+      json
+    >
+  >;
+}): void => {
+  const rjsqb = getRoamJsQueryBuilderProps(pageUid);
+  setRoamJsQueryBuilderProps({
+    pageUid,
+    nextRjsqb: {
+      ...rjsqb,
+      ...updates,
+    },
+  });
+};
+
 export const getPersistedCanvasSyncMode = ({
   pageUid,
 }: {
@@ -44,11 +93,55 @@ export const setCanvasSyncMode = ({
   pageUid: string;
   mode: CanvasSyncMode;
 }): void => {
+  updateCanvasSyncProps({
+    pageUid,
+    updates: {
+      [CANVAS_SYNC_MODE_KEY]: mode,
+    },
+  });
+};
+
+export const getCanvasSyncMigrationState = ({
+  pageUid,
+}: {
+  pageUid: string;
+}): CanvasSyncMigrationState | null => {
   const rjsqb = getRoamJsQueryBuilderProps(pageUid);
-  setBlockProps(pageUid, {
-    [QUERY_BUILDER_PROP_KEY]: {
-      ...rjsqb,
+  const migrationState = rjsqb[CANVAS_SYNC_MIGRATION_STATE_KEY];
+  return isCanvasSyncMigrationState(migrationState) ? migrationState : null;
+};
+
+export const setCanvasSyncMigrationState = ({
+  pageUid,
+  state,
+}: {
+  pageUid: string;
+  state: CanvasSyncMigrationState;
+}): void => {
+  updateCanvasSyncProps({
+    pageUid,
+    updates: {
+      [CANVAS_SYNC_MIGRATION_STATE_KEY]: state,
+    },
+  });
+};
+
+export const setCanvasSyncSettings = ({
+  pageUid,
+  mode,
+  migrationState,
+}: {
+  pageUid: string;
+  mode: CanvasSyncMode;
+  migrationState?: CanvasSyncMigrationState;
+}): void => {
+  updateCanvasSyncProps({
+    pageUid,
+    updates: {
       [CANVAS_SYNC_MODE_KEY]: mode,
+      ...(migrationState
+        ? { [CANVAS_SYNC_MIGRATION_STATE_KEY]: migrationState }
+        : {}),
     },
   });
 };
@@ -63,3 +156,78 @@ export const ensureCanvasSyncMode = ({
   setCanvasSyncMode({ pageUid, mode: DEFAULT_CANVAS_SYNC_MODE });
   return DEFAULT_CANVAS_SYNC_MODE;
 };
+
+export const getReadyCanvasStore = (
+  store: TLStore | TLStoreWithStatus | null,
+): TLStore | null => {
+  if (!store) return null;
+  if ("status" in store) {
+    return store.status === "synced-remote" ? store.store : null;
+  }
+  return store;
+};
+
+const getShapeRecordCount = (store: TLStore): number => {
+  return Object.values(store.serialize()).filter(
+    (record) => record.typeName === "shape",
+  ).length;
+};
+
+export const migrateLocalCanvasToCloud = ({
+  pageUid,
+  store,
+  migrations,
+  customShapeUtils,
+  customBindingUtils,
+}: {
+  pageUid: string;
+  store: TLStore;
+  migrations: MigrationSequence[];
+  customShapeUtils: readonly TLAnyShapeUtilConstructor[];
+  customBindingUtils: readonly TLAnyBindingUtilConstructor[];
+}): { migrated: boolean; migrationState: CanvasSyncMigrationState } => {
+  if (getShapeRecordCount(store) > 0) {
+    setCanvasSyncSettings({
+      pageUid,
+      mode: "sync",
+      migrationState: "done",
+    });
+    return {
+      migrated: false,
+      migrationState: "done",
+    };
+  }
+
+  const localSnapshot = getRoamCanvasSnapshot({
+    pageUid,
+    migrations,
+    customShapeUtils,
+    customBindingUtils,
+    includePersonalRecords: false,
+  });
+
+  if (!localSnapshot) {
+    setCanvasSyncSettings({
+      pageUid,
+      mode: "sync",
+      migrationState: "done",
+    });
+    return {
+      migrated: false,
+      migrationState: "done",
+    };
+  }
+
+  loadSnapshot(store, localSnapshot);
+
+  setCanvasSyncSettings({
+    pageUid,
+    mode: "sync",
+    migrationState: "done",
+  });
+
+  return {
+    migrated: true,
+    migrationState: "done",
+  };
+};