@agent-native/core 0.182.1 → 0.182.2-nightly-20260917225811

package/corpus/templates/design/actions/add-localhost-screens.ts

@@ -17,6 +17,7 @@ import {
 } from "../server/lib/design-data-mutation.js";
 import { snapshotDesignBeforeAgentEdit } from "../server/lib/design-versions.js";
 import { resolveLocalhostConnectionScope } from "../server/lib/localhost-connection.js";
+import { withDesignSourceMutationTransaction } from "../server/source-workspace.js";
 import {
   mergeCanvasFramePlacements,
   parseCanvasFrameGeometryById,
@@ -938,7 +939,7 @@ export default defineAction({
         )
           ? preferredExisting
           : undefined;
-      const existing =
+      let existing =
         matchingPreferredExisting ??
         routeCandidates.find((candidate) => {
           const frame = existingCanvasFrames[candidate.id];
@@ -997,27 +998,51 @@ export default defineAction({
       seenRouteRequestKeys.add(routeRequestKey);
 
       if (existing) {
-        await db
-          .update(schema.designFiles)
-          .set({ content: url, fileType: "html", updatedAt: now })
-          .where(eq(schema.designFiles.id, existing.id));
-        if (await hasCollabState(existing.id)) {
-          await applyText(existing.id, url, "content", "agent");
+        const updated = await withDesignSourceMutationTransaction(
+          designId,
+          async (tx) => {
+            const [current] = await tx
+              .select({ id: schema.designFiles.id })
+              .from(schema.designFiles)
+              .where(
+                and(
+                  eq(schema.designFiles.id, existing!.id),
+                  eq(schema.designFiles.designId, designId),
+                ),
+              )
+              .limit(1);
+            if (!current) return false;
+            await tx
+              .update(schema.designFiles)
+              .set({ content: url, fileType: "html", updatedAt: now })
+              .where(eq(schema.designFiles.id, existing!.id));
+            return true;
+          },
+        );
+        if (updated) {
+          if (await hasCollabState(existing.id)) {
+            await applyText(existing.id, url, "content", "agent");
+          } else {
+            await seedFromText(existing.id, url);
+          }
         } else {
-          await seedFromText(existing.id, url);
+          existing = undefined;
         }
-      } else {
+      }
+      if (!existing) {
         for (let attempt = 0; ; attempt += 1) {
           try {
-            await db.insert(schema.designFiles).values({
-              id: fileId,
-              designId,
-              filename,
-              fileType: "html",
-              content: url,
-              createdAt: now,
-              updatedAt: now,
-            });
+            await withDesignSourceMutationTransaction(designId, (tx) =>
+              tx.insert(schema.designFiles).values({
+                id: fileId,
+                designId,
+                filename,
+                fileType: "html",
+                content: url,
+                createdAt: now,
+                updatedAt: now,
+              }),
+            );
             await seedFromText(fileId, url);
             break;
           } catch (err) {
@@ -1048,10 +1073,17 @@ export default defineAction({
               routeUrlsMatch(winner.content, url)
             ) {
               fileId = winner.id;
-              await db
-                .update(schema.designFiles)
-                .set({ content: url, fileType: "html", updatedAt: now })
-                .where(eq(schema.designFiles.id, winner.id));
+              await withDesignSourceMutationTransaction(designId, (tx) =>
+                tx
+                  .update(schema.designFiles)
+                  .set({ content: url, fileType: "html", updatedAt: now })
+                  .where(
+                    and(
+                      eq(schema.designFiles.id, winner.id),
+                      eq(schema.designFiles.designId, designId),
+                    ),
+                  ),
+              );
               if (await hasCollabState(winner.id)) {
                 await applyText(winner.id, url, "content", "agent");
               } else {

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

@@ -12,12 +12,9 @@
  *                    HTML attribute on the component root.
  * - `classReplace` — replaces one Tailwind class with another on the root node.
  *
- * **Real-app sources (localhost / fusion):** deliberately fail closed. This
- * action's patcher operates on SQL-backed HTML design files; it must never be
- * reused for compiled JSX/TSX source. Real-app prop persistence needs a
- * dedicated consented, version-guarded bridge transform. Until that exists,
- * callers may preview but this action returns `ctaRequired: true` without
- * reading or modifying a design file.
+ * **Real-app sources:** a literal JSX attribute on a single authored localhost
+ * anchor uses the consented, version-guarded local-file CAS path. Transformed,
+ * repeated, shared, and fusion sources still fail closed for agent handoff.
  *
  * See DESIGN-STUDIO-PLAN.md §6.1, §7 (preview/apply contract), §11 phase 2.
  */
@@ -76,9 +73,16 @@ import {
   type ComponentSourceDocument,
 } from "../shared/component-links.js";
 import {
+  COMPONENT_PROP_PREFIX,
   componentNameFor,
   componentNodeIdMatches,
+  propNameToDataAttribute,
 } from "../shared/component-model.js";
+import {
+  planLocalJsxVisualEdit,
+  readLiteralJsxPropsAtAnchor,
+  type LocalJsxSourceAnchor,
+} from "../shared/local-jsx-visual-edit.js";
 import { designSourceTypeFromData } from "../shared/source-mode.js";
 import { sourceContentHash } from "../shared/source-workspace.js";
 import {
@@ -87,6 +91,8 @@ import {
   restoreComponentMainInDesign,
   type ComponentArchiveMutationResult,
 } from "./_component-archive.js";
+import readLocalFileAction from "./read-local-file.js";
+import writeLocalFileAction from "./write-local-file.js";
 
 type SupportedStructureIntent =
   | DeleteNodeEditIntent
@@ -105,6 +111,32 @@ type ComponentStructureEdit =
     }
   | { kind: "structure"; intents: SupportedStructureIntent[] };
 
+interface LocalComponentSource extends LocalJsxSourceAnchor {
+  connectionId: string;
+  path: string;
+  expectedVersionHash?: string;
+  expectedValue?: string;
+}
+
+function jsxPropNameForComponentAttribute(attribute: string): string {
+  if (!attribute.startsWith(COMPONENT_PROP_PREFIX)) return attribute;
+  return attribute
+    .slice(COMPONENT_PROP_PREFIX.length)
+    .replace(/-([a-z])/g, (_, char: string) => char.toUpperCase());
+}
+
+function literalJsxPropNameForComponentAttribute(
+  content: string,
+  anchor: LocalJsxSourceAnchor,
+  attribute: string,
+): string | undefined {
+  const literalProps = readLiteralJsxPropsAtAnchor({ content, anchor });
+  const matches = literalProps?.filter(
+    ({ name }) => propNameToDataAttribute(name) === attribute,
+  );
+  return matches?.length === 1 ? matches[0]!.name : undefined;
+}
+
 interface LinkedComponentSelection {
   fileId: string;
   nodeIds: string[];
@@ -808,8 +840,9 @@ export default defineAction({
     "For inline/Alpine designs, edits the data-agent-native-prop-* attributes, " +
     "x-data expression, or class list of the component root via the deterministic " +
     "HTML-patch path (same seam as apply-visual-edit). " +
-    "For real-app sources, returns ctaRequired=true without modifying any file; " +
-    "compiled source requires a dedicated consented bridge transform. " +
+    "For a literal JSX attribute on a single authored localhost anchor, uses the " +
+    "consented local-file CAS path; transformed, repeated, shared, and fusion " +
+    "sources return ctaRequired=true. " +
     "The structure variant atomically propagates bounded delete, wrap, unwrap, " +
     "move, and style intents across linked HTML files; unsupported structural " +
     "operations fail before any file is written. " +
@@ -923,6 +956,31 @@ export default defineAction({
           .describe(
             "Exact source version hashes for every HTML file in the Design. Required for linked property and structure edits.",
           ),
+        local: z
+          .object({
+            connectionId: z.string().min(1),
+            path: z.string().min(1),
+            line: z.number().int().positive(),
+            column: z.number().int().positive(),
+            positionPrecision: z
+              .enum(["authored", "transformed", "unknown"])
+              .optional(),
+            runtimeMultiplicity: z.number().int().positive().optional(),
+            scope: z
+              .enum([
+                "single-instance",
+                "repeated-render",
+                "shared-component-definition",
+                "unknown",
+              ])
+              .optional(),
+            expectedVersionHash: z.string().optional(),
+            expectedValue: z
+              .string()
+              .optional()
+              .describe("Current literal JSX prop value used as a CAS guard."),
+          })
+          .optional(),
       })
       .optional(),
   }),
@@ -935,13 +993,115 @@ export default defineAction({
     const rawData = (access.resource as { data?: unknown }).data;
     const sourceType = designSourceTypeFromData(rawData);
 
-    // Fail closed for every real-app tier even if its generic capability map
-    // advertises applyEdit. This action only knows how to patch SQL-backed HTML;
-    // allowing localhost through here could report success for the mirror while
-    // leaving the real JSX/TSX file untouched. A future compiled-source action
-    // must perform consent, canonical path resolution, AST anchoring, and an
-    // expected-version bridge write as one dedicated transaction.
+    const localSource = source?.local as LocalComponentSource | undefined;
+
+    // Literal localhost JSX props reuse the existing authored-anchor planner
+    // and consented bridge CAS. All other real-app edits stay fail-closed.
     if (sourceType !== "inline") {
+      if (
+        sourceType === "localhost" &&
+        localSource &&
+        edit.kind === "attribute"
+      ) {
+        await assertAccess("design", designId, "editor");
+        if (!localSource.expectedVersionHash) {
+          return {
+            designId,
+            nodeId,
+            sourceType,
+            persisted: false,
+            conflict: true,
+            error:
+              "Component prop edits require the source version captured with the live selection. Refresh the selection and retry.",
+          };
+        }
+        const live = await readLocalFileAction.run({
+          designId,
+          connectionId: localSource.connectionId,
+          path: localSource.path,
+        });
+        if (
+          localSource.expectedVersionHash &&
+          live.versionHash !== localSource.expectedVersionHash
+        ) {
+          return {
+            designId,
+            nodeId,
+            sourceType,
+            persisted: false,
+            conflict: true,
+            error:
+              "The local component source changed while the prop edit was being prepared. Refresh and retry.",
+            source: {
+              kind: "local-file" as const,
+              connectionId: localSource.connectionId,
+              path: localSource.path,
+              versionHash: live.versionHash,
+            },
+          };
+        }
+
+        const jsxPropName =
+          literalJsxPropNameForComponentAttribute(
+            live.content,
+            localSource,
+            edit.attribute,
+          ) ?? jsxPropNameForComponentAttribute(edit.attribute);
+        const planned = planLocalJsxVisualEdit({
+          content: live.content,
+          anchor: localSource,
+          intent: {
+            kind: "attributes",
+            values: {
+              [jsxPropName]: edit.value,
+              [edit.attribute]: edit.value,
+            },
+            expectedValues: {
+              [jsxPropName]: localSource.expectedValue,
+            },
+          },
+        });
+        if (planned.result.status !== "applied") {
+          return {
+            designId,
+            nodeId,
+            sourceType,
+            persisted: false,
+            ctaRequired: planned.result.status === "needsAgent",
+            error: planned.result.message,
+            result: planned.result,
+          };
+        }
+
+        let write: Awaited<ReturnType<typeof writeLocalFileAction.run>> | null =
+          null;
+        if (planned.result.changed) {
+          await snapshotDesignBeforeAgentEdit(designId, context);
+          write = await writeLocalFileAction.run({
+            designId,
+            connectionId: localSource.connectionId,
+            relPath: localSource.path,
+            content: planned.content,
+            expectedVersionHash: live.versionHash,
+            requireExpectedVersionHash: true,
+          });
+        }
+        return {
+          designId,
+          nodeId,
+          sourceType,
+          persisted: write ? write.written : !planned.result.changed,
+          ctaRequired: false,
+          source: {
+            kind: "local-file" as const,
+            connectionId: localSource.connectionId,
+            path: localSource.path,
+            versionHash: write?.versionHash ?? live.versionHash,
+          },
+          content: planned.content,
+          result: planned.result,
+        };
+      }
       return {
         designId,
         nodeId,

package/corpus/templates/design/actions/apply-visual-edit.ts

@@ -1064,7 +1064,8 @@ export default defineAction({
       if (
         editIntent.kind !== "textContent" &&
         editIntent.kind !== "class" &&
-        editIntent.kind !== "style"
+        editIntent.kind !== "style" &&
+        editIntent.kind !== "attribute"
       ) {
         return {
           result: {
@@ -1458,6 +1459,7 @@ export default defineAction({
 
       const workspace = await resolveSourceWorkspace(file.designId, {
         includeContent: true,
+        includeBoard: true,
       });
       if (workspace.sourceType !== "inline") {
         return noWrite(

package/corpus/templates/design/actions/create-component.ts

@@ -20,9 +20,9 @@
  * **Tier A (Alpine / inline):**  always available — the design HTML is the
  * source of truth.
  *
- * **Tier B (real-app, localhost / fusion):**  source writes require the
- * `applyEdit` capability (bridge write hardening). Until that lands the action
- * returns `ctaRequired: true` without modifying any source.
+ * **Tier B (real-app, localhost):** a single authored JSX opening tag can be
+ * promoted through the consented local-file CAS path. Transformed, repeated,
+ * shared, or fusion sources still return `ctaRequired: true`.
  *
  * See DESIGN-STUDIO-PLAN.md §6.1 (component model) and §7 (action surface).
  */
@@ -68,7 +68,13 @@ import {
   linkedComponentRootForNode,
 } from "../shared/component-model.js";
 import { hasCapability } from "../shared/design-source-capabilities.js";
+import {
+  planLocalJsxVisualEdit,
+  type LocalJsxSourceAnchor,
+} from "../shared/local-jsx-visual-edit.js";
 import { designSourceTypeFromData } from "../shared/source-mode.js";
+import readLocalFileAction from "./read-local-file.js";
+import writeLocalFileAction from "./write-local-file.js";
 
 // ─── Pure helpers ─────────────────────────────────────────────────────────────
 
@@ -81,8 +87,22 @@ export interface ComponentAttributeStamp {
 }
 
 export interface CreateComponentSourceExpectation {
-  currentContent: string;
-  expectedVersionHash: string;
+  currentContent?: string;
+  expectedVersionHash?: string;
+}
+
+export interface CreateComponentLocalSourceReceipt {
+  kind: "local-file";
+  connectionId: string;
+  path: string;
+  versionHash: string;
+}
+
+interface LocalComponentSource extends LocalJsxSourceAnchor {
+  connectionId: string;
+  path: string;
+  expectedVersionHash?: string;
+  propStamps?: ComponentAttributeStamp[];
 }
 
 /** A linked component owns its descendants; they cannot become nested mains. */
@@ -260,9 +280,9 @@ export default defineAction({
     'data-agent-native-component="<Name>" plus data-agent-native-prop-* for ' +
     "obvious variant-like attributes (data-variant/size/state, aria-pressed, " +
     "etc.). For inline/Alpine designs this writes the HTML directly via the " +
-    "deterministic patch path. For real-app sources the applyEdit capability " +
-    "must be available; otherwise returns ctaRequired=true without modifying " +
-    "any file. After it runs the node is a recognised component instance, so " +
+    "deterministic patch path. For localhost React, a single authored JSX " +
+    "anchor uses the consented local-file CAS path; transformed, repeated, " +
+    "shared, or fusion sources return ctaRequired=true. After it runs the node is a recognised component instance, so " +
     "component-model detection, the canvas outline, and the Component section " +
     "all pick it up.",
   schema: z.object({
@@ -293,10 +313,41 @@ export default defineAction({
       .object({
         currentContent: z
           .string()
+          .optional()
           .describe("Exact source preimage the editor planned against."),
         expectedVersionHash: z
           .string()
+          .optional()
           .describe("Hash of the live source preimage."),
+        local: z
+          .object({
+            connectionId: z.string().min(1),
+            path: z.string().min(1),
+            line: z.number().int().positive(),
+            column: z.number().int().positive(),
+            positionPrecision: z
+              .enum(["authored", "transformed", "unknown"])
+              .optional(),
+            runtimeMultiplicity: z.number().int().positive().optional(),
+            scope: z
+              .enum([
+                "single-instance",
+                "repeated-render",
+                "shared-component-definition",
+                "unknown",
+              ])
+              .optional(),
+            expectedVersionHash: z.string().optional(),
+            propStamps: z
+              .array(
+                z.object({
+                  name: z.string().min(1),
+                  value: z.string(),
+                }),
+              )
+              .optional(),
+          })
+          .optional(),
       })
       .optional()
       .describe(
@@ -323,9 +374,16 @@ export default defineAction({
     const rawData = (access.resource as { data?: unknown }).data;
     const sourceType = designSourceTypeFromData(rawData);
     const caps = resolveSourceCapabilities(sourceType);
-
-    // Real-app sources gate on `applyEdit` (bridge write hardening).
-    if (sourceType !== "inline" && !hasCapability(caps, "applyEdit")) {
+    const localSource = source?.local as LocalComponentSource | undefined;
+
+    // Real-app sources gate on `applyEdit` (bridge write hardening). A
+    // localhost source with an authored JSX anchor can use the existing
+    // consented local-file CAS path for literal component annotations.
+    if (
+      sourceType !== "inline" &&
+      !(sourceType === "localhost" && localSource) &&
+      !hasCapability(caps, "applyEdit")
+    ) {
       return {
         designId,
         sourceType,
@@ -338,7 +396,109 @@ export default defineAction({
     }
 
     await assertAccess("design", designId, "editor");
-    await snapshotDesignBeforeAgentEdit(designId, context);
+
+    if (sourceType !== "inline") {
+      if (sourceType !== "localhost" || !localSource) {
+        return {
+          designId,
+          sourceType,
+          persisted: false,
+          ctaRequired: true,
+          ctaMessage:
+            "Creating a component from this source requires an authored localhost JSX anchor.",
+        };
+      }
+
+      if (!localSource.expectedVersionHash) {
+        return {
+          designId,
+          sourceType,
+          persisted: false,
+          conflict: true,
+          error:
+            "Create Component requires the source version captured with the live selection. Refresh the selection and retry.",
+        };
+      }
+
+      const live = await readLocalFileAction.run({
+        designId,
+        connectionId: localSource.connectionId,
+        path: localSource.path,
+      });
+      if (
+        localSource.expectedVersionHash &&
+        live.versionHash !== localSource.expectedVersionHash
+      ) {
+        return {
+          designId,
+          sourceType,
+          persisted: false,
+          conflict: true,
+          error:
+            "The local component source changed while Create Component was being prepared. Refresh and retry.",
+          source: {
+            kind: "local-file" as const,
+            connectionId: localSource.connectionId,
+            path: localSource.path,
+            versionHash: live.versionHash,
+          },
+        };
+      }
+
+      const componentName = normalizeComponentName(name);
+      const values = Object.fromEntries([
+        [COMPONENT_NAME_ATTR, componentName],
+        ...(localSource.propStamps ?? []).map((stamp) => [
+          stamp.name,
+          stamp.value,
+        ]),
+      ]);
+      const planned = planLocalJsxVisualEdit({
+        content: live.content,
+        anchor: localSource,
+        intent: { kind: "attributes", values },
+      });
+      if (planned.result.status !== "applied") {
+        return {
+          designId,
+          sourceType,
+          persisted: false,
+          ctaRequired: planned.result.status === "needsAgent",
+          error: planned.result.message,
+          result: planned.result,
+        };
+      }
+
+      let write: Awaited<ReturnType<typeof writeLocalFileAction.run>> | null =
+        null;
+      if (planned.result.changed) {
+        await snapshotDesignBeforeAgentEdit(designId, context);
+        write = await writeLocalFileAction.run({
+          designId,
+          connectionId: localSource.connectionId,
+          relPath: localSource.path,
+          content: planned.content,
+          expectedVersionHash: live.versionHash,
+          requireExpectedVersionHash: true,
+        });
+      }
+      return {
+        designId,
+        nodeId,
+        componentName,
+        sourceType,
+        persisted: write ? write.written : !planned.result.changed,
+        ctaRequired: false,
+        source: {
+          kind: "local-file" as const,
+          connectionId: localSource.connectionId,
+          path: localSource.path,
+          versionHash: write?.versionHash ?? live.versionHash,
+        },
+        content: planned.content,
+        result: planned.result,
+      };
+    }
 
     // ── Fetch file ───────────────────────────────────────────────────────────
     const conditions = [
@@ -490,6 +650,7 @@ export default defineAction({
       updatedAt: string;
     } | null = null;
     if (contentChanged) {
+      await snapshotDesignBeforeAgentEdit(designId, context);
       persistedReceipt = await writeInlineSourceFile({
         designId: file.designId,
         file: workspaceFile,