@agent-native/core 0.80.8 → 0.80.10

package/corpus/templates/design/actions/run-design-extension-action.ts

@@ -0,0 +1,284 @@
+/**
+ * run-design-extension-action — thin dispatcher.
+ *
+ * Routes an extension action request to the correct first-party action via
+ * the existing action surface.  Extensions add NO permanent editor chrome —
+ * this action is the single call-through so the agent doesn't need to remember
+ * which internal action backs each extension capability.
+ *
+ * For first-party extensions (design.asset-library, design.shader-fills,
+ * design.token-auditor, design.motion-presets), the action dispatches to the
+ * correct implementation.  The caller can always call the underlying action
+ * directly; this dispatcher exists as a convenience layer for the agent and
+ * for extension iframe code that calls `appAction("run-design-extension-action")`.
+ *
+ * For user-created extensions (kind="user-extension"), the action does NOT
+ * inject content into or modify the extension iframe itself — the iframe
+ * bridge handles that.  Instead, it records the request context so the agent
+ * can follow up.
+ *
+ * Reuses the existing extension infra:
+ * - Core `list-extensions` / `get-extension` for user extension resolution.
+ * - Per-action implementations for first-party capabilities.
+ * - The `design.editor.inspector` slot contract from DesignExtensionsPanel.tsx.
+ *
+ * Plan reference: DESIGN-STUDIO-PLAN.md §6.7 + §7 (`run-design-extension-action`).
+ */
+
+import { defineAction } from "@agent-native/core";
+import { resolveAccess } from "@agent-native/core/sharing";
+import { z } from "zod";
+
+// ─── Supported first-party extension ids ──────────────────────────────────────
+
+const FIRST_PARTY_IDS = [
+  "design.asset-library",
+  "design.shader-fills",
+  "design.token-auditor",
+  "design.motion-presets",
+] as const;
+
+type FirstPartyId = (typeof FIRST_PARTY_IDS)[number];
+
+// ─── Capability routing map ───────────────────────────────────────────────────
+
+/**
+ * Maps a `extensionId:capabilityId` pair to the action the caller should use.
+ * The dispatcher does NOT inline-call other actions (actions are not composable
+ * that way in this framework) — it returns routing guidance with the exact
+ * action name and params so the agent makes one follow-up call.
+ */
+interface CapabilityRoute {
+  action: string;
+  paramHint: string;
+  readOnly: boolean;
+  gated?: boolean;
+  gateReason?: string;
+}
+
+const CAPABILITY_ROUTES: Record<string, CapabilityRoute> = {
+  // Asset Library
+  "design.asset-library:browse": {
+    action: "get-design-snapshot",
+    paramHint:
+      "Call get-design-snapshot to inspect the active design, then use the Assets MCP tool (generate-asset / open-asset-picker) or the Assets app via call-agent.",
+    readOnly: true,
+  },
+  "design.asset-library:insert": {
+    action: "insert-asset",
+    paramHint:
+      "Call insert-asset with { assetUrl, designId?, fileId?, ownerId? }.  Pass ownerId from view-screen.designSelection for selection-aware placement.",
+    readOnly: false,
+  },
+  "design.asset-library:generate": {
+    action: "call-agent",
+    paramHint:
+      'Delegate to the Assets app via call-agent with agent "assets" and a generation prompt.  Pass the returned assetUrl to insert-asset.',
+    readOnly: false,
+  },
+
+  // Shader Fills
+  "design.shader-fills:catalog": {
+    action: "get-shader",
+    paramHint: "Call get-shader with an optional source context.",
+    readOnly: true,
+  },
+  "design.shader-fills:preview": {
+    action: "preview-shader-fill",
+    paramHint:
+      "Call preview-shader-fill with { descriptor: { preset, params?, colors?, speed? }, target? }.  Returns previewCss + bridgeMessage; no writes.",
+    readOnly: true,
+  },
+  "design.shader-fills:code-snippet": {
+    action: "apply-shader",
+    paramHint:
+      "Call apply-shader with { descriptor, surface?, target?, source? }.  Returns JSX import + snippet or HTML bridge mount for manual insertion.",
+    readOnly: true,
+  },
+  "design.shader-fills:apply": {
+    action: "apply-shader-fill",
+    paramHint:
+      "Call apply-shader-fill with { descriptor, target?, source?, surface? }.  NOTE: currently returns gated:true — all safety conditions are unmet.  Use preview or code-snippet instead.",
+    readOnly: false,
+    gated: true,
+    gateReason:
+      "apply-shader-fill is GATED until runtime rendering + source-write path + CSS fallback + diff proof are all in place.  It will return { ok: false, gated: true } today.",
+  },
+
+  // Token Auditor
+  "design.token-auditor:index": {
+    action: "index-design-tokens",
+    paramHint:
+      "Call index-design-tokens with { designId? } to parse CSS vars from the design.",
+    readOnly: true,
+  },
+  "design.token-auditor:preview-edit": {
+    action: "preview-design-token-edit",
+    paramHint:
+      "Call preview-design-token-edit with { designId, tokenId, value } for a live CSS-var preview.",
+    readOnly: true,
+  },
+  "design.token-auditor:apply-edit": {
+    action: "apply-design-token-edit",
+    paramHint:
+      "Call apply-design-token-edit with { designId, tokenId, value } to persist via the Tweaks loop.",
+    readOnly: false,
+  },
+  "design.token-auditor:write-source": {
+    action: "apply-design-token-edit",
+    paramHint:
+      "Source write-back is planned.  Call apply-design-token-edit — for inline designs it persists via Tweaks; for real-app sources with writeTokens capability it writes to the source file.",
+    readOnly: false,
+    gated: true,
+    gateReason:
+      "Source write-back to globals.css / tailwind.config is planned pending bridge hardening.",
+  },
+
+  // Motion Presets
+  "design.motion-presets:preview": {
+    action: "get-motion-timeline",
+    paramHint:
+      "Motion preview is a client-side postMessage bridge operation, not a server action. " +
+      "To inspect an existing timeline before committing, call get-motion-timeline with { designId }. " +
+      "To trigger a live scrub preview in the editor iframe, send a `motion-preview` postMessage from the extension UI.",
+    readOnly: true,
+  },
+  "design.motion-presets:apply": {
+    action: "apply-motion-edit",
+    paramHint:
+      "Call apply-motion-edit with { designId, fileId?, timeline: { tracks, durationMs } } for an atomic Write to CSS commit.",
+    readOnly: false,
+  },
+  "design.motion-presets:write-source": {
+    action: "apply-motion-edit",
+    paramHint:
+      "Real-source CSS module write-back is planned for fusion tier.  Today apply-motion-edit writes to the managed <style> block for inline designs.",
+    readOnly: false,
+    gated: true,
+    gateReason:
+      "CSS module write-back is planned pending fusion bridge hardening.",
+  },
+};
+
+// ─── Action ──────────────────────────────────────────────────────────────────
+
+export default defineAction({
+  description: `
+Dispatch an action through a first-party Design Studio extension surface.
+
+This is a thin routing layer — it does not call the underlying action itself;
+instead it returns the exact action name + param hint so the agent makes one
+follow-up call.  This keeps the extension surface composable without
+duplicating action logic.
+
+Supported first-party extensions (extensionId):
+  design.asset-library   — browse / insert / generate assets.
+  design.shader-fills    — catalog / preview / code-snippet / apply (apply is GATED).
+  design.token-auditor   — index / preview-edit / apply-edit / write-source.
+  design.motion-presets  — preview / apply / write-source.
+
+For user-created Alpine extensions, use list-extensions / get-extension / update-extension.
+The extension iframe itself is not called by this action — only the backing action route.
+  `.trim(),
+  schema: z.object({
+    extensionId: z
+      .string()
+      .describe(
+        "First-party extension id.  One of: " + FIRST_PARTY_IDS.join(", "),
+      ),
+    capabilityId: z
+      .string()
+      .describe(
+        "Capability to invoke within the extension.  Call list-design-extensions to see available capabilities per extension.",
+      ),
+    context: z
+      .object({
+        designId: z.string().optional(),
+        fileId: z.string().optional(),
+        nodeId: z.string().optional(),
+        selector: z.string().optional(),
+        ownerId: z.string().optional(),
+      })
+      .optional()
+      .describe(
+        "Optional context from the current design editor state (view-screen output).",
+      ),
+  }),
+  readOnly: true, // This dispatcher only returns routing guidance; it never writes.
+  run: async ({ extensionId, capabilityId, context }) => {
+    // Enforce read access before doing anything else when a designId is given,
+    // so this dispatcher can't be used to probe whether a design exists.
+    if (context?.designId) {
+      const access = await resolveAccess("design", context.designId);
+      if (!access) {
+        const err = new Error("Design not found") as Error & {
+          statusCode: number;
+        };
+        err.statusCode = 404;
+        throw err;
+      }
+    }
+
+    // Validate extension id.
+    if (!FIRST_PARTY_IDS.includes(extensionId as FirstPartyId)) {
+      return {
+        ok: false,
+        error: `Unknown first-party extensionId: "${extensionId}".`,
+        knownExtensions: FIRST_PARTY_IDS,
+        hint: "For user-created extensions, use list-extensions / get-extension / update-extension.",
+      };
+    }
+
+    const routeKey = `${extensionId}:${capabilityId}`;
+    const route = CAPABILITY_ROUTES[routeKey];
+
+    if (!route) {
+      // Return available capabilities for this extension.
+      const availableCaps = Object.keys(CAPABILITY_ROUTES)
+        .filter((k) => k.startsWith(`${extensionId}:`))
+        .map((k) => k.split(":")[1]);
+
+      return {
+        ok: false,
+        error: `Unknown capabilityId "${capabilityId}" for extension "${extensionId}".`,
+        availableCapabilities: availableCaps,
+        hint: `Call list-design-extensions with extensionId "${extensionId}" to see all capabilities.`,
+      };
+    }
+
+    // Build a helpful context-aware param hint.
+    let contextualHint = route.paramHint;
+    if (context?.designId) {
+      contextualHint += `  Current designId: "${context.designId}".`;
+    }
+    if (context?.fileId) {
+      contextualHint += `  Current fileId: "${context.fileId}".`;
+    }
+    if (context?.nodeId ?? context?.selector) {
+      const target = context.nodeId
+        ? `nodeId="${context.nodeId}"`
+        : `selector="${context.selector}"`;
+      contextualHint += `  Current target: ${target}.`;
+    }
+    if (context?.ownerId) {
+      contextualHint += `  Current ownerId: "${context.ownerId}".`;
+    }
+
+    return {
+      ok: true,
+      extensionId,
+      capabilityId,
+      route: {
+        action: route.action,
+        paramHint: contextualHint,
+        readOnly: route.readOnly,
+        gated: route.gated ?? false,
+        gateReason: route.gateReason ?? null,
+      },
+      nextStep: route.gated
+        ? `NOTE: This capability is gated.  ${route.gateReason ?? ""}  The underlying action will return a clear gated result; do not imply the operation will succeed.`
+        : `Call the action "${route.action}" with the params described in paramHint.`,
+      slotId: "design.editor.inspector",
+    };
+  },
+});

