nudge-ui 0.2.2 → 0.2.4

package/dist/inspector/comments/verification.js

@@ -0,0 +1,52 @@
+import { getDraftChanges } from "../changes/draftChanges.js";
+import { documentTarget, targetKey } from "../drafts/model.js";
+import { isCanvasProjectionRevisionCurrent, projectDraftToDocument } from "../canvas/projection.js";
+import { commentFingerprint, commentViewport, resolveCommentElement } from "./element.js";
+import { commentRoute, getCommentClearRevision, getComments, removeComment } from "./store.js";
+const documentReads = new WeakMap();
+const readingDocuments = new WeakSet();
+export function isReadingCommentSource(doc) { return readingDocuments.has(doc); }
+/** Serializes clean reads and restores the latest previews even if the read fails. */
+export function readCommentSource(doc, read) {
+    const previous = documentReads.get(doc) ?? Promise.resolve();
+    const operation = previous.catch(() => undefined).then(async () => {
+        readingDocuments.add(doc);
+        try {
+            const revision = await projectDraftToDocument(doc, { changes: [], structuralChanges: [] });
+            if (revision === null || !isCanvasProjectionRevisionCurrent(doc, revision))
+                return null;
+            return read();
+        }
+        finally {
+            try {
+                await projectDraftToDocument(doc, getDraftChanges(targetKey(documentTarget(doc.location.href))));
+                // Deliver projection mutation records before accepting another source signal.
+                await new Promise((resolve) => setTimeout(resolve, 0));
+            }
+            finally {
+                readingDocuments.delete(doc);
+            }
+        }
+    });
+    documentReads.set(doc, operation);
+    return operation;
+}
+/** Changed, uniquely located elements resolve after handoff; missing and ambiguous targets remain. */
+export async function reconcileComments(doc) {
+    const revision = getCommentClearRevision();
+    const sent = getComments().filter((item) => item.handedOff && item.route === commentRoute(doc));
+    if (sent.length === 0)
+        return;
+    const resolved = await readCommentSource(doc, () => sent.filter((item) => {
+        if (item.viewport !== commentViewport(doc))
+            return false;
+        const element = resolveCommentElement(doc, item.target);
+        return element !== null && commentFingerprint(element) !== item.baseline;
+    }));
+    if (revision !== getCommentClearRevision())
+        return;
+    for (const item of resolved ?? []) {
+        if (getComments().some((current) => current.id === item.id && current.note === item.note && current.handedOff))
+            removeComment(item.id);
+    }
+}

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

@@ -1,7 +1,12 @@
-import type { ComponentOverride, ComponentRuntimeAdapter, EditableComponentTarget, RuntimeComponentTarget } from "./types.js";
+import type { ComponentOverride, ComponentRootInvocation, ComponentRuntimeAdapter, EditableComponentTarget, RuntimeComponentTarget } from "./types.js";
 /** Register a framework adapter without coupling semantic resolution to React. */
 export declare function registerComponentRuntimeAdapter(adapter: ComponentRuntimeAdapter): () => void;
 export declare function inspectComponentTargets(element: HTMLElement): RuntimeComponentTarget[];
