nudge-ui 0.2.4 → 0.2.6

package/dist/inspector/index.js

@@ -1,268 +1,6 @@
-import { startWorkspaceController } from "./workspace/controller.js";
-import { createElement } from "react";
-import { createRoot } from "react-dom/client";
-import { InspectorShell, toggleInspector, setInspectorOpen } from "./shell/InspectorShell.js";
-import { setSelectedElement } from "./selection/selectionStore.js";
-import { removeManagedSheet } from "./projection/managedStylesheet.js";
-import { isInspectorToggleShortcut, isOriginalPreviewShortcut, SEND_PROMPT_HOTKEY_EVENT, } from "./shell/shortcuts.js";
-import { isCanvasRenderer } from "./canvas/roleDetection.js";
-import { isKeyboardShortcutMessage } from "./canvas/frameProtocol.js";
-import { subscribeCanvasRendererMessages } from "./canvas/rendererMessageRouter.js";
-import { bootstrapRenderer } from "./canvas/rendererBootstrap.js";
-import { setRestoreCount, } from "./canvas/sessionStore.js";
-import { getChangesList } from "./changes/changesLog.js";
-import { acquireLease, enableWriteGuard, hasWriteLease, subscribeOwnership, } from "./canvas/workspaceLease.js";
-import { cancelStaleDetection, startStaleDetection } from "./canvas/staleChangeDetector.js";
-import { LockedWorkspaceNotice } from "./canvas/LockedWorkspaceNotice.js";
-import { AppShell } from "./shell/AppShell.js";
-import { installInspectionBridge } from "./inspection/bridge.js";
-import { releaseDocumentProjection, getStructuralChanges } from "./projection/structuralProjection.js";
-import { cancelInlineTextEdit } from "./inline-text/inlineTextEditor.js";
-import { configureNudgeUiRuntime, getNudgeUiRuntimeConfig, isDemoRuntime } from "./runtime/runtimeConfig.js";
-import { setCanvasMode } from "./canvas/viewStore.js";
-import { isNudgeUiDev, setNudgeUiHostDevFlag } from "./runtime/devFlag.js";
-import { clearClipboardHandoff, } from "./prompt/clipboardHandoff.js";
-import { createWorkspace, InspectorSessionProvider, } from "./session/index.js";
-import { clearSketchClipboardHandoff } from "./sketch/handoff.js";
-import { cancelSketchInteraction, isSketchInteractionActive } from "./sketch/interaction.js";
-import { setOriginalPreviewActive } from "./shell/originalPreview.js";
-import { initializeSketchStore } from "./sketch/store.js";
+export { bootstrapNudgeUi, mountInspector, unmountInspector } from "./boot.js";
 export { resolveNudgeUiClientEntry } from "../transport/editor.js";
