@agent-native/core 0.92.9 → 0.92.11

package/corpus/templates/design/app/pages/design-editor/editor-state.ts

@@ -244,6 +244,44 @@ export function shouldReplacePreviewAfterVisualStyleCommit(args: {
   return !args.runtimeApplied && !args.runtimeStyleApplied;
 }
 
+export interface OptimisticTextDecorationLineEntry {
+  key: string;
+  value: string;
+}
+
+/**
+ * BUG-DOUBLE-TOGGLE-RACE — Cmd+U (toggle underline) / Cmd+Shift+X (toggle
+ * strikethrough) commit through the SHORTHAND "textDecoration" property, but
+ * commitVisualStyles' synchronous optimistic patch to
+ * selectedElement.computedStyles only merges the exact key(s) it committed —
+ * it never decomposes "textDecoration" into the LONGHAND
+ * "textDecorationLine" the toggle reads to decide its next value.
+ * `computedStyles.textDecorationLine` only catches up once the bridge's
+ * async getComputedStyle round trip lands. A second toggle press within that
+ * window would otherwise recompute nextTextDecorationLineValue from the
+ * STALE pre-toggle value, land on the exact value the first press already
+ * committed, and get deduped as a no-op — consecutive toggles silently stop
+ * alternating.
+ *
+ * Resolves which value a toggle handler should treat as "current": a
+ * still-fresh optimistic value this same toggle family already recorded for
+ * the SAME selected element (`tracked.key === elementKey`) wins over the
+ * (possibly stale) computedStyles reading, since the async measurement that
+ * would refresh computedStyles may not have landed yet. A different/new
+ * element key (or no tracked entry) falls back to computedStyles, so newly
+ * selecting a different element always starts from ITS OWN real state.
+ */
+export function resolveOptimisticTextDecorationLine(
+  tracked: OptimisticTextDecorationLineEntry | null | undefined,
+  elementKey: string | undefined,
+  computedTextDecorationLine: string | undefined,
+): string | undefined {
+  if (tracked && elementKey !== undefined && tracked.key === elementKey) {
+    return tracked.value;
+  }
+  return computedTextDecorationLine;
+}
+
 /**
  * PF12: decide whether a style change from EditPanel (ScrubInput scrub tick /
  * DesignColorPicker drag tick) should skip the expensive source commit

package/corpus/templates/design/app/pages/design-editor/overview-annotation-context.ts

@@ -0,0 +1,157 @@
+import type { DrawAnnotation } from "@/components/visual-editor/DrawOverlay";
+
+export interface OverviewAnnotationScreen {
+  id: string;
+  name: string;
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+
+export interface OverviewAnnotationViewportMap {
+  width: number;
+  height: number;
+  zoom: number;
+  screens: OverviewAnnotationScreen[];
+  board?: { x: number; y: number; width: number; height: number };
+}
+
+function escapeSelector(value: string) {
+  return typeof CSS !== "undefined" && typeof CSS.escape === "function"
+    ? CSS.escape(value)
+    : value.replace(/["\\]/g, "\\$&");
+}
+
+export function collectOverviewAnnotationViewportMap({
+  container,
+  screens,
+  zoom,
+}: {
+  container: HTMLElement;
+  screens: readonly { id: string; name: string }[];
+  zoom: number;
+}): OverviewAnnotationViewportMap {
+  const containerRect = container.getBoundingClientRect();
+  const relativeRect = (rect: DOMRect) => ({
+    x: rect.left - containerRect.left,
+    y: rect.top - containerRect.top,
+    width: rect.width,
+    height: rect.height,
+  });
+  const mappedScreens = screens.flatMap((screen) => {
+    const shell = container.querySelector<HTMLElement>(
+      `[data-frame-id="${escapeSelector(screen.id)}"]`,
+    );
+    return shell
+      ? [
+          {
+            id: screen.id,
+            name: screen.name,
+            ...relativeRect(shell.getBoundingClientRect()),
+          },
+        ]
+      : [];
+  });
+  const boardSurface = container.querySelector<HTMLElement>(
+    "[data-board-surface-layer]",
+  );
+  return {
+    width: containerRect.width,
+    height: containerRect.height,
+    zoom,
+    screens: mappedScreens,
+    board: boardSurface
+      ? relativeRect(boardSurface.getBoundingClientRect())
+      : undefined,
+  };
+}
+
+function annotationBounds(annotation: DrawAnnotation) {
+  if (annotation.type === "text") {
+    return {
+      left: annotation.position.x,
+      top: annotation.position.y,
+      right: annotation.position.x,
+      bottom: annotation.position.y,
+    };
+  }
+  const values = Array.from(
+    annotation.pathData?.matchAll(/-?\d+(?:\.\d+)?/g) ?? [],
+    (match) => Number(match[0]),
+  );
+  const xs = values.filter((_, index) => index % 2 === 0);
+  const ys = values.filter((_, index) => index % 2 === 1);
+  if (!xs.length || !ys.length) return null;
+  return {
+    left: Math.min(...xs),
+    top: Math.min(...ys),
+    right: Math.max(...xs),
+    bottom: Math.max(...ys),
+  };
+}
+
+function mappedAnnotationRegions(
+  annotation: DrawAnnotation,
+  viewportMap: OverviewAnnotationViewportMap,
+) {
+  const bounds = annotationBounds(annotation);
+  if (!bounds) return ["board"];
+  const screens = viewportMap.screens.filter(
+    (screen) =>
+      bounds.right >= screen.x &&
+      bounds.left <= screen.x + screen.width &&
+      bounds.bottom >= screen.y &&
+      bounds.top <= screen.y + screen.height,
+  );
+  return screens.length
+    ? screens.map((screen) => `${screen.name} (${screen.id})`)
+    : ["board outside screens"];
+}
+
+export function formatOverviewAnnotationMessage({
+  designId,
+  designTitle,
+  annotations,
+  instruction,
+  viewportMap,
+}: {
+  designId: string;
+  designTitle?: string;
+  annotations: DrawAnnotation[];
+  instruction: string;
+  viewportMap: OverviewAnnotationViewportMap;
+}) {
+  const drawing = annotations
+    .map((annotation) => {
+      const regions = mappedAnnotationRegions(annotation, viewportMap).join(
+        ", ",
+      );
+      return annotation.type === "path"
+        ? `[stroke regions=${regions} color=${annotation.color} w=${annotation.lineWidth}] ${annotation.pathData}`
+        : `[label regions=${regions} text="${annotation.text ?? ""}" at ${annotation.position.x.toFixed(0)},${annotation.position.y.toFixed(0)}]`;
+    })
+    .join("\n");
+  const screenMap = viewportMap.screens
+    .map(
+      (screen) =>
+        `- ${screen.name} (${screen.id}): x=${screen.x.toFixed(1)}, y=${screen.y.toFixed(1)}, width=${screen.width.toFixed(1)}, height=${screen.height.toFixed(1)}`,
+    )
+    .join("\n");
+  const boardMap = viewportMap.board
+    ? `Board surface: x=${viewportMap.board.x.toFixed(1)}, y=${viewportMap.board.y.toFixed(1)}, width=${viewportMap.board.width.toFixed(1)}, height=${viewportMap.board.height.toFixed(1)}`
+    : "Board surface: the viewport outside the mapped screen rectangles";
+
+  return [
+    `[Annotations on the all-screens canvas for design ${designId}${designTitle ? ` (${designTitle})` : ""}]`,
+    `Overview viewport: ${viewportMap.width.toFixed(0)}x${viewportMap.height.toFixed(0)} at ${viewportMap.zoom.toFixed(1)}% zoom`,
+    "Coordinates and screen bounds are viewport-relative at send time; their x/y positions encode the current canvas pan.",
+    "",
+    "[Screen map]",
+    screenMap || "- No screen rectangles were visible",
+    boardMap,
+    ...(drawing ? ["", "[Drawing]", drawing] : []),
+    "",
+    instruction || "Apply these annotations to the design.",
+  ].join("\n");
+}

package/corpus/templates/design/app/pages/design-editor/overview-camera.ts

@@ -76,9 +76,11 @@ export function getScreenFrameOriginCanvas(args: {
  * `getInitialFrameGeometry(index, ...)` fallback `getSelectedScreenGeometryForInspector`
  * and `getScreenFrameOriginCanvas` above already use — as `FrameEntry[]` for
  * `@shared/canvas-math` bounds/fit helpers (`getFrameGroupBounds`,
- * `getCameraForBounds`). Optionally includes the board frame (real Figma has
- * no board-file equivalent, but a design with only board primitives and no
- * screens should still have something to fit to).
+ * `getCameraForBounds`). Optionally includes the bounds of actual board
+ * content. This must never receive the logical board hit-test surface: that
+ * surface is intentionally enormous and including it would make zoom-to-fit
+ * and adjacent-screen placement behave as though the design were 131,072px
+ * wide even when the board is empty.
  */
 export function getAllScreenFrameEntries(args: {
   overviewScreens: Array<{
@@ -87,7 +89,7 @@ export function getAllScreenFrameEntries(args: {
     height?: number;
   }>;
   canvasFrameGeometryById: CanvasFrameGeometryById;
-  boardFrameGeometry?: FrameGeometry;
+  boardContentBounds?: FrameGeometry | null;
   boardFileId?: string | null;
 }): FrameEntry[] {
   const entries: FrameEntry[] = args.overviewScreens.map((screen, index) => {
@@ -103,10 +105,10 @@ export function getAllScreenFrameEntries(args: {
   });
   if (
     args.boardFileId &&
-    args.boardFrameGeometry &&
+    args.boardContentBounds &&
     !entries.some((entry) => entry.id === args.boardFileId)
   ) {
-    entries.push({ id: args.boardFileId, geometry: args.boardFrameGeometry });
+    entries.push({ id: args.boardFileId, geometry: args.boardContentBounds });
   }
   return entries;
 }
@@ -436,3 +438,57 @@ export function shouldPopToOverviewOnZoomChange(args: {
   if (args.suppressExplicitZoom) return false;
   return shouldPopToOverviewOnZoomOut(args);
 }
+
+/**
+ * PASTE-HERE-IN-CONTENT: converts a viewport client point into a
+ * screen/iframe-local canvas point, given that iframe's own
+ * boundingClientRect and the zoom percent (0-100) currently scaling it.
+ *
+ * Shared by DesignEditor's getContextCanvasPoint (the background/board
+ * right-click path, reached through CanvasContextMenu's own
+ * onContextMenuCapture) and handleIframeContextMenu (a right-click that
+ * lands ON rendered screen content — an element, or empty in-screen space —
+ * which opens the menu imperatively via a ref and so bypasses
+ * onContextMenuCapture, and with it getCanvasPoint, entirely). Before this
+ * was wired into handleIframeContextMenu too, "Paste here" triggered from a
+ * right-click on actual screen content never got a canvasX/canvasY at all
+ * and silently fell back to the position-less cascade/offset paste instead
+ * of landing under the cursor — only a right-click on the empty canvas
+ * background (which still goes through onContextMenuCapture) worked.
+ *
+ * Returns null when there's no iframe rect to measure against or the zoom
+ * factor is non-positive (would divide by zero / invert the sign), matching
+ * "no reliable canvas point" — callers fall back to their own
+ * container-relative or position-less behavior in that case.
+ */
+export function computeIframeLocalCanvasPoint(args: {
+  clientX: number;
+  clientY: number;
+  iframeRect: { left: number; top: number } | null | undefined;
+  zoomPercent: number;
+}): { x: number; y: number } | null {
+  if (!args.iframeRect || !(args.zoomPercent > 0)) return null;
+  const factor = args.zoomPercent / 100;
+  return {
+    x: Math.max(0, (args.clientX - args.iframeRect.left) / factor),
+    y: Math.max(0, (args.clientY - args.iframeRect.top) / factor),
+  };
+}
+
+/**
+ * Reads MultiScreenCanvas's live imperative zoom from the exact inline
+ * transform written by `applyViewToDom` while a wheel/pinch gesture is still
+ * settling. React's `overviewCanvasZoom` intentionally lags those per-frame
+ * DOM writes until the gesture commit, so cursor-sensitive commands must use
+ * this value when it is available.
+ */
+export function readOverviewZoomPercentFromTransform(
+  transform: string | null | undefined,
+  fallbackZoomPercent: number,
+): number {
+  const match = transform?.match(/(?:^|\s)scale\(\s*([-+]?\d*\.?\d+)\s*\)/i);
+  const scale = match ? Number(match[1]) : Number.NaN;
+  return Number.isFinite(scale) && scale > 0
+    ? scale * 100
+    : fallbackZoomPercent;
+}

package/corpus/templates/design/app/pages/design-editor/pending-edits.ts

@@ -18,6 +18,12 @@ import {
 
 import type { ElementInfo } from "@/components/design/types";
 
+import {
+  buildReactSemanticHandoff,
+  redactReactSourceAnchor,
+  type ReactSourceAnchor,
+  type ReactSourceScope,
+} from "./react-semantic-handoff";
 import { camelStyleProperty } from "./style-utils";
 
 export interface PendingVisualStyleEdit {
@@ -26,6 +32,7 @@ export interface PendingVisualStyleEdit {
   screenName: string;
   selector: string;
   sourceId?: string | null;
+  sourceAnchor?: ReactSourceAnchor;
   tagName?: string | null;
   classes: string[];
   styles: Record<string, string>;
@@ -104,6 +111,7 @@ export interface PendingLiveTextEdit {
   screenName: string;
   selector: string;
   sourceId?: string | null;
+  sourceAnchor?: ReactSourceAnchor;
   tagName?: string | null;
   classes: string[];
   value: string;
@@ -120,13 +128,154 @@ export interface PendingLiveStructureEdit {
   screenName: string;
   selector: string;
   sourceId?: string | null;
+  sourceAnchor?: ReactSourceAnchor;
   anchorSelector: string;
   anchorSourceId?: string | null;
+  anchorSourceAnchor?: ReactSourceAnchor;
   placement: "before" | "after" | "inside";
   requestId?: string;
   updatedAt: number;
 }
 
+/**
+ * Convert bridge provenance into a bounded semantic source anchor. Runtime
+ * ids remain useful for correlating the live preview, but they are never
+ * treated as source identities by the coding-agent handoff.
+ */
+interface NormalizedResolvablePath {
+  value: string;
+  absolute: boolean;
+  caseInsensitive: boolean;
+}
+
+function normalizeResolvablePath(
+  rawValue: string | undefined,
+): NormalizedResolvablePath | undefined {
+  const raw = rawValue?.trim().replace(/\\/g, "/");
+  if (!raw || raw.includes("\0")) return undefined;
+
+  let prefix = "";
+  let remainder = raw;
+  let absolute = false;
+  let caseInsensitive = false;
+  const drive = raw.match(/^([a-z]):(\/.*)?$/i);
+  if (drive) {
+    // `C:foo` is drive-relative and must not be treated as a project path.
+    if (!drive[2]?.startsWith("/")) return undefined;
+    prefix = `${drive[1]!.toUpperCase()}:/`;
+    remainder = drive[2].slice(1);
+    absolute = true;
+    caseInsensitive = true;
+  } else if (raw.startsWith("//")) {
+    const [server, share, ...rest] = raw.slice(2).split("/");
+    if (!server || !share) return undefined;
+    prefix = `//${server}/${share}`;
+    remainder = rest.join("/");
+    absolute = true;
+    caseInsensitive = true;
+  } else if (raw.startsWith("/")) {
+    prefix = "/";
+    remainder = raw.slice(1);
+    absolute = true;
+  } else if (/^[a-z]+:/i.test(raw)) {
+    // URL-like values and unsupported drive-relative paths are not files.
+    return undefined;
+  }
+
+  const segments: string[] = [];
+  for (const segment of remainder.split("/")) {
+    if (!segment || segment === ".") continue;
+    if (segment === "..") {
+      if (segments.length > 0) {
+        segments.pop();
+      } else if (!absolute) {
+        // A relative path may not escape its unknown project root.
+        return undefined;
+      }
+      continue;
+    }
+    segments.push(segment);
+  }
+
+  const suffix = segments.join("/");
+  const value = absolute
+    ? prefix.endsWith("/")
+      ? `${prefix}${suffix}`
+      : suffix
+        ? `${prefix}/${suffix}`
+        : prefix
+    : suffix;
+  if (!value) return undefined;
+  return { value, absolute, caseInsensitive };
+}
+
+function sourcePathRelativeToRoot(args: {
+  sourceFile: string;
+  rootPath?: string;
+}): string | undefined {
+  const source = normalizeResolvablePath(args.sourceFile);
+  if (!source) return undefined;
+  if (!source.absolute) return source.value;
+
+  const root = normalizeResolvablePath(args.rootPath);
+  if (!root?.absolute || root.caseInsensitive !== source.caseInsensitive) {
+    return undefined;
+  }
+  const comparableSource = source.caseInsensitive
+    ? source.value.toLowerCase()
+    : source.value;
+  const comparableRoot = root.caseInsensitive
+    ? root.value.toLowerCase()
+    : root.value;
+  const rootPrefix = comparableRoot.endsWith("/")
+    ? comparableRoot
+    : `${comparableRoot}/`;
+  if (!comparableSource.startsWith(rootPrefix)) return undefined;
+  const relative = source.value.slice(rootPrefix.length);
+  return normalizeResolvablePath(relative)?.value;
+}
+
+export function reactSourceAnchorForPendingEdit(args: {
+  info?: Pick<ElementInfo, "provenance" | "sourceId" | "selector"> | null;
+  id?: string;
+  runtimeMultiplicity?: number;
+  scope?: ReactSourceScope;
+  reason?: string;
+  rootPath?: string;
+}): ReactSourceAnchor | undefined {
+  const provenance = args.info?.provenance;
+  const sourceFile = provenance?.sourceFile?.trim();
+  if (!sourceFile || !provenance?.line || !provenance.column) return undefined;
+  const runtimeMultiplicity =
+    Number.isInteger(args.runtimeMultiplicity) &&
+    (args.runtimeMultiplicity ?? 0) > 0
+      ? args.runtimeMultiplicity!
+      : 1;
+  const relPath = sourcePathRelativeToRoot({
+    sourceFile,
+    rootPath: args.rootPath,
+  });
+  return {
+    id:
+      args.id?.trim() ||
+      args.info?.sourceId?.trim() ||
+      args.info?.selector?.trim() ||
+      undefined,
+    // Keep the raw Fiber value only in local state. Prompt serialization goes
+    // through redactReactSourceAnchor, which omits absolute paths until the
+    // connection root has resolved them to a safe project-relative relPath.
+    sourceFile,
+    ...(relPath ? { relPath } : {}),
+    line: provenance.line,
+    column: provenance.column,
+    component: provenance.component,
+    runtimeMultiplicity,
+    ...(args.reason?.trim() ? { reason: args.reason.trim() } : {}),
+    scope:
+      args.scope ?? (runtimeMultiplicity > 1 ? "repeated-render" : "unknown"),
+  };
+}
+
 export type PendingLiveNonStyleEdit =
   | PendingLiveTextEdit
   | PendingLiveStructureEdit;
@@ -289,6 +438,7 @@ export function formatPendingVisualStylePrompt(args: {
     screenName: edit.screenName,
     selector: edit.selector,
     sourceId: edit.sourceId ?? null,
+    sourceAnchor: redactReactSourceAnchor(edit.sourceAnchor),
     tagName: edit.tagName ?? null,
     classes: edit.classes,
     styles: edit.styles,
@@ -297,6 +447,21 @@ export function formatPendingVisualStylePrompt(args: {
   const hasBreakpointScopedEdits = args.edits.some(
     (edit) => edit.breakpoint && edit.breakpoint.upperBoundPx !== null,
   );
+  const reactSourceAnchors = [
+    ...args.edits.map((edit) => edit.sourceAnchor),
+    ...(args.liveEdits ?? []).flatMap((edit) =>
+      edit.kind === "structure"
+        ? [edit.sourceAnchor, edit.anchorSourceAnchor]
+        : [edit.sourceAnchor],
+    ),
+  ].filter((anchor): anchor is ReactSourceAnchor => Boolean(anchor));
+  const hasReactSourceAnchors = reactSourceAnchors.length > 0;
+  const hasRepeatedOrSharedReactScope = reactSourceAnchors.some(
+    (anchor) =>
+      (anchor.runtimeMultiplicity ?? 1) > 1 ||
+      anchor.scope === "repeated-render" ||
+      anchor.scope === "shared-component-definition",
+  );
   const liveEditPayload = (args.liveEdits ?? []).map((edit) => {
     if (edit.kind === "text") {
       return {
@@ -306,12 +471,44 @@ export function formatPendingVisualStylePrompt(args: {
         screenName: edit.screenName,
         selector: edit.selector,
         sourceId: edit.sourceId ?? null,
+        sourceAnchor: redactReactSourceAnchor(edit.sourceAnchor),
         tagName: edit.tagName ?? null,
         classes: edit.classes,
         value: edit.value,
         html: edit.html,
       };
     }
+    const subjectAnchor = edit.sourceAnchor
+      ? { ...edit.sourceAnchor, id: "subject" }
+      : undefined;
+    const targetAnchor = edit.anchorSourceAnchor
+      ? { ...edit.anchorSourceAnchor, id: "target" }
+      : undefined;
+    const semanticHandoff =
+      subjectAnchor && targetAnchor
+        ? buildReactSemanticHandoff({
+            operation: edit.placement === "inside" ? "reparent" : "move",
+            desiredChange: `Move the selected runtime element ${edit.placement} the target runtime element.`,
+            sourceAnchors: [subjectAnchor, targetAnchor],
+            runtimeRelationship: {
+              kind: edit.placement,
+              subjectAnchorIds: ["subject"],
+              targetAnchorId: "target",
+              screenId: edit.screenId,
+              description: `${edit.selector} ${edit.placement} ${edit.anchorSelector}`,
+            },
+            // The packet intentionally starts without a hash: its execution
+            // contract requires read-local-file before every write.
+            versionHashes: [],
+          })
+        : {
+            ok: false as const,
+            rejection: {
+              code: "missing-source-provenance" as const,
+              reason:
+                "Exact subject and target source anchors were not both available for this React structure edit.",
+            },
+          };
     return {
       kind: edit.kind,
       screenId: edit.screenId,
@@ -319,9 +516,14 @@ export function formatPendingVisualStylePrompt(args: {
       screenName: edit.screenName,
       selector: edit.selector,
       sourceId: edit.sourceId ?? null,
+      sourceAnchor: redactReactSourceAnchor(edit.sourceAnchor),
       anchorSelector: edit.anchorSelector,
       anchorSourceId: edit.anchorSourceId ?? null,
+      anchorSourceAnchor: redactReactSourceAnchor(edit.anchorSourceAnchor),
       placement: edit.placement,
+      ...(semanticHandoff.ok
+        ? { semanticHandoff: semanticHandoff.handoff }
+        : { semanticHandoffFailure: semanticHandoff.rejection }),
     };
   });
 
@@ -333,6 +535,12 @@ export function formatPendingVisualStylePrompt(args: {
       : "",
     "",
     "Use the Design source tools to make the source match the current live canvas preview. Read each target screen, resolve source ids/selectors through the code-layer projection, then apply the style, text, and structure changes with focused source edits. Preserve layout, behavior, and unrelated styling.",
+    hasReactSourceAnchors
+      ? "React sourceAnchor fields are source provenance; runtime source ids and selectors are correlation hints only. Verify every project-relative file, line, column, component, and surrounding control flow before editing. Never use a generic AST reparent, group, wrapper, or other structural transform. For semantic structure edits, follow the embedded semanticHandoff packet and use this exact guarded sequence: read-local-file, capture its versionHash, obtain human write consent, write-local-file with expectedVersionHash and requireExpectedVersionHash: true, then keep the preview pending until HMR proves the intended runtime relationship. On a version conflict, re-read and re-plan; never overwrite blindly."
+      : "",
+    hasRepeatedOrSharedReactScope
+      ? "At least one React anchor is repeated at runtime or resolves to a shared component definition. Inspect map/conditional/component call sites and confirm whether the change should affect one instance or every instance before writing source."
+      : "",
     hasBreakpointScopedEdits
       ? "Edits that carry a `breakpoint` field were made while a narrower breakpoint frame was active: apply them as width-scoped overrides (apply-visual-edit with `activeFrameWidthPx` set to breakpoint.activeWidthPx), NOT as base writes — base values must keep rendering at wider viewports."
       : "",
@@ -361,6 +569,43 @@ export function resolveOverviewScreenSourceType(
   );
 }
 
+export function shouldUseRuntimeLayerProjection(args: {
+  screen:
+    | { sourceType?: unknown; bridgeUrl?: string | null }
+    | null
+    | undefined;
+  fallbackSourceType?: DesignSourceType;
+  content: string;
+}): boolean {
+  if (
+    resolveOverviewScreenSourceType(
+      args.screen,
+      args.fallbackSourceType ?? "inline",
+    ) !== "localhost"
+  ) {
+    return false;
+  }
+  try {
+    const url = new URL(args.content.trim());
+    return url.protocol === "http:" || url.protocol === "https:";
+  } catch {
+    return false;
+  }
+}
+
+export function shouldPreferRuntimeLayerProjection(args: {
+  eligible: boolean;
+  runtimeNodeCount: number;
+  sourceNodeCount: number;
+}): boolean {
+  // A hydrated localhost tree is the visible app's ground truth even when SSR
+  // happened to emit the same number of nodes (or more wrappers). Keep the
+  // source projection separately for writes; never use counts to decide which
+  // tree represents the live Layers panel.
+  void args.sourceNodeCount;
+  return args.eligible && args.runtimeNodeCount > 0;
+}
+
 export function shouldShowPendingVisualStyleApply(args: {
   edits: readonly PendingVisualStyleEdit[];
   liveEdits?: readonly PendingLiveNonStyleEdit[];