package/corpus/templates/design/actions/set-active-breakpoint.ts

@@ -0,0 +1,39 @@
+import { defineAction } from "@agent-native/core";
+import { writeAppState } from "@agent-native/core/application-state";
+import { assertAccess } from "@agent-native/core/sharing";
+import { z } from "zod";
+
+import "../server/db/index.js"; // ensure registerShareableResource runs
+
+export default defineAction({
+  description:
+    "Set the active breakpoint for a design editor session. " +
+    "The active breakpoint controls which frame is the current edit scope: " +
+    "editing a layer while 'base' is active writes unprefixed Tailwind classes; " +
+    "editing while 'md' is active writes md: prefixed classes. " +
+    "Persists to application state so the agent and UI always agree on the active scope.",
+  schema: z.object({
+    designId: z.string().describe("Design project ID"),
+    breakpointId: z
+      .string()
+      .describe(
+        "Id of the BreakpointDefinition to activate, or the literal string 'auto' " +
+          "to reset to a single-frame (all-breakpoints) view.",
+      ),
+  }),
+  run: async ({ designId, breakpointId }) => {
+    await assertAccess("design", designId, "editor");
+
+    // Persist as application state so view-screen returns it and the UI reflects it.
+    await writeAppState(`design-active-breakpoint:${designId}`, {
+      designId,
+      activeBreakpointId: breakpointId,
+      setAt: new Date().toISOString(),
+    });
+
+    return {
+      designId,
+      activeBreakpointId: breakpointId,
+    };
+  },
+});

