@agent-native/core 0.79.27 → 0.80.0

package/corpus/templates/design/actions/add-localhost-screens.ts

@@ -0,0 +1,426 @@
+import { defineAction, embedApp } from "@agent-native/core";
+import {
+  applyText,
+  hasCollabState,
+  seedFromText,
+} from "@agent-native/core/collab";
+import { buildDeepLink } from "@agent-native/core/server";
+import {
+  getRequestOrgId,
+  getRequestUserEmail,
+} from "@agent-native/core/server/request-context";
+import { assertAccess } from "@agent-native/core/sharing";
+import { and, desc, eq, isNull } from "drizzle-orm";
+import { nanoid } from "nanoid";
+import { z } from "zod";
+
+import { getDb, schema } from "../server/db/index.js";
+import {
+  mergeCanvasFramePlacements,
+  type CanvasFramePlacement,
+} from "../shared/canvas-frames.js";
+import {
+  makeLocalhostRouteId,
+  titleFromRoutePath,
+  type LocalhostDesignRouteManifest,
+} from "../shared/source-mode.js";
+
+const routeInputSchema = z.object({
+  routeId: z.string().optional(),
+  path: z.string().optional(),
+  url: z.string().optional(),
+  title: z.string().optional(),
+  width: z.number().positive().optional(),
+  height: z.number().positive().optional(),
+  x: z.number().optional(),
+  y: z.number().optional(),
+  z: z.number().optional(),
+});
+
+type LocalhostScreenInput = z.infer<typeof routeInputSchema>;
+
+function designDeepLink(designId: string): string {
+  return buildDeepLink({
+    app: "design",
+    view: "editor",
+    params: { designId, editorView: "overview" },
+    to: `/design/${encodeURIComponent(designId)}`,
+  });
+}
+
+function parseJson<T>(value: string | null | undefined, fallback: T): T {
+  if (!value) return fallback;
+  try {
+    return JSON.parse(value) as T;
+  } catch {
+    return fallback;
+  }
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return Boolean(value && typeof value === "object" && !Array.isArray(value));
+}
+
+function normalizeBaseUrl(value: string): string {
+  const parsed = new URL(value);
+  parsed.hash = "";
+  return parsed.toString().replace(/\/$/, "");
+}
+
+function routeUrl(baseUrl: string, route: { path?: string; url?: string }) {
+  const raw = route.url ?? route.path ?? "/";
+  const parsed = new URL(raw, `${baseUrl}/`);
+  parsed.hash = "";
+  return parsed.toString();
+}
+
+function pathFromUrl(baseUrl: string, url: string, fallback?: string) {
+  try {
+    const parsed = new URL(url);
+    const base = new URL(baseUrl);
+    if (parsed.origin === base.origin) {
+      return `${parsed.pathname}${parsed.search}` || "/";
+    }
+  } catch {
+    // Fall through to the provided fallback.
+  }
+  return fallback ?? "/";
+}
+
+function slugForPath(pathOrUrl: string) {
+  const parsed = (() => {
+    try {
+      return new URL(pathOrUrl).pathname + new URL(pathOrUrl).search;
+    } catch {
+      return pathOrUrl;
+    }
+  })();
+  const slug = parsed
+    .replace(/^\/+/, "")
+    .replace(/[^a-zA-Z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .toLowerCase();
+  return (slug || "home").slice(0, 80);
+}
+
+function uniqueFilename(
+  pathOrUrl: string,
+  used: Set<string>,
+  preferred?: string,
+) {
+  const base = preferred ?? `localhost-${slugForPath(pathOrUrl)}.html`;
+  const [stem, extension = "html"] = base.split(/\.(?=[^.]+$)/);
+  let filename = `${stem}.${extension}`;
+  let suffix = 2;
+  while (used.has(filename)) {
+    filename = `${stem}-${suffix}.${extension}`;
+    suffix += 1;
+  }
+  used.add(filename);
+  return filename;
+}
+
+export default defineAction({
+  description:
+    "Create or refresh URL-backed localhost screens in a design project. " +
+    "Use after connect-localhost to place local app routes on the overview " +
+    "canvas as iframe-backed artboards with editable URL metadata.",
+  schema: z.object({
+    designId: z.string().describe("Design project ID to add screens to."),
+    connectionId: z
+      .string()
+      .optional()
+      .describe(
+        "Localhost connection ID from connect-localhost. Omit to use the latest connection.",
+      ),
+    routes: z
+      .preprocess(
+        (value) => (typeof value === "string" ? JSON.parse(value) : value),
+        z.array(routeInputSchema).optional(),
+      )
+      .describe(
+        "Routes or URL states to place. Each may include path, url, title, width, height, x/y/z.",
+      ),
+    paths: z
+      .preprocess(
+        (value) => (typeof value === "string" ? JSON.parse(value) : value),
+        z.array(z.string()).optional(),
+      )
+      .describe("Shortcut for routes when only paths/URLs are needed."),
+    defaultWidth: z
+      .number()
+      .positive()
+      .optional()
+      .default(1280)
+      .describe("Default iframe viewport width."),
+    defaultHeight: z
+      .number()
+      .positive()
+      .optional()
+      .default(900)
+      .describe("Default iframe viewport height."),
+    startX: z.number().optional().default(0),
+    startY: z.number().optional().default(0),
+    gap: z.number().optional().default(160),
+  }),
+  mcpApp: {
+    compactCatalog: true,
+    resource: embedApp({
+      title: "Local visual edit",
+      description: "Open local URL-backed screens in Design overview mode.",
+      iframeTitle: "Agent-Native Design",
+      openLabel: "Open overview",
+      height: 680,
+    }),
+  },
+  run: async ({
+    designId,
+    connectionId,
+    routes,
+    paths,
+    defaultWidth,
+    defaultHeight,
+    startX,
+    startY,
+    gap,
+  }) => {
+    await assertAccess("design", designId, "editor");
+    const ownerEmail = getRequestUserEmail();
+    if (!ownerEmail) throw new Error("no authenticated user");
+    const orgId = getRequestOrgId() ?? null;
+    const db = getDb();
+
+    const connectionClauses = [
+      eq(schema.designLocalhostConnections.ownerEmail, ownerEmail),
+      orgId
+        ? eq(schema.designLocalhostConnections.orgId, orgId)
+        : isNull(schema.designLocalhostConnections.orgId),
+    ];
+    if (connectionId) {
+      connectionClauses.push(
+        eq(schema.designLocalhostConnections.id, connectionId),
+      );
+    }
+
+    const [connection] = await db
+      .select()
+      .from(schema.designLocalhostConnections)
+      .where(and(...connectionClauses))
+      .orderBy(desc(schema.designLocalhostConnections.updatedAt))
+      .limit(1);
+
+    if (!connection) {
+      throw new Error(
+        connectionId
+          ? `No localhost connection found for ${connectionId}.`
+          : "No localhost connection found. Run connect-localhost first.",
+      );
+    }
+
+    const devServerUrl = normalizeBaseUrl(connection.devServerUrl);
+    const manifest = parseJson<LocalhostDesignRouteManifest>(
+      connection.routeManifest,
+      {
+        version: 1,
+        sourceType: "localhost",
+        devServerUrl,
+        rootPath: connection.rootPath ?? undefined,
+        routes: [],
+        generatedAt: connection.updatedAt ?? new Date(0).toISOString(),
+      },
+    );
+    const manifestByPath = new Map(
+      manifest.routes.map((route) => [route.path, route]),
+    );
+    const manifestById = new Map(
+      manifest.routes.map((route) => [route.id, route]),
+    );
+    const requestedRoutes: LocalhostScreenInput[] = routes?.length
+      ? routes
+      : paths?.length
+        ? paths.map((path) => ({ path }))
+        : manifest.routes.map((route) => ({
+            routeId: route.id,
+            path: route.path,
+            title: route.title,
+            width:
+              typeof route.metadata?.width === "number"
+                ? route.metadata.width
+                : undefined,
+            height:
+              typeof route.metadata?.height === "number"
+                ? route.metadata.height
+                : undefined,
+          }));
+
+    if (requestedRoutes.length === 0) {
+      throw new Error(
+        "No routes were provided and the localhost manifest has no routes.",
+      );
+    }
+
+    const [design] = await db
+      .select({ data: schema.designs.data })
+      .from(schema.designs)
+      .where(eq(schema.designs.id, designId))
+      .limit(1);
+    const existingFiles = await db
+      .select()
+      .from(schema.designFiles)
+      .where(eq(schema.designFiles.designId, designId));
+    const existingByFilename = new Map(
+      existingFiles.map((file) => [file.filename, file]),
+    );
+    const usedFilenames = new Set(existingFiles.map((file) => file.filename));
+    const now = new Date().toISOString();
+    const savedScreens: Array<{
+      id: string;
+      filename: string;
+      title: string;
+      path: string;
+      url: string;
+      routeId: string;
+      width: number;
+      height: number;
+    }> = [];
+    const placements: CanvasFramePlacement[] = [];
+
+    for (let index = 0; index < requestedRoutes.length; index += 1) {
+      const input = requestedRoutes[index]!;
+      const manifestRoute =
+        (input.routeId ? manifestById.get(input.routeId) : undefined) ??
+        (input.path ? manifestByPath.get(input.path) : undefined);
+      const url = routeUrl(devServerUrl, {
+        path: input.path ?? manifestRoute?.path,
+        url: input.url,
+      });
+      const path = pathFromUrl(
+        devServerUrl,
+        url,
+        input.path ?? manifestRoute?.path ?? "/",
+      );
+      const routeId =
+        input.routeId ?? manifestRoute?.id ?? makeLocalhostRouteId(path);
+      const title =
+        input.title ?? manifestRoute?.title ?? titleFromRoutePath(path);
+      const width = input.width ?? defaultWidth;
+      const height = input.height ?? defaultHeight;
+      const preferredFilename = `localhost-${slugForPath(path)}.html`;
+      const existing = existingByFilename.get(preferredFilename);
+      const filename =
+        existing?.filename ??
+        uniqueFilename(path, usedFilenames, preferredFilename);
+      const fileId = existing?.id ?? nanoid();
+
+      if (existing) {
+        await db
+          .update(schema.designFiles)
+          .set({ content: url, fileType: "html", updatedAt: now })
+          .where(eq(schema.designFiles.id, existing.id));
+        if (await hasCollabState(existing.id)) {
+          await applyText(existing.id, url, "content", "agent");
+        } else {
+          await seedFromText(existing.id, url);
+        }
+      } else {
+        await db.insert(schema.designFiles).values({
+          id: fileId,
+          designId,
+          filename,
+          fileType: "html",
+          content: url,
+          createdAt: now,
+          updatedAt: now,
+        });
+        await seedFromText(fileId, url);
+      }
+
+      savedScreens.push({
+        id: fileId,
+        filename,
+        title,
+        path,
+        url,
+        routeId,
+        width,
+        height,
+      });
+      placements.push({
+        fileId,
+        filename,
+        x: input.x ?? startX + index * (width + gap),
+        y: input.y ?? startY,
+        width,
+        height,
+        z: input.z ?? index,
+      });
+    }
+
+    const prevData = parseJson<Record<string, unknown>>(design?.data, {});
+    const mergedFrames = mergeCanvasFramePlacements({
+      existing: prevData.canvasFrames,
+      placements,
+      resolveFileId: (placement) => placement.fileId,
+    });
+    const previousMetadata = isRecord(prevData.screenMetadata)
+      ? { ...prevData.screenMetadata }
+      : {};
+    const previousLocalhostScreens = isRecord(prevData.localhostScreens)
+      ? { ...prevData.localhostScreens }
+      : {};
+    for (const screen of savedScreens) {
+      const metadata = {
+        sourceType: "localhost",
+        previewState: "live",
+        title: screen.title,
+        width: screen.width,
+        height: screen.height,
+        url: screen.url,
+        previewUrl: screen.url,
+        connectionId: connection.id,
+        routeId: screen.routeId,
+        path: screen.path,
+        bridgeUrl: connection.bridgeUrl ?? undefined,
+      };
+      previousMetadata[screen.id] = metadata;
+      previousLocalhostScreens[screen.id] = metadata;
+    }
+
+    await db
+      .update(schema.designs)
+      .set({
+        data: JSON.stringify({
+          ...prevData,
+          sourceMode: "localhost",
+          canvasFrames: mergedFrames.canvasFrames,
+          screenMetadata: previousMetadata,
+          localhostScreens: previousLocalhostScreens,
+          updatedAt: now,
+        }),
+        updatedAt: now,
+      })
+      .where(eq(schema.designs.id, designId));
+
+    return {
+      designId,
+      connectionId: connection.id,
+      devServerUrl,
+      bridgeUrl: connection.bridgeUrl ?? null,
+      screenCount: savedScreens.length,
+      screens: savedScreens,
+      placedFrames: mergedFrames.placedFrames,
+      overview: true,
+      urlPath: `/design/${designId}`,
+    };
+  },
+  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 overview",
+      view: "editor",
+    };
+  },
+});

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