@agent-native/core 0.79.27 → 0.80.1

package/corpus/templates/design/actions/index-design-system-with-builder.ts

@@ -0,0 +1,259 @@
+import { defineAction } from "@agent-native/core";
+import {
+  startBuilderDesignSystemIndex,
+  type BuilderDesignSystemIndexFile,
+} from "@agent-native/core/server";
+import {
+  getRequestOrgId,
+  getRequestUserEmail,
+} from "@agent-native/core/server/request-context";
+import { eq } from "drizzle-orm";
+import { nanoid } from "nanoid";
+import { z } from "zod";
+
+import { getDb, schema } from "../server/db/index.js";
+
+const MAX_CODE_FILES = 50;
+const MAX_TOTAL_CODE_BYTES = 2 * 1024 * 1024;
+
+const codeFileSchema = z.object({
+  filename: z.string().trim().min(1).describe("File name or relative path"),
+  content: z.string().describe("Raw text content of the code/design file"),
+  mimeType: z.string().trim().optional().describe("Optional MIME type"),
+});
+
+function mimeTypeForFilename(filename: string, explicit?: string): string {
+  if (explicit?.trim()) return explicit.trim();
+  const lower = filename.toLowerCase();
+  if (lower.endsWith(".css")) return "text/css";
+  if (lower.endsWith(".json")) return "application/json";
+  if (lower.endsWith(".md") || lower.endsWith(".mdx")) return "text/markdown";
+  if (lower.endsWith(".html")) return "text/html";
+  if (lower.endsWith(".svg")) return "image/svg+xml";
+  return "text/plain";
+}
+
+function makeFiles(
+  codeFiles: Array<z.infer<typeof codeFileSchema>> | undefined,
+): BuilderDesignSystemIndexFile[] {
+  const encoder = new TextEncoder();
+  const files: BuilderDesignSystemIndexFile[] = [];
+  let totalBytes = 0;
+  for (const file of (codeFiles ?? []).slice(0, MAX_CODE_FILES)) {
+    const data = encoder.encode(file.content);
+    if (totalBytes + data.byteLength > MAX_TOTAL_CODE_BYTES) break;
+    totalBytes += data.byteLength;
+    files.push({
+      name: file.filename.replace(/^\/+/, "") || "code.txt",
+      data,
+      mimeType: mimeTypeForFilename(file.filename, file.mimeType),
+    });
+  }
+  return files;
+}
+
+function localBuilderDesignSystemId(builderDesignSystemId: string): string {
+  const slug = builderDesignSystemId
+    .replace(/[^a-zA-Z0-9_-]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 96);
+  return `builder-${slug || "design-system"}`;
+}
+
+function builderProxyData({
+  builderDesignSystemId,
+  jobId,
+  builderUrl,
+  projectName,
+  description,
+}: {
+  builderDesignSystemId: string;
+  jobId: string;
+  builderUrl: string;
+  projectName?: string;
+  description?: string;
+}) {
+  return JSON.stringify({
+    source: "builder",
+    builderDesignSystemId,
+    builderJobId: jobId,
+    builderUrl,
+    colors: {
+      primary: "var(--primary)",
+      secondary: "var(--secondary)",
+      accent: "var(--accent)",
+      background: "var(--background)",
+      surface: "var(--card)",
+      text: "var(--foreground)",
+      textMuted: "var(--muted-foreground)",
+    },
+    typography: {
+      headingFont: "inherit",
+      bodyFont: "inherit",
+      headingWeight: "700",
+      bodyWeight: "400",
+      headingSizes: { h1: "48px", h2: "32px", h3: "24px" },
+    },
+    spacing: { elementGap: "24px", pagePadding: "48px" },
+    borders: { radius: "12px", accentWidth: "1px" },
+    logos: [],
+    notes: [
+      "This is a local proxy for a Builder-indexed design system.",
+      `Builder design system id: ${builderDesignSystemId}`,
+      `Builder indexing job id: ${jobId}`,
+      `Builder URL: ${builderUrl}`,
+      projectName ? `Requested name: ${projectName}` : "",
+      description ? `Context: ${description}` : "",
+      "Use Builder as the source of truth for extracted tokens and guidance.",
+    ]
+      .filter(Boolean)
+      .join("\n"),
+  });
+}
+
+function builderProxyInstructions({
+  builderDesignSystemId,
+  jobId,
+  builderUrl,
+}: {
+  builderDesignSystemId: string;
+  jobId: string;
+  builderUrl: string;
+}) {
+  return [
+    "This design system is indexed and owned by Builder.",
+    `Builder design system id: ${builderDesignSystemId}`,
+    `Builder job id: ${jobId}`,
+    `Builder URL: ${builderUrl}`,
+    "When generating designs, treat Builder as the source of truth for the final extracted tokens, assets, and guidance.",
+  ].join("\n");
+}
+
+export default defineAction({
+  description:
+    "Start Builder design-system indexing from a GitHub repository and/or code files. " +
+    "Use this instead of local import-code/import-github when the user wants a reusable brand kit or design system. " +
+    "Requires Builder.io to be connected; Builder owns the indexed design-system docs, generated guidance, and job state.",
+  schema: z.object({
+    projectName: z
+      .string()
+      .optional()
+      .describe("Optional Builder project/design-system name"),
+    description: z
+      .string()
+      .optional()
+      .describe("Additional brand context or instructions for Builder"),
+    githubRepoUrl: z
+      .string()
+      .optional()
+      .describe("GitHub repository URL to index with Builder"),
+    connectedProjectId: z
+      .string()
+      .optional()
+      .describe("Optional existing Builder project id to attach indexing to"),
+    codeFiles: z
+      .array(codeFileSchema)
+      .optional()
+      .describe("Optional inlined code/design files to upload to Builder"),
+  }),
+  run: async ({
+    projectName,
+    description,
+    githubRepoUrl,
+    connectedProjectId,
+    codeFiles,
+  }) => {
+    const files = makeFiles(codeFiles);
+    const result = await startBuilderDesignSystemIndex({
+      projectName,
+      description,
+      githubRepoUrl,
+      connectedProjectId,
+      files,
+    });
+    const ownerEmail = getRequestUserEmail();
+    if (!ownerEmail) throw new Error("no authenticated user");
+
+    const db = getDb();
+    const now = new Date().toISOString();
+    const orgId = getRequestOrgId();
+    const baseLocalDesignSystemId = localBuilderDesignSystemId(
+      result.designSystemId,
+    );
+    const title = projectName?.trim() || "Builder indexed design system";
+    const localData = builderProxyData({
+      builderDesignSystemId: result.designSystemId,
+      jobId: result.jobId,
+      builderUrl: result.builderUrl,
+      projectName,
+      description,
+    });
+    const customInstructions = builderProxyInstructions({
+      builderDesignSystemId: result.designSystemId,
+      jobId: result.jobId,
+      builderUrl: result.builderUrl,
+    });
+    const [existing] = await db
+      .select({
+        id: schema.designSystems.id,
+        ownerEmail: schema.designSystems.ownerEmail,
+      })
+      .from(schema.designSystems)
+      .where(eq(schema.designSystems.id, baseLocalDesignSystemId))
+      .limit(1);
+    const localDesignSystemId =
+      existing && existing.ownerEmail !== ownerEmail
+        ? `${baseLocalDesignSystemId}-${nanoid(8)}`
+        : baseLocalDesignSystemId;
+    if (existing && existing.ownerEmail === ownerEmail) {
+      await db
+        .update(schema.designSystems)
+        .set({
+          title,
+          description:
+            description ??
+            `Builder indexed design system ${result.designSystemId}`,
+          data: localData,
+          assets: "[]",
+          customInstructions,
+          updatedAt: now,
+        })
+        .where(eq(schema.designSystems.id, existing.id));
+    } else {
+      const [ownedSystem] = await db
+        .select({ id: schema.designSystems.id })
+        .from(schema.designSystems)
+        .where(eq(schema.designSystems.ownerEmail, ownerEmail))
+        .limit(1);
+      await db.insert(schema.designSystems).values({
+        id: localDesignSystemId,
+        title,
+        description:
+          description ??
+          `Builder indexed design system ${result.designSystemId}`,
+        data: localData,
+        assets: "[]",
+        customInstructions,
+        isDefault: !ownedSystem,
+        ownerEmail,
+        orgId,
+        createdAt: now,
+        updatedAt: now,
+      });
+    }
+
+    return {
+      ...result,
+      localDesignSystemId,
+      uploadedFileCount: files.length,
+      instructions: [
+        "Builder design-system indexing has started.",
+        `Builder design system: ${result.designSystemId}`,
+        `Local selectable design system: ${localDesignSystemId}`,
+        `Builder job: ${result.jobId}`,
+        `Open: ${result.builderUrl}`,
+        "Use the local design system id in Design flows; Builder remains the source of truth for the indexed brand kit.",
+      ].join("\n"),
+    };
+  },
+});

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