package/corpus/templates/design/actions/view-screen.ts

@@ -20,9 +20,82 @@ import { getDb, schema } from "../server/db/index.js";
 import { parseCanvasFrameGeometryById } from "../shared/canvas-frames.js";
 import { designGenerationSessionKey } from "../shared/generation-session.js";
 
+function stringProp(value: unknown, key: string): string | undefined {
+  if (!value || typeof value !== "object") return undefined;
+  const candidate = (value as Record<string, unknown>)[key];
+  return typeof candidate === "string" ? candidate : undefined;
+}
+
+function stringArrayProp(value: unknown, key: string): string[] {
+  if (!value || typeof value !== "object") return [];
+  const candidate = (value as Record<string, unknown>)[key];
+  return Array.isArray(candidate)
+    ? candidate.filter((item): item is string => typeof item === "string")
+    : [];
+}
+
+function resolveActiveScreen(
+  files: Array<{
+    id: string;
+    filename: string;
+    fileType: string | null;
+    updatedAt: string | null;
+  }>,
+  navigation: unknown,
+  designSelection: unknown,
+) {
+  const selectionFileId = stringProp(designSelection, "activeFileId");
+  if (selectionFileId) {
+    const active = files.find((file) => file.id === selectionFileId);
+    if (active) return active;
+  }
+
+  const selectionFilename = stringProp(designSelection, "activeFilename");
+  if (selectionFilename) {
+    const active = files.find((file) => file.filename === selectionFilename);
+    if (active) return active;
+  }
+
+  const selectedScreenIds = stringArrayProp(
+    designSelection,
+    "selectedScreenIds",
+  );
+  for (const screenId of selectedScreenIds) {
+    const selected = files.find((file) => file.id === screenId);
+    if (selected) return selected;
+  }
+
+  const navigationTargets = [
+    stringProp(navigation, "fileId"),
+    stringProp(navigation, "screenId"),
+    stringProp(navigation, "filename"),
+    stringProp(navigation, "screen"),
+  ].filter((value): value is string => !!value);
+  for (const target of navigationTargets) {
+    const active = files.find(
+      (file) =>
+        file.id === target ||
+        file.filename === target ||
+        file.filename.replace(/\.[^.]+$/, "") === target,
+    );
+    if (active) return active;
+  }
+
+  const view = stringProp(navigation, "view");
+  const editorView =
+    stringProp(navigation, "editorView") ?? stringProp(navigation, "viewMode");
+  if (view === "present" || (view === "editor" && editorView === "single")) {
+    return (
+      files.find((file) => file.filename === "index.html") ?? files[0] ?? null
+    );
+  }
+
+  return null;
+}
+
 export default defineAction({
   description:
-    "See what the user is currently looking at on screen. Returns the current navigation state including which design is open, which view they are on (list, editor, design-systems, present, templates, settings), active/focused design screen, selected element, active inspector tab (design, tweaks, or extensions), overview canvas state, plus any pending question overlay or variant grid. Always call this first before taking any action.",
+    "See what the user is currently looking at on screen. Returns the current navigation state including which design is open, which view they are on (list, editor, design-systems, present, templates, settings), active/focused design screen, selected element, active inspector tab (design, tweaks, or extensions), overview canvas state, plus any pending question overlay. Always call this first before taking any action.",
   schema: z.object({}),
   http: false,
   run: async () => {
@@ -43,14 +116,6 @@ export default defineAction({
     const generationSession = designId
       ? await readAppState(designGenerationSessionKey(designId))
       : undefined;
-    const designVariants = designId
-      ? await readAppState("design-variants").then((value) => {
-          if (!value || typeof value !== "object") return undefined;
-          return (value as { designId?: unknown }).designId === designId
-            ? value
-            : undefined;
-        })
-      : undefined;
 
     const screen: Record<string, unknown> = {};
     if (navigation) screen.navigation = navigation;
@@ -84,27 +149,11 @@ export default defineAction({
             data = {};
           }
         }
-        const activeFileId =
-          designSelection &&
-          typeof designSelection === "object" &&
-          typeof (designSelection as { activeFileId?: unknown })
-            .activeFileId === "string"
-            ? (designSelection as { activeFileId: string }).activeFileId
-            : undefined;
-        const activeFilename =
-          designSelection &&
-          typeof designSelection === "object" &&
-          typeof (designSelection as { activeFilename?: unknown })
-            .activeFilename === "string"
-            ? (designSelection as { activeFilename: string }).activeFilename
-            : undefined;
         screen.design = {
           id: designId,
           title: (access.resource as { title?: unknown }).title ?? null,
           screens: files,
-          activeScreen: activeFileId
-            ? (files.find((file) => file.id === activeFileId) ?? null)
-            : (files.find((file) => file.filename === activeFilename) ?? null),
+          activeScreen: resolveActiveScreen(files, navigation, designSelection),
           canvasFrames: parseCanvasFrameGeometryById(data.canvasFrames),
         };
       }
@@ -114,11 +163,6 @@ export default defineAction({
       screen.note =
         "Questions are visible to the user as a full-canvas overlay. Wait for their answers (they'll come back as a chat message) before generating.";
     }
-    if (designVariants) {
-      screen.pendingVariants = designVariants;
-      screen.variantsNote =
-        'A variant picker is open. Wait for the user to choose a direction before generating further. In an inline MCP app their pick returns to you automatically; if it opened as a browser tab (a CLI or code editor), they paste an auto-copied summary or just tell you which one (e.g. "use variant A"). Once you know the choice, read the saved index.html with get-design-snapshot. Do not call generate-design while this picker is open.';
-    }
     if (generationSession) {
       const GENERATION_SESSION_TTL_MS = 10 * 60 * 1000; // 10 minutes
       const startedAt =