@agent-native/core 0.154.4 → 0.155.0

package/corpus/templates/content/app/components/editor/CommentsSidebar.tsx

@@ -1,6 +1,10 @@
 import { sendToAgentChat } from "@agent-native/core/client/agent-chat";
 import { emailToName } from "@agent-native/core/client/collab";
 import { useT } from "@agent-native/core/client/i18n";
+import {
+  InlineMarkdown,
+  type InlineMarkdownProtectedSpan,
+} from "@agent-native/core/client/markdown";
 import {
   IconCheck,
   IconMessageCircle,
@@ -40,23 +44,28 @@ import { CommentComposer, type MentionEntry } from "./CommentComposer";
 
 /**
  * Render a comment body, styling any `@mention` tokens that match the comment's
- * stored mentions. Plain text otherwise — no HTML is interpreted.
+ * stored mentions. Raw HTML is never interpreted.
  */
-function renderCommentBody(content: string, mentions: CommentMention[]) {
+function commentMentionSpans(
+  mentions: CommentMention[],
+): InlineMarkdownProtectedSpan[] {
   const labels = Array.from(
     new Set(mentions.map((m) => m.name).filter((n): n is string => !!n)),
   ).sort((a, b) => b.length - a.length);
-  if (labels.length === 0) return content;
-  const escaped = labels.map((l) => l.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"));
-  const re = new RegExp(`(@(?:${escaped.join("|")}))`, "g");
-  return content.split(re).map((seg, i) =>
-    seg.startsWith("@") && labels.includes(seg.slice(1)) ? (
-      <span key={i} className="comment-mention">
-        {seg}
-      </span>
-    ) : (
-      seg
-    ),
+  return labels.map((label) => ({
+    source: `@${label}`,
+    label: `@${label}`,
+    className: "comment-mention",
+  }));
+}
+
+function renderCommentBody(content: string, mentions: CommentMention[]) {
+  return (
+    <InlineMarkdown
+      content={content}
+      inline
+      protectedSpans={commentMentionSpans(mentions)}
+    />
   );
 }
 
@@ -942,9 +951,9 @@ function ThreadView({
                 {formatDate(c.created_at)}
               </span>
             </div>
-            <p className="text-[13px] text-foreground/90 pl-8 leading-relaxed whitespace-pre-wrap">
+            <div className="text-[13px] text-foreground/90 pl-8 leading-relaxed">
               {renderCommentBody(c.content, c.mentions)}
-            </p>
+            </div>
           </div>
         ))}
       </div>

package/corpus/templates/content/app/components/editor/database/DatabaseView.tsx

@@ -1631,6 +1631,11 @@ function DatabaseTable({
   ) {
     if (!databaseId) return null;
     if (isWorkspaceCatalog) return null;
+    const mutationContract = data?.mutationContract;
+    if (!mutationContract) {
+      toast.error(dbText("failedToCreateRow"));
+      return null;
+    }
     const propertyValues = {
       ...databasePropertyValuesForNewItem(filters, properties, filterMode),
       ...propertyValueOverrides,
@@ -1638,8 +1643,10 @@ function DatabaseTable({
     let response;
     try {
       response = await addItem.mutateAsync({
-        databaseId,
-        title,
+        target: mutationContract.target,
+        expectedSchemaRevision: mutationContract.schemaRevision,
+        idempotencyKey: crypto.randomUUID(),
+        ...(title.trim() ? { title } : {}),
         propertyValues:
           Object.keys(propertyValues).length > 0 ? propertyValues : undefined,
       });
@@ -1650,12 +1657,7 @@ function DatabaseTable({
       });
       return null;
     }
-    const createdItem = databaseCreatedItemForImmediatePreview(response, {
-      databaseId,
-      parentDocument: document,
-      title,
-      propertyValues,
-    });
+    const createdItem = response.createdItem ?? null;
     const needsPreview =
       !!createdItem &&
       databaseCreatedItemNeedsPreview(items, createdItem, options);

package/corpus/templates/content/app/hooks/use-content-database.ts

@@ -12,6 +12,7 @@ import type {
   CancelPreparedBuilderSourceUpdateResponse,
   ChangeContentDatabaseSourceRoleRequest,
   ContentDatabaseResponse,
+  ContentDatabaseRowMutationResult,
   ContentDatabaseSourceAttachmentAck,
   ContentDatabaseSourceAttachmentResult,
   ContentDatabaseItemsPageResponse,
@@ -819,40 +820,40 @@ export function useTrashedContentDatabases() {
 
 export function useAddDatabaseItem(documentId: string) {
   const queryClient = useQueryClient();
-  return useActionMutation<ContentDatabaseResponse, AddDatabaseItemRequest>(
-    "add-database-item",
-    {
-      skipActionQueryInvalidation: true,
-      onSuccess: (data) => {
-        if (data.createdItem) {
-          queryClient.setQueriesData<ContentDatabaseResponse>(
-            {
-              queryKey: ["action", "get-content-database"],
-              predicate: (query) => {
-                if (
-                  !isContentDatabaseQueryForDocument(query.queryKey, documentId)
-                ) {
-                  return false;
-                }
-                const params = query.queryKey[2] as {
-                  tableQuery?: unknown;
-                };
-                return params.tableQuery === undefined;
-              },
+  return useActionMutation<
+    ContentDatabaseRowMutationResult,
+    AddDatabaseItemRequest
+  >("add-database-item", {
+    skipActionQueryInvalidation: true,
+    onSuccess: (data) => {
+      if (data.createdItem) {
+        queryClient.setQueriesData<ContentDatabaseResponse>(
+          {
+            queryKey: ["action", "get-content-database"],
+            predicate: (query) => {
+              if (
+                !isContentDatabaseQueryForDocument(query.queryKey, documentId)
+              ) {
+                return false;
+              }
+              const params = query.queryKey[2] as {
+                tableQuery?: unknown;
+              };
+              return params.tableQuery === undefined;
             },
-            (current) =>
-              applyOptimisticItemToContentDatabase(current, data.createdItem!),
-          );
-        }
-        queryClient.invalidateQueries({
-          queryKey: contentDatabaseQueryKey(documentId),
-        });
-        queryClient.invalidateQueries({
-          queryKey: ["action", "list-documents"],
-        });
-      },
+          },
+          (current) =>
+            applyOptimisticItemToContentDatabase(current, data.createdItem!),
+        );
+      }
+      queryClient.invalidateQueries({
+        queryKey: contentDatabaseQueryKey(documentId),
+      });
+      queryClient.invalidateQueries({
+        queryKey: ["action", "list-documents"],
+      });
     },
-  );
+  });
 }
 
 export function useSubmitContentDatabaseForm(documentId: string) {

package/corpus/templates/content/changelog/2026-08-10-database-row-actions-now-validate-exact-schemas-and-safe-ret.md

@@ -0,0 +1,6 @@
+---
+type: improved
+date: 2026-08-10
+---
+
+Database row actions now validate exact schemas and safe retries before changing data.

package/corpus/templates/content/parity/matrix.md

@@ -9,7 +9,7 @@ This generated matrix tracks whether high-value Content UI operations use the sa
 | database.lifecycle-and-trash                       | database    | Create, soft-delete, restore, list, and inspect content databases                                         | action-backed         | `create-content-database`, `create-inline-content-database`, `delete-content-database`, `get-content-database`, `list-content-databases`, `list-trashed-content-databases`, `restore-content-database`                                                                                                                                                                                                      | `app/components/editor/SlashCommandMenu.tsx`, `app/hooks/use-content-database.ts`, `app/hooks/use-documents.ts`                                                                           | Database pages and database records are created, read, soft-deleted, restored, and listed.                                                                                                                                                                                                | -                                                                                                                                                                                                                                          | -                | P0             | covered       | `actions/content-database-lifecycle.db.test.ts`                                                                                                                                                                         | `database-source-scope`          | -                              |
 | database.private-preview-drafts                    | database    | Persist and reconcile a user's private database-page preview draft                                        | action-backed         | `get-preview-document-draft`, `update-preview-document-draft`                                                                                                                                                                                                                                                                                                                                               | `app/components/editor/database/DatabaseView.tsx`, `app/hooks/use-documents.ts`                                                                                                           | A user's private preview draft is read, saved, conflict-checked, or deleted without changing the shared database page until the normal save flow applies it.                                                                                                                              | These per-user editor-state actions are intentionally hidden from agent tools because preview drafts are a private UI recovery mechanism.                                                                                                  | -                | P1             | covered       | `actions/preview-document-draft.db.test.ts`                                                                                                                                                                             | -                                | -                              |
 | database.properties-and-view-config                | database    | Configure properties, values, ordering, and saved views                                                   | action-backed         | `configure-document-property`, `delete-document-property`, `duplicate-document-property`, `get-content-database-personal-view`, `list-document-properties`, `reorder-document-property`, `set-document-property`, `update-content-database-personal-view`, `update-content-database-view`                                                                                                                   | `app/components/editor/DocumentProperties.tsx`, `app/components/editor/DocumentDatabase.tsx`, `app/components/editor/database/DatabaseView.tsx`, `app/hooks/use-document-properties.ts`   | Property schemas, property values, property order, filters, sorts, grouping, hidden columns, view type, and view settings are stored.                                                                                                                                                     | -                                                                                                                                                                                                                                          | -                | P0             | covered       | `actions/bind-content-database-source-field.db.test.ts`, `actions/content-database-source-actions.test.ts`, `actions/resync-content-database-source.db.test.ts`                                                         | `database-source-scope`          | -                              |
-| database.rows                                      | database    | Add, duplicate, move, open, edit, and remove database rows                                                | action-backed         | `add-database-item`, `upsert-database-item-by-key`, `remove-database-items`, `duplicate-database-items`, `duplicate-database-item`, `migrate-content-database-rows`, `move-database-item`, `set-document-property`                                                                                                                                                                                          | `app/components/editor/DocumentDatabase.tsx`, `app/components/editor/database/DatabaseView.tsx`                                                                                           | Database row memberships and ordering are created, duplicated, moved, edited, and removed without deleting the backing page; bounded migrations atomically update row bodies and properties through the same canonical data model.                                                        | -                                                                                                                                                                                                                                          | -                | P0             | covered       | `actions/database-row-batch-actions.db.test.ts`, `actions/migrate-content-database-rows.db.test.ts`, `parity/__tests__/database-row-batch-reliability.test.ts`                                                          | `database-bulk-row-reliability`  | -                              |
+| database.rows                                      | database    | Add, duplicate, move, open, edit, and remove database rows                                                | action-backed         | `add-database-item`, `update-database-item`, `upsert-database-item-by-key`, `remove-database-items`, `duplicate-database-items`, `duplicate-database-item`, `migrate-content-database-rows`, `move-database-item`, `set-document-property`                                                                                                                                                                  | `app/components/editor/DocumentDatabase.tsx`, `app/components/editor/database/DatabaseView.tsx`                                                                                           | Database row memberships and ordering are created, duplicated, moved, edited, and removed without deleting the backing page; bounded migrations atomically update row bodies and properties through the same canonical data model.                                                        | -                                                                                                                                                                                                                                          | -                | P0             | covered       | `actions/database-row-batch-actions.db.test.ts`, `actions/upsert-database-item-by-key.db.test.ts`, `actions/migrate-content-database-rows.db.test.ts`, `parity/__tests__/database-row-batch-reliability.test.ts`        | `database-bulk-row-reliability`  | -                              |
 | database.table-query-page                          | database    | Query one constrained page while retaining database metadata                                              | action-backed         | `query-content-database-items`                                                                                                                                                                                                                                                                                                                                                                              | `app/components/editor/database/DatabaseView.tsx`, `app/hooks/use-content-database.ts`                                                                                                    | -                                                                                                                                                                                                                                                                                         | This UI-only bounded projection is intentionally hidden with agentTool: false; agents use get-content-database for the complete database contract.                                                                                         | -                | P0             | covered       | `actions/content-database-lifecycle.db.test.ts`, `app/hooks/use-content-database.test.ts`                                                                                                                               | -                                | -                              |
 | editor.agent-assist-prompts                        | editor      | Ask AI from slash generation or comment context                                                           | client-assist         | -                                                                                                                                                                                                                                                                                                                                                                                                           | `app/components/editor/SlashCommandMenu.tsx`, `app/components/editor/CommentsSidebar.tsx`                                                                                                 | No direct durable mutation; the prompt asks the agent to use document actions when it decides to write.                                                                                                                                                                                   | -                                                                                                                                                                                                                                          | -                | P1             | none          | -                                                                                                                                                                                                                       | -                                | -                              |
 | editor.client-formatting-and-insertions            | editor      | Rich text formatting, selection state, slash block insertion, and copy actions                            | client-only-ephemeral | -                                                                                                                                                                                                                                                                                                                                                                                                           | `app/components/editor/BubbleToolbar.tsx`, `app/components/editor/SlashCommandMenu.tsx`, `app/components/editor/DocumentToolbar.tsx`                                                      | -                                                                                                                                                                                                                                                                                         | -                                                                                                                                                                                                                                          | -                | P1             | none          | -                                                                                                                                                                                                                       | -                                | -                              |

package/corpus/templates/content/parity/matrix.ts

@@ -345,6 +345,7 @@ export const parityMatrix: ParityRow[] = [
     status: "action-backed",
     actions: [
       "add-database-item",
+      "update-database-item",
       "upsert-database-item-by-key",
       "remove-database-items",
       "duplicate-database-items",
@@ -360,6 +361,7 @@ export const parityMatrix: ParityRow[] = [
     followUpPR: null,
     coverageRefs: [
       "actions/database-row-batch-actions.db.test.ts",
+      "actions/upsert-database-item-by-key.db.test.ts",
       "actions/migrate-content-database-rows.db.test.ts",
       "parity/__tests__/database-row-batch-reliability.test.ts",
     ],

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

@@ -234,6 +234,7 @@ export const contentDatabases = table(
     ownerBlockId: text("owner_block_id"),
     title: text("title").notNull().default("Untitled database"),
     systemRole: text("system_role"),
+    naturalKeyPropertyId: text("natural_key_property_id"),
     viewConfigJson: text("view_config_json").notNull().default("{}"),
     filesSystemPropertiesSeeded: integer("files_system_properties_seeded")
       .notNull()
@@ -287,9 +288,9 @@ export const contentDatabaseItems = table(
   ],
 );
 
-// Opt-in stable-key claims are the durable concurrency fence for the generic
-// database-row upsert action. They intentionally do not constrain ordinary
-// property editing or change add-database-item behavior.
+// Opt-in stable-key claims are the durable concurrency fence for configured
+// natural-key upserts. Ordinary property editing stays independent until a
+// text property is explicitly selected as the database's natural key.
 export const contentDatabaseItemKeyClaims = table(
   "content_database_item_key_claims",
   {
@@ -494,6 +495,41 @@ export const contentDatabaseMigrationReceipts = table(
   ],
 );
 
+export const contentDatabaseRowMutationReceipts = table(
+  "content_database_row_mutation_receipts",
+  {
+    id: text("id").primaryKey(),
+    ownerEmail: text("owner_email").notNull().default("local@localhost"),
+    orgId: text("org_id"),
+    spaceId: text("space_id").notNull(),
+    databaseId: text("database_id").notNull(),
+    databaseDocumentId: text("database_document_id").notNull(),
+    operation: text("operation").notNull(),
+    itemId: text("item_id").notNull(),
+    documentId: text("document_id").notNull(),
+    idempotencyKey: text("idempotency_key").notNull(),
+    payloadDigest: text("payload_digest").notNull(),
+    schemaRevision: text("schema_revision").notNull(),
+    preRowRevision: text("pre_row_revision"),
+    postRowRevision: text("post_row_revision").notNull(),
+    resultJson: text("result_json").notNull().default("{}"),
+    createdAt: text("created_at").notNull().default(now()),
+    updatedAt: text("updated_at").notNull().default(now()),
+  },
+  (receipt) => [
+    uniqueIndex(
+      "content_database_row_mutation_receipts_database_key_unique",
+    ).on(receipt.databaseId, receipt.idempotencyKey),
+    index("content_database_row_mutation_receipts_owner_database_idx").on(
+      receipt.ownerEmail,
+      receipt.databaseId,
+    ),
+    index("content_database_row_mutation_receipts_document_idx").on(
+      receipt.documentId,
+    ),
+  ],
+);
+
 export const documentPropertyValues = table("document_property_values", {
   id: text("id").primaryKey(),
   ownerEmail: text("owner_email").notNull().default("local@localhost"),

package/corpus/templates/content/server/plugins/db.ts

@@ -1011,6 +1011,36 @@ export const runContentMigrations = runMigrations(
         ALTER TABLE document_blocks ALTER COLUMN addressable SET DEFAULT true`,
       },
     },
+    {
+      version: 84,
+      name: "content-database-row-mutation-contract",
+      sql: `ALTER TABLE content_databases ADD COLUMN IF NOT EXISTS natural_key_property_id TEXT;
+      CREATE TABLE IF NOT EXISTS content_database_row_mutation_receipts (
+        id TEXT PRIMARY KEY,
+        owner_email TEXT NOT NULL DEFAULT 'local@localhost',
+        org_id TEXT,
+        space_id TEXT NOT NULL,
+        database_id TEXT NOT NULL,
+        database_document_id TEXT NOT NULL,
+        operation TEXT NOT NULL,
+        item_id TEXT NOT NULL,
+        document_id TEXT NOT NULL,
+        idempotency_key TEXT NOT NULL,
+        payload_digest TEXT NOT NULL,
+        schema_revision TEXT NOT NULL,
+        pre_row_revision TEXT,
+        post_row_revision TEXT NOT NULL,
+        result_json TEXT NOT NULL DEFAULT '{}',
+        created_at TEXT NOT NULL DEFAULT (datetime('now')),
+        updated_at TEXT NOT NULL DEFAULT (datetime('now'))
+      );
+      CREATE UNIQUE INDEX IF NOT EXISTS content_database_row_mutation_receipts_database_key_unique
+        ON content_database_row_mutation_receipts (database_id, idempotency_key);
+      CREATE INDEX IF NOT EXISTS content_database_row_mutation_receipts_owner_database_idx
+        ON content_database_row_mutation_receipts (owner_email, database_id);
+      CREATE INDEX IF NOT EXISTS content_database_row_mutation_receipts_document_idx
+        ON content_database_row_mutation_receipts (document_id)`,
+    },
   ],
   { table: "content_migrations" },
 );

package/corpus/templates/content/shared/api.ts

@@ -225,6 +225,7 @@ export interface ConfigureDocumentPropertyRequest {
   description?: string;
   visibility?: DocumentPropertyVisibility;
   options?: DocumentPropertyOptions;
+  naturalKey?: boolean;
 }
 
 export interface SetDocumentPropertyRequest {
@@ -258,8 +259,10 @@ export interface ReorderDocumentPropertyRequest {
 export interface ContentDatabase {
   id: string;
   documentId: string;
+  spaceId?: string | null;
   title: string;
   systemRole?: string | null;
+  naturalKeyPropertyId?: string | null;
   description?: string;
   viewConfig: ContentDatabaseViewConfig;
   createdAt: string;
@@ -469,6 +472,62 @@ export interface ContentDatabaseItem {
   // a secondary source contributes on top of it. Absent for non-federated rows.
   canonicalKey?: string | null;
   sourceOverlays?: ContentDatabaseSourceOverlay[];
+  rowRevision?: string;
+}
+
+export interface ContentDatabaseMutationTarget {
+  authorityScope:
+    | { kind: "personal"; id: string }
+    | { kind: "organization"; id: string };
+  spaceId: string;
+  databaseId: string;
+  databaseDocumentId: string;
+}
+
+export interface ContentDatabaseMutationContract {
+  target: ContentDatabaseMutationTarget;
+  schemaRevision: string;
+  naturalKeyPropertyId: string | null;
+  properties: Array<{
+    id: string;
+    name: string;
+    type: DocumentPropertyType;
+    writable: boolean;
+    sourceManaged: boolean;
+    acceptedShape: string | null;
+    options: DocumentPropertyOptions;
+  }>;
+}
+
+export interface ContentDatabaseRowMutationReceipt {
+  receiptId: string;
+  operation: "create" | "update" | "upsert";
+  outcome: "created" | "updated" | "unchanged";
+  target: ContentDatabaseMutationTarget;
+  schemaRevision: string;
+  row: {
+    itemId: string;
+    documentId: string;
+    urlPath: string;
+    rowRevision: string;
+  };
+  affected: { title: boolean; propertyIds: string[] };
+  idempotency: {
+    key: string;
+    result: "applied" | "replayed";
+    payloadDigest: string;
+  };
+  revisions: { before: string | null; after: string };
+  readback: {
+    verified: true;
+    title: string;
+    propertyValues: Record<string, DocumentPropertyValue>;
+  };
+}
+
+export interface ContentDatabaseRowMutationResult {
+  receipt: ContentDatabaseRowMutationReceipt;
+  createdItem?: ContentDatabaseItem;
 }
 
 // A secondary source's read-only contribution to a federated row, matched on the
@@ -828,6 +887,7 @@ export interface ContentDatabaseResponse {
   removedCount?: number;
   timings?: BuilderActionTiming[];
   tableQueryMode?: "server" | "client-required";
+  mutationContract?: ContentDatabaseMutationContract;
   /** Client-only optimistic state while real provider rows are being attached. */
   attachPreview?: {
     sourceTable: string;
@@ -892,9 +952,22 @@ export interface CreateInlineDatabaseResponse {
 }
 
 export interface AddDatabaseItemRequest {
-  databaseId: string;
+  target: ContentDatabaseMutationTarget;
+  expectedSchemaRevision: string;
+  idempotencyKey: string;
   title?: string;
-  propertyValues?: Record<string, DocumentPropertyValue>;
+  propertyValues?: Record<string, unknown>;
+}
+
+export interface UpdateDatabaseItemRequest extends AddDatabaseItemRequest {
+  itemId: string;
+  documentId: string;
+  expectedRowRevision: string;
+}
+
+export interface UpsertDatabaseItemByKeyRequest extends AddDatabaseItemRequest {
+  keyValue: string;
+  expectedRowRevision: string | null;
 }
 
 export interface SubmitContentDatabaseFormRequest {

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

@@ -171,12 +171,15 @@ const reuseLabelSchema = z
     }
   });
 
-function hasBreakpointSet(value: unknown): boolean {
-  if (!value || typeof value !== "object" || Array.isArray(value)) {
-    return false;
-  }
+function classifyBreakpointSet(
+  value: unknown,
+): "absent" | "malformed" | "present" {
+  if (value === null || value === undefined) return "absent";
+  if (typeof value !== "object" || Array.isArray(value)) return "malformed";
   const breakpoints = (value as { breakpoints?: unknown }).breakpoints;
-  return Array.isArray(breakpoints) && breakpoints.length > 0;
+  if (breakpoints === undefined) return "malformed";
+  if (!Array.isArray(breakpoints)) return "malformed";
+  return breakpoints.length > 0 ? "present" : "malformed";
 }
 
 function jsonValuesEqual(left: unknown, right: unknown): boolean {
@@ -1137,7 +1140,7 @@ const generateDesignAction = defineAction({
           mergedData.breakpointSetUpdatedAt = updatedAt;
         } else if (
           generatedBreakpointSet.length > 0 &&
-          !hasBreakpointSet(mergedData.breakpointSet)
+          classifyBreakpointSet(mergedData.breakpointSet) === "absent"
         ) {
           mergedData.breakpointSet = {
             id: "generated-responsive",
@@ -1200,7 +1203,7 @@ const generateDesignAction = defineAction({
           devices && devices.length > 0
             ? jsonValuesEqual(currentBreakpointWidths, expectedBreakpointWidths)
             : generatedBreakpointSet.length === 0 ||
-              hasBreakpointSet(current.breakpointSet);
+              classifyBreakpointSet(current.breakpointSet) !== "absent";
         return framesApplied && breakpointSetApplied;
       },
     });

package/corpus/templates/design/actions/present-design-variants.ts

@@ -89,12 +89,25 @@ async function hasLinkedDesignSystem(designId: string): Promise<boolean> {
   return Boolean(design?.designSystemId?.trim());
 }
 
-function hasBreakpointSet(value: unknown): boolean {
-  if (!value || typeof value !== "object" || Array.isArray(value)) {
-    return false;
-  }
+/**
+ * Absent, or present but unreadable — the caller must not treat these alike.
+ * A malformed set is still the user's data: overwriting it with the generated
+ * default silently discards breakpoints they configured, so it reports
+ * `"malformed"` and the install is skipped rather than clobbering it.
+ */
+function classifyBreakpointSet(
+  value: unknown,
+): "absent" | "malformed" | "present" {
+  if (value === null || value === undefined) return "absent";
+  if (typeof value !== "object" || Array.isArray(value)) return "malformed";
   const breakpoints = (value as { breakpoints?: unknown }).breakpoints;
-  return Array.isArray(breakpoints) && breakpoints.length > 0;
+  if (breakpoints === undefined) return "malformed";
+  if (!Array.isArray(breakpoints)) return "malformed";
+  return breakpoints.length > 0 ? "present" : "malformed";
+}
+
+function hasBreakpointSet(value: unknown): boolean {
+  return classifyBreakpointSet(value) === "present";
 }
 
 function designDeepLink(designId: string): string {
@@ -1042,9 +1055,16 @@ export default defineAction({
       });
     }
 
+    // Presenting options should not silently reconfigure the design. When it
+    // does, the overview paints an extra preview beside EVERY primary frame
+    // from then on — including screens created later — so the caller is told.
+    let installedBreakpointSet = false;
+
     await mutateDesignData({
       designId,
       mutate: (current, { updatedAt }) => {
+        installedBreakpointSet =
+          classifyBreakpointSet(current.breakpointSet) === "absent";
         // Placement depends on the breakpoint set in effect after this call, so
         // it is resolved here (inside the compare-and-set body) rather than
         // against a design snapshot that a concurrent write may have moved on
@@ -1106,7 +1126,9 @@ export default defineAction({
           canvasFrames: mergedFrames.canvasFrames,
           screenMetadata: previousMetadata,
           designVariantSets: previousVariantSets,
-          ...(hasBreakpointSet(current.breakpointSet)
+          // Only when genuinely absent. A malformed set is the user's data in
+          // a shape this action cannot read, not a blank slate to overwrite.
+          ...(classifyBreakpointSet(current.breakpointSet) !== "absent"
             ? {}
             : {
                 breakpointSet: {
@@ -1227,6 +1249,13 @@ export default defineAction({
       embed: true,
       cleanedUpPreviousVariantScreens: variantSetCleanup.removedFileIds.length,
       deletedSupersededSetIds: variantSetCleanup.removedSetIds,
+      ...(installedBreakpointSet
+        ? {
+            installedBreakpointSet: DEFAULT_RESPONSIVE_BREAKPOINTS.map(
+              (breakpoint) => breakpoint.widthPx,
+            ),
+          }
+        : {}),
       fallbackInstructions: FALLBACK_INSTRUCTIONS,
       nextRequiredAction:
         'Wait for the user to pick a screen in chat. Then delete each unchosen variant screen with delete-file at most once, call get-design-snapshot exactly once with fileId for the chosen screen, and call edit-design with that same fileId in a bounded pass. Use mode "replace-file" to replace the representative direction screen with a complete but compact requested app/product UI in the chosen visual style. Prioritize the primary workflow and render secondary details as visible controls, states, or affordances if the full feature list is too large for one reliable edit. Do not leave a direction board, variant brief, or summary card as the final result. Do not repeat delete/snapshot cycles. Do not call generate-design after a variant pick. Stop after the first successful edit-design save.',

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

@@ -25,6 +25,10 @@ import type {
   A11yFindingCategory,
   A11ySeverity,
 } from "../shared/design-review.js";
+import {
+  describeDesignHtmlIntegrityIssue,
+  inspectDesignHtmlDocumentIntegrity,
+} from "../shared/html-integrity.js";
 
 // ---------------------------------------------------------------------------
 // HTML helpers (static analysis — no DOM runtime available server-side)
@@ -259,6 +263,34 @@ export function checkTapTargets(html: string): A11yFinding[] {
   return findings;
 }
 
+/**
+ * Screens that render with an Alpine-controlled element covering them. Every
+ * other check here is a regex over the raw string; this one delegates to the
+ * save-time integrity parser so the audit and the write gate cannot drift into
+ * disagreeing about the same document. It is the only check that can see the
+ * failure a screenshot cannot: `take-design-screenshot` waits for Alpine to
+ * settle, so a pre-Alpine cover never appears in the agent's own capture.
+ */
+export function checkRenderBlockingOverlays(html: string): A11yFinding[] {
+  const result = inspectDesignHtmlDocumentIntegrity(html);
+  const issues = [...(result.detail ?? []), ...(result.advisory ?? [])].filter(
+    (issue) =>
+      issue.issue === "runtime-overlay-unhidden" ||
+      issue.issue === "runtime-cloak-missing" ||
+      issue.issue === "runtime-alpine-missing",
+  );
+
+  return issues.map((issue, index) => ({
+    id: `render-blocking-overlay:${issue.issue}-${index}`,
+    severity: "error" as A11ySeverity,
+    category: "render-blocking-overlay" as A11yFindingCategory,
+    message:
+      "An Alpine-controlled element can cover the screen before Alpine starts.",
+    detail: describeDesignHtmlIntegrityIssue(issue),
+    fixAvailable: false,
+  }));
+}
+
 /** Check for animations/transitions without a prefers-reduced-motion guard. */
 function checkReducedMotion(html: string): A11yFinding[] {
   const findings: A11yFinding[] = [];
@@ -848,6 +880,7 @@ export default defineAction({
       ...checkReducedMotion(html),
       ...checkFocusVisibility(html),
       ...checkContrastHint(html),
+      ...checkRenderBlockingOverlays(html),
       ...tokenDriftFindings,
       ...designSystemFindings,
     ];

package/corpus/templates/design/changelog/2026-08-13-the-design-audit-now-catches-a-screen-that-renders-behind-an.md

@@ -0,0 +1,6 @@
+---
+type: added
+date: 2026-08-13
+---
+
+The design audit now catches a screen that renders behind a full-frame Alpine overlay — the failure a screenshot cannot show, because the capture waits for Alpine to settle and the overlay is gone by then.

package/corpus/templates/design/shared/design-review.ts

@@ -25,6 +25,7 @@ export const A11Y_FINDING_CATEGORIES = [
   "role",
   "token-drift",
   "design-system-drift",
+  "render-blocking-overlay",
   "other",
 ] as const;