@canonical/react-ssr 0.22.0 → 0.24.0

package/dist/types/lib/renderer/SitemapRenderer.d.ts

@@ -0,0 +1,153 @@
+import type { PipeableStreamResult, SitemapConfig, SitemapGetter, SitemapItem } from "./types.js";
+/**
+ * Renders an XML sitemap from a set of async data sources.
+ *
+ * Unlike `JSXRenderer`, this renderer produces XML (not HTML) and does not use
+ * React. The render pipeline is functional: each stage returns data rather than
+ * mutating instance state, so calling render methods multiple times produces
+ * identical results for the same underlying data.
+ *
+ * Implements the same three render methods as `JSXRenderer` — `renderToReadableStream`,
+ * `renderToPipeableStream`, and `renderToString` — with the same `statusCode` /
+ * `statusReady` metadata contract. This allows consumers to use either renderer
+ * interchangeably.
+ *
+ * @example
+ * ```ts
+ * const renderer = new SitemapRenderer(
+ *   [() => fetchPages(), () => fetchPosts()],
+ *   { baseUrl: "https://example.com", defaultChangefreq: "weekly" },
+ * );
+ *
+ * const stream = await renderer.renderToReadableStream();
+ * return new Response(stream, {
+ *   status: renderer.statusCode,
+ *   headers: { "Content-Type": "application/xml; charset=utf-8" },
+ * });
+ * ```
+ */
+export default class SitemapRenderer {
+    protected readonly getters: readonly SitemapGetter[];
+    protected readonly config: SitemapConfig;
+    /**
+     * HTTP status code determined during rendering.
+     *
+     * Set to 200 on successful render. Errors from getters propagate as
+     * thrown exceptions rather than setting this to 500 — the consumer's
+     * error handler decides the status code for unexpected failures.
+     */
+    statusCode: number;
+    /**
+     * Resolves when `statusCode` is determined.
+     *
+     * For all three render methods on `SitemapRenderer`, this resolves by
+     * the time the method's returned Promise settles (or synchronously for
+     * the portions that are sync).
+     */
+    statusReady: Promise<void>;
+    /**
+     * Create a sitemap renderer.
+     *
+     * @param getters - Async functions that each return a batch of sitemap items.
+     *   Called concurrently via `Promise.all` during rendering.
+     * @param config - Base URL and optional defaults for changefreq / priority.
+     */
+    constructor(getters: readonly SitemapGetter[], config: SitemapConfig);
+    /**
+     * Load sitemap items from all configured getters.
+     *
+     * Calls every getter concurrently and flattens the results into a single
+     * array. This is the only async step in the pipeline.
+     *
+     * @note This method is impure — it calls external async data sources.
+     * @returns A flat array of raw sitemap items from all getters.
+     */
+    protected loadItems(): Promise<SitemapItem[]>;
+    /**
+     * Resolve URLs and apply defaults to raw sitemap items.
+     *
+     * For each item:
+     * - Relative `loc` values are resolved against `config.baseUrl`. An empty
+     *   `loc` resolves to the base URL itself.
+     * - `lastmod` dates are formatted to `YYYY-MM-DD` (ISO 8601 date-only).
+     * - Missing `changefreq` and `priority` are filled from `config` defaults.
+     *
+     * @param items - Raw items as returned by `loadItems`.
+     * @returns A new array of items with resolved URLs and applied defaults.
+     */
+    protected formatItems(items: readonly SitemapItem[]): SitemapItem[];
+    /**
+     * Format a `Date` object or ISO string to a `YYYY-MM-DD` date string.
+     *
+     * The Sitemaps protocol specifies W3C Datetime format; the date-only
+     * variant (`YYYY-MM-DD`) is the most common form used in practice.
+     *
+     * @param date - A `Date` instance or an ISO 8601 date/datetime string.
+     * @returns The date formatted as `YYYY-MM-DD`.
+     */
+    protected static formatDate(date: Date | string): string;
+    /**
+     * Escape the five XML special characters in a string.
+     *
+     * Prevents malformed XML when interpolating user-supplied URLs that may
+     * contain `&` (common in query strings), `<`, `>`, `"`, or `'`.
+     *
+     * @param value - The raw string to escape.
+     * @returns The string with `&`, `<`, `>`, `"`, and `'` replaced by their XML entities.
+     */
+    protected static escapeXml(value: string): string;
+    /**
+     * Serialise a list of formatted sitemap items into an XML sitemap string.
+     *
+     * Produces a complete `<?xml>` document with a `<urlset>` root element
+     * conforming to the Sitemaps 0.9 schema. Only non-null optional fields
+     * (`lastmod`, `changefreq`, `priority`) are included in the output.
+     *
+     * @param items - Formatted items (URLs resolved, dates formatted).
+     * @returns The complete XML sitemap as a string.
+     */
+    protected toXml(items: readonly SitemapItem[]): string;
+    /**
+     * Build the full XML string by loading items, applying formatting, and
+     * serialising to XML.
+     */
+    protected buildXml(): Promise<string>;
+    /**
+     * Render the sitemap to a web `ReadableStream`.
+     *
+     * Loads items from all getters, formats them, serialises to XML, and
+     * wraps the result in a `ReadableStream`. Sets `statusCode` to 200.
+     *
+     * @note This method is impure — it calls external data sources and mutates `statusCode`.
+     *
+     * @param _signal - Accepted for API compatibility with `JSXRenderer`. Not used.
+     * @returns A `ReadableStream` of the XML sitemap.
+     */
+    renderToReadableStream: (_signal?: AbortSignal) => Promise<ReadableStream>;
+    /**
+     * Render the sitemap to a Node.js pipeable stream.
+     *
+     * Returns `{ pipe, abort }` synchronously. The actual XML generation is
+     * async (getters are called), so data is pushed to the stream when ready.
+     * `statusReady` resolves when the XML is built and `statusCode` is set.
+     *
+     * @note This method is impure — it calls external data sources and mutates `statusCode`.
+     *
+     * @returns The pipe/abort handles for the XML stream.
+     */
+    renderToPipeableStream: () => PipeableStreamResult;
+    /**
+     * Render the sitemap to a complete XML string.
+     *
+     * Loads items from all getters, formats them, and returns the serialised
+     * XML. Sets `statusCode` to 200.
+     *
+     * Async because the getters are async.
+     *
+     * @note This method is impure — it calls external data sources and mutates `statusCode`.
+     *
+     * @returns The complete XML sitemap string.
+     */
+    renderToString: () => Promise<string>;
+}
+//# sourceMappingURL=SitemapRenderer.d.ts.map

