@agent-native/core 0.90.5 → 0.90.8

package/corpus/templates/design/shared/board-file.ts

@@ -612,6 +612,365 @@ function _inferSvgPrimitiveKind(inner: string): string | null {
   return null;
 }
 
+// ---------------------------------------------------------------------------
+// Poisoned nested-coordinate normalization
+// ---------------------------------------------------------------------------
+
+/**
+ * Half-size of the board's oversized iframe surface (131072 / 2). The board
+ * renderer shifts top-level board elements by this amount via a
+ * `body > [data-agent-native-node-id]{translate:65536px 65536px}` rule
+ * (DesignCanvas.tsx embeddedContentOffsetStyle) so board coordinate (0,0)
+ * lands at the center of the surface.
+ *
+ * Historic bugs wrote NESTED board children's left/top in board-IFRAME
+ * viewport coordinates (board coordinate + 65536) instead of parent-relative
+ * coordinates — and, before the offset rule was scoped to top-level children,
+ * the compounding translate could stack the offset more than once. The
+ * helpers below detect and repair those persisted values.
+ */
+export const BOARD_SURFACE_CONTENT_OFFSET_PX = 65_536;
+
+/**
+ * How far from an exact 65536-multiple a coordinate may sit and still be
+ * classified as "poisoned by the surface offset". Real poisoned values look
+ * like `k * 65536 + boardCoordinate` where the board coordinate of actual
+ * content is at most a few thousand px from origin; real parent-relative
+ * coordinates of nested children are bounded by their parent's size (far
+ * below this). A quarter of the offset is a comfortable margin on both sides.
+ */
+const BOARD_COORD_POISON_REMAINDER_MAX_PX = 16_384;
+
+/**
+ * Largest magnitude a rebased nested coordinate may have (when the parent's
+ * size is unknown) before it is considered garbage and clamped back into the
+ * parent's box. No sane nested child sits 16k px from its parent's origin.
+ */
+const BOARD_NESTED_COORD_SANE_MAX_PX = 16_384;
+
+/**
+ * Returns true when a persisted left/top value carries the board-surface
+ * offset fingerprint: within BOARD_COORD_POISON_REMAINDER_MAX_PX of a
+ * non-zero multiple of 65536.
+ */
+export function isBoardSurfacePoisonedCoord(value: number): boolean {
+  if (!Number.isFinite(value)) return false;
+  const k = Math.round(value / BOARD_SURFACE_CONTENT_OFFSET_PX);
+  if (k === 0) return false;
+  return (
+    Math.abs(value - k * BOARD_SURFACE_CONTENT_OFFSET_PX) <=
+    BOARD_COORD_POISON_REMAINDER_MAX_PX
+  );
+}
+
+/**
+ * Strips the board-surface offset from a coordinate when (and only when) it
+ * carries the poison fingerprint; all other values pass through untouched.
+ * `66904 → 1368`, `-65420 → 116`, `131172 → 100`, `250 → 250`.
+ */
+export function stripBoardSurfaceOffsetFromCoord(value: number): number {
+  if (!isBoardSurfacePoisonedCoord(value)) return value;
+  const k = Math.round(value / BOARD_SURFACE_CONTENT_OFFSET_PX);
+  return value - k * BOARD_SURFACE_CONTENT_OFFSET_PX;
+}
+
+/**
+ * Parent-relative position for a node being reparented INTO a target
+ * container, from the two elements' persisted absolute positions in the same
+ * coordinate space. This is the pure seam used by
+ * `handleOverviewPrimitiveReparent` (DesignEditor.tsx).
+ *
+ * Both inputs are normalized with `stripBoardSurfaceOffsetFromCoord` first:
+ * a source that was persisted in board-iframe viewport coordinates
+ * (boardCoord + 65536 — see BOARD_SURFACE_CONTENT_OFFSET_PX) is rebased to
+ * board space before subtracting the target's origin, so the child's new
+ * left/top always comes out parent-relative regardless of which upstream
+ * path produced the source position. For in-screen reparenting (small
+ * screen-root coordinates on both sides) the strip is a no-op and this is a
+ * plain subtraction.
+ */
+export function computeReparentedChildPosition(
+  source: { x: number; y: number },
+  target: { x: number; y: number },
+): { x: number; y: number } {
+  return {
+    x:
+      stripBoardSurfaceOffsetFromCoord(source.x) -
+      stripBoardSurfaceOffsetFromCoord(target.x),
+    y:
+      stripBoardSurfaceOffsetFromCoord(source.y) -
+      stripBoardSurfaceOffsetFromCoord(target.y),
+  };
+}
+
+interface BoardWalkFrame {
+  tagName: string;
+  isNodeIdElement: boolean;
+  left: number | null;
+  top: number | null;
+  width: number | null;
+  height: number | null;
+}
+
+const BOARD_HTML_TAG_RE =
+  /<!--[\s\S]*?-->|<\/?([a-zA-Z][\w:-]*)((?:"[^"]*"|'[^']*'|[^"'<>])*)\/?>/g;
+
+/** Tags whose raw text content must not be tag-walked. */
+const BOARD_RAW_TEXT_TAGS = new Set(["script", "style", "textarea"]);
+
+function parseInlineStylePx(
+  style: string,
+  prop: "left" | "top" | "width" | "height",
+): number | null {
+  const match = style.match(
+    new RegExp(
+      `(?:^|;)\\s*${prop}\\s*:\\s*(-?\\d+(?:\\.\\d+)?)px\\s*(?=;|$)`,
+      "i",
+    ),
+  );
+  if (!match?.[1]) return null;
+  const parsed = Number(match[1]);
+  return Number.isFinite(parsed) ? parsed : null;
+}
+
+function replaceInlineStylePx(
+  style: string,
+  prop: "left" | "top",
+  next: number,
+): string {
+  return style.replace(
+    new RegExp(`((?:^|;)\\s*${prop}\\s*:\\s*)(-?\\d+(?:\\.\\d+)?)px`, "i"),
+    `$1${next}px`,
+  );
+}
+
+function rebaseNestedBoardCoord(args: {
+  value: number;
+  ancestorOrigin: number;
+  parentSize: number | null;
+  childSize: number | null;
+}): number {
+  const { value, ancestorOrigin, parentSize, childSize } = args;
+  if (!isBoardSurfacePoisonedCoord(value)) return value;
+  // Two distinct historic poison shapes, distinguishable by the sign of the
+  // offset multiple:
+  // - k >= 1 (positive): value = k*65536 + boardCoordinate — the child's
+  //   board/viewport-space position was written verbatim (container-drop
+  //   persist path). Parent-relative = board coordinate minus the parent's
+  //   accumulated board-space origin.
+  // - k <= -1 (negative): value = parentRelative - 65536 — the bridge's
+  //   rect-space nest rebase pre-compensated the (old, blanket) content
+  //   translate. The stripped remainder already IS parent-relative; no
+  //   ancestor subtraction. (A genuine board coordinate can never reach
+  //   k <= -1 here: that would put content beyond the surface edge.)
+  const k = Math.round(value / BOARD_SURFACE_CONTENT_OFFSET_PX);
+  let rebased =
+    stripBoardSurfaceOffsetFromCoord(value) - (k > 0 ? ancestorOrigin : 0);
+  // Sanity clamp: exact recovery is possible for the common single-poison
+  // case, but compounded corruption (the parent moved after the child's
+  // position was written, multiple stacked offsets, user "fixes" made while
+  // the content rendered off-world) can leave a rebased value that is still
+  // far outside the parent. Pull those back into the parent's box so the
+  // child is at least visible and re-editable — the alternative is an
+  // element parked tens of thousands of px off-world.
+  const sane =
+    parentSize !== null
+      ? rebased >= -parentSize && rebased <= 2 * parentSize
+      : Math.abs(rebased) <= BOARD_NESTED_COORD_SANE_MAX_PX;
+  if (!sane) {
+    const max =
+      parentSize !== null ? Math.max(0, parentSize - (childSize ?? 0)) : 0;
+    rebased = Math.min(Math.max(0, rebased), max);
+  }
+  return Math.round(rebased);
+}
+
+/**
+ * Repairs already-persisted board content whose NESTED children carry
+ * left/top values poisoned by the board-surface offset (near-65536-multiple
+ * values — see BOARD_SURFACE_CONTENT_OFFSET_PX).
+ *
+ * For each element that (a) carries `data-agent-native-node-id`, (b) has at
+ * least one node-id-bearing ancestor inside `<body>` (i.e. is a nested board
+ * child, never a top-level one — top-level children legitimately use raw
+ * board coordinates), and (c) has a poisoned inline left and/or top:
+ *
+ * 1. the nearest 65536-multiple is stripped (recovering the board-space
+ *    coordinate the value was written from),
+ * 2. the accumulated origin of its node-id ancestor chain (using
+ *    already-normalized ancestor values, walking outer→inner) is subtracted
+ *    to produce a parent-relative coordinate, and
+ * 3. values that are still implausible after rebasing are clamped into the
+ *    parent's box.
+ *
+ * Everything else — non-poisoned coordinates, top-level children, elements
+ * without node ids, all other markup — passes through byte-identical. The
+ * function is pure, string-level (no DOM), and idempotent: normalized output
+ * contains no poisoned values, so a second pass returns `changed: false`.
+ *
+ * Applied on board-content load/adopt (DesignEditor) so designs corrupted by
+ * the historic nest-on-drop bugs self-heal the next time an editor opens
+ * them, and as a post-reparent safety net.
+ *
+ * Detectability (finding 4): this repair is a heuristic rewrite of
+ * already-persisted content with no built-in trace — a bad heuristic could
+ * silently mis-rebase real content and nobody would know. The return value
+ * includes `fixedNodeCount` and a small `samples` list (each node's original
+ * vs. rebased left/top) so callers can log what actually happened; this
+ * function itself stays side-effect-free (no console usage) so it remains
+ * safely callable from any context (including the post-reparent safety-net
+ * call sites, not just the load effect) — logging is the caller's job.
+ */
+const NORMALIZE_POISONED_COORDS_SAMPLE_LIMIT = 5;
+
+export function normalizePoisonedBoardNestedCoords(html: string): {
+  html: string;
+  changed: boolean;
+  fixedNodeCount: number;
+  samples: Array<{
+    nodeId: string | null;
+    before: { left: number | null; top: number | null };
+    after: { left: number | null; top: number | null };
+  }>;
+} {
+  if (!html || !html.includes("data-agent-native-node-id")) {
+    return { html, changed: false, fixedNodeCount: 0, samples: [] };
+  }
+  // Cheap pre-scan: a poisoned coordinate needs at least 5 digits
+  // (|value| >= 65536 - 16384 = 49152).
+  if (!/(?:left|top)\s*:\s*-?\d{5,}/i.test(html)) {
+    return { html, changed: false, fixedNodeCount: 0, samples: [] };
+  }
+
+  const bodyStart = html.indexOf("<body");
+  const bodyTagEnd = bodyStart === -1 ? -1 : html.indexOf(">", bodyStart);
+  const walkStart = bodyTagEnd === -1 ? 0 : bodyTagEnd + 1;
+  const bodyClose = html.lastIndexOf("</body>");
+  const walkEnd = bodyClose === -1 ? html.length : bodyClose;
+
+  const stack: BoardWalkFrame[] = [];
+  let out = "";
+  let cursor = 0;
+  let changed = false;
+  let fixedNodeCount = 0;
+  const samples: Array<{
+    nodeId: string | null;
+    before: { left: number | null; top: number | null };
+    after: { left: number | null; top: number | null };
+  }> = [];
+
+  BOARD_HTML_TAG_RE.lastIndex = walkStart;
+  let match: RegExpExecArray | null;
+  while ((match = BOARD_HTML_TAG_RE.exec(html)) !== null) {
+    if (match.index >= walkEnd) break;
+    const token = match[0];
+    const tagName = match[1]?.toLowerCase();
+    if (!tagName) continue; // comment
+
+    if (token.startsWith("</")) {
+      const index = stack.map((frame) => frame.tagName).lastIndexOf(tagName);
+      if (index >= 0) stack.splice(index);
+      continue;
+    }
+
+    // Raw-text elements: skip their content wholesale so stray "<" inside
+    // scripts/styles can't desync the walk.
+    if (BOARD_RAW_TEXT_TAGS.has(tagName) && !token.endsWith("/>")) {
+      const close = html.indexOf(`</${tagName}`, BOARD_HTML_TAG_RE.lastIndex);
+      if (close === -1) break;
+      BOARD_HTML_TAG_RE.lastIndex = close;
+      continue;
+    }
+
+    const attrs = match[2] ?? "";
+    const isNodeIdElement = /\bdata-agent-native-node-id\s*=/.test(attrs);
+    const styleMatch = token.match(/(\bstyle\s*=\s*)("([^"]*)"|'([^']*)')/i);
+    const style = styleMatch?.[3] ?? styleMatch?.[4] ?? "";
+    let left = parseInlineStylePx(style, "left");
+    let top = parseInlineStylePx(style, "top");
+    const width = parseInlineStylePx(style, "width");
+    const height = parseInlineStylePx(style, "height");
+
+    const nodeIdAncestors = stack.filter((frame) => frame.isNodeIdElement);
+    const isNestedBoardChild = isNodeIdElement && nodeIdAncestors.length > 0;
+    const leftPoisoned =
+      isNestedBoardChild && left !== null && isBoardSurfacePoisonedCoord(left);
+    const topPoisoned =
+      isNestedBoardChild && top !== null && isBoardSurfacePoisonedCoord(top);
+
+    if ((leftPoisoned || topPoisoned) && styleMatch) {
+      const parent = nodeIdAncestors[nodeIdAncestors.length - 1];
+      const originX = nodeIdAncestors.reduce(
+        (sum, frame) => sum + (frame.left ?? 0),
+        0,
+      );
+      const originY = nodeIdAncestors.reduce(
+        (sum, frame) => sum + (frame.top ?? 0),
+        0,
+      );
+      const beforeLeft = left;
+      const beforeTop = top;
+      let nextStyle = style;
+      if (leftPoisoned && left !== null) {
+        left = rebaseNestedBoardCoord({
+          value: left,
+          ancestorOrigin: originX,
+          parentSize: parent?.width ?? null,
+          childSize: width,
+        });
+        nextStyle = replaceInlineStylePx(nextStyle, "left", left);
+      }
+      if (topPoisoned && top !== null) {
+        top = rebaseNestedBoardCoord({
+          value: top,
+          ancestorOrigin: originY,
+          parentSize: parent?.height ?? null,
+          childSize: height,
+        });
+        nextStyle = replaceInlineStylePx(nextStyle, "top", top);
+      }
+      if (nextStyle !== style) {
+        fixedNodeCount += 1;
+        if (samples.length < NORMALIZE_POISONED_COORDS_SAMPLE_LIMIT) {
+          const nodeIdMatch =
+            /\bdata-agent-native-node-id\s*=\s*("([^"]*)"|'([^']*)')/.exec(
+              attrs,
+            );
+          samples.push({
+            nodeId: nodeIdMatch?.[2] ?? nodeIdMatch?.[3] ?? null,
+            before: { left: beforeLeft, top: beforeTop },
+            after: { left, top },
+          });
+        }
+        const quote = styleMatch[2]?.startsWith("'") ? "'" : '"';
+        const rewrittenToken =
+          token.slice(0, styleMatch.index ?? 0) +
+          styleMatch[1] +
+          quote +
+          nextStyle +
+          quote +
+          token.slice((styleMatch.index ?? 0) + styleMatch[0].length);
+        out += html.slice(cursor, match.index) + rewrittenToken;
+        cursor = match.index + token.length;
+        changed = true;
+      }
+    }
+
+    const selfClosing = token.endsWith("/>") || VOID_ELEMENTS.has(tagName);
+    if (!selfClosing) {
+      stack.push({ tagName, isNodeIdElement, left, top, width, height });
+    }
+  }
+
+  if (!changed) return { html, changed: false, fixedNodeCount: 0, samples: [] };
+  return {
+    html: out + html.slice(cursor),
+    changed: true,
+    fixedNodeCount,
+    samples,
+  };
+}
+
 // ---------------------------------------------------------------------------
 // Private helpers
 // ---------------------------------------------------------------------------