@@ -0,0 +1,95 @@
+import { defineAction } from "@agent-native/core";
+import {
+  getRequestOrgId,
+  getRequestUserEmail,
+} from "@agent-native/core/server/request-context";
+import { and, desc, eq, isNull } from "drizzle-orm";
+import { z } from "zod";
+
+import { getDb, schema } from "../server/db/index.js";
+import type {
+  DesignBridgeCapability,
+  LocalhostDesignRouteManifest,
+} from "../shared/source-mode.js";
+
+function parseJson<T>(value: string, fallback: T): T {
+  try {
+    return JSON.parse(value) as T;
+  } catch {
+    return fallback;
+  }
+}
+
+export default defineAction({
+  description:
+    "List localhost Design source connections for the current user. Use this before creating localhost artboards or resolving local routes.",
+  schema: z.object({
+    id: z.string().optional().describe("Optional connection ID filter."),
+    status: z
+      .enum(["connected", "detected", "manual", "error"])
+      .optional()
+      .describe("Optional status filter."),
+  }),
+  readOnly: true,
+  http: { method: "GET" },
+  run: async ({ id, status }) => {
+    const ownerEmail = getRequestUserEmail();
+    if (!ownerEmail) throw new Error("no authenticated user");
+    const orgId = getRequestOrgId() ?? null;
+    const clauses = [
+      eq(schema.designLocalhostConnections.ownerEmail, ownerEmail),
+      orgId
+        ? eq(schema.designLocalhostConnections.orgId, orgId)
+        : isNull(schema.designLocalhostConnections.orgId),
+    ];
+    if (id) clauses.push(eq(schema.designLocalhostConnections.id, id));
+    if (status) {
+      clauses.push(eq(schema.designLocalhostConnections.status, status));
+    }
+
+    const rows = await getDb()
+      .select()
+      .from(schema.designLocalhostConnections)
+      .where(and(...clauses))
+      .orderBy(desc(schema.designLocalhostConnections.updatedAt));
+
+    const connections = rows.map((row) => {
+      const routeManifest = parseJson<LocalhostDesignRouteManifest>(
+        row.routeManifest,
+        {
+          version: 1,
+          sourceType: "localhost",
+          devServerUrl: row.devServerUrl,
+          rootPath: row.rootPath ?? undefined,
+          routes: [],
+          generatedAt: row.updatedAt ?? new Date(0).toISOString(),
+        },
+      );
+      const capabilities = parseJson<DesignBridgeCapability[]>(
+        row.capabilities,
+        [],
+      );
+      return {
+        id: row.id,
+        sourceType: row.sourceType,
+        name: row.name,
+        devServerUrl: row.devServerUrl,
+        bridgeUrl: row.bridgeUrl ?? null,
+        rootPath: row.rootPath ?? null,
+        routeManifest,
+        routes: routeManifest.routes,
+        routeCount: routeManifest.routes.length,
+        capabilities,
+        status: row.status,
+        lastSeenAt: row.lastSeenAt ?? null,
+        createdAt: row.createdAt,
+        updatedAt: row.updatedAt,
+      };
+    });
+
+    return {
+      count: connections.length,
+      connections,
+    };
+  },
+});

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

