@liveblocks/server 1.0.4 → 1.0.6

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-import { DistributiveOmit, SetParentKeyOp, DeleteCrdtOp, ClientMsg as ClientMsg$1, JsonObject, Json, Brand, asPos, SerializedRootObject, SerializedChild, StorageNode, SerializedCrdt, Awaitable, PlainLsonObject, NodeMap, NodeStream, ClientWireOp, IgnoredOp, IUserInfo, ServerMsg as ServerMsg$1, BaseUserMeta } from '@liveblocks/core';
+import { DistributiveOmit, SetParentKeyOp, DeleteCrdtOp, ClientMsg as ClientMsg$1, JsonObject, Json, Brand, asPos, SerializedCrdt, IUserInfo, SerializedRootObject, SerializedChild, StorageNode, Awaitable, PlainLsonObject, NodeMap as NodeMap$1, NodeStream as NodeStream$1, ClientWireOp, IgnoredOp, ServerMsg as ServerMsg$1, BaseUserMeta } from '@liveblocks/core';
 export { BroadcastEventClientMsg, ClientMsg, ClientWireOp, CreateListOp, CreateMapOp, CreateObjectOp, CreateOp, CreateRegisterOp, DeleteCrdtOp, DeleteObjectKeyOp, FetchStorageClientMsg, FetchYDocClientMsg, HasOpId, IgnoredOp, Op, RoomStateServerMsg, ServerMsg, ServerWireOp, SetParentKeyOp, UpdateObjectOp, UpdatePresenceClientMsg, UpdateStorageClientMsg, UpdateYDocClientMsg } from '@liveblocks/core';
 import * as decoders from 'decoders';
 import { Decoder } from 'decoders';
@@ -313,6 +313,32 @@ declare class Logger {
  */
 
 type Pos = ReturnType<typeof asPos>;
+type NodeTuple<T extends SerializedCrdt = SerializedCrdt> = [
+    id: string,
+    value: T
+];
+type NodeMap = {
+    size: number;
+    [Symbol.iterator]: () => IterableIterator<[id: string, node: SerializedCrdt]>;
+    clear: () => void;
+    delete: (key: string) => boolean;
+    get: (key: string) => SerializedCrdt | undefined;
+    has: (key: string) => boolean;
+    keys: () => Iterable<string>;
+    set(key: string, value: SerializedCrdt): void;
+};
+type NodeStream = Iterable<NodeTuple>;
+/**
+ * Leased session data structure for server-side sessions with temporarily persisted presence.
+ */
+type LeasedSession = {
+    sessionId: string;
+    presence: Json;
+    updatedAt: number;
+    info: IUserInfo;
+    ttl: number;
+    actorId: number;
+};
 
 /**
  * Copyright (c) Liveblocks Inc.
@@ -514,6 +540,28 @@ interface IStorageDriver {
      * @private Test-only: never use in production.
      */
     DANGEROUSLY_wipe_all_y_updates(): Awaitable<void>;
+    /**
+     * List all leased sessions.
+     * Note: Does NOT filter by expiration - returns all stored sessions.
+     * Expiration logic is handled at the Room.ts level.
+     */
+    list_leased_sessions(): Awaitable<Iterable<[sessionId: string, session: LeasedSession]>>;
+    /**
+     * Get a specific leased session by session ID.
+     * Note: Does NOT check expiration - returns the stored session if it exists.
+     * Expiration logic is handled at the Room.ts level.
+     */
+    get_leased_session(sessionId: string): Awaitable<LeasedSession | undefined>;
+    /**
+     * Create or update a leased session.
+     * Note: This is a full replace operation - the caller is responsible for
+     * merging/patching presence if needed.
+     */
+    put_leased_session(session: LeasedSession): Awaitable<void>;
+    /**
+     * Delete a leased session by session ID.
+     */
+    delete_leased_session(sessionId: string): Awaitable<void>;
 }
 
 /**
@@ -639,7 +687,7 @@ declare function snapshotToPlainLson_lazy(snapshot: IReadableSnapshot): StringGe
  * Takes a copy of the provided nodes, so the snapshot is isolated from
  * subsequent mutations to the source.
  */
