@dabble/patches 0.9.1 → 0.9.5

package/README.md

@@ -16,6 +16,26 @@ doc.change(state => (state.title = 'New Title'));
 
 Changes apply immediately for snappy UIs, then sync to the server in the background. Offline? No problem. Changes queue up and sync when you're back online.
 
+## Scope: what Patches is and is not
+
+Patches is a **generic primitives library**. It provides the building blocks (OT, LWW, sync transport, doc-store interfaces) for realtime systems. Compose it into your own backend and frontend.
+
+Patches knows about:
+
+- JSON documents, JSON Patch operations, and snapshots
+- Operational Transformation and Last-Write-Wins conflict resolution
+- A transport surface (WebSocket, SSE+REST, WebRTC) that moves changes between clients and a server
+- HTTP status codes propagated as `StatusError` (401, 403, 404, 410) — so consuming apps can branch on the response
+
+Patches does **not** know about:
+
+- Users, roles, invites, memberships, or any access-control model
+- Apps, projects, books, documents-as-products, or any app-specific terminology
+- Email sending, name/email lookups, or any identity service
+- UX policy for what to do when access is lost (consuming apps decide whether a 403 means "show a banner", "kick out of the doc", or anything else)
+
+If a feature feels like it belongs in Patches but mentions an app concept (e.g. "an invite for a project"), it doesn't belong here — it belongs one level up, in the app's own client SDK or in the consuming app itself. The Patches surface should stay generic enough to back any realtime system.
+
 ## Two Sync Strategies
 
 Patches gives you two conflict resolution approaches. Pick the right tool for the job.
@@ -254,7 +274,7 @@ When to use which? WebSocket for document sync. WebRTC for presence/cursors to r
 
 ### Awareness (Presence & Cursors)
 
-Show who's online, where their cursor is, what they're selecting. Works over both WebSocket and WebRTC.
+Show who's online, where their cursor is, what they're selecting. `WebRTCAwareness` carries presence over peer-to-peer WebRTC connections, with the signaling handshake multiplexed over whatever sync channel you already have open — `WebSocketTransport` or `PatchesREST` (SSE+REST). No second connection, same `clientId`.
 
 See [Awareness documentation](./docs/awareness.md) for implementation details.
 

package/dist/net/PatchesSync.d.ts

@@ -84,19 +84,6 @@ declare class PatchesSync extends ReadonlyStoreClass<PatchesSyncState> {
      * Provides the pending changes that were discarded so the application can handle them.
      */
     readonly onRemoteDocDeleted: easy_signal.Signal<(docId: string, pendingChanges: Change[]) => void>;
-    /**
-     * Signal emitted when the server reports the caller is no longer authorised
-     * to read/write a tracked document (e.g. a co-author was revoked, removed
-     * from a shared collection, or never had access in the first place).
-     *
-     * Local cleanup mirrors `onRemoteDocDeleted` — untrack, drop the local
-     * cache, return any pending changes that were lost — but the doc itself
-     * still exists server-side. Consumers that maintain a workspace listing
-     * (e.g. a "Shared with Me" dashboard) should remove the doc from their
-     * own state when this fires; otherwise it would resurface on next start
-     * and immediately re-fail with the same 403.
-     */
-    readonly onRemoteDocAccessRevoked: easy_signal.Signal<(docId: string, pendingChanges: Change[]) => void>;
     /**
      * Signal emitted after pending branch metas have been synced to the server.
      * Consumers should use this to refresh in-memory branch state (e.g. call `loadCached()`
@@ -196,21 +183,6 @@ declare class PatchesSync extends ReadonlyStoreClass<PatchesSyncState> {
      * Cleans up local state and notifies the application with any pending changes that were lost.
      */
     protected _handleRemoteDocDeleted(docId: string): Promise<void>;
-    /**
-     * Sibling of `_handleRemoteDocDeleted` for the access-revoked path.
-     * Same local cleanup (close, untrack, drop cache, clear sync state) but
-     * the doc is not tombstoned server-side — it just isn't ours anymore.
-     * Emitted as a distinct signal so consumers can show different UX
-     * ("Your access was revoked" vs. "Project was deleted") without having
-     * to inspect error codes themselves.
-     */
-    protected _handleRemoteDocAccessRevoked(docId: string): Promise<void>;
-    /**
-     * Local cleanup shared by `_handleRemoteDocDeleted` and
-     * `_handleRemoteDocAccessRevoked`. Returns pending changes that were
-     * lost so the caller can include them in the application-facing signal.
-     */
-    protected _cleanupAfterAccessLoss(docId: string): Promise<Change[]>;
     /**
      * Adds, updates, or removes a doc state entry immutably and notifies via store.
      * - Pass a full DocSyncState to add a new entry or overwrite an existing one.
@@ -239,14 +211,6 @@ declare class PatchesSync extends ReadonlyStoreClass<PatchesSyncState> {
      * Helper to detect DOC_DELETED (410) errors from the server.
      */
     protected _isDocDeletedError(err: unknown): boolean;
-    /**
-     * Helper to detect ACCESS_REVOKED (403) errors from the server. Used by
-     * the sync/flush catch blocks to short-circuit straight into the
-     * `_handleRemoteDocAccessRevoked` cleanup path rather than latching the
-     * error onto `docStates[docId].syncError` (which would surface as a
-     * permanent "Unable to Sync" pill in the UI).
-     */
-    protected _isAccessRevokedError(err: unknown): boolean;
 }
 
 export { PatchesSync, type PatchesSyncOptions, type PatchesSyncState };

