@bquery/bquery 1.10.0 → 1.11.0

package/dist/ssr/renderer.d.ts

@@ -0,0 +1,25 @@
+/**
+ * DOM-free SSR renderer.
+ *
+ * Operates on the virtual node tree produced by `html-parser.ts` and
+ * evaluates `bq-*` directives without depending on any browser DOM API.
+ * Runs unmodified on Bun, Deno and Node and is the default backend used by
+ * `renderToString()` whenever the global `DOMParser` is not configured to
+ * take precedence.
+ *
+ * @module bquery/ssr
+ * @internal
+ */
+import type { BindingContext } from '../view/types';
+export declare const sanitizeHtmlForSSR: (raw: string) => string;
+/**
+ * Renders a template through the DOM-free pipeline.
+ *
+ * @internal
+ */
+export declare const renderTemplatePure: (template: string, data: BindingContext, options?: {
+    prefix?: string;
+    stripDirectives?: boolean;
+    annotateHydration?: boolean;
+}) => string;
+//# sourceMappingURL=renderer.d.ts.map

package/dist/ssr/renderer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"renderer.d.ts","sourceRoot":"","sources":["../../src/ssr/renderer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAUH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAuKpD,eAAO,MAAM,kBAAkB,GAAI,KAAK,MAAM,KAAG,MA6DhD,CAAC;AAmLF;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,GAC7B,UAAU,MAAM,EAChB,MAAM,cAAc,EACpB,UAAS;IAAE,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,eAAe,CAAC,EAAE,OAAO,CAAC;IAAC,iBAAiB,CAAC,EAAE,OAAO,CAAA;CAAO,KACxF,MAeF,CAAC"}

package/dist/ssr/resumability.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Resumability hooks.
+ *
+ * A *very* small primitive that lets the server publish JSON-serializable
+ * values which the client can read back without re-running the producer.
+ * Think of it as a typed key/value store that survives the serialization
+ * boundary.
+ *
+ * It is intentionally not a full Qwik-style resumability system — bQuery's
+ * reactive graph is rebuilt on the client. Instead, this primitive helps
+ * applications avoid double-fetching loader-style data by parking it on
+ * `window.__BQUERY_RESUME__` (or a custom global) inside a CSP-nonce-aware
+ * `<script>` tag.
+ *
+ * @module bquery/ssr
+ */
+/** Server-side resumable state collector. */
+export interface ResumableState {
+    /** Stash a JSON-serializable value under `key`. */
+    set: (key: string, value: unknown) => void;
+    /** Read a value back (server-side, useful for tests). */
+    get: <T = unknown>(key: string) => T | undefined;
+    /** All collected entries. */
+    entries: () => Record<string, unknown>;
+    /** Build the `<script>` tag to embed in HTML. */
+    render: (options?: {
+        nonce?: string;
+        scriptId?: string;
+        globalKey?: string;
+    }) => string;
+}
+/** Options for `createResumableState()`. */
+export interface CreateResumableStateOptions {
+    /** Initial entries. */
+    initial?: Record<string, unknown>;
+}
+/**
+ * Creates a server-side resumable state collector.
+ *
+ * @example
+ * ```ts
+ * const resume = createResumableState();
+ * resume.set('user', { id: 1, name: 'Ada' });
+ *
+ * // Inject into HTML:
+ * const tag = resume.render({ nonce: ctx.nonce });
+ * ```
+ */
+export declare const createResumableState: (options?: CreateResumableStateOptions) => ResumableState;
+/** Reader returned by `resumeState()`. */
+export interface ResumeReader {
+    /** Get a typed value from the resumable snapshot. */
+    get: <T = unknown>(key: string) => T | undefined;
+    /** Whether the snapshot was found. */
+    hasSnapshot: boolean;
+    /** All entries (read-only). */
+    entries: () => Record<string, unknown>;
+}
+/**
+ * Reads a previously-emitted resumable snapshot from `window` and cleans it
+ * up. Safe to call in any environment; returns an empty reader when no
+ * snapshot is present (server, tests, etc.).
+ */
+export declare const resumeState: (globalKey?: string, scriptId?: string) => ResumeReader;
+//# sourceMappingURL=resumability.d.ts.map

