nudge-ui 0.2.2 → 0.2.3

package/dist/inspector/drafts/store.js

@@ -0,0 +1,231 @@
+import { useSyncExternalStore } from "react";
+import { getCanvasCards, selectCard, focusCanvasCards, activateIframeWorkspace } from "../canvas/canvasStore.js";
+import { contentEditTarget } from "../canvas/frameContent.js";
+import { deserializeChange, isSerializableChange, serializeChange, } from "../changes/codecs.js";
+import { getActiveDraftChanges, getDraftChanges, restoreDraftChanges, subscribeDraftChanges, setActiveDraft, clearDraftChanges, listDraftIds, resetDraftChanges, } from "../changes/draftChanges.js";
+import { refreshDraftPreview } from "../changes/changesLog.js";
+import { isStructuralChange } from "../projection/structuralProjection.js";
+import { canWriteWorkspace } from "../canvas/workspaceLease.js";
+import { getSketchStoreSnapshot, subscribeSketchStore } from "../sketch/store.js";
+import { documentTarget, isDraftTarget, targetFromKey, targetKey } from "./model.js";
+let projectId = "";
+let persistent = true;
+/** Overrides the capture-URL owner for sketches drawn while another draft was active. */
+const sketchOwners = new Map();
+const contentDrafts = new WeakMap();
+const listeners = new Set();
+let snapshot = null;
+function publish() {
+    snapshot = null;
+    for (const listener of listeners)
+        listener();
+}
+subscribeDraftChanges(publish);
+subscribeSketchStore(publish);
+function storageKey() { return `nudge-ui-drafts:${projectId}:v2`; }
+export function draftIdForContent(content) {
+    let id = contentDrafts.get(content);
+    if (id === undefined) {
+        id = targetKey(contentEditTarget(content));
+        contentDrafts.set(content, id);
+    }
+    return id;
+}
+export function draftIdForCard(cardId) {
+    const card = getCanvasCards().find((candidate) => candidate.id === cardId);
+    return card ? draftIdForContent(card.content) : null;
+}
+export function sketchOwner(document) {
+    const owner = sketchOwners.get(document.id);
+    if (owner)
+        return owner;
+    try {
+        return targetKey(documentTarget(document.capture.url));
+    }
+    catch {
+        return null;
+    }
+}
+function readDraft(id, target) {
+    const workspace = getDraftChanges(id);
+    return {
+        id,
+        target,
+        revision: workspace.revision,
+        contents: { changes: workspace.changes, structuralChanges: workspace.structuralChanges },
+        sketchIds: getSketchStoreSnapshot().documents.filter((document) => sketchOwner(document) === id).map((document) => document.id),
+    };
+}
+export function getDraft(id) {
+    const target = targetFromKey(id);
+    return target ? readDraft(id, target) : null;
+}
+export function getDraftForCard(cardId) {
+    const id = draftIdForCard(cardId);
+    return id ? getDraft(id) : null;
+}
+export function getDraftContentsForCard(cardId) {
+    const draft = getDraftForCard(cardId);
+    return draft ? { changes: draft.contents.changes, structuralChanges: draft.contents.structuralChanges } : null;
+}
+export function persistDrafts() {
+    if (!projectId || !persistent || !canWriteWorkspace())
+        return;
+    const sketches = getSketchStoreSnapshot();
+    const liveSketches = new Set(sketches.documents.map((document) => document.id));
+    const value = {
+        schemaVersion: 2, projectId,
+        drafts: listDraftIds().flatMap((id) => {
+            const target = targetFromKey(id);
+            const workspace = getDraftChanges(id);
+            if (!target || workspace.changes.length + workspace.structuralChanges.length === 0)
+                return [];
+            return [{
+                    target,
+                    revision: workspace.revision,
+                    contents: {
+                        changes: workspace.changes.flatMap((change) => {
+                            const serialized = serializeChange(change);
+                            return serialized ? [serialized] : [];
+                        }),
+                        structuralChanges: workspace.structuralChanges,
+                    },
+                }];
+        }),
+        sketchOwners: Object.fromEntries([...sketchOwners].filter(([id]) => !sketches.ready || liveSketches.has(id))),
+    };
+    try {
+        localStorage.setItem(storageKey(), JSON.stringify(value));
+    }
+    catch {
+        return;
+    }
+}
+function validPersisted(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const candidate = value;
+    if (candidate.schemaVersion !== 2 || candidate.projectId !== projectId || !Array.isArray(candidate.drafts))
+        return false;
+    const targets = new Set();
+    for (const draft of candidate.drafts) {
+        if (!draft || !isDraftTarget(draft.target) || targets.has(targetKey(draft.target))
+            || !Number.isSafeInteger(draft.revision) || draft.revision < 1
+            || !draft.contents || !Array.isArray(draft.contents.changes) || !draft.contents.changes.every(isSerializableChange)
+            || !Array.isArray(draft.contents.structuralChanges) || !draft.contents.structuralChanges.every(isStructuralChange))
+            return false;
+        const textIds = draft.contents.changes.filter((change) => change.kind === "text-content").map((change) => "id" in change ? change.id : "");
+        if (new Set(textIds).size !== textIds.length)
+            return false;
+        targets.add(targetKey(draft.target));
+    }
+    return !!candidate.sketchOwners && typeof candidate.sketchOwners === "object" && !Array.isArray(candidate.sketchOwners)
+        && Object.values(candidate.sketchOwners).every((id) => typeof id === "string" && targetFromKey(id) !== null);
+}
+/** Replaces every in-memory draft with the stored drafts, so a tab that takes over never writes stale edits. */
+export function loadDrafts(nextProjectId, options = {}) {
+    projectId = nextProjectId;
+    persistent = options.persistent ?? true;
+    sketchOwners.clear();
+    resetDraftChanges();
+    try {
+        const raw = persistent ? localStorage.getItem(storageKey()) : null;
+        const stored = raw ? JSON.parse(raw) : null;
+        if (validPersisted(stored)) {
+            for (const draft of stored.drafts) {
+                restoreDraftChanges(targetKey(draft.target), { changes: draft.contents.changes.map(deserializeChange), structuralChanges: draft.contents.structuralChanges }, draft.revision);
+            }
+            for (const [sketchId, draftId] of Object.entries(stored.sketchOwners))
+                sketchOwners.set(sketchId, draftId);
+        }
+    }
+    catch {
+        resetDraftChanges();
+        sketchOwners.clear();
+    }
+    publish();
+    refreshDraftPreview();
+}
+export function activateDraftForCard(cardId) {
+    const draftId = draftIdForCard(cardId);
+    if (draftId)
+        activateDraft(draftId, cardId);
+}
+export function activateDraft(draftId, preferredCardId) {
+    const previous = getActiveDraftChanges().draftId;
+    setActiveDraft(draftId, () => revealDraft(draftId, preferredCardId));
+    if (previous !== draftId)
+        refreshDraftPreview();
+}
+function revealDraft(draftId, preferredCardId) {
+    const cards = getCanvasCards();
+    let frame = cards.find((card) => card.id === preferredCardId && draftIdForContent(card.content) === draftId)
+        ?? cards.find((card) => draftIdForContent(card.content) === draftId);
+    const target = targetFromKey(draftId);
+    if (!frame && target?.kind === "application") {
+        const original = cards.find((card) => card.id === preferredCardId && card.content.kind === "route");
+        if (original) {
+            selectCard(original.id);
+            frame = activateIframeWorkspace(target.route, { width: window.innerWidth, height: window.innerHeight }, { replaceActiveCard: true }) ?? undefined;
+        }
+    }
+    if (!frame)
+        return;
+    activateDraftForCard(frame.id);
+    selectCard(frame.id);
+    focusCanvasCards([frame.id]);
+}
+export function clearSavedIterationDraft(cardId, expectedRevision) {
+    const draftId = draftIdForCard(cardId);
+    return !!draftId && clearDraftChanges(draftId, expectedRevision);
+}
+/** Returns the first preferred frame that exists, then the first frame. */
+export function getEditableCardId(...preferredCardIds) {
+    const cards = getCanvasCards();
+    return preferredCardIds.find((id) => !!id && cards.some((card) => card.id === id)) ?? cards[0]?.id ?? null;
+}
+export function assignSketchToDraft(draftId, sketchId) {
+    if (sketchOwners.get(sketchId) === draftId || !targetFromKey(draftId))
+        return;
+    sketchOwners.set(sketchId, draftId);
+    publish();
+}
+export function sketchBelongsToCard(document, cardId) {
+    if (!projectId || !cardId)
+        return true;
+    const draftId = draftIdForCard(cardId);
+    return !!draftId && sketchOwner(document) === draftId;
+}
+export function subscribeDrafts(listener) {
+    listeners.add(listener);
+    return () => listeners.delete(listener);
+}
+export function getDraftsSnapshot() {
+    if (!snapshot) {
+        const ids = new Set([...listDraftIds(), ...getSketchStoreSnapshot().documents.flatMap((document) => sketchOwner(document) ?? [])]);
+        snapshot = { projectId, drafts: [...ids].flatMap((id) => getDraft(id) ?? []) };
+    }
+    return snapshot;
+}
+export function useDrafts() { return useSyncExternalStore(subscribeDrafts, getDraftsSnapshot, getDraftsSnapshot); }
+/** Discards stored and in-memory drafts for the current project. */
+export function clearDrafts() {
+    if (projectId && persistent && canWriteWorkspace()) {
+        try {
+            localStorage.removeItem(storageKey());
+        }
+        catch {
+            return;
+        }
+    }
+    sketchOwners.clear();
+    resetDraftChanges();
+    publish();
+}
+export function resetDrafts() {
+    projectId = "";
+    persistent = true;
+    sketchOwners.clear();
+    resetDraftChanges();
+    publish();
+}

