@lunora/client 0.0.0 → 1.0.0-alpha.2

package/dist/packem_shared/preload.d-BoDmFqSG.d.ts

@@ -0,0 +1,20 @@
+import { F as FunctionReference, L as LunoraClient, A as ArgsOf, R as ReturnOf, P as Preloaded } from "./lunora-client.d-DGvyuJ_p.js";
+/**
+* Run a query once on the server (during SSR) and capture its result in a
+* serializable {@link Preloaded} token. Embed the token in the rendered HTML and
+* pass it to `usePreloadedQuery` on the client: the first client render shows
+* the server value with no loading flash, then a live subscription takes over.
+*
+* The query is executed through the supplied {@link LunoraClient} over the same
+* HTTP RPC path the browser uses, so the SSR client only needs a `fetch`
+* implementation that can reach the worker — no in-process Durable Object access.
+*/
+declare const preloadQuery: <F extends FunctionReference>(client: LunoraClient, function_: F, args: ArgsOf<F>, options?: {
+  shardKey?: string;
+}) => Promise<Preloaded<ReturnOf<F>>>;
+/**
+* Read the captured value out of a {@link Preloaded} token without subscribing.
+* Useful on the server (or in tests) when you only need the data, not a live feed.
+*/
+declare const preloadedQueryResult: <T>(preloaded: Preloaded<T>) => T;
+export { preloadedQueryResult as a, preloadQuery as p };

package/dist/packem_shared/preload.d-dSaRMuhL.d.mts

@@ -0,0 +1,20 @@
+import { F as FunctionReference, L as LunoraClient, A as ArgsOf, R as ReturnOf, P as Preloaded } from "./lunora-client.d-DGvyuJ_p.mjs";
+/**
+* Run a query once on the server (during SSR) and capture its result in a
+* serializable {@link Preloaded} token. Embed the token in the rendered HTML and
+* pass it to `usePreloadedQuery` on the client: the first client render shows
+* the server value with no loading flash, then a live subscription takes over.
+*
+* The query is executed through the supplied {@link LunoraClient} over the same
+* HTTP RPC path the browser uses, so the SSR client only needs a `fetch`
+* implementation that can reach the worker — no in-process Durable Object access.
+*/
+declare const preloadQuery: <F extends FunctionReference>(client: LunoraClient, function_: F, args: ArgsOf<F>, options?: {
+  shardKey?: string;
+}) => Promise<Preloaded<ReturnOf<F>>>;
+/**
+* Read the captured value out of a {@link Preloaded} token without subscribing.
+* Useful on the server (or in tests) when you only need the data, not a live feed.
+*/
+declare const preloadedQueryResult: <T>(preloaded: Preloaded<T>) => T;
+export { preloadedQueryResult as a, preloadQuery as p };

package/dist/packem_shared/preloadQuery-lobFkD2Z.mjs

@@ -0,0 +1,13 @@
+const preloadQuery = async (client, function_, args, options = {}) => {
+  const value = await client.query(function_, args, options);
+  return {
+    __lunoraPreloaded: true,
+    args: args ?? {},
+    functionPath: function_.__lunoraRef,
+    shardKey: options.shardKey,
+    value
+  };
+};
+const preloadedQueryResult = (preloaded) => preloaded.value;
+
+export { preloadQuery, preloadedQueryResult };

package/dist/pagination/index.d.mts

