@agent-native/core 0.92.10 → 0.92.11

package/corpus/templates/design/actions/detach-component-instance.ts

@@ -0,0 +1,337 @@
+/**
+ * detach-component-instance — Figma's "Detach instance" (⌥⌘B).
+ *
+ * There is no separate component "definition"/template markup anywhere in
+ * this codebase (see `shared/component-model.ts`): a component instance is
+ * just an ordinary element carrying a `data-agent-native-component="Name"`
+ * annotation (plus optional `data-agent-native-prop-*` overrides), and every
+ * instance of the same name is an independently-duplicated copy of HTML —
+ * `component_index` only stores metadata (props/variants/runtime selectors),
+ * never markup. Detaching an instance therefore doesn't need to "inline a
+ * template" the way a real component-instantiation system would: the node's
+ * current rendered markup already IS the fully expanded content. Detach
+ * severs the *component-instance linkage* by stripping the annotation
+ * attributes, so `is-component-instance` checks (`isComponentInstance`,
+ * `index-components`, `get-component-details`) stop recognizing this node —
+ * exactly Figma's "instance becomes a plain layer" semantics — while leaving
+ * position, size, layout, classes, text, and Alpine (`x-data`) behavior
+ * completely untouched.
+ *
+ * Persists through the same deterministic HTML-patch + collab seam as
+ * `apply-component-prop-edit` / `apply-visual-edit` (`writeInlineSourceFile`
+ * with an `expectedVersionHash` CAS guard), so it participates in the
+ * editor's undo/collab machinery exactly like every other HTML-mutating
+ * action — there is no separate undo/history log in this codebase to hook
+ * into (see those actions' docs).
+ *
+ * Inline/Alpine designs only; real-app sources fail closed (same posture as
+ * `apply-component-prop-edit`).
+ */
+
+import { defineAction } from "@agent-native/core/action";
+import {
+  agentEnterDocument,
+  agentLeaveDocument,
+  agentUpdateSelection,
+} from "@agent-native/core/collab";
+import {
+  accessFilter,
+  assertAccess,
+  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 {
+  writeInlineSourceFile,
+  type SourceWorkspaceFile,
+} from "../server/source-workspace.js";
+import { buildCodeLayerProjection } from "../shared/code-layer.js";
+import type { CodeLayerSource } from "../shared/code-layer.js";
+import { agentSelectionDescriptor } from "../shared/collab-selection.js";
+import {
+  componentNameFor,
+  componentNodeIdMatches,
+  COMPONENT_NAME_ATTR,
+  COMPONENT_PROP_PREFIX,
+} from "../shared/component-model.js";
+import { designSourceTypeFromData } from "../shared/source-mode.js";
+import { sourceContentHash } from "../shared/source-workspace.js";
+
+// ─── Pure transform ────────────────────────────────────────────────────────
+
+/**
+ * Strip the `data-agent-native-component` annotation and every
+ * `data-agent-native-prop-*` override attribute from a node's opening tag,
+ * using its source span. Pure — no DB / IO — so it can be unit tested
+ * directly.
+ *
+ * Leaves everything else (classes, style, text, `x-data`, `id`,
+ * `data-agent-native-node-id`, …) untouched: the node keeps its current
+ * rendered appearance and behavior, it simply stops being recognized as a
+ * component instance.
+ */
+export function stripComponentAnnotations(
+  html: string,
+  source: { openStart: number; openEnd: number } | null | undefined,
+): { content: string; changed: boolean; removedAttributes: string[] } {
+  if (!source) {
+    return { content: html, changed: false, removedAttributes: [] };
+  }
+
+  const openTag = html.slice(source.openStart, source.openEnd);
+  const removed: string[] = [];
+  let newOpenTag = openTag;
+
+  const componentAttrRe = new RegExp(
+    `\\s+${COMPONENT_NAME_ATTR}\\s*=\\s*(?:"[^"]*"|'[^']*'|[^\\s>"']+)`,
+    "i",
+  );
+  if (componentAttrRe.test(newOpenTag)) {
+    removed.push(COMPONENT_NAME_ATTR);
+    newOpenTag = newOpenTag.replace(componentAttrRe, "");
+  }
+
+  const propAttrRe = new RegExp(
+    `\\s+${COMPONENT_PROP_PREFIX}[a-z0-9-]+\\s*=\\s*(?:"[^"]*"|'[^']*'|[^\\s>"']+)`,
+    "gi",
+  );
+  newOpenTag = newOpenTag.replace(propAttrRe, (match) => {
+    removed.push(match.trim().split("=")[0] ?? match.trim());
+    return "";
+  });
+
+  if (newOpenTag === openTag) {
+    return { content: html, changed: false, removedAttributes: [] };
+  }
+
+  return {
+    content:
+      html.slice(0, source.openStart) + newOpenTag + html.slice(source.openEnd),
+    changed: true,
+    removedAttributes: removed,
+  };
+}
+
+// ─── Persistence ────────────────────────────────────────────────────────────
+
+async function persistEdit(file: {
+  id: string;
+  designId: string;
+  filename: string;
+  content: string;
+  expectedVersionHash: string;
+}): Promise<string> {
+  await assertAccess("design", file.designId, "editor");
+
+  agentEnterDocument(file.id);
+  try {
+    const workspaceFile: SourceWorkspaceFile = {
+      id: file.id,
+      designId: file.designId,
+      filename: file.filename,
+      fileType: "html",
+      content: file.content,
+      createdAt: null,
+      updatedAt: null,
+    };
+
+    const result = await writeInlineSourceFile({
+      designId: file.designId,
+      file: workspaceFile,
+      content: file.content,
+      expectedVersionHash: file.expectedVersionHash,
+    });
+
+    return result.updatedAt;
+  } finally {
+    agentLeaveDocument(file.id);
+  }
+}
+
+// ─── Action ───────────────────────────────────────────────────────────────────
+
+export default defineAction({
+  description:
+    "Detach a component instance (Figma's ⌥⌘B): strip the " +
+    "data-agent-native-component annotation and its data-agent-native-prop-* " +
+    "overrides from the selected instance root so it becomes a plain, " +
+    "unlinked element. Position, size, classes, text, and behavior are " +
+    "unchanged — only the component-instance linkage is removed. " +
+    "Inline/Alpine designs only.",
+  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; defaults to index.html"),
+    source: z
+      .object({
+        currentContent: z
+          .string()
+          .optional()
+          .describe("Latest editor HTML snapshot, when available."),
+        revision: z
+          .string()
+          .optional()
+          .describe(
+            "design_files.updatedAt value the currentContent is based on.",
+          ),
+      })
+      .optional(),
+  }),
+  run: async ({ designId, nodeId, fileId, source }) => {
+    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,
+        detached: false,
+        ctaRequired: true,
+        ctaMessage:
+          "Detach instance requires a dedicated consented, version-guarded " +
+          "compiled-source transform for real-app sources. Not yet available.",
+      };
+    }
+
+    await assertAccess("design", designId, "editor");
+    const db = getDb();
+
+    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,
+        updatedAt: schema.designFiles.updatedAt,
+      })
+      .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.");
+
+    if (
+      source?.currentContent &&
+      source.revision &&
+      file.updatedAt &&
+      source.revision !== file.updatedAt
+    ) {
+      return {
+        designId,
+        nodeId,
+        detached: false,
+        conflict: true,
+        fileId: file.id,
+        filename: file.filename,
+        error:
+          "This file changed since this detach was prepared. Refresh the editor and try again.",
+      };
+    }
+
+    const html =
+      typeof source?.currentContent === "string"
+        ? source.currentContent
+        : (file.content ?? "");
+    const baseVersionHash = sourceContentHash(html);
+
+    const codeLayerSource: CodeLayerSource = {
+      kind: "design-file",
+      designId: file.designId,
+      fileId: file.id,
+      filename: file.filename,
+    };
+
+    const projection = buildCodeLayerProjection(html, {
+      source: codeLayerSource,
+    });
+
+    const node = projection.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) — nothing to detach.`,
+      );
+    }
+
+    const {
+      content: patchedContent,
+      changed,
+      removedAttributes,
+    } = stripComponentAnnotations(html, node.source);
+
+    if (!changed) {
+      return {
+        designId,
+        nodeId,
+        componentName,
+        detached: false,
+        fileId: file.id,
+        filename: file.filename,
+        note: "No component annotation attributes found on this node's open tag.",
+      };
+    }
+
+    const updatedAt = await persistEdit({
+      id: file.id,
+      designId: file.designId,
+      filename: file.filename,
+      content: patchedContent,
+      expectedVersionHash: baseVersionHash,
+    });
+
+    agentUpdateSelection(file.id, {
+      selection: agentSelectionDescriptor(
+        { nodeId, selector: node.selector },
+        "Detaching instance",
+      ),
+      nodeId,
+      editingFile: file.filename,
+      designId: file.designId,
+    });
+
+    return {
+      designId,
+      nodeId,
+      componentName,
+      detached: true,
+      removedAttributes,
+      fileId: file.id,
+      filename: file.filename,
+      updatedAt,
+      content: patchedContent,
+      note: `Detached from component "${componentName}". This node is now a plain element.`,
+    };
+  },
+});

package/corpus/templates/design/actions/export-design-as-figma-svg.ts

@@ -0,0 +1,219 @@
+/**
+ * export-design-as-figma-svg — export a design screen (or a selected
+ * subtree) as a genuinely VECTOR SVG document that Figma imports as
+ * editable layers (rect/path/gradients/filters stay editable; `<text>` is
+ * vectorized to outline paths on import — see the returned report's
+ * `vectorizedTextCaveat`). This is a different artifact from `export-svg`,
+ * which wraps the standalone HTML in a `foreignObject` for the editor's own
+ * "Download SVG" parity — Figma cannot import that as vectors at all, it
+ * stays an opaque embedded HTML blob.
+ *
+ * Resolution mirrors `take-design-screenshot.ts`: a single HTML screen
+ * (`fileId`, or `designId` + `filename` defaulting to `index.html`), using
+ * live collab content when the screen is actively being edited. `nodeId`
+ * additionally scopes the export to one selected element's subtree via its
+ * `data-agent-native-node-id` — the same attribute the editor stamps on
+ * selectable layers.
+ */
+
+import { defineAction } from "@agent-native/core";
+import { getText, hasCollabState } from "@agent-native/core/collab";
+import { accessFilter } from "@agent-native/core/sharing";
+import { and, eq } from "drizzle-orm";
+import { z } from "zod";
+
+import { getDb, schema } from "../server/db/index.js";
+import { trySaveExportFile } from "../server/lib/design-export.js";
+import {
+  renderDesignToFigmaSvg,
+  safeFigmaSvgFilename,
+} from "../server/lib/design-to-figma-svg.js";
+import { isMissingBrowserError } from "../server/lib/playwright-runtime.js";
+import "../server/db/index.js"; // ensure registerShareableResource runs
+
+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 {
+    // SQL content is the deterministic fallback.
+  }
+  return storedContent;
+}
+
+/** Model-actionable message when no headless Chromium binary is available. */
+export function chromiumUnavailableReason(err: unknown): string {
+  const detail = err instanceof Error ? err.message : String(err);
+  return (
+    "A headless Chromium browser is not available in this environment, so the " +
+    "vector SVG export cannot run here (this is expected in hosted/serverless " +
+    "deploys, which do not bundle a Chromium binary). Fall back to `export-svg` " +
+    "(a foreignObject-wrapped HTML snapshot — not Figma-importable as vectors, " +
+    "but still a usable static preview) or `export-html`. " +
+    `(${detail})`
+  );
+}
+
+export default defineAction({
+  description:
+    "Export a design screen (or a selected element's subtree via nodeId) as a " +
+    "genuinely vector SVG document — real <rect>/<path>/<text>/<image> markup " +
+    "with <linearGradient>/<radialGradient>/<filter> defs, which Figma imports " +
+    "as normal EDITABLE layers (unlike `export-svg`'s foreignObject wrapper, " +
+    "which Figma cannot import as vectors). Returns the SVG string plus an " +
+    "export report classifying each element as vectorized, approximated, " +
+    "rasterized, or omitted. Note: Figma converts all imported SVG <text> to " +
+    "outlined vector paths on paste/drag-import — geometry stays pixel-exact " +
+    "but the text is no longer live/editable type in Figma; see the report's " +
+    "`vectorizedTextCaveat`.",
+  schema: z.object({
+    designId: z
+      .string()
+      .optional()
+      .describe("Design project id. Required unless fileId is provided."),
+    fileId: z
+      .string()
+      .optional()
+      .describe(
+        "Specific design_files.id to export. Takes priority over designId/filename.",
+      ),
+    filename: z
+      .string()
+      .optional()
+      .default("index.html")
+      .describe(
+        "Filename to export when fileId is not provided. Defaults to index.html.",
+      ),
+    nodeId: z
+      .string()
+      .optional()
+      .describe(
+        "Scope the export to one element's subtree via its data-agent-native-node-id, " +
+          "instead of the whole screen.",
+      ),
+    embedImages: z
+      .boolean()
+      .optional()
+      .default(true)
+      .describe(
+        "Fetch and inline http(s) image sources/background-images as data: URIs, so the " +
+          "SVG is self-contained for clipboard paste. Set false to keep absolute URLs.",
+      ),
+    width: z.coerce
+      .number()
+      .int()
+      .positive()
+      .optional()
+      .describe(
+        "Render viewport width in px. Defaults to the screen's natural width or 1440.",
+      ),
+    height: z.coerce
+      .number()
+      .int()
+      .positive()
+      .optional()
+      .describe(
+        "Render viewport height in px. Defaults to the screen's natural height or 1200.",
+      ),
+  }),
+  readOnly: true,
+  http: { method: "POST" },
+  run: async ({
+    designId,
+    fileId,
+    filename,
+    nodeId,
+    embedImages,
+    width,
+    height,
+  }) => {
+    if (!designId && !fileId) {
+      throw new Error("designId or fileId is required.");
+    }
+
+    const db = getDb();
+    const conditions = [
+      accessFilter(schema.designs, schema.designShares),
+      fileId
+        ? eq(schema.designFiles.id, fileId)
+        : eq(schema.designFiles.designId, designId ?? ""),
+    ];
+    if (!fileId) {
+      conditions.push(
+        eq(schema.designFiles.filename, filename ?? "index.html"),
+      );
+    }
+
+    const [file] = await db
+      .select({
+        id: schema.designFiles.id,
+        designId: schema.designFiles.designId,
+        filename: schema.designFiles.filename,
+        fileType: schema.designFiles.fileType,
+        content: schema.designFiles.content,
+      })
+      .from(schema.designFiles)
+      .innerJoin(
+        schema.designs,
+        eq(schema.designFiles.designId, schema.designs.id),
+      )
+      .where(and(...conditions))
+      .limit(1);
+
+    if (!file) {
+      const err = new Error("Design file not found") as Error & {
+        statusCode: number;
+      };
+      err.statusCode = 404;
+      throw err;
+    }
+    if (file.fileType !== "html") {
+      throw new Error(
+        `export-design-as-figma-svg only supports HTML files (got "${file.fileType}").`,
+      );
+    }
+
+    const [designRow] = await db
+      .select({ title: schema.designs.title })
+      .from(schema.designs)
+      .where(eq(schema.designs.id, file.designId))
+      .limit(1);
+
+    const html = await liveContent(file.id, file.content ?? "");
+
+    let result: Awaited<ReturnType<typeof renderDesignToFigmaSvg>>;
+    try {
+      result = await renderDesignToFigmaSvg({
+        html,
+        width: width ?? 1440,
+        height: height ?? 1200,
+        title: designRow?.title ?? file.filename,
+        rootSelector: nodeId ? `[data-agent-native-node-id="${nodeId}"]` : null,
+        embedImages: embedImages ?? true,
+      });
+    } catch (err) {
+      if (isMissingBrowserError(err)) {
+        return { ok: false, reason: chromiumUnavailableReason(err) };
+      }
+      throw err;
+    }
+
+    const filenameOut = safeFigmaSvgFilename(designRow?.title ?? file.filename);
+    const saveResult = await trySaveExportFile(filenameOut, result.svg);
+
+    return {
+      ok: true,
+      designId: file.designId,
+      fileId: file.id,
+      filename: filenameOut,
+      svg: result.svg,
+      report: result.report,
+      ...saveResult,
+    };
+  },
+});

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()