@agent-native/core 0.92.11 → 0.93.0

package/corpus/templates/design/server/lib/local-figma-qa-upload.ts

@@ -0,0 +1,112 @@
+import { createHash, randomUUID } from "node:crypto";
+import { mkdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+
+import {
+  registerFileUploadProvider,
+  type FileUploadProvider,
+} from "@agent-native/core/server";
+
+const QA_UPLOAD_FLAG = "AGENT_NATIVE_DESIGN_QA_LOCAL_UPLOADS";
+const MAX_QA_ASSET_BYTES = 16 * 1024 * 1024;
+const QA_UPLOAD_ROOT = path.resolve(
+  "node_modules/.cache/agent-native-design/figma-qa-assets",
+);
+
+const MIME_EXTENSIONS = new Map([
+  ["image/png", "png"],
+  ["image/jpeg", "jpg"],
+  ["image/webp", "webp"],
+  ["image/gif", "gif"],
+  ["image/avif", "avif"],
+]);
+
+export function isLocalFigmaQaUploadEnabled(
+  env: NodeJS.ProcessEnv = process.env,
+): boolean {
+  return (
+    env.NODE_ENV !== "production" &&
+    /^(?:1|true)$/i.test(env[QA_UPLOAD_FLAG] ?? "")
+  );
+}
+
+function ownerDirectory(ownerEmail: string, rootDir = QA_UPLOAD_ROOT): string {
+  const ownerKey = createHash("sha256")
+    .update(ownerEmail.trim().toLowerCase())
+    .digest("hex")
+    .slice(0, 24);
+  return path.join(rootDir, ownerKey);
+}
+
+export function localFigmaQaAssetPath(
+  ownerEmail: string,
+  assetId: string,
+  rootDir = QA_UPLOAD_ROOT,
+): string | null {
+  if (!/^[a-f0-9-]{36}\.(?:png|jpg|webp|gif|avif)$/.test(assetId)) {
+    return null;
+  }
+  const ownerRoot = ownerDirectory(ownerEmail, rootDir);
+  const resolved = path.resolve(ownerRoot, assetId);
+  return resolved.startsWith(`${path.resolve(ownerRoot)}${path.sep}`)
+    ? resolved
+    : null;
+}
+
+export function localFigmaQaAssetMimeType(assetId: string): string | null {
+  const extension = path.extname(assetId).slice(1);
+  for (const [mimeType, candidate] of MIME_EXTENSIONS) {
+    if (candidate === extension) return mimeType;
+  }
+  return null;
+}
+
+export function createLocalFigmaQaUploadProvider(options?: {
+  rootDir?: string;
+  enabled?: () => boolean;
+}): FileUploadProvider {
+  const rootDir = options?.rootDir ?? QA_UPLOAD_ROOT;
+  const enabled = options?.enabled ?? isLocalFigmaQaUploadEnabled;
+  return {
+    id: "design-local-figma-qa",
+    name: "Design local Figma QA storage",
+    isConfigured: enabled,
+    upload: async ({ data, mimeType, ownerEmail }) => {
+      if (!enabled()) {
+        throw new Error("Local Figma QA storage is not enabled.");
+      }
+      if (!ownerEmail?.trim()) {
+        throw new Error(
+          "Local Figma QA storage requires an authenticated owner.",
+        );
+      }
+      const extension = MIME_EXTENSIONS.get(
+        (mimeType ?? "").split(";", 1)[0]!.trim().toLowerCase(),
+      );
+      if (!extension) {
+        throw new Error("Local Figma QA storage accepts image assets only.");
+      }
+      const bytes = data instanceof Uint8Array ? data : new Uint8Array(data);
+      if (bytes.byteLength === 0 || bytes.byteLength > MAX_QA_ASSET_BYTES) {
+        throw new Error("Local Figma QA asset size is outside the safe limit.");
+      }
+
+      const assetId = `${randomUUID()}.${extension}`;
+      const ownerRoot = ownerDirectory(ownerEmail, rootDir);
+      const filepath = localFigmaQaAssetPath(ownerEmail, assetId, rootDir);
+      if (!filepath)
+        throw new Error("Could not allocate a safe QA asset path.");
+      await mkdir(ownerRoot, { recursive: true, mode: 0o700 });
+      await writeFile(filepath, bytes, { flag: "wx", mode: 0o600 });
+      return {
+        id: assetId,
+        url: `/api/qa-figma-import-assets/${assetId}`,
+        provider: "design-local-figma-qa",
+      };
+    },
+  };
+}
+
+export function registerLocalFigmaQaUploadProvider(): void {
+  registerFileUploadProvider(createLocalFigmaQaUploadProvider());
+}

package/corpus/templates/design/server/lib/verify-write-grant.ts

@@ -36,6 +36,20 @@ export interface WriteGrantResult {
   grantId: string;
 }
 
+/**
+ * Safe client-facing precondition error. The action HTTP surface only returns
+ * messages for explicit 4xx errors; without this status the Code workbench
+ * receives a generic 500 and cannot open the human consent dialog.
+ */
+export class WriteConsentRequiredError extends Error {
+  readonly statusCode = 428;
+
+  constructor(message: string) {
+    super(message);
+    this.name = "WriteConsentRequiredError";
+  }
+}
+
 /**
  * Resolve the active write-consent grant for a given design + connection.
  * Throws if no valid grant exists or the target path escapes rootPath.
@@ -62,7 +76,7 @@ export async function verifyWriteGrant(
     .limit(1);
 
   if (!grant) {
-    throw new Error(
+    throw new WriteConsentRequiredError(
       "No localhost write-consent grant found for this design + connection. " +
         "Call request-localhost-write-consent to prompt the user, then retry " +
         "this write after they click 'Allow writes'.",
@@ -71,7 +85,7 @@ export async function verifyWriteGrant(
 
   const now = new Date().toISOString();
   if (grant.grantedUntil < now) {
-    throw new Error(
+    throw new WriteConsentRequiredError(
       `Localhost write-consent grant expired at ${grant.grantedUntil}. ` +
         "Call request-localhost-write-consent to prompt the user for a new " +
         "grant, then retry this write.",

package/corpus/templates/design/server/lib/visible-clipboard-html.ts

@@ -1,4 +1,5 @@
-const MAX_CLIPBOARD_HTML_BYTES = 2 * 1024 * 1024;
+const MAX_RAW_CLIPBOARD_HTML_BYTES = 64 * 1024 * 1024;
+const MAX_VISIBLE_CLIPBOARD_HTML_BYTES = 2 * 1024 * 1024;
 
 function byteLength(value: string): number {
   return Buffer.byteLength(value, "utf8");
@@ -14,6 +15,8 @@ function removeHiddenClipboardData(html: string): string {
       /<span\b[^>]*\bdata-buffer\s*=\s*(["'])[\s\S]*?\1[^>]*>\s*<\/span>/gi,
       "",
     )
+    .replace(/<!--\s*\((figmeta|figma)\)[\s\S]*?\(\/\1\)\s*-->/gi, "")
+    .replace(/&lt;!--\s*\((figmeta|figma)\)[\s\S]*?\(\/\1\)\s*--&gt;/gi, "")
     .replace(/<meta\b[^>]*charset[^>]*>/gi, "")
     .trim();
 }
@@ -21,11 +24,18 @@ function removeHiddenClipboardData(html: string): string {
 export function parseVisibleClipboardHtml(html: string): {
   fallbackHtml?: string;
 } {
-  if (byteLength(html) > MAX_CLIPBOARD_HTML_BYTES) {
-    throw new Error("Clipboard HTML is too large to import (max 2 MB).");
+  if (byteLength(html) > MAX_RAW_CLIPBOARD_HTML_BYTES) {
+    throw new Error(
+      "Clipboard transfer data is too large to import (max 64 MB).",
+    );
   }
 
   const fallbackHtml = removeHiddenClipboardData(html);
+  if (byteLength(fallbackHtml) > MAX_VISIBLE_CLIPBOARD_HTML_BYTES) {
+    throw new Error(
+      "Visible clipboard HTML is too large to import (max 2 MB).",
+    );
+  }
   return {
     fallbackHtml: fallbackHtml || undefined,
   };

package/corpus/templates/design/server/plugins/agent-chat.ts

@@ -13,9 +13,12 @@ const DESIGN_BACKGROUND_RUN_NO_PROGRESS_TIMEOUT_MS = 12 * 60_000;
 const INITIAL_TOOL_NAMES = [
   "view-screen",
   "list-designs",
+  "list-design-templates",
   "get-design",
   "get-design-snapshot",
   "create-design",
+  "create-design-from-template",
+  "save-design-as-template",
   "open-visual-edit",
   "add-localhost-screens",
   "list-localhost-connections",
@@ -51,6 +54,8 @@ export default createAgentChatPlugin({
 
 When the user asks for a new design and the current navigation view is list, settings, design-systems, or otherwise has no designId, create a new design first. Do not reuse, delete screens from, or edit a previous design unless the user explicitly names that design or the current navigation state is an editor/present view with that designId.
 
+When the user asks to start from a template, call list-design-templates and then create-design-from-template. The copied files and canvas dimensions are already the starting point. If the user also supplied a prompt, call get-design-snapshot once and refine unlocked content with edit-design; do not call generate-design or replace the template with a fresh screen. Layers marked data-agent-native-locked="true" and their descendants must remain byte-for-byte unchanged. Ask the user to unlock one explicitly if they want it changed.
+
 When the user asks you to refine an existing design, call view-screen if the open design is unclear, then read the live current file with get-design-snapshot before editing. For small localized changes, call edit-design with exact search/replace edits. For broad copy-only changes such as translating all visible text, call edit-design in replace-file mode with the complete updated file content from the snapshot so the HTML structure, scripts, styles, and tweaks are preserved without dozens of fragile search blocks. Do not claim the design is updated until the mutating action succeeds.
 
 When the user picks one direction from a set of presented variants, delete each unchosen variant screen at most once, then call get-design-snapshot exactly once for the kept screen's fileId and call edit-design on that same fileId. Use edit-design replace-file when expanding the placeholder into a complete but compact product UI in the chosen direction. Prioritize the primary workflow and render secondary details as visible controls, states, or affordances if the feature list is too large for one reliable edit. Do not call generate-design after a variant pick unless the user explicitly asks to create a separate new screen.
@@ -61,5 +66,7 @@ Provider-specific Design actions are shortcuts, not limits. If a first-class act
 
 Design's GitHub provider API uses the saved GITHUB_TOKEN secret when present. Never ask the user to paste tokens into chat. For large GitHub search results or repository scans, pass stageAs and pagination options to provider-api-request, then use query-staged-dataset to count, filter, group, or project the staged rows.
 
+Design's Figma integration uses the saved, user-scoped FIGMA_ACCESS_TOKEN secret; never ask for the token in chat or pass it as an action argument. Use import-figma-frame for a frame/layer link and import-figma-clipboard for Figma Cmd+C metadata. Current clipboard metadata includes exact selected node ids and supports multi-selection; if Figma changes that private field, fall back conservatively and recommend "Copy link to selection." Use provider-api-catalog/docs/request for open-ended reads of files, nodes, components, styles, images, comments, versions, and Enterprise variables. Figma REST cannot create arbitrary canvas frames/layers. For Design-to-Figma handoff use export-design-as-figma-svg / Copy as SVG, or Figma's official OAuth MCP write tools when they are actually connected. Never claim SVG preserves live text, auto-layout, components, variables, or prototype behavior; report the export/import fidelity caveats.
+
 For raster image generation, use available first-party Assets MCP tools such as generate-asset instead of placeholders or generic stock-image descriptions. When the Assets picker returns selectedAsset/chooseAsset/chooseImage context while a design is open, call insert-asset with the chosen asset URL/id, then refine placement with normal Design edit tools if needed. Preserve Assets assetId, runId, and URLs verbatim.`,
 });

package/corpus/templates/design/server/plugins/db.ts

@@ -342,6 +342,48 @@ ALTER TABLE design_files ADD COLUMN IF NOT EXISTS content_operation_result_hash
       name: "design-localhost-preview-token",
       sql: `ALTER TABLE design_localhost_connections ADD COLUMN IF NOT EXISTS preview_token TEXT`,
     },
+    {
+      version: 23,
+      name: "design-templates",
+      sql: `CREATE TABLE IF NOT EXISTS design_templates (
+    id TEXT PRIMARY KEY,
+    title TEXT NOT NULL,
+    description TEXT,
+    category TEXT NOT NULL DEFAULT 'other',
+    source_design_id TEXT,
+    design_system_id TEXT,
+    data TEXT NOT NULL DEFAULT '{}',
+    width INTEGER,
+    height INTEGER,
+    locked_layer_count INTEGER NOT NULL DEFAULT 0,
+    created_at TEXT DEFAULT (datetime('now')),
+    updated_at TEXT DEFAULT (datetime('now')),
+    owner_email TEXT NOT NULL DEFAULT 'local@localhost',
+    org_id TEXT,
+    visibility TEXT NOT NULL DEFAULT 'private'
+  );
+CREATE TABLE IF NOT EXISTS design_template_shares (
+    id TEXT PRIMARY KEY,
+    resource_id TEXT NOT NULL,
+    principal_type TEXT NOT NULL,
+    principal_id TEXT NOT NULL,
+    role TEXT NOT NULL DEFAULT 'viewer',
+    created_by TEXT NOT NULL,
+    created_at TEXT NOT NULL DEFAULT (datetime('now'))
+  );
+CREATE TABLE IF NOT EXISTS design_template_files (
+    id TEXT PRIMARY KEY,
+    template_id TEXT NOT NULL,
+    filename TEXT NOT NULL,
+    content TEXT NOT NULL,
+    file_type TEXT NOT NULL DEFAULT 'html',
+    created_at TEXT DEFAULT (datetime('now')),
+    updated_at TEXT DEFAULT (datetime('now'))
+  );
+CREATE INDEX IF NOT EXISTS design_templates_owner_org_updated_idx ON design_templates (owner_email, org_id, updated_at);
+CREATE INDEX IF NOT EXISTS design_template_shares_resource_principal_idx ON design_template_shares (resource_id, principal_type, principal_id);
+CREATE INDEX IF NOT EXISTS design_template_files_template_idx ON design_template_files (template_id, updated_at)`,
+    },
   ],
   { table: "design_migrations" },
 );

package/corpus/templates/design/server/plugins/local-figma-qa-upload.ts

@@ -0,0 +1,7 @@
+import { defineNitroPlugin } from "@agent-native/core/server";
+
+import { registerLocalFigmaQaUploadProvider } from "../lib/local-figma-qa-upload.js";
+
+export default defineNitroPlugin(() => {
+  registerLocalFigmaQaUploadProvider();
+});

package/corpus/templates/design/server/register-secrets.ts

@@ -35,23 +35,23 @@ registerRequiredSecret({
         };
       }
       return { ok: false, error: `GitHub returned ${res.status}.` };
-    } catch (err: any) {
+    } catch {
       return {
         ok: false,
-        error: `Could not reach GitHub: ${err?.message ?? err}`,
+        error: "Could not reach GitHub. Check your network and try again.",
       };
     }
   },
 });
 
-// Optional: enables browsing reusable Figma components/component sets in the
-// Design asset rail. The provider API injects this server-side as
+// Optional: connects Figma frame import, library browsing, and open-ended REST
+// reads in agent chat. The provider API injects this server-side as
 // X-Figma-Token; never pass it through action parameters or chat.
 registerRequiredSecret({
   key: "FIGMA_ACCESS_TOKEN",
   label: "Figma access token",
   description:
-    "Optional. Enables browsing and inserting Figma library components from files you can access.",
+    "Connect Figma frame links, exact clipboard paste, libraries, styles, and open-ended agent queries. Generate a personal access token with current_user:read and file_content:read; add library_content:read for file libraries, team_library_content:read for team libraries, or Enterprise file_variables:read only when needed.",
   docsUrl: "https://developers.figma.com/docs/rest-api/personal-access-tokens/",
   scope: "user",
   kind: "api-key",
@@ -69,14 +69,14 @@ registerRequiredSecret({
       if (res.status === 401 || res.status === 403) {
         return {
           ok: false,
-          error: `Figma rejected this token (${res.status}). Check that it is active and has access to the file.`,
+          error: `Figma rejected this token (${res.status}). Check that it is active and includes current_user:read; frame import also needs file_content:read.`,
         };
       }
       return { ok: false, error: `Figma returned ${res.status}.` };
-    } catch (err: any) {
+    } catch {
       return {
         ok: false,
-        error: `Could not reach Figma: ${err?.message ?? err}`,
+        error: "Could not reach Figma. Check your network and try again.",
       };
     }
   },

package/corpus/templates/design/server/routes/api/qa-figma-import-assets/[assetId].get.ts

@@ -0,0 +1,46 @@
+import { createReadStream } from "node:fs";
+import { stat } from "node:fs/promises";
+
+import { getSession, streamFile } from "@agent-native/core/server";
+import { defineEventHandler, getRouterParam, setResponseStatus } from "h3";
+
+import {
+  isLocalFigmaQaUploadEnabled,
+  localFigmaQaAssetMimeType,
+  localFigmaQaAssetPath,
+} from "../../../lib/local-figma-qa-upload.js";
+
+export default defineEventHandler(async (event) => {
+  if (!isLocalFigmaQaUploadEnabled()) {
+    setResponseStatus(event, 404);
+    return { error: "Not found" };
+  }
+  const session = await getSession(event).catch(() => null);
+  if (!session?.email) {
+    setResponseStatus(event, 401);
+    return { error: "Unauthorized" };
+  }
+
+  const assetId = getRouterParam(event, "assetId") ?? "";
+  const filepath = localFigmaQaAssetPath(session.email, assetId);
+  const mimeType = localFigmaQaAssetMimeType(assetId);
+  if (!filepath || !mimeType) {
+    setResponseStatus(event, 400);
+    return { error: "Invalid asset id" };
+  }
+  try {
+    const info = await stat(filepath);
+    if (!info.isFile()) throw new Error("not a file");
+  } catch {
+    setResponseStatus(event, 404);
+    return { error: "Not found" };
+  }
+
+  event.node!.res!.setHeader("Content-Type", mimeType);
+  event.node!.res!.setHeader(
+    "Cache-Control",
+    "private, max-age=31536000, immutable",
+  );
+  event.node!.res!.setHeader("X-Content-Type-Options", "nosniff");
+  return streamFile(createReadStream(filepath));
+});

package/corpus/templates/design/server/source-workspace.ts

@@ -5,9 +5,11 @@ import {
   seedFromText,
 } from "@agent-native/core/collab";
 import { assertAccess, resolveAccess } from "@agent-native/core/sharing";
-import { eq } from "drizzle-orm";
+import { and, eq, isNull } from "drizzle-orm";
 
 import { isBoardFile } from "../shared/board-file.js";
+import { assertDesignHtmlEditIntegrity } from "../shared/html-integrity.js";
+import { assertLockedLayersPreserved } from "../shared/locked-layers.js";
 import { designSourceTypeFromData } from "../shared/source-mode.js";
 import type { DesignSourceType } from "../shared/source-mode.js";
 import {
@@ -49,6 +51,31 @@ export interface SourceWorkspaceFile {
 // the expectedVersionHash guard — never silently clobbered.
 const _writeLocks = new Map<string, Promise<void>>();
 
+/**
+ * Normalize affected-row metadata from every createGetDb backend: libSQL,
+ * PGlite, Neon, postgres.js, better-sqlite3, and D1.
+ */
+function affectedRowCount(result: unknown): number | undefined {
+  const candidate = result as
+    | {
+        rowsAffected?: unknown;
+        affectedRows?: unknown;
+        rowCount?: unknown;
+        count?: unknown;
+        changes?: unknown;
+        meta?: { changes?: unknown };
+      }
+    | undefined;
+  const value =
+    candidate?.rowsAffected ??
+    candidate?.affectedRows ??
+    candidate?.rowCount ??
+    candidate?.count ??
+    candidate?.changes ??
+    candidate?.meta?.changes;
+  return typeof value === "number" ? value : undefined;
+}
+
 // Exported so other write paths touching the same per-file critical section
 // (content read -> optimistic-concurrency hash check -> collab/SQL write) can
 // serialize under the SAME lock instead of each guarding independently. Two
@@ -57,15 +84,11 @@ const _writeLocks = new Map<string, Promise<void>>();
 // prevent the interleave, only serializing the whole read-check-write section
 // per file id does. See actions/update-file.ts's content-write path.
 //
-// IN-PROCESS ONLY: `_writeLocks` is a plain JS `Map`, so this only serializes
-// writes within a single Node.js process/worker. Multi-instance / horizontally
-// scaled hosted deployments (several server processes/pods behind a load
-// balancer) do NOT share this lock — two requests routed to DIFFERENT
-// processes can still race past each other, since each process has its own
-// independent `_writeLocks` Map. A real cross-process guard would need
-// something like a Postgres/SQL advisory lock (e.g. `pg_advisory_lock`) or a
-// distributed lock service, keyed by file id, shared across all instances.
-// This is a known, tracked follow-up — not implemented here.
+// `_writeLocks` is intentionally only a fast in-process serialization layer.
+// Cross-process correctness comes from the content + updatedAt SQL CAS in
+// writeInlineSourceFile (and the operation-lineage CAS in update-file): a
+// different instance that commits first makes the losing update affect zero
+// rows, so it is rejected instead of overwriting the winner.
 export async function withSourceFileWriteLock<T>(
   fileId: string,
   fn: () => Promise<T>,
@@ -320,6 +343,19 @@ export async function writeInlineSourceFile(args: {
       };
     }
 
+    if (
+      currentFile.fileType === "html" ||
+      currentFile.fileType === "jsx" ||
+      current.content.includes("data-agent-native-locked")
+    ) {
+      assertLockedLayersPreserved(current.content, args.content);
+    }
+    assertDesignHtmlEditIntegrity({
+      previousContent: current.content,
+      nextContent: args.content,
+      fileType: currentFile.fileType ?? args.file.fileType ?? "html",
+    });
+
     if (await hasCollabState(args.file.id)) {
       const liveBeforeApply = await getText(args.file.id, "content");
       if (
@@ -353,8 +389,25 @@ export async function writeInlineSourceFile(args: {
     // true mirror of the converged live document under the lock rather than
     // trusting args.content directly.
     const authoritativeContent = await getText(args.file.id, "content");
+    try {
+      assertDesignHtmlEditIntegrity({
+        previousContent: current.content,
+        nextContent: authoritativeContent,
+        fileType: currentFile.fileType ?? args.file.fileType ?? "html",
+      });
+    } catch (error) {
+      // `applyText` is a full-target diff, but keep the write transaction
+      // fail-closed even if a malformed/concurrent collab state somehow
+      // converges to something other than the validated candidate. Restore
+      // the exact pre-write live content before SQL can observe corruption.
+      await applyText(args.file.id, current.content, "content", "agent");
+      throw error;
+    }
 
-    await db
+    // The JS lock is process-local. Guard the SQL mirror with the exact
+    // content + revision read above so a writer on another instance cannot
+    // commit between our read/live-doc mutation and this final persistence.
+    const updateResult = await db
       .update(schema.designFiles)
       .set({
         content: authoritativeContent,
@@ -366,7 +419,46 @@ export async function writeInlineSourceFile(args: {
         contentOperationRevision: null,
         contentOperationResultHash: null,
       })
-      .where(eq(schema.designFiles.id, args.file.id));
+      .where(
+        and(
+          eq(schema.designFiles.id, args.file.id),
+          eq(schema.designFiles.designId, args.designId),
+          eq(schema.designFiles.content, currentFile.content),
+          currentFile.updatedAt === null
+            ? isNull(schema.designFiles.updatedAt)
+            : eq(schema.designFiles.updatedAt, currentFile.updatedAt),
+        ),
+      );
+
+    const affected = affectedRowCount(updateResult);
+    let persisted = affected === 1;
+    if (affected === undefined) {
+      const [confirmed] = await db
+        .select({
+          content: schema.designFiles.content,
+          updatedAt: schema.designFiles.updatedAt,
+        })
+        .from(schema.designFiles)
+        .where(eq(schema.designFiles.id, args.file.id))
+        .limit(1);
+      persisted =
+        confirmed?.content === authoritativeContent &&
+        confirmed.updatedAt === updatedAt;
+    }
+
+    if (!persisted) {
+      const [winner] = await db
+        .select({ content: schema.designFiles.content })
+        .from(schema.designFiles)
+        .where(eq(schema.designFiles.id, args.file.id))
+        .limit(1);
+      if (winner && winner.content !== authoritativeContent) {
+        await applyText(args.file.id, winner.content, "content", "agent");
+      }
+      throw new SourceWorkspaceEditConflictError(
+        "Source file changed while it was being saved. Re-read the file and retry.",
+      );
+    }
 
     await db
       .update(schema.designs)