@@ -0,0 +1,82 @@
+/**
+* `@lunora/client/pagination` — the framework-agnostic pagination state machine
+* shared by every Lunora UI adapter (React, Vue, Svelte, Solid).
+*
+* Owns cursor tracking, page-size rebalancing (split/join), `initialPages`,
+* `rebalance`, and the shared types (`Page`, `PaginationResult`,
+* `PaginationStatus`, `PaginatedCoreResult`). Nothing here imports a UI
+* framework — each adapter wires the pure functions into its own reactive
+* primitives.
+*/
+/** Grow factor: a bounded page is split when it exceeds this multiple of its target size. */
+declare const SPLIT_FACTOR = 2;
+/** Shrink factor: a bounded page with a neighbour is joined when it falls below this multiple of its target size. */
+declare const JOIN_FACTOR = .5;
+/** A loaded page: a fixed `(lower, upper]` range plus the size it targets. */
+interface Page {
+  lower: null | string;
+  numItems: number;
+  upper: null | string;
+}
+/** One page returned by a paginated query — the shape `.paginate()` yields. */
+interface PaginationResult<T = unknown> {
+  continueCursor: null | string;
+  isDone: boolean;
+  page: T[];
+  /**
+  * Reactive-pagination only: the midpoint cursor of a bounded
+  * `(cursor, endCursor]` page, used to split an over-grown page into two
+  * adjacent ranges. Absent on legacy (open-ended) pages.
+  */
+  splitCursor?: null | string;
+}
+/**
+* Lifecycle of a `usePaginatedQuery` feed.
+*
+* - `LoadingFirstPage` — the first page is in flight; `results` is empty.
+* - `CanLoadMore` — the loaded tail has a cursor; calling `loadMore` fetches the next page.
+* - `LoadingMore` — a `loadMore` page is in flight; earlier results stay visible.
+* - `Exhausted` — every page has loaded and the server reported `isDone`.
+*/
+type PaginationStatus = "CanLoadMore" | "Exhausted" | "LoadingFirstPage" | "LoadingMore";
+interface PaginatedCoreResult<T> {
+  /** Request another page off the open-ended tail. A no-op unless `status === "CanLoadMore"`. */
+  loadMore: (numberItems: number) => void;
+  /** Per-page resolved results in order; entries are `undefined` until a page resolves. */
+  pageResults: (PaginationResult<T> | undefined)[];
+  status: PaginationStatus;
+}
+/** First-page seed: a single open-ended range starting at the feed head. */
+declare const initialPages: (numberItems: number) => Page[];
+/**
+* Run the SPLIT/JOIN maintenance pass over the current page list given freshly
+* resolved results. Returns a new page list when a boundary changed, or
+* `undefined` when the layout is already balanced (so the caller can skip a
+* setState).
+*
+* Only ONE structural edit is applied per pass (the first split or join found),
+* letting the subsequent re-render's resolved results drive the next pass — this
+* keeps each transition observable and avoids reasoning about several
+* simultaneous boundary moves.
+*/
+declare const rebalance: (pages: Page[], results: (PaginationResult | undefined)[]) => Page[] | undefined;
+/**
+* Derive the feed `status` and the next-page cursor from the current page list
+* and resolved page results. Framework adapters call this each render/effect to
+* compute what to expose to callers.
+*/
+declare const derivePaginationStatus: <T>(skipped: boolean, pageResults: (PaginationResult<T> | undefined)[]) => {
+  nextCursor: null | string | undefined;
+  status: PaginationStatus;
+};
+/**
+* Apply a `loadMore` to the current page list. Pins the open-ended tail at
+* `cursor` (making it a fixed bounded range) and appends a fresh open-ended
+* page starting at `cursor`. The shared boundary keeps the feed gap- and
+* dup-free.
+*
+* Returns the new page list, or `undefined` when the given `cursor` is not
+* valid (null or undefined — caller should no-op).
+*/
+declare const applyLoadMore: (pages: Page[], cursor: null | string | undefined, numberItems: number) => Page[] | undefined;
+export { JOIN_FACTOR, type Page, type PaginatedCoreResult, type PaginationResult, type PaginationStatus, SPLIT_FACTOR, applyLoadMore, derivePaginationStatus, initialPages, rebalance };

package/dist/pagination/index.d.ts

