Fix shapes jumping to center after drawing and cursor drift under zoom/pan

CLAUDE.md

@@ -2,6 +2,13 @@
 
 This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
 
+**Top-level rules — these override defaults:**
+
+- **Zero comments** unless explaining a non-obvious *why*. See [Code conventions](#code-conventions).
+- **Simple, readable code over clever code.** Prefer 3 obvious lines over 1 dense line.
+- **Atomic commits** after each logical unit of work. See [Commits](#commits--atomic-always).
+- **Before creating** a new hook, util, or component — grep for an existing one. Follow existing patterns.
+
 ## Project Overview
 
 Thinkix is an AI-native infinite canvas whiteboard built with Next.js 16, React 19, and the Plait board library. The AI agent can read the current board, create new structures, and edit existing elements via a Unix-shell-style command set and a custom DSL. The project uses Bun workspaces for shared code and Liveblocks + Yjs for live collaboration.
@@ -195,8 +202,91 @@ NEXT_PUBLIC_POSTHOG_HOST=...
 
 ## Code conventions
 
-- Self-documenting code; no ceremonial comments. Only comment non-obvious *why*.
+### Comments — default is zero
+
+Write code that does not need comments. Before adding any comment, apply this test: **does it explain WHY something is done this way, in a way the code itself cannot?** If it describes WHAT the code does, delete it and rename variables/functions until the code speaks for itself.
+
+**Never write comments like these:**
+
+```ts
+// Loop through elements and filter selected ones
+const selected = elements.filter(isSelected);
+
+// Set the active tool to pen
+setActiveTool('pen');
+
+// Check if the board exists
+if (!board) return null;
+
+/** Handles the click event */
+function handleClick() { ... }
+
+// Initialize state
+const [count, setCount] = useState(0);
+```
+
+**These are acceptable** (non-obvious why, workaround context, gotcha warnings):
+
+```ts
+// Plait re-orders jsonb keys on write; serialize canonically or prompt
+// caching breaks downstream. See #142.
+const payload = canonicalize(element);
+
+// updatePointerType has no native hook — patched in with-tool-sync.ts
+BoardTransforms.updatePointerType = patchedUpdatePointerType;
+
+// Liveblocks presence uses screen coords; we convert to canvas/world
+// coords here so cursors render correctly across different viewports.
+const worldPos = screenToCanvas(screenPos, viewport);
+```
+
+JSDoc is allowed only on exported package APIs (`packages/*`), never on internal functions whose name and signature already tell the story.
+
+### Simplicity over cleverness
+
+Optimize for the next reader, not for elegance or impressiveness.
+
+**Do:**
+```ts
+const activeUsers = users.filter(user => user.isActive);
+const names = activeUsers.map(user => user.name);
+```
+
+**Don't:**
+```ts
+const names = users.reduce((acc, u) => (u.isActive ? [...acc, u.name] : acc), [] as string[]);
+```
+
+Rules:
+- Prefer a plain `for`/`filter`/`map` chain over a dense one-liner with nested ternaries, `reduce`-to-build-objects, or point-free composition.
+- Prefer 3 obvious lines over 1 dense line. Always.
+- Prefer duplication over the wrong abstraction — do not invent a helper or generic until the third usage.
+- Early returns over nested conditionals: `if (!board) return null` at the top, not an `else` branch at the bottom.
+- No nested ternaries. Extract to a variable or use `if`/`else`.
+- If you feel the urge to add a comment explaining clever logic — that is the signal to rewrite the logic, not add the comment.
+
+### Naming
+
+- Functions: verbs (`createBoard`, `handleClick`, `resolveProvider`).
+- Variables/constants: nouns (`activeUsers`, `boardId`, `GRID_SIZE`).
+- Booleans: adjectives/state (`isActive`, `hasPermission`, `shouldRender`).
+- Names should be specific enough to be grep-able. Avoid single letters except in tight lambda args (`items.map(x => x.id)` is fine; `function f(x, y, z)` is not).
+
+### Commits — atomic, always
+
+Commit after each logical unit of work. Do not batch unrelated changes.
+
+- One logical change per commit. Refactors, behavior changes, and test additions are separate commits even within the same task.
+- If a fix requires a preparatory refactor, commit the refactor first (with no behavior change), then commit the fix.
+- Conventional commit format: `fix(collab): …`, `feat(agent): …`, `refactor(board): …`, `test: …`, `chore: …`.
+- Never mix generated files (`parser.js`) with hand-written changes unless the generation is caused by that change — and say so in the commit body.
+- Commit messages: subject says WHAT changed, body (when needed) says WHY.
+
+### General
+
 - Feature modules expose a small `index.ts` barrel. Follow existing patterns instead of introducing new ones.
+- Before creating a new hook, util, or component, grep the codebase for an existing one that does the same thing.
 - Types flow from `@thinkix/shared` (no JSX) and `shared/constants` (JSX allowed).
-- Prefer early returns (`if (!board) return null`).
-- Keep PRs focused; if you change the DSL grammar, regenerate the parser before opening the PR (see `CONTRIBUTING.md`).
+- `const`-first. Only use `let` when reassignment is genuinely needed.
+- Single-responsibility functions. If a function does two things, split it.
+- Keep PRs focused; if you change the DSL grammar, regenerate the parser before opening the PR (see `CONTRIBUTING.md`).

features/board/components/BoardCanvas.tsx

@@ -93,10 +93,11 @@ function RemoteSyncHandler({
 
   useEffect(() => {
     if (!syncBusContext) return;
-    
+
     const unsubscribe = syncBusContext.syncBus.subscribeToRemoteChanges((elements: BoardElement[]) => {
       const normalized = normalizeElements(elements);
       onElementsChange(normalized);
+      board.children = normalized;
       listRender.update(normalized, {
         board: board,
         parent: board,
@@ -110,7 +111,11 @@ function RemoteSyncHandler({
   return null;
 }
 
-export function BoardCanvas({
+export function BoardCanvas(props: BoardCanvasProps) {
+  return <BoardCanvasInner key={props.boardData?.id ?? 'default'} {...props} />;
+}
+
+function BoardCanvasInner({
   initialValue,
   className,
   children,
@@ -131,25 +136,19 @@ export function BoardCanvas({
     [boardThemeMode],
   );
 
-  const initialElements = useMemo(() => {
-    return syncElementsForBoardTheme(
+  const [value, setValue] = useState<PlaitElement[]>(() =>
+    syncElementsForBoardTheme(
       boardData?.elements ?? resolvedInitialValue,
       getBoardThemeMode(boardData?.theme ?? DEFAULT_THEME),
-    );
-  }, [boardData?.elements, boardData?.theme, resolvedInitialValue]);
-
-  const [value, setValue] = useState<PlaitElement[]>(initialElements);
+    ),
+  );
 
   useEffect(() => {
     if (boardData) {
       setCurrentBoardId(boardData.id);
     }
   }, [boardData, setCurrentBoardId]);
 
-  useEffect(() => {
-    setValue(initialElements);
-  }, [initialElements]);
-
   useAutoSave({
     board: board,
     enabled: !!boardData,
@@ -195,7 +194,6 @@ export function BoardCanvas({
   return (
     <div className={`relative w-full h-full board-wrapper ${className || ''} ${boardCursorClass}`}>
       <Wrapper
-        key={boardData?.id ?? 'default'}
         value={value}
         options={DEFAULT_BOARD_OPTIONS}
         plugins={plugins}

packages/collaboration/src/components/cursor-overlay.tsx

@@ -5,6 +5,7 @@ import type { PlaitBoard } from '@plait/core';
 import type { CursorState } from '../cursor-manager';
 import { getVisibleCursors, getActiveCursors } from '../cursor-manager';
 import { useViewport } from '../hooks/use-viewport';
+import { documentToScreen, getViewportContainerElement } from '../utils';
 
 interface CursorOverlayProps {
   cursors: Map<string, CursorState>;
@@ -123,14 +124,12 @@ export function CursorOverlay({
   const viewport = useViewport(board);
   const [containerRect, setContainerRect] = useState<DOMRect | null>(null);
 
-      useEffect(() => {
+  useEffect(() => {
     const getContainer = (): Element | null => {
       if (containerRef?.current) {
         return containerRef.current;
       }
-      // Fallback to DOM query for backward compatibility
-      const container = document.querySelector('.plait-board-container') as HTMLElement | null;
-      return container?.querySelector('svg') || container;
+      return getViewportContainerElement(board);
     };
 
     const update = () => {
@@ -153,7 +152,7 @@ export function CursorOverlay({
       window.removeEventListener('resize', update);
       observer.disconnect();
     };
-  }, [containerRef]);
+  }, [containerRef, board]);
 
   const renderableCursors = useMemo((): RenderableCursor[] => {
     if (!containerRect) return [];
@@ -172,10 +171,11 @@ export function CursorOverlay({
     visible.forEach((cursor, id) => {
       if (count >= maxCursors) return;
 
+      const { x, y } = documentToScreen(cursor.documentX, cursor.documentY, viewport);
       result.push({
         id,
-        screenX: cursor.documentX * viewport.zoom + viewport.offsetX + containerRect.left,
-        screenY: cursor.documentY * viewport.zoom + viewport.offsetY + containerRect.top,
+        screenX: x + containerRect.left,
+        screenY: y + containerRect.top,
         userName: cursor.userName,
         userColor: cursor.userColor,
         userAvatar: cursor.userAvatar,

packages/collaboration/src/cursor-manager.ts

@@ -1,5 +1,5 @@
 import type { Cursor, CollaborationUser } from './types';
-import type { Viewport } from './utils/viewport';
+import { documentToScreen, screenToDocument, type Viewport } from './utils/viewport';
 
 export interface CursorState {
   userId: string;
@@ -57,9 +57,8 @@ export class CursorManager {
     viewport: Viewport,
     pointerType: 'mouse' | 'pen' | 'touch' = 'mouse'
   ): void {
-    const documentX = (clientX - containerRect.left - viewport.offsetX) / viewport.zoom;
-    const documentY = (clientY - containerRect.top - viewport.offsetY) / viewport.zoom;
-
+    const { x: documentX, y: documentY } = screenToDocument(clientX, clientY, containerRect, viewport);
+
     this.pendingUpdate = { x: documentX, y: documentY };
     this.pendingPointer = pointerType;
 
@@ -150,8 +149,7 @@ export class CursorManager {
   }
 
   getCursorScreenState(cursor: CursorState, viewport: Viewport): CursorState & { screenX: number; screenY: number } {
-    const screenX = cursor.documentX * viewport.zoom + viewport.offsetX;
-    const screenY = cursor.documentY * viewport.zoom + viewport.offsetY;
+    const { x: screenX, y: screenY } = documentToScreen(cursor.documentX, cursor.documentY, viewport);
     return { ...cursor, screenX, screenY };
   }
 
@@ -242,9 +240,8 @@ export function getVisibleCursors(
   const margin = 100;
 
   for (const [id, cursor] of cursors) {
-    const screenX = cursor.documentX * viewport.zoom + viewport.offsetX;
-    const screenY = cursor.documentY * viewport.zoom + viewport.offsetY;
-
+    const { x: screenX, y: screenY } = documentToScreen(cursor.documentX, cursor.documentY, viewport);
+
     if (screenX < -margin || screenX > screenWidth + margin) continue;
     if (screenY < -margin || screenY > screenHeight + margin) continue;
 

packages/collaboration/src/hooks/use-cursor-tracking.ts

@@ -9,7 +9,12 @@ import {
   createCursorManager,
 } from '../cursor-manager';
 import type { Cursor, CollaborationUser } from '../types';
-import { getViewport, type Viewport } from '../utils';
+import {
+  getViewport,
+  getViewportContainerElement,
+  documentToScreen,
+  type Viewport,
+} from '../utils';
 
 export interface UseCursorTrackingOptions {
   board: PlaitBoard | null;
@@ -72,11 +77,13 @@ export function useCursorTracking({
     const handlePointerMove = (e: PointerEvent) => {
       const target = e.target;
       if (!(target instanceof Element)) return;
-
-      const svg = target.closest('svg');
-      if (!svg || !boardRef.current) return;
 
-      const rect = svg.getBoundingClientRect();
+      if (!target.closest('.plait-board-container') || !boardRef.current) return;
+
+      const container = getViewportContainerElement(boardRef.current);
+      if (!container) return;
+
+      const rect = container.getBoundingClientRect();
       const viewport = getViewport(boardRef.current);
 
       if (rafId) {
@@ -156,9 +163,6 @@ export function useCursorScreenState(
   cursor: CursorState,
   viewport: Viewport
 ): CursorState & { screenX: number; screenY: number } {
-  return {
-    ...cursor,
-    screenX: cursor.documentX * viewport.zoom + viewport.offsetX,
-    screenY: cursor.documentY * viewport.zoom + viewport.offsetY,
-  };
+  const { x: screenX, y: screenY } = documentToScreen(cursor.documentX, cursor.documentY, viewport);
+  return { ...cursor, screenX, screenY };
 }

packages/collaboration/src/hooks/use-sync.ts

@@ -4,6 +4,7 @@ import { useEffect, useRef, useCallback } from 'react';
 import { useStorage, useMutation, useSelf } from '@liveblocks/react/suspense';
 import type { PlaitElement, PlaitBoard } from '@plait/core';
 import { usePresence } from '../providers/liveblocks/hooks';
+import { getViewport, getViewportContainerElement, screenToDocument } from '../utils';
 
 interface UseBoardSyncOptions {
   board: PlaitBoard | null;
@@ -70,12 +71,17 @@ export function useBoardCursorTracking(board: PlaitBoard | null, enabled: boolea
     const handlePointerMove = (e: Event) => {
       const pointerEvent = e as PointerEvent;
       const target = pointerEvent.target as SVGElement | HTMLElement;
-      const svg = target.closest('svg');
-      if (!svg) return;
+      if (!target.closest('.plait-board-container')) return;
 
-      const rect = svg.getBoundingClientRect();
-      const x = (pointerEvent.clientX - rect.left - board.viewport.offsetX) / board.viewport.zoom;
-      const y = (pointerEvent.clientY - rect.top - board.viewport.offsetY) / board.viewport.zoom;
+      const container = getViewportContainerElement(board);
+      if (!container) return;
+
+      const { x, y } = screenToDocument(
+        pointerEvent.clientX,
+        pointerEvent.clientY,
+        container.getBoundingClientRect(),
+        getViewport(board)
+      );
 
       updateCursor({ x, y, pointer: pointerEvent.pointerType as 'mouse' | 'pen' | 'touch' });
     };

packages/collaboration/src/hooks/use-viewport.ts

@@ -4,10 +4,14 @@ import { useEffect, useState, useRef } from 'react';
 import type { PlaitBoard } from '@plait/core';
 import { getViewport, type Viewport } from '../utils';
 
-const DEFAULT_VIEWPORT: Viewport = { zoom: 1, offsetX: 0, offsetY: 0 };
+const DEFAULT_VIEWPORT: Viewport = { zoom: 1, originationX: 0, originationY: 0 };
 
 function viewportsEqual(a: Viewport, b: Viewport): boolean {
-  return a.zoom === b.zoom && a.offsetX === b.offsetX && a.offsetY === b.offsetY;
+  return (
+    a.zoom === b.zoom &&
+    a.originationX === b.originationX &&
+    a.originationY === b.originationY
+  );
 }
 
 export function useViewport(board: PlaitBoard | null): Viewport {

packages/collaboration/src/utils/index.ts

@@ -1,2 +1,8 @@
-export { getViewport, screenToDocument, documentToScreen, type Viewport } from './viewport';
+export {
+  getViewport,
+  screenToDocument,
+  documentToScreen,
+  getViewportContainerElement,
+  type Viewport,
+} from './viewport';
 export { debounce, throttle } from './timing';