package/dist/inspector/index.js

@@ -1,3 +1,4 @@
+import { startWorkspaceController } from "./workspace/controller.js";
 import { createElement } from "react";
 import { createRoot } from "react-dom/client";
 import { InspectorShell, toggleInspector, setInspectorOpen } from "./shell/InspectorShell.js";
@@ -8,20 +9,19 @@ import { isCanvasRenderer } from "./canvas/roleDetection.js";
 import { isKeyboardShortcutMessage } from "./canvas/frameProtocol.js";
 import { subscribeCanvasRendererMessages } from "./canvas/rendererMessageRouter.js";
 import { bootstrapRenderer } from "./canvas/rendererBootstrap.js";
-import { hydrateSession, enableAutoSave, scheduleAutoSave, scheduleCanvasSave, setRestoreCount, } from "./canvas/sessionStore.js";
-import { subscribeChanges, getChangesList } from "./changes/changesLog.js";
-import { subscribe as subscribeCanvas } from "./canvas/canvasStore.js";
-import { acquireLease, enableWriteGuard, hasWriteLease, releaseLease, subscribeOwnership, } from "./canvas/workspaceLease.js";
+import { setRestoreCount, } from "./canvas/sessionStore.js";
+import { getChangesList } from "./changes/changesLog.js";
+import { acquireLease, enableWriteGuard, hasWriteLease, subscribeOwnership, } from "./canvas/workspaceLease.js";
 import { cancelStaleDetection, startStaleDetection } from "./canvas/staleChangeDetector.js";
 import { LockedWorkspaceNotice } from "./canvas/LockedWorkspaceNotice.js";
 import { AppShell } from "./shell/AppShell.js";
 import { installInspectionBridge } from "./inspection/bridge.js";
