@agent-native/core 0.92.10 → 0.92.12

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

@@ -57,23 +57,59 @@ function jsonValuesEqual(left: unknown, right: unknown): boolean {
   return JSON.stringify(left) === JSON.stringify(right);
 }
 
+// Same-process mutex guarding the generation-session read-modify-write below.
+// generate-screens' own tool description explicitly recommends fanning out
+// parallel generate-design calls per returned frame ("fan out calls to
+// generate-design for each returned frame"). Without this lock, two
+// concurrent calls for the same designId both read the same pre-update
+// session, each only marks its own frame done, and whichever writeAppState
+// lands second silently discards the first call's frame-done update —
+// application state has no CAS/versioning primitive (unlike designs.data's
+// mutateDesignData), so a plain read-then-write here is a classic lost-update
+// race. This mirrors the same-process serialization
+// server/lib/design-data-mutation.ts uses (withDesignDataLock) for the
+// designs.data column. Cross-process races remain (no CAS primitive exists
+// for application state), but same-process fan-out from one agent turn is
+// the realistic, explicitly-encouraged case this closes.
+const generationSessionLocks = new Map<string, Promise<unknown>>();
+
+function withGenerationSessionLock<T>(
+  designId: string,
+  callback: () => Promise<T>,
+): Promise<T> {
+  const previous = generationSessionLocks.get(designId) ?? Promise.resolve();
+  const next = previous.then(callback, callback);
+  generationSessionLocks.set(designId, next);
+  const cleanup = () => {
+    if (generationSessionLocks.get(designId) === next) {
+      generationSessionLocks.delete(designId);
+    }
+  };
+  next.then(cleanup, cleanup);
+  return next;
+}
+
 async function updateGenerationSessionForSavedFiles(
   designId: string,
   savedFilenames: string[],
 ) {
-  const key = designGenerationSessionKey(designId);
-  const rawSession = await readAppState(key).catch(() => null);
-  if (!rawSession || typeof rawSession !== "object") return;
-  const session = rawSession as unknown as DesignGenerationSession;
-  if (session.designId !== designId || !Array.isArray(session.frames)) return;
-
-  const nextSession = updateGenerationSessionWithSavedFiles(
-    session,
-    savedFilenames,
-  );
-  if (nextSession === session) return;
+  await withGenerationSessionLock(designId, async () => {
+    const key = designGenerationSessionKey(designId);
+    const rawSession = await readAppState(key).catch(() => null);
+    if (!rawSession || typeof rawSession !== "object") return;
+    const session = rawSession as unknown as DesignGenerationSession;
+    if (session.designId !== designId || !Array.isArray(session.frames)) {
+      return;
+    }
+
+    const nextSession = updateGenerationSessionWithSavedFiles(
+      session,
+      savedFilenames,
+    );
+    if (nextSession === session) return;
 
-  await writeAppState(key, nextSession as unknown as Record<string, unknown>);
+    await writeAppState(key, nextSession as unknown as Record<string, unknown>);
+  });
 }
 
 const generateDesignAgentParameters = {
@@ -228,6 +264,37 @@ const generateDesignAction = defineAction({
                 message: "canvasFrames entries require fileId or filename",
               }),
           )
+          // Reject two placements for the same target in one call. Without
+          // this, mergeCanvasFramePlacements folds both entries into a single
+          // canvasFrames[fileId] value (last one wins), but the mutateDesignData
+          // isApplied check below verifies EVERY placedFrames entry against
+          // that single folded value — so the earlier, now-overwritten entry
+          // always fails the equality check. Since the mutate callback is
+          // deterministic, every retry recomputes the identical mismatch, so
+          // the whole action always fails with a "concurrent write conflicts"
+          // error after burning through all retries, even though nothing else
+          // was actually writing to the design.
+          .superRefine((frames, ctx) => {
+            const seen = new Map<string, number>();
+            frames.forEach((frame, index) => {
+              const key = frame.fileId
+                ? `id:${frame.fileId}`
+                : `name:${frame.filename}`;
+              const firstIndex = seen.get(key);
+              if (firstIndex !== undefined) {
+                ctx.addIssue({
+                  code: z.ZodIssueCode.custom,
+                  path: [index],
+                  message:
+                    `canvasFrames entry ${index} duplicates the target already placed ` +
+                    `at index ${firstIndex} (${frame.fileId ? `fileId ${frame.fileId}` : `filename ${frame.filename}`}). ` +
+                    "Pass exactly one placement per screen.",
+                });
+                return;
+              }
+              seen.set(key, index);
+            });
+          })
           .optional(),
       )
       .optional()

