experimental-a2 0.5.1 → 0.6.0

package/dist/react.js

@@ -1,5 +1,5 @@
 "use client";
-import { t as createClient } from "./client-BKlyLiOU.js";
+import { t as createClient } from "./client-Dj5d3SP_.js";
 import { createContext, createElement, useContext, useEffect, useMemo, useSyncExternalStore } from "react";
 //#region src/react.ts
 /**
@@ -13,10 +13,15 @@ import { createContext, createElement, useContext, useEffect, useMemo, useSyncEx
 * renders resolve the same live session. Everything is typed by the
 * reducer value — no type arguments, and nothing here ever touches the
 * machine module.
+*
+* The standalone `useSession(client, sessionId, options?)` is the
+* provider-less primitive for client-first apps: identity-mapped
+* handles, one leased stream per session, and an app-owned hydration
+* input — the hook holds the stream until the app hands it a
+* `{ state, index }` fold.
 */
 function createReact(options) {
 	const Context = createContext(null);
-	const providerMounts = /* @__PURE__ */ new WeakMap();
 	const resolveSession = "client" in options ? (sessionId, _api, initialState, initialIndex, initialEvents, participant) => options.client.session(sessionId, {
 		initialState,
 		initialIndex,
@@ -53,48 +58,82 @@ function createReact(options) {
 			initialEvents,
 			participant
 		]);
-		useEffect(() => {
-			const mounts = providerMounts.get(client) ?? 0;
-			providerMounts.set(client, mounts + 1);
-			if (mounts === 0) client.connect();
-			return () => {
-				const remaining = (providerMounts.get(client) ?? 1) - 1;
-				if (remaining === 0) {
-					providerMounts.delete(client);
-					client.close();
-				} else providerMounts.set(client, remaining);
-			};
-		}, [client]);
+		useSessionLifecycle(client, true);
 		return createElement(Context.Provider, { value: client }, props.children);
 	}
-	function useSession() {
+	function useBoundSession() {
 		const client = useContext(Context);
 		if (!client) throw new Error("useSession must be rendered inside its matching SessionProvider");
-		const snapshot = useSyncExternalStore(client.subscribe, client.getSnapshot, client.getSnapshot);
-		return useMemo(() => {
-			const { setPresence } = client;
-			const { presence } = snapshot;
-			return {
-				state: snapshot.state,
-				events: snapshot.events,
-				index: snapshot.index,
-				connection: snapshot.connection,
-				push: client.push,
-				loadHistory: client.loadHistory,
-				history: snapshot.history,
-				...setPresence && presence ? {
-					presence,
-					setPresence
-				} : {}
-			};
-		}, [snapshot, client]);
+		return useSessionResult(client);
 	}
 	return {
 		SessionProvider,
-		useSession
+		useSession: useBoundSession
 	};
 }
+/**
+* Hold a stream lease while mounted and `live` — the client refcounts
+* leases per handle, so however many providers and hooks mount one
+* session, the first connects and the last release closes
+* (StrictMode-safe: the lease is retaken on remount). A standalone
+* hook without a `hydrate` value passes `live: false` and holds the
+* stream — connecting an unhydrated session would replay the whole
+* log, and the library never picks the expensive path silently.
+*/
+function useSessionLifecycle(session, live) {
+	useEffect(() => {
+		if (!live) return;
+		return session.connect();
+	}, [session, live]);
+}
+function useSessionResult(session) {
+	const snapshot = useSyncExternalStore(session.subscribe, session.getSnapshot, session.getSnapshot);
+	return useMemo(() => {
+		const { setPresence } = session;
+		const { presence } = snapshot;
+		return {
+			state: snapshot.state,
+			events: snapshot.events,
+			index: snapshot.index,
+			connection: snapshot.connection,
+			push: session.push,
+			loadHistory: session.loadHistory,
+			history: snapshot.history,
+			...setPresence && presence ? {
+				presence,
+				setPresence
+			} : {}
+		};
+	}, [snapshot, session]);
+}
+/**
+* The standalone, provider-less hook — for apps whose components reach
+* sessions ad hoc (a sidebar of channel sessions, a user session read
+* from a menu). Takes the shared client and a session id; the handle
+* is identity-mapped, so every hook and provider mounting the same
+* session shares one runtime and one leased stream. Hydration is
+* app-owned: pass `hydrate` when your fetch lands; until then the
+* stream is held, and your data layer's loading state is the pending
+* state.
+*/
+function useSession(client, sessionId, options) {
+	const { participant, hydrate } = options ?? {};
+	const session = useMemo(() => client.session(sessionId, {
+		...hydrate === void 0 ? {} : {
+			initialState: hydrate.state,
+			initialIndex: hydrate.index
+		},
+		...participant === void 0 ? {} : { participant }
+	}), [
+		client,
+		sessionId,
+		hydrate,
+		participant
+	]);
+	useSessionLifecycle(session, hydrate !== void 0);
+	return useSessionResult(session);
+}
 //#endregion
-export { createReact };
+export { createReact, useSession };
 
 //# sourceMappingURL=react.js.map

package/dist/react.js.map

@@ -1 +1 @@
-{"version":3,"file":"react.js","names":[],"sources":["../src/react.ts"],"sourcesContent":["'use client'\n/**\n * experimental-a2/react — React bindings over experimental-a2/client.\n *\n * `createReact({ client })` is a factory (like createContext): call it\n * once in a `'use client'` module with a shared A2 client and export the\n * bound pair. Server components import `SessionProvider` from that module\n * as a client reference; client components import `useSession` from the\n * same file. The shared client also makes imperative pushes and provider\n * renders resolve the same live session. Everything is typed by the\n * reducer value — no type arguments, and nothing here ever touches the\n * machine module.\n */\n\nimport {\n  createContext,\n  createElement,\n  useContext,\n  useEffect,\n  useMemo,\n  useSyncExternalStore,\n  type ReactElement,\n  type ReactNode,\n} from 'react'\nimport {\n  createClient,\n  type A2Client,\n  type Connection,\n  type HistoryState,\n  type LoadHistoryOptions,\n  type PushResult,\n  type SessionClient,\n  type SessionClientPresence,\n  type SessionSnapshot,\n} from './client.ts'\nimport type {\n  AppendInput,\n  ContractEvent,\n  EventDefs,\n  PresenceDefs,\n  PresenceMap,\n  PresencePatch,\n  WithPresence,\n} from './contract.ts'\nimport type { Reducer } from './reducer.ts'\n\nexport type SessionProviderProps<D extends EventDefs, S> = {\n  /** Which session to subscribe to. */\n  sessionId: string\n  /** Base path of the route exposing GET (stream) and POST (push). */\n  api: string\n  /** The server-rendered fold — the first paint, no client JS needed. */\n  initialState: S\n  /** The fold's frontier — the stream resumes exactly there. */\n  initialIndex: number\n  /** Server-rendered event history through `initialIndex`. */\n  initialEvents?: ContractEvent<D>[]\n  /**\n   * This client's presence identity — required to call `setPresence`.\n   * Caller-supplied (a user id, a tab nonce, a guest name): A2 does\n   * not invent an identity story.\n   */\n  participant?: string\n  children?: ReactNode\n}\n\nexport type BoundSessionProviderProps<D extends EventDefs, S> = Omit<\n  SessionProviderProps<D, S>,\n  'api'\n>\n\n/**\n * The presence members of the hook result — intersected in via\n * `WithPresence`, so they exist exactly when the contract declares\n * presence fields (the reducer is the client's typed handle on it).\n */\nexport type UseSessionPresence<P extends PresenceDefs> = {\n  /** The replicated presence map, this client included (local echo). */\n  presence: PresenceMap<P>\n  /**\n   * Fire-and-forget: validated locally, echoed into the map\n   * immediately, coalesced on the wire to a fixed cadence (a leading\n   * send immediately, then at most one merged send per interval;\n   * later values win per field), stamped with the frontier at send\n   * time as `seen`. Requires the provider's `participant`.\n   */\n  setPresence: (values: PresencePatch<P>['values']) => void\n}\n\nexport type UseSessionResult<\n  D extends EventDefs,\n  S,\n  P extends PresenceDefs = Record<never, never>,\n> = WithPresence<P, UseSessionPresence<P>> & {\n  /** The live view, folded through the shared reducer. */\n  state: S\n  /** The raw event feed — observed, seeded, or backscrolled. */\n  events: ContractEvent<D>[]\n  /** The stream frontier — `lastSeenIndex` for cancellation. */\n  index: number\n  /**\n   * The connection, as a discriminated union — `error` exists only\n   * while disconnected; \"reconnecting…\" is\n   * `status === 'connecting' && reconnects > 0`.\n   */\n  connection: Connection\n  /**\n   * Typed optimistic append. Awaiting it gives the server ack;\n   * `.confirmed` resolves when the live stream has delivered the batch\n   * back. Rejects with the server's A2Error codes.\n   */\n  push: (...events: AppendInput<D>[]) => PushResult<D>\n  /**\n   * Backscroll: fetch a bounded slice of older events into `events`.\n   * Defaults page backward 50 at a time from the oldest loaded event.\n   * Display data only — `state` and the optimistic overlay never move.\n   */\n  loadHistory: (options?: LoadHistoryOptions) => Promise<ContractEvent<D>[]>\n  /** Backscroll progress: `complete` means the feed reaches index 1. */\n  history: HistoryState\n}\n\nexport type A2React<\n  D extends EventDefs,\n  S,\n  P extends PresenceDefs = Record<never, never>,\n> = {\n  SessionProvider: (props: SessionProviderProps<D, S>) => ReactElement\n  useSession: () => UseSessionResult<D, S, P>\n}\n\nexport type BoundA2React<\n  D extends EventDefs,\n  S,\n  P extends PresenceDefs = Record<never, never>,\n> = {\n  SessionProvider: (props: BoundSessionProviderProps<D, S>) => ReactElement\n  useSession: () => UseSessionResult<D, S, P>\n}\n\nexport function createReact<\n  D extends EventDefs,\n  S,\n  P extends PresenceDefs = Record<never, never>,\n>(options: { client: A2Client<D, S, P> }): BoundA2React<D, S, P>\nexport function createReact<\n  D extends EventDefs,\n  S,\n  P extends PresenceDefs = Record<never, never>,\n>(options: { reducer: Reducer<D, S, P> }): A2React<D, S, P>\nexport function createReact<\n  D extends EventDefs,\n  S,\n  P extends PresenceDefs = Record<never, never>,\n>(\n  options: { client: A2Client<D, S, P> } | { reducer: Reducer<D, S, P> },\n): BoundA2React<D, S, P> | A2React<D, S, P> {\n  const Context = createContext<SessionClient<D, S, P> | null>(null)\n  const providerMounts = new WeakMap<SessionClient<D, S, P> & object, number>()\n  const resolveSession: (\n    sessionId: string,\n    api: string | undefined,\n    initialState: S,\n    initialIndex: number,\n    initialEvents: ContractEvent<D>[] | undefined,\n    participant: string | undefined,\n  ) => SessionClient<D, S, P> =\n    'client' in options\n      ? (\n          sessionId,\n          _api,\n          initialState,\n          initialIndex,\n          initialEvents,\n          participant,\n        ) =>\n          options.client.session(sessionId, {\n            initialState,\n            initialIndex,\n            ...(initialEvents === undefined ? {} : { initialEvents }),\n            ...(participant === undefined ? {} : { participant }),\n          })\n      : (() => {\n          const clients = new Map<string, A2Client<D, S, P>>()\n          return (\n            sessionId: string,\n            api: string | undefined,\n            initialState: S,\n            initialIndex: number,\n            initialEvents: ContractEvent<D>[] | undefined,\n            participant: string | undefined,\n          ) => {\n            if (api === undefined) {\n              throw new TypeError(\n                'SessionProvider requires api when createReact binds a reducer',\n              )\n            }\n            let client = clients.get(api)\n            if (!client) {\n              client = createClient({ reducer: options.reducer, api })\n              clients.set(api, client)\n            }\n            return client.session(sessionId, {\n              initialState,\n              initialIndex,\n              ...(initialEvents === undefined ? {} : { initialEvents }),\n              ...(participant === undefined ? {} : { participant }),\n            })\n          }\n        })()\n\n  function SessionProvider(\n    props: SessionProviderProps<D, S> | BoundSessionProviderProps<D, S>,\n  ): ReactElement {\n    const {\n      sessionId,\n      initialState,\n      initialIndex,\n      initialEvents,\n      participant,\n    } = props\n    const api = 'api' in props ? props.api : undefined\n    const client = useMemo(\n      () =>\n        resolveSession(\n          sessionId,\n          api,\n          initialState,\n          initialIndex,\n          initialEvents,\n          participant,\n        ),\n      [sessionId, api, initialState, initialIndex, initialEvents, participant],\n    )\n    useEffect(() => {\n      const mounts = providerMounts.get(client) ?? 0\n      providerMounts.set(client, mounts + 1)\n      if (mounts === 0) client.connect()\n      return () => {\n        const remaining = (providerMounts.get(client) ?? 1) - 1\n        if (remaining === 0) {\n          providerMounts.delete(client)\n          client.close()\n        } else {\n          providerMounts.set(client, remaining)\n        }\n      }\n    }, [client])\n    return createElement(Context.Provider, { value: client }, props.children)\n  }\n\n  function useSession(): UseSessionResult<D, S, P> {\n    const client = useContext(Context)\n    if (!client) {\n      throw new Error(\n        'useSession must be rendered inside its matching SessionProvider',\n      )\n    }\n    const snapshot: SessionSnapshot<D, S, P> = useSyncExternalStore(\n      client.subscribe,\n      client.getSnapshot,\n      client.getSnapshot,\n    )\n    return useMemo(() => {\n      // Runtime mirror of the WithPresence surface: the client attaches\n      // setPresence (and the snapshot carries presence) exactly when the\n      // reducer declares presence fields — no runtime-inert members.\n      const { setPresence } = client as Partial<SessionClientPresence<P>>\n      const { presence } = snapshot as Partial<{ presence: PresenceMap<P> }>\n      return {\n        state: snapshot.state,\n        events: snapshot.events,\n        index: snapshot.index,\n        connection: snapshot.connection,\n        push: client.push,\n        loadHistory: client.loadHistory,\n        history: snapshot.history,\n        ...(setPresence && presence ? { presence, setPresence } : {}),\n      } as UseSessionResult<D, S, P>\n    }, [snapshot, client])\n  }\n\n  return { SessionProvider, useSession }\n}\n"],"mappings":";;;;;;;;;;;;;;;;AAsJA,SAAgB,YAKd,SAC0C;CAC1C,MAAM,UAAU,cAA6C,IAAI;CACjE,MAAM,iCAAiB,IAAI,QAAiD;CAC5E,MAAM,iBAQJ,YAAY,WAEN,WACA,MACA,cACA,cACA,eACA,gBAEA,QAAQ,OAAO,QAAQ,WAAW;EAChC;EACA;EACA,GAAI,kBAAkB,KAAA,IAAY,CAAC,IAAI,EAAE,cAAc;EACvD,GAAI,gBAAgB,KAAA,IAAY,CAAC,IAAI,EAAE,YAAY;CACrD,CAAC,WACI;EACL,MAAM,0BAAU,IAAI,IAA+B;EACnD,QACE,WACA,KACA,cACA,cACA,eACA,gBACG;GACH,IAAI,QAAQ,KAAA,GACV,MAAM,IAAI,UACR,+DACF;GAEF,IAAI,SAAS,QAAQ,IAAI,GAAG;GAC5B,IAAI,CAAC,QAAQ;IACX,SAAS,aAAa;KAAE,SAAS,QAAQ;KAAS;IAAI,CAAC;IACvD,QAAQ,IAAI,KAAK,MAAM;GACzB;GACA,OAAO,OAAO,QAAQ,WAAW;IAC/B;IACA;IACA,GAAI,kBAAkB,KAAA,IAAY,CAAC,IAAI,EAAE,cAAc;IACvD,GAAI,gBAAgB,KAAA,IAAY,CAAC,IAAI,EAAE,YAAY;GACrD,CAAC;EACH;CACF,EAAA,CAAG;CAET,SAAS,gBACP,OACc;EACd,MAAM,EACJ,WACA,cACA,cACA,eACA,gBACE;EACJ,MAAM,MAAM,SAAS,QAAQ,MAAM,MAAM,KAAA;EACzC,MAAM,SAAS,cAEX,eACE,WACA,KACA,cACA,cACA,eACA,WACF,GACF;GAAC;GAAW;GAAK;GAAc;GAAc;GAAe;EAAW,CACzE;EACA,gBAAgB;GACd,MAAM,SAAS,eAAe,IAAI,MAAM,KAAK;GAC7C,eAAe,IAAI,QAAQ,SAAS,CAAC;GACrC,IAAI,WAAW,GAAG,OAAO,QAAQ;GACjC,aAAa;IACX,MAAM,aAAa,eAAe,IAAI,MAAM,KAAK,KAAK;IACtD,IAAI,cAAc,GAAG;KACnB,eAAe,OAAO,MAAM;KAC5B,OAAO,MAAM;IACf,OACE,eAAe,IAAI,QAAQ,SAAS;GAExC;EACF,GAAG,CAAC,MAAM,CAAC;EACX,OAAO,cAAc,QAAQ,UAAU,EAAE,OAAO,OAAO,GAAG,MAAM,QAAQ;CAC1E;CAEA,SAAS,aAAwC;EAC/C,MAAM,SAAS,WAAW,OAAO;EACjC,IAAI,CAAC,QACH,MAAM,IAAI,MACR,iEACF;EAEF,MAAM,WAAqC,qBACzC,OAAO,WACP,OAAO,aACP,OAAO,WACT;EACA,OAAO,cAAc;GAInB,MAAM,EAAE,gBAAgB;GACxB,MAAM,EAAE,aAAa;GACrB,OAAO;IACL,OAAO,SAAS;IAChB,QAAQ,SAAS;IACjB,OAAO,SAAS;IAChB,YAAY,SAAS;IACrB,MAAM,OAAO;IACb,aAAa,OAAO;IACpB,SAAS,SAAS;IAClB,GAAI,eAAe,WAAW;KAAE;KAAU;IAAY,IAAI,CAAC;GAC7D;EACF,GAAG,CAAC,UAAU,MAAM,CAAC;CACvB;CAEA,OAAO;EAAE;EAAiB;CAAW;AACvC"}
+{"version":3,"file":"react.js","names":[],"sources":["../src/react.ts"],"sourcesContent":["'use client'\n/**\n * experimental-a2/react — React bindings over experimental-a2/client.\n *\n * `createReact({ client })` is a factory (like createContext): call it\n * once in a `'use client'` module with a shared A2 client and export the\n * bound pair. Server components import `SessionProvider` from that module\n * as a client reference; client components import `useSession` from the\n * same file. The shared client also makes imperative pushes and provider\n * renders resolve the same live session. Everything is typed by the\n * reducer value — no type arguments, and nothing here ever touches the\n * machine module.\n *\n * The standalone `useSession(client, sessionId, options?)` is the\n * provider-less primitive for client-first apps: identity-mapped\n * handles, one leased stream per session, and an app-owned hydration\n * input — the hook holds the stream until the app hands it a\n * `{ state, index }` fold.\n */\n\nimport {\n  createContext,\n  createElement,\n  useContext,\n  useEffect,\n  useMemo,\n  useSyncExternalStore,\n  type ReactElement,\n  type ReactNode,\n} from 'react'\nimport {\n  createClient,\n  type A2Client,\n  type Connection,\n  type HistoryState,\n  type LoadHistoryOptions,\n  type PushResult,\n  type SessionClient,\n  type SessionClientPresence,\n  type SessionSnapshot,\n} from './client.ts'\nimport type {\n  AppendInput,\n  ContractEvent,\n  EventDefs,\n  PresenceDefs,\n  PresenceMap,\n  PresencePatch,\n  WithPresence,\n} from './contract.ts'\nimport type { Reducer } from './reducer.ts'\n\nexport type UseSessionOptions<S> = {\n  /** Overrides the client's `participant` for this session — for apps\n   * whose identity is only known at mount time. Bound once per\n   * session handle. */\n  participant?: string\n  /**\n   * The server fold this session mounts from: the `{ state, index }`\n   * pair `session.state(reducer)` returns, fetched by the app through\n   * its own route. Atomic on purpose — the fold and its frontier\n   * travel together or not at all. While `undefined` (the app's fetch\n   * has not landed), the hook holds the stream; when the value\n   * arrives, the session hydrates through the ordinary re-hydration\n   * seam and the stream connects at that frontier. To fold from the log's start\n   * deliberately, hand the fold's true starting point:\n   * `{ state: reducer.initialState, index: 0 }` — state at index 0 is\n   * the reducer's seed by definition, so the explicit replay needs no\n   * special vocabulary. There is no pending/ready echo on the result:\n   * whether the fold has been handed over is this option — the\n   * caller's own input — so the data layer's loading state IS the\n   * pending state.\n   */\n  hydrate?: { state: S; index: number } | undefined\n}\n\nexport type SessionProviderProps<D extends EventDefs, S> = {\n  /** Which session to subscribe to. */\n  sessionId: string\n  /** Base path of the route exposing GET (stream) and POST (push). */\n  api: string\n  /** The server-rendered fold — the first paint, no client JS needed. */\n  initialState: S\n  /** The fold's frontier — the stream resumes exactly there. */\n  initialIndex: number\n  /** Server-rendered event history through `initialIndex`. */\n  initialEvents?: ContractEvent<D>[]\n  /** Overrides the client's `participant` for this session — for apps\n   * whose identity is only known at mount time. */\n  participant?: string\n  children?: ReactNode\n}\n\nexport type BoundSessionProviderProps<D extends EventDefs, S> = Omit<\n  SessionProviderProps<D, S>,\n  'api'\n>\n\n/**\n * The presence members of the hook result — intersected in via\n * `WithPresence`, so they exist exactly when the contract declares\n * presence fields (the reducer is the client's typed handle on it).\n */\nexport type UseSessionPresence<P extends PresenceDefs> = {\n  /** The replicated presence map, this client included (local echo). */\n  presence: PresenceMap<P>\n  /**\n   * Fire-and-forget: validated locally, echoed into the map\n   * immediately, coalesced on the wire to a fixed cadence (a leading\n   * send immediately, then at most one merged send per interval;\n   * later values win per field), stamped with the frontier at send\n   * time as `seen`. Requires the provider's `participant`.\n   */\n  setPresence: (values: PresencePatch<P>['values']) => void\n}\n\nexport type UseSessionResult<\n  D extends EventDefs,\n  S,\n  P extends PresenceDefs = Record<never, never>,\n> = WithPresence<P, UseSessionPresence<P>> & {\n  /** The live view, folded through the shared reducer. */\n  state: S\n  /** The raw event feed — observed, seeded, or backscrolled. */\n  events: ContractEvent<D>[]\n  /** The stream frontier — `lastSeenIndex` for cancellation. */\n  index: number\n  /**\n   * The connection, as a discriminated union — `error` exists only\n   * while disconnected; \"reconnecting…\" is\n   * `status === 'connecting' && reconnects > 0`.\n   */\n  connection: Connection\n  /**\n   * Typed optimistic append. Awaiting it gives the server ack;\n   * `.confirmed` resolves when the live stream has delivered the batch\n   * back. Rejects with the server's A2Error codes.\n   */\n  push: (...events: AppendInput<D>[]) => PushResult<D>\n  /**\n   * Backscroll: fetch a bounded slice of older events into `events`.\n   * Defaults page backward 50 at a time from the oldest loaded event.\n   * Display data only — `state` and the optimistic overlay never move.\n   */\n  loadHistory: (options?: LoadHistoryOptions) => Promise<ContractEvent<D>[]>\n  /** Backscroll progress: `complete` means the feed reaches index 1. */\n  history: HistoryState\n}\n\nexport type A2React<\n  D extends EventDefs,\n  S,\n  P extends PresenceDefs = Record<never, never>,\n> = {\n  SessionProvider: (props: SessionProviderProps<D, S>) => ReactElement\n  useSession: () => UseSessionResult<D, S, P>\n}\n\nexport type BoundA2React<\n  D extends EventDefs,\n  S,\n  P extends PresenceDefs = Record<never, never>,\n> = {\n  SessionProvider: (props: BoundSessionProviderProps<D, S>) => ReactElement\n  useSession: () => UseSessionResult<D, S, P>\n}\n\nexport function createReact<\n  D extends EventDefs,\n  S,\n  P extends PresenceDefs = Record<never, never>,\n>(options: { client: A2Client<D, S, P> }): BoundA2React<D, S, P>\nexport function createReact<\n  D extends EventDefs,\n  S,\n  P extends PresenceDefs = Record<never, never>,\n>(options: { reducer: Reducer<D, S, P> }): A2React<D, S, P>\nexport function createReact<\n  D extends EventDefs,\n  S,\n  P extends PresenceDefs = Record<never, never>,\n>(\n  options: { client: A2Client<D, S, P> } | { reducer: Reducer<D, S, P> },\n): BoundA2React<D, S, P> | A2React<D, S, P> {\n  const Context = createContext<SessionClient<D, S, P> | null>(null)\n  const resolveSession: (\n    sessionId: string,\n    api: string | undefined,\n    initialState: S,\n    initialIndex: number,\n    initialEvents: ContractEvent<D>[] | undefined,\n    participant: string | undefined,\n  ) => SessionClient<D, S, P> =\n    'client' in options\n      ? (\n          sessionId,\n          _api,\n          initialState,\n          initialIndex,\n          initialEvents,\n          participant,\n        ) =>\n          options.client.session(sessionId, {\n            initialState,\n            initialIndex,\n            ...(initialEvents === undefined ? {} : { initialEvents }),\n            ...(participant === undefined ? {} : { participant }),\n          })\n      : (() => {\n          const clients = new Map<string, A2Client<D, S, P>>()\n          return (\n            sessionId: string,\n            api: string | undefined,\n            initialState: S,\n            initialIndex: number,\n            initialEvents: ContractEvent<D>[] | undefined,\n            participant: string | undefined,\n          ) => {\n            if (api === undefined) {\n              throw new TypeError(\n                'SessionProvider requires api when createReact binds a reducer',\n              )\n            }\n            let client = clients.get(api)\n            if (!client) {\n              client = createClient({ reducer: options.reducer, api })\n              clients.set(api, client)\n            }\n            return client.session(sessionId, {\n              initialState,\n              initialIndex,\n              ...(initialEvents === undefined ? {} : { initialEvents }),\n              ...(participant === undefined ? {} : { participant }),\n            })\n          }\n        })()\n\n  function SessionProvider(\n    props: SessionProviderProps<D, S> | BoundSessionProviderProps<D, S>,\n  ): ReactElement {\n    const {\n      sessionId,\n      initialState,\n      initialIndex,\n      initialEvents,\n      participant,\n    } = props\n    const api = 'api' in props ? props.api : undefined\n    const client = useMemo(\n      () =>\n        resolveSession(\n          sessionId,\n          api,\n          initialState,\n          initialIndex,\n          initialEvents,\n          participant,\n        ),\n      [sessionId, api, initialState, initialIndex, initialEvents, participant],\n    )\n    useSessionLifecycle(client, true)\n    return createElement(Context.Provider, { value: client }, props.children)\n  }\n\n  function useBoundSession(): UseSessionResult<D, S, P> {\n    const client = useContext(Context)\n    if (!client) {\n      throw new Error(\n        'useSession must be rendered inside its matching SessionProvider',\n      )\n    }\n    return useSessionResult(client)\n  }\n\n  return { SessionProvider, useSession: useBoundSession }\n}\n\n// ── the shared session lifecycle ───────────────────────────────\n\n/**\n * Hold a stream lease while mounted and `live` — the client refcounts\n * leases per handle, so however many providers and hooks mount one\n * session, the first connects and the last release closes\n * (StrictMode-safe: the lease is retaken on remount). A standalone\n * hook without a `hydrate` value passes `live: false` and holds the\n * stream — connecting an unhydrated session would replay the whole\n * log, and the library never picks the expensive path silently.\n */\nfunction useSessionLifecycle<D extends EventDefs, S, P extends PresenceDefs>(\n  session: SessionClient<D, S, P>,\n  live: boolean,\n): void {\n  useEffect(() => {\n    if (!live) return\n    return session.connect()\n  }, [session, live])\n}\n\nfunction useSessionResult<D extends EventDefs, S, P extends PresenceDefs>(\n  session: SessionClient<D, S, P>,\n): UseSessionResult<D, S, P> {\n  const snapshot: SessionSnapshot<D, S, P> = useSyncExternalStore(\n    session.subscribe,\n    session.getSnapshot,\n    session.getSnapshot,\n  )\n  return useMemo(() => {\n    // Runtime mirror of the WithPresence surface: the client attaches\n    // setPresence (and the snapshot carries presence) exactly when the\n    // reducer declares presence fields — no runtime-inert members.\n    const { setPresence } = session as Partial<SessionClientPresence<P>>\n    const { presence } = snapshot as Partial<{ presence: PresenceMap<P> }>\n    return {\n      state: snapshot.state,\n      events: snapshot.events,\n      index: snapshot.index,\n      connection: snapshot.connection,\n      push: session.push,\n      loadHistory: session.loadHistory,\n      history: snapshot.history,\n      ...(setPresence && presence ? { presence, setPresence } : {}),\n    } as UseSessionResult<D, S, P>\n  }, [snapshot, session])\n}\n\n/**\n * The standalone, provider-less hook — for apps whose components reach\n * sessions ad hoc (a sidebar of channel sessions, a user session read\n * from a menu). Takes the shared client and a session id; the handle\n * is identity-mapped, so every hook and provider mounting the same\n * session shares one runtime and one leased stream. Hydration is\n * app-owned: pass `hydrate` when your fetch lands; until then the\n * stream is held, and your data layer's loading state is the pending\n * state.\n */\nexport function useSession<\n  D extends EventDefs,\n  S,\n  P extends PresenceDefs = Record<never, never>,\n>(\n  client: A2Client<D, S, P>,\n  sessionId: string,\n  options?: UseSessionOptions<S>,\n): UseSessionResult<D, S, P> {\n  const { participant, hydrate } = options ?? {}\n  const session = useMemo(\n    () =>\n      client.session(sessionId, {\n        ...(hydrate === undefined\n          ? {}\n          : { initialState: hydrate.state, initialIndex: hydrate.index }),\n        ...(participant === undefined ? {} : { participant }),\n      }),\n    [client, sessionId, hydrate, participant],\n  )\n  useSessionLifecycle(session, hydrate !== undefined)\n  return useSessionResult(session)\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;AAiLA,SAAgB,YAKd,SAC0C;CAC1C,MAAM,UAAU,cAA6C,IAAI;CACjE,MAAM,iBAQJ,YAAY,WAEN,WACA,MACA,cACA,cACA,eACA,gBAEA,QAAQ,OAAO,QAAQ,WAAW;EAChC;EACA;EACA,GAAI,kBAAkB,KAAA,IAAY,CAAC,IAAI,EAAE,cAAc;EACvD,GAAI,gBAAgB,KAAA,IAAY,CAAC,IAAI,EAAE,YAAY;CACrD,CAAC,WACI;EACL,MAAM,0BAAU,IAAI,IAA+B;EACnD,QACE,WACA,KACA,cACA,cACA,eACA,gBACG;GACH,IAAI,QAAQ,KAAA,GACV,MAAM,IAAI,UACR,+DACF;GAEF,IAAI,SAAS,QAAQ,IAAI,GAAG;GAC5B,IAAI,CAAC,QAAQ;IACX,SAAS,aAAa;KAAE,SAAS,QAAQ;KAAS;IAAI,CAAC;IACvD,QAAQ,IAAI,KAAK,MAAM;GACzB;GACA,OAAO,OAAO,QAAQ,WAAW;IAC/B;IACA;IACA,GAAI,kBAAkB,KAAA,IAAY,CAAC,IAAI,EAAE,cAAc;IACvD,GAAI,gBAAgB,KAAA,IAAY,CAAC,IAAI,EAAE,YAAY;GACrD,CAAC;EACH;CACF,EAAA,CAAG;CAET,SAAS,gBACP,OACc;EACd,MAAM,EACJ,WACA,cACA,cACA,eACA,gBACE;EACJ,MAAM,MAAM,SAAS,QAAQ,MAAM,MAAM,KAAA;EACzC,MAAM,SAAS,cAEX,eACE,WACA,KACA,cACA,cACA,eACA,WACF,GACF;GAAC;GAAW;GAAK;GAAc;GAAc;GAAe;EAAW,CACzE;EACA,oBAAoB,QAAQ,IAAI;EAChC,OAAO,cAAc,QAAQ,UAAU,EAAE,OAAO,OAAO,GAAG,MAAM,QAAQ;CAC1E;CAEA,SAAS,kBAA6C;EACpD,MAAM,SAAS,WAAW,OAAO;EACjC,IAAI,CAAC,QACH,MAAM,IAAI,MACR,iEACF;EAEF,OAAO,iBAAiB,MAAM;CAChC;CAEA,OAAO;EAAE;EAAiB,YAAY;CAAgB;AACxD;;;;;;;;;;AAaA,SAAS,oBACP,SACA,MACM;CACN,gBAAgB;EACd,IAAI,CAAC,MAAM;EACX,OAAO,QAAQ,QAAQ;CACzB,GAAG,CAAC,SAAS,IAAI,CAAC;AACpB;AAEA,SAAS,iBACP,SAC2B;CAC3B,MAAM,WAAqC,qBACzC,QAAQ,WACR,QAAQ,aACR,QAAQ,WACV;CACA,OAAO,cAAc;EAInB,MAAM,EAAE,gBAAgB;EACxB,MAAM,EAAE,aAAa;EACrB,OAAO;GACL,OAAO,SAAS;GAChB,QAAQ,SAAS;GACjB,OAAO,SAAS;GAChB,YAAY,SAAS;GACrB,MAAM,QAAQ;GACd,aAAa,QAAQ;GACrB,SAAS,SAAS;GAClB,GAAI,eAAe,WAAW;IAAE;IAAU;GAAY,IAAI,CAAC;EAC7D;CACF,GAAG,CAAC,UAAU,OAAO,CAAC;AACxB;;;;;;;;;;;AAYA,SAAgB,WAKd,QACA,WACA,SAC2B;CAC3B,MAAM,EAAE,aAAa,YAAY,WAAW,CAAC;CAC7C,MAAM,UAAU,cAEZ,OAAO,QAAQ,WAAW;EACxB,GAAI,YAAY,KAAA,IACZ,CAAC,IACD;GAAE,cAAc,QAAQ;GAAO,cAAc,QAAQ;EAAM;EAC/D,GAAI,gBAAgB,KAAA,IAAY,CAAC,IAAI,EAAE,YAAY;CACrD,CAAC,GACH;EAAC;EAAQ;EAAW;EAAS;CAAW,CAC1C;CACA,oBAAoB,SAAS,YAAY,KAAA,CAAS;CAClD,OAAO,iBAAiB,OAAO;AACjC"}

package/docs/guides/03-react.mdx

@@ -218,7 +218,11 @@ That identity is an in-memory L1, not another source of truth. Repeated
 `session(id)` calls reuse it while active and for five idle minutes by
 default. A newer server fold advances it, pending pushes stay overlaid,
 and a stale server render cannot rewind it. The optional IndexedDB cache
-is the L2: it survives reloads; the memory runtime does not.
+is the L2: it survives reloads; the memory runtime does not. The
+stream is shared the same way: `connect()` takes a lease and returns
+its release, so however many hooks, providers, or plain calls hold one
+session open, the first lease connects and the last release closes
+(`close()` is the hard stop).
 
 One detail worth knowing: every push carries a client-generated event id.
 That id is how the ack finds its optimistic entry, and it makes retrying
@@ -234,6 +238,99 @@ revisits paint from the local copy, the stream resumes from the cached
 frontier, and offline pushes queue and replay. See
 [Local-first](/guides/local-first).
 
+## Client-first sessions
+
+Everything above assumes a server component hands the first fold down.
+A client-rendered app often has nothing to hand: a sidebar showing ten
+channel sessions, a user session read from deep inside a menu, panes
+that mount from client-side navigation. No server fold, and no natural
+provider boundary for components that reach sessions ad hoc.
+
+For that shape, `experimental-a2/react` exports a standalone hook. Any
+component can mount any session, no provider needed:
+
+```tsx app/orders/[orderId]/order-badge.tsx
+'use client'
+import { useSession } from 'experimental-a2/react'
+import { ordersClient } from './session'
+
+export function OrderBadge({ orderId }: { orderId: string }) {
+  // your fetch (SWR, a router loader, a parent's payload): anything
+  // that lands the { state, index } your route returns (below), e.g.
+  // const { data } = useSWR(`/api/orders/${orderId}/state`)
+  const data = undefined // still loading
+
+  const { state } = useSession(ordersClient, orderId, { hydrate: data })
+  if (!data) return <span>…</span> // your loading state IS the pending state
+  return <span>{state.status}</span>
+}
+```
+
+The fold comes from your own route, and the route is one line of A2:
+
+```ts app/api/orders/[orderId]/state/route.ts
+import { ordersServer } from '@/server/orders'
+import { ordersReducer } from '@/reducer'
+
+export async function GET(
+  _req: Request,
+  { params }: { params: Promise<{ orderId: string }> },
+) {
+  const { orderId } = await params
+  // here's where you'd do auth, or any other checks
+  return Response.json(
+    await ordersServer.session(orderId).state(ordersReducer),
+  )
+}
+```
+
+Note what is not on the wire: a reducer name. The route calls
+`session.state(reducer)` with the reducer by reference, the same
+module your client bundle folds with. That matters because renaming a
+reducer is the [snapshot invalidation knob](/concepts/state): if the
+name traveled on the wire, every rename would open a version-skew
+window between deployed clients and servers. By reference, the knob
+stays free. And unlike a history slice, which is immutable once read
+and earns a standard wire shape, a state read is a moving snapshot;
+there is nothing for the library to standardize, so the read stays
+behind your route, under your auth and caching policy.
+
+`hydrate` is one atomic option: the `{ state, index }` pair
+`session.state(reducer)` returns. State and its frontier travel
+together or not at all; a half-present handoff cannot compile. While
+it is `undefined` (your fetch has not landed), the hook holds the
+stream and `state` is the reducer's `initialState`. There is no
+pending flag on the result: whether the fold has been handed over is
+your own input, so your data layer's loading state is the pending
+state. When the value arrives, the session hydrates
+and the stream connects at that frontier. The hold is deliberate:
+connecting without a fold means replaying the whole log through the
+browser, and the library never picks the expensive path silently. When
+a full replay is what you want (a short log, a debug view), hand the
+fold's true starting point:
+`hydrate: { state: ordersReducer.initialState, index: 0 }`. State at
+index 0 is the reducer's seed by definition, so the explicit replay
+needs no special vocabulary; the stream then delivers every event
+live.
+
+The rest behaves like the provider. The handle is identity-mapped
+(every hook and provider mounting the same session shares one runtime)
+and each mount holds a lease on the shared stream (see
+[the client identity note](#the-client-component)). A later, further
+fold handed to the same session
+advances it and a stale one is ignored, the same never-move-backward
+rule as everywhere else. For presence, identity comes from the
+client's `participant` (set once on `createClient`) or the hook's
+`participant` option, which overrides it. The
+result is exactly the shape the bound hook returns. There is no
+loading or error member: the
+library performs no fetch here, so your data layer's states are the
+states, retried however your data layer retries.
+
+`SessionProvider` keeps its required `initialState`/`initialIndex`.
+The provider is the server-handoff tool; the hook is the client-first
+tool.
+
 ## Keep the backend out of the bundle
 
 The split is structural, not disciplinary. Core `experimental-a2` (the contract,

package/docs/guides/09-presence.mdx

@@ -94,8 +94,11 @@ presence-only push acks `[]`.
 
 ## The browser
 
-The provider takes a `participant` id (yours to mint: a user id, a tab
-nonce, the playground's guest name). The hook grows two members. The
+Presence needs a `participant` id (yours to mint: a user id, a tab
+nonce, the playground's guest name). State it once on
+`createClient({ participant })` when the app knows it at module scope,
+or pass it to the provider, whose `participant` prop overrides the
+client's. The hook grows two members. The
 session module is the usual pair from
 [Live UI](/guides/react#the-session-module), bound to a reducer that
 carries the canvas contract:

package/docs/reference/01-api.mdx

@@ -650,7 +650,7 @@ transition and the destination should adopt the same optimistic session.
 | `initialState`  | server-rendered state                                  |
 | `initialIndex`  | the fold's frontier, where the stream resumes          |
 | `initialEvents` | optional earlier raw events for a history UI           |
-| `participant`   | this client's presence identity; required to call `setPresence` |
+| `participant`   | overrides the client's `participant`; one of the two is required to call `setPresence` |
 
 Opens the stream on mount, closes it on unmount, reconnects with
 backoff from the current frontier. `participant` binds at the session's
@@ -706,8 +706,9 @@ invert). No ack, no `confirmed`, no retry.
 Both members exist only when the contract declares `presence`; their
 value and field types come from its schemas, through the reducer, with
 no type arguments (the reducer is the client's typed handle on the
-contract; it still never folds presence). `setPresence` requires the
-provider's `participant`. If the map holds only your own echo with
+contract; it still never folds presence). `setPresence` requires a
+`participant`: the client's default, or the provider's override. If
+the map holds only your own echo with
 participants active, the GET route forgot `presence: true`. See
 [Presence](/guides/presence).
 
@@ -754,6 +755,37 @@ connection as dead (aborts it and reconnects), so `live` means bytes
 are actually flowing, not "the socket hasn't errored yet". See
 [Live UI](/guides/react).
 
+### `useSession(client, sessionId, options?)`
+
+```ts
+useSession(client: A2Client, sessionId: string, options?: {
+  participant?: string // overrides the client's participant
+  hydrate?: { state: S; index: number }
+}): UseSessionResult
+```
+
+The standalone, provider-less hook. It returns the same result shape
+as the bound hook, for apps whose components reach sessions ad hoc (a
+sidebar of channel sessions, a user session read from a menu). The
+handle is identity-mapped: every hook and provider mounting the same
+session shares one runtime. The stream is refcounted: the first mount
+connects, the last unmount closes (StrictMode-safe).
+
+`hydrate` is the hydration input, one atomic option: the
+`{ state, index }` pair `session.state(reducer)` returns, fetched by
+your app through its own route and handed over whenever it lands.
+While it is `undefined`, the hook holds the stream (connecting without
+a fold would replay the whole log). There is no pending flag on the
+result: whether the fold has been handed over is your own input, so
+your data layer's loading state is the pending state.
+When it arrives, the session hydrates under the usual
+never-move-backward rule and the stream connects at that frontier.
+For a deliberate full replay, hand the fold's true starting point:
+`{ state: reducer.initialState, index: 0 }`. State at index 0 is the
+reducer's seed by definition, so the explicit replay needs no special
+vocabulary. See
+[Client-first sessions](/guides/react#client-first-sessions).
+
 ## `experimental-a2/ai`
 
 ### `agent(options)`
@@ -1035,6 +1067,7 @@ createClient(options: {
   reducer: Reducer
   api: ClientApi
   gcTime?: number // idle session lifetime; 5 minutes by default
+  participant?: string // default presence identity for every session
 }): A2Client
 
 type ClientApi =
@@ -1049,11 +1082,19 @@ queue with ack/rollback, and the local fold. `client.session(id, {
 initialState?, initialIndex?, initialEvents?, participant? })` returns a
 handle with `getSnapshot()`/`subscribe()` (the `useSyncExternalStore`
 contract), `push()`, `loadHistory()`, `connect()`, and `close()`.
+`connect()` takes a lease on the live stream and returns its release:
+leases refcount per handle (the first connects, releasing the last
+closes, releasing twice is a no-op), so independent consumers of one
+identity-mapped handle never fight over the stream. `close()` is the
+hard stop: it drops every outstanding lease and closes now; a later
+`connect()` starts fresh.
 Snapshots carry `state`, `events`, `index`, `history`, and `connection`
 (the same fields `useSession` exposes), and `push` returns the same
 ack-then-`confirmed` result. On contracts that declare `presence` the handle also carries
 `setPresence()` and snapshots carry the `presence` map, exactly like
-the hook; `participant` is the identity `setPresence` sends under. Use
+the hook; `participant` is the identity `setPresence` sends under:
+stated once on `createClient` as the default for every handle, or per
+session as the override. Use
 it directly from any other framework, or none.
 
 Within one `A2Client`, repeated `session(id)` calls return the same live

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "experimental-a2",
-  "version": "0.5.1",
+  "version": "0.6.0",
   "description": "Durable sync and reactions for things with a lifecycle: one event log, derived state, and live client per session.",
   "license": "MIT",
   "type": "module",

package/src/client.ts

@@ -177,13 +177,19 @@ export type SessionClient<
    * this throws a TypeError there.
    */
   loadHistory(options?: LoadHistoryOptions): Promise<ContractEvent<D>[]>
-  /** Open the live stream (idempotent while open). Reconnects with
-   * backoff and resumes from the frontier until `close()`. */
-  connect(): void
   /**
-   * Stop the live stream. Not terminal: `connect()` starts it again
-   * from the current frontier — which is what makes the React
-   * StrictMode mount dance (setup → cleanup → setup) work.
+   * Take a lease on the live stream and return its release. Leases
+   * refcount per handle — the first connects, releasing the last
+   * closes — so independent consumers of one identity-mapped handle
+   * (two hooks, a hook plus vanilla code) never fight over the
+   * stream. Releasing twice is a no-op. While any lease is held the
+   * stream reconnects with backoff and resumes from the frontier.
+   */
+  connect(): () => void
+  /**
+   * The hard stop: drops every outstanding lease and closes the
+   * stream now. Not terminal — a later `connect()` starts fresh from
+   * the current frontier.
    */
   close(): void
 }
@@ -193,11 +199,8 @@ export type SessionOptions<D extends EventDefs, S> = {
   initialIndex?: number
   /** Server-rendered history through `initialIndex`. Seeds the event feed. */
   initialEvents?: ContractEvent<D>[]
-  /**
-   * This client's presence identity — required to call `setPresence`.
-   * Caller-supplied (a user id, a tab nonce, a guest name): A2 does
-   * not invent an identity story. Bound once per session handle.
-   */
+  /** Overrides the client's `participant` for this session handle.
+   * Bound once per handle. */
   participant?: string
 }
 
@@ -263,6 +266,14 @@ export type CreateClientOptions<
   /** How long an idle session keeps its in-memory identity, in
    * milliseconds. Defaults to five minutes; `Infinity` disables GC. */
   gcTime?: number
+  /**
+   * This client's presence identity — required to call `setPresence`.
+   * Caller-supplied (a user id, a tab nonce, a guest name): A2 does
+   * not invent an identity story; the app states it once here. The
+   * default for every session handle this client creates;
+   * `session(id, { participant })` overrides it per handle.
+   */
+  participant?: string
 }
 
 const PUSH_ATTEMPTS = 3
@@ -1022,7 +1033,7 @@ export function createClient<
     // stream; the own entry is the local echo — server copies of self
     // are ignored (the echo is at least as new, and comparing it to
     // server stamps would put two clocks in one order).
-    let participant = sessionOptions?.participant
+    let participant = sessionOptions?.participant ?? options.participant
     // Participant and field keys arrive off the wire, so the map and
     // every entry are built null-prototype — see `nullProtoRecord`.
     let presenceState: PresenceMap = nullProtoRecord()
@@ -1292,7 +1303,7 @@ export function createClient<
     const setPresence = (values: PresencePatch<P>['values']): void => {
       if (participant === undefined) {
         throw new TypeError(
-          'setPresence requires a participant — pass one in the session options (the SessionProvider participant prop)',
+          'setPresence requires a participant — pass one to createClient({ participant }) or in the session options (the SessionProvider/useSession participant prop)',
         )
       }
       const validated: Record<string, unknown> = nullProtoRecord()
@@ -1600,11 +1611,34 @@ export function createClient<
 
     // ── the live stream ──────────────────────────────────────────
     // A run-generation model instead of a terminal `closed` flag:
-    // close() bumps the generation (the running loop notices and
+    // stopping bumps the generation (the running loop notices and
     // exits), connect() starts a fresh one. Reentrant by design.
+    // Consumers hold leases: connect() counts one and returns its
+    // release, the last release stops the stream, and close() is the
+    // hard stop — it drops every lease and stops now (bumping
+    // `leaseEpoch` makes the outstanding releases inert).
     let generation = 0
     let active = false
     let abort: AbortController | null = null
+    let leases = 0
+    let leaseEpoch = 0
+
+    const stopStream = (): void => {
+      touch(sessionId)
+      if (!active) return
+      active = false
+      generation += 1 // the running loop notices and exits
+      abort?.abort()
+      abort = null
+      // A pending trailing send dies with the stream — losing one is
+      // fine by definition; sets made while closed accumulate in
+      // `presenceResend` and repaint after the next connect.
+      clearTimeout(presenceTimer)
+      presenceTimer = undefined
+      presenceBuffer = null
+      status = 'closed'
+      notify()
+    }
 
     const runStream = async (run: number): Promise<void> => {
       let backoff = STREAM_TIMINGS.reconnectBaseMs
@@ -1727,27 +1761,29 @@ export function createClient<
       loadHistory,
       connect() {
         touch(sessionId)
-        if (active) return
-        active = true
-        status = 'connecting'
-        notify()
-        void runStream(generation)
+        leases += 1
+        const epoch = leaseEpoch
+        if (!active) {
+          active = true
+          status = 'connecting'
+          notify()
+          void runStream(generation)
+        }
+        let released = false
+        return () => {
+          // Idempotent, and inert after a hard close() — a stale
+          // release must not touch leases taken since.
+          if (released || leaseEpoch !== epoch) return
+          released = true
+          touch(sessionId)
+          leases -= 1
+          if (leases === 0) stopStream()
+        }
       },
       close() {
-        touch(sessionId)
-        if (!active) return
-        active = false
-        generation += 1 // the running loop notices and exits
-        abort?.abort()
-        abort = null
-        // A pending trailing send dies with the stream — losing one is
-        // fine by definition; sets made while closed accumulate in
-        // `presenceResend` and repaint after the next connect.
-        clearTimeout(presenceTimer)
-        presenceTimer = undefined
-        presenceBuffer = null
-        status = 'closed'
-        notify()
+        leases = 0
+        leaseEpoch += 1
+        stopStream()
       },
       hydrate(next) {
         touch(sessionId)