nudge-ui 0.2.4 → 0.2.6

package/dist/inspector/canvas/canvasStore.js

@@ -1,10 +1,9 @@
-import { iterationId, contentSourceUrl, contentEditTarget } from "./frameContent.js";
-import { recordCanvasChange, discardCanvasHistory, isDraftLocked, forgetDraft } from "../changes/draftChanges.js";
-import { targetKey } from "../drafts/model.js";
+import { iterationId, contentSourceUrl } from "./frameContent.js";
+import { frameLifecycle } from "./frameLifecycle.js";
+import { recordCanvasChange, discardCanvasHistory } from "../workspace/timeline.js";
 import { useSyncExternalStore } from "react";
 import { DEFAULT_CAMERA, getBoardCamera, placeBoardCamera, restoreCanvasView, setCanvasMode, } from "./viewStore.js";
 import { normalizeUrl, normalizedUrlKey } from "./normalizeUrl.js";
-import { removeHtmlArtifact } from "../iterations/client.js";
 import { applyLayoutShifts, boundsOf, centerCamera, fitCamera, layoutShifts, nextCardPosition, pushOverlappingCards, reinsertInRecordedOrder, iterationPosition, } from "./layout.js";
 const frameGroups = new Map();
 export function setFrameGroup(group) { frameGroups.set(group.id, group); }
@@ -75,7 +74,7 @@ function notify() {
     }
     listeners.forEach((l) => l());
 }
