@agent-native/core 0.92.11 → 0.93.0

package/corpus/templates/design/actions/get-figma-connection-status.ts

@@ -0,0 +1,26 @@
+import { defineAction } from "@agent-native/core";
+import { resolveSecret } from "@agent-native/core/server";
+import { z } from "zod";
+
+const FIGMA_ACCESS_TOKEN_KEY = "FIGMA_ACCESS_TOKEN";
+
+/**
+ * Return only whether the current authenticated request can use Figma.
+ *
+ * The registered-secrets endpoint intentionally reports user-vault metadata
+ * only. Local and single-tenant Design runtimes may instead provide a managed
+ * credential, so the import UI needs a request-scoped availability check that
+ * follows the exact same resolver as the importer without returning the
+ * credential, its suffix, or its source.
+ */
+export default defineAction({
+  description:
+    "Check whether this authenticated Design session can use the Figma API without returning credential values or metadata.",
+  schema: z.object({}),
+  http: { method: "GET" },
+  readOnly: true,
+  agentTool: false,
+  run: async () => ({
+    available: Boolean(await resolveSecret(FIGMA_ACCESS_TOKEN_KEY)),
+  }),
+});

package/corpus/templates/design/actions/get-figma-design-context.ts

@@ -0,0 +1,138 @@
+import { defineAction } from "@agent-native/core";
+import { z } from "zod";
+
+import {
+  fetchFigmaRenderUrl,
+  summarizeFigmaNode,
+} from "../server/lib/figma-design-context.js";
+import {
+  fetchFigmaNode,
+  fetchFileStructure,
+  type FigmaFileDepthNode,
+} from "../server/lib/figma-node-import.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>.",
+      ),
+    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). Used when figmaUrl has no node-id. " +
+          "Omit both to get an overview of the file's pages and top-level frames first.",
+      ),
+    depth: z.coerce
+      .number()
+      .int()
+      .min(1)
+      .max(10)
+      .default(4)
+      .describe(
+        "How many levels of children to expand below the requested node before truncating (only applies when nodeId is resolved).",
+      ),
+    maxNodes: z.coerce
+      .number()
+      .int()
+      .min(10)
+      .max(1000)
+      .default(300)
+      .describe(
+        "Safety cap on total nodes summarized, to bound response size.",
+      ),
+    includeScreenshot: z
+      .boolean()
+      .default(true)
+      .describe(
+        "Also fetch a rendered screenshot URL for the requested node via the Figma images REST endpoint.",
+      ),
+    screenshotFormat: z.enum(["png", "svg"]).default("png"),
+  })
+  .refine((value) => value.figmaUrl || value.fileKey, {
+    message: "Pass figmaUrl or fileKey.",
+    path: ["figmaUrl"],
+  });
+
+function summarizeStructure(document: FigmaFileDepthNode) {
+  return (document.children ?? []).map((page) => ({
+    id: page.id,
+    name: page.name,
+    type: page.type,
+    frames: (page.children ?? []).map((frame) => ({
+      id: frame.id,
+      name: frame.name,
+      type: frame.type,
+      childCount: frame.children?.length ?? 0,
+    })),
+  }));
+}
+
+export default defineAction({
+  description:
+    "Answer 'what's in this Figma file/frame?' with a compact, LLM-friendly structural summary — the chat equivalent of the official Figma MCP's get_metadata + get_design_context (read-only, no screen is created; use import-figma-frame to actually bring a frame into Design as an editable screen). Pass only figmaUrl/fileKey to get an overview of the file's pages and top-level frames (like get_metadata with no node id); pass a nodeId (or a node-id link) to get a depth-limited node tree with box geometry, fills/strokes/effects/corner-radii, auto-layout, text/style, and (by default) a rendered screenshot URL for that node. Requires the saved FIGMA_ACCESS_TOKEN secret.",
+  schema: schemaInput,
+  http: { method: "GET" },
+  readOnly: true,
+  publicAgent: { expose: true, readOnly: true, requiresAuth: true },
+  run: async (args) => {
+    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 nodeId =
+      parseFigmaNodeId(args.nodeId) ?? parseFigmaNodeId(args.figmaUrl);
+
+    if (!nodeId) {
+      const document = await fetchFileStructure(fileKey, 3);
+      const pages = summarizeStructure(document);
+      return {
+        source: "figma",
+        fileKey,
+        mode: "overview" as const,
+        pages,
+        guidance:
+          "No nodeId was given, so this lists the file's pages and top-level frames only (mirrors the official Figma MCP's get_metadata with no node id). Call get-figma-design-context again with one of these frame ids (or a node-id link) for a full structural summary and screenshot of that frame.",
+      };
+    }
+
+    const node = await fetchFigmaNode(fileKey, nodeId);
+    const {
+      node: summary,
+      nodeCount,
+      truncated,
+    } = summarizeFigmaNode(node, {
+      maxDepth: args.depth,
+      maxNodes: args.maxNodes,
+    });
+    const screenshotUrl = args.includeScreenshot
+      ? await fetchFigmaRenderUrl(fileKey, nodeId, args.screenshotFormat)
+      : null;
+
+    return {
+      source: "figma",
+      fileKey,
+      nodeId,
+      mode: "node" as const,
+      nodeCount,
+      truncated,
+      summary,
+      screenshotUrl,
+      guidance: truncated
+        ? "This tree was truncated by depth or node-count limits (see truncatedDepth/truncatedChildren on individual nodes). Re-run with a larger depth/maxNodes, or target a nested nodeId directly, to see more. To bring this frame into Design as a real editable screen, use import-figma-frame instead of hand-reconstructing it from this summary."
+        : "To bring this frame into Design as a real editable screen (not just this summary), use import-figma-frame.",
+    };
+  },
+});