@@ -0,0 +1,82 @@
+/**
+* `@lunora/client/pagination` — the framework-agnostic pagination state machine
+* shared by every Lunora UI adapter (React, Vue, Svelte, Solid).
+*
+* Owns cursor tracking, page-size rebalancing (split/join), `initialPages`,
+* `rebalance`, and the shared types (`Page`, `PaginationResult`,
+* `PaginationStatus`, `PaginatedCoreResult`). Nothing here imports a UI
+* framework — each adapter wires the pure functions into its own reactive
+* primitives.
+*/
+/** Grow factor: a bounded page is split when it exceeds this multiple of its target size. */
+declare const SPLIT_FACTOR = 2;
+/** Shrink factor: a bounded page with a neighbour is joined when it falls below this multiple of its target size. */
+declare const JOIN_FACTOR = .5;
+/** A loaded page: a fixed `(lower, upper]` range plus the size it targets. */
+interface Page {
+  lower: null | string;
+  numItems: number;
+  upper: null | string;
+}
+/** One page returned by a paginated query — the shape `.paginate()` yields. */
+interface PaginationResult<T = unknown> {
+  continueCursor: null | string;
+  isDone: boolean;
+  page: T[];
+  /**
+  * Reactive-pagination only: the midpoint cursor of a bounded
+  * `(cursor, endCursor]` page, used to split an over-grown page into two
+  * adjacent ranges. Absent on legacy (open-ended) pages.
+  */
+  splitCursor?: null | string;
+}
+/**
+* Lifecycle of a `usePaginatedQuery` feed.
+*
+* - `LoadingFirstPage` — the first page is in flight; `results` is empty.
+* - `CanLoadMore` — the loaded tail has a cursor; calling `loadMore` fetches the next page.
+* - `LoadingMore` — a `loadMore` page is in flight; earlier results stay visible.
+* - `Exhausted` — every page has loaded and the server reported `isDone`.
+*/
+type PaginationStatus = "CanLoadMore" | "Exhausted" | "LoadingFirstPage" | "LoadingMore";
+interface PaginatedCoreResult<T> {
+  /** Request another page off the open-ended tail. A no-op unless `status === "CanLoadMore"`. */
+  loadMore: (numberItems: number) => void;
+  /** Per-page resolved results in order; entries are `undefined` until a page resolves. */
+  pageResults: (PaginationResult<T> | undefined)[];
+  status: PaginationStatus;
+}
+/** First-page seed: a single open-ended range starting at the feed head. */
+declare const initialPages: (numberItems: number) => Page[];
+/**
+* Run the SPLIT/JOIN maintenance pass over the current page list given freshly
+* resolved results. Returns a new page list when a boundary changed, or
+* `undefined` when the layout is already balanced (so the caller can skip a
+* setState).
+*
+* Only ONE structural edit is applied per pass (the first split or join found),
+* letting the subsequent re-render's resolved results drive the next pass — this
+* keeps each transition observable and avoids reasoning about several
+* simultaneous boundary moves.
+*/
+declare const rebalance: (pages: Page[], results: (PaginationResult | undefined)[]) => Page[] | undefined;
+/**
+* Derive the feed `status` and the next-page cursor from the current page list
+* and resolved page results. Framework adapters call this each render/effect to
+* compute what to expose to callers.
+*/
+declare const derivePaginationStatus: <T>(skipped: boolean, pageResults: (PaginationResult<T> | undefined)[]) => {
+  nextCursor: null | string | undefined;
+  status: PaginationStatus;
+};
+/**
+* Apply a `loadMore` to the current page list. Pins the open-ended tail at
+* `cursor` (making it a fixed bounded range) and appends a fresh open-ended
+* page starting at `cursor`. The shared boundary keeps the feed gap- and
+* dup-free.
+*
+* Returns the new page list, or `undefined` when the given `cursor` is not
+* valid (null or undefined — caller should no-op).
+*/
+declare const applyLoadMore: (pages: Page[], cursor: null | string | undefined, numberItems: number) => Page[] | undefined;
+export { JOIN_FACTOR, type Page, type PaginatedCoreResult, type PaginationResult, type PaginationStatus, SPLIT_FACTOR, applyLoadMore, derivePaginationStatus, initialPages, rebalance };

package/dist/pagination/index.mjs

@@ -0,0 +1,61 @@
+const SPLIT_FACTOR = 2;
+const JOIN_FACTOR = 0.5;
+const initialPages = (numberItems) => [
+  // eslint-disable-next-line unicorn/no-null -- `lower: null` is the feed head, `upper: null` the open-ended tail — both are wire-shape cursors.
+  { lower: null, numItems: numberItems, upper: null }
+];
+const rebalance = (pages, results) => {
+  for (const [index, page] of pages.entries()) {
+    if (page.upper === null) {
+      continue;
+    }
+    const result = results[index];
+    if (!result) {
+      continue;
+    }
+    const size = result.page.length;
+    if (size > SPLIT_FACTOR * page.numItems && result.splitCursor) {
+      const split = result.splitCursor;
+      const next = [...pages];
+      next.splice(index, 1, { lower: page.lower, numItems: page.numItems, upper: split }, { lower: split, numItems: page.numItems, upper: page.upper });
+      return next;
+    }
+    if (size < JOIN_FACTOR * page.numItems && index + 1 < pages.length) {
+      const neighbour = pages[index + 1];
+      if (!neighbour) {
+        continue;
+      }
+      const next = [...pages];
+      next.splice(index, 2, { lower: page.lower, numItems: page.numItems, upper: neighbour.upper });
+      return next;
+    }
+  }
+  return void 0;
+};
+const derivePaginationStatus = (skipped, pageResults) => {
+  if (skipped || !pageResults[0]) {
+    return { nextCursor: void 0, status: "LoadingFirstPage" };
+  }
+  const tail = pageResults.at(-1);
+  if (!tail) {
+    return { nextCursor: void 0, status: "LoadingMore" };
+  }
+  if (tail.isDone || tail.continueCursor === null) {
+    return { nextCursor: void 0, status: "Exhausted" };
+  }
+  return { nextCursor: tail.continueCursor, status: "CanLoadMore" };
+};
+const applyLoadMore = (pages, cursor, numberItems) => {
+  if (cursor === void 0 || cursor === null) {
+    return void 0;
+  }
+  const next = [...pages];
+  const tail = next.at(-1);
+  if (tail) {
+    next[next.length - 1] = { lower: tail.lower, numItems: tail.numItems, upper: cursor };
+  }
+  next.push({ lower: cursor, numItems: numberItems, upper: null });
+  return next;
+};
+
+export { JOIN_FACTOR, SPLIT_FACTOR, applyLoadMore, derivePaginationStatus, initialPages, rebalance };

