@agent-native/core 0.80.10 → 0.81.0

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

@@ -6,37 +6,32 @@
  * 2. Persist the `motion_timeline` row (insert or update).
  * 3. Compile the tracks into deterministic CSS.
  * 4. Inject/replace the managed `<style data-agent-native-motion>` block inside
- *    the design's HTML content, using the same persist path as apply-visual-edit
- *    (Yjs/collab + SQL, via agentEnterDocument / applyText / seedFromText).
+ *    the design's durable HTML content.
  * 5. Update `compiledHash` on the row to guard against drift.
  * 6. Return a diff summary (bytes before/after, track count, hash).
  *
  * Never writes unless all steps succeed. Scrubbing/preview is handled by the
  * separate `motion-preview` postMessage path on the frontend — this action is
- * the deliberate "Write to CSS" commit step.
+ * the durable autosave/persist path for edited timelines.
  */
 
 import { defineAction } from "@agent-native/core";
-import {
-  agentEnterDocument,
-  agentLeaveDocument,
-  applyText,
-  getText,
-  hasCollabState,
-  seedFromText,
-} from "@agent-native/core/collab";
 import {
   getRequestOrgId,
   getRequestUserEmail,
 } from "@agent-native/core/server/request-context";
 import { accessFilter, assertAccess } from "@agent-native/core/sharing";
-import { and, eq } from "drizzle-orm";
+import { and, desc, eq } from "drizzle-orm";
 import { nanoid } from "nanoid";
 import { z } from "zod";
 
 import { getDb, schema } from "../server/db/index.js";
 import "../server/db/index.js"; // ensure registerShareableResource runs
-import { compile } from "../shared/motion-compiler.js";
+import {
+  assertSafeMotionCssProperty,
+  assertSafeMotionCssToken,
+  compile,
+} from "../shared/motion-compiler.js";
 import type { MotionTrack } from "../shared/motion-timeline.js";
 
 // ─── Zod schemas ─────────────────────────────────────────────────────────────
@@ -85,47 +80,6 @@ const MOTION_STYLE_CLOSE = "</style>";
  */
 const STYLE_CLOSE_RE = /<\s*\/\s*style\b[^>]*>/i;
 
