nudge-ui 0.2.0 → 0.2.2

package/dist/inspector/canvas/rendererSelectionProxy.js

@@ -1,6 +1,7 @@
 import { getSelectedElements, setSelectedElement, toggleSelectedElement } from "../selection/selectionStore.js";
 import { selectCard } from "./canvasStore.js";
 import { RENDERER_ELEMENT_ID_ATTR } from "./rendererCidIndex.js";
+import { inspectComponentTargets } from "../componentSemantics/index.js";
 function isHtmlElementInDocument(node, doc) {
     const frameWindow = doc.defaultView;
     return frameWindow !== null && node instanceof frameWindow.HTMLElement;
@@ -26,7 +27,9 @@ function findClickedElement(doc, elementId, cid, src) {
     if (candidates.length !== 1)
         return null;
     const candidate = candidates[0] ?? null;
-    if (!candidate || candidate.getAttribute("data-cid") !== cid || candidate.getAttribute("data-src") !== src)
+    if (!candidate
+        || candidate.getAttribute("data-cid") !== cid
+        || (candidate.getAttribute("data-src") ?? "") !== src)
         return null;
     return isHtmlElementInDocument(candidate, doc) ? candidate : null;
 }
@@ -38,6 +41,7 @@ export function handleElementClick(msg, iframe, cardId) {
         selectCard(cardId);
         return;
     }
+    const componentTargets = inspectComponentTargets(el);
     const selected = {
         cid: msg.cid,
         src: el.getAttribute("data-src") ?? msg.src,
@@ -46,7 +50,7 @@ export function handleElementClick(msg, iframe, cardId) {
         line: msg.line,
         column: 0,
         domElement: el,
-        componentTargets: [],
+        componentTargets,
     };
     // setSelectedElement must run before any side effect that could reload the
     // host page, otherwise the selection would be discarded by the unload.

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

@@ -38,6 +38,7 @@ export interface DurableSession {
         y: number;
         zoom: number;
     };
+    focusedCardId?: string | null;
     changes: SerializableChange[];
     structuralChanges: StructuralChange[];
     clipboardHandoff: ClipboardHandoffSnapshot | null;

package/dist/inspector/canvas/sessionStore.js

@@ -1,11 +1,10 @@
 import { getWorkspaceChanges } from "../changes/workspaceChanges.js";
 import { loadWorkspaceChanges } from "../changes/changesLog.js";
 import { deserializeChange, isSerializableChange, serializeChange, } from "../changes/codecs.js";
-import { getCanvasMode, getCanvasCards, getCanvasComparisonGroups, getBoardCamera, setBoardCamera, hydrateCanvasStore, removeCanvasCard, } from "./canvasStore.js";
+import { getCanvasMode, getCanvasCards, getCanvasComparisonGroups, getFocusedCardId, getBoardCamera, setBoardCamera, hydrateCanvasStore, removeCanvasCard, } from "./canvasStore.js";
 import { applyRules } from "../projection/managedStylesheet.js";
 import { clearWorkspace as clearWorkspaceLog } from "../changes/changesLog.js";
 import { removeManagedSheet } from "../projection/managedStylesheet.js";
-import { clearInspectorLayout } from "../shell/panelLayout.js";
 import { setSelectedElement } from "../selection/selectionStore.js";
 import { canWriteWorkspace } from "./workspaceLease.js";
 import { isStructuralChange, resetStructuralDeleteProjection, } from "../projection/structuralProjection.js";
@@ -121,6 +120,7 @@ function buildSession() {
             })),
         })),
         camera: { x: camera.x, y: camera.y, zoom: camera.zoom },
+        focusedCardId: getFocusedCardId(),
         changes: serializableChanges,
         structuralChanges: workspace.structuralChanges.map((change) => ({ ...change })),
         clipboardHandoff: getClipboardHandoffSnapshot(),
@@ -330,7 +330,16 @@ export function hydrateSession() {
         y: cameraRaw.y,
         zoom: cameraRaw.zoom,
     };