package/dist/query/index.d.mts

@@ -0,0 +1,62 @@
+import { S as SubscriptionError, F as FunctionReference, A as ArgsOf, R as ReturnOf, L as LunoraClient, a as Unsubscribe } from "../packem_shared/lunora-client.d-DGvyuJ_p.mjs";
+export type { b as SubscriptionErrorCallback } from "../packem_shared/lunora-client.d-DGvyuJ_p.mjs";
+import '@lunora/runtime';
+/**
+* The sentinel a framework adapter resolves its reactive args to when it wants
+* to short-circuit a query — no network call, no socket.
+*/
+declare const SKIP: "skip";
+/** Args after a framework has resolved its reactivity primitive, or the skip sentinel. */
+type ResolvedArgs<F extends FunctionReference> = ArgsOf<F> | typeof SKIP;
+/**
+* The framework-neutral sinks a {@link createQuerySubscription} call drives. A
+* framework adapter supplies these, wiring each into its own reactivity
+* primitive (a TanStack cache write, a Vue `ref`, a Svelte store `set`, a Solid
+* signal setter).
+*
+* `onData` fires when a fresh server value lands (the initial frame or a delta).
+* `onError` fires when the subscription attach threw, or the server pushed a
+* subscription-scoped error — it is optional, and when omitted an attach throw
+* propagates to the caller (preserving the "no error channel" behaviour of
+* adapters like Solid/Vue that never had one) rather than being swallowed.
+* `onReset` fires when the resolved args are `"skip"`: clear any prior value.
+*/
+interface QuerySubscriptionSinks<T> {
+  onData: (value: T) => void;
+  onError?: (error: SubscriptionError) => void;
+  onReset?: () => void;
+}
+interface QuerySubscriptionOptions {
+  /** Route to a specific shard when the target function is `.shardBy(...)`-partitioned. */
+  shardKey?: string;
+}
+/** Normalise an unknown thrown value into the client's {@link SubscriptionError} shape. */
+declare const toSubscriptionError: (error: unknown) => SubscriptionError;
+/**
+* The subscribe → snapshot → error/reset → cleanup state machine shared by
+* every Lunora framework adapter's live-query hook.
+*
+* Given a `client`, a function reference, the already-resolved `args` (a
+* framework reads its own reactive source first, then hands the plain value in),
+* and a set of {@link QuerySubscriptionSinks}, this opens one `client.subscribe`
+* registration and returns the {@link Unsubscribe} to tear it down. Each
+* framework owns *when* to call this (a React effect, a Vue `watch`, a Svelte
+* store start callback, a Solid `createEffect(on(...))`) and *where* to stash
+* the value — this owns the lifecycle in between, so the skip-handling, the
+* value/error fan-out, the attach-throw normalisation, and the
+* cancellation-guarded teardown live in exactly one place.
+*
+* Behaviour. When `args === "skip"` it calls `sinks.onReset?.()` and returns a
+* no-op teardown; no `client.subscribe` is issued. Otherwise it opens
+* `client.subscribe(fn, args, …, { shardKey, onError })`: server pushes route to
+* `sinks.onData`, and the client's own `onError` channel (a server-rejected
+* subscription) routes to `sinks.onError` when present. The attach is wrapped —
+* if `client.subscribe` itself throws, the error is normalised to a
+* {@link SubscriptionError} and delivered to `sinks.onError` when present; with
+* no `onError` sink the throw is rethrown so adapters without an error channel
+* behave exactly as before. The returned teardown is idempotent and
+* cancellation-guarded: once it runs, no further `onData`/`onError` from an
+* in-flight push reaches the sinks.
+*/
+declare const createQuerySubscription: <F extends FunctionReference, T = ReturnOf<F>>(client: LunoraClient, function_: F, args: ResolvedArgs<F>, sinks: QuerySubscriptionSinks<T>, options?: QuerySubscriptionOptions) => Unsubscribe;
+export { type ArgsOf, type FunctionReference, type QuerySubscriptionOptions, type QuerySubscriptionSinks, type ResolvedArgs, type ReturnOf, SKIP, type SubscriptionError, type Unsubscribe, createQuerySubscription, toSubscriptionError };

