@lunora/client 1.0.0-alpha.22 → 1.0.0-alpha.24

package/dist/packem_shared/httpStream-DIdL8NEw.mjs

@@ -0,0 +1,168 @@
+import { LunoraError } from '@lunora/errors';
+import { createStream } from './DEFAULT_MAX_BUFFER-7hFnzNk9.mjs';
+
+const SSE_FIELD_SPACE_RE = /^ /u;
+const parameterToString = (value) => typeof value === "object" && value !== null ? JSON.stringify(value) : String(value);
+const parseSseFrame = (raw) => {
+  let event = "";
+  const dataLines = [];
+  for (const line of raw.split("\n")) {
+    if (line.startsWith("event:")) {
+      event = line.slice("event:".length).replace(SSE_FIELD_SPACE_RE, "");
+    } else if (line.startsWith("data:")) {
+      dataLines.push(line.slice("data:".length).replace(SSE_FIELD_SPACE_RE, ""));
+    }
+  }
+  return { data: dataLines.join("\n"), event };
+};
+const buildHttpStreamUrl = (route, args, baseUrl) => {
+  const parameters = args.params ?? {};
+  const path = route.path.split("/").map((segment) => {
+    if (!segment.startsWith(":")) {
+      return segment;
+    }
+    const name = segment.slice(1);
+    const value = parameters[name];
+    if (value === void 0) {
+      throw new LunoraError("HTTP_STREAM_MISSING_PARAM", `httpStream: missing path param ":${name}" for route ${route.path}`);
+    }
+    return encodeURIComponent(parameterToString(value));
+  }).join("/");
+  const search = new URLSearchParams();
+  for (const [key, value] of Object.entries(args.searchParams ?? {})) {
+    if (value !== void 0) {
+      search.set(key, parameterToString(value));
+    }
+  }
+  const query = search.toString();
+  const trimmedBase = baseUrl.endsWith("/") ? baseUrl.slice(0, -1) : baseUrl;
+  return `${trimmedBase}${path}${query === "" ? "" : `?${query}`}`;
+};
+const handleSseFrame = (frame, handle) => {
+  if (frame.event === "complete") {
+    handle.complete();
+    return true;
+  }
+  if (frame.event === "error") {
+    let payload = {};
+    try {
+      payload = JSON.parse(frame.data);
+    } catch {
+    }
+    const message = typeof payload.message === "string" ? payload.message : "stream error";
+    const code = typeof payload.code === "string" ? payload.code : "HTTP_STREAM_ERROR";
+    handle.fail(new LunoraError(code, message));
+    return true;
+  }
+  if ((frame.event === "" || frame.event === "message") && frame.data !== "") {
+    try {
+      handle.push(JSON.parse(frame.data));
+    } catch {
+      handle.fail(new LunoraError("HTTP_STREAM_BAD_CHUNK", "httpStream: malformed SSE chunk (invalid JSON)"));
+      return true;
+    }
+  }
+  return false;
+};
+const pumpSseBody = async (body, handle) => {
+  const reader = body.getReader();
+  const decoder = new TextDecoder();
+  let buffer = "";
+  const drainFrames = () => {
+    let separatorIndex = buffer.indexOf("\n\n");
+    while (separatorIndex !== -1) {
+      const frame = parseSseFrame(buffer.slice(0, separatorIndex));
+      buffer = buffer.slice(separatorIndex + 2);
+      if (handleSseFrame(frame, handle)) {
+        return true;
+      }
+      separatorIndex = buffer.indexOf("\n\n");
+    }
+    return false;
+  };
+  for (; ; ) {
+    const { done, value } = await reader.read();
+    if (done) {
+      break;
+    }
+    buffer += decoder.decode(value, { stream: true }).replaceAll("\r\n", "\n");
+    if (drainFrames()) {
+      await reader.cancel().catch(() => {
+      });
+      return;
+    }
+  }
+  buffer += decoder.decode().replaceAll("\r\n", "\n");
+  if (!drainFrames()) {
+    handle.fail(new LunoraError("HTTP_STREAM_INTERRUPTED", "httpStream: stream ended without a complete frame"));
+  }
+};
+const httpStream = (route, args, options = {}) => {
+  const fetchImpl = options.fetch ?? (typeof fetch === "function" ? fetch.bind(globalThis) : void 0);
+  if (!fetchImpl) {
+    throw new LunoraError("INTERNAL", "httpStream: no `fetch` implementation available");
+  }
+  const url = buildHttpStreamUrl(route, args ?? {}, options.baseUrl ?? "");
+  const ac = new AbortController();
+  let onExternalAbort;
+  if (options.signal) {
+    if (options.signal.aborted) {
+      ac.abort();
+    } else {
+      onExternalAbort = () => {
+        ac.abort();
+      };
+      options.signal.addEventListener("abort", onExternalAbort, { once: true });
+    }
+  }
+  const detachExternalAbort = () => {
+    if (onExternalAbort) {
+      options.signal?.removeEventListener("abort", onExternalAbort);
+    }
+  };
+  const { handle, iterable } = createStream({
+    maxBuffer: options.maxBuffer,
+    onCancel: () => {
+      ac.abort();
+    }
+  });
+  (async () => {
+    try {
+      const response = await fetchImpl(url, {
+        headers: { accept: "text/event-stream", ...options.headers },
+        method: route.method,
+        signal: ac.signal
+      });
+      if (!response.ok) {
+        await response.body?.cancel().catch(() => {
+        });
+        handle.fail(
+          new LunoraError("HTTP_STREAM_STATUS", `httpStream: request failed (status ${response.status.toString()})`, {
+            status: response.status
+          })
+        );
+        return;
+      }
+      if (!response.body) {
+        handle.fail(new LunoraError("HTTP_STREAM_NO_BODY", "httpStream: response has no body"));
+        return;
+      }
+      await pumpSseBody(response.body, handle);
+    } finally {
+      detachExternalAbort();
+    }
+  })().catch((error) => {
+    if (ac.signal.aborted) {
+      handle.complete();
+      return;
+    }
+    if (error instanceof Error && "code" in error) {
+      handle.fail(error);
+      return;
+    }
+    handle.fail(new LunoraError("HTTP_STREAM_TRANSPORT", error instanceof Error ? error.message : String(error), { cause: error }));
+  });
+  return iterable;
+};
+
+export { httpStream };

