@agent-native/core 0.129.1 → 0.130.0

package/corpus/templates/design/app/pages/VisualEdit.tsx

@@ -8,6 +8,7 @@ import {
   IconDeviceFloppy,
   IconLayoutGrid,
 } from "@tabler/icons-react";
+import { useEffect, useState } from "react";
 import { Link } from "react-router";
 
 import { Button } from "@/components/ui/button";
@@ -16,10 +17,22 @@ export default function VisualEditPage() {
   const t = useT();
   const { session } = useSession();
   const hasSession = Boolean(session?.email);
-  const primaryHref = hasSession
-    ? "/"
-    : buildSignInReturnHref({ returnTo: "/visual-edit?intent=save" });
-  const primaryAriaLabel = hasSession
+  const [hasHydrated, setHasHydrated] = useState(false);
+  const [signInHref, setSignInHref] = useState<string | null>(null);
+
+  useEffect(() => {
+    setHasHydrated(true);
+    if (hasSession) return;
+    setSignInHref(
+      buildSignInReturnHref({ returnTo: "/visual-edit?intent=save" }),
+    );
+  }, [hasSession]);
+
+  // Server shells are intentionally anonymous; defer session-specific chrome
+  // until after hydration so the public entry never reconciles different links.
+  const isSignedIn = hasHydrated && hasSession;
+  const primaryHref = isSignedIn ? "/" : (signInHref ?? undefined);
+  const primaryAriaLabel = isSignedIn
     ? t("visualEdit.openDesign")
     : t("designEditor.signUpToSave");
 
@@ -35,7 +48,7 @@ export default function VisualEditPage() {
           </Link>
           <Button asChild variant="outline" size="sm">
             <a href={primaryHref} aria-label={primaryAriaLabel}>
-              {hasSession
+              {isSignedIn
                 ? t("visualEdit.openDesign")
                 : t("designEditor.signUpToSave")}
               <IconArrowUpRight className="size-4" />
@@ -59,7 +72,7 @@ export default function VisualEditPage() {
               <Button asChild size="lg" className="gap-2">
                 <a href={primaryHref} aria-label={primaryAriaLabel}>
                   <IconDeviceFloppy className="size-4" />
-                  {hasSession
+                  {isSignedIn
                     ? t("visualEdit.openDesign")
                     : t("designEditor.signUpToSave")}
                 </a>

package/corpus/templates/design/app/pages/design-editor/action-error.ts

@@ -0,0 +1,19 @@
+/**
+ * The action HTTP surface echoes a real message only for explicit client
+ * errors; an unclassified failure comes back as a 5xx "Internal server error"
+ * with the cause server-log-only. Show the former as toast detail and drop the
+ * latter, so a toast never reads as if it explained something when it didn't.
+ */
+
+/** `callAction` prefixes every rejection with `Action <name> failed: `. */
+const CALL_ACTION_PREFIX = /^Action [\w.-]+ failed:\s*/;
+
+export function actionErrorDetail(error: unknown): string | undefined {
+  const status = (error as { status?: unknown } | null | undefined)?.status;
+  if (typeof status !== "number" || status < 400 || status >= 500) {
+    return undefined;
+  }
+  const message = error instanceof Error ? error.message : "";
+  const detail = message.replace(CALL_ACTION_PREFIX, "").trim();
+  return detail || undefined;
+}

package/corpus/templates/design/app/pages/design-editor/canvas-primitive-insert.ts

@@ -13,6 +13,7 @@ import {
 } from "./canvas-primitives";
 import { BOARD_TEXT_AUTO_COLOR_MARKER } from "./cross-screen-text-color";
 import { escapeHtmlAttributeValue, escapeHtmlText } from "./dom-utils";
+import { isStandaloneHttpUrl } from "./editor-state";
 import type { DesignFile } from "./types";
 
 export function nextDuplicatedFilename(
@@ -188,6 +189,11 @@ export function appendCanvasPrimitiveToHtml(
   options?: { preserveNegativePosition?: boolean; isBoardTarget?: boolean },
 ): string | null {
   if (typeof window === "undefined") return null;
+  // A live/localhost screen stores its route URL here, not a document.
+  // Appending to it parses the URL as body text and returns a whole HTML file,
+  // which the caller then persists OVER the URL — the screen stops being live
+  // and the route is gone. There is no correct append for this shape.
+  if (isStandaloneHttpUrl(content)) return null;
   try {
     const doc = new DOMParser().parseFromString(content, "text/html");
     if (!doc.body) return null;
@@ -477,3 +483,26 @@ export function appendCanvasPrimitiveToHtml(
     return null;
   }
 }
+
+/**
+ * Extract one newly-created primitive from a temporary document as markup the
+ * live iframe bridge can insert. URL-backed screens keep their route URL in the
+ * Design file, so their creation path must serialize a node without ever
+ * rewriting that file content.
+ */
+export function extractCanvasPrimitiveHtml(
+  content: string,
+  nodeId: string,
+): string | null {
+  if (typeof window === "undefined") return null;
+  try {
+    const doc = new DOMParser().parseFromString(content, "text/html");
+    const safeNodeId = nodeId.replace(/["\\]/g, "\\$&");
+    return (
+      doc.querySelector(`[data-agent-native-node-id="${safeNodeId}"]`)
+        ?.outerHTML ?? null
+    );
+  } catch {
+    return null;
+  }
+}

package/corpus/templates/design/app/pages/design-editor/clone-and-pen-edit.ts

@@ -14,6 +14,7 @@ import {
 import { uniqueLayerId } from "./canvas-primitive-insert";
 import { reassignClonedAuthoredIds } from "./clone-idrefs";
 import { queryUniqueSelector } from "./dom-utils";
+import { isStandaloneHttpUrl } from "./editor-state";
 import {
   applyPortableStyles,
   elementAtPortableStylePath,
@@ -236,6 +237,11 @@ export function insertClonedHtmlLayers(
   nodeIdMap: Map<string, string>;
 } | null {
   if (typeof window === "undefined" || layerHtmls.length === 0) return null;
+  // Same hazard appendCanvasPrimitiveToHtml guards: a live screen's stored
+  // content is its route URL, and returning an "edited document" for it means
+  // the caller persists HTML over the URL. Paste, duplicate, and image-drop
+  // all land here, so refuse the shape once rather than at each of them.
+  if (isStandaloneHttpUrl(content)) return null;
   try {
     const doc = new DOMParser().parseFromString(content, "text/html");
     if (!doc.body) return null;

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

@@ -6,6 +6,11 @@ import {
   removeCodeLayerNodeFromHtml,
 } from "@shared/code-layer";
 import { isComponentInstance } from "@shared/component-model";
+import {
+  ELEMENT_PROVENANCE_METHODS,
+  type ElementProvenanceFramework,
+  type ElementProvenanceMethod,
+} from "@shared/source-mode";
 export {
   renameFilenamePreservingExtension,
   replaceDataScreenReferences,
@@ -83,6 +88,69 @@ export function codeLayerSelectorAliases(
   );
 }
 
+/**
+ * Selector candidate groups for a host-initiated removal in the LIVE iframe
+ * (the bridge's `delete-element`), one group per node to remove.
+ *
+ * A live/localhost screen runs two different node-id namespaces: the document
+ * carries the ids the injected bridge assigned there, while every host-side
+ * projection is built from the fetched source snapshot that
+ * `ensureCodeLayerNodeIdsInHtml` stamped separately. A selector taken from the
+ * source projection therefore matches nothing in the running document — and
+ * `delete-element` is fire-and-forget, so the editor reported success and
+ * cleared the selection while the element stayed on screen.
+ *
+ * Order of trust: the runtime layer model's aliases (Layers-panel selection on
+ * a runtime-projected screen), then the source-projection selectors carrying
+ * the bridge-reported identities as extra candidates, then those identities
+ * alone. `findRuntimeTarget` in the bridge takes the first candidate that
+ * resolves, so a group may safely mix namespaces.
+ */
+export function liveDeleteSelectorGroups(args: {
+  runtimeAliasGroups: readonly (readonly string[])[];
+  liveSelectionSelectors: readonly string[];
+  fallbackSelectors: readonly string[];
+}): string[][] {
+  const runtimeGroups = args.runtimeAliasGroups
+    .map((aliases) => aliases.filter(Boolean))
+    .filter((aliases) => aliases.length > 0);
+  if (runtimeGroups.length > 0) return runtimeGroups;
+  const liveSelectors = Array.from(
+    new Set(args.liveSelectionSelectors.filter(Boolean)),
+  );
+  if (args.fallbackSelectors.length > 0) {
+    return args.fallbackSelectors.map((selector) =>
+      Array.from(new Set([selector, ...liveSelectors])),
+    );
+  }
+  return liveSelectors.length > 0 ? [liveSelectors] : [];
+}
+
+/**
+ * Whether Delete must run the LIVE-screen removal path (delete the running
+ * DOM node + queue a pending live edit for the coding agent) instead of
+ * rewriting the screen's stored source, mirroring the `localhost` branch
+ * handleVisualStructureChange already takes for a drag-move.
+ *
+ * Deliberately does NOT require a source-snapshot node: a Layers-panel
+ * selection on a runtime-projected screen only exists in the runtime id
+ * namespace, so gating the delete on a resolved source snapshot meant such a
+ * row could be selected and never deleted at all. The runtime alias groups
+ * ARE the target here.
+ */
+export function shouldDeleteThroughLiveScreen(args: {
+  screenSourceType: string | null | undefined;
+  runtimeAliasGroups: readonly (readonly string[])[];
+  liveSelectionSelectors: readonly string[];
+}): boolean {
+  if (args.screenSourceType !== "localhost") return false;
+  return (
+    args.runtimeAliasGroups.some((aliases) =>
+      aliases.some((alias) => Boolean(alias)),
+    ) || args.liveSelectionSelectors.some((selector) => Boolean(selector))
+  );
+}
+
 export function normalizeCodeLayerSelector(selector: string): string {
   return (
     selector
@@ -326,12 +394,84 @@ function provenanceForCodeLayerNode(
     node.dataAttributes["data-source-column"],
   );
   const component = node.dataAttributes["data-component-name"]?.trim();
-  if (!sourceFile && !line && !column && !component) return undefined;
+  const declaredFramework =
+    node.dataAttributes["data-source-framework"]?.trim();
+  const framework =
+    declaredFramework === "html" ||
+    declaredFramework === "react" ||
+    declaredFramework === "vue" ||
+    declaredFramework === "svelte"
+      ? (declaredFramework as ElementProvenanceFramework)
+      : undefined;
+  const ownerSourceFile = node.dataAttributes["data-source-owner-file"]?.trim();
+  const ownerLine = positiveIntegerDataAttribute(
+    node.dataAttributes["data-source-owner-line"],
+  );
+  const ownerColumn = positiveIntegerDataAttribute(
+    node.dataAttributes["data-source-owner-column"],
+  );
+  const ownerComponentName =
+    node.dataAttributes["data-source-owner-component"]?.trim();
+  const ownerKey = node.dataAttributes["data-source-owner-key"]?.trim();
+  const declaredMethod = node.dataAttributes["data-source-method"]?.trim();
+  const declaredOwnerMethod =
+    node.dataAttributes["data-source-owner-method"]?.trim();
+  // The owner site has its own tier: an authored `data-attribute` element can
+  // still owe its owner line to a transformed React 19 owner stack. Unlike
+  // `method` below there is no build-time convention to fall back on — this
+  // bridge is the only writer of data-source-owner-*, and it always labels the
+  // tier — so an unlabelled owner position stays "unknown" rather than
+  // inheriting a claim of authored coordinates.
+  const ownerMethod = ELEMENT_PROVENANCE_METHODS.includes(
+    declaredOwnerMethod as ElementProvenanceMethod,
+  )
+    ? (declaredOwnerMethod as ElementProvenanceMethod)
+    : undefined;
+  // The bridge stamps the tier alongside the position; a projection carrying a
+  // position with no tier came from a build-time transform's own attributes.
+  const method = ELEMENT_PROVENANCE_METHODS.includes(
+    declaredMethod as ElementProvenanceMethod,
+  )
+    ? (declaredMethod as ElementProvenanceMethod)
+    : sourceFile
+      ? "data-attribute"
+      : undefined;
+  const unavailable = node.dataAttributes["data-source-unavailable"]?.trim();
+  // The bridge only stamps a reason when the node resolved to no location, so
+  // a resolved anchor must never carry one back out of the projection.
+  const unavailableReason =
+    !sourceFile &&
+    (unavailable === "not-framework" ||
+      unavailable === "not-react" ||
+      unavailable === "no-debug-info")
+      ? unavailable
+      : undefined;
+  if (
+    !sourceFile &&
+    !line &&
+    !column &&
+    !component &&
+    !framework &&
+    !ownerSourceFile &&
+    !ownerKey &&
+    !unavailableReason
+  ) {
+    return undefined;
+  }
   return {
+    ...(framework ? { framework } : {}),
     ...(sourceFile ? { sourceFile } : {}),
     ...(line ? { line } : {}),
     ...(column ? { column } : {}),
     ...(component ? { component } : {}),
+    ...(ownerSourceFile ? { ownerSourceFile } : {}),
+    ...(ownerLine ? { ownerLine } : {}),
+    ...(ownerColumn ? { ownerColumn } : {}),
+    ...(ownerComponentName ? { ownerComponentName } : {}),
+    ...(ownerKey ? { ownerKey } : {}),
+    ...(method ? { method } : {}),
+    ...(ownerMethod ? { ownerMethod } : {}),
+    ...(unavailableReason ? { unavailableReason } : {}),
   };
 }
 
@@ -465,11 +605,44 @@ export function codeLayerNodeMatchesBridgeTarget(
   return codeLayerSelectorMatches(node, selector);
 }
 
-export function resolveCodeLayerNodeFromBridge(
+/**
+ * `absent` and `ambiguous` must stay distinguishable all the way to the UI —
+ * five matching instances is a scoping question, a gone element is a different
+ * failure. Collapsing both into `null` is what made a style commit on a repeated
+ * component claim the element no longer existed while it was on screen.
+ */
+export type CodeLayerResolution =
+  | { status: "resolved"; node: CodeLayerNode }
+  | { status: "absent" }
+  | { status: "ambiguous"; candidates: CodeLayerNode[] };
+
+/**
+ * A client-rendered app serves `<html><body><div id="root">`, so its projection
+ * holds none of the markup the user can select and every selection reads as
+ * "absent" — a different fact, with a different remedy, from a removed element.
+ * The bound is deliberate: an authored page worth editing has more nodes, and a
+ * false positive only costs a more specific refusal message.
+ */
+const MOUNT_SHELL_MAX_NODES = 4;
+
+export function isClientRenderedMountShell(projection: {
+  nodes: CodeLayerNode[];
+}): boolean {
+  if (projection.nodes.length > MOUNT_SHELL_MAX_NODES) return false;
+  return projection.nodes.every(
+    (node) =>
+      node.tag === "html" ||
+      node.tag === "head" ||
+      node.tag === "body" ||
+      (node.children.length === 0 && !collapsedElementText(node.textSnippet)),
+  );
+}
+
+export function resolveCodeLayerTargetFromBridge(
   projection: { nodes: CodeLayerNode[] },
   selector?: string,
   sourceId?: string,
-): CodeLayerNode | null {
+): CodeLayerResolution {
   // Id-based match first, across the WHOLE projection (not just up to
   // whichever node the old combined-predicate `.find()` reached first) — a
   // sourceId identifies one node by its own stable id/data-attribute, which
@@ -482,7 +655,7 @@ export function resolveCodeLayerNodeFromBridge(
     const idMatch = projection.nodes.find((node) =>
       codeLayerNodeMatchesSourceId(node, sourceId),
     );
-    if (idMatch) return idMatch;
+    if (idMatch) return { status: "resolved", node: idMatch };
   }
   // No sourceId (or no node carries it yet, e.g. a bridge target minted a
   // fresh pending id the projection hasn't picked up) — fall back to the
@@ -493,29 +666,49 @@ export function resolveCodeLayerNodeFromBridge(
   // selector that matches more than one node rather than silently picking
   // the first DOM-order match — mirror that discipline here so a duplicate/
   // move/style edit can never silently land on the wrong sibling instance.
-  if (!selector) return null;
+  if (!selector) return { status: "absent" };
   const selectorMatches = projection.nodes.filter((node) =>
     codeLayerSelectorMatches(node, selector),
   );
-  return selectorMatches.length === 1 ? selectorMatches[0]! : null;
+  if (selectorMatches.length === 1) {
+    return { status: "resolved", node: selectorMatches[0]! };
+  }
+  return selectorMatches.length === 0
+    ? { status: "absent" }
+    : { status: "ambiguous", candidates: selectorMatches };
+}
+
+export function resolveCodeLayerNodeFromBridge(
+  projection: { nodes: CodeLayerNode[] },
+  selector?: string,
+  sourceId?: string,
+): CodeLayerNode | null {
+  const resolution = resolveCodeLayerTargetFromBridge(
+    projection,
+    selector,
+    sourceId,
+  );
+  return resolution.status === "resolved" ? resolution.node : null;
 }
 
 export function collapsedElementText(value: string | null | undefined): string {
   return value?.replace(/\s+/g, " ").trim() ?? "";
 }
 
-export function resolveCodeLayerNodeFromElementInfo(
+export function resolveCodeLayerTargetFromElementInfo(
   projection: { nodes: CodeLayerNode[] },
   info: ElementInfo | null | undefined,
-): CodeLayerNode | null {
-  if (!info) return null;
-  const direct = resolveCodeLayerNodeFromBridge(
+): CodeLayerResolution {
+  if (!info) return { status: "absent" };
+  const direct = resolveCodeLayerTargetFromBridge(
     projection,
     info.selector,
     info.sourceId ?? info.id,
   );
-  if (direct) return direct;
+  if (direct.status === "resolved") return direct;
 
+  // Score even an ambiguous selector: text/class/id evidence it does not carry
+  // can single out one instance. Ambiguity only survives if scoring ties too.
   const tagName = info.tagName.toLowerCase();
   const text = collapsedElementText(info.textContent);
   const classes = new Set(info.classes);
@@ -541,11 +734,25 @@ export function resolveCodeLayerNodeFromElementInfo(
     .filter((candidate) => candidate.score >= 4)
     .sort((a, b) => b.score - a.score);
 
-  if (scored.length === 0) return null;
   const [best, next] = scored;
-  if (!best) return null;
-  if (next && next.score === best.score) return null;
-  return best.node;
+  if (!best) return direct;
+  if (next && next.score === best.score) {
+    return {
+      status: "ambiguous",
+      candidates: scored
+        .filter((candidate) => candidate.score === best.score)
+        .map((candidate) => candidate.node),
+    };
+  }
+  return { status: "resolved", node: best.node };
+}
+
+export function resolveCodeLayerNodeFromElementInfo(
+  projection: { nodes: CodeLayerNode[] },
+  info: ElementInfo | null | undefined,
+): CodeLayerNode | null {
+  const resolution = resolveCodeLayerTargetFromElementInfo(projection, info);
+  return resolution.status === "resolved" ? resolution.node : null;
 }
 
 export function canonicalElementInfoForCodeLayerNode(
@@ -554,6 +761,11 @@ export function canonicalElementInfoForCodeLayerNode(
 ): ElementInfo {
   return {
     ...info,
+    // Keep the bridge's own identity before overwriting it — it is the only
+    // one that resolves in a live document. Idempotent: re-canonicalizing an
+    // already-canonicalized info must not overwrite it with the source id.
+    runtimeSelector: info.runtimeSelector ?? info.selector,
+    runtimeSourceId: info.runtimeSourceId ?? info.sourceId,
     sourceId: bridgeSourceIdForCodeLayerNode(node),
     selector: preferredCodeLayerSelector(node),
     classes: node.classes,
@@ -592,6 +804,56 @@ export function elementInfoIsRuntimeOnly(
   );
 }
 
+/**
+ * Per-node refinement of a file's "layers panel is showing the runtime
+ * (localhost-hydrated) tree" flag into an actual "this node has no
+ * resolvable source counterpart" signal.
+ *
+ * `fileIsRuntimeProjected` alone is true for basically every hydrated
+ * localhost screen, React or not — see shouldPreferRuntimeLayerProjection's
+ * doc comment in design-editor/pending-edits.ts — so callers that gated a
+ * React-semantic-handoff requirement on that file-level flag treated every
+ * node on every localhost screen as unresolvable, including on a page with
+ * no React at all.
+ *
+ * Match on the stamped `data-agent-native-node-id` attribute, NOT
+ * CodeLayerNode.id: `id` is `hashStable(sourceKey:...)` (see nodeIdFor in
+ * shared/code-layer.ts), and sourceKey differs between the runtime and
+ * source projection parses of the very same content, so `id` never lines up
+ * even for the identical element — the stamped DOM attribute does.
+ */
+export function isCodeLayerNodeRuntimeOnly(args: {
+  fileIsRuntimeProjected: boolean;
+  nodeIdAttr: string | undefined;
+  sourceNodeIdAttrs: ReadonlySet<string>;
+}): boolean {
+  if (!args.fileIsRuntimeProjected) return false;
+  if (!args.nodeIdAttr) return true;
+  return !args.sourceNodeIdAttrs.has(args.nodeIdAttr);
+}
+
+/**
+ * Whether a Layers-panel hide/lock toggle on a runtime (localhost-hydrated)
+ * node can be handed off to the agent to make durable in React source.
+ *
+ * The handoff is about DURABILITY — writing `data-agent-native-hidden` /
+ * `-locked` into JSX. The visual effect is host state that DesignCanvas
+ * mirrors into the iframe as a `layer-states` message; the source attribute
+ * has no rendering power of its own. A localhost target with no React
+ * debug-source provenance (plain HTML, or a React build without the source
+ * plugin) can never resolve an anchor, so gating the preview on the handoff
+ * made hide/lock a total no-op there and reported "source anchors still
+ * loading" for a load that will never happen. "Nothing to write into" and
+ * "source not loaded yet" must stay different answers.
+ */
+export function runtimeLayerStateHandoffMode(args: {
+  runtimeOnly: boolean;
+  provenanceSourceFile: string | null | undefined;
+}): "handoff" | "preview-only" {
+  if (!args.runtimeOnly) return "preview-only";
+  return args.provenanceSourceFile?.trim() ? "handoff" : "preview-only";
+}
+
 export function codeLayerPatchMessage(
   message: string | null | undefined,
   fallback: string,

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

@@ -1,18 +1,32 @@
+import { isStandaloneHttpUrl } from "@shared/html-content";
+
 import {
+  type DesignFile,
   type DesignLeftPanel,
   type DesignTool,
+  type EditorMode,
   SHOW_DESIGN_CODE_LEFT_PANEL,
 } from "./types";
 
-function isStandaloneHttpUrl(value: string): boolean {
-  const trimmed = value.trim();
-  if (!/^https?:\/\//i.test(trimmed)) return false;
-  try {
-    const parsed = new URL(trimmed);
-    return parsed.protocol === "http:" || parsed.protocol === "https:";
-  } catch {
-    return false;
-  }
+// Definition moved to shared/ so the server write path and code-layer's
+// document transforms guard on the same predicate. Re-exported here because
+// the editor's URL-backed-screen refusals all import it from this module.
+export { isStandaloneHttpUrl };
+
+/**
+ * A live-screen route intentionally refuses whole-document replacement. That
+ * is a successful no-op, unlike an unavailable preview bridge, which callers
+ * must recover by rebuilding their render state.
+ */
+export type PreviewContentReplaceResult =
+  | "applied"
+  | "skipped-live-route"
+  | "unavailable";
+
+export function previewContentReplaceNeedsRenderFallback(
+  result: PreviewContentReplaceResult,
+): boolean {
+  return result === "unavailable";
 }
 
 /**
@@ -110,6 +124,7 @@ export function getDesignEditorStateUrlSearch(args: {
   leftPanel?: DesignLeftPanel | null;
   zoom?: number | null;
   tool?: DesignTool | null;
+  mode?: EditorMode | null;
 }) {
   const params = new URLSearchParams(args.currentSearch);
   const leftPanel =
@@ -155,6 +170,11 @@ export function getDesignEditorStateUrlSearch(args: {
   } else {
     params.delete("tool");
   }
+  if (args.viewMode === "single") {
+    params.set("mode", "interact");
+  } else {
+    params.delete("mode");
+  }
   const query = params.toString();
   return query ? `?${query}` : "";
 }
@@ -491,3 +511,49 @@ export function shouldSendKeepalive(
 ): boolean {
   return hashKnown || !collabLive;
 }
+
+const EMPTY_DESIGN_FILES: DesignFile[] = [];
+
+/**
+ * Identity-stable `design.files` read for the editor render body.
+ *
+ * `design` is null until the `get-design` query resolves, and a literal `??
+ * []` there mints a new array on every render of that window. That identity
+ * feeds `files` → `proposalFileIds` → the pending-node-rewrite effect, whose
+ * empty-files branch commits a fresh `[]` — a passive-effect update that
+ * re-renders, remints the array, and re-fires itself until the query lands
+ * ("Maximum update depth exceeded" on cold loads). Return the shared empty
+ * array so the no-files render is stable.
+ */
+export function resolveServerFiles(
+  design: { files?: DesignFile[] } | null | undefined,
+): DesignFile[] {
+  return design?.files ?? EMPTY_DESIGN_FILES;
+}
+
+/**
+ * Pure decision helper (exported for unit testing) for the pending-local-write
+ * reconcile: now that `file` arrived from the server, may the editor stop
+ * overlaying this file's pending local content and trust the query cache?
+ *
+ * Matching content alone does not prove the server took the write. Every
+ * optimistic writer also mirrors its content into the cached `get-design`
+ * payload while deliberately keeping the file's prior server-clock
+ * `updatedAt`, so an echo of our own cache write is indistinguishable from an
+ * acknowledgement by content. A writer that records `baseUpdatedAt` keeps its
+ * overlay until `updatedAt` actually advances; retiring it early leaves the
+ * cache as the only carrier of the edit, and a `get-design` response already
+ * in flight when the write happened then lands with pre-write content and the
+ * edit vanishes until a reload.
+ */
+export function shouldRetirePendingLocalFileContent(
+  pending: { content: string; baseUpdatedAt?: string | null } | undefined,
+  file: { content?: string | null; updatedAt?: string | null },
+): boolean {
+  if (!pending) return false;
+  if ((file.content ?? "") !== pending.content) return false;
+  return (
+    pending.baseUpdatedAt === undefined ||
+    file.updatedAt !== pending.baseUpdatedAt
+  );
+}

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

@@ -0,0 +1,28 @@
+const LAYER_STATE_SCOPE_SEPARATOR = "\u001f";
+
+export function scopedLayerStateId(screenId: string, layerId: string): string {
+  return layerId === screenId
+    ? screenId
+    : `${screenId}${LAYER_STATE_SCOPE_SEPARATOR}${layerId}`;
+}
+
+export function layerStateIdsForScreen(
+  stateIds: ReadonlySet<string>,
+  screenId: string,
+): Set<string> {
+  const prefix = `${screenId}${LAYER_STATE_SCOPE_SEPARATOR}`;
+  const result = new Set<string>();
+  if (stateIds.has(screenId)) result.add(screenId);
+  stateIds.forEach((id) => {
+    if (id.startsWith(prefix)) result.add(id.slice(prefix.length));
+  });
+  return result;
+}
+
+export function hasScopedLayerState(
+  stateIds: ReadonlySet<string>,
+  screenId: string,
+  layerId: string,
+): boolean {
+  return stateIds.has(scopedLayerStateId(screenId, layerId));
+}