@agent-native/core 0.182.1 → 0.182.2-nightly-20260917225811

package/corpus/templates/design/actions/get-component-details.ts

@@ -25,7 +25,13 @@ import { z } from "zod";
 
 import { getDb, schema } from "../server/db/index.js";
 import "../server/db/index.js"; // ensure registerShareableResource runs
+import {
+  fetchLocalhostSnapshot,
+  resolveLocalhostBridgeConnection,
+  resolveLocalhostConnectionScope,
+} from "../server/lib/localhost-connection.js";
 import { resolveSourceCapabilities } from "../shared/capability-resolver.js";
+import { sanitizeMarkup } from "../shared/capture-sanitize.js";
 import { buildCodeLayerProjection } from "../shared/code-layer.js";
 import type { CodeLayerNode, CodeLayerSource } from "../shared/code-layer.js";
 import {
@@ -39,9 +45,14 @@ import {
   componentNodeIdMatches,
   extractProps,
   type ComponentInstance,
+  instanceFromNode,
 } from "../shared/component-model.js";
 import { hasCapability } from "../shared/design-source-capabilities.js";
-import { designSourceTypeFromData } from "../shared/source-mode.js";
+import { isStandaloneHttpUrl } from "../shared/html-content.js";
+import {
+  designConnectionIdFromData,
+  designSourceTypeFromData,
+} from "../shared/source-mode.js";
 
 export function canRestoreComponentMain(
   node: Pick<CodeLayerNode, "dataAttributes">,
@@ -65,6 +76,126 @@ function parseJson<T>(raw: string | null | undefined, fallback: T): T {
   }
 }
 
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return Boolean(value && typeof value === "object" && !Array.isArray(value));
+}
+
+function metadataForFile(
+  data: Record<string, unknown>,
+  fileId: string,
+): Record<string, unknown> {
+  for (const key of ["screenMetadata", "localhostScreens"]) {
+    const metadata = data[key];
+    const entry = isRecord(metadata) ? metadata[fileId] : undefined;
+    if (isRecord(entry)) return entry;
+  }
+  return {};
+}
+
+function stringValue(
+  attributes: Record<string, string>,
+  names: readonly string[],
+): string | undefined {
+  for (const name of names) {
+    const value = attributes[name]?.trim();
+    if (value) return value;
+  }
+  return undefined;
+}
+
+function positiveIntegerValue(
+  attributes: Record<string, string>,
+  names: readonly string[],
+): number | undefined {
+  const raw = stringValue(attributes, names);
+  if (!raw || !/^\d+$/.test(raw)) return undefined;
+  const value = Number(raw);
+  return Number.isSafeInteger(value) && value > 0 ? value : undefined;
+}
+
+function liveComponentNameFor(
+  node: CodeLayerNode,
+  sourceType: ReturnType<typeof designSourceTypeFromData>,
+): string | null {
+  return (
+    componentNameFor(node) ??
+    (sourceType !== "inline"
+      ? (stringValue(node.dataAttributes, ["data-component-name"]) ?? null)
+      : null)
+  );
+}
+
+function liveInstanceForNode(
+  node: CodeLayerNode,
+  name: string,
+): NonNullable<ReturnType<typeof instanceFromNode>> {
+  const existing = instanceFromNode(node);
+  if (existing) return existing;
+  const stableNodeId =
+    stringValue(node.dataAttributes, ["data-agent-native-node-id"]) ?? node.id;
+  const alpineDataRaw = node.attributes["x-data"];
+  return {
+    instanceId: stableNodeId,
+    name,
+    props: extractProps(node),
+    alpineData: typeof alpineDataRaw === "string" ? alpineDataRaw : undefined,
+    selector: node.selector,
+    nodeId: stableNodeId,
+    componentId:
+      stringValue(node.dataAttributes, [COMPONENT_ID_ATTR]) ?? undefined,
+    componentRef:
+      stringValue(node.dataAttributes, [COMPONENT_REF_ATTR]) ?? undefined,
+  };
+}
+
+function sourceLocationForNode(
+  node: CodeLayerNode,
+  indexRow:
+    | {
+        filePath?: string | null;
+        exportName?: string | null;
+      }
+    | undefined,
+  canResolveToFile: boolean,
+  componentName: string,
+) {
+  if (!canResolveToFile) return undefined;
+  const filePath =
+    stringValue(node.dataAttributes, [
+      "data-source-file",
+      "data-agent-native-source-file",
+      "data-agent-native-source-path",
+    ]) ?? indexRow?.filePath;
+  if (!filePath) return undefined;
+  const line = positiveIntegerValue(node.dataAttributes, [
+    "data-source-line",
+    "data-agent-native-source-line",
+  ]);
+  const column = positiveIntegerValue(node.dataAttributes, [
+    "data-source-column",
+    "data-agent-native-source-column",
+  ]);
+  return {
+    filePath,
+    exportName: indexRow?.exportName ?? undefined,
+    ...(line ? { line } : {}),
+    ...(column ? { column } : {}),
+    componentName:
+      stringValue(node.dataAttributes, ["data-component-name"]) ??
+      componentName,
+  };
+}
+
+export class ComponentDetailsLiveProjectionError extends Error {
+  readonly statusCode = 424;
+  readonly code = "LIVE_PROJECTION_UNAVAILABLE";
+
+  constructor(message: string) {
+    super(message);
+    this.name = "ComponentDetailsLiveProjectionError";
+  }
+}
+
 // ─── Action ───────────────────────────────────────────────────────────────────
 
 export default defineAction({
@@ -86,10 +217,36 @@ export default defineAction({
       .string()
       .optional()
       .describe("Design file id. Defaults to index.html."),
+    runtime: z
+      .object({
+        name: z.string().min(1),
+        nodeId: z.string().min(1),
+        selector: z.string().min(1),
+        props: z.array(
+          z.object({ name: z.string().min(1), value: z.string() }),
+        ),
+        literalProps: z
+          .array(z.object({ name: z.string().min(1), value: z.string() }))
+          .optional(),
+        alpineData: z.string().nullable().optional(),
+        componentId: z.string().optional(),
+        componentRef: z.string().optional(),
+        isMain: z.boolean().optional(),
+        sourceLocation: z
+          .object({
+            filePath: z.string().min(1),
+            exportName: z.string().optional(),
+          })
+          .optional(),
+      })
+      .optional()
+      .describe(
+        "Runtime component metadata from a URL-backed preview. This keeps the inspector on the live DOM projection when the SQL file stores only a route URL.",
+      ),
   }),
   readOnly: true,
   http: { method: "GET" },
-  run: async ({ designId, nodeId, fileId }) => {
+  run: async ({ designId, nodeId, fileId, runtime }) => {
     // ── Access check ────────────────────────────────────────────────────────
     const access = await resolveAccess("design", designId);
     if (!access) throw new Error("Design not found");
@@ -114,6 +271,62 @@ export default defineAction({
         ? "Prop write-back requires the bridge applyEdit capability. Preview controls remain available until source write hardening is enabled."
         : undefined;
 
+    // URL-backed files store the route URL in SQL rather than the rendered
+    // DOM. Use the accepted runtime projection for the inspector instead of
+    // pretending that URL is an HTML source document.
+    if (runtime) {
+      const [indexRow] = await db
+        .select()
+        .from(schema.componentIndex)
+        .where(
+          and(
+            eq(schema.componentIndex.designId, designId),
+            eq(schema.componentIndex.name, runtime.name),
+          ),
+        )
+        .limit(1);
+      const persistedProps = parseJson<unknown[]>(indexRow?.props, []);
+      const persistedVariants = parseJson<Record<string, string[]>>(
+        indexRow?.variants,
+        {},
+      );
+      const persistedStories = parseJson<unknown[]>(indexRow?.stories, []);
+      const instance: ComponentInstance = {
+        instanceId: runtime.nodeId,
+        name: runtime.name,
+        props: runtime.props,
+        alpineData: runtime.alpineData ?? undefined,
+        selector: runtime.selector,
+        nodeId: runtime.nodeId,
+        componentId: runtime.componentId,
+        componentRef: runtime.componentRef,
+      };
+      return {
+        designId,
+        nodeId,
+        sourceType,
+        instance,
+        name: runtime.name,
+        isMain:
+          runtime.isMain ??
+          Boolean(runtime.componentId && !runtime.componentRef),
+        canRestore: false,
+        observedProps: runtime.props,
+        literalProps: runtime.literalProps,
+        persistedProps,
+        persistedVariants,
+        persistedStories,
+        sourceLocation: runtime.sourceLocation,
+        capabilities: {
+          canResolveToFile,
+          hasFullIndex,
+          canEditProps,
+          ctaRequired,
+          ctaMessage,
+        },
+      };
+    }
+
     // ── Fetch design file ────────────────────────────────────────────────────
     const conditions = [
       accessFilter(schema.designs, schema.designShares, undefined, "viewer", {
@@ -131,6 +344,7 @@ export default defineAction({
         designId: schema.designFiles.designId,
         filename: schema.designFiles.filename,
         content: schema.designFiles.content,
+        data: schema.designs.data,
       })
       .from(schema.designFiles)
       .innerJoin(
@@ -142,11 +356,51 @@ export default defineAction({
 
     if (!file) throw new Error("Design HTML file not found.");
 
-    // Use the durable SQL source for component prop reads. A connected editor
-    // can briefly hold an older Yjs text snapshot while server-side prop writes
-    // have already updated SQL; preferring collab here makes the inspector
-    // rehydrate stale props even though the canvas renders the saved source.
-    const html = file.content ?? "";
+    // Inline screens use durable SQL. URL-backed screens must be projected from
+    // the live bridge because the stored value is only a route URL.
+    let html = file.content ?? "";
+    if (isStandaloneHttpUrl(html)) {
+      if (sourceType !== "localhost") {
+        throw new ComponentDetailsLiveProjectionError(
+          `Component details for URL-backed screen "${file.filename}" require a localhost bridge snapshot; source type "${sourceType}" has no live component mapping.`,
+        );
+      }
+      const designData = parseJson<Record<string, unknown>>(file.data, {});
+      const metadata = metadataForFile(designData, file.id);
+      const connectionId =
+        (typeof metadata.connectionId === "string" &&
+          metadata.connectionId.trim()) ||
+        designConnectionIdFromData(designData);
+      if (!connectionId) {
+        throw new ComponentDetailsLiveProjectionError(
+          `URL-backed screen "${file.filename}" has no localhost connection metadata. Reopen visual edit or reconnect the localhost app before requesting component details.`,
+        );
+      }
+      const { ownerEmail, orgId } = await resolveLocalhostConnectionScope({
+        designId,
+      });
+      const connection = await resolveLocalhostBridgeConnection({
+        connectionId,
+        ownerEmail,
+        orgId,
+      });
+      const previewToken =
+        typeof metadata.previewToken === "string"
+          ? metadata.previewToken
+          : null;
+      html = sanitizeMarkup(
+        await fetchLocalhostSnapshot({
+          bridgeUrl: connection.bridgeUrl,
+          previewToken,
+          url: html,
+        }),
+      ).trim();
+      if (!html) {
+        throw new ComponentDetailsLiveProjectionError(
+          `The localhost bridge returned an empty snapshot for "${file.filename}". Reload the live frame and retry.`,
+        );
+      }
+    }
 
     // ── Projection lookup ────────────────────────────────────────────────────
     const codeLayerSource: CodeLayerSource = {
@@ -169,28 +423,16 @@ export default defineAction({
       );
     }
 
-    const name = componentNameFor(node);
+    const name = liveComponentNameFor(node, sourceType);
     if (!name) {
       throw new Error(
-        `Node "${nodeId}" does not carry a data-agent-native-component attribute and is not a component root.`,
+        `Node "${nodeId}" does not carry component provenance and is not a component root.`,
       );
     }
 
     // ── Simple props from attributes ─────────────────────────────────────────
     const observedProps = extractProps(node);
-    const alpineData =
-      typeof node.attributes["x-data"] === "string"
-        ? node.attributes["x-data"]
-        : undefined;
-
-    const instance: ComponentInstance = {
-      instanceId: node.id,
-      name,
-      props: observedProps,
-      alpineData,
-      selector: node.selector,
-      nodeId,
-    };
+    const instance = liveInstanceForNode(node, name);
 
     // ── Lookup persisted component_index row ─────────────────────────────────
     const [indexRow] = await db
@@ -212,17 +454,14 @@ export default defineAction({
     const persistedStories = parseJson<unknown[]>(indexRow?.stories, []);
 
     // ── Source location (real-app only) ──────────────────────────────────────
-    // The bridge `resolveNodeToFile` op maps a node id to a source file + span.
-    // For inline designs the capability is `available` but resolves to the
-    // design file itself (no external source file).  We surface whatever we
-    // have from the index row.
-    const sourceLocation =
-      canResolveToFile && indexRow?.filePath
-        ? {
-            filePath: indexRow.filePath,
-            exportName: indexRow.exportName ?? undefined,
-          }
-        : undefined;
+    // Live bridge provenance is preferred; indexed metadata remains the
+    // fallback when the bridge did not stamp a source span.
+    const sourceLocation = sourceLocationForNode(
+      node,
+      indexRow,
+      canResolveToFile,
+      name,
+    );
 
     return {
       designId,

package/corpus/templates/design/actions/get-design-version.ts

@@ -28,6 +28,9 @@ function parseChatContext(raw: string | null): DesignVersionChatContext | null {
       context[key] = candidate;
     }
   }
+  if ((value as { surface?: unknown }).surface === "editor") {
+    context.surface = "editor";
+  }
   return Object.keys(context).length > 0 ? context : null;
 }
 
@@ -77,7 +80,12 @@ export default defineAction({
       designId,
       label: version.label,
       createdAt: version.createdAt,
-      source: chatContext ? ("chat" as const) : ("legacy" as const),
+      source:
+        chatContext?.surface === "editor"
+          ? ("editor" as const)
+          : chatContext
+            ? ("chat" as const)
+            : ("legacy" as const),
       fileCount: version.fileCount ?? snapshot.files.length,
       chatContext,
       designTitle: snapshot.designTitle ?? null,

package/corpus/templates/design/actions/go-to-main-component.ts

@@ -1,26 +1,9 @@
 /**
  * go-to-main-component — Figma's "Go to main component".
  *
- * DESIGN NOTE — mapping onto this codebase's data model: there is no
- * persisted "main component" concept anywhere here. A component is just a
- * name (`data-agent-native-component="Name"`) that happens to be stamped on
- * more than one element; every instance is an independently-duplicated copy
- * of HTML (see `shared/component-model.ts`, `component_index` schema — it
- * stores props/variants/runtime-selectors metadata, never a canonical
- * definition). A true "main component" would require a data-model addition
- * (e.g. an `isMain`/definition pointer on `component_index`) — out of scope
- * here; flagged for a follow-up if promoting a specific instance as
- * authoritative becomes a real need.
- *
- * Closest tractable equivalent: treat the EARLIEST instance of the same
- * component name — scanning every design file in `createdAt` order, document
- * order within each file — as the "main" analogue, mirroring the common case
- * where a component's original occurrence predates its copies. If the given
- * instance already IS that earliest one, this returns `isMain: true` instead
- * of navigating (nothing to jump to). Otherwise it writes a `navigate`
- * app-state command (same mechanism as `navigate` / `open-component-source`)
- * so the editor selects the target instance, including switching design
- * files when the main instance lives on a different screen.
+ * A canonical linked component has a persisted opaque id on its main root and
+ * references. Resolve that id first. Legacy name-only annotations still use
+ * the earliest same-name instance as their compatibility fallback.
  *
  * Navigation-only + inline/Alpine designs only (real-app sources return a
  * CTA). Because this writes the transient `navigate` application-state
@@ -43,6 +26,8 @@ import {
   scanComponentLibrary,
 } from "../shared/component-library.js";
 import {
+  COMPONENT_ID_ATTR,
+  COMPONENT_REF_ATTR,
   componentNameFor,
   componentNodeIdMatches,
 } from "../shared/component-model.js";
@@ -66,12 +51,11 @@ async function liveContent(
 export default defineAction({
   description:
     "Resolve the 'main' instance of a component (Figma's Go to main " +
-    "component). This codebase has no separate component-definition markup " +
-    "— components are structurally duplicated HTML matched by name — so the " +
-    "earliest instance found across the design's files stands in for the " +
-    "main component. Returns isMain=true when the given instance already IS " +
-    "that earliest one; otherwise navigates the editor to it (which may " +
-    "switch design files).",
+    "component). Canonical linked components resolve by their persisted " +
+    "component id; legacy name-only annotations fall back to the earliest " +
+    "same-name instance across the design's files. Returns isMain=true when " +
+    "the selected instance is already the main; otherwise navigates the " +
+    "editor to it.",
   schema: z.object({
     designId: z.string().describe("Design project ID"),
     nodeId: z
@@ -154,9 +138,12 @@ export default defineAction({
     }
 
     const componentName = componentNameFor(node);
-    if (!componentName) {
+    const componentId =
+      node.dataAttributes[COMPONENT_ID_ATTR]?.trim() ||
+      node.dataAttributes[COMPONENT_REF_ATTR]?.trim();
+    if (!componentName && !componentId) {
       throw new Error(
-        `Node "${nodeId}" is not a component root (no data-agent-native-component attribute).`,
+        `Node "${nodeId}" is not a component root (no component name or linked identity).`,
       );
     }
 
@@ -190,16 +177,31 @@ export default defineAction({
     );
 
     const entries = scanComponentLibrary(filesForScan);
-    const matches = entriesForComponent(entries, componentName);
+    const matches = componentId
+      ? entries.filter(
+          (entry) =>
+            entry.componentId === componentId ||
+            entry.componentRef === componentId,
+        )
+      : entriesForComponent(entries, componentName!);
 
     if (matches.length === 0) {
       // Shouldn't happen (the current node itself matches), but guard anyway.
       throw new Error(
-        `No instances of component "${componentName}" found across the design's files.`,
+        `No instances of component "${componentName ?? componentId}" found across the design's files.`,
+      );
+    }
+    const resolvedComponentName = componentName ?? matches[0]?.name;
+    if (!resolvedComponentName) {
+      throw new Error(
+        `Component identity "${componentId}" has no named canonical root.`,
       );
     }
 
-    const main = matches[0];
+    const main = componentId
+      ? (matches.find((entry) => entry.componentId === componentId) ??
+        matches[0])
+      : matches[0];
     // Compare against the caller's own stable `nodeId` param (a durable
     // data-agent-native-node-id), not `node.id` (an ephemeral id scoped to
     // this projection call) — `scanComponentLibrary` resolves the same
@@ -210,7 +212,7 @@ export default defineAction({
       return {
         designId,
         nodeId,
-        componentName,
+        componentName: resolvedComponentName,
         sourceType,
         ctaRequired: false,
         isMain: true,
@@ -218,8 +220,8 @@ export default defineAction({
         navigated: false,
         note:
           matches.length === 1
-            ? `"${componentName}" has only one instance — this is it.`
-            : `This is the earliest instance of "${componentName}" across the design.`,
+            ? `"${resolvedComponentName}" has only one instance — this is it.`
+            : `This is the earliest instance of "${resolvedComponentName}" across the design.`,
       };
     }
 
@@ -237,7 +239,7 @@ export default defineAction({
     return {
       designId,
       nodeId,
-      componentName,
+      componentName: resolvedComponentName,
       sourceType,
       ctaRequired: false,
       isMain: false,