-declare function makeInMemorySnapshot(values: NodeMap | NodeStream): IReadableSnapshot;
+declare function makeInMemorySnapshot(values: NodeMap$1 | NodeStream$1): IReadableSnapshot;
 
 /**
  * Copyright (c) Liveblocks Inc.
@@ -1055,6 +1103,7 @@ declare class Room<RM, SM, CM extends JsonObject, C = undefined> {
         socket: IServerWebSocket;
         lastActivity: Date;
     }[]): void;
+    private sendSessionStartMessages;
     /**
      * Registers a new BrowserSession into the Room server's session list, along with
      * the socket connection to use for that BrowserSession, now that it is known.
@@ -1063,7 +1112,7 @@ declare class Room<RM, SM, CM extends JsonObject, C = undefined> {
      * - Sends a ROOM_STATE message to the socket.
      * - Broadcasts a USER_JOINED message to all other sessions in the room.
      */
-    startBrowserSession(ticket: Ticket<SM, CM>, socket: IServerWebSocket, ctx?: C, defer?: (promise: Promise<void>) => void): void;
+    startBrowserSession(ticket: Ticket<SM, CM>, socket: IServerWebSocket, ctx?: C, defer?: (promise: Promise<void>) => void): Promise<void>;
     /**
      * Unregisters the BrowserSession for the given actor. Call this when the socket has
      * been closed from the client's end.
@@ -1116,7 +1165,24 @@ declare class Room<RM, SM, CM extends JsonObject, C = undefined> {
     getSession(sessionKey: SessionKey): BrowserSession<SM, CM> | undefined;
     listSessions(): BrowserSession<SM, CM>[];
     /**
-     * Will send the given ServerMsg to all Sessions, except the Session
+     * Upsert a leased session. Creates a new session if it doesn't exist (or is expired),
+     * or updates an existing session with merged presence.
+     */
+    upsertLeasedSession(sessionId: string, presence: JsonObject, ttl: number, info: IUserInfo, ctx?: C, defer?: (promise: Promise<void>) => void): Promise<void>;
+    /**
+     * List all server sessions. As a side effect, it will delete expired sessions.
+     */
+    listLeasedSessions(ctx?: C, defer?: (promise: Promise<void>) => void): Promise<LeasedSession[]>;
+    /**
+     * Delete a server session and broadcast USER_LEFT to all sessions.
+     */
+    deleteLeasedSession(session: LeasedSession, ctx?: C, defer?: (promise: Promise<void>) => void): Promise<void>;
+    /**
+     * Delete all server sessions and broadcast USER_LEFT to all sessions.
+     */
+    deleteAllLeasedSessions(ctx?: C, defer?: (promise: Promise<void>) => void): Promise<void>;
+    /**
+     * Will send the given ServerMsg through all Session, except the Session
      * where the message originates from.
      */
     sendToOthers(sender: SessionKey, serverMsg: ServerMsg | readonly ServerMsg[], ctx?: C, defer?: (promise: Promise<void>) => void): void;
