@agent-native/core 0.79.27 → 0.80.1

package/corpus/templates/design/actions/generate-screens.ts

@@ -0,0 +1,193 @@
+import { defineAction, embedApp } from "@agent-native/core";
+import { writeAppState } from "@agent-native/core/application-state";
+import { buildDeepLink } from "@agent-native/core/server";
+import { assertAccess } from "@agent-native/core/sharing";
+import { nanoid } from "nanoid";
+import { z } from "zod";
+
+import "../server/db/index.js";
+import { assignRegions } from "../shared/canvas-math.js";
+import {
+  designGenerationSessionKey,
+  type DesignGenerationFrame,
+  type DesignGenerationSession,
+} from "../shared/generation-session.js";
+
+const AGENT_NAMES = [
+  "Atlas",
+  "Nova",
+  "Kai",
+  "Mira",
+  "Sol",
+  "Vega",
+  "Rune",
+  "Iris",
+];
+
+const AGENT_COLORS = [
+  "var(--design-editor-accent-color)",
+  "hsl(var(--chart-2))",
+  "hsl(var(--chart-3))",
+  "hsl(var(--chart-4))",
+  "hsl(var(--chart-5))",
+];
+
+function designDeepLink(designId: string): string {
+  const path = `/design/${encodeURIComponent(designId)}?view=overview`;
+  return buildDeepLink({
+    app: "design",
+    view: "editor",
+    params: { designId },
+    to: path,
+  });
+}
+
+const requestedScreenSchema = z.object({
+  frameId: z.string().optional(),
+  title: z.string().min(1),
+  filename: z
+    .string()
+    .optional()
+    .describe("Target filename for this screen, such as onboarding.html"),
+  role: z.enum(["screen", "variant"]).optional().default("screen"),
+  variantOf: z.string().optional(),
+});
+
+export default defineAction({
+  description:
+    "Start a visible multi-agent generation session on the Design canvas. " +
+    "Use this before generating multiple screens or variations in parallel: it " +
+    "assigns non-overlapping canvas regions, publishes named agent/frame " +
+    "status to application state, and returns per-frame generation instructions. " +
+    "After this action, fan out calls to generate-design for each returned " +
+    "frame, passing the returned canvasFrame values to generate-design so " +
+    "screens appear in the infinite overview canvas.",
+  schema: z.object({
+    designId: z.string().describe("Design project ID to generate into"),
+    prompt: z.string().min(1).describe("Overall generation prompt"),
+    screens: z
+      .preprocess(
+        (value) => (typeof value === "string" ? JSON.parse(value) : value),
+        z.array(requestedScreenSchema).min(1).max(8),
+      )
+      .describe("Screens or variants that should be generated on the canvas"),
+    designSystemId: z
+      .string()
+      .optional()
+      .describe("Locked design system/token set for every worker"),
+    contextRefs: z
+      .array(z.string())
+      .optional()
+      .default([])
+      .describe("Selected frame/image/reference ids attached as context"),
+  }),
+  mcpApp: {
+    compactCatalog: true,
+    resource: embedApp({
+      title: "Design generation session",
+      description: "Open the Design editor with agent generation visible.",
+      iframeTitle: "Agent-Native Design",
+      openLabel: "Open generation session",
+      height: 720,
+    }),
+  },
+  run: async ({ designId, prompt, screens, designSystemId, contextRefs }) => {
+    await assertAccess("design", designId, "editor");
+    if (designSystemId) {
+      await assertAccess("design-system", designSystemId, "viewer");
+    }
+
+    const regions = assignRegions(screens.length, {
+      origin: { x: 0, y: 0 },
+      columns: screens.length <= 3 ? screens.length : 3,
+    });
+    const frames: DesignGenerationFrame[] = screens.map((screen, index) => {
+      const frameId = screen.frameId ?? nanoid();
+      return {
+        frameId,
+        agentId: `agent-${frameId}`,
+        agentName: AGENT_NAMES[index % AGENT_NAMES.length] ?? "Agent",
+        agentColor:
+          AGENT_COLORS[index % AGENT_COLORS.length] ??
+          "var(--design-editor-accent-color)",
+        region: regions[index]!,
+        role: screen.role,
+        variantOf: screen.variantOf,
+        status: "queued",
+        step: "Queued",
+        progress: 0,
+      };
+    });
+
+    const session: DesignGenerationSession = {
+      id: nanoid(),
+      designId,
+      status: "planning",
+      designSystemId,
+      prompt,
+      contextRefs,
+      frames,
+    };
+
+    await writeAppState(
+      designGenerationSessionKey(designId),
+      session as unknown as Record<string, unknown>,
+    );
+    await writeAppState("navigate", {
+      view: "editor",
+      designId,
+      editorView: "overview",
+      path: `/design/${encodeURIComponent(designId)}?view=overview`,
+    });
+
+    const targets = frames.map((frame, index) => {
+      const requested = screens[index]!;
+      const filename =
+        requested.filename ??
+        `${
+          requested.title
+            .toLowerCase()
+            .replace(/[^a-z0-9]+/g, "-")
+            .replace(/^-+|-+$/g, "")
+            .slice(0, 48) || `screen-${index + 1}`
+        }.html`;
+      return {
+        frameId: frame.frameId,
+        title: requested.title,
+        filename,
+        role: frame.role,
+        variantOf: frame.variantOf,
+        canvasFrame: {
+          filename,
+          x: frame.region.x,
+          y: frame.region.y,
+          width: frame.region.width,
+          height: frame.region.height,
+          z: index,
+        },
+      };
+    });
+
+    return {
+      designId,
+      sessionId: session.id,
+      status: session.status,
+      frames,
+      targets,
+      path: `/design/${encodeURIComponent(designId)}?view=overview`,
+      embed: true,
+      nextRequiredAction:
+        "Generate each target with generate-design, using the target filename and canvasFrame placement, the same designSystemId, and contextRefs for coherence.",
+    };
+  },
+  link: ({ result }) => {
+    if (!result || typeof result !== "object") return null;
+    const designId = (result as { designId?: string }).designId;
+    if (!designId) return null;
+    return {
+      url: designDeepLink(designId),
+      label: "Open generation session",
+      view: "editor",
+    };
+  },
+});

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,
+    };
+  },
+});