nudge-ui 0.2.2 → 0.2.4

package/dist/inspector/canvas/sessionStore.js

@@ -1,19 +1,20 @@
-import { getWorkspaceChanges } from "../changes/workspaceChanges.js";
-import { loadWorkspaceChanges } from "../changes/changesLog.js";
-import { deserializeChange, isSerializableChange, serializeChange, } from "../changes/codecs.js";
-import { getCanvasMode, getCanvasCards, getCanvasComparisonGroups, getFocusedCardId, getBoardCamera, setBoardCamera, hydrateCanvasStore, removeCanvasCard, } from "./canvasStore.js";
+import { isFrameContent } from "./frameContent.js";
+import { clearComments } from "../comments/store.js";
+import { documentTarget, targetFromKey } from "../drafts/model.js";
+import { canEditDraft, getActiveDraftChanges, isDraftLocked } from "../changes/draftChanges.js";
+import { getFrameGroups, isFrameGroup, getCanvasCards, getFocusedCardId, getSelectedCardId, hydrateCanvasStore, removeCanvasCard, } from "./canvasStore.js";
+import { getCanvasMode, getCanvasPresentation, getBoardCamera, setBoardCamera, } from "./viewStore.js";
 import { applyRules } from "../projection/managedStylesheet.js";
-import { clearWorkspace as clearWorkspaceLog } from "../changes/changesLog.js";
+import { clearActiveDraft } from "../changes/changesLog.js";
 import { removeManagedSheet } from "../projection/managedStylesheet.js";
 import { setSelectedElement } from "../selection/selectionStore.js";
 import { canWriteWorkspace } from "./workspaceLease.js";
-import { isStructuralChange, resetStructuralDeleteProjection, } from "../projection/structuralProjection.js";
+import { resetStructuralDeleteProjection, } from "../projection/structuralProjection.js";
 import { projectToAllReadyCards } from "./projection.js";
 import { getNudgeUiRuntimeConfig } from "../runtime/runtimeConfig.js";
 import { clearClipboardHandoff, getClipboardHandoffSnapshot, hydrateClipboardHandoff, isClipboardHandoffSnapshot, } from "../prompt/clipboardHandoff.js";