@@ -1165,6 +1231,11 @@ declare class Room<RM, SM, CM extends JsonObject, C = undefined> {
  * Concatenates multiple Uint8Arrays into a single Uint8Array.
  */
 declare function concatUint8Arrays(arrays: Uint8Array[]): Uint8Array;
+/**
+ * Check if a leased session is expired.
+ * Returns true if the current time is greater than or equal to updatedAt + ttl.
+ */
+declare function isLeasedSessionExpired(leasedSession: LeasedSession): boolean;
 
 /**
  * Copyright (c) Liveblocks Inc.
@@ -1392,6 +1463,7 @@ declare class InMemoryDriver implements IStorageDriver {
     private _nodes;
     private _metadb;
     private _ydb;
+    private _leasedSessions;
     constructor(options?: {
         initialActor?: number;
         initialNodes?: Iterable<[string, SerializedCrdt]>;
@@ -1402,6 +1474,10 @@ declare class InMemoryDriver implements IStorageDriver {
     get_meta(key: string): Promise<Json | undefined>;
     put_meta(key: string, value: Json): Promise<void>;
     delete_meta(key: string): Promise<void>;
+    list_leased_sessions(): Promise<IterableIterator<[string, LeasedSession]>>;
+    get_leased_session(sessionId: string): Promise<LeasedSession | undefined>;
+    put_leased_session(session: LeasedSession): Promise<void>;
+    delete_leased_session(sessionId: string): Promise<void>;
     next_actor(): number;
     iter_y_updates(docId: YDocId): Promise<IterableIterator<[string, Uint8Array]>>;
     write_y_updates(docId: YDocId, key: string, data: Uint8Array): Promise<void>;
@@ -1411,4 +1487,4 @@ declare class InMemoryDriver implements IStorageDriver {
     load_nodes_api(): IStorageDriverNodeAPI;
 }
 
-export { type ActorID, BackendSession, BrowserSession, ConsoleTarget, type CreateTicketOptions, DefaultMap, type FixOp, type Guid, type IReadableSnapshot, type IServerWebSocket, type IStorageDriver, type IStorageDriverNodeAPI, type IUserData, InMemoryDriver, type LoadingState, LogLevel, LogTarget, Logger, type MetadataDB, NestedMap, type Pos, type PreSerializedServerMsg, ProtocolVersion, ROOT_YDOC_ID, Room, type SessionKey, type Ticket, UniqueMap, type YDocId, type YUpdate, type YVector, ackIgnoredOp, clientMsgDecoder, concatUint8Arrays, guidDecoder, jsonObjectYolo, jsonYolo, makeInMemorySnapshot, makeMetadataDB, plainLsonToNodeStream, protocolVersionDecoder, quote, serialize as serializeServerMsg, snapshotToLossyJson_eager, snapshotToLossyJson_lazy, snapshotToNodeStream, snapshotToPlainLson_eager, snapshotToPlainLson_lazy, Storage as test_only__Storage, YjsStorage as test_only__YjsStorage, transientClientMsgDecoder, tryCatch };
+export { type ActorID, BackendSession, BrowserSession, ConsoleTarget, type CreateTicketOptions, DefaultMap, type FixOp, type Guid, type IReadableSnapshot, type IServerWebSocket, type IStorageDriver, type IStorageDriverNodeAPI, type IUserData, InMemoryDriver, type LeasedSession, type LoadingState, LogLevel, LogTarget, Logger, type MetadataDB, NestedMap, type NodeMap, type NodeStream, type NodeTuple, type Pos, type PreSerializedServerMsg, ProtocolVersion, ROOT_YDOC_ID, Room, type SessionKey, type Ticket, UniqueMap, type YDocId, type YUpdate, type YVector, ackIgnoredOp, clientMsgDecoder, concatUint8Arrays, guidDecoder, isLeasedSessionExpired, jsonObjectYolo, jsonYolo, makeInMemorySnapshot, makeMetadataDB, plainLsonToNodeStream, protocolVersionDecoder, quote, serialize as serializeServerMsg, snapshotToLossyJson_eager, snapshotToLossyJson_lazy, snapshotToNodeStream, snapshotToPlainLson_eager, snapshotToPlainLson_lazy, Storage as test_only__Storage, YjsStorage as test_only__YjsStorage, transientClientMsgDecoder, tryCatch };

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { DistributiveOmit, SetParentKeyOp, DeleteCrdtOp, ClientMsg as ClientMsg$1, JsonObject, Json, Brand, asPos, SerializedRootObject, SerializedChild, StorageNode, SerializedCrdt, Awaitable, PlainLsonObject, NodeMap, NodeStream, ClientWireOp, IgnoredOp, IUserInfo, ServerMsg as ServerMsg$1, BaseUserMeta } from '@liveblocks/core';
+import { DistributiveOmit, SetParentKeyOp, DeleteCrdtOp, ClientMsg as ClientMsg$1, JsonObject, Json, Brand, asPos, SerializedCrdt, IUserInfo, SerializedRootObject, SerializedChild, StorageNode, Awaitable, PlainLsonObject, NodeMap as NodeMap$1, NodeStream as NodeStream$1, ClientWireOp, IgnoredOp, ServerMsg as ServerMsg$1, BaseUserMeta } from '@liveblocks/core';
 export { BroadcastEventClientMsg, ClientMsg, ClientWireOp, CreateListOp, CreateMapOp, CreateObjectOp, CreateOp, CreateRegisterOp, DeleteCrdtOp, DeleteObjectKeyOp, FetchStorageClientMsg, FetchYDocClientMsg, HasOpId, IgnoredOp, Op, RoomStateServerMsg, ServerMsg, ServerWireOp, SetParentKeyOp, UpdateObjectOp, UpdatePresenceClientMsg, UpdateStorageClientMsg, UpdateYDocClientMsg } from '@liveblocks/core';
 import * as decoders from 'decoders';
 import { Decoder } from 'decoders';
@@ -313,6 +313,32 @@ declare class Logger {
  */
 
 type Pos = ReturnType<typeof asPos>;
+type NodeTuple<T extends SerializedCrdt = SerializedCrdt> = [
+    id: string,
+    value: T
+];
+type NodeMap = {
+    size: number;
+    [Symbol.iterator]: () => IterableIterator<[id: string, node: SerializedCrdt]>;
+    clear: () => void;
+    delete: (key: string) => boolean;
+    get: (key: string) => SerializedCrdt | undefined;
+    has: (key: string) => boolean;
+    keys: () => Iterable<string>;
+    set(key: string, value: SerializedCrdt): void;
+};
+type NodeStream = Iterable<NodeTuple>;
+/**
+ * Leased session data structure for server-side sessions with temporarily persisted presence.
+ */
+type LeasedSession = {
+    sessionId: string;
+    presence: Json;
+    updatedAt: number;
+    info: IUserInfo;
+    ttl: number;
+    actorId: number;
+};
 
 /**
  * Copyright (c) Liveblocks Inc.
@@ -514,6 +540,28 @@ interface IStorageDriver {
      * @private Test-only: never use in production.
      */
     DANGEROUSLY_wipe_all_y_updates(): Awaitable<void>;
+    /**
+     * List all leased sessions.
+     * Note: Does NOT filter by expiration - returns all stored sessions.
+     * Expiration logic is handled at the Room.ts level.
+     */
+    list_leased_sessions(): Awaitable<Iterable<[sessionId: string, session: LeasedSession]>>;
+    /**
+     * Get a specific leased session by session ID.
+     * Note: Does NOT check expiration - returns the stored session if it exists.
+     * Expiration logic is handled at the Room.ts level.
+     */
+    get_leased_session(sessionId: string): Awaitable<LeasedSession | undefined>;
+    /**
+     * Create or update a leased session.
+     * Note: This is a full replace operation - the caller is responsible for
+     * merging/patching presence if needed.
+     */
+    put_leased_session(session: LeasedSession): Awaitable<void>;
+    /**
+     * Delete a leased session by session ID.
+     */
+    delete_leased_session(sessionId: string): Awaitable<void>;
 }
 
 /**
@@ -639,7 +687,7 @@ declare function snapshotToPlainLson_lazy(snapshot: IReadableSnapshot): StringGe
  * Takes a copy of the provided nodes, so the snapshot is isolated from
  * subsequent mutations to the source.
  */
