@agent-native/core 0.92.10 → 0.92.12

package/corpus/templates/design/actions/import-figma-clipboard.ts

@@ -0,0 +1,134 @@
+import { defineAction } from "@agent-native/core";
+import { z } from "zod";
+
+import {
+  buildFigmaNodeCandidates,
+  extractVisibleTexts,
+  matchFigmaClipboardNodes,
+} from "../server/lib/figma-clipboard-match.js";
+import {
+  buildScreenFilesFromFigmaNodes,
+  fetchFileStructure,
+  fetchFigmaNodes,
+  summarizeFidelity,
+} from "../server/lib/figma-node-import.js";
+import { saveFigmaPasteHtmlFallback } from "../server/lib/figma-paste-fallback.js";
+import { saveImportedDesignFiles } from "../server/lib/import-design-files.js";
+import { parseVisibleClipboardHtml } from "../server/lib/visible-clipboard-html.js";
+import { parseFigmaFileKey } from "../shared/figma-url.js";
+
+const NODE_STRUCTURE_DEPTH = 3;
+
+const CREDENTIAL_MISSING_RE = /credential not configured/i;
+
+const AMBIGUOUS_GUIDANCE =
+  'Couldn\'t confidently match this paste to specific Figma nodes, so nothing was imported from the API. Paste a frame LINK instead (copy the frame in Figma, then "Copy link to selection") for an exact node import — or continue with the clipboard preview below.';
+
+const KEY_MISSING_GUIDANCE =
+  "Connect your Figma access token (Settings > Secrets > Figma access token) to import this paste as exact, editable Figma nodes. Imported from the clipboard preview instead.";
+
+export default defineAction({
+  description:
+    "Import a plain clipboard paste copied from Figma (Cmd+C in Figma, Cmd+V here). Figma's clipboard marker only carries a file key, not node ids, so this heuristically matches the pasted content against the file's top-level frames by name/text and imports exact REST nodes only on a confident match; otherwise it falls back to the lossy visible-HTML preview and reports why. For a guaranteed exact import, use import-figma-frame with a copied frame LINK (which does carry a node id) instead.",
+  schema: z.object({
+    designId: z
+      .string()
+      .optional()
+      .describe("Design id. Defaults to the active editor navigation state."),
+    figmetaFileKey: z
+      .string()
+      .trim()
+      .min(1)
+      .describe(
+        "The fileKey decoded from the clipboard's figmeta marker (see app/lib/figma-clipboard.ts's extractFigmeta).",
+      ),
+    clipboardHtml: z
+      .string()
+      .describe(
+        "The raw clipboard HTML (still containing the hidden figmeta/figbuffer markers) — used both for the legacy visible-HTML fallback and for node-matching against visible text.",
+      ),
+    originalName: z.string().optional(),
+  }),
+  run: async ({ designId, figmetaFileKey, clipboardHtml, originalName }) => {
+    const fileKey = parseFigmaFileKey(figmetaFileKey);
+    if (!fileKey) {
+      throw new Error("The clipboard's Figma file key could not be parsed.");
+    }
+
+    // Legacy fallback text is needed either way: as the actual save payload
+    // when we fall back, and as the "visible text" signal the matcher scores
+    // candidate frames against.
+    const parsedClipboard = parseVisibleClipboardHtml(clipboardHtml);
+    if (!parsedClipboard.fallbackHtml) {
+      throw new Error(
+        "No visible HTML was found in the clipboard. Copy a frame, then paste into the canvas.",
+      );
+    }
+    const clipboardTexts = extractVisibleTexts(parsedClipboard.fallbackHtml);
+
+    let figmaApiKeyMissing = false;
+    let matchStatus: "matched" | "ambiguous" | "none" | "error" = "error";
+
+    try {
+      const document = await fetchFileStructure(fileKey, NODE_STRUCTURE_DEPTH);
+      const candidates = buildFigmaNodeCandidates(document);
+      const matchResult = matchFigmaClipboardNodes(candidates, clipboardTexts);
+      matchStatus = matchResult.status;
+
+      if (matchResult.status === "matched") {
+        const nodeIds = matchResult.matches.map((match) => match.id);
+        const nodesById = await fetchFigmaNodes(fileKey, nodeIds);
+        const { files, fidelityEntries } = await buildScreenFilesFromFigmaNodes(
+          fileKey,
+          nodesById,
+        );
+        const saved = await saveImportedDesignFiles({
+          designId,
+          sourceType: "figma-clipboard-rest",
+          files,
+        });
+        return {
+          ...saved,
+          strategy: "restNodes" as const,
+          figma: {
+            fileKey,
+            nodeIds,
+            matched: matchResult.matches,
+          },
+          fidelityReport: summarizeFidelity(fidelityEntries),
+          guidance:
+            "Review fidelityReport.imageFallbacks for subtrees rendered as PNG and fidelityReport.approximated for properties CSS cannot express exactly.",
+        };
+      }
+    } catch (error) {
+      figmaApiKeyMissing = CREDENTIAL_MISSING_RE.test(
+        error instanceof Error ? error.message : String(error),
+      );
+      if (!figmaApiKeyMissing) {
+        // A real (non-credential) REST failure — network error, revoked
+        // token, file access issue, etc. Still fall back to the honest
+        // clipboard preview rather than losing the paste entirely, but this
+        // isn't a "no confident match" case, so don't claim ambiguity.
+        matchStatus = "error";
+      }
+    }
+
+    const saved = await saveFigmaPasteHtmlFallback({
+      designId,
+      clipboardHtml,
+      originalName,
+    });
+    return {
+      ...saved,
+      strategy: "htmlFallback" as const,
+      figmaApiKeyMissing,
+      matchStatus,
+      figma: { fileKey },
+      guidance: figmaApiKeyMissing
+        ? KEY_MISSING_GUIDANCE
+        : matchStatus === "ambiguous" || matchStatus === "none"
+          ? AMBIGUOUS_GUIDANCE
+          : "Imported the clipboard's visible-HTML preview after a Figma API error. Paste a frame link for an exact import.",
+    };
+  },
+});

