Enhance canvas sync functionality in Tldraw components

- Refactored Tldraw components to incorporate a per-canvas sync mode, allowing users to toggle between 'sync' and 'local' modes.
- Updated the main menu to include a checkbox for sync mode, with visual feedback for availability.
- Integrated new utilities for managing sync mode state and ensured proper propagation of sync settings across components.
- Improved user experience with tooltips and notifications related to sync mode changes.

Author: mdroidian

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

@@ -73,7 +73,7 @@ import {
   createNodeShapeTools,
   createNodeShapeUtils,
 } from "./DiscourseNodeUtil";
-import { hasRoamPersistedCanvasData, useRoamStore } from "./useRoamStore";
+import { useRoamStore } from "./useRoamStore";
 import {
   TLDRAW_CLOUDFLARE_SYNC_ENABLED,
   TLDRAW_CLOUDFLARE_SYNC_WS_BASE_URL,
@@ -115,6 +115,12 @@ import { TLRecord } from "@tldraw/tlschema";
 import { WHITE_LOGO_SVG } from "~/icons";
 import { BLOCK_REF_REGEX } from "roamjs-components/dom";
 import { defaultHandleExternalTextContent } from "./defaultHandleExternalTextContent";
+import {
+  CanvasSyncMode,
+  ensureCanvasSyncMode,
+  getEffectiveCanvasSyncMode,
+  setCanvasSyncMode,
+} from "./canvasSyncMode";
 
 declare global {
   // eslint-disable-next-line @typescript-eslint/consistent-type-definitions
@@ -153,16 +159,48 @@ const TldrawCanvas = ({ title }: { title: string }) => {
   // In Roam, canvas identity is currently keyed by the page UID.
   // Room sync is graph/page encoded as an opaque base64url token.
   const pageUid = useMemo(() => getPageUidByPageTitle(title), [title]);
-  const useCloudflareSync =
+  const [canvasSyncMode, setCanvasSyncModeState] = useState<CanvasSyncMode>(
+    () => getEffectiveCanvasSyncMode({ pageUid }),
+  );
+  const isCloudflareSyncAvailable =
     TLDRAW_CLOUDFLARE_SYNC_ENABLED &&
-    !!TLDRAW_CLOUDFLARE_SYNC_WS_BASE_URL &&
-    !hasRoamPersistedCanvasData(pageUid);
+    !!TLDRAW_CLOUDFLARE_SYNC_WS_BASE_URL;
+  const useCloudflareSync =
+    canvasSyncMode === "sync" && isCloudflareSyncAvailable;
+
+  useEffect(() => {
+    setCanvasSyncModeState(ensureCanvasSyncMode({ pageUid }));
+  }, [pageUid]);
+
+  const onCanvasSyncModeChange = useCallback(
+    (mode: CanvasSyncMode) => {
+      setCanvasSyncMode({ pageUid, mode });
+      setCanvasSyncModeState(mode);
+    },
+    [pageUid],
+  );
 
   if (useCloudflareSync) {
-    return <TldrawCanvasCloudflare title={title} pageUid={pageUid} />;
+    return (
+      <TldrawCanvasCloudflare
+        title={title}
+        pageUid={pageUid}
+        canvasSyncMode={canvasSyncMode}
+        isCloudflareSyncAvailable={isCloudflareSyncAvailable}
+        onCanvasSyncModeChange={onCanvasSyncModeChange}
+      />
+    );
   }
 
-  return <TldrawCanvasRoam title={title} pageUid={pageUid} />;
+  return (
+    <TldrawCanvasRoam
+      title={title}
+      pageUid={pageUid}
+      canvasSyncMode={canvasSyncMode}
+      isCloudflareSyncAvailable={isCloudflareSyncAvailable}
+      onCanvasSyncModeChange={onCanvasSyncModeChange}
+    />
+  );
 };
 
 type CanvasStoreAdapterArgs = {
@@ -232,33 +270,51 @@ const useCloudflareCanvasStore = ({
 const TldrawCanvasRoam = ({
   title,
   pageUid,
+  canvasSyncMode,
+  isCloudflareSyncAvailable,
+  onCanvasSyncModeChange,
 }: {
   title: string;
   pageUid: string;
+  canvasSyncMode: CanvasSyncMode;
+  isCloudflareSyncAvailable: boolean;
+  onCanvasSyncModeChange: (mode: CanvasSyncMode) => void;
 }) => {
   return (
     <TldrawCanvasShared
       title={title}
       pageUid={pageUid}
       useStoreAdapter={useRoamCanvasStore}
       isCloudflareSync={false}
+      canvasSyncMode={canvasSyncMode}
+      isCloudflareSyncAvailable={isCloudflareSyncAvailable}
+      onCanvasSyncModeChange={onCanvasSyncModeChange}
     />
   );
 };
 
 const TldrawCanvasCloudflare = ({
   title,
   pageUid,
+  canvasSyncMode,
+  isCloudflareSyncAvailable,
+  onCanvasSyncModeChange,
 }: {
   title: string;
   pageUid: string;
+  canvasSyncMode: CanvasSyncMode;
+  isCloudflareSyncAvailable: boolean;
+  onCanvasSyncModeChange: (mode: CanvasSyncMode) => void;
 }) => {
   return (
     <TldrawCanvasShared
       title={title}
       pageUid={pageUid}
       useStoreAdapter={useCloudflareCanvasStore}
       isCloudflareSync={true}
+      canvasSyncMode={canvasSyncMode}
+      isCloudflareSyncAvailable={isCloudflareSyncAvailable}
+      onCanvasSyncModeChange={onCanvasSyncModeChange}
     />
   );
 };
@@ -268,11 +324,17 @@ const TldrawCanvasShared = ({
   pageUid,
   useStoreAdapter,
   isCloudflareSync,
+  canvasSyncMode,
+  isCloudflareSyncAvailable,
+  onCanvasSyncModeChange,
 }: {
   title: string;
   pageUid: string;
   useStoreAdapter: (args: CanvasStoreAdapterArgs) => CanvasStoreAdapterResult;
   isCloudflareSync: boolean;
+  canvasSyncMode: CanvasSyncMode;
+  isCloudflareSyncAvailable: boolean;
+  onCanvasSyncModeChange: (mode: CanvasSyncMode) => void;
 }) => {
   const appRef = useRef<Editor | null>(null);
   const lastInsertRef = useRef<VecModel>();
@@ -591,8 +653,18 @@ const TldrawCanvasShared = ({
         allNodes,
         allRelationNames,
         allAddReferencedNodeActions,
+        canvasSyncMode,
+        isCloudflareSyncAvailable,
+        onCanvasSyncModeChange,
       }),
-    [allNodes, allRelationNames, allAddReferencedNodeActions],
+    [
+      allNodes,
+      allRelationNames,
+      allAddReferencedNodeActions,
+      canvasSyncMode,
+      isCloudflareSyncAvailable,
+      onCanvasSyncModeChange,
+    ],
   );
 
   // UTILS
@@ -859,12 +931,14 @@ const TldrawCanvasShared = ({
       onDrop={handleDrop}
     >
       {isCloudflareSync && (
-        <div
-          className="pointer-events-none absolute right-3 top-3 z-20 opacity-90"
-          title="Cloudflare Sync enabled"
+        <Tooltip
+          content="Sync mode is enabled. Collaborators on older builds may still open this canvas in local mode."
+          hoverOpenDelay={100}
         >
-          <Icon icon="cloud" size={12} className="text-green-500" />
-        </div>
+          <div className="absolute right-3 top-3 z-20 opacity-90">
+            <Icon icon="cloud" size={12} className="text-green-500" />
+          </div>
+        </Tooltip>
       )}
       <style>{tldrawStyles}</style>
 

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

@@ -14,6 +14,7 @@ import {
   DefaultKeyboardShortcutsDialogContent,
   DefaultToolbarContent,
   TldrawUiMenuItem,
+  TldrawUiMenuCheckboxItem,
   DefaultMainMenu,
   TldrawUiMenuGroup,
   useActions,
@@ -46,6 +47,8 @@ import { DISCOURSE_TOOL_SHORTCUT_KEY } from "~/data/userSettings";
 import { getSetting } from "~/utils/extensionSettings";
 import { CustomDefaultToolbar } from "./CustomDefaultToolbar";
 import { renderModifyNodeDialog } from "~/components/ModifyNodeDialog";
+import { CanvasSyncMode } from "./canvasSyncMode";
+import renderToast from "roamjs-components/components/Toast";
 
 export const getOnSelectForShape = ({
   shape,
@@ -185,10 +188,16 @@ export const createUiComponents = ({
   allNodes,
   allAddReferencedNodeActions,
   allRelationNames,
+  canvasSyncMode,
+  isCloudflareSyncAvailable,
+  onCanvasSyncModeChange,
 }: {
   allNodes: DiscourseNode[];
   allRelationNames: string[];
   allAddReferencedNodeActions: string[];
+  canvasSyncMode: CanvasSyncMode;
+  isCloudflareSyncAvailable: boolean;
+  onCanvasSyncModeChange: (mode: CanvasSyncMode) => void;
 }): TLUiComponents => {
   return {
     Toolbar: (props) => {
@@ -234,11 +243,36 @@ export const createUiComponents = ({
           </TldrawUiMenuSubmenu>
         );
       };
+      const onToggleSyncMode = (): void => {
+        const nextMode: CanvasSyncMode =
+          canvasSyncMode === "sync" ? "local" : "sync";
+        onCanvasSyncModeChange(nextMode);
+        if (nextMode === "sync") {
+          renderToast({
+            id: "tldraw-sync-mode-enabled-v0",
+            intent: "warning",
+            content: "Sync mode starts from a new blank sync canvas.",
+          });
+        }
+      };
+      const syncModeLabel = isCloudflareSyncAvailable
+        ? "Sync mode"
+        : "Sync mode (backend unavailable)";
 
       return (
         <DefaultMainMenu>
           <EditSubmenu />
           <CustomViewMenu /> {/* Replaced <ViewSubmenu /> */}
+          <TldrawUiMenuGroup id="sync-mode">
+            <TldrawUiMenuCheckboxItem
+              id="toggle-sync-mode"
+              label={syncModeLabel}
+              checked={canvasSyncMode === "sync"}
+              readonlyOk
+              disabled={!isCloudflareSyncAvailable}
+              onSelect={onToggleSyncMode}
+            />
+          </TldrawUiMenuGroup>
           <ExportFileContentSubMenu />
           <ExtrasGroup />
           <PreferencesGroup />

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

@@ -38,17 +38,6 @@ export const isTLStoreSnapshot = (value: unknown): value is TLStoreSnapshot => {
   );
 };
 
-/** True if the canvas has existing tldraw state persisted in Roam (any format). */
-export const hasRoamPersistedCanvasData = (pageUid: string): boolean => {
-  const props = getBlockProps(pageUid) as Record<string, unknown>;
-  const rjsqb =
-    typeof props?.["roamjs-query-builder"] === "object"
-      ? (props["roamjs-query-builder"] as Record<string, unknown>)
-      : {};
-  const tldraw = rjsqb?.tldraw;
-  return tldraw !== undefined && tldraw !== null;
-};
-
 const fixShapeIndices = (
   data: SerializedStore<TLRecord>,
 ): SerializedStore<TLRecord> => {