@bquery/bquery 1.10.0 → 1.11.1

package/src/ssr/index.ts

@@ -1,56 +1,38 @@
 /**
  * SSR / Pre-rendering module for bQuery.js.
  *
- * Provides server-side rendering, hydration, and store state serialization
- * utilities for bQuery applications. Enables rendering bQuery templates
- * to HTML strings on the server, serializing store state for client pickup,
- * and hydrating the pre-rendered DOM on the client.
+ * Server-side rendering, hydration, store-state serialization and runtime
+ * adapters for bQuery applications. The module is **runtime-agnostic** and
+ * runs on Bun, Deno and Node.js ≥ 24 without any external dependency.
  *
- * ## Features
+ * The synchronous `renderToString()` keeps its previous behaviour for
+ * backward compatibility but now automatically falls back to a fully
+ * DOM-free renderer when no `DOMParser` is available — that is what makes
+ * the same code path work on every server runtime.
  *
- * - **`renderToString(template, data)`** — Server-side render a bQuery
- *   template to an `SSRResult` containing an `html` string with directive evaluation.
- * - **`hydrateMount(selector, context, { hydrate: true })`** — Reuse
- *   existing server-rendered DOM and attach reactive bindings.
- * - **`serializeStoreState(options?)`** — Serialize store state into a
- *   `<script>` tag for client-side pickup.
- * - **`deserializeStoreState()`** — Read serialized state on the client.
- * - **`hydrateStore(id, state)` / `hydrateStores(stateMap)`** — Apply
- *   server state to client stores.
+ * ## Highlights
  *
- * ## Usage
- *
- * ### Server
- * ```ts
- * import { renderToString, serializeStoreState } from '@bquery/bquery/ssr';
- *
- * const { html } = renderToString(
- *   '<div id="app"><h1 bq-text="title"></h1></div>',
- *   { title: 'Welcome' }
- * );
- *
- * const { scriptTag } = serializeStoreState();
- *
- * // Send to client: html + scriptTag
- * ```
- *
- * ### Client
- * ```ts
- * import { hydrateMount, deserializeStoreState, hydrateStores } from '@bquery/bquery/ssr';
- * import { signal } from '@bquery/bquery/reactive';
- *
- * // Restore store state from SSR
- * const ssrState = deserializeStoreState();
- * hydrateStores(ssrState);
- *
- * // Hydrate the DOM with reactive bindings
- * const title = signal('Welcome');
- * hydrateMount('#app', { title }, { hydrate: true });
- * ```
+ * - **`renderToString(template, data)`** — synchronous render to HTML.
+ * - **`renderToStringAsync(template, data, ctx?)`** — awaits Promises and
+ *   `defer()` values in the binding context.
+ * - **`renderToStream(template, data, ctx?)`** — Web `ReadableStream<Uint8Array>`.
+ * - **`renderToResponse(template, data, ctx?)`** — high-level `Response`
+ *   wrapper with ETag, Cache-Control, head & store-state injection.
+ * - **`createSSRContext(...)`** — request/response context bag.
+ * - **`createHeadManager()`** — `<title>`, `<meta>`, `<link>` and
+ *   `<script>` collection.
+ * - **`hydrateMount` / `hydrateOnVisible` / `hydrateOnIdle` /
+ *   `hydrateOnInteraction` / `hydrateOnMedia` / `hydrateIsland`** — full
+ *   progressive-hydration toolkit.
+ * - **Runtime adapters** — `createWebHandler`, `createBunHandler`,
+ *   `createDenoHandler`, `createNodeHandler`, `createSSRHandler`.
  *
  * @module bquery/ssr
  */
 
+// ---------------------------------------------------------------------------
+// Existing public API (unchanged)
+// ---------------------------------------------------------------------------
 export { hydrateMount } from './hydrate';
 export type { HydrateMountOptions } from './hydrate';
 export { renderToString } from './render';
@@ -68,3 +50,114 @@ export type {
   SSRResult,
   SerializeOptions,
 } from './types';