-let hostElement = null;
-let reactRoot = null;
-let lockedRoot = null;
-const workspace = createWorkspace();
-let inspectorSession = null;
-let rendererBootstrapHandle = null;
-let workspaceController = null;
-let unsubscribeOwnership = null;
-let removeInspectionBridge = null;
-let keyboardPeekHeld = false;
-function onKeydown(e) {
-    if (isSketchInteractionActive())
-        return;
-    if (isInspectorToggleShortcut(e)) {
-        toggleInspector();
-        e.preventDefault();
-        return;
-    }
-    if (isOriginalPreviewShortcut(e)) {
-        keyboardPeekHeld = true;
-        setOriginalPreviewActive(true);
-        e.preventDefault();
-    }
-}
-function onKeyup(e) {
-    // Release only a keyboard-started peek so a button-held preview survives
-    // unrelated Backslash keyups (e.g. the panel-toggle shortcuts pressed
-    // mid-hold). A guarded keydown never sets the flag, so this stays a no-op
-    // for keyups without a matching hold.
-    if (e.code === "Backslash" && keyboardPeekHeld) {
-        keyboardPeekHeld = false;
-        setOriginalPreviewActive(false);
-    }
-}
-function onRendererKeyboardShortcut(message, identity) {
-    if (!isKeyboardShortcutMessage(message, identity))
-        return;
-    if (message.code === "KeyS" && message.phase === "keydown") {
-        window.dispatchEvent(new Event(SEND_PROMPT_HOTKEY_EVENT));
-        return;
-    }
-    if (message.code !== "Backslash")
-        return;
-    if (message.phase === "keydown") {
-        keyboardPeekHeld = true;
-        setOriginalPreviewActive(true);
-    }
-    else if (keyboardPeekHeld) {
-        keyboardPeekHeld = false;
-        setOriginalPreviewActive(false);
-    }
-}
-function disposeInspectorSession() {
-    const session = inspectorSession;
-    inspectorSession = null;
-    session?.dispose();
-}
-export function bootstrapNudgeUi(inspectorHost) {
-    const runtimeConfig = getNudgeUiRuntimeConfig();
-    const explicitDemo = isDemoRuntime();
-    if (!isNudgeUiDev() && !explicitDemo)
-        return;
-    if (explicitDemo) {
-        rendererBootstrapHandle?.teardown();
-        rendererBootstrapHandle = null;
-        // ADR-0014: only the configured demo runtime opens the shared dev gate
-        // for its own document. The bundle mode name alone must never flip it,
-        // so every build without both opt-ins stays governed by ADR-0002.
-        setNudgeUiHostDevFlag(true);
-        if (runtimeConfig.capabilities.canvas && isCanvasRenderer()) {
-            rendererBootstrapHandle = bootstrapRenderer() ?? null;
-            return;
-        }
-        // The public demo shares the iframe editor while keeping the write lease,
-        // persistence, and agent bridge disabled.
-        setCanvasMode("canvas");
-        workspaceController?.dispose();
-        workspaceController = startWorkspaceController();
-        mountInspector(inspectorHost);
-        setInspectorOpen(false);
-        return;
-    }
-    if (!runtimeConfig.capabilities.canvas) {
-        // A project can be reopened with a runtime that does not expose Canvas.
-        // Clear any stale in-memory mode before mounting the static inspector.
-        setCanvasMode("inspect");
-    }
-    rendererBootstrapHandle?.teardown();
-    rendererBootstrapHandle = null;
-    removeInspectionBridge?.();
-    removeInspectionBridge = installInspectionBridge();
-    if (getNudgeUiRuntimeConfig().capabilities.canvas && isCanvasRenderer()) {
-        rendererBootstrapHandle = bootstrapRenderer() ?? null;
-        return;
-    }
-    enableWriteGuard();
-    const leaseGranted = acquireLease();
-    if (!leaseGranted) {
-        mountLockedNotice(inspectorHost);
-        return;
-    }
-    startController(inspectorHost);
-}
-function startController(inspectorHost) {
-    if (!hasWriteLease()) {
-        mountLockedNotice(inspectorHost);
-        return;
-    }
-    if (lockedRoot) {
-        lockedRoot.unmount();
-        lockedRoot = null;
-    }
-    void initializeSketchStore(getNudgeUiRuntimeConfig().projectId).catch(() => undefined);
-    unsubscribeOwnership?.();
-    unsubscribeOwnership = subscribeOwnership((hasLease) => {
-        if (!hasLease) {
-            workspaceController?.dispose();
-            workspaceController = null;
-            mountLockedNotice(inspectorHost);
-        }
-    });
-    workspaceController?.dispose();
-    const result = startWorkspaceController();
-    workspaceController = result;
-    if (result.restored) {
-        setRestoreCount(getChangesList().length + getStructuralChanges().length);
-        const restored = getChangesList();
-        if (restored.length > 0) {
-            startStaleDetection(restored);
-        }
-    }
-    if (getNudgeUiRuntimeConfig().capabilities.canvas) {
-        // Normal controllers always host the iframe workspace. Hydration runs
-        // first so this mode change cannot discard cards, camera, or edits.
-        setCanvasMode("canvas");
-    }
-    mountInspector(inspectorHost);
-}
-function mountLockedNotice(host) {
-    if (reactRoot) {
-        reactRoot.unmount();
-        reactRoot = null;
-    }
-    try {
-        disposeInspectorSession();
-    }
-    finally {
-        cancelStaleDetection();
-        setInspectorOpen(false);
-        cancelInlineTextEdit();
-        cancelSketchInteraction();
-        clearSketchClipboardHandoff();
-        setSelectedElement(null);
-        removeManagedSheet();
-        releaseDocumentProjection(document);
-        hostElement = null;
-        unsubscribeOwnership?.();
-        unsubscribeOwnership = null;
-    }
-    const shadow = host.shadowRoot ?? host.attachShadow({ mode: "open" });
-    if (!lockedRoot) {
-        lockedRoot = createRoot(shadow);
-    }
-    lockedRoot.render(createElement(LockedWorkspaceNotice, {
-        onTakeover: () => startController(host),
-    }));
-}
-export function mountInspector(host) {
-    const demo = isDemoRuntime();
-    if (!demo && !hasWriteLease())
-        return;
-    const runtimeConfig = getNudgeUiRuntimeConfig();
-    if (runtimeConfig.capabilities.domNavigation !== true) {
-        configureNudgeUiRuntime({
-            ...runtimeConfig,
-            capabilities: { ...runtimeConfig.capabilities, domNavigation: true },
-        });
-    }
-    if (lockedRoot) {
-        lockedRoot.unmount();
-        lockedRoot = null;
-    }
-    if (!hostElement)
-        hostElement = host;
-    const shadow = host.shadowRoot ?? host.attachShadow({ mode: "open" });
-    if (!reactRoot) {
-        reactRoot = createRoot(shadow);
-        inspectorSession = workspace.createInspectorSession(host);
-        inspectorSession.registerCleanup(() => window.removeEventListener("keydown", onKeydown));
-        inspectorSession.registerCleanup(() => window.removeEventListener("keyup", onKeyup));
-        inspectorSession.registerCleanup(subscribeCanvasRendererMessages(({ identity, message }) => {
-            onRendererKeyboardShortcut(message, identity);
-        }));
-        reactRoot.render(createElement(InspectorSessionProvider, { inspector: inspectorSession, documentSession: null }, createElement(AppShell)));
-        window.addEventListener("keydown", onKeydown);
-        window.addEventListener("keyup", onKeyup);
-    }
-    setInspectorOpen(true);
-}
-export function unmountInspector() {
-    rendererBootstrapHandle?.teardown();
-    rendererBootstrapHandle = null;
-    workspaceController?.dispose();
-    workspaceController = null;
-    unsubscribeOwnership?.();
-    unsubscribeOwnership = null;
-    if (lockedRoot) {
-        lockedRoot.unmount();
-        lockedRoot = null;
-    }
-    cancelStaleDetection();
-    cancelInlineTextEdit();
-    cancelSketchInteraction();
-    setSelectedElement(null);
-    if (reactRoot) {
-        reactRoot.unmount();
-        reactRoot = null;
-    }
-    try {
-        disposeInspectorSession();
-    }
-    finally {
-        // Document-session cleanup already releases host projection when a
-        // session exists; release directly as well so projection applied outside
-        // a session (gestures, workspace projection) cannot leak across unmount.
-        releaseDocumentProjection(document);
-        clearClipboardHandoff();
-        clearSketchClipboardHandoff();
-        removeManagedSheet();
-        removeInspectionBridge?.();
-        removeInspectionBridge = null;
-        hostElement = null;
-    }
-}
-export { toggleInspector, setInspectorOpen } from "./shell/InspectorShell.js";
+export { toggleInspector, setInspectorOpen } from "./shell/openStore.js";
 export { InspectorShell } from "./shell/InspectorShell.js";
 export { detectFramework } from "./prompt/detectFramework.js";
 export { installStaticHtmlRuntimeIdentity, isRuntimeGeneratedSource, RUNTIME_ELEMENT_CID_PREFIX, RUNTIME_UNKNOWN_SOURCE_PREFIX, } from "./runtime/staticHtmlRuntimeIdentity.js";

