feat(canvas): add frontend structural document replica and op queue

docs/backend/contracts/websocket-events.md

@@ -9,6 +9,7 @@ Transport model:
 - Client sends JSON messages with a `type` discriminator.
 - Ephemeral events are relayed directly in-memory.
 - Durable structural events are committed through `canvas-service` first, then broadcast with committed metadata.
+- The sender also receives the committed structural event back as the client-side ack path for optimistic queue reconciliation.
 - `crdt_op` and `sync_request` are special-cased for replay/sync.
 
 ## Join Flow

frontend/package.json

@@ -22,7 +22,8 @@
     "codemirror": "^6.0.2",
     "react": "^19.2.4",
     "react-dom": "^19.2.4",
-    "react-router-dom": "^7.13.2"
+    "react-router-dom": "^7.13.2",
+    "zustand": "^5.0.12"
   },
   "devDependencies": {
     "@babel/core": "^7.29.0",

frontend/src/canvas/Canvas.tsx

@@ -18,6 +18,8 @@ import { useCanvasShortcutContainer } from "./shortcuts/useCanvasShortcutContain
 import type { NodeDragVisual } from "./dragVisuals";
 import { useCanvasDocument } from "./model/useCanvasDocument";
 import { createCursorPresenceStore } from "./presence/cursorPresenceStore";
+import { createCanvasDocumentStore } from "./document/canvasDocumentStore";
+import { createCanvasOperationQueueStore } from "./ops/canvasOperationQueueStore";
 
 interface CanvasProps {
   canvasId: string;
@@ -41,6 +43,10 @@ export function Canvas({ canvasId, userId, displayName }: CanvasProps) {
   const viewportRef = useRef<HTMLDivElement>(null);
   const sendRef = useRef<((event: CanvasOutboundEvent) => void) | null>(null);
   const cursorStore = useMemo(() => createCursorPresenceStore(), []);
+  // eslint-disable-next-line react-hooks/exhaustive-deps
+  const documentStore = useMemo(() => createCanvasDocumentStore(), [canvasId]);
+  // eslint-disable-next-line react-hooks/exhaustive-deps
+  const operationQueueStore = useMemo(() => createCanvasOperationQueueStore(), [canvasId]);
   const [remoteSelections, setRemoteSelections] = useState<
     Map<string, Set<string>>
   >(new Map());
@@ -76,6 +82,8 @@ export function Canvas({ canvasId, userId, displayName }: CanvasProps) {
     viewportRef,
     transformRef,
     sendRef,
+    documentStore,
+    operationQueueStore,
   });
 
   const [tool, setTool] = useState<CanvasTool>("select");
@@ -85,15 +93,8 @@ export function Canvas({ canvasId, userId, displayName }: CanvasProps) {
 
   const collabHandlers = useMemo(
     () => ({
-      onNodeCreate: remote.applyNodeCreate,
-      onNodeMove: (
-        remoteUserId: string,
-        nodeId: string,
-        x: number,
-        y: number,
-      ) => {
+      onNodeMove: (remoteUserId: string, nodeId: string, x: number, y: number) => {
         const previousNode = getNodeById(nodeId);
-        remote.applyNodeMove(remoteUserId, nodeId, x, y);
         if (!previousNode) return;
 
         setRemoteDragStates((prev) => {
@@ -130,10 +131,6 @@ export function Canvas({ canvasId, userId, displayName }: CanvasProps) {
           return next;
         });
       },
-      onNodeUpdate: remote.applyNodeUpdate,
-      onNodeDelete: remote.applyNodeDelete,
-      onEdgeCreate: remote.applyEdgeCreate,
-      onEdgeDelete: remote.applyEdgeDelete,
       onNodeSelect: (remoteUserId: string, nodeIds: string[]) => {
         setRemoteSelections((prev) => {
           const next = new Map(prev);
@@ -168,15 +165,17 @@ export function Canvas({ canvasId, userId, displayName }: CanvasProps) {
     remoteStrokes,
     send,
     onPointerMove: collabPointerMove,
-  } = useCanvasCollab(
+  } = useCanvasCollab({
     canvasId,
     userId,
     displayName,
     viewportRef,
     transformRef,
     cursorStore,
-    collabHandlers,
-  );
+    documentStore,
+    operationQueueStore,
+    handlers: collabHandlers,
+  });
 
   useEffect(() => {
     sendRef.current = send;

frontend/src/canvas/CursorOverlay.tsx

@@ -5,7 +5,7 @@ import resizeNwseCursorImage from "../assets/Cursor/Resize/North West South East
 import grabCursorImage from "../assets/Cursor/Grab/Grab.png";
 import grabbingCursorImage from "../assets/Cursor/Grab/Grabbing.png";
 import {
-  useRemoteCursors,
+  useInterpolatedRemoteCursors,
   type CursorPresenceStore,
 } from "./presence/cursorPresenceStore";
 import type { CollabUser } from "./presence/types";
@@ -60,8 +60,12 @@ function CursorGlyph({
     <div
       className={`pointer-events-none absolute flex items-start ${zClassName}`}
       style={{
-        left: x - CURSOR_TIP_OFFSET_X,
-        top: y - CURSOR_TIP_OFFSET_Y,
+        left: 0,
+        top: 0,
+        transform: `translate3d(${x - CURSOR_TIP_OFFSET_X}px, ${
+          y - CURSOR_TIP_OFFSET_Y
+        }px, 0)`,
+        willChange: "transform",
       }}
     >
       <svg
@@ -100,7 +104,7 @@ export function CursorOverlay({
   localCursorMode,
 }: Props) {
   const [localCursor, setLocalCursor] = useState<LocalCursor | null>(null);
-  const cursors = useRemoteCursors(cursorStore);
+  const cursors = useInterpolatedRemoteCursors(cursorStore);
 
   useEffect(() => {
     const viewport = viewportRef.current;
@@ -169,8 +173,12 @@ export function CursorOverlay({
             aria-hidden="true"
             draggable={false}
             style={{
-              left: localCursor.x - CURSOR_TIP_OFFSET_X,
-              top: localCursor.y - CURSOR_TIP_OFFSET_Y,
+              left: 0,
+              top: 0,
+              transform: `translate3d(${localCursor.x - CURSOR_TIP_OFFSET_X}px, ${
+                localCursor.y - CURSOR_TIP_OFFSET_Y
+              }px, 0)`,
+              willChange: "transform",
             }}
           />
         ))}