package/dist/ssr/resumability.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resumability.d.ts","sourceRoot":"","sources":["../../src/ssr/resumability.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAKH,6CAA6C;AAC7C,MAAM,WAAW,cAAc;IAC7B,mDAAmD;IACnD,GAAG,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;IAC3C,yDAAyD;IACzD,GAAG,EAAE,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,KAAK,CAAC,GAAG,SAAS,CAAC;IACjD,6BAA6B;IAC7B,OAAO,EAAE,MAAM,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACvC,iDAAiD;IACjD,MAAM,EAAE,CAAC,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,KAAK,MAAM,CAAC;CACzF;AAED,4CAA4C;AAC5C,MAAM,WAAW,2BAA2B;IAC1C,uBAAuB;IACvB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC;AAWD;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,oBAAoB,GAAI,UAAS,2BAAgC,KAAG,cAgChF,CAAC;AAEF,0CAA0C;AAC1C,MAAM,WAAW,YAAY;IAC3B,qDAAqD;IACrD,GAAG,EAAE,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,KAAK,CAAC,GAAG,SAAS,CAAC;IACjD,sCAAsC;IACtC,WAAW,EAAE,OAAO,CAAC;IACrB,+BAA+B;IAC/B,OAAO,EAAE,MAAM,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACxC;AAED;;;;GAIG;AACH,eAAO,MAAM,WAAW,GACtB,kBAA+B,EAC/B,iBAA8B,KAC7B,YA8BF,CAAC"}

package/dist/ssr/router-bridge.d.ts

@@ -0,0 +1,101 @@
+/**
+ * Router ↔ SSR bridge.
+ *
+ * On the server you typically need to:
+ * 1. Match the incoming URL against your router's route table.
+ * 2. Run any data loaders attached to the matched route.
+ * 3. Inject the resolved route + loader data into the SSR binding context.
+ *
+ * `resolveSSRRoute()` and `runRouteLoaders()` perform steps 1 and 2 without
+ * coupling the SSR module to the actual `createRouter()` runtime — only the
+ * pure `matchRoute()` helper from `@bquery/bquery/router` is used. Loaders
+ * live on `RouteDefinition.meta.loader` (additive, no existing field changes).
+ *
+ * @module bquery/ssr
+ */
+import type { Route, RouteDefinition } from '../router/types';
+import type { SSRContext } from './context';
+/**
+ * Loader signature for SSR routes. Attach as `meta.loader` on a
+ * `RouteDefinition` and `runRouteLoaders()` will invoke it with the matched
+ * route + the active SSR context.
+ */
+export type SSRRouteLoader<T = unknown> = (args: {
+    route: Route;
+    ctx: SSRContext;
+}) => T | Promise<T>;
+/** Result of `resolveSSRRoute()`. */
+export interface ResolvedSSRRoute {
+    /** Route-like snapshot for the requested URL, with `matched` set when found. */
+    route: Route;
+    /** Whether a route definition was actually matched. */
+    matched: boolean;
+    /** Whether the matched route has a `redirectTo` target. */
+    isRedirect: boolean;
+    /** Redirect target, if any. */
+    redirectTo?: string;
+}
+/**
+ * Matches a URL against a route table without instantiating a full router.
+ *
+ * Designed to be called on the server before the SSR render so userland can
+ * branch on `matched`/`isRedirect` (e.g. issue a 302 instead of rendering).
+ *
+ * @example
+ * ```ts
+ * import { resolveSSRRoute } from '@bquery/bquery/ssr';
+ *
+ * const { route, matched, isRedirect, redirectTo } = resolveSSRRoute({
+ *   url: new URL(request.url),
+ *   routes,
+ * });
+ *
+ * if (isRedirect) return Response.redirect(redirectTo!, 302);
+ * if (!matched) return new Response('Not Found', { status: 404 });
+ * ```
+ */
+export declare const resolveSSRRoute: (options: {
+    url: string | URL;
+    routes: RouteDefinition[];
+    /** Strip a base path before matching. Default: `''`. */
+    base?: string;
+}) => ResolvedSSRRoute;
+/**
+ * Runs the loader attached to the matched route (`meta.loader`), if any.
+ * Returns the resolved data, or `undefined` if no loader is configured.
+ */
+export declare const runRouteLoaders: <T = unknown>(route: Route, ctx: SSRContext) => Promise<T | undefined>;
+/**
+ * Convenience wrapper that resolves a route, runs its loader, and returns a
+ * binding-context fragment ready to be merged into the data passed to
+ * `renderToStringAsync()` / `renderToResponse()`.
+ *
+ * @example
+ * ```ts
+ * import {
+ *   createSSRContext,
+ *   createSSRRouterContext,
+ *   renderToResponse,
+ * } from '@bquery/bquery/ssr';
+ *
+ * const ctx = createSSRContext();
+ * const router = await createSSRRouterContext({ url: request.url, routes, ctx });
+ * if (router.isRedirect) return Response.redirect(router.redirectTo!, 302);
+ *
+ * return renderToResponse(template, { ...router.bindings }, { context: ctx });
+ * ```
+ */
+export declare const createSSRRouterContext: (options: {
+    url: string | URL;
+    routes: RouteDefinition[];
+    base?: string;
+    ctx: SSRContext;
+}) => Promise<{
+    route: Route;
+    matched: boolean;
+    isRedirect: boolean;
+    redirectTo?: string;
+    data: unknown;
+    bindings: Record<string, unknown>;
+}>;
+//# sourceMappingURL=router-bridge.d.ts.map

