@agent-native/core 0.79.26 → 0.80.0

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

@@ -13,53 +13,192 @@ import { and, eq } from "drizzle-orm";
 import { z } from "zod";
 
 import { getDb, schema } from "../server/db/index.js";
-import { applyEdits } from "../shared/apply-edits.js";
+import {
+  applyOneEdit,
+  type ApplyEditsResult,
+  type DesignEdit,
+} from "../shared/apply-edits.js";
+
+const editBlocksSchema = z.preprocess(
+  (v) => {
+    if (typeof v !== "string") return v;
+    // Don't let malformed JSON throw an uncaught SyntaxError — return the
+    // raw value so Zod produces a clean validation error instead.
+    try {
+      return JSON.parse(v);
+    } catch {
+      return v;
+    }
+  },
+  z
+    .array(
+      z.object({
+        search: z
+          .string()
+          .min(1)
+          .describe(
+            "Exact text to find, with enough surrounding context to be unique",
+          ),
+        replace: z.string().describe("Replacement text"),
+      }),
+    )
+    .min(1),
+);
+
+function stripStableNodeIdAttributes(value: string): {
+  content: string;
+  indexMap: number[];
+} {
+  const stableIdPattern =
+    /\sdata-agent-native-node-id\s*=\s*(?:"[^"]*"|'[^']*'|[^\s/>]+)/gi;
+  let content = "";
+  const indexMap: number[] = [];
+  let cursor = 0;
+  let match: RegExpExecArray | null;
+  while ((match = stableIdPattern.exec(value))) {
+    const chunk = value.slice(cursor, match.index);
+    for (let i = 0; i < chunk.length; i += 1) {
+      content += chunk[i];
+      indexMap.push(cursor + i);
+    }
+    cursor = match.index + match[0].length;
+  }
+  const tail = value.slice(cursor);
+  for (let i = 0; i < tail.length; i += 1) {
+    content += tail[i];
+    indexMap.push(cursor + i);
+  }
+  indexMap.push(value.length);
+  return { content, indexMap };
+}
+
+function findUniqueStableIdAgnosticSpan(
+  content: string,
+  search: string,
+): { start: number; end: number } | null {
+  const strippedContent = stripStableNodeIdAttributes(content);
+  const strippedSearch = stripStableNodeIdAttributes(search).content;
+  if (!strippedSearch) return null;
+
+  let count = 0;
+  let onlyIndex = -1;
+  let index = strippedContent.content.indexOf(strippedSearch);
+  while (index !== -1) {
+    count += 1;
+    onlyIndex = index;
+    if (count > 1) return null;
+    index = strippedContent.content.indexOf(strippedSearch, index + 1);
+  }
+  if (count !== 1) return null;
+
+  return {
+    start: strippedContent.indexMap[onlyIndex] ?? 0,
+    end:
+      strippedContent.indexMap[onlyIndex + strippedSearch.length] ??
+      content.length,
+  };
+}
+
+function applyOneEditWithStableIdFallback(
+  content: string,
+  edit: DesignEdit,
+  index: number,
+): string {
+  try {
+    return applyOneEdit(content, edit, index);
+  } catch (error) {
+    const span = findUniqueStableIdAgnosticSpan(content, edit.search);
+    if (!span) throw error;
+    return `${content.slice(0, span.start)}${edit.replace}${content.slice(span.end)}`;
+  }
+}
+
+export function applySearchReplaceEdits(
+  content: string,
+  edits: DesignEdit[],
+): ApplyEditsResult {
+  let next = content;
+  edits.forEach((edit, index) => {
+    next = applyOneEditWithStableIdFallback(next, edit, index);
+  });
+  return { content: next, applied: edits.length };
+}
 
 export default defineAction({
   description:
-    "Apply small, surgical search/replace edits to ONE file in a design — the " +
+    "Edit ONE file in a design after reading it with get-design-snapshot. " +
+    "For small localized refinements, apply surgical search/replace edits — the " +
     "preferred way to refine an existing design without regenerating the whole " +
     "file (cheaper, faster, and it preserves everything you don't touch). Each " +
     "edit's `search` must match the current file exactly and uniquely, so " +
     "include enough surrounding context. Read the file first with " +
     "`get-design-snapshot`. Wrapping an element is just a search/replace whose " +
-    "`replace` adds the wrapper around the original text. Use `generate-design` " +
+    "`replace` adds the wrapper around the original text. For broad copy-only " +
+    'changes such as translating all visible text, use `mode: "replace-file"` ' +
+    "with `replacementContent`: the complete updated file content copied from " +
+    "the snapshot with only the requested copy changed. Use `generate-design` " +
     "instead only for brand-new files or large structural rewrites.",
-  schema: z.object({
-    designId: z.string().describe("Design project ID"),
-    filename: z
-      .string()
-      .default("index.html")
-      .describe("File to edit (e.g. 'index.html')"),
-    edits: z
-      .preprocess(
-        (v) => {
-          if (typeof v !== "string") return v;
-          // Don't let malformed JSON throw an uncaught SyntaxError — return the
-          // raw value so Zod produces a clean validation error instead.
-          try {
-            return JSON.parse(v);
-          } catch {
-            return v;
-          }
-        },
-        z
-          .array(
-            z.object({
-              search: z
-                .string()
-                .min(1)
-                .describe(
-                  "Exact text to find, with enough surrounding context to be unique",
-                ),
-              replace: z.string().describe("Replacement text"),
-            }),
-          )
-          .min(1),
-      )
-      .describe("Search/replace blocks, applied in order"),
-  }),
-  run: async ({ designId, filename, edits }) => {
+  schema: z
+    .object({
+      designId: z.string().describe("Design project ID"),
+      filename: z
+        .string()
+        .default("index.html")
+        .describe("File to edit (e.g. 'index.html')"),
+      mode: z
+        .enum(["search-replace", "replace-file"])
+        .optional()
+        .describe(
+          "Defaults to search-replace. Use replace-file for broad copy-only edits like translating the whole page after reading get-design-snapshot.",
+        ),
+      edits: editBlocksSchema
+        .optional()
+        .describe(
+          "Search/replace blocks, applied in order. Use for small localized edits.",
+        ),
+      replacementContent: z
+        .string()
+        .min(1)
+        .optional()
+        .describe(
+          "Complete updated file content. Use only with mode=replace-file for broad copy-only changes; preserve all HTML structure, CSS, scripts, and tweaks from get-design-snapshot.",
+        ),
+    })
+    .superRefine((value, ctx) => {
+      const mode =
+        value.mode ??
+        (value.replacementContent !== undefined
+          ? "replace-file"
+          : "search-replace");
+
+      if (value.edits && value.replacementContent !== undefined) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          message:
+            "Use either edits or replacementContent in one edit-design call, not both.",
+          path: ["replacementContent"],
+        });
+      }
+
+      if (mode === "search-replace" && !value.edits) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          message:
+            "search-replace mode requires at least one edit block in edits.",
+          path: ["edits"],
+        });
+      }
+
+      if (mode === "replace-file" && value.replacementContent === undefined) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          message:
+            "replace-file mode requires replacementContent with the complete updated file.",
+          path: ["replacementContent"],
+        });
+      }
+    }),
+  run: async ({ designId, filename, edits, mode, replacementContent }) => {
     await assertAccess("design", designId, "editor");
 
     const db = getDb();
@@ -104,21 +243,34 @@ export default defineAction({
       // Collab read is best-effort; fall back to stored content.
     }
 
-    const { content: nextContent, applied } = applyEdits(base, edits);
+    const resolvedMode =
+      mode ??
+      (replacementContent !== undefined ? "replace-file" : "search-replace");
+    const { content: nextContent, applied } =
+      resolvedMode === "replace-file"
+        ? { content: replacementContent ?? "", applied: 0 }
+        : applySearchReplaceEdits(base, edits ?? []);
     const changed = nextContent !== base;
 
     if (changed) {
       // Mark agent presence + selection so live viewers can see where the
       // agent is working before the update arrives via collab.
       agentEnterDocument(file.id);
-      if (applied > 0) {
+      if (resolvedMode === "search-replace" && applied > 0) {
+        const firstSearch = edits?.[0]?.search;
         agentUpdateSelection(file.id, {
-          selection: edits[0]?.search
-            ? `[data-edit-target="${edits[0].search.slice(0, 40)}"]`
+          selection: firstSearch
+            ? `[data-edit-target="${firstSearch.slice(0, 40)}"]`
             : null,
           editingFile: filename,
           designId,
         });
+      } else {
+        agentUpdateSelection(file.id, {
+          selection: null,
+          editingFile: filename,
+          designId,
+        });
       }
 
       try {
@@ -148,6 +300,7 @@ export default defineAction({
       designId,
       filename,
       fileId: file.id,
+      mode: resolvedMode,
       editsApplied: applied,
       changed,
       bytesBefore: base.length,

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

@@ -14,6 +14,10 @@ import { nanoid } from "nanoid";
 import { z } from "zod";
 
 import { getDb, schema } from "../server/db/index.js";
+import {
+  mergeCanvasFramePlacements,
+  type CanvasFramePlacement,
+} from "../shared/canvas-frames.js";
 
 /** Editor deep link so external agents can surface "Open design". */
 function designDeepLink(designId: string): string {
@@ -34,7 +38,9 @@ export default defineAction({
     "version then refine individual files with `edit-design` (search/replace) rather " +
     "than resending a big multi-file payload — a single oversized payload can get cut " +
     "off mid-stream and stall the turn. " +
-    "Do not report a design as ready until this action succeeds.",
+    "Do not report a design as ready until this action succeeds. " +
+    "When adding multiple screens or states, pass canvasFrames with filenames " +
+    "and x/y/width/height so the new screens appear placed on the overview canvas.",
   schema: z.object({
     designId: z.string().describe("Design project ID to save content to"),
     prompt: z.string().describe("The generation prompt (stored for reference)"),
@@ -106,6 +112,34 @@ export default defineAction({
           "radius, dark mode, font choice). Each must reference a CSS var " +
           "the design's `:root` block actually uses.",
       ),
+    canvasFrames: z
+      .preprocess(
+        (v) => (typeof v === "string" ? JSON.parse(v) : v),
+        z
+          .array(
+            z
+              .object({
+                fileId: z.string().optional(),
+                filename: z.string().optional(),
+                x: z.number().optional(),
+                y: z.number().optional(),
+                width: z.number().optional(),
+                height: z.number().optional(),
+                rotation: z.number().optional(),
+                z: z.number().optional(),
+              })
+              .refine((frame) => frame.fileId || frame.filename, {
+                message: "canvasFrames entries require fileId or filename",
+              }),
+          )
+          .optional(),
+      )
+      .optional()
+      .describe(
+        "Optional overview-canvas placements for generated screens. " +
+          "Reference each screen by filename or fileId and include x/y/width/height " +
+          "from generate-screens regions or your planned canvas layout.",
+      ),
   }),
   mcpApp: {
     compactCatalog: true,
@@ -124,6 +158,7 @@ export default defineAction({
     designSystemId,
     projectType,
     tweaks,
+    canvasFrames,
   }) => {
     await assertAccess("design", designId, "editor");
     if (designSystemId) {
@@ -280,6 +315,40 @@ export default defineAction({
         type: tweak.type === "color-swatches" ? "color-swatch" : tweak.type,
       }));
     }
+    let placedFrames:
+      | Array<{
+          fileId: string;
+          filename?: string;
+          frame: CanvasFramePlacement;
+        }>
+      | undefined;
+    if (canvasFrames !== undefined) {
+      const savedByFileId = new Map(savedFiles.map((file) => [file.id, file]));
+      const savedByFilename = new Map(
+        savedFiles.map((file) => [file.filename, file]),
+      );
+      const existingByFileId = new Map(
+        existingFiles.map((file) => [file.id, file]),
+      );
+      const merged = mergeCanvasFramePlacements({
+        existing: prevData.canvasFrames,
+        placements: canvasFrames,
+        resolveFileId: (placement) => {
+          if (placement.fileId) {
+            return savedByFileId.has(placement.fileId) ||
+              existingByFileId.has(placement.fileId)
+              ? placement.fileId
+              : undefined;
+          }
+          return placement.filename
+            ? (savedByFilename.get(placement.filename)?.id ??
+                existingByName.get(placement.filename)?.id)
+            : undefined;
+        },
+      });
+      mergedData.canvasFrames = merged.canvasFrames;
+      placedFrames = merged.placedFrames;
+    }
     designUpdates.data = JSON.stringify(mergedData);
 
     await db
@@ -292,6 +361,7 @@ export default defineAction({
       urlPath: `/design/${designId}`,
       renderable: true,
       savedFiles,
+      placedFrames,
       fileCount: savedFiles.length,
     };
   },

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

@@ -0,0 +1,193 @@
+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 { nanoid } from "nanoid";
+import { z } from "zod";
+
+import "../server/db/index.js";
+import { assignRegions } from "../shared/canvas-math.js";
+import {
+  designGenerationSessionKey,
+  type DesignGenerationFrame,
+  type DesignGenerationSession,
+} from "../shared/generation-session.js";
+
+const AGENT_NAMES = [
+  "Atlas",
+  "Nova",
+  "Kai",
+  "Mira",
+  "Sol",
+  "Vega",
+  "Rune",
+  "Iris",
+];
+
+const AGENT_COLORS = [
+  "var(--design-editor-accent-color)",
+  "hsl(var(--chart-2))",
+  "hsl(var(--chart-3))",
+  "hsl(var(--chart-4))",
+  "hsl(var(--chart-5))",
+];
+
+function designDeepLink(designId: string): string {
+  const path = `/design/${encodeURIComponent(designId)}?view=overview`;
+  return buildDeepLink({
+    app: "design",
+    view: "editor",
+    params: { designId },
+    to: path,
+  });
+}
+
+const requestedScreenSchema = z.object({
+  frameId: z.string().optional(),
+  title: z.string().min(1),
+  filename: z
+    .string()
+    .optional()
+    .describe("Target filename for this screen, such as onboarding.html"),
+  role: z.enum(["screen", "variant"]).optional().default("screen"),
+  variantOf: z.string().optional(),
+});
+
+export default defineAction({
+  description:
+    "Start a visible multi-agent generation session on the Design canvas. " +
+    "Use this before generating multiple screens or variations in parallel: it " +
+    "assigns non-overlapping canvas regions, publishes named agent/frame " +
+    "status to application state, and returns per-frame generation instructions. " +
+    "After this action, fan out calls to generate-design for each returned " +
+    "frame, passing the returned canvasFrame values to generate-design so " +
+    "screens appear in the infinite overview canvas.",
+  schema: z.object({
+    designId: z.string().describe("Design project ID to generate into"),
+    prompt: z.string().min(1).describe("Overall generation prompt"),
+    screens: z
+      .preprocess(
+        (value) => (typeof value === "string" ? JSON.parse(value) : value),
+        z.array(requestedScreenSchema).min(1).max(8),
+      )
+      .describe("Screens or variants that should be generated on the canvas"),
+    designSystemId: z
+      .string()
+      .optional()
+      .describe("Locked design system/token set for every worker"),
+    contextRefs: z
+      .array(z.string())
+      .optional()
+      .default([])
+      .describe("Selected frame/image/reference ids attached as context"),
+  }),
+  mcpApp: {
+    compactCatalog: true,
+    resource: embedApp({
+      title: "Design generation session",
+      description: "Open the Design editor with agent generation visible.",
+      iframeTitle: "Agent-Native Design",
+      openLabel: "Open generation session",
+      height: 720,
+    }),
+  },
+  run: async ({ designId, prompt, screens, designSystemId, contextRefs }) => {
+    await assertAccess("design", designId, "editor");
+    if (designSystemId) {
+      await assertAccess("design-system", designSystemId, "viewer");
+    }
+
+    const regions = assignRegions(screens.length, {
+      origin: { x: 0, y: 0 },
+      columns: screens.length <= 3 ? screens.length : 3,
+    });
+    const frames: DesignGenerationFrame[] = screens.map((screen, index) => {
+      const frameId = screen.frameId ?? nanoid();
+      return {
+        frameId,
+        agentId: `agent-${frameId}`,
+        agentName: AGENT_NAMES[index % AGENT_NAMES.length] ?? "Agent",
+        agentColor:
+          AGENT_COLORS[index % AGENT_COLORS.length] ??
+          "var(--design-editor-accent-color)",
+        region: regions[index]!,
+        role: screen.role,
+        variantOf: screen.variantOf,
+        status: "queued",
+        step: "Queued",
+        progress: 0,
+      };
+    });
+
+    const session: DesignGenerationSession = {
+      id: nanoid(),
+      designId,
+      status: "planning",
+      designSystemId,
+      prompt,
+      contextRefs,
+      frames,
+    };
+
+    await writeAppState(
+      designGenerationSessionKey(designId),
+      session as unknown as Record<string, unknown>,
+    );
+    await writeAppState("navigate", {
+      view: "editor",
+      designId,
+      editorView: "overview",
+      path: `/design/${encodeURIComponent(designId)}?view=overview`,
+    });
+
+    const targets = frames.map((frame, index) => {
+      const requested = screens[index]!;
+      const filename =
+        requested.filename ??
+        `${
+          requested.title
+            .toLowerCase()
+            .replace(/[^a-z0-9]+/g, "-")
+            .replace(/^-+|-+$/g, "")
+            .slice(0, 48) || `screen-${index + 1}`
+        }.html`;
+      return {
+        frameId: frame.frameId,
+        title: requested.title,
+        filename,
+        role: frame.role,
+        variantOf: frame.variantOf,
+        canvasFrame: {
+          filename,
+          x: frame.region.x,
+          y: frame.region.y,
+          width: frame.region.width,
+          height: frame.region.height,
+          z: index,
+        },
+      };
+    });
+
+    return {
+      designId,
+      sessionId: session.id,
+      status: session.status,
+      frames,
+      targets,
+      path: `/design/${encodeURIComponent(designId)}?view=overview`,
+      embed: true,
+      nextRequiredAction:
+        "Generate each target with generate-design, using the target filename and canvasFrame placement, the same designSystemId, and contextRefs for coherence.",
+    };
+  },
+  link: ({ result }) => {
+    if (!result || typeof result !== "object") return null;
+    const designId = (result as { designId?: string }).designId;
+    if (!designId) return null;
+    return {
+      url: designDeepLink(designId),
+      label: "Open generation session",
+      view: "editor",
+    };
+  },
+});