-declare function makeInMemorySnapshot(values: NodeMap | NodeStream): IReadableSnapshot;
+declare function makeInMemorySnapshot(values: NodeMap$1 | NodeStream$1): IReadableSnapshot;
 
 /**
  * Copyright (c) Liveblocks Inc.
@@ -1055,6 +1103,7 @@ declare class Room<RM, SM, CM extends JsonObject, C = undefined> {
         socket: IServerWebSocket;
         lastActivity: Date;
     }[]): void;
+    private sendSessionStartMessages;
     /**
      * Registers a new BrowserSession into the Room server's session list, along with
      * the socket connection to use for that BrowserSession, now that it is known.
@@ -1063,7 +1112,7 @@ declare class Room<RM, SM, CM extends JsonObject, C = undefined> {
      * - Sends a ROOM_STATE message to the socket.
      * - Broadcasts a USER_JOINED message to all other sessions in the room.
      */
-    startBrowserSession(ticket: Ticket<SM, CM>, socket: IServerWebSocket, ctx?: C, defer?: (promise: Promise<void>) => void): void;
+    startBrowserSession(ticket: Ticket<SM, CM>, socket: IServerWebSocket, ctx?: C, defer?: (promise: Promise<void>) => void): Promise<void>;
     /**
      * Unregisters the BrowserSession for the given actor. Call this when the socket has
      * been closed from the client's end.
@@ -1116,7 +1165,24 @@ declare class Room<RM, SM, CM extends JsonObject, C = undefined> {
     getSession(sessionKey: SessionKey): BrowserSession<SM, CM> | undefined;
     listSessions(): BrowserSession<SM, CM>[];
     /**
-     * Will send the given ServerMsg to all Sessions, except the Session
+     * Upsert a leased session. Creates a new session if it doesn't exist (or is expired),
+     * or updates an existing session with merged presence.
+     */
+    upsertLeasedSession(sessionId: string, presence: JsonObject, ttl: number, info: IUserInfo, ctx?: C, defer?: (promise: Promise<void>) => void): Promise<void>;
+    /**
+     * List all server sessions. As a side effect, it will delete expired sessions.
+     */
+    listLeasedSessions(ctx?: C, defer?: (promise: Promise<void>) => void): Promise<LeasedSession[]>;
+    /**
+     * Delete a server session and broadcast USER_LEFT to all sessions.
+     */
+    deleteLeasedSession(session: LeasedSession, ctx?: C, defer?: (promise: Promise<void>) => void): Promise<void>;
+    /**
+     * Delete all server sessions and broadcast USER_LEFT to all sessions.
+     */
+    deleteAllLeasedSessions(ctx?: C, defer?: (promise: Promise<void>) => void): Promise<void>;
+    /**
+     * Will send the given ServerMsg through all Session, except the Session
      * where the message originates from.
      */
     sendToOthers(sender: SessionKey, serverMsg: ServerMsg | readonly ServerMsg[], ctx?: C, defer?: (promise: Promise<void>) => void): void;