package/dist/types/lib/renderer/SitemapRenderer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SitemapRenderer.d.ts","sourceRoot":"","sources":["../../../../src/lib/renderer/SitemapRenderer.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,oBAAoB,EACpB,aAAa,EACb,aAAa,EACb,WAAW,EACZ,MAAM,YAAY,CAAC;AAEpB;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,CAAC,OAAO,OAAO,eAAe;IA2BhC,SAAS,CAAC,QAAQ,CAAC,OAAO,EAAE,SAAS,aAAa,EAAE;IACpD,SAAS,CAAC,QAAQ,CAAC,MAAM,EAAE,aAAa;IA3B1C;;;;;;OAMG;IACI,UAAU,SAAO;IAExB;;;;;;OAMG;IACI,WAAW,EAAE,OAAO,CAAC,IAAI,CAAC,CAAqB;IAEtD;;;;;;OAMG;gBAEkB,OAAO,EAAE,SAAS,aAAa,EAAE,EACjC,MAAM,EAAE,aAAa;IAG1C;;;;;;;;OAQG;cACa,SAAS,IAAI,OAAO,CAAC,WAAW,EAAE,CAAC;IAKnD;;;;;;;;;;;OAWG;IACH,SAAS,CAAC,WAAW,CAAC,KAAK,EAAE,SAAS,WAAW,EAAE,GAAG,WAAW,EAAE;IAcnE;;;;;;;;OAQG;IACH,SAAS,CAAC,MAAM,CAAC,UAAU,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM,GAAG,MAAM;IAKxD;;;;;;;;OAQG;IACH,SAAS,CAAC,MAAM,CAAC,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM;IASjD;;;;;;;;;OASG;IACH,SAAS,CAAC,KAAK,CAAC,KAAK,EAAE,SAAS,WAAW,EAAE,GAAG,MAAM;IA6BtD;;;OAGG;cACa,QAAQ,IAAI,OAAO,CAAC,MAAM,CAAC;IAM3C;;;;;;;;;;OAUG;IACH,sBAAsB,GACpB,UAAU,WAAW,KACpB,OAAO,CAAC,cAAc,CAAC,CAWxB;IAEF;;;;;;;;;;OAUG;IACH,sBAAsB,QAAO,oBAAoB,CAqB/C;IAEF;;;;;;;;;;;OAWG;IACH,cAAc,QAAa,OAAO,CAAC,MAAM,CAAC,CAKxC;CACH"}

