@agent-native/core 0.70.0 → 0.70.2

package/corpus/templates/content/app/components/editor/previewDocumentSaveRegistry.ts

@@ -0,0 +1,132 @@
+// Module-level registry of ONE save controller per PEEK document id.
+//
+// PROBLEM (the rebase race class — what the per-doc lane could NOT fix):
+//   The row peek renders a SINGLE `DatabaseItemPreview` instance whose `item`
+//   prop changes on row-switch (it has no per-row `key`, so it does not remount).
+//   The old design gave it ONE controller whose target document id was REBASED on
+//   every row-switch, plus a shared cross-doc serialization lane. That produced
+//   two timing bugs no patch could fully close:
+//     - lane queue-jump: a `running`/`tail` microtask gap let a new enqueue
+//       dispatch synchronously AHEAD of already-queued saves; and
+//     - stale completion after rebase: an OLD-row in-flight save resolving AFTER
+//       the row-switch `mark()` overwrote the SHARED controller's `lastSaved` with
+//       the old payload and triggered a redundant save against the NEW row.
+//   Both are properties of sharing one mutable-target controller across rows.
+//
+// FIX (one controller per document id, ref-counted — mirrors blockFieldSaveRegistry):
+//   There is exactly ONE controller per document id. A controller's target doc id
+//   is fixed at creation and NEVER changes. Switching rows RELEASES the old doc's
+//   controller (whose release flushes its pending save synchronously, bound to its
+//   own id) and ACQUIRES the new doc's controller. No `saveTargetIdRef` rebase on
+//   a live controller; no cross-doc shared mutable target; no cross-doc lane.
+//
+//   With per-doc controllers each is single-flight + trailing for ITS doc only:
+//     - A stale completion can only ever advance ITS OWN controller's `lastSaved`
+//       (correct) — never another row's. The stale-completion-after-rebase bug is
+//       structurally impossible.
+//     - Single-flight per doc means at most one save in flight per id, so there is
+//       nothing left for a serialization lane to order. The lane is deleted.
+//
+//   - acquire(id, factory): returns the SAME controller for a doc id, creating it
+//     once via `factory` and bumping a ref-count.
+//   - release(id): decrements the ref-count. At 0 we do NOT evict immediately: we
+//     flush-then-evict. The final flush still dispatches synchronously bound to
+//     this doc id, and a quick reopen BEFORE the flush settles re-acquires the
+//     SAME instance (eviction cancelled) — so a quick reopen reuses the live
+//     controller and there is never a competing second controller for the id.
+
+import type { PreviewDocumentSaveController } from "./previewDocumentSaveController";
+
+interface Entry {
+  controller: PreviewDocumentSaveController;
+  refCount: number;
+  // Set while a flush-then-evict is pending after refCount hit 0. If a reopen
+  // re-acquires before the flush settles, we clear this so the entry is NOT
+  // evicted out from under the live instance.
+  evicting: boolean;
+}
+
+const registry = new Map<string, Entry>();
+
+function payloadsEqual(
+  a: PreviewDocumentSaveController["pending"],
+  b: PreviewDocumentSaveController["pending"],
+) {
+  return a.title === b.title && a.content === b.content;
+}
+
+function controllerIsDirty(controller: PreviewDocumentSaveController): boolean {
+  return !payloadsEqual(controller.pending, controller.lastSaved);
+}
+
+/**
+ * Acquire the controller for `documentId`, creating it once via `factory`.
+ * Increments the ref-count and cancels any in-progress eviction so a reopen
+ * reuses the live instance rather than racing a fresh one.
+ */
+export function acquirePreviewDocumentSaveController(
+  documentId: string,
+  factory: () => PreviewDocumentSaveController,
+): PreviewDocumentSaveController {
+  let entry = registry.get(documentId);
+  if (!entry) {
+    entry = { controller: factory(), refCount: 0, evicting: false };
+    registry.set(documentId, entry);
+  }
+  entry.refCount += 1;
+  // A reopen before a pending eviction settled: keep the instance alive.
+  entry.evicting = false;
+  return entry.controller;
+}
+
+/**
+ * Return the EXISTING controller for `documentId`, or undefined if none is
+ * registered. Does NOT create an entry and does NOT change the ref-count.
+ */
+export function peekPreviewDocumentSaveController(
+  documentId: string,
+): PreviewDocumentSaveController | undefined {
+  return registry.get(documentId)?.controller;
+}
+
+/**
+ * Release one reference to the controller for `documentId`. When the last
+ * reference is released we flush-then-evict: flush the latest dirty payload so a
+ * debounce that hadn't fired is not dropped (dispatched synchronously, bound to
+ * THIS doc id), then remove the entry ONLY if it is still unreferenced after the
+ * flush settles (a reopen during the flush re-acquires the same instance and
+ * cancels the eviction).
+ */
+export function releasePreviewDocumentSaveController(documentId: string): void {
+  const entry = registry.get(documentId);
+  if (!entry) return;
+  entry.refCount -= 1;
+  if (entry.refCount > 0) return;
+
+  entry.evicting = true;
+  const settle = () => {
+    const current = registry.get(documentId);
+    // Evict only if it is the SAME entry, still unreferenced, and still marked
+    // for eviction (a reopen would have flipped `evicting` off / refCount up).
+    if (current === entry && current.refCount === 0 && current.evicting) {
+      if (controllerIsDirty(current.controller)) {
+        current.evicting = false;
+        return;
+      }
+      registry.delete(documentId);
+    }
+  };
+  // flush() dispatches the final save synchronously (so it lands before any
+  // teardown/navigation) and resolves once it has settled, before we drop state.
+  Promise.resolve(entry.controller.flush()).then(settle, settle);
+}
+
+/** Test-only: how many controllers the registry currently holds. */
+export function activePreviewControllerCount(): number {
+  return registry.size;
+}
+
+/** Test-only: reset the registry between tests. */
+export function __resetPreviewDocumentSaveRegistry(): void {
+  registry.clear();
+}