package/dist/packem_shared/{local-store-DtcIW4c0.mjs → local-store-DIq-UWfD.mjs}

@@ -1,4 +1,4 @@
-import { SubscriptionRegistry } from './SubscriptionRegistry-D4jfIzZu.mjs';
+import { SubscriptionRegistry } from './SubscriptionRegistry-CxS_Inha.mjs';
 
 const foldOptimistic = (base, layers) => {
   let value = base;

package/dist/packem_shared/{lunora-client.d-pw-9sLl0.d.mts → lunora-client.d-B8bdwHLr.d.mts}

@@ -117,6 +117,55 @@ interface FunctionReference<Kind extends FunctionKind = FunctionKind, Args = unk
 type ArgsOf<F> = F extends FunctionReference<infer _K, infer A, infer _R> ? A : never;
 /** Extract the return type from a {@link FunctionReference}. */
 type ReturnOf<F> = F extends FunctionReference<infer _K, infer _A, infer R> ? R : never;
+/**
+* Typed reference to an HTTP-SSE stream route (`httpRoute.&lt;verb>(path).stream()`)
+* emitted by `@lunora/codegen` as `httpStreams.&lt;namespace>.&lt;name>`.
+*
+* Distinct from {@link FunctionReference}: this is the **HTTP-SSE route stream**
+* (opened with `fetch` + `ReadableStream` against the route's own URL), not the
+* WS procedure stream (`kind: "stream"`). At runtime it carries the HTTP verb
+* and the route path; the phantom marker carries the chunk / searchParams /
+* params types so `httpStream` (and the framework hooks over it) infer the
+* chunk type end-to-end.
+* @experimental Reconnect/POST-body/wire-fidelity design questions are still open, so the shape may change.
+*/
+interface HttpStreamRef<Chunk = unknown, SearchParams = unknown, Params = unknown> {
+  /**
+  * Phantom marker carrying the `Chunk`/`SearchParams`/`Params` type
+  * parameters for inference. Never present at runtime; declared in a
+  * covariant (output) position so a concrete reference stays assignable to
+  * a widened one.
+  */
+  readonly __lunoraHttpStream?: {
+    chunk: Chunk;
+    params: Params;
+    searchParams: SearchParams;
+  };
+  /** HTTP verb the route binds to (uppercased), e.g. `"GET"`. */
+  readonly method: string;
+  /** The route path as declared, e.g. `/api/tokens/:id` — `:name` segments are filled from `params`. */
+  readonly path: string;
+}
+/**
+* The call-side args of an HTTP-SSE stream route: `:name` path params plus URL query params.
+* @experimental Part of the HTTP-SSE stream surface.
+*/
+interface HttpStreamCallArgs<SearchParams = unknown, Params = unknown> {
+  /** Values for the route path's `:name` segments. */
+  params?: Params;
+  /** URL query params, appended to the request URL (undefined entries are skipped). */
+  searchParams?: SearchParams;
+}
+/**
+* Extract the chunk type from a {@link HttpStreamRef}.
+* @experimental Part of the HTTP-SSE stream surface.
+*/
+type HttpStreamChunkOf<R> = R extends HttpStreamRef<infer Chunk, infer _S, infer _P> ? Chunk : never;
+/**
+* Extract the call-side args type from a {@link HttpStreamRef}.
+* @experimental Part of the HTTP-SSE stream surface.
+*/
+type HttpStreamArgsOf<R> = R extends HttpStreamRef<infer _C, infer S, infer P> ? HttpStreamCallArgs<S, P> : never;
 type Unsubscribe = () => void;
 /**
 * Serializable result of `preloadQuery`. Produced on the server during SSR,
@@ -309,6 +358,15 @@ interface QueryCacheAdapter {
   /** Remove one cached query by key. */
   remove: (key: string) => Promise<void>;
 }