-// v12 is the first durable-session schema after the edit model and preview
-// diagnostic split. Previous session shapes are intentionally incompatible.
-const SCHEMA_VERSION = 12;
+import { activateDraftForCard, clearDrafts, persistDrafts } from "../drafts/store.js";
+const SCHEMA_VERSION = 17;
 const STORAGE_PREFIX = "nudge-ui";
 function projectId() {
     return getNudgeUiRuntimeConfig().projectId;
@@ -21,9 +22,6 @@ function projectId() {
 function isFiniteNumber(value) {
     return typeof value === "number" && Number.isFinite(value);
 }
-function isRecord(value) {
-    return value !== null && typeof value === "object" && !Array.isArray(value);
-}
 function isSameOriginUrl(value) {
     if (typeof value !== "string")
         return false;
@@ -34,95 +32,32 @@ function isSameOriginUrl(value) {
         return false;
     }
 }
-function hasOnlyKeys(value, allowed) {
-    return Object.keys(value).every((key) => allowed.includes(key));
-}
-function isSerializableComparisonGroup(value) {
-    if (!isRecord(value)
-        || !hasOnlyKeys(value, ["id", "label", "owner", "agentId", "cardIds", "routes"])
-        || typeof value.id !== "string"
-        || value.id.length === 0
-        || value.id.length > 256
-        || typeof value.label !== "string"
-        || value.label.length === 0
-        || value.label.length > 160
-        || value.owner !== "agent"
-        || typeof value.agentId !== "string"
-        || value.agentId.length === 0
-        || value.agentId.length > 256
-        || !Array.isArray(value.cardIds)
-        || value.cardIds.length === 0
-        || value.cardIds.length > 64
-        || !Array.isArray(value.routes)
-        || value.routes.length === 0
-        || value.routes.length > 64) {
-        return false;
-    }
-    if (!value.cardIds.every((cardId) => typeof cardId === "string" && cardId.length > 0 && cardId.length <= 256)) {
-        return false;
-    }
-    return value.routes.every((route) => {
-        if (!isRecord(route)
-            || !hasOnlyKeys(route, ["url", "title", "label"])
-            || !isSameOriginUrl(route.url)
-            || (route.title !== undefined && route.title !== null
-                && (typeof route.title !== "string" || route.title.length > 512))
-            || (route.label !== undefined
-                && (typeof route.label !== "string" || route.label.length > 160))) {
-            return false;
-        }
-        return true;
-    });
-}
 function storageKey(projectId) {
     return `${STORAGE_PREFIX}:${projectId}:v${SCHEMA_VERSION}`;
 }
 function buildSession() {
-    const workspace = getWorkspaceChanges();
-    const changes = workspace.changes;
-    const serializableChanges = [];
-    for (const change of changes) {
-        const serialized = serializeChange(change);
-        // serializeChange already fails closed, but re-validate here so a future
-        // serializer skew can never poison the whole durable session.
-        if (serialized && isSerializableChange(serialized))
-            serializableChanges.push(serialized);
-    }
     const cards = getCanvasCards();
-    const comparisonGroups = getCanvasComparisonGroups();
     const camera = getBoardCamera();
     const mode = getCanvasMode();
     return {
         schemaVersion: SCHEMA_VERSION,
         projectId: projectId(),
         mode,
+        presentation: getCanvasPresentation(),
+        groups: getFrameGroups(),
         inspectUrl: window.location.href,
         cards: cards.map((c) => ({
             id: c.id,
-            url: c.url,
+            content: c.content.kind === "route" ? { kind: "route", url: c.content.url } : { ...c.content },
             title: c.title,
+            ...(c.groupId ? { groupId: c.groupId } : {}),
             x: c.x,
             y: c.y,
             width: c.width,
             height: c.height,
-            ...(c.comparisonGroupId ? { comparisonGroupId: c.comparisonGroupId } : {}),
-        })),
-        comparisonGroups: comparisonGroups.map((group) => ({
-            id: group.id,
-            label: group.label,
-            owner: "agent",
-            agentId: group.agentId,
-            cardIds: [...group.cardIds],
-            routes: group.routes.map((route) => ({
-                url: route.url,
-                ...(route.title === undefined ? {} : { title: route.title }),
-                ...(route.label === undefined ? {} : { label: route.label }),
-            })),
         })),
         camera: { x: camera.x, y: camera.y, zoom: camera.zoom },
         focusedCardId: getFocusedCardId(),
-        changes: serializableChanges,
-        structuralChanges: workspace.structuralChanges.map((change) => ({ ...change })),
         clipboardHandoff: getClipboardHandoffSnapshot(),
     };
 }
@@ -142,6 +77,7 @@ function persistSessionUnchecked() {
     if (!projectId())
         return false;
     try {
+        persistDrafts();
         const session = buildSession();
         localStorage.setItem(storageKey(projectId()), JSON.stringify(session));
         return true;
@@ -203,7 +139,7 @@ export function hydrateSession() {
         const candidate = card;
         if (!card || typeof card !== "object" ||
             typeof candidate.id !== "string" ||
-            !isSameOriginUrl(candidate.url) ||
+            !isFrameContent(candidate.content, window.location.origin) ||
             !isFiniteNumber(candidate.x) ||
             !isFiniteNumber(candidate.y) ||
             !isFiniteNumber(candidate.width) ||
@@ -216,70 +152,20 @@ export function hydrateSession() {
         const c = card;
         serializableCards.push({
             id: c.id,
-            url: c.url,
+            content: c.content,
             title: typeof c.title === "string" ? c.title : null,
+            ...(typeof c.groupId === "string" && c.groupId.length <= 256 ? { groupId: c.groupId } : {}),
             x: c.x,
             y: c.y,
             width: c.width,
             height: c.height,
-            ...(typeof c.comparisonGroupId === "string"
-                ? { comparisonGroupId: c.comparisonGroupId }
-                : {}),
         });
     }
     if (new Set(serializableCards.map((card) => card.id)).size !== serializableCards.length) {
         safeDiscard();
         return { restored: false, changeCount: 0 };
     }
-    const comparisonGroupsRaw = s.comparisonGroups;
-    if (!Array.isArray(comparisonGroupsRaw) || comparisonGroupsRaw.length > 128) {
-        safeDiscard();
-        return { restored: false, changeCount: 0 };
-    }
-    const serializableComparisonGroups = [];
-    for (const group of comparisonGroupsRaw) {
-        if (!isSerializableComparisonGroup(group)) {
-            safeDiscard();
-            return { restored: false, changeCount: 0 };
-        }
-        serializableComparisonGroups.push({
-            id: group.id,
-            label: group.label,
-            owner: "agent",
-            agentId: group.agentId,
-            cardIds: [...group.cardIds],
-            routes: group.routes.map((route) => ({ ...route })),
-        });
-    }
-    if (new Set(serializableComparisonGroups.map((group) => group.id)).size
-        !== serializableComparisonGroups.length) {
-        safeDiscard();
-        return { restored: false, changeCount: 0 };
-    }
     const cardsById = new Map(serializableCards.map((card) => [card.id, card]));
-    const groupedCardIds = new Set();
-    for (const group of serializableComparisonGroups) {
-        if (group.cardIds.length !== group.routes.length) {
-            safeDiscard();
-            return { restored: false, changeCount: 0 };
-        }
-        for (const [routeIndex, cardId] of group.cardIds.entries()) {
-            const card = cardsById.get(cardId);
-            const route = group.routes[routeIndex];
-            if (!card || !route || card.comparisonGroupId !== group.id || groupedCardIds.has(cardId)
-                || card.url !== route.url) {
-                safeDiscard();
-                return { restored: false, changeCount: 0 };
-            }
-            groupedCardIds.add(cardId);
-        }
-    }
-    for (const card of serializableCards) {
-        if (card.comparisonGroupId && !serializableComparisonGroups.some((group) => group.id === card.comparisonGroupId)) {
-            safeDiscard();
-            return { restored: false, changeCount: 0 };
-        }
-    }
     const cameraRaw = s.camera;
     if (!cameraRaw || typeof cameraRaw !== "object" ||
         !isFiniteNumber(cameraRaw.x) ||
@@ -288,35 +174,9 @@ export function hydrateSession() {
         safeDiscard();
         return { restored: false, changeCount: 0 };
     }
-    const changesRaw = s.changes;
-    if (!Array.isArray(changesRaw)) {
-        safeDiscard();
-        return { restored: false, changeCount: 0 };
-    }
-    const deserializedChanges = [];
-    const textChangeIds = new Set();
-    for (const c of changesRaw) {
-        if (!isSerializableChange(c)) {
-            safeDiscard();
-            return { restored: false, changeCount: 0 };
-        }
-        if (c.kind === "text-content") {
-            if (textChangeIds.has(c.id)) {
-                safeDiscard();
-                return { restored: false, changeCount: 0 };
-            }
-            textChangeIds.add(c.id);
-        }
-        try {
-            deserializedChanges.push(deserializeChange(c));
-        }
-        catch {
-            safeDiscard();
-            return { restored: false, changeCount: 0 };
-        }
-    }
-    const structuralChanges = s.structuralChanges;
-    if (!Array.isArray(structuralChanges) || !structuralChanges.every(isStructuralChange)) {
+    const presentation = s.presentation ?? "focus";
+    const groups = Array.isArray(s.groups) ? s.groups.filter((group) => group?.kind !== "linked") : s.groups ?? [];
+    if ((presentation !== "focus" && presentation !== "canvas") || !Array.isArray(groups) || !groups.every(isFrameGroup)) {
         safeDiscard();
         return { restored: false, changeCount: 0 };
     }
@@ -339,10 +199,7 @@ export function hydrateSession() {
         safeDiscard();
         return { restored: false, changeCount: 0 };
     }
-    hydrateCanvasStore(s.mode, serializableCards, camera, serializableComparisonGroups, focusedCardId);
-    // Structural intent and instance evidence become visible atomically. The
-    // projection layer preserves structural-first document application order.
-    loadWorkspaceChanges(deserializedChanges, structuralChanges);
+    hydrateCanvasStore(s.mode, serializableCards, camera, focusedCardId, presentation, groups);
     hydrateClipboardHandoff(clipboardHandoff);
     // A different URL means the user intentionally navigated while Inspect was
     // active. Keep the durable edits, but adopt the new route instead of
@@ -350,8 +207,7 @@ export function hydrateSession() {
     // match and restoration remains unchanged.
     if (inspectRouteChanged)
         persistSessionUnchecked();
-    projectToAllReadyCards();
-    return { restored: true, changeCount: deserializedChanges.length + structuralChanges.length };
+    return { restored: true, changeCount: 0 };
 }
 function safeDiscard() {
     try {
@@ -361,7 +217,22 @@ function safeDiscard() {
         // ignore
     }
 }
+/** Clears the active frame's edit draft while preserving canvas geometry and other drafts. */
+export function clearSelectedFrameChanges() {
+    if (!canEditDraft())
+        return;
+    const cardId = getSelectedCardId() ?? getFocusedCardId();
+    if (cardId)
+        activateDraftForCard(cardId);
+    clearComments(targetFromKey(getActiveDraftChanges().draftId) ?? documentTarget(window.location.href));
+    clearActiveDraft();
+    setSelectedElement(null);
+    projectToAllReadyCards();
+    scheduleAutoSave();
+}
 export function clearSession() {
+    if (isDraftLocked())
+        return;
     if (!canWriteWorkspace())
         return;
     try {
@@ -370,8 +241,10 @@ export function clearSession() {
     catch {
         // ignore
     }
-    clearWorkspaceLog();
+    clearComments();
+    clearActiveDraft();
     clearClipboardHandoff();
+    clearDrafts();
     resetStructuralDeleteProjection();
     removeManagedSheet();
     setSelectedElement(null);
@@ -415,27 +288,14 @@ export function scheduleAutoSave() {
             autoSaveDirty = false;
     }, AUTOSAVE_DEBOUNCE_MS);
 }
-/**
- * Canvas mode/card/camera changes persist immediately (synchronous) so a
- * refresh always restores the workspace, even inside the edit-autosave
- * debounce window. Edit autosave stays coalesced behind the trailing timer.
- */
-export function scheduleCanvasSave() {
-    if (!autoSaveEnabled)
-        return;
-    if (persistSession())
-        autoSaveDirty = false;
-}
-function flushAutoSave() {
+export function scheduleCanvasSave() { scheduleAutoSave(); }
+export function flushAutoSave() {
     if (autosaveTimer !== null) {
         clearTimeout(autosaveTimer);
         autosaveTimer = null;
     }
     if (!autoSaveDirty)
         return;
-    // Keep the normal lease gate on the unload path. The controller registers
-    // this listener before releaseLease, so a current owner can flush a first
-    // write without allowing a stale tab to overwrite the new owner's session.
     if (persistSession())
         autoSaveDirty = false;
 }

package/dist/inspector/canvas/staleChangeDetector.js

@@ -1,10 +1,12 @@
+import { draftIdForCard } from "../drafts/store.js";
 import { isPreviewableChange, isTokenChange, } from "../changes/changesLog.js";
 import { changeKey } from "../changes/model.js";
 import { beginPreviewAttempt, clearPreviewDiagnostics, getHostPreviewDocument, notifyPreviewDiagnostics, publishPreviewDiagnostic, } from "../changes/previewDiagnostics.js";
-import { getWorkspaceChanges } from "../changes/workspaceChanges.js";
+import { getActiveDraftChanges } from "../changes/draftChanges.js";
 import { getCanvasPreviewDocument, getRegisteredFrames } from "./projection.js";
 import { findCanvasFrameBySource, PROJECT_ID, WORKSPACE_ID } from "./projection.js";
-import { getCanvasCards, getCanvasMode } from "./canvasStore.js";
+import { getCanvasCards } from "./canvasStore.js";
+import { getCanvasMode } from "./viewStore.js";
 import { isRendererMessageFor } from "./frameProtocol.js";
 import { getNudgeUiRuntimeConfig } from "../runtime/runtimeConfig.js";
 const VERIFICATION_TIMEOUT_MS = 5000;
@@ -82,6 +84,8 @@ function getPreviewDocuments() {
     const documents = getCanvasMode() === "canvas" ? [] : [getHostPreviewDocument()];
     const frames = getRegisteredFrames();
     for (const card of getCanvasCards()) {
+        if (draftIdForCard(card.id) && draftIdForCard(card.id) !== getActiveDraftChanges().draftId)
+            continue;
         if (frames.has(card.id))
             documents.push(getCanvasPreviewDocument(card.id));
     }
@@ -89,7 +93,7 @@ function getPreviewDocuments() {
 }
 function beginPreviewAttempts() {
     const attempts = new Map();
-    const revision = getWorkspaceChanges().revision;
+    const revision = getActiveDraftChanges().revision;
     for (const document of getPreviewDocuments()) {
         const attempt = beginPreviewAttempt(document, revision);
         if (attempt)
@@ -115,6 +119,8 @@ function gatherMatchEvidence(changes) {
     const frames = getRegisteredFrames();
     const cards = getCanvasCards();
     for (const card of cards) {
+        if (draftIdForCard(card.id) && draftIdForCard(card.id) !== getActiveDraftChanges().draftId)
+            continue;
         const frame = frames.get(card.id);
         if (!frame || !frame.contentWindow)
             continue;

package/dist/inspector/canvas/useCanvasLayoutAnimation.d.ts

@@ -0,0 +1,5 @@
+import { type RefObject } from "react";
+import { type CanvasCard } from "./canvasStore.js";
+import { type CanvasCamera, type CanvasPresentation } from "./viewStore.js";
+/** Animates frame creation and layout changes without delaying direct manipulation. */
+export declare function useCanvasLayoutAnimation(boardRef: RefObject<HTMLDivElement | null>, cards: readonly CanvasCard[], camera: CanvasCamera, presentation: CanvasPresentation): void;

package/dist/inspector/canvas/useCanvasLayoutAnimation.js

@@ -0,0 +1,107 @@
+import { iterationId } from "./frameContent.js";
+import { useEffect, useLayoutEffect, useRef } from "react";
+import {} from "./canvasStore.js";
+import { setCanvasLayoutTransitioning } from "./viewStore.js";
+const SLIDE_OPTIONS = { duration: 300, easing: "ease-out" };
+const CAMERA_OPTIONS = { duration: 150, easing: "ease-out" };
+/** Animates frame creation and layout changes without delaying direct manipulation. */
+export function useCanvasLayoutAnimation(boardRef, cards, camera, presentation) {
+    const previous = useRef({ cards, camera, presentation });
+    const animations = useRef([]);
+    const generation = useRef(0);
+    useEffect(() => {
+        const board = boardRef.current;
+        const cancel = () => {
+            generation.current += 1;
+            setCanvasLayoutTransitioning(false);
+            for (const animation of animations.current)
+                animation.cancel();
+            animations.current = [];
+        };
+        const cancelWheel = (event) => {
+            if (board && event.composedPath().includes(board))
+                cancel();
+        };
+        board?.addEventListener("pointerdown", cancel, true);
+        window.addEventListener("wheel", cancelWheel, true);
+        return () => {
+            cancel();
+            board?.removeEventListener("pointerdown", cancel, true);
+            window.removeEventListener("wheel", cancelWheel, true);
+        };
+    }, [boardRef]);
+    useLayoutEffect(() => {
+        const before = previous.current;
+        previous.current = { cards, camera, presentation };
+        const oldCards = new Map(before.cards.map((card) => [card.id, card]));
+        const layoutChanged = cards.some((card) => {
+            const old = oldCards.get(card.id);
+            return (!old && card.animateEntrance !== false && (card.entrance === "linked" || iterationId(card.content))) || (old && iterationId(card.content) && iterationId(old.content) !== iterationId(card.content));
+        });
+        const cameraChanged = camera.x !== before.camera.x || camera.y !== before.camera.y || camera.zoom !== before.camera.zoom;
+        const shouldAnimate = (layoutChanged || (cameraChanged && animations.current.length > 0))
+            && presentation === "canvas" && before.presentation === "canvas"
+            && !window.matchMedia?.("(prefers-reduced-motion: reduce)").matches;
+        const board = boardRef.current;
+        const animate = (element, frames, options = SLIDE_OPTIONS) => {
+            if (shouldAnimate && typeof element.animate === "function") {
+                animations.current.push(element.animate(frames, options));
+            }
+        };
+        if (shouldAnimate) {
+            generation.current += 1;
+            setCanvasLayoutTransitioning(true);
+            if (layoutChanged) {
+                for (const animation of animations.current)
+                    animation.cancel();
+                animations.current = [];
+            }
+            for (const element of board?.querySelectorAll(".canvas-card") ?? []) {
+                const card = cards.find((item) => item.id === element.dataset.cardId);
+                if (!card)
+                    continue;
+                const old = oldCards.get(card.id);
+                if (!old) {
+                    if (card.animateEntrance === false)
+                        continue;
+                    const slideRight = Boolean(card.entrance === "linked");
+                    animate(element, [
+                        { left: `${card.x - (slideRight ? 200 : 0)}px`, top: `${card.y - (slideRight ? 0 : 200)}px`, opacity: 0 },
+                        { left: `${card.x}px`, top: `${card.y}px`, opacity: 1 },
+                    ]);
+                }
+                else if (old.x !== card.x || old.y !== card.y) {
+                    animate(element, [{ left: `${old.x}px`, top: `${old.y}px` }, { left: `${card.x}px`, top: `${card.y}px` }]);
+                }
+            }
+            const content = board?.querySelector(".canvas-workspace__board-content");
+            if (content && cameraChanged) {
+                const current = animations.current.find((animation) => animation.playState === "running"
+                    && animation.effect?.target === content);
+                const from = current ? getComputedStyle(content).transform
+                    : `translate(${before.camera.x}px, ${before.camera.y}px) scale(${before.camera.zoom})`;
+                current?.cancel();
+                animate(content, [
+                    { transform: from },
+                    { transform: `translate(${camera.x}px, ${camera.y}px) scale(${camera.zoom})` },
+                ], CAMERA_OPTIONS);
+            }
+        }
+        if (shouldAnimate) {
+            const current = generation.current;
+            void Promise.all(animations.current.map((animation) => animation.finished.catch(() => undefined))).then(() => {
+                if (generation.current !== current)
+                    return;
+                animations.current = [];
+                setCanvasLayoutTransitioning(false);
+            });
+        }
+        else if (presentation !== before.presentation) {
+            generation.current += 1;
+            for (const animation of animations.current)
+                animation.cancel();
+            animations.current = [];
+            setCanvasLayoutTransitioning(false);
+        }
+    }, [boardRef, cards, camera, presentation]);
+}

package/dist/inspector/canvas/viewStore.d.ts

@@ -0,0 +1,38 @@
+export type CanvasMode = "inspect" | "canvas";
+export type CanvasPresentation = "focus" | "canvas";
+export interface CanvasCamera {
+    x: number;
+    y: number;
+    zoom: number;
+}
+export declare const MIN_CAMERA_ZOOM = 0.25;
+export declare const MAX_CAMERA_ZOOM = 3;
+export declare const DEFAULT_CAMERA: CanvasCamera;
+export declare function subscribeCanvasView(listener: () => void): () => void;
+export declare function getCanvasMode(): CanvasMode;
+export declare function setCanvasMode(next: CanvasMode): void;
+export declare function getCanvasPresentation(): CanvasPresentation;
+export declare function setCanvasPresentation(next: CanvasPresentation): void;
+/** Holding A temporarily enables app interaction without changing the selected tool. */
+export declare function setTemporaryAppInteraction(value: boolean): void;
+/** Element interactions pause while frame and camera geometry are animated. */
+export declare function setCanvasLayoutTransitioning(value: boolean): void;
+export declare function getCanvasLayoutTransitioning(): boolean;
+export declare function getBoardCamera(): CanvasCamera;
+export declare function setBoardCamera(next: CanvasCamera): void;
+export declare function updateBoardCamera(partial: Partial<CanvasCamera>): void;
+/** Moves the camera to frame content; the initial fit-all then no longer runs. */
+export declare function placeBoardCamera(next: CanvasCamera): void;
+export declare function hasFitAllRan(): boolean;
+export declare function resetFitAllFlag(): void;
+export declare function restoreCanvasView(next: {
+    mode: CanvasMode;
+    presentation: CanvasPresentation;
+    camera: CanvasCamera;
+}): void;
+export declare function useCanvasMode(): CanvasMode;
+export declare function useCanvasPresentation(): CanvasPresentation;
+export declare function useCanvasPresentationTransitioning(): boolean;
+export declare function useTemporaryAppInteraction(): boolean;
+export declare function useCanvasLayoutTransitioning(): boolean;
+export declare function useBoardCamera(): CanvasCamera;

package/dist/inspector/canvas/viewStore.js

@@ -0,0 +1,104 @@
+import { useSyncExternalStore } from "react";
+export const MIN_CAMERA_ZOOM = 0.25;
+export const MAX_CAMERA_ZOOM = 3;
+export const DEFAULT_CAMERA = { x: 0, y: 0, zoom: 1 };
+/** How the canvas is viewed. Frames, groups, and selection live in the canvas store. */
+let mode = "inspect";
+let presentation = "focus";
+let presentationTransitioning = false;
+let presentationTransitionTimer = null;
+let layoutTransitioning = false;
+let temporaryAppInteraction = false;
+let camera = { ...DEFAULT_CAMERA };
+let cameraPlaced = false;
+const listeners = new Set();
+function notify() {
+    for (const listener of listeners)
+        listener();
+}
+export function subscribeCanvasView(listener) {
+    listeners.add(listener);
+    return () => listeners.delete(listener);
+}
+function clampZoom(zoom) {
+    return Math.max(MIN_CAMERA_ZOOM, Math.min(MAX_CAMERA_ZOOM, zoom));
+}
+export function getCanvasMode() { return mode; }
+export function setCanvasMode(next) {
+    if (mode === next)
+        return;
+    mode = next;
+    notify();
+}
+export function getCanvasPresentation() { return presentation; }
+export function setCanvasPresentation(next) {
+    if (presentation === next)
+        return;
+    presentation = next;
+    presentationTransitioning = !window.matchMedia?.("(prefers-reduced-motion: reduce)").matches;
+    if (presentationTransitionTimer !== null)
+        window.clearTimeout(presentationTransitionTimer);
+    presentationTransitionTimer = presentationTransitioning
+        ? window.setTimeout(() => {
+            presentationTransitionTimer = null;
+            presentationTransitioning = false;
+            notify();
+        }, 220)
+        : null;
+    notify();
+}
+/** Holding A temporarily enables app interaction without changing the selected tool. */
+export function setTemporaryAppInteraction(value) {
+    if (temporaryAppInteraction === value)
+        return;
+    temporaryAppInteraction = value;
+    notify();
+}
+/** Element interactions pause while frame and camera geometry are animated. */
+export function setCanvasLayoutTransitioning(value) {
+    if (layoutTransitioning === value)
+        return;
+    layoutTransitioning = value;
+    notify();
+}
+export function getCanvasLayoutTransitioning() { return layoutTransitioning; }
+export function getBoardCamera() { return camera; }
+export function setBoardCamera(next) {
+    camera = { x: next.x, y: next.y, zoom: clampZoom(next.zoom) };
+    notify();
+}
+export function updateBoardCamera(partial) {
+    setBoardCamera({ ...camera, ...partial });
+}
+/** Moves the camera to frame content; the initial fit-all then no longer runs. */
+export function placeBoardCamera(next) {
+    cameraPlaced = true;
+    setBoardCamera(next);
+}
+export function hasFitAllRan() { return cameraPlaced; }
+export function resetFitAllFlag() { cameraPlaced = false; }
+export function restoreCanvasView(next) {
+    mode = next.mode;
+    presentation = next.presentation;
+    camera = { ...next.camera };
+    cameraPlaced = true;
+    notify();
+}
+export function useCanvasMode() {
+    return useSyncExternalStore(subscribeCanvasView, getCanvasMode, getCanvasMode);
+}
+export function useCanvasPresentation() {
+    return useSyncExternalStore(subscribeCanvasView, getCanvasPresentation, getCanvasPresentation);
+}
+export function useCanvasPresentationTransitioning() {
+    return useSyncExternalStore(subscribeCanvasView, () => presentationTransitioning, () => presentationTransitioning);
+}
+export function useTemporaryAppInteraction() {
+    return useSyncExternalStore(subscribeCanvasView, () => temporaryAppInteraction, () => temporaryAppInteraction);
+}
+export function useCanvasLayoutTransitioning() {
+    return useSyncExternalStore(subscribeCanvasView, getCanvasLayoutTransitioning, getCanvasLayoutTransitioning);
+}
+export function useBoardCamera() {
+    return useSyncExternalStore(subscribeCanvasView, getBoardCamera, getBoardCamera);
+}

package/dist/inspector/canvas/wheelPan.d.ts

@@ -0,0 +1,8 @@
+/** Converts wheel units to pixel distances for consistent canvas panning. */
+export declare function wheelPanDelta(event: Pick<WheelEvent, "deltaX" | "deltaY" | "deltaMode" | "shiftKey">, viewport: {
+    width: number;
+    height: number;
+}): {
+    x: number;
+    y: number;
+};

package/dist/inspector/canvas/wheelPan.js

@@ -0,0 +1,8 @@
+/** Converts wheel units to pixel distances for consistent canvas panning. */
+export function wheelPanDelta(event, viewport) {
+    const xUnit = event.deltaMode === 1 ? 16 : event.deltaMode === 2 ? viewport.width : 1;
+    const yUnit = event.deltaMode === 1 ? 16 : event.deltaMode === 2 ? viewport.height : 1;
+    const x = event.deltaX * xUnit;
+    const y = event.deltaY * yUnit;
+    return event.shiftKey && x === 0 ? { x: y, y: 0 } : { x, y };
+}