package/corpus/templates/content/app/global.css

@@ -296,6 +296,15 @@
   min-height: max(320px, 50vh);
 }
 
+/* Block fields stack multiple editors, so each surface uses a compact
+   min-height instead of the full-page max(320px, 50vh) — otherwise every field
+   reserves ~half the viewport and the gap between fields balloons. 6rem is the
+   Tailwind `min-h-24` step (~70% smaller than 320px). */
+.block-field-content .visual-editor-wrapper,
+.block-field-content .visual-editor-wrapper .notion-editor {
+  min-height: 6rem;
+}
+
 .notion-editor > *:first-child {
   margin-top: 0;
 }

package/corpus/templates/content/app/hooks/use-document-properties.ts

@@ -5,6 +5,7 @@ import type {
   DeleteDocumentPropertyRequest,
   DocumentPropertiesResponse,
   DuplicateDocumentPropertyRequest,
+  ReorderDocumentPropertyRequest,
   SetDocumentPropertyRequest,
 } from "@shared/api";
 
@@ -79,6 +80,26 @@ export function useDuplicateDocumentProperty(documentId: string) {
   });
 }
 
+export function useReorderDocumentProperty(documentId: string) {
+  const queryClient = useQueryClient();
+  return useActionMutation<
+    DocumentPropertiesResponse,
+    ReorderDocumentPropertyRequest
+  >("reorder-document-property", {
+    onSuccess: () => {
+      queryClient.invalidateQueries({
+        queryKey: ["action", "list-document-properties", { documentId }],
+      });
+      queryClient.invalidateQueries({
+        queryKey: ["action", "get-document", { id: documentId }],
+      });
+      queryClient.invalidateQueries({
+        queryKey: ["action", "get-content-database"],
+      });
+    },
+  });
+}
+
 export function useDeleteDocumentProperty(documentId: string) {
   const queryClient = useQueryClient();
   return useActionMutation<

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

@@ -102,6 +102,17 @@ export const contentDatabases = table("content_databases", {
   documentId: text("document_id").notNull(),
   title: text("title").notNull().default("Untitled database"),
   viewConfigJson: text("view_config_json").notNull().default("{}"),
+  // Single source of truth for the primary "Content" Blocks field — the one
+  // backed by `documents.content`. A DB-enforced single-primary invariant: at
+  // most one property id lives here, so two concurrent seeds can never produce
+  // two aliasing primaries. NULL means there is currently no primary Blocks
+  // field (never seeded, or the primary was intentionally deleted).
+  primaryBlocksPropertyId: text("primary_blocks_property_id"),
+  // 1 once a database has been seeded with its primary Blocks field at least
+  // once. Distinguishes "never seeded" (legacy database needing backfill) from
+  // "primary intentionally deleted" (seeded once, then removed — must NOT be
+  // reseeded). See delete-document-property.
+  blocksSeeded: integer("blocks_seeded").notNull().default(0),
   createdAt: text("created_at").notNull().default(now()),
   updatedAt: text("updated_at").notNull().default(now()),
 });
@@ -243,4 +254,23 @@ export const documentPropertyValues = table("document_property_values", {
   updatedAt: text("updated_at").notNull().default(now()),
 });
 
+// Independent backing store for ADDITIONAL "Blocks" property fields. The
+// default/primary Blocks field ("Content") is backed by `documents.content`
+// (so the existing TipTap/Yjs editor, collab, and existing data migrate for
+// free). Every other Blocks field on a row gets its OWN content here, keyed by
+// (documentId, propertyId) — guaranteeing no two Blocks fields ever alias the
+// same content. Stored as markdown, same shape as `documents.content`.
+export const documentBlockFieldContents = table(
+  "document_block_field_contents",
+  {
+    id: text("id").primaryKey(),
+    ownerEmail: text("owner_email").notNull().default("local@localhost"),
+    documentId: text("document_id").notNull(),
+    propertyId: text("property_id").notNull(),
+    content: text("content").notNull().default(""),
+    createdAt: text("created_at").notNull().default(now()),
+    updatedAt: text("updated_at").notNull().default(now()),
+  },
+);
+
 export const documentShares = createSharesTable("document_shares");

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

@@ -1,4 +1,17 @@
 import { runMigrations } from "@agent-native/core/db";
+import { repairUnseededBlocksFields } from "../../actions/_property-utils.js";
+
+function scheduleBlocksRepairRetry(attempt = 1): void {
+  const delayMs = Math.min(30_000 * attempt, 5 * 60_000);
+  const timeout = setTimeout(() => {
+    repairUnseededBlocksFields().catch(() => {
+      if (attempt < 5) scheduleBlocksRepairRetry(attempt + 1);
+    });
+  }, delayMs);
+  if (typeof timeout === "object" && "unref" in timeout) {
+    timeout.unref();
+  }
+}
 
 const runContentMigrations = runMigrations(
   [
@@ -418,6 +431,68 @@ const runContentMigrations = runMigrations(
         CREATE INDEX IF NOT EXISTS content_database_source_executions_change_set_idx ON content_database_source_executions (change_set_id);
         CREATE INDEX IF NOT EXISTS content_database_source_executions_idempotency_idx ON content_database_source_executions (idempotency_key)`,
     },
+    {
+      // Independent backing store for ADDITIONAL "Blocks" property fields. The
+      // primary "Content" Blocks field is backed by documents.content; every
+      // other Blocks field on a row stores its own content here, keyed by
+      // (document_id, property_id), so no two Blocks fields ever share content.
+      version: 48,
+      sql: `CREATE TABLE IF NOT EXISTS document_block_field_contents (
+      id TEXT PRIMARY KEY,
+      owner_email TEXT NOT NULL DEFAULT 'local@localhost',
+      document_id TEXT NOT NULL,
+      property_id TEXT NOT NULL,
+      content TEXT NOT NULL DEFAULT '',
+      created_at TEXT NOT NULL DEFAULT (datetime('now')),
+      updated_at TEXT NOT NULL DEFAULT (datetime('now'))
+    )`,
+    },
+    {
+      version: 49,
+      sql: `CREATE INDEX IF NOT EXISTS document_block_field_contents_document_idx ON document_block_field_contents (document_id);
+        CREATE UNIQUE INDEX IF NOT EXISTS document_block_field_contents_doc_prop_idx ON document_block_field_contents (document_id, property_id)`,
+    },
+    // v50-v52: DB-enforced single-primary Blocks invariant. `primary_blocks_property_id`
+    // is the one source of truth for which property backs `documents.content`;
+    // `blocks_seeded` records that a database was seeded once, so an intentionally
+    // deleted primary is never silently recreated. Both are additive and safe on
+    // existing data.
+    {
+      version: 50,
+      sql: `ALTER TABLE content_databases ADD COLUMN IF NOT EXISTS primary_blocks_property_id TEXT`,
+    },
+    {
+      version: 51,
+      sql: `ALTER TABLE content_databases ADD COLUMN IF NOT EXISTS blocks_seeded INTEGER NOT NULL DEFAULT 0`,
+    },
+    // v52: one-time backfill for LEGACY databases that already had a primary
+    // "Content" Blocks definition (seeded by the previous read-path safety net)
+    // before these columns existed. Point primary_blocks_property_id at that
+    // definition and mark the database seeded. Idempotent: only fills rows that
+    // are still NULL, and re-running is a no-op. Databases with NO primary
+    // definition are intentionally left unseeded — the startup repair seeds them
+    // exactly once via the authenticated path. The correlated subquery picks the
+    // primary definition by its options JSON marker (`"primary":true`); the
+    // simple `%...%` LIKE is portable across SQLite and Postgres.
+    {
+      version: 52,
+      sql: `UPDATE content_databases
+        SET primary_blocks_property_id = (
+              SELECT d.id FROM document_property_definitions d
+              WHERE d.database_id = content_databases.id
+                AND d.type = 'blocks'
+                AND d.options_json LIKE '%"primary":true%'
+              LIMIT 1
+            ),
+            blocks_seeded = 1
+        WHERE primary_blocks_property_id IS NULL
+          AND EXISTS (
+              SELECT 1 FROM document_property_definitions d
+              WHERE d.database_id = content_databases.id
+                AND d.type = 'blocks'
+                AND d.options_json LIKE '%"primary":true%'
+            )`,
+    },
   ],
   { table: "content_migrations" },
 );
@@ -453,4 +528,16 @@ export default async function contentDatabasePlugin(
 ) {
   await runContentMigrations(nitroApp);
   await runContentSourceMigrations(nitroApp);
+  // One-time, boot-time repair: seed the primary "Content" Blocks field for any
+  // legacy database that has never been seeded (blocks_seeded = 0). Idempotent —
+  // the atomic claim in seedDefaultBlocksField makes re-runs no-ops, and it
+  // never runs from a read path, so opening a shared/legacy row stays a pure
+  // read. Failures here must not crash boot; migrations themselves succeeded.
+  try {
+    await repairUnseededBlocksFields();
+  } catch {
+    // Retry in-process so a transient boot-time repair failure does not leave
+    // legacy databases without their primary Blocks field until a full reboot.
+    scheduleBlocksRepairRetry();
+  }
 }

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

@@ -194,6 +194,13 @@ export interface DeleteDocumentPropertyRequest {
   propertyId: string;
 }
 
+export interface ReorderDocumentPropertyRequest {
+  documentId: string;
+  propertyId: string;
+  targetPropertyId: string;
+  position?: "before" | "after";
+}
+
 export interface ContentDatabase {
   id: string;
   documentId: string;

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

@@ -13,6 +13,11 @@ export const EDITABLE_DOCUMENT_PROPERTY_TYPES = [
   "email",
   "phone",
   "relation",
+  // Capacities-style rich-text body field. Each Blocks field is its OWN
+  // independent content (NOT an alias of the page body). The default "Content"
+  // field is backed by `documents.content`; additional Blocks fields each get
+  // their own row in `document_block_field_contents`.
+  "blocks",
 ] as const;
 
 export const COMPUTED_DOCUMENT_PROPERTY_TYPES = [
@@ -44,6 +49,7 @@ export const CREATABLE_DOCUMENT_PROPERTY_TYPES = [
   "url",
   "email",
   "phone",
+  "blocks",
   "id",
   "created_time",
   "created_by",
@@ -91,6 +97,13 @@ export interface DocumentPropertyOptions {
   relation?: {
     databaseId?: string | null;
   };
+  // Set on the default/primary "Content" Blocks field. The primary field is the
+  // one whose content is backed by `documents.content` (the page body editor).
+  // Exactly one Blocks field per database should be primary; additional Blocks
+  // fields store their content independently in `document_block_field_contents`.
+  blocks?: {
+    primary?: boolean;
+  };
   rollup?: {
     relationPropertyId?: string | null;
     targetPropertyId?: string | null;
@@ -137,6 +150,7 @@ export const DOCUMENT_PROPERTY_TYPE_LABELS: Record<
   email: "Email",
   phone: "Phone",
   relation: "Relation",
+  blocks: "Blocks",
   formula: "Formula",
   rollup: "Rollup",
   id: "ID",
@@ -161,6 +175,88 @@ export function isComputedPropertyType(
   return (COMPUTED_DOCUMENT_PROPERTY_TYPES as readonly string[]).includes(type);
 }
 
+// The default name a database's seeded Blocks field gets.
+export const DEFAULT_BLOCKS_FIELD_NAME = "Content";
+
+export function isBlocksPropertyType(type: DocumentPropertyType): boolean {
+  return type === "blocks";
+}
+
+// The primary Blocks field is the one backed by `documents.content`. There is
+// at most one per database; it is the field seeded by default and is what the
+// page-body editor reads/writes.
+export function isPrimaryBlocksField(
+  options: DocumentPropertyOptions,
+): boolean {
+  return options.blocks?.primary === true;
+}
+
+// Word count for a Blocks field's markdown content. Strips the lightest layer
+// of markdown punctuation so a "412 words" table cell reflects prose, not
+// syntax. Kept dependency-free because `shared/properties` is bundled into the
+// browser.
+export function countWords(content: string | null | undefined): number {
+  const text = (content ?? "")
+    // Drop fenced code blocks wholesale — they're not prose.
+    .replace(/```[\s\S]*?```/g, " ")
+    // Strip inline/other markdown punctuation that would split or pad tokens.
+    .replace(/[#>*_`~\-+=|[\]()!]/g, " ")
+    .replace(/\s+/g, " ")
+    .trim();
+  if (!text) return 0;
+  return text.split(" ").filter(Boolean).length;
+}
+
+// "412 words" / "1 word" / "Empty" for table cells.
+export function formatWordCount(content: string | null | undefined): string {
+  const count = countWords(content);
+  if (count === 0) return "Empty";
+  return `${count.toLocaleString()} ${count === 1 ? "word" : "words"}`;
+}
+
+// Render decision for a set of Blocks-field types on one row:
+// - 0 or 1 Blocks field → "solo" (chromeless: no header, just the body).
+// - 2+                  → "multi" (each field gets a header + is collapsible).
+export function blocksRenderMode(blocksFieldCount: number): "solo" | "multi" {
+  return blocksFieldCount >= 2 ? "multi" : "solo";
+}
+
+// Whether deleting a property triggers the "only Blocks field" warning — i.e.
+// it is a Blocks field and it is the last one in the type, so removing it drops
+// the body for every object of this type.
+export function isOnlyBlocksFieldDeletion(args: {
+  type: DocumentPropertyType;
+  blocksFieldCount: number;
+}): boolean {
+  return isBlocksPropertyType(args.type) && args.blocksFieldCount <= 1;
+}
+
+// Where a Blocks field's content is stored. The primary "Content" field lives
+// on `documents.content` (the body); every other Blocks field has its own row
+// in the block-field content store. This single decision keeps reads and writes
+// in lockstep and guarantees no two fields ever share a backing location.
+export type BlocksStorageTarget = "document_body" | "block_field_store";
+
+export function blocksStorageTarget(
+  options: DocumentPropertyOptions,
+): BlocksStorageTarget {
+  return isPrimaryBlocksField(options) ? "document_body" : "block_field_store";
+}
+
+// Resolve a Blocks field's value for one row given the document body and the
+// (additional) block-field content store. Each field reads from exactly one
+// place — the primary from the body, others from their own keyed entry — so two
+// Blocks fields can never resolve to the same content.
+export function resolveBlocksFieldValue(args: {
+  options: DocumentPropertyOptions;
+  documentBody: string | null | undefined;
+  blockFieldContent: string | null | undefined;
+}): string {
+  return blocksStorageTarget(args.options) === "document_body"
+    ? (args.documentBody ?? "")
+    : (args.blockFieldContent ?? "");
+}
+
 export function defaultPropertyOptions(
   type: DocumentPropertyType,
 ): DocumentPropertyOptions {
@@ -198,6 +294,12 @@ export function defaultPropertyOptions(
     };
   }
 
+  // A manually-added Blocks field is independent (non-primary). The seeded
+  // default "Content" field is marked primary explicitly at seed time.
+  if (type === "blocks") {
+    return { blocks: { primary: false } };
+  }
+
   return {};
 }
 
