@agent-native/core 0.80.9 → 0.80.10

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

@@ -0,0 +1,404 @@
+/**
+ * apply-shader-fill — PERSISTING apply action.
+ *
+ * Writes the chosen shader fill onto a design element as a CSS `background`,
+ * the same gradient the preview renders. This is the deliberate commit step
+ * after `preview-shader-fill`; preview stays non-persisting.
+ *
+ * Safety model (this action is SAFETY-gated, not Builder-gated):
+ * - Editor access is asserted on the target design before any write
+ *   (`accessFilter` on the read + `assertAccess("design", id, "editor")`).
+ * - Only HTML design-file sources are writable — the deterministic HTML editor
+ *   (`applyVisualEdit`) is the single mutation seam, exactly like
+ *   `apply-visual-edit`. localhost / fusion / inline-html sources are NOT
+ *   written; the caller gets the preview + an explanation instead.
+ * - The persisted value is a CSS `background` produced by
+ *   `buildShaderFillBackground`, which runs every colour through the same strict
+ *   CSS-colour allowlist that `preview-shader-fill` uses (`shader-fill.ts`), so a
+ *   `descriptor.colors` payload can never inject CSS into the source.
+ * - The descriptor is validated against the preset manifest first, so callers
+ *   get clear errors before any round-trip.
+ *
+ * The write reuses the canonical persist path (Yjs/collab + SQL via
+ * agentEnterDocument / applyText / seedFromText), so collaborators and the agent
+ * stay in sync. The edit is a single inline-style `style.background` change on
+ * the resolved node — no structural inserts, no new owned rows.
+ *
+ * Plan reference: DESIGN-STUDIO-PLAN.md §6.7 + §7 (shader fill apply).
+ */
+
+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 StyleEditIntent,
+} from "../shared/code-layer.js";
+import {
+  buildShaderFillBackground,
+  generateShaderFillFallbackCss,
+  generateShaderFillPreviewCss,
+} from "../shared/shader-fill.js";
+import {
+  SHADER_PRESET_MAP,
+  type ShaderDescriptor,
+  type ShaderPresetName,
+  validateDescriptor,
+} from "../shared/shader-presets.js";
+
+// ─── Schema ──────────────────────────────────────────────────────────────────
+
+const PRESET_NAMES = Object.keys(SHADER_PRESET_MAP) as [
+  ShaderPresetName,
+  ...ShaderPresetName[],
+];
+
+const descriptorSchema = z.object({
+  preset: z
+    .enum(PRESET_NAMES)
+    .describe("Shader preset name. One of: " + PRESET_NAMES.join(", ")),
+  params: z
+    .record(z.string(), z.union([z.number(), z.boolean(), z.string()]))
+    .optional()
+    .default({})
+    .describe("Shader-specific params. Merged with preset defaults."),
+  colors: z
+    .array(z.string())
+    .optional()
+    .describe(
+      "Colour palette override. Falls back to preset defaults. Every colour " +
+        "is validated against a strict CSS-colour allowlist before it is " +
+        "written; unsafe entries are neutralised, never injected.",
+    ),
+  speed: z.number().optional(),
+  frame: z.number().optional(),
+  fit: z.enum(["none", "contain", "cover"]).optional(),
+  scale: z.number().optional(),
+  rotation: z.number().optional().describe("Rotation in radians."),
+  offsetX: z.number().optional(),
+  offsetY: z.number().optional(),
+});
+
+const sourceSchema = z
+  .object({
+    kind: z
+      .enum(["design-file", "inline-html", "localhost", "fusion"])
+      .default("design-file"),
+    designId: z.string().optional(),
+    fileId: z.string().optional(),
+    filename: z.string().optional(),
+    revision: z.string().optional(),
+  })
+  .describe(
+    "Design source. Only kind=design-file (HTML) is persisted. Provide " +
+      "designId (and optional filename) or fileId.",
+  );
+
+const targetSchema = z
+  .object({
+    nodeId: z.string().optional(),
+    selector: z.string().optional(),
+  })
+  .superRefine((target, ctx) => {
+    if (!target.nodeId && !target.selector) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        path: ["nodeId"],
+        message: "target.nodeId or target.selector is required",
+      });
+    }
+  })
+  .describe(
+    "Target element by nodeId (data-agent-native-node-id) or selector.",
+  );
+
+// ─── Persist helpers (mirrors apply-visual-edit.ts) ───────────────────────────
+
+interface ResolvedDesignFile {
+  id: string;
+  designId: string;
+  filename: string;
+  content: string;
+  codeLayerSource: CodeLayerSource;
+}
+
+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;
+}
+
+/**
+ * Resolve the target HTML design file with an access-scoped read, then assert
+ * editor access. Mirrors `resolveEditableDesignFile` in apply-visual-edit.ts so
+ * the shader-fill write goes through the exact same ownership gate.
+ */
+async function resolveEditableDesignFile(source: {
+  designId?: string;
+  fileId?: string;
+  filename?: string;
+  revision?: string;
+}): Promise<ResolvedDesignFile> {
+  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(
+      "Shader fills can only be persisted onto HTML design files for now.",
+    );
+  }
+  if (source.designId && file.designId !== source.designId) {
+    throw new Error(
+      `source.designId "${source.designId}" does not match file "${file.id}"`,
+    );
+  }
+  if (!source.fileId && source.filename && file.filename !== source.filename) {
+    throw new Error(
+      `source.filename "${source.filename}" does not match file "${file.id}"`,
+    );
+  }
+
+  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);
+    }
+
+    // guard:allow-unscoped — editor access on this design is asserted above
+    // (and again at the top of this helper); this only bumps the addressed
+    // design row's updatedAt.
+    await db
+      .update(schema.designs)
+      .set({ updatedAt: now })
+      .where(eq(schema.designs.id, file.designId));
+  } finally {
+    agentLeaveDocument(file.id);
+  }
+}
+
+// ─── Action ──────────────────────────────────────────────────────────────────
+
+export default defineAction({
+  description: `
+Persist a shader fill onto a design element as a CSS \`background\`.
+
+This is the commit step after preview-shader-fill. It writes the same gradient
+the preview renders onto the target element's inline style.background, using the
+deterministic HTML editor (the same persist path as apply-visual-edit).
+
+Gating: editor access on the target design is asserted before any write. Only
+HTML design-file sources are persisted; localhost / fusion / inline-html sources
+return the preview CSS plus an explanation and write nothing. Every colour is
+validated against the shared CSS-colour allowlist before it is written, so a
+descriptor.colors payload can never inject CSS into the source.
+
+Returns:
+- persisted     — true only when the source HTML was actually changed and saved.
+- background    — the CSS \`background\` value written (or that would be written).
+- fallbackCss   — a simpler static CSS background for export / PDF / SSR.
+- descriptor    — the resolved and validated ShaderDescriptor.
+- result        — the deterministic edit PatchResult (status, target, message).
+- bytesBefore / bytesAfter — proof-of-change for the persisted file.
+
+To preview without writing, call preview-shader-fill. To get a manual-edit code
+snippet (WebGL canvas / JSX component), call apply-shader.
+  `.trim(),
+  schema: z.object({
+    descriptor: descriptorSchema.describe("Shader preset + params to persist."),
+    target: targetSchema,
+    source: sourceSchema,
+  }),
+  run: async ({ descriptor: rawDescriptor, target, source }) => {
+    const descriptor: ShaderDescriptor = {
+      preset: rawDescriptor.preset as ShaderPresetName,
+      params: rawDescriptor.params ?? {},
+      colors: rawDescriptor.colors,
+      speed: rawDescriptor.speed,
+      frame: rawDescriptor.frame,
+      fit: rawDescriptor.fit,
+      scale: rawDescriptor.scale,
+      rotation: rawDescriptor.rotation,
+      offsetX: rawDescriptor.offsetX,
+      offsetY: rawDescriptor.offsetY,
+    };
+
+    // Validate against the preset manifest before any write so the caller gets
+    // clear errors without a wasted DB / collab round-trip.
+    const validation = validateDescriptor(descriptor);
+    if (!validation.valid) {
+      return {
+        ok: false,
+        persisted: false,
+        errors: validation.errors,
+        descriptor,
+        hint: "Fix the descriptor errors and retry. Call get-shader to see the full preset catalog.",
+      };
+    }
+
+    // Resolve the CSS `background` to write. Every colour is run through the
+    // strict CSS-colour allowlist here (same path preview-shader-fill uses).
+    const { background, colors } = buildShaderFillBackground(descriptor);
+    const fallbackCss = generateShaderFillFallbackCss(descriptor);
+
+    // Only HTML design-file sources are persisted. Everything else gets the
+    // preview value plus an explanation and writes nothing — the deterministic
+    // HTML editor is the single safe mutation seam.
+    if (source.kind !== "design-file") {
+      return {
+        ok: true,
+        persisted: false,
+        descriptor,
+        background: generateShaderFillPreviewCss(descriptor),
+        fallbackCss,
+        colors,
+        note:
+          `Shader fills are only persisted onto HTML design-file sources. ` +
+          `Source kind "${source.kind}" was not written. Inject the returned ` +
+          `background via the bridge for a live preview, or call apply-shader ` +
+          `for a manual-edit code snippet.`,
+      };
+    }
+
+    const file = await resolveEditableDesignFile(source);
+
+    const intent: StyleEditIntent = {
+      kind: "style",
+      target: { nodeId: target.nodeId, selector: target.selector },
+      property: "background",
+      value: background,
+    };
+
+    const patch = applyVisualEdit(file.content, intent, {
+      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,
+      });
+    }
+
+    const changed =
+      patch.result.status === "applied" && patch.result.changed === true;
+
+    if (changed) {
+      await persistDesignFileEdit({
+        id: file.id,
+        designId: file.designId,
+        content: patch.content,
+      });
+    }
+
+    return {
+      ok: patch.result.status === "applied",
+      persisted: changed,
+      descriptor,
+      background,
+      fallbackCss,
+      colors,
+      designId: file.designId,
+      fileId: file.id,
+      filename: file.filename,
+      result: patch.result,
+      bytesBefore: file.content.length,
+      bytesAfter: patch.content.length,
+      note: changed
+        ? "Shader fill persisted as the element's CSS background."
+        : "No change was written — the deterministic editor could not apply the edit. See result for details.",
+    };
+  },
+});

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