package/dist/net/PatchesSync.js

@@ -52,19 +52,6 @@ class PatchesSync extends (_a = ReadonlyStoreClass, _syncDoc_dec = [serialGate],
      * Provides the pending changes that were discarded so the application can handle them.
      */
     __publicField(this, "onRemoteDocDeleted", signal());
-    /**
-     * Signal emitted when the server reports the caller is no longer authorised
-     * to read/write a tracked document (e.g. a co-author was revoked, removed
-     * from a shared collection, or never had access in the first place).
-     *
-     * Local cleanup mirrors `onRemoteDocDeleted` — untrack, drop the local
-     * cache, return any pending changes that were lost — but the doc itself
-     * still exists server-side. Consumers that maintain a workspace listing
-     * (e.g. a "Shared with Me" dashboard) should remove the doc from their
-     * own state when this fires; otherwise it would resurface on next start
-     * and immediately re-fail with the same 403.
-     */
-    __publicField(this, "onRemoteDocAccessRevoked", signal());
     /**
      * Signal emitted after pending branch metas have been synced to the server.
      * Consumers should use this to refresh in-memory branch state (e.g. call `loadCached()`
@@ -373,10 +360,6 @@ class PatchesSync extends (_a = ReadonlyStoreClass, _syncDoc_dec = [serialGate],
         await this._handleRemoteDocDeleted(docId);
         return;
       }
-      if (this._isAccessRevokedError(err)) {
-        await this._handleRemoteDocAccessRevoked(docId);
-        return;
-      }
       const syncError = err instanceof Error ? err : new Error(String(err));
       this._updateDocSyncState(docId, { syncStatus: "error", syncError });
       console.error(`Error syncing doc ${docId}:`, err);
@@ -438,10 +421,6 @@ class PatchesSync extends (_a = ReadonlyStoreClass, _syncDoc_dec = [serialGate],
         await this._handleRemoteDocDeleted(docId);
         return;
       }
-      if (this._isAccessRevokedError(err)) {
-        await this._handleRemoteDocAccessRevoked(docId);
-        return;
-      }
       const flushError = err instanceof Error ? err : new Error(String(err));
       this._updateDocSyncState(docId, { syncStatus: "error", syncError: flushError });
       console.error(`Flush failed for doc ${docId}:`, err);
@@ -583,27 +562,6 @@ class PatchesSync extends (_a = ReadonlyStoreClass, _syncDoc_dec = [serialGate],
    * Cleans up local state and notifies the application with any pending changes that were lost.
    */
   async _handleRemoteDocDeleted(docId) {
-    const pendingChanges = await this._cleanupAfterAccessLoss(docId);
-    await this.onRemoteDocDeleted.emit(docId, pendingChanges);
-  }
-  /**
-   * Sibling of `_handleRemoteDocDeleted` for the access-revoked path.
-   * Same local cleanup (close, untrack, drop cache, clear sync state) but
-   * the doc is not tombstoned server-side — it just isn't ours anymore.
-   * Emitted as a distinct signal so consumers can show different UX
-   * ("Your access was revoked" vs. "Project was deleted") without having
-   * to inspect error codes themselves.
-   */
-  async _handleRemoteDocAccessRevoked(docId) {
-    const pendingChanges = await this._cleanupAfterAccessLoss(docId);
-    await this.onRemoteDocAccessRevoked.emit(docId, pendingChanges);
-  }
-  /**
-   * Local cleanup shared by `_handleRemoteDocDeleted` and
-   * `_handleRemoteDocAccessRevoked`. Returns pending changes that were
-   * lost so the caller can include them in the application-facing signal.
-   */
-  async _cleanupAfterAccessLoss(docId) {
     const algorithm = this._getAlgorithm(docId);
     const pendingChanges = await algorithm.getPendingToSend(docId) ?? [];
     const doc = this.patches.getOpenDoc(docId);
@@ -613,7 +571,7 @@ class PatchesSync extends (_a = ReadonlyStoreClass, _syncDoc_dec = [serialGate],
     this.trackedDocs.delete(docId);
     this._updateDocSyncState(docId, void 0);
     await algorithm.confirmDeleteDoc(docId);
-    return pendingChanges;
+    await this.onRemoteDocDeleted.emit(docId, pendingChanges);
   }
   /**
    * Adds, updates, or removes a doc state entry immutably and notifies via store.
@@ -676,16 +634,6 @@ class PatchesSync extends (_a = ReadonlyStoreClass, _syncDoc_dec = [serialGate],
   _isDocDeletedError(err) {
     return err instanceof StatusError && err.code === ErrorCodes.DOC_DELETED;
   }
-  /**
-   * Helper to detect ACCESS_REVOKED (403) errors from the server. Used by
-   * the sync/flush catch blocks to short-circuit straight into the
-   * `_handleRemoteDocAccessRevoked` cleanup path rather than latching the
-   * error onto `docStates[docId].syncError` (which would surface as a
-   * permanent "Unable to Sync" pill in the UI).
-   */
-  _isAccessRevokedError(err) {
-    return err instanceof StatusError && err.code === ErrorCodes.ACCESS_REVOKED;
-  }
 }
 _init = __decoratorStart(_a);
 __decorateElement(_init, 1, "syncDoc", _syncDoc_dec, PatchesSync);

package/dist/net/error.d.ts

@@ -5,21 +5,21 @@ declare class StatusError extends Error {
 }
 /**
  * Standard error codes for Patches operations.
+ *
+ * Patches is permission-agnostic; these codes are surfaced verbatim from
+ * `StatusError.code` so consuming apps can branch on the HTTP status without
+ * reaching for string matching. Permission *policy* (what to do with a 403)
+ * lives in the consuming app.
  */
 declare const ErrorCodes: {
     /** Document was deleted (tombstone exists). */
     readonly DOC_DELETED: 410;
     /** Document not found (never existed). */
     readonly DOC_NOT_FOUND: 404;
-    /**
-     * Caller is no longer authorized to read/write the document.
-     * Distinct from DOC_DELETED — the doc still exists, the caller just lost
-     * membership (revoked, or removed from a shared collection). The sync
-     * loop treats it like a soft delete: untrack, drop local cache, emit
-     * `onRemoteDocAccessRevoked` so the application can remove the doc from
-     * its own workspace state.
-     */
-    readonly ACCESS_REVOKED: 403;
+    /** Caller is not authenticated (no/invalid credentials). */
+    readonly DOC_UNAUTHORIZED: 401;
+    /** Caller is authenticated but not authorized for this doc. */
+    readonly DOC_FORBIDDEN: 403;
 };
 /**
  * Error thrown when the JSON-RPC client receives a message that cannot be parsed as JSON.

package/dist/net/error.js

@@ -11,15 +11,10 @@ const ErrorCodes = {
   DOC_DELETED: 410,
   /** Document not found (never existed). */
   DOC_NOT_FOUND: 404,
-  /**
-   * Caller is no longer authorized to read/write the document.
-   * Distinct from DOC_DELETED — the doc still exists, the caller just lost
-   * membership (revoked, or removed from a shared collection). The sync
-   * loop treats it like a soft delete: untrack, drop local cache, emit
-   * `onRemoteDocAccessRevoked` so the application can remove the doc from
-   * its own workspace state.
-   */
-  ACCESS_REVOKED: 403
+  /** Caller is not authenticated (no/invalid credentials). */
+  DOC_UNAUTHORIZED: 401,
+  /** Caller is authenticated but not authorized for this doc. */
+  DOC_FORBIDDEN: 403
 };
 class JSONRPCParseError extends Error {
   rawMessage;

package/dist/net/index.d.ts

@@ -1,20 +1,21 @@
-export { Invite, InviteProjectBookMeta, InviteProjectMetaSnapshot, InviteRole, InviteTo } from './invite.js';
 export { FetchTransport } from './http/FetchTransport.js';
 export { PatchesClient } from './PatchesClient.js';
 export { PatchesConnection } from './PatchesConnection.js';
 export { PatchesSync, PatchesSyncOptions, PatchesSyncState } from './PatchesSync.js';
 export { PatchesREST, PatchesRESTOptions } from './rest/PatchesREST.js';
+export { PatchesRESTSignalingTransport } from './rest/PatchesRESTSignalingTransport.js';
 export { BufferedEvent, SSEServer, SSEServerOptions } from './rest/SSEServer.js';
+export { SSESignalingService } from './rest/SSESignalingService.js';
 export { normalizeIds } from './rest/utils.js';
 export { JSONRPCClient } from './protocol/JSONRPCClient.js';
 export { ApiDefinition, ConnectionSignalSubscriber, JSONRPCServer, JSONRPCServerOptions, MessageHandler } from './protocol/JSONRPCServer.js';
 export { getAuthContext, getClientId } from './serverContext.js';
-export { AwarenessUpdateNotificationParams, BranchAPI, ClientTransport, ConnectionState, JsonRpcNotification, JsonRpcRequest, JsonRpcResponse, Message, PatchesAPI, PatchesNotificationParams, ServerTransport, SignalNotificationParams } from './protocol/types.js';
+export { AwarenessUpdateNotificationParams, BranchAPI, ClientTransport, ConnectionState, JsonRpcNotification, JsonRpcRequest, JsonRpcResponse, Message, PatchesAPI, PatchesNotificationParams, ServerTransport, SignalNotificationParams, SignalingTransport } from './protocol/types.js';
 export { rpcError, rpcNotification, rpcResponse } from './protocol/utils.js';
 export { Access, AuthContext, AuthorizationProvider, allowAll, assertNotDeleted, denyAll } from './websocket/AuthorizationProvider.js';
 export { onlineState } from './websocket/onlineState.js';
 export { PatchesWebSocket } from './websocket/PatchesWebSocket.js';
-export { JsonRpcMessage, SignalingService } from './websocket/SignalingService.js';
+export { JsonRpcMessage, SignalingService } from './signaling/SignalingService.js';
 export { WebSocketServer, WebSocketServerOptions } from './websocket/WebSocketServer.js';
 export { WebSocketOptions, WebSocketTransport } from './websocket/WebSocketTransport.js';
 export { CommitChangesOptions } from '../types.js';

package/dist/net/index.js

@@ -1,5 +1,4 @@
 import "../chunk-IZ2YBCUP.js";
-export * from "./invite.js";
 export * from "./http/FetchTransport.js";
 export * from "./PatchesClient.js";
 export * from "./PatchesConnection.js";
@@ -12,7 +11,7 @@ export * from "./protocol/utils.js";
 export * from "./websocket/AuthorizationProvider.js";
 export * from "./websocket/onlineState.js";
 export * from "./websocket/PatchesWebSocket.js";
-export * from "./websocket/SignalingService.js";
+export * from "./signaling/SignalingService.js";
 export * from "./websocket/WebSocketServer.js";
 export * from "./websocket/WebSocketTransport.js";
 export {

package/dist/net/protocol/JSONRPCServer.js

@@ -162,7 +162,7 @@ class JSONRPCServer {
     }
     const ok = await this.auth.canAccess(ctx, docId, access, method);
     if (!ok) {
-      throw new StatusError(401, `${access.toUpperCase()}_FORBIDDEN:${docId}`);
+      throw new StatusError(403, `${access.toUpperCase()}_FORBIDDEN:${docId}`);
     }
   }
   /**

package/dist/net/protocol/types.d.ts

@@ -1,4 +1,4 @@
-import { Unsubscriber } from 'easy-signal';
+import { Unsubscriber, Signal } from 'easy-signal';
 import { ListBranchesOptions, Branch, CreateBranchMetadata, EditableBranchMetadata, PatchesState, Change, ChangeInput, CommitChangesOptions, EditableVersionMetadata, ListVersionsOptions, VersionMetadata } from '../../types.js';
 import '../../json-patch/JSONPatch.js';
 import '@dabble/delta';
@@ -31,6 +31,20 @@ interface ClientTransport {
      */
     onMessage(cb: (raw: string) => void): Unsubscriber;
 }