package/dist/ssr/router-bridge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"router-bridge.d.ts","sourceRoot":"","sources":["../../src/ssr/router-bridge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAIH,OAAO,KAAK,EAAE,KAAK,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAC9D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAE5C;;;;GAIG;AACH,MAAM,MAAM,cAAc,CAAC,CAAC,GAAG,OAAO,IAAI,CAAC,IAAI,EAAE;IAC/C,KAAK,EAAE,KAAK,CAAC;IACb,GAAG,EAAE,UAAU,CAAC;CACjB,KAAK,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;AAQrB,qCAAqC;AACrC,MAAM,WAAW,gBAAgB;IAC/B,gFAAgF;IAChF,KAAK,EAAE,KAAK,CAAC;IACb,uDAAuD;IACvD,OAAO,EAAE,OAAO,CAAC;IACjB,2DAA2D;IAC3D,UAAU,EAAE,OAAO,CAAC;IACpB,+BAA+B;IAC/B,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,eAAe,GAAI,SAAS;IACvC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAC;IAClB,MAAM,EAAE,eAAe,EAAE,CAAC;IAC1B,wDAAwD;IACxD,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,KAAG,gBA+BH,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,eAAe,GAAU,CAAC,GAAG,OAAO,EAC/C,OAAO,KAAK,EACZ,KAAK,UAAU,KACd,OAAO,CAAC,CAAC,GAAG,SAAS,CASvB,CAAC;AAEF;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,sBAAsB,GAAU,SAAS;IACpD,GAAG,EAAE,MAAM,GAAG,GAAG,CAAC;IAClB,MAAM,EAAE,eAAe,EAAE,CAAC;IAC1B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,UAAU,CAAC;CACjB,KAAG,OAAO,CAAC;IACV,KAAK,EAAE,KAAK,CAAC;IACb,OAAO,EAAE,OAAO,CAAC;IACjB,UAAU,EAAE,OAAO,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,OAAO,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC,CAoBA,CAAC"}