package/dist/inspector/inline-text/inlineTextDiagnostics.d.ts

@@ -4,7 +4,5 @@ export declare function getInlineTextDiagnostics(): readonly InlineTextDiagnosti
 export declare function getInlineTextDiagnostic(): InlineTextDiagnostic | null;
 export declare function subscribeInlineTextDiagnostics(listener: () => void): () => void;
 export declare function useInlineTextDiagnostic(): InlineTextDiagnostic | null;
-/** Clear the current diagnostic, optionally only when it belongs to a frame. */
 export declare function clearInlineTextDiagnostics(ownerDocument?: Document): void;
-/** Keep feedback for the target that was just selected, but clear stale feedback. */
 export declare function clearInlineTextDiagnosticsForSelection(selectedElements: readonly HTMLElement[]): void;

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

@@ -43,7 +43,6 @@ export function useInlineTextDiagnostic() {
     useSyncExternalStore(subscribeInlineTextDiagnostics, () => revision, () => revision);
     return getInlineTextDiagnostic();
 }
-/** Clear the current diagnostic, optionally only when it belongs to a frame. */
 export function clearInlineTextDiagnostics(ownerDocument) {
     const current = diagnostics.at(-1);
     if (!current)
@@ -53,7 +52,6 @@ export function clearInlineTextDiagnostics(ownerDocument) {
     diagnostics = [];
     notify();
 }
-/** Keep feedback for the target that was just selected, but clear stale feedback. */
 export function clearInlineTextDiagnosticsForSelection(selectedElements) {
     const current = diagnostics.at(-1);
     if (!current)

package/dist/inspector/inline-text/inlineTextEditor.d.ts

@@ -1,6 +1,6 @@
 import { type TextBindingChoice, type TextEditBinding, type TextEditRejection, type TextEditRejectionReason } from "../componentSemantics/textBinding.js";
 import type { ChangeRecord } from "../changes/types.js";
-import type { TextProjectionScope } from "./textChangeBoundary.js";
+import type { TextProjectionScope } from "../changes/editModel.js";
 export type { TextEditBinding, TextEditRejection } from "../componentSemantics/textBinding.js";
 export type { TextBindingCandidate } from "../componentSemantics/textBinding.js";
 export interface InlineTextSession {
@@ -37,7 +37,6 @@ export declare function getInlineTextSession(): InlineTextSession | null;
 export declare function useInlineTextSession(): InlineTextSession | null;
 export declare function isInlineTextEditingActive(): boolean;
 export declare function cancelInlineTextEdit(): void;
-/** End a session owned by a document/frame that is about to be disposed. */
 export declare function disposeInlineTextEdit(reason?: "frame-disposed" | "route-disposed", ownerDocument?: Document): void;
 export type InlineTextEditIntent = {
     kind: "pointer-down";
@@ -55,15 +54,10 @@ export type InlineTextEditIntent = {
         y: number;
     };
 };
-/**
- * Handle one native interaction while keeping session-transition policy
- * local. Pointer-down preserves double-click intent across the first click's
- * blur commit, even when canonical projection replaces the target DOM.
- */
+/** Pointer-down preserves double-click intent across the first click's blur commit. */
 export declare function handleInlineTextEditIntent(intent: InlineTextEditIntent): InlineTextInteractionDisposition;
 export declare const inlineTextEditor: InlineTextEditor;
-/** Re-enter an existing canonical rendered-text projection through its empty
- * inspector affordance. This never guesses a new DOM target or source node. */
+/** Re-enters an existing projection; never guesses a new DOM target or source node. */
 export declare function beginInlineTextEditFromEmptyProjection(marker: HTMLElement): InlineTextSession | TextEditRejection;
 export declare function beginInlineTextEdit(element: HTMLElement, point?: {
     x: number;

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

@@ -1,6 +1,5 @@
-import { canEditDraft } from "../changes/draftChanges.js";
+import { appendChange, canEditDraft } from "../drafts/store.js";
 import { useSyncExternalStore } from "react";
-import { appendChange } from "../changes/changesLog.js";
 import { registerInlineTextClearHandler } from "./inlineTextLifecycle.js";
 import { isNudgeUiDev } from "../runtime/devFlag.js";
 import { initialTextEditDecision, chooseTextEditBinding, getTextEditScopeChoices, getTextEditBinding, prepareTextEditChange, } from "./textEditChange.js";
@@ -12,8 +11,7 @@ const listeners = new Set();
 let activeSession = null;
 let activeSessionDocument = null;
 let pendingEditIntent = null;
-// This remains armed if blur replaces the DOM between the second pointer-down
-// and dblclick; only the next handoff attempt or explicit teardown consumes it.
+// Stays armed if blur replaces the DOM between the second pointer-down and dblclick; the next handoff attempt or teardown consumes it.
 let handoffPointerArmed = false;
 let pendingReplayScheduled = false;
 let sessionRevision = 0;
@@ -52,7 +50,6 @@ export function cancelInlineTextEdit() {
     else
         clearInlineTextDiagnostics();
 }
-/** End a session owned by a document/frame that is about to be disposed. */
 export function disposeInlineTextEdit(reason = "frame-disposed", ownerDocument) {
     if (!ownerDocument) {
         discardPendingInlineTextEdit();
@@ -135,11 +132,7 @@ function schedulePendingInlineTextEdit() {
         drainPendingInlineTextEdit();
     });
 }
-/**
- * Request inline editing from a document gesture. This is the interaction
- * seam: it owns active-session handoff so gesture routers never discard a
- * valid target switch merely because another draft is settling.
- */
+/** Owns active-session handoff so gesture routers never discard a valid target switch. */
 function requestInlineTextEdit(target, point) {
     if (activeSession) {
         const hitTarget = target.ownerDocument.elementFromPoint?.(point.x, point.y);
@@ -148,10 +141,7 @@ function requestInlineTextEdit(target, point) {
             return "stop-propagation";
         }
     }
-    // Application-owned contenteditable surfaces must retain native editing
-    // semantics. They are intentionally rejected by text binding, but that
-    // rejection must not become an inspector-level suppression when another
-    // inline edit is already active.
+    // Application-owned contenteditable surfaces keep native editing semantics; their binding rejection must not become an inspector-level suppression.
     if (isApplicationOwnedEditingSurface(target))
         return "pass-through";
     const intent = {
@@ -171,11 +161,7 @@ function requestInlineTextEdit(target, point) {
         drainPendingInlineTextEdit();
     return "suppress";
 }
-/**
- * Handle one native interaction while keeping session-transition policy
- * local. Pointer-down preserves double-click intent across the first click's
- * blur commit, even when canonical projection replaces the target DOM.
- */
+/** Pointer-down preserves double-click intent across the first click's blur commit. */
 export function handleInlineTextEditIntent(intent) {
     if (intent.kind === "double-click") {
         return requestInlineTextEdit(intent.target, intent.point);
@@ -222,9 +208,7 @@ function restoreSelection(doc, snapshot) {
                 selection.addRange(range);
             }
             catch {
-                // A framework rerender can invalidate a saved range between cleanup
-                // and restoration. Removing the transient selection is safer than
-                // retaining a range in a detached editing wrapper.
+                // A framework rerender can invalidate a saved range; dropping the selection beats keeping a range in a detached wrapper.
                 selection.removeAllRanges();
             }
         }
@@ -241,14 +225,11 @@ function restoreDraft(candidate, host, text, ownership) {
     if (!hostIsOwned(candidate, host, ownership))
         return false;
     const original = candidate.textNode;
-    // Normal typing replaces the original node inside the wrapper, leaving it
-    // detached. If reconciliation moved that node into another live tree,
-    // never move it back into the captured position.
+    // Typing detaches the original node inside the wrapper; if reconciliation moved it into another live tree, never move it back.
     if (original.isConnected && original.parentNode !== host)
         return false;
     original.nodeValue = text;
-    // Keep the original Text node and replace only the transient wrapper. This
-    // preserves every sibling/descendant of an icon-plus-label host.
+    // Replacing only the transient wrapper preserves siblings/descendants of an icon-plus-label host.
     host.replaceWith(original);
     return true;
 }
@@ -269,8 +250,7 @@ function rangeInsideHost(host, range) {
     if (!isNodeInsideHost(host, range.startContainer)
         || !isNodeInsideHost(host, range.endContainer))
         return false;
-    // A host ancestor contains the common ancestor whenever both endpoints are
-    // inside it; StaticRange does not expose commonAncestorContainer.
+    // Endpoints inside the host imply the common ancestor is too; StaticRange does not expose commonAncestorContainer.
     return true;
 }
 function selectionInsideHost(host) {
@@ -412,8 +392,7 @@ function makeSession(candidate) {
     const originalParent = candidate.textNode.parentNode;
     const originalNextSibling = candidate.textNode.nextSibling;
     if (!originalParent) {
-        // `resolveTextBinding` only returns connected text nodes, but keep this
-        // boundary defensive if a framework mutates between resolution and wrap.
+        // resolveTextBinding returns connected text nodes, but a framework can mutate between resolution and wrap.
         throw new Error("Inline text target lost its parent before editing began.");
     }
     const ownership = { parent: originalParent, nextSibling: originalNextSibling };
@@ -424,12 +403,7 @@ function makeSession(candidate) {
     host.setAttribute("contenteditable", "plaintext-only");
     host.contentEditable = "plaintext-only";
     candidate.textNode.replaceWith(host);
-    // An empty Text node is retained for exact restoration, but leaving it as
-    // the first child of a native contenteditable makes Chromium insert the
-    // first character beside it. The input handler then has to coalesce two
-    // text nodes and the browser resets the caret to the start, reversing the
-    // visible draft. Let the empty editor start childless; restoreDraft still
-    // puts the captured node back at the owned insertion point on exit.
+    // A leading empty Text node makes Chromium insert the first character beside it and reset the caret; start childless and let restoreDraft put the node back on exit.
     if (candidate.before.length > 0)
         host.append(candidate.textNode);
     let finished = false;
@@ -487,8 +461,7 @@ function makeSession(candidate) {
         if (finished)
             return;
         const restoreFocus = editorOwnsFocus();
-        // A moved/reordered host has no safe insertion point. Remove only the
-        // temporary wrapper; never reinsert the original node into a new tree.
+        // A moved host has no safe insertion point: remove the wrapper, never reinsert the original node.
         if (host.isConnected)
             host.remove();
         finish("app-reconciled", "cancelled", discardedDraft, restoreFocus);
@@ -554,9 +527,7 @@ function makeSession(candidate) {
                 }
             }
         }
-        // A cancelled/unchanged re-entry keeps the same affordance. A committed
-        // non-empty value is synchronously reconciled by the text projection,
-        // which removes it after this session cleanup.
+        // Restore the affordance on cancel/unchanged; a committed non-empty value is removed by projection reconciliation.
         if (candidate.emptyProjectionMarker?.isConnected) {
             candidate.emptyProjectionMarker.hidden = false;
         }
@@ -567,8 +538,7 @@ function makeSession(candidate) {
         if (finished)
             return;
         if (event.isComposing || composing) {
-            // Enter/Escape belong to the IME until compositionend. Keeping the
-            // session alive makes the composition one canonical edit.
+            // Enter/Escape belong to the IME until compositionend; keeping the session alive makes the composition one canonical edit.
             event.stopPropagation();
             if (event.key === "Enter" || event.key === "Escape" || event.key === "Esc") {
                 event.preventDefault();
@@ -593,10 +563,7 @@ function makeSession(candidate) {
             session.cancel();
             return;
         }
-        // Keep inspector keyboard authority out of the draft while allowing the
-        // browser to handle ordinary typing and caret movement natively. The
-        // listener is scoped to this host so it does not intercept native input
-        // before the contenteditable target sees it.
+        // Keep inspector shortcuts out of the draft while native typing and caret movement still run.
         event.stopPropagation();
     }
     function onBlur() {
@@ -605,8 +572,7 @@ function makeSession(candidate) {
         blurPending = true;
         if (composing)
             return;
-        // Deferring one macrotask lets Escape cancel a browser blur that occurs
-        // while a contenteditable host is handling the key event.
+        // Deferring one macrotask lets Escape cancel a blur that fires while the host handles the key event.
         blurCommitHandle = setTimeout(() => {
             blurCommitHandle = null;
             if (!finished) {
@@ -619,8 +585,7 @@ function makeSession(candidate) {
         if (finished)
             return;
         const rejectBeforeInput = (reason) => {
-            // Some browsers still deliver input after a non-cancelable beforeinput.
-            // Remember the safe plain draft so that onInput can undo that mutation.
+            // Some browsers still deliver input after a non-cancelable beforeinput; remember the safe draft so onInput can undo it.
             if (!event.cancelable)
                 rejectedNextInput = reason;
             if (event.cancelable)
@@ -738,9 +703,7 @@ function makeSession(candidate) {
         event.stopPropagation();
         if (blurPending && !finished) {
             blurPending = false;
-            // Browsers may dispatch the final insertCompositionText/input after
-            // compositionend. Commit on the next macrotask so those final chars are
-            // part of this one canonical edit.
+            // Browsers may dispatch the final composition input after compositionend; commit on the next macrotask to include it.
             compositionFinalizeHandle = setTimeout(() => {
                 compositionFinalizeHandle = null;
                 if (!finished && !composing)
@@ -753,16 +716,14 @@ function makeSession(candidate) {
             return;
         const selection = doc.getSelection?.();
         if (!selection || selection.rangeCount === 0) {
-            // A panel click can clear the page selection before blur; let blur own
-            // the normal commit path unless the editing host still owns focus.
+            // A panel click can clear the page selection before blur; let blur own the commit path unless the host still owns focus.
             if (doc.activeElement === host)
                 endLifecycle("selection-removed");
             return;
         }
         if (selection && selection.rangeCount > 0 && selectionInsideHost(host))
             return;
-        // A removed selection/host is a lifecycle end, not a text operation. The
-        // original node is restored only while its owning host is still connected.
+        // A removed selection/host is a lifecycle end, not a text operation.
         if (!host.isConnected || !candidate.element.isConnected) {
             endLifecycle(!host.isConnected ? "host-removed" : "selection-removed");
             return;
@@ -778,9 +739,7 @@ function makeSession(candidate) {
         if (!OwnerNode || !(target instanceof OwnerNode))
             return;
         if (host.contains(target)) {
-            // All down/up events must reach the native editing host so caret and
-            // drag-selection behavior remains intact. The click itself is held so
-            // the app cannot activate the surrounding button/link.
+            // Down/up events must reach the host so caret and drag-selection work; the click is held so the app cannot activate the surrounding button/link.
             if (event.type === "mousedown" || event.type === "mouseup"
                 || event.type === "pointerdown" || event.type === "pointerup")
                 return;
@@ -791,9 +750,7 @@ function makeSession(candidate) {
         const inspectorRoot = doc.getElementById("nudge-ui-root");
         if (inspectorRoot && (target === inspectorRoot || inspectorRoot.contains(target)))
             return;
-        // At the document boundary, application actions are suspended for the
-        // duration of the draft. Inspector controls live in the scoped shadow
-        // host above and remain usable.
+        // Outside the inspector root, application actions are suspended for the duration of the draft.
         if (event.type !== "mousedown" && event.type !== "mouseup"
             && event.type !== "pointerdown" && event.type !== "pointerup") {
             event.preventDefault();
@@ -801,9 +758,7 @@ function makeSession(candidate) {
         event.stopPropagation();
     }
     function suppressHostPointer(event) {
-        // Keep the native default (focus transfer, caret placement, and drag
-        // selection) while preventing an application ancestor from observing the
-        // temporary host's pointer sequence.
+        // Keep native defaults; only stop an application ancestor from observing the host's pointer sequence.
         event.stopPropagation();
     }
     function onFrameDisposed() {
@@ -850,9 +805,6 @@ function makeSession(candidate) {
             }
         }
         else if (host.isConnected) {
-            // A reconciliation can move the temporary host before removing the
-            // original root. It no longer has an owned insertion point, so remove
-            // the wrapper rather than leaking an editor into the new tree.
             host.remove();
         }
         finish(reason, "cancelled", discardedDraft, restoreFocus);
@@ -915,17 +867,14 @@ function makeSession(candidate) {
                 endLifecycle("app-reconciled", after);
                 return null;
             }
-            // Always remove the temporary host before appending the canonical
-            // change. The React Adapter must own the permanent preview.
+            // Remove the temporary host before appending the change: the React Adapter must own the permanent preview.
             const restoreFocus = editorOwnsFocus();
             if (!restoreDraft(candidate, host, candidate.before, ownership)) {
                 cancelForReconciliation();
                 return null;
             }
             if (change?.kind === "text-content" && editDecision.scope === "rendered-instance") {
-                // The second text value is alternate evidence for re-entry after a
-                // previous projection. Validation happens after unwrapping because a
-                // mounted draft can make another identical root look unique.
+                // candidate.before is alternate evidence for re-entry; validate after unwrapping, when a mounted draft can make another identical root look unique.
                 const resolved = resolveTextProjectionTarget(doc, change.target, candidate.before);
                 if (resolved.status !== "resolved") {
                     if (!resumeDraft(after))
@@ -1027,8 +976,7 @@ export const inlineTextEditor = {
         return makeSession(candidate);
     },
 };
-/** Re-enter an existing canonical rendered-text projection through its empty
- * inspector affordance. This never guesses a new DOM target or source node. */
+/** Re-enters an existing projection; never guesses a new DOM target or source node. */
 export function beginInlineTextEditFromEmptyProjection(marker) {
     if (!canEditDraft()) {
         return { kind: "rejected", reason: "editing-active", message: "Wait for the iteration to finish saving before editing text." };
@@ -1050,9 +998,7 @@ export function beginInlineTextEditFromEmptyProjection(marker) {
     const candidate = resolveEmptyProjectionCandidate(marker);
     if (isTextEditRejection(candidate))
         return recordTextEditRejection(marker, candidate);
-    // Hide the affordance while its retained empty Text node is wrapped by the
-    // native editor. The marker is restored on cancel and removed by projection
-    // reconciliation on a successful non-empty commit.
+    // Hide the affordance while the editor wraps its empty Text node; cancel restores it, a non-empty commit removes it via reconciliation.
     marker.hidden = true;
     try {
         return makeSession(candidate);

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

@@ -1,9 +1,4 @@
-/**
- * A tiny lifecycle seam keeps canonical-history clearing independent from the
- * editor implementation. The editor registers its active-session disposer;
- * changesLog can then cancel it without importing the editor back through a
- * circular module edge.
- */
+// Keeps canonical-history clearing independent of the editor without importing it back through a circular edge.
 import { clearInlineTextDiagnostics } from "./inlineTextDiagnostics.js";
 let clearHandler = null;
 export function registerInlineTextClearHandler(handler) {

package/dist/inspector/inline-text/textEditChange.d.ts

@@ -1,7 +1,6 @@
 import type { TextBindingCandidate, TextEditBinding } from "../componentSemantics/textBinding.js";
 import type { ChangeRecord } from "../changes/types.js";
-import type { TextProjectionScope, TextProjectionTarget } from "./textChangeBoundary.js";
-/** Binding and scope decisions, independent of native editor lifecycle state. */
+import type { TextProjectionScope, TextProjectionTarget } from "../changes/editModel.js";
 export interface TextEditDecision {
     bindingIndex: number | null;
     scope: TextProjectionScope;