@agent-native/core 0.80.10 → 0.81.0

package/corpus/templates/design/actions/connect-localhost.ts

@@ -41,6 +41,41 @@ function normalizeUrl(value: string, label: string): string {
   return parsed.toString().replace(/\/$/, "");
 }
 
+function isLoopbackHostname(hostname: string): boolean {
+  const normalized = hostname.toLowerCase();
+  if (
+    normalized === "localhost" ||
+    normalized === "::1" ||
+    normalized === "[::1]"
+  ) {
+    return true;
+  }
+  const parts = normalized.split(".");
+  return (
+    parts.length === 4 &&
+    parts[0] === "127" &&
+    parts.every((part) => /^\d+$/.test(part) && Number(part) <= 255)
+  );
+}
+
+function normalizeBridgeUrl(value: string): string {
+  const normalized = normalizeUrl(value, "bridgeUrl");
+  const parsed = new URL(normalized);
+  if (parsed.username || parsed.password) {
+    throw new Error("bridgeUrl must not include credentials");
+  }
+  if (parsed.pathname !== "/" && parsed.pathname !== "") {
+    throw new Error("bridgeUrl must not include a path");
+  }
+  if (!isLoopbackHostname(parsed.hostname)) {
+    throw new Error("bridgeUrl must use localhost or a loopback IP address");
+  }
+  parsed.search = "";
+  parsed.hash = "";
+  parsed.pathname = "";
+  return parsed.toString().replace(/\/$/, "");
+}
+
 export default defineAction({
   description:
     "Register or refresh a localhost Design source connection produced by `agent-native design connect`. Stores the dev server URL, bridge URL, route manifest, and operation capabilities so the UI can later list local-code artboards.",
@@ -77,6 +112,12 @@ export default defineAction({
       .array(capabilitySchema)
       .optional()
       .describe("Bridge operation capabilities."),
+    bridgeToken: z
+      .string()
+      .optional()
+      .describe(
+        "The bridge's real auth token minted at bridge start. Stored on the connection so grant-localhost-write-consent can read it without minting its own.",
+      ),
     status: z
       .enum(["connected", "detected", "manual", "error"])
       .optional()
@@ -91,7 +132,7 @@ export default defineAction({
     const db = getDb();
     const devServerUrl = normalizeUrl(args.devServerUrl, "devServerUrl");
     const bridgeUrl = args.bridgeUrl
-      ? normalizeUrl(args.bridgeUrl, "bridgeUrl")
+      ? normalizeBridgeUrl(args.bridgeUrl)
       : undefined;
     const rawRoutes = args.routeManifest?.routes ?? args.routes ?? [];
     const routes = rawRoutes.map((route) => ({
@@ -115,18 +156,24 @@ export default defineAction({
       args.capabilities ??
       DESIGN_BRIDGE_OPERATIONS.map((operation) => ({
         operation,
-        status:
-          operation === "readFile" ||
-          operation === "applyEdit" ||
-          operation === "writeFile"
-            ? ("planned" as const)
-            : ("available" as const),
-        reason:
-          operation === "writeFile"
-            ? "Local file writes require the next bridge hardening pass."
-            : undefined,
+        status: "available" as const,
       }));
 
+    const existing = await db
+      .select({
+        id: schema.designLocalhostConnections.id,
+        bridgeToken: schema.designLocalhostConnections.bridgeToken,
+      })
+      .from(schema.designLocalhostConnections)
+      .where(
+        and(
+          eq(schema.designLocalhostConnections.id, id),
+          eq(schema.designLocalhostConnections.ownerEmail, ownerEmail),
+        ),
+      )
+      .limit(1);
+
+    const nextBridgeToken = args.bridgeToken?.trim() || undefined;
     const values = {
       id,
       name: args.name ?? new URL(devServerUrl).host,
@@ -136,6 +183,7 @@ export default defineAction({
       rootPath: routeManifest.rootPath ?? null,
       routeManifest: JSON.stringify(routeManifest),
       capabilities: JSON.stringify(capabilities),
+      bridgeToken: nextBridgeToken ?? existing[0]?.bridgeToken ?? null,
       status: args.status,
       lastSeenAt: now,
       ownerEmail,
@@ -143,17 +191,6 @@ export default defineAction({
       updatedAt: now,
     };
 
-    const existing = await db
-      .select({ id: schema.designLocalhostConnections.id })
-      .from(schema.designLocalhostConnections)
-      .where(
-        and(
-          eq(schema.designLocalhostConnections.id, id),
-          eq(schema.designLocalhostConnections.ownerEmail, ownerEmail),
-        ),
-      )
-      .limit(1);
-
     if (existing[0]) {
       await db
         .update(schema.designLocalhostConnections)

package/corpus/templates/design/actions/delete-design.ts

@@ -16,6 +16,26 @@ export default defineAction({
 
     const db = getDb();
 
+    await db
+      .delete(schema.designShares)
+      .where(eq(schema.designShares.resourceId, id));
+
+    await db
+      .delete(schema.componentIndex)
+      .where(eq(schema.componentIndex.designId, id));
+
+    await db
+      .delete(schema.motionTimeline)
+      .where(eq(schema.motionTimeline.designId, id));
+
+    await db
+      .delete(schema.designState)
+      .where(eq(schema.designState.designId, id));
+
+    await db
+      .delete(schema.designReviewSnapshot)
+      .where(eq(schema.designReviewSnapshot.designId, id));
+
     // Delete associated files first
     await db
       .delete(schema.designFiles)

package/corpus/templates/design/actions/export-zip.ts

@@ -10,6 +10,17 @@ import {
 } from "../server/lib/design-export.js";
 import "../server/db/index.js"; // ensure registerShareableResource runs
 
+const METADATA_ARCHIVE_DIR = "agent-native-metadata";
+
+function safeArchivePath(filename: string, fallback: string): string {
+  const normalized = filename
+    .replace(/\\/g, "/")
+    .split("/")
+    .filter((part) => part && part !== "." && part !== "..")
+    .join("/");
+  return normalized || fallback;
+}
+
 export default defineAction({
   description:
     "Export a design project as a ZIP file containing all design files and a README. " +
@@ -34,7 +45,8 @@ export default defineAction({
     const JSZip = (await import("jszip")).default;
     const zip = new JSZip();
 
-    // Add README
+    // Add generated metadata under a reserved folder so valid design files named
+    // README.md or design-data.json can still export at the project root.
     const readme = [
       `# ${row.title}`,
       "",
@@ -48,18 +60,21 @@ export default defineAction({
       ...files.map((f) => `- ${f.filename} (${f.fileType})`),
     ].join("\n");
 
-    zip.file("README.md", readme);
+    zip.file(`${METADATA_ARCHIVE_DIR}/README.md`, readme);
 
-    // Add all design files organized by type
-    for (const file of files) {
-      const folder =
-        file.fileType === "asset" ? "assets" : (file.fileType ?? "html");
-      zip.file(`${folder}/${file.filename}`, file.content ?? "");
+    // Preserve design-relative paths so exported HTML keeps working with
+    // sibling CSS/assets. Strip traversal segments defensively for legacy rows.
+    for (const [index, file] of files.entries()) {
+      const filename = safeArchivePath(
+        file.filename,
+        `design-file-${index + 1}.txt`,
+      );
+      zip.file(filename, file.content ?? "");
     }
 
     // Add design data if present
     if (row.data) {
-      zip.file("design-data.json", row.data);
+      zip.file(`${METADATA_ARCHIVE_DIR}/design-data.json`, row.data);
     }
 
     // Generate ZIP

package/corpus/templates/design/actions/generate-design.ts

@@ -66,7 +66,48 @@ async function updateGenerationSessionForSavedFiles(
   await writeAppState(key, nextSession as unknown as Record<string, unknown>);
 }
 
-export default defineAction({
+const generateDesignAgentParameters = {
+  type: "object",
+  properties: {
+    designId: {
+      type: "string",
+      description: "Existing design project ID to save generated content to.",
+    },
+    prompt: {
+      type: "string",
+      description: "The user's generation prompt.",
+    },
+    files: {
+      type: "string",
+      description:
+        "JSON array of files to save. Pass one compact, complete, renderable index.html first, e.g. " +
+        '[{"filename":"index.html","fileType":"html","content":"<!doctype html>..."}].',
+    },
+    designSystemId: {
+      type: ["string", "null"],
+      description:
+        "Optional design system ID used for generation. Pass null to unlink.",
+    },
+    projectType: {
+      type: "string",
+      enum: ["prototype", "other"],
+      description: "Optional project type hint.",
+    },
+    tweaks: {
+      type: "string",
+      description:
+        "Optional JSON array of tweak definitions. Omit unless the HTML uses matching CSS variables.",
+    },
+    canvasFrames: {
+      type: "string",
+      description:
+        "Optional JSON array of overview-canvas placements keyed by filename or fileId.",
+    },
+  },
+  required: ["designId", "prompt", "files"],
+} as const;
+
+const generateDesignAction = defineAction({
   description:
     "Save generated design content to a design project. " +
     "The agent calls this after generating HTML/CSS/JSX content to persist it " +
@@ -438,3 +479,14 @@ export default defineAction({
     };
   },
 });
+
+// Keep rich Zod validation for every runtime caller, but present a lean
+// string-JSON schema to native LLM tools. Anthropic models are prone to empty
+// object calls against this action's deeply nested array/object schema.
+export default {
+  ...generateDesignAction,
+  tool: {
+    ...generateDesignAction.tool,
+    parameters: generateDesignAgentParameters,
+  },
+};

package/corpus/templates/design/actions/get-component-details.ts

@@ -15,7 +15,6 @@
  */
 
 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";
@@ -27,29 +26,13 @@ import { buildCodeLayerProjection } from "../shared/code-layer.js";
 import type { CodeLayerSource } from "../shared/code-layer.js";
 import {
   componentNameFor,
+  componentNodeIdMatches,
   extractProps,
   type ComponentInstance,
 } from "../shared/component-model.js";
 import { hasCapability } from "../shared/design-source-capabilities.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;
-}
-
 function parseJson<T>(raw: string | null | undefined, fallback: T): T {
   if (!raw) return fallback;
   try {
@@ -112,6 +95,14 @@ export default defineAction({
     const caps = resolveSourceCapabilities(sourceType);
     const canResolveToFile = hasCapability(caps, "resolveNodeToFile");
     const hasFullIndex = hasCapability(caps, "indexComponents");
+    const canEditProps =
+      sourceType === "inline" || hasCapability(caps, "applyEdit");
+    const ctaRequired = !hasFullIndex || !canEditProps;
+    const ctaMessage = !hasFullIndex
+      ? "Full prop controls (TypeScript prop types, cva variants, Storybook stories) require a connected Builder app. Connect Builder to unlock."
+      : !canEditProps
+        ? "Prop write-back requires the bridge applyEdit capability. Preview controls remain available until source write hardening is enabled."
+        : undefined;
 
     // ── Fetch design file ────────────────────────────────────────────────────
     const conditions = [
@@ -139,7 +130,11 @@ export default defineAction({
 
     if (!file) throw new Error("Design HTML file not found.");
 
-    const html = await liveContent(file.id, file.content ?? "");
+    // Use the durable SQL source for component prop reads. A connected editor
+    // can briefly hold an older Yjs text snapshot while server-side prop writes
+    // have already updated SQL; preferring collab here makes the inspector
+    // rehydrate stale props even though the canvas renders the saved source.
+    const html = file.content ?? "";
 
     // ── Projection lookup ────────────────────────────────────────────────────
     const codeLayerSource: CodeLayerSource = {
@@ -153,7 +148,9 @@ export default defineAction({
       source: codeLayerSource,
     });
 
-    const node = projection.nodes.find((n) => n.id === nodeId);
+    const node = projection.nodes.find((n) =>
+      componentNodeIdMatches(n, nodeId),
+    );
     if (!node) {
       throw new Error(
         `Node "${nodeId}" not found in projection. Run get-code-layer-projection to list current node ids.`,
@@ -180,7 +177,7 @@ export default defineAction({
       props: observedProps,
       alpineData,
       selector: node.selector,
-      nodeId: node.id,
+      nodeId,
     };
 
     // ── Lookup persisted component_index row ─────────────────────────────────
@@ -231,11 +228,9 @@ export default defineAction({
       capabilities: {
         canResolveToFile,
         hasFullIndex,
-        canEditProps: true, // preview-only on inline; persists on real-app
-        ctaRequired: !hasFullIndex,
-        ctaMessage: !hasFullIndex
-          ? "Full prop controls (TypeScript prop types, cva variants, Storybook stories) require a connected Builder app. Connect Builder to unlock."
-          : undefined,
+        canEditProps,
+        ctaRequired,
+        ctaMessage,
       },
     };
   },

package/corpus/templates/design/actions/get-motion-timeline.ts

@@ -1,17 +1,109 @@
 import { defineAction } from "@agent-native/core";
+import { getText, hasCollabState } from "@agent-native/core/collab";
 import { accessFilter } from "@agent-native/core/sharing";
-import { and, eq } from "drizzle-orm";
+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
+import {
+  extractManagedMotionCss,
+  hashCss,
+  parse,
+} from "../shared/motion-compiler.js";
+import type { MotionTrack } from "../shared/motion-timeline.js";
+
+type TimelineSource = "stored" | "recovered-css" | "stored-css-drift";
+
+interface TimelineResult {
+  id: string | null;
+  designId: string;
+  sourceRef: string | null;
+  filePath: string | null;
+  tracks: unknown;
+  durationMs: number;
+  defaultEase: string;
+  compiledHash: string | null;
+  cssHash?: string | null;
+  source: TimelineSource;
+  createdAt: string | null;
+  updatedAt: string | null;
+}
+
+async function liveFileContent(
+  fileId: string,
+  storedContent: string,
+): Promise<string> {
+  try {
+    if (await hasCollabState(fileId)) {
+      const live = await getText(fileId, "content");
+      if (typeof live === "string") return live;
+    }
+  } catch {
+    // Best-effort; SQL is the fallback.
+  }
+  return storedContent;
+}
+
+function parseTrackJson(raw: string | null): MotionTrack[] {
+  try {
+    const parsed: unknown = JSON.parse(raw ?? "[]");
+    return Array.isArray(parsed) ? (parsed as MotionTrack[]) : [];
+  } catch {
+    return [];
+  }
+}
+
+async function readManagedCssForSource(args: {
+  designId: string;
+  sourceRef?: string;
+}): Promise<{ css: string; hash: string; tracks: MotionTrack[] } | null> {
+  if (!args.sourceRef) return null;
+
+  const db = getDb();
+  const [file] = await db
+    .select({
+      id: schema.designFiles.id,
+      content: schema.designFiles.content,
+    })
+    .from(schema.designFiles)
+    .innerJoin(
+      schema.designs,
+      eq(schema.designFiles.designId, schema.designs.id),
+    )
+    .where(
+      and(
+        accessFilter(schema.designs, schema.designShares),
+        eq(schema.designFiles.designId, args.designId),
+        eq(schema.designFiles.id, args.sourceRef),
+      ),
+    )
+    .limit(1);
+
+  if (!file) return null;
+
+  const content = await liveFileContent(file.id, file.content ?? "");
+  const css = extractManagedMotionCss(content);
+  if (!css) return null;
+
+  const tracks = parse(css).filter(
+    (track) =>
+      track.keyframes.length > 0 &&
+      track.keyframes.every((keyframe) => keyframe.value.trim().length > 0),
+  );
+  if (tracks.length === 0) return null;
+
+  return { css, hash: hashCss(css), tracks };
+}
 
 export default defineAction({
   description:
     "Read one or all motion timelines for a design. " +
     "Returns timeline metadata (id, sourceRef, filePath, durationMs, " +
     "defaultEase, compiledHash) and the full tracks array (each track has " +
-    "targetNodeId, property, and keyframes). Read-only.",
+    "targetNodeId, property, and keyframes). If sourceRef points at a design " +
+    "file and the metadata is missing or stale, recovers editable tracks from " +
+    "the managed <style data-agent-native-motion> block. Read-only.",
   readOnly: true,
   http: { method: "GET" },
   schema: z.object({
@@ -64,29 +156,62 @@ export default defineAction({
         eq(schema.motionTimeline.designId, schema.designs.id),
       )
       .where(and(...conditions))
+      .orderBy(desc(schema.motionTimeline.updatedAt))
       .limit(timelineId ? 1 : 100);
 
-    const timelines = rows.map((row) => {
-      let tracks: unknown = [];
-      try {
-        tracks = JSON.parse(row.tracks ?? "[]");
-      } catch {
-        tracks = [];
-      }
+    const timelines: TimelineResult[] = rows.map((row) => {
       return {
         id: row.id,
         designId: row.designId,
         sourceRef: row.sourceRef ?? null,
         filePath: row.filePath ?? null,
-        tracks,
+        tracks: parseTrackJson(row.tracks),
         durationMs: row.durationMs,
         defaultEase: row.defaultEase,
         compiledHash: row.compiledHash ?? null,
+        cssHash: null,
+        source: "stored",
         createdAt: row.createdAt,
         updatedAt: row.updatedAt,
       };
     });
 
+    const managedCss = timelineId
+      ? null
+      : await readManagedCssForSource({ designId, sourceRef });
+
+    if (managedCss) {
+      const [first] = timelines;
+      if (!first) {
+        timelines.push({
+          id: null,
+          designId,
+          sourceRef: sourceRef ?? null,
+          filePath: null,
+          tracks: managedCss.tracks,
+          durationMs: 1000,
+          defaultEase: "ease",
+          compiledHash: managedCss.hash,
+          cssHash: managedCss.hash,
+          source: "recovered-css",
+          createdAt: null,
+          updatedAt: null,
+        });
+      } else if (first.compiledHash !== managedCss.hash) {
+        timelines[0] = {
+          ...first,
+          tracks: managedCss.tracks,
+          cssHash: managedCss.hash,
+          source: "stored-css-drift",
+        };
+      } else {
+        timelines[0] = {
+          ...first,
+          cssHash: managedCss.hash,
+        };
+      }
+    }
+
     if (timelineId) {
       if (timelines.length === 0) {
         throw new Error(`Motion timeline not found: ${timelineId}`);

package/corpus/templates/design/actions/grant-localhost-write-consent.ts

@@ -0,0 +1,116 @@
+import { defineAction } from "@agent-native/core";
+import {
+  getRequestOrgId,
+  getRequestUserEmail,
+} from "@agent-native/core/server/request-context";
+import { assertAccess } from "@agent-native/core/sharing";
+import { and, eq } from "drizzle-orm";
+import { nanoid } from "nanoid";
+import { z } from "zod";
+
+import { getDb, schema } from "../server/db/index.js";
+
+/** Grant expiry: 8 hours from mint time. */
+const GRANT_TTL_MS = 8 * 60 * 60 * 1000;
+
+export default defineAction({
+  description:
+    "Record the user's explicit consent to allow the agent to write local files " +
+    "for a specific design + localhost connection. The grant scopes writes to the " +
+    "connection's rootPath and expires after 8 hours. Requires editor access on the design. " +
+    "The LocalhostWriteConsentDialog calls this after the user clicks 'Allow writes'.",
+  schema: z.object({
+    designId: z.string().describe("Design ID."),
+    connectionId: z
+      .string()
+      .describe("Localhost connection ID (from list-localhost-connections)."),
+  }),
+  run: async ({ designId, connectionId }) => {
+    await assertAccess("design", designId, "editor");
+
+    const ownerEmail = getRequestUserEmail();
+    if (!ownerEmail) throw new Error("no authenticated user");
+    const orgId = getRequestOrgId() ?? null;
+
+    const db = getDb();
+
+    // Fetch the connection to get rootPath and the real bridgeToken that the
+    // CLI registered when it started the bridge process.
+    const [connection] = await db
+      .select()
+      .from(schema.designLocalhostConnections)
+      .where(
+        and(
+          eq(schema.designLocalhostConnections.id, connectionId),
+          eq(schema.designLocalhostConnections.ownerEmail, ownerEmail),
+        ),
+      )
+      .limit(1);
+
+    if (!connection) {
+      throw new Error(
+        `Localhost connection "${connectionId}" not found for the current user.`,
+      );
+    }
+
+    const rootPath = connection.rootPath;
+    if (!rootPath) {
+      throw new Error(
+        `Connection "${connectionId}" has no rootPath. ` +
+          "Re-run `npx @agent-native/core@latest design connect` to record the root path.",
+      );
+    }
+
+    const bridgeToken = connection.bridgeToken;
+    if (!bridgeToken) {
+      throw new Error(
+        `Connection "${connectionId}" has no bridge token. ` +
+          "Re-run `npx @agent-native/core@latest design connect` so the CLI can register the real bridge token.",
+      );
+    }
+
+    const now = new Date();
+    const grantId = nanoid();
+    const grantedUntil = new Date(now.getTime() + GRANT_TTL_MS).toISOString();
+    const nowIso = now.toISOString();
+
+    // Upsert: if a grant already exists for this design+connection+user, replace it.
+    const [existing] = await db
+      .select({ id: schema.designLocalhostWriteGrants.id })
+      .from(schema.designLocalhostWriteGrants)
+      .where(
+        and(
+          eq(schema.designLocalhostWriteGrants.designId, designId),
+          eq(schema.designLocalhostWriteGrants.connectionId, connectionId),
+          eq(schema.designLocalhostWriteGrants.ownerEmail, ownerEmail),
+        ),
+      )
+      .limit(1);
+
+    if (existing) {
+      await db
+        .update(schema.designLocalhostWriteGrants)
+        .set({ bridgeToken, grantedUntil, rootPath })
+        .where(eq(schema.designLocalhostWriteGrants.id, existing.id));
+    } else {
+      await db.insert(schema.designLocalhostWriteGrants).values({
+        id: grantId,
+        designId,
+        connectionId,
+        rootPath,
+        bridgeToken,
+        grantedUntil,
+        ownerEmail,
+        orgId,
+        createdAt: nowIso,
+      });
+    }
+
+    return {
+      grantId: existing?.id ?? grantId,
+      bridgeToken,
+      rootPath,
+      grantedUntil,
+    };
+  },
+});