package/dist/ssr/runtime.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Runtime detection helpers for the SSR module.
+ *
+ * Detects whether the current runtime is Bun, Deno, Node.js, a browser,
+ * or a Web-Worker / edge runtime (Cloudflare Workers / `workerd`).
+ * Detection is feature-based and never throws; calling these helpers is
+ * safe in any environment that provides `globalThis`.
+ *
+ * @module bquery/ssr
+ */
+/**
+ * Identifier for a recognised JavaScript runtime.
+ */
+export type SSRRuntime = 'bun' | 'deno' | 'node' | 'browser' | 'workerd' | 'unknown';
+/**
+ * Detects the current runtime via feature checks on `globalThis`.
+ * Order matters: Bun and Deno expose Node compatibility shims, so they are
+ * checked first.
+ *
+ * @returns The detected runtime identifier, or `'unknown'` if none match.
+ *
+ * @example
+ * ```ts
+ * import { detectRuntime } from '@bquery/bquery/ssr';
+ *
+ * if (detectRuntime() === 'deno') {
+ *   // Deno-specific behaviour
+ * }
+ * ```
+ */
+export declare const detectRuntime: () => SSRRuntime;
+/**
+ * Returns `true` when called inside a server-side runtime (Bun, Deno, Node,
+ * Cloudflare Workers / `workerd`).
+ */
+export declare const isServerRuntime: () => boolean;
+/**
+ * Returns `true` when called inside a browser-like runtime (full DOM available).
+ */
+export declare const isBrowserRuntime: () => boolean;
+/**
+ * Lightweight feature-detection report for runtime capabilities relevant to SSR.
+ */
+export interface SSRRuntimeFeatures {
+    /** Whether `Request`/`Response`/`fetch` are available on `globalThis`. */
+    fetchApi: boolean;
+    /** Whether `ReadableStream` is available on `globalThis`. */
+    webStreams: boolean;
+    /** Whether `TextEncoder` is available on `globalThis`. */
+    textEncoder: boolean;
+    /** Whether `crypto.subtle` is available (used for ETag hashing). */
+    subtleCrypto: boolean;
+    /** Whether `crypto.randomUUID()` is available. */
+    randomUuid: boolean;
+    /** Whether the global `DOMParser` is available. */
+    domParser: boolean;
+}
+/**
+ * Returns a feature-detection report for the current runtime. All checks are
+ * non-throwing; missing globals yield `false`.
+ */
+export declare const getSSRRuntimeFeatures: () => SSRRuntimeFeatures;
+//# sourceMappingURL=runtime.d.ts.map

package/dist/ssr/runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../../src/ssr/runtime.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH;;GAEG;AACH,MAAM,MAAM,UAAU,GAAG,KAAK,GAAG,MAAM,GAAG,MAAM,GAAG,SAAS,GAAG,SAAS,GAAG,SAAS,CAAC;AAkBrF;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,aAAa,QAAO,UA8BhC,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,eAAe,QAAO,OAGlC,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,gBAAgB,QAAO,OAAwC,CAAC;AAE7E;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,0EAA0E;IAC1E,QAAQ,EAAE,OAAO,CAAC;IAClB,6DAA6D;IAC7D,UAAU,EAAE,OAAO,CAAC;IACpB,0DAA0D;IAC1D,WAAW,EAAE,OAAO,CAAC;IACrB,oEAAoE;IACpE,YAAY,EAAE,OAAO,CAAC;IACtB,kDAAkD;IAClD,UAAU,EAAE,OAAO,CAAC;IACpB,mDAAmD;IACnD,SAAS,EAAE,OAAO,CAAC;CACpB;AAED;;;GAGG;AACH,eAAO,MAAM,qBAAqB,QAAO,kBAcxC,CAAC"}