package/dist/types/lib/renderer/TextRenderer.d.ts

@@ -0,0 +1,83 @@
+import type { PipeableStreamResult, TextGetter } from "./types.js";
+/**
+ * Renders a plain-text document from async data sources.
+ *
+ * Produces output suitable for `llms.txt`, `humans.txt`, `security.txt`, or
+ * any text file that requires dynamic data (e.g. fetching page descriptions
+ * from a CMS for an LLM context file).
+ *
+ * The renderer is intentionally minimal — it accepts an array of async getters,
+ * each returning a string, and concatenates the results. No structure is imposed.
+ * The consumer controls formatting entirely.
+ *
+ * Implements the same three render methods and `statusCode` / `statusReady`
+ * contract as `JSXRenderer` and `SitemapRenderer`.
+ *
+ * @example
+ * ```ts
+ * const renderer = new TextRenderer([
+ *   async () => "# My App\n\nContext for LLMs about this application.\n",
+ *   async () => {
+ *     const pages = await fetchPages();
+ *     return pages.map(p => `- ${p.title}: ${p.url}`).join("\n");
+ *   },
+ * ]);
+ *
+ * const stream = await renderer.renderToReadableStream();
+ * return new Response(stream, {
+ *   status: renderer.statusCode,
+ *   headers: { "Content-Type": "text/plain; charset=utf-8" },
+ * });
+ * ```
+ */
+export default class TextRenderer {
+    protected readonly getters: readonly TextGetter[];
+    /**
+     * HTTP status code determined during rendering.
+     *
+     * Set to 200 on successful render. Errors from getters propagate as
+     * thrown exceptions — the consumer's error handler decides the status code.
+     */
+    statusCode: number;
+    /**
+     * Resolves when `statusCode` is determined.
+     */
+    statusReady: Promise<void>;
+    /**
+     * Create a text renderer.
+     *
+     * @param getters - Async functions that each return a string. Called
+     *   sequentially (order matters) and concatenated into the final document.
+     */
+    constructor(getters: readonly TextGetter[]);
+    /**
+     * Build the full text by calling all getters sequentially and concatenating.
+     */
+    protected buildText(): Promise<string>;
+    /**
+     * Render to a web `ReadableStream`.
+     *
+     * @note This method is impure — it calls external data sources and mutates `statusCode`.
+     *
+     * @param _signal - Accepted for API compatibility. Not used.
+     * @returns A `ReadableStream` of the plain-text document.
+     */
+    renderToReadableStream: (_signal?: AbortSignal) => Promise<ReadableStream>;
+    /**
+     * Render to a Node.js pipeable stream.
+     *
+     * Returns `{ pipe, abort }` synchronously. Data is pushed when ready.
+     *
+     * @note This method is impure — it calls external data sources and mutates `statusCode`.
+     */
+    renderToPipeableStream: () => PipeableStreamResult;
+    /**
+     * Render to a complete string.
+     *
+     * Async because the getters are async.
+     *
+     * @note This method is impure — it calls external data sources and mutates `statusCode`.
+     */
+    renderToString: () => Promise<string>;
+}
+//# sourceMappingURL=TextRenderer.d.ts.map

