@agent-native/core 0.80.8 → 0.80.9

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

@@ -56,10 +56,20 @@ const sourceSchema = z.preprocess(
     }),
 );
 
-const targetSchema = z.object({
-  nodeId: z.string().optional(),
-  selector: z.string().optional(),
-});
+const targetSchema = z
+  .object({
+    nodeId: z.string().optional(),
+    selector: z.string().optional(),
+  })
+  .superRefine((target, ctx) => {
+    if (!target.nodeId && !target.selector) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        path: ["nodeId"],
+        message: "target.nodeId or target.selector is required",
+      });
+    }
+  });
 
 const intentSchema = z.preprocess(
   parseJsonString,
@@ -168,6 +178,16 @@ async function resolveEditableDesignFile(
   if (file.fileType !== "html") {
     throw new Error("Visual code-layer edits only support HTML files for now.");
   }
+  if (source.designId && file.designId !== source.designId) {
+    throw new Error(
+      `source.designId "${source.designId}" does not match file "${file.id}"`,
+    );
+  }
+  if (source.filename && file.filename !== source.filename) {
+    throw new Error(
+      `source.filename "${source.filename}" does not match file "${file.id}"`,
+    );
+  }
 
   await assertAccess("design", file.designId, "editor");
 

package/corpus/templates/design/actions/export-coding-handoff.ts

@@ -11,6 +11,7 @@ import { z } from "zod";
 import { schema } from "../server/db/index.js";
 import {
   buildCodingHandoffPrompt,
+  buildHandoffZipUrl,
   buildRawHandoffUrl,
   normalizeHandoffFormat,
 } from "../server/lib/coding-handoff.js";
@@ -30,9 +31,9 @@ function designDeepLink(designId: string): string {
 
 export default defineAction({
   description:
-    "Turn a design into code: create a coding-tool handoff for a design " +
-    "project. Returns a tokenized raw-code URL external agents can fetch, " +
-    "plus a ready-to-copy prompt. The bundle reflects the design's CURRENT " +
+    "Turn a design into code: create an agent handoff for a design project. " +
+    "Returns tokenized raw and ZIP URLs external agents can fetch, plus a " +
+    "ready-to-copy prompt. The bundle reflects the design's CURRENT " +
     "state — live editor (collab) content plus the user's applied visual " +
     "tweaks resolved into the HTML :root — so the generated code matches the " +
     "tuned design, not the original generated tokens. This is the canonical " +
@@ -56,7 +57,7 @@ export default defineAction({
   mcpApp: {
     compactCatalog: true,
     resource: embedApp({
-      title: "Design coding handoff",
+      title: "Design agent handoff",
       description: "Open the design in the real Design editor.",
       iframeTitle: "Agent-Native Design",
       openLabel: "Open design",
@@ -97,8 +98,14 @@ export default defineAction({
       origin: resolvedOrigin,
       format: handoffFormat,
     });
+    const zipUrl = buildHandoffZipUrl({
+      id,
+      token,
+      origin: resolvedOrigin,
+    });
     const prompt = buildCodingHandoffPrompt({
       rawUrl,
+      zipUrl,
       title: design.title,
       fileCount: snapshot.files.length,
     });
@@ -106,6 +113,7 @@ export default defineAction({
     return {
       designId: id,
       rawUrl,
+      zipUrl,
       prompt,
       clipboardText: prompt,
       format: handoffFormat,

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

@@ -1,6 +1,5 @@
 import { defineAction, embedApp } from "@agent-native/core";
 import {
-  deleteAppState,
   readAppState,
   writeAppState,
 } from "@agent-native/core/application-state";
@@ -26,6 +25,7 @@ import {
 import {
   designGenerationSessionKey,
   type DesignGenerationSession,
+  updateGenerationSessionWithSavedFiles,
 } from "../shared/generation-session.js";
 
 /** Editor deep link so external agents can surface "Open design". */
@@ -57,28 +57,13 @@ async function updateGenerationSessionForSavedFiles(
   const session = rawSession as unknown as DesignGenerationSession;
   if (session.designId !== designId || !Array.isArray(session.frames)) return;
 
-  const saved = new Set(savedFilenames);
-  const frames = session.frames.map((frame) =>
-    frame.filename && saved.has(frame.filename)
-      ? {
-          ...frame,
-          status: "done" as const,
-          step: "Saved",
-          progress: 1,
-        }
-      : frame,
+  const nextSession = updateGenerationSessionWithSavedFiles(
+    session,
+    savedFilenames,
   );
-  const allDone = frames.every((frame) => frame.status === "done");
-  if (allDone) {
-    await deleteAppState(key);
-    return;
-  }
+  if (nextSession === session) return;
 
-  await writeAppState(key, {
-    ...session,
-    status: "generating",
-    frames,
-  } as unknown as Record<string, unknown>);
+  await writeAppState(key, nextSession as unknown as Record<string, unknown>);
 }
 
 export default defineAction({

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

@@ -51,7 +51,7 @@ const requestedScreenSchema = z
       .optional()
       .describe("Target filename for this screen, such as onboarding.html"),
     role: z.enum(["screen", "variant"]).optional().default("screen"),
-    variantOf: z.string().optional(),
+    variantOf: z.string().trim().min(1).optional(),
   })
   .superRefine((screen, ctx) => {
     if (screen.role === "variant" && !screen.variantOf) {
@@ -80,7 +80,48 @@ export default defineAction({
     screens: z
       .preprocess(
         (value) => (typeof value === "string" ? JSON.parse(value) : value),
-        z.array(requestedScreenSchema).min(1).max(8),
+        z
+          .array(requestedScreenSchema)
+          .min(1)
+          .max(8)
+          .superRefine((screens, ctx) => {
+            const requestAnchors = new Map<
+              string,
+              { index: number; role: DesignGenerationFrame["role"] }
+            >();
+            screens.forEach((screen, index) => {
+              const anchors = [screen.frameId, screen.filename, screen.title];
+              for (const anchor of anchors) {
+                if (!anchor || requestAnchors.has(anchor)) continue;
+                requestAnchors.set(anchor, {
+                  index,
+                  role: screen.role,
+                });
+              }
+            });
+
+            screens.forEach((screen, index) => {
+              if (screen.role !== "variant" || !screen.variantOf) return;
+              const anchor = requestAnchors.get(screen.variantOf);
+              if (!anchor) return;
+              if (anchor.index === index) {
+                ctx.addIssue({
+                  code: z.ZodIssueCode.custom,
+                  path: [index, "variantOf"],
+                  message: "variant screens cannot point to themselves",
+                });
+                return;
+              }
+              if (anchor.role === "variant") {
+                ctx.addIssue({
+                  code: z.ZodIssueCode.custom,
+                  path: [index, "variantOf"],
+                  message:
+                    "variant screens must anchor to a base screen, not another variant",
+                });
+              }
+            });
+          }),
       )
       .describe("Screens or variants that should be generated on the canvas"),
     designSystemId: z

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

@@ -14,6 +14,7 @@ export default defineAction({
   }),
   readOnly: true,
   requiresAuth: false,
+  publicAgent: { expose: true, readOnly: true, requiresAuth: false },
   http: { method: "GET" },
   run: async ({ id }) => {
     const access = await resolveAccess("design", id);

package/corpus/templates/design/actions/present-design-variants.ts

@@ -1,64 +1,245 @@
 import { defineAction, embedApp } from "@agent-native/core";
-import { writeAppState } from "@agent-native/core/application-state";
+import {
+  deleteAppState,
+  writeAppState,
+  writeAppStateForCurrentTab,
+} from "@agent-native/core/application-state";
+import { seedFromText } from "@agent-native/core/collab";
 import { buildDeepLink } from "@agent-native/core/server";
 import { assertAccess } from "@agent-native/core/sharing";
+import { eq } from "drizzle-orm";
+import { nanoid } from "nanoid";
 import { z } from "zod";
 
 import "../server/db/index.js"; // ensure registerShareableResource runs
+import { getDb, schema } from "../server/db/index.js";
+import {
+  mergeCanvasFramePlacements,
+  type CanvasFramePlacement,
+} from "../shared/canvas-frames.js";
+
+const VARIANT_GAP = 96;
+const MAX_COLUMNS = 3;
+const MOBILE_WIDTH = 390;
+const MOBILE_HEIGHT = 844;
+const TABLET_WIDTH = 768;
+const TABLET_HEIGHT = 1024;
+const DESKTOP_WIDTH = 1280;
+const DESKTOP_HEIGHT = 900;
 
 function designDeepLink(designId: string): string {
   return buildDeepLink({
     app: "design",
     view: "editor",
-    params: { designId },
-    // `handoff=chat` marks a link opened from a link-only host (CLI / Codex /
-    // Claude Code) so the editor shows a copyable paste-back summary after the
-    // user picks — the choice can't ride a host chat bridge there.
-    to: `/design/${encodeURIComponent(designId)}?handoff=chat`,
+    params: { designId, editorView: "overview" },
+    to: `/design/${encodeURIComponent(designId)}?view=overview`,
   });
 }
 
 const FALLBACK_INSTRUCTIONS =
-  "If the design opens as a browser link instead of inline, the user picks a " +
-  "direction there and the editor shows a copyable summary. Ask them to paste " +
-  "that summary back into chat so you can continue from the chosen direction. " +
-  'They can also just tell you which one in words (e.g. "use variant A" / "the ' +
-  'editorial one") — honor that too instead of insisting on the paste-back.';
+  "The generated directions have been saved as normal screens on the Design " +
+  "overview board. The chat shows one button per screen. Ask the user to pick " +
+  "a screen by name if the inline buttons are not available; after they pick, " +
+  "delete the other variant screens and continue from the kept screen.";
 
 const variantSchema = z.object({
   id: z.string().min(1).describe("Stable variant id, e.g. 'minimal-focus'"),
   label: z
     .string()
     .min(1)
-    .describe("Short user-facing variant name, e.g. 'One-Line Focus'"),
+    .describe("Short user-facing screen name, e.g. 'One-Line Focus'"),
   content: z
     .string()
     .min(1)
     .describe(
-      "Complete self-contained HTML document for this variant. Inline the CSS needed for the preview; avoid relying on external CSS/script CDNs because MCP app sandboxes may block them.",
+      "Complete self-contained HTML document for this variant. Inline the CSS needed for the preview; avoid relying on external CSS/script CDNs because app sandboxes may block them.",
+    ),
+  width: z
+    .number()
+    .positive()
+    .optional()
+    .describe(
+      "Optional source viewport/artboard width for the overview frame.",
+    ),
+  height: z
+    .number()
+    .positive()
+    .optional()
+    .describe(
+      "Optional source viewport/artboard height for the overview frame.",
     ),
 });
 
+interface VariantScreen {
+  id: string;
+  variantId: string;
+  label: string;
+  filename: string;
+  width: number;
+  height: number;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return Boolean(value && typeof value === "object" && !Array.isArray(value));
+}
+
+function parseJsonRecord(value: string | null | undefined) {
+  if (!value) return {};
+  try {
+    const parsed = JSON.parse(value);
+    return isRecord(parsed) ? parsed : {};
+  } catch {
+    return {};
+  }
+}
+
+function slugify(value: string, fallback: string) {
+  return (
+    value
+      .trim()
+      .toLowerCase()
+      .replace(/[^a-z0-9]+/g, "-")
+      .replace(/^-+|-+$/g, "")
+      .slice(0, 52) || fallback
+  );
+}
+
+function optionName(index: number) {
+  return `Option ${String.fromCharCode(65 + index)}`;
+}
+
+function uniqueFilename(preferred: string, used: Set<string>) {
+  const dot = preferred.lastIndexOf(".");
+  const stem = dot > 0 ? preferred.slice(0, dot) : preferred;
+  const ext = dot > 0 ? preferred.slice(dot) : ".html";
+  let candidate = `${stem}${ext}`;
+  let suffix = 2;
+  while (used.has(candidate)) {
+    candidate = `${stem}-${suffix}${ext}`;
+    suffix += 1;
+  }
+  used.add(candidate);
+  return candidate;
+}
+
+function firstCssPixelValue(content: string, property: string) {
+  const escaped = property.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const pattern = new RegExp(`${escaped}\\s*:\\s*(\\d{2,4})px`, "i");
+  const match = content.match(pattern);
+  if (!match) return undefined;
+  const value = Number(match[1]);
+  return Number.isFinite(value) ? value : undefined;
+}
+
+function boundedDimension(value: unknown, min: number, max: number) {
+  return typeof value === "number" && Number.isFinite(value)
+    ? Math.min(max, Math.max(min, Math.round(value)))
+    : undefined;
+}
+
+function inferVariantSize(variant: z.infer<typeof variantSchema>) {
+  const explicitWidth = boundedDimension(variant.width, 240, 1920);
+  const explicitHeight = boundedDimension(variant.height, 240, 3000);
+  if (explicitWidth && explicitHeight) {
+    return { width: explicitWidth, height: explicitHeight };
+  }
+
+  const content = variant.content;
+  const cssWidth =
+    firstCssPixelValue(content, "width") ??
+    firstCssPixelValue(content, "max-width") ??
+    firstCssPixelValue(content, "min-width");
+  const cssHeight =
+    firstCssPixelValue(content, "height") ??
+    firstCssPixelValue(content, "min-height");
+  const inferredWidth = boundedDimension(cssWidth, 240, 1920);
+  const inferredHeight = boundedDimension(cssHeight, 240, 3000);
+  if (inferredWidth && inferredWidth <= 560) {
+    return {
+      width: explicitWidth ?? inferredWidth,
+      height: explicitHeight ?? inferredHeight ?? MOBILE_HEIGHT,
+    };
+  }
+  if (inferredWidth && inferredHeight) {
+    return {
+      width: explicitWidth ?? inferredWidth,
+      height: explicitHeight ?? inferredHeight,
+    };
+  }
+
+  const lowercase = content.toLowerCase();
+  if (
+    /\b(?:mobile|phone|iphone|android)\b/.test(lowercase) ||
+    /\b(?:max-w-sm|max-w-md|w-\[(?:360|375|390|393|414)px\])\b/.test(lowercase)
+  ) {
+    return {
+      width: explicitWidth ?? MOBILE_WIDTH,
+      height: explicitHeight ?? MOBILE_HEIGHT,
+    };
+  }
+  if (/\b(?:tablet|ipad)\b/.test(lowercase)) {
+    return {
+      width: explicitWidth ?? TABLET_WIDTH,
+      height: explicitHeight ?? TABLET_HEIGHT,
+    };
+  }
+
+  return {
+    width: explicitWidth ?? DESKTOP_WIDTH,
+    height: explicitHeight ?? DESKTOP_HEIGHT,
+  };
+}
+
+function placeVariantScreens(screens: VariantScreen[]) {
+  const placements: CanvasFramePlacement[] = [];
+  const columns = Math.min(MAX_COLUMNS, Math.max(1, screens.length));
+  let rowY = 0;
+
+  for (let rowStart = 0; rowStart < screens.length; rowStart += columns) {
+    const row = screens.slice(rowStart, rowStart + columns);
+    let x = 0;
+    let rowHeight = 0;
+
+    for (const [offset, screen] of row.entries()) {
+      placements.push({
+        fileId: screen.id,
+        filename: screen.filename,
+        x,
+        y: rowY,
+        width: screen.width,
+        height: screen.height,
+        z: rowStart + offset,
+      });
+      x += screen.width + VARIANT_GAP;
+      rowHeight = Math.max(rowHeight, screen.height);
+    }
+
+    rowY += rowHeight + VARIANT_GAP;
+  }
+
+  return placements;
+}
+
 export default defineAction({
   description:
-    "Present generated design directions in the Design editor so the user can " +
-    "visually compare options and pick one. Provide 2-5 variants (3 is the " +
-    "sweet spot). Use this for design exploration before calling " +
-    "generate-design. The user's choice is persisted automatically by the app; " +
-    "if it opens as a browser link, they paste a copyable summary back to chat " +
-    'or simply tell you which one (e.g. "use variant A").',
+    "Present generated design directions as normal screens on the Design " +
+    "overview board and ask the user to choose one with inline chat buttons. " +
+    "Provide 2-5 variants (3 is the sweet spot). Use this for design " +
+    "exploration before follow-up refinement. After the user's choice, keep " +
+    "the chosen screen, delete the other generated variant screens, and " +
+    "continue from the kept screen.",
   schema: z.object({
     designId: z.string().describe("Design project ID to show variants for"),
     prompt: z
       .string()
       .optional()
-      .describe("Caption shown above the variant grid"),
+      .describe("Caption shown in chat above the variant choice buttons"),
     variants: z
       .array(variantSchema)
       .min(2)
       .max(5)
       .describe(
-        "2-5 concise, visually distinct generated design options to preview side by side (3 is the sweet spot). Inline CSS so all options render in the MCP app preview.",
+        "2-5 concise, visually distinct generated design options to place as overview screens (3 is the sweet spot). Inline CSS so all options render in the app preview.",
       ),
   }),
   mcpApp: {
@@ -66,30 +247,174 @@ export default defineAction({
     resource: embedApp({
       title: "Design directions",
       description:
-        "Open the Design editor with a visual picker for generated variants.",
+        "Open the Design editor with generated directions on the overview board.",
       iframeTitle: "Agent-Native Design",
-      openLabel: "Open design directions",
+      openLabel: "Open screen overview",
       height: 720,
     }),
   },
   run: async ({ designId, prompt, variants }) => {
     await assertAccess("design", designId, "editor");
 
-    await writeAppState("design-variants", {
+    const db = getDb();
+    const now = new Date().toISOString();
+    const [design] = await db
+      .select({ data: schema.designs.data })
+      .from(schema.designs)
+      .where(eq(schema.designs.id, designId))
+      .limit(1);
+    const existingFiles = await db
+      .select()
+      .from(schema.designFiles)
+      .where(eq(schema.designFiles.designId, designId));
+    const usedFilenames = new Set(existingFiles.map((file) => file.filename));
+    const variantSetId = nanoid();
+    const screens: VariantScreen[] = [];
+
+    for (let index = 0; index < variants.length; index += 1) {
+      const variant = variants[index]!;
+      const label = variant.label.trim() || optionName(index);
+      const slug = slugify(label, `option-${index + 1}`);
+      const preferredFilename = `variant-${slug}.html`;
+      const filename = uniqueFilename(preferredFilename, usedFilenames);
+      const fileId = nanoid();
+      const { width, height } = inferVariantSize(variant);
+
+      await db.insert(schema.designFiles).values({
+        id: fileId,
+        designId,
+        filename,
+        fileType: "html",
+        content: variant.content,
+        createdAt: now,
+        updatedAt: now,
+      });
+      await seedFromText(fileId, variant.content);
+
+      screens.push({
+        id: fileId,
+        variantId: variant.id,
+        label,
+        filename,
+        width,
+        height,
+      });
+    }
+
+    const placements = placeVariantScreens(screens);
+    await db.transaction(async (tx) => {
+      const [currentDesign] = await tx
+        .select({ data: schema.designs.data })
+        .from(schema.designs)
+        .where(eq(schema.designs.id, designId))
+        .limit(1);
+      const prevData = parseJsonRecord(currentDesign?.data ?? design?.data);
+      const mergedFrames = mergeCanvasFramePlacements({
+        existing: prevData.canvasFrames,
+        placements,
+        resolveFileId: (placement) => placement.fileId,
+      });
+      const previousMetadata = isRecord(prevData.screenMetadata)
+        ? { ...prevData.screenMetadata }
+        : {};
+      const previousVariantSets = isRecord(prevData.designVariantSets)
+        ? { ...prevData.designVariantSets }
+        : {};
+      for (const screen of screens) {
+        previousMetadata[screen.id] = {
+          sourceType: "inline",
+          previewState: "preview",
+          title: screen.label,
+          width: screen.width,
+          height: screen.height,
+          variantSetId,
+          variantId: screen.variantId,
+        };
+      }
+      previousVariantSets[variantSetId] = {
+        id: variantSetId,
+        prompt: prompt ?? "Pick a direction",
+        createdAt: now,
+        screens: screens.map((screen) => ({
+          id: screen.id,
+          variantId: screen.variantId,
+          label: screen.label,
+          filename: screen.filename,
+          width: screen.width,
+          height: screen.height,
+        })),
+      };
+
+      await tx
+        .update(schema.designs)
+        .set({
+          data: JSON.stringify({
+            ...prevData,
+            canvasFrames: mergedFrames.canvasFrames,
+            screenMetadata: previousMetadata,
+            designVariantSets: previousVariantSets,
+            updatedAt: now,
+          }),
+          updatedAt: now,
+        })
+        .where(eq(schema.designs.id, designId));
+    });
+
+    await writeAppState("navigate", {
+      view: "editor",
       designId,
-      prompt: prompt ?? "Pick a direction",
-      variants,
+      editorView: "overview",
+      path: `/design/${encodeURIComponent(designId)}?view=overview`,
+    });
+    await writeAppStateForCurrentTab("guided-questions", {
+      title: prompt ?? "Pick a direction",
+      description:
+        "All options are on the board. Choose the one to keep and I will continue from it.",
+      submitLabel: "Use selected direction",
+      submitMessage: "Use this design direction.",
+      skipLabel: "Show another set",
+      skipMessage: "None of these directions are right.",
+      questions: [
+        {
+          id: "variant",
+          type: "text-options",
+          question: "Which screen should I keep?",
+          required: true,
+          allowOther: false,
+          includeExplore: false,
+          includeDecide: false,
+          submitOnSelect: true,
+          options: screens.map((screen, index) => {
+            const otherScreens = screens
+              .filter((other) => other.id !== screen.id)
+              .map(
+                (other) =>
+                  `${other.label} (${other.filename}, file id ${other.id})`,
+              )
+              .join("; ");
+            return {
+              label: screen.label || optionName(index),
+              value:
+                `Keep "${screen.label}" (${screen.filename}, file id ${screen.id}) ` +
+                `from variant set ${variantSetId}. Delete the other variant screens: ${otherScreens}.`,
+            };
+          }),
+        },
+      ],
     });
+    await deleteAppState("design-variants").catch(() => false);
 
     return {
       designId,
       prompt: prompt ?? "Pick a direction",
-      count: variants.length,
-      path: `/design/${encodeURIComponent(designId)}?handoff=chat`,
+      variantSetId,
+      count: screens.length,
+      screens,
+      path: `/design/${encodeURIComponent(designId)}?view=overview`,
       embed: true,
       fallbackInstructions: FALLBACK_INSTRUCTIONS,
       nextRequiredAction:
-        "Wait for the user to pick a variant before refining or calling generate-design.",
+        "Wait for the user to pick a screen in chat. Then delete the unchosen variant screens with delete-file and continue from the chosen screen.",
     };
   },
   link: ({ result }) => {
@@ -98,7 +423,7 @@ export default defineAction({
     if (!designId) return null;
     return {
       url: designDeepLink(designId),
-      label: "Open design directions",
+      label: "Open screen overview",
       view: "editor",
     };
   },