@agent-native/core 0.79.27 → 0.80.0

package/corpus/templates/design/actions/get-code-layer-projection.ts

@@ -0,0 +1,191 @@
+import { defineAction } from "@agent-native/core";
+import { getText, hasCollabState } from "@agent-native/core/collab";
+import { accessFilter } from "@agent-native/core/sharing";
+import { and, eq } from "drizzle-orm";
+import { z } from "zod";
+
+import { getDb, schema } from "../server/db/index.js";
+import {
+  buildCodeLayerProjection,
+  buildCodeLayerTree,
+  type CodeLayerSource,
+} from "../shared/code-layer.js";
+import { normalizeDesignSourceType } from "../shared/source-mode.js";
+
+type ProjectionActionSource = CodeLayerSource & { html?: string };
+
+function parseJsonString(value: unknown): unknown {
+  if (typeof value !== "string") return value;
+  try {
+    return JSON.parse(value);
+  } catch {
+    return value;
+  }
+}
+
+const sourceSchema = z.preprocess(
+  parseJsonString,
+  z.object({
+    kind: z
+      .enum(["design-file", "inline-html", "local-file", "remote-url"])
+      .default("design-file"),
+    sourceType: z.enum(["inline", "localhost", "fusion"]).optional(),
+    designId: z.string().optional(),
+    fileId: z.string().optional(),
+    filename: z.string().optional().default("index.html"),
+    path: z.string().optional(),
+    url: z.string().optional(),
+    connectionId: z.string().optional(),
+    routeId: z.string().optional(),
+    artboardId: z.string().optional(),
+    bridgeUrl: z.string().optional(),
+    revision: z.string().optional(),
+    html: z.string().optional(),
+  }),
+);
+
+async function liveContent(
+  fileId: string,
+  storedContent: string,
+): Promise<string> {
+  try {
+    if (await hasCollabState(fileId)) {
+      const live = await getText(fileId, "content");
+      if (typeof live === "string") return live;
+    }
+  } catch {
+    // The stored SQL content remains the deterministic fallback.
+  }
+  return storedContent;
+}
+
+async function resolveDesignFileSource(
+  source: ProjectionActionSource,
+): Promise<{
+  html: string;
+  source: CodeLayerSource;
+}> {
+  if (!source.fileId && !source.designId) {
+    throw new Error(
+      "source.designId or source.fileId is required for design-file.",
+    );
+  }
+
+  const db = getDb();
+  const conditions = [
+    accessFilter(schema.designs, schema.designShares),
+    source.fileId
+      ? eq(schema.designFiles.id, source.fileId)
+      : eq(schema.designFiles.designId, source.designId ?? ""),
+  ];
+  if (!source.fileId) {
+    conditions.push(
+      eq(schema.designFiles.filename, source.filename ?? "index.html"),
+    );
+  }
+
+  const [file] = await db
+    .select({
+      id: schema.designFiles.id,
+      designId: schema.designFiles.designId,
+      filename: schema.designFiles.filename,
+      fileType: schema.designFiles.fileType,
+      content: schema.designFiles.content,
+    })
+    .from(schema.designFiles)
+    .innerJoin(
+      schema.designs,
+      eq(schema.designFiles.designId, schema.designs.id),
+    )
+    .where(and(...conditions))
+    .limit(1);
+
+  if (!file) {
+    throw new Error("Design HTML file not found.");
+  }
+  if (file.fileType !== "html") {
+    throw new Error(`Code layer projection only supports HTML files for now.`);
+  }
+
+  return {
+    html: await liveContent(file.id, file.content ?? ""),
+    source: {
+      kind: "design-file",
+      sourceType: "inline",
+      designId: file.designId,
+      fileId: file.id,
+      filename: file.filename,
+      revision: source.revision,
+    },
+  };
+}
+
+export default defineAction({
+  description:
+    "Build a deterministic Code Layer Projection for an inline/SQL HTML design file. " +
+    "The projection maps real source elements to selectable code-backed layer nodes with selectors, spans, layout context, and edit capabilities.",
+  schema: z.object({
+    source: sourceSchema.describe(
+      "Projection source. Use kind=design-file with designId/filename or fileId for SQL-backed Design files; kind=inline-html with html for previews.",
+    ),
+  }),
+  readOnly: true,
+  http: { method: "GET" },
+  run: async ({ source }) => {
+    const actionSource = source as ProjectionActionSource;
+
+    if (actionSource.kind === "inline-html") {
+      const html = actionSource.html ?? "";
+      const projectionSource: CodeLayerSource = {
+        kind: "inline-html",
+        sourceType: "inline",
+        filename: actionSource.filename,
+        revision: actionSource.revision,
+      };
+      const projection = buildCodeLayerProjection(html, {
+        source: projectionSource,
+      });
+      return {
+        projection,
+        layers: buildCodeLayerTree(projection),
+      };
+    }
+
+    if (actionSource.kind !== "design-file") {
+      const projectionSource: CodeLayerSource = {
+        kind: actionSource.kind,
+        sourceType:
+          actionSource.sourceType ??
+          normalizeDesignSourceType(actionSource.kind) ??
+          undefined,
+        path: actionSource.path,
+        url: actionSource.url,
+        connectionId: actionSource.connectionId,
+        routeId: actionSource.routeId,
+        artboardId: actionSource.artboardId,
+        bridgeUrl: actionSource.bridgeUrl,
+        filename: actionSource.filename,
+        revision: actionSource.revision,
+      };
+      const projection = buildCodeLayerProjection("", {
+        source: projectionSource,
+      });
+      return {
+        projection,
+        layers: buildCodeLayerTree(projection),
+        unsupported: true,
+        message:
+          "Only inline-html and SQL design-file sources are supported by this action today.",
+      };
+    }
+
+    const resolved = await resolveDesignFileSource(actionSource);
+    const projection = buildCodeLayerProjection(resolved.html, {
+      source: resolved.source,
+    });
+    return {
+      projection,
+      layers: buildCodeLayerTree(projection),
+    };
+  },
+});