+
+// ---------------------------------------------------------------------------
+// Runtime detection
+// ---------------------------------------------------------------------------
+export { detectRuntime, getSSRRuntimeFeatures, isBrowserRuntime, isServerRuntime } from './runtime';
+export type { SSRRuntime, SSRRuntimeFeatures } from './runtime';
+
+// ---------------------------------------------------------------------------
+// Configuration
+// ---------------------------------------------------------------------------
+export { configureSSR, getSSRConfig } from './config';
+export type { SSRDocumentImpl, SSRRendererBackend } from './config';
+
+// ---------------------------------------------------------------------------
+// Async/streaming render pipeline
+// ---------------------------------------------------------------------------
+export { renderToResponse, renderToStream, renderToStringAsync } from './render-async';
+export type { AsyncRenderOptions, AsyncSSRResult, RenderToResponseOptions } from './render-async';
+
+// ---------------------------------------------------------------------------
+// SSR context
+// ---------------------------------------------------------------------------
+export { createSSRContext } from './context';
+export type { CreateSSRContextOptions, SSRContext } from './context';
+
+// ---------------------------------------------------------------------------
+// Head + assets + nonce
+// ---------------------------------------------------------------------------
+export { createAssetManager, createHeadManager } from './head';
+export type {
+  AssetManager,
+  HeadManager,
+  SSRAsset,
+  SSRHeadState,
+  SSRLink,
+  SSRMeta,
+  SSRScript,
+  UseHeadOptions,
+} from './head';
+
+// ---------------------------------------------------------------------------
+// Async loaders / defer
+// ---------------------------------------------------------------------------
+export { defer, defineLoader } from './async';
+export type { SSRLoader } from './async';
+
+// ---------------------------------------------------------------------------
+// Hydration strategies
+// ---------------------------------------------------------------------------
+export {
+  hydrateIsland,
+  hydrateOnIdle,
+  hydrateOnInteraction,
+  hydrateOnMedia,
+  hydrateOnVisible,
+} from './strategies';
+export type { HydrationHandle } from './strategies';
+
+// ---------------------------------------------------------------------------
+// Hydration mismatch detection
+// ---------------------------------------------------------------------------
+export { verifyHydration } from './mismatch';
+export type { HydrationMismatch, VerifyHydrationOptions } from './mismatch';
+export { HYDRATION_HASH_ATTR } from './hash';
+
+// ---------------------------------------------------------------------------
+// Suspense / out-of-order streaming
+// ---------------------------------------------------------------------------
+export { renderToStreamSuspense } from './suspense';
+export type { SuspenseStreamOptions } from './suspense';
+
+// ---------------------------------------------------------------------------
+// Router ↔ SSR bridge
+// ---------------------------------------------------------------------------
+export { createSSRRouterContext, resolveSSRRoute, runRouteLoaders } from './router-bridge';
+export type { ResolvedSSRRoute, SSRRouteLoader } from './router-bridge';
+
+// ---------------------------------------------------------------------------
+// Versioned store snapshots
+// ---------------------------------------------------------------------------
+export { hydrateStoreSnapshot, readStoreSnapshot, serializeStoreSnapshot } from './store-snapshot';
+export type {
+  HydrateSnapshotOptions,
+  HydrateSnapshotResult,
+  SerializeSnapshotOptions,
+  SerializeSnapshotResult,
+  SSRStoreSnapshot,
+} from './store-snapshot';
+
+// ---------------------------------------------------------------------------
+// Resumability
+// ---------------------------------------------------------------------------
+export { createResumableState, resumeState } from './resumability';
+export type { CreateResumableStateOptions, ResumableState, ResumeReader } from './resumability';
+
+// ---------------------------------------------------------------------------
+// Runtime adapters
+// ---------------------------------------------------------------------------
+export {
+  createBunHandler,
+  createDenoHandler,
+  createNodeHandler,
+  createSSRHandler,
+  createWebHandler,
+} from './adapters';
+export type {
+  NodeHandlerOptions,
+  NodeIncomingMessage,
+  NodeServerResponse,
+  SSRRequestHandler,
+} from './adapters';

package/src/ssr/mismatch.ts

