@multiplatform.one/frappe 6.6.0 → 7.0.0

package/types/frappeReact.d.ts

@@ -1,6 +1,7 @@
 import type { Collection } from "@tanstack/db";
 import { type FrappeCollectionOptionsConfig } from "./collection";
 import { SyncModule } from "./sync";
+import type { DebugMutationEntry } from "./sync/types";
 /**
  * Configuration for creating a Frappe collection with connection details.
  */
@@ -13,6 +14,20 @@ export interface UseFrappeCollectionConfig {
      * behind a reverse proxy so the base URL port is used.
      */
     socketPort?: number;
+    /**
+     * Dial the realtime socket at this origin instead of deriving it from
+     * `baseURL` + `socketPort` — for dev servers that proxy `/socket.io` on
+     * their own origin (same-origin socket). See
+     * `RealtimeConfig.socketBaseURL`.
+     */
+    socketBaseURL?: string;
+    /**
+     * Frappe site name — the Socket.IO namespace the realtime connection must
+     * join. Required whenever the `baseURL` hostname is not the bench site
+     * name (e.g. baseURL http://127.0.0.1:8000 serving site "localhost"). See
+     * `RealtimeConfig.siteName`.
+     */
+    siteName?: string;
     /** Authentication configuration */
     auth?: {
         useToken?: boolean;
@@ -37,6 +52,14 @@ export interface UseFrappeCollectionConfig {
  * Intended for devtools integration — not part of the public API.
  */
 export declare function __getActiveSyncModule(): SyncModule | undefined;
+/**
+ * Public accessor for the shared SyncModule behind a connection config —
+ * the seam consumers use to issue engine mutations that a collection can't
+ * express (e.g. custom-transport writes via `mutation.execute`). Returns
+ * the same refcounted instance the collection hooks use, or undefined
+ * during SSR.
+ */
+export declare function getFrappeSyncModule(config: UseFrappeCollectionConfig | undefined): SyncModule | undefined;
 /**
  * React hook that returns a TanStack DB Collection backed by a Frappe doctype.
  *
@@ -114,6 +137,31 @@ export declare function useFrappeDoctypeEvents(config: UseFrappeCollectionConfig
     type: string;
     payload?: unknown;
 }) => void, enabled?: boolean): void;
+/** Result of {@link useFrappePendingMutations}. */
+export interface UseFrappePendingMutationsResult {
+    /** All live ledger entries (pending + failed), submission order. */
+    entries: DebugMutationEntry[];
+    /** Entries still awaiting a server ack. */
+    pending: DebugMutationEntry[];
+    /** Entries the server rejected — rollback already ran; show these. */
+    failed: DebugMutationEntry[];
+    /** Re-issues every pending/failed entry with its ORIGINAL mutation id
+     * (idempotent on the server via Idempotency-Key). */
+    retry: () => Promise<void>;
+    /** Drops one failed entry without retrying (clears the error surface). */
+    dismiss: (id: string) => void;
+}
+/**
+ * React hook exposing the mutation ledger for a connection (optionally
+ * scoped to one doctype): which optimistic writes are still in flight and
+ * which the server rejected. This is the state behind the rejected-write
+ * UI contract — a surface that initiated a write renders `failed` entries
+ * inline (e.g. via frappe-ui's `SyncErrorNotice`) with `retry`/`dismiss`.
+ *
+ * Reactive: re-reads on every store emit, but only re-renders when the
+ * ledger signature (ids × status × retryCount) actually changes.
+ */
+export declare function useFrappePendingMutations(config: UseFrappeCollectionConfig | undefined, doctype?: string): UseFrappePendingMutationsResult;
 /**
  * Configuration for the useInfiniteScroll hook
  */
@@ -170,7 +218,7 @@ export interface UseInfiniteScrollResult {
  *
  *   return (
  *     <div>
- *       {data.map(pokemon => <PokemonCard key={pokemon.name} {...pokemon} />)}
+ *       {data.map(pokemon => <PokemonCard key={pokemon.name} pokemon={pokemon} />)}
  *       <div ref={sentinelRef}>
  *         {isLoadingMore ? <Spinner /> : hasMore ? "Scroll for more" : "No more items"}
  *       </div>
@@ -254,7 +302,7 @@ export interface UseFrappeInfiniteListResult<TDoc> {
  *
  *   return (
  *     <div>
- *       {items.map(pokemon => <PokemonCard key={pokemon.name} {...pokemon} />)}
+ *       {items.map(pokemon => <PokemonCard key={pokemon.name} pokemon={pokemon} />)}
  *       <div ref={sentinelRef}>
  *         {hasMore ? <Spinner /> : "No more pokemon"}
  *       </div>

package/types/frappeReact.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"frappeReact.d.ts","sourceRoot":"","sources":["../src/frappeReact.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"frappeReact.d.ts","sourceRoot":"","sources":["../src/frappeReact.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAE/C,OAAO,EAGL,KAAK,6BAA6B,EACnC,MAAM,cAAc,CAAC;AAMtB,OAAO,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAC;AAEpC,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAGvD;;GAEG;AACH,MAAM,WAAW,yBAAyB;IACxC,wCAAwC;IACxC,OAAO,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;;OAKG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,mCAAmC;IACnC,IAAI,CAAC,EAAE;QACL,QAAQ,CAAC,EAAE,OAAO,CAAC;QACnB,KAAK,CAAC,EAAE,MAAM,GAAG,CAAC,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC;QAClD,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,kEAAkE;QAClE,SAAS,CAAC,EAAE,MAAM,GAAG,CAAC,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC;KACvD,CAAC;IACF,sCAAsC;IACtC,WAAW,CAAC,EAAE,OAAO,cAAc,EAAE,WAAW,CAAC;IACjD;;;;OAIG;IACH,aAAa,CAAC,EAAE,OAAO,YAAY,EAAE,cAAc,CAAC,eAAe,CAAC,CAAC;IACrE,sEAAsE;IACtE,QAAQ,CAAC,EAAE,OAAO,YAAY,EAAE,eAAe,CAAC;CACjD;AAQD;;;GAGG;AACH,wBAAgB,qBAAqB,IAAI,UAAU,GAAG,SAAS,CAG9D;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,yBAAyB,GAAG,SAAS,GAC5C,UAAU,GAAG,SAAS,CAGxB;AAqWD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,SAAS,MAAM,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,EACzF,MAAM,EAAE,yBAAyB,GAAG,SAAS,EAC7C,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,IAAI,CAAC,6BAA6B,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC,GAC1D,UAAU,CAAC,IAAI,EAAE,MAAM,CAAC,GAAG,SAAS,CA+DtC;AAMD,wDAAwD;AACxD,MAAM,WAAW,qBAAqB;IACpC,kCAAkC;IAClC,SAAS,EAAE,OAAO,CAAC;IACnB,uDAAuD;IACvD,aAAa,EAAE,OAAO,CAAC;CACxB;AAOD;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,yBAAyB,GAAG,SAAS,GAC5C,qBAAqB,CAsBvB;AAED;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,yBAAyB,GAAG,SAAS,EAC7C,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,CAAC,KAAK,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,OAAO,CAAA;CAAE,KAAK,IAAI,EAC7D,OAAO,UAAO,GACb,IAAI,CAsBN;AAMD,mDAAmD;AACnD,MAAM,WAAW,+BAA+B;IAC9C,oEAAoE;IACpE,OAAO,EAAE,kBAAkB,EAAE,CAAC;IAC9B,2CAA2C;IAC3C,OAAO,EAAE,kBAAkB,EAAE,CAAC;IAC9B,sEAAsE;IACtE,MAAM,EAAE,kBAAkB,EAAE,CAAC;IAC7B;yDACqD;IACrD,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3B,0EAA0E;IAC1E,OAAO,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,IAAI,CAAC;CAC/B;AAID;;;;;;;;;GASG;AACH,wBAAgB,yBAAyB,CACvC,MAAM,EAAE,yBAAyB,GAAG,SAAS,EAC7C,OAAO,CAAC,EAAE,MAAM,GACf,+BAA+B,CAuCjC;AAMD;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACtC,6CAA6C;IAC7C,OAAO,EAAE,OAAO,CAAC;IACjB,6CAA6C;IAC7C,SAAS,EAAE,OAAO,CAAC;IACnB,uDAAuD;IACvD,UAAU,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACvC,wDAAwD;IACxD,IAAI,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;IACtB,gDAAgD;IAChD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,8CAA8C;IAC9C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,0CAA0C;IAC1C,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,8CAA8C;IAC9C,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACtC,4CAA4C;IAC5C,WAAW,EAAE,KAAK,CAAC,WAAW,CAAC,OAAO,GAAG,IAAI,CAAC,CAAC;IAC/C,gDAAgD;IAChD,SAAS,EAAE,OAAO,CAAC;IACnB,uCAAuC;IACvC,aAAa,EAAE,OAAO,CAAC;CACxB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,uBAAuB,GAAG,uBAAuB,CAmH1F;AAED;;GAEG;AACH,MAAM,WAAW,2BAA2B,CAAC,IAAI;IAC/C,sCAAsC;IACtC,MAAM,EAAE,yBAAyB,GAAG,SAAS,CAAC;IAC9C,uBAAuB;IACvB,OAAO,EAAE,MAAM,CAAC;IAChB,sBAAsB;IACtB,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,uBAAuB;IACvB,OAAO,CAAC,EAAE,KAAK,CAAC,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrE,6BAA6B;IAC7B,OAAO,CAAC,EAAE,OAAO,cAAc,EAAE,OAAO,CAAC;IACzC,8BAA8B;IAC9B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,mCAAmC;IACnC,SAAS,CAAC,EAAE,CAAC,GAAG,EAAE,IAAI,KAAK,IAAI,CAAC;CACjC;AAED;;GAEG;AACH,MAAM,WAAW,2BAA2B,CAAC,IAAI;IAC/C,uBAAuB;IACvB,KAAK,EAAE,IAAI,EAAE,CAAC;IACd,uCAAuC;IACvC,OAAO,EAAE,OAAO,CAAC;IACjB,0CAA0C;IAC1C,SAAS,EAAE,OAAO,CAAC;IACnB,0CAA0C;IAC1C,aAAa,EAAE,OAAO,CAAC;IACvB,8BAA8B;IAC9B,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;IACpB,wCAAwC;IACxC,WAAW,EAAE,KAAK,CAAC,WAAW,CAAC,OAAO,GAAG,IAAI,CAAC,CAAC;IAC/C,oCAAoC;IACpC,QAAQ,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9B,0CAA0C;IAC1C,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7B,mCAAmC;IACnC,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,SAAS,MAAM,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,EAC3F,OAAO,EAAE,2BAA2B,CAAC,IAAI,CAAC,GACzC,2BAA2B,CAAC,IAAI,CAAC,CAuJnC"}

package/types/index.d.ts

@@ -10,13 +10,15 @@ export { AuthModule } from "./auth";
 export { CallModule } from "./call";
 export { DbModule } from "./db";
 export { FileModule } from "./file";
-export { RealtimeModule } from "./realtime";
+export { RealtimeModule, RealtimePlatform } from "./realtime";
+export type { RealtimeConfig, RealtimeTransport, RealtimeSSEConfig, SSEFrame, SSEMappedEvent, SSEMessageEventLike, SSEEventSourceLike, SSEEventSourceConstructor, DocRoom, ListRoom, } from "./realtime";
 export { SyncModule } from "./sync";
 export { createFrappeCollection, frappeCollectionOptions, createFixtureCollection, fixtureCollectionOptions, } from "./collection";
 export type { FrappeCollectionOptionsConfig, FixtureCollectionOptionsConfig } from "./collection";
-export { createOptimisticAction } from "./optimistic";
-export { useFrappeCollection, useFrappeConnection, useFrappeDoctypeEvents, useInfiniteScroll, useFrappeInfiniteList, __getActiveSyncModule, } from "./frappeReact";
-export type { FrappeConnectionState, UseFrappeCollectionConfig, UseInfiniteScrollConfig, UseInfiniteScrollResult, UseFrappeInfiniteListConfig, UseFrappeInfiniteListResult, } from "./frappeReact";
+export { createOptimisticAction, isOptimisticTempId, newOptimisticTempId, OPTIMISTIC_TEMP_PREFIX, runOptimisticRpc, } from "./optimistic";
+export type { OptimisticRpcContext, OptimisticRpcOptions } from "./optimistic";
+export { useFrappeCollection, useFrappeConnection, useFrappeDoctypeEvents, useFrappePendingMutations, useInfiniteScroll, useFrappeInfiniteList, getFrappeSyncModule, __getActiveSyncModule, } from "./frappeReact";
+export type { FrappeConnectionState, UseFrappeCollectionConfig, UseFrappePendingMutationsResult, UseInfiniteScrollConfig, UseInfiniteScrollResult, UseFrappeInfiniteListConfig, UseFrappeInfiniteListResult, } from "./frappeReact";
 export type { SyncRealtimeEvent } from "./sync";
 export { useDebouncedSearch, useThrottledPagination, createRateLimitedBatch } from "./pacer";
 export type { DebouncedSearchOptions, DebouncedSearchResult, FrappeConnectionConfig, ThrottledPaginationOptions, ThrottledPaginationResult, RateLimitedBatchOptions, RateLimitedBatchHandle, } from "./pacer";
@@ -32,8 +34,8 @@ export type { BackfillArgs, BackfillResponse, CursorPaginationArgs, CursorPagina
 export { useDocTypeMeta, useLinkSearch, useLinkTitle, useDocTypeSearch, parseDependsOn, parseFormLayout, } from "./doctype";
 export type { DocTypeMeta, DocTypeField, DocTypePermission, FormSection, FormColumn, FrappeFieldType, LinkSearchResult, LinkSearchOptions, DocTypeSearchResult, } from "./doctype";
 export type { FrappeDocValue, FrappeDocData, FrappeDoc, ChildTableRow } from "./common/types";
-export type { SyncOptions, PageBoundaries, RehydrationStrategy, Mutation, ConnectionConfig, TabCoordinationConfig, TabMessage, FrappeDebugState, DebugSubscription, DebugMutationEntry, PageIsland, } from "./sync/types";
-export { Order } from "./sync/types";
+export type { SyncOptions, PageBoundaries, RehydrationStrategy, Mutation, CreateMutation, UpdateMutation, DeleteMutation, ConnectionConfig, TabCoordinationConfig, TabMessage, FrappeDebugState, DebugSubscription, DebugMutationEntry, PageIsland, } from "./sync/types";
+export { Order, Operation } from "./sync/types";
 export { MergeStrategy, FieldMergeStrategy } from "./sync/merge";
 export type { FieldMergeStrategyOrFunction, MergeConfig, MergeResult } from "./sync/merge";
 export { matchesFilters, validateFilters, normalizeFilters, extractFilterFields, extractSingleName, formatFilter, hasServerOnlyOperators, canEvaluateClientSide, isTreeOperator, getClientEvaluationBlockers, FilterOperator, } from "./sync/filters";

package/types/index.d.ts.map

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

package/types/optimistic.d.ts

@@ -35,4 +35,42 @@ export { tanstackCreateOptimisticAction as createOptimisticAction };
  * await tx.isPersisted.promise;
  * ```
  */
+/** Prefix shared with the MutationEngine's synthesized create identities. */
+export declare const OPTIMISTIC_TEMP_PREFIX = "tmp_";
+/** Issues a client-only identity for an optimistic record (`tmp_<uuid>`). */
+export declare function newOptimisticTempId(): string;
+/** True when a document name is a client-issued optimistic identity. */
+export declare function isOptimisticTempId(name: unknown): name is string;
+export interface OptimisticRpcContext {
+    /** Client-only identity for the optimistic record (`tmp_<uuid>`). */
+    tempId: string;
+}
+export interface OptimisticRpcOptions<TAck> {
+    /**
+     * Apply the mutation locally, synchronously, before the request is sent.
+     * Returns the undo that restores the exact pre-apply state (rollback).
+     * The applied record should use `ctx.tempId` as its identity and carry a
+     * pending marker for the UI.
+     */
+    apply: (ctx: OptimisticRpcContext) => (() => void) | undefined | void;
+    /** The server RPC. */
+    send: (ctx: OptimisticRpcContext) => Promise<TAck>;
+    /**
+     * Converge on ack: replace the `ctx.tempId` record with the server's
+     * authoritative record (dedupe by server identity — a racing refetch may
+     * already have delivered it).
+     */
+    reconcile?: (ack: TAck, ctx: OptimisticRpcContext) => void;
+    /**
+     * Visible-error surface for the rollback path (house `notify()` or an
+     * inline error slot). Runs after the apply-phase undo.
+     */
+    onError?: (error: unknown, ctx: OptimisticRpcContext) => void;
+}
+/**
+ * Runs one mutation through the optimistic lifecycle:
+ * apply (local, immediate) → send → reconcile on ack, or undo + onError on
+ * failure (the error rethrows).
+ */
+export declare function runOptimisticRpc<TAck>(options: OptimisticRpcOptions<TAck>): Promise<TAck>;
 //# sourceMappingURL=optimistic.d.ts.map

package/types/optimistic.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"optimistic.d.ts","sourceRoot":"","sources":["../src/optimistic.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,sBAAsB,IAAI,8BAA8B,EAAE,MAAM,cAAc,CAAC;AAExF,OAAO,EAAE,8BAA8B,IAAI,sBAAsB,EAAE,CAAC;AAEpE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG"}
+{"version":3,"file":"optimistic.d.ts","sourceRoot":"","sources":["../src/optimistic.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,sBAAsB,IAAI,8BAA8B,EAAE,MAAM,cAAc,CAAC;AAExF,OAAO,EAAE,8BAA8B,IAAI,sBAAsB,EAAE,CAAC;AAEpE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AA8BH,6EAA6E;AAC7E,eAAO,MAAM,sBAAsB,SAAS,CAAC;AAE7C,6EAA6E;AAC7E,wBAAgB,mBAAmB,IAAI,MAAM,CAM5C;AAED,wEAAwE;AACxE,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI,IAAI,MAAM,CAEhE;AAED,MAAM,WAAW,oBAAoB;IACnC,qEAAqE;IACrE,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,oBAAoB,CAAC,IAAI;IACxC;;;;;OAKG;IACH,KAAK,EAAE,CAAC,GAAG,EAAE,oBAAoB,KAAK,CAAC,MAAM,IAAI,CAAC,GAAG,SAAS,GAAG,IAAI,CAAC;IACtE,sBAAsB;IACtB,IAAI,EAAE,CAAC,GAAG,EAAE,oBAAoB,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACnD;;;;OAIG;IACH,SAAS,CAAC,EAAE,CAAC,GAAG,EAAE,IAAI,EAAE,GAAG,EAAE,oBAAoB,KAAK,IAAI,CAAC;IAC3D;;;OAGG;IACH,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE,oBAAoB,KAAK,IAAI,CAAC;CAC/D;AAED;;;;GAIG;AACH,wBAAsB,gBAAgB,CAAC,IAAI,EAAE,OAAO,EAAE,oBAAoB,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAe/F"}

package/types/pacer.d.ts

@@ -1,5 +1,6 @@
 import type { Collection } from "@tanstack/db";
 import type { FrappeDoc, FrappeDocData } from "./common/types";
+import type { FixtureProvider } from "./fixtures";
 import type { SyncModule } from "./sync";
 /**
  * Options for `useDebouncedSearch`.
@@ -47,6 +48,13 @@ export interface FrappeConnectionConfig {
         token?: string | (() => string | Promise<string>);
         type?: string;
     };
+    /**
+     * Fixture provider for story / test hosts. Consumers already forward it
+     * (frappe-ui's FrappeProvider builds this config from its own context), and
+     * `useDocTypeMeta` reads doctype metadata from it before reaching for the
+     * network.
+     */
+    fixtures?: FixtureProvider;
 }
 /**
  * Debounced search hook for Frappe doctypes.

package/types/pacer.d.ts.map

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

package/types/realtime.d.ts

@@ -6,6 +6,90 @@ export declare enum RealtimePlatform {
     Web = "web",
     ReactNative = "react-native"
 }
+export type RealtimeTransport = "socketio" | "sse";
+/** One SSE frame as received off the wire (before any mapping). */
+export interface SSEFrame {
+    /** SSE event type — the `event:` classification line, or `"message"` for unnamed frames. */
+    type: string;
+    /** Raw `data:` payload (SSE data is always a string). */
+    data: string;
+    /** The stream's last `id:` line as of this frame (empty when the server sent none). */
+    lastEventId: string;
+}
+/** One handler-map delivery produced by `RealtimeSSEConfig.mapFrame`. */
+export interface SSEMappedEvent {
+    event: string;
+    payload: unknown;
+}
+/** Minimal structural slice of a WHATWG `MessageEvent` the SSE transport reads. */
+export interface SSEMessageEventLike {
+    type?: string;
+    data?: unknown;
+    lastEventId?: string;
+}
+/**
+ * Minimal structural slice of the WHATWG EventSource interface used by the
+ * SSE transport. The global browser/Node implementation satisfies it, and so
+ * do the common polyfills (`eventsource` on npm, `react-native-sse`).
+ */
+export interface SSEEventSourceLike {
+    addEventListener(type: string, listener: (event: SSEMessageEventLike) => void): void;
+    removeEventListener(type: string, listener: (event: SSEMessageEventLike) => void): void;
+    close(): void;
+}
+export type SSEEventSourceConstructor = new (url: string, init?: {
+    withCredentials?: boolean;
+}) => SSEEventSourceLike;
+export interface RealtimeSSEConfig {
+    /** Absolute stream URL. Wins over `path` when both are set. */
+    url?: string;
+    /**
+     * Stream path resolved against `baseURL` (e.g.
+     * `"/api/method/shc.events.stream"` for the SHC daemon). One of `url` or
+     * `path` is REQUIRED: SSE endpoints are server-specific — a real Frappe
+     * bench has none at all — so a framework default would only ever 404, and
+     * `connect()` throws a descriptive error instead of guessing.
+     */
+    path?: string;
+    /**
+     * Browser EventSource credential mode: send cookies on the stream request.
+     * This is the primary browser auth path — EventSource cannot set request
+     * headers, so header-based token auth is impossible there (see
+     * `queryParams` for the token alternative).
+     */
+    withCredentials?: boolean;
+    /**
+     * Injectable EventSource constructor for runtimes without a global one
+     * (React Native, Node < 22, GJS) — e.g. the `eventsource` npm package or
+     * `react-native-sse`. When omitted the global `EventSource` is used, and
+     * `connect()` throws an error naming this option when neither exists.
+     */
+    EventSource?: SSEEventSourceConstructor;
+    /**
+     * Named SSE event types (`event:` classification lines) to listen for, in
+     * addition to unnamed `"message"` frames and handler-registered names.
+     * EventSource only dispatches a NAMED event when a listener for that exact
+     * type is attached, so `mapFrame`-driven apps — whose handler names differ
+     * from the wire's frame types — must list the server's classifications
+     * here (e.g. `["docker", "audit", "error", "event"]` for the SHC daemon).
+     */
+    events?: string[];
+    /**
+     * Translate one SSE frame into zero or more handler deliveries. Return
+     * `null`/`undefined` to drop the frame. When omitted, the default mapping
+     * delivers under the frame's `event:` type name with `JSON.parse(data)` as
+     * the payload (falling back to the raw string when the data isn't JSON).
+     */
+    mapFrame?: (frame: SSEFrame) => SSEMappedEvent[] | null | undefined;
+    /**
+     * Extra query parameters appended to the stream URL — the token-auth path
+     * for SSE (headers are off-limits in browsers, see `withCredentials`).
+     * Values may be getters; they are re-resolved every time the EventSource
+     * is (re)created, so a rotated token is picked up by `updateAuth()`'s
+     * reconnect.
+     */
+    queryParams?: Record<string, string | (() => string | Promise<string>)>;
+}
 export interface RealtimeConfig {
     auth?: AuthConfig;
     baseURL: string;
@@ -22,6 +106,23 @@ export interface RealtimeConfig {
      * `/socket.io` to the SocketIO backend.
      */
     socketPort?: number;
+    /**
+     * Dial the Socket.IO connection at this origin instead of deriving host and
+     * port from `baseURL` + `socketPort`.
+     *
+     * Built for dev servers that proxy `/socket.io` on their own origin (e.g.
+     * apps/one's `frappeSocketioDevProxy`): pointing the socket at the PAGE
+     * origin makes the handshake same-origin, so the browser stops blocking the
+     * cross-origin polling response (the reflected allow-origin is the proxy's
+     * injected bench origin, not the page's). Only the connection target
+     * changes — the namespace still comes from `siteName` (falling back to the
+     * `baseURL` hostname), because Frappe resolves the site server-side from
+     * the proxy-injected headers, not from where the client dialed.
+     *
+     * Wins over `socketPort` when both are set. Omit in production, where the
+     * reverse proxy already serves `/socket.io` on the `baseURL` origin.
+     */
+    socketBaseURL?: string;
     /**
      * Frappe site name, used as the Socket.IO namespace.
      *
@@ -37,14 +138,49 @@ export interface RealtimeConfig {
     siteName?: string;
     platform?: RealtimePlatform;
     socketOptions?: Partial<ManagerOptions & SocketOptions>;
+    /**
+     * Wire transport for realtime events.
+     *
+     * - `"socketio"` (default): Frappe's real realtime server — Socket.IO with
+     *   doc/doctype rooms and two-way subscribe emits. Omitting `transport`
+     *   keeps this exact behavior.
+     * - `"sse"`: a one-way `text/event-stream` endpoint consumed via
+     *   EventSource. Built for Frappe-wire-compatible servers that serve
+     *   realtime as SSE instead of Socket.IO (e.g. the SHC daemon's
+     *   `GET /api/method/shc.events.stream`). Requires `sse.url` or `sse.path`.
+     *   Room subscriptions become client-side bookkeeping (nothing can be
+     *   emitted upstream) and `sse.mapFrame` decides how server frames fan out
+     *   to handler events. Missed-event resume via the `Last-Event-ID` header
+     *   is native EventSource behavior and is not reimplemented here.
+     */
+    transport?: RealtimeTransport;
+    /** SSE transport options — only read when `transport` is `"sse"`. */
+    sse?: RealtimeSSEConfig;
 }
+export type DocRoom = {
+    doctype: string;
+    name: string;
+};
+export type ListRoom = {
+    doctype: string;
+    filters?: Record<string, unknown>;
+};
 export declare class RealtimeModule {
     private socket;
+    /** Live EventSource when the `"sse"` transport is active. */
+    private eventSource;
     private handlerMap;
     /** Tracks events with socket listeners attached to prevent duplicates. */
     private attachedSocketEvents;
     /** Stored socket event handler references for proper cleanup. */
     private socketEventHandlers;
+    /** Tracks SSE event types with listeners attached to prevent duplicates. */
+    private attachedSseEvents;
+    /** Stored SSE listener references for proper cleanup. */
+    private sseListeners;
+    /** One-shot debug notices for SSE's one-way limitations. */
+    private sseRoomNoticeLogged;
+    private sseEmitNoticeLogged;
     /** Active doc rooms — re-emitted on every (re)connect. */
     private docRooms;
     /** Active list rooms — re-emitted on every (re)connect. */
@@ -70,10 +206,46 @@ export declare class RealtimeModule {
      */
     private refreshSocketAuth;
     private resolveHealthyWaiters;
+    private isSSE;
     private waitUntilHealthy;
     private ensureConnected;
     private resubscribeRooms;
-    private connect;
+    /**
+     * Open the realtime transport now. Room-driven auto-connect
+     * (subscribeDoc/subscribeList) remains the primary lifecycle in both
+     * transports — this is public for SSE consumers that use no doc/list room
+     * bookkeeping: a one-way stream has nothing to emit on join, so nothing
+     * else would ever open it. Idempotent while a transport exists or a
+     * connect is in flight.
+     */
+    connect(): Promise<void>;
+    /**
+     * SSE branch of connect(): construct an EventSource against the configured
+     * stream URL. EventSource connects at construction, auto-reconnects on
+     * failure, and resumes missed frames itself by sending the stream's last
+     * `id:` as the `Last-Event-ID` request header — none of that is
+     * reimplemented here.
+     */
+    private connectSSE;
+    private buildSSEURL;
+    private initSSEHandlers;
+    private attachSSEListener;
+    private detachSSEListener;
+    private isCoreSSEType;
+    /**
+     * Single entry point for everything the EventSource dispatches. Dataless
+     * events are transport lifecycle (`open`/`error` as plain Events); anything
+     * carrying `data` is a server frame — including frames the server
+     * classified `event: error`, which arrive as MessageEvents WITH data and
+     * must not be mistaken for connection errors.
+     */
+    private handleSSEEvent;
+    /**
+     * Logged once: SSE is one-way, so doc/list room membership can't be sent
+     * upstream — rooms are recorded client-side (see getDocRooms/getListRooms)
+     * for mapFrame-driven filtering and for a future two-way transport.
+     */
+    private logSSERoomNoticeOnce;
     /**
      * Tear down the socket without clearing app handlers or room subscriptions.
      * Used by auth refresh so listeners/rooms survive credential rotation.
@@ -117,5 +289,15 @@ export declare class RealtimeModule {
     updateAuth(auth: AuthConfig): Promise<void>;
     emit(event: string, data: unknown): void;
     getSocket(): Socket<import("@socket.io/component-emitter").DefaultEventsMap, import("@socket.io/component-emitter").DefaultEventsMap> | undefined;
+    /** Live EventSource when the SSE transport is connected (undefined otherwise). */
+    getEventSource(): SSEEventSourceLike | undefined;
+    /**
+     * Doc rooms recorded by subscribeDoc. Under SSE these are client-side
+     * bookkeeping only (nothing is emitted upstream) — mapFrame-driven apps
+     * consult them to filter or route frames.
+     */
+    getDocRooms(): DocRoom[];
+    /** List rooms recorded by subscribeList — same client-side semantics as getDocRooms. */
+    getListRooms(): ListRoom[];
 }
 //# sourceMappingURL=realtime.d.ts.map

package/types/realtime.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"realtime.d.ts","sourceRoot":"","sources":["../src/realtime.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAE9E,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAG/C,MAAM,MAAM,OAAO,GAAG,CAAC,OAAO,EAAE,OAAO,KAAK,IAAI,CAAC;AAEjD,oBAAY,gBAAgB;IAC1B,IAAI,SAAS;IACb,GAAG,QAAQ;IACX,WAAW,iBAAiB;CAC7B;AAED,MAAM,WAAW,cAAc;IAC7B,IAAI,CAAC,EAAE,UAAU,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB;;;;;;;;;;;OAWG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,gBAAgB,CAAC;IAC5B,aAAa,CAAC,EAAE,OAAO,CAAC,cAAc,GAAG,aAAa,CAAC,CAAC;CACzD;AASD,qBAAa,cAAc;IACzB,OAAO,CAAC,MAAM,CAAqB;IACnC,OAAO,CAAC,UAAU,CAAmC;IACrD,0EAA0E;IAC1E,OAAO,CAAC,oBAAoB,CAAqB;IACjD,iEAAiE;IACjE,OAAO,CAAC,mBAAmB,CAAiD;IAC5E,0DAA0D;IAC1D,OAAO,CAAC,QAAQ,CAA8B;IAC9C,2DAA2D;IAC3D,OAAO,CAAC,SAAS,CAA+B;IAChD,OAAO,CAAC,aAAa,CAAS;IAC9B,OAAO,CAAC,YAAY,CAAS;IAC7B,OAAO,CAAC,cAAc,CAAoC;IAC1D,OAAO,CAAC,MAAM,CAAiB;IAC/B,oEAAoE;IACpE,OAAO,CAAC,mBAAmB,CAAC,CAAgB;gBAEhC,MAAM,EAAE,cAAc;IAOlC,OAAO,CAAC,cAAc;IAyBtB,OAAO,CAAC,YAAY;YA0BN,cAAc;IA2D5B;;;;;;;;OAQG;IACH,OAAO,CAAC,iBAAiB;IAmBzB,OAAO,CAAC,qBAAqB;IAK7B,OAAO,CAAC,gBAAgB;YAeV,eAAe;IAQ7B,OAAO,CAAC,gBAAgB;YAYV,OAAO;IA0CrB;;;OAGG;IACH,OAAO,CAAC,cAAc;IAgBtB,OAAO,CAAC,YAAY;IAwCpB;;OAEG;IACH,OAAO,CAAC,oBAAoB;IAW5B;;OAEG;IACH,OAAO,CAAC,oBAAoB;IAW5B,OAAO,CAAC,cAAc;IAQhB,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IAkBxD,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,IAAI;IAUpC,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAShE,cAAc,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI;IAQnD;;;;;;OAMG;IACG,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAQtF,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAQtC;;;;;;;;OAQG;IACH,OAAO,CAAC,gBAAgB;IASxB,SAAS;IAIT,UAAU,IAAI,IAAI;IAOZ,UAAU,CAAC,IAAI,EAAE,UAAU;IAejC,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO;IAMjC,SAAS;CAGV"}
+{"version":3,"file":"realtime.d.ts","sourceRoot":"","sources":["../src/realtime.ts"],"names":[],"mappings":"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"}

package/types/sync/index.d.ts

@@ -1,7 +1,7 @@
 import type { FrappeDoc, FrappeDocData } from "../common/types";
 import type { DbModule } from "../db";
 import type { RealtimeModule } from "../realtime";
-import type { BackfillArgs, SyncOptions, FrappeDebugState, Mutation, RealtimeEventType, SubscriptionQuery } from "./types";
+import type { BackfillArgs, DebugMutationEntry, SyncOptions, FrappeDebugState, Mutation, RealtimeEventType, SubscriptionQuery } from "./types";
 /** Realtime event forwarded to `subscribeRealtimeEvents` listeners. */
 export interface SyncRealtimeEvent {
     type: RealtimeEventType;
@@ -107,6 +107,21 @@ export declare class SyncModule {
      * Replays pending mutations with error handling.
      */
     replayPending(): Promise<void>;
+    /**
+     * Public read of the mutation ledger: journal entries still awaiting the
+     * server (`Status.Pending`) or rejected by it (`Status.Failed`), ordered
+     * by submission sequence. Confirmed entries are dropped from the journal
+     * and never appear here. Read inside a `subscribeStore` callback for a
+     * reactive pending/error surface (see `useFrappePendingMutations`).
+     */
+    getMutationEntries(doctype?: string): DebugMutationEntry[];
+    /**
+     * Drops a failed (or still-pending) ledger entry without retrying it —
+     * the "dismiss" half of the rejected-write contract. The optimistic
+     * rollback already ran when the mutation failed; this only clears the
+     * error affordance.
+     */
+    dismissMutation(id: string): void;
     /** Reads a single document from the local cache. */
     getDocFromCache<T extends FrappeDocData = FrappeDocData>(doctype: string, name: string): T | undefined;
     /** Returns subscription metadata by id. */

package/types/sync/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/sync/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAChE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AACtC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAUlD,OAAO,KAAK,EACV,YAAY,EAGZ,WAAW,EACX,gBAAgB,EAChB,QAAQ,EACR,iBAAiB,EACjB,iBAAiB,EAClB,MAAM,SAAS,CAAC;AAEjB,uEAAuE;AACvE,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,iBAAiB,CAAC;IACxB,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AACH,qBAAa,UAAU;IACrB,OAAO,CAAC,eAAe,CAAkB;IACzC,OAAO,CAAC,eAAe,CAAkB;IACzC,OAAO,CAAC,cAAc,CAAyB;IAC/C,0DAA0D;IAC1D,OAAO,CAAC,sBAAsB,CAAiD;IAC/E,OAAO,CAAC,mBAAmB,CAAsB;IACjD,sEAAsE;IACtE,OAAO,CAAC,cAAc,CAAiB;IACvC,wDAAwD;IACxD,OAAO,CAAC,eAAe,CAAkB;IACzC,+CAA+C;IAC/C,OAAO,CAAC,kBAAkB,CAAqB;IAC/C,gEAAgE;IAChE,OAAO,CAAC,kBAAkB,CAAqB;IAC/C,6DAA6D;IAC7D,OAAO,CAAC,YAAY,CAAC,CAAa;IAClC,OAAO,CAAC,kBAAkB,CAAC,CAAa;IACxC,OAAO,CAAC,qBAAqB,CAAC,CAAa;IAC3C,OAAO,CAAC,mBAAmB,CAAC,CAAa;IACzC,6CAA6C;IAC7C,OAAO,CAAC,iBAAiB,CAAC,CAAiC;IAC3D,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAW;IAC9B,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAiB;IAC3C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAc;gBAE1B,EAAE,EAAE,QAAQ,EAAE,QAAQ,CAAC,EAAE,cAAc,EAAE,OAAO,GAAE,WAAgB;IAoE9E;;;OAGG;IACH,OAAO,CAAC,iBAAiB;IAoBzB;;;;;;;;OAQG;IACG,SAAS,CAAC,IAAI,SAAS,aAAa,EAAE,KAAK,EAAE,iBAAiB;IAepE;;OAEG;IACH,WAAW,CAAC,cAAc,EAAE,MAAM;IAO5B,MAAM,CAAC,QAAQ,EAAE,QAAQ,CAAC,aAAa,CAAC;IAgB9C;;OAEG;IACG,QAAQ,CAAC,IAAI,EAAE,YAAY;IAKjC;;OAEG;IACG,aAAa;IAKnB,oDAAoD;IACpD,eAAe,CAAC,CAAC,SAAS,aAAa,GAAG,aAAa,EACrD,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,GACX,CAAC,GAAG,SAAS;IAIhB,2CAA2C;IAC3C,eAAe,CAAC,EAAE,EAAE,MAAM;IAI1B;;OAEG;IACH,sBAAsB,CAAC,IAAI,SAAS,aAAa,EAAE,EAAE,EAAE,MAAM,GAAG,SAAS,CAAC,IAAI,CAAC,EAAE;IAIjF;;;OAGG;IACG,OAAO,CAAC,IAAI,SAAS,aAAa,EACtC,cAAc,EAAE,MAAM,EACtB,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,CAAC;IAM7B;;;OAGG;IACG,YAAY,CAAC,IAAI,SAAS,aAAa,EAC3C,cAAc,EAAE,MAAM,EACtB,WAAW,EAAE,MAAM,EACnB,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,CAAC;IAU7B;;OAEG;IACH,WAAW,CAAC,cAAc,EAAE,MAAM;IAIlC,+EAA+E;IACzE,WAAW,CAAC,IAAI,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,EAAE;IAQ3D,8DAA8D;IAC9D,cAAc,CAAC,QAAQ,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI;IAOhD;;;;;OAKG;IACH,uBAAuB,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,iBAAiB,KAAK,IAAI,GAAG,MAAM,IAAI;IAOjF;;;;OAIG;IACH,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAInC,6CAA6C;IAC7C,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAIrC;;;;;;OAMG;IACH,kBAAkB,IAAI;QAAE,SAAS,EAAE,OAAO,CAAC;QAAC,aAAa,EAAE,OAAO,CAAA;KAAE;IAIpE,mFAAmF;IACnF,OAAO,CAAC,IAAI;IASZ,kEAAkE;IAClE,UAAU;IAYV,uCAAuC;IACjC,OAAO;IA+Bb;;;OAGG;IACH,OAAO,IAAI,gBAAgB;IA0E3B;;OAEG;IACH,QAAQ,IAAI,OAAO;CAGpB"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/sync/index.ts"],"names":[],"mappings":"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"}

package/types/sync/mutationEngine.d.ts

@@ -43,6 +43,13 @@ export declare class MutationEngine {
     private handleOptimisticCreate;
     private handleServerCreate;
     private handleServerUpdate;
+    /**
+     * Applies the local side of a delete: cache eviction, subscription
+     * membership removal, and gap-filling rehydration. Runs before the server
+     * call (mutate() body) so the row disappears immediately; the journal
+     * snapshot restores it if the server rejects.
+     */
+    private applyOptimisticDelete;
     private handleServerDelete;
     private handleTemporaryToRealMapping;
     private refetchAffectedDocs;

package/types/sync/mutationEngine.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mutationEngine.d.ts","sourceRoot":"","sources":["../../src/sync/mutationEngine.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAa,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAChE,OAAO,KAAK,EAAiB,QAAQ,EAAE,MAAM,OAAO,CAAC;AACrD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAIlD,OAAO,KAAK,EAAE,eAAe,EAAW,MAAM,mBAAmB,CAAC;AAClE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACzD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AACxD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAUjE,OAAO,KAAK,EAGV,WAAW,EACX,QAAQ,EAIT,MAAM,SAAS,CAAC;AASjB,MAAM,WAAW,SAAS;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,OAAO,CAAC;CAChB;AAED,qBAAa,cAAc;IACzB,OAAO,CAAC,wBAAwB,CAA6B;IAC7D,OAAO,CAAC,sBAAsB,CAAkC;IAChE,8CAA8C;IAC9C,OAAO,CAAC,YAAY,CAA6C;IACjE,qCAAqC;IACrC,OAAO,CAAC,cAAc,CAAiC;IACvD,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAW;IAC9B,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA6B;IACtD,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAkB;IAClD,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAkB;IAClD,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAsB;IAC1D,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAqB;IACxD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAc;gBAGpC,EAAE,EAAE,QAAQ,EACZ,QAAQ,EAAE,cAAc,GAAG,SAAS,EACpC,eAAe,EAAE,eAAe,EAChC,eAAe,EAAE,eAAe,EAChC,mBAAmB,EAAE,mBAAmB,EACxC,kBAAkB,EAAE,kBAAkB,EACtC,OAAO,GAAE,WAAgB;IAc3B;;;OAGG;IACH,OAAO,CAAC,aAAa;IAqBrB;;OAEG;YACW,UAAU;IAmFxB;;OAEG;IACG,eAAe,IAAI,OAAO,CAAC,IAAI,CAAC;IAKhC,MAAM,CAAC,IAAI,SAAS,aAAa,EAAE,QAAQ,EAAE,QAAQ,CAAC,IAAI,CAAC;YAyHnD,sBAAsB;YAgBtB,sBAAsB;YA0DtB,kBAAkB;YAoClB,kBAAkB;YAQlB,kBAAkB;IAwBhC,OAAO,CAAC,4BAA4B;YAuBtB,mBAAmB;YAwBnB,mBAAmB;IA4BjC;;;OAGG;YACW,uBAAuB;YA6CvB,kBAAkB;YAwBlB,cAAc;IAyD5B;;;;;;;;;;;;;;;;OAgBG;IACH,OAAO,CAAC,4BAA4B;IA6DpC,OAAO,CAAC,gCAAgC;IAkCxC,OAAO,CAAC,eAAe;IAoBvB;;;;;;;;;;;;;;;;OAgBG;IACG,aAAa;IA0GnB;;OAEG;IACH,OAAO,CAAC,aAAa;IAqBrB;;OAEG;IACH,OAAO,CAAC,mBAAmB;IAgD3B;;;OAGG;IACH,OAAO,CAAC,gBAAgB;IAWxB,2CAA2C;IAC3C,2BAA2B,IAAI,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC;IAIlD,qCAAqC;IACrC,sBAAsB;IAKtB;;OAEG;IACH,OAAO;CAMR"}
+{"version":3,"file":"mutationEngine.d.ts","sourceRoot":"","sources":["../../src/sync/mutationEngine.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAa,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAChE,OAAO,KAAK,EAAiB,QAAQ,EAAE,MAAM,OAAO,CAAC;AACrD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAIlD,OAAO,KAAK,EAAE,eAAe,EAAW,MAAM,mBAAmB,CAAC;AAClE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACzD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AACxD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAUjE,OAAO,KAAK,EAGV,WAAW,EACX,QAAQ,EAIT,MAAM,SAAS,CAAC;AAqBjB,MAAM,WAAW,SAAS;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,OAAO,CAAC;CAChB;AAED,qBAAa,cAAc;IACzB,OAAO,CAAC,wBAAwB,CAA6B;IAC7D,OAAO,CAAC,sBAAsB,CAAkC;IAChE,8CAA8C;IAC9C,OAAO,CAAC,YAAY,CAA6C;IACjE,qCAAqC;IACrC,OAAO,CAAC,cAAc,CAAiC;IACvD,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAW;IAC9B,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA6B;IACtD,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAkB;IAClD,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAkB;IAClD,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAsB;IAC1D,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAqB;IACxD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAc;gBAGpC,EAAE,EAAE,QAAQ,EACZ,QAAQ,EAAE,cAAc,GAAG,SAAS,EACpC,eAAe,EAAE,eAAe,EAChC,eAAe,EAAE,eAAe,EAChC,mBAAmB,EAAE,mBAAmB,EACxC,kBAAkB,EAAE,kBAAkB,EACtC,OAAO,GAAE,WAAgB;IAc3B;;;OAGG;IACH,OAAO,CAAC,aAAa;IAqBrB;;OAEG;YACW,UAAU;IAmFxB;;OAEG;IACG,eAAe,IAAI,OAAO,CAAC,IAAI,CAAC;IAKhC,MAAM,CAAC,IAAI,SAAS,aAAa,EAAE,QAAQ,EAAE,QAAQ,CAAC,IAAI,CAAC;YA2InD,sBAAsB;YAgBtB,sBAAsB;YA0DtB,kBAAkB;YAwClB,kBAAkB;IAoBhC;;;;;OAKG;IACH,OAAO,CAAC,qBAAqB;YAef,kBAAkB;IAahC,OAAO,CAAC,4BAA4B;YAuBtB,mBAAmB;YAwBnB,mBAAmB;IA4BjC;;;OAGG;YACW,uBAAuB;YA6CvB,kBAAkB;YAwBlB,cAAc;IAyD5B;;;;;;;;;;;;;;;;OAgBG;IACH,OAAO,CAAC,4BAA4B;IA6DpC,OAAO,CAAC,gCAAgC;IAkCxC,OAAO,CAAC,eAAe;IAoBvB;;;;;;;;;;;;;;;;OAgBG;IACG,aAAa;IA0GnB;;OAEG;IACH,OAAO,CAAC,aAAa;IAqBrB;;OAEG;IACH,OAAO,CAAC,mBAAmB;IAgD3B;;;OAGG;IACH,OAAO,CAAC,gBAAgB;IAWxB,2CAA2C;IAC3C,2BAA2B,IAAI,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC;IAIlD,qCAAqC;IACrC,sBAAsB;IAKtB;;OAEG;IACH,OAAO;CAMR"}

package/types/sync/mutationJournal.d.ts

@@ -39,6 +39,12 @@ export declare class MutationJournal {
         message: string;
         [key: string]: unknown;
     }): void;
+    /**
+     * Drops an entry without confirming it — the "dismiss" affordance for a
+     * failed mutation the user chose not to retry. Unlike `confirm` this makes
+     * no claim the write reached the server.
+     */
+    remove(id: string): void;
     listPending(): {
         id: string;
         entry: Pending;

package/types/sync/mutationJournal.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mutationJournal.d.ts","sourceRoot":"","sources":["../../src/sync/mutationJournal.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAChE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AACzC,OAAO,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AAEjC,eAAO,MAAM,kBAAkB,yBAAyB,CAAC;AAEzD,MAAM,WAAW,OAAO;IACtB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,KAAK,GAAG;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;KAAE,CAAC;IAC5D,SAAS,EAAE,SAAS,CAAC;IACrB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,SAAS,CAAC,aAAa,CAAC,CAAC;IACpC,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,SAAS,CAAC,aAAa,CAAC,CAAC;IAClC,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,sBAAsB;IACrC,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,qBAAa,eAAe;IAC1B,OAAO,CAAC,YAAY,CAAC,CAAiC;IACtD,OAAO,CAAC,kBAAkB,CAAU;IACpC,OAAO,CAAC,GAAG,CAAuB;IAClC,OAAO,CAAC,OAAO,CAA8B;IAC7C,OAAO,CAAC,cAAc,CAAK;IAC3B,OAAO,CAAC,OAAO,CAAC,CAAU;gBAEd,OAAO,CAAC,EAAE,sBAAsB;IAgB5C,GAAG,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO;IAU9B,GAAG,CAAC,EAAE,EAAE,MAAM;IAUd,OAAO,CAAC,EAAE,EAAE,MAAM;IAOlB,IAAI,CAAC,EAAE,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,KAAK,GAAG;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;KAAE;IAS1E,WAAW;YACkB,MAAM;eAAS,OAAO;;IAcnD,aAAa,IAAI,KAAK,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,OAAO,CAAA;KAAE,CAAC;IAStD,cAAc;IAWd,eAAe;IAOf,KAAK;IAKL,OAAO;IAKP,OAAO,CAAC,eAAe;IAIvB,OAAO,CAAC,SAAS;IAKjB,OAAO,CAAC,gBAAgB;IAYxB,OAAO,CAAC,kBAAkB;IAM1B,OAAO,CAAC,qBAAqB;CAI9B"}
+{"version":3,"file":"mutationJournal.d.ts","sourceRoot":"","sources":["../../src/sync/mutationJournal.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAChE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AACzC,OAAO,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AAEjC,eAAO,MAAM,kBAAkB,yBAAyB,CAAC;AAEzD,MAAM,WAAW,OAAO;IACtB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,KAAK,GAAG;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;KAAE,CAAC;IAC5D,SAAS,EAAE,SAAS,CAAC;IACrB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,SAAS,CAAC,aAAa,CAAC,CAAC;IACpC,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,SAAS,CAAC,aAAa,CAAC,CAAC;IAClC,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,sBAAsB;IACrC,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,qBAAa,eAAe;IAC1B,OAAO,CAAC,YAAY,CAAC,CAAiC;IACtD,OAAO,CAAC,kBAAkB,CAAU;IACpC,OAAO,CAAC,GAAG,CAAuB;IAClC,OAAO,CAAC,OAAO,CAA8B;IAC7C,OAAO,CAAC,cAAc,CAAK;IAC3B,OAAO,CAAC,OAAO,CAAC,CAAU;gBAEd,OAAO,CAAC,EAAE,sBAAsB;IAgB5C,GAAG,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO;IAU9B,GAAG,CAAC,EAAE,EAAE,MAAM;IAUd,OAAO,CAAC,EAAE,EAAE,MAAM;IAOlB,IAAI,CAAC,EAAE,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,KAAK,GAAG;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;KAAE;IAS1E;;;;OAIG;IACH,MAAM,CAAC,EAAE,EAAE,MAAM;IAIjB,WAAW;YACkB,MAAM;eAAS,OAAO;;IAcnD,aAAa,IAAI,KAAK,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,OAAO,CAAA;KAAE,CAAC;IAStD,cAAc;IAWd,eAAe;IAOf,KAAK;IAKL,OAAO;IAKP,OAAO,CAAC,eAAe;IAIvB,OAAO,CAAC,SAAS;IAKjB,OAAO,CAAC,gBAAgB;IAYxB,OAAO,CAAC,kBAAkB;IAM1B,OAAO,CAAC,qBAAqB;CAI9B"}

package/types/sync/types.d.ts

@@ -104,6 +104,18 @@ export interface CreateMutation<D extends FrappeDocData> {
      * this single field.
      */
     temporaryName?: string;
+    /**
+     * Custom server transport. When set, the engine performs the write via
+     * this function instead of `db.createDoc` — everything else (optimistic
+     * apply, journal, temp→real remap, rollback, ledger) is unchanged. Used
+     * for desk RPCs whose server-side behavior a plain REST insert cannot
+     * reproduce (e.g. `frappe.desk.form.utils.add_comment` inserts with
+     * ignore_permissions and extracts inline images). Must resolve with the
+     * created document (the ack the remap needs). Mutations carrying a
+     * transport skip request batching, and a journal replay after a page
+     * refresh falls back to the REST path (functions don't persist).
+     */
+    execute?: () => Promise<FrappeDoc<D>>;
 }
 export interface UpdateMutation<Data extends FrappeDocData> {
     mutationId: string;
@@ -114,6 +126,12 @@ export interface UpdateMutation<Data extends FrappeDocData> {
         doctype: string;
         name: string;
     }[];
+    /**
+     * Custom server transport (see {@link CreateMutation.execute}). May
+     * resolve with the updated document to seed the cache; resolving void
+     * keeps the optimistic value until the realtime echo reconciles.
+     */
+    execute?: () => Promise<FrappeDoc<Data> | void>;
 }
 export interface DeleteMutation<Data extends FrappeDocData> {
     mutationId: string;
@@ -124,6 +142,8 @@ export interface DeleteMutation<Data extends FrappeDocData> {
         doctype: string;
         name: string;
     }[];
+    /** Custom server transport (see {@link CreateMutation.execute}). */
+    execute?: () => Promise<void>;
 }
 export type Mutation<Data extends FrappeDocData> = CreateMutation<Data> | UpdateMutation<Data> | DeleteMutation<Data>;
 export declare enum BackfillScope {