@agent-native/core 0.163.3 → 0.164.1

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

@@ -0,0 +1,183 @@
+import { getBrowserTabId } from "@agent-native/core/client/hooks";
+import { buildSignInReturnHref } from "@agent-native/core/client/ui";
+import { buildCodeLayerProjection } from "@shared/code-layer";
+
+import type { ElementInfo } from "@/components/design/types";
+import { designSelectionStateKeysForTab } from "@/hooks/use-navigation-state";
+import type {
+  PostAuthDesignIntent,
+  RuntimeLayerSnapshot,
+} from "@/pages/design-editor/command-types";
+
+// Selection is tab-scoped (like navigation) so a second editor tab cannot
+// overwrite this tab's selection context. The global key is mirrored as a
+// fallback for CLI/external agents that do not send a browser tab id.
+export function designSelectionStateKeys(): string[] {
+  return designSelectionStateKeysForTab(getBrowserTabId());
+}
+
+export function runtimeMultiplicityForElementProvenance(
+  snapshots: Record<string, RuntimeLayerSnapshot>,
+  info: ElementInfo | null | undefined,
+): number {
+  const provenance = info?.provenance;
+  if (!provenance?.sourceFile || !provenance.line || !provenance.column) {
+    return 1;
+  }
+  let count = 0;
+  for (const snapshot of Object.values(snapshots)) {
+    const projection = buildCodeLayerProjection(snapshot.html);
+    for (const node of projection.nodes) {
+      const attrs = node.dataAttributes;
+      if (
+        attrs["data-source-file"] === provenance.sourceFile &&
+        Number(attrs["data-source-line"]) === provenance.line &&
+        Number(attrs["data-source-column"]) === provenance.column &&
+        (!provenance.component ||
+          attrs["data-component-name"] === provenance.component)
+      ) {
+        count += 1;
+      }
+    }
+  }
+  return Math.max(1, count);
+}
+
+export function buildSignInHrefForDesignIntent(
+  intent: PostAuthDesignIntent,
+): string {
+  if (typeof window === "undefined") return buildSignInReturnHref();
+  return buildSignInReturnHref({
+    returnTo: `${window.location.pathname}?intent=${encodeURIComponent(intent)}`,
+  });
+}
+
+export function buildSignInHrefForComment(): string {
+  if (typeof window === "undefined") return buildSignInReturnHref();
+  return buildSignInReturnHref({ returnTo: window.location.pathname });
+}
+
+/**
+ * True only when the incoming (intent-less) selection authoritatively refers to
+ * a different element than the committed one (sourceId match wins, else CSS
+ * selector). Returns false when identity can't be compared, so a real selection
+ * is never dropped.
+ */
+export function isSupersededSelectionEcho(
+  incoming: ElementInfo,
+  current: ElementInfo | null,
+): boolean {
+  if (!current) return false;
+  const incomingId = incoming.sourceId?.trim();
+  const currentId = current.sourceId?.trim();
+  if (incomingId && currentId) return incomingId !== currentId;
+  const incomingSelector = incoming.selector?.trim();
+  const currentSelector = current.selector?.trim();
+  if (incomingSelector && currentSelector)
+    return incomingSelector !== currentSelector;
+  return false;
+}
+
+export function describeSelectionForHost(element: ElementInfo): {
+  label: string;
+  detail: string;
+} {
+  const text = element.textContent?.trim();
+  const label =
+    element.provenance?.component ||
+    element.componentName ||
+    (text ? text.slice(0, 60) : "") ||
+    element.tagName.toLowerCase();
+  const provenance = element.provenance;
+  const sourceFile = provenance?.sourceFile
+    ? `${provenance.sourceFile}${provenance.line ? `:${provenance.line}` : ""}`
+    : null;
+  const classSelector = element.classes?.length
+    ? `${element.tagName.toLowerCase()}.${element.classes.slice(0, 2).join(".")}`
+    : null;
+  const detail =
+    sourceFile ??
+    classSelector ??
+    element.selector ??
+    element.tagName.toLowerCase();
+  return { label, detail };
+}
+
+export function reloadRunningAppPreviewFrames(): void {
+  if (typeof document === "undefined") return;
+  const frames = document.querySelectorAll<HTMLIFrameElement>(
+    "iframe[data-design-preview-iframe]",
+  );
+  for (const frame of frames) {
+    const src = frame.getAttribute("src");
+    if (!src) continue;
+    let origin: string;
+    try {
+      origin = new URL(src, window.location.href).origin;
+      // coercion-ok: an unparsable src names no container to reload.
+    } catch {
+      continue;
+    }
+    if (origin === window.location.origin) continue;
+    frame.contentWindow?.postMessage({ type: "agentNative.reload" }, origin);
+  }
+}
+
+/**
+ * A code-layer-derived ElementInfo carries authored inline styles and a zero
+ * rect, so the inspector shows 0 for anything the source does not state
+ * (hug sizing, in-flow position). Measure the live preview node instead.
+ */
+export function withMeasuredGeometry(
+  info: ElementInfo,
+  screenId?: string,
+): ElementInfo {
+  const rect = info.boundingRect;
+  if (rect && (rect.width > 0 || rect.height > 0)) return info;
+  if (typeof document === "undefined") return info;
+  const selector = info.runtimeSelector ?? info.selector;
+  if (!selector) return info;
+  // Selectors and stamped ids are per-screen, so an unscoped scan can measure
+  // identical markup on a different screen.
+  const owning = screenId
+    ? document.querySelector<HTMLIFrameElement>(
+        `iframe[data-design-preview-iframe][data-screen-iframe-id="${CSS.escape(screenId)}"]`,
+      )
+    : null;
+  const frames = owning
+    ? [owning]
+    : Array.from(
+        document.querySelectorAll<HTMLIFrameElement>(
+          "iframe[data-design-preview-iframe]",
+        ),
+      );
+  for (const frame of frames) {
+    let node: Element | null = null;
+    try {
+      node = frame.contentDocument?.querySelector(selector) ?? null;
+    } catch {
+      node = null;
+    }
+    if (!node) continue;
+    const box = node.getBoundingClientRect();
+    if (box.width <= 0 && box.height <= 0) continue;
+    const computed = frame.contentWindow?.getComputedStyle(node);
+    return {
+      ...info,
+      boundingRect: {
+        x: box.x,
+        y: box.y,
+        width: box.width,
+        height: box.height,
+      },
+      computedStyles: computed
+        ? {
+            width: computed.width,
+            height: computed.height,
+            ...info.computedStyles,
+          }
+        : info.computedStyles,
+    };
+  }
+  return info;
+}