package/dist/types/lib/renderer/TextRenderer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TextRenderer.d.ts","sourceRoot":"","sources":["../../../../src/lib/renderer/TextRenderer.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,oBAAoB,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAEnE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,MAAM,CAAC,OAAO,OAAO,YAAY;IAoBnB,SAAS,CAAC,QAAQ,CAAC,OAAO,EAAE,SAAS,UAAU,EAAE;IAnB7D;;;;;OAKG;IACI,UAAU,SAAO;IAExB;;OAEG;IACI,WAAW,EAAE,OAAO,CAAC,IAAI,CAAC,CAAqB;IAEtD;;;;;OAKG;gBAC4B,OAAO,EAAE,SAAS,UAAU,EAAE;IAE7D;;OAEG;cACa,SAAS,IAAI,OAAO,CAAC,MAAM,CAAC;IAQ5C;;;;;;;OAOG;IACH,sBAAsB,GACpB,UAAU,WAAW,KACpB,OAAO,CAAC,cAAc,CAAC,CAWxB;IAEF;;;;;;OAMG;IACH,sBAAsB,QAAO,oBAAoB,CAqB/C;IAEF;;;;;;OAMG;IACH,cAAc,QAAa,OAAO,CAAC,MAAM,CAAC,CAKxC;CACH"}

package/dist/types/lib/renderer/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../../../src/lib/renderer/constants.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,gBAAgB,qBAAqB,CAAC"}

package/dist/types/lib/renderer/index.d.ts

@@ -0,0 +1,7 @@
+export * from "./constants.js";
+export { default as Extractor } from "./Extractor.js";
+export { default as JSXRenderer } from "./JSXRenderer.js";
+export { default as SitemapRenderer } from "./SitemapRenderer.js";
+export { default as TextRenderer } from "./TextRenderer.js";
+export type { PipeableStreamResult, RendererOptions, ServerEntrypoint, ServerEntrypointProps, SitemapConfig, SitemapGetter, SitemapItem, TextGetter, } from "./types.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/types/lib/renderer/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/lib/renderer/index.ts"],"names":[],"mappings":"AAAA,cAAc,gBAAgB,CAAC;AAC/B,OAAO,EAAE,OAAO,IAAI,SAAS,EAAE,MAAM,gBAAgB,CAAC;AACtD,OAAO,EAAE,OAAO,IAAI,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC1D,OAAO,EAAE,OAAO,IAAI,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAClE,OAAO,EAAE,OAAO,IAAI,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAC5D,YAAY,EACV,oBAAoB,EACpB,eAAe,EACf,gBAAgB,EAChB,qBAAqB,EACrB,aAAa,EACb,aAAa,EACb,WAAW,EACX,UAAU,GACX,MAAM,YAAY,CAAC"}

package/dist/types/lib/renderer/types.d.ts

