experimental-a2 0.16.0 → 0.17.0

package/src/react.ts

@@ -1,27 +1,9 @@
 'use client'
-/**
- * experimental-a2/react — React bindings over experimental-a2/client.
- *
- * `createReact({ client })` is a factory (like createContext): call it
- * once in a `'use client'` module with a shared A2 client and export the
- * bound pair. Server components import `SessionProvider` from that module
- * as a client reference; client components import `useSession` from the
- * same file. The shared client also makes imperative pushes and provider
- * 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.
- */
-
 import {
   createContext,
   createElement,
   useContext,
+  use,
   useEffect,
   useMemo,
   useSyncExternalStore,
@@ -37,10 +19,11 @@ import {
   type PushResult,
   type SessionClient,
   type SessionClientPresence,
-  type SessionSnapshot,
+  type SessionOptions,
 } from './client.ts'
 import type {
   AppendInput,
+  Contract,
   ContractEvent,
   EventDefs,
   PresenceDefs,
@@ -49,44 +32,24 @@ import type {
   WithPresence,
 } from './contract.ts'
 import type { Reducer } from './reducer.ts'
+import {
+  createRenderSession,
+  resolveInitialForReact,
+} from './client-render-session.ts'
+import { isInitialPromise, type InitialSnapshot } from './initial-snapshot.ts'
 
 export type UseSessionOptions<S> = {
-  /** Overrides the client's `participant` for this session — for apps
-   * whose identity is only known at mount time. Bound once per
-   * session handle. */
   participant?: string
-  /**
-   * The server fold this session mounts from: the `{ state, index }`
-   * pair `session.state(reducer)` returns, fetched by the app through
-   * its own route. Atomic on purpose — the fold and its frontier
-   * travel together or not at all. While `undefined` (the app's fetch
-   * has not landed), the hook holds the stream; when the value
-   * arrives, the session hydrates through the ordinary re-hydration
-   * seam and the stream connects at that frontier. To fold from the log's start
-   * deliberately, 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. There is no pending/ready echo on the result:
-   * whether the fold has been handed over is this option — the
-   * caller's own input — so the data layer's loading state IS the
-   * pending state.
-   */
-  hydrate?: { state: S; index: number } | undefined
+  initial?: InitialSnapshot<S>
+  enabled?: boolean
+  suspend?: boolean
 }
 
 export type SessionProviderProps<D extends EventDefs, S> = {
-  /** Which session to subscribe to. */
   sessionId: string
-  /** Base path of the route exposing GET (stream) and POST (push). */
   api: string
-  /** The server-rendered fold — the first paint, no client JS needed. */
-  initialState: S
-  /** The fold's frontier — the stream resumes exactly there. */
-  initialIndex: number
-  /** Server-rendered event history through `initialIndex`. */
+  initial?: InitialSnapshot<S>
   initialEvents?: ContractEvent<D>[]
-  /** Overrides the client's `participant` for this session — for apps
-   * whose identity is only known at mount time. */
   participant?: string
   children?: ReactNode
 }
@@ -96,11 +59,6 @@ export type BoundSessionProviderProps<D extends EventDefs, S> = Omit<
   'api'
 >
 
-/**
- * The presence members of the hook result — intersected in via
- * `WithPresence`, so they exist exactly when the contract declares
- * presence fields (the reducer is the client's typed handle on it).
- */
 export type UseSessionPresence<P extends PresenceDefs> = {
   /** The replicated presence map, this client included (local echo). */
   presence: PresenceMap<P>
@@ -121,6 +79,8 @@ export type UseSessionResult<
 > = WithPresence<P, UseSessionPresence<P>> & {
   /** The live view, folded through the shared reducer. */
   state: S
+  /** A state/index snapshot has been applied; independent of connection status. */
+  hydrated: boolean
   /** The raw event feed — observed, seeded, or backscrolled. */
   events: ContractEvent<D>[]
   /** The stream frontier — `lastSeenIndex` for cancellation. */
@@ -149,219 +109,224 @@ export type UseSessionResult<
   history: HistoryState
 }
 
+export type BoundSessionOptions<
+  D extends EventDefs,
+  S,
+  P extends PresenceDefs,
+> = UseSessionOptions<S> & {
+  sessionId?: string
+  client?: A2Client<D, S, P>
+}
+
 export type A2React<
   D extends EventDefs,
   S,
   P extends PresenceDefs = Record<never, never>,
-  V = S,
 > = {
   SessionProvider: (props: SessionProviderProps<D, S>) => ReactElement
-  useSession: () => UseSessionResult<D, V, P>
+  useSession: (
+    options?: BoundSessionOptions<D, S, P>,
+  ) => UseSessionResult<D, S, P>
 }
 
 export type BoundA2React<
   D extends EventDefs,
   S,
   P extends PresenceDefs = Record<never, never>,
-  V = S,
 > = {
   SessionProvider: (props: BoundSessionProviderProps<D, S>) => ReactElement
-  useSession: () => UseSessionResult<D, V, P>
+  useSession: (
+    options?: BoundSessionOptions<D, S, P>,
+  ) => UseSessionResult<D, S, P>
 }
 
 export function createReact<
   D extends EventDefs,
   S,
   P extends PresenceDefs = Record<never, never>,
-  V = S,
->(options: { client: A2Client<D, S, P, V> }): BoundA2React<D, S, P, V>
+>(options: { client: A2Client<D, S, P> }): BoundA2React<D, S, P>
 export function createReact<
   D extends EventDefs,
   S,
   P extends PresenceDefs = Record<never, never>,
-  V = S,
->(options: { reducer: Reducer<D, S, P, V> }): A2React<D, S, P, V>
+>(options: { contract: Contract<D, P, Reducer<D, S, P>> }): A2React<D, S, P>
 export function createReact<
   D extends EventDefs,
   S,
   P extends PresenceDefs = Record<never, never>,
-  V = S,
 >(
-  options: { client: A2Client<D, S, P, V> } | { reducer: Reducer<D, S, P, V> },
-): BoundA2React<D, S, P, V> | A2React<D, S, P, V> {
-  const Context = createContext<SessionClient<D, S, P, V> | null>(null)
-  const resolveSession: (
-    sessionId: string,
-    api: string | undefined,
-    initialState: S,
-    initialIndex: number,
-    initialEvents: ContractEvent<D>[] | undefined,
-    participant: string | undefined,
-  ) => SessionClient<D, S, P, V> =
-    'client' in options
-      ? (
-          sessionId,
-          _api,
-          initialState,
-          initialIndex,
-          initialEvents,
-          participant,
-        ) =>
-          options.client.session(sessionId, {
-            initialState,
-            initialIndex,
-            ...(initialEvents === undefined ? {} : { initialEvents }),
-            ...(participant === undefined ? {} : { participant }),
-          })
-      : (() => {
-          const clients = new Map<string, A2Client<D, S, P, V>>()
-          return (
-            sessionId: string,
-            api: string | undefined,
-            initialState: S,
-            initialIndex: number,
-            initialEvents: ContractEvent<D>[] | undefined,
-            participant: string | undefined,
-          ) => {
-            if (api === undefined) {
-              throw new TypeError(
-                'SessionProvider requires api when createReact binds a reducer',
-              )
-            }
-            let client = clients.get(api)
-            if (!client) {
-              client = createClient({ reducer: options.reducer, api })
-              clients.set(api, client)
-            }
-            return client.session(sessionId, {
-              initialState,
-              initialIndex,
-              ...(initialEvents === undefined ? {} : { initialEvents }),
-              ...(participant === undefined ? {} : { participant }),
-            })
-          }
-        })()
+  options:
+    | { client: A2Client<D, S, P> }
+    | { contract: Contract<D, P, Reducer<D, S, P>> },
+): BoundA2React<D, S, P> | A2React<D, S, P> {
+  type Scope = {
+    client: A2Client<D, S, P>
+    sessionId: string
+    settings: SessionOptions<D, S>
+  }
+  const Context = createContext<Scope | null>(null)
+  const clients = new Map<string, A2Client<D, S, P>>()
+  const resolveClient = (api: string | undefined): A2Client<D, S, P> => {
+    if ('client' in options) return options.client
+    if (api === undefined)
+      throw new TypeError(
+        'SessionProvider requires api when createReact binds a contract',
+      )
+    let client = clients.get(api)
+    if (!client) {
+      client = createClient({ contract: options.contract, api })
+      clients.set(api, client)
+    }
+    return client
+  }
 
   function SessionProvider(
     props: SessionProviderProps<D, S> | BoundSessionProviderProps<D, S>,
   ): ReactElement {
-    const {
-      sessionId,
-      initialState,
-      initialIndex,
-      initialEvents,
-      participant,
-    } = props
+    const { sessionId, initial, initialEvents, participant } = props
     const api = 'api' in props ? props.api : undefined
-    const client = useMemo(
-      () =>
-        resolveSession(
-          sessionId,
-          api,
-          initialState,
-          initialIndex,
-          initialEvents,
-          participant,
-        ),
-      [sessionId, api, initialState, initialIndex, initialEvents, participant],
+    const scope = useMemo(
+      () => ({
+        client: resolveClient(api),
+        sessionId,
+        settings: {
+          ...(initial === undefined ? {} : { initial }),
+          ...(initialEvents === undefined ? {} : { initialEvents }),
+          ...(participant === undefined ? {} : { participant }),
+        },
+      }),
+      [sessionId, api, initial, initialEvents, participant],
     )
-    useSessionLifecycle(client, true)
-    return createElement(Context.Provider, { value: client }, props.children)
+    return createElement(Context.Provider, { value: scope }, props.children)
   }
 
-  function useBoundSession(): UseSessionResult<D, V, P> {
-    const client = useContext(Context)
-    if (!client) {
-      throw new Error(
-        'useSession must be rendered inside its matching SessionProvider',
+  function useBoundSession(
+    overrides: BoundSessionOptions<D, S, P> = {},
+  ): UseSessionResult<D, S, P> {
+    const scope = useContext(Context)
+    const client =
+      overrides.client ??
+      scope?.client ??
+      ('client' in options ? options.client : undefined)
+    const sessionId = overrides.sessionId ?? scope?.sessionId
+    if (!client || sessionId === undefined)
+      throw new TypeError(
+        'provide client and sessionId through SessionProvider or hook options',
       )
-    }
-    return useSessionResult(client)
+    const inherits = client === scope?.client && sessionId === scope?.sessionId
+    const inherited = inherits ? scope.settings : undefined
+    const { initial, participant } = overrides
+    const settings = useMemo(
+      () => ({
+        ...inherited,
+        ...(initial === undefined ? {} : { initial }),
+        ...(participant === undefined ? {} : { participant }),
+      }),
+      [inherited, initial, participant],
+    )
+    return useLiveSession({
+      client,
+      sessionId,
+      settings,
+      enabled: overrides.enabled ?? true,
+      suspend: overrides.suspend ?? false,
+    })
   }
 
   return { SessionProvider, useSession: useBoundSession }
 }
 
-// ── the shared session lifecycle ───────────────────────────────
-
-/**
- * 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<D extends EventDefs, S, P extends PresenceDefs, V>(
-  session: SessionClient<D, S, P, V>,
-  live: boolean,
-): void {
-  useEffect(() => {
-    if (!live) return
-    return session.connect()
-  }, [session, live])
-}
-
-function useSessionResult<D extends EventDefs, S, P extends PresenceDefs, V>(
-  session: SessionClient<D, S, P, V>,
-): UseSessionResult<D, V, P> {
-  const snapshot: SessionSnapshot<D, V, P> = useSyncExternalStore(
+function useLiveSession<
+  D extends EventDefs,
+  S,
+  P extends PresenceDefs,
+>(options: {
+  client: A2Client<D, S, P>
+  sessionId: string
+  settings: SessionOptions<D, S>
+  enabled: boolean
+  suspend: boolean
+}): UseSessionResult<D, S, P> {
+  const { client, sessionId, settings, enabled, suspend } = options
+  const browserSession = useMemo(() => {
+    if (typeof window === 'undefined') {
+      if (isInitialPromise(settings.initial))
+        void settings.initial.catch(() => {})
+      return undefined
+    }
+    return client.session(sessionId, settings)
+  }, [client, sessionId, settings])
+  const promise = isInitialPromise(settings.initial)
+    ? settings.initial
+    : undefined
+  const resolved = promise && suspend ? use(promise) : undefined
+  const renderInitial = promise ? resolved : settings.initial
+  const renderSession = useMemo(() => {
+    let session: SessionClient<D, S, P> | undefined
+    return () => {
+      session ??= createRenderSession({
+        client,
+        sessionId,
+        settings: { ...settings, initial: renderInitial },
+      })
+      return session
+    }
+  }, [client, sessionId, settings, renderInitial])
+  const session = browserSession ?? renderSession()
+  if (browserSession && promise && suspend)
+    resolveInitialForReact({
+      client,
+      session: browserSession,
+      source: promise,
+      value: resolved,
+    })
+  const serverSnapshot = useMemo(
+    () => () => renderSession().getSnapshot(),
+    [renderSession],
+  )
+  const snapshot = useSyncExternalStore(
     session.subscribe,
     session.getSnapshot,
-    session.getSnapshot,
+    serverSnapshot,
   )
+  useEffect(() => {
+    if (enabled) return session.connect()
+  }, [session, enabled])
   return useMemo(() => {
-    // Runtime mirror of the WithPresence surface: the client attaches
-    // setPresence (and the snapshot carries presence) exactly when the
-    // reducer declares presence fields — no runtime-inert members.
     const { setPresence } = session as Partial<SessionClientPresence<P>>
     const { presence } = snapshot as Partial<{ presence: PresenceMap<P> }>
     return {
-      state: snapshot.state,
-      events: snapshot.events,
-      index: snapshot.index,
-      connection: snapshot.connection,
+      ...snapshot,
       push: session.push,
       reconnect: session.reconnect,
       loadHistory: session.loadHistory,
-      history: snapshot.history,
       ...(setPresence && presence ? { presence, setPresence } : {}),
-    } as UseSessionResult<D, V, P>
-  }, [snapshot, session])
+    } as UseSessionResult<D, S, P>
+  }, [session, snapshot])
 }
 
-/**
- * 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.
- */
 export function useSession<
   D extends EventDefs,
   S,
   P extends PresenceDefs = Record<never, never>,
-  V = S,
 >(
-  client: A2Client<D, S, P, V>,
+  client: A2Client<D, S, P>,
   sessionId: string,
-  options?: UseSessionOptions<S>,
-): UseSessionResult<D, V, P> {
-  const { participant, hydrate } = options ?? {}
-  const session = useMemo(
-    () =>
-      client.session(sessionId, {
-        ...(hydrate === undefined
-          ? {}
-          : { initialState: hydrate.state, initialIndex: hydrate.index }),
-        ...(participant === undefined ? {} : { participant }),
-      }),
-    [client, sessionId, hydrate, participant],
+  options: UseSessionOptions<NoInfer<S>> = {},
+): UseSessionResult<D, S, P> {
+  const { initial, participant } = options
+  const settings = useMemo(
+    () => ({
+      ...(initial === undefined ? {} : { initial }),
+      ...(participant === undefined ? {} : { participant }),
+    }),
+    [initial, participant],
   )
-  useSessionLifecycle(session, hydrate !== undefined)
-  return useSessionResult(session)
+  return useLiveSession({
+    client,
+    sessionId,
+    settings,
+    enabled: options.enabled ?? true,
+    suspend: options.suspend ?? false,
+  })
 }