package/corpus/templates/design/actions/generate-screens.ts

@@ -2,10 +2,11 @@ import { defineAction, embedApp } from "@agent-native/core";
 import { writeAppState } from "@agent-native/core/application-state";
 import { buildDeepLink } from "@agent-native/core/server";
 import { assertAccess } from "@agent-native/core/sharing";
+import { eq } from "drizzle-orm";
 import { nanoid } from "nanoid";
 import { z } from "zod";
 
-import "../server/db/index.js";
+import { getDb, schema } from "../server/db/index.js";
 import {
   type AssignedCanvasRegion,
   DEFAULT_ASSIGNED_REGION_GAP,
@@ -186,6 +187,28 @@ export default defineAction({
           .min(1)
           .max(8)
           .superRefine((screens, ctx) => {
+            // Two screens sharing an explicit frameId would produce two
+            // DesignGenerationFrame entries with the same frameId (and thus
+            // the same derived agentId `agent-${frameId}`) once frames get
+            // built below, colliding agent presence/status tracking for both
+            // screens on the overview canvas.
+            const frameIdsSeen = new Map<string, number>();
+            screens.forEach((screen, index) => {
+              if (!screen.frameId) return;
+              const firstIndex = frameIdsSeen.get(screen.frameId);
+              if (firstIndex !== undefined) {
+                ctx.addIssue({
+                  code: z.ZodIssueCode.custom,
+                  path: [index, "frameId"],
+                  message:
+                    `duplicate frameId "${screen.frameId}" (already used at index ${firstIndex}); ` +
+                    "each screen needs a distinct frameId",
+                });
+                return;
+              }
+              frameIdsSeen.set(screen.frameId, index);
+            });
+
             const requestAnchors = new Map<
               string,
               { index: number; role: DesignGenerationFrame["role"] }
@@ -259,21 +282,43 @@ export default defineAction({
           : DEFAULT_ASSIGNED_REGION_MAX_COLUMNS,
     });
 
-    const seenFilenames = new Map<string, number>();
-    // Dedupe any filename (explicit or auto-generated) so two screens can never
-    // resolve to the same target file — otherwise generate-design silently
-    // overwrites the first screen's output with the second's.
+    // Seed the used-filename set with the design's EXISTING files, not just
+    // names requested in this call. Without this, a requested/auto-slugged
+    // target (e.g. a screen titled "Onboarding" slugging to "onboarding.html")
+    // can silently collide with an already-saved screen: generate-design's
+    // existing-file lookup is keyed by filename, so the later generate-design
+    // call for that "new" target would UPDATE (overwrite) the pre-existing
+    // file instead of creating the new screen the agent intended.
+    const db = getDb();
+    const existingFiles = await db
+      .select({ filename: schema.designFiles.filename })
+      .from(schema.designFiles)
+      .where(eq(schema.designFiles.designId, designId));
+    const usedFilenames = new Set(
+      existingFiles
+        .map((file) => file.filename)
+        .filter((filename): filename is string => Boolean(filename)),
+    );
+    // Dedupe any filename (explicit or auto-generated) so two screens can
+    // never resolve to the same target file, and so no target collides with
+    // an existing screen — otherwise generate-design silently overwrites the
+    // other screen's content.
     const dedupeFilename = (base: string): string => {
-      if (!seenFilenames.has(base)) {
-        seenFilenames.set(base, 1);
+      if (!usedFilenames.has(base)) {
+        usedFilenames.add(base);
         return base;
       }
-      const count = seenFilenames.get(base)! + 1;
-      seenFilenames.set(base, count);
       const dot = base.lastIndexOf(".");
-      return dot > 0
-        ? `${base.slice(0, dot)}-${count}${base.slice(dot)}`
-        : `${base}-${count}`;
+      const stem = dot > 0 ? base.slice(0, dot) : base;
+      const ext = dot > 0 ? base.slice(dot) : "";
+      let count = 2;
+      let candidate = `${stem}-${count}${ext}`;
+      while (usedFilenames.has(candidate)) {
+        count += 1;
+        candidate = `${stem}-${count}${ext}`;
+      }
+      usedFilenames.add(candidate);
+      return candidate;
     };
     const requestedTargets = screens.map((screen, index) => {
       if (screen.filename) return dedupeFilename(screen.filename);

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

@@ -0,0 +1,115 @@
+import { defineAction } from "@agent-native/core";
+import { z } from "zod";
+
+import { executeProviderApiRequest } from "../server/lib/provider-api.js";
+import { parseFigmaFileKey } from "../shared/figma-url.js";
+
+const schemaInput = z
+  .object({
+    fileUrl: z
+      .string()
+      .trim()
+      .optional()
+      .describe(
+        "Figma file URL, for example https://www.figma.com/design/<fileKey>/...",
+      ),
+    fileKey: z
+      .string()
+      .trim()
+      .optional()
+      .describe("Figma file key. Used when fileUrl is omitted."),
+  })
+  .refine((value) => value.fileUrl || value.fileKey, {
+    message: "Pass fileUrl or fileKey.",
+    path: ["fileUrl"],
+  });
+
+type FigmaProviderEnvelope = {
+  response?: {
+    ok?: boolean;
+    status?: number;
+    statusText?: string;
+    json?: unknown;
+    text?: string;
+  };
+};
+
+type FigmaStyleRecord = {
+  key?: unknown;
+  node_id?: unknown;
+  style_type?: unknown;
+  name?: unknown;
+  description?: unknown;
+};
+
+function stringValue(value: unknown): string | null {
+  return typeof value === "string" && value.trim() ? value.trim() : null;
+}
+
+function providerJson(envelope: unknown, label: string): unknown {
+  const response = (envelope as FigmaProviderEnvelope | null)?.response;
+  if (!response) throw new Error(`Figma ${label} response was empty.`);
+  if (response.ok === false) {
+    const detail =
+      stringValue(response.text) ||
+      response.statusText ||
+      `HTTP ${response.status ?? "error"}`;
+    throw new Error(`Figma ${label} request failed: ${detail}`);
+  }
+  return response.json;
+}
+
+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.",
+  schema: schemaInput,
+  http: { method: "GET" },
+  readOnly: true,
+  publicAgent: { expose: true, readOnly: true, requiresAuth: true },
+  run: async (args) => {
+    const fileKey =
+      parseFigmaFileKey(args.fileKey) ?? parseFigmaFileKey(args.fileUrl);
+    if (!fileKey) {
+      throw new Error("Could not find a Figma file key in the provided URL.");
+    }
+
+    const envelope = await executeProviderApiRequest({
+      provider: "figma",
+      method: "GET",
+      path: `/files/${fileKey}/styles`,
+      maxBytes: 2 * 1024 * 1024,
+    });
+    const json = providerJson(envelope, "styles") as {
+      meta?: { styles?: unknown };
+    };
+    const records = Array.isArray(json.meta?.styles)
+      ? (json.meta!.styles as FigmaStyleRecord[])
+      : [];
+
+    const styles = records
+      .filter((record) => record && typeof record === "object")
+      .map((record) => ({
+        key: stringValue(record.key),
+        nodeId: stringValue(record.node_id),
+        styleType: stringValue(record.style_type),
+        name: stringValue(record.name) ?? "Untitled style",
+        description: stringValue(record.description),
+      }));
+
+    const byType = styles.reduce<Record<string, number>>((acc, style) => {
+      const type = style.styleType ?? "UNKNOWN";
+      acc[type] = (acc[type] ?? 0) + 1;
+      return acc;
+    }, {});
+
+    return {
+      source: "figma",
+      fileKey,
+      total: styles.length,
+      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.",
+    };
+  },
+});

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

@@ -0,0 +1,254 @@
+/**
+ * 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.
+ *
+ * Navigation-only + inline/Alpine designs only (real-app sources return a
+ * CTA). Because this writes the transient `navigate` application-state
+ * command, it is exposed as the default POST mutation rather than a GET.
+ */
+
+import { defineAction } from "@agent-native/core/action";
+import { writeAppState } from "@agent-native/core/application-state";
+import { getText, hasCollabState } from "@agent-native/core/collab";
+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 { buildCodeLayerProjection } from "../shared/code-layer.js";
+import type { CodeLayerSource } from "../shared/code-layer.js";
+import {
+  entriesForComponent,
+  scanComponentLibrary,
+} from "../shared/component-library.js";
+import {
+  componentNameFor,
+  componentNodeIdMatches,
+} from "../shared/component-model.js";
+import { designSourceTypeFromData } from "../shared/source-mode.js";
+
+async function liveContent(
+  fileId: string,
+  storedContent: string,
+): Promise<string> {
+  try {
+    if (await hasCollabState(fileId)) {
+      const live = await getText(fileId, "content");
+      if (typeof live === "string") return live;
+    }
+  } catch {
+    // Collab reads are best-effort; SQL content is the fallback.
+  }
+  return storedContent;
+}
+
+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).",
+  schema: z.object({
+    designId: z.string().describe("Design project ID"),
+    nodeId: z
+      .string()
+      .describe("data-agent-native-node-id of the component instance root"),
+    fileId: z
+      .string()
+      .optional()
+      .describe(
+        "Design file id the instance currently lives in; defaults to index.html",
+      ),
+  }),
+  run: async ({ designId, nodeId, fileId }) => {
+    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,
+        nodeId,
+        sourceType,
+        ctaRequired: true,
+        ctaMessage:
+          "Go to main component requires a connected Builder app for " +
+          "real-app sources. Not yet available.",
+        isMain: false,
+        navigated: false,
+      };
+    }
+
+    const db = getDb();
+
+    // ── Resolve the current node + component name ──────────────────────────
+    const conditions = [
+      accessFilter(schema.designs, schema.designShares),
+      eq(schema.designFiles.designId, designId),
+      fileId
+        ? eq(schema.designFiles.id, fileId)
+        : eq(schema.designFiles.filename, "index.html"),
+    ];
+
+    const [file] = 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(...conditions))
+      .limit(1);
+
+    if (!file) throw new Error("Design HTML file not found.");
+
+    const currentHtml = await liveContent(file.id, file.content ?? "");
+    const codeLayerSource: CodeLayerSource = {
+      kind: "design-file",
+      designId: file.designId,
+      fileId: file.id,
+      filename: file.filename,
+    };
+    const currentProjection = buildCodeLayerProjection(currentHtml, {
+      source: codeLayerSource,
+    });
+
+    const node = currentProjection.nodes.find((n) =>
+      componentNodeIdMatches(n, nodeId),
+    );
+    if (!node) {
+      throw new Error(
+        `Node "${nodeId}" not found. Run get-code-layer-projection to list current ids.`,
+      );
+    }
+
+    const componentName = componentNameFor(node);
+    if (!componentName) {
+      throw new Error(
+        `Node "${nodeId}" is not a component root (no data-agent-native-component attribute).`,
+      );
+    }
+
+    // ── Scan every design file for instances of this component ─────────────
+    const allFiles = 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);
+
+    // Use the freshest content we already read for the current file so the
+    // instance we just resolved (possibly from a live collab doc) matches up
+    // with `node.id` exactly.
+    const filesForScan = allFiles.map((row) =>
+      row.id === file.id ? { ...row, content: currentHtml } : row,
+    );
+
+    const entries = scanComponentLibrary(filesForScan);
+    const matches = 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.`,
+      );
+    }
+
+    const main = 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
+    // durable id for every entry, so this is an apples-to-apples comparison.
+    const isMain = main.fileId === file.id && main.nodeId === nodeId;
+
+    if (isMain) {
+      return {
+        designId,
+        nodeId,
+        componentName,
+        sourceType,
+        ctaRequired: false,
+        isMain: true,
+        instanceCount: matches.length,
+        navigated: false,
+        note:
+          matches.length === 1
+            ? `"${componentName}" has only one instance — this is it.`
+            : `This is the earliest instance of "${componentName}" across the design.`,
+      };
+    }
+
+    await writeAppState("navigate", {
+      view: "editor",
+      designId,
+      editorView: "single",
+      fileId: main.fileId,
+      filename: main.filename,
+      selectedNodeId: main.nodeId,
+      inspectorTab: "design",
+      inspectorSection: "component",
+    });
+
+    return {
+      designId,
+      nodeId,
+      componentName,
+      sourceType,
+      ctaRequired: false,
+      isMain: false,
+      instanceCount: matches.length,
+      main: {
+        fileId: main.fileId,
+        filename: main.filename,
+        nodeId: main.nodeId,
+        selector: main.selector,
+      },
+      navigated: true,
+    };
+  },
+});

package/corpus/templates/design/actions/grant-localhost-write-consent.ts

@@ -19,7 +19,7 @@ export default defineAction({
     "for a specific design + localhost connection. The grant scopes writes to the " +
     "connection's rootPath and expires after 8 hours. Requires editor access on the design. " +
     "The LocalhostWriteConsentDialog calls this after the user clicks 'Allow writes'.",
-  // This action mints/returns the real bridgeToken that unlocks the local
+  // This action persists the real bridgeToken that unlocks the local
   // bridge's unrestricted /read-file, /write-file, and /apply-edit. It must
   // only ever be triggered by a human clicking "Allow writes" in
   // LocalhostWriteConsentDialog — never by the agent itself, or an agent
@@ -27,7 +27,9 @@ export default defineAction({
   // human consent model entirely. `agentTool: false` hides it from every
   // agent tool surface (in-app assistant, MCP, A2A) while keeping it
   // callable from the frontend via `callAction` / `useActionMutation` and
-  // the raw `/_agent-native/actions/grant-localhost-write-consent` route.
+  // the raw `/_agent-native/actions/grant-localhost-write-consent` route. The
+  // token intentionally stays server-side: browser callers only need grant
+  // metadata because write-local-file adds bridge authentication itself.
   agentTool: false,
   schema: z.object({
     designId: z.string().describe("Design ID."),
@@ -124,7 +126,6 @@ export default defineAction({
 
     return {
       grantId: existing?.id ?? grantId,
-      bridgeToken,
       rootPath,
       grantedUntil,
     };

package/corpus/templates/design/actions/import-design-source.ts

@@ -2,12 +2,12 @@ import { defineAction } from "@agent-native/core";
 import { assertAccess } from "@agent-native/core/sharing";
 import { z } from "zod";
 
+import { saveFigmaPasteHtmlFallback } from "../server/lib/figma-paste-fallback.js";
 import {
   normalizeImportedHtmlDocument,
   resolveImportDesignId,
   saveImportedDesignFiles,
 } from "../server/lib/import-design-files.js";
-import { parseVisibleClipboardHtml } from "../server/lib/visible-clipboard-html.js";
 
 const MAX_HTML_IMPORT_BYTES = 2 * 1024 * 1024;
 
@@ -62,38 +62,11 @@ export default defineAction({
       };
     }
 
-    const parsed = parseVisibleClipboardHtml(content);
-    if (!parsed.fallbackHtml) {
-      throw new Error(
-        "No visible HTML was found in the clipboard. Copy a frame, then paste into the canvas.",
-      );
-    }
-    const saved = await saveImportedDesignFiles({
+    return saveFigmaPasteHtmlFallback({
       designId: resolvedDesignId,
-      sourceType: "figma-paste-html",
-      files: [
-        {
-          filename: baseFilename(originalName, "figma-paste"),
-          fileType: "html",
-          content: normalizeImportedHtmlDocument(
-            parsed.fallbackHtml,
-            "visible clipboard HTML",
-          ),
-          source: {
-            sourceType: "figma-paste-html",
-          },
-        },
-      ],
+      clipboardHtml: content,
+      originalName,
     });
-    return {
-      ...saved,
-      stats: {
-        sourceKind: "figma-paste",
-        format: "html",
-        frameCount: saved.files.length,
-        imageCount: 0,
-      },
-    };
   },
   link: ({ result }) => {
     if (!result || typeof result !== "object") return null;