@@ -0,0 +1,161 @@
+/**
+ * Shared type contracts for the SSR renderer domain.
+ *
+ * These types define the interface between renderers (which produce HTML or XML
+ * content and record metadata like status codes) and server adapters (which
+ * deliver that content over HTTP). Renderers are transport-agnostic — they
+ * never write to a response object.
+ */
+import type * as React from "react";
+import type { RenderToPipeableStreamOptions, RenderToReadableStreamOptions } from "react-dom/server";
+/**
+ * The pipe/abort handles returned by `renderToPipeableStream`.
+ *
+ * Mirrors the shape of React's `PipeableStream` but decoupled from the
+ * `react-dom/server` import so consumers don't need to depend on it directly.
+ */
+export interface PipeableStreamResult {
+    /** Pipe the rendered HTML to a Node.js writable stream (e.g. `ServerResponse`). */
+    pipe: <W extends NodeJS.WritableStream>(destination: W) => W;
+    /** Abort the in-progress render. */
+    abort: (reason?: unknown) => void;
+}
+/**
+ * Configuration for a `JSXRenderer` instance.
+ *
+ * Controls locale, HTML shell extraction, and options forwarded to
+ * React's streaming APIs.
+ */
+export interface RendererOptions {
+    /**
+     * Locale for the rendered page, passed as the `lang` prop to the server
+     * entrypoint component. Defaults to `"en"` when omitted.
+     */
+    defaultLocale?: string;
+    /**
+     * A full HTML string (typically from a Vite build) whose `<head>` tags
+     * are extracted and injected into the rendered output. When omitted,
+     * the renderer produces output without extracted head elements.
+     */
+    htmlString?: string;
+    /**
+     * Options forwarded to `react-dom/server.renderToPipeableStream`.
+     *
+     * The renderer merges its own `bootstrapScriptContent`, `bootstrapScripts`,
+     * and `bootstrapModules` into these options, but user-provided values take
+     * priority and are never overwritten.
+     */
+    renderToPipeableStreamOptions?: RenderToPipeableStreamOptions;
+    /**
+     * Options forwarded to `react-dom/server.renderToReadableStream`.
+     *
+     * Same merge semantics as `renderToPipeableStreamOptions`. When omitted,
+     * the shared bootstrap options from `renderToPipeableStreamOptions` are
+     * used as a fallback (the bootstrap fields are structurally identical
+     * between the two option types).
+     */
+    renderToReadableStreamOptions?: RenderToReadableStreamOptions;
+}
+/**
+ * Props received by the server entrypoint component during SSR.
+ *
+ * The renderer assembles these from the locale, the extracted HTML head elements
+ * (when an HTML shell is provided), and the initial data for hydration.
+ *
+ * @typeParam InitialData - Shape of the hydration data embedded in the page.
+ */
+export interface ServerEntrypointProps<InitialData extends Record<string, unknown>> {
+    /** BCP 47 language tag for the page (e.g. `"en"`, `"fr-CA"`). */
+    lang?: string;
+    /**
+     * `<script>` elements extracted from the HTML shell, as React elements.
+     * Undefined when no HTML shell was provided.
+     */
+    scriptElements?: React.ReactElement[];
+    /**
+     * `<link>` elements extracted from the HTML shell, as React elements.
+     * Undefined when no HTML shell was provided.
+     */
+    linkElements?: React.ReactElement[];
+    /**
+     * `<title>`, `<meta>`, `<style>`, and `<base>` elements from the HTML shell,
+     * as React elements. Undefined when no HTML shell was provided.
+     */
+    otherHeadElements?: React.ReactElement[];
+    /**
+     * Data to embed in `window.__INITIAL_DATA__` for client hydration.
+     *
+     * The renderer serialises this object as JSON in a `<script>` tag so that the
+     * client can read it during hydration without a second network request. The
+     * JSON is escaped to prevent `</script>` injection.
+     */
+    initialData?: InitialData;
+}
+/**
+ * A React component used as the server-side rendering entry point.
+ *
+ * Receives `ServerEntrypointProps` and is expected to render the full `<html>`
+ * document, including the extracted head elements and initial data.
+ *
+ * @typeParam InitialData - Shape of the hydration data embedded in the page.
+ */
+export type ServerEntrypoint<InitialData extends Record<string, unknown>> = React.ComponentType<ServerEntrypointProps<InitialData>>;
+/**
+ * A single URL entry in an XML sitemap.
+ *
+ * Follows the Sitemaps XML protocol: https://www.sitemaps.org/protocol.html.
+ * All fields except `loc` are optional — the renderer applies defaults from
+ * `SitemapConfig` for `changefreq` and `priority`.
+ */
+export interface SitemapItem {
+    /**
+     * URL of the page. Can be absolute (`https://example.com/about`) or relative
+     * (`/about`). Relative URLs are resolved against `SitemapConfig.baseUrl`.
+     * An empty string resolves to the base URL itself.
+     */
+    loc: string;
+    /**
+     * Date of last modification. Accepts a `Date` object or an ISO 8601 string.
+     * Formatted to `YYYY-MM-DD` in the output XML.
+     */
+    lastmod?: Date | string;
+    /** How frequently the page is likely to change. */
+    changefreq?: "always" | "hourly" | "daily" | "weekly" | "monthly" | "yearly" | "never";
+    /**
+     * Priority of this URL relative to other URLs on the site.
+     * Valid range is `0.0` to `1.0`. Default is `0.5` per the protocol.
+     */
+    priority?: number;
+}
+/**
+ * An async function that produces a batch of sitemap items.
+ *
+ * The `SitemapRenderer` accepts an array of getters, calls them concurrently
+ * via `Promise.all`, and flattens the results into a single item list.
+ */
+export type SitemapGetter = () => Promise<SitemapItem[]>;
+/**
+ * Configuration for the `SitemapRenderer`.
+ *
+ * Defines the canonical base URL used to resolve relative `loc` values,
+ * and optional defaults applied to items that omit `changefreq` or `priority`.
+ */
+export interface SitemapConfig {
+    /**
+     * The canonical base URL for the site (e.g. `"https://example.com"`).
+     * Used to resolve relative `loc` values in sitemap items.
+     */
+    baseUrl: string;
+    /** Default `changefreq` applied to items that do not specify one. */
+    defaultChangefreq?: SitemapItem["changefreq"];
+    /** Default `priority` applied to items that do not specify one (0.0 to 1.0). */
+    defaultPriority?: number;
+}
+/**
+ * An async function that produces a string of text content.
+ *
+ * The `TextRenderer` accepts an array of getters, calls them sequentially
+ * (order matters for document structure), and concatenates the results.
+ */
+export type TextGetter = () => Promise<string>;
+//# sourceMappingURL=types.d.ts.map

