nudge-ui 0.2.4 → 0.2.6

package/dist/inspector/projection/renderedInstance.js

@@ -1,9 +1,10 @@
-import { getActiveDraftChanges, getDraftChanges } from "../changes/draftChanges.js";
+import { getActiveDraftChanges, getDraftChanges } from "../drafts/store.js";
 import { inspectRootInvocations } from "../componentSemantics/adapterRegistry.js";
 import { escapeAttrValue } from "./cssEscapes.js";
 import { isNudgeUiDev } from "../runtime/devFlag.js";
 import { relocateSourceSite, sourceSiteSelector } from "../selection/sourceSite.js";
 import { isRenderedInstanceOverride } from "../changes/editModel.js";
+import { boundRuntimeEvidence, isRuntimeGeneratedSource, normalizeRuntimeTag, runtimeDomPath } from "../runtime/staticHtmlRuntimeIdentity.js";
 export { isRenderedInstanceOverride, isRenderedInstanceRef } from "../changes/editModel.js";
 const PROJECTION_ATTR = "data-projection-instance";
 let nextOverrideId = 1;
@@ -28,7 +29,6 @@ function candidates(doc, sourceSite) {
         return [];
     }
 }
-/** Captures conservative, serializable identity at the moment of the action. */
 export function captureRenderedInstance(el) {
     const cid = el.getAttribute("data-cid") ?? "";
     const src = el.getAttribute("data-src") ?? "";
@@ -45,19 +45,18 @@ export function captureRenderedInstance(el) {
             props: el.getAttribute("data-cprops"),
             text: normalizedText(el),
             ariaLabel: el.getAttribute("aria-label"),
+            ...(isRuntimeGeneratedSource(src) ? {
+                tagName: normalizeRuntimeTag(el.tagName),
+                domPath: runtimeDomPath(el),
+                elementId: boundRuntimeEvidence(el.id || null),
+            } : {}),
         },
     };
 }
-/**
- * Resolves exactly one element, or declines to apply. Occurrence documents the
- * captured placement, but structural previews can legitimately change it.
- * Evidence, narrowed by a recorded invocation when present, must therefore
- * identify one current candidate before an edit can be applied.
- */
+/** Occurrence documents captured placement, but structural previews can change it; evidence must identify exactly one current candidate. */
 export function resolveRenderedInstance(doc, ref) {
     const sourceCandidates = candidates(doc, ref.sourceSite);
     const { props, text, ariaLabel = null, invocation } = ref.locator;
-    // An ordinal alone is not an identity for a repeated source site.
     if (!invocation && sourceCandidates.length > 1 && props === null && text === null && ariaLabel === null) {
         return { status: "ambiguous" };
     }
@@ -78,18 +77,12 @@ export function resolveRenderedInstance(doc, ref) {
     }
     if (matchingEvidence.length === 0)
         return { status: "missing" };
-    // Evidence alone is never enough to choose between two identical rendered
-    // outputs. This is particularly important for structural anchors: applying
-    // one move to an arbitrary identical parent would reorder the wrong group.
+    // Evidence alone never chooses between identical outputs; an arbitrary pick would reorder the wrong group.
     if (matchingEvidence.length > 1)
         return { status: "ambiguous" };
     return { status: "resolved", element: matchingEvidence[0] };
 }
