opendevbrowser 0.0.16 → 0.0.17

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

@@ -0,0 +1,1061 @@
+import { CANVAS_PROTOCOL_VERSION, MAX_CANVAS_PAYLOAD_BYTES } from "../types.js";
+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";
+const OVERLAY_STYLE = `
+#opendevbrowser-canvas-style,
+.opendevbrowser-canvas-highlight {
+  box-sizing: border-box;
+}
+.opendevbrowser-canvas-highlight {
+  outline: 2px solid #20d5c6 !important;
+  outline-offset: 3px !important;
+}
+.opendevbrowser-canvas-overlay {
+  position: fixed;
+  top: 16px;
+  right: 16px;
+  z-index: 2147483647;
+  max-width: 320px;
+  padding: 12px 14px;
+  border-radius: 14px;
+  border: 1px solid rgba(255,255,255,0.16);
+  background: rgba(7,17,29,0.92);
+  color: #f3f6fb;
+  font: 12px/1.4 "Segoe UI", sans-serif;
+  box-shadow: 0 18px 40px rgba(0,0,0,0.3);
+}
+.opendevbrowser-canvas-overlay strong {
+  display: block;
+  margin-bottom: 4px;
+}
+`;
+export class CanvasRuntime {
+    sendEnvelope;
+    tabs = new TabManager();
+    sessions = new TargetSessionCoordinator();
+    pagePorts = new Map();
+    pendingPageActions = new Map();
+    constructor(options) {
+        this.sendEnvelope = options.send;
+    }
+    attachPort(port) {
+        if (port.name !== "canvas-page") {
+            return;
+        }
+        const tabId = port.sender?.tab?.id;
+        if (typeof tabId !== "number") {
+            port.disconnect();
+            return;
+        }
+        let ports = this.pagePorts.get(tabId);
+        if (!ports) {
+            ports = new Set();
+            this.pagePorts.set(tabId, ports);
+        }
+        ports.add(port);
+        port.onDisconnect.addListener(() => {
+            const current = this.pagePorts.get(tabId);
+            current?.delete(port);
+            if (current && current.size === 0) {
+                this.pagePorts.delete(tabId);
+            }
+            for (const [requestId, pending] of this.pendingPageActions.entries()) {
+                if (pending.tabId !== tabId) {
+                    continue;
+                }
+                clearTimeout(pending.timeoutId);
+                pending.reject(new Error("Canvas page disconnected before action completed."));
+                this.pendingPageActions.delete(requestId);
+            }
+        });
+        port.onMessage.addListener((message) => {
+            const record = isRecord(message) ? message : null;
+            if (!record) {
+                return;
+            }
+            this.handlePagePortMessage(tabId, record);
+        });
+        this.postCanvasState(port, this.getPageStateByTabId(tabId), "canvas-page:init");
+    }
+    getPageStateByTargetId(targetId) {
+        try {
+            return this.getPageStateByTabId(parseTargetId(targetId));
+        }
+        catch {
+            return null;
+        }
+    }
+    async performPageAction(targetId, action, selector, timeoutMs = 2500) {
+        const tabId = parseTargetId(targetId);
+        const port = await this.waitForPagePort(tabId, timeoutMs);
+        return await new Promise((resolve, reject) => {
+            const requestId = crypto.randomUUID();
+            const timeoutId = setTimeout(() => {
+                this.pendingPageActions.delete(requestId);
+                reject(new Error("Canvas page action timed out."));
+            }, timeoutMs);
+            this.pendingPageActions.set(requestId, { tabId, resolve, reject, timeoutId });
+            try {
+                port.postMessage({
+                    type: "canvas-page-action-request",
+                    requestId,
+                    selector: selector ?? null,
+                    action
+                });
+            }
+            catch (error) {
+                clearTimeout(timeoutId);
+                this.pendingPageActions.delete(requestId);
+                reject(error instanceof Error ? error : new Error("Canvas page action failed."));
+            }
+        });
+    }
+    handleMessage(message) {
+        if (message.type === "canvas_hello") {
+            this.handleHello(message);
+            return;
+        }
+        if (message.type === "canvas_ping") {
+            this.handlePing(message);
+            return;
+        }
+        if (message.type === "canvas_event" && message.event === "canvas_client_disconnected") {
+            this.handleClientDisconnected(message);
+            return;
+        }
+        if (message.type === "canvas_request") {
+            void this.handleRequest(message).catch((error) => {
+                logError("canvas.handle_request", error, { code: "canvas_request_failed", extra: { command: message.command } });
+                this.sendError(message, normalizeCanvasError(error));
+            });
+        }
+    }
+    handleHello(message) {
+        if (message.version !== CANVAS_PROTOCOL_VERSION) {
+            this.sendError({ requestId: "canvas_hello", clientId: message.clientId, canvasSessionId: undefined }, {
+                code: "not_supported",
+                message: "Unsupported canvas protocol version.",
+                retryable: false,
+                details: { supported: [CANVAS_PROTOCOL_VERSION], received: message.version }
+            });
+            return;
+        }
+        const ack = {
+            type: "canvas_hello_ack",
+            version: CANVAS_PROTOCOL_VERSION,
+            clientId: message.clientId,
+            maxPayloadBytes: MAX_CANVAS_PAYLOAD_BYTES,
+            capabilities: [
+                "canvas.tab.open",
+                "canvas.tab.close",
+                "canvas.tab.sync",
+                "canvas.overlay.mount",
+                "canvas.overlay.unmount",
+                "canvas.overlay.select",
+                "canvas.overlay.sync"
+            ]
+        };
+        this.sendEnvelope(ack);
+    }
+    handlePing(message) {
+        const pong = {
+            type: "canvas_pong",
+            id: message.id,
+            clientId: message.clientId
+        };
+        this.sendEnvelope(pong);
+    }
+    handleClientDisconnected(message) {
+        const clientId = message.clientId;
+        if (!clientId) {
+            return;
+        }
+        for (const session of this.sessions.listOwnedBy(clientId)) {
+            void this.closeRuntimeSession(session, "client_disconnected");
+        }
+    }
+    handlePagePortMessage(tabId, message) {
+        if (message.type === "canvas-page-action-response") {
+            const pending = this.pendingPageActions.get(message.requestId);
+            if (!pending) {
+                return;
+            }
+            clearTimeout(pending.timeoutId);
+            this.pendingPageActions.delete(message.requestId);
+            if (message.ok) {
+                pending.resolve(message.value);
+            }
+            else {
+                pending.reject(new Error(message.error || "Canvas page action failed."));
+            }
+            return;
+        }
+        const session = this.sessions.getByTabId(tabId);
+        if (message.type === "canvas-page-ready" || message.type === "canvas-page-request-state") {
+            this.broadcastCanvasState(tabId, "canvas-page:init");
+            return;
+        }
+        if (!session) {
+            return;
+        }
+        if (message.type === "canvas-page-view-state") {
+            this.mergeEditorState(session, message.viewport, message.selection);
+            this.broadcastCanvasState(tabId, "canvas-page:update");
+            return;
+        }
+        if (message.type === "canvas-page-patch-request") {
+            if (!Array.isArray(message.patches) || message.patches.length === 0 || typeof message.baseRevision !== "number") {
+                return;
+            }
+            this.mergeEditorState(session, undefined, message.selection);
+            session.pendingMutation = true;
+            this.broadcastCanvasState(tabId, "canvas-page:update");
+            this.sendEvent({
+                type: "canvas_event",
+                clientId: session.ownerClientId,
+                canvasSessionId: session.id,
+                event: "canvas_patch_requested",
+                payload: {
+                    targetId: session.designTabTargetId,
+                    documentId: session.document.documentId,
+                    baseRevision: message.baseRevision,
+                    patches: message.patches,
+                    selection: session.selection
+                }
+            });
+        }
+    }
+    async handleRequest(message) {
+        switch (message.command) {
+            case "canvas.tab.open":
+                this.sendResponse(message, await this.openTab(message));
+                return;
+            case "canvas.tab.close":
+                this.sendResponse(message, await this.closeTab(message));
+                return;
+            case "canvas.tab.sync":
+                this.sendResponse(message, await this.syncTab(message));
+                return;
+            case "canvas.overlay.mount":
+                this.sendResponse(message, await this.mountOverlay(message));
+                return;
+            case "canvas.overlay.unmount":
+                this.sendResponse(message, await this.unmountOverlay(message));
+                return;
+            case "canvas.overlay.select":
+                this.sendResponse(message, await this.selectOverlay(message));
+                return;
+            case "canvas.overlay.sync":
+                this.sendResponse(message, await this.syncOverlay(message));
+                return;
+            default:
+                this.sendError(message, {
+                    code: "not_supported",
+                    message: `Unsupported canvas command: ${message.command}`,
+                    retryable: false
+                });
+        }
+    }
+    async openTab(message) {
+        const record = requireRecord(message.payload, "payload");
+        const document = requireCanvasDocument(record.document);
+        const previewMode = requireEnum(record.previewMode, "previewMode", ["focused", "pinned", "background"]);
+        const tab = await this.createTab(chrome.runtime.getURL("canvas.html"), previewMode);
+        const tabId = requireTabId(tab);
+        const session = this.createOrReplaceSession(message, tabId, document, previewMode, record);
+        this.broadcastCanvasState(tabId, "canvas-page:init");
+        this.sendEvent({
+            type: "canvas_event",
+            clientId: message.clientId,
+            canvasSessionId: session.id,
+            event: "canvas_session_created",
+            payload: { tabId, targetId: session.designTabTargetId }
+        });
+        return {
+            targetId: session.designTabTargetId,
+            previewState: session.previewState
+        };
+    }
+    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);
+        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);
+        await this.tabs.closeTab(tabId);
+        this.sendEvent({
+            type: "canvas_event",
+            clientId: session.ownerClientId,
+            canvasSessionId: session.id,
+            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,
+            targetIds: [...session.targets.keys()],
+            releasedTargetIds: [targetId],
+            previewState: "background"
+        };
+    }
+    async syncTab(message) {
+        const session = this.requireSessionForMessage(message);
+        const record = requireRecord(message.payload, "payload");
+        const tabId = parseTargetId(requireString(record.targetId, "targetId"));
+        const existingTab = await this.tabs.getTab(tabId);
+        if (!existingTab) {
+            throw new Error(`Canvas target is unavailable: ${tabId}`);
+        }
+        const summary = normalizeCanvasSessionSummary(record.summary);
+        session.document = requireCanvasDocument(record.document);
+        session.documentRevision = optionalNumber(record.documentRevision);
+        session.html = requireRenderedHtml(record);
+        session.summary = summary;
+        session.previewTargets = normalizeCanvasTargetStateSummaries(record.targets ?? summary.targets);
+        session.overlayMounts = parseOverlayMounts(record.overlayMounts ?? summary.overlayMounts);
+        session.feedback = parseFeedbackEvents(record.feedback);
+        session.feedbackCursor = optionalString(record.feedbackCursor) ?? lastFeedbackCursor(session.feedback);
+        session.pendingMutation = false;
+        this.mergeEditorState(session, normalizeViewport(record.viewport), normalizeSelection(record.selection));
+        session.previewState = normalizePreviewState(record.previewState) ?? session.previewState;
+        session.previewMode = normalizePreviewState(record.previewMode) ?? session.previewMode;
+        this.broadcastCanvasState(tabId, "canvas-page:update");
+        return {
+            ok: true,
+            targetId: formatTargetId(tabId),
+            previewState: session.previewState
+        };
+    }
+    async mountOverlay(message) {
+        const session = this.requireSessionForMessage(message);
+        const record = requireRecord(message.payload, "payload");
+        const tabId = parseTargetId(requireString(record.targetId, "targetId"));
+        const prototypeId = optionalString(record.prototypeId) ?? "default";
+        await insertCss(tabId, OVERLAY_STYLE);
+        const mountId = `mount_${crypto.randomUUID()}`;
+        const result = await executeInTab(tabId, mountOverlayScript, [{
+                mountId,
+                cssText: OVERLAY_STYLE,
+                title: session.document.title,
+                prototypeId,
+                selection: session.selection
+            }]);
+        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: "background",
+            overlayState: result?.previewState ?? "mounted",
+            capabilities: { selection: true, guides: true }
+        };
+    }
+    async unmountOverlay(message) {
+        const session = this.requireSessionForMessage(message);
+        const record = requireRecord(message.payload, "payload");
+        const mountId = requireString(record.mountId, "mountId");
+        const tabId = parseTargetId(requireString(record.targetId, "targetId"));
+        await executeInTab(tabId, unmountOverlayScript, [mountId]);
+        session.overlayMounts = session.overlayMounts.filter((mount) => mount.mountId !== mountId);
+        this.broadcastIfDesignTab(session);
+        return {
+            ok: true,
+            mountId,
+            previewState: "background",
+            overlayState: "idle"
+        };
+    }
+    async selectOverlay(message) {
+        const session = this.requireSessionForMessage(message);
+        const record = requireRecord(message.payload, "payload");
+        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") {
+            session.selection = {
+                pageId: session.document.pages[0]?.id ?? null,
+                nodeId,
+                targetId: formatTargetId(tabId),
+                updatedAt: new Date().toISOString()
+            };
+            this.broadcastIfDesignTab(session);
+        }
+        return {
+            targetId: formatTargetId(tabId),
+            selection
+        };
+    }
+    async syncOverlay(message) {
+        const session = this.requireSessionForMessage(message);
+        const record = requireRecord(message.payload, "payload");
+        const tabId = parseTargetId(requireString(record.targetId, "targetId"));
+        const mountId = requireString(record.mountId, "mountId");
+        await insertCss(tabId, OVERLAY_STYLE);
+        const result = await executeInTab(tabId, syncOverlayScript, [{
+                mountId,
+                title: session.document.title,
+                selection: session.selection
+            }]);
+        return {
+            ok: true,
+            mountId,
+            targetId: formatTargetId(tabId),
+            overlayState: result?.overlayState ?? "mounted"
+        };
+    }
+    createOrReplaceSession(message, tabId, document, previewMode, record) {
+        const canvasSessionId = resolveCanvasSessionId(message, record);
+        const clientId = requireString(message.clientId, "clientId");
+        const requestedLeaseId = optionalString(message.leaseId);
+        const summary = normalizeCanvasSessionSummary(record.summary);
+        const existing = this.sessions.get(canvasSessionId);
+        if (existing) {
+            if (existing.ownerClientId !== clientId || (requestedLeaseId && existing.leaseId !== requestedLeaseId)) {
+                throw new Error("Canvas session ownership mismatch.");
+            }
+            if (existing.designTabTargetId && existing.designTabTargetId !== formatTargetId(tabId)) {
+                void this.tabs.closeTab(parseTargetId(existing.designTabTargetId)).catch(() => undefined);
+            }
+            existing.designTabTargetId = formatTargetId(tabId);
+            existing.document = document;
+            existing.documentRevision = optionalNumber(record.documentRevision);
+            existing.html = requireRenderedHtml(record);
+            existing.summary = summary;
+            existing.previewTargets = normalizeCanvasTargetStateSummaries(record.targets ?? summary.targets);
+            existing.overlayMounts = parseOverlayMounts(record.overlayMounts ?? summary.overlayMounts);
+            existing.feedback = parseFeedbackEvents(record.feedback);
+            existing.feedbackCursor = optionalString(record.feedbackCursor) ?? lastFeedbackCursor(existing.feedback);
+            existing.previewMode = previewMode;
+            existing.previewState = previewMode;
+            existing.pendingMutation = false;
+            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 session = this.sessions.createSession(clientId, tabId, leaseId, {
+            title: document.title,
+            url: chrome.runtime.getURL("canvas.html")
+        }, {
+            designTabTargetId: formatTargetId(tabId),
+            document,
+            documentRevision: optionalNumber(record.documentRevision),
+            html: requireRenderedHtml(record),
+            summary,
+            previewMode,
+            previewState: previewMode,
+            previewTargets: normalizeCanvasTargetStateSummaries(record.targets ?? summary.targets),
+            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 },
+            pendingMutation: false
+        }, canvasSessionId);
+        return session;
+    }
+    requireSessionForMessage(message, record) {
+        const payload = record ?? (isRecord(message.payload) ? message.payload : {});
+        const session = resolveSessionForMessage(this.sessions, message, payload);
+        const clientId = requireString(message.clientId, "clientId");
+        const leaseId = optionalString(message.leaseId);
+        if (session.ownerClientId !== clientId || (leaseId && session.leaseId !== leaseId)) {
+            throw new Error("Canvas session ownership mismatch.");
+        }
+        return session;
+    }
+    mergeEditorState(session, viewport, selection) {
+        if (viewport) {
+            session.viewport = {
+                x: typeof viewport.x === "number" ? viewport.x : session.viewport.x,
+                y: typeof viewport.y === "number" ? viewport.y : session.viewport.y,
+                zoom: typeof viewport.zoom === "number" && Number.isFinite(viewport.zoom) ? viewport.zoom : session.viewport.zoom
+            };
+        }
+        if (selection) {
+            session.selection = {
+                pageId: typeof selection.pageId === "string" ? selection.pageId : session.selection.pageId,
+                nodeId: typeof selection.nodeId === "string" || selection.nodeId === null ? selection.nodeId : session.selection.nodeId,
+                targetId: typeof selection.targetId === "string" || selection.targetId === null ? selection.targetId : session.selection.targetId,
+                updatedAt: new Date().toISOString()
+            };
+        }
+    }
+    getPageStateByTabId(tabId) {
+        const session = this.sessions.getByTabId(tabId);
+        if (!session || !session.designTabTargetId) {
+            return null;
+        }
+        return buildPageState(session, tabId);
+    }
+    async waitForPagePort(tabId, timeoutMs) {
+        const existing = this.firstConnectedPagePort(tabId);
+        if (existing) {
+            return existing;
+        }
+        const startedAt = Date.now();
+        while (Date.now() - startedAt < timeoutMs) {
+            await delay(50);
+            const next = this.firstConnectedPagePort(tabId);
+            if (next) {
+                return next;
+            }
+        }
+        throw new Error("Canvas page port unavailable.");
+    }
+    firstConnectedPagePort(tabId) {
+        const ports = this.pagePorts.get(tabId);
+        if (!ports || ports.size === 0) {
+            return null;
+        }
+        return ports.values().next().value ?? null;
+    }
+    sendResponse(message, payload) {
+        const response = {
+            type: "canvas_response",
+            requestId: message.requestId,
+            clientId: message.clientId,
+            canvasSessionId: message.canvasSessionId,
+            payload
+        };
+        this.sendEnvelope(response);
+    }
+    sendError(message, error) {
+        this.sendEnvelope({
+            type: "canvas_error",
+            requestId: message.requestId,
+            clientId: message.clientId,
+            canvasSessionId: message.canvasSessionId,
+            error
+        });
+    }
+    sendEvent(event) {
+        this.sendEnvelope(event);
+    }
+    postCanvasState(port, state, type, extra = {}) {
+        try {
+            port.postMessage({
+                type,
+                state,
+                ...extra
+            });
+        }
+        catch {
+            // ignore disconnected page ports
+        }
+    }
+    broadcastCanvasState(tabId, type, extra = {}) {
+        const ports = this.pagePorts.get(tabId);
+        if (!ports || ports.size === 0) {
+            return;
+        }
+        const state = this.getPageStateByTabId(tabId);
+        for (const port of ports) {
+            this.postCanvasState(port, state, type, extra);
+        }
+    }
+    broadcastIfDesignTab(session) {
+        if (!session.designTabTargetId) {
+            return;
+        }
+        this.broadcastCanvasState(parseTargetId(session.designTabTargetId), "canvas-page:update");
+    }
+    async closeRuntimeSession(session, reason) {
+        const released = [...session.targets.values()];
+        for (const target of released) {
+            this.broadcastCanvasState(target.tabId, "canvas-page:closed", { reason });
+            await this.tabs.closeTab(target.tabId).catch(() => undefined);
+            this.pagePorts.delete(target.tabId);
+        }
+        this.sessions.delete(session.id);
+        this.sendEvent({
+            type: "canvas_event",
+            clientId: session.ownerClientId,
+            canvasSessionId: session.id,
+            event: "canvas_session_expired",
+            payload: { reason }
+        });
+    }
+    async createTab(url, previewMode) {
+        return await new Promise((resolve, reject) => {
+            chrome.tabs.create({ url, active: previewMode === "focused", pinned: previewMode === "pinned" }, (tab) => {
+                const lastError = chrome.runtime.lastError;
+                if (lastError) {
+                    reject(new Error(lastError.message));
+                    return;
+                }
+                if (!tab || typeof tab.id !== "number") {
+                    reject(new Error("Canvas tab creation failed"));
+                    return;
+                }
+                resolve(tab);
+            });
+        });
+    }
+}
+function buildPageState(session, tabId) {
+    return {
+        tabId,
+        targetId: formatTargetId(tabId),
+        canvasSessionId: session.id,
+        documentId: session.document.documentId,
+        documentRevision: session.documentRevision,
+        title: session.document.title,
+        document: session.document,
+        html: session.html,
+        previewMode: session.previewMode,
+        previewState: session.previewState,
+        updatedAt: new Date().toISOString(),
+        summary: session.summary,
+        targets: session.previewTargets,
+        overlayMounts: session.overlayMounts,
+        feedback: session.feedback,
+        feedbackCursor: session.feedbackCursor,
+        selection: session.selection,
+        viewport: session.viewport,
+        pendingMutation: session.pendingMutation
+    };
+}
+function defaultSelection(pageId) {
+    return {
+        pageId,
+        nodeId: null,
+        targetId: null,
+        updatedAt: new Date().toISOString()
+    };
+}
+function normalizeViewport(value) {
+    if (!isRecord(value)) {
+        return null;
+    }
+    return {
+        x: typeof value.x === "number" ? value.x : undefined,
+        y: typeof value.y === "number" ? value.y : undefined,
+        zoom: typeof value.zoom === "number" ? value.zoom : undefined
+    };
+}
+function normalizeSelection(value) {
+    if (!isRecord(value)) {
+        return null;
+    }
+    return {
+        pageId: typeof value.pageId === "string" || value.pageId === null ? value.pageId : undefined,
+        nodeId: typeof value.nodeId === "string" || value.nodeId === null ? value.nodeId : undefined,
+        targetId: typeof value.targetId === "string" || value.targetId === null ? value.targetId : undefined
+    };
+}
+function requireCanvasDocument(value) {
+    const document = requireRecord(value, "document");
+    const pagesValue = Array.isArray(document.pages) ? document.pages : [];
+    return {
+        documentId: requireString(document.documentId, "documentId"),
+        title: optionalString(document.title) ?? "OpenDevBrowser Canvas",
+        updatedAt: optionalString(document.updatedAt) ?? undefined,
+        bindings: Array.isArray(document.bindings)
+            ? document.bindings.flatMap((bindingValue) => {
+                const binding = isRecord(bindingValue) ? bindingValue : null;
+                if (!binding || typeof binding.id !== "string" || typeof binding.nodeId !== "string") {
+                    return [];
+                }
+                return [{
+                        id: binding.id,
+                        nodeId: binding.nodeId,
+                        kind: optionalString(binding.kind) ?? "component",
+                        componentName: optionalString(binding.componentName) ?? undefined,
+                        metadata: isRecord(binding.metadata) ? binding.metadata : {}
+                    }];
+            })
+            : [],
+        assets: Array.isArray(document.assets)
+            ? document.assets.flatMap((assetValue) => {
+                const asset = isRecord(assetValue) ? assetValue : null;
+                if (!asset || typeof asset.id !== "string") {
+                    return [];
+                }
+                return [{
+                        id: asset.id,
+                        sourceType: optionalString(asset.sourceType) ?? undefined,
+                        kind: optionalString(asset.kind) ?? undefined,
+                        repoPath: optionalString(asset.repoPath),
+                        url: optionalString(asset.url),
+                        mime: optionalString(asset.mime) ?? undefined,
+                        metadata: isRecord(asset.metadata) ? asset.metadata : {}
+                    }];
+            })
+            : [],
+        componentInventory: Array.isArray(document.componentInventory)
+            ? document.componentInventory.filter(isRecord)
+            : [],
+        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 : {}
+            };
+        })
+    };
+}
+function requireRenderedHtml(record) {
+    return requireString(record.html, "html");
+}
+function normalizeRect(value) {
+    if (!isRecord(value)) {
+        return { x: 0, y: 0, width: 320, height: 180 };
+    }
+    return {
+        x: typeof value.x === "number" ? value.x : 0,
+        y: typeof value.y === "number" ? value.y : 0,
+        width: typeof value.width === "number" ? value.width : 320,
+        height: typeof value.height === "number" ? value.height : 180
+    };
+}
+function parseOverlayMounts(value) {
+    if (!Array.isArray(value)) {
+        return [];
+    }
+    return value.flatMap((entry) => {
+        if (!isRecord(entry)) {
+            return [];
+        }
+        const mountId = optionalString(entry.mountId);
+        const targetId = optionalString(entry.targetId);
+        const mountedAt = optionalString(entry.mountedAt);
+        return mountId && targetId && mountedAt
+            ? [{ mountId, targetId, mountedAt }]
+            : [];
+    });
+}
+function parseFeedbackEvents(value) {
+    if (!Array.isArray(value)) {
+        return [];
+    }
+    const events = [];
+    for (const entry of value) {
+        if (!isRecord(entry)) {
+            continue;
+        }
+        if (entry.eventType === "feedback.item" && isRecord(entry.item)) {
+            const item = entry.item;
+            const id = optionalString(item.id);
+            const cursor = optionalString(item.cursor);
+            const documentId = optionalString(item.documentId);
+            if (!id || !cursor || !documentId) {
+                continue;
+            }
+            events.push({
+                eventType: "feedback.item",
+                item: {
+                    id,
+                    cursor,
+                    category: optionalString(item.category) ?? "validation",
+                    class: optionalString(item.class) ?? "feedback",
+                    severity: optionalString(item.severity) ?? "info",
+                    message: optionalString(item.message) ?? "",
+                    documentId,
+                    documentRevision: typeof item.documentRevision === "number" ? item.documentRevision : 0,
+                    pageId: optionalString(item.pageId),
+                    prototypeId: optionalString(item.prototypeId),
+                    targetId: optionalString(item.targetId),
+                    evidenceRefs: Array.isArray(item.evidenceRefs) ? item.evidenceRefs.filter((ref) => typeof ref === "string") : [],
+                    details: isRecord(item.details) ? item.details : {}
+                }
+            });
+            continue;
+        }
+        if (entry.eventType === "feedback.heartbeat") {
+            events.push({
+                eventType: "feedback.heartbeat",
+                cursor: optionalString(entry.cursor),
+                ts: optionalString(entry.ts) ?? new Date().toISOString(),
+                activeTargetIds: Array.isArray(entry.activeTargetIds) ? entry.activeTargetIds.filter((id) => typeof id === "string") : []
+            });
+            continue;
+        }
+        if (entry.eventType === "feedback.complete") {
+            const reason = optionalString(entry.reason);
+            if (!reason) {
+                continue;
+            }
+            events.push({
+                eventType: "feedback.complete",
+                cursor: optionalString(entry.cursor),
+                ts: optionalString(entry.ts) ?? new Date().toISOString(),
+                reason: reason
+            });
+            continue;
+        }
+    }
+    return events;
+}
+function lastFeedbackCursor(events) {
+    for (let index = events.length - 1; index >= 0; index -= 1) {
+        const entry = events[index];
+        if (entry?.eventType === "feedback.item") {
+            return entry.item.cursor;
+        }
+        if (entry?.eventType === "feedback.heartbeat" || entry?.eventType === "feedback.complete") {
+            return entry.cursor;
+        }
+    }
+    return null;
+}
+function dedupeOverlayMounts(mounts) {
+    const byId = new Map();
+    for (const mount of mounts) {
+        byId.set(mount.mountId, mount);
+    }
+    return [...byId.values()];
+}
+function requireRecord(value, label) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new Error(`Invalid ${label}`);
+    }
+    return value;
+}
+function resolveCanvasSessionId(message, payload) {
+    return optionalString(message.canvasSessionId)
+        ?? optionalString(payload.canvasSessionId)
+        ?? optionalString(isRecord(payload.summary) ? payload.summary.canvasSessionId : undefined)
+        ?? createCoordinatorId();
+}
+function resolveSessionForMessage(sessions, message, payload) {
+    const directId = optionalString(message.canvasSessionId)
+        ?? optionalString(payload.canvasSessionId)
+        ?? optionalString(isRecord(payload.summary) ? payload.summary.canvasSessionId : undefined);
+    if (directId) {
+        return sessions.requireSession(directId);
+    }
+    const targetId = optionalString(payload.targetId);
+    if (targetId) {
+        const session = sessions.getByTabId(parseTargetId(targetId));
+        if (session) {
+            return session;
+        }
+    }
+    throw missingCanvasSession();
+}
+function missingCanvasSession() {
+    return new Error("Missing canvasSessionId");
+}
+function isRecord(value) {
+    return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+function requireString(value, label) {
+    if (typeof value !== "string" || value.trim().length === 0) {
+        throw new Error(`Missing ${label}`);
+    }
+    return value;
+}
+function optionalString(value) {
+    return typeof value === "string" && value.trim().length > 0 ? value : null;
+}
+function optionalNumber(value) {
+    return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+function requireEnum(value, label, allowed) {
+    if (typeof value !== "string" || !allowed.includes(value)) {
+        throw new Error(`Invalid ${label}`);
+    }
+    return value;
+}
+function normalizePreviewState(value) {
+    return value === "focused" || value === "pinned" || value === "background" || value === "degraded"
+        ? value
+        : null;
+}
+function parseTargetId(targetId) {
+    const raw = targetId.startsWith("tab-") ? targetId.slice(4) : targetId;
+    const tabId = Number(raw);
+    if (!Number.isInteger(tabId) || tabId <= 0) {
+        throw new Error(`Invalid targetId: ${targetId}`);
+    }
+    return tabId;
+}
+function formatTargetId(tabId) {
+    if (!Number.isInteger(tabId)) {
+        throw new Error("Tab id unavailable");
+    }
+    return `tab-${tabId}`;
+}
+function requireTabId(tab) {
+    const tabId = tab.id;
+    if (typeof tabId !== "number" || !Number.isInteger(tabId)) {
+        throw new Error("Canvas tab creation failed");
+    }
+    return tabId;
+}
+async function insertCss(tabId, css) {
+    await new Promise((resolve, reject) => {
+        chrome.scripting.insertCSS({ target: { tabId }, css }, () => {
+            const lastError = chrome.runtime.lastError;
+            if (lastError) {
+                reject(new Error(lastError.message));
+                return;
+            }
+            resolve();
+        });
+    });
+}
+async function executeInTab(tabId, func, args) {
+    return await new Promise((resolve, reject) => {
+        chrome.scripting.executeScript({ target: { tabId }, func: func, args }, (results) => {
+            const lastError = chrome.runtime.lastError;
+            if (lastError) {
+                reject(new Error(lastError.message));
+                return;
+            }
+            const [first] = results ?? [];
+            resolve((first?.result ?? null));
+        });
+    });
+}
+function mountOverlayScript(input) {
+    const styleId = "opendevbrowser-canvas-style";
+    if (!document.getElementById(styleId)) {
+        const style = document.createElement("style");
+        style.id = styleId;
+        style.textContent = input.cssText;
+        document.head.append(style);
+    }
+    document.getElementById(input.mountId)?.remove();
+    const root = document.createElement("div");
+    root.id = input.mountId;
+    root.className = "opendevbrowser-canvas-overlay";
+    const heading = document.createElement("strong");
+    heading.textContent = input.title;
+    const detail = document.createElement("div");
+    detail.textContent = input.selection.nodeId ? `Selected ${input.selection.nodeId}` : input.prototypeId;
+    root.append(heading, detail);
+    document.body.append(root);
+    if (input.selection.nodeId) {
+        const element = document.querySelector(`[data-node-id="${input.selection.nodeId}"]`);
+        if (element instanceof HTMLElement) {
+            element.classList.add("opendevbrowser-canvas-highlight");
+        }
+    }
+    return { previewState: "overlay_mounted" };
+}
+function unmountOverlayScript(mountId) {
+    document.getElementById(mountId)?.remove();
+    document.querySelectorAll(".opendevbrowser-canvas-highlight").forEach((element) => {
+        element.classList.remove("opendevbrowser-canvas-highlight");
+    });
+    return true;
+}
+function selectOverlayScript(input) {
+    document.querySelectorAll(".opendevbrowser-canvas-highlight").forEach((element) => {
+        element.classList.remove("opendevbrowser-canvas-highlight");
+    });
+    const selector = typeof input.selectionHint.selector === "string"
+        ? input.selectionHint.selector
+        : (input.nodeId ? `[data-node-id="${input.nodeId}"]` : null);
+    const element = selector ? document.querySelector(selector) : null;
+    if (!(element instanceof HTMLElement)) {
+        return { matched: false };
+    }
+    element.classList.add("opendevbrowser-canvas-highlight");
+    return {
+        matched: true,
+        selector,
+        tagName: element.tagName.toLowerCase(),
+        text: element.innerText.slice(0, 160),
+        id: element.id || null,
+        className: element.className || null
+    };
+}
+function syncOverlayScript(input) {
+    let root = document.getElementById(input.mountId);
+    if (!(root instanceof HTMLElement)) {
+        root = document.createElement("div");
+        root.id = input.mountId;
+        root.className = "opendevbrowser-canvas-overlay";
+        const heading = document.createElement("strong");
+        heading.textContent = input.title;
+        const detail = document.createElement("div");
+        detail.textContent = input.selection.nodeId ? `Selected ${input.selection.nodeId}` : "Canvas overlay synced";
+        root.append(heading, detail);
+        document.body.append(root);
+    }
+    const strong = root.querySelector("strong");
+    if (strong) {
+        strong.textContent = input.title;
+    }
+    const detail = root.querySelector("div");
+    if (detail) {
+        detail.textContent = input.selection.nodeId ? `Selected ${input.selection.nodeId}` : "Canvas overlay synced";
+    }
+    document.querySelectorAll(".opendevbrowser-canvas-highlight").forEach((element) => {
+        element.classList.remove("opendevbrowser-canvas-highlight");
+    });
+    if (input.selection.nodeId) {
+        const element = document.querySelector(`[data-node-id="${input.selection.nodeId}"]`);
+        if (element instanceof HTMLElement) {
+            element.classList.add("opendevbrowser-canvas-highlight");
+        }
+    }
+    return { overlayState: "mounted" };
+}
+function normalizeCanvasError(error) {
+    if (error instanceof Error) {
+        const message = error.message;
+        const restricted = message.includes("Cannot access") || message.includes("chrome://") || message.includes("restricted");
+        return {
+            code: restricted ? "restricted_url" : "execution_failed",
+            message,
+            retryable: false
+        };
+    }
+    return {
+        code: "execution_failed",
+        message: "Canvas request failed",
+        retryable: false
+    };
+}
+function delay(ms) {
+    return new Promise((resolve) => {
+        setTimeout(resolve, ms);
+    });
+}