@agent-native/core 0.92.6 → 0.92.8

package/corpus/templates/design/server/db/schema.ts

@@ -12,6 +12,12 @@ export const designs = table("designs", {
   title: text("title").notNull(),
   description: text("description"),
   data: text("data").notNull(),
+  // Monotonic per-client sequence numbers for path-addressed data writes.
+  // Kept outside `data` so editor/export payloads stay free of transport
+  // bookkeeping while late keepalive requests can be rejected atomically.
+  dataOperationRevisions: text("data_operation_revisions")
+    .notNull()
+    .default("{}"),
   projectType: text("project_type").notNull().default("prototype"),
   designSystemId: text("design_system_id"),
   createdAt: text("created_at").default(now()),
@@ -43,6 +49,12 @@ export const designFiles = table("design_files", {
   designId: text("design_id").notNull(),
   filename: text("filename").notNull(),
   content: text("content").notNull(),
+  // Last accepted browser content-save operation. This transport metadata
+  // stays beside (rather than inside) the document so a late unload
+  // keepalive can be rejected without parsing or rewriting user content.
+  contentOperationSource: text("content_operation_source"),
+  contentOperationRevision: integer("content_operation_revision"),
+  contentOperationResultHash: text("content_operation_result_hash"),
   fileType: text("file_type").notNull().default("html"),
   createdAt: text("created_at").default(now()),
   updatedAt: text("updated_at").default(now()),
@@ -75,6 +87,10 @@ export const designLocalhostConnections = table(
       .notNull()
       .default("connected"),
     lastSeenAt: text("last_seen_at"),
+    /** Read-only credential used by browser preview/bridge-registration calls.
+     * It is one-way derived from the filesystem token when not supplied by a
+     * newer bridge, so leaking it cannot grant source-file access. */
+    previewToken: text("preview_token"),
     bridgeToken: text("bridge_token"),
     ownerEmail: text("owner_email").notNull(),
     orgId: text("org_id"),

package/corpus/templates/design/server/lib/design-data-access.ts

@@ -0,0 +1,70 @@
+const EDITOR_ROLES = new Set(["owner", "admin", "editor"]);
+
+/**
+ * Public visibility is read-only. Ownership and explicit share grants are
+ * resolved separately by the framework, so they can still upgrade the caller
+ * to owner/admin/editor without making an anonymous public link writable.
+ */
+export function publicDesignAccessRole(): "viewer" {
+  return "viewer";
+}
+
+function removeLocalhostCredentials(
+  value: unknown,
+  ancestors: WeakSet<object>,
+  allowPreviewToken: boolean,
+): unknown {
+  if (!value || typeof value !== "object") return value;
+  if (ancestors.has(value)) {
+    throw new Error("Design data contains a circular reference");
+  }
+
+  ancestors.add(value);
+  try {
+    if (Array.isArray(value)) {
+      return value.map((child) =>
+        removeLocalhostCredentials(child, ancestors, allowPreviewToken),
+      );
+    }
+
+    return Object.fromEntries(
+      Object.entries(value as Record<string, unknown>)
+        .filter(
+          ([key]) =>
+            key !== "bridgeToken" &&
+            (allowPreviewToken || key !== "previewToken"),
+        )
+        .map(([key, child]) => [
+          key,
+          removeLocalhostCredentials(child, ancestors, allowPreviewToken),
+        ]),
+    );
+  } finally {
+    ancestors.delete(value);
+  }
+}
+
+/**
+ * Filter persisted design data before sending it to a caller.
+ *
+ * Filesystem bridge tokens unlock privileged loopback endpoints and are never
+ * returned through design data, including to owners/editors. The separate
+ * read-only preview token is available only to callers with an editor role;
+ * anonymous/public viewers fail closed rather than gaining access to a local
+ * development server. Invalid persisted JSON also fails closed to null.
+ */
+export function designDataForAccessRole(data: unknown, role: unknown): unknown {
+  const allowPreviewToken = typeof role === "string" && EDITOR_ROLES.has(role);
+
+  try {
+    if (typeof data === "string") {
+      const parsed = JSON.parse(data) as unknown;
+      return JSON.stringify(
+        removeLocalhostCredentials(parsed, new WeakSet(), allowPreviewToken),
+      );
+    }
+    return removeLocalhostCredentials(data, new WeakSet(), allowPreviewToken);
+  } catch {
+    return null;
+  }
+}

package/corpus/templates/design/server/lib/design-data-mutation.ts

@@ -0,0 +1,249 @@
+import { assertAccess } from "@agent-native/core/sharing";
+import { and, eq, isNull } from "drizzle-orm";
+
+import { getDb, schema } from "../db/index.js";
+
+const DEFAULT_MAX_ATTEMPTS = 8;
+const CONFLICT_BACKOFF_MS = 8;
+const designDataLocks = new Map<string, Promise<unknown>>();
+
+export type DesignDataRecord = Record<string, unknown>;
+
+export class DesignDataMutationConflictError extends Error {
+  constructor(designId: string, attempts: number) {
+    super(
+      `Failed to update design "${designId}" after ${attempts} concurrent write conflicts. Please retry.`,
+    );
+    this.name = "DesignDataMutationConflictError";
+  }
+}
+
+export class InvalidDesignDataError extends Error {
+  constructor(designId: string) {
+    super(
+      `Design "${designId}" has invalid data JSON. Refusing to overwrite it; repair or restore the design data before retrying.`,
+    );
+    this.name = "InvalidDesignDataError";
+  }
+}
+
+function parseDesignData(
+  designId: string,
+  serialized: string | null,
+): DesignDataRecord {
+  // A small number of legacy rows predate the current NOT NULL schema. Treat
+  // SQL NULL as the old empty-data sentinel, while still refusing malformed
+  // non-null JSON so a corrupt blob is never silently discarded.
+  if (serialized === null) return {};
+  try {
+    const parsed: unknown = JSON.parse(serialized);
+    if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+      return parsed as DesignDataRecord;
+    }
+  } catch {
+    // The dedicated error below explains why the write is refused.
+  }
+  throw new InvalidDesignDataError(designId);
+}
+
+function serializeDesignData(designId: string, data: DesignDataRecord): string {
+  if (!data || typeof data !== "object" || Array.isArray(data)) {
+    throw new InvalidDesignDataError(designId);
+  }
+  try {
+    const serialized = JSON.stringify(data);
+    if (typeof serialized === "string") return serialized;
+  } catch {
+    // The dedicated error below keeps circular/non-serializable transforms
+    // from turning into a partial or ambiguous write.
+  }
+  throw new InvalidDesignDataError(designId);
+}
+
+function nextUpdatedAt(current: string | null, now: Date): string {
+  const currentMs = current ? Date.parse(current) : Number.NaN;
+  const nextMs = Number.isFinite(currentMs)
+    ? Math.max(now.getTime(), currentMs + 1)
+    : now.getTime();
+  return new Date(nextMs).toISOString();
+}
+
+function conflictDelay(attempt: number): Promise<void> {
+  return new Promise((resolve) => {
+    setTimeout(resolve, Math.min(64, CONFLICT_BACKOFF_MS * (attempt + 1)));
+  });
+}
+
+function isRetryableTransactionConflict(error: unknown): boolean {
+  const code =
+    error && typeof error === "object" && "code" in error
+      ? String((error as { code?: unknown }).code ?? "")
+      : "";
+  return (
+    code === "SQLITE_BUSY" ||
+    code === "SQLITE_LOCKED" ||
+    code === "40001" || // Postgres serialization failure
+    code === "40P01" // Postgres deadlock detected
+  );
+}
+
+function withDesignDataLock<T>(
+  designId: string,
+  callback: () => Promise<T>,
+): Promise<T> {
+  const previous = designDataLocks.get(designId) ?? Promise.resolve();
+  const next = previous.then(callback, callback);
+  designDataLocks.set(designId, next);
+  const cleanup = () => {
+    if (designDataLocks.get(designId) === next) {
+      designDataLocks.delete(designId);
+    }
+  };
+  next.then(cleanup, cleanup);
+  return next;
+}
+
+interface MutateDesignDataOptions {
+  designId: string;
+  mutate: (
+    current: DesignDataRecord,
+    context: { updatedAt: string },
+  ) => DesignDataRecord;
+  /**
+   * Proves the caller's intent is present in the committed row. This is
+   * deliberately intent-based rather than whole-object equality: a sibling
+   * writer may safely add unrelated keys immediately after our commit.
+   */
+  isApplied: (persisted: DesignDataRecord) => boolean;
+  maxAttempts?: number;
+  now?: () => Date;
+}
+
+/**
+ * Atomically mutate the designs.data JSON record without losing sibling keys.
+ *
+ * The conditional UPDATE is portable Drizzle query-builder SQL (no RETURNING,
+ * dialect-specific JSON operator, or driver result-shape assumption). The
+ * read, compare-and-swap, and confirmation read live in one transaction. A
+ * post-commit read then proves the requested intent survived before success is
+ * reported. Explicit property deletion performed by `mutate` is preserved
+ * because the complete transformed object is the CAS candidate.
+ *
+ * Isolation assumptions: local better-sqlite3 transactions use the framework's
+ * BEGIN IMMEDIATE + top-level queue, so no sibling writer can enter between
+ * the read and CAS. Postgres may let a sibling commit after the read, but its
+ * conditional UPDATE is re-evaluated after the row-lock wait; the confirmation
+ * read detects a lost CAS and triggers a retry. Other supported drivers get the
+ * same guarded predicate plus confirmation/post-commit verification rather
+ * than relying on a driver-specific affected-row result.
+ */
+async function mutateDesignDataUnlocked({
+  designId,
+  mutate,
+  isApplied,
+  maxAttempts = DEFAULT_MAX_ATTEMPTS,
+  now = () => new Date(),
+}: MutateDesignDataOptions): Promise<{
+  data: DesignDataRecord;
+  updatedAt: string;
+}> {
+  // Re-assert at the shared write boundary. Callers also check before doing
+  // parse/index work so unauthorized requests fail early, but this helper must
+  // remain independently scoped if a new action adopts it later.
+  await assertAccess("design", designId, "editor");
+  const db = getDb();
+
+  for (let attempt = 0; attempt < maxAttempts; attempt += 1) {
+    let committed: { data: DesignDataRecord; updatedAt: string } | undefined;
+
+    try {
+      committed = await db.transaction(async (tx) => {
+        const [currentRow] = await tx
+          .select({
+            data: schema.designs.data,
+            updatedAt: schema.designs.updatedAt,
+          })
+          .from(schema.designs)
+          .where(eq(schema.designs.id, designId));
+
+        if (!currentRow) {
+          throw new Error(`Design "${designId}" not found.`);
+        }
+
+        const updatedAt = nextUpdatedAt(currentRow.updatedAt, now());
+        const currentData = parseDesignData(designId, currentRow.data);
+        const nextData = mutate(currentData, { updatedAt });
+        const nextSerialized = serializeDesignData(designId, nextData);
+        const revisionConditions = [
+          eq(schema.designs.id, designId),
+          currentRow.data === null
+            ? isNull(schema.designs.data)
+            : eq(schema.designs.data, currentRow.data),
+        ];
+        revisionConditions.push(
+          currentRow.updatedAt === null
+            ? isNull(schema.designs.updatedAt)
+            : eq(schema.designs.updatedAt, currentRow.updatedAt),
+        );
+
+        await tx
+          .update(schema.designs)
+          .set({ data: nextSerialized, updatedAt })
+          .where(and(...revisionConditions));
+
+        // Avoid driver-specific rowsAffected/rowCount/RETURNING contracts.
+        // Inside the same transaction the row remains locked after a winning
+        // UPDATE, so exact equality proves this CAS attempt wrote its candidate.
+        const [confirmed] = await tx
+          .select({ data: schema.designs.data })
+          .from(schema.designs)
+          .where(eq(schema.designs.id, designId));
+
+        if (!confirmed) {
+          throw new Error(`Design "${designId}" not found after update.`);
+        }
+        if (confirmed.data !== nextSerialized) {
+          throw new DesignDataMutationConflictError(designId, attempt + 1);
+        }
+
+        return { data: nextData, updatedAt };
+      });
+    } catch (error) {
+      if (
+        !(error instanceof DesignDataMutationConflictError) &&
+        !isRetryableTransactionConflict(error)
+      ) {
+        throw error;
+      }
+    }
+
+    if (committed) {
+      const [persistedRow] = await db
+        .select({ data: schema.designs.data })
+        .from(schema.designs)
+        .where(eq(schema.designs.id, designId));
+      if (!persistedRow) {
+        throw new Error(`Design "${designId}" not found after commit.`);
+      }
+      const persistedData = parseDesignData(designId, persistedRow.data);
+      if (isApplied(persistedData)) {
+        return { data: persistedData, updatedAt: committed.updatedAt };
+      }
+    }
+
+    if (attempt < maxAttempts - 1) await conflictDelay(attempt);
+  }
+
+  throw new DesignDataMutationConflictError(designId, maxAttempts);
+}
+
+export function mutateDesignData(
+  options: MutateDesignDataOptions,
+): Promise<{ data: DesignDataRecord; updatedAt: string }> {
+  // Serialize same-process calls before entering a backend transaction. This
+  // avoids overlapping libSQL/SQLite transactions on one client; the CAS
+  // remains necessary for multi-instance and cross-process writers.
+  return withDesignDataLock(options.designId, () =>
+    mutateDesignDataUnlocked(options),
+  );
+}

package/corpus/templates/design/server/lib/fusion-screens.ts

@@ -29,8 +29,8 @@ import {
   parseCanvasFrameGeometryById,
   type CanvasFramePlacement,
 } from "../../shared/canvas-frames.js";
-import { parseDesignDataBlob } from "../../shared/full-app.js";
 import { getDb, schema } from "../db/index.js";
+import { mutateDesignData } from "./design-data-mutation.js";
 
 /** Default iframe viewport, mirroring add-localhost-screens' defaults. */
 export const DEFAULT_FUSION_SCREEN_WIDTH = 1280;
@@ -117,18 +117,6 @@ export async function upsertFusionScreens(args: {
   }
 
   const db = getDb();
-  const [design] = await db
-    .select({ data: schema.designs.data })
-    .from(schema.designs)
-    .where(eq(schema.designs.id, designId))
-    .limit(1);
-  const prevData = parseDesignDataBlob(design?.data);
-  const existingCanvasFrames = parseCanvasFrameGeometryById(
-    prevData.canvasFrames,
-  );
-  const existingMetadata = isRecord(prevData.screenMetadata)
-    ? { ...(prevData.screenMetadata as Record<string, unknown>) }
-    : {};
   const existingFiles = await db
     .select()
     .from(schema.designFiles)
@@ -140,22 +128,6 @@ export async function upsertFusionScreens(args: {
   const now = new Date().toISOString();
 
   const results: FusionScreenResult[] = [];
-  const placements: CanvasFramePlacement[] = [];
-
-  // Only place screens that don't already have canvas geometry so re-syncs
-  // never reset positions the user has arranged. New screens start after the
-  // right-most existing frame.
-  const existingGeometries = Object.values(existingCanvasFrames);
-  let nextX = startX;
-  if (existingGeometries.length > 0) {
-    nextX =
-      Math.max(
-        startX,
-        ...existingGeometries.map(
-          (frame) => (frame.x ?? 0) + (frame.width ?? width),
-        ),
-      ) + gap;
-  }
 
   for (let index = 0; index < paths.length; index += 1) {
     const path = paths[index]!;
@@ -190,57 +162,98 @@ export async function upsertFusionScreens(args: {
     }
 
     results.push({ fileId, filename, path, url, title, width, height });
-    if (!existingCanvasFrames[fileId]) {
-      placements.push({
-        fileId,
-        filename,
-        x: nextX,
-        y: startY,
-        width,
-        height,
-        z: placements.length,
-      });
-      nextX += width + gap;
-    }
   }
 
-  const mergedFrames = mergeCanvasFramePlacements({
-    existing: prevData.canvasFrames,
-    placements,
-    resolveFileId: (placement) => placement.fileId,
-  });
+  let placedFrames: Array<{
+    fileId: string;
+    filename?: string;
+    frame: CanvasFramePlacement;
+  }> = [];
+  await mutateDesignData({
+    designId,
+    mutate: (current, { updatedAt }) => {
+      const currentFrames = parseCanvasFrameGeometryById(current.canvasFrames);
+      const existingGeometries = Object.values(currentFrames);
+      let nextX = startX;
+      if (existingGeometries.length > 0) {
+        nextX =
+          Math.max(
+            startX,
+            ...existingGeometries.map(
+              (frame) => (frame.x ?? 0) + (frame.width ?? width),
+            ),
+          ) + gap;
+      }
 
-  for (const screen of results) {
-    // Preserve user-adjusted title/dimensions on refresh; only the URL keys
-    // must always track the current preview URL.
-    const prevMeta = isRecord(existingMetadata[screen.fileId])
-      ? (existingMetadata[screen.fileId] as Record<string, unknown>)
-      : {};
-    existingMetadata[screen.fileId] = {
-      ...prevMeta,
-      sourceType: "fusion",
-      previewState: "live",
-      title: prevMeta.title ?? screen.title,
-      width: prevMeta.width ?? screen.width,
-      height: prevMeta.height ?? screen.height,
-      url: screen.url,
-      previewUrl: screen.url,
-      path: screen.path,
-    };
-  }
+      const placements: CanvasFramePlacement[] = [];
+      for (const screen of results) {
+        if (currentFrames[screen.fileId]) continue;
+        placements.push({
+          fileId: screen.fileId,
+          filename: screen.filename,
+          x: nextX,
+          y: startY,
+          width,
+          height,
+          z: placements.length,
+        });
+        nextX += width + gap;
+      }
+      const mergedFrames = mergeCanvasFramePlacements({
+        existing: current.canvasFrames,
+        placements,
+        resolveFileId: (placement) => placement.fileId,
+      });
+      placedFrames = mergedFrames.placedFrames;
 
-  await db
-    .update(schema.designs)
-    .set({
-      data: JSON.stringify({
-        ...prevData,
+      const metadata = isRecord(current.screenMetadata)
+        ? { ...current.screenMetadata }
+        : {};
+      for (const screen of results) {
+        // Preserve user-adjusted title/dimensions on refresh; only URL-backed
+        // source fields track the current container preview.
+        const candidate = metadata[screen.fileId];
+        const previous: Record<string, unknown> = isRecord(candidate)
+          ? candidate
+          : {};
+        metadata[screen.fileId] = {
+          ...previous,
+          sourceType: "fusion",
+          previewState: "live",
+          title: previous.title ?? screen.title,
+          width: previous.width ?? screen.width,
+          height: previous.height ?? screen.height,
+          url: screen.url,
+          previewUrl: screen.url,
+          path: screen.path,
+        };
+      }
+
+      return {
+        ...current,
         canvasFrames: mergedFrames.canvasFrames,
-        screenMetadata: existingMetadata,
-        updatedAt: now,
-      }),
-      updatedAt: now,
-    })
-    .where(eq(schema.designs.id, designId));
+        screenMetadata: metadata,
+        updatedAt,
+      };
+    },
+    isApplied: (current) => {
+      const frames = parseCanvasFrameGeometryById(current.canvasFrames);
+      const metadata = isRecord(current.screenMetadata)
+        ? current.screenMetadata
+        : {};
+      return results.every((screen) => {
+        const entry = metadata[screen.fileId];
+        return (
+          Boolean(frames[screen.fileId]) &&
+          isRecord(entry) &&
+          entry.sourceType === "fusion" &&
+          entry.url === screen.url &&
+          entry.previewUrl === screen.url &&
+          entry.path === screen.path
+        );
+      });
+    },
+  });
 
-  return { screens: results, placedFrames: mergedFrames.placedFrames };
+  return { screens: results, placedFrames };
 }