+/**
+ * Returns the invocations, nearest first, whose entire rendered output is this
+ * element. Null means no enabled runtime could read the element's ancestry.
+ */
+export declare function inspectRootInvocations(element: HTMLElement): ComponentRootInvocation[] | null;
 /**
  * Resolve multiplicity through the owning runtime Adapter. The inspector does
  * not infer it from DOM order or retain a React fiber as durable identity.

package/dist/inspector/componentSemantics/adapterRegistry.js

@@ -1,5 +1,5 @@
 import { getNudgeUiRuntimeConfig } from "../runtime/runtimeConfig.js";
-import { copyComponentOverrides, copyRuntimeTarget, getHostRuntimeAdapters, registerHostRuntimeAdapter, replaceHostRuntimeAdapterOverrides, } from "./runtimeBridge.js";
+import { copyComponentOverrides, copyRootInvocations, copyRuntimeTarget, getHostRuntimeAdapters, registerHostRuntimeAdapter, replaceHostRuntimeAdapterOverrides, } from "./runtimeBridge.js";
 const diagnosedAdapters = new WeakSet();
 function enabledRuntimeAdapters(ownerGlobal) {
     if (!getNudgeUiRuntimeConfig().capabilities.componentSemantics)
@@ -42,6 +42,28 @@ export function inspectComponentTargets(element) {
     }
     return targets;
 }
+/**
+ * Returns the invocations, nearest first, whose entire rendered output is this
+ * element. Null means no enabled runtime could read the element's ancestry.
+ */
+export function inspectRootInvocations(element) {
+    let invocations = null;
+    const ownerGlobal = element.ownerDocument.defaultView ?? globalThis;
+    for (const adapter of enabledRuntimeAdapters(ownerGlobal)) {
+        if (!adapter.rootInvocations)
+            continue;
+        try {
+            const inspected = adapter.rootInvocations(element);
+            if (inspected === null || inspected === undefined)
+                continue;
+            invocations = [...(invocations ?? []), ...copyRootInvocations(inspected)];
+        }
+        catch (error) {
+            diagnoseAdapter(adapter, error instanceof Error ? error.message : String(error));
+        }
+    }
+    return invocations;
+}
 function diagnoseAdapter(adapter, detail) {
     if (diagnosedAdapters.has(adapter))
         return;

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

@@ -1,10 +1,11 @@
 import { type ReactElement } from "react";
-import type { ComponentInvocationMeta, ComponentOverride, ComponentRuntimeAdapter, RuntimeComponentTarget } from "./types.js";
+import type { ComponentInvocationMeta, ComponentOverride, ComponentRootInvocation, ComponentRuntimeAdapter, RuntimeComponentTarget } from "./types.js";
 /** Returns null when this runtime has no mounted boundary for the callsite. */
 export declare function getReactCallsiteMultiplicity(callsiteId: string): number | null;
 /** Test/runtime teardown hook; canonical changes never depend on this state. */
 export declare function resetReactComponentRuntime(): void;
 export declare function instrumentReactComponent(element: ReactElement<Record<string, unknown>>, meta: ComponentInvocationMeta): ReactElement;
 export declare function inspectReactComponentTargets(element: HTMLElement): RuntimeComponentTarget[];
+export declare function inspectReactRootInvocations(element: HTMLElement): ComponentRootInvocation[] | null;
 export declare function replaceReactComponentOverrides(overrides: ComponentOverride[]): void;
 export declare const reactComponentRuntimeAdapter: ComponentRuntimeAdapter;

package/dist/inspector/componentSemantics/reactRuntime.js

@@ -4,6 +4,9 @@ import { getNudgeUiRuntimeConfig } from "../runtime/runtimeConfig.js";
 const BOUNDARY_MARKER = Symbol.for("nudge-ui.react-component-boundary");
 const EMPTY_OVERRIDE = Object.freeze({});
 const REACT_MAJOR_VERSION = Number.parseInt(reactVersion, 10);
+/** React work tags for host output that has no string element type. */
+const HOST_PORTAL_TAG = 4;
+const HOST_TEXT_TAG = 6;
 let overridesByCallsite = new Map();
 const listeners = new Set();
 /**
@@ -161,6 +164,40 @@ export function inspectReactComponentTargets(element) {
     }
     return targets;
 }
+function isHostOutput(fiber) {
+    return typeof fiber.type === "string" || fiber.tag === HOST_TEXT_TAG || fiber.tag === HOST_PORTAL_TAG;
+}
+/** Counts top-level host outputs below a fiber, stopping once there are two. */
+function hostOutputCount(fiber) {
+    let count = 0;
+    const visit = (parent) => {
+        for (let child = parent.child ?? null; child && count < 2; child = child.sibling ?? null) {
+            if (isHostOutput(child))
+                count += 1;
+            else
+                visit(child);
+        }
+    };
+    visit(fiber);
+    return count;
+}
+export function inspectReactRootInvocations(element) {
+    if (!getNudgeUiRuntimeConfig().capabilities.componentSemantics)
+        return null;
+    const host = findFiber(element);
+    if (!host)
+        return null;
+    const invocations = [];
+    for (let fiber = host.return ?? null; fiber && !isHostOutput(fiber); fiber = fiber.return ?? null) {
+        if (!isBoundaryType(fiber.type) || !fiber.memoizedProps?.meta)
+            continue;
+        if (hostOutputCount(fiber) !== 1)
+            break;
+        const { callsiteId, componentName } = fiber.memoizedProps.meta;
+        invocations.push({ callsiteId, componentName });
+    }
+    return invocations;
+}
 export function replaceReactComponentOverrides(overrides) {
     if (!getNudgeUiRuntimeConfig().capabilities.componentSemantics)
         return;
@@ -182,5 +219,6 @@ export const reactComponentRuntimeAdapter = {
     inspect: inspectReactComponentTargets,
     replaceOverrides: replaceReactComponentOverrides,
     getCallsiteMultiplicity: getReactCallsiteMultiplicity,
+    rootInvocations: inspectReactRootInvocations,
 };
 registerHostRuntimeAdapter(reactComponentRuntimeAdapter);

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

@@ -1,5 +1,5 @@
-import type { ComponentOverride, ComponentRuntimeAdapter, RuntimeComponentTarget } from "./types.js";
-export type { ComponentFramework, ComponentInvocationMeta, ComponentOverride, ComponentRuntimeAdapter, RuntimeComponentTarget, } from "./types.js";
+import type { ComponentOverride, ComponentRootInvocation, ComponentRuntimeAdapter, RuntimeComponentTarget } from "./types.js";
+export type { ComponentFramework, ComponentInvocationMeta, ComponentOverride, ComponentRootInvocation, ComponentRuntimeAdapter, RuntimeComponentTarget, } from "./types.js";
 /** Version of the page-global host runtime Adapter Interface. */
 export declare const NUDGE_UI_HOST_RUNTIME_VERSION = 1;
 /**
@@ -21,5 +21,7 @@ export declare function replaceHostRuntimeAdapterOverrides(overrides: readonly C
  * the host/client seam.
  */
 export declare function copyRuntimeTarget(target: RuntimeComponentTarget): RuntimeComponentTarget;
+/** Copies a host Adapter's root invocations into plain protocol data. */
+export declare function copyRootInvocations(invocations: readonly ComponentRootInvocation[]): ComponentRootInvocation[];
 /** Copies override commands before dispatching them into a host Adapter. */
 export declare function copyComponentOverrides(overrides: readonly ComponentOverride[]): ComponentOverride[];

package/dist/inspector/componentSemantics/runtimeBridge.js

@@ -104,6 +104,23 @@ export function copyRuntimeTarget(target) {
         ...(target.mountedCount === undefined ? {} : { mountedCount: target.mountedCount }),
     };
 }
+/** Copies a host Adapter's root invocations into plain protocol data. */
+export function copyRootInvocations(invocations) {
+    if (!Array.isArray(invocations)) {
+        throw new TypeError("Nudge UI received invalid root invocations from a host Adapter.");
+    }
+    return invocations.map((invocation) => {
+        if (invocation === null
+            || typeof invocation !== "object"
+            || typeof invocation.callsiteId !== "string"
+            || invocation.callsiteId.length === 0
+            || typeof invocation.componentName !== "string"
+            || invocation.componentName.length === 0) {
+            throw new TypeError("Nudge UI received an invalid root invocation from a host Adapter.");
+        }
+        return { callsiteId: invocation.callsiteId, componentName: invocation.componentName };
+    });
+}
 /** Copies override commands before dispatching them into a host Adapter. */
 export function copyComponentOverrides(overrides) {
     return overrides.map((override) => {

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

@@ -61,6 +61,11 @@ export interface RuntimeComponentTarget {
     /** Adapter-reported mounted invocation count for this callsite. */
     mountedCount?: number;
 }
+/** A component invocation whose entire rendered output is one DOM element. */
+export interface ComponentRootInvocation {
+    callsiteId: string;
+    componentName: string;
+}
 export interface ComponentPropContract {
     name: string;
     control: "select" | "boolean" | "text";
@@ -93,4 +98,10 @@ export interface ComponentRuntimeAdapter {
      * fail closed instead of broadening a semantic override.
      */
     getCallsiteMultiplicity?(callsiteId: string): number | null | undefined;
+    /**
+     * Return, nearest first, the invocations whose entire rendered output is
+     * this element. A runtime that cannot read the element's ancestry must
+     * return null so structural identity fails closed.
+     */
+    rootInvocations?(element: HTMLElement): ComponentRootInvocation[] | null;
 }

package/dist/inspector/drafts/model.d.ts

@@ -0,0 +1,35 @@
+import type { DraftContents } from "../changes/draftChanges.js";
+export type DraftTarget = {
+    readonly kind: "application";
+    readonly route: string;
+} | {
+    readonly kind: "html";
+    readonly artifactId: string;
+    readonly path: string;
+};
+/** A draft's ID is its target key, so every frame showing the same page or iteration edits one draft. */
+export interface Draft {
+    readonly id: string;
+    readonly target: DraftTarget;
+    readonly revision: number;
+    readonly contents: DraftContents;
+    readonly sketchIds: readonly string[];
+}
+export interface DraftSnapshot {
+    readonly projectId: string;
+    readonly drafts: readonly Draft[];
+}
+export declare function applicationTarget(url?: string): {
+    kind: "application";
+    route: string;
+};
+export declare function htmlTarget(artifactId: string): {
+    kind: "html";
+    artifactId: string;
+    path: string;
+};
+/** Maps a captured document URL to the draft that owns it: an iteration preview or an application page. */
+export declare function documentTarget(url: string): DraftTarget;
+export declare function targetKey(target: DraftTarget): string;
+export declare function targetFromKey(key: string): DraftTarget | null;
+export declare function isDraftTarget(value: unknown): value is DraftTarget;

package/dist/inspector/drafts/model.js

@@ -0,0 +1,45 @@
+import { normalizeUrl, normalizedUrlKey } from "../canvas/normalizeUrl.js";
+const ARTIFACT_PATH = /^\/__nudge_ui__\/artifacts\/([a-f0-9-]{36})\//i;
+export function applicationTarget(url = window.location.href) {
+    const page = new URL(url, window.location.href);
+    page.searchParams.delete("nudge-ui");
+    page.searchParams.sort();
+    const normalized = normalizeUrl(page.href);
+    return { kind: "application", route: normalizedUrlKey(normalized) };
+}
+export function htmlTarget(artifactId) {
+    return { kind: "html", artifactId, path: `.nudge/artifacts/${artifactId}/document.html` };
+}
+/** Maps a captured document URL to the draft that owns it: an iteration preview or an application page. */
+export function documentTarget(url) {
+    const artifactId = ARTIFACT_PATH.exec(new URL(url, window.location.href).pathname)?.[1];
+    return artifactId ? htmlTarget(artifactId) : applicationTarget(url);
+}
+export function targetKey(target) {
+    return target.kind === "application" ? `application:${target.route}` : `html:${target.artifactId}`;
+}
+export function targetFromKey(key) {
+    if (key.startsWith("html:"))
+        return htmlTarget(key.slice("html:".length));
+    if (!key.startsWith("application:"))
+        return null;
+    const target = { kind: "application", route: key.slice("application:".length) };
+    return isDraftTarget(target) ? target : null;
+}
+export function isDraftTarget(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const target = value;
+    if (target.kind === "application") {
+        if (typeof target.route !== "string")
+            return false;
+        try {
+            return applicationTarget(target.route).route === target.route;
+        }
+        catch {
+            return false;
+        }
+    }
+    return target.kind === "html" && typeof target.artifactId === "string"
+        && target.path === `.nudge/artifacts/${target.artifactId}/document.html`;
+}

package/dist/inspector/drafts/store.d.ts

@@ -0,0 +1,28 @@
+import { type FrameContent } from "../canvas/frameContent.js";
+import { type DraftContents } from "../changes/draftChanges.js";
+import type { SketchDocument } from "../sketch/model.js";
+import { type Draft, type DraftSnapshot } from "./model.js";
+export declare function draftIdForContent(content: FrameContent): string;
+export declare function draftIdForCard(cardId: string): string | null;
+export declare function sketchOwner(document: SketchDocument): string | null;
+export declare function getDraft(id: string): Draft | null;
+export declare function getDraftForCard(cardId: string): Draft | null;
+export declare function getDraftContentsForCard(cardId: string): DraftContents | null;
+export declare function persistDrafts(): void;
+/** Replaces every in-memory draft with the stored drafts, so a tab that takes over never writes stale edits. */
+export declare function loadDrafts(nextProjectId: string, options?: {
+    persistent?: boolean;
+}): void;
+export declare function activateDraftForCard(cardId: string): void;
+export declare function activateDraft(draftId: string, preferredCardId?: string): void;
+export declare function clearSavedIterationDraft(cardId: string, expectedRevision?: number): boolean;
+/** Returns the first preferred frame that exists, then the first frame. */
+export declare function getEditableCardId(...preferredCardIds: readonly (string | null | undefined)[]): string | null;
+export declare function assignSketchToDraft(draftId: string, sketchId: string): void;
+export declare function sketchBelongsToCard(document: SketchDocument, cardId: string | null): boolean;
+export declare function subscribeDrafts(listener: () => void): () => void;
+export declare function getDraftsSnapshot(): DraftSnapshot;
+export declare function useDrafts(): DraftSnapshot;
+/** Discards stored and in-memory drafts for the current project. */
+export declare function clearDrafts(): void;
+export declare function resetDrafts(): void;

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();
+}