nudge-ui 0.2.4 → 0.2.6

package/dist/inspector/projection/textProjection.js

@@ -1,7 +1,8 @@
-import { getActiveDraftChanges, getDraftChanges } from "../changes/draftChanges.js";
+import { boundRuntimeEvidence, normalizeRuntimeTag, runtimeDomPath } from "../runtime/staticHtmlRuntimeIdentity.js";
+import { getActiveDraftChanges, getDraftChanges } from "../drafts/store.js";
 import { sourceSiteSelector } from "../selection/sourceSite.js";
 import { isNudgeUiDev } from "../runtime/devFlag.js";
-import { isTextContentChangeValue, isTextProjectionTargetValue, } from "../inline-text/textChangeBoundary.js";
+import { isTextContentChangeValue, isTextProjectionTargetValue, } from "../changes/editModel.js";
 import { isInteractionStylesInstalled } from "../overlay/interactionStyles.js";
 /** Strict JSON boundary guard for a text projection target. */
 export const isTextProjectionTarget = isTextProjectionTargetValue;
@@ -15,7 +16,6 @@ function hasOnlyKeys(value, allowed) {
 export const TEXT_PROJECTION_ATTR = "data-projection-text";
 /** Inspector-owned hit target for a projected text node whose value is empty. */
 export const EMPTY_TEXT_PROJECTION_ATTR = "data-empty-text";
-/** Inspector-owned exact-node evidence paired with EMPTY_TEXT_PROJECTION_ATTR. */
 export const EMPTY_TEXT_PROJECTION_PATH_ATTR = "data-empty-text-path";
 const UNSAFE_TEXT_TAGS = new Set(["SCRIPT", "STYLE", "TEXTAREA", "OPTION"]);
 const UNSAFE_MIXED_DESCENDANT_TAGS = new Set([
@@ -49,19 +49,14 @@ function isEmptyTextAffordance(node) {
 function hasInlineTextEditor(element) {
     return element.querySelector('[data-inline-editor="true"]') !== null;
 }
-/**
- * What the application last rendered into each projected Text node. A source
- * update can render the projected value itself, so restoring `before` would
- * overwrite real application output that the framework will not repaint.
- */
+/** A restore must not overwrite real application output that the framework will not repaint. */
 let applicationText = new WeakMap();
 function isInlineEditorNode(node) {
     return node.nodeType === 1 && (node.matches('[data-inline-editor="true"]')
         || hasInlineTextEditor(node));
 }
 function recordApplicationWrites(records) {
-    // The inline editor swaps its wrapper back for the original node, writing
-    // the draft, in one task. That write belongs to the editor.
+    // The inline editor writes the draft while swapping its wrapper back in the same task; that write belongs to the editor.
     if (records.some((record) => record.type === "childList"
         && [...record.addedNodes, ...record.removedNodes].some(isInlineEditorNode)))
         return;
@@ -166,8 +161,7 @@ function nodeAtPath(root, path) {
     }
     return current;
 }
-/** 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 function resolveTextProjectionTextNode(element, target, expectedText = target.beforeText) {
     if (target.textNodePath) {
         const atPath = nodeAtPath(element, target.textNodePath);
@@ -190,28 +184,27 @@ export function resolveTextProjectionTextNode(element, target, expectedText = ta
     }
     return matches.length === 1 ? matches[0] : null;
 }
-function hasSafeMixedDescendants(element) {
-    // <br> only controls line layout. The projection targets one exact text
-    // node, so keeping the break while changing that node is safe; formatting
-    // descendants below still reject a flattening text projection.
+export function isUnsafeTextHost(element) {
+    return UNSAFE_TEXT_TAGS.has(element.tagName);
+}
+export function isInApplicationEditingHost(element) {
+    const editingHost = element.closest("[contenteditable]");
+    return Boolean(editingHost
+        && editingHost.getAttribute("data-inline-editor") !== "true"
+        && editingHost.getAttribute("contenteditable") !== "false");
+}
+export function hasSafeMixedDescendants(element) {
+    // <br> only controls line layout, so it stays allowed; the projection targets one exact text node.
     for (const descendant of Array.from(element.querySelectorAll("*"))) {
         if (UNSAFE_MIXED_DESCENDANT_TAGS.has(descendant.tagName))
             return false;
-        const editingHost = descendant.closest("[contenteditable]");
-        if (editingHost
-            && editingHost.getAttribute("data-inline-editor") !== "true"
-            && editingHost.getAttribute("contenteditable") !== "false")
+        if (isInApplicationEditingHost(descendant))
             return false;
     }
     return true;
 }
 function textHostIsSafe(element, allowEmpty = false, target) {
-    if (UNSAFE_TEXT_TAGS.has(element.tagName))
-        return false;
-    const editingHost = element.closest("[contenteditable]");
-    if (editingHost
-        && editingHost.getAttribute("data-inline-editor") !== "true"
-        && editingHost.getAttribute("contenteditable") !== "false")
+    if (isUnsafeTextHost(element) || isInApplicationEditingHost(element))
         return false;
     if (allowEmpty && element.childNodes.length === 0)
         return true;
@@ -223,9 +216,7 @@ function textHostIsSafe(element, allowEmpty = false, target) {
             && (allowEmpty || textNode.nodeValue?.length)
             && hasSafeMixedDescendants(element));
     }
-    // An empty-text affordance is inspector-owned and deliberately sits beside
-    // the retained empty Text node. Ignore it when proving that a direct leaf
-    // remains safe; otherwise the affordance would invalidate its own target.
+    // Ignore inspector-owned affordances here; otherwise the affordance would invalidate its own target.
     const applicationChildren = Array.from(element.children)
         .filter((child) => !isEmptyTextAffordance(child)
         && child.getAttribute("data-inline-editor") !== "true");
@@ -235,17 +226,10 @@ function textHostIsSafe(element, allowEmpty = false, target) {
     if (textNodes.length === 1) {
         return allowEmpty || Boolean(textNodes[0]?.nodeValue?.length);
     }
-    // The temporary inline editor wraps the retained direct Text node. Treat
-    // that inspector-owned wrapper as transparent while validating the
-    // canonical projection; otherwise its insertion would self-report as an
-    // application reconciliation and remove the re-entry slot mid-session.
+    // The inline editor's wrapper is inspector-owned; treating it as an application child would drop the re-entry slot.
     const editingHosts = Array.from(element.children)
         .filter((child) => child.getAttribute("data-inline-editor") === "true");
-    // The browser may split/replace the retained empty Text node while the
-    // native editor receives its first input. The wrapper is still inspector
-    // owned; its plain-text input guards are responsible for rejecting rich or
-    // paragraph edits, so validation must not cancel the session on that
-    // transient child shape.
+    // The browser may split the empty Text node on first input; that transient shape must not cancel the session.
     return editingHosts.length === 1;
 }
 function sourceCandidates(doc, sourceSite) {
@@ -269,7 +253,6 @@ function evidenceMatches(element, target, expectedText) {
                 && target.textNodePath === undefined
                 && (element.textContent ?? "") === ""));
 }
-/** Capture stable source/evidence identity without retaining a DOM reference. */
 export function captureTextProjectionTarget(element, beforeText = element.textContent ?? "", selectedTextNode) {
     if (!element.isConnected)
         return null;
@@ -295,14 +278,13 @@ export function captureTextProjectionTarget(element, beforeText = element.textCo
         props: element.getAttribute("data-cprops"),
         ariaLabel: element.getAttribute("aria-label"),
         beforeText,
+        tagName: normalizeRuntimeTag(element.tagName),
+        elementId: boundRuntimeEvidence(element.id || null),
+        domPath: runtimeDomPath(element),
         ...pathTarget,
     };
 }
-/**
- * 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 function resolveTextProjectionTarget(doc, target, afterText) {
     const candidates = sourceCandidates(doc, target.sourceSite);
     const evidence = candidates.filter((element) => evidenceMatches(element, target, target.beforeText)
@@ -347,9 +329,7 @@ function emptyTextAffordanceFor(doc, state, change, element) {
         return null;
     const parentElement = parent;
     const path = markerKey(change.target);
-    // During re-entry the temporary editor wraps the empty Text node. The
-    // existing slot remains beside that wrapper; search the whole projected
-    // root before creating another slot inside the editing host.
+    // Search the whole root before creating another slot; during re-entry the editor wrapper sits between the slot and the Text node.
     const existing = Array.from(element.querySelectorAll(`[${EMPTY_TEXT_PROJECTION_ATTR}]`))
         .find((child) => child.getAttribute(EMPTY_TEXT_PROJECTION_ATTR) === change.id
         && child.getAttribute(EMPTY_TEXT_PROJECTION_PATH_ATTR) === path);
@@ -365,18 +345,13 @@ function emptyTextAffordanceFor(doc, state, change, element) {
     affordance.setAttribute("role", "presentation");
     affordance.setAttribute("contenteditable", "false");
     affordance.tabIndex = -1;
-    // It has no application text and is never a source identity. The
-    // interaction stylesheet supplies its visible, borderless hit geometry.
+    // Never a source identity; the interaction stylesheet supplies its hit geometry.
     affordance.hidden = !isInteractionStylesInstalled(doc);
     parentElement.insertBefore(affordance, textNode.nextSibling);
     state.emptyAffordances.set(change.id, affordance);
     return affordance;
 }
-/**
- * Keep inspector-owned empty-text hit slots aligned with the canonical text
- * projection. Slots are colocated with the exact retained Text node, so they
- * do not replace application structure or alter the durable text path.
- */
+/** Slots are colocated with the retained Text node so they never alter the durable text path. */
 function syncEmptyTextAffordances(doc, state, changes) {
     const emptyChanges = new Map(changes.filter((change) => change.after.length === 0).map((change) => [change.id, change]));
     const seen = new Set();
@@ -414,7 +389,6 @@ function syncEmptyTextAffordances(doc, state, changes) {
         emptyTextAffordanceFor(doc, state, change, applied.element);
     }
 }
-/** Returns the canonical record represented by an inspector empty-text slot. */
 export function getTextContentChangeById(changeId) {
     return canonicalChanges.get(changeId) ?? null;
 }
@@ -450,9 +424,7 @@ function restoreAppliedProjection(state, applied) {
         return;
     if (!hasProjectionMarker(element, applied.change.target, applied.change.id))
         return;
-    // Never overwrite a newer application/reconciliation state during undo or
-    // clear. The marker, identity evidence, and projected value must all still
-    // belong to us; text alone is not proof after a source-site identity change.
+    // Only restore when the marker and identity evidence still match; text alone is not proof.
     if (!textProjectionIdentityMatches(element, applied.change))
         return;
     const textNode = resolveTextProjectionTextNode(element, applied.change.target, applied.change.after);
@@ -483,11 +455,7 @@ function validationStatus(applied) {
     const directEmpty = applied.change.target.textNodePath === undefined
         && applied.change.after.length === 0
         && (element.textContent ?? "") === "";
-    // While an empty projection is being reopened, the native editor owns a
-    // draft value that intentionally differs from the canonical empty value.
-    // Keep the projection applied until the editor restores its Text node and
-    // appends the next canonical snapshot; otherwise removing the slot changes
-    // the wrapper's ownership and cancels the draft mid-keystroke.
+    // While an empty projection is reopened the editor's draft intentionally differs; dropping it mid-keystroke would cancel the draft.
     const inlineDraft = hasInlineTextEditor(element);
     const identityValid = textProjectionIdentityMatches(element, applied.change);
     const safe = textHostIsSafe(element, applied.change.after.length === 0, applied.change.target);
@@ -496,12 +464,7 @@ function validationStatus(applied) {
     }
     return "applied";
 }
-/**
- * A controller can hydrate before a lazy route has mounted its tracked roots.
- * Keep a missing/ambiguous record pending and retry only when the document
- * mutates; an overridden projection remains authoritative and is never
- * re-applied.
- */
+/** Missing/ambiguous records stay pending until the document mutates; an overridden projection is never re-applied. */
 function resolvePendingProjection(doc, state, applied) {
     if (applied.status !== "missing" && applied.status !== "ambiguous") {
         return validationStatus(applied);
@@ -585,7 +548,6 @@ function getDocumentState(doc) {
     documentStates.set(doc, state);
     return state;
 }
-/** Apply one controller-owned text snapshot to a document adapter. */
 export function applyTextContentProjection(doc, changes) {
     if (!isNudgeUiDev())
         return [];
@@ -593,9 +555,7 @@ export function applyTextContentProjection(doc, changes) {
     setCanonicalTextContentChanges(changes);
     const key = JSON.stringify(changes);
     if (state.snapshotKey === key) {
-        // Reconciliation can happen between controller snapshots. Validate before
-        // reporting so a pending MutationObserver callback cannot leave a stale
-        // "applied" result visible to the Changes Log.
+        // Validate before reporting so a pending observer callback cannot leave a stale result in the Changes Log.
         validateAppliedProjection(doc, state);
         const reports = reportsForSnapshot(state, changes);
         storeReports(doc, reports);
@@ -604,10 +564,7 @@ export function applyTextContentProjection(doc, changes) {
     const previous = state.applied;
     const next = new Map();
     const incomingIds = new Set(changes.map((change) => change.id));
-    // Removing a canonical record is an explicit revert/clear. Restore only a
-    // marker/value still owned by that record; every surviving record keeps its
-    // current application status and must not be replayed merely because an
-    // unrelated change altered the shared snapshot.
+    // Removed records are an explicit revert; surviving records keep their status and must not be replayed because an unrelated change altered the snapshot.
     for (const [id, applied] of previous) {
         if (incomingIds.has(id))
             continue;
@@ -655,9 +612,7 @@ export function applyTextContentProjection(doc, changes) {
     }
     state.applied = next;
     syncEmptyTextAffordances(doc, state, changes);
-    // Drop markers that do not belong to the current controller snapshot. This
-    // also cleans a marker left by a previous runtime instance without touching
-    // a surviving overridden projection in `next`.
+    // Also cleans markers left by a previous runtime instance without touching a surviving overridden projection.
     for (const marker of Array.from(doc.querySelectorAll(`[${TEXT_PROJECTION_ATTR}]`))) {
         const markers = readProjectionMarkers(marker);
         for (const [key, id] of markers) {

package/dist/inspector/prompt/PromptSettingsDialog.d.ts

@@ -10,6 +10,5 @@ export interface PromptSettingsFieldsProps {
     onChange: (value: string) => void;
     instructionsRef?: RefObject<HTMLTextAreaElement | null>;
 }
-/** Edits the instructions appended to every generated prompt. */
 export declare function PromptSettingsFields({ value, onChange, instructionsRef, }: PromptSettingsFieldsProps): ReactElement;
 export declare function PromptSettingsDialog({ open, value, onChange, onOpenChange, }: PromptSettingsDialogProps): ReactElement;

package/dist/inspector/prompt/PromptSettingsDialog.js

@@ -3,7 +3,6 @@ import { useRef } from "react";
 import { Dialog } from "@base-ui/react/dialog";
 import { IconX } from "@tabler/icons-react";
 import { portalContainer } from "../ui/portalContainer.js";
-/** Edits the instructions appended to every generated prompt. */
 export function PromptSettingsFields({ value, onChange, instructionsRef, }) {
     return (_jsxs(_Fragment, { children: [_jsx("div", { className: "prompt-settings__field", children: _jsx("textarea", { ref: instructionsRef, id: "nudge-ui-custom-instructions", className: "prompt-settings__textarea", "data-test": "prompt-custom-instructions", "aria-label": "Custom instructions", rows: 6, value: value, onChange: (event) => onChange(event.currentTarget.value) }) }), _jsx("div", { className: "prompt-settings__actions", children: _jsx(Dialog.Close, { className: "button button--primary", "data-test": "prompt-settings-done", type: "button", children: "Done" }) })] }));
 }

package/dist/inspector/prompt/clipboardHandoff.d.ts

@@ -27,5 +27,6 @@ export declare function getClipboardHandoffRecords(draftId: string): {
     structuralChanges: StructuralChange[];
 };
 export declare function reconcileClipboardHandoff(doc?: Document): Promise<number>;
+/** A check briefly removes the copied preview, so reconciling nothing doubles the interval to avoid flashing on continuously mutating pages. */
 export declare function startClipboardHandoffController(doc?: Document): () => void;
 export {};

package/dist/inspector/prompt/clipboardHandoff.js

@@ -1,5 +1,5 @@
 import { changeKey } from "../changes/model.js";
-import { getDraftChanges, getActiveDraftChanges, subscribeActiveDraftChanges } from "../changes/draftChanges.js";
+import { getDraftChanges, getActiveDraftChanges, subscribeActiveDraftChanges } from "../drafts/store.js";
 import { documentRevisions, subscribeDocumentRevision } from "../tokens/resolution/cssomCollector.js";
 import { captureHandoffOwner, handoffChangeFingerprint, handoffStructuralFingerprint, verifyAndReconcileHandoff, } from "../agent/verification.js";
 import { isDraftTarget } from "../drafts/model.js";
@@ -124,33 +124,50 @@ export async function reconcileClipboardHandoff(doc = document) {
     }
     return removed;
 }
+const CHECK_DELAY_MS = 450;
+const MAX_CHECK_DELAY_MS = 8_000;
+/** A check briefly removes the copied preview, so reconciling nothing doubles the interval to avoid flashing on continuously mutating pages. */
 export function startClipboardHandoffController(doc = document) {
     const view = doc.defaultView;
     let timer = null;
     let checking = false;
     let stopped = false;
-    const schedule = () => {
+    let interval = CHECK_DELAY_MS;
+    let lastCheckEndedAt = -Infinity;
+    const run = () => {
+        timer = null;
         if (stopped || checking || !checkpoints.size)
             return;
+        checking = true;
+        void reconcileClipboardHandoff(doc).then((removed) => {
+            interval = removed > 0 ? CHECK_DELAY_MS : Math.min(interval * 2, MAX_CHECK_DELAY_MS);
+        }, () => undefined).finally(() => {
+            lastCheckEndedAt = Date.now();
+            setTimeout(() => { checking = false; }, 0);
+        });
+    };
+    const schedule = () => {
+        if (stopped || checking || !checkpoints.size || timer !== null)
+            return;
+        // Let the change that triggered this settle, and keep the backoff interval.
+        timer = setTimeout(run, Math.max(CHECK_DELAY_MS, lastCheckEndedAt + interval - Date.now()));
+    };
+    const returned = () => {
+        interval = CHECK_DELAY_MS;
+        lastCheckEndedAt = -Infinity;
         if (timer !== null)
             clearTimeout(timer);
-        timer = setTimeout(() => {
-            timer = null;
-            if (stopped || checking || !checkpoints.size)
-                return;
-            checking = true;
-            void reconcileClipboardHandoff(doc).catch(() => undefined).finally(() => {
-                setTimeout(() => { checking = false; }, 0);
-            });
-        }, 450);
+        timer = null;
+        schedule();
     };
     const visible = () => { if (doc.visibilityState === "visible")
-        schedule(); };
+        returned(); };
     documentRevisions(doc);
     const stopRevision = subscribeDocumentRevision(doc, schedule);
     const stopChanges = subscribeActiveDraftChanges(pruneCheckpoints);
-    view?.addEventListener("focus", schedule);
-    view?.addEventListener("pageshow", schedule);
+    const stopHandoff = subscribeClipboardHandoff(() => { interval = CHECK_DELAY_MS; });
+    view?.addEventListener("focus", returned);
+    view?.addEventListener("pageshow", returned);
     doc.addEventListener("visibilitychange", visible);
     schedule();
     return () => {
@@ -159,8 +176,9 @@ export function startClipboardHandoffController(doc = document) {
             clearTimeout(timer);
         stopRevision();
         stopChanges();
-        view?.removeEventListener("focus", schedule);
-        view?.removeEventListener("pageshow", schedule);
+        stopHandoff();
+        view?.removeEventListener("focus", returned);
+        view?.removeEventListener("pageshow", returned);
         doc.removeEventListener("visibilitychange", visible);
     };
 }

package/dist/inspector/prompt/generatePrompt.d.ts

@@ -1,4 +1,4 @@
-import type { ChangeRecord } from "../changes/changesLog.js";
+import type { ChangeRecord } from "../changes/types.js";
 import type { StructuralChange } from "../projection/structuralProjection.js";
 import type { AgentSketchMetadata } from "../agent/protocol.js";
 import { type ElementComment } from "../comments/store.js";
@@ -6,6 +6,6 @@ export interface FrameworkHints {
     framework?: string;
     stylingSystem?: string;
 }
-/** Counts the final edit intents exported by the prompt, preserving gesture history for undo. */
+/** Counts the exported intents, not the raw gesture history. */
 export declare function countPromptChanges(changes: readonly ChangeRecord[], structuralChanges?: readonly StructuralChange[], sketchCount?: number): number;
 export declare function generatePrompt(changes: ChangeRecord[], frameworkHints?: FrameworkHints, structuralChanges?: readonly StructuralChange[], customInstructions?: string, sketches?: readonly AgentSketchMetadata[], comments?: readonly ElementComment[]): string;