package/corpus/templates/design/actions/get-shader.ts

@@ -0,0 +1,119 @@
+import { defineAction } from "@agent-native/core";
+import { z } from "zod";
+
+import {
+  SHADER_PRESET_MAP,
+  SHADER_PRESETS,
+  type ShaderPresetName,
+} from "../shared/shader-presets.js";
+
+export default defineAction({
+  description:
+    "Return the available GPU shader preset catalog and instructions for reading current shader state " +
+    "on a design element. Because shader state lives in source code (JSX props or data-shader attributes), " +
+    "this action cannot parse live values itself — it returns the full preset catalog and oriented guidance " +
+    "so the agent knows what to look for when inspecting the code. " +
+    "Call get-code-layer-projection to read the actual HTML/JSX, then look for data-shader attributes " +
+    "(inline HTML mode) or @paper-design/shaders-react component names (framework mode).",
+  schema: z.object({
+    source: z
+      .object({
+        kind: z.enum(["design-file", "inline-html"]).default("design-file"),
+        designId: z.string().optional(),
+        fileId: z.string().optional(),
+      })
+      .optional()
+      .describe(
+        "Optional design source context. When provided, the instructions are tailored to the source kind.",
+      ),
+    target: z
+      .object({
+        nodeId: z.string().optional(),
+        selector: z.string().optional(),
+      })
+      .optional()
+      .describe(
+        "Optional target element. When provided, the inspection hint is scoped to that element.",
+      ),
+  }),
+  readOnly: true,
+  run: async ({ source, target }) => {
+    const sourceKind = source?.kind ?? "design-file";
+    const targetDescription = target?.nodeId
+      ? `element with id="${target.nodeId}"`
+      : target?.selector
+        ? `element matching "${target.selector}"`
+        : "any element";
+
+    const availablePresets = (
+      Object.keys(SHADER_PRESET_MAP) as ShaderPresetName[]
+    ).map((name) => {
+      const def = SHADER_PRESET_MAP[name];
+      return {
+        name,
+        label: def.label,
+        description: def.description,
+        isEffect: def.isEffect ?? false,
+        maxColorCount: def.maxColorCount,
+        paramKeys: def.params.map((p) => p.key),
+      };
+    });
+
+    const presetSummaryLines = SHADER_PRESETS.map((p) => {
+      const paramKeys = p.params.map((param) => param.key).join(", ");
+      return `  ${p.name} (${p.label}): ${p.description}${paramKeys ? ` — params: ${paramKeys}` : ""}`;
+    });
+
+    const inspectionStepsFramework = [
+      `1. Call get-code-layer-projection with the design source to retrieve the rendered HTML or JSX.`,
+      `2. Look for any import from "@paper-design/shaders-react".`,
+      `   If found, note the imported component name — that is the active preset.`,
+      `3. Read the component's JSX props: colors, colorBack, colorFront, speed, frame, fit, scale,`,
+      `   rotation, offsetX, offsetY, and any shader-specific params (distortion, swirl, shape, etc.).`,
+      `4. The zIndex prop (or style.zIndex) tells you whether it's a fill (0) or effect (2).`,
+      `5. Reconstruct the ShaderDescriptor from those props to pass back to apply-shader if editing.`,
+    ];
+
+    const inspectionStepsInline = [
+      `1. Call get-code-layer-projection with the design source to retrieve the rendered HTML.`,
+      `2. Look for <canvas data-shader='...'> elements${target ? ` inside ${targetDescription}` : ""}.`,
+      `3. Parse the data-shader JSON attribute — it is a ShaderDescriptor object with`,
+      `   { preset, params, colors?, speed?, frame?, fit?, scale?, rotation?, offsetX?, offsetY? }.`,
+      `4. The canvas element's inline style z-index tells you whether it's a fill (0) or effect (2).`,
+      `5. To update the shader, modify the data-shader attribute value via apply-visual-edit`,
+      `   with a style or attribute intent, or use apply-shader to regenerate the canvas element.`,
+    ];
+
+    const inspectionSteps =
+      sourceKind === "inline-html"
+        ? inspectionStepsInline
+        : inspectionStepsFramework;
+
+    const hint =
+      sourceKind === "inline-html"
+        ? `Search the HTML for data-shader attributes. The value is a JSON ShaderDescriptor. ` +
+          `Example: data-shader='{"preset":"MeshGradient","params":{"distortion":0.8},"colors":["#e0eaff","#241d9a"]}'.`
+        : `Search the JSX for imports from "@paper-design/shaders-react" and look for the component ` +
+          `(e.g. <MeshGradient colors={[...]} distortion={0.8} style={{...}} />). ` +
+          `The component name is the preset name.`;
+
+    const instructions = [
+      `To read the current shader state on ${targetDescription}:`,
+      "",
+      ...inspectionSteps,
+      "",
+      `Hint: ${hint}`,
+      "",
+      `To apply or change a shader, call apply-shader with the desired descriptor.`,
+      `apply-shader validates params and returns the exact JSX or HTML to insert.`,
+    ].join("\n");
+
+    return {
+      availablePresets,
+      presetNames: availablePresets.map((p) => p.name),
+      presetSummary: presetSummaryLines.join("\n"),
+      instructions,
+      hint,
+    };
+  },
+});

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/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": [