@@ -0,0 +1,110 @@
+/**
+ * Hydration mismatch detection.
+ *
+ * The DOM-free SSR renderer can annotate every element that carries a `bq-*`
+ * directive with a small `data-bq-h` hash (see `RenderOptions.annotateHydration`).
+ * On the client, `verifyHydration()` walks the live DOM, recomputes the same
+ * hash for each annotated element and reports any divergence.
+ *
+ * The check is intentionally cheap and safe: collisions only result in false
+ * negatives (a mismatch slips through), never in false positives (a stable
+ * tree never reports a mismatch).
+ *
+ * @module bquery/ssr
+ */
+
+import { cheapHash, collectDirectiveSignatureFromElement, HYDRATION_HASH_ATTR } from './hash';
+import { detectDevEnvironment } from '../core/env';
+
+/** A single hydration mismatch entry returned by `verifyHydration()`. */
+export interface HydrationMismatch {
+  /** The DOM element whose annotation diverged. */
+  element: Element;
+  /** The hash that the server emitted (`data-bq-h` value). */
+  expected: string;
+  /** The hash recomputed from the live element. */
+  actual: string;
+  /** The directive signature that was hashed (useful for diagnostics). */
+  signature: string;
+}
+
+/** Options for `verifyHydration`. */
+export interface VerifyHydrationOptions {
+  /** Directive prefix to match. Default: `'bq'`. */
+  prefix?: string;
+  /**
+   * Whether to log a `console.warn` for each mismatch. Defaults to `true` in
+   * non-production environments and `false` otherwise. Pass an explicit
+   * boolean to override.
+   */
+  warn?: boolean;
+  /** Optional callback invoked once per mismatch. */
+  onMismatch?: (mismatch: HydrationMismatch) => void;
+}
+
+/**
+ * Walks `[data-bq-h]` elements within `root`, recomputes the directive hash
+ * and reports mismatches. Returns the list of mismatches; callers can react
+ * however they want (throw in tests, log in dev, ignore in production).
+ *
+ * Safe to call in any environment. When the runtime has no DOM (server-side)
+ * or `root` has no `querySelectorAll`, the function returns an empty array
+ * without throwing.
+ *
+ * @example
+ * ```ts
+ * import { detectDevEnvironment } from '@bquery/bquery';
+ * import { hydrateMount, verifyHydration } from '@bquery/bquery/ssr';
+ *
+ * const view = hydrateMount('#app', context);
+ * if (detectDevEnvironment()) {
+ *   verifyHydration(document.getElementById('app')!);
+ * }
+ * ```
+ */
+export const verifyHydration = (
+  root: Element | Document,
+  options: VerifyHydrationOptions = {}
+): HydrationMismatch[] => {
+  const prefix = options.prefix ?? 'bq';
+  const warn = options.warn ?? detectDevEnvironment();
+  const onMismatch = options.onMismatch;
+
+  const mismatches: HydrationMismatch[] = [];
+
+  if (!root || typeof (root as Element).querySelectorAll !== 'function') {
+    return mismatches;
+  }
+
+  // Include the root itself if it carries the annotation.
+  const annotated: Element[] = [];
+  if (
+    typeof (root as Element).getAttribute === 'function' &&
+    (root as Element).getAttribute(HYDRATION_HASH_ATTR) !== null
+  ) {
+    annotated.push(root as Element);
+  }
+  for (const el of Array.from(root.querySelectorAll(`[${HYDRATION_HASH_ATTR}]`))) {
+    annotated.push(el);
+  }
+
+  for (const el of annotated) {
+    const expected = el.getAttribute(HYDRATION_HASH_ATTR) ?? '';
+    const signature = collectDirectiveSignatureFromElement(el, prefix);
+    const actual = cheapHash(signature);
+    if (actual !== expected) {
+      const mismatch: HydrationMismatch = { element: el, expected, actual, signature };
+      mismatches.push(mismatch);
+      onMismatch?.(mismatch);
+      if (warn) {
+        console.warn(
+          `[bQuery SSR] Hydration mismatch on <${el.tagName.toLowerCase()}>: ` +
+            `server="${expected}" client="${actual}" signature="${signature}".`,
+          el
+        );
+      }
+    }
+  }
+
+  return mismatches;
+};

package/src/ssr/render-async.ts

