@agent-native/core 0.80.9 → 0.80.11

package/corpus/templates/design/actions/list-design-extensions.ts

@@ -0,0 +1,309 @@
+/**
+ * list-design-extensions — read action.
+ *
+ * Returns the first-party Design Studio extensions with their capability and
+ * availability status.  The four built-in extensions are:
+ *
+ *   1. Asset Library     — selection-aware asset insertion (ships now).
+ *   2. Shader Fills      — GPU shader fill previews (preview-only now; apply gated).
+ *   3. Token Auditor     — reads token usage across the design and flags clashes.
+ *   4. Motion Presets    — one-click motion preset application.
+ *
+ * These are FIRST-PARTY extensions described as static metadata — they do not
+ * live in the extensions SQL table (they are capabilities of the design app,
+ * not user-created Alpine mini-apps).  The UI surfaces them in the
+ * `design.editor.inspector` slot alongside user-installed extensions.
+ *
+ * The action also returns which actions power each extension, so the agent
+ * can invoke them directly without going through the extension iframe sandbox.
+ *
+ * Plan reference: DESIGN-STUDIO-PLAN.md §6.7 + §7 (`list-design-extensions`).
+ */
+
+import { defineAction } from "@agent-native/core";
+import { z } from "zod";
+
+// ─── First-party extension catalog ───────────────────────────────────────────
+
+export type DesignExtensionAvailability =
+  | "available" // ships now; can be used immediately
+  | "preview-only" // read / preview possible; write/apply is gated
+  | "planned"; // exists in the plan; not yet implemented
+
+export interface DesignExtensionCapabilityEntry {
+  id: string;
+  label: string;
+  status: DesignExtensionAvailability;
+  reason?: string;
+}
+
+export interface FirstPartyDesignExtension {
+  /** Stable machine identifier — used by run-design-extension-action. */
+  id: string;
+  name: string;
+  description: string;
+  /** Tabler icon name (without the `Icon` prefix). */
+  icon: string;
+  /**
+   * Overall availability of this extension.
+   * Individual capabilities may be more restrictive.
+   */
+  availability: DesignExtensionAvailability;
+  /** Human-readable availability note shown in the UI. */
+  availabilityNote: string;
+  /** Fine-grained capability breakdown. */
+  capabilities: DesignExtensionCapabilityEntry[];
+  /** Design Studio actions that power this extension. */
+  actions: string[];
+  /**
+   * Whether this extension is registered in the `design.editor.inspector`
+   * extension slot as an installable first-party item.
+   */
+  slotId: "design.editor.inspector";
+}
+
+const FIRST_PARTY_EXTENSIONS: FirstPartyDesignExtension[] = [
+  // ── 1. Asset Library ─────────────────────────────────────────────────────
+  {
+    id: "design.asset-library",
+    name: "Asset Library",
+    description:
+      "Browse and insert generated or uploaded assets into the active design screen. " +
+      "Selection-aware: inserts near the selected element when one is active.",
+    icon: "Photo",
+    availability: "available",
+    availabilityNote: "Fully available — call insert-asset with an asset URL.",
+    capabilities: [
+      {
+        id: "browse",
+        label: "Browse asset library",
+        status: "available",
+      },
+      {
+        id: "insert",
+        label: "Insert asset into design",
+        status: "available",
+        reason:
+          "Uses insert-asset; selection-aware insertion lands immediately.",
+      },
+      {
+        id: "generate",
+        label: "Generate new asset via Assets app",
+        status: "available",
+        reason:
+          "Delegate to the Assets app via call-agent or the Assets MCP tool.",
+      },
+    ],
+    actions: ["insert-asset", "get-design-snapshot"],
+    slotId: "design.editor.inspector",
+  },
+
+  // ── 2. Shader Fills ──────────────────────────────────────────────────────
+  {
+    id: "design.shader-fills",
+    name: "Shader Fills",
+    description:
+      "GPU-accelerated shader fill presets (MeshGradient, GrainGradient, Voronoi, " +
+      "Metaballs, Warp, GodRays, Dithering, PaperTexture).  Preview as CSS gradient " +
+      "without writing anything; full apply is gated until runtime rendering + " +
+      "source-write + fallback + diff proof are all in place.",
+    icon: "Sparkles",
+    availability: "preview-only",
+    availabilityNote:
+      "Preview-only.  Call preview-shader-fill for a live CSS preview or " +
+      "apply-shader for a manual-edit code snippet.  apply-shader-fill is " +
+      "gated and will return NOT_YET_AVAILABLE until safety conditions are met.",
+    capabilities: [
+      {
+        id: "catalog",
+        label: "Browse shader preset catalog",
+        status: "available",
+        reason: "Call get-shader to see all 8 presets.",
+      },
+      {
+        id: "preview",
+        label: "Preview shader fill as CSS gradient",
+        status: "available",
+        reason:
+          "Call preview-shader-fill — returns previewCss + bridgeMessage; no writes.",
+      },
+      {
+        id: "code-snippet",
+        label: "Generate code snippet for manual edit",
+        status: "available",
+        reason:
+          "Call apply-shader — returns JSX import + snippet or HTML bridge mount.",
+      },
+      {
+        id: "apply",
+        label: "Apply shader fill (persist to design)",
+        status: "preview-only",
+        reason:
+          "apply-shader-fill is GATED until: (1) runtime WebGL rendering verified via " +
+          "captureSnapshot, (2) source-write bridge available, (3) CSS fallback embedded " +
+          "alongside canvas, (4) before/after diff produced.  Today it returns gated:true.",
+      },
+    ],
+    actions: [
+      "get-shader",
+      "preview-shader-fill",
+      "apply-shader",
+      "apply-shader-fill",
+    ],
+    slotId: "design.editor.inspector",
+  },
+
+  // ── 3. Token Auditor ─────────────────────────────────────────────────────
+  {
+    id: "design.token-auditor",
+    name: "Token Auditor",
+    description:
+      "Reads CSS custom property (token) usage across the active design, surfaces " +
+      "clashes (e.g. hard-coded colours that should be tokens, unused tokens), and " +
+      "guides token-first editing via the Tweaks loop.",
+    icon: "Palette",
+    availability: "available",
+    availabilityNote:
+      "Token reads are available for all source types.  Token write-back " +
+      "to real source files (globals.css / tailwind.config) is gated on bridge " +
+      "hardening and requires a real-app source type.",
+    capabilities: [
+      {
+        id: "index",
+        label: "Index tokens from design",
+        status: "available",
+        reason: "Call index-design-tokens to parse CSS vars from the design.",
+      },
+      {
+        id: "preview-edit",
+        label: "Preview token edit",
+        status: "available",
+        reason: "Call preview-design-token-edit for a live CSS-var preview.",
+      },
+      {
+        id: "apply-edit",
+        label: "Apply token edit (persist)",
+        status: "available",
+        reason:
+          "Call apply-design-token-edit — persists via the Tweaks loop for inline designs.",
+      },
+      {
+        id: "write-source",
+        label: "Write token back to source file",
+        status: "preview-only",
+        reason:
+          "Source write-back (globals.css / tailwind.config) requires a real-app " +
+          "source type and bridge hardening.  Currently planned.",
+      },
+    ],
+    actions: [
+      "index-design-tokens",
+      "preview-design-token-edit",
+      "apply-design-token-edit",
+      "get-design-surface-index",
+    ],
+    slotId: "design.editor.inspector",
+  },
+
+  // ── 4. Motion Presets ────────────────────────────────────────────────────
+  {
+    id: "design.motion-presets",
+    name: "Motion Presets",
+    description:
+      "One-click animation presets (fade-in, slide-up, pulse, bounce, spin) that " +
+      "apply to the selected node via the motion timeline.  Preview is live; " +
+      "Write to CSS commits the keyframes atomically.",
+    icon: "PlayerPlay",
+    availability: "available",
+    availabilityNote:
+      "Motion preview is available for all source types.  Write to CSS (apply-motion-edit) " +
+      "is atomic and available for inline + localhost.  Source write-back to real CSS " +
+      "modules remains planned for the fusion tier.",
+    capabilities: [
+      {
+        id: "preview",
+        label: "Preview motion preset (scrub, no write)",
+        status: "available",
+        reason:
+          "Preview sends a motion-preview bridge message — no DB / collab write.",
+      },
+      {
+        id: "apply",
+        label: "Write keyframes to CSS (apply-motion-edit)",
+        status: "available",
+        reason:
+          "apply-motion-edit is atomic: persists timeline row + compiled CSS + " +
+          "Yjs/collab update + diff proof in one call.",
+      },
+      {
+        id: "write-source",
+        label: "Write to real CSS module / motion-react",
+        status: "preview-only",
+        reason:
+          "Real-source CSS module write-back is planned for fusion tier after bridge hardening.",
+      },
+    ],
+    actions: [
+      "get-motion-timeline",
+      "apply-motion-edit",
+      "remove-motion-timeline",
+    ],
+    slotId: "design.editor.inspector",
+  },
+];
+
+// ─── Action ──────────────────────────────────────────────────────────────────
+
+export default defineAction({
+  description: `
+List the first-party Design Studio extensions with their capability and availability status.
+
+Returns the four built-in extensions:
+  1. Asset Library     — selection-aware asset insertion (available now).
+  2. Shader Fills      — GPU shader fill previews (preview-only; apply is gated).
+  3. Token Auditor     — token usage reads + edits (available; source write-back planned).
+  4. Motion Presets    — one-click animation presets (available; source write-back planned).
+
+Each entry includes the actions that power it so the agent can call them directly.
+Use run-design-extension-action to dispatch an action through the extension surface.
+  `.trim(),
+  schema: z.object({
+    filter: z
+      .object({
+        availability: z
+          .enum(["available", "preview-only", "planned", "all"])
+          .optional()
+          .default("all")
+          .describe("Return only extensions with this availability status."),
+        extensionId: z
+          .string()
+          .optional()
+          .describe("Return only the extension with this id."),
+      })
+      .optional(),
+  }),
+  readOnly: true,
+  run: async ({ filter }) => {
+    let extensions = FIRST_PARTY_EXTENSIONS;
+
+    if (filter?.extensionId) {
+      extensions = extensions.filter((e) => e.id === filter.extensionId);
+    }
+
+    if (filter?.availability && filter.availability !== "all") {
+      extensions = extensions.filter(
+        (e) => e.availability === filter.availability,
+      );
+    }
+
+    return {
+      extensions,
+      count: extensions.length,
+      slotId: "design.editor.inspector",
+      note:
+        "These are first-party Design Studio extensions.  User-created extensions " +
+        "live in the `design.editor.inspector` slot and can be listed via the core " +
+        "`list-extensions` action with a search filter for the slot id.",
+    };
+  },
+});

