nudge-ui 0.2.5 → 0.2.6

package/dist/inspector/projection/managedStylesheet.js

@@ -42,9 +42,7 @@ export function ensureManagedSheet() {
     }
     let sheet = el.sheet;
     if (!sheet) {
-        // A browser may reject a newly-authored conditional rule (or a test DOM may
-        // not implement it). Recreate the managed element so later clear/revert
-        // operations can always recover instead of leaving history wedged.
+        // Recreate the element when the browser rejects the sheet so clear/revert can still recover.
         el.remove();
         el = doc.createElement("style");
         el.id = SHEET_ID;
@@ -64,7 +62,6 @@ export function ensureManagedSheet() {
 }
 function exposeManagedSheetText(doc) {
     if (isNudgeUiDev() && doc.defaultView) {
-        // Keep the canonical CSS available to dev diagnostics.
         doc.defaultView.__nudgeUiGetManagedSheetText = getManagedSheetText;
     }
 }
@@ -98,18 +95,12 @@ export function rulesToCssText(rules) {
     }
     return lines.join("\n");
 }
-/** Canonical rules retained so a framework can rehydrate a moved style node. */
+/** Retained so a framework can rehydrate a moved style node. */
 let managedRules = [];
-/** Synchronous serialized view of the rules currently projected into the managed sheet. */
 export function getManagedSheetText() {
     return rulesToCssText(managedRules);
 }