-/**
- * Resolves a reference whose source position may have moved since capture.
- * A relocated site still renders matching authored evidence, so an evidence
- * miss there is reported as ambiguous rather than as proof of absence.
- */
+/** A relocated site still renders matching evidence, so an evidence miss is reported as ambiguous, not missing. */
 export function resolveMovedRenderedInstance(doc, ref) {
     const exact = resolveRenderedInstance(doc, ref);
     if (exact.status !== "missing")
@@ -101,12 +94,7 @@ export function resolveMovedRenderedInstance(doc, ref) {
     const moved = resolveRenderedInstance(doc, { ...ref, sourceSite });
     return moved.status === "missing" ? { status: "ambiguous" } : moved;
 }
-/**
- * Captures identity for a structural target. When evidence matches several
- * identical outputs, the nearest component invocation whose entire output is
- * this element can still identify it. Otherwise the evidence-only reference
- * is returned and resolves as ambiguous.
- */
+/** Falls back to the nearest component invocation when evidence matches several identical outputs. */
 export function captureStructuralTarget(el) {
     const ref = captureRenderedInstance(el);
     if (!ref || resolveRenderedInstance(el.ownerDocument, ref).status !== "ambiguous")
@@ -119,7 +107,7 @@ export function captureStructuralTarget(el) {
     }
     return ref;
 }
-/** Checks stable source/evidence fields without treating a post-move ordinal as identity. */
+/** Ignores the ordinal, which is not identity after a move. */
 export function matchesRenderedInstanceEvidence(el, ref) {
     const { props, text, ariaLabel = null } = ref.locator;
     return (el.getAttribute("data-cid") ?? "") === ref.sourceSite.cid
@@ -128,14 +116,12 @@ export function matchesRenderedInstanceEvidence(el, ref) {
         && normalizedText(el) === text
         && el.getAttribute("aria-label") === ariaLabel;
 }
-/** Builds an instance override without changing the element's transient edit scope. */
 export function buildRenderedInstanceOverride(el) {
     const target = captureRenderedInstance(el);
     if (!target)
         return null;
     return buildRenderedInstanceOverrideForTarget(target);
 }
-/** Creates a serializable override for identity that was already validated. */
 export function buildRenderedInstanceOverrideForTarget(target) {
     return {
         id: `override-${crypto.randomUUID?.() ?? nextOverrideId++}`,
@@ -149,7 +135,6 @@ export function createRenderedInstanceOverride(el) {
     transientTargets.set(el, override);
     return override;
 }
-/** Returns an active transient target or the canonical target projected here. */
 export function getRenderedInstanceOverride(el) {
     const transient = transientTargets.get(el);
     if (transient)
@@ -166,7 +151,6 @@ export function instanceSelector(override) {
     const source = sourceSiteSelector(override.target.sourceSite.cid, override.target.sourceSite.src);
     return source ? `${source}[${PROJECTION_ATTR}="${escapeAttrValue(override.id)}"]` : null;
 }
-/** Extracts the distinct canonical targets which renderers must resolve. */
 export function collectRenderedInstanceOverrides(changes) {
     const result = new Map();
     for (const change of changes) {
@@ -253,10 +237,7 @@ function getDocumentState(doc) {
     documentStates.set(doc, state);
     return state;
 }
-/**
- * The document-projection adapter only applies a new canonical snapshot. A
- * later reconciliation changes diagnostics but never starts a reapply loop.
- */
+/** A later reconciliation changes diagnostics but never starts a reapply loop. */
 export function applyRenderedInstanceProjection(doc, overrides) {
     if (!isNudgeUiDev())
         return [];
@@ -294,7 +275,6 @@ export function setCanonicalRenderedInstanceOverrides(overrides) {
 export function getRenderedInstanceProjectionReports(doc) {
     return reportsByDocument.get(doc) ?? [];
 }
-/** Diagnostics arrive independently when a renderer reports or React reconciles. */
 export function subscribeRenderedInstanceDiagnostics(listener) {
     diagnosticListeners.add(listener);
     return () => diagnosticListeners.delete(listener);

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

@@ -1,13 +1,8 @@
 import type { FrameProjection } from "../canvas/projection.js";
 import type { StructuralChange, StructuralDelete, StructuralMove, StructuralProjectionReason, StructuralProjectionReport } from "../changes/structuralTypes.js";
 export { isStructuralChange, isStructuralDelete, isStructuralMove, isStructuralProjectionReport, } from "./structuralProjectionBoundary.js";
-/**
- * Controller-owned structural intent. It contains no DOM node, placeholder,
- * position, or renderer-local identity. Each document resolves a snapshot for
- * itself and keeps any physical preview artefacts private to that document.
- */
+/** Canonical intent carries no DOM node, placeholder, or renderer-local identity; each document keeps its own preview artefacts. */
 export type { StructuralChange, StructuralDelete, StructuralMove, StructuralProjectionReason, StructuralProjectionReport, StructuralProjectionStatus, } from "../changes/structuralTypes.js";
-/** Conservative HTML containment policy shared by gesture and projection code. */
 export declare function canContainElement(parent: HTMLElement, child: HTMLElement): boolean;
 export type StructuralMoveLegality = {
     valid: true;
@@ -18,11 +13,7 @@ export type StructuralMoveLegality = {
     valid: false;
     reason: StructuralProjectionReason;
 };
-/**
- * Applies the one conservative move policy used by guide calculation, commit,
- * and resolved document projection. The returned elements are document-local
- * and must never be stored in canonical structural intent.
- */
+/** Returned elements are document-local and must never be stored in canonical intent. */
 export declare function getStructuralMoveLegality(element: HTMLElement, destination: {
     parent: HTMLElement;
     before: Node | null;
@@ -32,65 +23,33 @@ export interface StructuralChangeDiagnostic extends StructuralProjectionReport {
 }
 /** Returns bounded view state used to verify a delete in the same rendered view. */
 export declare function documentStateKey(doc: Document, excluded?: HTMLElement): string | undefined;
-/** Captures a delete intent once, in the controller, at the user gesture. */
 export declare function createStructuralDelete(element: HTMLElement, id?: string): StructuralDelete | null;
-/**
- * Capture a move only when every address can be represented by durable
- * rendered-instance references. Local DOM positions are deliberately never a
- * fallback: a missed preview is safer than moving the wrong item.
- */
+/** Local DOM positions are never a fallback: a missed preview beats moving the wrong item. */
 export declare function createStructuralMove(element: HTMLElement, destination: {
     parent: HTMLElement;
     before: Node | null;
 }, id?: string): StructuralMove | null;
 export declare function getStructuralChanges(): readonly StructuralChange[];
 export declare function getStructuralDeletes(): readonly StructuralDelete[];
-/** Revert removes one canonical intent and leaves every other intent intact. */
 export declare function revertStructuralChange(changeId: string): boolean;
-/**
- * Removes source-verified structural intents without leaving an undo path that
- * can recreate their browser-only previews.
- *
- * Agent completion can verify a subset of one dispatched snapshot. The
- * remaining records and their useful history stay intact while every verified
- * ID is pruned from canonical state, undo/redo snapshots, and Canvas reports.
- */
-export declare function reconcileVerifiedStructuralChanges(verifiedIds: ReadonlySet<string>): number;
 /** State changes drive controller-to-renderer projection. Diagnostics do not. */
 export declare function subscribeStructuralChanges(listener: () => void): () => void;
 /** Compatibility name retained while the controller moved to a full union. */
 export declare const subscribeStructuralDeletes: typeof subscribeStructuralChanges;
-/** Diagnostics change after host/frame resolution or a one-shot conflict check. */
 export declare function subscribeStructuralDiagnostics(listener: () => void): () => void;
-/** Monotonic snapshot for React consumers of document-local diagnostics. */
 export declare function getStructuralDiagnosticRevision(): number;
-/**
- * Apply one full controller snapshot to one document. Physical nodes and
- * placeholders stay in the document state only; history stays serializable in
- * the controller. A same snapshot never reapplies an overridden preview.
- */
+/** Physical nodes stay document-local; an unchanged snapshot never reapplies an overridden preview. */
 export declare function applyStructuralProjection(doc: Document, snapshot: readonly StructuralChange[]): StructuralProjectionReport[];
-/** Compatibility entry point for the delete-only 0050 callers. */
+/** Compatibility entry point for delete-only callers. */
 export declare function applyStructuralDeleteProjection(doc: Document, snapshot: readonly StructuralDelete[]): StructuralProjectionReport[];
 export declare function getStructuralProjectionReports(doc: Document): readonly StructuralProjectionReport[];
-/**
- * Frames may report only their document-local outcome. The controller owns
- * these reports and filters them against its current canonical change set.
- */
+/** Frames report document-local outcomes; the controller filters them against its canonical change set. */
 export declare function recordCanvasStructuralProjectionReports(cardId: string, revision: number, reports: readonly StructuralProjectionReport[], projection?: FrameProjection): void;
 export declare function clearCanvasStructuralProjectionReports(cardId: string): void;
-/** Removes document-local reports for canonical intents that no longer exist. */
 export declare function pruneStructuralProjectionReports(changeIds: ReadonlySet<string>): void;
-/** Clears reports before restoring or clearing an atomic workspace snapshot. */
 export declare function clearStructuralProjectionReports(): void;
 export declare function getStructuralChangeDiagnostics(changeId: string): StructuralChangeDiagnostic[];
 /** Controller teardown/test hook. It is not a user-visible history operation. */
 export declare function resetStructuralDeleteProjection(): void;
-/**
- * Releases one document's structural projection without touching canonical
- * workspace intent. Applied deletes/moves owned by this document are restored
- * and the document observer is disconnected; the controller snapshot stays
- * intact so a later remount can re-project from canonical state. Register as
- * a document-session cleanup alongside disposeBrowserCssInspection.
- */
+/** Restores this document's previews and disconnects its observer; canonical intent stays intact for a later remount. */
 export declare function releaseDocumentProjection(doc: Document): void;

package/dist/inspector/projection/structuralProjection.js

@@ -1,7 +1,6 @@
-import { getActiveDraftChanges, getDraftChanges } from "../changes/draftChanges.js";
+import { commitStructuralChange, getActiveDraftChanges, getDraftChanges, revertStructuralChange as revertDraftStructuralChange, subscribeActiveDraftChanges, } from "../drafts/store.js";
 import { captureRenderedInstance, captureStructuralTarget, matchesRenderedInstanceEvidence, resolveRenderedInstance, } from "./renderedInstance.js";
 import { isStructuralProjectionReport } from "./structuralProjectionBoundary.js";
-import { resetDraftChanges, draftChangeStore, } from "../changes/draftChanges.js";
 export { isStructuralChange, isStructuralDelete, isStructuralMove, isStructuralProjectionReport, } from "./structuralProjectionBoundary.js";
 const VOID_PARENT_TAGS = new Set([
     "area", "base", "br", "col", "embed", "hr", "img", "input", "link", "meta", "param", "source", "track", "wbr",
@@ -24,7 +23,6 @@ function isUnsupportedWrappedFlexRow(element) {
         && (style.flexDirection || "row").startsWith("row")
         && Boolean(style.flexWrap && style.flexWrap !== "nowrap");
 }
-/** Conservative HTML containment policy shared by gesture and projection code. */
 export function canContainElement(parent, child) {
     const parentTag = parent.tagName.toLowerCase();
     if (VOID_PARENT_TAGS.has(parentTag)
@@ -34,11 +32,7 @@ export function canContainElement(parent, child) {
         return false;
     return !PHRASING_PARENT_TAGS.has(parentTag) || isPhrasingElement(child);
 }
-/**
- * Applies the one conservative move policy used by guide calculation, commit,
- * and resolved document projection. The returned elements are document-local
- * and must never be stored in canonical structural intent.
- */
+/** Returned elements are document-local and must never be stored in canonical intent. */
 export function getStructuralMoveLegality(element, destination) {
     if (!element.isConnected)
         return { valid: false, reason: "target" };
@@ -109,8 +103,10 @@ function documentRoute(doc) {
     }
 }
 function stableStateValue(value, seen = new WeakSet()) {
-    if (!value || typeof value !== "object")
+    if (value === null || typeof value === "string" || typeof value === "number" || typeof value === "boolean")
         return value;
+    if (typeof value !== "object")
+        return String(value);
     if (seen.has(value))
         return "[Circular]";
     seen.add(value);
@@ -173,14 +169,15 @@ export function documentStateKey(doc, excluded) {
     }
 }
 function cloneSnapshot(snapshot) {
-    // Structural changes are small JSON-safe records. Cloning their top-level
-    // array is enough: no operation mutates a change or its nested references.
+    // Shallow clone is enough: no operation mutates a change or its nested references.
     return [...snapshot];
 }
-function projectStructuralChanges(snapshot) {
-    reprojectKnownDocuments(snapshot.structuralChanges);
+/** The Draft store already re-projected the host; this covers every other known document. */
+function projectStructuralChanges() {
+    const changes = getStructuralChanges();
+    for (const doc of documentStates.keys())
+        applyStructuralProjection(doc, changes);
 }
-/** Captures a delete intent once, in the controller, at the user gesture. */
 export function createStructuralDelete(element, id = structuralId()) {
     const target = captureStructuralTarget(element);
     if (!target)
@@ -194,16 +191,12 @@ export function createStructuralDelete(element, id = structuralId()) {
         ...(route ? { route } : {}),
         ...(state ? { state } : {}),
     };
-    if (!draftChangeStore.commitStructuralChange(change))
+    if (!commitStructuralChange(change))
         return null;
-    projectStructuralChanges(draftChangeStore.getSnapshot());
+    projectStructuralChanges();
     return change;
 }
-/**
- * Capture a move only when every address can be represented by durable
- * rendered-instance references. Local DOM positions are deliberately never a
- * fallback: a missed preview is safer than moving the wrong item.
- */
+/** Local DOM positions are never a fallback: a missed preview beats moving the wrong item. */
 export function createStructuralMove(element, destination, id = structuralId()) {
     const legality = getStructuralMoveLegality(element, destination);
     if (!legality.valid)
@@ -237,60 +230,33 @@ export function createStructuralMove(element, destination, id = structuralId())
                 : destinationChildren.length - (sameParent ? 1 : 0),
         },
     };
-    if (!draftChangeStore.commitStructuralChange(change))
+    if (!commitStructuralChange(change))
         return null;
-    projectStructuralChanges(draftChangeStore.getSnapshot());
+    projectStructuralChanges();
     return change;
 }
 export function getStructuralChanges() {
-    return draftChangeStore.getSnapshot().structuralChanges;
+    return getActiveDraftChanges().structuralChanges;
 }
 export function getStructuralDeletes() {
     return getStructuralChanges().filter((change) => change.kind === "delete");
 }
-/** Revert removes one canonical intent and leaves every other intent intact. */
 export function revertStructuralChange(changeId) {
-    const changed = draftChangeStore.revertStructuralChangeRecord(changeId);
+    const changed = revertDraftStructuralChange(changeId);
     if (changed)
-        projectStructuralChanges(draftChangeStore.getSnapshot());
+        projectStructuralChanges();
     return changed;
 }
-/**
- * Removes source-verified structural intents without leaving an undo path that
- * can recreate their browser-only previews.
- *
- * Agent completion can verify a subset of one dispatched snapshot. The
- * remaining records and their useful history stay intact while every verified
- * ID is pruned from canonical state, undo/redo snapshots, and Canvas reports.
- */
-export function reconcileVerifiedStructuralChanges(verifiedIds) {
-    if (verifiedIds.size === 0)
-        return 0;
-    const removed = draftChangeStore.reconcileActiveDraftChanges(new Set(), verifiedIds);
-    if (removed === 0)
-        return 0;
-    projectStructuralChanges(draftChangeStore.getSnapshot());
-    for (const [cardId, canvasReports] of reportsByCanvasCard) {
-        reportsByCanvasCard.set(cardId, {
-            ...canvasReports,
-            reports: canvasReports.reports.filter((report) => !verifiedIds.has(report.changeId)),
-        });
-    }
-    notifyDiagnostics();
-    return removed;
-}
 /** State changes drive controller-to-renderer projection. Diagnostics do not. */
 export function subscribeStructuralChanges(listener) {
-    return draftChangeStore.subscribe(listener);
+    return subscribeActiveDraftChanges(listener);
 }
 /** Compatibility name retained while the controller moved to a full union. */
 export const subscribeStructuralDeletes = subscribeStructuralChanges;
-/** Diagnostics change after host/frame resolution or a one-shot conflict check. */
 export function subscribeStructuralDiagnostics(listener) {
     diagnosticListeners.add(listener);
     return () => diagnosticListeners.delete(listener);
 }
-/** Monotonic snapshot for React consumers of document-local diagnostics. */
 export function getStructuralDiagnosticRevision() {
     return diagnosticRevision;
 }
@@ -311,6 +277,7 @@ function getDocumentState(doc) {
     return state;
 }
 function installDocumentObserver(doc, state) {
+    // SAFETY: attaches are read from the document's own realm so cross-origin frames use their own MutationObserver.
     const viewWithObserver = doc.defaultView;
     const Observer = viewWithObserver?.MutationObserver
         ?? (typeof MutationObserver !== "undefined" ? MutationObserver : undefined);
@@ -338,14 +305,10 @@ function scheduleValidation(doc, state) {
     state.validationQueued = true;
     queueMicrotask(() => {
         state.validationQueued = false;
-        // A renderer can receive its projection before its application tree has
-        // mounted. Retry unresolved records after that tree changes so a valid
-        // late mount converges without requiring another controller message.
+        // Retry unresolved records when the tree changes so a late-mounting renderer converges without another controller message.
         if (hasUnresolvedAppliedChange(state)) {
             rebuildForSnapshot(doc, state, state.snapshot, false);
-            // The replay is synchronous, so external renderer mutations cannot
-            // interleave with it. Discard only the records produced by the replay;
-            // future renderer mutations remain observed and can trigger another try.
+            // The replay is synchronous, so discarding its records only drops the replay's own mutations.
             state.observer?.takeRecords();
             storeReports(doc, reportsForSnapshot(state, state.snapshot));
             return;
@@ -379,8 +342,7 @@ function restoreApplied(local) {
     if (local.kind === "unresolved")
         return;
     if (local.kind === "delete") {
-        // If React already replaced our placeholder, never reinsert the stale
-        // detached node. The observer will (or already did) report overridden.
+        // Never reinsert a stale detached node when React already replaced our placeholder.
         if (local.placeholder.isConnected)
             local.placeholder.replaceWith(local.element);
         return;
@@ -391,8 +353,7 @@ function restoreApplied(local) {
     local.fromParent.insertBefore(local.element, anchor);
 }
 function rebuildForSnapshot(doc, state, snapshot, schedulePostReplayValidation = true) {
-    // React may have changed a projected node before its mutation callback ran.
-    // Validate synchronously so a rebuild never restores a framework-owned node.
+    // React may have changed a projected node before its mutation callback ran; validate before rebuilding.
     validateAppliedPreview(doc, state);
     const activeIds = new Set(snapshot.map((change) => change.id));
     const retainedOverrides = new Map();
@@ -400,9 +361,7 @@ function rebuildForSnapshot(doc, state, snapshot, schedulePostReplayValidation =
         if (local.status === "overridden" && activeIds.has(id))
             retainedOverrides.set(id, local);
     }
-    // Undo in reverse application order, reconstructing this document's source
-    // baseline before replaying the desired canonical sequence. This is what
-    // makes reverting an earlier move correct when later moves remain.
+    // Undo in reverse order to reconstruct the source baseline; this is what makes reverting an earlier move correct when later moves remain.
     for (const id of [...state.appliedOrder].reverse()) {
         const local = state.applied.get(id);
         if (local && local.status !== "overridden")
@@ -418,8 +377,7 @@ function rebuildForSnapshot(doc, state, snapshot, schedulePostReplayValidation =
             continue;
         applyChangeToDocument(doc, state, change);
     }
-    // Moves need to verify the final placement, after all later canonical
-    // operations have replayed, rather than the transient first insertion.
+    // Verify the final placement after all later canonical operations replayed, not the transient first insertion.
     for (const local of state.applied.values()) {
         if (local.kind === "move" && local.status === "applied") {
             local.expectedParent = local.element.parentElement ?? local.expectedParent;
@@ -503,13 +461,6 @@ function validationStatus(local) {
         ? "applied"
         : "overridden";
 }
-/** Rebuild already-mounted document adapters from canonical data only. */
-function reprojectKnownDocuments(changes = getStructuralChanges()) {
-    for (const [doc, state] of documentStates) {
-        rebuildForSnapshot(doc, state, changes);
-        storeReports(doc, reportsForSnapshot(state, state.snapshot));
-    }
-}
 function validateAppliedPreview(doc, state) {
     let changed = false;
     for (const local of state.applied.values()) {
@@ -525,11 +476,7 @@ function validateAppliedPreview(doc, state) {
         return;
     storeReports(doc, reportsForSnapshot(state, state.snapshot));
 }
-/**
- * Apply one full controller snapshot to one document. Physical nodes and
- * placeholders stay in the document state only; history stays serializable in
- * the controller. A same snapshot never reapplies an overridden preview.
- */
+/** Physical nodes stay document-local; an unchanged snapshot never reapplies an overridden preview. */
 export function applyStructuralProjection(doc, snapshot) {
     const state = getDocumentState(doc);
     const key = JSON.stringify(snapshot);
@@ -539,17 +486,14 @@ export function applyStructuralProjection(doc, snapshot) {
     storeReports(doc, reports);
     return reports;
 }
-/** Compatibility entry point for the delete-only 0050 callers. */
+/** Compatibility entry point for delete-only callers. */
 export function applyStructuralDeleteProjection(doc, snapshot) {
     return applyStructuralProjection(doc, snapshot);
 }
 export function getStructuralProjectionReports(doc) {
     return reportsByDocument.get(doc) ?? [];
 }
-/**
- * Frames may report only their document-local outcome. The controller owns
- * these reports and filters them against its current canonical change set.
- */
+/** Frames report document-local outcomes; the controller filters them against its canonical change set. */
 export function recordCanvasStructuralProjectionReports(cardId, revision, reports, projection) {
     if (!Number.isSafeInteger(revision) || revision < 0 || !reports.every(isStructuralProjectionReport))
         return;
@@ -572,7 +516,6 @@ export function clearCanvasStructuralProjectionReports(cardId) {
         return;
     notifyDiagnostics();
 }
-/** Removes document-local reports for canonical intents that no longer exist. */
 export function pruneStructuralProjectionReports(changeIds) {
     if (changeIds.size === 0)
         return;
@@ -584,7 +527,6 @@ export function pruneStructuralProjectionReports(changeIds) {
     }
     notifyDiagnostics();
 }
-/** Clears reports before restoring or clearing an atomic workspace snapshot. */
 export function clearStructuralProjectionReports() {
     reportsByCanvasCard.clear();
     reportsByDocument = new WeakMap();
@@ -619,16 +561,9 @@ export function resetStructuralDeleteProjection() {
     reportsByCanvasCard.clear();
     nextStructuralId = 1;
     diagnosticRevision = 0;
-    resetDraftChanges();
     notifyDiagnostics();
 }
-/**
- * Releases one document's structural projection without touching canonical
- * workspace intent. Applied deletes/moves owned by this document are restored
- * and the document observer is disconnected; the controller snapshot stays
- * intact so a later remount can re-project from canonical state. Register as
- * a document-session cleanup alongside disposeBrowserCssInspection.
- */
+/** Restores this document's previews and disconnects its observer; canonical intent stays intact for a later remount. */
 export function releaseDocumentProjection(doc) {
     const state = documentStates.get(doc);
     if (!state) {

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

@@ -1,8 +1,8 @@
 import type { FrameProjection } from "../canvas/projection.js";
-import { isTextProjectionTargetValue, type TextContentChangeRecord, type TextProjectionTarget, type TextProjectionScope, type TextBindingEvidence } from "../inline-text/textChangeBoundary.js";
+import { isTextProjectionTargetValue, type TextContentChangeRecord, type TextProjectionTarget, type TextProjectionScope, type TextBindingEvidence } from "../changes/editModel.js";
 /** Strict JSON boundary guard for a text projection target. */
 export declare const isTextProjectionTarget: typeof isTextProjectionTargetValue;
-export type { TextProjectionTarget } from "../inline-text/textChangeBoundary.js";
+export type { TextProjectionTarget } from "../changes/editModel.js";
 export type TextProjectionStatus = "applied" | "missing" | "ambiguous" | "overridden";
 export interface TextProjectionReport {
     changeId: string;
@@ -17,7 +17,6 @@ export interface TextContentProjectionDiagnostic extends TextProjectionReport {
 export declare const TEXT_PROJECTION_ATTR = "data-projection-text";
 /** Inspector-owned hit target for a projected text node whose value is empty. */
 export declare const EMPTY_TEXT_PROJECTION_ATTR = "data-empty-text";
-/** Inspector-owned exact-node evidence paired with EMPTY_TEXT_PROJECTION_ATTR. */
 export declare const EMPTY_TEXT_PROJECTION_PATH_ATTR = "data-empty-text-path";
 export type TextProjectionResolution = {
     status: "resolved";
@@ -27,22 +26,17 @@ export type TextProjectionResolution = {
 } | {
     status: "ambiguous";
 };
-/** Find the exact text node represented by a target, tolerating a changed
- * child path only when one bounded before/after text node remains unique. */
+/** Tolerates a changed child path only when one before/after text node remains unique. */
 export declare function resolveTextProjectionTextNode(element: HTMLElement, target: Pick<TextProjectionTarget, "textNodePath"> & Partial<Pick<TextProjectionTarget, "beforeText">>, expectedText?: string | undefined): Text | null;
-/** Capture stable source/evidence identity without retaining a DOM reference. */
+export declare function isUnsafeTextHost(element: Element): boolean;
+export declare function isInApplicationEditingHost(element: Element): boolean;
+export declare function hasSafeMixedDescendants(element: HTMLElement): boolean;
 export declare function captureTextProjectionTarget(element: HTMLElement, beforeText?: string, selectedTextNode?: Text): TextProjectionTarget | null;
-/**
- * Resolve against source identity and bounded evidence. Occurrence is kept as
- * presentation metadata only and is never used to choose among identical
- * repeated outputs.
- */
+/** Occurrence is presentation metadata only; identical repeated outputs resolve as ambiguous. */
 export declare function resolveTextProjectionTarget(doc: Document, target: TextProjectionTarget, afterText?: string): TextProjectionResolution;
 export declare function textProjectionSelector(target: TextProjectionTarget): string | null;
 export declare function collectTextContentChanges(changes: ReadonlyArray<unknown>): TextContentChangeRecord[];
-/** Returns the canonical record represented by an inspector empty-text slot. */
 export declare function getTextContentChangeById(changeId: string): TextContentChangeRecord | null;
-/** Apply one controller-owned text snapshot to a document adapter. */
 export declare function applyTextContentProjection(doc: Document, changes: ReadonlyArray<TextContentChangeRecord>): TextProjectionReport[];
 /** Registers controller-owned text changes without projecting them into the editor shell. */
 export declare function setCanonicalTextContentChanges(changes: ReadonlyArray<TextContentChangeRecord>): void;