package/corpus/templates/design/actions/get-figma-styles.ts

@@ -61,7 +61,7 @@ function providerJson(envelope: unknown, label: string): unknown {
 
 export default defineAction({
   description:
-    "Summarize a Figma file's published styles (fill/text/effect/grid) by name, description, and node id. This is the file's Styles panel, NOT the Enterprise Variables API — full design-token extraction (including variables/collections) routes through index-design-system-with-builder or import-file --format fig. Requires the saved FIGMA_ACCESS_TOKEN secret.",
+    "Summarize a Figma file's published styles (fill/text/effect/grid) by name, description, and node id. This is the file's Styles panel, NOT the Enterprise Variables API — reusable design-system extraction routes through index-design-system-with-builder or the Design System Setup .fig upload. Requires the saved FIGMA_ACCESS_TOKEN secret.",
   schema: schemaInput,
   http: { method: "GET" },
   readOnly: true,
@@ -109,7 +109,7 @@ export default defineAction({
       byType,
       styles,
       guidance:
-        "These are the file's published FILL/TEXT/EFFECT/GRID styles (name, description, node id), not the Enterprise Variables API. For full design-system token extraction (variables, collections, modes) use index-design-system-with-builder or import-file --format fig instead of hand-mapping these style records.",
+        "These are the file's published FILL/TEXT/EFFECT/GRID styles (name, description, node id), not the Enterprise Variables API. For reusable design-system extraction use index-design-system-with-builder or the Design System Setup .fig upload instead of hand-mapping these style records.",
     };
   },
 });

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

@@ -20,16 +20,20 @@ import { parseFigmaFileKey } from "../shared/figma-url.js";
 const NODE_STRUCTURE_DEPTH = 3;
 
 const CREDENTIAL_MISSING_RE = /credential not configured/i;
+const DURABLE_STORAGE_REQUIRED_RE =
+  /authenticated user so assets can be stored durably|could not store a Figma image durably|needs durable file storage/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.";
+  "Connect your Figma access token (Settings > Connections > Figma access token) to import this paste as exact, editable Figma nodes.";
+const SELECTION_TRUNCATED_GUIDANCE =
+  "Figma copied more than 100 selected nodes. Imported the first 100; split larger selections into smaller pastes so every layer is included.";
 
 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.",
+    "Import a clipboard paste copied from Figma (Cmd+C in Figma, Cmd+V here). Current Figma clients include exact selected node ids in the figmeta marker, so those nodes are fetched directly through the Figma REST API. Older or changed clipboard formats fall back to a conservative name/text match, then to any visible HTML preview. A saved FIGMA_ACCESS_TOKEN is required for REST import; a copied frame link remains the stable public-contract path.",
   schema: z.object({
     designId: z
       .string()
@@ -42,34 +46,94 @@ export default defineAction({
       .describe(
         "The fileKey decoded from the clipboard's figmeta marker (see app/lib/figma-clipboard.ts's extractFigmeta).",
       ),
+    selectedNodeIds: z
+      .array(
+        z
+          .string()
+          .max(64)
+          .regex(/^\d+:\d+$/),
+      )
+      .max(100)
+      .optional()
+      .describe(
+        "Exact selected node ids decoded from Figma's current selectedNodeData clipboard field. Omit for older clipboard formats.",
+      ),
+    selectedNodeIdsTruncated: z
+      .boolean()
+      .optional()
+      .describe(
+        "True when the client capped a Figma clipboard selection to the first 100 exact node ids.",
+      ),
     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.",
+        "Figma clipboard HTML used for fallback matching. When exact node ids are present, the client removes the large private data-buffer while retaining figmeta and visible HTML.",
       ),
     originalName: z.string().optional(),
   }),
-  run: async ({ designId, figmetaFileKey, clipboardHtml, originalName }) => {
+  run: async ({
+    designId,
+    figmetaFileKey,
+    selectedNodeIds,
+    selectedNodeIdsTruncated,
+    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.
+    // Current Figma clipboard HTML commonly contains only figmeta + the
+    // private binary figma buffer, with no visible HTML at all. Exact REST ids
+    // must therefore run before requiring the legacy preview/matching signal.
     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);
+    const clipboardTexts = parsedClipboard.fallbackHtml
+      ? extractVisibleTexts(parsedClipboard.fallbackHtml)
+      : [];
 
     let figmaApiKeyMissing = false;
     let matchStatus: "matched" | "ambiguous" | "none" | "error" = "error";
 
     try {
+      if (selectedNodeIds?.length) {
+        const nodesById = await fetchFigmaNodes(fileKey, selectedNodeIds);
+        const { files, fidelityEntries } = await buildScreenFilesFromFigmaNodes(
+          fileKey,
+          nodesById,
+        );
+        const saved = await saveImportedDesignFiles({
+          designId,
+          sourceType: "figma-clipboard-rest",
+          files,
+        });
+        const selectionWarnings = selectedNodeIdsTruncated
+          ? [SELECTION_TRUNCATED_GUIDANCE]
+          : [];
+        return {
+          ...saved,
+          warnings: [...saved.warnings, ...selectionWarnings],
+          strategy: "restNodes" as const,
+          figma: {
+            fileKey,
+            nodeIds: selectedNodeIds,
+            matchSource: "clipboardNodeIds" as const,
+            selectionTruncated: selectedNodeIdsTruncated === true,
+          },
+          fidelityReport: summarizeFidelity(fidelityEntries),
+          guidance: selectedNodeIdsTruncated
+            ? `${SELECTION_TRUNCATED_GUIDANCE} Review fidelityReport for conversion details.`
+            : "Imported the exact nodes selected in Figma. Review fidelityReport.imageFallbacks for subtrees rendered as PNG and fidelityReport.approximated for properties CSS cannot express exactly.",
+        };
+      }
+
+      if (clipboardTexts.length === 0) {
+        matchStatus = "none";
+        throw new Error(
+          "The Figma clipboard did not include exact node ids or visible text for matching.",
+        );
+      }
+
       const document = await fetchFileStructure(fileKey, NODE_STRUCTURE_DEPTH);
       const candidates = buildFigmaNodeCandidates(document);
       const matchResult = matchFigmaClipboardNodes(candidates, clipboardTexts);
@@ -101,9 +165,26 @@ export default defineAction({
         };
       }
     } catch (error) {
-      figmaApiKeyMissing = CREDENTIAL_MISSING_RE.test(
-        error instanceof Error ? error.message : String(error),
-      );
+      const errorMessage =
+        error instanceof Error ? error.message : String(error);
+      // The importer intentionally refuses to persist Figma's expiring render
+      // URLs. Keep its actionable storage setup error instead of disguising it
+      // as an ordinary clipboard-format fallback.
+      if (DURABLE_STORAGE_REQUIRED_RE.test(errorMessage)) {
+        throw error;
+      }
+      figmaApiKeyMissing = CREDENTIAL_MISSING_RE.test(errorMessage);
+      if (
+        selectedNodeIds?.length &&
+        !parsedClipboard.fallbackHtml &&
+        !figmaApiKeyMissing
+      ) {
+        // Exact ids prove this was a current Figma clipboard. With no visible
+        // fallback, a real REST/import failure must remain truthful and
+        // actionable rather than being mislabeled as a clipboard format that
+        // omitted ids.
+        throw error;
+      }
       if (!figmaApiKeyMissing) {
         // A real (non-credential) REST failure — network error, revoked
         // token, file access issue, etc. Still fall back to the honest
@@ -113,6 +194,21 @@ export default defineAction({
       }
     }
 
+    if (!parsedClipboard.fallbackHtml) {
+      return {
+        designId,
+        files: [],
+        warnings: [],
+        strategy: "htmlFallback" as const,
+        figmaApiKeyMissing,
+        matchStatus,
+        figma: { fileKey },
+        guidance: figmaApiKeyMissing
+          ? `${KEY_MISSING_GUIDANCE} Current Figma clipboard data has no browser-readable HTML fallback, so paste a frame link after connecting the token.`
+          : "This Figma clipboard format did not expose exact node ids or browser-readable HTML. Paste a frame link for an exact import.",
+      };
+    }
+
     const saved = await saveFigmaPasteHtmlFallback({
       designId,
       clipboardHtml,

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

@@ -1,4 +1,5 @@
 import { defineAction } from "@agent-native/core";
+import { assertAccess } from "@agent-native/core/sharing";
 import { z } from "zod";
 
 import {
@@ -7,7 +8,10 @@ import {
   resolveTargetNodeId,
   summarizeFidelity,
 } from "../server/lib/figma-node-import.js";
-import { saveImportedDesignFiles } from "../server/lib/import-design-files.js";
+import {
+  resolveImportDesignId,
+  saveImportedDesignFiles,
+} from "../server/lib/import-design-files.js";
 import { parseFigmaFileKey, parseFigmaNodeId } from "../shared/figma-url.js";
 
 const schemaInput = z
@@ -49,7 +53,7 @@ const schemaInput = z
 
 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.",
+    "Import a Figma frame/component by URL or file key + node id, mapping supported structure to fidelity-aware HTML (position, auto-layout as flexbox, text, fills/gradients, strokes, corner radii, effects) and saving it as a new Design screen. Geometry and paint models HTML/CSS cannot represent faithfully (including masks, vector/boolean geometry, lines/arcs, advanced strokes/text, and transformed image crops) use rendered fallbacks instead of silently importing the wrong visual. Returns a fidelity report of which nodes 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) => {
@@ -67,6 +71,13 @@ export default defineAction({
     const requestedNodeId =
       parseFigmaNodeId(args.nodeId) ?? parseFigmaNodeId(args.figmaUrl);
 
+    // Validate the target before any provider fetch, rendered-fallback
+    // download, or durable upload. saveImportedDesignFiles checks again at
+    // mutation time, but waiting until then leaves external work and orphaned
+    // assets behind when a caller names a design they cannot edit.
+    const designId = await resolveImportDesignId(args.designId);
+    await assertAccess("design", designId, "editor");
+
     const nodeId = await resolveTargetNodeId(fileKey, requestedNodeId);
     const rootNode = await fetchFigmaNode(fileKey, nodeId);
 
@@ -79,7 +90,7 @@ export default defineAction({
     );
 
     const saved = await saveImportedDesignFiles({
-      designId: args.designId,
+      designId,
       sourceType: "figma-import",
       files,
     });
@@ -89,7 +100,7 @@ export default defineAction({
       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).",
+        "Review fidelityReport.imageFallbacks for subtrees rendered as PNG (masks, vector/boolean geometry, lines/arcs, advanced strokes/text, transformed image crops, and unsupported node types) and fidelityReport.approximated for properties CSS cannot express exactly (rotation, per-side stroke alignment, radial/angular/diamond gradients, blur radius scale, and live component/variable/prototype semantics).",
     };
   },
 });

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

@@ -76,6 +76,10 @@ export default defineAction({
     const files = buildBuilderDesignSystemIndexFiles({
       codeFiles,
       designMd,
+      // Agent action payloads intentionally stay at the core 2 MB inline
+      // budget. Fail loudly instead of silently dropping a larger `.fig`;
+      // the setup screen's guarded multipart route supports up to 200 MB.
+      overflowBehavior: "throw",
     });
     const result = await startBuilderDesignSystemIndex({
       projectName,

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

@@ -0,0 +1,118 @@
+import { defineAction } from "@agent-native/core";
+import {
+  getRequestOrgId,
+  getRequestUserEmail,
+} from "@agent-native/core/server/request-context";
+import { accessFilter } from "@agent-native/core/sharing";
+import { and, desc, eq, inArray, sql } from "drizzle-orm";
+import { z } from "zod";
+
+import { getDb, schema } from "../server/db/index.js";
+import { DESIGN_TEMPLATE_PRESETS } from "../shared/design-template-presets.js";
+import { designTemplateCategorySchema } from "./save-design-as-template.js";
+
+const PREVIEW_MAX_BYTES = 50_000;
+
+export default defineAction({
+  description:
+    "List reusable Design templates, including built-in starters plus templates the user can access or publicly discover.",
+  schema: z.object({
+    category: designTemplateCategorySchema.optional(),
+    includePreview: z.enum(["true", "false"]).optional().default("false"),
+  }),
+  readOnly: true,
+  http: { method: "GET" },
+  run: async ({ category, includePreview }) => {
+    const db = getDb();
+    const userEmail = getRequestUserEmail();
+    const access = accessFilter(
+      schema.designTemplates,
+      schema.designTemplateShares,
+      { userEmail, orgId: getRequestOrgId() },
+      "viewer",
+      { includePublic: true },
+    );
+    const rows = await db
+      .select({
+        id: schema.designTemplates.id,
+        title: schema.designTemplates.title,
+        description: schema.designTemplates.description,
+        category: schema.designTemplates.category,
+        width: schema.designTemplates.width,
+        height: schema.designTemplates.height,
+        lockedLayerCount: schema.designTemplates.lockedLayerCount,
+        visibility: schema.designTemplates.visibility,
+        ownerEmail: schema.designTemplates.ownerEmail,
+        createdAt: schema.designTemplates.createdAt,
+        updatedAt: schema.designTemplates.updatedAt,
+      })
+      .from(schema.designTemplates)
+      .where(
+        category
+          ? and(access, eq(schema.designTemplates.category, category))
+          : access,
+      )
+      .orderBy(desc(schema.designTemplates.updatedAt));
+
+    const previews = new Map<string, string>();
+    if (includePreview === "true" && rows.length > 0) {
+      const files = await db
+        .select({
+          templateId: schema.designTemplateFiles.templateId,
+          filename: schema.designTemplateFiles.filename,
+          fileType: schema.designTemplateFiles.fileType,
+          content: sql<string>`substr(${schema.designTemplateFiles.content}, 1, ${PREVIEW_MAX_BYTES})`,
+        })
+        .from(schema.designTemplateFiles)
+        .where(
+          inArray(
+            schema.designTemplateFiles.templateId,
+            rows.map((row) => row.id),
+          ),
+        );
+      for (const file of files) {
+        if (!previews.has(file.templateId) && file.fileType === "html") {
+          previews.set(file.templateId, file.content);
+        }
+        if (file.filename === "index.html" && file.fileType === "html") {
+          previews.set(file.templateId, file.content);
+        }
+      }
+    }
+
+    const presets = DESIGN_TEMPLATE_PRESETS.filter(
+      (preset) => !category || preset.category === category,
+    ).map((preset) => ({
+      id: preset.id,
+      title: preset.title,
+      description: preset.description,
+      category: preset.category,
+      width: preset.width,
+      height: preset.height,
+      lockedLayerCount: 2,
+      visibility: "public" as const,
+      isOwner: false,
+      source: "starter" as const,
+      createdAt: null,
+      updatedAt: null,
+      ...(includePreview === "true" ? { previewHtml: preset.content } : {}),
+    }));
+
+    const saved = rows.map(({ ownerEmail, ...row }) => ({
+      ...row,
+      isOwner:
+        !!userEmail && ownerEmail.toLowerCase() === userEmail.toLowerCase(),
+      source: "saved" as const,
+      ...(includePreview === "true"
+        ? { previewHtml: previews.get(row.id) ?? null }
+        : {}),
+    }));
+
+    return {
+      count: presets.length + saved.length,
+      starterCount: presets.length,
+      savedCount: saved.length,
+      templates: [...presets, ...saved],
+    };
+  },
+});

package/corpus/templates/design/actions/navigate.ts

@@ -9,6 +9,7 @@
  *   pnpm action navigate --view=editor --designId=abc123 --editorView=overview
  *   pnpm action navigate --view=editor --designId=abc123 --filename=checkout.html
  *   pnpm action navigate --view=design-systems
+ *   pnpm action navigate --view=templates
  *   pnpm action navigate --view=design-systems --designSystemId=abc123
  *   pnpm action navigate --view=settings
  *   pnpm action navigate --path=/some/route
@@ -23,6 +24,7 @@
  *   --filename   Screen filename to focus in the design editor
  *   --tool       Design editor tool to activate
  *   --designSystemId Design system ID (for design-systems view)
+ *   --templateId Saved or starter template ID (for templates view)
  *   --path       URL path to navigate to
  */
 
@@ -59,11 +61,18 @@ const designLeftPanelSchema = z.enum([
 
 export default defineAction({
   description:
-    "Navigate the UI to a specific view or path. Views: list, editor, design-systems, present, settings. Use --designId with editor/present views and --designSystemId with design-systems. For designs, use editorView=overview to show the infinite screens canvas, or editorView=single with fileId/filename/screen to focus a screen. Use leftPanel=file|agent|assets|import|tools|tokens|code to focus the left rail, including Import and the wide Code workspace. Legacy inspectorTab=extensions opens Tools. Use tool to activate a design editor tool.",
+    "Navigate the UI to a specific view or path. Views: list, templates, editor, design-systems, present, settings. Use --templateId with templates, --designId with editor/present views, and --designSystemId with design-systems. For designs, use editorView=overview to show the infinite screens canvas, or editorView=single with fileId/filename/screen to focus a screen. Use leftPanel=file|agent|assets|import|tools|tokens|code to focus the left rail, including Import and the wide Code workspace. Legacy inspectorTab=extensions opens Tools. Use tool to activate a design editor tool.",
   schema: z
     .object({
       view: z
-        .enum(["list", "editor", "design-systems", "present", "settings"])
+        .enum([
+          "list",
+          "templates",
+          "editor",
+          "design-systems",
+          "present",
+          "settings",
+        ])
         .optional()
         .describe("View name to navigate to"),
       designId: z.string().optional().describe("Design ID for editor/present"),
@@ -110,6 +119,10 @@ export default defineAction({
         .string()
         .optional()
         .describe("Design system ID for design-systems view"),
+      templateId: z
+        .string()
+        .optional()
+        .describe("Saved or starter template ID for templates view"),
       path: z.string().optional().describe("URL path to navigate to"),
     })
     .superRefine((args, ctx) => {
@@ -161,6 +174,7 @@ export default defineAction({
     if (args.zoom !== undefined) nav.zoom = args.zoom;
     if (args.tool) nav.tool = args.tool;
     if (args.designSystemId) nav.designSystemId = args.designSystemId;
+    if (args.templateId) nav.templateId = args.templateId;
     if (args.path) nav.path = args.path;
     await writeAppState("navigate", nav);
     return `Navigating to ${args.view || args.path}${

package/corpus/templates/design/actions/provider-api-request.ts

@@ -13,6 +13,15 @@ import {
 const ProviderSchema = z.enum(DESIGN_PROVIDER_API_IDS);
 const MethodSchema = z.enum(["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD"]);
 
+export function requiresProviderApiApproval(args: {
+  provider: string;
+  method: string;
+}): boolean {
+  return (
+    args.provider === "figma" && args.method !== "GET" && args.method !== "HEAD"
+  );
+}
+
 const PaginationSchema = z
   .object({
     nextCursorPath: z
@@ -75,7 +84,7 @@ export default defineAction({
     "The request is constrained to the provider host, uses saved scoped credentials such as GITHUB_TOKEN or FIGMA_ACCESS_TOKEN automatically, blocks private/internal URLs, and redacts secrets from responses. " +
     "\n\nSTAGING MODE (preferred for large responses): Pass stageAs to write response items into a scratch dataset instead of returning the raw body. " +
     "Returns { dataset, rowCount, columns, sampleRows } so only a compact summary enters context. Use query-staged-dataset to aggregate, filter, and project the data without re-fetching. " +
-    "\n\nPAGINATION: When stageAs is set, pass pagination config to fetch all pages server-side into the same dataset. For GitHub page pagination, use pageParam='page', pageSize from per_page, and itemsPath when the response object contains an items array.",
+    "\n\nPAGINATION: When stageAs is set, pass pagination config to fetch all pages server-side into the same dataset. For GitHub page pagination, use pageParam='page', pageSize from per_page, and itemsPath when the response object contains an items array. Figma REST can read files/nodes/styles/components and perform a few scoped writes such as comments or Enterprise variables, but it cannot create arbitrary canvas layers; use the official Figma MCP when connected or the Figma SVG export workflow for canvas handoff.",
   schema: z.object({
     provider: ProviderSchema.describe("Configured provider API to call."),
     method: MethodSchema.default("GET").describe("HTTP method to use."),
@@ -195,6 +204,7 @@ export default defineAction({
       ),
   }),
   http: false,
+  needsApproval: requiresProviderApiApproval,
   run: async (args) => {
     if (args.stageAs) {
       const ctx = getCredentialContext();