package/corpus/templates/design/app/pages/design-editor/effects/adopt-db-file-content.ts

@@ -0,0 +1,270 @@
+import { shouldUseLiveFileContent } from "@shared/html-content";
+import { sourceContentHash } from "@shared/source-workspace";
+import type { Dispatch, RefObject, SetStateAction } from "react";
+import * as Y from "yjs";
+
+import {
+  TAB_ID,
+  shouldAdoptExternalReconcileContent,
+} from "@/pages/design-editor/editor-session";
+import type { PreviewContentReplaceResult } from "@/pages/design-editor/editor-state";
+import { previewContentReplaceNeedsRenderFallback } from "@/pages/design-editor/editor-state";
+import type { ContentHistoryChange } from "@/pages/design-editor/history";
+import type { DesignFile } from "@/pages/design-editor/types";
+
+export interface AdoptDbFileContentArgs {
+  activeFile: DesignFile;
+  agentActive: boolean;
+  clearStaleAgentCollabRecovery: () => void;
+  collabContent: string | null;
+  collabContentFileId: string | null;
+  collabContentFileIdRef: RefObject<string | null>;
+  collabContentRef: RefObject<string | null>;
+  documentFileContentRef: RefObject<string | null>;
+  documentFileUpdatedAtRef: RefObject<string | null>;
+  isLeadClient: boolean;
+  isSynced: boolean;
+  lastAckedFileContentHashRef: RefObject<Record<string, string>>;
+  lastAppliedFileUpdatedAtRef: RefObject<string | null>;
+  lastLocalContentRef: RefObject<string | null>;
+  latestActiveContentRef: RefObject<string | null>;
+  recordExternalContentHistoryCheckpoint: (
+    change: ContentHistoryChange,
+  ) => void;
+  replacePreviewContent: (
+    nextContent: string,
+    selector?: string | null,
+    options?: { forceFullDocument?: boolean },
+  ) => PreviewContentReplaceResult;
+  setCollabContent: Dispatch<SetStateAction<string | null>>;
+  setCollabContentFileId: Dispatch<SetStateAction<string | null>>;
+  setContentRenderRevision: Dispatch<SetStateAction<number>>;
+  staleAgentCollabRecoveryTimerRef: RefObject<number | null>;
+  undoManagerRef: RefObject<Y.UndoManager | null>;
+  ydoc: Y.Doc | null;
+}
+
+export function runAdoptDbFileContent({
+  activeFile,
+  agentActive,
+  clearStaleAgentCollabRecovery,
+  collabContent,
+  collabContentFileId,
+  collabContentFileIdRef,
+  collabContentRef,
+  documentFileContentRef,
+  documentFileUpdatedAtRef,
+  isLeadClient,
+  isSynced,
+  lastAckedFileContentHashRef,
+  lastAppliedFileUpdatedAtRef,
+  lastLocalContentRef,
+  latestActiveContentRef,
+  recordExternalContentHistoryCheckpoint,
+  replacePreviewContent,
+  setCollabContent,
+  setCollabContentFileId,
+  setContentRenderRevision,
+  staleAgentCollabRecoveryTimerRef,
+  undoManagerRef,
+  ydoc,
+}: AdoptDbFileContentArgs) {
+  if (!activeFile || !isSynced) return;
+  const dbContent = activeFile.content ?? "";
+  const dbUpdatedAt = activeFile.updatedAt ?? null;
+  const activeScopedCollabContent =
+    collabContentFileId === activeFile.id ? collabContent : null;
+  if (
+    typeof activeScopedCollabContent === "string" &&
+    !shouldUseLiveFileContent({
+      liveContent: activeScopedCollabContent,
+      storedContent: dbContent,
+      fileType: activeFile.fileType,
+    })
+  ) {
+    clearStaleAgentCollabRecovery();
+    setCollabContent(dbContent);
+    setCollabContentFileId(activeFile.id);
+    lastLocalContentRef.current = dbContent;
+    latestActiveContentRef.current = dbContent;
+    lastAckedFileContentHashRef.current[activeFile.id] =
+      sourceContentHash(dbContent);
+    if (dbUpdatedAt) lastAppliedFileUpdatedAtRef.current = dbUpdatedAt;
+    if (
+      previewContentReplaceNeedsRenderFallback(
+        replacePreviewContent(dbContent, null, {
+          forceFullDocument: true,
+        }),
+      )
+    ) {
+      setContentRenderRevision((revision) => revision + 1);
+    }
+
+    if (isLeadClient && ydoc) {
+      const ytext = ydoc.getText("content");
+      if (ytext.toString() !== dbContent) {
+        // Untracked full rewrite (agent edit / external DB content
+        // replacing a live doc that diverged) — clear the undo stack so a
+        // stale tracked delta can't be replayed against content it no
+        // longer matches (see U1: this is the primary corruption path —
+        // agent edits, motion autosave, and id-stamping all land here).
+        undoManagerRef.current?.clear(true, false);
+        ydoc.transact(() => {
+          ytext.delete(0, ytext.length);
+          ytext.insert(0, dbContent);
+        }, TAB_ID);
+      }
+    }
+    return;
+  }
+
+  // Already reflecting this exact content (our own echo or Yjs already
+  // delivered it) — just advance the watermark and stop.
+  if (
+    activeScopedCollabContent === dbContent ||
+    lastLocalContentRef.current === dbContent
+  ) {
+    if (dbUpdatedAt) lastAppliedFileUpdatedAtRef.current = dbUpdatedAt;
+    return;
+  }
+
+  // Only adopt genuinely newer content. No baseline yet (fresh file load)
+  // always adopts so a stale persisted Y.Doc can't shadow newer SQL. See
+  // shouldAdoptExternalReconcileContent's doc comment
+  // (design-editor/editor-session.ts) for the same-millisecond tie-break
+  // fix this closes: a strict `>` used to silently drop a real external
+  // write that landed in the same millisecond as the one already applied,
+  // whenever agentActive was false.
+  const applied = lastAppliedFileUpdatedAtRef.current;
+  const externalNewer = shouldAdoptExternalReconcileContent({
+    appliedUpdatedAt: applied,
+    dbUpdatedAt,
+    agentActive,
+  });
+  const staleAgentEchoPossible =
+    agentActive &&
+    !!applied &&
+    !!dbUpdatedAt &&
+    dbUpdatedAt === applied &&
+    lastLocalContentRef.current !== activeScopedCollabContent;
+  if (!externalNewer) {
+    if (staleAgentEchoPossible) {
+      if (staleAgentCollabRecoveryTimerRef.current === null) {
+        const expectedContent = dbContent;
+        const expectedUpdatedAt = dbUpdatedAt;
+        const expectedFileId = activeFile.id;
+        staleAgentCollabRecoveryTimerRef.current = window.setTimeout(() => {
+          staleAgentCollabRecoveryTimerRef.current = null;
+          const currentCollab = collabContentRef.current;
+          if (collabContentFileIdRef.current !== expectedFileId) return;
+          if (documentFileUpdatedAtRef.current !== expectedUpdatedAt) return;
+          if (documentFileContentRef.current !== expectedContent) return;
+          if (currentCollab === expectedContent) return;
+          if (lastLocalContentRef.current === currentCollab) return;
+
+          setCollabContent(expectedContent);
+          setCollabContentFileId(expectedFileId);
+          lastLocalContentRef.current = expectedContent;
+          latestActiveContentRef.current = expectedContent;
+          lastAckedFileContentHashRef.current[expectedFileId] =
+            sourceContentHash(expectedContent);
+          lastAppliedFileUpdatedAtRef.current = expectedUpdatedAt;
+          if (
+            previewContentReplaceNeedsRenderFallback(
+              replacePreviewContent(expectedContent, null, {
+                forceFullDocument: true,
+              }),
+            )
+          ) {
+            setContentRenderRevision((revision) => revision + 1);
+          }
+
+          if (isLeadClient && ydoc) {
+            const ytext = ydoc.getText("content");
+            if (ytext.toString() !== expectedContent) {
+              // Untracked full rewrite — see U1 note above.
+              undoManagerRef.current?.clear(true, false);
+              ydoc.transact(() => {
+                ytext.delete(0, ytext.length);
+                ytext.insert(0, expectedContent);
+              }, TAB_ID);
+            }
+          }
+        }, 1200);
+      }
+    } else {
+      clearStaleAgentCollabRecovery();
+    }
+    return;
+  }
+  clearStaleAgentCollabRecovery();
+
+  // U21: this whole effect exists BECAUSE the Yjs observe path (which
+  // already checkpoints agent edits into the local undo fallback, see U3
+  // above at the ytext.observe handler) can miss the update — same-tab
+  // background, a paused collab poll, or no collab session ever
+  // established for this viewer. Every branch below used to respond to
+  // that exact case by clearing the undo manager with nothing to fall back
+  // to, so Cmd+Z after an agent-driven full-content replacement that
+  // landed via THIS path had nothing left to restore — the reported
+  // "pressed cmd+z but unable to change it back", reproduced end-to-end:
+  // an `edit-design`/`update-file` write (mode=replace-file) lands purely
+  // through `writeInlineSourceFile`'s SQL write, never through the Yjs
+  // collab broadcast that the U3 checkpoint above depends on to learn
+  // `agentActive` — so gating this path on the SAME `agentActive` flag
+  // (sourced from `useCollaborativeDoc`'s Yjs `requestSource === "agent"`
+  // signal) would almost never fire here, since the very reason a change
+  // lands on THIS path instead of the Yjs-observe path is that no matching
+  // Yjs broadcast arrived to flip that flag. Unlike the Yjs-observe site
+  // (which can distinguish an agent transaction from a human peer's by
+  // origin), this path cannot reliably tell "agent" from "another human
+  // editing the same design without a live collab session" apart — but
+  // recording a local undo checkpoint either way is still correct and
+  // safe: it only affects what THIS viewer's Cmd+Z reverts to, never what
+  // gets written back to any other collaborator.
+  const previousActiveContentForCheckpoint = latestActiveContentRef.current;
+  if (
+    typeof previousActiveContentForCheckpoint === "string" &&
+    previousActiveContentForCheckpoint !== dbContent
+  ) {
+    recordExternalContentHistoryCheckpoint({
+      fileId: activeFile.id,
+      before: previousActiveContentForCheckpoint,
+      after: dbContent,
+    });
+  }
+
+  // Render the newer content immediately so the preview is never stale.
+  setCollabContent(dbContent);
+  setCollabContentFileId(activeFile.id);
+  lastLocalContentRef.current = dbContent;
+  latestActiveContentRef.current = dbContent;
+  lastAckedFileContentHashRef.current[activeFile.id] =
+    sourceContentHash(dbContent);
+  if (dbUpdatedAt) lastAppliedFileUpdatedAtRef.current = dbUpdatedAt;
+  if (
+    previewContentReplaceNeedsRenderFallback(
+      replacePreviewContent(dbContent, null, { forceFullDocument: true }),
+    )
+  ) {
+    setContentRenderRevision((revision) => revision + 1);
+  }
+
+  // Lead client mirrors it into the shared Y.Doc so other open clients
+  // receive it through Yjs and the durable collab state stays in step. The
+  // agent's update-file/generate-design already wrote the Y.Doc in-process,
+  // so in the common case this is a no-op diff; it only does real work when
+  // the Yjs update was missed (the failure this fallback exists to cover).
+  if (isLeadClient && ydoc) {
+    const ytext = ydoc.getText("content");
+    if (ytext.toString() !== dbContent) {
+      // Untracked full rewrite — see U1 note above. The view-appropriate
+      // checkpoint recorded above (U21) is what Cmd+Z now falls back to.
+      undoManagerRef.current?.clear(true, false);
+      ydoc.transact(() => {
+        ytext.delete(0, ytext.length);
+        ytext.insert(0, dbContent);
+      }, TAB_ID);
+    }
+  }
+}

