@multiplatform.one/frappe 6.7.0 → 7.0.0

package/src/doctype.ts

@@ -503,6 +503,13 @@ function useHttpClientRef(
 /**
  * Fetch and cache DocType metadata (schema, fields, layout, permissions).
  *
+ * Metadata comes from `frappe.desk.form.load.getdoctype`, the whitelisted RPC
+ * the Desk itself uses, so ordinary users load forms too — the REST
+ * `/api/resource/DocType/<name>` route reads the DocType *document* and is
+ * System-Manager-only. That route stays as a fallback for desk-less sites
+ * where the RPC is not registered. When `config.fixtures` carries a "DocType"
+ * entry for the doctype it is used instead and no request is made.
+ *
  * Responses are cached per-session in memory keyed by `{baseURL}:{doctype}`.
  * The `refetch` function clears the cache entry and forces a fresh fetch.
  *
@@ -576,13 +583,50 @@ export function useDocTypeMeta(
 
     (async () => {
       try {
-        const response = await http.get<{ data: RawDocTypeResponse }>(
-          `/api/resource/DocType/${encodeURIComponent(doctype)}`,
-        );
-
+        // Fixture hosts (stories/tests) keep the getdoctype-shaped meta doc in
+        // the provider's "DocType" collection — the same convention the
+        // backoffice meta loader uses. Providers that stub only documents fall
+        // through to the network below.
+        const fromFixtures = config.fixtures
+          ? ((await config.fixtures.getDoc("DocType", doctype)) as RawDocTypeResponse | null)
+          : null;
         if (cancelled) return;
 
-        const raw = response.payload?.data;
+        let raw = fromFixtures?.fields ? fromFixtures : undefined;
+
+        if (!raw) {
+          // `getdoctype` is the whitelisted RPC the Desk itself loads form
+          // metadata with, and every logged-in user may call it. Reading
+          // `/api/resource/DocType/<name>` instead asks for the DocType
+          // *document*, which only System Manager holds read permission on, so
+          // ordinary users got a 403 PermissionError — and Frappe's
+          // developer-mode traceback rendered into the UI instead of a form.
+          const response = await http.get<{ docs?: RawDocTypeResponse[] }>(
+            "/api/method/frappe.desk.form.load.getdoctype",
+            { doctype },
+          );
+
+          if (cancelled) return;
+
+          // docs[0] is the requested doctype; docs[1..] are its child tables.
+          const docs = response.payload?.docs;
+          raw = docs?.find((doc) => doc?.name === doctype) ?? docs?.[0];
+        }
+
+        if (!raw) {
+          // Sites that expose the REST API without the desk leave the RPC
+          // above unregistered, so it answers with no `docs`. The document
+          // route still serves meta there, and such a site's API clients are
+          // typically System Managers, who may read it.
+          const rest = await http.get<{ data?: RawDocTypeResponse }>(
+            `/api/resource/DocType/${encodeURIComponent(doctype)}`,
+          );
+
+          if (cancelled) return;
+
+          raw = rest.payload?.data;
+        }
+
         if (!raw) {
           throw new Error(`No data returned for DocType "${doctype}"`);
         }
@@ -605,8 +649,8 @@ export function useDocTypeMeta(
     // Depend on the stable string `cacheKey` (baseURL + doctype), NOT the
     // `config` object — callers frequently pass a freshly-allocated config
     // object every render. Keying on the object identity would re-run this
-    // effect on every render and, when the request fails (e.g. a Guest hitting
-    // the permission-gated DocType meta endpoint → 403, which never populates
+    // effect on every render and, when the request fails (e.g. a Guest calling
+    // the login-gated getdoctype RPC → 403, which never populates
     // `metaCache`), spin into an infinite refetch loop.
   }, [cacheKey, version]);
 

package/src/frappeReact.ts

@@ -1,6 +1,6 @@
 import { isWindowDefined } from "@multiplatform.one/platform";
 import type { Collection } from "@tanstack/db";
-import { useCallback, useEffect, useRef, useState } from "react";
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import {
   createFrappeCollection,
   releaseFrappeCollectionSync,
@@ -12,6 +12,8 @@ import { DbModule } from "./db";
 import { FixtureDbModule } from "./fixtureDb";
 import { RealtimeModule } from "./realtime";
 import { SyncModule } from "./sync";
+import { Status } from "./sync/types";
+import type { DebugMutationEntry } from "./sync/types";
 import { isBrowser } from "./util";
 
 /**
@@ -26,6 +28,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;
@@ -61,6 +77,20 @@ export function __getActiveSyncModule(): SyncModule | undefined {
   return 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 function getFrappeSyncModule(
+  config: UseFrappeCollectionConfig | undefined,
+): SyncModule | undefined {
+  if (!config) return undefined;
+  return getSyncModule(config);
+}
+
 /**
  * Gets or creates a shared SyncModule for the given config.
  * SyncModules are cached by baseURL to prevent duplicate connections.
@@ -90,7 +120,18 @@ function getSyncModule(config: UseFrappeCollectionConfig): SyncModule | undefine
     return sync;
   }
 
-  const key = config.baseURL;
+  // Key on the full socket target, not just baseURL: socketPort /
+  // socketBaseURL / siteName all change where (or how) the realtime socket
+  // dials, so configs that differ in them must not share a SyncModule —
+  // sharing would silently keep the FIRST config's socket target for every
+  // later consumer. Consumers reading the same FrappeProvider still coalesce
+  // (identical fields → identical key).
+  const key = [
+    config.baseURL,
+    config.socketPort ?? "",
+    config.socketBaseURL ?? "",
+    config.siteName ?? "",
+  ].join("|");
   let sync = syncModuleCache.get(key);
   if (!sync) {
     // The FIRST config for a baseURL wins for every later consumer (the
@@ -114,6 +155,12 @@ function getSyncModule(config: UseFrappeCollectionConfig): SyncModule | undefine
     const realtimeConfig = {
       baseURL: config.baseURL,
       socketPort: config.socketPort,
+      socketBaseURL: config.socketBaseURL,
+      // Forward siteName: Frappe's realtime server only emits events on the
+      // site's namespace, so dropping it here silently connected sockets to
+      // a namespace the server rejects whenever the baseURL hostname isn't
+      // the site name (e.g. 127.0.0.1 vs "localhost").
+      siteName: config.siteName,
       auth: authConfig,
       socketOptions: config.socketOptions,
     };
@@ -601,6 +648,81 @@ export function useFrappeDoctypeEvents(
   }, [enabled, config?.baseURL, !!config?.fixtures, doctype]);
 }
 
+// ---------------------------------------------------------------------------
+// Mutation ledger hook
+// ---------------------------------------------------------------------------
+
+/** 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;
+}
+
+const EMPTY_LEDGER: DebugMutationEntry[] = [];
+
+/**
+ * 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 function useFrappePendingMutations(
+  config: UseFrappeCollectionConfig | undefined,
+  doctype?: string,
+): UseFrappePendingMutationsResult {
+  const [entries, setEntries] = useState<DebugMutationEntry[]>(EMPTY_LEDGER);
+  const syncModuleRef = useRef<SyncModule | undefined>(undefined);
+
+  useEffect(() => {
+    if (!config || !isBrowser()) {
+      setEntries(EMPTY_LEDGER);
+      return;
+    }
+    const syncModule = getSyncModule(config);
+    if (!syncModule) return;
+    syncModuleRef.current = syncModule;
+
+    let lastSignature = "";
+    const read = () => {
+      const next = syncModule.getMutationEntries(doctype);
+      const signature = next.map((e) => `${e.id}:${e.status}:${e.retryCount}`).join("|");
+      if (signature === lastSignature) return;
+      lastSignature = signature;
+      setEntries(next.length === 0 ? EMPTY_LEDGER : next);
+    };
+    read();
+    return syncModule.subscribeStore(read);
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [config?.baseURL, !!config?.fixtures, doctype]);
+
+  const retry = useCallback(async () => {
+    await syncModuleRef.current?.replayPending();
+  }, []);
+
+  const dismiss = useCallback((id: string) => {
+    syncModuleRef.current?.dismissMutation(id);
+  }, []);
+
+  return useMemo(() => {
+    const pending = entries.filter((e) => e.status === Status.Pending);
+    const failed = entries.filter((e) => e.status === Status.Failed);
+    return { entries, pending, failed, retry, dismiss };
+  }, [entries, retry, dismiss]);
+}
+
 // ---------------------------------------------------------------------------
 // Infinite Scroll Hook
 // ---------------------------------------------------------------------------
@@ -663,7 +785,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>
@@ -865,7 +987,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/src/index.ts

@@ -35,20 +35,30 @@ export {
   fixtureCollectionOptions,
 } from "./collection";
 export type { FrappeCollectionOptionsConfig, FixtureCollectionOptionsConfig } from "./collection";
-export { createOptimisticAction } from "./optimistic";
+export {
+  createOptimisticAction,
+  isOptimisticTempId,
+  newOptimisticTempId,
+  OPTIMISTIC_TEMP_PREFIX,
+  runOptimisticRpc,
+} from "./optimistic";
+export type { OptimisticRpcContext, OptimisticRpcOptions } from "./optimistic";
 
 // React hooks for Frappe + TanStack DB
 export {
   useFrappeCollection,
   useFrappeConnection,
   useFrappeDoctypeEvents,
+  useFrappePendingMutations,
   useInfiniteScroll,
   useFrappeInfiniteList,
+  getFrappeSyncModule,
   __getActiveSyncModule,
 } from "./frappeReact";
 export type {
   FrappeConnectionState,
   UseFrappeCollectionConfig,
+  UseFrappePendingMutationsResult,
   UseInfiniteScrollConfig,
   UseInfiniteScrollResult,
   UseFrappeInfiniteListConfig,
@@ -180,6 +190,9 @@ export type {
   PageBoundaries,
   RehydrationStrategy,
   Mutation,
+  CreateMutation,
+  UpdateMutation,
+  DeleteMutation,
   ConnectionConfig,
   TabCoordinationConfig,
   TabMessage,
@@ -188,7 +201,7 @@ export type {
   DebugMutationEntry,
   PageIsland,
 } from "./sync/types";
-export { Order } from "./sync/types";
+export { Order, Operation } from "./sync/types";
 export { MergeStrategy, FieldMergeStrategy } from "./sync/merge";
 export type { FieldMergeStrategyOrFunction, MergeConfig, MergeResult } from "./sync/merge";
 

package/src/optimistic.spec.ts

@@ -1,6 +1,12 @@
 import { createOptimisticAction as tanstackCreateOptimisticAction } from "@tanstack/db";
-import { describe, expect, it } from "vitest";
-import { createOptimisticAction } from "./optimistic";
+import { describe, expect, it, vi } from "vitest";
+import {
+  OPTIMISTIC_TEMP_PREFIX,
+  createOptimisticAction,
+  isOptimisticTempId,
+  newOptimisticTempId,
+  runOptimisticRpc,
+} from "./optimistic";
 
 describe("createOptimisticAction re-export", () => {
   it("is the same reference as @tanstack/db createOptimisticAction", () => {
@@ -11,3 +17,108 @@ describe("createOptimisticAction re-export", () => {
     expect(typeof createOptimisticAction).toBe("function");
   });
 });
+
+describe("newOptimisticTempId / isOptimisticTempId", () => {
+  it("issues unique tmp_-prefixed identities (MutationEngine convention)", () => {
+    const a = newOptimisticTempId();
+    const b = newOptimisticTempId();
+    expect(a.startsWith(OPTIMISTIC_TEMP_PREFIX)).toBe(true);
+    expect(b.startsWith(OPTIMISTIC_TEMP_PREFIX)).toBe(true);
+    expect(a).not.toBe(b);
+    expect(isOptimisticTempId(a)).toBe(true);
+  });
+
+  it("rejects server-issued names and non-strings", () => {
+    expect(isOptimisticTempId("TODO-0001")).toBe(false);
+    expect(isOptimisticTempId(undefined)).toBe(false);
+    expect(isOptimisticTempId(42)).toBe(false);
+  });
+});
+
+describe("runOptimisticRpc lifecycle", () => {
+  it("applies locally BEFORE the request resolves (local apply is the first reveal)", async () => {
+    const order: string[] = [];
+    let releaseSend: (value: string) => void = () => {};
+    const sendGate = new Promise<string>((resolve) => {
+      releaseSend = resolve;
+    });
+
+    const promise = runOptimisticRpc<string>({
+      apply: () => {
+        order.push("apply");
+        return () => order.push("undo");
+      },
+      send: async () => {
+        order.push("send");
+        return sendGate;
+      },
+      reconcile: () => order.push("reconcile"),
+    });
+
+    // Apply and send already happened synchronously; the ack has not landed.
+    expect(order).toEqual(["apply", "send"]);
+    releaseSend("ack");
+    await expect(promise).resolves.toBe("ack");
+    expect(order).toEqual(["apply", "send", "reconcile"]);
+  });
+
+  it("passes the SAME temp id through apply, send, and reconcile (identity convergence)", async () => {
+    const seen: string[] = [];
+    await runOptimisticRpc({
+      apply: (ctx) => {
+        seen.push(ctx.tempId);
+      },
+      send: async (ctx) => {
+        seen.push(ctx.tempId);
+        return "ok";
+      },
+      reconcile: (_ack, ctx) => {
+        seen.push(ctx.tempId);
+      },
+    });
+    expect(seen).toHaveLength(3);
+    expect(new Set(seen).size).toBe(1);
+    expect(isOptimisticTempId(seen[0])).toBe(true);
+  });
+
+  it("rolls back (undo) then surfaces the error visibly (onError) on failure, and rethrows", async () => {
+    const order: string[] = [];
+    const failure = new Error("server said no");
+    const onError = vi.fn((error: unknown) => {
+      order.push("onError");
+      expect(error).toBe(failure);
+    });
+
+    await expect(
+      runOptimisticRpc({
+        apply: () => {
+          order.push("apply");
+          return () => order.push("undo");
+        },
+        send: async () => {
+          throw failure;
+        },
+        reconcile: () => order.push("reconcile"),
+        onError,
+      }),
+    ).rejects.toBe(failure);
+
+    // Rollback precedes the visible error; reconcile never runs.
+    expect(order).toEqual(["apply", "undo", "onError"]);
+    expect(onError).toHaveBeenCalledTimes(1);
+  });
+
+  it("still surfaces onError when apply returned no undo", async () => {
+    const onError = vi.fn();
+    await expect(
+      runOptimisticRpc({
+        apply: () => {},
+        send: async () => {
+          throw new Error("boom");
+        },
+        onError,
+      }),
+    ).rejects.toThrow("boom");
+    expect(onError).toHaveBeenCalledTimes(1);
+  });
+});

package/src/optimistic.ts

@@ -37,3 +37,98 @@ export { tanstackCreateOptimisticAction as createOptimisticAction };
  * await tx.isPersisted.promise;
  * ```
  */
+
+// ---------------------------------------------------------------------------
+// Optimistic RPC lifecycle — the ONE pattern for mutations that ride
+// whitelisted desk RPCs instead of the document CRUD path.
+// ---------------------------------------------------------------------------
+//
+// Document CRUD (collection insert/update/delete) is already optimistic via
+// the MutationEngine: local cache apply → journal Pending → server ack →
+// temp-id → real-name remap, snapshot rollback on failure. Desk RPC
+// mutations (add_comment, assign_to, tags, likes, shares…) bypass that
+// engine, and every callsite used to hand-roll "await, then refetch" — the
+// user saw nothing until the server round-trip completed.
+//
+// `runOptimisticRpc` gives those callsites the same lifecycle the engine
+// gives documents, without per-callsite hacks:
+//
+//   1. APPLY     — synchronous local apply BEFORE the request leaves;
+//                  returns the undo used for rollback. The applied state
+//                  should carry a pending marker so surfaces can render it
+//                  visible-but-distinct (Axiom 6 HONEST STATE).
+//   2. SEND      — the RPC itself.
+//   3. RECONCILE — on ack, converge the optimistic identity (the issued
+//                  `tmp_*` id) to the server identity so the optimistic
+//                  record and the server record become ONE record, never
+//                  duplicates.
+//   4. ROLLBACK  — on failure, the apply-phase undo runs, then `onError`
+//                  surfaces a visible error (house `notify()`), and the
+//                  error rethrows for the caller.
+
+/** Prefix shared with the MutationEngine's synthesized create identities. */
+export const OPTIMISTIC_TEMP_PREFIX = "tmp_";
+
+/** Issues a client-only identity for an optimistic record (`tmp_<uuid>`). */
+export function newOptimisticTempId(): string {
+  const id =
+    typeof crypto !== "undefined" && "randomUUID" in crypto
+      ? crypto.randomUUID()
+      : Math.random().toString(36).slice(2);
+  return `${OPTIMISTIC_TEMP_PREFIX}${id}`;
+}
+
+/** True when a document name is a client-issued optimistic identity. */
+export function isOptimisticTempId(name: unknown): name is string {
+  return typeof name === "string" && name.startsWith(OPTIMISTIC_TEMP_PREFIX);
+}
+
+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 async function runOptimisticRpc<TAck>(options: OptimisticRpcOptions<TAck>): Promise<TAck> {
+  const ctx: OptimisticRpcContext = { tempId: newOptimisticTempId() };
+  const undo = options.apply(ctx) ?? undefined;
+  try {
+    const ack = await options.send(ctx);
+    options.reconcile?.(ack, ctx);
+    return ack;
+  } catch (error) {
+    try {
+      undo?.();
+    } finally {
+      options.onError?.(error, ctx);
+    }
+    throw error;
+  }
+}

package/src/pacer.ts

@@ -6,6 +6,7 @@ import { useCallback, useMemo, useRef, useState } from "react";
 import type { FrappeDoc, FrappeDocData } from "./common/types";
 import type { AuthConfig } from "./core/types";
 import { DbModule } from "./db";
+import type { FixtureProvider } from "./fixtures";
 import { HttpClient } from "./core/http";
 import type { SyncModule } from "./sync";
 import { Operation } from "./sync/types";
@@ -62,6 +63,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;
 }
 
 function createDbModule(config: FrappeConnectionConfig): DbModule {

package/src/realtime.spec.ts

@@ -783,6 +783,68 @@ describe("RealtimeModule", () => {
       rt.disconnect();
     });
 
+    it("uses an explicit siteName as the Socket.IO namespace (127.0.0.1 → localhost)", async () => {
+      // Frappe socketio maps Host localhost/127.0.0.1 to conf.default_site
+      // and rejects any other namespace. Connecting via the IPv4 literal
+      // (the serve_dev.py workaround for shcd on [::1]:8000) must still
+      // join /localhost, not /127.0.0.1.
+      const rt = new RealtimeModule({
+        baseURL: "http://127.0.0.1:8000",
+        socketPort: 9000,
+        siteName: "localhost",
+      });
+      await (rt as any).connect();
+
+      const calls = (io as unknown as ReturnType<typeof vi.fn>).mock.calls;
+      expect(calls[calls.length - 1]?.[0]).toBe("http://127.0.0.1:9000/localhost");
+      rt.disconnect();
+    });
+
+    it("dials socketBaseURL when set, joining the siteName namespace (same-origin dev)", async () => {
+      // Web dev: the dev server proxies /socket.io on the PAGE origin (e.g.
+      // :3998) to the bench socketio — the client must dial that origin, not
+      // baseURL+socketPort, so the polling handshake is same-origin.
+      const rt = new RealtimeModule({
+        baseURL: "http://127.0.0.1:8000",
+        socketBaseURL: "http://127.0.0.1:3998",
+        siteName: "localhost",
+      });
+      await (rt as any).connect();
+
+      const calls = (io as unknown as ReturnType<typeof vi.fn>).mock.calls;
+      expect(calls[calls.length - 1]?.[0]).toBe("http://127.0.0.1:3998/localhost");
+      rt.disconnect();
+    });
+
+    it("socketBaseURL wins over socketPort and trims a trailing slash", async () => {
+      const rt = new RealtimeModule({
+        baseURL: "http://127.0.0.1:8000",
+        socketPort: 9000,
+        socketBaseURL: "http://localhost:3998/",
+        siteName: "localhost",
+      });
+      await (rt as any).connect();
+
+      const calls = (io as unknown as ReturnType<typeof vi.fn>).mock.calls;
+      expect(calls[calls.length - 1]?.[0]).toBe("http://localhost:3998/localhost");
+      rt.disconnect();
+    });
+
+    it("falls back to the baseURL hostname namespace under socketBaseURL without siteName", async () => {
+      // Same fallback as the derived path: the namespace comes from the
+      // BENCH URL's hostname — never from socketBaseURL, whose hostname is
+      // the dev server, not a Frappe site.
+      const rt = new RealtimeModule({
+        baseURL: "http://bench.example.com:8000",
+        socketBaseURL: "http://localhost:3998",
+      });
+      await (rt as any).connect();
+
+      const calls = (io as unknown as ReturnType<typeof vi.fn>).mock.calls;
+      expect(calls[calls.length - 1]?.[0]).toBe("http://localhost:3998/bench.example.com");
+      rt.disconnect();
+    });
+
     it("uses the token scheme when auth type is token", async () => {
       const rt = new RealtimeModule({
         baseURL: "http://localhost:3000",

package/src/realtime.ts

@@ -120,6 +120,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.
    *
@@ -223,6 +240,23 @@ export class RealtimeModule {
 
   private getSocketURL(): string {
     const base = this.config.baseURL.replace(/\/$/, "");
+    // Same-origin override: dial socketBaseURL directly (e.g. the page
+    // origin, whose dev server proxies /socket.io to the bench's socketio).
+    // The namespace is still siteName — falling back to the baseURL hostname
+    // exactly like the derived path below, NOT the socketBaseURL hostname,
+    // which would be the dev-server host and never a Frappe site.
+    if (this.config.socketBaseURL) {
+      const socketBase = this.config.socketBaseURL.replace(/\/$/, "");
+      let siteName = this.config.siteName;
+      if (!siteName) {
+        try {
+          siteName = new URL(base).hostname;
+        } catch {
+          siteName = base.replace(/^https?:\/\//, "").split(/[/:]/)[0];
+        }
+      }
+      return `${socketBase}/${siteName}`;
+    }
     try {
       const url = new URL(base);
       // Assemble origin from parts instead of mutating url.port and reading