@agent-native/core 0.80.10 → 0.81.0

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

@@ -32,7 +32,11 @@ 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, extractProps } from "../shared/component-model.js";
+import {
+  componentNameFor,
+  componentNodeIdMatches,
+  extractProps,
+} from "../shared/component-model.js";
 import { normalizeDesignSourceType } from "../shared/source-mode.js";
 
 // ─── Helpers ──────────────────────────────────────────────────────────────────
@@ -62,7 +66,15 @@ async function liveContent(
 export interface ComponentPropPreviewMessage {
   /** Matches the existing parent→iframe postMessage type vocabulary. */
   type: "style-change" | "replace-document-content" | "select-element";
-  payload: Record<string, unknown>;
+  selector?: string;
+  nodeId?: string;
+  attributeOverrides?: Record<string, string>;
+  classEdit?: {
+    kind: "class";
+    operation: "replace";
+    from: string;
+    to: string;
+  };
 }
 
 // ─── Action ───────────────────────────────────────────────────────────────────
@@ -156,7 +168,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. Run get-code-layer-projection to list current ids.`,
@@ -182,35 +196,29 @@ export default defineAction({
       // attribute without a full HTML replace.
       messages.push({
         type: "style-change",
-        payload: {
-          selector: node.selector,
-          nodeId,
-          attributeOverrides: { "x-data": edit.value },
-        },
+        selector: node.selector,
+        nodeId,
+        attributeOverrides: { "x-data": edit.value },
       });
     } else if (edit.kind === "attribute") {
       messages.push({
         type: "style-change",
-        payload: {
-          selector: node.selector,
-          nodeId,
-          attributeOverrides: { [edit.attribute]: edit.value },
-        },
+        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",
-        payload: {
-          selector: node.selector,
-          nodeId,
-          classEdit: {
-            kind: "class",
-            operation: "replace",
-            from: edit.from,
-            to: edit.to,
-          },
+        selector: node.selector,
+        nodeId,
+        classEdit: {
+          kind: "class",
+          operation: "replace",
+          from: edit.from,
+          to: edit.to,
         },
       });
     }
@@ -218,10 +226,8 @@ export default defineAction({
     // Also emit a select-element message so the canvas highlights the node.
     messages.push({
       type: "select-element",
-      payload: {
-        selector: node.selector,
-        nodeId,
-      },
+      selector: node.selector,
+      nodeId,
     });
 
     const sourceType =

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

@@ -2,8 +2,8 @@
  * 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 bridge (`tweak-values` /
- * `style-change` messages) **without persisting anything**.
+ * can apply it to the selected node via the `shader-fill-preview` bridge
+ * message **without persisting anything**.
  *
  * Deliberately lightweight:
  * - No DB access.
@@ -84,11 +84,11 @@ export default defineAction({
 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 bridge style-change or tweak-values).
+- 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 style-change message.
+- 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.
 
@@ -139,14 +139,12 @@ support; it has no effect on the static CSS preview output today.
     const fallbackBlock = buildShaderFillFallbackBlock(selector, descriptor);
 
     // Build a ready-to-post bridge payload for the iframe.
-    // The `style-change` message type is already handled by DesignCanvas.tsx.
+    // The `shader-fill-preview` message type is handled by DesignCanvas.tsx.
     const bridgeMessage = {
-      type: "style-change",
-      nodeId: target?.nodeId ?? null,
+      type: "shader-fill-preview",
       selector: target?.selector ?? null,
-      styles: {
-        background: previewCss,
-      },
+      nodeId: target?.nodeId ?? null,
+      css: previewCss,
       // Metadata so the client can attach a "preview only" badge.
       _preview: true,
       _source: "shader-fill",
@@ -167,7 +165,7 @@ support; it has no effect on the static CSS preview output today.
       JSON.stringify(bridgeMessage, null, 2),
       ``,
       `Apply steps:`,
-      `1. Inject the previewCss via a bridge "style-change" message (no write, no persist).`,
+      `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.`,

package/corpus/templates/design/actions/provider-api-catalog.ts

@@ -10,7 +10,7 @@ const ProviderSchema = z.enum(DESIGN_PROVIDER_API_IDS);
 
 export default defineAction({
   description:
-    "List raw HTTP API capabilities for Design-connected providers. Use before provider-api-request when design-token import convenience actions are too narrow. Returns provider base URLs, auth style, credential key names, docs/spec URLs, placeholders, and examples; never returns secret values.",
+    "List raw HTTP API capabilities for Design-connected providers such as GitHub and Figma. Use before provider-api-request when design-token, repository, or Figma-library convenience actions are too narrow. Returns provider base URLs, auth style, credential key names, docs/spec URLs, placeholders, and examples; never returns secret values.",
   schema: z.object({
     provider: ProviderSchema.optional().describe(
       "Optional provider id to inspect. Omit to list every Design provider API escape hatch.",
@@ -22,7 +22,7 @@ export default defineAction({
     return {
       providers: await listProviderApiCatalog(provider),
       guidance:
-        "Design actions like import-github are workflow shortcuts, not capability limits. When the GitHub API can answer the question with a better endpoint, query, body, pagination mode, metadata field, or API version, inspect docs/spec URLs and call provider-api-request directly. GitHub auth uses the saved GITHUB_TOKEN secret and never exposes the token value.",
+        "Design actions like import-github and list-figma-library-assets are workflow shortcuts, not capability limits. When GitHub or Figma can answer the question with a better endpoint, query, body, pagination mode, metadata field, or API version, inspect docs/spec URLs and call provider-api-request directly. Auth uses saved scoped secrets such as GITHUB_TOKEN or FIGMA_ACCESS_TOKEN and never exposes token values.",
     };
   },
 });

package/corpus/templates/design/actions/provider-api-docs.ts

@@ -25,7 +25,7 @@ const WebContentSearchSchema = z.object({
 
 export default defineAction({
   description:
-    "Inspect provider API docs/spec metadata, or fetch any public API documentation page, OpenAPI spec, changelog, or web page. Use this before provider-api-request when the exact GitHub endpoint, payload shape, pagination, or API version is uncertain.",
+    "Inspect provider API docs/spec metadata, or fetch any public API documentation page, OpenAPI spec, changelog, or web page. Use this before provider-api-request when the exact GitHub/Figma endpoint, payload shape, pagination, or API version is uncertain.",
   schema: z.object({
     provider: ProviderSchema.describe(
       "Provider whose API docs/spec to inspect.",

package/corpus/templates/design/actions/provider-api-request.ts

@@ -71,8 +71,8 @@ const PaginationSchema = z
 export default defineAction({
   description:
     "Make an arbitrary authenticated HTTP request to a Design-connected provider API. " +
-    "Use this as the flexible escape hatch when a convenience action cannot express the needed GitHub endpoint, file tree query, issue/search query, request body, pagination mode, payload shape, or API version. " +
-    "The request is constrained to the provider host, uses the saved GITHUB_TOKEN automatically, blocks private/internal URLs, and redacts secrets from responses. " +
+    "Use this as the flexible escape hatch when a convenience action cannot express the needed GitHub endpoint, Figma file/library endpoint, request body, pagination mode, payload shape, or API version. " +
+    "The request is constrained to the provider host, uses saved scoped credentials such as GITHUB_TOKEN or FIGMA_ACCESS_TOKEN automatically, blocks private/internal URLs, and redacts secrets from responses. " +
     "\n\nSTAGING MODE (preferred for large responses): Pass stageAs to write response items into a scratch dataset instead of returning the raw body. " +
     "Returns { dataset, rowCount, columns, sampleRows } so only a compact summary enters context. Use query-staged-dataset to aggregate, filter, and project the data without re-fetching. " +
     "\n\nPAGINATION: When stageAs is set, pass pagination config to fetch all pages server-side into the same dataset. For GitHub page pagination, use pageParam='page', pageSize from per_page, and itemsPath when the response object contains an items array.",
@@ -83,7 +83,7 @@ export default defineAction({
       .string()
       .min(1)
       .describe(
-        "Provider API path such as /repos/{owner}/{repo}/contents/{path}, /search/code, /issues, or a full URL on an allowed provider host. Use placeholders from provider-api-catalog when provided.",
+        "Provider API path such as /repos/{owner}/{repo}/contents/{path}, /search/code, /files/{fileKey}/components, /images/{fileKey}, or a full URL on an allowed provider host. Use placeholders from provider-api-catalog when provided.",
       ),
     query: z
       .unknown()

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

@@ -0,0 +1,48 @@
+import { defineAction } from "@agent-native/core";
+import { getRequestUserEmail } from "@agent-native/core/server/request-context";
+import { assertAccess } from "@agent-native/core/sharing";
+import { and, eq } from "drizzle-orm";
+import { z } from "zod";
+
+import { getDb, schema } from "../server/db/index.js";
+
+export default defineAction({
+  description:
+    "Revoke a previously granted localhost write-consent for a design + connection. " +
+    "After revocation the agent can no longer write local files until the user re-grants consent. " +
+    "Requires editor access on the design.",
+  schema: z.object({
+    designId: z.string().describe("Design ID."),
+    connectionId: z
+      .string()
+      .describe("Localhost connection ID whose grant should be revoked."),
+  }),
+  run: async ({ designId, connectionId }) => {
+    await assertAccess("design", designId, "editor");
+
+    const ownerEmail = getRequestUserEmail();
+    if (!ownerEmail) throw new Error("no authenticated user");
+
+    const db = getDb();
+
+    const deleted = await db
+      .delete(schema.designLocalhostWriteGrants)
+      .where(
+        and(
+          eq(schema.designLocalhostWriteGrants.designId, designId),
+          eq(schema.designLocalhostWriteGrants.connectionId, connectionId),
+          eq(schema.designLocalhostWriteGrants.ownerEmail, ownerEmail),
+        ),
+      );
+
+    // `deleted` shape varies by dialect; check rows affected via the object.
+    const rowsAffected =
+      (deleted as unknown as { rowsAffected?: number })?.rowsAffected ?? 0;
+
+    return {
+      designId,
+      connectionId,
+      revoked: rowsAffected > 0,
+    };
+  },
+});

package/corpus/templates/design/actions/run-design-audit.ts

@@ -108,6 +108,8 @@ function checkMissingLabels(html: string): A11yFinding[] {
   let idx = 0;
   for (const m of html.matchAll(inputPattern)) {
     const tag = m[0];
+    const inputStart = m.index ?? 0;
+    const inputEnd = inputStart + tag.length;
     const typeMatch = tag.match(/\btype\s*=\s*(?:"([^"]*?)"|'([^']*?)')/i);
     const type = (typeMatch?.[1] ?? typeMatch?.[2] ?? "text").toLowerCase();
     // Hidden and submit/button/image inputs don't need visible labels
@@ -123,8 +125,9 @@ function checkMissingLabels(html: string): A11yFinding[] {
     const hasExplicitLabel = inputId
       ? new RegExp(`for\\s*=\\s*(?:"${inputId}"|'${inputId}')`, "i").test(html)
       : false;
+    const hasImplicitLabel = isWrappedByLabel(html, inputStart, inputEnd);
 
-    if (!hasAriaLabel && !hasExplicitLabel) {
+    if (!hasAriaLabel && !hasExplicitLabel && !hasImplicitLabel) {
       findings.push({
         id: `missing-label:input-${idx}`,
         severity: "error" as A11ySeverity,
@@ -143,8 +146,53 @@ function checkMissingLabels(html: string): A11yFinding[] {
   return findings;
 }
 
-/** Check interactive elements that are likely too small for touch targets (< ~44px heuristic via Tailwind class). */
-function checkTapTargets(html: string): A11yFinding[] {
+function isWrappedByLabel(
+  html: string,
+  inputStart: number,
+  inputEnd: number,
+): boolean {
+  const labelOpen = html.lastIndexOf("<label", inputStart);
+  if (labelOpen === -1) return false;
+  const labelCloseBeforeInput = html.lastIndexOf("</label", inputStart);
+  if (labelCloseBeforeInput > labelOpen) return false;
+  const labelCloseAfterInput = html.indexOf("</label", inputEnd);
+  return labelCloseAfterInput !== -1;
+}
+
+/**
+ * Whether an interactive element already declares a minimum size that meets the
+ * 44px tap-target floor. This recognises exactly what the inline auto-fix adds
+ * (`min-h-[44px] min-w-[44px]`) plus equivalents — arbitrary `min-h`/`min-w`
+ * values in px/rem/em ≥ 44px, the Tailwind spacing scale (`min-h-11` = 44px on a
+ * 4px step), and full-bleed minimums (`min-h-full` / `min-h-screen`). Without
+ * this, a fixed element keeps its original tiny `h-4` class and the audit would
+ * re-flag it forever, so the audit↔fix loop would never converge.
+ */
+function hasAdequateMinTapSize(tag: string): boolean {
+  // Arbitrary values: min-h-[44px], min-w-[2.75rem], etc.
+  const arbitraryPattern = /\bmin-(?:h|w)-\[([\d.]+)(px|rem|em)\]/gi;
+  let m: RegExpExecArray | null;
+  while ((m = arbitraryPattern.exec(tag)) !== null) {
+    const value = Number.parseFloat(m[1] ?? "");
+    if (!Number.isFinite(value)) continue;
+    const px = m[2]?.toLowerCase() === "px" ? value : value * 16;
+    if (px >= 44) return true;
+  }
+  // Tailwind spacing scale: min-h-11 / min-w-11 = 2.75rem = 44px (4px per step).
+  const scalePattern = /\bmin-(?:h|w)-(\d+)\b/gi;
+  while ((m = scalePattern.exec(tag)) !== null) {
+    if (Number.parseInt(m[1] ?? "", 10) * 4 >= 44) return true;
+  }
+  // Full-bleed minimums always clear the tap floor.
+  return /\bmin-(?:h|w)-(?:full|screen)\b/.test(tag);
+}
+
+/**
+ * Check interactive elements that are likely too small for touch targets
+ * (< ~44px heuristic via Tailwind class). Exported for unit tests that assert
+ * the audit↔fix loop converges (a fixed element must stop being flagged).
+ */
+export function checkTapTargets(html: string): A11yFinding[] {
   const findings: A11yFinding[] = [];
   // Heuristic: buttons/links with explicit tiny size classes (h-4, h-5, w-4, w-5, size-4, size-5)
   // and no explicit larger override or sr-only are flagged.
@@ -158,7 +206,8 @@ function checkTapTargets(html: string): A11yFinding[] {
     if (
       tinyPattern.test(tag) &&
       !largePattern.test(tag) &&
-      !srOnlyPattern.test(tag)
+      !srOnlyPattern.test(tag) &&
+      !hasAdequateMinTapSize(tag)
     ) {
       findings.push({
         id: `tap-target:interactive-${idx}`,
@@ -170,7 +219,7 @@ function checkTapTargets(html: string): A11yFinding[] {
         nodeId: extractNodeId(tag),
         selector: extractSelector(tag, "button"),
         wcag: "2.5.5",
-        fixAvailable: false,
+        fixAvailable: true,
       });
     }
     idx++;
@@ -272,7 +321,7 @@ function checkFocusVisibility(html: string): A11yFinding[] {
         nodeId: extractNodeId(tag),
         selector: extractSelector(tag, tag.match(/^<([a-z]+)/i)?.[1] ?? "*"),
         wcag: "2.4.7",
-        fixAvailable: false,
+        fixAvailable: true,
       });
     }
     inlineIdx++;
@@ -286,10 +335,23 @@ function checkContrastHint(html: string): A11yFinding[] {
   // Static analysis cannot compute real contrast ratios without a DOM/CSS
   // cascade resolver. We flag the presence of explicit low-opacity text colors
   // as a human-review hint — the UI will show these as "info" prompts.
-  const lowOpacityTextPattern =
-    /class\s*=\s*"[^"]*\btext-(?:white|black|gray-\d+)\s+(?:opacity-[0-3]\d|text-opacity-[0-3]\d)[^"]*"/gi;
+  const tagPattern = /<([a-z][a-z0-9:-]*)\b[^>]*>/gi;
+  const textColorPattern = /\btext-(?:white|black|gray-\d+)\b/i;
+  const lowOpacityPattern = /\b(?:opacity-[0-3]\d|text-opacity-[0-3]\d)\b/i;
   let idx = 0;
-  for (const m of html.matchAll(lowOpacityTextPattern)) {
+  for (const m of html.matchAll(tagPattern)) {
+    const tag = m[0];
+    const classMatch = tag.match(/\bclass\s*=\s*(?:"([^"]*?)"|'([^']*?)')/i);
+    const className = classMatch?.[1] ?? classMatch?.[2] ?? "";
+    if (
+      !textColorPattern.test(className) ||
+      !lowOpacityPattern.test(className)
+    ) {
+      continue;
+    }
+    const tagName = m[1] ?? "*";
+    const nodeId = extractNodeId(tag);
+    const selector = extractSelector(tag, tagName);
     findings.push({
       id: `contrast:low-opacity-${idx}`,
       severity: "info" as A11ySeverity,
@@ -298,6 +360,8 @@ function checkContrastHint(html: string): A11yFinding[] {
         "Text element has a low-opacity modifier — verify contrast ratio meets 4.5:1 minimum.",
       detail:
         "Low-opacity text can fail WCAG 1.4.3. Run a live contrast check in the browser.",
+      nodeId,
+      selector,
       wcag: "1.4.3",
       fixAvailable: false,
     });
@@ -353,7 +417,7 @@ export default defineAction({
       ),
   }),
   readOnly: true,
-  http: { method: "GET" },
+  http: { method: "POST" },
   run: async ({ designId, fileId, filename }) => {
     const db = getDb();
 

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

@@ -146,7 +146,7 @@ const CAPABILITY_ROUTES: Record<string, CapabilityRoute> = {
   "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.",
+      "Call apply-motion-edit with { designId, fileId?, timeline: { tracks, durationMs } } for an atomic managed CSS timeline save.",
     readOnly: false,
   },
   "design.motion-presets:write-source": {

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

@@ -95,7 +95,7 @@ function resolveActiveScreen(
 
 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. 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 or tweaks), active left rail panel (file, agent, assets, tools, or tokens), overview canvas state, plus any pending question overlay. Always call this first before taking any action.",
   schema: z.object({}),
   http: false,
   run: async () => {

package/corpus/templates/design/actions/write-local-file.ts

@@ -0,0 +1,213 @@
+/**
+ * write-local-file — write or patch a local file through the design bridge.
+ *
+ * Security gates (in order):
+ *  1. assertAccess: the caller must have editor access to the design.
+ *  2. File extension: only .html, .htm, and .css files are allowed.
+ *  3. verifyWriteGrant: a valid (non-expired) user-approved write-consent grant
+ *     must exist. The agent CANNOT bypass this check.
+ *  4. Path confinement: assertPathInside ensures the target stays inside
+ *     rootPath (pre-bridge check; bridge also validates with realpath).
+ *  5. Bridge token: the X-Bridge-Token header is set to the per-grant token
+ *     minted at consent time so the bridge can reject unauthorized calls.
+ */
+
+import path from "node:path";
+
+import { defineAction } from "@agent-native/core";
+import { getRequestUserEmail } from "@agent-native/core/server/request-context";
+import { 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 { verifyWriteGrant } from "../server/lib/verify-write-grant.js";
+
+/** File extensions the agent is permitted to write via the bridge. */
+const ALLOWED_EXTENSIONS = new Set([".html", ".htm", ".css"]);
+
+function assertAllowedExtension(relPath: string): void {
+  const ext = path.extname(relPath).toLowerCase();
+  if (!ALLOWED_EXTENSIONS.has(ext)) {
+    throw new Error(
+      `File "${relPath}" has extension "${ext}" which is not allowed. ` +
+        "Only .html, .htm, and .css files may be written through the bridge.",
+    );
+  }
+}
+
+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 parsed = new URL(value.trim());
+  if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+    throw new Error("bridgeUrl must be an http(s) URL");
+  }
+  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:
+    "Write or patch a local file (HTML or CSS only) via the localhost design bridge. " +
+    "The user MUST have already granted write consent via grant-localhost-write-consent; " +
+    "this action will reject the request if no valid grant exists. " +
+    "Pass content for a full file write, or {search, replace} for a targeted patch. " +
+    "Requires editor access on the design.",
+  schema: z.object({
+    designId: z.string().describe("Design ID."),
+    connectionId: z
+      .string()
+      .describe("Localhost connection ID (must have an active write grant)."),
+    relPath: z
+      .string()
+      .describe(
+        "Path to the file relative to the connection rootPath. " +
+          "Only .html, .htm, and .css files are accepted.",
+      ),
+    content: z
+      .string()
+      .optional()
+      .describe(
+        "Full replacement file content. Use for new files or complete rewrites.",
+      ),
+    patch: z
+      .object({
+        search: z
+          .string()
+          .describe("Exact text to search for (must appear exactly once)."),
+        replace: z.string().describe("Replacement text."),
+      })
+      .optional()
+      .describe(
+        "Search-and-replace patch. Use for targeted edits. " +
+          "Mutually exclusive with content.",
+      ),
+  }),
+  run: async ({ designId, connectionId, relPath, content, patch }) => {
+    // --- Gate 1: access ---
+    await assertAccess("design", designId, "editor");
+
+    const ownerEmail = getRequestUserEmail();
+    if (!ownerEmail) throw new Error("no authenticated user");
+
+    // --- Gate 2: extension whitelist ---
+    assertAllowedExtension(relPath);
+
+    // --- Gate 3: valid write-consent grant ---
+    const grant = await verifyWriteGrant({
+      designId,
+      connectionId,
+      ownerEmail,
+      targetPath: relPath,
+    });
+
+    // --- Gate 4: exactly one of content/patch must be provided ---
+    if (content === undefined && patch === undefined) {
+      throw new Error(
+        "Either content (full file write) or patch (search/replace) must be provided.",
+      );
+    }
+    if (content !== undefined && patch !== undefined) {
+      throw new Error(
+        "content and patch are mutually exclusive. Provide one or the other.",
+      );
+    }
+
+    // --- Resolve bridge URL ---
+    const db = getDb();
+    const [connection] = await db
+      .select({ bridgeUrl: schema.designLocalhostConnections.bridgeUrl })
+      .from(schema.designLocalhostConnections)
+      .where(
+        and(
+          eq(schema.designLocalhostConnections.id, connectionId),
+          eq(schema.designLocalhostConnections.ownerEmail, ownerEmail),
+        ),
+      )
+      .limit(1);
+
+    if (!connection?.bridgeUrl) {
+      throw new Error(
+        `No bridge URL found for connection "${connectionId}". ` +
+          "Ensure the design bridge is running (npx @agent-native/core@latest design connect).",
+      );
+    }
+
+    const bridgeUrl = normalizeBridgeUrl(connection.bridgeUrl);
+    const headers: Record<string, string> = {
+      "Content-Type": "application/json",
+      "X-Bridge-Token": grant.bridgeToken,
+    };
+
+    if (content !== undefined) {
+      // Full file write
+      const res = await fetch(`${bridgeUrl}/write-file`, {
+        method: "POST",
+        headers,
+        body: JSON.stringify({ relPath, content }),
+      });
+      if (!res.ok) {
+        const errText = await res.text().catch(() => res.statusText);
+        throw new Error(`Bridge write-file failed (${res.status}): ${errText}`);
+      }
+      return { designId, relPath, operation: "write" as const, written: true };
+    } else {
+      // Search-and-replace patch — first read, then apply-edit
+      const readRes = await fetch(`${bridgeUrl}/read-file`, {
+        method: "POST",
+        headers,
+        body: JSON.stringify({ relPath }),
+      });
+      if (!readRes.ok) {
+        const errText = await readRes.text().catch(() => readRes.statusText);
+        throw new Error(
+          `Bridge read-file failed (${readRes.status}): ${errText}`,
+        );
+      }
+
+      const applyRes = await fetch(`${bridgeUrl}/apply-edit`, {
+        method: "POST",
+        headers,
+        body: JSON.stringify({
+          relPath,
+          search: patch!.search,
+          replace: patch!.replace,
+        }),
+      });
+      if (!applyRes.ok) {
+        const errText = await applyRes.text().catch(() => applyRes.statusText);
+        throw new Error(
+          `Bridge apply-edit failed (${applyRes.status}): ${errText}`,
+        );
+      }
+      return { designId, relPath, operation: "patch" as const, written: true };
+    }
+  },
+});