@agent-native/core 0.79.27 → 0.80.1

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

@@ -0,0 +1,277 @@
+import { defineAction } from "@agent-native/core";
+import { z } from "zod";
+
+import {
+  SHADER_PRESET_MAP,
+  type ShaderDescriptor,
+  type ShaderPresetName,
+  validateDescriptor,
+} from "../shared/shader-presets.js";
+
+// Zod v4 enum values must be an array
+const PRESET_NAMES = Object.keys(SHADER_PRESET_MAP) as [
+  ShaderPresetName,
+  ...ShaderPresetName[],
+];
+
+const sourceSchema = z.object({
+  kind: z.enum(["design-file", "inline-html"]).default("design-file"),
+  designId: z.string().optional(),
+  fileId: z.string().optional(),
+  html: z.string().optional(),
+});
+
+const targetSchema = z.object({
+  nodeId: z.string().optional(),
+  selector: z.string().optional(),
+});
+
+const descriptorSchema = z.object({
+  preset: z
+    .enum(PRESET_NAMES)
+    .describe(
+      "One of the 8 shader presets: MeshGradient, GrainGradient, Voronoi, Metaballs, Warp, GodRays, Dithering, PaperTexture.",
+    ),
+  params: z
+    .record(z.string(), z.union([z.number(), z.boolean(), z.string()]))
+    .optional()
+    .default({}),
+  colors: z.array(z.string()).optional(),
+  speed: z.number().optional(),
+  frame: z.number().optional(),
+  fit: z.enum(["none", "contain", "cover"]).optional(),
+  scale: z.number().optional(),
+  rotation: z.number().optional(),
+  offsetX: z.number().optional(),
+  offsetY: z.number().optional(),
+});
+
+/**
+ * Serialize a JSX prop value to a JSX-safe string.
+ * Strings become `"value"`, numbers and booleans become `{value}`.
+ */
+function serializePropValue(val: number | boolean | string): string {
+  if (typeof val === "string") return `"${val}"`;
+  return `{${val}}`;
+}
+
+/**
+ * Build the JSX snippet + import line for a descriptor.
+ * The result is copy-pasteable into a React/JSX source file.
+ */
+function buildJsxSnippet(
+  descriptor: ShaderDescriptor,
+  surface: "fill" | "effect",
+): { importLine: string; jsxSnippet: string } {
+  const presetDef = SHADER_PRESET_MAP[descriptor.preset];
+  const componentName = descriptor.preset;
+
+  const zIndex = surface === "fill" ? 0 : 2;
+  const pointerEvents = surface === "effect" ? "none" : undefined;
+
+  const styleEntries: string[] = [
+    `position: "absolute"`,
+    `inset: 0`,
+    `zIndex: ${zIndex}`,
+    `width: "100%"`,
+    `height: "100%"`,
+  ];
+  if (pointerEvents) {
+    styleEntries.push(`pointerEvents: "${pointerEvents}"`);
+  }
+  const styleStr = styleEntries.join(", ");
+
+  const propLines: string[] = [];
+
+  // Colors — use provided colors or fall back to preset defaults
+  if (descriptor.colors && descriptor.colors.length > 0) {
+    propLines.push(`  colors={${JSON.stringify(descriptor.colors)}}`);
+  } else if (presetDef.defaultColors && presetDef.defaultColors.length > 0) {
+    propLines.push(`  colors={${JSON.stringify(presetDef.defaultColors)}}`);
+  }
+
+  // Single-color params from preset defaults when not in colors array
+  if (presetDef.defaultColorBack && !presetDef.defaultColors) {
+    propLines.push(`  colorBack="${presetDef.defaultColorBack}"`);
+  }
+  if (presetDef.defaultColorFront && !presetDef.defaultColors) {
+    propLines.push(`  colorFront="${presetDef.defaultColorFront}"`);
+  }
+
+  // Shader-specific params — merge preset defaults with descriptor overrides.
+  // ParamDef.default can be string[] for "colors" kind params; skip those here.
+  const defaultParamValues = Object.fromEntries(
+    presetDef.params
+      .filter((p) => !Array.isArray(p.default))
+      .map((p) => [p.key, p.default as number | boolean | string]),
+  );
+  const mergedParams: Record<string, number | boolean | string> = {
+    ...defaultParamValues,
+    ...(descriptor.params ?? {}),
+  };
+
+  for (const [key, val] of Object.entries(mergedParams)) {
+    propLines.push(`  ${key}=${serializePropValue(val)}`);
+  }
+
+  // Universal sizing/animation params from top-level descriptor fields
+  if (descriptor.speed !== undefined)
+    propLines.push(`  speed={${descriptor.speed}}`);
+  if (descriptor.frame !== undefined)
+    propLines.push(`  frame={${descriptor.frame}}`);
+  if (descriptor.fit !== undefined) propLines.push(`  fit="${descriptor.fit}"`);
+  if (descriptor.scale !== undefined)
+    propLines.push(`  scale={${descriptor.scale}}`);
+  if (descriptor.rotation !== undefined)
+    propLines.push(`  rotation={${descriptor.rotation}}`);
+  if (descriptor.offsetX !== undefined)
+    propLines.push(`  offsetX={${descriptor.offsetX}}`);
+  if (descriptor.offsetY !== undefined)
+    propLines.push(`  offsetY={${descriptor.offsetY}}`);
+
+  propLines.push(`  style={{ ${styleStr} }}`);
+
+  const jsxSnippet = `<${componentName}\n${propLines.join("\n")}\n/>`;
+  const importLine = `import { ${componentName} } from "@paper-design/shaders-react";`;
+
+  return { importLine, jsxSnippet };
+}
+
+/**
+ * Build the vanilla <canvas> data-shader element for inline HTML artboards.
+ * The design runtime reads `data-shader` and mounts the WebGL shader into the canvas.
+ */
+function buildBridgeMount(
+  descriptor: ShaderDescriptor,
+  surface: "fill" | "effect",
+): string {
+  const zIndex = surface === "fill" ? 0 : 2;
+  const pointerEvents = surface === "effect" ? "none" : "auto";
+  // Escape single quotes in the JSON so the attribute is safe in single-quoted HTML
+  const dataShader = JSON.stringify(descriptor).replace(/'/g, "&#39;");
+
+  return (
+    `<canvas\n` +
+    `  data-shader='${dataShader}'\n` +
+    `  style="position:absolute;inset:0;width:100%;height:100%;` +
+    `z-index:${zIndex};pointer-events:${pointerEvents};"\n` +
+    `></canvas>`
+  );
+}
+
+export default defineAction({
+  description: `
+Apply a GPU shader effect to a design element by validating params and returning the exact code
+to insert. This is a planning/validation action — it does not write files itself; the agent
+uses the returned snippets to make the actual edit via edit-design or apply-visual-edit.
+
+Available presets (8 total):
+- MeshGradient: Smooth flowing color spots with distortion + swirl. Best for hero/card fills. Accepts up to 10 colors.
+- GrainGradient: Noisy gradient in 7 shape modes (wave, dots, truchet, corners, ripple, blob, sphere). Up to 7 colors + colorBack.
+- Voronoi: Animated Voronoi cells with glow and gap colors. Good for geometric/abstract backgrounds.
+- Metaballs: Organic blobs that merge and split. Playful, great for marketing backgrounds.
+- Warp: Domain-warped distortion in several shape patterns (checks, cross, circle, star, waves, spiral). Abstract / high-energy.
+- GodRays: Volumetric light rays from a configurable source. Dramatic lighting effects.
+- Dithering: Ordered dithering overlay (composites over the layer beneath). Use surface="effect".
+- PaperTexture: Procedural paper with grain, fiber, crumples, and folds. Static by default (no animation).
+
+surface="fill" places the shader behind content (z-index 0, pointer-events auto).
+surface="effect" places it in front (z-index 2, pointer-events none) — use for overlays like Dithering.
+
+Framework artboards (React/JSX files): paste the returned importLine at the top and jsxSnippet
+inside the container element. The agent should call edit-design with the exact text.
+
+Inline/Alpine artboards (HTML files): inject the returned bridgeMount <canvas> element at the
+top of the container. The design runtime automatically mounts the shader.
+  `.trim(),
+  schema: z.object({
+    source: sourceSchema
+      .optional()
+      .describe(
+        "Design source for context. kind=design-file uses the SQL-backed file; kind=inline-html operates on inline HTML.",
+      ),
+    target: targetSchema
+      .optional()
+      .describe(
+        "Target element by nodeId or CSS selector. When omitted, the shader targets the root artboard container.",
+      ),
+    surface: z
+      .enum(["fill", "effect"])
+      .default("fill")
+      .describe(
+        'fill: shader sits behind content (z-index 0). effect: shader composites over content (z-index 2, pointer-events none). Use "effect" for Dithering.',
+      ),
+    descriptor: descriptorSchema.describe(
+      "Shader preset + params to apply. Use get-shader first to see available presets and current state.",
+    ),
+  }),
+  readOnly: true,
+  run: async ({ descriptor, surface, target }) => {
+    // Cast to ShaderDescriptor for the shared helpers
+    const desc: ShaderDescriptor = {
+      preset: descriptor.preset as ShaderPresetName,
+      params: descriptor.params ?? {},
+      colors: descriptor.colors,
+      speed: descriptor.speed,
+      frame: descriptor.frame,
+      fit: descriptor.fit,
+      scale: descriptor.scale,
+      rotation: descriptor.rotation,
+      offsetX: descriptor.offsetX,
+      offsetY: descriptor.offsetY,
+    };
+
+    const validation = validateDescriptor(desc);
+    if (!validation.valid) {
+      return {
+        ok: false,
+        errors: validation.errors,
+        descriptor: desc,
+        availablePresets: Object.keys(SHADER_PRESET_MAP),
+      };
+    }
+
+    const { importLine, jsxSnippet } = buildJsxSnippet(desc, surface);
+    const bridgeMount = buildBridgeMount(desc, surface);
+
+    const targetDescription = target?.nodeId
+      ? `node with id="${target.nodeId}"`
+      : target?.selector
+        ? `element matching selector "${target.selector}"`
+        : "the root artboard container element";
+
+    const instructions = [
+      `To apply the "${desc.preset}" shader as a ${surface} to ${targetDescription}:`,
+      "",
+      "== For React/JSX (framework artboard) ==",
+      `1. Add this import near the top of the component file (if not already present):`,
+      `   ${importLine}`,
+      `2. Inside ${targetDescription}, insert as the ${surface === "fill" ? "first" : "last"} child:`,
+      jsxSnippet
+        .split("\n")
+        .map((l) => `   ${l}`)
+        .join("\n"),
+      `   The parent element must have position:relative (or position:absolute/fixed) for the absolute positioning to work.`,
+      "",
+      "== For inline HTML artboard ==",
+      `1. Inside ${targetDescription}, insert as the ${surface === "fill" ? "first" : "last"} child:`,
+      bridgeMount
+        .split("\n")
+        .map((l) => `   ${l}`)
+        .join("\n"),
+      `   The parent element must have position:relative for the absolute positioning to work.`,
+      "",
+      "Use edit-design for JSX files (structural insert) or apply-visual-edit for inline HTML.",
+    ].join("\n");
+
+    return {
+      ok: true,
+      descriptor: desc,
+      surface,
+      importLine,
+      jsxSnippet,
+      bridgeMount,
+      instructions,
+    };
+  },
+});

package/corpus/templates/design/actions/apply-visual-edit.ts

@@ -0,0 +1,303 @@
+import { defineAction } from "@agent-native/core";
+import {
+  agentEnterDocument,
+  agentLeaveDocument,
+  agentUpdateSelection,
+  applyText,
+  getText,
+  hasCollabState,
+  seedFromText,
+} from "@agent-native/core/collab";
+import { accessFilter, assertAccess } from "@agent-native/core/sharing";
+import { and, eq } from "drizzle-orm";
+import { z } from "zod";
+
+import { getDb, schema } from "../server/db/index.js";
+import {
+  applyVisualEdit,
+  type CodeLayerSource,
+  type EditIntent,
+} from "../shared/code-layer.js";
+
+type VisualEditActionSource = 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"),
+    designId: z.string().optional(),
+    fileId: z.string().optional(),
+    filename: z.string().optional().default("index.html"),
+    path: z.string().optional(),
+    url: z.string().optional(),
+    revision: z.string().optional(),
+    html: z.string().optional(),
+  }),
+);
+
+const targetSchema = z.object({
+  nodeId: z.string().optional(),
+  selector: z.string().optional(),
+});
+
+const intentSchema = z.preprocess(
+  parseJsonString,
+  z.discriminatedUnion("kind", [
+    z.object({
+      kind: z.literal("style"),
+      target: targetSchema,
+      property: z
+        .string()
+        .describe(
+          "CSS property to set. Deterministic edits cover the visual editor's common layout, typography, fill, stroke, effect, transform, and spacing properties.",
+        ),
+      value: z.string().describe("CSS value to write into the inline style."),
+    }),
+    z.object({
+      kind: z.literal("class"),
+      target: targetSchema,
+      operation: z.enum(["add", "remove", "replace", "set"]),
+      className: z.string().optional(),
+      classNames: z.array(z.string()).optional(),
+      from: z.string().optional(),
+      to: z.string().optional(),
+    }),
+    z.object({
+      kind: z.literal("textContent"),
+      target: targetSchema,
+      value: z.string().describe("Text content for a leaf HTML element."),
+      html: z
+        .string()
+        .optional()
+        .describe(
+          "Optional sanitized inner HTML for preserving styled inline text runs.",
+        ),
+    }),
+    z.object({
+      kind: z.literal("moveNode"),
+      target: targetSchema,
+      anchor: targetSchema,
+      placement: z.enum(["before", "after", "inside"]),
+    }),
+  ]),
+);
+
+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 {
+    // Collab reads are best-effort; SQL content remains the fallback.
+  }
+  return storedContent;
+}
+
+async function resolveEditableDesignFile(
+  source: VisualEditActionSource,
+): Promise<{
+  id: string;
+  designId: string;
+  filename: string;
+  content: string;
+  codeLayerSource: 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("Visual code-layer edits only support HTML files for now.");
+  }
+
+  await assertAccess("design", file.designId, "editor");
+
+  return {
+    id: file.id,
+    designId: file.designId,
+    filename: file.filename,
+    content: await liveContent(file.id, file.content ?? ""),
+    codeLayerSource: {
+      kind: "design-file",
+      designId: file.designId,
+      fileId: file.id,
+      filename: file.filename,
+      revision: source.revision,
+    },
+  };
+}
+
+async function persistDesignFileEdit(file: {
+  id: string;
+  designId: string;
+  content: string;
+}): Promise<void> {
+  await assertAccess("design", file.designId, "editor");
+
+  const db = getDb();
+  const now = new Date().toISOString();
+
+  agentEnterDocument(file.id);
+  try {
+    await db
+      .update(schema.designFiles)
+      .set({ content: file.content, updatedAt: now })
+      .where(eq(schema.designFiles.id, file.id));
+
+    if (await hasCollabState(file.id)) {
+      await applyText(file.id, file.content, "content", "agent");
+    } else {
+      await seedFromText(file.id, file.content);
+    }
+
+    await db
+      .update(schema.designs)
+      .set({ updatedAt: now })
+      .where(eq(schema.designs.id, file.designId));
+  } finally {
+    agentLeaveDocument(file.id);
+  }
+}
+
+export default defineAction({
+  description:
+    "Apply one deterministic visual edit to a code-backed HTML design layer. " +
+    "Supports safe inline style, class, and leaf textContent edits on inline/SQL HTML files; escalates ambiguous or structural edits with PatchResult statuses.",
+  schema: z.object({
+    source: sourceSchema.describe(
+      "Edit source. Use kind=design-file with designId/filename or fileId to persist into SQL; kind=inline-html with html for a preview-only patch.",
+    ),
+    intent: intentSchema.describe(
+      "Visual edit intent targeting a CodeLayerProjection nodeId or selector.",
+    ),
+    includeContent: z
+      .boolean()
+      .optional()
+      .default(false)
+      .describe("Include patched HTML content in the response."),
+  }),
+  run: async ({ source, intent, includeContent }) => {
+    const actionSource = source as VisualEditActionSource;
+    const editIntent = intent as EditIntent;
+
+    if (actionSource.kind === "inline-html") {
+      const codeLayerSource: CodeLayerSource = {
+        kind: "inline-html",
+        filename: actionSource.filename,
+        revision: actionSource.revision,
+      };
+      const patch = applyVisualEdit(actionSource.html ?? "", editIntent, {
+        source: codeLayerSource,
+      });
+      return {
+        result: patch.result,
+        projection: patch.projection,
+        patchedContent: includeContent ? patch.content : undefined,
+        bytesBefore: (actionSource.html ?? "").length,
+        bytesAfter: patch.content.length,
+      };
+    }
+
+    if (actionSource.kind !== "design-file") {
+      const codeLayerSource: CodeLayerSource = {
+        kind: actionSource.kind,
+        path: actionSource.path,
+        url: actionSource.url,
+        filename: actionSource.filename,
+        revision: actionSource.revision,
+      };
+      const patch = applyVisualEdit("", editIntent, {
+        source: codeLayerSource,
+      });
+      return {
+        result: patch.result,
+        projection: patch.projection,
+        bytesBefore: 0,
+        bytesAfter: 0,
+      };
+    }
+
+    const file = await resolveEditableDesignFile(actionSource);
+    const patch = applyVisualEdit(file.content, editIntent, {
+      source: file.codeLayerSource,
+    });
+
+    if (patch.result.target) {
+      agentUpdateSelection(file.id, {
+        selection: patch.result.target.selector,
+        nodeId: patch.result.target.nodeId,
+        editingFile: file.filename,
+        designId: file.designId,
+      });
+    }
+
+    if (patch.result.status === "applied" && patch.result.changed) {
+      await persistDesignFileEdit({
+        id: file.id,
+        designId: file.designId,
+        content: patch.content,
+      });
+    }
+
+    return {
+      result: patch.result,
+      projection: patch.projection,
+      designId: file.designId,
+      fileId: file.id,
+      filename: file.filename,
+      persisted: patch.result.status === "applied" && patch.result.changed,
+      patchedContent: includeContent ? patch.content : undefined,
+      bytesBefore: file.content.length,
+      bytesAfter: patch.content.length,
+    };
+  },
+});