+/**
+ * Lifecycle-aware transport that {@link WebRTCTransport} can ride on top of as a
+ * signaling channel. Anything implementing {@link ClientTransport} plus a
+ * `connect()` / `state` / `onStateChange` triplet qualifies — including
+ * `WebSocketTransport` and `PatchesRESTSignalingTransport`.
+ */
+interface SignalingTransport extends ClientTransport {
+    /** Open the underlying channel. May be a no-op if the channel is already open. */
+    connect(): Promise<void> | void;
+    /** Current connection state. */
+    readonly state: ConnectionState;
+    /** Emits whenever {@link state} changes. */
+    readonly onStateChange: Signal<(state: ConnectionState) => void>;
+}
 /**
  * Minimal contract for server-side transports that can have **multiple** logical peers.
  * Each message must indicate the **from / to** connection. Any additional lifecycle
@@ -155,4 +169,4 @@ interface SignalNotificationParams {
     data: any;
 }
 
-export { type AwarenessUpdateNotificationParams, type BranchAPI, type ClientTransport, CommitChangesOptions, type ConnectionState, type JsonRpcNotification, type JsonRpcRequest, type JsonRpcResponse, type Message, type PatchesAPI, type PatchesNotificationParams, type ServerTransport, type SignalNotificationParams };
+export { type AwarenessUpdateNotificationParams, type BranchAPI, type ClientTransport, CommitChangesOptions, type ConnectionState, type JsonRpcNotification, type JsonRpcRequest, type JsonRpcResponse, type Message, type PatchesAPI, type PatchesNotificationParams, type ServerTransport, type SignalNotificationParams, type SignalingTransport };

package/dist/net/rest/PatchesREST.d.ts

@@ -2,7 +2,6 @@ import * as easy_signal from 'easy-signal';
 import { Change, CommitChangesOptions, PatchesState, ChangeInput, DeleteDocOptions, EditableVersionMetadata, ListVersionsOptions, VersionMetadata, PatchesSnapshot, Branch, CreateBranchMetadata, EditableBranchMetadata } from '../../types.js';
 import { PatchesConnection } from '../PatchesConnection.js';
 import { ConnectionState } from '../protocol/types.js';
-import { Invite } from '../invite.js';
 import '../../json-patch/JSONPatch.js';
 import '@dabble/delta';
 import '../../json-patch/types.js';
@@ -37,6 +36,11 @@ declare class PatchesREST implements PatchesConnection {
     readonly onStateChange: easy_signal.Signal<(state: ConnectionState) => void>;
     readonly onChangesCommitted: easy_signal.Signal<(docId: string, changes: Change[], options?: CommitChangesOptions) => void>;
     readonly onDocDeleted: easy_signal.Signal<(docId: string) => void>;
+    /**
+     * Emits raw JSON-RPC strings received over the multiplexed `signal` SSE channel.
+     * Used by `PatchesRESTSignalingTransport` to drive `WebRTCTransport`'s signaling.
+     */
+    readonly onSignal: easy_signal.Signal<(raw: string) => void>;
     private _url;
     private _state;
     private eventSource;