-    hydrateCanvasStore(s.mode, serializableCards, camera, serializableComparisonGroups);
+    const focusedCardId = s.focusedCardId === undefined || s.focusedCardId === null
+        ? null
+        : typeof s.focusedCardId === "string" && cardsById.has(s.focusedCardId)
+            ? s.focusedCardId
+            : undefined;
+    if (focusedCardId === undefined) {
+        safeDiscard();
+        return { restored: false, changeCount: 0 };
+    }
+    hydrateCanvasStore(s.mode, serializableCards, camera, serializableComparisonGroups, focusedCardId);
     // Structural intent and instance evidence become visible atomically. The
     // projection layer preserves structural-first document application order.
     loadWorkspaceChanges(deserializedChanges, structuralChanges);
@@ -366,7 +375,6 @@ export function clearSession() {
     resetStructuralDeleteProjection();
     removeManagedSheet();
     setSelectedElement(null);
-    clearInspectorLayout();
     for (const card of getCanvasCards()) {
         removeCanvasCard(card.id);
     }

package/dist/inspector/canvas/staleChangeDetector.js

@@ -4,7 +4,7 @@ import { beginPreviewAttempt, clearPreviewDiagnostics, getHostPreviewDocument, n
 import { getWorkspaceChanges } from "../changes/workspaceChanges.js";
 import { getCanvasPreviewDocument, getRegisteredFrames } from "./projection.js";
 import { findCanvasFrameBySource, PROJECT_ID, WORKSPACE_ID } from "./projection.js";
-import { getCanvasCards } from "./canvasStore.js";
+import { getCanvasCards, getCanvasMode } from "./canvasStore.js";
 import { isRendererMessageFor } from "./frameProtocol.js";
 import { getNudgeUiRuntimeConfig } from "../runtime/runtimeConfig.js";
 const VERIFICATION_TIMEOUT_MS = 5000;
@@ -79,7 +79,7 @@ function checkTokenDrift(change) {
     return null;
 }
 function getPreviewDocuments() {
-    const documents = [getHostPreviewDocument()];
+    const documents = getCanvasMode() === "canvas" ? [] : [getHostPreviewDocument()];
     const frames = getRegisteredFrames();
     for (const card of getCanvasCards()) {
         if (frames.has(card.id))
@@ -99,15 +99,17 @@ function beginPreviewAttempts() {
 }
 function gatherMatchEvidence(changes) {
     const evidence = new Map();
-    const hostDocument = getHostPreviewDocument();
-    for (let i = 0; i < changes.length; i++) {
-        const change = changes[i];
-        if (isTokenChange(change))
-            continue;
-        if (checkSelectorInDocument(document, change.selector)) {
-            const routes = evidence.get(i) ?? [];
-            routes.push(hostDocument);
-            evidence.set(i, routes);
+    if (getCanvasMode() !== "canvas") {
+        const hostDocument = getHostPreviewDocument();
+        for (let i = 0; i < changes.length; i++) {
+            const change = changes[i];
+            if (isTokenChange(change))
+                continue;
+            if (checkSelectorInDocument(document, change.selector)) {
+                const routes = evidence.get(i) ?? [];
+                routes.push(hostDocument);
+                evidence.set(i, routes);
+            }
         }
     }
     const frames = getRegisteredFrames();
@@ -131,13 +133,13 @@ function gatherMatchEvidence(changes) {
 }
 function applyStaleResults(changes, attempts) {
     const evidence = gatherMatchEvidence(changes);
-    const hostAttempt = attempts.get(getHostPreviewDocument().logicalDocument);
+    const tokenAttempt = attempts.values().next().value;
     for (let i = 0; i < changes.length; i++) {
         const change = changes[i];
         if (isTokenChange(change)) {
             const drift = checkTokenDrift(change);
-            if (drift && hostAttempt)
-                publishPreviewDiagnostic(hostAttempt, changeKey(change), drift);
+            if (drift && tokenAttempt)
+                publishPreviewDiagnostic(tokenAttempt, changeKey(change), drift);
             continue;
         }
         const routes = evidence.get(i);

package/dist/inspector/changes/changesLog.js

@@ -8,6 +8,8 @@ import { workspaceChangeStore, } from "./workspaceChanges.js";
 import { beginPreviewAttempt, clearPreviewDiagnostics, getHostPreviewDocument, publishPreviewDiagnostic, } from "./previewDiagnostics.js";
 import { clearStructuralProjectionReports, pruneStructuralProjectionReports } from "../projection/structuralProjection.js";
 import { applyHostWorkspaceProjection, compileWorkspaceProjection, } from "../projection/workspaceProjection.js";
+import { isEditorShellDocument } from "../runtime/editorShell.js";
+import { isOriginalPreviewActive, subscribeOriginalPreview, } from "../shell/originalPreview.js";
 export { isComponentChange, isElementChange, isTextContentChange, isTextContentChangeValue, isPreviewableChange, isTokenChange, } from "./types.js";
 /**
  * Deferred delta verification (0044). Only the keys touched by a mutation are
@@ -28,14 +30,28 @@ export function getPendingRules() {
     return buildManagedStyleRules(getChangesSnapshot());
 }
 function reapply(workspace) {
-    applyHostWorkspaceProjection(compileWorkspaceProjection(workspace));
+    // While hold-to-view-original is active the host document intentionally
+    // shows the page without inspector changes. Commits still land in the
+    // canonical store; the release path re-projects the latest snapshot.
+    if (isOriginalPreviewActive())
+        return;
+    if (!isEditorShellDocument())
+        applyHostWorkspaceProjection(compileWorkspaceProjection(workspace));
 }
 function flushVerification() {
     verificationHandle = null;
+    // Probing the original preview would report the held-back changes as
+    // conflicts. Keep the pending targets; releasing re-verifies them.
+    if (isOriginalPreviewActive())
+        return;
     const targets = pendingVerificationTargets;
     pendingVerificationTargets = new Map();
     if (targets.size === 0)
         return;
+    // The editor shell has no application document. Renderer diagnostics are
+    // owned by renderer projection reports.
+    if (isEditorShellDocument())
+        return;
     const current = getChangesSnapshot();
     const attempt = beginPreviewAttempt(getHostPreviewDocument(), workspaceChangeStore.getSnapshot().revision);
     if (!attempt)
@@ -93,6 +109,20 @@ function markForVerification(keys, verificationTargets) {
     if (added)
         scheduleVerification();
 }
+/**
+ * Releasing hold-to-view-original restores the edited preview; re-verify the
+ * surviving set against the restored DOM instead of leaving peek-era state.
+ * The retry is forced: a flush that ran during the hold retains its targets
+ * without scheduling, so markForVerification alone would see every key
+ * already present and schedule nothing.
+ */
+subscribeOriginalPreview(() => {
+    if (isOriginalPreviewActive())
+        return;
+    markForVerification(getChangesSnapshot().map(changeKey));
+    if (pendingVerificationTargets.size > 0)
+        scheduleVerification();
+});
 /** Append records and report whether canonical workspace state changed. */
 export function appendChanges(incoming, options = {}) {
     const result = workspaceChangeStore.commitChangeRecords(incoming);

package/dist/inspector/changes/managedStyleProjection.d.ts

@@ -3,4 +3,4 @@ import { type ChangeRecord, type PreviewableChangeRecord } from "./types.js";
 /** The source selector stays canonical; the projection marker is document-local. */
 export declare function selectorForManagedChange(change: PreviewableChangeRecord): string | null;
 export declare function buildManagedStyleRules(changes: ChangeRecord[]): StyleRule[];
-export declare function verifyManagedStyleProjection(change: PreviewableChangeRecord, selectedElement?: HTMLElement | null): PreviewResult | null;
+export declare function verifyManagedStyleProjection(change: PreviewableChangeRecord, selectedElement?: HTMLElement | null, ownerDocument?: Document): PreviewResult | null;

package/dist/inspector/changes/managedStyleProjection.js

@@ -63,7 +63,7 @@ export function buildManagedStyleRules(changes) {
     // emitted afterwards so their additional marker specificity wins.
     return [...sourceRules.values(), ...instanceRules.values()];
 }
-export function verifyManagedStyleProjection(change, selectedElement) {
+export function verifyManagedStyleProjection(change, selectedElement, ownerDocument = document) {
     // Deferred verification must use the selection that existed when the
     // projection was committed. Reading the live selection here can make a
     // host-document change verify against a later canvas selection (or vice
@@ -75,13 +75,13 @@ export function verifyManagedStyleProjection(change, selectedElement) {
     // A Canvas-only selection belongs to an iframe. The controller stylesheet
     // cannot verify it synchronously; leave its result unknown until the frame
     // has received the canonical projection rather than claiming it is stale.
-    if (selected && selected.ownerDocument !== document) {
+    if (selected && selected.ownerDocument !== ownerDocument) {
         return null;
     }
     let targets = [];
     try {
         const selector = selectorForManagedChange(change);
-        targets = selector ? Array.from(document.querySelectorAll(selector)) : [];
+        targets = selector ? Array.from(ownerDocument.querySelectorAll(selector)) : [];
     }
     catch {
         targets = [];

package/dist/inspector/changes/structuralTypes.d.ts

@@ -4,6 +4,10 @@ export interface StructuralDelete {
     id: string;
     kind: "delete";
     target: RenderedInstanceRef;
+    /** Hash-independent route where the target was captured. */
+    route?: string;
+    /** Bounded view identity where the target was captured. */
+    state?: string;
 }
 /** Controller-owned intent to move one rendered instance. */
 export interface StructuralMove {

package/dist/inspector/changes/workspaceChanges.d.ts

@@ -31,6 +31,10 @@ export interface WorkspaceChangeStore {
     restoreWorkspaceChanges(next: WorkspaceContents): void;
     clearWorkspaceChanges(): void;
 }
+/** Groups consecutive synchronous updates from one gesture into one undo step.
+ * Updates outside the callback keep their own history entries.
+ */
+export declare function createChangeHistoryGroup(): (update: () => void) => void;
 export declare const workspaceChangeStore: WorkspaceChangeStore;
 /** Compatibility accessors retained for callers that have not adopted the store seam. */
 export declare function getWorkspaceChanges(): WorkspaceChangesSnapshot;

package/dist/inspector/changes/workspaceChanges.js

@@ -5,6 +5,7 @@ let contents = { changes: [], structuralChanges: [] };
 let revision = 0;
 let undoStack = [];
 let redoStack = [];
+let activeHistoryGroup;
 let snapshot = createSnapshot();
 const listeners = new Set();
 function cloneContents(value) {
@@ -60,11 +61,36 @@ function commit(next) {
         return false;
     const before = cloneContents(contents);
     contents = cloneContents(next);
-    undoStack.push({ before, after: cloneContents(contents) });
+    const previous = undoStack.at(-1);
+    const entry = {
+        before: activeHistoryGroup && previous?.group === activeHistoryGroup ? previous.before : before,
+        after: cloneContents(contents),
+        group: activeHistoryGroup,
+    };
+    if (activeHistoryGroup && previous?.group === activeHistoryGroup)
+        undoStack.pop();
+    if (!sameWorkspaceContents(entry.before, entry.after))
+        undoStack.push(entry);
     redoStack = [];
     publish();
     return true;
 }
+/** Groups consecutive synchronous updates from one gesture into one undo step.
+ * Updates outside the callback keep their own history entries.
+ */
+export function createChangeHistoryGroup() {
+    const group = Symbol("change-history-group");
+    return (update) => {
+        const previous = activeHistoryGroup;
+        activeHistoryGroup = group;
+        try {
+            update();
+        }
+        finally {
+            activeHistoryGroup = previous;
+        }
+    };
+}
 function getSnapshot() {
     return snapshot;
 }
@@ -123,7 +149,7 @@ function reconcileWorkspaceChangesImpl(verifiedKeys, verifiedStructuralIds) {
         return 0;
     contents = next;
     const prune = (entries) => entries
-        .map((entry) => ({ before: retain(entry.before), after: retain(entry.after) }))
+        .map((entry) => ({ group: entry.group, before: retain(entry.before), after: retain(entry.after) }))
         .filter((entry) => !sameWorkspaceContents(entry.before, entry.after));
     undoStack = prune(undoStack);
     redoStack = prune(redoStack);
@@ -159,7 +185,7 @@ function redoWorkspaceChangeImpl() {
         return false;
     redoStack.pop();
     contents = cloneContents(entry.after);
-    undoStack.push(entry);
+    undoStack.push({ before: entry.before, after: entry.after });
     publish();
     return true;
 }

package/dist/inspector/clientManifest.d.ts

@@ -8,6 +8,11 @@ export interface NudgeUiClientManifest {
     readonly version: typeof NUDGE_UI_CLIENT_MANIFEST_VERSION;
     readonly revision: number;
     readonly runtime: NudgeUiRuntimeConfig;
+    /** Project-owned, loopback-only agent bridge started by the dev host. */
+    readonly agentBridge?: {
+        readonly baseUrl: string;
+        readonly autoConnect?: boolean;
+    };
     /** Optional document preparation requested by the host Adapter. */
     readonly document?: {
         readonly runtimeIdentity?: "static-html";
@@ -19,6 +24,8 @@ export interface NudgeUiClientManifest {
         readonly strategy: "refresh-manifest" | "reload-document";
         readonly events?: readonly string[];
     };
+    /** Set by `NUDGE_UI=1`: automated browsers open the editor instead of the plain app. */
+    readonly inspectAutomatedBrowsers?: true;
 }
 /** Parses and normalizes an external manifest before it replaces inspector state. */
 export declare function parseNudgeUiClientManifest(value: unknown): NudgeUiClientManifest | null;

package/dist/inspector/clientManifest.js

@@ -20,14 +20,26 @@ value) {
             version: NUDGE_UI_CLIENT_MANIFEST_VERSION,
             revision: value.revision,
             runtime: normalizeNudgeUiRuntimeConfig(value.runtime),
+            ...(isAgentBridge(value.agentBridge) ? { agentBridge: value.agentBridge } : {}),
             ...(value.document === undefined ? {} : { document: value.document }),
             ...(value.reload === undefined ? {} : { reload: value.reload }),
+            ...(value.inspectAutomatedBrowsers === true ? { inspectAutomatedBrowsers: true } : {}),
         };
     }
     catch {
         return null;
     }
 }
+function isAgentBridge(value) {
+    if (value === undefined)
+        return false;
+    if (!isRecord(value))
+        return false;
+    const candidate = value;
+    if (typeof candidate.baseUrl !== "string" || candidate.baseUrl.length === 0)
+        return false;
+    return candidate.autoConnect === undefined || typeof candidate.autoConnect === "boolean";
+}
 function isDocumentOptions(
 // Optional manifest capability is parsed before use.
 // oxlint-disable-next-line anti-slop/no-unknown-parameters

package/dist/inspector/componentSemantics/adapterRegistry.js

@@ -1,10 +1,10 @@
 import { getNudgeUiRuntimeConfig } from "../runtime/runtimeConfig.js";
 import { copyComponentOverrides, copyRuntimeTarget, getHostRuntimeAdapters, registerHostRuntimeAdapter, replaceHostRuntimeAdapterOverrides, } from "./runtimeBridge.js";
 const diagnosedAdapters = new WeakSet();
-function enabledRuntimeAdapters() {
+function enabledRuntimeAdapters(ownerGlobal) {
     if (!getNudgeUiRuntimeConfig().capabilities.componentSemantics)
         return [];
-    return [...getHostRuntimeAdapters()];
+    return [...getHostRuntimeAdapters(ownerGlobal)];
 }
 /** Register a framework adapter without coupling semantic resolution to React. */
 export function registerComponentRuntimeAdapter(adapter) {
@@ -12,7 +12,8 @@ export function registerComponentRuntimeAdapter(adapter) {
 }
 export function inspectComponentTargets(element) {
     const targets = [];
-    for (const adapter of enabledRuntimeAdapters()) {
+    const ownerGlobal = element.ownerDocument.defaultView ?? globalThis;
+    for (const adapter of enabledRuntimeAdapters(ownerGlobal)) {
         let inspected;
         try {
             inspected = adapter.inspect(element);

package/dist/inspector/componentSemantics/runtimeBridge.d.ts

@@ -11,8 +11,8 @@ export declare const NUDGE_UI_HOST_RUNTIME_VERSION = 1;
  * not accumulate stale implementations.
  */
 export declare function registerHostRuntimeAdapter(adapter: ComponentRuntimeAdapter): () => void;
-/** Returns the active host runtime Adapters for this browser realm. */
-export declare function getHostRuntimeAdapters(): readonly ComponentRuntimeAdapter[];
+/** Returns the active host runtime Adapters for the requested browser realm. */
+export declare function getHostRuntimeAdapters(ownerGlobal?: typeof globalThis): readonly ComponentRuntimeAdapter[];
 /** Stores the latest projection and sends it to every registered host Adapter. */
 export declare function replaceHostRuntimeAdapterOverrides(overrides: readonly ComponentOverride[]): void;
 /**

package/dist/inspector/componentSemantics/runtimeBridge.js

@@ -42,9 +42,22 @@ export function registerHostRuntimeAdapter(adapter) {
         }
     };
 }
-/** Returns the active host runtime Adapters for this browser realm. */
-export function getHostRuntimeAdapters() {
-    return [...registry().adapters.values()];
+/** Returns the active host runtime Adapters for the requested browser realm. */
+export function getHostRuntimeAdapters(ownerGlobal = globalThis) {
+    if (ownerGlobal === globalThis)
+        return [...registry().adapters.values()];
+    const current = ownerGlobal[HOST_RUNTIME_KEY];
+    if (current === undefined)
+        return [];
+    const mapConstructor = Reflect.get(ownerGlobal, "Map");
+    if (!mapConstructor
+        || typeof current !== "object"
+        || current === null
+        || current.version !== NUDGE_UI_HOST_RUNTIME_VERSION
+        || !(current.adapters instanceof mapConstructor)) {
+        throw new Error(`Nudge UI host runtime is incompatible with version ${NUDGE_UI_HOST_RUNTIME_VERSION}.`);
+    }
+    return [...(current.adapters.values())];
 }
 /** Stores the latest projection and sends it to every registered host Adapter. */
 export function replaceHostRuntimeAdapterOverrides(overrides) {

package/dist/inspector/index.d.ts

@@ -1,3 +1,4 @@
+export { resolveNudgeUiClientEntry } from "../transport/editor.js";
 export declare function bootstrapNudgeUi(inspectorHost: HTMLElement): void;
 export declare function mountInspector(host: HTMLElement): void;
 export declare function unmountInspector(): void;
@@ -6,6 +7,7 @@ export { InspectorShell } from "./shell/InspectorShell.js";
 export { detectFramework } from "./prompt/detectFramework.js";
 export { installStaticHtmlRuntimeIdentity, isRuntimeGeneratedSource, RUNTIME_ELEMENT_CID_PREFIX, RUNTIME_UNKNOWN_SOURCE_PREFIX, } from "./runtime/staticHtmlRuntimeIdentity.js";
 export { isCanvasRenderer } from "./canvas/roleDetection.js";
+export { createNudgeUiEditorUrl, hasNudgeUiDirectTabIntent, isNudgeUiDirectUrl, readNudgeUiEditorTarget, rememberNudgeUiDirectTabIntent, } from "../transport/editor.js";
 export { NUDGE_UI_INSPECTION_VERSION, inspectElement, installInspectionBridge } from "./inspection/bridge.js";
 export type { NudgeUiInspectionBridge, ElementInspection, InspectElementOptions, InspectionCatalogEntry, InspectionControl } from "./inspection/bridge.js";
 export { beginInlineTextEdit, cancelInlineTextEdit, disposeInlineTextEdit, getInlineTextDiagnostic, getInlineTextDiagnostics, getInlineTextSession, inlineTextEditor, isInlineTextEditingActive, subscribeInlineTextDiagnostics, resolveTextBinding, useInlineTextSession, } from "./inline-text/inlineTextEditor.js";