@@ -221,6 +323,10 @@ export function parsePropertyOptions(
                   : null,
             }
           : undefined,
+      blocks:
+        parsed.blocks && typeof parsed.blocks === "object"
+          ? { primary: parsed.blocks.primary === true }
+          : undefined,
       rollup:
         parsed.rollup && typeof parsed.rollup === "object"
           ? {
@@ -436,6 +542,9 @@ export function normalizePropertyValue(
     case "url":
     case "email":
     case "phone":
+    // A Blocks field's value is its markdown content — a plain string, same
+    // shape as `documents.content`.
+    case "blocks":
       return String(value);
     case "date":
       return normalizeDatePropertyValue(value);

package/corpus/templates/forms/.agents/skills/form-responses/SKILL.md

@@ -72,10 +72,20 @@ Each response is stored in the `responses` SQL table:
 | `submittedAt`    | text | ISO timestamp                        |
 | `ip`             | text | Submitter IP when available          |
 | `submitterEmail` | text | Submitter email hint when known      |
+| `pageUrl`        | text | Page the respondent was on, if sent  |
+| `clientSurface`  | text | App surface: web, electron, or tauri |
 
 `submitterEmail` may come from the logged-in Forms session or from trusted
 feedback clients that pass the logged-in user email as submission metadata.
 
+`pageUrl` and `clientSurface` are hidden pass-through fields: trusted embeds
+(e.g. the framework FeedbackButton) forward the URL of the page the respondent
+was on and the runtime shell they were in (`web`, `electron`, or `tauri`) as
+submission metadata, so owners can see which screen and which app feedback came
+from. Both are null for direct fills that send no context, and `clientSurface`
+is allowlisted server-side (unknown values are dropped). The responses table
+surfaces them as "Page" and "Source" columns when any response carries them.
+
 The `data` JSON maps field IDs to values:
 
 ```json

package/corpus/templates/forms/actions/export-responses.ts

@@ -35,6 +35,8 @@ export default defineAction({
         id: r.id,
         submittedAt: r.submittedAt,
         submitterEmail: r.submitterEmail ?? null,
+        pageUrl: r.pageUrl ?? null,
+        clientSurface: r.clientSurface ?? null,
         ...JSON.parse(r.data),
       }));
       fs.writeFileSync(outputPath, JSON.stringify(data, null, 2));
@@ -43,6 +45,8 @@ export default defineAction({
         "ID",
         "Submitted At",
         "Submitter Email",
+        "Page URL",
+        "Source",
         ...fields.map((f: any) => f.label),
       ];
       const rows = responses.map((r) => {
@@ -51,6 +55,8 @@ export default defineAction({
           r.id,
           r.submittedAt,
           r.submitterEmail ?? "",
+          r.pageUrl ?? "",
+          r.clientSurface ?? "",
           ...fields.map((f: any) => {
             const val = data[f.id];
             if (Array.isArray(val)) return val.join("; ");

package/corpus/templates/forms/actions/list-responses.ts

@@ -49,6 +49,8 @@ export default defineAction({
         data: JSON.parse(r.data),
         submittedAt: r.submittedAt,
         submitterEmail: r.submitterEmail ?? null,
+        pageUrl: r.pageUrl ?? null,
+        clientSurface: r.clientSurface ?? null,
       })) as FormResponse[],
       total: (total as any)?.count ?? 0,
       fields: JSON.parse(form.fields),

package/corpus/templates/forms/actions/response-insights.ts

@@ -318,6 +318,8 @@ export default defineAction({
             submittedAt: schema.responses.submittedAt,
             ip: schema.responses.ip,
             submitterEmail: schema.responses.submitterEmail,
+            pageUrl: schema.responses.pageUrl,
+            clientSurface: schema.responses.clientSurface,
           })
           .from(schema.responses)
           .where(responseFilter)