package/corpus/templates/design/actions/list-design-source-capabilities.ts

@@ -0,0 +1,153 @@
+import { defineAction } from "@agent-native/core";
+import { resolveAccess } from "@agent-native/core/sharing";
+import { eq } from "drizzle-orm";
+import { z } from "zod";
+
+import { getDb, schema } from "../server/db/index.js";
+import { resolveSourceCapabilities } from "../shared/capability-resolver.js";
+import { DESIGN_CAPABILITY_NAMES } from "../shared/design-source-capabilities.js";
+import "../server/db/index.js"; // ensure registerShareableResource runs
+import { normalizeDesignSourceType } from "../shared/source-mode.js";
+
+export default defineAction({
+  description:
+    "Return the capability matrix for a design's current source. " +
+    "The matrix maps each capability name (readFile, writeFile, applyEdit, " +
+    "resolveNodeToFile, previewPatch, diffPatch, captureSnapshot, captureState, " +
+    "indexComponents, indexTokens, writeTokens, previewMotion, writeMotion, " +
+    "branch, deployPreview, deploy) to its status (available | planned | " +
+    "unavailable) plus an optional human-readable reason. " +
+    "UI controls and agent actions must gate on this matrix — never on sourceType alone.",
+  schema: z.object({
+    designId: z
+      .string()
+      .describe("Design project ID to fetch source capabilities for"),
+  }),
+  readOnly: true,
+  http: { method: "GET" },
+  run: async ({ designId }) => {
+    const access = await resolveAccess("design", designId);
+    if (!access) {
+      throw new Error("Design not found");
+    }
+
+    const db = getDb();
+
+    // Resolve source type from the design's data blob.  The `sourceType`
+    // field lives inside `designs.data` as a JSON key (set by connect-localhost
+    // and the fusion upgrade flow), falling back to "inline" when absent.
+    let rawSourceType: unknown = "inline";
+    const rawData = (access.resource as { data?: unknown }).data;
+    if (typeof rawData === "string") {
+      try {
+        const parsed: unknown = JSON.parse(rawData);
+        if (
+          parsed !== null &&
+          typeof parsed === "object" &&
+          !Array.isArray(parsed) &&
+          "sourceType" in (parsed as object)
+        ) {
+          rawSourceType = (parsed as { sourceType: unknown }).sourceType;
+        }
+      } catch {
+        // Stale/invalid JSON — default to "inline".
+      }
+    }
+
+    const sourceType = normalizeDesignSourceType(rawSourceType) ?? "inline";
+    const capabilities = resolveSourceCapabilities(sourceType);
+
+    // Collect active localhost capabilities from the design's stored connection,
+    // if any, so that a bridge handshake that has already proven readFile
+    // is reflected here too.
+    let connectionCapabilities: Record<string, { status: string }> = {};
+    if (sourceType === "localhost") {
+      try {
+        const rawDesignData =
+          typeof rawData === "string" ? JSON.parse(rawData) : {};
+        const connectionId =
+          typeof rawDesignData === "object" &&
+          rawDesignData !== null &&
+          "connectionId" in rawDesignData
+            ? String(rawDesignData.connectionId)
+            : undefined;
+
+        if (connectionId) {
+          const [conn] = await db
+            .select({
+              capabilities: schema.designLocalhostConnections.capabilities,
+            })
+            .from(schema.designLocalhostConnections)
+            .where(eq(schema.designLocalhostConnections.id, connectionId))
+            .limit(1);
+
+          if (conn?.capabilities) {
+            try {
+              const parsed: unknown = JSON.parse(conn.capabilities);
+              if (Array.isArray(parsed)) {
+                // Bridge capabilities are DesignBridgeCapability[] with operation + status.
+                for (const entry of parsed) {
+                  if (
+                    entry !== null &&
+                    typeof entry === "object" &&
+                    "operation" in entry &&
+                    "status" in entry
+                  ) {
+                    const op = String(
+                      (entry as { operation: unknown }).operation,
+                    );
+                    const st = String((entry as { status: unknown }).status);
+                    connectionCapabilities[op] = { status: st };
+                  }
+                }
+              }
+            } catch {
+              // Ignore stale/invalid capability JSON.
+            }
+          }
+        }
+      } catch {
+        // Non-fatal: fall back to the defaults.
+      }
+    }
+
+    // Merge proven bridge capabilities (only for capabilities that exist in
+    // DESIGN_CAPABILITY_NAMES and only when the bridge reports "available").
+    const merged = { ...capabilities };
+    for (const capName of DESIGN_CAPABILITY_NAMES) {
+      const bridgeEntry = connectionCapabilities[capName];
+      if (bridgeEntry?.status === "available") {
+        merged[capName] = { status: "available" };
+      }
+    }
+
+    // Flatten to a list for easy agent consumption.
+    const capabilityList = DESIGN_CAPABILITY_NAMES.map((name) => ({
+      name,
+      ...merged[name],
+    }));
+
+    const availableNames = capabilityList
+      .filter((c) => c.status === "available")
+      .map((c) => c.name);
+
+    return {
+      designId,
+      sourceType,
+      capabilities: capabilityList,
+      availableCapabilities: availableNames,
+      summary: {
+        canWrite:
+          merged.applyEdit.status === "available" ||
+          merged.writeFile.status === "available",
+        canIndexComponents: merged.indexComponents.status === "available",
+        canWriteTokens: merged.writeTokens.status === "available",
+        canMotion:
+          merged.previewMotion.status === "available" ||
+          merged.writeMotion.status === "available",
+        canBranch: merged.branch.status === "available",
+        canDeploy: merged.deploy.status === "available",
+      },
+    };
+  },
+});