package/dist/types/lib/renderer/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../src/lib/renderer/types.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,KAAK,KAAK,MAAM,OAAO,CAAC;AACpC,OAAO,KAAK,EACV,6BAA6B,EAC7B,6BAA6B,EAC9B,MAAM,kBAAkB,CAAC;AAI1B;;;;;GAKG;AACH,MAAM,WAAW,oBAAoB;IACnC,mFAAmF;IACnF,IAAI,EAAE,CAAC,CAAC,SAAS,MAAM,CAAC,cAAc,EAAE,WAAW,EAAE,CAAC,KAAK,CAAC,CAAC;IAC7D,oCAAoC;IACpC,KAAK,EAAE,CAAC,MAAM,CAAC,EAAE,OAAO,KAAK,IAAI,CAAC;CACnC;AAID;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC9B;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IAEvB;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB;;;;;;OAMG;IACH,6BAA6B,CAAC,EAAE,6BAA6B,CAAC;IAE9D;;;;;;;OAOG;IACH,6BAA6B,CAAC,EAAE,6BAA6B,CAAC;CAC/D;AAID;;;;;;;GAOG;AACH,MAAM,WAAW,qBAAqB,CACpC,WAAW,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAE3C,iEAAiE;IACjE,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd;;;OAGG;IACH,cAAc,CAAC,EAAE,KAAK,CAAC,YAAY,EAAE,CAAC;IAEtC;;;OAGG;IACH,YAAY,CAAC,EAAE,KAAK,CAAC,YAAY,EAAE,CAAC;IAEpC;;;OAGG;IACH,iBAAiB,CAAC,EAAE,KAAK,CAAC,YAAY,EAAE,CAAC;IAEzC;;;;;;OAMG;IACH,WAAW,CAAC,EAAE,WAAW,CAAC;CAC3B;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,gBAAgB,CAAC,WAAW,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,IACtE,KAAK,CAAC,aAAa,CAAC,qBAAqB,CAAC,WAAW,CAAC,CAAC,CAAC;AAI1D;;;;;;GAMG;AACH,MAAM,WAAW,WAAW;IAC1B;;;;OAIG;IACH,GAAG,EAAE,MAAM,CAAC;IAEZ;;;OAGG;IACH,OAAO,CAAC,EAAE,IAAI,GAAG,MAAM,CAAC;IAExB,mDAAmD;IACnD,UAAU,CAAC,EACP,QAAQ,GACR,QAAQ,GACR,OAAO,GACP,QAAQ,GACR,SAAS,GACT,QAAQ,GACR,OAAO,CAAC;IAEZ;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;;GAKG;AACH,MAAM,MAAM,aAAa,GAAG,MAAM,OAAO,CAAC,WAAW,EAAE,CAAC,CAAC;AAEzD;;;;;GAKG;AACH,MAAM,WAAW,aAAa;IAC5B;;;OAGG;IACH,OAAO,EAAE,MAAM,CAAC;IAEhB,qEAAqE;IACrE,iBAAiB,CAAC,EAAE,WAAW,CAAC,YAAY,CAAC,CAAC;IAE9C,gFAAgF;IAChF,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAID;;;;;GAKG;AACH,MAAM,MAAM,UAAU,GAAG,MAAM,OAAO,CAAC,MAAM,CAAC,CAAC"}

package/dist/types/lib/server/index.d.ts

@@ -0,0 +1,3 @@
+export { serveStream } from "./serveStream.js";
+export { serveString } from "./serveString.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/types/lib/server/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/lib/server/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC/C,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/types/lib/server/serveStream.d.ts

