@agent-native/core 0.92.12 → 0.93.0

package/corpus/templates/design/actions/create-design-from-template.ts

@@ -0,0 +1,220 @@
+import { defineAction, embedApp } from "@agent-native/core";
+import { buildDeepLink } from "@agent-native/core/server";
+import {
+  getRequestOrgId,
+  getRequestUserEmail,
+} from "@agent-native/core/server/request-context";
+import { assertAccess, resolveAccess } from "@agent-native/core/sharing";
+import { eq } from "drizzle-orm";
+import { nanoid } from "nanoid";
+import { z } from "zod";
+
+import { getDb, schema } from "../server/db/index.js";
+import {
+  redactTemplateDesignData,
+  remapTemplateFileIds,
+} from "../server/lib/design-template-data.js";
+import { getDesignTemplatePreset } from "../shared/design-template-presets.js";
+import { countLockedLayersAcrossFiles } from "../shared/locked-layers.js";
+import { annotateScreenHtmlForPersist } from "../shared/screen-annotation.js";
+import { sourceContentHash } from "../shared/source-workspace.js";
+
+interface TemplateFile {
+  id: string;
+  filename: string;
+  fileType: string;
+  content: string;
+}
+
+export default defineAction({
+  description:
+    "Create an editable design from a reusable template. The action copies the template files, exact dimensions, defaults, and locked layers. " +
+    "When a prompt is supplied, refine the copied files with get-design-snapshot and edit-design; do not replace the template with generate-design.",
+  schema: z.object({
+    templateId: z.string().min(1).describe("Template or starter template ID"),
+    title: z.string().trim().min(1).max(120).optional(),
+    prompt: z
+      .string()
+      .trim()
+      .max(4_000)
+      .optional()
+      .describe("Optional refinement request to apply after copying"),
+    designSystemId: z
+      .string()
+      .min(1)
+      .nullable()
+      .optional()
+      .describe("Override the template design system, or null to unlink"),
+  }),
+  mcpApp: {
+    compactCatalog: true,
+    resource: embedApp({
+      title: "Design from template",
+      description: "Open the copied template in the Design editor.",
+      iframeTitle: "Agent-Native Design",
+      openLabel: "Open design",
+      height: 680,
+    }),
+  },
+  run: async ({ templateId, title, prompt, designSystemId }) => {
+    const preset = getDesignTemplatePreset(templateId);
+    const db = getDb();
+
+    let templateTitle: string;
+    let templateDescription: string | null;
+    let templateCategory: string;
+    let templateData: string;
+    let templateDesignSystemId: string | null;
+    let templateUpdatedAt: string | null;
+    let files: TemplateFile[];
+
+    if (preset) {
+      const presetFileId = `file:${preset.id}`;
+      templateTitle = preset.title;
+      templateDescription = preset.description;
+      templateCategory = preset.category;
+      templateDesignSystemId = null;
+      templateUpdatedAt = null;
+      templateData = JSON.stringify({
+        canvasFrames: {
+          [presetFileId]: {
+            x: 0,
+            y: 0,
+            width: preset.width,
+            height: preset.height,
+          },
+        },
+      });
+      files = [
+        {
+          id: presetFileId,
+          filename: preset.filename,
+          fileType: "html",
+          content: preset.content,
+        },
+      ];
+    } else {
+      const access = await resolveAccess("design-template", templateId);
+      if (!access) throw new Error("Template not found");
+      const template = access.resource;
+      templateTitle = String(template.title ?? "Untitled template");
+      templateDescription =
+        typeof template.description === "string" ? template.description : null;
+      templateCategory = String(template.category ?? "other");
+      templateData = typeof template.data === "string" ? template.data : "{}";
+      templateDesignSystemId =
+        typeof template.designSystemId === "string"
+          ? template.designSystemId
+          : null;
+      templateUpdatedAt =
+        typeof template.updatedAt === "string" ? template.updatedAt : null;
+      files = await db
+        .select({
+          id: schema.designTemplateFiles.id,
+          filename: schema.designTemplateFiles.filename,
+          fileType: schema.designTemplateFiles.fileType,
+          content: schema.designTemplateFiles.content,
+        })
+        .from(schema.designTemplateFiles)
+        .where(eq(schema.designTemplateFiles.templateId, templateId));
+    }
+
+    if (files.length === 0) throw new Error("Template has no files");
+
+    let linkedDesignSystemId =
+      designSystemId === undefined ? templateDesignSystemId : designSystemId;
+    if (linkedDesignSystemId) {
+      try {
+        await assertAccess("design-system", linkedDesignSystemId, "viewer");
+      } catch {
+        if (designSystemId !== undefined)
+          throw new Error("Design system not found");
+        linkedDesignSystemId = null;
+      }
+    }
+
+    const ownerEmail = getRequestUserEmail();
+    if (!ownerEmail) throw new Error("Not authenticated");
+    const orgId = getRequestOrgId() ?? null;
+    const designId = nanoid();
+    const now = new Date().toISOString();
+    const fileIdMap = new Map(files.map((file) => [file.id, nanoid()]));
+    const data = remapTemplateFileIds(
+      redactTemplateDesignData(templateData),
+      fileIdMap,
+    );
+    data.templateSource = {
+      templateId,
+      title: templateTitle,
+      category: templateCategory,
+      templateUpdatedAt,
+      instantiatedAt: now,
+    };
+    if (prompt) data.templatePrompt = prompt;
+
+    const persistedFiles = files.map((file) => ({
+      ...file,
+      id: fileIdMap.get(file.id)!,
+      content: annotateScreenHtmlForPersist(file.content, file.fileType),
+    }));
+
+    await db.transaction(async (tx) => {
+      await tx.insert(schema.designs).values({
+        id: designId,
+        title: title ?? templateTitle,
+        description: templateDescription,
+        data: JSON.stringify(data),
+        projectType: "prototype",
+        designSystemId: linkedDesignSystemId,
+        ownerEmail,
+        orgId,
+        visibility: orgId ? "org" : "private",
+        createdAt: now,
+        updatedAt: now,
+      });
+      await tx.insert(schema.designFiles).values(
+        persistedFiles.map((file) => ({
+          id: file.id,
+          designId,
+          filename: file.filename,
+          fileType: file.fileType,
+          content: file.content,
+          createdAt: now,
+          updatedAt: now,
+        })),
+      );
+    });
+
+    return {
+      id: designId,
+      title: title ?? templateTitle,
+      templateId,
+      templateTitle,
+      fileCount: files.length,
+      lockedLayerCount: countLockedLayersAcrossFiles(persistedFiles),
+      templateBaselineFiles: persistedFiles.map((file) => ({
+        id: file.id,
+        contentHash: sourceContentHash(file.content),
+      })),
+      promptPending: Boolean(prompt),
+      nextRequiredAction: prompt
+        ? "Call get-design-snapshot, then refine unlocked content with edit-design. Do not call generate-design."
+        : null,
+    };
+  },
+  link: ({ result }) => {
+    if (!result || typeof result !== "object") return null;
+    const id = (result as { id?: string }).id;
+    if (!id) return null;
+    return {
+      url: buildDeepLink({
+        app: "design",
+        view: "editor",
+        params: { designId: id },
+        to: `/design/${encodeURIComponent(id)}`,
+      }),
+      label: "Open design",
+      view: "editor",
+    };
+  },
+});