@@ -0,0 +1,286 @@
+/**
+ * Async / streaming render entry points.
+ *
+ * Builds on top of the synchronous `renderToString()` and adds:
+ * - `renderToStringAsync()` — awaits Promise/`defer()` values in the context.
+ * - `renderToStream()` — emits the HTML as a Web `ReadableStream<Uint8Array>`.
+ * - `renderToResponse()` — wraps the stream in a `Response` with sensible
+ *   defaults (`Content-Type`, `Cache-Control`, ETag, head injection, store
+ *   state injection).
+ *
+ * All three run on Bun, Deno and Node ≥ 24 without external dependencies.
+ *
+ * @module bquery/ssr
+ */
+
+import type { BindingContext } from '../view/types';
+import { resolveContext } from './async';
+import { createSSRContext, type SSRContext } from './context';
+import { renderToString } from './render';
+import { serializeStoreState } from './serialize';
+import type { RenderOptions, SSRResult } from './types';
+
+const escapeAttr = (value: string): string =>
+  value.replace(/&/g, '&amp;').replace(/"/g, '&quot;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+
+/**
+ * HTML ASCII whitespace used between tag names and attributes. Includes form
+ * feed (`\f`) because the HTML tokenizer treats it as whitespace alongside
+ * spaces, tabs, CR and LF.
+ */
+const isHtmlWhitespace = (ch: string | undefined): boolean =>
+  ch === ' ' || ch === '\n' || ch === '\t' || ch === '\r' || ch === '\f';
+
+const injectScriptNonce = (scriptTag: string, nonce: string): string => {
+  const scriptPrefix = '<script';
+  if (scriptTag.slice(0, scriptPrefix.length).toLowerCase() !== scriptPrefix) {
+    return scriptTag;
+  }
+
+  const next = scriptTag[scriptPrefix.length];
+  if (next !== '>' && !isHtmlWhitespace(next)) {
+    return scriptTag;
+  }
+
+  return `<script nonce="${escapeAttr(nonce)}"${scriptTag.slice(scriptPrefix.length)}`;
+};
+
+/**
+ * Options accepted by the async render APIs. Extends the base `RenderOptions`
+ * with response-shaping switches.
+ */
+export interface AsyncRenderOptions extends RenderOptions {
+  /** Pre-built SSR context. Created automatically if omitted. */
+  context?: SSRContext;
+  /**
+   * Whether to inject the head manager output, asset manifest and store-state
+   * `<script>` tag into the output HTML when the template contains
+   * `</head>`/`</body>` markers. Default: `true`.
+   */
+  injectHead?: boolean;
+  /**
+   * Custom store-state script ID/global key forwarded to `serializeStoreState()`.
+   */
+  storeScriptId?: string;
+  storeGlobalKey?: string;
+}
+
+/** Result of an async render call. */
+export interface AsyncSSRResult extends SSRResult {
+  /** SSR context that produced this result. */
+  context: SSRContext;
+  /** Aggregated head HTML (already injected when `injectHead` is true). */
+  headHtml: string;
+  /** Aggregated asset preload HTML (already injected when `injectHead` is true). */
+  assetsHtml: string;
+  /** `<script>` tag with serialized store state, if any. */
+  storeScriptTag: string;
+}
+
+const injectIntoHead = (html: string, fragment: string): string => {
+  if (!fragment) return html;
+  const idx = html.toLowerCase().indexOf('</head>');
+  if (idx === -1) return html;
+  return html.slice(0, idx) + fragment + html.slice(idx);
+};
+
+const injectBeforeBodyEnd = (html: string, fragment: string): string => {
+  if (!fragment) return html;
+  const idx = html.toLowerCase().lastIndexOf('</body>');
+  if (idx === -1) return html;
+  return html.slice(0, idx) + fragment + html.slice(idx);
+};
+
+/**
+ * Async-aware render. Resolves all `Promise`/`defer()` values in the context,
+ * then delegates to `renderToString()` and applies head/asset/store-state
+ * injection based on the SSR context.
+ */
+export const renderToStringAsync = async (
+  template: string,
+  data: BindingContext,
+  options: AsyncRenderOptions = {}
+): Promise<AsyncSSRResult> => {
+  const context = options.context ?? createSSRContext({ mode: 'string' });
+
+  if (context.signal.aborted) {
+    throw new DOMException('SSR render aborted', 'AbortError');
+  }
+
+  const resolvedData = await resolveContext(data, context);
+
+  if (context.signal.aborted) {
+    throw new DOMException('SSR render aborted', 'AbortError');
+  }
+
+  const baseOptions: RenderOptions = {
+    prefix: options.prefix,
+    stripDirectives: options.stripDirectives,
+    includeStoreState: false,
+    annotateHydration: options.annotateHydration,
+  };
+
+  let { html, storeState } = renderToString(template, resolvedData, baseOptions);
+
+  const headHtml = context.head.render({ nonce: context.nonce });
+  const assetsHtml = context.assets.render({ nonce: context.nonce });
+
+  let storeScriptTag = '';
+  if (options.includeStoreState) {
+    const storeIds = Array.isArray(options.includeStoreState)
+      ? options.includeStoreState
+      : undefined;
+    const result = serializeStoreState({
+      storeIds,
+      scriptId: options.storeScriptId,
+      globalKey: options.storeGlobalKey,
+    });
+    storeState = result.stateJson;
+    storeScriptTag = result.scriptTag;
+    if (context.nonce) {
+      // Inject nonce into the script tag.
+      storeScriptTag = injectScriptNonce(storeScriptTag, context.nonce);
+    }
+  }
+
+  if (options.injectHead !== false) {
+    html = injectIntoHead(html, headHtml + assetsHtml);
+    html = injectBeforeBodyEnd(html, storeScriptTag);
+  }
+
+  return {
+    html,
+    storeState,
+    context,
+    headHtml,
+    assetsHtml,
+    storeScriptTag,
+  };
+};
+
+const getEncoder = (): TextEncoder => {
+  if (typeof TextEncoder === 'undefined') {
+    throw new Error('bQuery SSR: TextEncoder is not available in this runtime.');
+  }
+  return new TextEncoder();
+};
+
+/**
+ * Renders a template into a Web `ReadableStream<Uint8Array>`. The stream is
+ * single-chunk for now (the HTML is fully resolved before flushing) but is
+ * exposed as a stream so adapters can pipe it directly into Bun/Deno/Node
+ * responses without buffering into memory twice.
+ *
+ * Future Suspense-style streaming patches will reuse the same return type.
+ */
+export const renderToStream = (
+  template: string,
+  data: BindingContext,
+  options: AsyncRenderOptions = {}
+): ReadableStream<Uint8Array> => {
+  if (typeof ReadableStream === 'undefined') {
+    throw new Error('bQuery SSR: ReadableStream is not available in this runtime.');
+  }
+
+  const encoder = getEncoder();
+  const ctx = options.context ?? createSSRContext({ ...options, mode: 'stream' });
+  const merged: AsyncRenderOptions = { ...options, context: ctx };
+
+  return new ReadableStream<Uint8Array>({
+    async start(controller) {
+      const onAbort = () => {
+        try {
+          controller.error(new DOMException('SSR stream aborted', 'AbortError'));
+        } catch {
+          /* already closed */
+        }
+      };
+      if (ctx.signal.aborted) {
+        onAbort();
+        return;
+      }
+      ctx.signal.addEventListener('abort', onAbort, { once: true });
+
+      try {
+        const result = await renderToStringAsync(template, data, merged);
+        controller.enqueue(encoder.encode(result.html));
+        controller.close();
+      } catch (error) {
+        ctx.signal.removeEventListener('abort', onAbort);
+        try {
+          controller.error(error);
+        } catch {
+          /* already errored */
+        }
+      } finally {
+        ctx.signal.removeEventListener('abort', onAbort);
+      }
+    },
+  });
+};
+
+const computeWeakEtag = async (text: string): Promise<string | null> => {
+  const subtle = (globalThis as { crypto?: { subtle?: SubtleCrypto } }).crypto?.subtle;
+  if (!subtle) return null;
+  try {
+    const digest = await subtle.digest('SHA-1', getEncoder().encode(text));
+    const bytes = new Uint8Array(digest);
+    let hex = '';
+    for (const b of bytes) hex += b.toString(16).padStart(2, '0');
+    return `W/"${hex.slice(0, 27)}"`;
+  } catch {
+    return null;
+  }
+};
+
+/** Options for `renderToResponse()`. */
+export interface RenderToResponseOptions extends AsyncRenderOptions {
+  /** Override the response status code. */
+  status?: number;
+  /** Override the `Content-Type` header. Default: `text/html; charset=utf-8`. */
+  contentType?: string;
+  /** Set a `Cache-Control` header value. */
+  cacheControl?: string;
+  /** Whether to compute a weak ETag from the rendered HTML. Default: `false`. */
+  etag?: boolean;
+  /** Extra headers merged into the response. */
+  headers?: HeadersInit;
+}
+
+/**
+ * Renders a template and returns a `Response` ready to be returned from a
+ * `fetch`-style handler (`Bun.serve`, `Deno.serve`, Hono, Elysia, etc.).
+ *
+ * Honours `SSRContext.signal` for cancellation and `SSRContext.responseHeaders`
+ * for headers added during the render path.
+ */
+export const renderToResponse = async (
+  template: string,
+  data: BindingContext,
+  options: RenderToResponseOptions = {}
+): Promise<Response> => {
+  const ctx = options.context ?? createSSRContext({ ...options, mode: 'string' });
+  const merged: AsyncRenderOptions = { ...options, context: ctx };
+  const result = await renderToStringAsync(template, data, merged);
+  const status = options.status ?? ctx.status ?? 200;
+
+  const headers = new Headers(options.headers);
+  for (const [k, v] of ctx.responseHeaders) headers.append(k, v);
+  if (!headers.has('content-type')) {
+    headers.set('content-type', options.contentType ?? 'text/html; charset=utf-8');
+  }
+  if (options.cacheControl) headers.set('cache-control', options.cacheControl);
+
+  if (options.etag) {
+    const etag = await computeWeakEtag(result.html);
+    if (etag) {
+      headers.set('etag', etag);
+      const ifNoneMatch = ctx.headers.get('if-none-match');
+      if (ifNoneMatch && ifNoneMatch === etag) {
+        return new Response(null, { status: 304, headers });
+      }
+    }
+  }
+
+  return new Response(result.html, { status, headers });
+};