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

package/dist/packem_shared/{LunoraClient-Clb118SU.mjs → LunoraClient-BBCQjjbl.mjs}

@@ -1,16 +1,17 @@
 import { LunoraError } from '@lunora/errors';
-import { s as stableStringify } from './stable-key-wv6eP48B.mjs';
+import { s as stableWireKey, d as decodeWire, e as encodeWire } from './wire-key-Djie6aaR.mjs';
 import createInMemoryBookmarkStorage from './createInMemoryBookmarkStorage-BoN7a7TH.mjs';
 import { ClientQueryStore } from './createClientQuery-CQ51bWAE.mjs';
 import { TabCoordinator } from './TabCoordinator-BwRR8H06.mjs';
 import { isMutationDelta, applyDelta } from './applyDelta-CRKZ1PBt.mjs';
-import { f as foldOptimistic, a as applyOptimisticLayer, d as dropConfirmedLayers, n as notifySubscription, c as createLocalStore } from './local-store-DtcIW4c0.mjs';
+import { httpStream } from './httpStream-BJU-aflc.mjs';
+import { f as foldOptimistic, a as applyOptimisticLayer, d as dropConfirmedLayers, n as notifySubscription, c as createLocalStore } from './local-store-DIq-UWfD.mjs';
 import { O as OfflineQueue, n as nextId, i as isStaleVersion, r as reportPersistenceError } from './offline-queue-CF4_Co5k.mjs';
 import { resolvePersistenceAdapter } from './createInMemoryPersistence-DZ2VHWgm.mjs';
 import { resolveQueryCacheAdapter, queryCacheKey } from './createInMemoryQueryCache-DiaGZkA2.mjs';
 import { createReconnect } from './createReconnect-Di_-oHH7.mjs';
 import { createStream } from './DEFAULT_MAX_BUFFER-7hFnzNk9.mjs';
-import { SubscriptionRegistry } from './SubscriptionRegistry-D4jfIzZu.mjs';
+import { SubscriptionRegistry } from './SubscriptionRegistry-CxS_Inha.mjs';
 
 const MAX_BATCH_ENTRIES = 500;
 
@@ -24,230 +25,6 @@ const evictOldestEntry = (map, capacity) => {
   }
 };
 