-import { releaseDocumentProjection, subscribeStructuralChanges } from "./projection/structuralProjection.js";
+import { releaseDocumentProjection, getStructuralChanges } from "./projection/structuralProjection.js";
 import { cancelInlineTextEdit } from "./inline-text/inlineTextEditor.js";
 import { configureNudgeUiRuntime, getNudgeUiRuntimeConfig, isDemoRuntime } from "./runtime/runtimeConfig.js";
-import { setCanvasMode } from "./canvas/canvasStore.js";
+import { setCanvasMode } from "./canvas/viewStore.js";
 import { isNudgeUiDev, setNudgeUiHostDevFlag } from "./runtime/devFlag.js";
-import { clearClipboardHandoff, subscribeClipboardHandoff, } from "./prompt/clipboardHandoff.js";
+import { clearClipboardHandoff, } from "./prompt/clipboardHandoff.js";
 import { createWorkspace, InspectorSessionProvider, } from "./session/index.js";
 import { clearSketchClipboardHandoff } from "./sketch/handoff.js";
 import { cancelSketchInteraction, isSketchInteractionActive } from "./sketch/interaction.js";
@@ -34,8 +34,7 @@ let lockedRoot = null;
 const workspace = createWorkspace();
 let inspectorSession = null;
 let rendererBootstrapHandle = null;