package/corpus/templates/design/actions/import-figma-frame.ts

@@ -0,0 +1,95 @@
+import { defineAction } from "@agent-native/core";
+import { z } from "zod";
+
+import {
+  buildScreenFilesFromFigmaNodes,
+  fetchFigmaNode,
+  resolveTargetNodeId,
+  summarizeFidelity,
+} from "../server/lib/figma-node-import.js";
+import { saveImportedDesignFiles } from "../server/lib/import-design-files.js";
+import { parseFigmaFileKey, parseFigmaNodeId } from "../shared/figma-url.js";
+
+const schemaInput = z
+  .object({
+    figmaUrl: z
+      .string()
+      .trim()
+      .optional()
+      .describe(
+        "Figma file/frame URL, e.g. https://www.figma.com/design/<fileKey>/<name>?node-id=<id>. A branch URL (/branch/<key>/) resolves to the branch's own file.",
+      ),
+    fileKey: z
+      .string()
+      .trim()
+      .optional()
+      .describe("Figma file key. Used when figmaUrl is omitted or has no key."),
+    nodeId: z
+      .string()
+      .trim()
+      .optional()
+      .describe(
+        "Figma node id (colon or dash form, e.g. '12:34' or '12-34'). Used when figmaUrl has no node-id. Defaults to the file's first top-level frame when omitted.",
+      ),
+    designId: z
+      .string()
+      .optional()
+      .describe("Design id. Defaults to the active editor navigation state."),
+    asNewScreen: z
+      .boolean()
+      .default(true)
+      .describe(
+        "Must be true today: the imported frame is always saved as a new screen. Reserved for a future 'replace existing screen' mode.",
+      ),
+  })
+  .refine((value) => value.figmaUrl || value.fileKey, {
+    message: "Pass figmaUrl or fileKey.",
+    path: ["figmaUrl"],
+  });
+
+export default defineAction({
+  description:
+    "Import a Figma frame/component by URL or file key + node id, mapping it to pixel-accurate HTML (position, auto-layout as flexbox, text, fills/gradients, strokes, corner radii, effects) and saving it as a new Design screen. Unsupported node types (vector networks, boolean ops) render as exact PNG fallbacks instead of approximated shapes. Returns a fidelity report of which properties were exact, approximated, or image-fallback. Requires the saved FIGMA_ACCESS_TOKEN secret.",
+  schema: schemaInput,
+  publicAgent: { expose: true, readOnly: false, requiresAuth: true },
+  run: async (args) => {
+    if (args.asNewScreen === false) {
+      throw new Error(
+        "asNewScreen: false is not supported yet. Omit it or pass true — the imported frame is always saved as a new screen.",
+      );
+    }
+
+    const fileKey =
+      parseFigmaFileKey(args.fileKey) ?? parseFigmaFileKey(args.figmaUrl);
+    if (!fileKey) {
+      throw new Error("Could not find a Figma file key in the provided URL.");
+    }
+    const requestedNodeId =
+      parseFigmaNodeId(args.nodeId) ?? parseFigmaNodeId(args.figmaUrl);
+
+    const nodeId = await resolveTargetNodeId(fileKey, requestedNodeId);
+    const rootNode = await fetchFigmaNode(fileKey, nodeId);
+
+    const { files, fidelityEntries } = await buildScreenFilesFromFigmaNodes(
+      fileKey,
+      { [nodeId]: rootNode },
+      {
+        source: () => ({ figmaUrl: args.figmaUrl ?? null }),
+      },
+    );
+
+    const saved = await saveImportedDesignFiles({
+      designId: args.designId,
+      sourceType: "figma-import",
+      files,
+    });
+
+    return {
+      ...saved,
+      figma: { fileKey, nodeId, nodeName: rootNode.name ?? null },
+      fidelityReport: summarizeFidelity(fidelityEntries),
+      guidance:
+        "Review fidelityReport.imageFallbacks for subtrees rendered as PNG (vector networks, boolean ops, unsupported node types) and fidelityReport.approximated for properties CSS cannot express exactly (rotation, per-side strokes, radial/angular/diamond gradients, blur radius scale).",
+    };
+  },
+});