package/dist/query/index.d.ts

@@ -0,0 +1,62 @@
+import { S as SubscriptionError, F as FunctionReference, A as ArgsOf, R as ReturnOf, L as LunoraClient, a as Unsubscribe } from "../packem_shared/lunora-client.d-DGvyuJ_p.js";
+export type { b as SubscriptionErrorCallback } from "../packem_shared/lunora-client.d-DGvyuJ_p.js";
+import '@lunora/runtime';
+/**
+* The sentinel a framework adapter resolves its reactive args to when it wants
+* to short-circuit a query — no network call, no socket.
+*/
+declare const SKIP: "skip";
+/** Args after a framework has resolved its reactivity primitive, or the skip sentinel. */
+type ResolvedArgs<F extends FunctionReference> = ArgsOf<F> | typeof SKIP;
+/**
+* The framework-neutral sinks a {@link createQuerySubscription} call drives. A
+* framework adapter supplies these, wiring each into its own reactivity
+* primitive (a TanStack cache write, a Vue `ref`, a Svelte store `set`, a Solid
+* signal setter).
+*
+* `onData` fires when a fresh server value lands (the initial frame or a delta).
+* `onError` fires when the subscription attach threw, or the server pushed a
+* subscription-scoped error — it is optional, and when omitted an attach throw
+* propagates to the caller (preserving the "no error channel" behaviour of
+* adapters like Solid/Vue that never had one) rather than being swallowed.
+* `onReset` fires when the resolved args are `"skip"`: clear any prior value.
+*/
+interface QuerySubscriptionSinks<T> {
+  onData: (value: T) => void;
+  onError?: (error: SubscriptionError) => void;
+  onReset?: () => void;
+}
+interface QuerySubscriptionOptions {
+  /** Route to a specific shard when the target function is `.shardBy(...)`-partitioned. */
+  shardKey?: string;
+}
+/** Normalise an unknown thrown value into the client's {@link SubscriptionError} shape. */
+declare const toSubscriptionError: (error: unknown) => SubscriptionError;
+/**
+* The subscribe → snapshot → error/reset → cleanup state machine shared by
+* every Lunora framework adapter's live-query hook.
+*
+* Given a `client`, a function reference, the already-resolved `args` (a
+* framework reads its own reactive source first, then hands the plain value in),
+* and a set of {@link QuerySubscriptionSinks}, this opens one `client.subscribe`
+* registration and returns the {@link Unsubscribe} to tear it down. Each
+* framework owns *when* to call this (a React effect, a Vue `watch`, a Svelte
+* store start callback, a Solid `createEffect(on(...))`) and *where* to stash
+* the value — this owns the lifecycle in between, so the skip-handling, the
+* value/error fan-out, the attach-throw normalisation, and the
+* cancellation-guarded teardown live in exactly one place.
+*
+* Behaviour. When `args === "skip"` it calls `sinks.onReset?.()` and returns a
+* no-op teardown; no `client.subscribe` is issued. Otherwise it opens
+* `client.subscribe(fn, args, …, { shardKey, onError })`: server pushes route to
+* `sinks.onData`, and the client's own `onError` channel (a server-rejected
+* subscription) routes to `sinks.onError` when present. The attach is wrapped —
+* if `client.subscribe` itself throws, the error is normalised to a
+* {@link SubscriptionError} and delivered to `sinks.onError` when present; with
+* no `onError` sink the throw is rethrown so adapters without an error channel
+* behave exactly as before. The returned teardown is idempotent and
+* cancellation-guarded: once it runs, no further `onData`/`onError` from an
+* in-flight push reaches the sinks.
+*/
+declare const createQuerySubscription: <F extends FunctionReference, T = ReturnOf<F>>(client: LunoraClient, function_: F, args: ResolvedArgs<F>, sinks: QuerySubscriptionSinks<T>, options?: QuerySubscriptionOptions) => Unsubscribe;
+export { type ArgsOf, type FunctionReference, type QuerySubscriptionOptions, type QuerySubscriptionSinks, type ResolvedArgs, type ReturnOf, SKIP, type SubscriptionError, type Unsubscribe, createQuerySubscription, toSubscriptionError };

