@agent-native/core 0.133.2 → 0.133.3

package/corpus/templates/content/changelog/2026-08-01-large-builder-databases-now-show-rows-immediately-and-finish.md

@@ -0,0 +1,6 @@
+---
+type: improved
+date: 2026-08-01
+---
+
+Large Builder databases now show rows immediately and finish syncing much faster.

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

@@ -10,6 +10,7 @@ This generated matrix tracks whether high-value Content UI operations use the sa
 | 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, and delete database rows                                                      | action-backed         | `add-database-item`, `delete-database-items`, `delete-document`, `duplicate-database-items`, `duplicate-database-item`, `move-database-item`, `set-document-property`                                                                                                                                                                                                                                       | `app/components/editor/DocumentDatabase.tsx`, `app/components/editor/database/DatabaseView.tsx`                                                                                           | Database row backing documents and row ordering are created, duplicated, moved, edited, and deleted.                                                                                                                                                                                      | -                                                                                                                                                                                                                                          | -                | P0             | covered       | `actions/database-row-batch-actions.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          | -                                                                                                                                                                                                                       | -                                | -                              |
 | editor.document-body-and-title                     | editor      | Edit document title, body, icon, image alt text, and precise text                                         | action-backed         | `edit-document`, `pull-document`, `set-image-alt-text`, `transcribe-media`, `update-document`                                                                                                                                                                                                                                                                                                               | `app/components/editor/DocumentEditor.tsx`, `app/components/editor/DocumentDatabase.tsx`, `app/components/editor/extensions/ImageBlock.tsx`, `app/components/editor/SlashCommandMenu.tsx` | Document content, title, icon, image metadata, and text replacements are saved to the same document source.                                                                                                                                                                               | -                                                                                                                                                                                                                                          | -                | P0             | covered       | `actions/content-database-lifecycle.db.test.ts`, `actions/_local-file-documents.test.ts`                                                                                                                                | `document-search-edit`           | -                              |
@@ -26,7 +27,7 @@ This generated matrix tracks whether high-value Content UI operations use the sa
 | source-sync.builder-cms-review-and-write-gates     | source-sync | Review, stage, validate, cancel, and execute Builder CMS source writes                                    | action-backed         | `cancel-prepared-builder-source-update`, `execute-builder-source-batch`, `execute-builder-source-execution`, `prepare-builder-source-execution`, `prepare-builder-source-review`, `preview-builder-source-review`, `review-content-database-source-change-set`, `set-content-database-source-write-mode`, `stage-builder-source-bulk-update`, `stage-builder-revision`, `validate-builder-source-execution` | `app/components/editor/DocumentDatabase.tsx`, `app/components/editor/database/DatabaseView.tsx`, `app/components/editor/database-sources/BuilderSourceReviewDialog.tsx`                   | Builder source write mode, staged reviews, pre-dispatch cancellations, validation records, and bounded execution records are created through guarded actions.                                                                                                                             | -                                                                                                                                                                                                                                          | -                | P0             | covered       | `actions/builder-source-review-gates.db.test.ts`, `actions/cancel-prepared-builder-source-update.db.test.ts`, `actions/execute-builder-source-execution.test.ts`, `actions/stage-builder-source-bulk-update.db.test.ts` | `builder-source-review-readonly` | -                              |
 | source-sync.builder-documents                      | source-sync | List, pull, check, and push Builder docs/blog MDX documents                                               | action-backed         | `check-builder-doc`, `list-builder-docs`, `pull-builder-doc`, `push-builder-doc`                                                                                                                                                                                                                                                                                                                            | `actions/list-builder-docs.ts`, `actions/pull-builder-doc.ts`, `actions/check-builder-doc.ts`, `actions/push-builder-doc.ts`                                                              | Builder docs/blog entries can be read into Content, checked locally, and pushed through guarded Builder document actions.                                                                                                                                                                 | -                                                                                                                                                                                                                                          | -                | P1             | seeded        | -                                                                                                                                                                                                                       | -                                | -                              |
 | source-sync.builder-required-field-materialization | source-sync | Add required Builder publishing fields to a connected collection                                          | action-backed         | `materialize-builder-required-fields`                                                                                                                                                                                                                                                                                                                                                                       | `app/components/editor/database/DatabaseView.tsx`, `app/hooks/use-content-database.ts`                                                                                                    | Required Builder fields are materialized as editable Content properties in one local mutation.                                                                                                                                                                                            | This bounded safe-model setup action is intentionally hidden from the agent tool list; the visible source settings surface invokes it.                                                                                                     | -                | P1             | covered       | `actions/materialize-builder-required-fields.test.ts`                                                                                                                                                                   | -                                | -                              |
-| source-sync.database-source-bindings               | source-sync | Attach, inspect, refresh, disconnect, join, and bind database sources                                     | action-backed         | `add-content-database-source-field-property`, `attach-content-database-source`, `bind-content-database-source-field`, `change-content-database-source-role`, `disconnect-content-database-source`, `get-content-database-source`, `list-builder-cms-models`, `list-notion-database-sources`, `refresh-content-database-source`, `suggest-source-join-key`                                                   | `app/components/editor/DocumentDatabase.tsx`, `app/components/editor/DocumentProperties.tsx`, `app/components/editor/database/DatabaseView.tsx`, `app/hooks/use-content-database.ts`      | Mounted database source metadata, fields, source role, join keys, and source-field/property bindings are stored and refreshed.                                                                                                                                                            | -                                                                                                                                                                                                                                          | -                | 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`          | -                              |
+| source-sync.database-source-bindings               | source-sync | Attach, inspect, refresh, disconnect, join, and bind database sources                                     | action-backed         | `add-content-database-source-field-property`, `attach-content-database-source`, `bind-content-database-source-field`, `change-content-database-source-role`, `disconnect-content-database-source`, `get-content-database-source`, `list-builder-cms-models`, `list-notion-database-sources`, `preview-content-database-source-attach`, `refresh-content-database-source`, `suggest-source-join-key`         | `app/components/editor/DocumentDatabase.tsx`, `app/components/editor/DocumentProperties.tsx`, `app/components/editor/database/DatabaseView.tsx`, `app/hooks/use-content-database.ts`      | Mounted database source metadata, fields, source role, join keys, and source-field/property bindings are stored and refreshed.                                                                                                                                                            | -                                                                                                                                                                                                                                          | -                | 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`          | -                              |
 | source-sync.provider-api-and-staged-datasets       | source-sync | Inspect provider APIs and stage/query/delete large provider datasets                                      | action-backed         | `delete-staged-dataset`, `list-staged-datasets`, `provider-api-catalog`, `provider-api-docs`, `provider-api-request`, `query-staged-dataset`                                                                                                                                                                                                                                                                | `actions/provider-api-catalog.ts`, `actions/provider-api-docs.ts`, `actions/provider-api-request.ts`, `actions/query-staged-dataset.ts`                                                   | Provider API metadata and staged dataset scratch storage support scoped agent/source analysis.                                                                                                                                                                                            | -                                                                                                                                                                                                                                          | -                | P1             | seeded        | -                                                                                                                                                                                                                       | -                                | -                              |
 | versions.history-and-restore                       | versions    | Open version history and restore a previous document version                                              | action-backed         | `list-document-versions`, `restore-document-version`                                                                                                                                                                                                                                                                                                                                                        | `app/components/editor/VersionHistoryPanel.tsx`, `app/hooks/use-document-versions.ts`                                                                                                     | Document versions are listed and selected versions can restore the document while snapshotting current state.                                                                                                                                                                             | -                                                                                                                                                                                                                                          | -                | P0             | seeded        | -                                                                                                                                                                                                                       | -                                | -                              |
 | workspace.spaces-and-files-catalog                 | workspace   | Provision, navigate, and delete Content spaces through Files and Workspaces with personal expansion state | action-backed         | `backfill-content-files`, `create-content-space`, `delete-content-space`, `ensure-content-spaces`, `get-content-sidebar-state`, `list-content-spaces`, `update-content-sidebar-state`                                                                                                                                                                                                                       | `app/components/sidebar/DocumentSidebar.tsx`, `app/hooks/use-content-spaces.ts`                                                                                                           | Personal and organization spaces, user-created workspaces, their canonical Files databases, the personal Workspaces catalog, and each user's sidebar expansion state are stored and reconciled in SQL; deleting a user-created workspace atomically removes its catalog row and contents. | -                                                                                                                                                                                                                                          | -                | P0             | covered       | `actions/content-spaces.db.test.ts`, `actions/content-files.db.test.ts`, `actions/content-sidebar-state.test.ts`                                                                                                        | -                                | -                              |

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

@@ -266,6 +266,30 @@ export const parityMatrix: ParityRow[] = [
     coverageRefs: ["actions/content-database-lifecycle.db.test.ts"],
     evalScenarioIds: ["database-source-scope"],
   },
+  {
+    id: "database.table-query-page",
+    surface: "database",
+    label: "Query one constrained page while retaining database metadata",
+    uiEntrypoints: [
+      "app/components/editor/database/DatabaseView.tsx",
+      "app/hooks/use-content-database.ts",
+    ],
+    durableEffect: null,
+    uiImplementation:
+      "The table view loads changed search, filter, and sort results through a page-only action while the base database response remains visible.",
+    status: "action-backed",
+    actions: ["query-content-database-items"],
+    exception:
+      "This UI-only bounded projection is intentionally hidden with agentTool: false; agents use get-content-database for the complete database contract.",
+    reliabilityRisk: "none",
+    spinePriority: "P0",
+    testCoverage: "covered",
+    followUpPR: null,
+    coverageRefs: [
+      "actions/content-database-lifecycle.db.test.ts",
+      "app/hooks/use-content-database.test.ts",
+    ],
+  },
   {
     id: "database.form-submissions",
     surface: "database",
@@ -402,6 +426,7 @@ export const parityMatrix: ParityRow[] = [
       "get-content-database-source",
       "list-builder-cms-models",
       "list-notion-database-sources",
+      "preview-content-database-source-attach",
       "refresh-content-database-source",
       "suggest-source-join-key",
     ],

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

@@ -276,6 +276,13 @@ export interface ContentDatabaseFilter {
   parentFilterGroupId?: string;
 }
 
+export interface ContentDatabaseTableQuery {
+  search: string;
+  filters: ContentDatabaseFilter[];
+  sorts: ContentDatabaseSort[];
+  filterMode: ContentDatabaseFilterMode;
+}
+
 export type ContentDatabaseColumnCalculation =
   | "count_all"
   | "count_values"
@@ -707,6 +714,10 @@ export interface ContentDatabaseSource {
   fields: ContentDatabaseSourceFieldMapping[];
   rows: ContentDatabaseSourceRow[];
   changeSets: ContentDatabaseSourceChangeSet[];
+  projection?: {
+    rows: "complete" | "page";
+    changeSets: "complete" | "page";
+  };
   bodyHydration?: ContentDatabaseBodyHydrationSummary;
 }
 
@@ -774,17 +785,32 @@ export interface ContentDatabaseResponse {
     hasMore: boolean;
   };
   createdItemId?: string;
+  createdItem?: ContentDatabaseItem;
   createdDocumentId?: string;
   createdDocumentUpdatedAt?: string;
   duplicatedItemId?: string;
   duplicatedDocumentId?: string;
   duplicatedItemIds?: string[];
+  duplicatedItems?: ContentDatabaseItem[];
   duplicatedDocumentIds?: string[];
   deletedItemIds?: string[];
   deletedDocumentIds?: string[];
   timings?: BuilderActionTiming[];
+  tableQueryMode?: "server" | "client-required";
+  /** Client-only optimistic state while real provider rows are being attached. */
+  attachPreview?: {
+    sourceTable: string;
+    fetchedAt: string;
+    importedItemCount?: number;
+    complete?: boolean;
+  };
 }
 
+export type ContentDatabaseItemsPageResponse = Pick<
+  ContentDatabaseResponse,
+  "items" | "source" | "sources" | "pagination" | "tableQueryMode"
+>;
+
 export interface BuilderActionTiming {
   name: string;
   durationMs: number;
@@ -897,6 +923,8 @@ export interface AttachContentDatabaseSourceRequest {
   sourceType?: ContentDatabaseSourceType;
   sourceName?: string;
   sourceTable?: string;
+  /** Projected Builder model fields already visible in the model picker. */
+  builderFieldPaths?: string[];
   /** "items" adds more rows; "details" joins fields onto existing rows. */
   relationshipMode?: "items" | "details";
   join?: ContentDatabaseSourceJoinRequest;
@@ -906,6 +934,31 @@ export interface AttachContentDatabaseSourceRequest {
   offset?: number;
 }
 
+export interface ContentDatabaseSourceAttachmentAck {
+  responseProjection: "ack";
+  databaseId: string;
+  documentId: string;
+  sourceId: string;
+  sourceType: ContentDatabaseSourceType;
+  sourceTable: string;
+  importedItemCount: number;
+  fetchedAt: string;
+}
+
+export type ContentDatabaseSourceAttachmentResult =
+  | ContentDatabaseResponse
+  | ContentDatabaseSourceAttachmentAck;
+
+export interface BuilderCmsAttachPreviewResponse {
+  databaseId: string;
+  documentId: string;
+  sourceTable: string;
+  base: ContentDatabaseResponse;
+  items: ContentDatabaseItem[];
+  fetchedAt: string;
+  hasMore: boolean;
+}
+
 export interface ChangeContentDatabaseSourceRoleRequest {
   databaseId?: string;
   documentId?: string;
@@ -985,6 +1038,7 @@ export interface RefreshContentDatabaseSourceRequest {
   documentId?: string;
   sourceId?: string;
   fullRefresh?: boolean;
+  finishBuilderPagination?: boolean;
   expectedBuilderContinuationOffset?: number;
 }
 
@@ -1259,10 +1313,6 @@ export interface PreviewBuilderSourceReviewResponse {
 }
 
 export interface PrepareBuilderSourceReviewResponse {
-  database: ContentDatabase;
-  properties: DocumentProperty[];
-  items: ContentDatabaseItem[];
-  source: ContentDatabaseSource | null;
   review: ContentDatabaseSourceReviewPayload;
   /**
    * Maps the operator-selected diff identities to the immutable change-set

package/corpus/templates/content/shared/database-query.ts

@@ -0,0 +1,359 @@
+import type {
+  ContentDatabaseFilter,
+  ContentDatabaseFilterMode,
+  ContentDatabaseItem,
+  ContentDatabaseSort,
+  ContentDatabaseTableQuery,
+  DocumentProperty,
+} from "./api.js";
+import { documentPropertyDatePart, formulaValueText } from "./properties.js";
+
+export function applyContentDatabaseTableQuery(
+  items: ContentDatabaseItem[],
+  properties: DocumentProperty[],
+  query: ContentDatabaseTableQuery,
+) {
+  const search = query.search.trim().toLowerCase();
+  const searched = search
+    ? items.filter((item) =>
+        itemSearchText(item, properties).toLowerCase().includes(search),
+      )
+    : items;
+  const activeFilters = query.filters.filter(isActiveFilter);
+  const filtered = activeFilters.length
+    ? searched.filter((item) =>
+        itemMatchesFilterTree(
+          item,
+          properties,
+          activeFilters,
+          query.filterMode,
+        ),
+      )
+    : searched;
+
+  if (query.sorts.length === 0) return filtered;
+  return [...filtered].sort((left, right) => {
+    for (const sort of query.sorts) {
+      const comparison = compareSortValues(
+        itemSortValue(left, properties, sort),
+        itemSortValue(right, properties, sort),
+      );
+      if (comparison !== 0) {
+        return sort.direction === "asc" ? comparison : -comparison;
+      }
+    }
+    return 0;
+  });
+}
+
+export function contentDatabaseTableQueryUsesProperties(
+  query: ContentDatabaseTableQuery,
+  propertyIds: ReadonlySet<string>,
+) {
+  if (propertyIds.size === 0) return false;
+  if (query.search.trim()) return true;
+  return [...query.filters, ...query.sorts].some(
+    (constraint) =>
+      constraint.key !== "name" && propertyIds.has(constraint.key),
+  );
+}
+
+function itemMatchesFilterTree(
+  item: ContentDatabaseItem,
+  properties: DocumentProperty[],
+  filters: ContentDatabaseFilter[],
+  filterMode: ContentDatabaseFilterMode,
+) {
+  const rootFilters = filters.filter((filter) => !filter.parentFilterGroupId);
+  const nestedGroups = new Map<string, ContentDatabaseFilter[]>();
+  for (const filter of filters) {
+    if (!filter.parentFilterGroupId || !filter.filterGroupId) continue;
+    nestedGroups.set(filter.filterGroupId, [
+      ...(nestedGroups.get(filter.filterGroupId) ?? []),
+      filter,
+    ]);
+  }
+  const matches = [
+    ...rootFilters.map((filter) => itemMatchesFilter(item, properties, filter)),
+    ...[...nestedGroups.values()].map((group) =>
+      combineMatches(
+        group.map((filter) => itemMatchesFilter(item, properties, filter)),
+        filterMode,
+      ),
+    ),
+  ];
+  return combineMatches(matches, filterMode);
+}
+
+function combineMatches(
+  matches: boolean[],
+  filterMode: ContentDatabaseFilterMode,
+) {
+  if (matches.length === 0) return true;
+  return filterMode === "or" ? matches.some(Boolean) : matches.every(Boolean);
+}
+
+function isActiveFilter(filter: ContentDatabaseFilter) {
+  if (
+    !["is_empty", "is_not_empty", "is_checked", "is_unchecked"].includes(
+      filter.operator,
+    )
+  ) {
+    return selectedFilterValues(filter.value).length > 0;
+  }
+  return true;
+}
+
+function itemMatchesFilter(
+  item: ContentDatabaseItem,
+  properties: DocumentProperty[],
+  filter: ContentDatabaseFilter,
+) {
+  const value = itemFilterValue(item, properties, filter.key);
+  const property = itemFilterProperty(item, properties, filter.key);
+  if (filter.operator === "is_empty") return !value.trim();
+  if (filter.operator === "is_not_empty") return !!value.trim();
+  if (filter.operator === "is_checked") return property?.value === true;
+  if (filter.operator === "is_unchecked") return property?.value !== true;
+
+  if (filter.operator === "greater_than" || filter.operator === "less_than") {
+    const current = propertyNumberValue(property);
+    const target = Number(filter.value.trim());
+    if (!Number.isFinite(current) || !Number.isFinite(target)) return false;
+    return filter.operator === "greater_than"
+      ? current > target
+      : current < target;
+  }
+
+  if (
+    filter.operator === "before" ||
+    filter.operator === "after" ||
+    filter.operator === "between"
+  ) {
+    const current = propertyDateValue(property);
+    if (!Number.isFinite(current)) return false;
+    if (filter.operator === "between") {
+      const range = filterDateRange(filter.value);
+      return !!range && current >= range[0] && current <= range[1];
+    }
+    const target = new Date(filter.value.trim()).getTime();
+    if (!Number.isFinite(target)) return false;
+    return filter.operator === "before" ? current < target : current > target;
+  }
+
+  const candidateValues = itemFilterCandidateValues(
+    item,
+    properties,
+    filter.key,
+  ).map((candidate) => candidate.trim().toLowerCase());
+  const selectedValues = selectedFilterValues(filter.value).map((candidate) =>
+    candidate.trim().toLowerCase(),
+  );
+  const normalizedValue = value.trim().toLowerCase();
+  const normalizedFilter = selectedValues[0] ?? "";
+  const usesDiscreteValues =
+    property?.definition.type === "select" ||
+    property?.definition.type === "status" ||
+    property?.definition.type === "multi_select" ||
+    property?.definition.type === "person";
+  if (
+    usesDiscreteValues &&
+    (filter.operator === "equals" || filter.operator === "contains")
+  ) {
+    return selectedValues.some((filterValue) =>
+      candidateValues.includes(filterValue),
+    );
+  }
+  if (usesDiscreteValues && filter.operator === "does_not_equal") {
+    return selectedValues.every(
+      (filterValue) => !candidateValues.includes(filterValue),
+    );
+  }
+  if (filter.operator === "equals") {
+    return candidateValues.includes(normalizedFilter);
+  }
+  if (filter.operator === "does_not_equal") {
+    return !candidateValues.includes(normalizedFilter);
+  }
+  return normalizedValue.includes(normalizedFilter);
+}
+
+function selectedFilterValues(value: string) {
+  const trimmed = value.trim();
+  if (!trimmed) return [];
+  try {
+    const parsed = JSON.parse(trimmed) as unknown;
+    if (!Array.isArray(parsed)) return [trimmed];
+    return [
+      ...new Set(
+        parsed
+          .filter((item): item is string => typeof item === "string")
+          .map((item) => item.trim())
+          .filter(Boolean),
+      ),
+    ];
+  } catch {
+    return [trimmed];
+  }
+}
+
+function filterDateRange(value: string): [number, number] | null {
+  const values = selectedFilterValues(value);
+  const start = new Date(values[0] ?? "").getTime();
+  const end = new Date(values[1] ?? "").getTime();
+  if (!Number.isFinite(start) || !Number.isFinite(end)) return null;
+  return start <= end ? [start, end] : [end, start];
+}
+
+function itemSearchText(
+  item: ContentDatabaseItem,
+  properties: DocumentProperty[],
+) {
+  return [
+    item.document.title || "Untitled",
+    ...properties.map((property) =>
+      propertyValueText(
+        item.properties.find(
+          (candidate) => candidate.definition.id === property.definition.id,
+        ) ?? property,
+      ),
+    ),
+  ].join(" ");
+}
+
+function itemSortValue(
+  item: ContentDatabaseItem,
+  properties: DocumentProperty[],
+  sort: ContentDatabaseSort,
+) {
+  if (sort.key === "name") return item.document.title || "";
+  return propertyValueText(
+    item.properties.find((candidate) => candidate.definition.id === sort.key) ??
+      properties.find((candidate) => candidate.definition.id === sort.key) ??
+      null,
+  );
+}
+
+function itemFilterValue(
+  item: ContentDatabaseItem,
+  properties: DocumentProperty[],
+  key: string,
+) {
+  if (key === "name") return item.document.title || "";
+  return propertyValueText(itemFilterProperty(item, properties, key));
+}
+
+function itemFilterProperty(
+  item: ContentDatabaseItem,
+  properties: DocumentProperty[],
+  key: string,
+) {
+  if (key === "name") return null;
+  return (
+    item.properties.find((candidate) => candidate.definition.id === key) ??
+    properties.find((candidate) => candidate.definition.id === key) ??
+    null
+  );
+}
+
+function itemFilterCandidateValues(
+  item: ContentDatabaseItem,
+  properties: DocumentProperty[],
+  key: string,
+) {
+  if (key === "name") return [item.document.title || ""];
+  const property = itemFilterProperty(item, properties, key);
+  if (!property || property.value === null || property.value === undefined) {
+    return [""];
+  }
+  if (Array.isArray(property.value)) {
+    return property.value.flatMap((id) => {
+      const optionName =
+        property.definition.options.options?.find((option) => option.id === id)
+          ?.name ?? id;
+      return [id, optionName];
+    });
+  }
+  if (
+    property.definition.type === "select" ||
+    property.definition.type === "status"
+  ) {
+    const id = String(property.value);
+    const optionName =
+      property.definition.options.options?.find((option) => option.id === id)
+        ?.name ?? id;
+    return [id, optionName];
+  }
+  return [propertyValueText(property)];
+}
+
+function propertyValueText(property: DocumentProperty | null | undefined) {
+  if (!property || property.value === null || property.value === undefined) {
+    return "";
+  }
+  if (Array.isArray(property.value)) {
+    return property.value
+      .map(
+        (id) =>
+          property.definition.options.options?.find(
+            (option) => option.id === id,
+          )?.name ?? id,
+      )
+      .join(" ");
+  }
+  if (
+    property.definition.type === "select" ||
+    property.definition.type === "status"
+  ) {
+    return (
+      property.definition.options.options?.find(
+        (option) => option.id === String(property.value),
+      )?.name ?? String(property.value)
+    );
+  }
+  if (property.definition.type === "checkbox") {
+    return property.value ? "Checked" : "Unchecked";
+  }
+  return formulaValueText(property.value);
+}
+
+function compareSortValues(left: string, right: string) {
+  const leftNumber = Number(left);
+  const rightNumber = Number(right);
+  if (
+    left.trim() &&
+    right.trim() &&
+    Number.isFinite(leftNumber) &&
+    Number.isFinite(rightNumber)
+  ) {
+    return leftNumber - rightNumber;
+  }
+  return left.localeCompare(right, undefined, {
+    numeric: true,
+    sensitivity: "base",
+  });
+}
+
+function propertyNumberValue(property: DocumentProperty | null | undefined) {
+  if (
+    !property ||
+    property.value === null ||
+    property.value === undefined ||
+    property.value === ""
+  ) {
+    return Number.NaN;
+  }
+  const value =
+    typeof property.value === "number"
+      ? property.value
+      : Number(String(property.value).trim());
+  return Number.isFinite(value) ? value : Number.NaN;
+}
+
+function propertyDateValue(property: DocumentProperty | null | undefined) {
+  if (!property || !property.value) return Number.NaN;
+  const value = new Date(
+    documentPropertyDatePart(property.value, "start") || String(property.value),
+  ).getTime();
+  return Number.isFinite(value) ? value : Number.NaN;
+}

package/dist/client/use-action.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"use-action.d.ts","sourceRoot":"","sources":["../../src/client/use-action.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"use-action.d.ts","sourceRoot":"","sources":["../../src/client/use-action.ts"],"names":[],"mappings":"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"}

package/dist/client/use-action.js

@@ -130,6 +130,12 @@ function appendActionQueryParam(qs, key, value) {
         }
         return;
     }
+    if (typeof value === "object") {
+        // defineAction restores JSON strings when the schema expects an object.
+        // Preserve nested GET params instead of collapsing them to "[object Object]".
+        qs.append(key, JSON.stringify(value));
+        return;
+    }
     qs.append(key, String(value));
 }
 /**