@agent-native/core 0.80.10 → 0.81.0

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

@@ -6,6 +6,18 @@ import { z } from "zod";
 import { getDb, schema } from "../server/db/index.js";
 import "../server/db/index.js"; // ensure registerShareableResource runs
 
+function parseJsonRecord(raw: string | null): Record<string, unknown> | null {
+  if (!raw) return null;
+  try {
+    const parsed = JSON.parse(raw) as unknown;
+    return parsed && typeof parsed === "object" && !Array.isArray(parsed)
+      ? (parsed as Record<string, unknown>)
+      : null;
+  } catch {
+    return null;
+  }
+}
+
 export default defineAction({
   description:
     "List all design states, fixtures, and captures for a design. " +
@@ -52,6 +64,8 @@ export default defineAction({
         kind: schema.designState.kind,
         breakpoint: schema.designState.breakpoint,
         route: schema.designState.route,
+        fixtureData: schema.designState.fixtureData,
+        captureData: schema.designState.captureData,
         previewRef: schema.designState.previewRef,
         createdAt: schema.designState.createdAt,
         updatedAt: schema.designState.updatedAt,
@@ -66,7 +80,11 @@ export default defineAction({
 
     return {
       count: rows.length,
-      states: rows,
+      states: rows.map((row) => ({
+        ...row,
+        fixtureData: parseJsonRecord(row.fixtureData),
+        captureData: parseJsonRecord(row.captureData),
+      })),
     };
   },
 });

package/corpus/templates/design/actions/list-figma-library-assets.ts

@@ -0,0 +1,292 @@
+import { defineAction } from "@agent-native/core";
+import { z } from "zod";
+
+import { executeProviderApiRequest } from "../server/lib/provider-api.js";
+
+const FIGMA_FILE_KEY_RE = /^[A-Za-z0-9_-]{8,}$/;
+
+const FigmaRenderFormatSchema = z.enum(["svg", "png"]).default("svg");
+
+const schemaInput = z
+  .object({
+    fileUrl: z
+      .string()
+      .trim()
+      .optional()
+      .describe(
+        "Figma file URL, for example https://www.figma.com/design/<fileKey>/...",
+      ),
+    fileKey: z
+      .string()
+      .trim()
+      .optional()
+      .describe("Figma file key. Used when fileUrl is omitted."),
+    query: z
+      .string()
+      .trim()
+      .optional()
+      .describe("Optional case-insensitive search over names/descriptions."),
+    limit: z.coerce
+      .number()
+      .int()
+      .min(1)
+      .max(64)
+      .default(48)
+      .describe("Maximum number of Figma library assets to return."),
+    renderFormat: FigmaRenderFormatSchema.describe(
+      "Image format for insertable render URLs.",
+    ),
+  })
+  .refine((value) => value.fileUrl || value.fileKey, {
+    message: "Pass fileUrl or fileKey.",
+    path: ["fileUrl"],
+  });
+
+type FigmaProviderEnvelope = {
+  response?: {
+    ok?: boolean;
+    status?: number;
+    statusText?: string;
+    json?: unknown;
+    text?: string;
+  };
+};
+
+type FigmaAssetKind = "component" | "component_set";
+
+type FigmaComponentRecord = {
+  key?: unknown;
+  file_key?: unknown;
+  node_id?: unknown;
+  name?: unknown;
+  description?: unknown;
+  thumbnail_url?: unknown;
+  created_at?: unknown;
+  updated_at?: unknown;
+  containing_frame?: unknown;
+  user?: unknown;
+};
+
+type FigmaImageResponse = {
+  images?: Record<string, string | null | undefined>;
+};
+
+function stringValue(value: unknown): string | null {
+  return typeof value === "string" && value.trim() ? value.trim() : null;
+}
+
+function numberOrDefault(value: number | undefined, fallback: number): number {
+  return typeof value === "number" && Number.isFinite(value) ? value : fallback;
+}
+
+export function parseFigmaFileKey(input: string | undefined): string | null {
+  const value = input?.trim();
+  if (!value) return null;
+  if (FIGMA_FILE_KEY_RE.test(value)) return value;
+
+  try {
+    const url = new URL(value);
+    const parts = url.pathname.split("/").filter(Boolean);
+    for (const segment of ["design", "file", "proto"]) {
+      const index = parts.indexOf(segment);
+      if (index >= 0) {
+        const candidate = parts[index + 1];
+        if (candidate && FIGMA_FILE_KEY_RE.test(candidate)) return candidate;
+      }
+    }
+  } catch {
+    return null;
+  }
+
+  return null;
+}
+
+function figmaNodeUrl(
+  fileKey: string,
+  nodeId: string,
+  fileUrl?: string,
+): string {
+  const nodeParam = nodeId.replace(/:/g, "-");
+  try {
+    const url = new URL(fileUrl || `https://www.figma.com/design/${fileKey}`);
+    url.searchParams.set("node-id", nodeParam);
+    return url.href;
+  } catch {
+    return `https://www.figma.com/design/${fileKey}?node-id=${encodeURIComponent(
+      nodeParam,
+    )}`;
+  }
+}
+
+function recordSearchText(record: FigmaComponentRecord): string {
+  const frame =
+    record.containing_frame &&
+    typeof record.containing_frame === "object" &&
+    "name" in record.containing_frame
+      ? stringValue((record.containing_frame as { name?: unknown }).name)
+      : null;
+  return [stringValue(record.name), stringValue(record.description), frame]
+    .filter(Boolean)
+    .join(" ")
+    .toLowerCase();
+}
+
+function matchesQuery(record: FigmaComponentRecord, query: string | undefined) {
+  const normalized = query?.trim().toLowerCase();
+  if (!normalized) return true;
+  return recordSearchText(record).includes(normalized);
+}
+
+function normalizeFigmaRecords(
+  value: unknown,
+  kind: FigmaAssetKind,
+): FigmaComponentRecord[] {
+  if (!value || typeof value !== "object") return [];
+  const meta = (value as { meta?: unknown }).meta;
+  const key = kind === "component" ? "components" : "component_sets";
+  const records =
+    meta && typeof meta === "object"
+      ? (meta as Record<string, unknown>)[key]
+      : undefined;
+  if (!Array.isArray(records)) return [];
+  return records.filter(
+    (record): record is FigmaComponentRecord =>
+      !!record && typeof record === "object",
+  );
+}
+
+function providerJson(envelope: unknown, label: string): unknown {
+  const response = (envelope as FigmaProviderEnvelope | null)?.response;
+  if (!response) throw new Error(`Figma ${label} response was empty.`);
+  if (response.ok === false) {
+    const detail =
+      stringValue(response.text) ||
+      response.statusText ||
+      `HTTP ${response.status ?? "error"}`;
+    throw new Error(`Figma ${label} request failed: ${detail}`);
+  }
+  return response.json;
+}
+
+async function figmaGet(path: string, query?: Record<string, unknown>) {
+  return executeProviderApiRequest({
+    provider: "figma",
+    method: "GET",
+    path,
+    query,
+    maxBytes: 2 * 1024 * 1024,
+  });
+}
+
+export default defineAction({
+  description:
+    "List reusable assets from a Figma file for the Design asset panel. Returns components and component sets with thumbnails, insertable render URLs, and source provenance. Requires a saved FIGMA_ACCESS_TOKEN secret.",
+  schema: schemaInput,
+  http: { method: "GET" },
+  readOnly: true,
+  publicAgent: { expose: true, readOnly: true, requiresAuth: true },
+  run: async (args) => {
+    const fileKey =
+      parseFigmaFileKey(args.fileKey) ?? parseFigmaFileKey(args.fileUrl);
+    if (!fileKey) {
+      throw new Error("Could not find a Figma file key in the provided URL.");
+    }
+
+    const limit = numberOrDefault(args.limit, 48);
+    const [componentsEnvelope, componentSetsEnvelope] = await Promise.all([
+      figmaGet(`/files/${fileKey}/components`),
+      figmaGet(`/files/${fileKey}/component_sets`),
+    ]);
+    const componentRecords = normalizeFigmaRecords(
+      providerJson(componentsEnvelope, "components"),
+      "component",
+    )
+      .filter((record) => matchesQuery(record, args.query))
+      .map((record) => ({ kind: "component" as const, record }));
+    const componentSetRecords = normalizeFigmaRecords(
+      providerJson(componentSetsEnvelope, "component sets"),
+      "component_set",
+    )
+      .filter((record) => matchesQuery(record, args.query))
+      .map((record) => ({ kind: "component_set" as const, record }));
+
+    const rawItems = [...componentRecords, ...componentSetRecords].slice(
+      0,
+      limit,
+    );
+    const renderIds = rawItems
+      .map((item) => stringValue(item.record.node_id))
+      .filter((id): id is string => !!id);
+    let rendered: Record<string, string | null | undefined> = {};
+    if (renderIds.length > 0) {
+      const imagesEnvelope = await figmaGet(`/images/${fileKey}`, {
+        ids: renderIds.join(","),
+        format: args.renderFormat,
+        svg_include_id: true,
+      });
+      const images = providerJson(
+        imagesEnvelope,
+        "images",
+      ) as FigmaImageResponse;
+      rendered = images.images ?? {};
+    }
+
+    const assets = rawItems
+      .map(({ kind, record }) => {
+        const nodeId = stringValue(record.node_id);
+        const key = stringValue(record.key);
+        const name = stringValue(record.name) ?? "Untitled Figma asset";
+        const description = stringValue(record.description);
+        const thumbnailUrl = stringValue(record.thumbnail_url);
+        const renderUrl = nodeId ? stringValue(rendered[nodeId]) : null;
+        const containingFrame =
+          record.containing_frame && typeof record.containing_frame === "object"
+            ? {
+                name:
+                  stringValue(
+                    (record.containing_frame as { name?: unknown }).name,
+                  ) ?? null,
+                nodeId:
+                  stringValue(
+                    (record.containing_frame as { nodeId?: unknown }).nodeId,
+                  ) ??
+                  stringValue(
+                    (record.containing_frame as { node_id?: unknown }).node_id,
+                  ),
+              }
+            : null;
+
+        return {
+          id: `figma:${fileKey}:${nodeId ?? key ?? name}`,
+          kind,
+          fileKey,
+          nodeId,
+          componentKey: key,
+          name,
+          description,
+          thumbnailUrl,
+          renderUrl,
+          insertUrl: renderUrl ?? thumbnailUrl,
+          sourceUrl: nodeId
+            ? figmaNodeUrl(fileKey, nodeId, args.fileUrl)
+            : null,
+          containingFrame,
+          createdAt: stringValue(record.created_at),
+          updatedAt: stringValue(record.updated_at),
+        };
+      })
+      .filter((asset) => asset.nodeId || asset.componentKey);
+
+    return {
+      source: "figma",
+      fileKey,
+      query: args.query ?? null,
+      renderFormat: args.renderFormat,
+      total: componentRecords.length + componentSetRecords.length,
+      returned: assets.length,
+      assets,
+      guidance:
+        "Use renderUrl/insertUrl with insert-asset and preserve fileKey, nodeId, componentKey, and sourceUrl for provenance. Components/component sets are reusable Figma library assets; styles and variables belong in design-system token sync.",
+    };
+  },
+});

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

@@ -0,0 +1,238 @@
+/**
+ * migrate-board-objects-to-file
+ *
+ * Lazy, idempotent migration that converts the legacy designs.data.boardObjects
+ * JSON blob into the new board file architecture.
+ *
+ * ## What it does
+ *
+ * 1. Guards on boardFileId already set — returns early if the migration has
+ *    already run (idempotent).
+ * 2. Reads designs.data.boardObjects and converts each entry into an HTML
+ *    fragment via boardObjectEntryToHtmlFragment, preserving negative left/top
+ *    coordinates exactly (no clamping).
+ * 3. Inserts the fragments as direct <body> children of a new __board__.html
+ *    design file (or merges into an existing one if somehow already present).
+ * 4. Stores the new file's id into designs.data.boardFileId in a transaction.
+ * 5. Nulls out designs.data.boardObjects so the old model no longer conflicts.
+ *
+ * ## Contract
+ *
+ * - Requires editor access on the design.
+ * - SCHEMA ADDITIVE ONLY — no columns are dropped or renamed; only designs.data
+ *   JSON keys change.
+ * - Safe to call on designs with no board objects: creates the board file with
+ *   an empty body and sets boardFileId.
+ *
+ * ## Trigger
+ *
+ * Called by DesignEditor on design open when designs.data.boardFileId is absent.
+ */
+
+import { defineAction } from "@agent-native/core";
+import { seedFromText } from "@agent-native/core/collab";
+import { assertAccess } from "@agent-native/core/sharing";
+import { and, eq } from "drizzle-orm";
+import { nanoid } from "nanoid";
+import { z } from "zod";
+
+import { getDb, schema } from "../server/db/index.js";
+import {
+  BOARD_FILENAME,
+  boardObjectEntryToHtmlFragment,
+  emptyBoardHtml,
+} from "../shared/board-file.js";
+import { parseBoardObjects } from "../shared/board-objects.js";
+
+export default defineAction({
+  description:
+    "Migrate the legacy boardObjects blob (designs.data.boardObjects) into the " +
+    "new board file architecture. Creates a __board__.html design file, writes " +
+    "each board object as an absolute-positioned HTML element (preserving " +
+    "negative coordinates), stores boardFileId in designs.data, and nulls " +
+    "boardObjects. Idempotent — returns immediately if boardFileId is already " +
+    "set. Requires editor access on the design.",
+  schema: z.object({
+    designId: z
+      .string()
+      .describe("Design project ID to migrate board objects for."),
+  }),
+  run: async ({ designId }) => {
+    await assertAccess("design", designId, "editor");
+
+    const db = getDb();
+
+    // ── 1. Idempotency guard ──────────────────────────────────────────────
+    // Read the design data JSON to check whether boardFileId is already set.
+    // guard:allow-unscoped — assertAccess "editor" above scopes this read to
+    // the requesting user's accessible designs.
+    const [existing] = await db
+      .select({ data: schema.designs.data })
+      .from(schema.designs)
+      .where(eq(schema.designs.id, designId))
+      .limit(1);
+
+    if (!existing) {
+      throw new Error(`Design "${designId}" not found.`);
+    }
+
+    let parsed: Record<string, unknown>;
+    try {
+      const raw = JSON.parse(existing.data);
+      parsed =
+        raw && typeof raw === "object" && !Array.isArray(raw)
+          ? (raw as Record<string, unknown>)
+          : {};
+    } catch {
+      parsed = {};
+    }
+
+    if (
+      typeof parsed["boardFileId"] === "string" &&
+      parsed["boardFileId"].length > 0
+    ) {
+      return {
+        designId,
+        migrated: false,
+        boardFileId: parsed["boardFileId"] as string,
+        reason: "boardFileId already set — migration already complete.",
+      };
+    }
+
+    // ── 2. Parse legacy board objects ────────────────────────────────────
+    const boardObjects = parseBoardObjects(parsed["boardObjects"]);
+    const entries = Object.values(boardObjects);
+
+    // ── 3. Build the board HTML ───────────────────────────────────────────
+    // Start from the canonical empty-board template and inject each entry as
+    // a direct <body> child.  Negative left/top are preserved — the migration
+    // intentionally does NOT clamp coords (appendCanvasPrimitiveToHtml clamps
+    // to x/y >= 0 for new screen primitives; the board surface has no such
+    // restriction).
+    let boardHtml = emptyBoardHtml();
+    if (entries.length > 0) {
+      const fragments = entries
+        .sort((a, b) => {
+          // Stable render order: lower z first, then creation order.
+          const az = a.geometry.z ?? 0;
+          const bz = b.geometry.z ?? 0;
+          if (az !== bz) return az - bz;
+          return a.createdAt < b.createdAt ? -1 : 1;
+        })
+        .map((entry) => boardObjectEntryToHtmlFragment(entry))
+        .join("\n");
+
+      // Insert fragments before </body>.
+      boardHtml = boardHtml.replace("</body>", `${fragments}\n</body>`);
+    }
+
+    const now = new Date().toISOString();
+
+    // ── 4. Upsert the board file and update designs.data atomically ───────
+    // Run in a transaction so concurrent opens cannot create two board files.
+    let boardFileId = "";
+
+    await db.transaction(async (tx) => {
+      // Re-read designs.data inside the transaction to guard against a
+      // concurrent migration that raced us.
+      const [fresh] = await tx
+        .select({ data: schema.designs.data })
+        .from(schema.designs)
+        .where(eq(schema.designs.id, designId))
+        .limit(1);
+
+      if (!fresh) {
+        throw new Error(`Design "${designId}" not found.`);
+      }
+
+      let freshParsed: Record<string, unknown>;
+      try {
+        const raw = JSON.parse(fresh.data);
+        freshParsed =
+          raw && typeof raw === "object" && !Array.isArray(raw)
+            ? (raw as Record<string, unknown>)
+            : {};
+      } catch {
+        freshParsed = {};
+      }
+
+      // Double-check inside the transaction.
+      if (
+        typeof freshParsed["boardFileId"] === "string" &&
+        freshParsed["boardFileId"].length > 0
+      ) {
+        boardFileId = freshParsed["boardFileId"] as string;
+        return; // Another concurrent call already finished — skip.
+      }
+
+      // Check if a __board__.html file was somehow already created (shouldn't
+      // happen in normal flow, but be defensive).
+      const [existingBoardFile] = await tx
+        .select({ id: schema.designFiles.id })
+        .from(schema.designFiles)
+        .where(
+          and(
+            eq(schema.designFiles.designId, designId),
+            eq(schema.designFiles.filename, BOARD_FILENAME),
+          ),
+        )
+        .limit(1);
+
+      if (existingBoardFile) {
+        // Board file exists but boardFileId was not set — link it and update
+        // its content.
+        boardFileId = existingBoardFile.id;
+        await tx
+          .update(schema.designFiles)
+          .set({ content: boardHtml, updatedAt: now })
+          .where(eq(schema.designFiles.id, boardFileId));
+      } else {
+        // Create the board file.
+        boardFileId = nanoid();
+        await tx.insert(schema.designFiles).values({
+          id: boardFileId,
+          designId,
+          filename: BOARD_FILENAME,
+          fileType: "html",
+          content: boardHtml,
+          createdAt: now,
+          updatedAt: now,
+        });
+      }
+
+      // Write boardFileId into designs.data; null out boardObjects.
+      const nextData: Record<string, unknown> = {
+        ...freshParsed,
+        boardFileId,
+        boardObjects: null,
+      };
+
+      await tx
+        .update(schema.designs)
+        .set({
+          data: JSON.stringify(nextData),
+          updatedAt: now,
+        })
+        .where(eq(schema.designs.id, designId));
+    });
+
+    // ── 5. Seed collab state for the new board file ───────────────────────
+    // (Best-effort: collab seeding after the file row is committed.)
+    try {
+      await seedFromText(boardFileId, boardHtml);
+    } catch {
+      // Non-fatal — the board file still renders from SQL content.
+    }
+
+    return {
+      designId,
+      migrated: true,
+      boardFileId,
+      migratedObjectCount: entries.length,
+      message:
+        entries.length > 0
+          ? `Migrated ${entries.length} board object(s) to board file ${boardFileId}.`
+          : `Created empty board file ${boardFileId} (no legacy board objects).`,
+    };
+  },
+});

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

@@ -18,7 +18,8 @@
  *   --view       View name (list, editor, design-systems, present, templates, settings)
  *   --designId   Design ID (for editor/present views)
  *   --editorView Editor mode for designs: single or overview
- *   --inspectorTab Inspector tab for designs: design, tweaks, or extensions
+ *   --inspectorTab Inspector tab for designs: design or tweaks (extensions opens Tools for compatibility)
+ *   --leftPanel  Left editor panel: file, agent, assets, tools, or tokens
  *   --fileId     Screen/file id to focus in the design editor
  *   --filename   Screen filename to focus in the design editor
  *   --tool       Design editor tool to activate
@@ -47,9 +48,17 @@ const designEditorToolSchema = z.enum([
   "scale",
 ]);
 
+const designLeftPanelSchema = z.enum([
+  "file",
+  "agent",
+  "assets",
+  "tools",
+  "tokens",
+]);
+
 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 inspectorTab=extensions to focus the in-editor extension panel. Use tool to activate a design editor tool.",
+    "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.",
   schema: z
     .object({
       view: z
@@ -83,6 +92,10 @@ export default defineAction({
         .enum(["design", "tweaks", "extensions"])
         .optional()
         .describe("Alias for inspectorTab"),
+      leftPanel: designLeftPanelSchema
+        .optional()
+        .describe("Design editor left rail panel to focus"),
+      panel: designLeftPanelSchema.optional().describe("Alias for leftPanel"),
       fileId: z.string().optional().describe("Design file/screen ID to focus"),
       screenId: z.string().optional().describe("Alias for fileId"),
       filename: z
@@ -146,6 +159,8 @@ export default defineAction({
     if (editorView) nav.editorView = editorView;
     const inspectorTab = args.inspectorTab ?? args.inspector;
     if (inspectorTab) nav.inspectorTab = inspectorTab;
+    const leftPanel = args.leftPanel ?? args.panel;
+    if (leftPanel) nav.leftPanel = leftPanel;
     if (args.fileId) nav.fileId = args.fileId;
     if (args.screenId) nav.screenId = args.screenId;
     if (args.filename) nav.filename = args.filename;
@@ -159,7 +174,7 @@ export default defineAction({
       args.designId ? ` (design: ${args.designId})` : ""
     }${editorView ? ` (${editorView} view)` : ""}${
       inspectorTab ? ` (${inspectorTab} inspector)` : ""
-    }${
+    }${leftPanel ? ` (${leftPanel} panel)` : ""}${
       args.fileId || args.screenId || args.filename || args.screen
         ? ` (screen: ${args.fileId ?? args.screenId ?? args.filename ?? args.screen})`
         : ""

package/corpus/templates/design/actions/open-component-source.ts

@@ -36,7 +36,10 @@ import "../server/db/index.js"; // ensure registerShareableResource runs
 import { resolveSourceCapabilities } from "../shared/capability-resolver.js";
 import { buildCodeLayerProjection } from "../shared/code-layer.js";
 import type { CodeLayerSource } from "../shared/code-layer.js";
-import { componentNameFor } from "../shared/component-model.js";
+import {
+  componentNameFor,
+  componentNodeIdMatches,
+} from "../shared/component-model.js";
 import { hasCapability } from "../shared/design-source-capabilities.js";
 import { normalizeDesignSourceType } from "../shared/source-mode.js";
 
@@ -148,7 +151,9 @@ export default defineAction({
       source: codeLayerSource,
     });
 
-    const node = projection.nodes.find((n) => n.id === nodeId);
+    const node = projection.nodes.find((n) =>
+      componentNodeIdMatches(n, nodeId),
+    );
     if (!node) {
       throw new Error(
         `Node "${nodeId}" not found. Run get-code-layer-projection to list current ids.`,