@@ -1165,6 +1231,11 @@ declare class Room<RM, SM, CM extends JsonObject, C = undefined> {
  * Concatenates multiple Uint8Arrays into a single Uint8Array.
  */
 declare function concatUint8Arrays(arrays: Uint8Array[]): Uint8Array;
+/**
+ * Check if a leased session is expired.
+ * Returns true if the current time is greater than or equal to updatedAt + ttl.
+ */
+declare function isLeasedSessionExpired(leasedSession: LeasedSession): boolean;
 
 /**
  * Copyright (c) Liveblocks Inc.
@@ -1392,6 +1463,7 @@ declare class InMemoryDriver implements IStorageDriver {
     private _nodes;
     private _metadb;
     private _ydb;
+    private _leasedSessions;
     constructor(options?: {
         initialActor?: number;
         initialNodes?: Iterable<[string, SerializedCrdt]>;
@@ -1402,6 +1474,10 @@ declare class InMemoryDriver implements IStorageDriver {
     get_meta(key: string): Promise<Json | undefined>;
     put_meta(key: string, value: Json): Promise<void>;
     delete_meta(key: string): Promise<void>;
+    list_leased_sessions(): Promise<IterableIterator<[string, LeasedSession]>>;
+    get_leased_session(sessionId: string): Promise<LeasedSession | undefined>;
+    put_leased_session(session: LeasedSession): Promise<void>;
+    delete_leased_session(sessionId: string): Promise<void>;
     next_actor(): number;
     iter_y_updates(docId: YDocId): Promise<IterableIterator<[string, Uint8Array]>>;
     write_y_updates(docId: YDocId, key: string, data: Uint8Array): Promise<void>;
@@ -1411,4 +1487,4 @@ declare class InMemoryDriver implements IStorageDriver {
     load_nodes_api(): IStorageDriverNodeAPI;
 }
 
-export { type ActorID, BackendSession, BrowserSession, ConsoleTarget, type CreateTicketOptions, DefaultMap, type FixOp, type Guid, type IReadableSnapshot, type IServerWebSocket, type IStorageDriver, type IStorageDriverNodeAPI, type IUserData, InMemoryDriver, type LoadingState, LogLevel, LogTarget, Logger, type MetadataDB, NestedMap, type Pos, type PreSerializedServerMsg, ProtocolVersion, ROOT_YDOC_ID, Room, type SessionKey, type Ticket, UniqueMap, type YDocId, type YUpdate, type YVector, ackIgnoredOp, clientMsgDecoder, concatUint8Arrays, guidDecoder, jsonObjectYolo, jsonYolo, makeInMemorySnapshot, makeMetadataDB, plainLsonToNodeStream, protocolVersionDecoder, quote, serialize as serializeServerMsg, snapshotToLossyJson_eager, snapshotToLossyJson_lazy, snapshotToNodeStream, snapshotToPlainLson_eager, snapshotToPlainLson_lazy, Storage as test_only__Storage, YjsStorage as test_only__YjsStorage, transientClientMsgDecoder, tryCatch };
+export { type ActorID, BackendSession, BrowserSession, ConsoleTarget, type CreateTicketOptions, DefaultMap, type FixOp, type Guid, type IReadableSnapshot, type IServerWebSocket, type IStorageDriver, type IStorageDriverNodeAPI, type IUserData, InMemoryDriver, type LeasedSession, type LoadingState, LogLevel, LogTarget, Logger, type MetadataDB, NestedMap, type NodeMap, type NodeStream, type NodeTuple, type Pos, type PreSerializedServerMsg, ProtocolVersion, ROOT_YDOC_ID, Room, type SessionKey, type Ticket, UniqueMap, type YDocId, type YUpdate, type YVector, ackIgnoredOp, clientMsgDecoder, concatUint8Arrays, guidDecoder, isLeasedSessionExpired, jsonObjectYolo, jsonYolo, makeInMemorySnapshot, makeMetadataDB, plainLsonToNodeStream, protocolVersionDecoder, quote, serialize as serializeServerMsg, snapshotToLossyJson_eager, snapshotToLossyJson_lazy, snapshotToNodeStream, snapshotToPlainLson_eager, snapshotToPlainLson_lazy, Storage as test_only__Storage, YjsStorage as test_only__YjsStorage, transientClientMsgDecoder, tryCatch };

package/dist/index.js

@@ -850,9 +850,11 @@ var InMemoryDriver = class {
     __publicField(this, "_nodes");
     __publicField(this, "_metadb");
     __publicField(this, "_ydb");
+    __publicField(this, "_leasedSessions");
     this._nodes = /* @__PURE__ */ new Map();
     this._metadb = /* @__PURE__ */ new Map();
     this._ydb = /* @__PURE__ */ new Map();
+    this._leasedSessions = /* @__PURE__ */ new Map();
     this._nextActor = options?.initialActor ?? -1;
     for (const [key, value] of options?.initialNodes ?? []) {
       this._nodes.set(key, value);
@@ -877,6 +879,18 @@ var InMemoryDriver = class {
   async delete_meta(key) {
     this._metadb.delete(key);
   }
+  async list_leased_sessions() {
+    return this._leasedSessions.entries();
+  }
+  async get_leased_session(sessionId) {
+    return this._leasedSessions.get(sessionId);
+  }
+  async put_leased_session(session) {
+    this._leasedSessions.set(session.sessionId, session);
+  }
+  async delete_leased_session(sessionId) {
+    this._leasedSessions.delete(sessionId);
+  }
   next_actor() {
     return ++this._nextActor;
   }
@@ -1681,6 +1695,10 @@ function makeRoomStateMsg(actor, nonce, scopes, users, publicMeta) {
     meta: publicMeta ?? {}
   };
 }
+function isLeasedSessionExpired(leasedSession) {
+  const now = Date.now();
+  return now >= leasedSession.updatedAt + leasedSession.ttl;
+}
 
 // src/Room.ts
 var messagesDecoder = array2(clientMsgDecoder);
@@ -1993,6 +2011,50 @@ var Room = class {
       newSession.markActive(lastActivity);
     }
   }
+  async sendSessionStartMessages(newSession, ticket, ctx, defer = () => {
+    throw new Error(
+      "One of your hook handlers returned a promise, but no side effect collector was provided. Pass a `defer` callback to sendSessionStartMessages() to collect async side effects."
+    );
+  }) {
+    const users = {};
+    for (const session of this.otherSessions(ticket.sessionKey)) {
+      users[session.actor] = {
+        id: session.user.id,
+        info: session.user.info,
+        scopes: session.scopes
+      };
+    }
+    const leasedSessions = await this.listLeasedSessions(
+      ctx,
+      defer
+    );
+    for (const leasedSession of leasedSessions) {
+      users[leasedSession.actorId] = {
+        id: leasedSession.sessionId,
+        info: leasedSession.info,
+        scopes: []
+      };
+    }
+    newSession.send(
+      makeRoomStateMsg(
+        newSession.actor,
+        ticket.sessionKey,
+        // called "nonce" in the protocol
+        newSession.scopes,
+        users,
+        ticket.publicMeta
+      )
+    );
+    for (const leasedSession of leasedSessions) {
+      newSession.send({
+        type: ServerMsgCode2.UPDATE_PRESENCE,
+        actor: leasedSession.actorId,
+        targetActor: newSession.actor,
+        // full presence to new user
+        data: leasedSession.presence
+      });
+    }
+  }
   /**
    * Registers a new BrowserSession into the Room server's session list, along with
    * the socket connection to use for that BrowserSession, now that it is known.
@@ -2001,7 +2063,7 @@ var Room = class {
    * - Sends a ROOM_STATE message to the socket.
    * - Broadcasts a USER_JOINED message to all other sessions in the room.
    */
-  startBrowserSession(ticket, socket, ctx, defer = () => {
+  async startBrowserSession(ticket, socket, ctx, defer = () => {
     throw new Error(
       "One of your hook handlers returned a promise, but no side effect collector was provided. Pass a `defer` callback to startBrowserSession() to collect async side effects."
     );
@@ -2021,24 +2083,7 @@ var Room = class {
     }
     const newSession = new BrowserSession(ticket, socket, __privateGet(this, __debug2));
     this.sessions.set(ticket.sessionKey, newSession);
-    const users = {};
-    for (const session of this.otherSessions(ticket.sessionKey)) {
-      users[session.actor] = {
-        id: session.user.id,
-        info: session.user.info,
-        scopes: session.scopes
-      };
-    }
-    newSession.send(
-      makeRoomStateMsg(
-        newSession.actor,
-        ticket.sessionKey,
-        // called "nonce" in the protocol
-        newSession.scopes,
-        users,
-        ticket.publicMeta
-      )
-    );
+    await this.sendSessionStartMessages(newSession, ticket, ctx, defer);
     this.sendToOthers(
       ticket.sessionKey,
       {
@@ -2191,7 +2236,136 @@ var Room = class {
     return Array.from(this.sessions.values());
   }
   /**
-   * Will send the given ServerMsg to all Sessions, except the Session
+   * Upsert a leased session. Creates a new session if it doesn't exist (or is expired),
+   * or updates an existing session with merged presence.
+   */
+  async upsertLeasedSession(sessionId, presence, ttl, info, ctx, defer = () => {
+    throw new Error(
+      "One of your hook handlers returned a promise, but no side effect collector was provided. Pass a `defer` callback to upsertLeasedSession() to collect async side effects."
+    );
+  }) {
+    const existingSession = await this.driver.get_leased_session(sessionId);
+    const isExpired = existingSession !== void 0 && isLeasedSessionExpired(existingSession);
+    if (isExpired) {
+      await this.deleteLeasedSession(existingSession, ctx, defer);
+    }
+    if (existingSession === void 0 || isExpired) {
+      const actorId = await this.getNextActor();
+      const now = Date.now();
+      const session = {
+        sessionId,
+        presence,
+        updatedAt: now,
+        info,
+        ttl,
+        actorId
+      };
+      await this.driver.put_leased_session(session);
+      this.sendToAll(
+        {
+          type: ServerMsgCode2.USER_JOINED,
+          actor: actorId,
+          id: sessionId,
+          info,
+          scopes: []
+        },
+        ctx,
+        defer
+      );
+      this.sendToAll(
+        {
+          type: ServerMsgCode2.UPDATE_PRESENCE,
+          actor: actorId,
+          data: presence,
+          targetActor: 1
+        },
+        ctx,
+        defer
+      );
+    } else {
+      const mergedPresence = {
+        ...existingSession.presence,
+        ...presence
+      };
+      const updatedSession = {
+        ...existingSession,
+        //info, UserInfo is immutable after creation
+        presence: mergedPresence,
+        updatedAt: Date.now(),
+        ttl
+      };
+      await this.driver.put_leased_session(updatedSession);
+      this.sendToAll(
+        {
+          type: ServerMsgCode2.UPDATE_PRESENCE,
+          actor: existingSession.actorId,
+          data: presence
+          // Send only the patch, not the full merged presence
+          // NO targetActor - this makes it a partial presence patch
+        },
+        ctx,
+        defer
+      );
+    }
+  }
+  /**
+   * List all server sessions. As a side effect, it will delete expired sessions.
+   */
+  async listLeasedSessions(ctx, defer = () => {
+    throw new Error(
+      "One of your hook handlers returned a promise, but no side effect collector was provided. Pass a `defer` callback to listLeasedSessions() to collect async side effects."
+    );
+  }) {
+    await this.load(ctx);
+    const sessions = await this.driver.list_leased_sessions();
+    const validSessions = [];
+    const toDelete = [];
+    for (const [_, session] of sessions) {
+      if (isLeasedSessionExpired(session)) {
+        toDelete.push(session);
+      } else {
+        validSessions.push(session);
+      }
+    }
+    for (const session of toDelete) {
+      await this.deleteLeasedSession(session, ctx, defer);
+    }
+    return validSessions;
+  }
+  /**
+   * Delete a server session and broadcast USER_LEFT to all sessions.
+   */
+  async deleteLeasedSession(session, ctx, defer = () => {
+    throw new Error(
+      "One of your hook handlers returned a promise, but no side effect collector was provided. Pass a `defer` callback to deleteLeasedSession() to collect async side effects."
+    );
+  }) {
+    this.sendToAll(
+      {
+        type: ServerMsgCode2.USER_LEFT,
+        actor: session.actorId
+      },
+      ctx,
+      defer
+    );
+    await this.driver.delete_leased_session(session.sessionId);
+  }
+  /**
+   * Delete all server sessions and broadcast USER_LEFT to all sessions.
+   */
+  async deleteAllLeasedSessions(ctx, defer = () => {
+    throw new Error(
+      "One of your hook handlers returned a promise, but no side effect collector was provided. Pass a `defer` callback to deleteAllLeasedSessions() to collect async side effects."
+    );
+  }) {
+    await this.load(ctx);
+    const sessions = await this.driver.list_leased_sessions();
+    for (const [_, session] of sessions) {
+      await this.deleteLeasedSession(session, ctx, defer);
+    }
+  }
+  /**
+   * Will send the given ServerMsg through all Session, except the Session
    * where the message originates from.
    */
   sendToOthers(sender, serverMsg, ctx, defer = () => {
@@ -2555,6 +2729,7 @@ export {
   clientMsgDecoder,
   concatUint8Arrays,
   guidDecoder,
+  isLeasedSessionExpired,
   jsonObjectYolo,
   jsonYolo,
   makeInMemorySnapshot,