@@ -6,6 +6,8 @@
  * Usage:
  *   pnpm action navigate --view=list
  *   pnpm action navigate --view=editor --designId=abc123
+ *   pnpm action navigate --view=editor --designId=abc123 --editorView=overview
+ *   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
@@ -15,6 +17,10 @@
  * Options:
  *   --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
+ *   --fileId     Screen/file id to focus in the design editor
+ *   --filename   Screen filename to focus in the design editor
  *   --designSystemId Design system ID (for design-systems view)
  *   --path       URL path to navigate to
  */
@@ -25,7 +31,7 @@ import { z } from "zod";
 
 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.",
+    "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.",
   schema: z.object({
     view: z
       .enum([
@@ -40,6 +46,38 @@ export default defineAction({
       .optional()
       .describe("View name to navigate to"),
     designId: z.string().optional().describe("Design ID for editor/present"),
+    editorView: z
+      .enum(["single", "overview"])
+      .optional()
+      .describe(
+        "Design editor view: overview for the infinite screens canvas, single for a focused screen",
+      ),
+    viewMode: z
+      .enum(["single", "overview"])
+      .optional()
+      .describe("Alias for editorView"),
+    inspectorTab: z
+      .enum(["design", "tweaks", "extensions"])
+      .optional()
+      .describe("Design editor inspector tab to focus"),
+    inspector: z
+      .enum(["design", "tweaks", "extensions"])
+      .optional()
+      .describe("Alias for inspectorTab"),
+    fileId: z.string().optional().describe("Design file/screen ID to focus"),
+    screenId: z.string().optional().describe("Alias for fileId"),
+    filename: z
+      .string()
+      .optional()
+      .describe("Design screen filename to focus, such as checkout.html"),
+    screen: z
+      .string()
+      .optional()
+      .describe("Screen id, filename, or name to focus"),
+    zoom: z
+      .number()
+      .optional()
+      .describe("Optional design canvas zoom percentage"),
     designSystemId: z
       .string()
       .optional()
@@ -51,14 +89,29 @@ export default defineAction({
     if (!args.view && !args.path) {
       throw new Error("At least --view or --path is required.");
     }
-    const nav: Record<string, string> = {};
+    const nav: Record<string, unknown> = {};
     if (args.view) nav.view = args.view;
     if (args.designId) nav.designId = args.designId;
+    const editorView = args.editorView ?? args.viewMode;
+    if (editorView) nav.editorView = editorView;
+    const inspectorTab = args.inspectorTab ?? args.inspector;
+    if (inspectorTab) nav.inspectorTab = inspectorTab;
+    if (args.fileId) nav.fileId = args.fileId;
+    if (args.screenId) nav.screenId = args.screenId;
+    if (args.filename) nav.filename = args.filename;
+    if (args.screen) nav.screen = args.screen;
+    if (args.zoom !== undefined) nav.zoom = args.zoom;
     if (args.designSystemId) nav.designSystemId = args.designSystemId;
     if (args.path) nav.path = args.path;
     await writeAppState("navigate", nav);
     return `Navigating to ${args.view || args.path}${
       args.designId ? ` (design: ${args.designId})` : ""
+    }${editorView ? ` (${editorView} view)` : ""}${
+      inspectorTab ? ` (${inspectorTab} inspector)` : ""
+    }${
+      args.fileId || args.screenId || args.filename || args.screen
+        ? ` (screen: ${args.fileId ?? args.screenId ?? args.filename ?? args.screen})`
+        : ""
     }${args.designSystemId ? ` (design system: ${args.designSystemId})` : ""}`;
   },
 });

package/corpus/templates/design/actions/update-file.ts

@@ -23,8 +23,15 @@ export default defineAction({
       .enum(["html", "css", "jsx", "asset"])
       .optional()
       .describe("Updated file type"),
+    syncCollab: z
+      .boolean()
+      .optional()
+      .default(true)
+      .describe(
+        "Whether to mirror content updates into the live collaboration document.",
+      ),
   }),
-  run: async ({ id, content, filename, fileType }) => {
+  run: async ({ id, content, filename, fileType, syncCollab }) => {
     // Path traversal guard on filename
     if (
       filename &&
@@ -74,7 +81,7 @@ export default defineAction({
       .where(eq(schema.designFiles.id, id));
 
     // Push content through the collab layer so live editors see the change
-    if (content !== undefined) {
+    if (content !== undefined && syncCollab) {
       const collabExists = await hasCollabState(id);
       if (collabExists) {
         await applyText(id, content, "content", "agent");

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

@@ -12,11 +12,17 @@ import {
   readAppState,
   readAppStateForCurrentTab,
 } from "@agent-native/core/application-state";
+import { resolveAccess } from "@agent-native/core/sharing";
+import { eq } from "drizzle-orm";
 import { z } from "zod";
 
+import { getDb, schema } from "../server/db/index.js";
+import { parseCanvasFrameGeometryById } from "../shared/canvas-frames.js";
+import { designGenerationSessionKey } from "../shared/generation-session.js";
+
 export default defineAction({
   description:
-    "See what the user is currently looking at on screen. Returns the current navigation state including which design is open, which view they are on (list, editor, design-systems, present, templates, settings), plus any pending question overlay or variant grid. Always call this first before taking any action.",
+    "See what the user is currently looking at on screen. Returns the current navigation state including which design is open, which view they are on (list, editor, design-systems, present, templates, settings), active/focused design screen, selected element, active inspector tab (design, tweaks, or extensions), overview canvas state, plus any pending question overlay or variant grid. Always call this first before taking any action.",
   schema: z.object({}),
   http: false,
   run: async () => {
@@ -35,10 +41,68 @@ export default defineAction({
       (designId
         ? await readAppState(`show-questions:${designId}`)
         : undefined) ?? (await readAppState("show-questions"));
+    const generationSession = designId
+      ? await readAppState(designGenerationSessionKey(designId))
+      : undefined;
 
     const screen: Record<string, unknown> = {};
     if (navigation) screen.navigation = navigation;
     if (designSelection) screen.designSelection = designSelection;
+    if (designId) {
+      const access = await resolveAccess("design", designId).catch(() => null);
+      if (access) {
+        const db = getDb();
+        const files = await db
+          .select({
+            id: schema.designFiles.id,
+            filename: schema.designFiles.filename,
+            fileType: schema.designFiles.fileType,
+            updatedAt: schema.designFiles.updatedAt,
+          })
+          .from(schema.designFiles)
+          .where(eq(schema.designFiles.designId, designId));
+        let data: Record<string, unknown> = {};
+        const rawData = (access.resource as { data?: unknown }).data;
+        if (typeof rawData === "string") {
+          try {
+            const parsed = JSON.parse(rawData);
+            if (
+              parsed &&
+              typeof parsed === "object" &&
+              !Array.isArray(parsed)
+            ) {
+              data = parsed as Record<string, unknown>;
+            }
+          } catch {
+            data = {};
+          }
+        }
+        const activeFileId =
+          designSelection &&
+          typeof designSelection === "object" &&
+          typeof (designSelection as { activeFileId?: unknown })
+            .activeFileId === "string"
+            ? (designSelection as { activeFileId: string }).activeFileId
+            : undefined;
+        const activeFilename =
+          designSelection &&
+          typeof designSelection === "object" &&
+          typeof (designSelection as { activeFilename?: unknown })
+            .activeFilename === "string"
+            ? (designSelection as { activeFilename: string }).activeFilename
+            : undefined;
+        screen.design = {
+          id: designId,
+          title: (access.resource as { title?: unknown }).title ?? null,
+          screens: files,
+          activeScreen:
+            files.find((file) => file.id === activeFileId) ??
+            files.find((file) => file.filename === activeFilename) ??
+            null,
+          canvasFrames: parseCanvasFrameGeometryById(data.canvasFrames),
+        };
+      }
+    }
     if (showQuestions) {
       screen.pendingQuestions = showQuestions;
       screen.note =
@@ -49,6 +113,9 @@ export default defineAction({
       screen.variantsNote =
         'A variant picker is open. Wait for the user to choose a direction before generating further. In an inline MCP app their pick returns to you automatically; if it opened as a browser tab (a CLI or code editor), they paste an auto-copied summary or just tell you which one (e.g. "use variant A"). Once you know the choice, read the saved index.html with get-design-snapshot. Do not call generate-design while this picker is open.';
     }
+    if (generationSession) {
+      screen.generationSession = generationSession;
+    }
 
     if (Object.keys(screen).length === 0) {
       return "No application state found. Is the app running?";

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

@@ -29,6 +29,11 @@
       "id": "design-exploration",
       "action": "present-design-variants",
       "path": "/design"
+    },
+    {
+      "id": "visual-edit",
+      "action": "add-localhost-screens",
+      "path": "/design"
     }
   ],
   "skills": [
@@ -36,6 +41,11 @@
       "path": ".agents/skills/design-generation",
       "visibility": "both",
       "exportAs": "design-exploration"
+    },
+    {
+      "path": ".agents/skills/visual-edit",
+      "visibility": "both",
+      "exportAs": "visual-edit"
     }
   ],
   "hostAdapters": [