-/**
- * Rehydrate the CSSOM after moving the managed style element in <head>.
- *
- * Some browsers replace the CSSStyleSheet when that element is reattached.
- * Rewriting the canonical text keeps the new sheet and the model aligned.
- */
+/** Some browsers replace the CSSStyleSheet when the style element is reattached, so rewrite the canonical text. */
 function rehydrateManagedSheet(doc, el) {
     const sheet = el.sheet;
     if (!sheet)
@@ -130,10 +121,6 @@ function rehydrateManagedSheet(doc, el) {
     failedRehydrationCssText = el.sheet.cssRules.length === rules.length ? null : cssText;
     notifyBrowserStylesheetChange(doc);
 }
-/**
- * Writes the canonical projection to the managed style element and retains a
- * copy for rehydration if a framework moves or reparses that element.
- */
 function rebuildSheetText(rules) {
     const desired = rules.map((rule) => ({
         ...rule,
@@ -166,11 +153,7 @@ function rebuildSheetText(rules) {
         : null;
     notifyBrowserStylesheetChange(document);
 }
-/**
- * Replaces the managed sheet with the canonical projection. Keeping the
- * serialized rules authoritative avoids stale CSSStyleRule references when a
- * framework dev server reparses or reattaches style nodes during a render.
- */
+/** Serialized rules stay authoritative to avoid stale CSSStyleRule references when a framework reparses style nodes. */
 export function applyRules(rules) {
     ensureManagedSheet();
     const desired = [];
@@ -213,7 +196,6 @@ function hasImportantAuthorRule(el, property) {
     }
     return false;
 }
-/** Verify what the browser painted after the managed sheet was projected. */
 export function verifyPreview(el, property, requestedValue) {
     if (!el || !el.isConnected) {
         return { requestedValue, computedValue: "", status: "conflict", reason: "target-missing" };

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

@@ -18,50 +18,27 @@ export interface DocumentProjectionReport {
 export interface RenderedInstanceChangeDiagnostic extends DocumentProjectionReport {
     document: "Inspect" | `Canvas ${string}`;
 }
-/** Captures conservative, serializable identity at the moment of the action. */
 export declare function captureRenderedInstance(el: HTMLElement): RenderedInstanceRef | 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 declare function resolveRenderedInstance(doc: Document, ref: RenderedInstanceRef): ResolutionResult;
-/**
- * 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 declare function resolveMovedRenderedInstance(doc: Document, ref: RenderedInstanceRef): ResolutionResult;
-/**
- * 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 declare function captureStructuralTarget(el: HTMLElement): RenderedInstanceRef | null;
-/** Checks stable source/evidence fields without treating a post-move ordinal as identity. */
+/** Ignores the ordinal, which is not identity after a move. */
 export declare function matchesRenderedInstanceEvidence(el: HTMLElement, ref: RenderedInstanceRef): boolean;
-/** Builds an instance override without changing the element's transient edit scope. */
 export declare function buildRenderedInstanceOverride(el: HTMLElement): RenderedInstanceOverride | null;
-/** Creates a serializable override for identity that was already validated. */
 export declare function buildRenderedInstanceOverrideForTarget(target: RenderedInstanceRef): RenderedInstanceOverride;
 export declare function createRenderedInstanceOverride(el: HTMLElement): RenderedInstanceOverride | null;
-/** Returns an active transient target or the canonical target projected here. */
 export declare function getRenderedInstanceOverride(el: HTMLElement): RenderedInstanceOverride | null;
 export declare function clearRenderedInstanceOverride(el: HTMLElement): RenderedInstanceOverride | null;
 export declare function instanceSelector(override: RenderedInstanceOverride): string | null;
-/** Extracts the distinct canonical targets which renderers must resolve. */
 export declare function collectRenderedInstanceOverrides(changes: ReadonlyArray<unknown>): RenderedInstanceOverride[];
-/**
- * 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 declare function applyRenderedInstanceProjection(doc: Document, overrides: ReadonlyArray<RenderedInstanceOverride>): DocumentProjectionReport[];
 /** Registers controller-owned overrides without projecting them into the editor shell. */
 export declare function setCanonicalRenderedInstanceOverrides(overrides: ReadonlyArray<RenderedInstanceOverride>): void;
 export declare function getRenderedInstanceProjectionReports(doc: Document): readonly DocumentProjectionReport[];
-/** Diagnostics arrive independently when a renderer reports or React reconciles. */
 export declare function subscribeRenderedInstanceDiagnostics(listener: () => void): () => void;
 export declare function getRenderedInstanceDiagnosticRevision(): number;
 export declare function recordCanvasRenderedInstanceProjectionReports(cardId: string, revision: number, reports: readonly DocumentProjectionReport[], projection?: FrameProjection): void;

package/dist/inspector/projection/renderedInstance.js

@@ -29,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") ?? "";
@@ -54,16 +53,10 @@ export function captureRenderedInstance(el) {
         },
     };
 }
-/**
- * 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" };
     }
@@ -84,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")
@@ -107,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")
@@ -125,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
@@ -134,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++}`,
@@ -155,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)
@@ -172,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) {
@@ -259,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 [];
@@ -300,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,56 +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;
 /** 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

@@ -23,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)
@@ -33,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" };
@@ -108,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);
@@ -172,8 +169,7 @@ 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];
 }
 /** The Draft store already re-projected the host; this covers every other known document. */
@@ -182,7 +178,6 @@ function projectStructuralChanges() {
     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)
@@ -201,11 +196,7 @@ export function createStructuralDelete(element, id = structuralId()) {
     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)
@@ -250,7 +241,6 @@ export function getStructuralChanges() {
 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 = revertDraftStructuralChange(changeId);
     if (changed)
@@ -263,12 +253,10 @@ export function subscribeStructuralChanges(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;
 }
@@ -289,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);
@@ -316,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;
@@ -357,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;
@@ -369,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();
@@ -378,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")
@@ -396,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;
@@ -496,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);
@@ -510,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;
@@ -543,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;
@@ -555,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();
@@ -592,13 +563,7 @@ export function resetStructuralDeleteProjection() {
     diagnosticRevision = 0;
     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

@@ -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,28 +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;
-/** Whether an element's text is code, form state, or other non-prose content. */
 export declare function isUnsafeTextHost(element: Element): boolean;
-/** Whether an application-owned editing region contains the element. */
 export declare function isInApplicationEditingHost(element: Element): boolean;
-/** Whether replacing one text node inside the element keeps its authored markup. */
 export declare function hasSafeMixedDescendants(element: HTMLElement): boolean;
-/** Capture stable source/evidence identity without retaining a DOM reference. */
 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;