@agent-native/core 0.80.9 → 0.80.11

package/corpus/templates/design/actions/preview-component-prop-edit.ts

@@ -0,0 +1,260 @@
+/**
+ * preview-component-prop-edit — preview-only action.
+ *
+ * Computes the iframe bridge messages needed to preview a component prop
+ * change on the canvas without persisting anything to the database or Yjs.
+ *
+ * The caller pushes the returned `bridgeMessages` into the iframe via the
+ * existing `postMessage` channel (the same mechanism as `tweak-values` and
+ * `style-change`).  No writes are performed here.
+ *
+ * Supported prop edit kinds:
+ * - `alpineData`   — replaces the `x-data` attribute on the component root
+ *                    (Alpine variant / state switch).  Returned as a
+ *                    `style-change` bridge message targeting the node selector.
+ * - `attribute`    — sets any HTML attribute (e.g. `class`, `aria-*`,
+ *                    `data-agent-native-prop-*`).
+ * - `classReplace` — replaces one Tailwind utility with another on the root
+ *                    (lightweight responsive / variant preview via the
+ *                    existing `responsive-class` edit kind understood by
+ *                    the bridge).
+ *
+ * See DESIGN-STUDIO-PLAN.md §6.1 and §7 (preview vs apply contract).
+ */
+
+import { defineAction } from "@agent-native/core";
+import { getText, hasCollabState } from "@agent-native/core/collab";
+import { accessFilter, resolveAccess } from "@agent-native/core/sharing";
+import { and, eq } from "drizzle-orm";
+import { z } from "zod";
+
+import { getDb, schema } from "../server/db/index.js";
+import "../server/db/index.js"; // ensure registerShareableResource runs
+import { buildCodeLayerProjection } from "../shared/code-layer.js";
+import type { CodeLayerSource } from "../shared/code-layer.js";
+import {
+  componentNameFor,
+  componentNodeIdMatches,
+  extractProps,
+} from "../shared/component-model.js";
+import { normalizeDesignSourceType } from "../shared/source-mode.js";
+
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+
+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 is the fallback.
+  }
+  return storedContent;
+}
+
+// ─── Bridge message shapes ────────────────────────────────────────────────────
+
+/**
+ * A bridge message the client pushes into the canvas iframe via postMessage.
+ * The `type` matches the existing parent→iframe message vocabulary so no new
+ * message types are introduced.
+ */
+export interface ComponentPropPreviewMessage {
+  /** Matches the existing parent→iframe postMessage type vocabulary. */
+  type: "style-change" | "replace-document-content" | "select-element";
+  selector?: string;
+  nodeId?: string;
+  attributeOverrides?: Record<string, string>;
+  classEdit?: {
+    kind: "class";
+    operation: "replace";
+    from: string;
+    to: string;
+  };
+}
+
+// ─── Action ───────────────────────────────────────────────────────────────────
+
+export default defineAction({
+  description:
+    "Preview a component prop edit on the canvas without persisting. " +
+    "Returns bridge messages the client pushes into the canvas iframe via " +
+    "postMessage to show the change immediately. Supports alpineData (x-data " +
+    "attribute replace), attribute (arbitrary HTML attribute set), and " +
+    "classReplace (Tailwind utility swap) edit kinds.",
+  schema: z.object({
+    designId: z.string().describe("Design project ID"),
+    nodeId: z
+      .string()
+      .describe("data-agent-native-node-id of the component root to preview"),
+    fileId: z
+      .string()
+      .optional()
+      .describe("Design file id; defaults to index.html"),
+    edit: z
+      .discriminatedUnion("kind", [
+        z.object({
+          kind: z.literal("alpineData"),
+          value: z
+            .string()
+            .describe(
+              "New x-data expression for the Alpine component root, " +
+                "e.g. \"{ variant: 'outline', disabled: false }\"",
+            ),
+        }),
+        z.object({
+          kind: z.literal("attribute"),
+          attribute: z.string().describe("HTML attribute name to set"),
+          value: z.string().describe("New attribute value"),
+        }),
+        z.object({
+          kind: z.literal("classReplace"),
+          from: z.string().describe("Existing Tailwind class token to remove"),
+          to: z.string().describe("Replacement Tailwind class token to add"),
+        }),
+      ])
+      .describe("The prop edit to preview"),
+  }),
+  readOnly: true,
+  http: { method: "POST" },
+  run: async ({ designId, nodeId, fileId, edit }) => {
+    const db = getDb();
+
+    // ── Access check ────────────────────────────────────────────────────────
+    const access = await resolveAccess("design", designId);
+    if (!access) throw new Error("Design not found");
+
+    // ── Fetch file ───────────────────────────────────────────────────────────
+    const conditions = [
+      accessFilter(schema.designs, schema.designShares),
+      eq(schema.designFiles.designId, designId),
+      fileId
+        ? eq(schema.designFiles.id, fileId)
+        : eq(schema.designFiles.filename, "index.html"),
+    ];
+
+    const [file] = await db
+      .select({
+        id: schema.designFiles.id,
+        designId: schema.designFiles.designId,
+        filename: schema.designFiles.filename,
+        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.");
+
+    const html = await liveContent(file.id, file.content ?? "");
+
+    // ── Resolve node ─────────────────────────────────────────────────────────
+    const codeLayerSource: CodeLayerSource = {
+      kind: "design-file",
+      designId: file.designId,
+      fileId: file.id,
+      filename: file.filename,
+    };
+
+    const projection = buildCodeLayerProjection(html, {
+      source: codeLayerSource,
+    });
+
+    const node = projection.nodes.find((n) =>
+      componentNodeIdMatches(n, nodeId),
+    );
+    if (!node) {
+      throw new Error(
+        `Node "${nodeId}" not found. Run get-code-layer-projection to list current ids.`,
+      );
+    }
+
+    const componentName = componentNameFor(node);
+    if (!componentName) {
+      throw new Error(
+        `Node "${nodeId}" is not a component root (no data-agent-native-component attribute).`,
+      );
+    }
+
+    // ── Build bridge messages ────────────────────────────────────────────────
+    // All edit kinds map to existing parent→iframe message types so the client
+    // can push them without any new bridge surface.
+
+    const messages: ComponentPropPreviewMessage[] = [];
+
+    if (edit.kind === "alpineData") {
+      // Replace the x-data expression — communicated as a style-change with
+      // a special `attributeOverrides` key so the bridge can patch the DOM
+      // attribute without a full HTML replace.
+      messages.push({
+        type: "style-change",
+        selector: node.selector,
+        nodeId,
+        attributeOverrides: { "x-data": edit.value },
+      });
+    } else if (edit.kind === "attribute") {
+      messages.push({
+        type: "style-change",
+        selector: node.selector,
+        nodeId,
+        attributeOverrides: { [edit.attribute]: edit.value },
+      });
+    } else if (edit.kind === "classReplace") {
+      // Communicate as a responsive-class intent so the bridge applies it via
+      // the existing deterministic class-patch path.
+      messages.push({
+        type: "style-change",
+        selector: node.selector,
+        nodeId,
+        classEdit: {
+          kind: "class",
+          operation: "replace",
+          from: edit.from,
+          to: edit.to,
+        },
+      });
+    }
+
+    // Also emit a select-element message so the canvas highlights the node.
+    messages.push({
+      type: "select-element",
+      selector: node.selector,
+      nodeId,
+    });
+
+    const sourceType =
+      normalizeDesignSourceType(
+        (() => {
+          try {
+            const d = JSON.parse(
+              (access.resource as { data?: string }).data ?? "{}",
+            ) as Record<string, unknown>;
+            return d.sourceType ?? "inline";
+          } catch {
+            return "inline";
+          }
+        })(),
+      ) ?? "inline";
+
+    return {
+      designId,
+      nodeId,
+      componentName,
+      sourceType,
+      editKind: edit.kind,
+      /** Push each of these messages into the canvas iframe via postMessage. */
+      bridgeMessages: messages,
+      /** Snapshot of current observed props for before/after display. */
+      currentProps: extractProps(node),
+      note: "Preview only — no database writes performed. Call apply-component-prop-edit to persist.",
+    };
+  },
+});

package/corpus/templates/design/actions/preview-design-token-edit.ts

@@ -0,0 +1,113 @@
+import { defineAction } from "@agent-native/core";
+import { resolveAccess } from "@agent-native/core/sharing";
+import { z } from "zod";
+
+import "../server/db/index.js"; // ensure registerShareableResource runs
+import { resolveTweaksToCssVars } from "../shared/resolve-tweaks.js";
+
+// ---------------------------------------------------------------------------
+// Token-edit patch schema
+// ---------------------------------------------------------------------------
+
+const tokenEditSchema = z.object({
+  /** The CSS custom property to update, e.g. "--primary-color". */
+  cssVar: z.string().startsWith("--").describe("CSS custom property to edit"),
+  /** New value string, e.g. "#3B82F6" or "0.75rem". */
+  value: z.string().describe("New value for the token"),
+});
+
+// ---------------------------------------------------------------------------
+// Action — preview only, no DB writes
+// ---------------------------------------------------------------------------
+
+export default defineAction({
+  description:
+    "Preview the effect of a design token edit without persisting it. " +
+    "Returns the full tweak-values payload (a { '--var': 'value' } map) " +
+    "that the client pushes into the iframe via the existing tweak-values " +
+    "postMessage so the user sees the change immediately before committing. " +
+    "No database writes are performed.",
+  schema: z.object({
+    designId: z.string().describe("Design project ID"),
+    edits: z
+      .array(tokenEditSchema)
+      .min(1)
+      .describe("One or more { cssVar, value } edits to preview"),
+  }),
+  readOnly: true,
+  http: { method: "POST" },
+  run: async ({ designId, edits }) => {
+    // Requires at least viewer access
+    const access = await resolveAccess("design", designId);
+    if (!access) {
+      throw new Error("Design not found");
+    }
+
+    const design = access.resource;
+
+    // Load existing tweak definitions and selections from the design's data
+    let designData: Record<string, unknown> = {};
+    try {
+      designData = design.data
+        ? (JSON.parse(design.data) as Record<string, unknown>)
+        : {};
+    } catch {
+      // Malformed JSON — treat as empty.
+    }
+
+    type TweakDef = Parameters<typeof resolveTweaksToCssVars>[0][number];
+    const tweaks: TweakDef[] = Array.isArray(designData.tweaks)
+      ? (designData.tweaks as TweakDef[])
+      : [];
+
+    const existingSelections =
+      designData.tweakSelections &&
+      typeof designData.tweakSelections === "object" &&
+      !Array.isArray(designData.tweakSelections)
+        ? (designData.tweakSelections as Record<
+            string,
+            string | number | boolean
+          >)
+        : {};
+
+    // Build the merged selection map with the requested edits applied.
+    // If the edit targets a known tweak cssVar we set by tweakId; otherwise
+    // we include the raw var in the payload so the client can apply it directly.
+    const cssVarToTweakId = new Map<string, string>();
+    for (const t of tweaks) {
+      if (t.cssVar) cssVarToTweakId.set(t.cssVar, t.id);
+    }
+
+    // Merged selections: existing + requested edits
+    const mergedSelections: Record<string, string | number | boolean> = {
+      ...existingSelections,
+    };
+    const directOverrides: Record<string, string> = {};
+    for (const { cssVar, value } of edits) {
+      const tweakId = cssVarToTweakId.get(cssVar);
+      if (tweakId) {
+        mergedSelections[tweakId] = value;
+      } else {
+        // Not a known tweak — include as a direct CSS var override
+        directOverrides[cssVar] = value;
+      }
+    }
+
+    // Resolve the full tweak set with the merged selections
+    const resolvedFromTweaks = resolveTweaksToCssVars(tweaks, mergedSelections);
+
+    // Merge in any direct overrides (CSS vars not backed by a tweak definition)
+    const tweakValues: Record<string, string> = {
+      ...resolvedFromTweaks,
+      ...directOverrides,
+    };
+
+    return {
+      designId,
+      /** Full `tweak-values` postMessage payload — push this into the iframe. */
+      tweakValues,
+      /** The specific edits that were previewed, for confirmation display. */
+      previewedEdits: edits,
+    };
+  },
+});

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

@@ -0,0 +1,187 @@
+/**
+ * preview-shader-fill — preview-only action.
+ *
+ * Returns the CSS mesh-gradient approximation for a shader fill so the caller
+ * can apply it to the selected node via the `shader-fill-preview` bridge
+ * message **without persisting anything**.
+ *
+ * Deliberately lightweight:
+ * - No DB access.
+ * - No Yjs / collab writes.
+ * - No bridge message sent by this action — the client consumes the returned
+ *   CSS and decides how to forward it to the iframe.
+ *
+ * Composes with motion: the `speed` field on the descriptor can be keyframed
+ * later via `apply-motion-edit` once CSS-animation support is proven; for now
+ * the preview is static-CSS-only (no WebGL, no canvas).
+ *
+ * Plan reference: DESIGN-STUDIO-PLAN.md §6.7 + §7 (`preview-shader-fill`).
+ */
+
+import { defineAction } from "@agent-native/core";
+import { z } from "zod";
+
+import {
+  generateShaderFillPreviewCss,
+  generateShaderFillFallbackCss,
+  buildShaderFillFallbackBlock,
+} 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.  Merge with preset defaults."),
+  colors: z
+    .array(z.string())
+    .optional()
+    .describe("Colour palette override.  Falls back to preset defaults."),
+  speed: z
+    .number()
+    .optional()
+    .describe(
+      "Animation speed multiplier (1 = normal).  Stored for future motion keyframe support; no effect on the static CSS preview.",
+    ),
+  frame: z.number().optional().describe("Static frame time (0–10000)."),
+  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 targetSchema = z
+  .object({
+    nodeId: z.string().optional(),
+    selector: z.string().optional(),
+  })
+  .optional()
+  .describe(
+    "Target element.  Provide nodeId or CSS selector.  When omitted, the root artboard container is targeted.",
+  );
+
+// ─── Action ──────────────────────────────────────────────────────────────────
+
+export default defineAction({
+  description: `
+Preview a CSS mesh-gradient shader fill on the selected design node without persisting anything.
+
+Returns:
+- previewCss   — a CSS \`background\` value for the live preview (inject via the shader-fill-preview bridge message).
+- fallbackCss  — a simpler static CSS \`background\` for export / PDF / SSR contexts.
+- fallbackBlock — a complete CSS rule block (selector + fallback background) ready to embed.
+- descriptor   — the resolved and validated ShaderDescriptor.
+- bridgeMessage — a ready-to-use JSON bridge payload for the iframe shader-fill-preview message.
+
+Call this before apply-shader-fill.  The preview is purely CSS — no WebGL, no canvas, no writes.
+
+Motion note: the \`speed\` field is accepted and stored on the descriptor for future motion-keyframe
+support; it has no effect on the static CSS preview output today.
+  `.trim(),
+  schema: z.object({
+    descriptor: descriptorSchema,
+    target: targetSchema,
+  }),
+  readOnly: true,
+  run: async ({ descriptor: rawDescriptor, target }) => {
+    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 so the caller gets clear errors
+    // before wasting a round-trip to the iframe.
+    const validation = validateDescriptor(descriptor);
+    if (!validation.valid) {
+      return {
+        ok: false,
+        errors: validation.errors,
+        descriptor,
+        hint: "Fix the descriptor errors and retry.  Call get-shader to see the full preset catalog.",
+      };
+    }
+
+    const previewCss = generateShaderFillPreviewCss(descriptor);
+    const fallbackCss = generateShaderFillFallbackCss(descriptor);
+
+    // Build a selector string for the fallback block — prefer nodeId selector.
+    const selector = target?.selector
+      ? target.selector
+      : target?.nodeId
+        ? `[data-agent-native-node-id="${target.nodeId}"]`
+        : ":root";
+
+    const fallbackBlock = buildShaderFillFallbackBlock(selector, descriptor);
+
+    // Build a ready-to-post bridge payload for the iframe.
+    // The `shader-fill-preview` message type is handled by DesignCanvas.tsx.
+    const bridgeMessage = {
+      type: "shader-fill-preview",
+      selector: target?.selector ?? null,
+      nodeId: target?.nodeId ?? null,
+      css: previewCss,
+      // Metadata so the client can attach a "preview only" badge.
+      _preview: true,
+      _source: "shader-fill",
+      _preset: descriptor.preset,
+    };
+
+    const instructions = [
+      `== Preview CSS (set as \`background\` on the target element) ==`,
+      previewCss,
+      ``,
+      `== Static Fallback CSS (for export/SSR — set as \`background\`) ==`,
+      fallbackCss,
+      ``,
+      `== Fallback block (embed in a <style> tag) ==`,
+      fallbackBlock,
+      ``,
+      `== Bridge message (post to the iframe) ==`,
+      JSON.stringify(bridgeMessage, null, 2),
+      ``,
+      `Apply steps:`,
+      `1. Inject the previewCss via a bridge "shader-fill-preview" message (no write, no persist).`,
+      `2. If the user approves, call apply-shader-fill — but note that action is currently GATED`,
+      `   and will return a clear not-yet-available result until runtime rendering +`,
+      `   source-write + diff proof are all in place.`,
+      `3. For inline/Alpine artboards, apply-shader (the existing planning action) returns`,
+      `   a <canvas data-shader=...> element that the design runtime mounts as WebGL.`,
+    ].join("\n");
+
+    return {
+      ok: true,
+      descriptor,
+      previewCss,
+      fallbackCss,
+      fallbackBlock,
+      bridgeMessage,
+      instructions,
+      note: "This is a preview-only result.  Nothing was written to the database or source.",
+    };
+  },
+});

package/corpus/templates/design/actions/remove-breakpoint.ts

@@ -0,0 +1,103 @@
+import { defineAction } from "@agent-native/core";
+import { assertAccess } from "@agent-native/core/sharing";
+import { eq } from "drizzle-orm";
+import { z } from "zod";
+
+import { getDb, schema } from "../server/db/index.js";
+import "../server/db/index.js"; // ensure registerShareableResource runs
+import type { BreakpointSet } from "../shared/design-state.js";
+
+function readBreakpointSet(designData: string | null): BreakpointSet | null {
+  if (!designData) return null;
+  try {
+    const parsed = JSON.parse(designData) as Record<string, unknown>;
+    if (parsed.breakpointSet && typeof parsed.breakpointSet === "object") {
+      return parsed.breakpointSet as BreakpointSet;
+    }
+  } catch {
+    // ignore
+  }
+  return null;
+}
+
+function writeBreakpointSet(
+  designData: string | null,
+  set: BreakpointSet,
+  now: string,
+): string {
+  let prev: Record<string, unknown> = {};
+  if (designData) {
+    try {
+      const parsed = JSON.parse(designData);
+      if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+        prev = parsed;
+      }
+    } catch {
+      // ignore
+    }
+  }
+  return JSON.stringify({
+    ...prev,
+    breakpointSet: set,
+    breakpointSetUpdatedAt: now,
+  });
+}
+
+export default defineAction({
+  description:
+    "Remove a breakpoint frame from the design's breakpoint set by its id. " +
+    "If the active breakpoint (stored in application state) matches the removed " +
+    "breakpoint, the UI should reset to the first remaining breakpoint or 'auto'.",
+  schema: z.object({
+    designId: z.string().describe("Design project ID"),
+    breakpointId: z
+      .string()
+      .describe("Id of the BreakpointDefinition to remove."),
+  }),
+  run: async ({ designId, breakpointId }) => {
+    await assertAccess("design", designId, "editor");
+
+    const db = getDb();
+    const [design] = await db
+      .select({ data: schema.designs.data })
+      .from(schema.designs)
+      .where(eq(schema.designs.id, designId))
+      .limit(1);
+
+    if (!design) throw new Error(`Design '${designId}' not found.`);
+
+    const set = readBreakpointSet(design.data);
+    if (!set) {
+      return {
+        removed: false,
+        reason: "No breakpoint set found for this design.",
+      };
+    }
+
+    const removed = set.breakpoints.find((bp) => bp.id === breakpointId);
+    if (!removed) {
+      return {
+        removed: false,
+        reason: `Breakpoint '${breakpointId}' not found in the set.`,
+      };
+    }
+
+    const updatedSet: BreakpointSet = {
+      ...set,
+      breakpoints: set.breakpoints.filter((bp) => bp.id !== breakpointId),
+    };
+
+    const now = new Date().toISOString();
+    const updatedData = writeBreakpointSet(design.data, updatedSet, now);
+    await db
+      .update(schema.designs)
+      .set({ data: updatedData, updatedAt: now })
+      .where(eq(schema.designs.id, designId));
+
+    return {
+      removed: true,
+      removedBreakpoint: removed,
+      breakpointSet: updatedSet,
+    };
+  },
+});