@agent-native/core 0.92.9 → 0.92.11

package/corpus/templates/design/app/lib/figma-clipboard.ts

@@ -0,0 +1,157 @@
+/**
+ * Client-side Figma clipboard helpers: decode the `figmeta` marker Figma
+ * writes into a copy's clipboard HTML, and decide which action a paste
+ * should route through.
+ *
+ * Figma wraps a small base64 JSON payload (`{"fileKey","pasteID","dataType"}`)
+ * between literal `(figmeta)`/`(/figmeta)` markers — the same markers
+ * `hasFigmaClipboardPayload` in `design-import.ts` already scans for to detect
+ * a Figma paste at all. Some Figma clients may instead put that same base64
+ * blob directly in the `data-metadata` attribute with no wrapper markers, so
+ * `extractFigmeta` tries both, defensively, and never throws — any malformed
+ * input just means "not a decodable Figma paste".
+ *
+ * Important caveat carried through to the server: `figmeta` has no node ids
+ * (only a `fileKey`), and `pasteID` is an ephemeral, server-side identifier
+ * that isn't resolvable to a node through the public REST API. So a plain
+ * clipboard paste can only ever get an exact node import on a best-effort,
+ * heuristic match (see `server/lib/figma-clipboard-match.ts`) — a copied
+ * frame LINK (which carries a real `node-id`) is the only guaranteed-exact
+ * path (`import-figma-frame`).
+ */
+
+export interface FigmetaPayload {
+  fileKey: string;
+  pasteID?: number;
+  dataType?: string;
+}
+
+const FIGMETA_MARKER_RE = /\(figmeta\)([^(]*?)\(\/figmeta\)/i;
+const DATA_METADATA_ATTR_RE = /\bdata-metadata\s*=\s*(["'])([\s\S]*?)\1/i;
+
+function decodeBase64Json(raw: string): unknown {
+  const trimmed = raw.trim();
+  if (!trimmed) return null;
+  try {
+    const decoded =
+      typeof atob === "function"
+        ? atob(trimmed)
+        : Buffer.from(trimmed, "base64").toString("utf8");
+    return JSON.parse(decoded);
+  } catch {
+    return null;
+  }
+}
+
+function isFigmetaPayload(value: unknown): value is FigmetaPayload {
+  if (!value || typeof value !== "object") return false;
+  const fileKey = (value as { fileKey?: unknown }).fileKey;
+  return typeof fileKey === "string" && fileKey.trim().length > 0;
+}
+
+function normalizeFigmetaPayload(value: FigmetaPayload): FigmetaPayload {
+  const payload: FigmetaPayload = { fileKey: value.fileKey.trim() };
+  if (typeof value.pasteID === "number") payload.pasteID = value.pasteID;
+  if (typeof value.dataType === "string") payload.dataType = value.dataType;
+  return payload;
+}
+
+/**
+ * Extracts and decodes the `figmeta` payload from a clipboard's raw HTML (or
+ * plain text), if present. Returns `null` for anything that isn't a
+ * decodable Figma `figmeta` marker — this never throws, so callers can run it
+ * unconditionally on every paste.
+ */
+export function extractFigmeta(
+  html: string | null | undefined,
+): FigmetaPayload | null {
+  if (!html) return null;
+
+  const markerMatch = html.match(FIGMETA_MARKER_RE);
+  if (markerMatch?.[1]) {
+    const parsed = decodeBase64Json(markerMatch[1]);
+    if (isFigmetaPayload(parsed)) return normalizeFigmetaPayload(parsed);
+  }
+
+  // Defensive fallback: some clients may emit data-metadata as a bare base64
+  // blob with no (figmeta)...(/figmeta) wrapper markers.
+  const attrMatch = html.match(DATA_METADATA_ATTR_RE);
+  if (attrMatch?.[2]) {
+    const parsed = decodeBase64Json(attrMatch[2]);
+    if (isFigmetaPayload(parsed)) return normalizeFigmetaPayload(parsed);
+  }
+
+  return null;
+}
+
+export type FigmaApiKeyStatus = "configured" | "missing" | "unknown";
+export type FigmaPasteStrategy = "rest" | "html-fallback" | "not-figma";
+
+/**
+ * Pure decision matrix for what a paste should attempt, given whether it
+ * decoded a `figmeta` payload and (if known) whether the Figma access token
+ * is configured:
+ *
+ * - No `figmeta` -> not a Figma paste at all (`"not-figma"`).
+ * - `figmeta` present but the key is known-missing -> skip the REST attempt
+ *   entirely and go straight to the legacy HTML path (`"html-fallback"`).
+ * - `figmeta` present and the key is configured, or its status isn't known
+ *   client-side -> attempt the REST import (`"rest"`). The server is the
+ *   authority on whether the key actually works; passing `"unknown"` here
+ *   just means "try REST, let the server fall back for real if it can't."
+ */
+export function decideFigmaPasteStrategy(
+  figmeta: FigmetaPayload | null,
+  apiKeyStatus: FigmaApiKeyStatus = "unknown",
+): FigmaPasteStrategy {
+  if (!figmeta) return "not-figma";
+  if (apiKeyStatus === "missing") return "html-fallback";
+  return "rest";
+}
+
+export type FigmaPasteImportCall =
+  | {
+      action: "import-figma-clipboard";
+      payload: {
+        figmetaFileKey: string;
+        clipboardHtml: string;
+        originalName?: string;
+      };
+    }
+  | {
+      action: "import-design-source";
+      payload: {
+        sourceType: "figma-paste-html";
+        content: string;
+        originalName?: string;
+      };
+    };
+
+/**
+ * Resolves the actual action name + payload a paste should call, given the
+ * raw clipboard HTML. Used by both the canvas-level paste listener and the
+ * Import panel's Figma-paste target so the two call sites stay in lockstep.
+ */
+export function resolveFigmaPasteImportCall(
+  content: string,
+  originalName = "figma-paste.html",
+): FigmaPasteImportCall {
+  const figmeta = extractFigmeta(content);
+  const strategy = decideFigmaPasteStrategy(figmeta, "unknown");
+
+  if (strategy === "not-figma") {
+    return {
+      action: "import-design-source",
+      payload: { sourceType: "figma-paste-html", content, originalName },
+    };
+  }
+
+  return {
+    action: "import-figma-clipboard",
+    payload: {
+      figmetaFileKey: figmeta!.fileKey,
+      clipboardHtml: content,
+      originalName,
+    },
+  };
+}

package/corpus/templates/design/app/lib/figma-svg-copy.ts

@@ -0,0 +1,221 @@
+import { callAction } from "@agent-native/core/client";
+
+export type FigmaSvgCopyErrorCode =
+  | "unsupported"
+  | "blocked"
+  | "write-failed"
+  | "render-failed";
+
+export class FigmaSvgCopyError extends Error {
+  readonly code: FigmaSvgCopyErrorCode;
+
+  constructor(code: FigmaSvgCopyErrorCode, cause?: unknown) {
+    super(`Figma SVG copy ${code}`);
+    this.name = "FigmaSvgCopyError";
+    this.code = code;
+    if (cause !== undefined) {
+      Object.defineProperty(this, "cause", {
+        configurable: true,
+        value: cause,
+      });
+    }
+  }
+}
+
+type ClipboardWriter = Pick<Clipboard, "write"> & {
+  writeText?: Clipboard["writeText"];
+};
+
+type ClipboardItemConstructor = {
+  new (items: Record<string, Blob | Promise<Blob>>): ClipboardItem;
+  supports?: (type: string) => boolean;
+};
+
+export interface FigmaSvgExportActionResult {
+  ok: boolean;
+  reason?: string;
+  svg?: string;
+  filename?: string;
+  report?: unknown;
+}
+
+export interface FigmaSvgExportParams {
+  designId?: string;
+  fileId?: string;
+  filename?: string;
+  nodeId?: string;
+  embedImages?: boolean;
+}
+
+export interface FigmaSvgCopyEnvironment {
+  clipboard?: ClipboardWriter | null;
+  ClipboardItem?: ClipboardItemConstructor | null;
+  /** Injectable override for tests — defaults to the real `callAction`. */
+  callExportAction?: (
+    params: FigmaSvgExportParams,
+  ) => Promise<FigmaSvgExportActionResult>;
+}
+
+function defaultFigmaSvgCopyEnvironment(): FigmaSvgCopyEnvironment {
+  return {
+    clipboard:
+      typeof navigator === "undefined" ? null : (navigator.clipboard ?? null),
+    ClipboardItem:
+      typeof globalThis.ClipboardItem === "undefined"
+        ? null
+        : globalThis.ClipboardItem,
+  };
+}
+
+function defaultCallExportAction(
+  params: FigmaSvgExportParams,
+): Promise<FigmaSvgExportActionResult> {
+  // Same cast-to-loose-signature pattern as design-save-outbox.ts's
+  // `invokeAction` default: the action registry's generated `ActionName`
+  // union doesn't need to be threaded through this small client module.
+  return (
+    callAction as (
+      name: string,
+      params: Record<string, unknown>,
+    ) => Promise<FigmaSvgExportActionResult>
+  )("export-design-as-figma-svg", params as unknown as Record<string, unknown>);
+}
+
+export function canCopyFigmaSvgToClipboard(
+  environment: FigmaSvgCopyEnvironment = defaultFigmaSvgCopyEnvironment(),
+): boolean {
+  // `text/plain` (the proven Figma-paste MIME — see the export-handoff skill's
+  // "Export to Figma (SVG)" section) only needs a plain `clipboard.write` or
+  // `writeText`; ClipboardItem is optional (only gates the extra
+  // `image/svg+xml` representation).
+  return Boolean(
+    (environment.clipboard?.write && environment.ClipboardItem) ||
+    environment.clipboard?.writeText,
+  );
+}
+
+function supportsClipboardType(
+  ClipboardItemCtor: ClipboardItemConstructor,
+  type: string,
+): boolean {
+  try {
+    return (
+      typeof ClipboardItemCtor.supports !== "function" ||
+      ClipboardItemCtor.supports(type)
+    );
+  } catch {
+    return false;
+  }
+}
+
+function classifyClipboardWriteError(error: unknown): FigmaSvgCopyErrorCode {
+  const name =
+    error && typeof error === "object" && "name" in error
+      ? String(error.name)
+      : "";
+  if (name === "NotAllowedError" || name === "SecurityError") return "blocked";
+  if (name === "NotSupportedError" || error instanceof TypeError)
+    return "unsupported";
+  return "write-failed";
+}
+
+export interface FigmaSvgCopyResult {
+  filename: string;
+  report: unknown;
+}
+
+/**
+ * Exports a design screen (or a selected element's subtree via `nodeId`) as
+ * a genuinely vector SVG through the `export-design-as-figma-svg` action,
+ * then writes it to the system clipboard as BOTH:
+ *
+ *   - `text/plain` — the raw SVG markup. This is the MIME Figma's own paste
+ *     handler reads for "paste as vector shapes"; a `image/svg+xml`-only
+ *     clipboard write is NOT enough on its own for a reliable Figma paste.
+ *   - `image/svg+xml` — the same markup as a typed image representation,
+ *     for any other paste target that specifically requests SVG images.
+ *
+ * Call this from a user-gesture handler (e.g. a context-menu "Copy as SVG"
+ * item) — `clipboard.write` requires transient activation in most browsers,
+ * the same reason `copyPngPromiseToClipboard` in `png-clipboard.ts` is
+ * gesture-scoped.
+ */
+export async function copyDesignAsFigmaSvg(
+  params: FigmaSvgExportParams,
+  environment: FigmaSvgCopyEnvironment = defaultFigmaSvgCopyEnvironment(),
+): Promise<FigmaSvgCopyResult> {
+  if (!canCopyFigmaSvgToClipboard(environment)) {
+    throw new FigmaSvgCopyError("unsupported");
+  }
+
+  const callExportAction =
+    environment.callExportAction ?? defaultCallExportAction;
+  const clipboard = environment.clipboard;
+  const ClipboardItemCtor = environment.ClipboardItem;
+
+  let renderError: unknown;
+  const exportPromise = callExportAction(params)
+    .then((result) => {
+      if (!result.ok || !result.svg) {
+        throw new FigmaSvgCopyError(
+          "render-failed",
+          new Error(result.reason ?? "Figma SVG export failed"),
+        );
+      }
+      return result as FigmaSvgExportActionResult & { svg: string };
+    })
+    .catch((error: unknown) => {
+      renderError =
+        error instanceof FigmaSvgCopyError
+          ? error
+          : new FigmaSvgCopyError("render-failed", error);
+      throw renderError;
+    });
+  // ClipboardItem owns the promises below in real browsers. Keep a separate
+  // observer so test doubles or an early clipboard rejection cannot surface an
+  // unhandled action/render rejection.
+  void exportPromise.catch(() => undefined);
+
+  try {
+    if (clipboard?.write && ClipboardItemCtor) {
+      // Call clipboard.write while the initiating click/key event still owns
+      // transient activation. ClipboardItem deliberately receives pending
+      // Blob promises, matching the proven PNG clipboard path; awaiting the
+      // server render first makes slow exports fail in Safari and hardened
+      // Chromium even though the user invoked the command correctly.
+      const textBlobPromise = exportPromise.then(
+        (result) => new Blob([result.svg], { type: "text/plain" }),
+      );
+      void textBlobPromise.catch(() => undefined);
+      const items: Record<string, Blob | Promise<Blob>> = {
+        "text/plain": textBlobPromise,
+      };
+      if (supportsClipboardType(ClipboardItemCtor, "image/svg+xml")) {
+        const svgBlobPromise = exportPromise.then(
+          (result) => new Blob([result.svg], { type: "image/svg+xml" }),
+        );
+        void svgBlobPromise.catch(() => undefined);
+        items["image/svg+xml"] = svgBlobPromise;
+      }
+      await clipboard.write([new ClipboardItemCtor(items)]);
+    } else if (clipboard?.writeText) {
+      // No ClipboardItem constructor available — still deliver the SVG
+      // markup as text/plain, which is the proven Figma-paste path anyway.
+      const result = await exportPromise;
+      await clipboard.writeText(result.svg);
+    } else {
+      throw new FigmaSvgCopyError("unsupported");
+    }
+  } catch (error) {
+    if (error instanceof FigmaSvgCopyError) throw error;
+    if (renderError !== undefined) throw renderError;
+    throw new FigmaSvgCopyError(classifyClipboardWriteError(error), error);
+  }
+
+  const result = await exportPromise;
+
+  return {
+    filename: result.filename ?? "design-figma.svg",
+    report: result.report,
+  };
+}

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

@@ -306,11 +306,41 @@ export function bridgeSourceIdForCodeLayerNode(node: CodeLayerNode): string {
   );
 }
 
+function positiveIntegerDataAttribute(
+  value: string | undefined,
+): number | undefined {
+  const trimmed = value?.trim();
+  if (!trimmed || !/^\d+$/.test(trimmed)) return undefined;
+  const parsed = Number(trimmed);
+  return Number.isSafeInteger(parsed) && parsed > 0 ? parsed : undefined;
+}
+
+function provenanceForCodeLayerNode(
+  node: CodeLayerNode,
+): ElementInfo["provenance"] {
+  const sourceFile = node.dataAttributes["data-source-file"]?.trim();
+  const line = positiveIntegerDataAttribute(
+    node.dataAttributes["data-source-line"],
+  );
+  const column = positiveIntegerDataAttribute(
+    node.dataAttributes["data-source-column"],
+  );
+  const component = node.dataAttributes["data-component-name"]?.trim();
+  if (!sourceFile && !line && !column && !component) return undefined;
+  return {
+    ...(sourceFile ? { sourceFile } : {}),
+    ...(line ? { line } : {}),
+    ...(column ? { column } : {}),
+    ...(component ? { component } : {}),
+  };
+}
+
 export function elementInfoFromCodeLayerNode(node: CodeLayerNode): ElementInfo {
   return {
     tagName: node.tag,
     id: typeof node.attributes.id === "string" ? node.attributes.id : undefined,
     sourceId: bridgeSourceIdForCodeLayerNode(node),
+    provenance: provenanceForCodeLayerNode(node),
     selector: preferredCodeLayerSelector(node),
     classes: node.classes,
     computedStyles: Object.fromEntries(
@@ -347,15 +377,83 @@ export function cssStyleAliases(
   return result;
 }
 
+// BUG-UNDO-RESIZE-GEOMETRY: width/height are the two computedStyles keys the
+// Layout panel's W/H fields actually read (edit-panel/element-classification.ts's
+// cssElementSize parses element.computedStyles.width/height first, falling
+// back to boundingRect only when that's missing/unparseable). Every other
+// computedStyles property is fine to carry over additively when the fresh
+// (reverted/replayed) source doesn't mention it — most style properties come
+// from a CSS class the string-parse can't see, so keeping the previously
+// known value is the right default. Width/height are different: an undo or
+// redo of a resize commit is EXACTLY a change to (or removal of) an inline
+// width/height, so a stale carried-over value here isn't just incomplete —
+// it's actively wrong (it's the pre-undo/pre-redo box size).
+const GEOMETRY_STYLE_PROPERTIES = ["width", "height"] as const;
+
 export function refreshedComputedStyles(
   info: ElementInfo,
   sourceStyles: Record<string, string>,
   sourceClasses: readonly string[],
 ): Record<string, string> {
   const sourceWithAliases = cssStyleAliases(sourceStyles);
-  return sourceClasses.length > 0
-    ? { ...info.computedStyles, ...sourceWithAliases }
-    : sourceWithAliases;
+  const merged: Record<string, string> =
+    sourceClasses.length > 0
+      ? { ...info.computedStyles, ...sourceWithAliases }
+      : { ...sourceWithAliases };
+  GEOMETRY_STYLE_PROPERTIES.forEach((property) => {
+    if (!(property in sourceWithAliases)) delete merged[property];
+  });
+  return merged;
+}
+
+/**
+ * Companion to `refreshedComputedStyles` for the same undo/redo/remote-sync
+ * resync path — `ElementInfo.boundingRect` is otherwise left completely
+ * untouched by `refreshElementInfoFromContent` (both its node-match branch,
+ * via `canonicalElementInfoForCodeLayerNode`'s `{...info}` spread, and its
+ * DOM-parse fallback, via its own `{...info}` spread), so it keeps showing
+ * whatever rect was live-measured before the content change. `cssElementSize`
+ * falls back to `boundingRect.width`/`height` whenever computedStyles has no
+ * parseable value for that axis, so a permanently-stale boundingRect can
+ * still surface the pre-undo/redo size even after `refreshedComputedStyles`
+ * is fixed. Reuses the SAME freshly-resolved computedStyles (already merged
+ * above) so both fields agree, instead of re-deriving from a different
+ * source.
+ *
+ * Exported for unit testing.
+ */
+export function refreshedBoundingRectSize(
+  info: ElementInfo,
+  computedStyles: Record<string, string>,
+): ElementInfo["boundingRect"] {
+  const parsedWidth = parseFloat(computedStyles.width ?? "");
+  const parsedHeight = parseFloat(computedStyles.height ?? "");
+  return {
+    ...info.boundingRect,
+    width:
+      Number.isFinite(parsedWidth) && parsedWidth >= 0
+        ? parsedWidth
+        : info.boundingRect.width,
+    height:
+      Number.isFinite(parsedHeight) && parsedHeight >= 0
+        ? parsedHeight
+        : info.boundingRect.height,
+  };
+}
+
+function codeLayerNodeMatchesSourceId(
+  node: CodeLayerNode,
+  sourceId: string,
+): boolean {
+  return (
+    node.id === sourceId ||
+    node.dataAttributes["data-agent-native-node-id"] === sourceId ||
+    node.dataAttributes["data-code-layer-id"] === sourceId ||
+    node.dataAttributes["data-layer-id"] === sourceId ||
+    node.dataAttributes["data-builder-id"] === sourceId ||
+    node.dataAttributes["data-loc"] === sourceId ||
+    node.attributes.id === sourceId
+  );
 }
 
 export function codeLayerNodeMatchesBridgeTarget(
@@ -363,19 +461,7 @@ export function codeLayerNodeMatchesBridgeTarget(
   selector?: string,
   sourceId?: string,
 ): boolean {
-  if (sourceId) {
-    if (node.id === sourceId) return true;
-    if (
-      node.dataAttributes["data-agent-native-node-id"] === sourceId ||
-      node.dataAttributes["data-code-layer-id"] === sourceId ||
-      node.dataAttributes["data-layer-id"] === sourceId ||
-      node.dataAttributes["data-builder-id"] === sourceId ||
-      node.dataAttributes["data-loc"] === sourceId ||
-      node.attributes.id === sourceId
-    ) {
-      return true;
-    }
-  }
+  if (sourceId && codeLayerNodeMatchesSourceId(node, sourceId)) return true;
   return codeLayerSelectorMatches(node, selector);
 }
 
@@ -384,11 +470,34 @@ export function resolveCodeLayerNodeFromBridge(
   selector?: string,
   sourceId?: string,
 ): CodeLayerNode | null {
-  return (
-    projection.nodes.find((node) =>
-      codeLayerNodeMatchesBridgeTarget(node, selector, sourceId),
-    ) ?? null
+  // 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
+  // is unique in a well-formed projection, so this branch alone can never be
+  // ambiguous. Checking it before the selector fallback also fixes a subtler
+  // pre-existing bug: the old single-pass `.find()` could match an EARLIER
+  // node purely by selector before ever reaching the correct sourceId match
+  // later in iteration order.
+  if (sourceId) {
+    const idMatch = projection.nodes.find((node) =>
+      codeLayerNodeMatchesSourceId(node, sourceId),
+    );
+    if (idMatch) return 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
+  // bridge's structural selector. Unlike an id, a generic short selector
+  // (e.g. a 2-segment "div > p" suffix path) can legitimately match several
+  // repeated list/card/row instances. The server-side resolver for the same
+  // problem (code-layer.ts's resolveTarget) explicitly refuses to resolve a
+  // 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;
+  const selectorMatches = projection.nodes.filter((node) =>
+    codeLayerSelectorMatches(node, selector),
   );
+  return selectorMatches.length === 1 ? selectorMatches[0]! : null;
 }
 
 export function collapsedElementText(value: string | null | undefined): string {
@@ -606,13 +715,15 @@ export function refreshElementInfoFromContent(
     );
   if (node) {
     const sourceInfo = elementInfoFromCodeLayerNode(node);
+    const computedStyles = refreshedComputedStyles(
+      info,
+      sourceInfo.computedStyles,
+      sourceInfo.classes,
+    );
     return {
       ...canonicalElementInfoForCodeLayerNode(info, node),
-      computedStyles: refreshedComputedStyles(
-        info,
-        sourceInfo.computedStyles,
-        sourceInfo.classes,
-      ),
+      computedStyles,
+      boundingRect: refreshedBoundingRectSize(info, computedStyles),
       textContent: sourceInfo.textContent,
       childElementCount: sourceInfo.childElementCount,
       isFlexChild: sourceInfo.isFlexChild,
@@ -626,14 +737,16 @@ export function refreshElementInfoFromContent(
     const element = queryUniqueSelector(doc, info.selector);
     if (!element) return null;
     const classes = Array.from(element.classList);
+    const computedStyles = refreshedComputedStyles(
+      info,
+      parseInlineStyleAttribute(element.getAttribute("style")),
+      classes,
+    );
     return {
       ...info,
       classes,
-      computedStyles: refreshedComputedStyles(
-        info,
-        parseInlineStyleAttribute(element.getAttribute("style")),
-        classes,
-      ),
+      computedStyles,
+      boundingRect: refreshedBoundingRectSize(info, computedStyles),
       textContent: element.textContent?.slice(0, 200) ?? info.textContent,
       childElementCount: element.children.length,
     };

package/corpus/templates/design/app/pages/design-editor/collab-sync.ts

@@ -41,3 +41,18 @@ export function resolveScreenCollabSyncTarget({
     overviewDocConnected && overviewPresenceFileId === fileId;
   return { writeLiveDoc, syncCollab: !writeLiveDoc };
 }
+
+/** A local transaction already updated the preview optimistically, and a
+ * same-content remote transaction is only an acknowledgement echo. Only a
+ * genuinely different remote snapshot should touch the live document. */
+export function shouldApplyRemotePreviewContent({
+  isLocalEdit,
+  previousContent,
+  nextContent,
+}: {
+  isLocalEdit: boolean;
+  previousContent: string | null;
+  nextContent: string;
+}): boolean {
+  return !isLocalEdit && nextContent !== previousContent;
+}

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

@@ -18,3 +18,36 @@ export function createEditorSaveOperationSource(
 
 /** Yjs origin tracked by the local undo manager. */
 export const LOCAL_EDIT_ORIGIN = `${TAB_ID}:local`;
+
+/**
+ * TIE-BREAK: decides whether polled DB content should be adopted into the
+ * live editor during the file-content reconcile effect (DesignEditor.tsx).
+ * Callers only reach this decision once BOTH of the effect's own
+ * "already reflecting this exact content" early-returns have already ruled
+ * out `dbContent` matching what's currently rendered — so every call here
+ * represents a genuine content difference.
+ *
+ * A strict `dbUpdatedAt > applied` used to be the only "is this newer"
+ * check, which silently DROPPED a real external write whenever it landed in
+ * the same millisecond as the previously-applied one (timestamp
+ * resolution) — the tie was never treated as "newer," so the second write's
+ * content just never rendered. That's only safe to fix by treating a tie as
+ * adoptable while `agentActive` is false: when the agent IS active, a tied
+ * timestamp with different content is more likely a live self-echo race
+ * (the agent's own Yjs-tracked edit still mid-flight), which the caller's
+ * `staleAgentEchoPossible` debounced recovery timer already handles
+ * separately and more carefully — forcing immediate adoption for that case
+ * too would skip the debounce and reintroduce the exact race it exists to
+ * prevent.
+ */
+export function shouldAdoptExternalReconcileContent(args: {
+  appliedUpdatedAt: string | null | undefined;
+  dbUpdatedAt: string | null | undefined;
+  agentActive: boolean;
+}): boolean {
+  const { appliedUpdatedAt, dbUpdatedAt, agentActive } = args;
+  if (!appliedUpdatedAt) return true;
+  if (!dbUpdatedAt) return false;
+  if (dbUpdatedAt > appliedUpdatedAt) return true;
+  return dbUpdatedAt === appliedUpdatedAt && !agentActive;
+}