@marktiderman/genesis-core 1.4.0 → 1.5.0

package/README.md

@@ -140,3 +140,84 @@ try {
 the root and `@marktiderman/genesis-core/schema`. Check with
 `isDataWriteError(error)` rather than `instanceof`, which fails when two copies
 of the package are installed.
+
+### Field-level errors
+
+A `DataWriteError` may carry `fields`: field (column) name → a message safe to
+show by that input. `useResourceForm` puts each one on its field
+(`setError(field, { type: "server" })`), focuses the first, and sets
+`errors.root` to the error's message as the summary; a field the form does not
+show appears only in the summary.
+
+`createSupabaseProvider` fills `fields` where Postgres says which column it
+means (`fieldErrorsFromPostgrest`), and replaces the error's message with a
+plain sentence (the raw text stays on `cause`):
+
+| Code | Read from | Field message | Error message |
+| --- | --- | --- | --- |
+| `23505` unique | `details`: `Key (email)=(…) already exists.` | "This value is already in use." (several columns: "This combination is already in use.") | "Email is already in use." |
+| `23502` not null | `message`: `null value in column "title" …` | "This field is required." | "Title is required." |
+| `23503` foreign key (insert/update) | `details`: `Key (owner_id)=(…) is not present in table …` | "The selected item doesn't exist." | "Owner Id: the selected item doesn't exist." |
+
+Only plain column names are taken from the store's text; the values it echoes
+and constraint names never reach a message. Anything else (expression indexes,
+check constraints) is left unmapped. Your own provider or `prepare` rule can
+throw `new DataWriteError("invalid", "…", { fields: { slug: "Pick another slug." } })`.
+
+## Mutation modes
+
+`useResource` (its `create`, `update`, `remove`) and `useResourceForm` take
+`mutationMode`:
+
+| Mode | Cache | Provider | Returned promise / `onSuccess` |
+| --- | --- | --- | --- |
+| `"pessimistic"` (default) | refetched after the write | at once | after the write |
+| `"optimistic"` | patched at once; put back if the write fails | at once | at once |
+| `"undoable"` | patched at once; put back on undo or failure | after `undoDelayMs` (default 5000) unless undone | at once |
+
+- **Failures** in `optimistic` / `undoable` mode go to `onError` (the caller
+  was already told it worked, and the cache has been put back). Show them
+  there. `useResourceForm` also puts them on the form, if it is still open.
+- **The undo control is yours.** Core has no UI: `onUndoable(write)` is called
+  with `{ resource, kind, id, strategy, delayMs, undo(), commit() }`.
+  genesis-ui's `ResourceForm` and `ResourcePage` show a sonner toast with an
+  Undo button.
+- **A provider that serves `undo`** (`capabilities().undo === true` and an
+  `undo` method) gets an `undoable` write at once; `undo()` then calls
+  `provider.undo(resource, { auditId })` with the audit id the write returned
+  (`strategy: "provider"`). Without an audit id no undo is offered.
+- **Leaving sends.** When the hook unmounts during the delay (the form closes,
+  the route changes), waiting writes are sent at once, as React Admin does.
+  Closing or reloading the tab also sends them, and holds the page with the
+  browser's prompt so the requests can finish.
+- **What is patched:** an update merges the values into the row in every
+  cached list (`[resource, "list", …]`) and detail (`[resource, "detail", id,
+  …]`); a delete removes the row and lowers `total`. A create patches nothing
+  (its id and place in a sorted list are the server's), so `optimistic` /
+  `undoable` only change when it is sent and when the caller moves on. A
+  rollback restores only the row it patched, so concurrent writes on other
+  rows survive.
+- **Refetching waits.** While an optimistic or undoable write on a resource is
+  pending, the hooks hold off invalidating `[resource]`; the last write to
+  settle refetches. Other code that invalidates the resource (or a window-focus
+  refetch) during the delay shows the server's rows until then.
+
+```ts
+const tasks = useResource("tasks", {
+  mutationMode: "undoable",
+  onUndoable: (write) => toast("Deleted.", { action: { label: "Undo", onClick: () => void write.undo() } }),
+  onError: (error) => toast.error(error.message),
+});
+await tasks.remove(id); // resolves at once; sent in 5 s unless undone
+```
+
+## Unsaved changes
+
+`useResourceForm({ warnWhenUnsaved: true })` (default off) warns while the
+form is dirty: the browser's prompt on closing or reloading the tab, and
+`confirmLeave()` for in-app navigation. It returns `isDirty` (false again once
+a save succeeds or is handed off) and `confirmLeave()` (true when it is fine to
+leave; asks with `window.confirm` otherwise). For other state,
+`useUnsavedChangesGuard({ when, message, confirm })` gives the same
+`confirmLeave` and `beforeunload` handling. Neither depends on a router; see
+genesis-ui's SKILL.md "Unsaved changes" for React Router and TanStack Router.

package/dist/{chunk-6MBACQYA.js → chunk-5NHR6ZXS.js}

@@ -5,6 +5,11 @@ var DataWriteError = class extends Error {
   currentVersion;
   /** The store's own error code, when it gave one. */
   code;
+  /**
+   * Per-field messages (field name → safe message), when the store said which
+   * values it rejected. See `DataWriteErrorOptions.fields`.
+   */
+  fields;
   constructor(outcome, message, options = {}) {
     super(message, options.cause === void 0 ? void 0 : { cause: options.cause });
     this.name = "DataWriteError";
@@ -12,6 +17,9 @@ var DataWriteError = class extends Error {
     this.current = options.current;
     this.currentVersion = options.currentVersion;
     if (options.code !== void 0) this.code = options.code;
+    if (options.fields && Object.keys(options.fields).length > 0) {
+      this.fields = Object.freeze({ ...options.fields });
+    }
   }
 };
 function isDataWriteError(error) {
@@ -19,5 +27,5 @@ function isDataWriteError(error) {
 }
 
 export { DataWriteError, isDataWriteError };
-//# sourceMappingURL=chunk-6MBACQYA.js.map
-//# sourceMappingURL=chunk-6MBACQYA.js.map
+//# sourceMappingURL=chunk-5NHR6ZXS.js.map
+//# sourceMappingURL=chunk-5NHR6ZXS.js.map

package/dist/chunk-5NHR6ZXS.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/schema/write-outcome.ts"],"names":[],"mappings":";AAuDO,IAAM,cAAA,GAAN,cAA6B,KAAA,CAAM;AAAA,EAC/B,OAAA;AAAA,EACA,OAAA;AAAA,EACA,cAAA;AAAA;AAAA,EAEA,IAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAKA,MAAA;AAAA,EAET,WAAA,CAAY,OAAA,EAAuB,OAAA,EAAiB,OAAA,GAAiC,EAAC,EAAG;AACvF,IAAA,KAAA,CAAM,OAAA,EAAS,QAAQ,KAAA,KAAU,MAAA,GAAY,SAAY,EAAE,KAAA,EAAO,OAAA,CAAQ,KAAA,EAAO,CAAA;AACjF,IAAA,IAAA,CAAK,IAAA,GAAO,gBAAA;AACZ,IAAA,IAAA,CAAK,OAAA,GAAU,OAAA;AACf,IAAA,IAAA,CAAK,UAAU,OAAA,CAAQ,OAAA;AACvB,IAAA,IAAA,CAAK,iBAAiB,OAAA,CAAQ,cAAA;AAC9B,IAAA,IAAI,OAAA,CAAQ,IAAA,KAAS,MAAA,EAAW,IAAA,CAAK,OAAO,OAAA,CAAQ,IAAA;AACpD,IAAA,IAAI,OAAA,CAAQ,UAAU,MAAA,CAAO,IAAA,CAAK,QAAQ,MAAM,CAAA,CAAE,SAAS,CAAA,EAAG;AAC5D,MAAA,IAAA,CAAK,SAAS,MAAA,CAAO,MAAA,CAAO,EAAE,GAAG,OAAA,CAAQ,QAAQ,CAAA;AAAA,IACnD;AAAA,EACF;AACF;AAMO,SAAS,iBAAiB,KAAA,EAAyC;AACxE,EAAA,OACE,iBAAiB,KAAA,IACjB,KAAA,CAAM,SAAS,gBAAA,IACf,OAAQ,MAAgC,OAAA,KAAY,QAAA;AAExD","file":"chunk-5NHR6ZXS.js","sourcesContent":["// ---------------------------------------------------------------------------\n// Why a write did not save (DATA-STUDIO.md \"Write safety\")\n//\n// A write that changes nothing is never reported as \"permission denied\" by\n// assumption. The provider re-reads the row and says what actually happened.\n// ---------------------------------------------------------------------------\n\nimport type { DataRow } from \"./types\";\n\n/**\n * - `conflict`: someone else changed the row since it was read. `current`\n *   carries the row as it is now.\n * - `gone`: the row was deleted, or is no longer visible to this user. The\n *   two cannot be told apart without a privileged look at the table, which\n *   would show this user a fact about a row they cannot see.\n * - `forbidden`: the row is visible and unchanged, but the app or the\n *   database does not let this user make this change. Only reported when\n *   that is proven, never assumed from \"zero rows changed\".\n * - `invalid`: the store rejected the value (type, constraint, not-null).\n * - `audit_failed`: the audit entry could not be written, so the edit was\n *   rolled back with it.\n * - `unauthenticated`: no signed-in user, or the session expired.\n * - `error`: anything else. The edit did not commit.\n */\nexport type WriteOutcome =\n  | \"conflict\"\n  | \"gone\"\n  | \"forbidden\"\n  | \"invalid\"\n  | \"audit_failed\"\n  | \"unauthenticated\"\n  | \"error\";\n\nexport interface DataWriteErrorOptions {\n  /** The row as it is now, for a `conflict`. Only fields the user may read. */\n  current?: DataRow;\n  /** The row's current version token, for a `conflict`. */\n  currentVersion?: string | null;\n  /**\n   * The store's own error code, when it gave one (a Postgres SQLSTATE such as\n   * `23505`, or a PostgREST code such as `PGRST301`).\n   */\n  code?: string;\n  /**\n   * Per-field messages, keyed by field (column) name, for a write the store\n   * rejected because of particular values. Each message is safe to show next\n   * to its input: plain words, never the store's raw text or the value.\n   * `useResourceForm` puts each one on its field.\n   */\n  fields?: Record<string, string>;\n  /** The underlying error, kept for logging. */\n  cause?: unknown;\n}\n\n/** Thrown by a provider when a write did not commit. */\nexport class DataWriteError extends Error {\n  readonly outcome: WriteOutcome;\n  readonly current?: DataRow;\n  readonly currentVersion?: string | null;\n  /** The store's own error code, when it gave one. */\n  readonly code?: string;\n  /**\n   * Per-field messages (field name → safe message), when the store said which\n   * values it rejected. See `DataWriteErrorOptions.fields`.\n   */\n  readonly fields?: Readonly<Record<string, string>>;\n\n  constructor(outcome: WriteOutcome, message: string, options: DataWriteErrorOptions = {}) {\n    super(message, options.cause === undefined ? undefined : { cause: options.cause });\n    this.name = \"DataWriteError\";\n    this.outcome = outcome;\n    this.current = options.current;\n    this.currentVersion = options.currentVersion;\n    if (options.code !== undefined) this.code = options.code;\n    if (options.fields && Object.keys(options.fields).length > 0) {\n      this.fields = Object.freeze({ ...options.fields });\n    }\n  }\n}\n\n/**\n * `instanceof` fails when two copies of this package are installed, so check\n * the shape instead.\n */\nexport function isDataWriteError(error: unknown): error is DataWriteError {\n  return (\n    error instanceof Error &&\n    error.name === \"DataWriteError\" &&\n    typeof (error as { outcome?: unknown }).outcome === \"string\"\n  );\n}\n"]}

package/dist/chunk-BQOJX67X.js

@@ -0,0 +1,31 @@
+import { useDataProvider } from './chunk-GGSXSI6Z.js';
+import { useQuery } from '@tanstack/react-query';
+
+var providerIds = /* @__PURE__ */ new WeakMap();
+var nextProviderId = 1;
+function providerId(provider) {
+  let id = providerIds.get(provider);
+  if (id === void 0) {
+    id = nextProviderId++;
+    providerIds.set(provider, id);
+  }
+  return id;
+}
+function capabilitiesQueryKey(provider, resource) {
+  return ["__capabilities", providerId(provider), resource ?? ""];
+}
+function useCapabilities(resource, options = {}) {
+  const provider = useDataProvider();
+  return useQuery({
+    queryKey: capabilitiesQueryKey(provider, resource),
+    queryFn: () => provider.capabilities(resource),
+    enabled: (options.enabled ?? true) && !!provider.capabilities,
+    // Fresh for as long as this provider is in use; a swapped-out provider's
+    // entry has no observers and is collected after the usual gcTime.
+    staleTime: Infinity
+  });
+}
+
+export { capabilitiesQueryKey, useCapabilities };
+//# sourceMappingURL=chunk-BQOJX67X.js.map
+//# sourceMappingURL=chunk-BQOJX67X.js.map

package/dist/chunk-BQOJX67X.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/hooks/use-capabilities.ts"],"names":[],"mappings":";;;AAMA,IAAM,WAAA,uBAAkB,OAAA,EAAwB;AAChD,IAAI,cAAA,GAAiB,CAAA;AAErB,SAAS,WAAW,QAAA,EAA0B;AAC5C,EAAA,IAAI,EAAA,GAAK,WAAA,CAAY,GAAA,CAAI,QAAQ,CAAA;AACjC,EAAA,IAAI,OAAO,MAAA,EAAW;AACpB,IAAA,EAAA,GAAK,cAAA,EAAA;AACL,IAAA,WAAA,CAAY,GAAA,CAAI,UAAU,EAAE,CAAA;AAAA,EAC9B;AACA,EAAA,OAAO,EAAA;AACT;AAQO,SAAS,oBAAA,CAAqB,UAAkB,QAAA,EAAkD;AACvG,EAAA,OAAO,CAAC,gBAAA,EAAkB,UAAA,CAAW,QAAQ,CAAA,EAAG,YAAY,EAAE,CAAA;AAChE;AAOO,SAAS,eAAA,CACd,QAAA,EACA,OAAA,GAAiC,EAAC,EACI;AACtC,EAAA,MAAM,WAAW,eAAA,EAAgB;AACjC,EAAA,OAAO,QAAA,CAA+B;AAAA,IACpC,QAAA,EAAU,oBAAA,CAAqB,QAAA,EAAU,QAAQ,CAAA;AAAA,IACjD,OAAA,EAAS,MAAM,QAAA,CAAS,YAAA,CAAc,QAAQ,CAAA;AAAA,IAC9C,UAAU,OAAA,CAAQ,OAAA,IAAW,IAAA,KAAS,CAAC,CAAC,QAAA,CAAS,YAAA;AAAA;AAAA;AAAA,IAGjD,SAAA,EAAW;AAAA,GACZ,CAAA;AACH","file":"chunk-BQOJX67X.js","sourcesContent":["import { useQuery, type UseQueryResult } from \"@tanstack/react-query\";\nimport { useDataProvider } from \"../provider/context\";\nimport type { ProviderCapabilities } from \"../schema/types\";\n\n// A stable id per provider object, so capabilities cached for one provider\n// are never served for another that shares the same QueryClient.\nconst providerIds = new WeakMap<object, number>();\nlet nextProviderId = 1;\n\nfunction providerId(provider: object): number {\n  let id = providerIds.get(provider);\n  if (id === undefined) {\n    id = nextProviderId++;\n    providerIds.set(provider, id);\n  }\n  return id;\n}\n\n/**\n * The query key for `provider`'s capabilities for `resource`. It includes\n * the provider's identity: swapping the provider (another tenant, a\n * different store) asks the new one instead of reusing the old answer.\n * @internal\n */\nexport function capabilitiesQueryKey(provider: object, resource: string | undefined): readonly unknown[] {\n  return [\"__capabilities\", providerId(provider), resource ?? \"\"];\n}\n\n/**\n * What the data provider can do for `resource` (`provider.capabilities`),\n * cached per provider and resource. `data` stays undefined for a provider\n * that doesn't report capabilities, so a UI keeps its defaults.\n */\nexport function useCapabilities(\n  resource: string | undefined,\n  options: { enabled?: boolean } = {},\n): UseQueryResult<ProviderCapabilities> {\n  const provider = useDataProvider();\n  return useQuery<ProviderCapabilities>({\n    queryKey: capabilitiesQueryKey(provider, resource),\n    queryFn: () => provider.capabilities!(resource),\n    enabled: (options.enabled ?? true) && !!provider.capabilities,\n    // Fresh for as long as this provider is in use; a swapped-out provider's\n    // entry has no observers and is collected after the usual gcTime.\n    staleTime: Infinity,\n  });\n}\n"]}

package/dist/{chunk-P4OIIRQS.js → chunk-DVW5GXWZ.js}

@@ -1,3 +1,4 @@
+import { invalidateResource, useDelayedWrites, executeWrite, cachedRecord } from './chunk-QH4P5MI2.js';
 import { relatedKeys } from './chunk-7NUL32W7.js';
 import { useDataProvider } from './chunk-GGSXSI6Z.js';
 import { useState, useCallback, useMemo } from 'react';
@@ -20,6 +21,8 @@ function useResource(resource, options = {}) {
     defaultSort,
     defaultFilters,
     defaultPerPage = 25,
+    defaultPage = 1,
+    defaultSearch = "",
     select,
     searchFields: searchFieldsOption,
     enabled = true,
@@ -28,15 +31,18 @@ function useResource(resource, options = {}) {
     onCreateSuccess,
     onUpdateSuccess,
     onDeleteSuccess,
-    onError
+    onError,
+    mutationMode = "pessimistic",
+    undoDelayMs,
+    onUndoable
   } = options;
   const provider = useDataProvider();
   const queryClient = useQueryClient();
   const [sort, setSortRaw] = useState(defaultSort);
   const [filters, setFiltersRaw] = useState(defaultFilters ?? []);
-  const [page, setPage] = useState(1);
+  const [page, setPage] = useState(Math.max(1, Math.floor(defaultPage)));
   const [perPage, setPerPageRaw] = useState(defaultPerPage);
-  const [searchQuery, setSearchQuery] = useState("");
+  const [searchQuery, setSearchQuery] = useState(defaultSearch);
   const defaultFiltersKey = stableFilterKey(defaultFilters);
   const [syncedFiltersKey, setSyncedFiltersKey] = useState(defaultFiltersKey);
   if (defaultFiltersKey !== syncedFiltersKey) {
@@ -84,7 +90,7 @@ function useResource(resource, options = {}) {
   });
   const invalidateAfter = useCallback(
     (event) => {
-      void queryClient.invalidateQueries({ queryKey: [resource] });
+      void invalidateResource(queryClient, resource);
       for (const queryKey of relatedKeys(provider, event, invalidates)) {
         void queryClient.invalidateQueries({ queryKey: [...queryKey] });
       }
@@ -97,37 +103,75 @@ function useResource(resource, options = {}) {
     },
     [resource]
   );
+  const reportError = onError ?? defaultOnError;
+  const delayed = useDelayedWrites();
+  const modeArgs = {
+    queryClient,
+    provider,
+    resource,
+    mode: mutationMode,
+    undoDelayMs,
+    onUndoable,
+    delayed,
+    failedLater: reportError
+  };
   const createMutation = useMutation({
     mutationFn: async (data) => {
-      const result = await provider.create(resource, { data });
-      return result.data;
-    },
-    onSuccess: (data) => {
-      invalidateAfter({ resource, kind: "create", id: data.id, record: data });
-      onCreateSuccess?.(data);
+      const outcome = await executeWrite({
+        ...modeArgs,
+        kind: "create",
+        data,
+        send: async () => {
+          const result = await provider.create(resource, { data });
+          return { record: result.data, audit: result.audit };
+        },
+        committed: (record) => {
+          invalidateAfter({ resource, kind: "create", id: record.id, record });
+          onCreateSuccess?.(record);
+        }
+      });
+      return outcome.status === "committed" ? outcome.record : data;
     },
-    onError: onError ?? defaultOnError
+    onError: reportError
   });
   const updateMutation = useMutation({
     mutationFn: async ({ id, data }) => {
-      const result = await provider.update(resource, { id, data });
-      return result.data;
+      const before = cachedRecord(queryClient, resource, id);
+      const outcome = await executeWrite({
+        ...modeArgs,
+        kind: "update",
+        id,
+        data,
+        send: async () => {
+          const result = await provider.update(resource, { id, data });
+          return { record: result.data, audit: result.audit };
+        },
+        committed: (record) => {
+          invalidateAfter({ resource, kind: "update", id, record });
+          onUpdateSuccess?.(record);
+        }
+      });
+      return outcome.status === "committed" ? outcome.record : { ...before ?? {}, ...data, id: before?.id ?? id };
     },
-    onSuccess: (data, { id }) => {
-      invalidateAfter({ resource, kind: "update", id, record: data });
-      onUpdateSuccess?.(data);
-    },
-    onError: onError ?? defaultOnError
+    onError: reportError
   });
   const deleteMutation = useMutation({
     mutationFn: async (id) => {
-      await provider.deleteOne(resource, { id });
-    },
-    onSuccess: (_data, id) => {
-      invalidateAfter({ resource, kind: "delete", id });
-      onDeleteSuccess?.();
+      await executeWrite({
+        ...modeArgs,
+        kind: "delete",
+        id,
+        send: async () => {
+          const result = await provider.deleteOne(resource, { id });
+          return { record: void 0, audit: result?.audit };
+        },
+        committed: () => {
+          invalidateAfter({ resource, kind: "delete", id });
+          onDeleteSuccess?.();
+        }
+      });
     },
-    onError: onError ?? defaultOnError
+    onError: reportError
   });
   const create = useCallback(
     (data) => createMutation.mutateAsync(data),
@@ -161,5 +205,5 @@ function useResource(resource, options = {}) {
 }
 
 export { useResource };
-//# sourceMappingURL=chunk-P4OIIRQS.js.map
-//# sourceMappingURL=chunk-P4OIIRQS.js.map
+//# sourceMappingURL=chunk-DVW5GXWZ.js.map
+//# sourceMappingURL=chunk-DVW5GXWZ.js.map

package/dist/chunk-DVW5GXWZ.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/hooks/use-resource.ts"],"names":["keepPreviousData","keepPreviousPlaceholder"],"mappings":"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","file":"chunk-DVW5GXWZ.js","sourcesContent":["import { useState, useCallback, useMemo } from \"react\";\nimport {\n  keepPreviousData as keepPreviousPlaceholder,\n  useQuery,\n  useMutation,\n  useQueryClient,\n  type UseQueryResult,\n  type UseMutationResult,\n} from \"@tanstack/react-query\";\nimport { useDataProvider } from \"../provider/context\";\nimport type {\n  BaseRecord,\n  Identifier,\n  SortParam,\n  FilterParam,\n  ListParams,\n  ListResult,\n  InvalidationKey,\n  WriteEvent,\n} from \"../provider/types\";\nimport { relatedKeys } from \"./related-keys\";\nimport {\n  cachedRecord,\n  executeWrite,\n  invalidateResource,\n  useDelayedWrites,\n  type MutationModeOptions,\n} from \"./mutation-mode\";\n\n// ---------------------------------------------------------------------------\n// Options\n// ---------------------------------------------------------------------------\n\nexport interface UseResourceOptions<T> extends MutationModeOptions {\n  defaultSort?: SortParam;\n  /**\n   * Re-synced whenever its value changes (deep-equal, order-independent),\n   * not just its identity — safe to pass a scope/audience-derived array that\n   * changes across renders. This only covers CHANGES on an already-mounted\n   * hook, though: if this starts `undefined` while the real value resolves\n   * asynchronously, gate `enabled` on that same readiness signal too — the\n   * hook cannot tell \"no defaultFilters intended\" apart from \"not resolved\n   * yet,\" so an ungated hook's very first fetch can still run unscoped.\n   */\n  defaultFilters?: FilterParam[];\n  defaultPerPage?: number;\n  /** The page to start on (from 1), e.g. restored from the URL. Default 1. */\n  defaultPage?: number;\n  /** The search to start with, e.g. restored from the URL. Default \"\". */\n  defaultSearch?: string;\n  /** Supabase select/join syntax, e.g. \"*, author:profiles(name)\". */\n  select?: string;\n  /** Fields to search across when setSearch is called. Required for server-side search. */\n  searchFields?: string[];\n  /** Disable auto-fetching. */\n  enabled?: boolean;\n  /**\n   * Other query keys to invalidate after a create, update or delete, on top\n   * of `[resource]` and the provider's own `invalidates` (e.g. `[[\"me\"]]`\n   * when a write changes the signed-in user's roles).\n   */\n  invalidates?: InvalidationKey[];\n  /**\n   * While the next page / sort / search is loading, keep returning the\n   * previous result (`list.isPlaceholderData` is true meanwhile) instead of\n   * dropping to `undefined`. A paged list then stays on screen between pages\n   * rather than flashing a skeleton. Default false.\n   */\n  keepPreviousData?: boolean;\n  /**\n   * After the write commits, with the provider's row. In `optimistic` and\n   * `undoable` modes that is after `create` / `update` / `remove` have\n   * already resolved.\n   */\n  onCreateSuccess?: (data: T) => void;\n  onUpdateSuccess?: (data: T) => void;\n  onDeleteSuccess?: () => void;\n  /**\n   * A write failed. In `optimistic` and `undoable` modes this is the only\n   * place a failure is reported (the cache has already been put back), so\n   * show it to the user here.\n   */\n  onError?: (error: Error) => void;\n}\n\n// ---------------------------------------------------------------------------\n// Return type\n// ---------------------------------------------------------------------------\n\nexport interface UseResourceReturn<T> {\n  /** TanStack Query result for the list query. */\n  list: UseQueryResult<ListResult<T>>;\n  /** Current list params (pagination, sort, filters, search). */\n  params: ListParams;\n  setSort: (sort: SortParam | undefined) => void;\n  setFilters: (filters: FilterParam[]) => void;\n  setPage: (page: number) => void;\n  setPerPage: (perPage: number) => void;\n  setSearch: (query: string) => void;\n  /**\n   * Create a new record. Returns the created item. In `optimistic` and\n   * `undoable` modes it resolves at once with the values given (no `id` yet;\n   * `onCreateSuccess` gets the stored row).\n   */\n  create: (data: Partial<T>) => Promise<T>;\n  /**\n   * Update an existing record by id. Returns the updated item. In\n   * `optimistic` and `undoable` modes it resolves at once with the cached\n   * row merged with `data`.\n   */\n  update: (id: Identifier, data: Partial<T>) => Promise<T>;\n  /** Delete a record by id. Resolves at once in `optimistic` / `undoable` modes. */\n  remove: (id: Identifier) => Promise<void>;\n  /** True when any mutation is in-flight. */\n  isMutating: boolean;\n  createMutation: UseMutationResult<T, Error, Partial<T>>;\n  updateMutation: UseMutationResult<T, Error, { id: Identifier; data: Partial<T> }>;\n  deleteMutation: UseMutationResult<void, Error, Identifier>;\n}\n\n// ---------------------------------------------------------------------------\n// Filter identity — a deep-equality key independent of object-key order, so\n// a caller that rebuilds the same logical filters via a differently-ordered\n// spread (e.g. `{...base, operator: \"eq\"}` vs `{operator: \"eq\", ...base}`)\n// doesn't trip a spurious resync + pagination reset on an unrelated rerender.\n// ---------------------------------------------------------------------------\n\nfunction stableFilterKey(filters: FilterParam[] | undefined): string | undefined {\n  if (!filters) return undefined;\n  return JSON.stringify(\n    filters.map((f) => {\n      const sorted: Record<string, unknown> = {};\n      for (const key of Object.keys(f).sort()) {\n        sorted[key] = (f as unknown as Record<string, unknown>)[key];\n      }\n      return sorted;\n    }),\n  );\n}\n\n// ---------------------------------------------------------------------------\n// Hook\n// ---------------------------------------------------------------------------\n\nexport function useResource<T extends BaseRecord = BaseRecord>(\n  resource: string,\n  options: UseResourceOptions<T> = {},\n): UseResourceReturn<T> {\n  const {\n    defaultSort,\n    defaultFilters,\n    defaultPerPage = 25,\n    defaultPage = 1,\n    defaultSearch = \"\",\n    select,\n    searchFields: searchFieldsOption,\n    enabled = true,\n    invalidates,\n    keepPreviousData = false,\n    onCreateSuccess,\n    onUpdateSuccess,\n    onDeleteSuccess,\n    onError,\n    mutationMode = \"pessimistic\",\n    undoDelayMs,\n    onUndoable,\n  } = options;\n\n  const provider = useDataProvider();\n  const queryClient = useQueryClient();\n\n  // -------------------------------------------------------------------------\n  // State\n  // -------------------------------------------------------------------------\n\n  const [sort, setSortRaw] = useState<SortParam | undefined>(defaultSort);\n  const [filters, setFiltersRaw] = useState<FilterParam[]>(defaultFilters ?? []);\n  const [page, setPage] = useState(Math.max(1, Math.floor(defaultPage)));\n  const [perPage, setPerPageRaw] = useState(defaultPerPage);\n  const [searchQuery, setSearchQuery] = useState(defaultSearch);\n\n  // `defaultFilters` often resolves asynchronously — a caller's scope/audience\n  // (team, project, ...) can still be loading on first render, so the array\n  // it passes in changes value (not just identity) after mount, and may later\n  // clear back to undefined (e.g. the scope itself is cleared). Re-syncing\n  // here, during render rather than in an effect, means `filters` is already\n  // correct by the time `params`/`list` below compute for this pass — no\n  // stray unscoped fetch on the frame before an effect would have caught up.\n  //\n  // This only closes the gap for `defaultFilters` CHANGING across renders on\n  // an already-mounted, already-enabled hook (e.g. a scope switch). It cannot\n  // help the very first render: `filters` still seeds from whatever\n  // `defaultFilters` is on mount, and `undefined` here is genuinely ambiguous\n  // between \"this caller never uses defaultFilters\" (in which case forcing a\n  // fetch to wait would break it forever) and \"the real value hasn't resolved\n  // yet.\" A caller in the second case MUST also gate `enabled` on that same\n  // readiness signal for its very first fetch to be correctly scoped — this\n  // hook has no way to tell the two cases apart on its own.\n  const defaultFiltersKey = stableFilterKey(defaultFilters);\n  const [syncedFiltersKey, setSyncedFiltersKey] = useState(defaultFiltersKey);\n  if (defaultFiltersKey !== syncedFiltersKey) {\n    setSyncedFiltersKey(defaultFiltersKey);\n    setFiltersRaw(defaultFilters ?? []);\n    setPage(1);\n  }\n\n  const setSort = useCallback((s: SortParam | undefined) => {\n    setSortRaw(s);\n    setPage(1);\n  }, []);\n\n  const setFilters = useCallback((f: FilterParam[]) => {\n    setFiltersRaw(f);\n    setPage(1);\n  }, []);\n\n  const setPerPage = useCallback((value: number) => {\n    setPerPageRaw(value);\n    setPage(1);\n  }, []);\n\n  const setSearch = useCallback((query: string) => {\n    setSearchQuery(query);\n    setPage(1);\n  }, []);\n\n  // -------------------------------------------------------------------------\n  // Params\n  // -------------------------------------------------------------------------\n\n  const params = useMemo<ListParams>(() => {\n    const p: ListParams = {\n      pagination: { page, perPage },\n      sort,\n      filters: filters.length > 0 ? filters : undefined,\n      select,\n    };\n    if (searchQuery && searchFieldsOption && searchFieldsOption.length > 0) {\n      p.search = { query: searchQuery, fields: searchFieldsOption };\n    }\n    return p;\n  }, [page, perPage, sort, filters, select, searchQuery, searchFieldsOption]);\n\n  // -------------------------------------------------------------------------\n  // List query\n  // -------------------------------------------------------------------------\n\n  const listQueryKey = useMemo(\n    () => [resource, \"list\", params] as const,\n    [resource, params],\n  );\n\n  const list = useQuery<ListResult<T>>({\n    queryKey: listQueryKey,\n    queryFn: () => provider.getList<T>(resource, params),\n    enabled,\n    placeholderData: keepPreviousData ? keepPreviousPlaceholder : undefined,\n  });\n\n  // -------------------------------------------------------------------------\n  // Mutations\n  // -------------------------------------------------------------------------\n\n  const invalidateAfter = useCallback(\n    (event: WriteEvent) => {\n      // Waits while an optimistic/undoable write on the resource is pending.\n      void invalidateResource(queryClient, resource);\n      for (const queryKey of relatedKeys(provider, event, invalidates)) {\n        void queryClient.invalidateQueries({ queryKey: [...queryKey] });\n      }\n    },\n    [queryClient, resource, provider, invalidates],\n  );\n\n  const defaultOnError = useCallback(\n    (error: Error) => {\n      console.error(`[useResource] ${resource} mutation failed:`, error.message);\n    },\n    [resource],\n  );\n  const reportError = onError ?? defaultOnError;\n\n  const delayed = useDelayedWrites();\n  const modeArgs = {\n    queryClient,\n    provider,\n    resource,\n    mode: mutationMode,\n    undoDelayMs,\n    onUndoable,\n    delayed,\n    failedLater: reportError,\n  };\n\n  const createMutation = useMutation<T, Error, Partial<T>>({\n    mutationFn: async (data) => {\n      const outcome = await executeWrite<T>({\n        ...modeArgs,\n        kind: \"create\",\n        data: data as Record<string, unknown>,\n        send: async () => {\n          const result = await provider.create<T>(resource, { data });\n          return { record: result.data, audit: result.audit };\n        },\n        committed: (record) => {\n          invalidateAfter({ resource, kind: \"create\", id: record.id, record });\n          onCreateSuccess?.(record);\n        },\n      });\n      return outcome.status === \"committed\" ? outcome.record : (data as T);\n    },\n    onError: reportError,\n  });\n\n  const updateMutation = useMutation<\n    T,\n    Error,\n    { id: Identifier; data: Partial<T> }\n  >({\n    mutationFn: async ({ id, data }) => {\n      const before = cachedRecord(queryClient, resource, id);\n      const outcome = await executeWrite<T>({\n        ...modeArgs,\n        kind: \"update\",\n        id,\n        data: data as Record<string, unknown>,\n        send: async () => {\n          const result = await provider.update<T>(resource, { id, data });\n          return { record: result.data, audit: result.audit };\n        },\n        committed: (record) => {\n          invalidateAfter({ resource, kind: \"update\", id, record });\n          onUpdateSuccess?.(record);\n        },\n      });\n      return outcome.status === \"committed\"\n        ? outcome.record\n        : ({ ...(before ?? {}), ...data, id: before?.id ?? id } as T);\n    },\n    onError: reportError,\n  });\n\n  const deleteMutation = useMutation<void, Error, Identifier>({\n    mutationFn: async (id) => {\n      await executeWrite<void>({\n        ...modeArgs,\n        kind: \"delete\",\n        id,\n        send: async () => {\n          const result = await provider.deleteOne(resource, { id });\n          return { record: undefined, audit: result?.audit };\n        },\n        committed: () => {\n          invalidateAfter({ resource, kind: \"delete\", id });\n          onDeleteSuccess?.();\n        },\n      });\n    },\n    onError: reportError,\n  });\n\n  // -------------------------------------------------------------------------\n  // Convenience wrappers\n  // -------------------------------------------------------------------------\n\n  const create = useCallback(\n    (data: Partial<T>) => createMutation.mutateAsync(data),\n    [createMutation],\n  );\n\n  const update = useCallback(\n    (id: Identifier, data: Partial<T>) =>\n      updateMutation.mutateAsync({ id, data }),\n    [updateMutation],\n  );\n\n  const remove = useCallback(\n    (id: Identifier) => deleteMutation.mutateAsync(id),\n    [deleteMutation],\n  );\n\n  const isMutating =\n    createMutation.isPending ||\n    updateMutation.isPending ||\n    deleteMutation.isPending;\n\n  return {\n    list,\n    params,\n    setSort,\n    setFilters,\n    setPage,\n    setPerPage,\n    setSearch,\n    create,\n    update,\n    remove,\n    isMutating,\n    createMutation,\n    updateMutation,\n    deleteMutation,\n  };\n}\n"]}

package/dist/chunk-HT43MPKW.js

@@ -0,0 +1,3 @@
+
+//# sourceMappingURL=chunk-HT43MPKW.js.map
+//# sourceMappingURL=chunk-HT43MPKW.js.map

package/dist/{chunk-EL7YGOTY.js.map → chunk-HT43MPKW.js.map}

@@ -1 +1 @@
-{"version":3,"sources":[],"names":[],"mappings":"","file":"chunk-EL7YGOTY.js"}
+{"version":3,"sources":[],"names":[],"mappings":"","file":"chunk-HT43MPKW.js"}

package/dist/chunk-HUNGCTRA.js

@@ -0,0 +1,33 @@
+// src/schema/read-outcome.ts
+var DataReadError = class extends Error {
+  outcome;
+  /** The store's own error code, when it gave one. */
+  code;
+  constructor(outcome, message, options = {}) {
+    super(message, options.cause === void 0 ? void 0 : { cause: options.cause });
+    this.name = "DataReadError";
+    this.outcome = outcome;
+    if (options.code !== void 0) this.code = options.code;
+  }
+};
+function isDataReadError(error) {
+  return error instanceof Error && error.name === "DataReadError" && typeof error.outcome === "string";
+}
+function readFailureMessage(outcome, noun, one, plural = `${noun}s`) {
+  switch (outcome) {
+    case "unauthenticated":
+      return "Your session has ended. Sign in again to continue.";
+    case "forbidden":
+      return one ? `You don't have access to this ${noun}.` : `You don't have access to these ${plural}.`;
+    case "gone":
+      return `This ${noun} doesn't exist, or you can't see it.`;
+    case "invalid":
+      return one ? `This ${noun} couldn't be loaded.` : `These ${plural} couldn't be loaded.`;
+    default:
+      return one ? `This ${noun} couldn't be loaded. Try again.` : `These ${plural} couldn't be loaded. Try again.`;
+  }
+}
+
+export { DataReadError, isDataReadError, readFailureMessage };
+//# sourceMappingURL=chunk-HUNGCTRA.js.map
+//# sourceMappingURL=chunk-HUNGCTRA.js.map

package/dist/chunk-HUNGCTRA.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/schema/read-outcome.ts"],"names":[],"mappings":";AAyBO,IAAM,aAAA,GAAN,cAA4B,KAAA,CAAM;AAAA,EAC9B,OAAA;AAAA;AAAA,EAEA,IAAA;AAAA,EAET,WAAA,CAAY,OAAA,EAAsB,OAAA,EAAiB,OAAA,GAAgC,EAAC,EAAG;AACrF,IAAA,KAAA,CAAM,OAAA,EAAS,QAAQ,KAAA,KAAU,MAAA,GAAY,SAAY,EAAE,KAAA,EAAO,OAAA,CAAQ,KAAA,EAAO,CAAA;AACjF,IAAA,IAAA,CAAK,IAAA,GAAO,eAAA;AACZ,IAAA,IAAA,CAAK,OAAA,GAAU,OAAA;AACf,IAAA,IAAI,OAAA,CAAQ,IAAA,KAAS,MAAA,EAAW,IAAA,CAAK,OAAO,OAAA,CAAQ,IAAA;AAAA,EACtD;AACF;AAMO,SAAS,gBAAgB,KAAA,EAAwC;AACtE,EAAA,OACE,iBAAiB,KAAA,IACjB,KAAA,CAAM,SAAS,eAAA,IACf,OAAQ,MAAgC,OAAA,KAAY,QAAA;AAExD;AAGO,SAAS,mBAAmB,OAAA,EAAsB,IAAA,EAAc,KAAc,MAAA,GAAS,CAAA,EAAG,IAAI,CAAA,CAAA,CAAA,EAAa;AAChH,EAAA,QAAQ,OAAA;AAAS,IACf,KAAK,iBAAA;AACH,MAAA,OAAO,oDAAA;AAAA,IACT,KAAK,WAAA;AACH,MAAA,OAAO,GAAA,GAAM,CAAA,8BAAA,EAAiC,IAAI,CAAA,CAAA,CAAA,GAAM,kCAAkC,MAAM,CAAA,CAAA,CAAA;AAAA,IAClG,KAAK,MAAA;AACH,MAAA,OAAO,QAAQ,IAAI,CAAA,oCAAA,CAAA;AAAA,IACrB,KAAK,SAAA;AACH,MAAA,OAAO,GAAA,GAAM,CAAA,KAAA,EAAQ,IAAI,CAAA,oBAAA,CAAA,GAAyB,SAAS,MAAM,CAAA,oBAAA,CAAA;AAAA,IACnE;AACE,MAAA,OAAO,GAAA,GAAM,CAAA,KAAA,EAAQ,IAAI,CAAA,+BAAA,CAAA,GAAoC,SAAS,MAAM,CAAA,+BAAA,CAAA;AAAA;AAElF","file":"chunk-HUNGCTRA.js","sourcesContent":["// ---------------------------------------------------------------------------\n// Why a read failed, in words a user can be shown\n//\n// A store's own error text (\"relation \\\"tasks\\\" does not exist\", \"JWT\n// expired\", a constraint name) is for developers. A read error carries a\n// plain message for the screen and keeps the store's error as its `cause`.\n// ---------------------------------------------------------------------------\n\n/**\n * - `unauthenticated`: no signed-in user, or the session expired.\n * - `forbidden`: this user may not read these records.\n * - `gone`: the one record asked for doesn't exist, or isn't visible.\n * - `invalid`: the request itself was wrong (an unknown column, a bad value).\n * - `error`: anything else.\n */\nexport type ReadOutcome = \"unauthenticated\" | \"forbidden\" | \"gone\" | \"invalid\" | \"error\";\n\nexport interface DataReadErrorOptions {\n  /** The store's own error code (a Postgres SQLSTATE or PostgREST code). */\n  code?: string;\n  /** The underlying error, with its raw text, kept for logging. */\n  cause?: unknown;\n}\n\n/** Thrown by a provider when a read failed. Its `message` is safe to show. */\nexport class DataReadError extends Error {\n  readonly outcome: ReadOutcome;\n  /** The store's own error code, when it gave one. */\n  readonly code?: string;\n\n  constructor(outcome: ReadOutcome, message: string, options: DataReadErrorOptions = {}) {\n    super(message, options.cause === undefined ? undefined : { cause: options.cause });\n    this.name = \"DataReadError\";\n    this.outcome = outcome;\n    if (options.code !== undefined) this.code = options.code;\n  }\n}\n\n/**\n * `instanceof` fails when two copies of this package are installed, so check\n * the shape instead.\n */\nexport function isDataReadError(error: unknown): error is DataReadError {\n  return (\n    error instanceof Error &&\n    error.name === \"DataReadError\" &&\n    typeof (error as { outcome?: unknown }).outcome === \"string\"\n  );\n}\n\n/** The plain sentence for a failed read of `noun` records (one, or a list). */\nexport function readFailureMessage(outcome: ReadOutcome, noun: string, one: boolean, plural = `${noun}s`): string {\n  switch (outcome) {\n    case \"unauthenticated\":\n      return \"Your session has ended. Sign in again to continue.\";\n    case \"forbidden\":\n      return one ? `You don't have access to this ${noun}.` : `You don't have access to these ${plural}.`;\n    case \"gone\":\n      return `This ${noun} doesn't exist, or you can't see it.`;\n    case \"invalid\":\n      return one ? `This ${noun} couldn't be loaded.` : `These ${plural} couldn't be loaded.`;\n    default:\n      return one ? `This ${noun} couldn't be loaded. Try again.` : `These ${plural} couldn't be loaded. Try again.`;\n  }\n}\n"]}

package/dist/{chunk-IHWWJUEN.js → chunk-IZT2O57C.js}

@@ -1,8 +1,11 @@
+import { useUnsavedChangesGuard } from './chunk-XQO4OH2N.js';
+import { isDataWriteError } from './chunk-5NHR6ZXS.js';
 import { titleCase } from './chunk-RYEXWQFD.js';
-import { useOne } from './chunk-ZK5C3OOT.js';
+import { useDelayedWrites, cachedRecord, executeWrite, invalidateResource } from './chunk-QH4P5MI2.js';
 import { relatedKeys } from './chunk-7NUL32W7.js';
+import { useOne } from './chunk-ZK5C3OOT.js';
 import { useDataProvider, useStorage } from './chunk-GGSXSI6Z.js';
-import { useMemo, useEffect, useCallback } from 'react';
+import { useMemo, useEffect, useState, useRef, useCallback } from 'react';
 import { useForm } from 'react-hook-form';
 import { zodResolver } from '@hookform/resolvers/zod';
 import { z } from 'zod';
@@ -234,7 +237,11 @@ function useResourceForm(options) {
     autoPlaceholder = true,
     validationMode,
     autosave,
-    invalidates
+    invalidates,
+    warnWhenUnsaved = false,
+    mutationMode = "pessimistic",
+    undoDelayMs,
+    onUndoable
   } = options;
   const autosaveEnabled = !!autosave;
   const debounceMs = typeof autosave === "object" ? autosave.debounceMs ?? 1e3 : 1e3;
@@ -320,54 +327,133 @@ function useResourceForm(options) {
       subscription.unsubscribe();
     };
   }, [autosaveEnabled, resource, action, form, debounceMs, storage]);
+  const rhfDirty = form.formState.isDirty;
+  const [savedClean, setSavedClean] = useState(false);
+  const savedCleanRef = useRef(false);
+  useEffect(() => {
+    const subscription = form.watch((_values, info) => {
+      if (!info.name) return;
+      savedCleanRef.current = false;
+      setSavedClean(false);
+    });
+    return () => subscription.unsubscribe();
+  }, [form]);
+  const isDirty = rhfDirty && !savedClean;
+  const warn = !!warnWhenUnsaved;
+  const { confirmLeave: guardConfirm } = useUnsavedChangesGuard({
+    when: warn && isDirty,
+    message: typeof warnWhenUnsaved === "object" ? warnWhenUnsaved.message : void 0
+  });
+  const confirmLeave = useCallback(
+    // The ref, not state: a router blocker may ask in the same tick as the
+    // save's onSuccess navigates, before a re-render.
+    () => !warn || savedCleanRef.current ? true : guardConfirm(),
+    [warn, guardConfirm]
+  );
+  const markSaved = useCallback(() => {
+    savedCleanRef.current = true;
+    setSavedClean(true);
+  }, []);
+  const delayed = useDelayedWrites();
+  const showError = useCallback(
+    (error) => {
+      const fieldErrors = isDataWriteError(error) ? error.fields : void 0;
+      const known = new Set(resolvedFields.map((f) => f.key));
+      let first;
+      if (fieldErrors) {
+        for (const [field, message] of Object.entries(fieldErrors)) {
+          if (!known.has(field)) continue;
+          form.setError(field, { type: "server", message });
+          first ??= field;
+        }
+      }
+      form.setError("root", { type: "server", message: error.message });
+      if (first) {
+        try {
+          form.setFocus(first);
+        } catch {
+        }
+      }
+    },
+    [form, resolvedFields]
+  );
+  const reportError = useCallback(
+    (error) => {
+      savedCleanRef.current = false;
+      setSavedClean(false);
+      showError(error);
+      if (onError) {
+        onError(error);
+      } else {
+        console.error(`[useResourceForm] ${action} failed for "${resource}":`, error);
+      }
+    },
+    [showError, onError, action, resource]
+  );
   const handleSubmit = useCallback(
     async (formData) => {
       try {
-        let result;
         let recordId;
-        if (action === "create") {
-          const res = await provider.create(resource, { data: formData });
-          result = res.data;
-        } else {
+        if (action === "edit") {
           recordId = id ?? String(effectiveData?.id ?? "");
           if (!recordId) {
             throw new Error("Cannot update record: no ID available. Provide an id prop or ensure the record has an id field.");
           }
-          const res = await provider.update(resource, { id: recordId, data: formData });
-          result = res.data;
-        }
-        if (autosaveEnabled && action === "create") {
-          try {
-            storage.removeItem(`genesis-draft:${resource}:new`);
-          } catch (err) {
-            console.warn(`[useResourceForm] Draft cleanup failed for "${resource}":`, err instanceof Error ? err.message : String(err));
-          }
         }
-        await queryClient.invalidateQueries({ queryKey: [resource] });
-        const related = relatedKeys(
+        const before = recordId != null ? cachedRecord(queryClient, resource, recordId) : void 0;
+        const outcome = await executeWrite({
+          queryClient,
           provider,
-          {
-            resource,
-            kind: action === "create" ? "create" : "update",
-            id: recordId ?? result.id,
-            record: result
+          resource,
+          kind: action === "create" ? "create" : "update",
+          id: recordId,
+          // The cache holds rows; patch it only when the form's values are
+          // row-shaped (no provider.toFormValues reshaping this record).
+          data: formSource === effectiveData ? formData : void 0,
+          mode: mutationMode,
+          undoDelayMs,
+          onUndoable,
+          delayed,
+          send: async () => {
+            const res = action === "create" ? await provider.create(resource, { data: formData }) : await provider.update(resource, { id: recordId, data: formData });
+            return { record: res.data, audit: res.audit };
           },
-          invalidates
-        );
-        await Promise.all(related.map((queryKey) => queryClient.invalidateQueries({ queryKey: [...queryKey] })));
-        onSuccess?.(result);
-      } catch (err) {
-        const error = err instanceof Error ? err : new Error(String(err));
-        form.setError("root", { message: error.message });
-        if (onError) {
-          onError(error);
+          committed: async (result) => {
+            if (autosaveEnabled && action === "create") {
+              try {
+                storage.removeItem(`genesis-draft:${resource}:new`);
+              } catch (err) {
+                console.warn(`[useResourceForm] Draft cleanup failed for "${resource}":`, err instanceof Error ? err.message : String(err));
+              }
+            }
+            await invalidateResource(queryClient, resource);
+            const related = relatedKeys(
+              provider,
+              {
+                resource,
+                kind: action === "create" ? "create" : "update",
+                id: recordId ?? result.id,
+                record: result
+              },
+              invalidates
+            );
+            await Promise.all(related.map((queryKey) => queryClient.invalidateQueries({ queryKey: [...queryKey] })));
+          },
+          failedLater: reportError
+        });
+        markSaved();
+        if (outcome.status === "committed") {
+          onSuccess?.(outcome.record);
         } else {
-          console.error(`[useResourceForm] ${action} failed for "${resource}":`, error);
+          onSuccess?.(
+            action === "edit" ? { ...before ?? effectiveData ?? {}, ...formData, id: recordId } : { ...formData }
+          );
         }
+      } catch (err) {
+        reportError(err instanceof Error ? err : new Error(String(err)));
       }
     },
-    // form is stable (from useForm) but included for correctness since we call form.setError
-    [action, provider, resource, id, effectiveData, queryClient, onSuccess, onError, autosaveEnabled, form, storage, invalidates]
+    [action, provider, resource, id, effectiveData, formSource, queryClient, onSuccess, autosaveEnabled, storage, invalidates, mutationMode, undoDelayMs, onUndoable, delayed, reportError, markSaved]
   );
   const onSubmit = useCallback(
     (e) => form.handleSubmit(handleSubmit)(e),
@@ -380,10 +466,12 @@ function useResourceForm(options) {
     onSubmit,
     handleSave: handleSubmit,
     isSaving,
-    isLoading
+    isLoading,
+    isDirty,
+    confirmLeave
   };
 }
 
 export { buildArrayItemDefaults, useResourceForm };
-//# sourceMappingURL=chunk-IHWWJUEN.js.map
-//# sourceMappingURL=chunk-IHWWJUEN.js.map
+//# sourceMappingURL=chunk-IZT2O57C.js.map
+//# sourceMappingURL=chunk-IZT2O57C.js.map