package/corpus/templates/design/actions/index-design-system-with-builder.ts

@@ -13,8 +13,23 @@ import { upsertBuilderProxyDesignSystem } from "../server/lib/builder-design-sys
 
 const codeFileSchema = z.object({
   filename: z.string().trim().min(1).describe("File name or relative path"),
-  content: z.string().describe("Raw text content of the code/design file"),
+  content: z
+    .string()
+    .describe(
+      "File content. Text files (code, CSS, markdown, JSON, SVG): raw text. " +
+        "Binary files -- most importantly `.fig` (a zip/kiwi binary container, " +
+        'never valid text) -- MUST be base64-encoded with encoding: "base64"; ' +
+        "sending raw/binary-as-string content with the default utf8 encoding " +
+        "corrupts the file before it reaches Builder.",
+    ),
   mimeType: z.string().trim().optional().describe("Optional MIME type"),
+  encoding: z
+    .enum(["utf8", "base64"])
+    .optional()
+    .describe(
+      "Encoding of `content`. Defaults to utf8. Set to base64 for `.fig` and " +
+        "other binary files.",
+    ),
 });
 
 export default defineAction({

package/corpus/templates/design/actions/list-design-components.ts

@@ -0,0 +1,104 @@
+/**
+ * list-design-components — read action.
+ *
+ * Scans every HTML file in a design for `data-agent-native-component`
+ * annotations and returns one summary row per distinct component name
+ * (instance count + a representative instance to preview/source from).
+ *
+ * Unlike `index-components` (which only scans one file at a time and persists
+ * metadata into `component_index`), this action is a lightweight, read-only,
+ * cross-file scan purpose-built for the Swap Instance component picker — the
+ * caller needs to know every component name that exists ANYWHERE in the
+ * design, not just on the active screen.
+ *
+ * Inline/Alpine designs only; real-app sources return an empty list with a
+ * CTA (matches `index-components`' real-app posture).
+ */
+
+import { defineAction } from "@agent-native/core/action";
+import { accessFilter, resolveAccess } from "@agent-native/core/sharing";
+import { and, eq } from "drizzle-orm";
+import { z } from "zod";
+
+import { getDb, schema } from "../server/db/index.js";
+import "../server/db/index.js"; // ensure registerShareableResource runs
+import {
+  scanComponentLibrary,
+  summarizeComponentLibrary,
+} from "../shared/component-library.js";
+import { designSourceTypeFromData } from "../shared/source-mode.js";
+
+export default defineAction({
+  description:
+    "List every distinct component (by data-agent-native-component name) " +
+    "found across ALL html files in a design, with instance counts, for the " +
+    "Swap Instance component picker. Inline/Alpine designs only.",
+  schema: z.object({
+    designId: z.string().describe("Design project ID"),
+    excludeName: z
+      .string()
+      .optional()
+      .describe(
+        "Component name to omit from the results, e.g. the currently " +
+          "selected instance's own component so it isn't offered as a swap target.",
+      ),
+  }),
+  readOnly: true,
+  http: { method: "GET" },
+  run: async ({ designId, excludeName }) => {
+    const access = await resolveAccess("design", designId);
+    if (!access) throw new Error("Design not found");
+
+    const rawData = (access.resource as { data?: unknown }).data;
+    const sourceType = designSourceTypeFromData(rawData);
+
+    if (sourceType !== "inline") {
+      return {
+        designId,
+        sourceType,
+        ctaRequired: true,
+        ctaMessage:
+          "Listing components across the design library requires a " +
+          "connected Builder app for real-app sources. Not yet available.",
+        components: [],
+        totalComponents: 0,
+      };
+    }
+
+    const db = getDb();
+
+    const files = await db
+      .select({
+        id: schema.designFiles.id,
+        designId: schema.designFiles.designId,
+        filename: schema.designFiles.filename,
+        content: schema.designFiles.content,
+      })
+      .from(schema.designFiles)
+      .innerJoin(
+        schema.designs,
+        eq(schema.designFiles.designId, schema.designs.id),
+      )
+      .where(
+        and(
+          accessFilter(schema.designs, schema.designShares),
+          eq(schema.designFiles.designId, designId),
+          eq(schema.designFiles.fileType, "html"),
+        ),
+      )
+      .orderBy(schema.designFiles.createdAt);
+
+    const entries = scanComponentLibrary(files);
+    const components = summarizeComponentLibrary(entries).filter(
+      (component) => component.name !== excludeName,
+    );
+
+    return {
+      designId,
+      sourceType,
+      ctaRequired: false,
+      components,
+      totalComponents: components.length,
+    };
+  },
+});

package/corpus/templates/design/actions/list-figma-library-assets.ts

@@ -2,8 +2,7 @@ import { defineAction } from "@agent-native/core";
 import { z } from "zod";
 
 import { executeProviderApiRequest } from "../server/lib/provider-api.js";
-
-const FIGMA_FILE_KEY_RE = /^[A-Za-z0-9_-]{8,}$/;
+import { parseFigmaFileKey } from "../shared/figma-url.js";
 
 const FigmaRenderFormatSchema = z.enum(["svg", "png"]).default("svg");
 
@@ -79,28 +78,6 @@ function numberOrDefault(value: number | undefined, fallback: number): number {
   return typeof value === "number" && Number.isFinite(value) ? value : fallback;
 }
 
-export function parseFigmaFileKey(input: string | undefined): string | null {
-  const value = input?.trim();
-  if (!value) return null;
-  if (FIGMA_FILE_KEY_RE.test(value)) return value;
-
-  try {
-    const url = new URL(value);
-    const parts = url.pathname.split("/").filter(Boolean);
-    for (const segment of ["design", "file", "proto"]) {
-      const index = parts.indexOf(segment);
-      if (index >= 0) {
-        const candidate = parts[index + 1];
-        if (candidate && FIGMA_FILE_KEY_RE.test(candidate)) return candidate;
-      }
-    }
-  } catch {
-    return null;
-  }
-
-  return null;
-}
-
 function figmaNodeUrl(
   fileKey: string,
   nodeId: string,

package/corpus/templates/design/actions/open-component-source.ts

@@ -18,8 +18,8 @@
  * to open.
  *
  * Navigation is written via `writeAppState("navigate", ...)` — the same
- * mechanism used by the `navigate` action — so the caller can trigger UI
- * navigation without a round-trip.
+ * mechanism used by the `navigate` action. Because this writes transient
+ * application state, the action uses the default POST mutation transport.
  *
  * See DESIGN-STUDIO-PLAN.md §6.1 (jump-to-source) and §7 (action surface).
  */
@@ -80,8 +80,6 @@ export default defineAction({
       .optional()
       .describe("Design file id; defaults to index.html"),
   }),
-  readOnly: true,
-  http: { method: "GET" },
   run: async ({ designId, nodeId, fileId }) => {
     const db = getDb();