package/corpus/templates/design/shared/breakpoint-media.ts

@@ -254,6 +254,12 @@ export function parseBreakpointMediaCss(css: string): BreakpointMediaModel {
     if (body === null) continue;
     mediaRe.lastIndex = bodyStart + body.length + 1;
 
+    // Matches the LAST [data-agent-native-node-id="…"] attribute directly
+    // before the `{`, so it accepts BOTH the legacy single-attribute selector
+    // and the current doubled-attribute selector (see
+    // serializeBreakpointMediaModel below) without double-counting: on a
+    // doubled selector the scan skips the first attribute occurrence (no `{`
+    // after it) and captures the nodeId exactly once from the second.
     const ruleRe =
       /\[data-agent-native-node-id="((?:\\.|[^"\\])*)"\]\s*\{([^}]*)\}/g;
     let ruleMatch: RegExpExecArray | null;
@@ -310,10 +316,22 @@ export function serializeBreakpointMediaModel(
       const lines = properties.map(
         (property) => `    ${property}: ${declarations[property]};`,
       );
+      // Doubled attribute selector → specificity (0,2,0), beating any single
+      // Tailwind utility class (0,1,0) REGARDLESS of stylesheet order. This
+      // matters because designs load Tailwind via the Play CDN script, which
+      // injects its generated utility sheet at RUNTIME — always after this
+      // static managed block — so an equal-specificity (0,1,0) single
+      // attribute selector always lost by source order and the breakpoint
+      // override silently never rendered (verified on real designs: the
+      // @media rule was live and matching, but .px-5 won). Doubling the
+      // attribute survives DOM reorder, Tailwind re-injection, and any
+      // future stylesheet ordering change; parseBreakpointMediaCss above
+      // accepts both formats, and because every write re-serializes the
+      // whole block, legacy single-attribute rules are upgraded to this
+      // format on the next edit automatically.
+      const attrSelector = `[data-agent-native-node-id="${escAttr(nodeId)}"]`;
       rules.push(
-        `  [data-agent-native-node-id="${escAttr(nodeId)}"] {\n` +
-          `${lines.join("\n")}\n` +
-          `  }`,
+        `  ${attrSelector}${attrSelector} {\n${lines.join("\n")}\n  }`,
       );
     }
     if (rules.length === 0) continue;