-let beforeUnloadAttached = false;
-let persistenceSubscribed = false;
+let workspaceController = null;
 let unsubscribeOwnership = null;
 let removeInspectionBridge = null;
 let keyboardPeekHeld = false;
@@ -105,6 +104,8 @@ export function bootstrapNudgeUi(inspectorHost) {
         // The public demo shares the iframe editor while keeping the write lease,
         // persistence, and agent bridge disabled.
         setCanvasMode("canvas");
+        workspaceController?.dispose();
+        workspaceController = startWorkspaceController();
         mountInspector(inspectorHost);
         setInspectorOpen(false);
         return;
@@ -142,12 +143,17 @@ function startController(inspectorHost) {
     void initializeSketchStore(getNudgeUiRuntimeConfig().projectId).catch(() => undefined);
     unsubscribeOwnership?.();
     unsubscribeOwnership = subscribeOwnership((hasLease) => {
-        if (!hasLease)
+        if (!hasLease) {
+            workspaceController?.dispose();
+            workspaceController = null;
             mountLockedNotice(inspectorHost);
+        }
     });
-    const result = hydrateSession();
+    workspaceController?.dispose();
+    const result = startWorkspaceController();
+    workspaceController = result;
     if (result.restored) {
-        setRestoreCount(result.changeCount);
+        setRestoreCount(getChangesList().length + getStructuralChanges().length);
         const restored = getChangesList();
         if (restored.length > 0) {
             startStaleDetection(restored);
@@ -159,21 +165,6 @@ function startController(inspectorHost) {
         setCanvasMode("canvas");
     }
     mountInspector(inspectorHost);
-    enableAutoSave();
-    if (!beforeUnloadAttached) {
-        // enableAutoSave registers its flush listener first. Release the lease only
-        // after the pending session write has had a chance to pass the ownership
-        // gate during beforeunload.
-        window.addEventListener("beforeunload", releaseLease);
-        beforeUnloadAttached = true;
-    }
-    if (!persistenceSubscribed) {
-        subscribeChanges(() => scheduleAutoSave());
-        subscribeStructuralChanges(() => scheduleAutoSave());
-        subscribeClipboardHandoff(() => scheduleAutoSave());
-        subscribeCanvas(() => scheduleCanvasSave());
-        persistenceSubscribed = true;
-    }
 }
 function mountLockedNotice(host) {
     if (reactRoot) {
@@ -239,6 +230,8 @@ export function mountInspector(host) {
 export function unmountInspector() {
     rendererBootstrapHandle?.teardown();
     rendererBootstrapHandle = null;
+    workspaceController?.dispose();
+    workspaceController = null;
     unsubscribeOwnership?.();
     unsubscribeOwnership = null;
     if (lockedRoot) {

package/dist/inspector/inline-text/inlineTextEditor.js

@@ -1,3 +1,4 @@
+import { canEditDraft } from "../changes/draftChanges.js";
 import { useSyncExternalStore } from "react";
 import { appendChange } from "../changes/changesLog.js";
 import { registerInlineTextClearHandler } from "./inlineTextLifecycle.js";
@@ -1029,6 +1030,9 @@ export const inlineTextEditor = {
 /** Re-enter an existing canonical rendered-text projection through its empty
  * inspector affordance. This never guesses a new DOM target or source node. */
 export function beginInlineTextEditFromEmptyProjection(marker) {
+    if (!canEditDraft()) {
+        return { kind: "rejected", reason: "editing-active", message: "Wait for the iteration to finish saving before editing text." };
+    }
     if (!isNudgeUiDev()) {
         return {
             kind: "rejected",
@@ -1063,6 +1067,9 @@ export function beginInlineTextEditFromEmptyProjection(marker) {
     }
 }
 export function beginInlineTextEdit(element, point) {
+    if (!canEditDraft()) {
+        return { kind: "rejected", reason: "editing-active", message: "Wait for the iteration to finish saving before editing text." };
+    }
     if (!isNudgeUiDev()) {
         return {
             kind: "rejected",

package/dist/inspector/inspection/useBrowserCssInspection.js

@@ -5,6 +5,12 @@ const EMPTY_SELECTION = [];
 function isSelectedElementList(selected) {
     return Array.isArray(selected);
 }
+const EMPTY_VIEW = {
+    element: null,
+    elements: [],
+    stableProperties: [],
+    documentTokens: null,
+};
 function normalizeSelection(selected) {
     if (!selected)
         return EMPTY_SELECTION;
@@ -22,6 +28,9 @@ function inspectStableView(session, selected, state, includeDocumentTokens, elem
         : [];
     const documentTokens = includeDocumentTokens ? session.inspectTokens() : null;
     return {
+        selection: selected,
+        state,
+        session,
         element: primary,
         elements,
         stableProperties,
@@ -155,5 +164,10 @@ export function useBrowserCssInspection(selected, state = "base", options = {})
         const timeoutId = setTimeout(warm, 200);
         return () => clearTimeout(timeoutId);
     }, [session, selectedDocument]);
-    return view;
+    // Selection effects run after children render. Never expose the previous
+    // element's authored rows while the new selection is waiting for inspection.
+    const matchesSelection = view.session === session && view.state === state
+        && view.selection.length === selectedElements.length
+        && view.selection.every((element, index) => element.domElement === selectedElements[index]?.domElement);
+    return matchesSelection ? view : EMPTY_VIEW;
 }

package/dist/inspector/iterations/capture.d.ts

@@ -0,0 +1,2 @@
+/** Captures the visible DOM of a same-origin frame as a script-free HTML iteration. */
+export declare function captureHtmlIteration(frame: HTMLIFrameElement): Promise<string>;

package/dist/inspector/iterations/capture.js

@@ -0,0 +1,173 @@
+import { HTML_ARTIFACT_REVISION_ATTRIBUTE } from "../../transport/artifacts.js";
+/** Captures the visible DOM of a same-origin frame as a script-free HTML iteration. */
+export async function captureHtmlIteration(frame) {
+    const source = frame.contentDocument;
+    const view = frame.contentWindow;
+    if (!source || !view?.document.documentElement)
+        throw new Error("The frame is not ready to capture.");
+    await source.fonts?.ready;
+    await Promise.all([...source.images].map((image) => image.decode?.().catch(() => undefined)));
+    const original = source.documentElement;
+    const copy = original.cloneNode(true);
+    copy.removeAttribute(HTML_ARTIFACT_REVISION_ATTRIBUTE);
+    const sourceElements = [original, ...original.querySelectorAll("*")];
+    const copiedElements = [copy, ...copy.querySelectorAll("*")];
+    const assets = new Map();
+    for (let index = 0; index < sourceElements.length; index += 1) {
+        const sourceElement = sourceElements[index];
+        const copied = copiedElements[index];
+        if (sourceElement.nodeType !== 1 || copied.nodeType !== 1)
+            continue;
+        // Renderer IDs belong to the source iframe's node registry. The iteration's
+        // fresh registry can reuse those values for different nodes.
+        copied.removeAttribute("data-renderer-id");
+        // Preserve authored inline values (percentages, variables, and calc), rather
+        // than replacing them with computed dimensions at the capture viewport.
+        const inline = copied.getAttribute("style");
+        if (inline)
+            copied.setAttribute("style", await resolveCssUrls(inline, source.baseURI, assets));
+        if (sourceElement.tagName === "INPUT" && copied.tagName === "INPUT") {
+            const input = sourceElement;
+            copied.setAttribute("value", input.value);
+            if (input.checked)
+                copied.setAttribute("checked", "");
+            else
+                copied.removeAttribute("checked");
+        }
+        if (sourceElement.tagName === "TEXTAREA" && copied.tagName === "TEXTAREA")
+            copied.textContent = sourceElement.value;
+        if (sourceElement.tagName === "CANVAS" && copied.tagName === "CANVAS") {
+            try {
+                const image = source.createElement("img");
+                image.src = sourceElement.toDataURL();
+                for (const attribute of [...copied.attributes])
+                    image.setAttribute(attribute.name, attribute.value);
+                copied.replaceWith(image);
+            }
+            catch { /* Tainted canvases remain empty. */ }
+        }
+    }
+    const base = source.createElement("base");
+    base.href = source.querySelector("base")?.href ?? source.location.href;
+    copy.querySelectorAll("base").forEach((element) => element.remove());
+    (copy.querySelector("head") ?? copy).prepend(base);
+    copy.querySelectorAll('script, iframe, object, embed, meta[http-equiv="refresh"], meta[http-equiv="Content-Security-Policy"], link[rel=modulepreload], link[rel=preload]').forEach((element) => element.remove());
+    copy.querySelectorAll("[data-nudge-ui-mount], #nudge-ui-root").forEach((element) => element.remove());
+    copy.querySelectorAll("a, form").forEach((element) => {
+        element.removeAttribute("href");
+        element.removeAttribute("action");
+    });
+    copy.querySelectorAll("*").forEach((element) => {
+        for (const attribute of [...element.attributes]) {
+            if (/^on/i.test(attribute.name))
+                element.removeAttribute(attribute.name);
+        }
+    });
+    for (const image of copy.querySelectorAll("img")) {
+        const url = image.getAttribute("src");
+        if (url)
+            image.src = await inlineAsset(url, base.href, assets);
+    }
+    await captureStylesheets(source, copy, sourceElements, copiedElements, assets);
+    return `<!doctype html>\n${copy.outerHTML}`;
+}
+/** Copies live CSSOM rules in place so stylesheet order and media stay intact. */
+async function captureStylesheets(document, copy, sourceElements, copiedElements, assets) {
+    for (const sheet of [...document.styleSheets]) {
+        const owner = sheet.ownerNode;
+        // Some DOM implementations do not expose ownerNode.
+        const sourceNode = owner ?? sourceElements.find((element) => "sheet" in element && element.sheet === sheet);
+        const index = sourceNode ? sourceElements.indexOf(sourceNode) : -1;
+        const copiedNode = index >= 0 ? copiedElements[index] : undefined;
+        if (!copiedNode?.parentNode)
+            continue;
+        if (sheet.disabled) {
+            copiedNode.remove();
+            continue;
+        }
+        let css;
+        try {
+            css = [...sheet.cssRules].map((rule) => rule.cssText).join("\n");
+        }
+        catch {
+            if (!sheet.href)
+                continue;
+            try {
+                const response = await fetch(sheet.href);
+                if (!response.ok)
+                    continue;
+                css = await response.text();
+            }
+            catch {
+                // Keep the stylesheet link when CORS prevents embedding it. Its URL
+                // still resolves against the original base and retains responsiveness.
+                continue;
+            }
+        }
+        const style = document.createElement("style");
+        for (const attribute of [...copiedNode.attributes]) {
+            if (!["href", "rel", "integrity", "crossorigin"].includes(attribute.name)) {
+                style.setAttribute(attribute.name, attribute.value);
+            }
+        }
+        style.textContent = await resolveCssUrls(css, sheet.href ?? document.baseURI, assets);
+        // Captured edits become the iteration's base. The renderer must create its own
+        // managed stylesheet for new edits instead of clearing these captured rules.
+        if (style.id === "nudge-ui-styles") {
+            style.removeAttribute("id");
+            style.removeAttribute("data-nudge-ui");
+            style.setAttribute("data-nudge-capture-overrides", "");
+        }
+        copiedNode.replaceWith(style);
+    }
+    for (const sheet of document.adoptedStyleSheets ?? []) {
+        if (sheet.disabled)
+            continue;
+        const style = document.createElement("style");
+        style.textContent = await resolveCssUrls([...sheet.cssRules].map((rule) => rule.cssText).join("\n"), document.baseURI, assets);
+        (copy.querySelector("head") ?? copy).append(style);
+    }
+}
+async function resolveCssUrls(css, base, assets) {
+    const matches = [...css.matchAll(/url\(\s*(["']?)([^)"']+)\1\s*\)/g)];
+    const values = await Promise.all(matches.map((match) => inlineAsset(match[2], base, assets)));
+    let index = 0;
+    return css.replace(/url\(\s*(["']?)([^)"']+)\1\s*\)/g, () => `url("${values[index++]}")`);
+}
+async function inlineAsset(path, base, assets) {
+    if (path.trim().startsWith("#"))
+        return path;
+    let url;
+    try {
+        url = new URL(path, base).href;
+    }
+    catch {
+        return path;
+    }
+    if (!/^https?:/.test(url))
+        return url;
+    const existing = assets.get(url);
+    if (existing)
+        return existing;
+    const value = (async () => {
+        try {
+            const response = await fetch(url);
+            if (!response.ok || Number(response.headers.get("content-length")) > 4_000_000)
+                return url;
+            const blob = await response.blob();
+            if (blob.size > 4_000_000)
+                return url;
+            const bytes = new Uint8Array(await blob.arrayBuffer());
+            let binary = "";
+            for (let offset = 0; offset < bytes.length; offset += 8192) {
+                binary += String.fromCharCode(...bytes.subarray(offset, offset + 8192));
+            }
+            return `data:${blob.type || "application/octet-stream"};base64,${btoa(binary)}`;
+        }
+        catch {
+            return url;
+        }
+    })();
+    assets.set(url, value);
+    return value;
+}

package/dist/inspector/iterations/client.d.ts

@@ -0,0 +1,7 @@
+import { type HtmlArtifactRevision } from "../../transport/artifacts.js";
+export declare function artifactDocumentUrl(id: string): string;
+export declare function readHtmlArtifactRevision(id: string): Promise<HtmlArtifactRevision>;
+/** Checks the editing base before saving and promoting a captured document. */
+export declare function commitHtmlArtifact(id: string, expected: HtmlArtifactRevision, html?: string): Promise<HtmlArtifactRevision>;
+export declare function createHtmlArtifact(frame: HTMLIFrameElement, sourceUrl: string, title: string, capturedHtml?: string): Promise<string>;
+export declare function removeHtmlArtifact(id: string): Promise<void>;

package/dist/inspector/iterations/client.js

@@ -0,0 +1,52 @@
+import { isHtmlArtifactRevision, HTML_ITERATION_CONFLICT } from "../../transport/artifacts.js";
+import { NUDGE_UI_ARTIFACTS_PATH } from "../../transport/routes.js";
+import { captureHtmlIteration } from "./capture.js";
+export function artifactDocumentUrl(id) {
+    return `${NUDGE_UI_ARTIFACTS_PATH}/${id}/preview`;
+}
+export async function readHtmlArtifactRevision(id) {
+    const response = await fetch(`${NUDGE_UI_ARTIFACTS_PATH}/${id}/revision`, { cache: "no-store", signal: AbortSignal.timeout(10000) });
+    if (!response.ok)
+        throw new Error("The HTML iteration could not be refreshed.");
+    const revision = await response.json();
+    if (!isHtmlArtifactRevision(revision))
+        throw new Error("The HTML iteration returned an invalid revision.");
+    return revision;
+}
+/** Checks the editing base before saving and promoting a captured document. */
+export async function commitHtmlArtifact(id, expected, html) {
+    const response = await fetch(`${NUDGE_UI_ARTIFACTS_PATH}/${id}/commit`, {
+        method: "POST",
+        signal: AbortSignal.timeout(10000),
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ expected, ...(html === undefined ? {} : { html }) }),
+    });
+    if (response.status === 409)
+        throw new Error(HTML_ITERATION_CONFLICT);
+    if (!response.ok)
+        throw new Error((await response.text()) || "The HTML iteration could not be saved.");
+    const revision = await response.json();
+    if (!isHtmlArtifactRevision(revision))
+        throw new Error("The HTML iteration returned an invalid revision.");
+    return revision;
+}
+export async function createHtmlArtifact(frame, sourceUrl, title, capturedHtml) {
+    const id = crypto.randomUUID();
+    const html = capturedHtml ?? await captureHtmlIteration(frame);
+    const response = await fetch(NUDGE_UI_ARTIFACTS_PATH, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({
+            id, html, sourceUrl, title,
+            viewport: { width: frame.clientWidth, height: frame.clientHeight },
+        }),
+    });
+    if (!response.ok)
+        throw new Error((await response.text()) || "The HTML iteration could not be saved.");
+    return id;
+}
+export async function removeHtmlArtifact(id) {
+    const response = await fetch(`${NUDGE_UI_ARTIFACTS_PATH}/${id}`, { method: "DELETE", keepalive: true });
+    if (!response.ok)
+        throw new Error((await response.text()) || "The HTML iteration could not be removed.");
+}

package/dist/inspector/iterations/coordinator.d.ts

@@ -0,0 +1,15 @@
+import type { HtmlArtifactRevision } from "../../transport/artifacts.js";
+import { type DraftContents } from "../changes/draftChanges.js";
+/** Owned transport; tests use a working in-memory artifact store. */
+export interface HtmlIterationStorage {
+    readRevision(id: string): Promise<HtmlArtifactRevision>;
+    commit(id: string, expected: HtmlArtifactRevision, html?: string): Promise<HtmlArtifactRevision>;
+}
+/** Owns save ordering, draft settlement, and external document promotion. */
+export declare function createHtmlIterationCoordinator(storage: HtmlIterationStorage): {
+    prepare(cardId: string, artifactId: string, baseRevision: string, capture: () => Promise<string>): Promise<DraftContents>;
+    refresh(cardId: string, artifactId: string, baseRevision: string, available: () => boolean): Promise<boolean>;
+};
+/** Materializes pending intent before the agent can start editing document.html. */
+export declare function prepareHtmlIterationHandoff(cardId: string, artifactId: string, frame: HTMLIFrameElement): Promise<DraftContents>;
+export declare function refreshHtmlIteration(cardId: string, artifactId: string, frame: HTMLIFrameElement): Promise<boolean>;