@agent-native/core 0.102.1 → 0.103.0

package/corpus/templates/content/shared/builder-mdx.ts

@@ -1850,10 +1850,14 @@ function nodeSlice(body: string, node: MdxNode) {
 
 function freshTextBlock(markdown: string): unknown {
   const text = markdownToBuilderTextHtml(markdown);
+  return freshTextHtmlBlock(text, markdown);
+}
+
+function freshTextHtmlBlock(text: string, stableSource: string): unknown {
   return {
     "@type": "@builder.io/sdk:Element",
     "@version": 2,
-    id: `builder-mdx-${stableHash(markdown).slice(0, 16)}`,
+    id: `builder-mdx-${stableHash(stableSource).slice(0, 16)}`,
     component: {
       name: "Text",
       options: { text },
@@ -1868,6 +1872,91 @@ function freshTextBlock(markdown: string): unknown {
   };
 }
 
+function assertSafeFreshCalloutNode(node: MdxNode) {
+  for (const child of node.children ?? []) {
+    if (
+      child.type === "mdxFlowExpression" ||
+      child.type === "mdxTextExpression" ||
+      child.type === "mdxjsEsm" ||
+      child.type === "mdxJsxFlowElement" ||
+      child.type === "mdxJsxTextElement"
+    ) {
+      throw new Error("Unsupported dynamic syntax inside Builder callout.");
+    }
+    assertSafeFreshCalloutNode(child);
+  }
+}
+
+function findMdxOpeningTagEnd(raw: string) {
+  let quote: '"' | "'" | null = null;
+  let escaped = false;
+  for (let index = 0; index < raw.length; index += 1) {
+    const character = raw[index];
+    if (escaped) {
+      escaped = false;
+      continue;
+    }
+    if (character === "\\" && quote) {
+      escaped = true;
+      continue;
+    }
+    if (quote) {
+      if (character === quote) quote = null;
+      continue;
+    }
+    if (character === '"' || character === "'") {
+      quote = character;
+      continue;
+    }
+    if (character === ">") return index;
+  }
+  return -1;
+}
+
+function freshCalloutBlock(
+  node: MdxNode,
+  raw: string,
+  occurrence: number,
+): unknown {
+  let icon = "💡";
+  for (const attribute of node.attributes ?? []) {
+    if (
+      attribute.type !== "mdxJsxAttribute" ||
+      !attribute.name ||
+      (attribute.value !== null && typeof attribute.value !== "string")
+    ) {
+      throw new Error("Builder callout attributes must be literal values.");
+    }
+    if (attribute.name === "icon") {
+      icon = attribute.value || "💡";
+      continue;
+    }
+    if (attribute.name === "color") continue;
+    throw new Error(
+      `Unsupported Builder callout attribute: ${attribute.name}.`,
+    );
+  }
+  assertSafeFreshCalloutNode(node);
+
+  const openingEnd = findMdxOpeningTagEnd(raw);
+  const closingStart = raw.lastIndexOf("</callout>");
+  if (openingEnd < 0 || closingStart < openingEnd) {
+    throw new Error("Builder callout must have an explicit closing tag.");
+  }
+  const markdown = raw
+    .slice(openingEnd + 1, closingStart)
+    .split(/\r?\n/)
+    .map((line) => line.replace(/^(?:\t| {2})/, ""))
+    .join("\n")
+    .trim();
+  const content = markdownToBuilderTextHtml(markdown);
+  const iconHtml = icon ? `<p><strong>${escapeHtml(icon)}</strong></p>` : "";
+  return freshTextHtmlBlock(
+    `<blockquote>${iconHtml}${content}</blockquote>`,
+    `${raw}\n@source:${node.position?.start?.offset ?? occurrence}`,
+  );
+}
+
 const BUILDER_TABLE_TAGS = new Set([
   "table",
   "colgroup",
@@ -2510,7 +2599,7 @@ export async function builderMdxBodyToBuilderBlocks(
 ) {
   const root = await parseMdxRoot(body);
   const blocks: unknown[] = [];
-  for (const child of root.children ?? []) {
+  for (const [childIndex, child] of (root.children ?? []).entries()) {
     const raw = nodeSlice(body, child);
     if (!raw) continue;
     if (
@@ -2528,6 +2617,10 @@ export async function builderMdxBodyToBuilderBlocks(
         blocks.push(freshTableBlock(child, raw));
         continue;
       }
+      if (child.name === "callout") {
+        blocks.push(freshCalloutBlock(child, raw, childIndex));
+        continue;
+      }
       const block = await blockFromMdxComponent(raw, sidecars);
       if (block) {
         blocks.push(block);
@@ -2775,24 +2868,78 @@ function inlineMarkdownToHtml(value: string) {
     .replace(/\*\*([^*]+)\*\*/g, "<strong>$1</strong>")
     .replace(/_([^_]+)_/g, "<em>$1</em>")
     .replace(/`([^`]+)`/g, "<code>$1</code>")
-    .replace(/\[([^\]]+)\]\(([^)]+)\)/g, '<a href="$2">$1</a>');
+    .replace(/\[([^\]]+)\]\(([^)]+)\)/g, (_match, label, destination) => {
+      const href = destination.trim();
+      const hasScheme = /^[a-z][a-z\d+.-]*:/i.test(href);
+      const hasSafeScheme = /^(?:https?:\/\/|mailto:|tel:)/i.test(href);
+      const isNetworkPath = /^(?:\/\/|\\\\)/.test(href);
+      const hasControlCharacter = /[\u0000-\u001f\u007f]/.test(href);
+      if (
+        !href ||
+        isNetworkPath ||
+        hasControlCharacter ||
+        (hasScheme && !hasSafeScheme)
+      ) {
+        return label;
+      }
+      return `<a href="${href}">${label}</a>`;
+    });
+}
+
+type MarkdownListNode = {
+  type: "ul" | "ol";
+  value: string;
+  children: MarkdownListNode[];
+};
+
+function renderMarkdownListNodes(nodes: MarkdownListNode[]): string {
+  const html: string[] = [];
+  for (let index = 0; index < nodes.length; ) {
+    const type = nodes[index].type;
+    const items: string[] = [];
+    while (index < nodes.length && nodes[index].type === type) {
+      const node = nodes[index];
+      items.push(
+        `<li>${inlineMarkdownToHtml(node.value)}${renderMarkdownListNodes(node.children)}</li>`,
+      );
+      index += 1;
+    }
+    html.push(`<${type}>${items.join("")}</${type}>`);
+  }
+  return html.join("");
 }
 
 export function markdownToBuilderTextHtml(markdown: string) {
   const lines = markdown.trim().split(/\r?\n/);
   const html: string[] = [];
-  let listItems: string[] = [];
-  let listType: "ul" | "ol" | null = null;
+  let listItems: MarkdownListNode[] = [];
+  let listStack: Array<{ indent: number; node: MarkdownListNode }> = [];
   const flushList = () => {
-    if (!listItems.length || !listType) return;
-    html.push(`<${listType}>${listItems.join("")}</${listType}>`);
+    if (!listItems.length) return;
+    html.push(renderMarkdownListNodes(listItems));
     listItems = [];
-    listType = null;
+    listStack = [];
   };
-  const appendListItem = (type: "ul" | "ol", value: string) => {
-    if (listType && listType !== type) flushList();
-    listType = type;
-    listItems.push(`<li>${inlineMarkdownToHtml(value)}</li>`);
+  const appendListItem = (
+    type: "ul" | "ol",
+    value: string,
+    whitespace: string,
+  ) => {
+    const indent = [...whitespace].reduce(
+      (width, character) => width + (character === "\t" ? 2 : 1),
+      0,
+    );
+    while (
+      listStack.length &&
+      listStack[listStack.length - 1].indent >= indent
+    ) {
+      listStack.pop();
+    }
+    const node: MarkdownListNode = { type, value, children: [] };
+    const parent = listStack[listStack.length - 1]?.node;
+    if (parent) parent.children.push(node);
+    else listItems.push(node);
+    listStack.push({ indent, node });
   };
   for (const line of lines) {
     const trimmed = line.trim();
@@ -2815,14 +2962,14 @@ export function markdownToBuilderTextHtml(markdown: string) {
       );
       continue;
     }
-    const unorderedList = trimmed.match(/^[-*]\s+(.+)$/);
+    const unorderedList = line.match(/^(\s*)[-*]\s+(.+)$/);
     if (unorderedList) {
-      appendListItem("ul", unorderedList[1]);
+      appendListItem("ul", unorderedList[2], unorderedList[1]);
       continue;
     }
-    const orderedList = trimmed.match(/^\d+\.\s+(.+)$/);
+    const orderedList = line.match(/^(\s*)\d+\.\s+(.+)$/);
     if (orderedList) {
-      appendListItem("ol", orderedList[1]);
+      appendListItem("ol", orderedList[2], orderedList[1]);
       continue;
     }
     flushList();

package/corpus/templates/design/.agents/skills/design-templates/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: design-templates
+description: >-
+  Find, save, copy, and adapt Design templates. Use when the user references a
+  template, a prior design, or wants a reusable starting point.
+---
+
+# Design Templates
+
+## Prerequisites
+
+- Read `navigation` or call `view-screen` when the current template or design
+  is unclear.
+- Treat built-in and user-created entries as one template concept. Their
+  ownership and available share/delete actions differ, but creation uses the
+  same action.
+
+## Workflow
+
+1. **Resolve the starting point.** When the user mentions a template, past
+   design, or prior work, call both `list-design-templates` and `list-designs`
+   before generating. Match the requested name or id; ask only when multiple
+   plausible results remain.
+2. **Save a reusable template.** Call `save-design-as-template` with the source
+   `designId`. The action snapshots inline screens, canvas dimensions,
+   defaults, linked design system, and locked layers.
+3. **Create from a template.** Call `create-design-from-template` with the
+   resolved `templateId`. Pass `designSystemId` only when the user selected an
+   override; the action access-checks it and returns the effective linked id.
+4. **Stop after a pure copy.** If there is no prompt and no pending design-system
+   adaptation, open the copied design and do not start generation.
+5. **Adapt copied screens.** When the user supplied a prompt or chose a
+   different accessible design system, call `get-design-snapshot` exactly once,
+   then refine the existing unlocked content with `edit-design`. Never call
+   `generate-design`, delete the copied screens, or recreate the template from
+   scratch.
+6. **Verify.** Read back the copied design and confirm its screens, canvas
+   dimensions, linked design system, and locked-layer boundaries before
+   reporting completion.
+
+## Locked Layers
+
+`data-agent-native-locked="true"` is authoritative. Keep each locked element
+and all descendants byte-for-byte unchanged during adaptation. If the user
+explicitly wants one changed, ask them to unlock it in the Layers panel first.
+
+## Ownership
+
+- Built-in templates cannot be renamed, shared, or deleted.
+- Owned user templates may be shared with the standard resource sharing UI and
+  deleted with `delete-design-template`.
+- Do not model templates as ordinary `designs` rows and do not invent alternate
+  template action names.
+
+## Related Skills
+
+- `design-generation` — creating and refining Design screens.
+- `design-systems` — applying linked systems and tokens.
+- `sharing` — access and sharing rules for user-created templates.

package/corpus/templates/design/AGENTS.md

@@ -133,12 +133,15 @@ patterns live in `.agents/skills/`.
   `generate-design` for new files. For broad rewrites of an existing selected
   file, use `edit-design` with `mode: "replace-file"` and the exact `fileId`;
   never resend files you aren't changing.
-- For reusable starting points, call `list-design-templates`. Use
+- When the user references a template, prior design, or past work, call both
+  `list-design-templates` and `list-designs` before generating so the existing
+  starting point is resolved instead of recreated. Use
   `save-design-as-template` to snapshot an editable inline design, including
   its screens, canvas dimensions, defaults, and locked layers. Use
   `create-design-from-template` to instantiate a normal design. If the user
   supplies a prompt, call `get-design-snapshot` once and refine the copied
   files with `edit-design`; never regenerate the template from scratch.
+  Read the `design-templates` skill for the complete copy/adaptation workflow.
 - Treat `data-agent-native-locked="true"` as an authoritative template
   boundary. Locked backgrounds, logos, and their descendants must remain
   byte-for-byte unchanged during agent edits. The server rejects attempts to
@@ -465,6 +468,8 @@ and requires Builder connected. See `full-app-build` skill for the full flow.
 Read the relevant skill before deeper work:
 
 - `design-generation` for creating/editing prototype HTML and variant flows.
+- `design-templates` for resolving, saving, copying, and adapting templates or
+  prior Design work without fresh generation.
 - `responsive-breakpoints` for Framer-style breakpoint editing (single DOM,
   cascading width-scoped overrides, the managed breakpoints media block).
 - `design-systems` for tokens, brand extraction, and linked systems.

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

@@ -4,7 +4,7 @@ import {
   getRequestOrgId,
   getRequestUserEmail,
 } from "@agent-native/core/server/request-context";
-import { assertAccess, resolveAccess } from "@agent-native/core/sharing";
+import { resolveAccess } from "@agent-native/core/sharing";
 import { eq } from "drizzle-orm";
 import { nanoid } from "nanoid";
 import { z } from "zod";
@@ -31,7 +31,7 @@ export default defineAction({
     "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"),
+    templateId: z.string().min(1).describe("Saved or built-in template ID"),
     title: z.string().trim().min(1).max(120).optional(),
     prompt: z
       .string()
@@ -124,14 +124,20 @@ export default defineAction({
     let linkedDesignSystemId =
       designSystemId === undefined ? templateDesignSystemId : designSystemId;
     if (linkedDesignSystemId) {
-      try {
-        await assertAccess("design-system", linkedDesignSystemId, "viewer");
-      } catch {
-        if (designSystemId !== undefined)
+      const designSystemAccess = await resolveAccess(
+        "design-system",
+        linkedDesignSystemId,
+      );
+      if (!designSystemAccess) {
+        if (designSystemId !== undefined) {
           throw new Error("Design system not found");
+        }
         linkedDesignSystemId = null;
       }
     }
+    const designSystemOverridden =
+      designSystemId !== undefined && designSystemId !== templateDesignSystemId;
+    const adaptationPending = Boolean(prompt);
 
     const ownerEmail = getRequestUserEmail();
     if (!ownerEmail) throw new Error("Not authenticated");
@@ -149,6 +155,9 @@ export default defineAction({
       category: templateCategory,
       templateUpdatedAt,
       instantiatedAt: now,
+      templateDesignSystemId,
+      appliedDesignSystemId: linkedDesignSystemId,
+      designSystemOverridden,
     };
     if (prompt) data.templatePrompt = prompt;
 
@@ -190,6 +199,8 @@ export default defineAction({
       title: title ?? templateTitle,
       templateId,
       templateTitle,
+      designSystemId: linkedDesignSystemId,
+      designSystemOverridden,
       fileCount: files.length,
       lockedLayerCount: countLockedLayersAcrossFiles(persistedFiles),
       templateBaselineFiles: persistedFiles.map((file) => ({
@@ -197,7 +208,8 @@ export default defineAction({
         contentHash: sourceContentHash(file.content),
       })),
       promptPending: Boolean(prompt),
-      nextRequiredAction: prompt
+      adaptationPending,
+      nextRequiredAction: adaptationPending
         ? "Call get-design-snapshot, then refine unlocked content with edit-design. Do not call generate-design."
         : null,
     };

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

@@ -15,7 +15,7 @@ const PREVIEW_MAX_BYTES = 50_000;
 
 export default defineAction({
   description:
-    "List reusable Design templates, including built-in starters plus templates the user can access or publicly discover.",
+    "List reusable Design templates, including built-in templates plus templates the user can access or publicly discover.",
   schema: z.object({
     category: designTemplateCategorySchema.optional(),
     includePreview: z.enum(["true", "false"]).optional().default("false"),
@@ -25,10 +25,11 @@ export default defineAction({
   run: async ({ category, includePreview }) => {
     const db = getDb();
     const userEmail = getRequestUserEmail();
+    const orgId = getRequestOrgId();
     const access = accessFilter(
       schema.designTemplates,
       schema.designTemplateShares,
-      { userEmail, orgId: getRequestOrgId() },
+      { userEmail, orgId },
       "viewer",
       { includePublic: true },
     );
@@ -41,6 +42,7 @@ export default defineAction({
         width: schema.designTemplates.width,
         height: schema.designTemplates.height,
         lockedLayerCount: schema.designTemplates.lockedLayerCount,
+        designSystemId: schema.designTemplates.designSystemId,
         visibility: schema.designTemplates.visibility,
         ownerEmail: schema.designTemplates.ownerEmail,
         createdAt: schema.designTemplates.createdAt,
@@ -54,31 +56,68 @@ export default defineAction({
       )
       .orderBy(desc(schema.designTemplates.updatedAt));
 
-    const previews = new Map<string, string>();
-    if (includePreview === "true" && rows.length > 0) {
-      const files = await db
-        .select({
-          templateId: schema.designTemplateFiles.templateId,
-          filename: schema.designTemplateFiles.filename,
-          fileType: schema.designTemplateFiles.fileType,
-          content: sql<string>`substr(${schema.designTemplateFiles.content}, 1, ${PREVIEW_MAX_BYTES})`,
-        })
-        .from(schema.designTemplateFiles)
-        .where(
-          inArray(
-            schema.designTemplateFiles.templateId,
-            rows.map((row) => row.id),
+    const linkedDesignSystemIds = Array.from(
+      new Set(
+        rows
+          .map((row) => row.designSystemId)
+          .filter(
+            (id): id is string => typeof id === "string" && id.length > 0,
           ),
-        );
+      ),
+    );
+    const [files, accessibleDesignSystems] = await Promise.all([
+      includePreview === "true" && rows.length > 0
+        ? db
+            .select({
+              templateId: schema.designTemplateFiles.templateId,
+              filename: schema.designTemplateFiles.filename,
+              fileType: schema.designTemplateFiles.fileType,
+              content: sql<string>`substr(${schema.designTemplateFiles.content}, 1, ${PREVIEW_MAX_BYTES})`,
+            })
+            .from(schema.designTemplateFiles)
+            .where(
+              and(
+                inArray(
+                  schema.designTemplateFiles.templateId,
+                  rows.map((row) => row.id),
+                ),
+                eq(schema.designTemplateFiles.fileType, "html"),
+              ),
+            )
+        : Promise.resolve([]),
+      linkedDesignSystemIds.length > 0
+        ? db
+            .select({ id: schema.designSystems.id })
+            .from(schema.designSystems)
+            .where(
+              and(
+                inArray(schema.designSystems.id, linkedDesignSystemIds),
+                accessFilter(
+                  schema.designSystems,
+                  schema.designSystemShares,
+                  { userEmail, orgId },
+                  "viewer",
+                  { includePublic: true },
+                ),
+              ),
+            )
+        : Promise.resolve([]),
+    ]);
+
+    const previews = new Map<string, string>();
+    if (includePreview === "true") {
       for (const file of files) {
-        if (!previews.has(file.templateId) && file.fileType === "html") {
+        if (!previews.has(file.templateId)) {
           previews.set(file.templateId, file.content);
         }
-        if (file.filename === "index.html" && file.fileType === "html") {
+        if (file.filename === "index.html") {
           previews.set(file.templateId, file.content);
         }
       }
     }
+    const accessibleDesignSystemIds = new Set(
+      accessibleDesignSystems.map((system) => system.id),
+    );
 
     const presets = DESIGN_TEMPLATE_PRESETS.filter(
       (preset) => !category || preset.category === category,
@@ -90,18 +129,25 @@ export default defineAction({
       width: preset.width,
       height: preset.height,
       lockedLayerCount: 2,
+      designSystemId: null,
       visibility: "public" as const,
       isOwner: false,
+      isBuiltIn: true,
       source: "starter" as const,
       createdAt: null,
       updatedAt: null,
       ...(includePreview === "true" ? { previewHtml: preset.content } : {}),
     }));
 
-    const saved = rows.map(({ ownerEmail, ...row }) => ({
+    const saved = rows.map(({ ownerEmail, designSystemId, ...row }) => ({
       ...row,
+      designSystemId:
+        designSystemId && accessibleDesignSystemIds.has(designSystemId)
+          ? designSystemId
+          : null,
       isOwner:
         !!userEmail && ownerEmail.toLowerCase() === userEmail.toLowerCase(),
+      isBuiltIn: false,
       source: "saved" as const,
       ...(includePreview === "true"
         ? { previewHtml: previews.get(row.id) ?? null }
@@ -110,9 +156,11 @@ export default defineAction({
 
     return {
       count: presets.length + saved.length,
+      builtInCount: presets.length,
+      userCount: saved.length,
       starterCount: presets.length,
       savedCount: saved.length,
-      templates: [...presets, ...saved],
+      templates: [...saved, ...presets],
     };
   },
 });

package/corpus/templates/design/actions/navigate.ts

@@ -24,7 +24,7 @@
  *   --filename   Screen filename to focus in the design editor
  *   --tool       Design editor tool to activate
  *   --designSystemId Design system ID (for design-systems view)
- *   --templateId Saved or starter template ID (for templates view)
+ *   --templateId Saved or built-in template ID (for templates view)
  *   --path       URL path to navigate to
  */
 
@@ -122,7 +122,7 @@ export default defineAction({
       templateId: z
         .string()
         .optional()
-        .describe("Saved or starter template ID for templates view"),
+        .describe("Saved or built-in template ID for templates view"),
       path: z.string().optional().describe("URL path to navigate to"),
     })
     .superRefine((args, ctx) => {

package/corpus/templates/design/actions/view-screen.ts

@@ -244,7 +244,9 @@ export default defineAction({
           width: preset.width,
           height: preset.height,
           lockedLayerCount: 2,
-          source: "starter",
+          designSystemId: null,
+          isBuiltIn: true,
+          source: "built-in",
         };
       } else {
         const templateAccess = await resolveAccess(
@@ -253,6 +255,15 @@ export default defineAction({
         ).catch(() => null);
         if (templateAccess) {
           const template = templateAccess.resource;
+          const linkedDesignSystemId =
+            typeof template.designSystemId === "string"
+              ? template.designSystemId
+              : null;
+          const designSystemAccess = linkedDesignSystemId
+            ? await resolveAccess("design-system", linkedDesignSystemId).catch(
+                () => null,
+              )
+            : null;
           screen.template = {
             id: templateId,
             title: template.title ?? null,
@@ -261,8 +272,10 @@ export default defineAction({
             width: template.width ?? null,
             height: template.height ?? null,
             lockedLayerCount: template.lockedLayerCount ?? 0,
+            designSystemId: designSystemAccess ? linkedDesignSystemId : null,
             visibility: template.visibility ?? "private",
-            source: "saved",
+            isBuiltIn: false,
+            source: "user",
           };
         }
       }

package/corpus/templates/design/agent-native.app-skill.json

@@ -37,6 +37,11 @@
     }
   ],
   "skills": [
+    {
+      "path": ".agents/skills/design-templates",
+      "visibility": "both",
+      "exportAs": "design-templates"
+    },
     {
       "path": ".agents/skills/design-generation",
       "visibility": "both",

package/corpus/templates/design/app/components/design/design-canvas/external-preview.ts

@@ -110,12 +110,16 @@ export function sanitizeLocalhostSourceSnapshotHtml(html: string): string {
   );
 }
 
+// Prototypes are still sandboxed, but user-initiated print/download controls
+// need the browser permissions that make `window.print()` and download links
+// work inside an iframe. Without these tokens the browser silently ignores
+// the common "Download / Print PDF" pattern.
 const EXTERNAL_PREVIEW_IFRAME_SANDBOX =
-  "allow-scripts allow-forms allow-popups allow-popups-to-escape-sandbox allow-same-origin";
+  "allow-scripts allow-forms allow-popups allow-popups-to-escape-sandbox allow-downloads allow-modals allow-same-origin";
 const EDITABLE_INLINE_IFRAME_SANDBOX =
-  "allow-scripts allow-popups allow-popups-to-escape-sandbox allow-same-origin";
+  "allow-scripts allow-popups allow-popups-to-escape-sandbox allow-downloads allow-modals allow-same-origin";
 const READ_ONLY_INLINE_IFRAME_SANDBOX =
-  "allow-scripts allow-popups allow-popups-to-escape-sandbox";
+  "allow-scripts allow-popups allow-popups-to-escape-sandbox allow-downloads allow-modals";
 
 export function getDesignCanvasIframeSandbox(args: {
   externalPreview: boolean;