@agent-native/core 0.82.0 → 0.84.0

package/corpus/templates/content/shared/nfm-registry.ts

@@ -36,6 +36,7 @@ import {
 
 import { builderDocsBlockConfigs } from "./builder-docs-blocks";
 import { inlineDatabaseBlockConfig } from "./inline-database-block";
+import { sourceComponentBlockConfig } from "./source-component-block";
 
 /**
  * Register the content block library (the dev-doc + OpenAPI + standard
@@ -62,6 +63,7 @@ export function registerContentBlocks(registry: BlockRegistry): void {
   for (const block of builderDocsBlockConfigs) {
     registry.register(block);
   }
+  registry.register(sourceComponentBlockConfig);
   registry.register(inlineDatabaseBlockConfig);
 }
 

package/corpus/templates/content/shared/source-component-block.ts

@@ -0,0 +1,141 @@
+import {
+  defineBlock,
+  type BlockMdxConfig,
+  type BlockSpec,
+} from "@agent-native/core/blocks/server";
+import { z } from "zod";
+
+export interface SourceComponentData {
+  provider: string;
+  componentName: string;
+  rawRef: string;
+  rawHash: string;
+  sourceLabel?: string;
+  previewStatus?: "available" | "unavailable" | "warning";
+  previewKind?: "summary" | "table" | "embed" | "symbol" | "component";
+  previewUrl?: string;
+  previewItems?: string[];
+  preview?: SourceComponentPreview;
+  title?: string;
+  summary?: string;
+}
+
+export interface SourceComponentPreview {
+  status: "available" | "unavailable" | "warning";
+  kind: "summary" | "table" | "embed" | "symbol" | "component";
+  label: string;
+  summary?: string;
+  fields?: SourceComponentPreviewField[];
+  table?: SourceComponentPreviewTable;
+  url?: string;
+}
+
+export interface SourceComponentPreviewField {
+  label: string;
+  value: string;
+}
+
+export interface SourceComponentPreviewTable {
+  columns: SourceComponentPreviewTableColumn[];
+  rows: Record<string, string>[];
+  truncated?: boolean;
+}
+
+export interface SourceComponentPreviewTableColumn {
+  id: string;
+  label: string;
+}
+
+const sourceComponentPreviewFieldSchema = z.object({
+  label: z.string().trim().min(1).max(80),
+  value: z.string().trim().max(200),
+});
+
+const sourceComponentPreviewTableColumnSchema = z.object({
+  id: z.string().trim().min(1).max(80),
+  label: z.string().trim().min(1).max(120),
+});
+
+const sourceComponentPreviewTableSchema = z.object({
+  columns: z.array(sourceComponentPreviewTableColumnSchema).max(12),
+  rows: z.array(z.record(z.string(), z.string().max(500))).max(6),
+  truncated: z.boolean().optional(),
+});
+
+const sourceComponentPreviewSchema = z.object({
+  status: z.enum(["available", "unavailable", "warning"]),
+  kind: z.enum(["summary", "table", "embed", "symbol", "component"]),
+  label: z.string().trim().min(1).max(160),
+  summary: z.string().trim().max(500).optional(),
+  fields: z.array(sourceComponentPreviewFieldSchema).max(8).optional(),
+  table: sourceComponentPreviewTableSchema.optional(),
+  url: z.string().trim().max(2_000).optional(),
+}) satisfies z.ZodType<SourceComponentPreview>;
+
+export const sourceComponentSchema = z.object({
+  provider: z.string().trim().min(1).max(80),
+  componentName: z.string().trim().min(1).max(160),
+  rawRef: z.string().trim().min(1),
+  rawHash: z.string().trim().min(1),
+  sourceLabel: z.string().trim().max(200).optional(),
+  previewStatus: z.enum(["available", "unavailable", "warning"]).optional(),
+  previewKind: z
+    .enum(["summary", "table", "embed", "symbol", "component"])
+    .optional(),
+  previewUrl: z.string().trim().max(2_000).optional(),
+  previewItems: z.array(z.string().trim().max(160)).max(8).optional(),
+  preview: sourceComponentPreviewSchema.optional(),
+  title: z.string().trim().max(200).optional(),
+  summary: z.string().trim().max(500).optional(),
+}) as unknown as z.ZodType<SourceComponentData>;
+
+export const sourceComponentMdx: BlockMdxConfig<SourceComponentData> = {
+  tag: "SourceComponent",
+  toAttrs: (data) => ({
+    provider: data.provider,
+    componentName: data.componentName,
+    rawRef: data.rawRef,
+    rawHash: data.rawHash,
+    sourceLabel: data.sourceLabel,
+    previewStatus: data.previewStatus,
+    previewKind: data.previewKind,
+    previewUrl: data.previewUrl,
+    previewItems: data.previewItems,
+    preview: data.preview as Record<string, unknown> | undefined,
+    previewTitle: data.title,
+    summary: data.summary,
+  }),
+  fromAttrs: (attrs) => ({
+    provider: attrs.string("provider") ?? "",
+    componentName: attrs.string("componentName") ?? "",
+    rawRef: attrs.string("rawRef") ?? "",
+    rawHash: attrs.string("rawHash") ?? "",
+    sourceLabel: attrs.string("sourceLabel"),
+    previewStatus: attrs.string("previewStatus") as
+      | SourceComponentData["previewStatus"]
+      | undefined,
+    previewKind: attrs.string("previewKind") as
+      | SourceComponentData["previewKind"]
+      | undefined,
+    previewUrl: attrs.string("previewUrl"),
+    previewItems: attrs.array<string>("previewItems"),
+    preview: attrs.object<SourceComponentPreview>("preview"),
+    title: attrs.string("previewTitle") ?? attrs.string("title"),
+    summary: attrs.string("summary"),
+  }),
+};
+
+const ServerReadStub = () => null;
+
+export const sourceComponentBlockConfig: BlockSpec<SourceComponentData> =
+  defineBlock<SourceComponentData>({
+    type: "source-component",
+    schema: sourceComponentSchema,
+    mdx: sourceComponentMdx,
+    Read: ServerReadStub,
+    placement: ["block"],
+    editSurface: "none",
+    label: "Source component",
+    description:
+      "A read-only source-native component marker that preserves provider-specific body blocks for round-trip sync.",
+  });

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

@@ -65,9 +65,14 @@ For one-shot agent setup, ask for JSON and keep the long-running bridge open in
 a second terminal if the user needs live updates:
 
 ```bash
-npx @agent-native/core@latest design connect --url http://localhost:5173 --root . --json
+npx @agent-native/core@latest design connect --url http://localhost:5173 --root .
+curl http://127.0.0.1:7331/manifest.json
 ```
 
+Do not use `--json` for an editable session. `--json`, `--once`, and
+`--dry-run` print the manifest and exit, so Design will fall back to a
+non-editable live iframe as soon as it tries to refresh the snapshot.
+
 ## Action Flow
 
 1. Register or refresh the bridge in Design:

package/corpus/templates/design/actions/add-localhost-screens.ts

@@ -17,6 +17,7 @@ import { z } from "zod";
 import { getDb, schema } from "../server/db/index.js";
 import {
   mergeCanvasFramePlacements,
+  parseCanvasFrameGeometryById,
   type CanvasFramePlacement,
 } from "../shared/canvas-frames.js";
 import {
@@ -148,6 +149,25 @@ function uniqueFilename(
   return filename;
 }
 
+export function viewportFilename(
+  pathOrUrl: string,
+  width: number,
+  height: number,
+) {
+  const viewport = `${Math.round(width)}x${Math.round(height)}`;
+  return `localhost-${slugForPath(pathOrUrl)}-${viewport}.html`;
+}
+
+function metadataNumber(
+  metadata: Record<string, unknown> | undefined,
+  key: "width" | "height",
+) {
+  const value = metadata?.[key];
+  return typeof value === "number" && Number.isFinite(value)
+    ? value
+    : undefined;
+}
+
 export default defineAction({
   description:
     "Create or refresh URL-backed localhost screens in a design project. " +
@@ -179,14 +199,12 @@ export default defineAction({
       .number()
       .positive()
       .optional()
-      .default(1280)
-      .describe("Default iframe viewport width."),
+      .describe("Default iframe viewport width. Defaults to 1280."),
     defaultHeight: z
       .number()
       .positive()
       .optional()
-      .default(900)
-      .describe("Default iframe viewport height."),
+      .describe("Default iframe viewport height. Defaults to 900."),
     startX: z.number().optional().default(0),
     startY: z.number().optional().default(0),
     gap: z.number().optional().default(160),
@@ -292,6 +310,13 @@ export default defineAction({
       .from(schema.designs)
       .where(eq(schema.designs.id, designId))
       .limit(1);
+    const prevData = parseJson<Record<string, unknown>>(design?.data, {});
+    const existingCanvasFrames = parseCanvasFrameGeometryById(
+      prevData.canvasFrames,
+    );
+    const existingMetadata = isRecord(prevData.screenMetadata)
+      ? (prevData.screenMetadata as Record<string, unknown>)
+      : {};
     const existingFiles = await db
       .select()
       .from(schema.designFiles)
@@ -301,6 +326,8 @@ export default defineAction({
     );
     const usedFilenames = new Set(existingFiles.map((file) => file.filename));
     const now = new Date().toISOString();
+    const effectiveDefaultWidth = defaultWidth ?? 1280;
+    const effectiveDefaultHeight = defaultHeight ?? 900;
     const savedScreens: Array<{
       id: string;
       filename: string;
@@ -333,9 +360,38 @@ export default defineAction({
       const title =
         input.title ?? manifestRoute?.title ?? titleFromRoutePath(path);
       const sourceFile = input.sourceFile ?? manifestRoute?.sourceFile;
-      const width = input.width ?? defaultWidth;
-      const height = input.height ?? defaultHeight;
-      const preferredFilename = `localhost-${slugForPath(path)}.html`;
+      const width = input.width ?? effectiveDefaultWidth;
+      const height = input.height ?? effectiveDefaultHeight;
+      const basePreferredFilename = `localhost-${slugForPath(path)}.html`;
+      const existingBase = existingByFilename.get(basePreferredFilename);
+      const requestedViewportExplicitly =
+        input.width !== undefined ||
+        input.height !== undefined ||
+        defaultWidth !== undefined ||
+        defaultHeight !== undefined;
+      const existingBaseMetadata = isRecord(
+        existingBase ? existingMetadata[existingBase.id] : undefined,
+      )
+        ? (existingMetadata[existingBase!.id] as Record<string, unknown>)
+        : undefined;
+      const existingBaseFrame = existingBase
+        ? existingCanvasFrames[existingBase.id]
+        : undefined;
+      const existingBaseWidth =
+        existingBaseFrame?.width ??
+        metadataNumber(existingBaseMetadata, "width");
+      const existingBaseHeight =
+        existingBaseFrame?.height ??
+        metadataNumber(existingBaseMetadata, "height");
+      const viewportDiffersFromBase =
+        (typeof existingBaseWidth === "number" &&
+          existingBaseWidth !== width) ||
+        (typeof existingBaseHeight === "number" &&
+          existingBaseHeight !== height);
+      const preferredFilename =
+        existingBase && requestedViewportExplicitly && viewportDiffersFromBase
+          ? viewportFilename(path, width, height)
+          : basePreferredFilename;
       const existing = existingByFilename.get(preferredFilename);
       const filename =
         existing?.filename ??
@@ -387,7 +443,6 @@ export default defineAction({
       });
     }
 
-    const prevData = parseJson<Record<string, unknown>>(design?.data, {});
     const mergedFrames = mergeCanvasFramePlacements({
       existing: prevData.canvasFrames,
       placements,

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

@@ -31,6 +31,7 @@ import {
   assertSafeMotionCssProperty,
   assertSafeMotionCssToken,
   compile,
+  injectManagedMotionCss,
 } from "../shared/motion-compiler.js";
 import type { MotionTrack } from "../shared/motion-timeline.js";
 
@@ -69,55 +70,12 @@ const trackSchema = z.object({
 
 // ─── Helpers ──────────────────────────────────────────────────────────────────
 
-const MOTION_STYLE_OPEN = "<style data-agent-native-motion>";
-const MOTION_STYLE_CLOSE = "</style>";
-
-/**
- * Bounded, case-insensitive matcher for any HTML `</style>` end tag
- * (`</style >`, `</STYLE>`, …). Used to locate the close of the managed block
- * without a naive `indexOf("</style>")` that would miss case/whitespace
- * variants — and to detect any `</style` sequence smuggled into compiled CSS.
- */
-const STYLE_CLOSE_RE = /<\s*\/\s*style\b[^>]*>/i;
-
-/**
- * Inject or replace the managed `<style data-agent-native-motion>` block in
- * the HTML content.  Inserts before `</head>` when not already present.
- */
-function injectMotionStyle(html: string, css: string): string {
-  const open = MOTION_STYLE_OPEN;
-  const close = MOTION_STYLE_CLOSE;
-  const openIdx = html.indexOf(open);
-
-  if (openIdx !== -1) {
-    // Find the matching closing tag after the open tag using a bounded regex
-    // (tolerates `</style >`, `</STYLE>`, etc.) instead of a literal indexOf.
-    const after = html.slice(openIdx + open.length);
-    const closeMatch = STYLE_CLOSE_RE.exec(after);
-    if (closeMatch) {
-      const closeIdx = openIdx + open.length + closeMatch.index;
-      // Replace the existing block.
-      return (
-        html.slice(0, openIdx) + open + "\n" + css + "\n" + html.slice(closeIdx)
-      );
-    }
-  }
-
-  // Not found — insert before </head> or, if there is no <head>, at the top.
-  const headClose = html.lastIndexOf("</head>");
-  const block = `${open}\n${css}\n${close}`;
-  if (headClose !== -1) {
-    return html.slice(0, headClose) + block + "\n" + html.slice(headClose);
-  }
-  return block + "\n" + html;
-}
-
 async function persistFileContent(
   fileId: string,
   designId: string,
   content: string,
   now: string,
-): Promise<void> {
+): Promise<string> {
   const db = getDb();
   await db
     .update(schema.designFiles)
@@ -134,6 +92,8 @@ async function persistFileContent(
     .update(schema.designs)
     .set({ updatedAt: now })
     .where(eq(schema.designs.id, designId));
+
+  return now;
 }
 
 // ─── Action ───────────────────────────────────────────────────────────────────
@@ -296,7 +256,7 @@ export default defineAction({
     });
 
     // ── 3. Inject the managed CSS block into the HTML ───────────────────────
-    const patchedContent = injectMotionStyle(currentContent, css);
+    const patchedContent = injectManagedMotionCss(currentContent, css);
     const bytesBefore = currentContent.length;
     const bytesAfter = patchedContent.length;
 
@@ -392,7 +352,12 @@ export default defineAction({
     // Written after the row so a SQL failure here leaves the timeline row
     // accurate (correct tracks + hash) and the stale HTML can be recompiled on
     // the next apply-motion-edit call via compiledHash drift detection.
-    await persistFileContent(fileId, designId, patchedContent, now);
+    const updatedAt = await persistFileContent(
+      fileId,
+      designId,
+      patchedContent,
+      now,
+    );
 
     return {
       timelineId: resolvedTimelineId,
@@ -401,6 +366,7 @@ export default defineAction({
       sourceRef: resolvedSourceRef,
       trackCount: typedTracks.length,
       compiledHash: hash,
+      updatedAt,
       bytesBefore,
       bytesAfter,
       bytesDelta: bytesAfter - bytesBefore,

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

@@ -90,7 +90,8 @@ export default defineAction({
   }),
   http: { method: "GET" },
   readOnly: true,
-  publicAgent: { expose: true, readOnly: true, requiresAuth: true },
+  requiresAuth: false,
+  publicAgent: { expose: true, readOnly: true, requiresAuth: false },
   run: ({ category }) => {
     const assets = category
       ? DESIGN_NATIVE_ASSETS.filter((asset) => asset.category === category)

package/corpus/templates/design/actions/migrate-board-objects-to-file.ts

@@ -39,6 +39,7 @@ import { z } from "zod";
 import { getDb, schema } from "../server/db/index.js";
 import {
   BOARD_FILENAME,
+  backfillBoardPrimitiveMarkers,
   boardObjectEntryToHtmlFragment,
   emptyBoardHtml,
 } from "../shared/board-file.js";
@@ -91,10 +92,57 @@ export default defineAction({
       typeof parsed["boardFileId"] === "string" &&
       parsed["boardFileId"].length > 0
     ) {
+      // ── Marker backfill path ───────────────────────────────────────────────
+      // The board file exists (boardFileId set), but it may have been created
+      // before the data-an-primitive marker was introduced.  Run the additive
+      // backfill so the layers-panel renders the correct icon (ellipse / text /
+      // frame / rectangle) instead of the generic code glyph.
+      const existingBoardFileId = parsed["boardFileId"] as string;
+
+      const [boardFileRow] = await db
+        .select({ content: schema.designFiles.content })
+        .from(schema.designFiles)
+        .where(eq(schema.designFiles.id, existingBoardFileId))
+        .limit(1);
+
+      if (boardFileRow) {
+        const originalContent = boardFileRow.content ?? "";
+        // Only run backfill when the board file has node-id elements but is
+        // missing at least one data-an-primitive marker.
+        const needsBackfill =
+          originalContent.includes("data-agent-native-node-id=") &&
+          !originalContent.includes("data-an-primitive=");
+
+        if (needsBackfill) {
+          const backfilledContent =
+            backfillBoardPrimitiveMarkers(originalContent);
+          const now = new Date().toISOString();
+          await db
+            .update(schema.designFiles)
+            .set({ content: backfilledContent, updatedAt: now })
+            .where(eq(schema.designFiles.id, existingBoardFileId));
+
+          // Best-effort collab re-seed.
+          try {
+            await seedFromText(existingBoardFileId, backfilledContent);
+          } catch {
+            // Non-fatal.
+          }
+
+          return {
+            designId,
+            migrated: false,
+            boardFileId: existingBoardFileId,
+            reason:
+              "boardFileId already set — backfilled missing data-an-primitive markers.",
+          };
+        }
+      }
+
       return {
         designId,
         migrated: false,
-        boardFileId: parsed["boardFileId"] as string,
+        boardFileId: existingBoardFileId,
         reason: "boardFileId already set — migration already complete.",
       };
     }

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

@@ -10,12 +10,11 @@
  *   pnpm action navigate --view=editor --designId=abc123 --filename=checkout.html
  *   pnpm action navigate --view=design-systems
  *   pnpm action navigate --view=design-systems --designSystemId=abc123
- *   pnpm action navigate --view=templates
  *   pnpm action navigate --view=settings
  *   pnpm action navigate --path=/some/route
  *
  * Options:
- *   --view       View name (list, editor, design-systems, present, templates, settings)
+ *   --view       View name (list, editor, design-systems, present, settings)
  *   --designId   Design ID (for editor/present views)
  *   --editorView Editor mode for designs: single or overview
  *   --inspectorTab Inspector tab for designs: design or tweaks (extensions opens Tools for compatibility)
@@ -58,19 +57,11 @@ const designLeftPanelSchema = z.enum([
 
 export default defineAction({
   description:
-    "Navigate the UI to a specific view or path. Views: list, editor, design-systems, present, templates, settings. Use --designId with editor/present views and --designSystemId with design-systems. For designs, use editorView=overview to show the infinite screens canvas, or editorView=single with fileId/filename/screen to focus a screen. Use leftPanel=file|agent|assets|tools|tokens to focus the Figma-style left rail. Legacy inspectorTab=extensions opens Tools. Use tool to activate a design editor tool.",
+    "Navigate the UI to a specific view or path. Views: list, editor, design-systems, present, settings. Use --designId with editor/present views and --designSystemId with design-systems. For designs, use editorView=overview to show the infinite screens canvas, or editorView=single with fileId/filename/screen to focus a screen. Use leftPanel=file|agent|assets|tools|tokens to focus the Figma-style left rail. Legacy inspectorTab=extensions opens Tools. Use tool to activate a design editor tool.",
   schema: z
     .object({
       view: z
-        .enum([
-          "list",
-          "editor",
-          "design-systems",
-          "present",
-          "templates",
-          "examples",
-          "settings",
-        ])
+        .enum(["list", "editor", "design-systems", "present", "settings"])
         .optional()
         .describe("View name to navigate to"),
       designId: z.string().optional().describe("Design ID for editor/present"),