package/corpus/templates/design/shared/code-layer.ts

@@ -785,6 +785,11 @@ const STYLE_PROPERTY_ALIASES: Record<string, VisualStyleProperty> = {
   radius: "border-radius",
   rotation: "rotate",
   shadow: "box-shadow",
+  // Vendor-prefixed longhands need explicit aliases: the generic camel→kebab
+  // pass in normalizeStyleProperty yields "webkit-text-stroke-*" WITHOUT the
+  // required leading dash, which would miss the allow-list entirely.
+  webkitTextStrokeColor: "-webkit-text-stroke-color",
+  webkitTextStrokeWidth: "-webkit-text-stroke-width",
 };
 
 // Matches url(...) in double-quoted, single-quoted, or unquoted form so each
@@ -1299,19 +1304,107 @@ function findHtmlTagEnd(html: string, start: number): number {
   return html.length;
 }
 
+// Depth-aware closing-tag scan: used for NON_VISUAL_TAGS (script/style/
+// template/etc) whose interiors are skipped wholesale rather than descended
+// into by the main parser loop. A naive "first </tag> after `from`" search
+// (the previous implementation) breaks the moment the same tag nests inside
+// itself — e.g. `<template x-if><ul><template x-for>…</template></ul>
+// </template>` (a completely ordinary Alpine x-if-wrapping-x-for pattern) —
+// because it matches the INNER `</template>` and resumes the main loop right
+// after it, leaving the outer element's true `</ul></template>` closes to be
+// mis-parsed as stray/unmatched tags against whatever unrelated element is
+// on the stack. That corrupted contentEnd tracking for enclosing elements
+// (observed: body-append/insertion offsets computed from the wrong node,
+// splicing moved content into template interiors). Track same-tag open/close
+// depth so only the tag that actually balances the ORIGINAL opening tag is
+// returned, matching real nested-template documents correctly.
 function findClosingTag(
   html: string,
   tag: string,
   from: number,
 ): { closeStart: number; closeEnd: number } | null {
-  const closeRe = new RegExp(`<\\/\\s*${tag}\\s*>`, "gi");
-  closeRe.lastIndex = from;
-  const match = closeRe.exec(html);
-  if (!match) return null;
-  return {
-    closeStart: match.index,
-    closeEnd: match.index + match[0].length,
-  };
+  const tagRe = new RegExp(`<(\\/?)\\s*${tag}\\b[^>]*>`, "gi");
+  tagRe.lastIndex = from;
+  let depth = 0;
+  let match: RegExpExecArray | null;
+  while ((match = tagRe.exec(html))) {
+    const isClose = match[1] === "/";
+    const selfClosing = !isClose && /\/\s*>$/.test(match[0]);
+    if (isClose) {
+      if (depth === 0) {
+        return {
+          closeStart: match.index,
+          closeEnd: match.index + match[0].length,
+        };
+      }
+      depth -= 1;
+    } else if (!selfClosing) {
+      depth += 1;
+    }
+    // Guard against zero-length matches causing an infinite loop (not
+    // expected given the tag-name-anchored pattern, but cheap to keep safe).
+    if (tagRe.lastIndex === match.index) {
+      tagRe.lastIndex += 1;
+    }
+  }
+  return null;
+}
+
+// Defense-in-depth safety net for moveNodeBetweenDocuments: `<template>`
+// interiors (x-if/x-for/x-show templates and friends) are opaque to
+// parseHtmlElements (NON_VISUAL_TAGS) and, per the DOM spec, live in a
+// detached DocumentFragment (`template.content`) — a node inserted into a
+// template's raw markup range renders nowhere, can't be selected/queried by
+// the runtime DOM, and is invisible to every downstream querySelector-based
+// pass (getElementInfo, setAbsolutePositioningForNodeInHtml, etc). A correct
+// findClosingTag (see above) prevents the offset MISCALCULATION that used to
+// cause this, but this function is kept as an independent second guard —
+// even if some other insertion-point calculation ever computes an offset
+// that lands inside a real `<template>` block, this catches it and callers
+// redirect to a real DOM slot instead of silently splicing into markup that
+// will never render or be selectable again.
+//
+// Finding 8: when it fires, callers used to always redirect to the end of
+// <body> (or end of document) — a silent teleport that can land an anchored
+// insert far from where the user was working. `findEnclosingTemplateClose`
+// below returns the ENCLOSING outer template's closeEnd position (the
+// offset immediately after its `</template>`) when `offset` is inside a
+// template interior, so callers can redirect there instead: still a
+// guaranteed-safe real-DOM slot (immediately after a closing tag, a sibling
+// of the template rather than jumping to doc end), just much closer to the
+// anchor the caller actually asked for.
+function isOffsetInsideTemplateInterior(html: string, offset: number): boolean {
+  return findEnclosingTemplateClose(html, offset) !== null;
+}
+
+// Exported ONLY for the finding-8 redirect-target unit test below: with
+// findClosingTag's offset-miscalculation bug fixed (see the doc comment
+// above), every insertAt this module's own callers compute through
+// parseHtmlElements-derived positions (anchor.start/end/contentEnd,
+// bodyEl.contentEnd) already lands OUTSIDE template interiors in practice —
+// NON_VISUAL_TAGS like <template> are skipped wholesale, so a template can
+// never itself become part of another element's registered content range.
+// That makes this guard a true defense-in-depth backstop with no reachable
+// integration-level repro through moveNodeBetweenDocuments today; testing
+// the redirect target directly against a synthetic offset is the honest way
+// to pin its behavior instead of contriving a fragile call into the guard.
+export function findEnclosingTemplateClose(
+  html: string,
+  offset: number,
+): { closeEnd: number } | null {
+  const templateOpenRe = /<template\b[^>]*>/gi;
+  let match: RegExpExecArray | null;
+  while ((match = templateOpenRe.exec(html))) {
+    const openEnd = match.index + match[0].length;
+    if (openEnd > offset) break;
+    const close = findClosingTag(html, "template", openEnd);
+    const contentEnd = close ? close.closeStart : html.length;
+    if (offset > openEnd && offset <= contentEnd) {
+      return { closeEnd: close ? close.closeEnd : html.length };
+    }
+    templateOpenRe.lastIndex = close ? close.closeEnd : html.length;
+  }
+  return null;
 }
 
 function parseHtmlElements(html: string): ParsedElement[] {
@@ -4031,6 +4124,17 @@ export interface MoveNodeBetweenDocumentsResult {
    * Only present when status is "applied".
    */
   movedNodeId?: string;
+  /**
+   * Finding 8: true when the requested anchor placement fell inside a
+   * `<template>` interior and the insert was redirected to a real DOM slot
+   * instead (immediately after the enclosing template's `</template>` when
+   * that could be located, otherwise the pre-existing doc-end/body-end
+   * fallback). Hosts can use this to toast a "landed near, not exactly
+   * where you dropped it" notice instead of the previous fully silent
+   * teleport. Only meaningful when status is "applied" and an anchor was
+   * requested.
+   */
+  anchorRedirected?: boolean;
 }
 
 /**
@@ -4117,6 +4221,7 @@ export function moveNodeBetweenDocuments(
 
   // --- Insert fragment into destHtml ---
   let nextDestHtml: string;
+  let anchorRedirected = false;
 
   if (anchorNodeId) {
     const anchor = destElements.find(
@@ -4130,7 +4235,7 @@ export function moveNodeBetweenDocuments(
         message: `Anchor node with data-agent-native-node-id="${anchorNodeId}" not found in destHtml.`,
       };
     }
-    const insertAt =
+    let insertAt =
       placement === "before"
         ? anchor.start
         : placement === "after"
@@ -4138,15 +4243,44 @@ export function moveNodeBetweenDocuments(
           : anchor.selfClosing
             ? anchor.end
             : anchor.contentEnd;
+    // Never splice into a <template> interior — it renders nowhere and is
+    // unselectable afterward (see isOffsetInsideTemplateInterior doc above).
+    // Finding 8: redirect to immediately AFTER the ENCLOSING outer
+    // </template> when it can be located — still a guaranteed-safe real-DOM
+    // slot, just a sibling of the template instead of a jump all the way to
+    // the end of <body>/the document. Falls back to the old doc-end/body-end
+    // behavior only if the enclosing template's close somehow can't be
+    // resolved (defense-in-depth for a guard that should always agree with
+    // itself here).
+    const enclosingTemplate = findEnclosingTemplateClose(destHtml, insertAt);
+    if (enclosingTemplate) {
+      insertAt = enclosingTemplate.closeEnd;
+      anchorRedirected = true;
+    } else if (isOffsetInsideTemplateInterior(destHtml, insertAt)) {
+      const bodyEl = destElements.find((el) => el.tag === "body");
+      insertAt = bodyEl
+        ? bodyEl.selfClosing
+          ? bodyEl.end
+          : bodyEl.contentEnd
+        : destHtml.length;
+      anchorRedirected = true;
+    }
     nextDestHtml = `${destHtml.slice(0, insertAt)}${fragment}${destHtml.slice(insertAt)}`;
   } else {
     // Default: find <body> and append inside it, or append at end of doc.
     const bodyEl = destElements.find((el) => el.tag === "body");
-    const insertAt = bodyEl
+    let insertAt = bodyEl
       ? bodyEl.selfClosing
         ? bodyEl.end
         : bodyEl.contentEnd
       : destHtml.length;
+    // Same template-interior guard as the anchored branch above — a
+    // miscomputed bodyEl.contentEnd (or a body that itself is only reachable
+    // through a template, e.g. a fragment being treated as a full document)
+    // must never land inside template markup.
+    if (isOffsetInsideTemplateInterior(destHtml, insertAt)) {
+      insertAt = destHtml.length;
+    }
     nextDestHtml = `${destHtml.slice(0, insertAt)}${fragment}${destHtml.slice(insertAt)}`;
   }
 
@@ -4158,5 +4292,6 @@ export function moveNodeBetweenDocuments(
     destHtml: nextDestHtml,
     status: "applied",
     movedNodeId,
+    ...(anchorRedirected ? { anchorRedirected: true } : {}),
   };
 }

package/dist/client/use-db-sync.d.ts

@@ -15,6 +15,24 @@ export type SyncEvent = {
     requestSource?: string;
     [k: string]: unknown;
 };
+/**
+ * True for sync events that drive immediate, agent-initiated UI navigation
+ * or interaction rather than passive data invalidation — app-state writes in
+ * general (they back `["app-state"]` queries directly), and specifically the
+ * `navigate` / `show-questions` / `__set_url__` app-state keys that
+ * `invalidateForEvents` special-cases into their own query keys below.
+ *
+ * `useDbSync` batches ordinary invalidation-driving events (action/collab/db
+ * change events) into one flush per `INVALIDATE_COALESCE_MS` so a chatty doc
+ * doesn't refetch on every keystroke. That trade-off is wrong for these
+ * events: agent-driven navigation, `set-url`, and guided-questions prompts
+ * must land as close to instantly as possible, so any batch containing one
+ * of these bypasses the coalesce window and flushes immediately instead.
+ *
+ * Exported as a small pure predicate so this classification is unit-testable
+ * independent of the transport/timer plumbing around it.
+ */
+export declare function isInteractionCriticalSyncEvent(event: SyncEvent): boolean;
 /** @internal */
 export declare function _resetSyncTransportRegistryForTests(): void;
 export interface SubscribeSyncEventsOptions {

package/dist/client/use-db-sync.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"use-db-sync.d.ts","sourceRoot":"","sources":["../../src/client/use-db-sync.ts"],"names":[],"mappings":"AAUA,UAAU,KAAK;IACb,QAAQ,EAAE,SAAS,OAAO,EAAE,CAAC;CAC9B;AAED,UAAU,WAAW;IACnB,iBAAiB,CAAC,IAAI,CAAC,EAAE;QACvB,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;QACpB,SAAS,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,OAAO,CAAC;KACvC,GAAG,IAAI,CAAC;CACV;AAeD,MAAM,MAAM,SAAS,GAAG;IACtB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;CACtB,CAAC;AAqbF,gBAAgB;AAChB,wBAAgB,mCAAmC,IAAI,IAAI,CAE1D;AAED,MAAM,WAAW,0BAA0B;IACzC,gEAAgE;IAChE,QAAQ,EAAE,CAAC,MAAM,EAAE,SAAS,EAAE,EAAE,OAAO,EAAE,MAAM,GAAG,SAAS,KAAK,IAAI,CAAC;IACrE,+EAA+E;IAC/E,gBAAgB,CAAC,EAAE,CAAC,SAAS,EAAE,OAAO,KAAK,IAAI,CAAC;IAChD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,GAAG,KAAK,CAAC;IACxB,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,0BAA0B,GAClC,MAAM,IAAI,CAkBZ;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,wBAAgB,SAAS,CACvB,OAAO,GAAE;IACP,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,GAAG,KAAK,CAAC;IACxB,sCAAsC;IACtC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,CAAC,IAAI,EAAE,GAAG,KAAK,IAAI,CAAC;IAC9B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,yBAAyB,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,OAAO,CAAC;IACtD,6BAA6B,CAAC,EAAE,MAAM,EAAE,CAAC;CACrC,GACL,IAAI,CAsLN;AAED,wCAAwC;AACxC,eAAO,MAAM,cAAc,kBAAY,CAAC;AAExC;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,GAAE;IACP,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,GAAG,KAAK,CAAC;IACxB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,eAAe,CAAC,EAAE,OAAO,CAAC;CACtB,GACL,MAAM,CAuDR"}
+{"version":3,"file":"use-db-sync.d.ts","sourceRoot":"","sources":["../../src/client/use-db-sync.ts"],"names":[],"mappings":"AAUA,UAAU,KAAK;IACb,QAAQ,EAAE,SAAS,OAAO,EAAE,CAAC;CAC9B;AAED,UAAU,WAAW;IACnB,iBAAiB,CAAC,IAAI,CAAC,EAAE;QACvB,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;QACpB,SAAS,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,OAAO,CAAC;KACvC,GAAG,IAAI,CAAC;CACV;AAsBD,MAAM,MAAM,SAAS,GAAG;IACtB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;CACtB,CAAC;AAkEF;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,8BAA8B,CAAC,KAAK,EAAE,SAAS,GAAG,OAAO,CAUxE;AAgYD,gBAAgB;AAChB,wBAAgB,mCAAmC,IAAI,IAAI,CAE1D;AAED,MAAM,WAAW,0BAA0B;IACzC,gEAAgE;IAChE,QAAQ,EAAE,CAAC,MAAM,EAAE,SAAS,EAAE,EAAE,OAAO,EAAE,MAAM,GAAG,SAAS,KAAK,IAAI,CAAC;IACrE,+EAA+E;IAC/E,gBAAgB,CAAC,EAAE,CAAC,SAAS,EAAE,OAAO,KAAK,IAAI,CAAC;IAChD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,GAAG,KAAK,CAAC;IACxB,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,0BAA0B,GAClC,MAAM,IAAI,CAkBZ;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,wBAAgB,SAAS,CACvB,OAAO,GAAE;IACP,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,GAAG,KAAK,CAAC;IACxB,sCAAsC;IACtC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,CAAC,IAAI,EAAE,GAAG,KAAK,IAAI,CAAC;IAC9B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,yBAAyB,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,OAAO,CAAC;IACtD,6BAA6B,CAAC,EAAE,MAAM,EAAE,CAAC;CACrC,GACL,IAAI,CAyON;AAED,wCAAwC;AACxC,eAAO,MAAM,cAAc,kBAAY,CAAC;AAExC;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,GAAE;IACP,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,GAAG,KAAK,CAAC;IACxB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,eAAe,CAAC,EAAE,OAAO,CAAC;CACtB,GACL,MAAM,CAuDR"}