+/**
+* Resolves the WS `?token=` credential fresh at every (re)connect — the channel
+* for short-lived tokens (e.g. the ephemeral admin sub-token the worker mints
+* at `POST /_lunora/admin/ws-token`) instead of a static secret in the URL.
+* May return the token synchronously or as a Promise; returning `undefined`
+* connects without a token. A thrown error / rejected Promise fails that
+* connect attempt, and the client retries with its normal reconnect backoff.
+*/
+type WsTokenProvider = () => Promise<string | undefined> | string | undefined;
 interface LunoraClientOptions {
   /**
   * Base path the worker mounts better-auth at, used by the client's
@@ -421,15 +479,21 @@ interface LunoraClientOptions {
   url: string;
   WebSocket?: typeof WebSocket;
   /**
-  * Token appended to the WebSocket URL as `?token=…`. The server matches it
-  * against `LUNORA_WS_BEARER` (to clear the upgrade gate) and/or
+  * Credential appended to the WebSocket URL as `?token=…`. The server matches
+  * it against `LUNORA_WS_BEARER` (to clear the upgrade gate) and/or
   * `LUNORA_ADMIN_TOKEN` (to authorize `__lunora_admin__:*` subscriptions —
-  * what the studio sets it to). Browsers can't set headers on the
-  * `WebSocket` constructor, so the query parameter is the only channel; it
-  * ends up in server logs and history, so prefer a short-lived rotating
-  * token in production.
+  * what the studio supplies). Browsers can't set headers on the `WebSocket`
+  * constructor, so the query parameter is the only channel; it ends up in
+  * server logs and history, so prefer a short-lived rotating token in
+  * production over a static secret.
+  *
+  * Pass a {@link WsTokenProvider} function to resolve the token fresh at
+  * every (re)connect — the channel for short-lived credentials such as the
+  * ephemeral admin sub-token minted by `POST /_lunora/admin/ws-token`: the
+  * provider re-mints on each reconnect, including the one following a `4001`
+  * token-expired drop, so a static master token never has to ride the URL.
   */
-  wsToken?: string;
+  wsToken?: string | WsTokenProvider;
   wsUrl?: string;
 }
 /** Wire envelope sent on `POST /_lunora/rpc`. */