-/**
- * Reject `<`, `>`, and any `</style` sequence in a CSS token before it is
- * compiled into the managed `<style>` block. Keyframe `value` / `ease` come
- * straight from the caller and are interpolated raw into the CSS, so an
- * unescaped `</style>` (or angle bracket) would break out of the style block
- * and inject arbitrary markup. Returns the original string when safe; throws on
- * a breakout attempt so the whole atomic write fails loudly rather than
- * persisting a poisoned block.
- */
-function assertSafeCssToken(value: string, field: string): string {
-  if (/[<>]/.test(value) || /<\s*\/\s*style/i.test(value)) {
-    throw new Error(
-      `Invalid ${field}: "<", ">", and "</style" are not allowed in motion CSS values.`,
-    );
-  }
-  return value;
-}
-
-/**
- * Validate that a CSS property name is a safe CSS identifier.
- *
- * Accepts standard and vendor-prefixed property names (e.g. "opacity",
- * "transform", "-webkit-transform") and nothing else.  Rejects any string
- * containing `:`, `;`, `{`, `}`, `<`, `/`, whitespace, or other characters
- * that could break out of a CSS declaration or `<style>` block context when
- * the property is interpolated as `${property}: ${value};` inside
- * `@keyframes`.
- *
- * Uses the strict CSS ident regex `^-?[a-zA-Z][a-zA-Z0-9-]*$` which covers
- * every real animatable CSS property while blocking injection payloads.
- */
-function assertSafeCssProperty(property: string, field: string): string {
-  if (!/^-?[a-zA-Z][a-zA-Z0-9-]*$/.test(property)) {
-    throw new Error(
-      `Invalid ${field}: "${property}" is not a valid CSS property identifier. ` +
-        "Only ASCII letters, digits, hyphens, and an optional leading hyphen are allowed.",
-    );
-  }
-  return property;
-}
-
 /**
  * Inject or replace the managed `<style data-agent-native-motion>` block in
  * the HTML content.  Inserts before `</head>` when not already present.
@@ -158,21 +112,6 @@ function injectMotionStyle(html: string, css: string): string {
   return block + "\n" + html;
 }
 
-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;
-}
-
 async function persistFileContent(
   fileId: string,
   designId: string,
@@ -180,29 +119,21 @@ async function persistFileContent(
   now: string,
 ): Promise<void> {
   const db = getDb();
-  agentEnterDocument(fileId);
-  try {
-    await db
-      .update(schema.designFiles)
-      .set({ content, updatedAt: now })
-      .where(eq(schema.designFiles.id, fileId));
-
-    if (await hasCollabState(fileId)) {
-      await applyText(fileId, content, "content", "agent");
-    } else {
-      await seedFromText(fileId, content);
-    }
-
-    // guard:allow-unscoped — the action's run() asserts editor access via
-    // assertAccess("design", designId, "editor") before this helper is
-    // invoked; this only touches the addressed design row's updatedAt.
-    await db
-      .update(schema.designs)
-      .set({ updatedAt: now })
-      .where(eq(schema.designs.id, designId));
-  } finally {
-    agentLeaveDocument(fileId);
-  }
+  await db
+    .update(schema.designFiles)
+    .set({ content, updatedAt: now })
+    .where(eq(schema.designFiles.id, fileId));
+
+  // Keep SQL as the source of truth for this atomic write. The editor adopts
+  // the returned HTML content without re-saving it; applying the whole document
+  // through an existing collab text snapshot can merge against stale iframe
+  // state and duplicate the managed motion stylesheet.
+  // guard:allow-unscoped — editor access on this design is asserted in run()
+  // before this helper is invoked; this only bumps the addressed design row.
+  await db
+    .update(schema.designs)
+    .set({ updatedAt: now })
+    .where(eq(schema.designs.id, designId));
 }
 
 // ─── Action ───────────────────────────────────────────────────────────────────
@@ -213,7 +144,7 @@ export default defineAction({
     "Persists the motion_timeline row, compiles tracks to CSS, injects the " +
     "managed <style data-agent-native-motion> block into the design's HTML, " +
     "and updates compiledHash — all in one atomic step. " +
-    "This is the 'Write to CSS' commit path; preview/scrubbing uses the " +
+    "This is the durable timeline persist path; preview/scrubbing uses the " +
     "motion-preview postMessage bridge, NOT this action.",
   schema: z.object({
     designId: z.string().describe("Design project ID."),
@@ -268,6 +199,14 @@ export default defineAction({
       .optional()
       .default(false)
       .describe("Include the full patched HTML in the response (large)."),
+    currentContent: z
+      .string()
+      .optional()
+      .describe(
+        "Current open editor HTML for the target file. When supplied, the " +
+          "managed motion CSS is patched into this content instead of the " +
+          "last SQL snapshot so in-flight local edits are preserved.",
+      ),
   }),
   run: async ({
     designId,
@@ -278,6 +217,7 @@ export default defineAction({
     durationMs,
     defaultEase,
     includeContent,
+    currentContent: currentContentInput,
   }) => {
     await assertAccess("design", designId, "editor");
 
@@ -319,7 +259,11 @@ export default defineAction({
     }
 
     const fileId = file.id;
-    const currentContent = await liveFileContent(fileId, file.content ?? "");
+    const resolvedSourceRef = sourceRef ?? fileId;
+    const currentContent =
+      currentContentInput !== undefined
+        ? currentContentInput
+        : (file.content ?? "");
 
     // ── 2. Compile tracks → CSS ─────────────────────────────────────────────
     const typedTracks = tracks as MotionTrack[];
@@ -328,20 +272,20 @@ export default defineAction({
     // keyframe values, and easing strings before they are compiled into the
     // managed <style> block.
     for (const track of typedTracks) {
-      assertSafeCssProperty(track.property, "track.property");
+      assertSafeMotionCssProperty(track.property, "track.property");
       for (const kf of track.keyframes) {
-        assertSafeCssToken(kf.value, "keyframe value");
+        assertSafeMotionCssToken(kf.value, "keyframe value");
         if (kf.ease !== undefined) {
-          assertSafeCssToken(kf.ease, "keyframe ease");
+          assertSafeMotionCssToken(kf.ease, "keyframe ease");
         }
       }
     }
-    assertSafeCssToken(defaultEase, "defaultEase");
+    assertSafeMotionCssToken(defaultEase, "defaultEase");
 
     const { css, hash } = compile({
       id: timelineId ?? "",
       designId,
-      sourceRef: sourceRef ?? null,
+      sourceRef: resolvedSourceRef,
       filePath: null,
       tracks: typedTracks,
       durationMs,
@@ -360,7 +304,7 @@ export default defineAction({
     // Resolve everything that can fail (existence + ownership) BEFORE touching
     // content, so we never persist HTML for a row that can't be written.
     const tracksJson = JSON.stringify(typedTracks);
-    const resolvedTimelineId = timelineId ?? nanoid();
+    let existingTimelineId = timelineId;
 
     let insertOwnerEmail: string | null = null;
     let insertOrgId: string | null = null;
@@ -384,21 +328,37 @@ export default defineAction({
         );
       }
     } else {
-      // Insert new row — derive ownership from the request context (same
-      // pattern as create-design-state and other create actions).
-      insertOwnerEmail = getRequestUserEmail() ?? null;
-      if (!insertOwnerEmail) throw new Error("no authenticated user");
-      insertOrgId = getRequestOrgId() ?? null;
+      const [existingForSource] = await db
+        .select({ id: schema.motionTimeline.id })
+        .from(schema.motionTimeline)
+        .where(
+          and(
+            eq(schema.motionTimeline.designId, designId),
+            eq(schema.motionTimeline.sourceRef, resolvedSourceRef),
+          ),
+        )
+        .orderBy(desc(schema.motionTimeline.updatedAt))
+        .limit(1);
+
+      if (existingForSource) {
+        existingTimelineId = existingForSource.id;
+      } else {
+        // Insert new row — derive ownership from the request context (same
+        // pattern as create-design-state and other create actions).
+        insertOwnerEmail = getRequestUserEmail() ?? null;
+        if (!insertOwnerEmail) throw new Error("no authenticated user");
+        insertOrgId = getRequestOrgId() ?? null;
+      }
     }
 
+    const resolvedTimelineId = existingTimelineId ?? nanoid();
+
     // ── 5. Persist the motion_timeline row FIRST (atomic SQL portion) ───────
     // The timeline row is written before the HTML so that a failure in the
-    // HTML/collab write step cannot leave the design content mutated without a
-    // corresponding row.  The reverse (HTML first) was a false atomicity
-    // guarantee: if the row write failed after the HTML write, the managed
-    // <style> block would be permanently out of sync with the DB state.
+    // HTML write step cannot leave the design content mutated without a
+    // corresponding row.
     await db.transaction(async (tx) => {
-      if (timelineId) {
+      if (existingTimelineId) {
         await tx
           .update(schema.motionTimeline)
           .set({
@@ -406,15 +366,15 @@ export default defineAction({
             durationMs,
             defaultEase,
             compiledHash: hash,
-            sourceRef: sourceRef ?? null,
+            sourceRef: resolvedSourceRef,
             updatedAt: now,
           })
-          .where(eq(schema.motionTimeline.id, timelineId));
+          .where(eq(schema.motionTimeline.id, existingTimelineId));
       } else {
         await tx.insert(schema.motionTimeline).values({
           id: resolvedTimelineId,
           designId,
-          sourceRef: sourceRef ?? null,
+          sourceRef: resolvedSourceRef,
           filePath: null,
           tracks: tracksJson,
           durationMs,
@@ -428,8 +388,8 @@ export default defineAction({
       }
     });
 
-    // ── 6. Persist the patched HTML content SECOND (Yjs/collab + SQL) ───────
-    // Written after the row so a collab/SQL failure here leaves the timeline row
+    // ── 6. Persist the patched HTML content SECOND ─────────────────────────
+    // Written after the row so a SQL failure here leaves the timeline row
     // accurate (correct tracks + hash) and the stale HTML can be recompiled on
     // the next apply-motion-edit call via compiledHash drift detection.
     await persistFileContent(fileId, designId, patchedContent, now);
@@ -438,6 +398,7 @@ export default defineAction({
       timelineId: resolvedTimelineId,
       designId,
       fileId,
+      sourceRef: resolvedSourceRef,
       trackCount: typedTracks.length,
       compiledHash: hash,
       bytesBefore,

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

@@ -19,24 +19,15 @@
  * - The descriptor is validated against the preset manifest first, so callers
  *   get clear errors before any round-trip.
  *
- * The write reuses the canonical persist path (Yjs/collab + SQL via
- * agentEnterDocument / applyText / seedFromText), so collaborators and the agent
- * stay in sync. The edit is a single inline-style `style.background` change on
- * the resolved node — no structural inserts, no new owned rows.
+ * The write persists durable SQL content directly. The edit is a single
+ * inline-style `style.background` change on the resolved node — no structural
+ * inserts, no new owned rows.
  *
  * Plan reference: DESIGN-STUDIO-PLAN.md §6.7 + §7 (shader fill apply).
  */
 
 import { defineAction } from "@agent-native/core";