package/corpus/templates/design/actions/list-design-states.ts

@@ -0,0 +1,90 @@
+import { defineAction } from "@agent-native/core";
+import { accessFilter } from "@agent-native/core/sharing";
+import { and, desc, eq } from "drizzle-orm";
+import { z } from "zod";
+
+import { getDb, schema } from "../server/db/index.js";
+import "../server/db/index.js"; // ensure registerShareableResource runs
+
+function parseJsonRecord(raw: string | null): Record<string, unknown> | null {
+  if (!raw) return null;
+  try {
+    const parsed = JSON.parse(raw) as unknown;
+    return parsed && typeof parsed === "object" && !Array.isArray(parsed)
+      ? (parsed as Record<string, unknown>)
+      : null;
+  } catch {
+    return null;
+  }
+}
+
+export default defineAction({
+  description:
+    "List all design states, fixtures, and captures for a design. " +
+    "States are alternate DOM/Alpine snapshots (Default, Loading, Empty, Error). " +
+    "Fixtures hold static data payloads for real-app preview. " +
+    "Captures are live snapshots of a running app's route + props taken via the bridge.",
+  schema: z.object({
+    designId: z.string().describe("Design project ID"),
+    kind: z
+      .enum(["state", "fixture", "capture"])
+      .optional()
+      .describe("Filter to a specific kind. Omit to return all kinds."),
+    sourceRef: z
+      .string()
+      .optional()
+      .describe(
+        "Filter to a specific source ref (file id for inline, route id for localhost/fusion). Omit to return all.",
+      ),
+  }),
+  readOnly: true,
+  http: { method: "GET" },
+  run: async ({ designId, kind, sourceRef }) => {
+    const db = getDb();
+
+    // Access is checked via the parent designs row (design_state has no own shares table).
+    const conditions = [
+      accessFilter(schema.designs, schema.designShares),
+      eq(schema.designState.designId, designId),
+    ];
+
+    if (kind) {
+      conditions.push(eq(schema.designState.kind, kind));
+    }
+    if (sourceRef) {
+      conditions.push(eq(schema.designState.sourceRef, sourceRef));
+    }
+
+    const rows = await db
+      .select({
+        id: schema.designState.id,
+        designId: schema.designState.designId,
+        sourceRef: schema.designState.sourceRef,
+        name: schema.designState.name,
+        kind: schema.designState.kind,
+        breakpoint: schema.designState.breakpoint,
+        route: schema.designState.route,
+        fixtureData: schema.designState.fixtureData,
+        captureData: schema.designState.captureData,
+        previewRef: schema.designState.previewRef,
+        createdAt: schema.designState.createdAt,
+        updatedAt: schema.designState.updatedAt,
+      })
+      .from(schema.designState)
+      .innerJoin(
+        schema.designs,
+        eq(schema.designState.designId, schema.designs.id),
+      )
+      .where(and(...conditions))
+      .orderBy(desc(schema.designState.updatedAt));
+
+    return {
+      count: rows.length,
+      states: rows.map((row) => ({
+        ...row,
+        fixtureData: parseJsonRecord(row.fixtureData),
+        captureData: parseJsonRecord(row.captureData),
+      })),
+    };
+  },
+});