package/dist/ssr/serialize.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"serialize.d.ts","sourceRoot":"","sources":["../../src/ssr/serialize.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,OAAO,KAAK,EAAE,sBAAsB,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC;AAcxE;;GAEG;AACH,MAAM,MAAM,eAAe,GAAG;IAC5B,mCAAmC;IACnC,SAAS,EAAE,MAAM,CAAC;IAClB,qDAAqD;IACrD,SAAS,EAAE,MAAM,CAAC;CACnB,CAAC;AA6BF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,eAAO,MAAM,mBAAmB,GAAI,UAAS,gBAAqB,KAAG,eA4DpE,CAAC;AAEF;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,qBAAqB,GAChC,kBAAsC,EACtC,iBAAmC,KAClC,sBA2DF,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,eAAO,MAAM,YAAY,GAAI,SAAS,MAAM,EAAE,OAAO,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAG,IAM9E,CAAC;AAEF;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,aAAa,GAAI,UAAU,sBAAsB,KAAG,IAIhE,CAAC"}
+{"version":3,"file":"serialize.d.ts","sourceRoot":"","sources":["../../src/ssr/serialize.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAKH,OAAO,KAAK,EAAE,sBAAsB,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC;AAcxE;;GAEG;AACH,MAAM,MAAM,eAAe,GAAG;IAC5B,mCAAmC;IACnC,SAAS,EAAE,MAAM,CAAC;IAClB,qDAAqD;IACrD,SAAS,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,eAAO,MAAM,mBAAmB,GAAI,UAAS,gBAAqB,KAAG,eA4DpE,CAAC;AAEF;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,qBAAqB,GAChC,kBAAsC,EACtC,iBAAmC,KAClC,sBA2DF,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,eAAO,MAAM,YAAY,GAAI,SAAS,MAAM,EAAE,OAAO,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAG,IAM9E,CAAC;AAEF;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,aAAa,GAAI,UAAU,sBAAsB,KAAG,IAIhE,CAAC"}

package/dist/ssr/store-snapshot.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Versioned store snapshots and strict drift-checking hydration.
+ *
+ * Sits *on top of* the simple `serializeStoreState()` / `hydrateStore()` pair
+ * to give applications a way to:
+ * - tag the snapshot with a schema version so a stale client can refuse to
+ *   apply server data that no longer matches its store shape;
+ * - opt into strict mode where unknown keys cause a warning;
+ * - selectively serialize / hydrate a subset of stores.
+ *
+ * Backwards compatible: the existing helpers stay untouched and remain the
+ * primary entry-point for simple use cases.
+ *
+ * @module bquery/ssr
+ */
+/** Versioned store snapshot. */
+export interface SSRStoreSnapshot {
+    /** Application-defined version string. Stable per schema. */
+    version: string;
+    /** Map of store ID → sanitized state. */
+    state: Record<string, Record<string, unknown>>;
+}
+/** Result of `serializeStoreSnapshot()`. */
+export interface SerializeSnapshotResult {
+    snapshot: SSRStoreSnapshot;
+    /** JSON-serialized snapshot. */
+    json: string;
+    /** `<script>` tag ready to embed (CSP-nonce-aware via `options.nonce`). */
+    scriptTag: string;
+}
+/** Options for `serializeStoreSnapshot()`. */
+export interface SerializeSnapshotOptions {
+    /** Schema version. Required: hydration only succeeds when versions match. */
+    version: string;
+    /** Subset of store IDs to serialize. Defaults to all registered stores. */
+    storeIds?: string[];
+    /** Element ID for the generated `<script>` tag. */
+    scriptId?: string;
+    /** Global window key where the snapshot is assigned. */
+    globalKey?: string;
+    /** CSP nonce applied to the generated `<script>`. */
+    nonce?: string;
+}
+/**
+ * Captures every registered store's state into a versioned snapshot and
+ * returns both the JSON payload and a ready-to-embed `<script>` tag.
+ */
+export declare const serializeStoreSnapshot: (options: SerializeSnapshotOptions) => SerializeSnapshotResult;
+/** Options for `hydrateStoreSnapshot()`. */
+export interface HydrateSnapshotOptions {
+    /**
+     * If set, the snapshot's `version` must match this value. Otherwise the
+     * function returns early (and warns when `strict` is true).
+     */
+    expectedVersion?: string;
+    /**
+     * Strict mode: warn on version mismatch + warn on unknown store IDs (i.e.
+     * the snapshot has IDs that aren't currently registered). Default: `false`.
+     */
+    strict?: boolean;
+}
+/** Result of `hydrateStoreSnapshot()`. */
+export interface HydrateSnapshotResult {
+    /** Whether the snapshot was applied. */
+    applied: boolean;
+    /** Reason when not applied (`'version-mismatch' | 'invalid-shape'`). */
+    reason?: 'version-mismatch' | 'invalid-shape';
+    /** IDs that were applied. */
+    appliedIds: string[];
+    /** IDs in the snapshot that no store exists for. */
+    unknownIds: string[];
+}
+/**
+ * Applies a previously-serialized `SSRStoreSnapshot` to the registered stores.
+ *
+ * Returns a structured result; never throws on drift unless an explicit error
+ * is thrown by a store's `$patch()` implementation.
+ */
+export declare const hydrateStoreSnapshot: (snapshot: unknown, options?: HydrateSnapshotOptions) => HydrateSnapshotResult;
+/**
+ * Reads the snapshot emitted by `serializeStoreSnapshot()` from `window`,
+ * cleans up the global, and returns the parsed `SSRStoreSnapshot`.
+ *
+ * Returns `null` when no snapshot was found or when it has the wrong shape.
+ */
+export declare const readStoreSnapshot: (globalKey?: string, scriptId?: string) => SSRStoreSnapshot | null;
+//# sourceMappingURL=store-snapshot.d.ts.map

package/dist/ssr/store-snapshot.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store-snapshot.d.ts","sourceRoot":"","sources":["../../src/ssr/store-snapshot.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAkBH,gCAAgC;AAChC,MAAM,WAAW,gBAAgB;IAC/B,6DAA6D;IAC7D,OAAO,EAAE,MAAM,CAAC;IAChB,yCAAyC;IACzC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CAChD;AAED,4CAA4C;AAC5C,MAAM,WAAW,uBAAuB;IACtC,QAAQ,EAAE,gBAAgB,CAAC;IAC3B,gCAAgC;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,2EAA2E;IAC3E,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,8CAA8C;AAC9C,MAAM,WAAW,wBAAwB;IACvC,6EAA6E;IAC7E,OAAO,EAAE,MAAM,CAAC;IAChB,2EAA2E;IAC3E,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,mDAAmD;IACnD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,wDAAwD;IACxD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,qDAAqD;IACrD,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;GAGG;AACH,eAAO,MAAM,sBAAsB,GACjC,SAAS,wBAAwB,KAChC,uBAkCF,CAAC;AAEF,4CAA4C;AAC5C,MAAM,WAAW,sBAAsB;IACrC;;;OAGG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB;;;OAGG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,0CAA0C;AAC1C,MAAM,WAAW,qBAAqB;IACpC,wCAAwC;IACxC,OAAO,EAAE,OAAO,CAAC;IACjB,wEAAwE;IACxE,MAAM,CAAC,EAAE,kBAAkB,GAAG,eAAe,CAAC;IAC9C,6BAA6B;IAC7B,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,oDAAoD;IACpD,UAAU,EAAE,MAAM,EAAE,CAAC;CACtB;AASD;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB,GAC/B,UAAU,OAAO,EACjB,UAAS,sBAA2B,KACnC,qBAmCF,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB,GAC5B,kBAAuC,EACvC,iBAAsC,KACrC,gBAAgB,GAAG,IAerB,CAAC"}

package/dist/ssr/strategies.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Progressive hydration strategies.
+ *
+ * Provide thin wrappers around `hydrateMount()` that defer the hydration
+ * pass until a chosen trigger fires. They are runtime-safe: in non-browser
+ * environments they fall back to immediate hydration (or a no-op) so the
+ * same code path can run in tests.
+ *
+ * @module bquery/ssr
+ */
+import type { BindingContext, View } from '../view/types';
+import { type HydrateMountOptions } from './hydrate';
+/** Common return shape for progressive hydration. */
+export interface HydrationHandle {
+    /** Cancels pending hydration (no-op if it has already run). */
+    cancel(): void;
+    /** Resolves with the View once hydration runs, or `null` if cancelled. */
+    ready: Promise<View | null>;
+}
+/**
+ * Hydrates the target only once it scrolls into view.
+ *
+ * Falls back to immediate hydration if `IntersectionObserver` is unavailable.
+ */
+export declare const hydrateOnVisible: (selector: string | Element, context: BindingContext, options?: HydrateMountOptions & {
+    rootMargin?: string;
+    threshold?: number;
+}) => HydrationHandle;
+/** Hydrates when the browser is idle. */
+export declare const hydrateOnIdle: (selector: string | Element, context: BindingContext, options?: HydrateMountOptions) => HydrationHandle;
+/** Hydrates on first user interaction (click/keydown/pointerdown/touchstart). */
+export declare const hydrateOnInteraction: (selector: string | Element, context: BindingContext, options?: HydrateMountOptions & {
+    events?: string[];
+}) => HydrationHandle;
+/** Hydrates only when a media query matches. */
+export declare const hydrateOnMedia: (selector: string | Element, context: BindingContext, query: string, options?: HydrateMountOptions) => HydrationHandle;
+/**
+ * Hydrates a single SSR island using the same runtime-safe target resolution
+ * as the other progressive hydration helpers. Returns `null` when the DOM is
+ * unavailable or the target cannot be resolved.
+ */
+export declare const hydrateIsland: (selector: string | Element, context: BindingContext, options?: HydrateMountOptions) => View | null;
+//# sourceMappingURL=strategies.d.ts.map

package/dist/ssr/strategies.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"strategies.d.ts","sourceRoot":"","sources":["../../src/ssr/strategies.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,IAAI,EAAE,MAAM,eAAe,CAAC;AAC1D,OAAO,EAAgB,KAAK,mBAAmB,EAAE,MAAM,WAAW,CAAC;AAgDnE,qDAAqD;AACrD,MAAM,WAAW,eAAe;IAC9B,+DAA+D;IAC/D,MAAM,IAAI,IAAI,CAAC;IACf,0EAA0E;IAC1E,KAAK,EAAE,OAAO,CAAC,IAAI,GAAG,IAAI,CAAC,CAAC;CAC7B;AAwCD;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,GAC3B,UAAU,MAAM,GAAG,OAAO,EAC1B,SAAS,cAAc,EACvB,UAAS,mBAAmB,GAAG;IAAE,UAAU,CAAC,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAAO,KAC9E,eA8BF,CAAC;AAEF,yCAAyC;AACzC,eAAO,MAAM,aAAa,GACxB,UAAU,MAAM,GAAG,OAAO,EAC1B,SAAS,cAAc,EACvB,UAAS,mBAAwB,KAChC,eAIF,CAAC;AAEF,iFAAiF;AACjF,eAAO,MAAM,oBAAoB,GAC/B,UAAU,MAAM,GAAG,OAAO,EAC1B,SAAS,cAAc,EACvB,UAAS,mBAAmB,GAAG;IAAE,MAAM,CAAC,EAAE,MAAM,EAAE,CAAA;CAAO,KACxD,eAyBF,CAAC;AAEF,gDAAgD;AAChD,eAAO,MAAM,cAAc,GACzB,UAAU,MAAM,GAAG,OAAO,EAC1B,SAAS,cAAc,EACvB,OAAO,MAAM,EACb,UAAS,mBAAwB,KAChC,eAqCF,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,aAAa,GACxB,UAAU,MAAM,GAAG,OAAO,EAC1B,SAAS,cAAc,EACvB,UAAS,mBAAwB,KAChC,IAAI,GAAG,IAAmD,CAAC"}

package/dist/ssr/suspense.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Suspense-style out-of-order streaming for SSR.
+ *
+ * Renders the synchronous shell with `defer(...)` placeholders wrapped in
+ * `<bq-slot id="bq-s-N">…</bq-slot>` markers, flushes that initial chunk,
+ * then streams a `<template id="bq-r-N">…</template>` plus a tiny inline
+ * patch script for every resolved promise. The patch script swaps the
+ * template content into the placeholder and removes both.
+ *
+ * Honours `SSRContext.signal` for cancellation and propagates the context
+ * nonce onto every emitted `<script>` tag for CSP-strict environments.
+ *
+ * @module bquery/ssr
+ */
+import type { BindingContext } from '../view/types';
+import type { AsyncRenderOptions } from './render-async';
+/**
+ * Options for `renderToStreamSuspense`.
+ *
+ * Only `context`, `prefix`, `stripDirectives`, and `annotateHydration` are
+ * inherited from the base async render options. Head/store injection and other
+ * response-shaping options are intentionally unsupported here.
+ */
+export interface SuspenseStreamOptions extends Pick<AsyncRenderOptions, 'context' | 'prefix' | 'stripDirectives' | 'annotateHydration'> {
+    /**
+     * Prefix used for slot/template IDs. Default: `'bq-s'` for placeholders
+     * and `'bq-r'` for resolved templates.
+     */
+    slotIdPrefix?: string;
+    /**
+     * Tag name used for the placeholder element. Default: `'bq-slot'`.
+     * Must be a valid custom-element tag (contain a `-`) so the browser keeps
+     * inner content intact.
+     */
+    slotTag?: string;
+}
+/**
+ * Renders a template into a Web `ReadableStream<Uint8Array>` with
+ * Suspense-style out-of-order streaming. The synchronous shell is flushed
+ * first; deferred slots stream in as their promises resolve.
+ *
+ * Use `bq-defer="key"` on an element whose content depends on a `defer()`
+ * value to mark where the placeholder wrapping should happen. Without the
+ * marker, resolved fragments are appended at the end of `<body>`.
+ */
+export declare const renderToStreamSuspense: (template: string, data: BindingContext, options?: SuspenseStreamOptions) => ReadableStream<Uint8Array>;
+//# sourceMappingURL=suspense.d.ts.map

package/dist/ssr/suspense.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"suspense.d.ts","sourceRoot":"","sources":["../../src/ssr/suspense.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAGH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAKpD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AA6GzD;;;;;;GAMG;AACH,MAAM,WAAW,qBACf,SAAQ,IAAI,CAAC,kBAAkB,EAAE,SAAS,GAAG,QAAQ,GAAG,iBAAiB,GAAG,mBAAmB,CAAC;IAChG;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AA2OD;;;;;;;;GAQG;AACH,eAAO,MAAM,sBAAsB,GACjC,UAAU,MAAM,EAChB,MAAM,cAAc,EACpB,UAAS,qBAA0B,KAClC,cAAc,CAAC,UAAU,CAyG3B,CAAC"}

package/dist/ssr/types.d.ts

@@ -25,6 +25,23 @@ export type RenderOptions = {
      * @default false
      */
     includeStoreState?: boolean | string[];
+    /**
+     * Whether to add a `data-bq-h` mismatch hash to every element that carries
+     * a `bq-*` directive. Used by `verifyHydration()` on the client to flag
+     * Server↔Client divergence in development. Adds ≈ 6–8 bytes per directive
+     * element; safe to leave on in production but only useful in dev builds.
+     *
+     * Do not combine this with `stripDirectives: true` if you plan to call
+     * `verifyHydration()` later: once the `bq-*` / `:` directives are stripped
+     * from the HTML, the client can no longer recompute the original signature,
+     * so verification will deterministically report mismatches.
+     *
+     * Currently honoured by the DOM-free renderer; the legacy DOM backend
+     * applies the same annotation when `DOMParser` is available.
+     *
+     * @default false
+     */
+    annotateHydration?: boolean;
 };
 /**
  * Result of a `renderToString` call.

package/dist/ssr/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/ssr/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,WAAW,CAAC;AAErD;;GAEG;AAEH;;GAEG;AACH,MAAM,MAAM,aAAa,GAAG;IAC1B;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB;;;;;OAKG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;IAE1B;;;;;OAKG;IACH,iBAAiB,CAAC,EAAE,OAAO,GAAG,MAAM,EAAE,CAAC;CACxC,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,SAAS,GAAG;IACtB,+BAA+B;IAC/B,IAAI,EAAE,MAAM,CAAC;IAEb;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,CAAC;AAEF,qDAAqD;AACrD,MAAM,MAAM,gBAAgB,GAAG,mBAAmB,CAAC;AAEnD;;GAEG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC7B;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB;;OAEG;IACH,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IAEpB;;OAEG;IACH,SAAS,CAAC,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,MAAM,CAAC;CACvC,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,sBAAsB,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/ssr/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,WAAW,CAAC;AAErD;;GAEG;AAEH;;GAEG;AACH,MAAM,MAAM,aAAa,GAAG;IAC1B;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB;;;;;OAKG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;IAE1B;;;;;OAKG;IACH,iBAAiB,CAAC,EAAE,OAAO,GAAG,MAAM,EAAE,CAAC;IAEvC;;;;;;;;;;;;;;;OAeG;IACH,iBAAiB,CAAC,EAAE,OAAO,CAAC;CAC7B,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,SAAS,GAAG;IACtB,+BAA+B;IAC/B,IAAI,EAAE,MAAM,CAAC;IAEb;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,CAAC;AAEF,qDAAqD;AACrD,MAAM,MAAM,gBAAgB,GAAG,mBAAmB,CAAC;AAEnD;;GAEG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC7B;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB;;OAEG;IACH,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IAEpB;;OAEG;IACH,SAAS,CAAC,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,MAAM,CAAC;CACvC,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,sBAAsB,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC"}