@@ -0,0 +1,41 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+/**
+ * Convenience wrapper that adapts a renderer factory into a Node.js `(req, res)` handler
+ * for pipeable stream rendering.
+ *
+ * Calls the factory with each incoming request. The factory is expected to construct
+ * a renderer (with per-request context like locale, auth, theme) and call
+ * `renderToPipeableStream()` on it. This wrapper then awaits `statusReady`, writes
+ * headers with the renderer's `statusCode`, and pipes the stream to the response.
+ *
+ * Does not set `Content-Type` — the consumer controls headers through the factory
+ * or by wrapping this handler. Defaults to `text/html; charset=utf-8`.
+ *
+ * @note This function is impure — it writes to the HTTP response.
+ *
+ * @param factory - A function that receives the request and returns a renderer.
+ *   The renderer must have `renderToPipeableStream()`, `statusCode`, and `statusReady`.
+ * @returns A Node.js request handler suitable for `app.use()` or `http.createServer()`.
+ *
+ * @example
+ * ```ts
+ * import { JSXRenderer } from "@canonical/react-ssr/renderer";
+ * import { serveStream } from "@canonical/react-ssr/server";
+ *
+ * app.use(serveStream((req) => {
+ *   return new JSXRenderer(
+ *     EntryServer,
+ *     { locale: getLocale(req), user: getUser(req) },
+ *     { htmlString },
+ *   );
+ * }));
+ * ```
+ */
+export declare function serveStream(factory: (req: IncomingMessage) => {
+    renderToPipeableStream: () => {
+        pipe: <W extends NodeJS.WritableStream>(destination: W) => W;
+    };
+    statusCode: number;
+    statusReady: Promise<void>;
+}): (req: IncomingMessage, res: ServerResponse) => Promise<void>;
+//# sourceMappingURL=serveStream.d.ts.map

package/dist/types/lib/server/serveStream.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"serveStream.d.ts","sourceRoot":"","sources":["../../../../src/lib/server/serveStream.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAEjE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,WAAW,CACzB,OAAO,EAAE,CAAC,GAAG,EAAE,eAAe,KAAK;IACjC,sBAAsB,EAAE,MAAM;QAC5B,IAAI,EAAE,CAAC,CAAC,SAAS,MAAM,CAAC,cAAc,EAAE,WAAW,EAAE,CAAC,KAAK,CAAC,CAAC;KAC9D,CAAC;IACF,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;CAC5B,IAEa,KAAK,eAAe,EAAE,KAAK,cAAc,mBAiBxD"}

package/dist/types/lib/server/serveString.d.ts

@@ -0,0 +1,37 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+/**
+ * Convenience wrapper that adapts a renderer factory into a Node.js `(req, res)` handler
+ * for string rendering.
+ *
+ * Calls the factory with each incoming request. The factory is expected to construct
+ * a renderer (with per-request context like locale, auth, theme) and call
+ * `renderToString()` on it. This wrapper then writes headers with the renderer's
+ * `statusCode` and sends the HTML string as the response body.
+ *
+ * Does not set `Content-Type` — defaults to `text/html; charset=utf-8`.
+ *
+ * @note This function is impure — it writes to the HTTP response.
+ *
+ * @param factory - A function that receives the request and returns a renderer.
+ *   The renderer must have `renderToString()` and `statusCode`.
+ * @returns A Node.js request handler suitable for `app.use()` or `http.createServer()`.
+ *
+ * @example
+ * ```ts
+ * import { JSXRenderer } from "@canonical/react-ssr/renderer";
+ * import { serveString } from "@canonical/react-ssr/server";
+ *
+ * app.use(serveString((req) => {
+ *   return new JSXRenderer(
+ *     EntryServer,
+ *     { locale: getLocale(req), user: getUser(req) },
+ *     { htmlString },
+ *   );
+ * }));
+ * ```
+ */
+export declare function serveString(factory: (req: IncomingMessage) => {
+    renderToString: () => string;
+    statusCode: number;
+}): (req: IncomingMessage, res: ServerResponse) => void;
+//# sourceMappingURL=serveString.d.ts.map