package/corpus/templates/design/app/pages/design-editor/effects/mirror-selection-to-agent-chat.ts

@@ -0,0 +1,134 @@
+import {
+  removeAgentChatContextItem,
+  setAgentChatContextItem,
+} from "@agent-native/core/client/agent-chat";
+import type { CodeLayerNode } from "@shared/code-layer";
+import type { RefObject } from "react";
+
+import type { ElementInfo } from "@/components/design/types";
+import { nodeRepromptSubtreeExcerpt } from "@/lib/node-reprompt";
+import { shouldMirrorSelectedElementToAgentChat } from "@/pages/design-editor/selection-state";
+import type { DesignData, DesignFile } from "@/pages/design-editor/types";
+
+export interface MirrorSelectionToAgentChatArgs {
+  activeFile: DesignFile;
+  activeProjectionContent: string;
+  composerContextHasOurKeyRef: RefObject<boolean>;
+  design: DesignData | null;
+  id: string | undefined;
+  isSignedIn: boolean;
+  mirroredSelectionIdRef: RefObject<string | null>;
+  selectedCodeLayerNode: CodeLayerNode | null;
+  selectedElement: ElementInfo | null;
+  sentSelectionIdRef: RefObject<string | null>;
+}
+
+export function runMirrorSelectionToAgentChat({
+  activeFile,
+  activeProjectionContent,
+  composerContextHasOurKeyRef,
+  design,
+  id,
+  isSignedIn,
+  mirroredSelectionIdRef,
+  selectedCodeLayerNode,
+  selectedElement,
+  sentSelectionIdRef,
+}: MirrorSelectionToAgentChatArgs) {
+  const key = "design:selected-element";
+  if (!isSignedIn) return;
+  if (!id || !shouldMirrorSelectedElementToAgentChat(selectedElement)) {
+    mirroredSelectionIdRef.current = null;
+    sentSelectionIdRef.current = null;
+    removeAgentChatContextItem(key);
+    return;
+  }
+
+  const selectionId = `${activeFile?.id ?? ""}::${selectedElement.sourceId ?? selectedElement.selector}`;
+  if (selectionId !== mirroredSelectionIdRef.current) {
+    // A genuinely new/changed selection always (re)attaches, regardless of
+    // whether the previous one was marked sent.
+    sentSelectionIdRef.current = null;
+  } else if (
+    sentSelectionIdRef.current === selectionId ||
+    !composerContextHasOurKeyRef.current
+  ) {
+    // Same selection as before, and either it was already marked sent, or
+    // the shared store no longer carries our key (a send just cleared it,
+    // observed by the bookkeeping effect below) — stay cleared. Critically:
+    // do nothing else here, so this branch never calls
+    // setAgentChatContextItem for a selection that hasn't changed.
+    if (!composerContextHasOurKeyRef.current) {
+      sentSelectionIdRef.current = selectionId;
+    }
+    return;
+  } else {
+    // Same selection, still present in the shared store, nothing to do —
+    // avoid republishing (and thus avoid the feedback loop above) when
+    // nothing about the selection actually changed.
+    return;
+  }
+  mirroredSelectionIdRef.current = selectionId;
+
+  const labelSource =
+    selectedElement.textContent?.trim() ||
+    selectedCodeLayerNode?.layerName ||
+    selectedElement.id ||
+    selectedElement.tagName.toLowerCase();
+  const shortLabel =
+    labelSource.length > 28 ? `${labelSource.slice(0, 25)}...` : labelSource;
+  const targetNodeId =
+    selectedCodeLayerNode?.dataAttributes[
+      "data-agent-native-node-id"
+    ]?.trim() ??
+    selectedElement.sourceId ??
+    null;
+  const targetSelector =
+    selectedCodeLayerNode?.selector ?? selectedElement.selector ?? null;
+  // Excerpt the outerHTML out of the SOURCE projection rather than the
+  // rendered DOM: this is the exact text edit-design's search/replace has
+  // to match, so an edit anchored to it cannot drift onto a child or
+  // sibling that merely measures the same on canvas.
+  const selectedNodeSpan = selectedCodeLayerNode?.source;
+  const outerHtmlExcerpt = selectedNodeSpan
+    ? nodeRepromptSubtreeExcerpt(
+        activeProjectionContent.slice(
+          selectedNodeSpan.start,
+          selectedNodeSpan.end,
+        ),
+      )
+    : "";
+  const contextLines = [
+    `Selected design element in design "${design?.title ?? id}".`,
+    `designId: ${id}`,
+    activeFile ? `fileId: ${activeFile.id}` : "",
+    activeFile ? `Active screen: ${activeFile.filename}` : "",
+    `target: ${targetNodeId ?? targetSelector ?? "unknown"}`,
+    targetNodeId ? `targetNodeId: ${targetNodeId}` : "",
+    targetSelector ? `targetSelector: ${targetSelector}` : "",
+    `Element: <${selectedElement.tagName.toLowerCase()}> ${shortLabel}`,
+    selectedCodeLayerNode ? `Code layer id: ${selectedCodeLayerNode.id}` : "",
+    selectedElement.classes.length
+      ? `Classes: ${selectedElement.classes.join(" ")}`
+      : "",
+    selectedElement.textContent?.trim()
+      ? `Text: ${selectedElement.textContent.trim()}`
+      : "",
+    outerHtmlExcerpt
+      ? `--- selected element (outerHTML excerpt, truncated) ---\n${outerHtmlExcerpt}`
+      : "",
+  ].filter(Boolean);
+
+  setAgentChatContextItem({
+    key,
+    title: shortLabel,
+    context: contextLines.join("\n"),
+    openSidebar: false,
+    // Mirror the selection into chat context without stealing focus: this
+    // effect re-fires on every selection change and on each get-design poll
+    // during an agent run, and focusing the composer here would blur (and
+    // tear down) an in-progress inline text edit on the canvas.
+    focus: false,
+  });
+  composerContextHasOurKeyRef.current = true;
+}