-import {
-  agentEnterDocument,
-  agentLeaveDocument,
-  agentUpdateSelection,
-  applyText,
-  getText,
-  hasCollabState,
-  seedFromText,
-} from "@agent-native/core/collab";
+import { agentUpdateSelection } from "@agent-native/core/collab";
 import { accessFilter, assertAccess } from "@agent-native/core/sharing";
 import { and, eq } from "drizzle-orm";
 import { z } from "zod";
@@ -65,6 +56,15 @@ const PRESET_NAMES = Object.keys(SHADER_PRESET_MAP) as [
   ShaderPresetName,
   ...ShaderPresetName[],
 ];
+const REVISION_CONFLICT_MESSAGE =
+  "This file changed since this shader fill was previewed. Refresh the editor and try again.";
+
+class ShaderFillRevisionConflictError extends Error {
+  constructor() {
+    super(REVISION_CONFLICT_MESSAGE);
+    this.name = "ShaderFillRevisionConflictError";
+  }
+}
 
 const descriptorSchema = z.object({
   preset: z
@@ -101,6 +101,16 @@ const sourceSchema = z
     fileId: z.string().optional(),
     filename: z.string().optional(),
     revision: z.string().optional(),
+    currentContent: z
+      .string()
+      .optional()
+      .describe(
+        "Current open editor HTML for the target file. When supplied, the " +
+          "shader background is patched into this content instead of the " +
+          "last SQL snapshot so in-flight local edits are preserved. " +
+          "source.revision must also be supplied as the file updatedAt value " +
+          "that currentContent was based on.",
+      ),
   })
   .describe(
     "Design source. Only kind=design-file (HTML) is persisted. Provide " +
@@ -132,24 +142,11 @@ interface ResolvedDesignFile {
   designId: string;
   filename: string;
   content: string;
+  updatedAt: string | null;
+  expectedUpdatedAt?: string;
   codeLayerSource: CodeLayerSource;
 }
 
-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 remains the fallback.
-  }
-  return storedContent;
-}
-
 /**
  * Resolve the target HTML design file with an access-scoped read, then assert
  * editor access. Mirrors `resolveEditableDesignFile` in apply-visual-edit.ts so
@@ -160,6 +157,7 @@ async function resolveEditableDesignFile(source: {
   fileId?: string;
   filename?: string;
   revision?: string;
+  currentContent?: string;
 }): Promise<ResolvedDesignFile> {
   if (!source.fileId && !source.designId) {
     throw new Error(
@@ -187,6 +185,7 @@ async function resolveEditableDesignFile(source: {
       filename: schema.designFiles.filename,
       fileType: schema.designFiles.fileType,
       content: schema.designFiles.content,
+      updatedAt: schema.designFiles.updatedAt,
     })
     .from(schema.designFiles)
     .innerJoin(
@@ -217,11 +216,31 @@ async function resolveEditableDesignFile(source: {
 
   await assertAccess("design", file.designId, "editor");
 
+  if (source.currentContent !== undefined && !source.revision) {
+    throw new Error(
+      "source.revision is required when source.currentContent is provided.",
+    );
+  }
+  if (
+    source.currentContent !== undefined &&
+    source.revision &&
+    file.updatedAt &&
+    source.revision !== file.updatedAt
+  ) {
+    throw new ShaderFillRevisionConflictError();
+  }
+
   return {
     id: file.id,
     designId: file.designId,
     filename: file.filename,
-    content: await liveContent(file.id, file.content ?? ""),
+    updatedAt: file.updatedAt,
+    expectedUpdatedAt:
+      source.currentContent !== undefined ? source.revision : undefined,
+    content:
+      source.currentContent !== undefined
+        ? source.currentContent
+        : (file.content ?? ""),
     codeLayerSource: {
       kind: "design-file",
       designId: file.designId,
@@ -236,35 +255,65 @@ async function persistDesignFileEdit(file: {
   id: string;
   designId: string;
   content: string;
-}): Promise<void> {
+  expectedUpdatedAt?: string;
+}): Promise<string> {
   await assertAccess("design", file.designId, "editor");
 
   const db = getDb();
   const now = new Date().toISOString();
 
-  agentEnterDocument(file.id);
-  try {
-    await db
-      .update(schema.designFiles)
-      .set({ content: file.content, updatedAt: now })
-      .where(eq(schema.designFiles.id, file.id));
-
-    if (await hasCollabState(file.id)) {
-      await applyText(file.id, file.content, "content", "agent");
-    } else {
-      await seedFromText(file.id, file.content);
+  if (file.expectedUpdatedAt) {
+    const [latest] = await db
+      .select({ updatedAt: schema.designFiles.updatedAt })
+      .from(schema.designFiles)
+      .where(eq(schema.designFiles.id, file.id))
+      .limit(1);
+    if (!latest) {
+      throw new Error("Design HTML file not found.");
+    }
+    if (latest.updatedAt && latest.updatedAt !== file.expectedUpdatedAt) {
+      throw new ShaderFillRevisionConflictError();
     }
+  }
+
+  await db
+    .update(schema.designFiles)
+    .set({ content: file.content, updatedAt: now })
+    .where(
+      file.expectedUpdatedAt
+        ? and(
+            eq(schema.designFiles.id, file.id),
+            eq(schema.designFiles.updatedAt, file.expectedUpdatedAt),
+          )
+        : eq(schema.designFiles.id, file.id),
+    );
 
-    // guard:allow-unscoped — editor access on this design is asserted above
-    // (and again at the top of this helper); this only bumps the addressed
-    // design row's updatedAt.
-    await db
-      .update(schema.designs)
-      .set({ updatedAt: now })
-      .where(eq(schema.designs.id, file.designId));
-  } finally {
-    agentLeaveDocument(file.id);
+  if (file.expectedUpdatedAt) {
+    const [saved] = await db
+      .select({
+        content: schema.designFiles.content,
+        updatedAt: schema.designFiles.updatedAt,
+      })
+      .from(schema.designFiles)
+      .where(eq(schema.designFiles.id, file.id))
+      .limit(1);
+    if (!saved || saved.updatedAt !== now || saved.content !== file.content) {
+      throw new ShaderFillRevisionConflictError();
+    }
   }
+
+  // Keep SQL as the source of truth for this guarded server write. The editor
+  // already has the live shader preview applied; feeding a full HTML document
+  // back through an existing collab text snapshot can merge against stale
+  // iframe state and corrupt the saved source.
+  // guard:allow-unscoped — editor access on this design is asserted above
+  // before this helper is invoked; this only bumps the addressed design row.
+  await db
+    .update(schema.designs)
+    .set({ updatedAt: now })
+    .where(eq(schema.designs.id, file.designId));
+
+  return now;
 }
 
 // ─── Action ──────────────────────────────────────────────────────────────────
@@ -350,7 +399,25 @@ snippet (WebGL canvas / JSX component), call apply-shader.
       };
     }
 
-    const file = await resolveEditableDesignFile(source);
+    let file: ResolvedDesignFile;
+    try {
+      file = await resolveEditableDesignFile(source);
+    } catch (error) {
+      if (error instanceof ShaderFillRevisionConflictError) {
+        return {
+          ok: false,
+          persisted: false,
+          conflict: true,
+          descriptor,
+          background,
+          fallbackCss,
+          colors,
+          error: error.message,
+          note: error.message,
+        };
+      }
+      throw error;
+    }
 
     const intent: StyleEditIntent = {
       kind: "style",
@@ -374,13 +441,36 @@ snippet (WebGL canvas / JSX component), call apply-shader.
 
     const changed =
       patch.result.status === "applied" && patch.result.changed === true;
+    let updatedAt: string | undefined;
 
     if (changed) {
-      await persistDesignFileEdit({
-        id: file.id,
-        designId: file.designId,
-        content: patch.content,
-      });
+      try {
+        updatedAt = await persistDesignFileEdit({
+          id: file.id,
+          designId: file.designId,
+          content: patch.content,
+          expectedUpdatedAt: file.expectedUpdatedAt,
+        });
+      } catch (error) {
+        if (error instanceof ShaderFillRevisionConflictError) {
+          return {
+            ok: false,
+            persisted: false,
+            conflict: true,
+            descriptor,
+            background,
+            fallbackCss,
+            colors,
+            designId: file.designId,
+            fileId: file.id,
+            filename: file.filename,
+            result: patch.result,
+            error: error.message,
+            note: error.message,
+          };
+        }
+        throw error;
+      }
     }
 
     return {
@@ -393,7 +483,9 @@ snippet (WebGL canvas / JSX component), call apply-shader.
       designId: file.designId,
       fileId: file.id,
       filename: file.filename,
+      updatedAt,
       result: patch.result,
+      patchedContent: patch.content,
       bytesBefore: file.content.length,
       bytesAfter: patch.content.length,
       note: changed

package/corpus/templates/design/actions/capture-design-state.ts

@@ -12,6 +12,11 @@ import { getDb, schema } from "../server/db/index.js";
 import "../server/db/index.js"; // ensure registerShareableResource runs
 import { hasCapability } from "../shared/design-source-capabilities.js";
 import type { DesignSourceCapabilities } from "../shared/design-source-capabilities.js";
+import {
+  normalizeDesignSourceType,
+  resolveDescriptorCapabilities,
+  type DesignSourceDescriptor,
+} from "../shared/source-mode.js";
 
 /**
  * Resolve the capabilities for the design's source type.
@@ -19,17 +24,35 @@ import type { DesignSourceCapabilities } from "../shared/design-source-capabilit
  */
 function resolveCapabilities(
   designData: string | null,
-): DesignSourceCapabilities | null {
-  if (!designData) return null;
+): DesignSourceCapabilities {
+  if (!designData) {
+    return resolveDescriptorCapabilities({ sourceType: "inline" });
+  }
+
   try {
     const parsed = JSON.parse(designData) as Record<string, unknown>;
     if (parsed.capabilities && typeof parsed.capabilities === "object") {
       return parsed.capabilities as DesignSourceCapabilities;
     }
+    const sourceType = normalizeDesignSourceType(parsed.sourceType) ?? "inline";
+    const descriptor: DesignSourceDescriptor =
+      sourceType === "fusion"
+        ? { sourceType, connected: parsed.connected === true }
+        : sourceType === "localhost"
+          ? {
+              sourceType,
+              connectionId:
+                typeof parsed.connectionId === "string"
+                  ? parsed.connectionId
+                  : "unknown",
+            }
+          : { sourceType };
+    return resolveDescriptorCapabilities(descriptor);
   } catch {
     // ignore parse errors
   }
-  return null;
+
+  return resolveDescriptorCapabilities({ sourceType: "inline" });
 }
 
 /**
@@ -167,7 +190,7 @@ export default defineAction({
     }
 
     const caps = resolveCapabilities(design.data);
-    if (caps !== null && !hasCapability(caps, "captureState")) {
+    if (!hasCapability(caps, "captureState")) {
       throw new Error(
         "The design's source does not support captureState. " +
           "Connect Builder or a localhost bridge to enable live captures.",