package/dist/types/lib/server/serveString.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"serveString.d.ts","sourceRoot":"","sources":["../../../../src/lib/server/serveString.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAEjE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAgB,WAAW,CACzB,OAAO,EAAE,CAAC,GAAG,EAAE,eAAe,KAAK;IACjC,cAAc,EAAE,MAAM,MAAM,CAAC;IAC7B,UAAU,EAAE,MAAM,CAAC;CACpB,IAEO,KAAK,eAAe,EAAE,KAAK,cAAc,UAclD"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@canonical/react-ssr",
   "description": "TBD",
-  "version": "0.22.0",
+  "version": "0.24.0",
   "type": "module",
   "module": "dist/esm/index.js",
   "types": "dist/types/index.d.ts",
@@ -13,7 +13,8 @@
     "name": "Canonical Webteam"
   },
   "bin": {
-    "serve-express": "./dist/esm/server/serve-express.js"
+    "serve-express": "./dist/esm/bin/serve-express.js",
+    "serve-bun": "./dist/esm/bin/serve-bun.js"
   },
   "repository": {
     "type": "git",
@@ -24,6 +25,11 @@
     "url": "https://github.com/canonical/pragma/issues"
   },
   "homepage": "https://github.com/canonical/pragma#readme",
+  "imports": {
+    "#adapter": "./src/lib/adapter/index.ts",
+    "#renderer": "./src/lib/renderer/index.ts",
+    "#server": "./src/lib/server/index.ts"
+  },
   "scripts": {
     "build": "tsc -p tsconfig.build.json",
     "build:all": "tsc -p tsconfig.build.json",
@@ -33,7 +39,9 @@
     "check:biome": "biome check",
     "check:biome:fix": "biome check --write",
     "check:ts": "tsc --noEmit",
-    "test": "echo 'No tests defined yet'"
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage"
   },
   "exports": {
     ".": {
@@ -41,36 +49,48 @@
       "types": "./dist/types/index.d.ts"
     },
     "./renderer": {
-      "import": "./dist/esm/renderer/index.js",
-      "types": "./dist/types/renderer/index.d.ts"
+      "import": "./dist/esm/lib/renderer/index.js",
+      "types": "./dist/types/lib/renderer/index.d.ts"
     },
     "./renderer/constants": {
-      "import": "./dist/esm/renderer/constants.js",
-      "types": "./dist/types/renderer/constants.d.ts"
+      "import": "./dist/esm/lib/renderer/constants.js",
+      "types": "./dist/types/lib/renderer/constants.d.ts"
     },
     "./server": {
-      "import": "./dist/esm/server/index.js",
-      "types": "./dist/types/server/index.d.ts"
+      "import": "./dist/esm/lib/server/index.js",
+      "types": "./dist/types/lib/server/index.d.ts"
+    },
+    "./adapter": {
+      "import": "./dist/esm/lib/adapter/index.js",
+      "types": "./dist/types/lib/adapter/index.d.ts"
     }
   },
   "devDependencies": {
     "@biomejs/biome": "2.4.9",
-    "@canonical/biome-config": "^0.22.0",
-    "@canonical/typescript-config-react": "^0.22.0",
-    "@canonical/webarchitect": "^0.22.0",
+    "@canonical/biome-config": "^0.24.0",
+    "@canonical/typescript-config-react": "^0.24.0",
+    "@canonical/webarchitect": "^0.24.0",
     "@types/express": "^5.0.6",
     "@types/node": "^24.12.0",
     "@types/react": "^19.2.14",
     "@types/react-dom": "^19.2.3",
-    "typescript": "^5.9.3"
+    "@vitest/coverage-v8": "^4.0.18",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.18"
   },
   "dependencies": {
-    "@canonical/utils": "^0.22.0",
-    "domhandler": "^6.0.0",
-    "express": "^5.2.1",
+    "@canonical/utils": "^0.24.0",
     "htmlparser2": "^10.1.0",
     "react": "^19.2.4",
     "react-dom": "^19.2.4"
   },
-  "gitHead": "99e187cf46d8bd7f3933705322fa4ab2d4a711e7"
+  "peerDependencies": {
+    "express": "^5.2.1"
+  },
+  "peerDependenciesMeta": {
+    "express": {
+      "optional": true
+    }
+  },
+  "gitHead": "28565e3591ad80525b62bd7be6343d1f12ebf4d0"
 }