@@ -46,6 +50,8 @@ declare class PatchesREST implements PatchesConnection {
     constructor(url: string, options?: PatchesRESTOptions);
     get url(): string;
     set url(url: string);
+    /** Current connection state of the underlying SSE stream. */
+    get state(): ConnectionState;
     connect(): Promise<void>;
     disconnect(): void;
     subscribe(ids: string | string[]): Promise<string[]>;
@@ -70,27 +76,21 @@ declare class PatchesREST implements PatchesConnection {
     deleteBranch(docId: string, branchId: string): Promise<void>;
     mergeBranch(docId: string, branchId: string): Promise<void>;
     /**
-     * Fetch a single invite addressed to the authenticated user.
-     * `GET /docs/:docId/_invites/:inviteId`
-     */
-    getInvite(docId: string, inviteId: string): Promise<Invite>;
-    /**
-     * Accept or decline an invite. Returns whether the server applied a role
-     * change (`ok` from `{ ok: boolean }`).
-     * `POST /docs/:docId/_invites/:inviteId` body `{ accept: boolean }`
-     */
-    acceptInvite(docId: string, inviteId: string, accept: boolean): Promise<boolean>;
-    /**
-     * Remove the authenticated user from `roles.users` (non-owners only).
-     * `POST /docs/:docId/_self/leave`
-     */
-    leaveProject(docId: string): Promise<boolean>;
-    /**
-     * Owner/co-author revokes another member. `targetUid` is removed from
-     * `roles.users` and tombstoned under `roles.formerUsers.revokedAt`.
-     * `POST /docs/:docId/_members/:uid/revoke`
+     * POSTs a raw JSON-RPC string to `/signal/:clientId`. Used as the upstream
+     * half of the multiplexed signaling channel: receive happens via the `signal`
+     * SSE event (see {@link onSignal}).
+     *
+     * The body is sent verbatim — callers pass an already-stringified JSON-RPC
+     * message. The endpoint forwards it to {@link SignalingService.handleClientMessage}.
+     *
+     * Silently no-ops when the SSE stream is not connected. Signaling is
+     * inherently best-effort and the server has no live `signal` channel back
+     * to this client until the stream is up, so a frame sent before connect
+     * resolves can't be relayed anyway. Throwing here would surface as an
+     * unhandled rejection through `JSONRPCClient.call`, which doesn't await
+     * `transport.send`.
      */
-    revokeMember(docId: string, targetUid: string): Promise<boolean>;
+    sendSignal(raw: string): Promise<void>;
     private _setState;
     private _getHeaders;
     private _fetch;

package/dist/net/rest/PatchesREST.js

@@ -13,6 +13,11 @@ class PatchesREST {
   onStateChange = signal();
   onChangesCommitted = signal();
   onDocDeleted = signal();
+  /**
+   * Emits raw JSON-RPC strings received over the multiplexed `signal` SSE channel.
+   * Used by `PatchesRESTSignalingTransport` to drive `WebRTCTransport`'s signaling.
+   */
+  onSignal = signal();
   _url;
   _state = "disconnected";
   eventSource = null;
@@ -36,6 +41,11 @@ class PatchesREST {
   set url(url) {
     this._url = url.replace(/\/$/, "");
   }
+  // --- Connection State ---
+  /** Current connection state of the underlying SSE stream. */
+  get state() {
+    return this._state;
+  }
   // --- Connection Lifecycle ---
   connect() {
     this.shouldBeConnected = true;
@@ -94,6 +104,9 @@ class PatchesREST {
         } catch {
         }
       });
+      es.addEventListener("signal", (e) => {
+        this.onSignal.emit(e.data);
+      });
       es.addEventListener("resync", () => {
         if (!this.shouldBeConnected) return;
         this._setState("disconnected");
@@ -189,51 +202,38 @@ class PatchesREST {
   async mergeBranch(docId, branchId) {
     await this._fetch(`/docs/${docId}/_branches/${encodeURIComponent(branchId)}/_merge`, { method: "POST" });
   }
-  // --- Invites & membership (pup REST) ---
-  /**
-   * Fetch a single invite addressed to the authenticated user.
-   * `GET /docs/:docId/_invites/:inviteId`
-   */
-  async getInvite(docId, inviteId) {
-    return this._fetch(`/docs/${docId}/_invites/${encodeURIComponent(inviteId)}`);
-  }
-  /**
-   * Accept or decline an invite. Returns whether the server applied a role
-   * change (`ok` from `{ ok: boolean }`).
-   * `POST /docs/:docId/_invites/:inviteId` body `{ accept: boolean }`
-   */
-  async acceptInvite(docId, inviteId, accept) {
-    const result = await this._fetch(`/docs/${docId}/_invites/${encodeURIComponent(inviteId)}`, {
-      method: "POST",
-      body: { accept }
-    });
-    return Boolean(result?.ok);
-  }
+  // --- WebRTC Signaling ---
   /**
-   * Remove the authenticated user from `roles.users` (non-owners only).
-   * `POST /docs/:docId/_self/leave`
+   * POSTs a raw JSON-RPC string to `/signal/:clientId`. Used as the upstream
+   * half of the multiplexed signaling channel: receive happens via the `signal`
+   * SSE event (see {@link onSignal}).
+   *
+   * The body is sent verbatim — callers pass an already-stringified JSON-RPC
+   * message. The endpoint forwards it to {@link SignalingService.handleClientMessage}.
+   *
+   * Silently no-ops when the SSE stream is not connected. Signaling is
+   * inherently best-effort and the server has no live `signal` channel back
+   * to this client until the stream is up, so a frame sent before connect
+   * resolves can't be relayed anyway. Throwing here would surface as an
+   * unhandled rejection through `JSONRPCClient.call`, which doesn't await
+   * `transport.send`.
    */
-  async leaveProject(docId) {
-    const result = await this._fetch(`/docs/${docId}/_self/leave`, {
+  async sendSignal(raw) {
+    if (this._state !== "connected") return;
+    const headers = await this._getHeaders();
+    const response = await globalThis.fetch(`${this._url}/signal/${this.clientId}`, {
       method: "POST",
-      body: {}
+      credentials: "include",
+      headers: {
+        "Content-Type": "application/json",
+        ...headers
+      },
+      body: raw,
+      signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS)
     });
-    return Boolean(result?.ok);
-  }
-  /**
-   * Owner/co-author revokes another member. `targetUid` is removed from
-   * `roles.users` and tombstoned under `roles.formerUsers.revokedAt`.
-   * `POST /docs/:docId/_members/:uid/revoke`
-   */
-  async revokeMember(docId, targetUid) {
-    const result = await this._fetch(
-      `/docs/${docId}/_members/${encodeURIComponent(targetUid)}/revoke`,
-      {
-        method: "POST",
-        body: {}
-      }
-    );
-    return Boolean(result?.ok);
+    if (!response.ok) {
+      throw new StatusError(response.status, response.statusText);
+    }
   }
   // --- Private Helpers ---
   _setState(state) {

package/dist/net/rest/PatchesRESTSignalingTransport.d.ts

@@ -0,0 +1,41 @@
+import * as easy_signal from 'easy-signal';
+import { Unsubscriber } from 'easy-signal';
+import { SignalingTransport, ConnectionState } from '../protocol/types.js';
+import { PatchesREST } from './PatchesREST.js';
+import '../../types.js';
+import '../../json-patch/JSONPatch.js';
+import '@dabble/delta';
+import '../../json-patch/types.js';
+import '../PatchesConnection.js';
+
+/**
+ * Adapter that exposes a {@link PatchesREST} connection as a {@link SignalingTransport}
+ * for `WebRTCTransport`. Multiplexes signaling over the existing SSE stream:
+ *
+ * - **send** → `PatchesREST.sendSignal()` → `POST /signal/:clientId`.
+ * - **receive** → subscribes to `PatchesREST.onSignal` (the `signal` SSE event).
+ *
+ * Does not own the connection. The application calls `patches.connect()`
+ * directly; `connect()` here just delegates so callers can still `await` it.
+ */
+declare class PatchesRESTSignalingTransport implements SignalingTransport {
+    private patches;
+    /**
+     * @param patches - The shared `PatchesREST` instance handling document sync.
+     *   The same `clientId` is used for both, so signaling addressing matches.
+     */
+    constructor(patches: PatchesREST);
+    get state(): ConnectionState;
+    get onStateChange(): easy_signal.Signal<(state: ConnectionState) => void>;
+    /**
+     * Delegates to {@link PatchesREST.connect}. Safe to call multiple times — if
+     * the SSE stream is already open, the underlying call is a no-op.
+     */
+    connect(): Promise<void>;
+    /** Sends a raw JSON-RPC frame upstream over the signaling REST endpoint. */
+    send(raw: string): Promise<void>;
+    /** Subscribes to inbound JSON-RPC frames received via the `signal` SSE event. */
+    onMessage(cb: (raw: string) => void): Unsubscriber;
+}
+
+export { PatchesRESTSignalingTransport };

package/dist/net/rest/PatchesRESTSignalingTransport.js

@@ -0,0 +1,34 @@
+import "../../chunk-IZ2YBCUP.js";
+class PatchesRESTSignalingTransport {
+  /**
+   * @param patches - The shared `PatchesREST` instance handling document sync.
+   *   The same `clientId` is used for both, so signaling addressing matches.
+   */
+  constructor(patches) {
+    this.patches = patches;
+  }
+  get state() {
+    return this.patches.state;
+  }
+  get onStateChange() {
+    return this.patches.onStateChange;
+  }
+  /**
+   * Delegates to {@link PatchesREST.connect}. Safe to call multiple times — if
+   * the SSE stream is already open, the underlying call is a no-op.
+   */
+  async connect() {
+    await this.patches.connect();
+  }
+  /** Sends a raw JSON-RPC frame upstream over the signaling REST endpoint. */
+  send(raw) {
+    return this.patches.sendSignal(raw);
+  }
+  /** Subscribes to inbound JSON-RPC frames received via the `signal` SSE event. */
+  onMessage(cb) {
+    return this.patches.onSignal(cb);
+  }
+}
+export {
+  PatchesRESTSignalingTransport
+};

package/dist/net/rest/SSEServer.d.ts

@@ -127,6 +127,21 @@ declare class SSEServer {
      * @param exceptClientId - Client ID to exclude (typically the one who made the change).
      */
     notify(docId: string, event: string, params: Record<string, any>, exceptClientId?: string): void;
+    /**
+     * Send an event directly to a single connected client, bypassing subscription
+     * routing. Used for client-targeted traffic like WebRTC signaling.
+     *
+     * Unlike {@link notify}, this does NOT buffer through expiry: if the client
+     * is currently disconnected, the call returns false and the event is dropped.
+     * Stale signaling replayed after a buffer expiry is harmful (peers gone, ICE
+     * candidates moot), so we deliberately do not preserve it.
+     *
+     * @param clientId - Target client.
+     * @param event - SSE event type (e.g. `'signal'`).
+     * @param data - Pre-serialised event payload.
+     * @returns true if the client was connected and the event was written.
+     */
+    sendToClient(clientId: string, event: string, data: string): boolean;
     /**
      * List all client IDs subscribed to a document.
      */

package/dist/net/rest/SSEServer.js

@@ -157,6 +157,31 @@ class SSEServer {
       }
     }
   }
+  /**
+   * Send an event directly to a single connected client, bypassing subscription
+   * routing. Used for client-targeted traffic like WebRTC signaling.
+   *
+   * Unlike {@link notify}, this does NOT buffer through expiry: if the client
+   * is currently disconnected, the call returns false and the event is dropped.
+   * Stale signaling replayed after a buffer expiry is harmful (peers gone, ICE
+   * candidates moot), so we deliberately do not preserve it.
+   *
+   * @param clientId - Target client.
+   * @param event - SSE event type (e.g. `'signal'`).
+   * @param data - Pre-serialised event payload.
+   * @returns true if the client was connected and the event was written.
+   */
+  sendToClient(clientId, event, data) {
+    const client = this.clients.get(clientId);
+    if (!client || !client.writer) return false;
+    this._writeEvent(client, {
+      id: client.nextEventId++,
+      event,
+      data,
+      timestamp: Date.now()
+    });
+    return true;
+  }
   /**
    * List all client IDs subscribed to a document.
    */