nudge-ui 0.2.0 → 0.2.1

package/dist/inspector/canvas/frameProtocol.js

@@ -1,7 +1,13 @@
 import { isDocumentProjectionReport } from "../projection/renderedInstance.js";
 import { isTextProjectionReport } from "../projection/textProjection.js";
 import { isStructuralProjectionReport } from "../projection/structuralProjectionBoundary.js";
-// v15 adds renderer-to-controller element deselection for Canvas frames. v14
+// 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
@@ -9,7 +15,7 @@ import { isStructuralProjectionReport } from "../projection/structuralProjection
 // 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.
-export const PROTOCOL_VERSION = 15;
+export const PROTOCOL_VERSION = 19;
 let rendererIdentity = null;
 export function setRendererIdentity(identity) {
     rendererIdentity = identity;
@@ -30,6 +36,21 @@ export function isRendererMessageFor(value, identity) {
         && message.workspaceId === identity.workspaceId
         && message.cardId === identity.cardId;
 }
+export function isKeyboardShortcutCode(value) {
+    return value === "Backslash" || value === "KeyV" || value === "KeyH" || 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;
+    if (!hasOnlyKeys(value, [
+        "type", "protocolVersion", "projectId", "workspaceId", "cardId", "phase", "code",
+    ]))
+        return false;
+    return ownValue(value, "type") === "keyboard-shortcut"
+        && (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))
@@ -51,6 +72,31 @@ 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;
+    if (!hasOnlyKeys(value, [
+        "type", "protocolVersion", "projectId", "workspaceId", "cardId",
+        "intent", "cid", "src", "elementId", "point", "clickCount", "emptyProjectionId",
+    ]))
+        return false;
+    const intent = ownValue(value, "intent");
+    const point = ownValue(value, "point");
+    const clickCount = ownValue(value, "clickCount");
+    const emptyProjectionId = ownValue(value, "emptyProjectionId");
+    return ownValue(value, "type") === "inline-text-intent"
+        && (intent === "pointer-down" || intent === "double-click")
+        && typeof ownValue(value, "cid") === "string"
+        && typeof ownValue(value, "src") === "string"
+        && typeof ownValue(value, "elementId") === "string"
+        && isProtocolObject(point)
+        && hasOnlyKeys(point, ["x", "y"])
+        && typeof ownValue(point, "x") === "number" && Number.isFinite(ownValue(point, "x"))
+        && typeof ownValue(point, "y") === "number" && Number.isFinite(ownValue(point, "y"))
+        && (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")
@@ -137,6 +183,7 @@ function isProtocolObject(value) {
 function ownValue(value, key) {
     switch (key) {
         case "additive": return value.additive;
+        case "emptyProjectionId": return value.emptyProjectionId;
         case "cardId": return value.cardId;
         case "cid": return value.cid;
         case "callsiteId": return value.callsiteId;
@@ -144,6 +191,11 @@ function ownValue(value, key) {
         case "elementId": return value.elementId;
         case "file": return value.file;
         case "line": return value.line;
+        case "intent": return value.intent;
+        case "point": return value.point;
+        case "clickCount": return value.clickCount;
+        case "x": return value.x;
+        case "y": return value.y;
         case "prop": return value.prop;
         case "projectId": return value.projectId;
         case "protocolVersion": return value.protocolVersion;
@@ -153,6 +205,8 @@ function ownValue(value, key) {
         case "selector": return value.selector;
         case "src": return value.src;
         case "component": return value.component;
+        case "code": return value.code;
+        case "phase": return value.phase;
         case "value": return value.value;
         case "workspaceId": return value.workspaceId;
     }

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

@@ -0,0 +1,3 @@
+export type CanvasInteractionTool = "move" | "pan" | "sketch";
+export declare function canvasToolForCode(code: string): CanvasInteractionTool | null;
+export declare function canvasToolForEvent(event: KeyboardEvent): CanvasInteractionTool | null;

package/dist/inspector/canvas/keyboardShortcuts.js

@@ -0,0 +1,14 @@
+export function canvasToolForCode(code) {
+    if (code === "KeyV")
+        return "move";
+    if (code === "KeyH")
+        return "pan";
+    if (code === "KeyP")
+        return "sketch";
+    return null;
+}
+export function canvasToolForEvent(event) {
+    if (event.repeat || event.altKey || event.ctrlKey || event.metaKey || event.shiftKey)
+        return null;
+    return canvasToolForCode(event.code);
+}

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

@@ -1,3 +1,4 @@
+import { type WorkspaceContents } from "../changes/workspaceChanges.js";
 import type { CanvasCard } from "./canvasStore.js";
 import { type PreviewDocument } from "../changes/previewDiagnostics.js";
 import { type CompiledManagedStyles } from "../projection/workspaceProjection.js";
@@ -23,6 +24,12 @@ export declare function computeProjection(): {
 };
 export declare function resetProjectionRevision(): void;
 export declare function sendProjectionToCard(card: CanvasCard, iframe: HTMLIFrameElement): void;
+/** Temporarily projects a snapshot through the renderer that owns the document. */
+export declare function projectWorkspaceSnapshotToDocument(doc: Document, snapshot: WorkspaceContents): Promise<number | null>;
+/** Returns whether an acknowledged temporary projection is still authoritative. */
+export declare function isCanvasProjectionRevisionCurrent(doc: Document, expectedRevision: number): boolean;
+/** Returns whether the live frame acknowledged its latest canonical workspace projection. */
+export declare function isCanvasCanonicalProjectionRevisionCurrent(doc: Document, expectedRevision: number): boolean;
 export declare function registerCardFrameSource(cardId: string, iframe: HTMLIFrameElement): void;
 export declare function registerCardFrame(cardId: string, iframe: HTMLIFrameElement): void;
 export declare function unregisterCardFrame(cardId: string): void;

package/dist/inspector/canvas/projection.js

@@ -1,16 +1,18 @@
 import { getWorkspaceChanges } from "../changes/workspaceChanges.js";
 import { getCanvasMode } from "./canvasStore.js";
 import { PROTOCOL_VERSION } from "./frameProtocol.js";
-import { clearCanvasRenderedInstanceProjectionReports, } from "../projection/renderedInstance.js";
-import { clearCanvasTextProjectionReports, } from "../projection/textProjection.js";
+import { clearCanvasRenderedInstanceProjectionReports, setCanonicalRenderedInstanceOverrides, } from "../projection/renderedInstance.js";
+import { clearCanvasTextProjectionReports, setCanonicalTextContentChanges, } from "../projection/textProjection.js";
 import { clearCanvasStructuralProjectionReports } from "../projection/structuralProjection.js";
 import { invalidatePreviewDocumentSession, startPreviewDocumentSession, } from "../changes/previewDiagnostics.js";
-import { applyHostWorkspaceProjection, compileWorkspaceProjection, } from "../projection/workspaceProjection.js";
+import { compileWorkspaceProjection, } from "../projection/workspaceProjection.js";
+import { isOriginalPreviewActive } from "../shell/originalPreview.js";
 import { disposeBrowserCssInspection } from "../inspection/browserCssInspectionRegistry.js";
 export const PROJECT_ID = window.location.origin;
 export const WORKSPACE_ID = crypto.randomUUID?.() ?? `ws-${Date.now()}`;
 let revision = 0;
 let lastRulesKey = null;
+let lastPeekActive = false;
 const frameProjectionStates = new Map();
 const previewDocuments = new Map();
 const projectionAcknowledgementListeners = new Set();
@@ -49,7 +51,32 @@ function projectionKey(plan) {
 }
 export function computeProjection() {
     const plan = compileWorkspaceProjection(getWorkspaceChanges());
-    applyHostWorkspaceProjection(plan);
+    if (isOriginalPreviewActive()) {
+        // Hold-to-view-original: frames show the page without inspector changes
+        // while canonical intent (and its projection key) stays untouched.
+        if (!lastPeekActive) {
+            lastPeekActive = true;
+            revision += 1;
+        }
+        return {
+            ...plan,
+            managedStyles: { rules: [], css: "" },
+            css: "",
+            instanceOverrides: [],
+            structuralChanges: [],
+            textContentChanges: [],
+            componentOverrides: [],
+            revision,
+        };
+    }
+    if (lastPeekActive) {
+        // Force the canonical projection to resend after a peek even though its
+        // key is unchanged since the peek began.
+        lastPeekActive = false;
+        lastRulesKey = null;
+    }
+    setCanonicalRenderedInstanceOverrides(plan.instanceOverrides);
+    setCanonicalTextContentChanges(plan.textContentChanges);
     const key = projectionKey(plan);
     if (key !== lastRulesKey) {
         lastRulesKey = key;
@@ -60,9 +87,11 @@ export function computeProjection() {
 export function resetProjectionRevision() {
     revision = 0;
     lastRulesKey = null;
+    lastPeekActive = false;
     for (const state of frameProjectionStates.values()) {
         state.sentRevision = -1;
         state.appliedRevision = -1;
+        state.canonicalSentRevision = -1;
     }
     projectionAcknowledgementVersion += 1;
     notifyProjectionAcknowledgementListeners();
@@ -72,12 +101,18 @@ export function sendProjectionToCard(card, iframe) {
     if (!win)
         return;
     const { css, revision: rev, instanceOverrides, structuralChanges, textContentChanges, componentOverrides } = computeProjection();
+    sendProjectionMessage(card.id, iframe, rev, css, instanceOverrides, structuralChanges, textContentChanges, componentOverrides, true);
+}
+function sendProjectionMessage(cardId, iframe, rev, css, instanceOverrides, structuralChanges, textContentChanges, componentOverrides, canonical = false) {
+    const win = iframe.contentWindow;
+    if (!win)
+        return;
     const msg = {
         type: "replace-styles",
         protocolVersion: PROTOCOL_VERSION,
         projectId: PROJECT_ID,
         workspaceId: WORKSPACE_ID,
-        cardId: card.id,
+        cardId,
         css,
         revision: rev,
         instanceOverrides: [...instanceOverrides],
@@ -85,9 +120,79 @@ export function sendProjectionToCard(card, iframe) {
         textContentChanges: [...textContentChanges],
         componentOverrides: [...componentOverrides],
     };
-    markProjectionSent(card.id, iframe, rev);
+    markProjectionSent(cardId, iframe, rev, canonical);
     win.postMessage(msg, window.location.origin);
 }
+/** Temporarily projects a snapshot through the renderer that owns the document. */
+export async function projectWorkspaceSnapshotToDocument(doc, snapshot) {
+    const entry = [...frameProjectionStates.entries()].find(([, state]) => state.document === doc);
+    if (!entry)
+        return null;
+    const [cardId, state] = entry;
+    const plan = compileWorkspaceProjection({ ...snapshot, revision: 0 });
+    revision += 1;
+    sendProjectionMessage(cardId, state.iframe, revision, plan.managedStyles.css, plan.instanceOverrides, plan.structuralChanges, plan.textContentChanges, plan.componentOverrides);
+    if (state.appliedRevision === revision && state.sentRevision === revision)
+        return revision;
+    const requestedRevision = revision;
+    return new Promise((resolve) => {
+        let settled = false;
+        let timer;
+        const finish = (appliedRevision) => {
+            if (settled)
+                return;
+            settled = true;
+            unsubscribe();
+            if (timer !== undefined)
+                clearTimeout(timer);
+            resolve(appliedRevision);
+        };
+        const unsubscribe = subscribeCanvasProjectionAcknowledgements(() => {
+            const current = frameProjectionStates.get(cardId);
+            if (!current || current.document !== doc)
+                finish(null);
+            else if (current.sentRevision > requestedRevision || current.appliedRevision > requestedRevision)
+                finish(null);
+            else if (current.appliedRevision === requestedRevision)
+                finish(requestedRevision);
+        });
+        timer = setTimeout(() => finish(null), 2_000);
+    });
+}
+/** Returns whether an acknowledged temporary projection is still authoritative. */
+export function isCanvasProjectionRevisionCurrent(doc, expectedRevision) {
+    for (const state of frameProjectionStates.values()) {
+        if (state.document !== doc)
+            continue;
+        try {
+            if (state.iframe.contentDocument !== doc)
+                return false;
+        }
+        catch {
+            return false;
+        }
+        return state.sentRevision === expectedRevision && state.appliedRevision === expectedRevision;
+    }
+    return false;
+}
+/** Returns whether the live frame acknowledged its latest canonical workspace projection. */
+export function isCanvasCanonicalProjectionRevisionCurrent(doc, expectedRevision) {
+    for (const state of frameProjectionStates.values()) {
+        if (state.document !== doc)
+            continue;
+        try {
+            if (state.iframe.contentDocument !== doc)
+                return false;
+        }
+        catch {
+            return false;
+        }
+        return state.canonicalSentRevision === expectedRevision
+            && state.sentRevision === expectedRevision
+            && state.appliedRevision === expectedRevision;
+    }
+    return false;
+}
 const frameRegistry = new Map();
 const frameSourceRegistry = new Map();
 export function registerCardFrameSource(cardId, iframe) {
@@ -109,6 +214,7 @@ export function registerCardFrame(cardId, iframe) {
             previewDocument,
             sentRevision: -1,
             appliedRevision: -1,
+            canonicalSentRevision: -1,
         });
     }
     else {
@@ -123,6 +229,8 @@ export function unregisterCardFrame(cardId) {
     frameRegistry.delete(cardId);
     invalidateCanvasPreviewDocument(cardId);
     frameProjectionStates.delete(cardId);
+    projectionAcknowledgementVersion += 1;
+    notifyProjectionAcknowledgementListeners();
     clearCanvasStructuralProjectionReports(cardId);
     clearCanvasRenderedInstanceProjectionReports(cardId);
     clearCanvasTextProjectionReports(cardId);
@@ -153,11 +261,13 @@ function getFrameDocument(iframe) {
         return null;
     }
 }
-function markProjectionSent(cardId, iframe, sentRevision) {
+function markProjectionSent(cardId, iframe, sentRevision, canonical = false) {
     const state = frameProjectionStates.get(cardId);
     if (!state || state.iframe !== iframe)
         return;
     state.sentRevision = Math.max(state.sentRevision, sentRevision);
+    if (canonical)
+        state.canonicalSentRevision = sentRevision;
 }
 /** Records the highest complete projection revision accepted by one frame. */
 export function recordCanvasProjectionApplied(cardId, appliedRevision) {
@@ -210,23 +320,6 @@ export function projectToAllReadyCards() {
         return;
     const { css, revision: rev, instanceOverrides, structuralChanges, textContentChanges, componentOverrides } = computeProjection();
     for (const [cardId, iframe] of frameRegistry) {
-        const win = iframe.contentWindow;
-        if (!win)
-            continue;
-        const msg = {
-            type: "replace-styles",
-            protocolVersion: PROTOCOL_VERSION,
-            projectId: PROJECT_ID,
-            workspaceId: WORKSPACE_ID,
-            cardId,
-            css,
-            revision: rev,
-            instanceOverrides: [...instanceOverrides],
-            structuralChanges: [...structuralChanges],
-            textContentChanges: [...textContentChanges],
-            componentOverrides: [...componentOverrides],
-        };
-        markProjectionSent(cardId, iframe, rev);
-        win.postMessage(msg, window.location.origin);
+        sendProjectionMessage(cardId, iframe, rev, css, instanceOverrides, structuralChanges, textContentChanges, componentOverrides, true);
     }
 }

package/dist/inspector/canvas/rendererBootstrap.js

@@ -4,7 +4,7 @@ import { findClosestAnchor, isEligibleNavigation, hasDifferentRoute } from "./li
 import { installRendererElementSelector } from "./rendererElementSelector.js";
 import { createFrameThrottle } from "../overlay/frameThrottle.js";
 import { isNudgeUiDev } from "../runtime/devFlag.js";
-import { getNudgeUiRuntimeConfig } from "../runtime/runtimeConfig.js";
+import { getNudgeUiRuntimeConfig, subscribeNudgeUiRuntime } from "../runtime/runtimeConfig.js";
 let activeRendererBootstrap = null;
 function ownsRendererBootstrap(owner) {
     return owner.active && activeRendererBootstrap?.owner === owner;
@@ -20,10 +20,25 @@ function sendFrameReady(owner) {
         protocolVersion: PROTOCOL_VERSION,
         url: window.location.href,
         title: document.title,
+        runtime: getNudgeUiRuntimeConfig(),
         ...identity,
     };
     sendToParent(msg);
 }
+function sendFrameRuntime(owner) {
+    if (!ownsRendererBootstrap(owner))
+        return;
+    const identity = getRendererIdentity();
+    if (!identity)
+        return;
+    const message = {
+        type: "frame-runtime",
+        protocolVersion: PROTOCOL_VERSION,
+        runtime: getNudgeUiRuntimeConfig(),
+        ...identity,
+    };
+    sendToParent(message);
+}
 function sendFrameMetadata(owner) {
     if (!ownsRendererBootstrap(owner))
         return;
@@ -132,6 +147,7 @@ export function bootstrapRenderer() {
     activeRendererBootstrap = { owner, handle };
     try {
         observeFrameMetadata(owner);
+        owner.resourceDisposers.push(subscribeNudgeUiRuntime(() => sendFrameRuntime(owner)));
         const disposeDiagnostics = startRendererProjectionDiagnostics();
         if (disposeDiagnostics)
             owner.resourceDisposers.push(disposeDiagnostics);
@@ -145,25 +161,10 @@ export function bootstrapRenderer() {
             const anchor = findClosestAnchor(event.target);
             if (!anchor)
                 return;
-            if (!isEligibleNavigation(anchor, event)) {
-                if (isPrimarySelfNavigation(anchor, event)) {
-                    event.preventDefault();
-                    const identity = getRendererIdentity();
-                    if (!identity)
-                        return;
-                    const msg = {
-                        type: "external-navigation",
-                        protocolVersion: PROTOCOL_VERSION,
-                        url: anchor.href,
-                        ...identity,
-                    };
-                    sendToParent(msg);
-                }
+            if (!isEligibleNavigation(anchor, event))
                 return;
-            }
             if (!hasDifferentRoute(anchor))
                 return;
-            event.preventDefault();
             const identity = getRendererIdentity();
             if (!identity)
                 return;
@@ -234,18 +235,10 @@ export function bootstrapRenderer() {
     }
     return handle;
 }
-function isPrimarySelfNavigation(anchor, event) {
-    if (event.ctrlKey || event.metaKey || event.shiftKey || event.button !== 0)
-        return false;
-    if (anchor.hasAttribute("download"))
-        return false;
-    if (anchor.target && anchor.target !== "" && anchor.target !== "_self")
-        return false;
-    return anchor.protocol === "http:" || anchor.protocol === "https:";
-}
 function installRendererPanProxy(owner) {
     let spaceHeld = false;
     let panning = false;
+    let boardGesturesEnabled = false;
     const panMoveUpdate = createFrameThrottle((point) => {
         if (!ownsRendererBootstrap(owner))
             return;
@@ -290,13 +283,20 @@ function installRendererPanProxy(owner) {
         if (event.data.type === "pan-modifier") {
             spaceHeld = event.data.spaceHeld;
         }
+        if (event.data.type === "board-gesture-state") {
+            boardGesturesEnabled = event.data.enabled;
+            if (!boardGesturesEnabled) {
+                spaceHeld = false;
+                endPan();
+            }
+        }
     };
     window.addEventListener("message", onMessage);
     owner.listenerRemovers.push(() => window.removeEventListener("message", onMessage));
     const onKeyDown = (event) => {
         if (!ownsRendererBootstrap(owner))
             return;
-        if (event.code === "Space" && !event.repeat && !isEditableTarget(event.target)) {
+        if (boardGesturesEnabled && event.code === "Space" && !event.repeat && !isEditableTarget(event.target)) {
             spaceHeld = true;
             if (getRendererIdentity())
                 event.preventDefault();
@@ -342,7 +342,7 @@ function installRendererPanProxy(owner) {
     const onPointerDown = (event) => {
         if (!ownsRendererBootstrap(owner))
             return;
-        if (!spaceHeld || event.button !== 0 || isEditableTarget(event.target))
+        if (!boardGesturesEnabled || !spaceHeld || event.button !== 0 || isEditableTarget(event.target))
             return;
         const identity = getRendererIdentity();
         if (!identity)
@@ -388,7 +388,7 @@ function installRendererPanProxy(owner) {
     const onWheel = (event) => {
         if (!ownsRendererBootstrap(owner))
             return;
-        if (!event.ctrlKey && !event.metaKey)
+        if (!boardGesturesEnabled || (!event.ctrlKey && !event.metaKey))
             return;
         const identity = getRendererIdentity();
         if (!identity)