-const toBase64 = (bytes) => {
-  let binary = "";
-  const chunk = 32768;
-  for (let index = 0; index < bytes.length; index += chunk) {
-    binary += String.fromCharCode(...bytes.subarray(index, index + chunk));
-  }
-  return btoa(binary);
-};
-const fromBase64 = (base64) => {
-  const binary = atob(base64);
-  const bytes = new Uint8Array(binary.length);
-  for (let index = 0; index < binary.length; index += 1) {
-    bytes[index] = binary.codePointAt(index) ?? 0;
-  }
-  return bytes;
-};
-
-const TAG = "$lunora.wire$";
-const MAX_DEPTH = 64;
-const MAX_BIGINT_DIGITS = 1024;
-const UNSAFE_KEY = "__proto__";
-const TYPED_ARRAY_CTORS = {
-  BigInt64Array,
-  BigUint64Array,
-  Float32Array,
-  Float64Array,
-  Int8Array,
-  Int16Array,
-  Int32Array,
-  Uint8Array,
-  Uint8ClampedArray,
-  Uint16Array,
-  Uint32Array
-};
-const ERROR_CTORS = {
-  Error,
-  EvalError,
-  RangeError,
-  ReferenceError,
-  SyntaxError,
-  TypeError,
-  URIError
-};
-const encodeWire = (value, depth = 0) => {
-  if (depth > MAX_DEPTH) {
-    throw new RangeError(`wire-codec: value nesting exceeds the ${MAX_DEPTH}-level limit`);
-  }
-  if (value === void 0) {
-    return [TAG, "undefined"];
-  }
-  if (value === null) {
-    return null;
-  }
-  const kind = typeof value;
-  if (kind === "bigint") {
-    return [TAG, "bigint", value.toString()];
-  }
-  if (kind === "number") {
-    const numeric = value;
-    if (Number.isNaN(numeric)) {
-      return [TAG, "nan"];
-    }
-    if (numeric === Infinity) {
-      return [TAG, "inf"];
-    }
-    if (numeric === -Infinity) {
-      return [TAG, "-inf"];
-    }
-    return numeric;
-  }
-  if (kind !== "object") {
-    return value;
-  }
-  if (value instanceof Date) {
-    return [TAG, "date", encodeWire(value.getTime(), depth + 1)];
-  }
-  if (value instanceof Error) {
-    const error = value;
-    const properties = {};
-    for (const key of Object.keys(error)) {
-      if (error[key] !== void 0) {
-        properties[key] = encodeWire(error[key], depth + 1);
-      }
-    }
-    const encodedError = [TAG, "error", error.name, error.message, properties];
-    if (error.cause !== void 0) {
-      encodedError.push(encodeWire(error.cause, depth + 1));
-    }
-    return encodedError;
-  }
-  if (value instanceof URL) {
-    return [TAG, "url", value.href];
-  }
-  if (value instanceof Map) {
-    return [TAG, "map", [...value.entries()].map(([k, v]) => [encodeWire(k, depth + 1), encodeWire(v, depth + 1)])];
-  }
-  if (value instanceof Set) {
-    return [TAG, "set", [...value].map((item) => encodeWire(item, depth + 1))];
-  }
-  if (value instanceof ArrayBuffer) {
-    return [TAG, "bytes", toBase64(new Uint8Array(value)), "ArrayBuffer"];
-  }
-  if (ArrayBuffer.isView(value)) {
-    const view = value;
-    const ctorName = view.constructor.name;
-    const bytes = new Uint8Array(view.buffer, view.byteOffset, view.byteLength);
-    return ctorName === "Uint8Array" ? [TAG, "bytes", toBase64(bytes)] : [TAG, "bytes", toBase64(bytes), ctorName];
-  }
-  if (Array.isArray(value)) {
-    const encoded = value.map((item) => encodeWire(item, depth + 1));
-    return encoded.length > 0 && encoded[0] === TAG ? [TAG, "arr", encoded] : encoded;
-  }
-  const proto = Object.getPrototypeOf(value);
-  if (proto !== null && proto !== Object.prototype) {
-    const name = value.constructor?.name ?? "value";
-    throw new TypeError(
-      `wire-codec: cannot encode a ${name} over the Lunora wire — only plain objects, arrays, and the supported built-ins (Date, Error, URL, Map, Set, ArrayBuffer/typed arrays, bigint) round-trip`
-    );
-  }
-  const source = value;
-  const result = {};
-  for (const key of Object.keys(source)) {
-    const field = source[key];
-    if (field !== void 0) {
-      result[key] = encodeWire(field, depth + 1);
-    }
-  }
-  return result;
-};
-const decodeWire = (value, depth = 0) => {
-  if (depth > MAX_DEPTH) {
-    throw new RangeError(`wire-codec: value nesting exceeds the ${MAX_DEPTH}-level limit`);
-  }
-  if (value === null || typeof value !== "object") {
-    return value;
-  }
-  if (Array.isArray(value)) {
-    if (value[0] === TAG) {
-      const tag = value[1];
-      switch (tag) {
-        case "-inf": {
-          return -Infinity;
-        }
-        case "arr": {
-          return value[2].map((item) => decodeWire(item, depth + 1));
-        }
-        case "bigint": {
-          const raw = value[2];
-          if (typeof raw !== "string" || raw.length > MAX_BIGINT_DIGITS || !/^-?\d+$/.test(raw)) {
-            throw new RangeError(`wire-codec: invalid or over-long bigint (max ${MAX_BIGINT_DIGITS} digits)`);
-          }
-          return BigInt(raw);
-        }
-        case "date": {
-          return new Date(decodeWire(value[2], depth + 1));
-        }
-        case "map": {
-          return new Map(value[2].map(([k, v]) => [decodeWire(k, depth + 1), decodeWire(v, depth + 1)]));
-        }
-        case "set": {
-          return new Set(value[2].map((item) => decodeWire(item, depth + 1)));
-        }
-        case "url": {
-          return new URL(value[2]);
-        }
-        case "error": {
-          const name = value[2];
-          const message = value[3];
-          const Ctor = (Object.hasOwn(ERROR_CTORS, name) ? ERROR_CTORS[name] : void 0) ?? Error;
-          const error = new Ctor(message);
-          if (error.name !== name) {
-            Object.defineProperty(error, "name", { configurable: true, value: name, writable: true });
-          }
-          const props = decodeWire(value[4], depth + 1);
-          for (const key of Object.keys(props)) {
-            if (key === UNSAFE_KEY) {
-              Object.defineProperty(error, key, { configurable: true, enumerable: true, value: props[key], writable: true });
-            } else {
-              error[key] = props[key];
-            }
-          }
-          if (value.length > 5) {
-            Object.defineProperty(error, "cause", { configurable: true, value: decodeWire(value[5], depth + 1), writable: true });
-          }
-          return error;
-        }
-        case "bytes": {
-          const bytes = fromBase64(value[2]);
-          const ctorName = value[3] ?? "Uint8Array";
-          if (ctorName === "ArrayBuffer") {
-            return bytes.buffer.byteLength === bytes.byteLength ? bytes.buffer : bytes.slice().buffer;
-          }
-          const Ctor = Object.hasOwn(TYPED_ARRAY_CTORS, ctorName) ? TYPED_ARRAY_CTORS[ctorName] : void 0;
-          return Ctor ? new Ctor(bytes.slice().buffer) : bytes;
-        }
-        case "inf": {
-          return Infinity;
-        }
-        case "nan": {
-          return Number.NaN;
-        }
-        case "undefined": {
-          return void 0;
-        }
-        default: {
-          return value.map((item) => decodeWire(item, depth + 1));
-        }
-      }
-    }
-    return value.map((item) => decodeWire(item, depth + 1));
-  }
-  const source = value;
-  const result = {};
-  for (const key of Object.keys(source)) {
-    const decoded = decodeWire(source[key], depth + 1);
-    if (key === UNSAFE_KEY) {
-      Object.defineProperty(result, key, { configurable: true, enumerable: true, value: decoded, writable: true });
-    } else {
-      result[key] = decoded;
-    }
-  }
-  return result;
-};
-
 class Listeners {
   listeners = /* @__PURE__ */ new Set();
   add(listener) {
@@ -892,8 +669,10 @@ 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) {
     if (this.wsToken === token) {
@@ -1162,7 +941,7 @@ class LunoraClient {
    */
   snapshotPrecondition(functionRef, args, shardKey) {
     const snapshot = this.peekActiveQueryValue(functionRef.__lunoraRef, args, shardKey);
-    const snapshotKey = snapshot === void 0 ? void 0 : stableStringify(snapshot);
+    const snapshotKey = snapshot === void 0 ? void 0 : stableWireKey(snapshot);
     return () => {
       const current = this.peekActiveQueryValue(functionRef.__lunoraRef, args, shardKey);
       if (snapshotKey === void 0 && current === void 0) {
@@ -1171,7 +950,7 @@ class LunoraClient {
       if (snapshotKey === void 0 || current === void 0) {
         return false;
       }
-      return stableStringify(current) === snapshotKey;
+      return stableWireKey(current) === snapshotKey;
     };
   }
   // --- Hydration helpers --------------------------------------------------
@@ -1213,7 +992,7 @@ class LunoraClient {
     if (!this.readyResolved) {
       return void 0;
     }
-    const argsKey = stableStringify(args);
+    const argsKey = stableWireKey(args);
     const key = queryCacheKey(functionPath, argsKey, shardKey);
     const entry = this.hydratedQueryCache.get(key);
     if (entry === void 0) {
@@ -1534,8 +1313,10 @@ 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) {
@@ -1550,11 +1331,11 @@ class LunoraClient {
     let socket;
     let timer;
     let closed = false;
-    const connect = () => {
+    const openWith = (token) => {
       if (closed || this.WebSocketImpl === void 0) {
         return;
       }
-      const url = this.wsToken === void 0 ? base : `${base}?token=${encodeURIComponent(this.wsToken)}`;
+      const url = token === void 0 ? base : `${base}?token=${encodeURIComponent(token)}`;
       socket = new this.WebSocketImpl(url);
       socket.addEventListener("open", () => {
         reconnect.reset();
@@ -1577,6 +1358,29 @@ class LunoraClient {
       socket.addEventListener("error", () => {
       });
     };
+    const connectWithProvider = async (provider) => {
+      let token;
+      try {
+        token = await provider();
+      } catch {
+        if (!closed) {
+          timer = setTimeout(connect, reconnect.next());
+        }
+        return;
+      }
+      openWith(token);
+    };
+    const connect = () => {
+      if (closed || this.WebSocketImpl === void 0) {
+        return;
+      }
+      const { wsToken } = this;
+      if (typeof wsToken === "function") {
+        connectWithProvider(wsToken).catch(() => void 0);
+        return;
+      }
+      openWith(wsToken);
+    };
     connect();
     return () => {
       closed = true;
@@ -2143,7 +1947,7 @@ class LunoraClient {
     if (!state) {
       this.nextSubId += 1;
       const id = `sub_${this.nextSubId.toString()}`;
-      const argsKey = stableStringify(argsRecord);
+      const argsKey = stableWireKey(argsRecord);
       const cached = this.takeHydratedCache(function_.__lunoraRef, argsKey, options.shardKey);
       state = {
         acked: false,
@@ -2223,7 +2027,10 @@ class LunoraClient {
       name: shape.name,
       onCheckpoint: options.onCheckpoint,
       rows: /* @__PURE__ */ new Map(),
-      shardKey: options.shardKey
+      shardKey: options.shardKey,
+      // Encode ONCE, here, so an unsupported arg value throws at this call
+      // site instead of inside a reconnect's open handler.
+      wireArgs: shape.args === void 0 ? void 0 : encodeCallArgs(shape.args, `shape args for '${shape.name}'`)
     };
     this.shapeSubscriptions.set(id, state);
     this.ensureSocket(options.shardKey);
@@ -2307,6 +2114,39 @@ class LunoraClient {
     }
     return iterable;
   }
+  /**
+   * 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(route, args, options = {}) {
+    if (this.closed) {
+      throw new LunoraError("CLIENT_CLOSED", "LunoraClient is closed");
+    }
+    if (!this.fetchImpl) {
+      throw new LunoraError("INTERNAL", "LunoraClient: no `fetch` implementation available");
+    }
+    const headers = {
+      ...this.authToken ? { authorization: `Bearer ${this.authToken}` } : {},
+      ...options.headers
+    };
+    return httpStream(route, args, {
+      baseUrl: this.url,
+      fetch: this.fetchImpl,
+      headers,
+      maxBuffer: options.maxBuffer,
+      signal: options.signal
+    });
+  }
   close() {
     this.closed = true;
     this.outboxLeaderRelease?.();
@@ -2666,13 +2506,13 @@ class LunoraClient {
     }
     return conn;
   }
-  wsUrlFor(shardKey) {
+  wsUrlFor(shardKey, token) {
     const params = [];
     if (shardKey !== void 0) {
       params.push(`shard=${encodeURIComponent(shardKey)}`);
     }
-    if (this.wsToken !== void 0) {
-      params.push(`token=${encodeURIComponent(this.wsToken)}`);
+    if (token !== void 0) {
+      params.push(`token=${encodeURIComponent(token)}`);
     }
     if (params.length === 0) {
       return this.wsUrl;
@@ -2869,7 +2709,40 @@ class LunoraClient {
     }
     conn.wsState = "connecting";
     this.emitConnectionStatus();
-    const socket = new this.WebSocketImpl(this.wsUrlFor(shardKey));
+    if (typeof this.wsToken === "function") {
+      this.openSocketWithProvidedToken(conn, shardKey, this.wsToken).catch(() => void 0);
+      return;
+    }
+    this.openSocket(conn, shardKey, this.wsToken);
+  }
+  /**
+   * 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.
+   */
+  async openSocketWithProvidedToken(conn, shardKey, provider) {
+    let token;
+    try {
+      token = await provider();
+    } catch {
+      this.handleDisconnect(conn);
+      return;
+    }
+    if (this.closed || this.WebSocketImpl === void 0 || conn.wsState !== "connecting" || conn.socket !== void 0) {
+      return;
+    }
+    this.openSocket(conn, shardKey, token);
+  }
+  /** Construct the shard socket and wire its lifecycle handlers. The connection must already be in the `connecting` state. */
+  openSocket(conn, shardKey, token) {
+    if (this.WebSocketImpl === void 0) {
+      return;
+    }
+    const socket = new this.WebSocketImpl(this.wsUrlFor(shardKey, token));
     conn.socket = socket;
     if (this.connectTimeoutMs > 0) {
       conn.connectTimer = setTimeout(() => {
@@ -3031,7 +2904,12 @@ class LunoraClient {
       // sub (a hydrated read or an earlier frame), so the server can
       // resume instead of re-snapshotting. Omitted on a cold sub.
       query: {
-        args: state.args,
+        // Wire-encode so a `bigint`/`Date`/bytes arg survives the frame's
+        // `JSON.stringify` (the shard `decodeWire`s at its subscribe entry
+        // point). Identity for pure-JSON args. Cannot throw here: the
+        // registry key (`stableWireKey`) already encoded these args at
+        // subscribe() time, so reconnect resends stay safe.
+        args: encodeWire(state.args),
         functionPath: state.fn.__lunoraRef,
         table,
         ...state.serverCursor === void 0 ? {} : { sinceSeq: state.serverCursor },
@@ -3047,7 +2925,11 @@ class LunoraClient {
     }
     sendOn(conn, {
       id: state.id,
-      shape: { name: state.name, ...state.args === void 0 ? {} : { args: state.args } },
+      // `wireArgs` is the pre-encoded form of `args` (computed at
+      // `subscribeShape` time) so a `bigint`/`Date`/bytes arg survives the
+      // frame's `JSON.stringify`; the shard `decodeWire`s it at its
+      // `shape_subscribe` entry point. Identity for pure-JSON args.
+      shape: { name: state.name, ...state.wireArgs === void 0 ? {} : { args: state.wireArgs } },
       type: "shape_subscribe",
       // Resume from the last applied checkpoint when we hold one; a cold
       // subscribe omits it and the server seeds the full membership.

package/dist/packem_shared/{SubscriptionRegistry-D4jfIzZu.mjs → SubscriptionRegistry-CxS_Inha.mjs}

@@ -1,8 +1,8 @@
-import { s as stableStringify } from './stable-key-wv6eP48B.mjs';
+import { s as stableWireKey } from './wire-key-Djie6aaR.mjs';
 
 class SubscriptionRegistry {
   static key(functionPath, args, shardKey) {
-    return `${functionPath}::${stableStringify(args)}::${shardKey ?? ""}`;
+    return `${functionPath}::${stableWireKey(args)}::${shardKey ?? ""}`;
   }
   byKey = /* @__PURE__ */ new Map();
   byId = /* @__PURE__ */ new Map();

package/dist/packem_shared/createLocalStore-BtqUmOQA.mjs

@@ -0,0 +1,2 @@
+export { c as createLocalStore } from './local-store-DIq-UWfD.mjs';
+import './SubscriptionRegistry-CxS_Inha.mjs';

package/dist/packem_shared/{createServerClient-Dxemst5C.mjs → createServerClient-CTTAmvMx.mjs}

@@ -1,4 +1,4 @@
-import { LunoraClient } from './LunoraClient-Clb118SU.mjs';
+import { LunoraClient } from './LunoraClient-BBCQjjbl.mjs';
 
 const createServerClient = (options) => {
   const client = new LunoraClient({ fetch: options.fetch, url: options.url });

package/dist/packem_shared/{createSnapshotPrecondition-CBwnVz6r.mjs → createSnapshotPrecondition-CxQ1T4ZP.mjs}

@@ -1,8 +1,8 @@
-import { s as stableStringify } from './stable-key-wv6eP48B.mjs';
+import { s as stableWireKey } from './wire-key-Djie6aaR.mjs';
 
 const createSnapshotPrecondition = (client, functionRef, args, shardKey) => {
   const snapshot = client.peekActiveQueryValue(functionRef.__lunoraRef, args, shardKey);
-  const snapshotKey = snapshot === void 0 ? void 0 : stableStringify(snapshot);
+  const snapshotKey = snapshot === void 0 ? void 0 : stableWireKey(snapshot);
   return () => {
     const current = client.peekActiveQueryValue(functionRef.__lunoraRef, args, shardKey);
     if (snapshotKey === void 0 && current === void 0) {
@@ -11,7 +11,7 @@ const createSnapshotPrecondition = (client, functionRef, args, shardKey) => {
     if (snapshotKey === void 0 || current === void 0) {
       return false;
     }
-    return stableStringify(current) === snapshotKey;
+    return stableWireKey(current) === snapshotKey;
   };
 };
 

package/dist/packem_shared/httpStream-BJU-aflc.mjs

@@ -0,0 +1,159 @@
+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();
+  if (options.signal) {
+    if (options.signal.aborted) {
+      ac.abort();
+    } else {
+      options.signal.addEventListener(
+        "abort",
+        () => {
+          ac.abort();
+        },
+        { once: true }
+      );
+    }
+  }
+  const { handle, iterable } = createStream({
+    maxBuffer: options.maxBuffer,
+    onCancel: () => {
+      ac.abort();
+    }
+  });
+  (async () => {
+    const response = await fetchImpl(url, {
+      headers: { accept: "text/event-stream", ...options.headers },
+      method: route.method,
+      signal: ac.signal
+    });
+    if (!response.ok) {
+      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);
+  })().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 };