opendevbrowser 0.0.17 → 0.0.19

package/extension/dist/canvas/canvas-runtime.js

@@ -3,6 +3,7 @@ import { logError } from "../logging.js";
 import { TabManager } from "../services/TabManager.js";
 import { TargetSessionCoordinator, createCoordinatorId } from "../ops/target-session-coordinator.js";
 import { normalizeCanvasSessionSummary, normalizeCanvasTargetStateSummaries } from "./model.js";
+import { DEFAULT_EDITOR_VIEWPORT } from "./viewport-fit.js";
 const OVERLAY_STYLE = `
 #opendevbrowser-canvas-style,
 .opendevbrowser-canvas-highlight {
@@ -33,12 +34,18 @@ const OVERLAY_STYLE = `
 `;
 export class CanvasRuntime {
     sendEnvelope;
+    registerOpsCanvasTarget;
+    unregisterOpsCanvasTarget;
+    encoder = new TextEncoder();
     tabs = new TabManager();
     sessions = new TargetSessionCoordinator();
+    overlaySessions = new Map();
     pagePorts = new Map();
     pendingPageActions = new Map();
     constructor(options) {
         this.sendEnvelope = options.send;
+        this.registerOpsCanvasTarget = options.registerOpsCanvasTarget;
+        this.unregisterOpsCanvasTarget = options.unregisterOpsCanvasTarget;
     }
     attachPort(port) {
         if (port.name !== "canvas-page") {
@@ -175,6 +182,11 @@ export class CanvasRuntime {
         for (const session of this.sessions.listOwnedBy(clientId)) {
             void this.closeRuntimeSession(session, "client_disconnected");
         }
+        for (const [sessionId, session] of this.overlaySessions.entries()) {
+            if (session.ownerClientId === clientId) {
+                this.overlaySessions.delete(sessionId);
+            }
+        }
     }
     handlePagePortMessage(tabId, message) {
         if (message.type === "canvas-page-action-response") {
@@ -209,7 +221,7 @@ export class CanvasRuntime {
             if (!Array.isArray(message.patches) || message.patches.length === 0 || typeof message.baseRevision !== "number") {
                 return;
             }
-            this.mergeEditorState(session, undefined, message.selection);
+            this.mergeEditorState(session, message.viewport, message.selection);
             session.pendingMutation = true;
             this.broadcastCanvasState(tabId, "canvas-page:update");
             this.sendEvent({
@@ -222,7 +234,20 @@ export class CanvasRuntime {
                     documentId: session.document.documentId,
                     baseRevision: message.baseRevision,
                     patches: message.patches,
-                    selection: session.selection
+                    selection: session.selection,
+                    viewport: session.viewport
+                }
+            });
+            return;
+        }
+        if (message.type === "canvas-page-history-request") {
+            this.sendEvent({
+                type: "canvas_event",
+                clientId: session.ownerClientId,
+                canvasSessionId: session.id,
+                event: "canvas_history_requested",
+                payload: {
+                    direction: message.direction
                 }
             });
         }
@@ -265,6 +290,12 @@ export class CanvasRuntime {
         const tab = await this.createTab(chrome.runtime.getURL("canvas.html"), previewMode);
         const tabId = requireTabId(tab);
         const session = this.createOrReplaceSession(message, tabId, document, previewMode, record);
+        await this.syncOpsTargetRegistration(session).catch((error) => {
+            logError("canvas.sync_ops_target_registration", error, {
+                code: "canvas_ops_target_registration_failed",
+                extra: { canvasSessionId: session.id, targetId: session.designTabTargetId }
+            });
+        });
         this.broadcastCanvasState(tabId, "canvas-page:init");
         this.sendEvent({
             type: "canvas_event",
@@ -279,15 +310,54 @@ export class CanvasRuntime {
         };
     }
     async closeTab(message) {
-        const session = this.requireSessionForMessage(message);
         const record = requireRecord(message.payload, "payload");
         const tabId = parseTargetId(requireString(record.targetId, "targetId"));
         const targetId = formatTargetId(tabId);
+        let session = null;
+        try {
+            session = this.requireSessionForMessage(message, record);
+        }
+        catch (error) {
+            if (!isIgnorableCanvasCloseLookupError(error)) {
+                throw error;
+            }
+        }
+        if (!session) {
+            const browserSessionId = optionalString(record.browserSessionId)
+                ?? optionalString(isRecord(record.summary) ? record.summary.browserSessionId : undefined);
+            if (browserSessionId && this.unregisterOpsCanvasTarget) {
+                await Promise.resolve(this.unregisterOpsCanvasTarget(browserSessionId, targetId)).catch((error) => {
+                    logError("canvas.unregister_ops_target", error, {
+                        code: "canvas_ops_target_unregister_failed",
+                        extra: { browserSessionId, targetId }
+                    });
+                });
+            }
+            this.broadcastCanvasState(tabId, "canvas-page:closed", { reason: "target_closed" });
+            this.pagePorts.delete(tabId);
+            await this.tabs.closeTab(tabId).catch(() => undefined);
+            return {
+                ok: true,
+                targetId,
+                targetIds: [],
+                releasedTargetIds: [targetId],
+                previewState: "background"
+            };
+        }
         this.broadcastCanvasState(tabId, "canvas-page:closed", { reason: "target_closed" });
         session.designTabTargetId = null;
         session.pendingMutation = false;
         this.pagePorts.delete(tabId);
         this.sessions.removeTarget(session.id, targetId);
+        const browserSessionId = readBrowserSessionId(session.summary);
+        if (browserSessionId && this.unregisterOpsCanvasTarget) {
+            await Promise.resolve(this.unregisterOpsCanvasTarget(browserSessionId, targetId)).catch((error) => {
+                logError("canvas.unregister_ops_target", error, {
+                    code: "canvas_ops_target_unregister_failed",
+                    extra: { browserSessionId, targetId }
+                });
+            });
+        }
         await this.tabs.closeTab(tabId);
         this.sendEvent({
             type: "canvas_event",
@@ -296,16 +366,6 @@ export class CanvasRuntime {
             event: "canvas_target_closed",
             payload: { targetId, tabId }
         });
-        if (session.targets.size === 0) {
-            this.sessions.delete(session.id);
-            this.sendEvent({
-                type: "canvas_event",
-                clientId: session.ownerClientId,
-                canvasSessionId: session.id,
-                event: "canvas_session_closed",
-                payload: { reason: "target_closed" }
-            });
-        }
         return {
             ok: true,
             targetId,
@@ -343,10 +403,27 @@ export class CanvasRuntime {
         };
     }
     async mountOverlay(message) {
-        const session = this.requireSessionForMessage(message);
         const record = requireRecord(message.payload, "payload");
+        const session = this.requireOverlaySession(message, record, true);
         const tabId = parseTargetId(requireString(record.targetId, "targetId"));
         const prototypeId = optionalString(record.prototypeId) ?? "default";
+        if (this.isDesignTabTarget(session, tabId)) {
+            const mountId = `mount_${crypto.randomUUID()}`;
+            const mount = {
+                mountId,
+                targetId: formatTargetId(tabId),
+                mountedAt: new Date().toISOString()
+            };
+            session.overlayMounts = dedupeOverlayMounts([...session.overlayMounts, mount]);
+            this.broadcastIfDesignTab(session);
+            return {
+                mountId,
+                targetId: formatTargetId(tabId),
+                previewState: session.previewState,
+                overlayState: "mounted",
+                capabilities: { selection: true, guides: true }
+            };
+        }
         await insertCss(tabId, OVERLAY_STYLE);
         const mountId = `mount_${crypto.randomUUID()}`;
         const result = await executeInTab(tabId, mountOverlayScript, [{
@@ -372,10 +449,20 @@ export class CanvasRuntime {
         };
     }
     async unmountOverlay(message) {
-        const session = this.requireSessionForMessage(message);
         const record = requireRecord(message.payload, "payload");
+        const session = this.requireOverlaySession(message, record);
         const mountId = requireString(record.mountId, "mountId");
         const tabId = parseTargetId(requireString(record.targetId, "targetId"));
+        if (this.isDesignTabTarget(session, tabId)) {
+            session.overlayMounts = session.overlayMounts.filter((mount) => mount.mountId !== mountId);
+            this.broadcastIfDesignTab(session);
+            return {
+                ok: true,
+                mountId,
+                previewState: session.previewState,
+                overlayState: "idle"
+            };
+        }
         await executeInTab(tabId, unmountOverlayScript, [mountId]);
         session.overlayMounts = session.overlayMounts.filter((mount) => mount.mountId !== mountId);
         this.broadcastIfDesignTab(session);
@@ -387,16 +474,19 @@ export class CanvasRuntime {
         };
     }
     async selectOverlay(message) {
-        const session = this.requireSessionForMessage(message);
         const record = requireRecord(message.payload, "payload");
+        const session = this.requireOverlaySession(message, record);
         const tabId = parseTargetId(requireString(record.targetId, "targetId"));
         const selectionHint = isRecord(record.selectionHint) ? record.selectionHint : {};
         const nodeId = optionalString(record.nodeId);
-        const selection = await executeInTab(tabId, selectOverlayScript, [{ selectionHint, nodeId }]);
-        if (typeof nodeId === "string") {
+        const selection = this.isDesignTabTarget(session, tabId)
+            ? resolveDesignTabOverlaySelection(session.document, nodeId, selectionHint)
+            : await executeInTab(tabId, selectOverlayScript, [{ selectionHint, nodeId }]);
+        const resolvedNodeId = typeof selection.nodeId === "string" ? selection.nodeId : nodeId;
+        if (typeof resolvedNodeId === "string") {
             session.selection = {
                 pageId: session.document.pages[0]?.id ?? null,
-                nodeId,
+                nodeId: resolvedNodeId,
                 targetId: formatTargetId(tabId),
                 updatedAt: new Date().toISOString()
             };
@@ -408,10 +498,19 @@ export class CanvasRuntime {
         };
     }
     async syncOverlay(message) {
-        const session = this.requireSessionForMessage(message);
         const record = requireRecord(message.payload, "payload");
+        const session = this.requireOverlaySession(message, record);
         const tabId = parseTargetId(requireString(record.targetId, "targetId"));
         const mountId = requireString(record.mountId, "mountId");
+        if (this.isDesignTabTarget(session, tabId)) {
+            this.broadcastIfDesignTab(session);
+            return {
+                ok: true,
+                mountId,
+                targetId: formatTargetId(tabId),
+                overlayState: "mounted"
+            };
+        }
         await insertCss(tabId, OVERLAY_STYLE);
         const result = await executeInTab(tabId, syncOverlayScript, [{
                 mountId,
@@ -432,6 +531,7 @@ export class CanvasRuntime {
         const summary = normalizeCanvasSessionSummary(record.summary);
         const existing = this.sessions.get(canvasSessionId);
         if (existing) {
+            this.overlaySessions.delete(existing.id);
             if (existing.ownerClientId !== clientId || (requestedLeaseId && existing.leaseId !== requestedLeaseId)) {
                 throw new Error("Canvas session ownership mismatch.");
             }
@@ -450,11 +550,13 @@ export class CanvasRuntime {
             existing.previewMode = previewMode;
             existing.previewState = previewMode;
             existing.pendingMutation = false;
+            this.mergeEditorState(existing, normalizeViewport(record.viewport), normalizeSelection(record.selection));
             this.sessions.addTarget(existing.id, tabId, { title: document.title, url: chrome.runtime.getURL("canvas.html") });
             this.sessions.setActiveTarget(existing.id, formatTargetId(tabId));
             return existing;
         }
         const leaseId = requestedLeaseId ?? createCoordinatorId();
+        const viewport = normalizeViewportState(record.viewport);
         const session = this.sessions.createSession(clientId, tabId, leaseId, {
             title: document.title,
             url: chrome.runtime.getURL("canvas.html")
@@ -470,10 +572,59 @@ export class CanvasRuntime {
             overlayMounts: parseOverlayMounts(record.overlayMounts ?? summary.overlayMounts),
             feedback: parseFeedbackEvents(record.feedback),
             feedbackCursor: optionalString(record.feedbackCursor) ?? lastFeedbackCursor(parseFeedbackEvents(record.feedback)),
-            selection: defaultSelection(document.pages[0]?.id ?? null),
-            viewport: { x: 120, y: 96, zoom: 1 },
+            selection: normalizeSelectionState(record.selection, document.pages[0]?.id ?? null),
+            viewport,
             pendingMutation: false
         }, canvasSessionId);
+        this.overlaySessions.delete(session.id);
+        return session;
+    }
+    requireOverlaySession(message, record, createIfMissing = false) {
+        try {
+            return this.requireSessionForMessage(message, record);
+        }
+        catch (error) {
+            if (!isIgnorableCanvasCloseLookupError(error)) {
+                throw error;
+            }
+        }
+        const sessionId = optionalString(message.canvasSessionId)
+            ?? optionalString(record.canvasSessionId)
+            ?? optionalString(isRecord(record.summary) ? record.summary.canvasSessionId : undefined);
+        if (!sessionId) {
+            throw missingCanvasSession();
+        }
+        const clientId = requireString(message.clientId, "clientId");
+        const requestedLeaseId = optionalString(message.leaseId);
+        const existing = this.overlaySessions.get(sessionId);
+        if (existing) {
+            if (existing.ownerClientId !== clientId || (requestedLeaseId && existing.leaseId !== requestedLeaseId)) {
+                throw new Error("Canvas session ownership mismatch.");
+            }
+            if (record.document !== undefined) {
+                existing.document = requireCanvasDocument(record.document);
+            }
+            if (record.selection !== undefined) {
+                existing.selection = normalizeSelectionState(record.selection, existing.document.pages[0]?.id ?? null);
+            }
+            existing.previewState = normalizePreviewState(record.previewState) ?? existing.previewState;
+            return existing;
+        }
+        if (!createIfMissing) {
+            throw new Error(`Unknown sessionId: ${sessionId}`);
+        }
+        const document = requireCanvasDocument(record.document);
+        const session = {
+            id: sessionId,
+            ownerClientId: clientId,
+            leaseId: requestedLeaseId ?? createCoordinatorId(),
+            designTabTargetId: null,
+            document,
+            previewState: normalizePreviewState(record.previewState) ?? "background",
+            overlayMounts: parseOverlayMounts(record.overlayMounts),
+            selection: normalizeSelectionState(record.selection, document.pages[0]?.id ?? null)
+        };
+        this.overlaySessions.set(sessionId, session);
         return session;
     }
     requireSessionForMessage(message, record) {
@@ -532,6 +683,9 @@ export class CanvasRuntime {
         }
         return ports.values().next().value ?? null;
     }
+    isDesignTabTarget(session, tabId) {
+        return session.designTabTargetId === formatTargetId(tabId);
+    }
     sendResponse(message, payload) {
         const response = {
             type: "canvas_response",
@@ -540,7 +694,39 @@ export class CanvasRuntime {
             canvasSessionId: message.canvasSessionId,
             payload
         };
-        this.sendEnvelope(response);
+        const serialized = JSON.stringify(payload ?? null);
+        if (this.encoder.encode(serialized).length <= MAX_CANVAS_PAYLOAD_BYTES) {
+            this.sendEnvelope(response);
+            return;
+        }
+        const payloadId = crypto.randomUUID();
+        const chunkSize = Math.max(1024, MAX_CANVAS_PAYLOAD_BYTES - 1024);
+        const chunks = [];
+        for (let i = 0; i < serialized.length; i += chunkSize) {
+            chunks.push(serialized.slice(i, i + chunkSize));
+        }
+        this.sendEnvelope({
+            type: "canvas_response",
+            requestId: message.requestId,
+            clientId: message.clientId,
+            canvasSessionId: message.canvasSessionId,
+            chunked: true,
+            payloadId,
+            totalChunks: chunks.length
+        });
+        chunks.forEach((data, index) => {
+            const chunk = {
+                type: "canvas_chunk",
+                requestId: message.requestId,
+                clientId: message.clientId,
+                canvasSessionId: message.canvasSessionId,
+                payloadId,
+                chunkIndex: index,
+                totalChunks: chunks.length,
+                data
+            };
+            this.sendEnvelope(chunk);
+        });
     }
     sendError(message, error) {
         this.sendEnvelope({
@@ -583,6 +769,7 @@ export class CanvasRuntime {
         this.broadcastCanvasState(parseTargetId(session.designTabTargetId), "canvas-page:update");
     }
     async closeRuntimeSession(session, reason) {
+        this.overlaySessions.delete(session.id);
         const released = [...session.targets.values()];
         for (const target of released) {
             this.broadcastCanvasState(target.tabId, "canvas-page:closed", { reason });
@@ -614,6 +801,16 @@ export class CanvasRuntime {
             });
         });
     }
+    async syncOpsTargetRegistration(session) {
+        const browserSessionId = readBrowserSessionId(session.summary);
+        if (!browserSessionId || !session.designTabTargetId || !this.registerOpsCanvasTarget) {
+            return;
+        }
+        const registered = await this.registerOpsCanvasTarget(browserSessionId, session.designTabTargetId);
+        if (registered?.targetId) {
+            session.designTabTargetId = registered.targetId;
+        }
+    }
 }
 function buildPageState(session, tabId) {
     return {
@@ -666,6 +863,27 @@ function normalizeSelection(value) {
         targetId: typeof value.targetId === "string" || value.targetId === null ? value.targetId : undefined
     };
 }
+function normalizeViewportState(value) {
+    if (!isRecord(value)) {
+        return { ...DEFAULT_EDITOR_VIEWPORT };
+    }
+    return {
+        x: typeof value.x === "number" ? value.x : DEFAULT_EDITOR_VIEWPORT.x,
+        y: typeof value.y === "number" ? value.y : DEFAULT_EDITOR_VIEWPORT.y,
+        zoom: typeof value.zoom === "number" ? value.zoom : DEFAULT_EDITOR_VIEWPORT.zoom
+    };
+}
+function normalizeSelectionState(value, defaultPageId) {
+    if (!isRecord(value)) {
+        return defaultSelection(defaultPageId);
+    }
+    return {
+        pageId: typeof value.pageId === "string" || value.pageId === null ? value.pageId : defaultPageId,
+        nodeId: typeof value.nodeId === "string" || value.nodeId === null ? value.nodeId : null,
+        targetId: typeof value.targetId === "string" || value.targetId === null ? value.targetId : null,
+        updatedAt: typeof value.updatedAt === "string" ? value.updatedAt : new Date().toISOString()
+    };
+}
 function requireCanvasDocument(value) {
     const document = requireRecord(value, "document");
     const pagesValue = Array.isArray(document.pages) ? document.pages : [];
@@ -706,38 +924,198 @@ function requireCanvasDocument(value) {
             })
             : [],
         componentInventory: Array.isArray(document.componentInventory)
-            ? document.componentInventory.filter(isRecord)
+            ? document.componentInventory.flatMap((entry, index) => normalizeComponentInventoryItem(entry, index))
             : [],
-        pages: pagesValue.map((pageValue) => {
-            const page = requireRecord(pageValue, "page");
-            const nodesValue = Array.isArray(page.nodes) ? page.nodes : [];
-            return {
-                id: requireString(page.id, "page.id"),
-                name: optionalString(page.name) ?? requireString(page.id, "page.id"),
-                path: optionalString(page.path) ?? "/",
-                rootNodeId: optionalString(page.rootNodeId) ?? null,
-                prototypeIds: Array.isArray(page.prototypeIds) ? page.prototypeIds.filter((entry) => typeof entry === "string") : [],
-                nodes: nodesValue.map((nodeValue) => {
-                    const node = requireRecord(nodeValue, "node");
-                    return {
-                        id: requireString(node.id, "node.id"),
-                        kind: optionalString(node.kind) ?? "frame",
-                        name: optionalString(node.name) ?? "node",
-                        pageId: optionalString(node.pageId) ?? undefined,
-                        parentId: optionalString(node.parentId),
-                        childIds: Array.isArray(node.childIds) ? node.childIds.filter((entry) => typeof entry === "string") : [],
-                        rect: normalizeRect(node.rect),
-                        props: isRecord(node.props) ? node.props : {},
-                        style: isRecord(node.style) ? node.style : {},
-                        bindingRefs: isRecord(node.bindingRefs) ? node.bindingRefs : {},
-                        metadata: isRecord(node.metadata) ? node.metadata : {}
-                    };
-                }),
-                metadata: isRecord(page.metadata) ? page.metadata : {}
-            };
-        })
+        tokens: normalizeTokenStore(document.tokens),
+        meta: normalizeDocumentMeta(document.meta),
+        pages: pagesValue.flatMap((pageValue) => normalizePage(pageValue))
+    };
+}
+function normalizePage(value) {
+    if (!isRecord(value) || typeof value.id !== "string") {
+        return [];
+    }
+    const pageId = value.id;
+    return [{
+            id: pageId,
+            name: typeof value.name === "string" ? value.name : pageId,
+            path: typeof value.path === "string" ? value.path : "/",
+            rootNodeId: typeof value.rootNodeId === "string" ? value.rootNodeId : null,
+            prototypeIds: Array.isArray(value.prototypeIds) ? value.prototypeIds.filter((entry) => typeof entry === "string") : [],
+            nodes: Array.isArray(value.nodes) ? value.nodes.flatMap((entry) => normalizeNode(entry, pageId)) : [],
+            metadata: isRecord(value.metadata) ? value.metadata : {}
+        }];
+}
+function normalizeNode(value, pageId) {
+    if (!isRecord(value) || typeof value.id !== "string") {
+        return [];
+    }
+    return [{
+            id: value.id,
+            kind: typeof value.kind === "string" ? value.kind : "frame",
+            name: typeof value.name === "string" ? value.name : value.id,
+            pageId,
+            parentId: typeof value.parentId === "string" ? value.parentId : null,
+            childIds: Array.isArray(value.childIds) ? value.childIds.filter((entry) => typeof entry === "string") : [],
+            rect: isRecord(value.rect) ? {
+                x: typeof value.rect.x === "number" ? value.rect.x : 0,
+                y: typeof value.rect.y === "number" ? value.rect.y : 0,
+                width: typeof value.rect.width === "number" ? value.rect.width : 240,
+                height: typeof value.rect.height === "number" ? value.rect.height : 120
+            } : { x: 0, y: 0, width: 240, height: 120 },
+            props: isRecord(value.props) ? value.props : {},
+            style: isRecord(value.style) ? value.style : {},
+            tokenRefs: isRecord(value.tokenRefs) ? value.tokenRefs : {},
+            bindingRefs: isRecord(value.bindingRefs) ? value.bindingRefs : {},
+            variantPatches: Array.isArray(value.variantPatches) ? value.variantPatches.filter(isRecord) : [],
+            metadata: isRecord(value.metadata) ? value.metadata : {}
+        }];
+}
+function normalizeComponentInventoryItem(value, index) {
+    if (!isRecord(value)) {
+        return [];
+    }
+    const id = optionalString(value.id) ?? `inventory_${index + 1}`;
+    const name = optionalString(value.name) ?? optionalString(value.componentName) ?? id;
+    return [{
+            id,
+            name,
+            componentName: optionalString(value.componentName),
+            sourceKind: optionalString(value.sourceKind),
+            sourceFamily: optionalString(value.sourceFamily) ?? undefined,
+            origin: optionalString(value.origin) ?? undefined,
+            framework: normalizeComponentRef(value.framework),
+            adapter: normalizeComponentRef(value.adapter),
+            plugin: normalizeComponentRef(value.plugin),
+            variants: Array.isArray(value.variants) ? value.variants.filter(isRecord) : [],
+            props: Array.isArray(value.props) ? value.props.filter(isRecord) : [],
+            slots: Array.isArray(value.slots) ? value.slots.filter(isRecord) : [],
+            events: Array.isArray(value.events) ? value.events.filter(isRecord) : [],
+            content: isRecord(value.content) ? value.content : {},
+            metadata: isRecord(value.metadata) ? value.metadata : {}
+        }];
+}
+function normalizeComponentRef(value) {
+    if (!isRecord(value)) {
+        return null;
+    }
+    const id = optionalString(value.id);
+    if (!id) {
+        return null;
+    }
+    return {
+        id,
+        label: optionalString(value.label) ?? optionalString(value.name),
+        packageName: optionalString(value.packageName) ?? undefined,
+        version: optionalString(value.version) ?? undefined,
+        metadata: isRecord(value.metadata) ? value.metadata : {}
+    };
+}
+function normalizeTokenStore(value) {
+    if (!isRecord(value)) {
+        return { values: {}, collections: [], aliases: [], bindings: [], metadata: {} };
+    }
+    const structured = "values" in value || "collections" in value || "aliases" in value || "bindings" in value || "metadata" in value;
+    return {
+        values: structured && isRecord(value.values) ? value.values : structured ? {} : value,
+        collections: Array.isArray(value.collections) ? value.collections.flatMap((entry) => normalizeTokenCollection(entry)) : [],
+        aliases: Array.isArray(value.aliases) ? value.aliases.flatMap((entry) => normalizeTokenAlias(entry)) : [],
+        bindings: Array.isArray(value.bindings) ? value.bindings.flatMap((entry) => normalizeTokenBinding(entry)) : [],
+        metadata: isRecord(value.metadata) ? value.metadata : {}
+    };
+}
+function normalizeTokenCollection(value) {
+    if (!isRecord(value) || typeof value.id !== "string") {
+        return [];
+    }
+    return [{
+            id: value.id,
+            name: typeof value.name === "string" ? value.name : value.id,
+            items: Array.isArray(value.items) ? value.items.flatMap((entry) => normalizeTokenItem(entry)) : [],
+            metadata: isRecord(value.metadata) ? value.metadata : {}
+        }];
+}
+function normalizeTokenItem(value) {
+    if (!isRecord(value) || typeof value.id !== "string" || typeof value.path !== "string") {
+        return [];
+    }
+    return [{
+            id: value.id,
+            path: normalizeTokenPath(value.path),
+            value: value.value,
+            type: typeof value.type === "string" ? value.type : undefined,
+            description: typeof value.description === "string" ? value.description : undefined,
+            modes: Array.isArray(value.modes) ? value.modes.flatMap((entry) => normalizeTokenMode(entry)) : [],
+            metadata: isRecord(value.metadata) ? value.metadata : {}
+        }];
+}
+function normalizeTokenMode(value) {
+    if (!isRecord(value) || typeof value.id !== "string" || typeof value.name !== "string") {
+        return [];
+    }
+    return [{
+            id: value.id,
+            name: value.name,
+            value: value.value,
+            metadata: isRecord(value.metadata) ? value.metadata : {}
+        }];
+}
+function normalizeTokenAlias(value) {
+    if (!isRecord(value) || typeof value.path !== "string" || typeof value.targetPath !== "string") {
+        return [];
+    }
+    return [{
+            path: normalizeTokenPath(value.path),
+            targetPath: normalizeTokenPath(value.targetPath),
+            modeId: typeof value.modeId === "string" ? value.modeId : null,
+            metadata: isRecord(value.metadata) ? value.metadata : {}
+        }];
+}
+function normalizeTokenBinding(value) {
+    if (!isRecord(value) || typeof value.path !== "string") {
+        return [];
+    }
+    return [{
+            path: normalizeTokenPath(value.path),
+            nodeId: typeof value.nodeId === "string" ? value.nodeId : null,
+            bindingId: typeof value.bindingId === "string" ? value.bindingId : null,
+            property: typeof value.property === "string" ? value.property : null,
+            metadata: isRecord(value.metadata) ? value.metadata : {}
+        }];
+}
+function normalizeTokenPath(path) {
+    return path.trim().replace(/^tokens\./, "");
+}
+function normalizeDocumentMeta(value) {
+    if (!isRecord(value)) {
+        return { imports: [], starter: null, adapterPlugins: [], pluginErrors: [], metadata: {} };
+    }
+    return {
+        imports: Array.isArray(value.imports) ? value.imports.filter(isRecord) : [],
+        starter: isRecord(value.starter) ? value.starter : null,
+        adapterPlugins: Array.isArray(value.adapterPlugins) ? value.adapterPlugins.filter(isRecord) : [],
+        pluginErrors: Array.isArray(value.pluginErrors)
+            ? value.pluginErrors.flatMap((entry) => normalizePluginError(entry))
+            : [],
+        metadata: isRecord(value.metadata) ? value.metadata : {}
     };
 }
+function normalizePluginError(value) {
+    if (!isRecord(value)) {
+        return [];
+    }
+    const code = optionalString(value.code);
+    const message = optionalString(value.message);
+    if (!code || !message) {
+        return [];
+    }
+    return [{
+            pluginId: optionalString(value.pluginId),
+            code,
+            message,
+            details: isRecord(value.details) ? value.details : {}
+        }];
+}
 function requireRenderedHtml(record) {
     return requireString(record.html, "html");
 }
@@ -849,6 +1227,47 @@ function dedupeOverlayMounts(mounts) {
     }
     return [...byId.values()];
 }
+function resolveDesignTabOverlaySelection(document, nodeId, selectionHint) {
+    const selector = typeof selectionHint.selector === "string" && selectionHint.selector.trim().length > 0
+        ? selectionHint.selector.trim()
+        : null;
+    const resolvedNodeId = nodeId
+        ?? readNodeIdFromSelector(selector)
+        ?? null;
+    if (!resolvedNodeId) {
+        return { matched: false, selector };
+    }
+    const node = findDocumentNode(document, resolvedNodeId);
+    if (!node) {
+        return { matched: false, selector: selector ?? `[data-node-id="${resolvedNodeId}"]` };
+    }
+    const text = typeof node.props.text === "string" ? node.props.text : null;
+    return {
+        matched: true,
+        selector: selector ?? `[data-node-id="${resolvedNodeId}"]`,
+        nodeId: resolvedNodeId,
+        tagName: "div",
+        text: text ? text.slice(0, 160) : "",
+        id: null,
+        className: "canvas-stage-node"
+    };
+}
+function readNodeIdFromSelector(selector) {
+    if (!selector) {
+        return null;
+    }
+    const match = selector.match(/^\[data-node-id=["']([^"'\\]]+)["']\]$/);
+    return match?.[1] ?? null;
+}
+function findDocumentNode(document, nodeId) {
+    for (const page of document.pages) {
+        const node = page.nodes.find((entry) => entry.id === nodeId);
+        if (node) {
+            return node;
+        }
+    }
+    return null;
+}
 function requireRecord(value, label) {
     if (!value || typeof value !== "object" || Array.isArray(value)) {
         throw new Error(`Invalid ${label}`);
@@ -861,6 +1280,12 @@ function resolveCanvasSessionId(message, payload) {
         ?? optionalString(isRecord(payload.summary) ? payload.summary.canvasSessionId : undefined)
         ?? createCoordinatorId();
 }
+function readBrowserSessionId(summary) {
+    if (!summary) {
+        return null;
+    }
+    return optionalString(summary.browserSessionId);
+}
 function resolveSessionForMessage(sessions, message, payload) {
     const directId = optionalString(message.canvasSessionId)
         ?? optionalString(payload.canvasSessionId)
@@ -880,6 +1305,10 @@ function resolveSessionForMessage(sessions, message, payload) {
 function missingCanvasSession() {
     return new Error("Missing canvasSessionId");
 }
+function isIgnorableCanvasCloseLookupError(error) {
+    const message = error instanceof Error ? error.message : String(error ?? "");
+    return message.includes("Unknown sessionId:") || message === "Missing canvasSessionId";
+}
 function isRecord(value) {
     return Boolean(value) && typeof value === "object" && !Array.isArray(value);
 }