-/** Adds one card while retaining the existing placement policy. */
+/** Adds one card to the end of the row. */
 export function addCanvasCard(url, title) {
     const before = cards;
     const size = lastUsedCardSize ?? defaultViewportSize();
@@ -139,8 +138,7 @@ function recordCreation(before, created) {
     const shifts = layoutShifts(before, cards);
     const restore = (redo) => {
         if (!redo) {
-            // Direct creation drags finish placement after the creation was recorded.
-            // Redo must recover the dropped position, dimensions, and loaded title.
+            // Direct creation drags finish placement after recording, so redo must recover the dropped geometry and title.
             for (const [index, recorded] of after.entries()) {
                 const current = createdIds.has(recorded.id) && cards.find((card) => card.id === recorded.id);
                 if (current)
@@ -183,14 +181,11 @@ function selectFallbackAfterRemoval(removedIds) {
     if (removedIds.has(focusedCardId ?? ""))
         focusedCardId = fallbackId;
 }
-function releaseUnusedIteration(card) {
-    const artifactId = iterationId(card.content);
-    if (!artifactId || cards.some((candidate) => iterationId(candidate.content) === artifactId))
+/** Reports removed iteration content; the drafts/artifacts owner decides what to release. */
+function releaseUnusedIteration(card, remaining = cards) {
+    if (!iterationId(card.content))
         return;
-    forgetDraft(targetKey(contentEditTarget(card.content)));
-    void removeHtmlArtifact(artifactId).catch((error) => {
-        console.warn("Nudge UI could not remove an unused HTML iteration:", error);
-    });
+    frameLifecycle().release(card.content, remaining.map((candidate) => candidate.content));
 }
 function recordRemoval(before, removed) {
     let snapshot = removed;
@@ -215,7 +210,7 @@ function recordRemoval(before, removed) {
     });
 }
 export function removeCanvasCard(id, { undoable = false } = {}) {
-    if (isDraftLocked())
+    if (!frameLifecycle().canEdit())
         return;
     const removed = cards.find((card) => card.id === id);
     if (!removed)
@@ -231,10 +226,7 @@ export function removeCanvasCard(id, { undoable = false } = {}) {
     if (!undoable)
         releaseUnusedIteration(removed);
 }
-/**
- * Opens one editor target in the iframe workspace without replacing restored
- * cards or their dimensions.
- */
+/** Opens one editor target without replacing restored cards or their dimensions. */
 export function activateIframeWorkspace(url, viewport, options = {}) {
     const normalized = normalizeUrl(url);
     if (!normalized || normalized.origin !== window.location.origin)
@@ -368,7 +360,7 @@ export function fitAllCards(viewport) {
         return;
     placeBoardCamera(fitCamera(bounds, viewport ?? windowViewport(), FIT_ALL_PADDING) ?? DEFAULT_CAMERA);
 }
-/** Centers a selected set of cards without changing the current zoom. */
+/** Centers the cards without changing the current zoom. */
 export function focusCanvasCards(cardIds, viewport) {
     const bounds = selectedBounds(cardIds);
     if (!bounds)
@@ -424,6 +416,36 @@ export function setCardPosition(id, x, y) {
     cards = cards.map((c) => (c.id === id ? { ...c, x, y } : c));
     notify();
 }
+function cardGeometry(id) {
+    const card = cards.find((candidate) => candidate.id === id);
+    return card ? { x: card.x, y: card.y, width: card.width, height: card.height } : null;
+}
+/** The returned commit records the whole gesture as one undo step; programmatic placement stays out of history. */
+export function beginCardGeometryChange(id) {
+    const before = cardGeometry(id);
+    let committed = false;
+    return () => {
+        if (committed || !before)
+            return;
+        committed = true;
+        const after = cardGeometry(id);
+        if (!after || (after.x === before.x && after.y === before.y && after.width === before.width && after.height === before.height))
+            return;
+        const restore = (geometry) => {
+            if (!cards.some((card) => card.id === id))
+                return;
+            cards = cards.map((card) => card.id === id ? { ...card, ...geometry } : card);
+            selectCard(id);
+            activateHistoryCard(id);
+        };
+        recordCanvasChange({
+            cardIds: [id],
+            undo: () => restore(before),
+            redo: () => restore(after),
+            dispose: () => undefined,
+        });
+    };
+}
 export function hydrateCanvasStore(newMode, newCards, newCamera, restoredFocusedCardId = null, restoredPresentation = "focus", restoredGroups = []) {
     frameGroups.clear();
     for (const group of restoredGroups)
@@ -469,7 +491,6 @@ function frameRoute(card) {
         label: normalized.pathname,
     };
 }
-/** Returns a route-based label that distinguishes copies and HTML iterations. */
 export function getCanvasCardLabel(card, frameCards = cards) {
     const route = frameRoute(card);
     const candidates = frameCards.some((candidate) => candidate.id === card.id) ? frameCards : [...frameCards, card];

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

@@ -0,0 +1,42 @@
+import type { CanvasFrame } from "./canvasFrame.js";
+import type { Rect } from "../overlay/overlayGeometry.js";
+import { type ControllerToRendererMessage, type FrameIdentity } from "./frameProtocol.js";
+export declare const PROJECT_ID: string;
+export declare const WORKSPACE_ID: string;
+export interface FramePoint {
+    readonly x: number;
+    readonly y: number;
+}
+/** Measured, not read from the camera: correct on the board, in focus view, and mid-transition. */
+export interface FrameViewport extends Readonly<Rect> {
+    readonly scale: number;
+}
+export interface RendererElementRef {
+    readonly elementId: string;
+    readonly cid: string;
+    readonly src: string;
+}
+type Envelope = "protocolVersion" | "projectId" | "workspaceId" | "cardId";
+type WithoutEnvelope<T> = T extends unknown ? Omit<T, Envelope> : never;
+export type ControllerMessageBody = WithoutEnvelope<ControllerToRendererMessage>;
+export interface FrameConnection {
+    readonly cardId: string;
+    readonly iframe: CanvasFrame;
+    readonly identity: FrameIdentity;
+    /** The renderer's document; null while the frame navigates or blocks access. */
+    document(): Document | null;
+    /** Null unless exactly one element carries the renderer ID and its source identity still matches. */
+    element(ref: RendererElementRef): HTMLElement | null;
+    viewport(): FrameViewport;
+    post(message: ControllerMessageBody): void;
+}
+export declare function measureFrameViewport(iframe: CanvasFrame): FrameViewport;
+export declare function toViewportPoint(viewport: FrameViewport, point: FramePoint): FramePoint;
+/** Pass `false` for an axis whose size is a guide thickness in controller pixels. */
+export declare function toViewportRect(viewport: FrameViewport, rect: Rect, scaleSize?: {
+    readonly width: boolean;
+    readonly height: boolean;
+}): Rect;
+export declare function findRendererElement(doc: Document | null, ref: RendererElementRef): HTMLElement | null;
+export declare function connectFrame(cardId: string, iframe: CanvasFrame): FrameConnection;
+export {};

package/dist/inspector/canvas/frameConnection.js

@@ -0,0 +1,73 @@
+import { PROTOCOL_VERSION, } from "./frameProtocol.js";
+import { RENDERER_ELEMENT_ID_ATTR } from "./rendererCidIndex.js";
+export const PROJECT_ID = typeof window !== "undefined" && window.location?.origin
+    ? window.location.origin
+    : "";
+export const WORKSPACE_ID = typeof crypto !== "undefined" && typeof crypto.randomUUID === "function"
+    ? crypto.randomUUID()
+    : `ws-${Date.now()}`;
+const RENDERER_ELEMENT_ID = /^r\d+$/;
+const connections = new WeakMap();
+export function measureFrameViewport(iframe) {
+    const rect = iframe.getBoundingClientRect();
+    return {
+        left: rect.left,
+        top: rect.top,
+        width: rect.width,
+        height: rect.height,
+        scale: iframe.clientWidth > 0 ? rect.width / iframe.clientWidth : 1,
+    };
+}
+export function toViewportPoint(viewport, point) {
+    return {
+        x: viewport.left + point.x * viewport.scale,
+        y: viewport.top + point.y * viewport.scale,
+    };
+}
+/** Pass `false` for an axis whose size is a guide thickness in controller pixels. */
+export function toViewportRect(viewport, rect, scaleSize = { width: true, height: true }) {
+    return {
+        left: viewport.left + rect.left * viewport.scale,
+        top: viewport.top + rect.top * viewport.scale,
+        width: scaleSize.width ? rect.width * viewport.scale : rect.width,
+        height: scaleSize.height ? rect.height * viewport.scale : rect.height,
+    };
+}
+export function findRendererElement(doc, ref) {
+    if (!doc || !RENDERER_ELEMENT_ID.test(ref.elementId))
+        return null;
+    const candidates = doc.querySelectorAll(`[${RENDERER_ELEMENT_ID_ATTR}="${ref.elementId}"]`);
+    const candidate = candidates.length === 1 ? candidates[0] : null;
+    if (!candidate
+        || candidate.getAttribute("data-cid") !== ref.cid
+        || (candidate.getAttribute("data-src") ?? "") !== ref.src)
+        return null;
+    const frameWindow = doc.defaultView;
+    return frameWindow && candidate instanceof frameWindow.HTMLElement ? candidate : null;
+}
+export function connectFrame(cardId, iframe) {
+    const existing = connections.get(iframe);
+    if (existing?.cardId === cardId)
+        return existing;
+    const identity = { projectId: PROJECT_ID, workspaceId: WORKSPACE_ID, cardId };
+    const connection = {
+        cardId,
+        iframe,
+        identity,
+        document() {
+            try {
+                return iframe.contentDocument;
+            }
+            catch {
+                return null;
+            }
+        },
+        element: (ref) => findRendererElement(connection.document(), ref),
+        viewport: () => measureFrameViewport(iframe),
+        post(message) {
+            iframe.contentWindow?.postMessage({ ...message, protocolVersion: PROTOCOL_VERSION, ...identity }, window.location.origin);
+        },
+    };
+    connections.set(iframe, connection);
+    return connection;
+}

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

@@ -1,5 +1,4 @@
 import { type DraftTarget } from "../drafts/model.js";
-/** Content identity is independent of frame geometry and its editable draft. */
 export type FrameContent = {
     kind: "route";
     url: string;

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

@@ -0,0 +1,12 @@
+import type { FrameContent } from "./frameContent.js";
+/**
+ * Cross-store effects a frame removal needs: whether drafts allow editing, and
+ * who releases the frame's draft and HTML artifact. Canvas registers nothing
+ * itself, so it never imports drafts or the iteration client.
+ */
+export interface FrameLifecycle {
+    readonly canEdit: () => boolean;
+    readonly release: (released: FrameContent, remaining: readonly FrameContent[]) => void;
+}
+export declare function setFrameLifecycle(next: FrameLifecycle | null): void;
+export declare function frameLifecycle(): FrameLifecycle;

package/dist/inspector/canvas/frameLifecycle.js

@@ -0,0 +1,11 @@
+const allowAll = {
+    canEdit: () => true,
+    release: () => undefined,
+};
+let lifecycle = allowAll;
+export function setFrameLifecycle(next) {
+    lifecycle = next ?? allowAll;
+}
+export function frameLifecycle() {
+    return lifecycle;
+}

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

@@ -2,17 +2,13 @@ import type { ComponentOverride } from "../componentSemantics/types.js";
 import type { RenderedInstanceOverride } from "../changes/editModel.js";
 import type { NudgeUiRuntimeConfig } from "../runtime/runtimeConfig.js";
 import type { SpacingDescriptor } from "../overlay/spacingGestures.js";
+import type { RendererCursor } from "../ui/customCursors.js";
 export declare const PROTOCOL_VERSION = 21;
 export interface FrameMessage {
     type: string;
     protocolVersion: number;
 }
-/**
- * Pre-identity solicitation from a renderer whose bootstrap finished after
- * the controller's load-time parent-ready (or whose document never received
- * one). Carries no FrameIdentity: the whole point is that the renderer does
- * not have one yet. The controller answers with ParentReadyMessage.
- */
+/** Pre-identity solicitation from a renderer that missed parent-ready; carries no FrameIdentity. */
 export interface RendererHelloMessage extends FrameMessage {
     type: "renderer-hello";
 }
@@ -59,32 +55,26 @@ export interface ReplaceStylesMessage extends FrameMessage {
     instanceOverrides: RenderedInstanceOverride[];
     /** Controller-owned structural intent; renderers never own this change log. */
     structuralChanges: import("../projection/structuralProjection.js").StructuralChange[];
-    /** Controller-owned durable rendered text intent. */
     textContentChanges: import("../changes/types.js").TextContentChangeRecord[];
-    /** Controller-owned semantic component overrides for Canvas runtimes. */
     componentOverrides: ComponentOverride[];
+    /** Generated identities the edits refer to; omitted while edits are hidden. */
+    runtimeIdentities?: import("../runtime/runtimeIdentityClaims.js").RuntimeIdentityClaim[];
 }
-/** Renderer acknowledgement that one complete controller snapshot is applied. */
 export interface ProjectionAppliedMessage extends RendererMessage {
     type: "projection-applied";
     revision: number;
 }
-/**
- * Renderer-local outcomes for one controller snapshot. This is diagnostic
- * data only: accepting it never changes controller-owned structural intent.
- */
+/** Diagnostics only: accepting these never changes controller-owned structural intent. */
 export interface StructuralProjectionReportMessage extends RendererMessage {
     type: "structural-projection-report";
     revision: number;
     reports: import("../projection/structuralProjection.js").StructuralProjectionReport[];
 }
-/** Renderer-local CSS-instance outcomes for one controller snapshot. */
 export interface RenderedInstanceProjectionReportMessage extends RendererMessage {
     type: "rendered-instance-projection-report";
     revision: number;
     reports: import("../projection/renderedInstance.js").DocumentProjectionReport[];
 }
-/** Renderer-local outcomes for one controller-owned text snapshot. */
 export interface TextProjectionReportMessage extends RendererMessage {
     type: "text-projection-report";
     revision: number;
@@ -96,7 +86,6 @@ export interface NavigationIntentMessage extends RendererMessage {
     /** The renderer kept its own route and asks the controller for a card instead. */
     openInCard?: boolean;
 }
-/** Tells a renderer whether ordinary link clicks open a new canvas card. */
 export interface LinkTargetStateMessage extends RendererMessage {
     type: "link-target-state";
     openInCard: boolean;
@@ -130,15 +119,12 @@ export interface ElementHoverMessage extends RendererMessage {
         x: number;
         y: number;
     } | null;
-    /** The spacing handle under the pointer. Drives the resize cursor and drag
-     * start; only present when the pointer is inside the handle hit area. */
+    /** The spacing handle under the pointer; only present inside the handle hit area. */
     spacing?: SpacingDescriptor | null;
-    /** The padding bar or layout gap area under the pointer, regardless of the
-     * handle. Drives the hover fill overlay across the whole area. */
+    /** The padding bar or layout gap area under the pointer, regardless of the handle. */
     hoverSpacing?: SpacingDescriptor | null;
 }
-/** Modifier state stays inside one renderer frame; the parent never infers it
- * from its own keyboard events because focus lives in the iframe. */
+/** The parent never infers modifier state: focus lives in the iframe. */
 export interface ElementMeasureStateMessage extends RendererMessage {
     type: "element-measure-state";
     altKey: boolean;
@@ -156,7 +142,6 @@ export interface ElementClickMessage extends RendererMessage {
     /** True for a Shift-click that toggles this target in the selection group. */
     additive?: boolean;
 }
-/** Requests controller-owned inline text editing for an element in this frame. */
 export interface InlineTextIntentMessage extends RendererMessage {
     type: "inline-text-intent";
     intent: "pointer-down" | "double-click";
@@ -170,7 +155,6 @@ export interface InlineTextIntentMessage extends RendererMessage {
     clickCount?: number;
     emptyProjectionId?: string;
 }
-/** Renderer request to clear the controller-owned element selection. */
 export interface ElementDeselectMessage extends RendererMessage {
     type: "element-deselect";
 }
@@ -199,7 +183,6 @@ export interface ElementDragMoveMessage extends RendererMessage {
         x: number;
         y: number;
     };
-    /** True while Shift is held; spacing drags use this to snap by 8px steps. */
     shiftKey?: boolean;
 }
 export interface ElementDragEndMessage extends RendererMessage {
@@ -208,7 +191,6 @@ export interface ElementDragEndMessage extends RendererMessage {
         x: number;
         y: number;
     };
-    /** True while Shift is held; spacing drags use this to snap by 8px steps. */
     shiftKey?: boolean;
     /** True when the renderer lost the gesture before the pointer was released. */
     cancelled?: boolean;
@@ -231,7 +213,6 @@ export interface HistoryRequestMessage extends RendererMessage {
     type: "history-request";
     action: "undo" | "redo";
 }
-/** Requests the parent-owned inspector visibility toggle from frame focus. */
 export interface InspectorToggleRequestMessage extends RendererMessage {
     type: "inspector-toggle-request";
 }
@@ -241,7 +222,6 @@ export interface InspectorOpenRequestMessage extends RendererMessage {
 }
 export type KeyboardShortcutCode = "Backslash" | "KeyI" | "KeyV" | "KeyC" | "KeyP" | "KeyS";
 export type KeyboardShortcutPhase = "keydown" | "keyup";
-/** Forwards controller-owned keyboard shortcuts from an iframe document. */
 export interface KeyboardShortcutMessage extends RendererMessage {
     type: "keyboard-shortcut";
     phase: KeyboardShortcutPhase;
@@ -281,7 +261,6 @@ export interface BoardGestureStateMessage extends RendererMessage {
     /** Ordinary wheel gestures pan the board instead of scrolling the app. */
     panScroll?: boolean;
 }
-/** Proxies modified wheel gestures that originate inside an iframe card. */
 export interface ZoomMessage extends RendererMessage {
     type: "zoom";
     deltaY: number;
@@ -290,7 +269,6 @@ export interface ZoomMessage extends RendererMessage {
         y: number;
     };
 }
-/** Proxies ordinary wheel gestures as normalized pixel distances. */
 export interface WheelPanMessage extends RendererMessage {
     type: "wheel-pan";
     deltaX: number;
@@ -301,25 +279,29 @@ export interface AppInteractionModifierMessage extends RendererMessage {
     type: "app-interaction-modifier";
     held: boolean;
 }
-export type FrameProtocolMessage = ParentReadyMessage | RendererHelloMessage | FrameReadyMessage | FrameRuntimeMessage | FrameMetadataMessage | FrameLoadError | ReplaceStylesMessage | ProjectionAppliedMessage | StructuralProjectionReportMessage | RenderedInstanceProjectionReportMessage | TextProjectionReportMessage | NavigationIntentMessage | LinkTargetStateMessage | ElementHoverMessage | ElementMeasureStateMessage | ElementClickMessage | InlineTextIntentMessage | ElementDeselectMessage | ElementDragStartMessage | ElementDragMoveMessage | ElementDragEndMessage | ElementDeleteMessage | ElementNudgeMessage | HistoryRequestMessage | InspectorToggleRequestMessage | InspectorOpenRequestMessage | KeyboardShortcutMessage | PanStartMessage | PanMoveMessage | PanEndMessage | PanModifierMessage | MeasureModifierMessage | BoardGestureStateMessage | ZoomMessage | WheelPanMessage | AppInteractionModifierMessage;
+export interface InspectorInteractionStateMessage extends RendererMessage {
+    type: "inspector-interaction-state";
+    open: boolean;
+    interactionsEnabled: boolean;
+    cursor: RendererCursor;
+    /** CSS cursor for the Comment tool; the controller renders it. */
+    commentCursor?: string;
+}
+export type RendererToControllerMessage = RendererHelloMessage | FrameReadyMessage | FrameRuntimeMessage | FrameMetadataMessage | FrameLoadError | ProjectionAppliedMessage | StructuralProjectionReportMessage | RenderedInstanceProjectionReportMessage | TextProjectionReportMessage | NavigationIntentMessage | ElementHoverMessage | ElementMeasureStateMessage | ElementClickMessage | InlineTextIntentMessage | ElementDeselectMessage | ElementDragStartMessage | ElementDragMoveMessage | ElementDragEndMessage | ElementDeleteMessage | ElementNudgeMessage | HistoryRequestMessage | InspectorToggleRequestMessage | InspectorOpenRequestMessage | KeyboardShortcutMessage | PanStartMessage | PanMoveMessage | PanEndMessage | PanModifierMessage | ZoomMessage | WheelPanMessage | AppInteractionModifierMessage;
+export type ControllerToRendererMessage = ParentReadyMessage | ReplaceStylesMessage | LinkTargetStateMessage | PanModifierMessage | MeasureModifierMessage | BoardGestureStateMessage | InspectorInteractionStateMessage;
+export declare function isRendererMessageType(type: unknown): type is RendererToControllerMessage["type"];
+export type FrameProtocolMessage = ParentReadyMessage | RendererHelloMessage | FrameReadyMessage | FrameRuntimeMessage | FrameMetadataMessage | FrameLoadError | ReplaceStylesMessage | ProjectionAppliedMessage | StructuralProjectionReportMessage | RenderedInstanceProjectionReportMessage | TextProjectionReportMessage | NavigationIntentMessage | LinkTargetStateMessage | ElementHoverMessage | ElementMeasureStateMessage | ElementClickMessage | InlineTextIntentMessage | ElementDeselectMessage | ElementDragStartMessage | ElementDragMoveMessage | ElementDragEndMessage | ElementDeleteMessage | ElementNudgeMessage | HistoryRequestMessage | InspectorToggleRequestMessage | InspectorOpenRequestMessage | KeyboardShortcutMessage | PanStartMessage | PanMoveMessage | PanEndMessage | PanModifierMessage | MeasureModifierMessage | BoardGestureStateMessage | ZoomMessage | WheelPanMessage | AppInteractionModifierMessage | InspectorInteractionStateMessage;
 export declare function setRendererIdentity(identity: FrameIdentity): void;
 export declare function clearRendererIdentity(expected?: FrameIdentity): void;
 export declare function getRendererIdentity(): FrameIdentity | null;
 export declare function isRendererMessageFor(value: unknown, identity: FrameIdentity): value is RendererMessage;
 export declare function isKeyboardShortcutCode(value: unknown): value is KeyboardShortcutCode;
-/** Strict JSON-only schema for renderer-originated global keyboard shortcuts. */
 export declare function isKeyboardShortcutMessage(value: unknown, identity: FrameIdentity): value is KeyboardShortcutMessage;
-/** Strict JSON-only schema for selecting an element from a renderer frame. */
 export declare function isElementClickMessage(value: unknown, identity: FrameIdentity): value is ElementClickMessage;
-/** Strict JSON-only schema for starting controller-owned inline text editing. */
 export declare function isInlineTextIntentMessage(value: unknown, identity: FrameIdentity): value is InlineTextIntentMessage;
-/** Strict JSON-only schema for renderer diagnostics before the parent records them. */
 export declare function isStructuralProjectionReportMessage(value: unknown, identity: FrameIdentity): value is StructuralProjectionReportMessage;
-/** Strict JSON-only schema for renderer CSS-instance diagnostics. */
 export declare function isRenderedInstanceProjectionReportMessage(value: unknown, identity: FrameIdentity): value is RenderedInstanceProjectionReportMessage;
-/** Strict JSON-only schema for renderer rendered-text diagnostics. */
 export declare function isTextProjectionReportMessage(value: unknown, identity: FrameIdentity): value is TextProjectionReportMessage;
-/** Strict JSON-only acknowledgement for a fully applied Canvas snapshot. */
 export declare function isProjectionAppliedMessage(value: unknown, identity: FrameIdentity): value is ProjectionAppliedMessage;
 export declare function isComponentOverrideList(value: unknown): value is ComponentOverride[];
 export declare function sendToParent(msg: FrameProtocolMessage): void;

package/dist/inspector/canvas/frameProtocol.js

@@ -1,24 +1,44 @@
 import { isDocumentProjectionReport } from "../projection/renderedInstance.js";
 import { isTextProjectionReport } from "../projection/textProjection.js";
 import { isStructuralProjectionReport } from "../projection/structuralProjectionBoundary.js";
-// v21 adds the Comment tool cursor and C shortcut.
-// v20 adds Shift state to element drag messages so spacing handles can snap
-// changes to 8px increments.
-// v19 adds spacing drag gestures (hover point, spacing descriptor, start
-// point, and cancelled drag-end) plus renderer-to-controller keyboard shortcut
-// forwarding for Canvas frames.
-// v18 adds parent-to-renderer Alt modifier forwarding for Canvas measurements.
-// v17 adds an idempotent renderer request to open the parent inspector. v16
-// adds controller-owned inline-text intents for Canvas frames. v15 adds
-// renderer-to-controller element deselection for Canvas frames. v14
-// adds border widths to hover geometry so containment measurements can exclude
-// the container border. v13 adds source-parent-aware structural moves and
-// bounded structural failure reasons to the full projection snapshot. v12
-// added the projection-applied acknowledgement: the controller can avoid
-// rereading a Canvas iframe until the renderer has applied its revision. v11
-// added the renderer-hello handshake solicitation for runtimes whose boot
-// completes after the controller's load-time parent-ready.
+// Bumped on every message-shape change; the controller and renderer must agree exactly.
 export const PROTOCOL_VERSION = 21;
+const RENDERER_MESSAGE_TYPES = {
+    "renderer-hello": true,
+    "frame-ready": true,
+    "frame-runtime": true,
+    "frame-metadata": true,
+    "frame-error": true,
+    "projection-applied": true,
+    "structural-projection-report": true,
+    "rendered-instance-projection-report": true,
+    "text-projection-report": true,
+    "navigation-intent": true,
+    "element-hover": true,
+    "element-measure-state": true,
+    "element-click": true,
+    "inline-text-intent": true,
+    "element-deselect": true,
+    "element-drag-start": true,
+    "element-drag-move": true,
+    "element-drag-end": true,
+    "element-delete": true,
+    "element-nudge": true,
+    "history-request": true,
+    "inspector-toggle-request": true,
+    "inspector-open-request": true,
+    "keyboard-shortcut": true,
+    "pan-start": true,
+    "pan-move": true,
+    "pan-end": true,
+    "pan-modifier": true,
+    "zoom": true,
+    "wheel-pan": true,
+    "app-interaction-modifier": true,
+};
+export function isRendererMessageType(type) {
+    return typeof type === "string" && Object.hasOwn(RENDERER_MESSAGE_TYPES, type);
+}
 let rendererIdentity = null;
 export function setRendererIdentity(identity) {
     rendererIdentity = identity;
@@ -46,7 +66,6 @@ export function isKeyboardShortcutCode(value) {
         || value === "KeyP"
         || value === "KeyS";
 }
-/** Strict JSON-only schema for renderer-originated global keyboard shortcuts. */
 export function isKeyboardShortcutMessage(value, identity) {
     if (!isRendererMessageFor(value, identity) || !isProtocolObject(value))
         return false;
@@ -58,7 +77,6 @@ export function isKeyboardShortcutMessage(value, identity) {
         && (ownValue(value, "phase") === "keydown" || ownValue(value, "phase") === "keyup")
         && isKeyboardShortcutCode(ownValue(value, "code"));
 }
-/** Strict JSON-only schema for selecting an element from a renderer frame. */
 export function isElementClickMessage(value, identity) {
     if (!isRendererMessageFor(value, identity) || !isProtocolObject(value))
         return false;
@@ -79,7 +97,6 @@ export function isElementClickMessage(value, identity) {
         && typeof ownValue(value, "component") === "string"
         && (additive === undefined || typeof additive === "boolean");
 }
-/** Strict JSON-only schema for starting controller-owned inline text editing. */
 export function isInlineTextIntentMessage(value, identity) {
     if (!isRendererMessageFor(value, identity) || !isProtocolObject(value))
         return false;
@@ -104,7 +121,6 @@ export function isInlineTextIntentMessage(value, identity) {
         && (clickCount === undefined || (typeof clickCount === "number" && Number.isSafeInteger(clickCount) && clickCount >= 0))
         && (emptyProjectionId === undefined || typeof emptyProjectionId === "string");
 }
-/** Strict JSON-only schema for renderer diagnostics before the parent records them. */
 export function isStructuralProjectionReportMessage(value, identity) {
     if (!isRendererMessageFor(value, identity) || !value || typeof value !== "object")
         return false;
@@ -119,7 +135,6 @@ export function isStructuralProjectionReportMessage(value, identity) {
         && Array.isArray(message.reports)
         && message.reports.every(isStructuralProjectionReport);
 }
-/** Strict JSON-only schema for renderer CSS-instance diagnostics. */
 export function isRenderedInstanceProjectionReportMessage(value, identity) {
     if (!isRendererMessageFor(value, identity) || !value || typeof value !== "object")
         return false;
@@ -134,7 +149,6 @@ export function isRenderedInstanceProjectionReportMessage(value, identity) {
         && Array.isArray(message.reports)
         && message.reports.every(isDocumentProjectionReport);
 }
-/** Strict JSON-only schema for renderer rendered-text diagnostics. */
 export function isTextProjectionReportMessage(value, identity) {
     if (!isRendererMessageFor(value, identity) || !isProtocolObject(value))
         return false;
@@ -150,7 +164,6 @@ export function isTextProjectionReportMessage(value, identity) {
         && Array.isArray(reports)
         && reports.every(isTextProjectionReport);
 }
-/** Strict JSON-only acknowledgement for a fully applied Canvas snapshot. */
 export function isProjectionAppliedMessage(value, identity) {
     if (!isRendererMessageFor(value, identity) || !isProtocolObject(value))
         return false;

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

@@ -1,3 +1,2 @@
 export declare const FRAME_SCROLLBAR_STYLE_ID = "nudge-ui-frame-scrollbar-styles";
-/** Gives frame documents thin scrollbars over a transparent track by default. */
 export declare function installFrameScrollbarStyles(doc: Document): () => void;

package/dist/inspector/canvas/frameScrollbarStyles.js

@@ -9,7 +9,6 @@ const FRAME_SCROLLBAR_CSS = `
     scrollbar-width: thin;
   }
 `;
-/** Gives frame documents thin scrollbars over a transparent track by default. */
 export function installFrameScrollbarStyles(doc) {
     if (!doc.head || doc.getElementById(FRAME_SCROLLBAR_STYLE_ID))
         return () => undefined;

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

@@ -1,3 +1,4 @@
+import { type CanvasCamera } from "./viewStore.js";
 export interface LayoutCard {
     readonly id: string;
     readonly x: number;
@@ -11,42 +12,29 @@ export interface Bounds {
     readonly maxX: number;
     readonly maxY: number;
 }
-/** The layout fields a creation may change on existing frames. */
+/** Where a new card or iteration is placed on the board. */
+export interface CardPosition {
+    readonly x: number;
+    readonly y: number;
+}
 export interface LayoutShift {
     readonly id: string;
     readonly from: Pick<LayoutCard, "x" | "y">;
     readonly to: Pick<LayoutCard, "x" | "y">;
 }
 export declare function boundsOf(cards: readonly LayoutCard[]): Bounds;
-/** Places a new frame to the right of every frame, on the first frame's row. */
-export declare function nextCardPosition(cards: readonly LayoutCard[], gap: number): {
-    x: number;
-    y: number;
-};
+export declare function nextCardPosition(cards: readonly LayoutCard[], gap: number): CardPosition;
 export declare function pushOverlappingCards<T extends LayoutCard>(cards: readonly T[], protectedIds: ReadonlySet<string>, gap: number): T[];
-export declare function iterationPosition(cards: readonly LayoutCard[], source: LayoutCard, gap: number): {
-    x: number;
-    y: number;
-};
-/** Zooms and centers content inside the padded viewport; null for empty content. */
+export declare function iterationPosition(cards: readonly LayoutCard[], source: LayoutCard, gap: number): CardPosition;
 export declare function fitCamera(bounds: Bounds, viewport: {
     width: number;
     height: number;
-}, padding: number): {
-    x: number;
-    y: number;
-    zoom: number;
-} | null;
+}, padding: number): CanvasCamera | null;
 export declare function centerCamera(bounds: Bounds, zoom: number, viewport: {
     width: number;
     height: number;
-}): {
-    x: number;
-    y: number;
-    zoom: number;
-};
+}): CanvasCamera;
 export declare function layoutShifts(before: readonly LayoutCard[], after: readonly LayoutCard[]): LayoutShift[];
 /** Replays recorded shifts as deltas, so frames moved since the creation keep their later moves. */
 export declare function applyLayoutShifts<T extends LayoutCard>(cards: readonly T[], shifts: readonly LayoutShift[], forward: boolean): T[];
-/** Reinserts recorded frames after their nearest recorded predecessor that still exists. */
 export declare function reinsertInRecordedOrder<T extends LayoutCard>(cards: readonly T[], recorded: readonly T[], ids: ReadonlySet<string>): T[];