@@ -997,9 +1061,10 @@ interface SubscriptionState {
   acked: boolean;
   readonly args: Record<string, unknown>;
   /**
-  * Stable-stringified `args`, computed once at subscribe time. Cached so the
-  * optimistic-update fan-out can compare against a mutation's args key without
-  * re-serializing every subscription's args on every mutation.
+  * Stable wire-key of `args` (`stableWireKey`), computed once at subscribe
+  * time. Cached so the optimistic-update fan-out can compare against a
+  * mutation's args key without re-serializing every subscription's args on
+  * every mutation.
   */
   readonly argsKey: string;
   readonly callbacks: Set<SubscriptionCallback>;
@@ -1068,11 +1133,13 @@ interface SubscriptionState {
 }
 /**
 * Active subscription registry. The client keys subscriptions by
-* `(functionPath, stableStringify(args), shardKey)` so duplicate calls share a
+* `(functionPath, stableWireKey(args), shardKey)` so duplicate calls share a
 * single server-side registration. Args are stably encoded (keys sorted at every
 * depth) so two structurally-equal arg records constructed with a different key
 * order (`{ a, b }` vs `{ b, a }`) collapse to the same key instead of leaking a
-* duplicate subscription.
+* duplicate subscription. Encoding the args' **wire form** keeps the key
+* byte-identical for pure-JSON args while giving wire-typed args (`bigint`,
+* `Date`, bytes, …) distinct stable tokens instead of a throw.
 */
 declare class SubscriptionRegistry {
   static key(functionPath: string, args: Record<string, unknown>, shardKey?: string): string;
@@ -1539,10 +1606,12 @@ declare class LunoraClient {
   * Replace the token appended to WS upgrade URLs as `?token=…` and close
   * every open shard socket so the reconnect picks up the new value. Call
   * this whenever the user's WS credential changes (rotating the admin token
-  * in the studio, switching workspaces, etc.). Bearer tokens for HTTP
-  * RPC are independent — see {@link setAuthToken}.
+  * in the studio, switching workspaces, etc.). Accepts a static string or a
+  * {@link WsTokenProvider} resolved fresh at every (re)connect — the channel
+  * for short-lived credentials like the minted ephemeral admin sub-token.
+  * Bearer tokens for HTTP RPC are independent — see {@link setAuthToken}.
   */
-  setWsToken(token: string | undefined): void;
+  setWsToken(token: string | undefined | WsTokenProvider): void;
   /**
   * Register (or clear, with `undefined`) the app context sent in the `connect`
   * envelope for a shard's socket, overriding the client-wide
@@ -1655,6 +1724,18 @@ declare class LunoraClient {
   */
   onMutationSettled(listener: (event: MutationSettledEvent) => void): Unsubscribe;
   /**
+  * The `WebSocket` implementation this client was constructed with (an
+  * explicit `options.WebSocket`, or the ambient global on platforms that have
+  * one) — `undefined` if neither is available. This is the seam a feature
+  * that opens its OWN socket outside the client's multiplexed connection
+  * (e.g. a voice-agent hook) should default to, instead of reaching for
+  * `globalThis.WebSocket` directly: on React Native the client wraps this
+  * constructor to inject the auth-headers factory's credential onto the
+  * upgrade request (`createLunoraClient`'s `withAuthWebSocket`), which a raw
+  * `new globalThis.WebSocket(url)` would silently bypass.
+  */
+  getWebSocketImpl(): typeof WebSocket | undefined;
+  /**
   * Read the current value for a {@link ClientQueryRef}. Returns
   * `ref.defaultValue` when no value has been explicitly set.
   */
@@ -1869,8 +1950,10 @@ declare class LunoraClient {
   * Subscribe to the live scheduled-jobs list over the SchedulerDO's admin
   * WebSocket. `onJobs` fires with the full list on connect and on every
   * change (schedule / cancel / alarm-fire). Reconnects with the client's
-  * configured backoff. Requires `wsToken` to be set to the admin token (the
-  * browser can't send an `Authorization` header on a WS). Returns an
+  * configured backoff. Requires `wsToken` to be set to an admin credential
+  * (the browser can't send an `Authorization` header on a WS) — the master
+  * token, or preferably a {@link WsTokenProvider} minting the ephemeral
+  * sub-token so the master credential stays out of the URL. Returns an
   * unsubscribe function that closes the socket and stops reconnecting.
   */
   subscribeScheduledJobs(onJobs: (jobs: ScheduleRecord[]) => void): Unsubscribe;
@@ -2370,6 +2453,25 @@ declare class LunoraClient {
     maxBuffer?: number;
     shardKey?: string;
   }): StreamIterable<ReturnOf<F>>;
+  /**
+  * Open a typed **HTTP-SSE route stream** (`httpRoute.&lt;verb>(path).stream()`).
+  * Distinct from {@link LunoraClient.stream}, which consumes the WS procedure
+  * stream (`kind: "stream"`): this one opens the route's own URL with `fetch`
+  * and parses the Server-Sent Events framing the route pump writes (`data:`
+  * chunks, a final `event: complete`, an `event: error` on throw).
+  *
+  * The reference comes from the generated `httpStreams.*` registry, so the
+  * yielded chunk type is the route handler's yielded type. Cancelling the
+  * returned iterable (or aborting `options.signal`) aborts the fetch, which
+  * the server handler observes via its `signal`. The client's bearer token
+  * (when set) rides as an `authorization` header.
+  * @experimental Reconnect/POST-body/wire-fidelity design questions are still open, so the shape may change.
+  */
+  httpStream<Ref extends HttpStreamRef>(route: Ref, args?: HttpStreamArgsOf<Ref>, options?: {
+    headers?: Record<string, string>;
+    maxBuffer?: number;
+    signal?: AbortSignal;
+  }): StreamIterable<HttpStreamChunkOf<Ref>>;
   close(): void;
   /**
   * Persist a mutation that can't go out on the wire right now (offline, or
@@ -2515,6 +2617,18 @@ declare class LunoraClient {
   */
   private resendShapeSubscriptions;
   private ensureSocket;
+  /**
+  * Resolve the {@link WsTokenProvider} and open the shard socket with the
+  * minted token. The connection is already in the `connecting` state, so the
+  * async gap is race-guarded: a client `close()`, a `setWsToken` bounce, or a
+  * competing connect that landed first all abandon this attempt. A provider
+  * failure fails the attempt through {@link handleDisconnect}, which arms the
+  * normal reconnect backoff — a broken mint endpoint degrades to retries, not
+  * a silent tokenless socket the admin gate would reject.
+  */
+  private openSocketWithProvidedToken;
+  /** Construct the shard socket and wire its lifecycle handlers. The connection must already be in the `connecting` state. */
+  private openSocket;
   private handleDisconnect;
   /**
   * Begin the keepalive heartbeat on an open connection. Each tick sends a
@@ -2719,4 +2833,4 @@ declare class LunoraClient {
   */
   private settleReplayBatchSlots;
 }
-export { StorageObject as $, ArgsOf as A, BookmarkStorage as B, CONFLICT_ERROR_CODE as C, DEFAULT_MAX_BUFFER as D, RowOp as E, FunctionReference as F, GlobalFacetResult as G, RpcEnvelope as H, RpcResponseBody as I, ScheduleRecord as J, SchedulerPoolStatus as K, LunoraClient as L, MutationCallOptions as M, SchedulerStatus as N, OfflineQueueOptions as O, Preloaded as P, QueryCacheAdapter as Q, ReturnOf as R, SubscriptionError as S, ServerMessage as T, User as U, ServerPokeEndMessage as V, ServerPokePartMessage as W, ServerPokeStartMessage as X, ShardTrafficEntry as Y, ShardTrafficResult as Z, StorageListPage as _, Unsubscribe as a, StreamHandle as a0, StreamIterable as a1, SubscriptionCallback as a2, SubscriptionRegistry as a3, SubscriptionState as a4, SyncWatermark as a5, WorkflowInstanceAction as a6, WorkflowInstanceDetail as a7, WorkflowInstancePage as a8, WorkflowInstanceStatus as a9, WorkflowInstanceSummary as aa, WorkflowStepDetail as ab, createClientQuery as ac, createLocalStore as ad, createStream as ae, getErrorCode as af, getRetryAfterMs as ag, isConflictError as ah, isForbiddenError as ai, isRateLimitedError as aj, isUnauthorizedError as ak, SubscriptionErrorCallback as b, PersistenceAdapter as c, ReconnectOptions as d, BatchSlot as e, CachedQuery as f, ClientMessage as g, ClientQueryRef as h, ClientShapeSubscribeMessage as i, ClientShapeUnsubscribeMessage as j, ConnectionStatus as k, FunctionArgumentDescriptor as l, FunctionDescriptor as m, GlobalFacetValue as n, GlobalFilterClause as o, GlobalTableInfo as p, GlobalTablePage as q, LunoraClientError as r, LunoraClientOptions as s, LunoraErrorCode as t, MutationSettledEvent as u, OptimisticLocalStore as v, OptimisticUpdate as w, OutboxMutation as x, OutboxSink as y, PersistedMutation as z };
+export { ServerPokePartMessage as $, ArgsOf as A, BookmarkStorage as B, CONFLICT_ERROR_CODE as C, DEFAULT_MAX_BUFFER as D, OptimisticUpdate as E, FunctionReference as F, GlobalFacetResult as G, HttpStreamRef as H, OutboxMutation as I, OutboxSink as J, PersistedMutation as K, LunoraClient as L, MutationCallOptions as M, RowOp as N, OfflineQueueOptions as O, Preloaded as P, QueryCacheAdapter as Q, ReturnOf as R, SubscriptionError as S, RpcEnvelope as T, User as U, RpcResponseBody as V, ScheduleRecord as W, SchedulerPoolStatus as X, SchedulerStatus as Y, ServerMessage as Z, ServerPokeEndMessage as _, Unsubscribe as a, ServerPokeStartMessage as a0, ShardTrafficEntry as a1, ShardTrafficResult as a2, StorageListPage as a3, StorageObject as a4, StreamHandle as a5, SubscriptionCallback as a6, SubscriptionRegistry as a7, SubscriptionState as a8, SyncWatermark as a9, WorkflowInstanceAction as aa, WorkflowInstanceDetail as ab, WorkflowInstancePage as ac, WorkflowInstanceStatus as ad, WorkflowInstanceSummary as ae, WorkflowStepDetail as af, WsTokenProvider as ag, createClientQuery as ah, createLocalStore as ai, createStream as aj, getErrorCode as ak, getRetryAfterMs as al, isConflictError as am, isForbiddenError as an, isRateLimitedError as ao, isUnauthorizedError as ap, SubscriptionErrorCallback as b, PersistenceAdapter as c, HttpStreamArgsOf as d, HttpStreamChunkOf as e, StreamIterable as f, ReconnectOptions as g, BatchSlot as h, CachedQuery as i, ClientMessage as j, ClientQueryRef as k, ClientShapeSubscribeMessage as l, ClientShapeUnsubscribeMessage as m, ConnectionStatus as n, FunctionArgumentDescriptor as o, FunctionDescriptor as p, GlobalFacetValue as q, GlobalFilterClause as r, GlobalTableInfo as s, GlobalTablePage as t, HttpStreamCallArgs as u, LunoraClientError as v, LunoraClientOptions as w, LunoraErrorCode as x, MutationSettledEvent as y, OptimisticLocalStore as z };

package/dist/packem_shared/{lunora-client.d-pw-9sLl0.d.ts → lunora-client.d-B8bdwHLr.d.ts}

@@ -117,6 +117,55 @@ interface FunctionReference<Kind extends FunctionKind = FunctionKind, Args = unk
 type ArgsOf<F> = F extends FunctionReference<infer _K, infer A, infer _R> ? A : never;
 /** Extract the return type from a {@link FunctionReference}. */
 type ReturnOf<F> = F extends FunctionReference<infer _K, infer _A, infer R> ? R : never;
+/**
+* Typed reference to an HTTP-SSE stream route (`httpRoute.&lt;verb>(path).stream()`)
+* emitted by `@lunora/codegen` as `httpStreams.&lt;namespace>.&lt;name>`.
+*
+* Distinct from {@link FunctionReference}: this is the **HTTP-SSE route stream**
+* (opened with `fetch` + `ReadableStream` against the route's own URL), not the
+* WS procedure stream (`kind: "stream"`). At runtime it carries the HTTP verb
+* and the route path; the phantom marker carries the chunk / searchParams /
+* params types so `httpStream` (and the framework hooks over it) infer the
+* chunk type end-to-end.
+* @experimental Reconnect/POST-body/wire-fidelity design questions are still open, so the shape may change.
+*/
+interface HttpStreamRef<Chunk = unknown, SearchParams = unknown, Params = unknown> {
+  /**
+  * Phantom marker carrying the `Chunk`/`SearchParams`/`Params` type
+  * parameters for inference. Never present at runtime; declared in a
+  * covariant (output) position so a concrete reference stays assignable to
+  * a widened one.
+  */
+  readonly __lunoraHttpStream?: {
+    chunk: Chunk;
+    params: Params;
+    searchParams: SearchParams;
+  };
+  /** HTTP verb the route binds to (uppercased), e.g. `"GET"`. */
+  readonly method: string;
+  /** The route path as declared, e.g. `/api/tokens/:id` — `:name` segments are filled from `params`. */
+  readonly path: string;
+}
+/**
+* The call-side args of an HTTP-SSE stream route: `:name` path params plus URL query params.
+* @experimental Part of the HTTP-SSE stream surface.
+*/
+interface HttpStreamCallArgs<SearchParams = unknown, Params = unknown> {
+  /** Values for the route path's `:name` segments. */
+  params?: Params;
+  /** URL query params, appended to the request URL (undefined entries are skipped). */
+  searchParams?: SearchParams;
+}
+/**
+* Extract the chunk type from a {@link HttpStreamRef}.
+* @experimental Part of the HTTP-SSE stream surface.
+*/
+type HttpStreamChunkOf<R> = R extends HttpStreamRef<infer Chunk, infer _S, infer _P> ? Chunk : never;
+/**
+* Extract the call-side args type from a {@link HttpStreamRef}.
+* @experimental Part of the HTTP-SSE stream surface.
+*/
+type HttpStreamArgsOf<R> = R extends HttpStreamRef<infer _C, infer S, infer P> ? HttpStreamCallArgs<S, P> : never;
 type Unsubscribe = () => void;
 /**
 * Serializable result of `preloadQuery`. Produced on the server during SSR,
@@ -309,6 +358,15 @@ interface QueryCacheAdapter {
   /** Remove one cached query by key. */
   remove: (key: string) => Promise<void>;
 }
+/**
+* Resolves the WS `?token=` credential fresh at every (re)connect — the channel
+* for short-lived tokens (e.g. the ephemeral admin sub-token the worker mints
+* at `POST /_lunora/admin/ws-token`) instead of a static secret in the URL.
+* May return the token synchronously or as a Promise; returning `undefined`
+* connects without a token. A thrown error / rejected Promise fails that
+* connect attempt, and the client retries with its normal reconnect backoff.
+*/
+type WsTokenProvider = () => Promise<string | undefined> | string | undefined;
 interface LunoraClientOptions {
   /**
   * Base path the worker mounts better-auth at, used by the client's
@@ -421,15 +479,21 @@ interface LunoraClientOptions {
   url: string;
   WebSocket?: typeof WebSocket;
   /**
-  * Token appended to the WebSocket URL as `?token=…`. The server matches it
-  * against `LUNORA_WS_BEARER` (to clear the upgrade gate) and/or
+  * Credential appended to the WebSocket URL as `?token=…`. The server matches
+  * it against `LUNORA_WS_BEARER` (to clear the upgrade gate) and/or
   * `LUNORA_ADMIN_TOKEN` (to authorize `__lunora_admin__:*` subscriptions —
-  * what the studio sets it to). Browsers can't set headers on the
-  * `WebSocket` constructor, so the query parameter is the only channel; it
-  * ends up in server logs and history, so prefer a short-lived rotating
-  * token in production.
+  * what the studio supplies). Browsers can't set headers on the `WebSocket`
+  * constructor, so the query parameter is the only channel; it ends up in
+  * server logs and history, so prefer a short-lived rotating token in
+  * production over a static secret.
+  *
+  * Pass a {@link WsTokenProvider} function to resolve the token fresh at
+  * every (re)connect — the channel for short-lived credentials such as the
+  * ephemeral admin sub-token minted by `POST /_lunora/admin/ws-token`: the
+  * provider re-mints on each reconnect, including the one following a `4001`
+  * token-expired drop, so a static master token never has to ride the URL.
   */
-  wsToken?: string;
+  wsToken?: string | WsTokenProvider;
   wsUrl?: string;
 }
 /** Wire envelope sent on `POST /_lunora/rpc`. */
@@ -997,9 +1061,10 @@ interface SubscriptionState {
   acked: boolean;
   readonly args: Record<string, unknown>;
   /**
-  * Stable-stringified `args`, computed once at subscribe time. Cached so the
-  * optimistic-update fan-out can compare against a mutation's args key without
-  * re-serializing every subscription's args on every mutation.
+  * Stable wire-key of `args` (`stableWireKey`), computed once at subscribe
+  * time. Cached so the optimistic-update fan-out can compare against a
+  * mutation's args key without re-serializing every subscription's args on
+  * every mutation.
   */
   readonly argsKey: string;
   readonly callbacks: Set<SubscriptionCallback>;
@@ -1068,11 +1133,13 @@ interface SubscriptionState {
 }
 /**
 * Active subscription registry. The client keys subscriptions by
-* `(functionPath, stableStringify(args), shardKey)` so duplicate calls share a
+* `(functionPath, stableWireKey(args), shardKey)` so duplicate calls share a
 * single server-side registration. Args are stably encoded (keys sorted at every
 * depth) so two structurally-equal arg records constructed with a different key
 * order (`{ a, b }` vs `{ b, a }`) collapse to the same key instead of leaking a
-* duplicate subscription.
+* duplicate subscription. Encoding the args' **wire form** keeps the key
+* byte-identical for pure-JSON args while giving wire-typed args (`bigint`,
+* `Date`, bytes, …) distinct stable tokens instead of a throw.
 */
 declare class SubscriptionRegistry {
   static key(functionPath: string, args: Record<string, unknown>, shardKey?: string): string;
@@ -1539,10 +1606,12 @@ declare class LunoraClient {
   * Replace the token appended to WS upgrade URLs as `?token=…` and close
   * every open shard socket so the reconnect picks up the new value. Call
   * this whenever the user's WS credential changes (rotating the admin token
-  * in the studio, switching workspaces, etc.). Bearer tokens for HTTP
-  * RPC are independent — see {@link setAuthToken}.
+  * in the studio, switching workspaces, etc.). Accepts a static string or a
+  * {@link WsTokenProvider} resolved fresh at every (re)connect — the channel
+  * for short-lived credentials like the minted ephemeral admin sub-token.
+  * Bearer tokens for HTTP RPC are independent — see {@link setAuthToken}.
   */
-  setWsToken(token: string | undefined): void;
+  setWsToken(token: string | undefined | WsTokenProvider): void;
   /**
   * Register (or clear, with `undefined`) the app context sent in the `connect`
   * envelope for a shard's socket, overriding the client-wide
@@ -1655,6 +1724,18 @@ declare class LunoraClient {
   */
   onMutationSettled(listener: (event: MutationSettledEvent) => void): Unsubscribe;
   /**
+  * The `WebSocket` implementation this client was constructed with (an
+  * explicit `options.WebSocket`, or the ambient global on platforms that have
+  * one) — `undefined` if neither is available. This is the seam a feature
+  * that opens its OWN socket outside the client's multiplexed connection
+  * (e.g. a voice-agent hook) should default to, instead of reaching for
+  * `globalThis.WebSocket` directly: on React Native the client wraps this
+  * constructor to inject the auth-headers factory's credential onto the
+  * upgrade request (`createLunoraClient`'s `withAuthWebSocket`), which a raw
+  * `new globalThis.WebSocket(url)` would silently bypass.
+  */
+  getWebSocketImpl(): typeof WebSocket | undefined;
+  /**
   * Read the current value for a {@link ClientQueryRef}. Returns
   * `ref.defaultValue` when no value has been explicitly set.
   */
@@ -1869,8 +1950,10 @@ declare class LunoraClient {
   * Subscribe to the live scheduled-jobs list over the SchedulerDO's admin
   * WebSocket. `onJobs` fires with the full list on connect and on every
   * change (schedule / cancel / alarm-fire). Reconnects with the client's
-  * configured backoff. Requires `wsToken` to be set to the admin token (the
-  * browser can't send an `Authorization` header on a WS). Returns an
+  * configured backoff. Requires `wsToken` to be set to an admin credential
+  * (the browser can't send an `Authorization` header on a WS) — the master
+  * token, or preferably a {@link WsTokenProvider} minting the ephemeral
+  * sub-token so the master credential stays out of the URL. Returns an
   * unsubscribe function that closes the socket and stops reconnecting.
   */
   subscribeScheduledJobs(onJobs: (jobs: ScheduleRecord[]) => void): Unsubscribe;
@@ -2370,6 +2453,25 @@ declare class LunoraClient {
     maxBuffer?: number;
     shardKey?: string;
   }): StreamIterable<ReturnOf<F>>;
+  /**
+  * Open a typed **HTTP-SSE route stream** (`httpRoute.&lt;verb>(path).stream()`).
+  * Distinct from {@link LunoraClient.stream}, which consumes the WS procedure
+  * stream (`kind: "stream"`): this one opens the route's own URL with `fetch`
+  * and parses the Server-Sent Events framing the route pump writes (`data:`
+  * chunks, a final `event: complete`, an `event: error` on throw).
+  *
+  * The reference comes from the generated `httpStreams.*` registry, so the
+  * yielded chunk type is the route handler's yielded type. Cancelling the
+  * returned iterable (or aborting `options.signal`) aborts the fetch, which
+  * the server handler observes via its `signal`. The client's bearer token
+  * (when set) rides as an `authorization` header.
+  * @experimental Reconnect/POST-body/wire-fidelity design questions are still open, so the shape may change.
+  */
+  httpStream<Ref extends HttpStreamRef>(route: Ref, args?: HttpStreamArgsOf<Ref>, options?: {
+    headers?: Record<string, string>;
+    maxBuffer?: number;
+    signal?: AbortSignal;
+  }): StreamIterable<HttpStreamChunkOf<Ref>>;
   close(): void;
   /**
   * Persist a mutation that can't go out on the wire right now (offline, or
@@ -2515,6 +2617,18 @@ declare class LunoraClient {
   */
   private resendShapeSubscriptions;
   private ensureSocket;
+  /**
+  * Resolve the {@link WsTokenProvider} and open the shard socket with the
+  * minted token. The connection is already in the `connecting` state, so the
+  * async gap is race-guarded: a client `close()`, a `setWsToken` bounce, or a
+  * competing connect that landed first all abandon this attempt. A provider
+  * failure fails the attempt through {@link handleDisconnect}, which arms the
+  * normal reconnect backoff — a broken mint endpoint degrades to retries, not
+  * a silent tokenless socket the admin gate would reject.
+  */
+  private openSocketWithProvidedToken;
+  /** Construct the shard socket and wire its lifecycle handlers. The connection must already be in the `connecting` state. */
+  private openSocket;
   private handleDisconnect;
   /**
   * Begin the keepalive heartbeat on an open connection. Each tick sends a
@@ -2719,4 +2833,4 @@ declare class LunoraClient {
   */
   private settleReplayBatchSlots;
 }
-export { StorageObject as $, ArgsOf as A, BookmarkStorage as B, CONFLICT_ERROR_CODE as C, DEFAULT_MAX_BUFFER as D, RowOp as E, FunctionReference as F, GlobalFacetResult as G, RpcEnvelope as H, RpcResponseBody as I, ScheduleRecord as J, SchedulerPoolStatus as K, LunoraClient as L, MutationCallOptions as M, SchedulerStatus as N, OfflineQueueOptions as O, Preloaded as P, QueryCacheAdapter as Q, ReturnOf as R, SubscriptionError as S, ServerMessage as T, User as U, ServerPokeEndMessage as V, ServerPokePartMessage as W, ServerPokeStartMessage as X, ShardTrafficEntry as Y, ShardTrafficResult as Z, StorageListPage as _, Unsubscribe as a, StreamHandle as a0, StreamIterable as a1, SubscriptionCallback as a2, SubscriptionRegistry as a3, SubscriptionState as a4, SyncWatermark as a5, WorkflowInstanceAction as a6, WorkflowInstanceDetail as a7, WorkflowInstancePage as a8, WorkflowInstanceStatus as a9, WorkflowInstanceSummary as aa, WorkflowStepDetail as ab, createClientQuery as ac, createLocalStore as ad, createStream as ae, getErrorCode as af, getRetryAfterMs as ag, isConflictError as ah, isForbiddenError as ai, isRateLimitedError as aj, isUnauthorizedError as ak, SubscriptionErrorCallback as b, PersistenceAdapter as c, ReconnectOptions as d, BatchSlot as e, CachedQuery as f, ClientMessage as g, ClientQueryRef as h, ClientShapeSubscribeMessage as i, ClientShapeUnsubscribeMessage as j, ConnectionStatus as k, FunctionArgumentDescriptor as l, FunctionDescriptor as m, GlobalFacetValue as n, GlobalFilterClause as o, GlobalTableInfo as p, GlobalTablePage as q, LunoraClientError as r, LunoraClientOptions as s, LunoraErrorCode as t, MutationSettledEvent as u, OptimisticLocalStore as v, OptimisticUpdate as w, OutboxMutation as x, OutboxSink as y, PersistedMutation as z };
+export { ServerPokePartMessage as $, ArgsOf as A, BookmarkStorage as B, CONFLICT_ERROR_CODE as C, DEFAULT_MAX_BUFFER as D, OptimisticUpdate as E, FunctionReference as F, GlobalFacetResult as G, HttpStreamRef as H, OutboxMutation as I, OutboxSink as J, PersistedMutation as K, LunoraClient as L, MutationCallOptions as M, RowOp as N, OfflineQueueOptions as O, Preloaded as P, QueryCacheAdapter as Q, ReturnOf as R, SubscriptionError as S, RpcEnvelope as T, User as U, RpcResponseBody as V, ScheduleRecord as W, SchedulerPoolStatus as X, SchedulerStatus as Y, ServerMessage as Z, ServerPokeEndMessage as _, Unsubscribe as a, ServerPokeStartMessage as a0, ShardTrafficEntry as a1, ShardTrafficResult as a2, StorageListPage as a3, StorageObject as a4, StreamHandle as a5, SubscriptionCallback as a6, SubscriptionRegistry as a7, SubscriptionState as a8, SyncWatermark as a9, WorkflowInstanceAction as aa, WorkflowInstanceDetail as ab, WorkflowInstancePage as ac, WorkflowInstanceStatus as ad, WorkflowInstanceSummary as ae, WorkflowStepDetail as af, WsTokenProvider as ag, createClientQuery as ah, createLocalStore as ai, createStream as aj, getErrorCode as ak, getRetryAfterMs as al, isConflictError as am, isForbiddenError as an, isRateLimitedError as ao, isUnauthorizedError as ap, SubscriptionErrorCallback as b, PersistenceAdapter as c, HttpStreamArgsOf as d, HttpStreamChunkOf as e, StreamIterable as f, ReconnectOptions as g, BatchSlot as h, CachedQuery as i, ClientMessage as j, ClientQueryRef as k, ClientShapeSubscribeMessage as l, ClientShapeUnsubscribeMessage as m, ConnectionStatus as n, FunctionArgumentDescriptor as o, FunctionDescriptor as p, GlobalFacetValue as q, GlobalFilterClause as r, GlobalTableInfo as s, GlobalTablePage as t, HttpStreamCallArgs as u, LunoraClientError as v, LunoraClientOptions as w, LunoraErrorCode as x, MutationSettledEvent as y, OptimisticLocalStore as z };