@@ -15,12 +15,117 @@ import { z } from "zod";
 import { getDb, schema } from "../server/db/index.js";
 import {
   applyVisualEdit,
+  type AutoLayoutEditIntent,
+  type ClassEditIntent,
   type CodeLayerSource,
   type EditIntent,
+  type UnwrapEditIntent,
+  type WrapNodesEditIntent,
 } from "../shared/code-layer.js";
+import type { TailwindBreakpointPrefix } from "../shared/design-state.js";
+import { utilityStem, widthToPrefix } from "../shared/responsive-classes.js";
 
 type VisualEditActionSource = CodeLayerSource & { html?: string };
 
+/** Tailwind responsive prefix values accepted by the action. */
+const TAILWIND_PREFIXES = ["base", "sm", "md", "lg", "xl", "2xl"] as const;
+
+/**
+ * Resolve the active breakpoint prefix for a class edit.
+ *
+ * - If `activeBreakpoint` is provided it is used directly.
+ * - If only `activeFrameWidthPx` is provided the prefix is derived via `widthToPrefix`.
+ * - If neither is provided the result is `null` (= no breakpoint scoping; global
+ *   class edit, current backward-compatible behaviour).
+ */
+function resolveActivePrefix(
+  activeBreakpoint?: TailwindBreakpointPrefix | null,
+  activeFrameWidthPx?: number | null,
+): TailwindBreakpointPrefix | null {
+  if (activeBreakpoint != null) return activeBreakpoint;
+  if (activeFrameWidthPx != null) return widthToPrefix(activeFrameWidthPx);
+  return null;
+}
+
+/**
+ * Derive a CSS-property key from a Tailwind class token for use in
+ * `responsive-class` `"remove"` operations (e.g. `"text-lg"` → `"font-size"`).
+ *
+ * Delegates to the shared `utilityStem` so the key matches EXACTLY what
+ * `setPropertyClass`/`removePropertyClass` compute internally — a divergent
+ * local heuristic would make breakpoint-scoped removes silently miss (and, with
+ * the old first-segment heuristic, nuke unrelated utilities like `text-center`).
+ */
+function stemFromToken(token: string): string {
+  // Strip any responsive prefix (e.g. "md:text-sm" → "text-sm").
+  const prefixMatch = /^(?:2xl|xl|lg|md|sm):/.exec(token);
+  const utility = prefixMatch ? token.slice(prefixMatch[0].length) : token;
+  return utilityStem(utility);
+}
+
+/**
+ * Convert a global `ClassEditIntent` into the equivalent `EditIntent` scoped to
+ * the given breakpoint prefix.
+ *
+ * - `"add"` and `"replace"` become `"responsive-class"` edits that write /
+ *   replace the utility at the target prefix.
+ * - `"remove"` becomes a `"responsive-class"` remove that strips the utility
+ *   stem at the target prefix.
+ * - `"set"` has no direct per-breakpoint analog (it replaces the whole class
+ *   list) and is passed through unchanged so existing behaviour is preserved.
+ *
+ * When `prefix` is `"base"`, the intent is returned unchanged because
+ * `setPropertyClass(className, "base", utility)` is equivalent to a
+ * global unprefixed add/replace and the existing `"class"` path already
+ * handles it correctly.
+ */
+function scopeClassIntentToBreakpoint(
+  intent: ClassEditIntent,
+  prefix: TailwindBreakpointPrefix,
+): EditIntent {
+  if (prefix === "base") return intent;
+
+  if (intent.operation === "add") {
+    const tokens =
+      intent.classNames ?? (intent.className ? [intent.className] : []);
+    if (tokens.length !== 1 || !tokens[0]) return intent;
+    return {
+      kind: "responsive-class",
+      target: intent.target,
+      prefix,
+      operation: "add",
+      utility: tokens[0],
+    };
+  }
+
+  if (intent.operation === "replace") {
+    if (!intent.to) return intent;
+    return {
+      kind: "responsive-class",
+      target: intent.target,
+      prefix,
+      operation: "replace",
+      utility: intent.to,
+    };
+  }
+
+  if (intent.operation === "remove") {
+    const tokens =
+      intent.classNames ?? (intent.className ? [intent.className] : []);
+    if (tokens.length !== 1 || !tokens[0]) return intent;
+    return {
+      kind: "responsive-class",
+      target: intent.target,
+      prefix,
+      operation: "remove",
+      stem: stemFromToken(tokens[0]),
+    };
+  }
+
+  // "set" — no per-breakpoint analog; fall back to global class edit.
+  return intent;
+}
+
 function parseJsonString(value: unknown): unknown {
   if (typeof value !== "string") return value;
   try {
@@ -39,7 +144,7 @@ const sourceSchema = z.preprocess(
         .default("design-file"),
       designId: z.string().optional(),
       fileId: z.string().optional(),
-      filename: z.string().optional().default("index.html"),
+      filename: z.string().optional(),
       path: z.string().optional(),
       url: z.string().optional(),
       revision: z.string().optional(),
@@ -110,6 +215,50 @@ const intentSchema = z.preprocess(
       anchor: targetSchema,
       placement: z.enum(["before", "after", "inside"]),
     }),
+    z.object({
+      kind: z.literal("wrapNodes"),
+      targetIds: z
+        .array(z.string())
+        .min(1)
+        .describe(
+          "data-agent-native-node-id values of sibling nodes to group. All must share a common parent.",
+        ),
+      autoLayout: z
+        .boolean()
+        .optional()
+        .describe(
+          "When true the wrapper gets display:flex; flex-direction:column; gap:8px and absolute positioning is stripped from each wrapped child.",
+        ),
+    }) satisfies z.ZodType<WrapNodesEditIntent>,
+    z.object({
+      kind: z.literal("unwrap"),
+      targetId: z
+        .string()
+        .describe(
+          "data-agent-native-node-id of the wrapper to remove, promoting its children to the wrapper's parent.",
+        ),
+    }) satisfies z.ZodType<UnwrapEditIntent>,
+    z.object({
+      kind: z.literal("autoLayout"),
+      targetId: z
+        .string()
+        .describe(
+          "data-agent-native-node-id of the container to convert to/from auto-layout.",
+        ),
+      enabled: z
+        .boolean()
+        .describe(
+          "true = enable auto-layout (display:flex + direction + gap, strip absolute positioning from direct children); false = set display:block.",
+        ),
+      direction: z
+        .enum(["row", "column"])
+        .optional()
+        .describe("Flex direction when enabling. Defaults to column."),
+      gap: z
+        .string()
+        .optional()
+        .describe("Gap value when enabling. Defaults to 8px."),
+    }) satisfies z.ZodType<AutoLayoutEditIntent>,
   ]),
 );
 