package/dist/query/index.mjs

@@ -0,0 +1 @@
+export { SKIP, createQuerySubscription, toSubscriptionError } from '../packem_shared/SKIP-vItZChkw.mjs';

package/dist/ssr/index.d.mts

@@ -0,0 +1,115 @@
+import { P as Preloaded, L as LunoraClient } from "../packem_shared/lunora-client.d-DGvyuJ_p.mjs";
+export type { A as ArgsOf, F as FunctionReference, R as ReturnOf } from "../packem_shared/lunora-client.d-DGvyuJ_p.mjs";
+export { p as preloadQuery, a as preloadedQueryResult } from "../packem_shared/preload.d-dSaRMuhL.mjs";
+import '@lunora/runtime';
+/**
+* Structural shape of a better-auth `getSession` call's resolved value.
+*
+* better-auth's `auth.api.getSession({ headers })` returns `{ user, session }`
+* when a valid session cookie is present, or `null` otherwise. We keep `user`
+* and `session` as open records so `@lunora/client/ssr` carries no hard dependency on
+* better-auth's concrete `User`/`Session` types — the adapter passing the real
+* `auth` instance keeps full inference, while this package stays decoupled.
+*/
+interface ServerSession<User extends Record<string, unknown> = Record<string, unknown>, Session extends Record<string, unknown> = Record<string, unknown>> {
+  readonly session: Session;
+  readonly user: User;
+}
+/**
+* Structural subset of a better-auth instance: just the one endpoint
+* `getServerSession` needs. Typing it this way (rather than importing
+* `@lunora/auth`'s `LunoraAuth`) means `@lunora/client/ssr` does not depend on
+* better-auth internals — any object exposing `api.getSession` works, including
+* a test stub. The concrete return type is inferred from the passed instance.
+*/
+interface AuthLike<Result = ServerSession | null> {
+  readonly api: {
+    getSession: (input: {
+      headers: Headers;
+    }) => Promise<Result> | Result;
+  };
+}
+/**
+* Anything `getServerSession` can read request headers from: a `Request`, a
+* `Headers` object, or a plain object exposing `headers`. SSR loaders across
+* meta-frameworks hand back slightly different request objects, so accept the
+* common shapes rather than forcing the caller to unwrap.
+*/
+type HeadersSource = Headers | Request | {
+  readonly headers: Headers;
+};
+/**
+* Resolve the signed-in session from a request inside an SSR loader.
+*
+* Wraps `auth.api.getSession({ headers })` — the helper every meta-framework
+* app otherwise hand-rolls — so a loader can read identity off the inbound
+* cookies in one call. Returns `{ user, session }` when a valid session cookie
+* is present, or `null` for anonymous requests.
+*
+* The `auth` parameter is structurally typed ({@link AuthLike}), so this
+* package does not depend on better-auth internals; pass a real
+* `@lunora/auth` instance to keep full type inference on `user`/`session`.
+* Forward the resolved session's token to `createServerClient` to run the
+* server-side load (and the later WS subscription) as the same identity.
+*/
+declare const getServerSession: <Result>(request: HeadersSource, auth: AuthLike<Result>) => Promise<NonNullable<Result> | null>;
+/**
+* Serialize a {@link Preloaded} token to a JSON string for embedding in the
+* rendered HTML (e.g. a `&lt;script>` payload the client
+* reads on hydration). Every field of `Preloaded` is JSON-serializable by
+* construction — `preloadQuery` only captures the query args, function path,
+* optional shard key, and the resolved value — so this is a thin, explicit
+* `JSON.stringify` that documents the dehydration seam and keeps callers from
+* accidentally stringifying a non-serializable wrapper.
+*
+* The `&lt;` is escaped to `&lt;` so the payload is safe to inline inside a
+* `&lt;script>` tag without a stray `&lt;/script>` (or `&lt;!--`) prematurely closing
+* it — the standard XSS-safe script-embedding precaution. This escaping is NOT
+* sufficient for an HTML *attribute* sink (which also needs the quote and `&amp;`
+* characters escaped); embed the output in a raw-text script element, not a
+* data attribute.
+*/
+declare const serializePreloaded: <T>(preloaded: Preloaded<T>) => string;
+/**
+* Inverse of {@link serializePreloaded}: parse a serialized token back into a
+* {@link Preloaded} value on the client. The `&lt;` escape from serialization
+* is transparent to `JSON.parse`, so no un-escaping step is needed.
+*/
+declare const deserializePreloaded: <T = unknown>(serialized: string) => Preloaded<T>;
+/** Options accepted by {@link createServerClient}. */
+interface ServerClientOptions {
+  /**
+  * `fetch` implementation used for HTTP RPC. Defaults to the ambient global
+  * `fetch` (present in Node 18+, Workers, and meta-framework SSR runtimes).
+  * Pass one explicitly to forward cookies/headers or to use an instrumented
+  * fetch.
+  */
+  fetch?: typeof fetch;
+  /**
+  * Bearer token sent as `Authorization: Bearer &lt;token>` on every RPC. In an
+  * SSR loader you typically read this from the request (e.g. the session
+  * resolved by `getServerSession`) and pass it here so the server-side
+  * load runs as the signed-in user — and so the client subscription that
+  * resumes after hydration carries the same identity.
+  */
+  token?: string;
+  /** Base URL of the deployed Lunora worker, e.g. `https://app.example.workers.dev`. */
+  url: string;
+}
+/**
+* Build a request-scoped {@link LunoraClient} for use inside an SSR loader. SSR
+* data loading only ever calls `.query()` (HTTP RPC over `fetch`); a
+* `LunoraClient` opens a socket lazily on `.subscribe()`/`.stream()` and those
+* are never called server-side, so no live connection is established even if the
+* server runtime happens to expose a global `WebSocket`.
+*
+* Create one per request rather than sharing a module-level instance: the bearer
+* token (and any forwarded cookies in `fetch`) are per-user, and a shared client
+* would leak one request's identity into another.
+*
+* This is the framework-neutral home of the helper that previously lived only in
+* `@lunora/react/server`; the React server module re-exports the same surface so
+* existing imports keep working.
+*/
+declare const createServerClient: (options: ServerClientOptions) => LunoraClient;
+export { type AuthLike, type HeadersSource, type Preloaded, type ServerClientOptions, type ServerSession, createServerClient, deserializePreloaded, getServerSession, serializePreloaded };