package/corpus/templates/design/actions/create-design-system.ts

@@ -8,17 +8,27 @@ import { nanoid } from "nanoid";
 import { z } from "zod";
 
 import { getDb, schema } from "../server/db/index.js";
+import {
+  DESIGN_SYSTEM_TEMPLATE_IDS,
+  getProductionDesignSystemTemplate,
+} from "../shared/design-system-templates.js";
 
-export default defineAction({
-  description:
-    "Create a new design system with brand colors, typography, spacing, and other design tokens. " +
-    "If this is the first design system for the user, it is automatically set as the default.",
-  schema: z.object({
+export const createDesignSystemSchema = z
+  .object({
+    templateId: z
+      .enum(DESIGN_SYSTEM_TEMPLATE_IDS)
+      .optional()
+      .describe(
+        "Optional production design-system template to copy: material-3, carbon-white, or primer-light",
+      ),
     title: z
       .string()
       .trim()
       .min(1, "title is required")
-      .describe("Design system name (e.g. 'Acme Corp Brand')"),
+      .optional()
+      .describe(
+        "Design system name (required without templateId; optional title override for a template)",
+      ),
     description: z
       .string()
       .optional()
@@ -27,8 +37,9 @@ export default defineAction({
       .string()
       .trim()
       .min(1, "data is required")
+      .optional()
       .describe(
-        "JSON string of DesignSystemData (colors, typography, spacing, etc.)",
+        "JSON string of DesignSystemData (required without templateId; templates supply their verified token snapshot)",
       ),
     assets: z
       .string()
@@ -38,13 +49,71 @@ export default defineAction({
       .string()
       .optional()
       .describe(
-        "Free-form guidance the agent should follow whenever it generates designs using this design system (tone, voice, layout preferences, dos and don'ts).",
+        "Free-form guidance the agent should follow whenever it generates designs using this design system (tone, voice, layout preferences, dos and don'ts). For templates, this is appended to the system's built-in guidance.",
       ),
-  }),
-  run: async ({ title, description, data, assets, customInstructions }) => {
+  })
+  .superRefine((value, ctx) => {
+    if (!value.templateId && !value.title) {
+      ctx.addIssue({
+        code: "custom",
+        path: ["title"],
+        message: "title is required without templateId",
+      });
+    }
+    if (!value.templateId && !value.data) {
+      ctx.addIssue({
+        code: "custom",
+        path: ["data"],
+        message: "data is required without templateId",
+      });
+    }
+    if (value.templateId && value.data) {
+      ctx.addIssue({
+        code: "custom",
+        path: ["data"],
+        message: "data cannot override a production template snapshot",
+      });
+    }
+  });
+
+export default defineAction({
+  description:
+    "Create a design system from custom tokens or copy a source-linked production template (Material Design 3, Carbon, or Primer). " +
+    "If this is the first design system for the user, it is automatically set as the default.",
+  schema: createDesignSystemSchema,
+  run: async ({
+    templateId,
+    title,
+    description,
+    data,
+    assets,
+    customInstructions,
+  }) => {
+    const template = templateId
+      ? getProductionDesignSystemTemplate(templateId)
+      : undefined;
+    const resolvedTitle = title ?? template?.title;
+    const resolvedDescription = description ?? template?.description;
+    const resolvedData =
+      data ?? (template ? JSON.stringify(template.data) : "");
+    const resolvedInstructions = template
+      ? [
+          template.customInstructions,
+          customInstructions?.trim()
+            ? `Additional guidance:\n${customInstructions.trim()}`
+            : "",
+        ]
+          .filter(Boolean)
+          .join("\n\n")
+      : (customInstructions ?? "");
+
+    if (!resolvedTitle || !resolvedData) {
+      throw new Error("title and data are required");
+    }
+
     // Validate that data is valid JSON and not an empty primitive.
     try {
-      const parsed = JSON.parse(data);
+      const parsed = JSON.parse(resolvedData);
       if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
         throw new Error();
       }
@@ -89,11 +158,11 @@ export default defineAction({
 
     await db.insert(schema.designSystems).values({
       id,
-      title,
-      description: description ?? null,
-      data,
+      title: resolvedTitle,
+      description: resolvedDescription ?? null,
+      data: resolvedData,
       assets: assets ?? null,
-      customInstructions: customInstructions ?? "",
+      customInstructions: resolvedInstructions,
       isDefault,
       ownerEmail,
       orgId,
@@ -101,6 +170,13 @@ export default defineAction({
       updatedAt: now,
     });
 
-    return { id, title, isDefault };
+    return {
+      id,
+      title: resolvedTitle,
+      isDefault,
+      templateId: template?.id,
+      sourceUrl: template?.sourceUrl,
+      version: template?.version,
+    };
   },
 });

package/corpus/templates/design/actions/delete-design-template.ts

@@ -0,0 +1,28 @@
+import { defineAction } from "@agent-native/core";
+import { assertAccess } from "@agent-native/core/sharing";
+import { eq } from "drizzle-orm";
+import { z } from "zod";
+
+import { getDb, schema } from "../server/db/index.js";
+
+export default defineAction({
+  description:
+    "Delete a saved Design template owned or administered by the user.",
+  schema: z.object({ id: z.string().min(1).describe("Saved template ID") }),
+  run: async ({ id }) => {
+    await assertAccess("design-template", id, "admin");
+    const db = getDb();
+    await db.transaction(async (tx) => {
+      await tx
+        .delete(schema.designTemplateShares)
+        .where(eq(schema.designTemplateShares.resourceId, id));
+      await tx
+        .delete(schema.designTemplateFiles)
+        .where(eq(schema.designTemplateFiles.templateId, id));
+      await tx
+        .delete(schema.designTemplates)
+        .where(eq(schema.designTemplates.id, id));
+    });
+    return { id, deleted: true };
+  },
+});

package/corpus/templates/design/actions/delete-file.ts

@@ -5,6 +5,7 @@ import { z } from "zod";
 
 import { getDb, schema } from "../server/db/index.js";
 import { mutateDesignData } from "../server/lib/design-data-mutation.js";
+import { countLockedLayers } from "../shared/locked-layers.js";
 
 function isRecord(value: unknown): value is Record<string, unknown> {
   return Boolean(value && typeof value === "object" && !Array.isArray(value));
@@ -73,6 +74,7 @@ export default defineAction({
       .select({
         id: schema.designFiles.id,
         designId: schema.designFiles.designId,
+        content: schema.designFiles.content,
       })
       .from(schema.designFiles)
       .innerJoin(
@@ -90,6 +92,11 @@ export default defineAction({
     if (!file) return { id, deleted: false, alreadyMissing: true };
 
     await assertAccess("design", file.designId, "editor");
+    if (countLockedLayers(file.content) > 0) {
+      throw new Error(
+        "This screen contains locked layers. Unlock them before deleting the screen.",
+      );
+    }
 
     const pruneMetadata = () =>
       mutateDesignData({

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

@@ -19,6 +19,7 @@ import {
   type ApplyEditsResult,
   type DesignEdit,
 } from "../shared/apply-edits.js";
+import { assertLockedLayersPreserved } from "../shared/locked-layers.js";
 
 const editBlocksSchema = z.preprocess(
   (v) => {
@@ -296,6 +297,8 @@ export default defineAction({
     const changed = nextContent !== base;
 
     if (changed) {
+      assertLockedLayersPreserved(base, nextContent);
+
       // Mark agent presence + selection so live viewers can see where the
       // agent is working before the update arrives via collab.
       //

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

@@ -25,10 +25,13 @@ import { z } from "zod";
 import { getDb, schema } from "../server/db/index.js";
 import { trySaveExportFile } from "../server/lib/design-export.js";
 import {
+  isMissingRootSelectorError,
   renderDesignToFigmaSvg,
   safeFigmaSvgFilename,
 } from "../server/lib/design-to-figma-svg.js";
 import { isMissingBrowserError } from "../server/lib/playwright-runtime.js";
+import { parseCanvasFrameGeometryById } from "../shared/canvas-frames.js";
+import { buildCodeLayerProjection } from "../shared/code-layer.js";
 import "../server/db/index.js"; // ensure registerShareableResource runs
 
 async function liveContent(
@@ -59,6 +62,71 @@ export function chromiumUnavailableReason(err: unknown): string {
   );
 }
 
+export function figmaSvgNodeSelector(nodeId: string): string {
+  const escaped = nodeId
+    .replace(/\\/g, "\\\\")
+    .replace(/"/g, '\\"')
+    .replace(/\r?\n/g, "\\a ");
+  return `[data-agent-native-node-id="${escaped}"]`;
+}
+
+export interface FigmaSvgNodeResolution {
+  rootSelector: string | null;
+  warning?: string;
+}
+
+/**
+ * Resolves a caller-supplied `nodeId` against the PERSISTED html this export
+ * actually renders, before ever touching a browser. Canvas selections mint
+ * live-DOM code-layer ids like `html:<hash>` (see `shared/code-layer.ts`'s
+ * `nodeIdFor`) that never literally exist in stored markup as a
+ * `data-agent-native-node-id` attribute — passing one straight into
+ * `figmaSvgNodeSelector` builds a selector that matches nothing in the
+ * rendered page, which previously surfaced as an unhandled 500
+ * ("No element matched rootSelector ..."). Re-parsing the SAME persisted
+ * HTML through the same code-layer projection (mirrors
+ * `resolve-selection-source.ts` / `apply-visual-edit`'s target resolution)
+ * recomputes the same deterministic ids/selectors, so a live id minted from
+ * this content resolves to the same node without needing a live browser for
+ * this step. Returns `rootSelector: null` (whole-screen export) with a
+ * `warning` when the id can't be resolved at all — callers should surface
+ * that warning in the export report instead of throwing.
+ */
+export function resolveFigmaSvgNodeSelector(
+  html: string,
+  nodeId: string,
+  source: { designId?: string; fileId?: string; filename?: string },
+): FigmaSvgNodeResolution {
+  const projection = buildCodeLayerProjection(html, {
+    source: {
+      kind: "design-file",
+      designId: source.designId,
+      fileId: source.fileId,
+      filename: source.filename,
+    },
+  });
+  const node = projection.nodes.find(
+    (candidate) =>
+      candidate.id === nodeId ||
+      candidate.dataAttributes["data-agent-native-node-id"] === nodeId ||
+      candidate.dataAttributes["data-code-layer-id"] === nodeId,
+  );
+  if (!node) {
+    return {
+      rootSelector: null,
+      warning:
+        `nodeId "${nodeId}" did not resolve to any element in this screen's ` +
+        "current content (it may be a stale live-DOM selection, or the " +
+        "screen changed since it was captured) — exported the whole screen " +
+        "instead.",
+    };
+  }
+  const persistedId = node.dataAttributes["data-agent-native-node-id"];
+  return {
+    rootSelector: persistedId ? figmaSvgNodeSelector(persistedId) : node.path,
+  };
+}
+
 export default defineAction({
   description:
     "Export a design screen (or a selected element's subtree via nodeId) as a " +
@@ -179,28 +247,92 @@ export default defineAction({
     }
 
     const [designRow] = await db
-      .select({ title: schema.designs.title })
+      .select({ title: schema.designs.title, data: schema.designs.data })
       .from(schema.designs)
       .where(eq(schema.designs.id, file.designId))
       .limit(1);
 
     const html = await liveContent(file.id, file.content ?? "");
 
+    // Prefer the screen's own saved canvas-frame dimensions (the overview
+    // board's per-file width/height) over the 1440x1200 legacy fallback, so
+    // the render viewport matches the actual screen frame instead of
+    // stretching layout-container widths (e.g. <body>) to an oversized
+    // viewport. An explicit `width`/`height` argument still wins.
+    let canvasFrameWidth: number | undefined;
+    let canvasFrameHeight: number | undefined;
+    if (designRow?.data) {
+      try {
+        const parsed = JSON.parse(designRow.data) as {
+          canvasFrames?: unknown;
+        };
+        const frame = parseCanvasFrameGeometryById(parsed?.canvasFrames)[
+          file.id
+        ];
+        canvasFrameWidth = frame?.width;
+        canvasFrameHeight = frame?.height;
+      } catch {
+        // Malformed/legacy `data` — fall through to the hardcoded default.
+      }
+    }
+    const resolvedWidth = width ?? canvasFrameWidth ?? 1440;
+    const resolvedHeight = height ?? canvasFrameHeight ?? 1200;
+
+    // A `nodeId` may be a persisted `data-agent-native-node-id` value OR a
+    // live-DOM code-layer id (`html:<hash>`) minted by the canvas/bridge,
+    // which never exists verbatim in the persisted HTML. Resolve it against
+    // the same content this export renders before ever touching a browser,
+    // and fail soft (whole-screen export + report warning) instead of
+    // letting an unresolved id 500 the render.
+    const warnings: string[] = [];
+    let rootSelector: string | null = null;
+    if (nodeId) {
+      const resolution = resolveFigmaSvgNodeSelector(html, nodeId, {
+        designId: file.designId,
+        fileId: file.id,
+        filename: file.filename,
+      });
+      rootSelector = resolution.rootSelector;
+      if (resolution.warning) warnings.push(resolution.warning);
+    }
+
     let result: Awaited<ReturnType<typeof renderDesignToFigmaSvg>>;
     try {
       result = await renderDesignToFigmaSvg({
         html,
-        width: width ?? 1440,
-        height: height ?? 1200,
+        width: resolvedWidth,
+        height: resolvedHeight,
         title: designRow?.title ?? file.filename,
-        rootSelector: nodeId ? `[data-agent-native-node-id="${nodeId}"]` : null,
+        rootSelector,
         embedImages: embedImages ?? true,
       });
     } catch (err) {
       if (isMissingBrowserError(err)) {
         return { ok: false, reason: chromiumUnavailableReason(err) };
       }
-      throw err;
+      // Defense in depth: even a selector resolved above can still miss the
+      // live-rendered DOM (e.g. collab content drifted since resolution).
+      // Never surface that as a 500 — retry once against the whole screen.
+      if (rootSelector && isMissingRootSelectorError(err)) {
+        warnings.push(
+          `The resolved selector for nodeId "${nodeId}" did not match the ` +
+            "rendered screen — exported the whole screen instead.",
+        );
+        result = await renderDesignToFigmaSvg({
+          html,
+          width: resolvedWidth,
+          height: resolvedHeight,
+          title: designRow?.title ?? file.filename,
+          rootSelector: null,
+          embedImages: embedImages ?? true,
+        });
+      } else {
+        throw err;
+      }
+    }
+
+    if (warnings.length > 0) {
+      result.report.warnings.push(...warnings);
     }
 
     const filenameOut = safeFigmaSvgFilename(designRow?.title ?? file.filename);

package/corpus/templates/design/actions/export-pdf.ts

@@ -52,7 +52,7 @@ export default defineAction({
       })),
       exportInfo: {
         format: "pdf",
-        note: "Use client-side rendering (e.g. html2canvas + jsPDF) to generate the PDF from the returned design data.",
+        note: "The Design editor renders the active artboard as a single-page raster PDF at its fixed authored size. This preserves visual appearance but does not provide selectable/vector text; export separate screens individually.",
       },
     };
   },

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

@@ -32,6 +32,7 @@ import {
   type DesignGenerationSession,
   updateGenerationSessionWithSavedFiles,
 } from "../shared/generation-session.js";
+import { assertLockedLayersPreserved } from "../shared/locked-layers.js";
 import { annotateScreenHtmlForPersist } from "../shared/screen-annotation.js";
 
 /** Editor deep link so external agents can surface "Open design". */
@@ -418,6 +419,8 @@ const generateDesignAction = defineAction({
           };
           const live = await readLiveSourceFile(workspaceFile);
 
+          assertLockedLayersPreserved(live.content, file.content);
+
           await writeInlineSourceFile({
             designId: existing.designId,
             file: workspaceFile,

package/corpus/templates/design/actions/get-design-snapshot.ts

@@ -5,6 +5,7 @@ import { z } from "zod";
 
 import { schema } from "../server/db/index.js";
 import { buildDesignSnapshot } from "../server/lib/design-snapshot.js";
+import { lockedLayerSnapshots } from "../shared/locked-layers.js";
 import "../server/db/index.js"; // ensure registerShareableResource runs
 
 /** Editor deep link so external agents can surface "Open design". */
@@ -108,6 +109,14 @@ export default defineAction({
       tweaks: snapshot.tweaks,
       appliedTweaks: snapshot.appliedTweaks,
       resolvedCssVars: snapshot.resolvedCssVars,
+      lockedLayers: files.flatMap((file) =>
+        lockedLayerSnapshots(file.content).map((layer) => ({
+          fileId: file.id,
+          filename: file.filename,
+          nodeId: layer.id,
+          layerName: layer.label,
+        })),
+      ),
       deepLink: designDeepLink(designId),
       ...(boundedFile
         ? {