@agent-native/core 0.83.0 → 0.84.1

package/corpus/templates/content/parity/render-matrix.ts

@@ -0,0 +1,90 @@
+import { writeFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+
+import { parityMatrix } from "./matrix";
+import type { ParityRow } from "./matrix.types";
+
+function escapeCell(value: string) {
+  return value.replace(/\|/g, "\\|").replace(/\n/g, "<br>");
+}
+
+function cell(value: string | string[] | null | undefined) {
+  if (Array.isArray(value))
+    return escapeCell(value.length ? value.join(", ") : "-");
+  if (value === null || value === undefined || value === "") return "-";
+  return escapeCell(value);
+}
+
+const headers = [
+  "ID",
+  "Surface",
+  "User-visible action",
+  "Status",
+  "Actions",
+  "UI entrypoints",
+  "Durable effect",
+  "Exception / gap",
+  "Reliability risk",
+  "Spine priority",
+  "Test coverage",
+  "Coverage refs",
+  "Eval scenarios",
+  "Follow-up",
+];
+
+function renderRow(row: ParityRow) {
+  return [
+    row.id,
+    row.surface,
+    row.label,
+    row.status,
+    row.actions.length
+      ? row.actions.map((action) => `\`${action}\``).join(", ")
+      : "-",
+    row.uiEntrypoints.map((entry) => `\`${entry}\``).join(", "),
+    row.durableEffect,
+    row.exception,
+    row.reliabilityRisk === "none" ? "-" : row.reliabilityRisk,
+    row.spinePriority,
+    row.testCoverage,
+    row.coverageRefs?.map((ref) => `\`${ref}\``).join(", "),
+    row.evalScenarioIds?.map((id) => `\`${id}\``).join(", "),
+    row.followUpPR,
+  ].map(cell);
+}
+
+function renderTable(rows: string[][]) {
+  const widths = headers.map((header, index) =>
+    Math.max(header.length, ...rows.map((row) => row[index]?.length ?? 0)),
+  );
+  const renderCells = (cells: string[]) =>
+    `| ${cells.map((value, index) => value.padEnd(widths[index])).join(" | ")} |`;
+  return [
+    renderCells(headers),
+    renderCells(widths.map((width) => "-".repeat(width))),
+    ...rows.map(renderCells),
+  ];
+}
+
+export function renderParityMatrixMarkdown(rows: ParityRow[] = parityMatrix) {
+  const sortedRows = [...rows].sort((a, b) => a.id.localeCompare(b.id));
+  return [
+    "# Content Agent/UI Action Parity Matrix",
+    "",
+    "This generated matrix tracks whether high-value Content UI operations use the same action surface agents can call, or have an explicit exception. Edit `matrix.ts`, then regenerate this file.",
+    "",
+    ...renderTable(sortedRows.map(renderRow)),
+    "",
+  ].join("\n");
+}
+
+const isCli = process.argv[1] === fileURLToPath(import.meta.url);
+
+if (isCli) {
+  const markdown = renderParityMatrixMarkdown();
+  if (process.argv.includes("--write")) {
+    writeFileSync(new URL("./matrix.md", import.meta.url), markdown);
+  } else {
+    process.stdout.write(markdown);
+  }
+}

package/corpus/templates/content/parity/scenario-to-eval.ts

@@ -0,0 +1,57 @@
+import {
+  contains,
+  createScorer,
+  defineEval,
+  type AgentRunOutput,
+  type Eval,
+} from "@agent-native/core/eval";
+
+import type { ParityEvalScenario } from "./eval-scenarios.ts";
+
+function expectedToolScorer(expectedTools: string[]) {
+  return createScorer<AgentRunOutput, { used: string[]; missing: string[] }>({
+    name: "expected_tools",
+    analyze(run) {
+      const usedTools = new Set(run.toolCalls);
+      return {
+        used: expectedTools.filter((tool) => usedTools.has(tool)),
+        missing: expectedTools.filter((tool) => !usedTools.has(tool)),
+      };
+    },
+    generateScore({ missing }) {
+      return expectedTools.length === 0 || missing.length === 0 ? 1 : 0;
+    },
+    generateReason({ analysis: { used, missing } }) {
+      if (missing.length === 0) {
+        return `Agent called all expected tool(s): ${used.join(", ")}`;
+      }
+      return `Called expected tool(s): ${used.join(", ") || "none"}; missing: ${missing.join(", ")}`;
+    },
+  });
+}
+
+export function scenarioToEval(scenario: ParityEvalScenario): Eval {
+  const name = `content-parity:${scenario.id}`;
+
+  if (!process.env[scenario.gateEnv]) {
+    return defineEval({
+      name,
+      input: { prompt: scenario.prompt },
+      threshold: 1,
+      skipReason: `Skipped because ${scenario.gateEnv} is unset`,
+      scorers: [],
+    });
+  }
+
+  return defineEval({
+    name,
+    input: { prompt: scenario.prompt },
+    threshold: 0.6,
+    scorers: [
+      contains(scenario.successSignals),
+      ...(scenario.expectedTools?.length
+        ? [expectedToolScorer(scenario.expectedTools)]
+        : []),
+    ],
+  });
+}

package/corpus/templates/content/shared/api.ts

@@ -646,6 +646,10 @@ export interface ContentDatabaseResponse {
   createdDocumentId?: string;
   duplicatedItemId?: string;
   duplicatedDocumentId?: string;
+  duplicatedItemIds?: string[];
+  duplicatedDocumentIds?: string[];
+  deletedItemIds?: string[];
+  deletedDocumentIds?: string[];
 }
 
 export interface ContentDatabaseUnavailableResponse {
@@ -701,6 +705,13 @@ export interface DuplicateDatabaseItemRequest {
   title?: string;
 }
 
+export interface DatabaseItemsBatchRequest {
+  databaseId?: string;
+  documentId?: string;
+  itemIds?: string[];
+  documentIds?: string[];
+}
+
 export interface MoveDatabaseItemRequest {
   itemId?: string;
   documentId?: string;

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"),