package/dist/ssr/index.d.ts

@@ -0,0 +1,115 @@
+import { P as Preloaded, L as LunoraClient } from "../packem_shared/lunora-client.d-DGvyuJ_p.js";
+export type { A as ArgsOf, F as FunctionReference, R as ReturnOf } from "../packem_shared/lunora-client.d-DGvyuJ_p.js";
+export { p as preloadQuery, a as preloadedQueryResult } from "../packem_shared/preload.d-BoDmFqSG.js";
+import '@lunora/runtime';
+/**
+* Structural shape of a better-auth `getSession` call's resolved value.
+*
+* better-auth's `auth.api.getSession({ headers })` returns `{ user, session }`
+* when a valid session cookie is present, or `null` otherwise. We keep `user`
+* and `session` as open records so `@lunora/client/ssr` carries no hard dependency on
+* better-auth's concrete `User`/`Session` types — the adapter passing the real
+* `auth` instance keeps full inference, while this package stays decoupled.
+*/
+interface ServerSession<User extends Record<string, unknown> = Record<string, unknown>, Session extends Record<string, unknown> = Record<string, unknown>> {
+  readonly session: Session;
+  readonly user: User;
+}
+/**
+* Structural subset of a better-auth instance: just the one endpoint
+* `getServerSession` needs. Typing it this way (rather than importing
+* `@lunora/auth`'s `LunoraAuth`) means `@lunora/client/ssr` does not depend on
+* better-auth internals — any object exposing `api.getSession` works, including
+* a test stub. The concrete return type is inferred from the passed instance.
+*/
+interface AuthLike<Result = ServerSession | null> {
+  readonly api: {
+    getSession: (input: {
+      headers: Headers;
+    }) => Promise<Result> | Result;
+  };
+}
+/**
+* Anything `getServerSession` can read request headers from: a `Request`, a
+* `Headers` object, or a plain object exposing `headers`. SSR loaders across
+* meta-frameworks hand back slightly different request objects, so accept the
+* common shapes rather than forcing the caller to unwrap.
+*/
+type HeadersSource = Headers | Request | {
+  readonly headers: Headers;
+};
+/**
+* Resolve the signed-in session from a request inside an SSR loader.
+*
+* Wraps `auth.api.getSession({ headers })` — the helper every meta-framework
+* app otherwise hand-rolls — so a loader can read identity off the inbound
+* cookies in one call. Returns `{ user, session }` when a valid session cookie
+* is present, or `null` for anonymous requests.
+*
+* The `auth` parameter is structurally typed ({@link AuthLike}), so this
+* package does not depend on better-auth internals; pass a real
+* `@lunora/auth` instance to keep full type inference on `user`/`session`.
+* Forward the resolved session's token to `createServerClient` to run the
+* server-side load (and the later WS subscription) as the same identity.
+*/
+declare const getServerSession: <Result>(request: HeadersSource, auth: AuthLike<Result>) => Promise<NonNullable<Result> | null>;
+/**
+* Serialize a {@link Preloaded} token to a JSON string for embedding in the
+* rendered HTML (e.g. a `&lt;script>` payload the client
+* reads on hydration). Every field of `Preloaded` is JSON-serializable by
+* construction — `preloadQuery` only captures the query args, function path,
+* optional shard key, and the resolved value — so this is a thin, explicit
+* `JSON.stringify` that documents the dehydration seam and keeps callers from
+* accidentally stringifying a non-serializable wrapper.
+*
+* The `&lt;` is escaped to `&lt;` so the payload is safe to inline inside a
+* `&lt;script>` tag without a stray `&lt;/script>` (or `&lt;!--`) prematurely closing
+* it — the standard XSS-safe script-embedding precaution. This escaping is NOT
+* sufficient for an HTML *attribute* sink (which also needs the quote and `&amp;`
+* characters escaped); embed the output in a raw-text script element, not a
+* data attribute.
+*/
+declare const serializePreloaded: <T>(preloaded: Preloaded<T>) => string;
+/**
+* Inverse of {@link serializePreloaded}: parse a serialized token back into a
+* {@link Preloaded} value on the client. The `&lt;` escape from serialization
+* is transparent to `JSON.parse`, so no un-escaping step is needed.
+*/
+declare const deserializePreloaded: <T = unknown>(serialized: string) => Preloaded<T>;
+/** Options accepted by {@link createServerClient}. */
+interface ServerClientOptions {
+  /**
+  * `fetch` implementation used for HTTP RPC. Defaults to the ambient global
+  * `fetch` (present in Node 18+, Workers, and meta-framework SSR runtimes).
+  * Pass one explicitly to forward cookies/headers or to use an instrumented
+  * fetch.
+  */
+  fetch?: typeof fetch;
+  /**
+  * Bearer token sent as `Authorization: Bearer &lt;token>` on every RPC. In an
+  * SSR loader you typically read this from the request (e.g. the session
+  * resolved by `getServerSession`) and pass it here so the server-side
+  * load runs as the signed-in user — and so the client subscription that
+  * resumes after hydration carries the same identity.
+  */
+  token?: string;
+  /** Base URL of the deployed Lunora worker, e.g. `https://app.example.workers.dev`. */
+  url: string;
+}
+/**
+* Build a request-scoped {@link LunoraClient} for use inside an SSR loader. SSR
+* data loading only ever calls `.query()` (HTTP RPC over `fetch`); a
+* `LunoraClient` opens a socket lazily on `.subscribe()`/`.stream()` and those
+* are never called server-side, so no live connection is established even if the
+* server runtime happens to expose a global `WebSocket`.
+*
+* Create one per request rather than sharing a module-level instance: the bearer
+* token (and any forwarded cookies in `fetch`) are per-user, and a shared client
+* would leak one request's identity into another.
+*
+* This is the framework-neutral home of the helper that previously lived only in
+* `@lunora/react/server`; the React server module re-exports the same surface so
+* existing imports keep working.
+*/
+declare const createServerClient: (options: ServerClientOptions) => LunoraClient;
+export { type AuthLike, type HeadersSource, type Preloaded, type ServerClientOptions, type ServerSession, createServerClient, deserializePreloaded, getServerSession, serializePreloaded };

package/dist/ssr/index.mjs

@@ -0,0 +1,4 @@
+export { getServerSession } from '../packem_shared/getServerSession-8jXewqxd.mjs';
+export { deserializePreloaded, serializePreloaded } from '../packem_shared/deserializePreloaded-C0eJTY_W.mjs';
+export { createServerClient } from '../packem_shared/createServerClient-BjZc3gD8.mjs';
+export { preloadQuery, preloadedQueryResult } from '../packem_shared/preloadQuery-lobFkD2Z.mjs';