@@ -183,7 +332,7 @@ async function resolveEditableDesignFile(
       `source.designId "${source.designId}" does not match file "${file.id}"`,
     );
   }
-  if (source.filename && file.filename !== source.filename) {
+  if (!source.fileId && source.filename && file.filename !== source.filename) {
     throw new Error(
       `source.filename "${source.filename}" does not match file "${file.id}"`,
     );
@@ -241,7 +390,8 @@ async function persistDesignFileEdit(file: {
 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.",
+    "Supports safe inline style, class, and leaf textContent edits on inline/SQL HTML files; escalates ambiguous or structural edits with PatchResult statuses. " +
+    "Pass activeBreakpoint (or activeFrameWidthPx) to scope a class edit to a specific Tailwind responsive prefix; omit for global (backward-compatible) behaviour.",
   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.",
@@ -254,10 +404,46 @@ export default defineAction({
       .optional()
       .default(false)
       .describe("Include patched HTML content in the response."),
+    activeBreakpoint: z
+      .enum(TAILWIND_PREFIXES)
+      .optional()
+      .nullable()
+      .describe(
+        "Active canvas breakpoint prefix. When set and the intent is a 'class' edit, the change is written as a breakpoint-scoped Tailwind class (e.g. 'md:text-lg') instead of a global class. 'base' writes an unprefixed class (same as omitting this field). Takes priority over activeFrameWidthPx.",
+      ),
+    activeFrameWidthPx: z
+      .number()
+      .int()
+      .positive()
+      .optional()
+      .nullable()
+      .describe(
+        "Canvas frame width in pixels. When activeBreakpoint is not set, this is used to derive the Tailwind responsive prefix (via widthToPrefix) and scope class edits accordingly. Ignored when activeBreakpoint is provided.",
+      ),
   }),
-  run: async ({ source, intent, includeContent }) => {
+  run: async ({
+    source,
+    intent,
+    includeContent,
+    activeBreakpoint,
+    activeFrameWidthPx,
+  }) => {
     const actionSource = source as VisualEditActionSource;
-    const editIntent = intent as EditIntent;
+    let editIntent = intent as EditIntent;
+
+    // Breakpoint scoping: when the caller specifies an active breakpoint (or
+    // frame width) and the intent is a plain `"class"` edit, convert it to a
+    // `"responsive-class"` edit scoped to the appropriate Tailwind prefix.
+    // All other intent kinds (style, textContent, moveNode, responsive-class)
+    // are passed through unchanged — the caller either already supplied the
+    // correct prefix (responsive-class) or does not need one (the others).
+    const activePrefix = resolveActivePrefix(
+      activeBreakpoint,
+      activeFrameWidthPx,
+    );
+    if (activePrefix !== null && editIntent.kind === "class") {
+      editIntent = scopeClassIntentToBreakpoint(editIntent, activePrefix);
+    }
 
     if (actionSource.kind === "inline-html") {
       const codeLayerSource: CodeLayerSource = {