@canonical/react-ssr 0.22.0 → 0.24.0

package/dist/esm/lib/renderer/index.js

@@ -0,0 +1,6 @@
+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";
+//# sourceMappingURL=index.js.map

package/dist/esm/lib/renderer/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","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"}

package/dist/esm/lib/renderer/types.js

@@ -0,0 +1,10 @@
+/**
+ * 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.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/esm/lib/renderer/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../../src/lib/renderer/types.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG"}

package/dist/esm/lib/server/index.js

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

package/dist/esm/lib/server/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","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/esm/lib/server/serveStream.js

@@ -0,0 +1,53 @@
+/**
+ * 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 function serveStream(factory) {
+    return async (req, res) => {
+        try {
+            const renderer = factory(req);
+            const result = renderer.renderToPipeableStream();
+            await renderer.statusReady;
+            res.writeHead(renderer.statusCode, {
+                "Content-Type": "text/html; charset=utf-8",
+            });
+            result.pipe(res);
+            /* v8 ignore next -- finish event fires after stream completes; not triggered in unit tests */
+            res.on("finish", () => res.end());
+        }
+        catch (error) {
+            console.error("Error during rendering:", error);
+            res.statusCode = 500;
+            res.end("Internal server error");
+        }
+    };
+}
+//# sourceMappingURL=serveStream.js.map

package/dist/esm/lib/server/serveStream.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"serveStream.js","sourceRoot":"","sources":["../../../../src/lib/server/serveStream.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,MAAM,UAAU,WAAW,CACzB,OAMC;IAED,OAAO,KAAK,EAAE,GAAoB,EAAE,GAAmB,EAAE,EAAE;QACzD,IAAI,CAAC;YACH,MAAM,QAAQ,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;YAC9B,MAAM,MAAM,GAAG,QAAQ,CAAC,sBAAsB,EAAE,CAAC;YACjD,MAAM,QAAQ,CAAC,WAAW,CAAC;YAC3B,GAAG,CAAC,SAAS,CAAC,QAAQ,CAAC,UAAU,EAAE;gBACjC,cAAc,EAAE,0BAA0B;aAC3C,CAAC,CAAC;YACH,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;YACjB,8FAA8F;YAC9F,GAAG,CAAC,EAAE,CAAC,QAAQ,EAAE,GAAG,EAAE,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,CAAC;QACpC,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,OAAO,CAAC,KAAK,CAAC,yBAAyB,EAAE,KAAK,CAAC,CAAC;YAChD,GAAG,CAAC,UAAU,GAAG,GAAG,CAAC;YACrB,GAAG,CAAC,GAAG,CAAC,uBAAuB,CAAC,CAAC;QACnC,CAAC;IACH,CAAC,CAAC;AACJ,CAAC"}

package/dist/esm/lib/server/serveString.js

@@ -0,0 +1,49 @@
+/**
+ * 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 function serveString(factory) {
+    return (req, res) => {
+        try {
+            const renderer = factory(req);
+            const body = renderer.renderToString();
+            res.writeHead(renderer.statusCode, {
+                "Content-Type": "text/html; charset=utf-8",
+            });
+            res.end(body);
+        }
+        catch (error) {
+            console.error("Error during rendering:", error);
+            res.statusCode = 500;
+            res.end("Internal server error");
+        }
+    };
+}
+//# sourceMappingURL=serveString.js.map

package/dist/esm/lib/server/serveString.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"serveString.js","sourceRoot":"","sources":["../../../../src/lib/server/serveString.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,MAAM,UAAU,WAAW,CACzB,OAGC;IAED,OAAO,CAAC,GAAoB,EAAE,GAAmB,EAAE,EAAE;QACnD,IAAI,CAAC;YACH,MAAM,QAAQ,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;YAC9B,MAAM,IAAI,GAAG,QAAQ,CAAC,cAAc,EAAE,CAAC;YACvC,GAAG,CAAC,SAAS,CAAC,QAAQ,CAAC,UAAU,EAAE;gBACjC,cAAc,EAAE,0BAA0B;aAC3C,CAAC,CAAC;YACH,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QAChB,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,OAAO,CAAC,KAAK,CAAC,yBAAyB,EAAE,KAAK,CAAC,CAAC;YAChD,GAAG,CAAC,UAAU,GAAG,GAAG,CAAC;YACrB,GAAG,CAAC,GAAG,CAAC,uBAAuB,CAAC,CAAC;QACnC,CAAC;IACH,CAAC,CAAC;AACJ,CAAC"}

package/dist/types/bin/serve-express.d.ts

@@ -0,0 +1,24 @@
+#!/usr/bin/env node
+/**
+ * Standalone Express server for serving an SSR application.
+ *
+ * Dynamically imports a renderer module that exports a factory function.
+ * The factory receives a Node `IncomingMessage` and returns a renderer.
+ * Supports both streaming and string rendering modes.
+ *
+ * @example
+ * ```sh
+ * # String rendering (default), one static directory
+ * serve-express dist/server/renderer.js --static assets:dist/client/assets
+ *
+ * # Streaming, multiple static directories
+ * serve-express dist/server/renderer.js --streaming \
+ *   --static assets:dist/client/assets \
+ *   --static public:dist/client/public
+ *
+ * # Custom port
+ * serve-express dist/server/renderer.js -p 3000 --static assets:dist/client/assets
+ * ```
+ */
+export {};
+//# sourceMappingURL=serve-express.d.ts.map

package/dist/types/bin/serve-express.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"serve-express.d.ts","sourceRoot":"","sources":["../../../src/bin/serve-express.ts"],"names":[],"mappings":";AAEA;;;;;;;;;;;;;;;;;;;;GAoBG"}

package/dist/types/index.d.ts

@@ -1,3 +1,4 @@
-export * as renderer from "./renderer/index.js";
-export * as server from "./server/index.js";
+export * as adapter from "./lib/adapter/index.js";
+export * as renderer from "./lib/renderer/index.js";
+export * as server from "./lib/server/index.js";
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,QAAQ,MAAM,qBAAqB,CAAC;AAChD,OAAO,KAAK,MAAM,MAAM,mBAAmB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,OAAO,MAAM,wBAAwB,CAAC;AAClD,OAAO,KAAK,QAAQ,MAAM,yBAAyB,CAAC;AACpD,OAAO,KAAK,MAAM,MAAM,uBAAuB,CAAC"}

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

@@ -0,0 +1,3 @@
+export { buildCacheControl, getMimeType, matchPattern } from "./mime.js";
+export type { CacheConfig, RendererFactory, RendererResult, RouteDefinition, StaticAssetConfig, } from "./types.js";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/lib/adapter/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AACzE,YAAY,EACV,WAAW,EACX,eAAe,EACf,cAAc,EACd,eAAe,EACf,iBAAiB,GAClB,MAAM,YAAY,CAAC"}

package/dist/types/lib/adapter/mime.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Minimal MIME type lookup for static asset serving.
+ *
+ * Covers the file types commonly produced by Vite builds (scripts, styles,
+ * images, fonts, source maps). Adapters use this when the platform doesn't
+ * provide native MIME detection (Cloudflare R2, Deno filesystem).
+ *
+ * No external dependencies — the lookup is a plain record.
+ */
+/**
+ * Look up the MIME type for a file path based on its extension.
+ *
+ * Returns `"application/octet-stream"` for unknown extensions.
+ *
+ * @param path - File path or name (e.g. `"main.abc123.js"`, `"/assets/logo.png"`).
+ * @returns The MIME type string.
+ */
+export declare function getMimeType(path: string): string;
+/**
+ * Build a `Cache-Control` header value from a cache configuration.
+ *
+ * @param cache - Cache configuration with optional directives.
+ * @returns A `Cache-Control` header string.
+ */
+export declare function buildCacheControl(cache: {
+    maxAge?: number;
+    sMaxAge?: number;
+    staleWhileRevalidate?: number;
+}): string;
+/**
+ * Match a URL pathname against a simple pattern.
+ *
+ * Supports three forms:
+ * - Exact match: `"/sitemap.xml"` matches only `"/sitemap.xml"`
+ * - Wildcard suffix: `"/api/*"` matches `"/api/"` and anything below
+ * - Catch-all: `"/*"` matches everything
+ *
+ * @param pattern - The route pattern.
+ * @param pathname - The URL pathname to test.
+ * @returns `true` if the pathname matches the pattern.
+ */
+export declare function matchPattern(pattern: string, pathname: string): boolean;
+//# sourceMappingURL=mime.d.ts.map

package/dist/types/lib/adapter/mime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mime.d.ts","sourceRoot":"","sources":["../../../../src/lib/adapter/mime.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AA0BH;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAKhD;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE;IACvC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,oBAAoB,CAAC,EAAE,MAAM,CAAC;CAC/B,GAAG,MAAM,CAOT;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAOvE"}

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

@@ -0,0 +1,85 @@
+/**
+ * Shared type contracts for SSR deployment adapters.
+ *
+ * These types define the interface between platform-specific adapters
+ * (Cloudflare Workers, Vercel, Deno Deploy) and the transport-agnostic
+ * renderers in `@canonical/react-ssr`. Adapters consume these types;
+ * renderers satisfy them.
+ */
+/**
+ * The subset of a renderer that adapters need to produce a response.
+ *
+ * Any renderer (`JSXRenderer`, `SitemapRenderer`, `TextRenderer`) satisfies
+ * this interface after calling the appropriate render method.
+ */
+export interface RendererResult {
+    /** Render to a web `ReadableStream` (Bun, Deno, Cloudflare Workers, Vercel Edge). */
+    renderToReadableStream: (signal?: AbortSignal) => Promise<ReadableStream>;
+    /** HTTP status code determined during rendering. */
+    statusCode: number;
+    /** Resolves when `statusCode` is determined. */
+    statusReady: Promise<void>;
+}
+/**
+ * A function that creates a renderer for a given request.
+ *
+ * All adapters use the Web Standard `Request` type. Adapters running on
+ * Node.js (e.g. Vercel serverless) convert `IncomingMessage` to `Request`
+ * internally before calling the factory.
+ */
+export type RendererFactory = (request: Request) => RendererResult;
+/**
+ * A route definition that maps a URL pattern to a renderer factory.
+ *
+ * Adapters iterate routes in order and use the first match. The pattern
+ * uses simple glob matching: `"/*"` matches everything, `"/sitemap.xml"`
+ * matches exactly, `"/api/*"` matches any path under `/api/`.
+ */
+export interface RouteDefinition {
+    /** URL pattern (e.g. `"/sitemap.xml"`, `"/api/*"`, `"/*"`). */
+    pattern: string;
+    /** Factory that creates a renderer for matched requests. */
+    factory: RendererFactory;
+    /**
+     * Content-Type header for responses from this route.
+     * Defaults to `"text/html; charset=utf-8"` when omitted.
+     */
+    contentType?: string;
+    /** Cache configuration for responses from this route. */
+    cache?: CacheConfig;
+}
+/**
+ * Cache-Control header configuration.
+ *
+ * Adapters translate these values into platform-appropriate caching:
+ * - Cloudflare: Cache API (`caches.default.put`) + `Cache-Control` header
+ * - Vercel: `Cache-Control` header (CDN respects `s-maxage`)
+ * - Deno: `Cache-Control` header only
+ */
+export interface CacheConfig {
+    /** Browser cache duration in seconds (`max-age`). */
+    maxAge?: number;
+    /** CDN/edge cache duration in seconds (`s-maxage`). */
+    sMaxAge?: number;
+    /** Duration in seconds to serve stale while revalidating (`stale-while-revalidate`). */
+    staleWhileRevalidate?: number;
+}
+/**
+ * Configuration for serving static assets (CSS, JS, images, fonts).
+ *
+ * Each entry maps a URL prefix to a source directory. The adapter serves
+ * matching requests from the source using the platform's optimal mechanism
+ * (R2 on Cloudflare, CDN on Vercel, filesystem on Deno/Bun).
+ */
+export interface StaticAssetConfig {
+    /** URL path prefix (e.g. `"/assets"`). */
+    urlPrefix: string;
+    /**
+     * Source directory or key prefix.
+     * - Cloudflare: R2 key prefix (e.g. `"assets"`)
+     * - Vercel: not used (static assets served by CDN from `.vercel/output/static/`)
+     * - Deno/Bun: filesystem path (e.g. `"dist/client/assets"`)
+     */
+    directory: string;
+}
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../src/lib/adapter/types.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH;;;;;GAKG;AACH,MAAM,WAAW,cAAc;IAC7B,qFAAqF;IACrF,sBAAsB,EAAE,CAAC,MAAM,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,cAAc,CAAC,CAAC;IAE1E,oDAAoD;IACpD,UAAU,EAAE,MAAM,CAAC;IAEnB,gDAAgD;IAChD,WAAW,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;CAC5B;AAED;;;;;;GAMG;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,OAAO,EAAE,OAAO,KAAK,cAAc,CAAC;AAEnE;;;;;;GAMG;AACH,MAAM,WAAW,eAAe;IAC9B,+DAA+D;IAC/D,OAAO,EAAE,MAAM,CAAC;IAEhB,4DAA4D;IAC5D,OAAO,EAAE,eAAe,CAAC;IAEzB;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB,yDAAyD;IACzD,KAAK,CAAC,EAAE,WAAW,CAAC;CACrB;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,WAAW;IAC1B,qDAAqD;IACrD,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB,uDAAuD;IACvD,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB,wFAAwF;IACxF,oBAAoB,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED;;;;;;GAMG;AACH,MAAM,WAAW,iBAAiB;IAChC,0CAA0C;IAC1C,SAAS,EAAE,MAAM,CAAC;IAElB;;;;;OAKG;IACH,SAAS,EAAE,MAAM,CAAC;CACnB"}

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

@@ -0,0 +1,4 @@
+export * as adapter from "./adapter/index.js";
+export * as renderer from "./renderer/index.js";
+export * as server from "./server/index.js";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/lib/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,OAAO,MAAM,oBAAoB,CAAC;AAC9C,OAAO,KAAK,QAAQ,MAAM,qBAAqB,CAAC;AAChD,OAAO,KAAK,MAAM,MAAM,mBAAmB,CAAC"}

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

@@ -0,0 +1,93 @@
+import React from "react";
+/**
+ * Collected representation of an HTML element extracted during SAX parsing.
+ *
+ * Mirrors the subset of DOM element data needed to construct a React element:
+ * the tag name, its attributes, and optional text content.
+ */
+interface CollectedElement {
+    name: string;
+    attribs: Record<string, string>;
+    text: string | undefined;
+}
+/**
+ * The three buckets into which `parseHeadElements` dispatches extracted tags.
+ */
+interface ParseResult {
+    links: CollectedElement[];
+    scripts: CollectedElement[];
+    others: CollectedElement[];
+}
+/**
+ * Extracts `<head>` elements from an HTML string and converts them to React elements.
+ *
+ * The primary use case is server-side rendering with Vite: the build process produces
+ * an HTML shell containing `<script>`, `<link>`, `<meta>`, `<title>`, `<style>`, and
+ * `<base>` tags. This class parses that shell via `parseHeadElements` (a SAX handler —
+ * no DOM tree is constructed) and exposes the extracted tags as React elements that the
+ * server entrypoint component can inject into its rendered output.
+ *
+ * Parsing happens once in the constructor. The three getter methods return the
+ * elements in the order they appeared in the original HTML.
+ */
+export default class Extractor {
+    /** Parsed head elements, grouped by category. */
+    protected readonly parsed: ParseResult;
+    /**
+     * Create an Extractor for the given HTML string.
+     *
+     * @param html - The full HTML string to parse (typically from a Vite build).
+     */
+    constructor(html: string);
+    /**
+     * Convert an HTML attribute name to the corresponding React prop name.
+     *
+     * Checks `REACT_KEYS_DICTIONARY` for known exceptions (e.g. `class` becomes
+     * `className`). Falls back to generic camelCase conversion, which correctly
+     * handles `data-*` and `aria-*` attributes.
+     *
+     * @param key - The HTML attribute name, e.g. `"crossorigin"` or `"data-test-id"`.
+     * @returns The React prop name, e.g. `"crossOrigin"` or `"dataTestId"`.
+     */
+    protected convertKeyToReactKey(key: string): string;
+    /**
+     * Convert a collected element into a `React.createElement` call.
+     *
+     * Attributes are mapped to React prop names via `convertKeyToReactKey`.
+     * A stable `key` prop is synthesised from the tag name and the element's
+     * position index so that React can reconcile lists of head elements.
+     *
+     * If the element has text content (e.g. `<title>My App</title>` or
+     * `<style>.body { color: red }</style>`), it is passed as the element's
+     * `children` argument.
+     *
+     * @param element - The collected element data from SAX parsing.
+     * @param index - The position of this element within its sibling group.
+     * @returns A React element matching the original HTML tag.
+     */
+    protected convertToReactElement(element: CollectedElement, index: number): React.ReactElement;
+    /**
+     * Return all `<link>` elements as React elements, in document order.
+     *
+     * Typically used to inject stylesheet and preload links into the
+     * server-rendered `<head>`.
+     */
+    getLinkElements(): React.ReactElement[];
+    /**
+     * Return all `<script>` elements as React elements, in document order.
+     *
+     * Preserving order is important: Vite dev mode emits module scripts
+     * that depend on being evaluated in sequence.
+     */
+    getScriptElements(): React.ReactElement[];
+    /**
+     * Return all non-script, non-link head elements as React elements, in document order.
+     *
+     * This covers `<title>`, `<style>`, `<meta>`, and `<base>`. Elements are returned
+     * in the order they appeared in the HTML, preserving inter-type ordering (a `<meta>`
+     * between two `<style>` tags stays between them).
+     */
+    getOtherHeadElements(): React.ReactElement[];
+}
+export {};
+//# sourceMappingURL=Extractor.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"Extractor.d.ts","sourceRoot":"","sources":["../../../../src/lib/renderer/Extractor.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,MAAM,OAAO,CAAC;AAoB1B;;;;;GAKG;AACH,UAAU,gBAAgB;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;CAC1B;AAED;;GAEG;AACH,UAAU,WAAW;IACnB,KAAK,EAAE,gBAAgB,EAAE,CAAC;IAC1B,OAAO,EAAE,gBAAgB,EAAE,CAAC;IAC5B,MAAM,EAAE,gBAAgB,EAAE,CAAC;CAC5B;AAuED;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,OAAO,OAAO,SAAS;IAC5B,iDAAiD;IACjD,SAAS,CAAC,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAEvC;;;;OAIG;gBACS,IAAI,EAAE,MAAM;IAIxB;;;;;;;;;OASG;IACH,SAAS,CAAC,oBAAoB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM;IAInD;;;;;;;;;;;;;;OAcG;IACH,SAAS,CAAC,qBAAqB,CAC7B,OAAO,EAAE,gBAAgB,EACzB,KAAK,EAAE,MAAM,GACZ,KAAK,CAAC,YAAY;IAWrB;;;;;OAKG;IACI,eAAe,IAAI,KAAK,CAAC,YAAY,EAAE;IAI9C;;;;;OAKG;IACI,iBAAiB,IAAI,KAAK,CAAC,YAAY,EAAE;IAMhD;;;;;;OAMG;IACI,oBAAoB,IAAI,KAAK,CAAC,YAAY,EAAE;CAGpD"}

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

@@ -0,0 +1,163 @@
+import { type RenderToPipeableStreamOptions } from "react-dom/server";
+import Extractor from "./Extractor.js";
+import type { PipeableStreamResult, RendererOptions, ServerEntrypoint, ServerEntrypointProps } from "./types.js";
+/**
+ * Server-side renderer for a React component.
+ *
+ * Accepts a React `ServerEntrypoint` component, optional initial data for
+ * hydration, and an optional HTML shell string (from a Vite build) whose
+ * `<head>` tags are extracted and injected into the rendered output.
+ *
+ * Three rendering strategies are available:
+ *
+ * - **ReadableStream** (`renderToReadableStream`) — returns a web `ReadableStream`.
+ *   Works natively with Bun, Deno, Cloudflare Workers, and any runtime that
+ *   supports the Web Streams API. Supports Suspense and progressive rendering.
+ *
+ * - **PipeableStream** (`renderToPipeableStream`) — returns a Node.js pipeable stream.
+ *   Works with Express, Fastify, and Node's built-in `http` module. Supports Suspense
+ *   and progressive rendering.
+ *
+ * - **String** (`renderToString`) — returns the full HTML as a string. All Suspense
+ *   boundaries resolve synchronously. The output is cacheable and works with Vite
+ *   HMR in dev mode.
+ *
+ * All strategies inject `<script>` and `<link>` tags from the HTML shell via
+ * React's `bootstrapScripts` / `bootstrapModules` mechanism, and embed
+ * `initialData` as a global `window.__INITIAL_DATA__` variable for client
+ * hydration.
+ *
+ * The renderer is transport-agnostic — it never writes to a response object.
+ * HTTP status codes and metadata are exposed via `statusCode` and `statusReady`
+ * for the consumer to use when constructing the response.
+ *
+ * @typeParam TComponent - The server entrypoint component type.
+ * @typeParam InitialData - Shape of the data embedded for client hydration.
+ */
+export default class JSXRenderer<TComponent extends ServerEntrypoint<InitialData>, InitialData extends Record<string, unknown>> {
+    protected readonly Component: TComponent;
+    protected readonly initialData: InitialData;
+    protected readonly options: RendererOptions;
+    protected extractor: Extractor | undefined;
+    /**
+     * HTTP status code determined during rendering.
+     *
+     * Starts at 200 and is set to 500 if a shell error occurs during streaming.
+     * For `renderToString`, it is always 200 (errors throw instead).
+     *
+     * Read this after the render method returns (for `renderToReadableStream` and
+     * `renderToString`) or after awaiting `statusReady` (for `renderToPipeableStream`).
+     */
+    statusCode: number;
+    /**
+     * Resolves when `statusCode` is determined.
+     *
+     * For `renderToReadableStream` and `renderToString`, this is already resolved
+     * by the time the method returns. For `renderToPipeableStream`, it resolves
+     * asynchronously when the shell is ready or errors.
+     */
+    statusReady: Promise<void>;
+    /**
+     * Create a renderer bound to a specific component and initial data.
+     *
+     * If `options.htmlString` is provided, the HTML is parsed once to extract
+     * `<head>` elements. These elements are then available as React elements
+     * via `getComponentProps()` for injection during rendering.
+     *
+     * @param Component - The React server entrypoint component.
+     * @param initialData - Data to embed in `window.__INITIAL_DATA__` for client hydration.
+     * @param options - Renderer configuration: locale, HTML shell, and stream options.
+     */
+    constructor(Component: TComponent, initialData?: InitialData, options?: RendererOptions);
+    /**
+     * Return the locale for the rendered page.
+     *
+     * Defaults to `"en"` when no `defaultLocale` was provided in options.
+     * The locale is passed as the `lang` prop to the server entrypoint component,
+     * which typically sets it as the `<html lang>` attribute.
+     */
+    getLocale(): string;
+    /**
+     * Assemble the props passed to the server entrypoint component.
+     *
+     * Combines the locale, initial data, and (when an HTML shell was provided)
+     * the extracted script, link, and other head elements into a single props
+     * object conforming to `ServerEntrypointProps`.
+     */
+    protected getComponentProps(): ServerEntrypointProps<InitialData>;
+    /**
+     * Extract `src` URLs from script elements that match a given loading strategy.
+     *
+     * Filters the provided React `<script>` elements by their `type` attribute:
+     * `"module"` selects ES module scripts, `"classic"` selects everything else.
+     * Returns only the `src` values, discarding inline scripts that have no `src`.
+     *
+     * @param scripts - React elements representing `<script>` tags.
+     * @param type - `"module"` for ES modules, `"classic"` for traditional scripts.
+     * @returns An array of script source URLs.
+     */
+    protected getScriptSourcesByType(scripts: React.ReactElement[], type: "module" | "classic"): string[];
+    /**
+     * Merge renderer-managed options into the user-provided stream options.
+     *
+     * Populates three React streaming options unless the caller already supplied them:
+     *
+     * - `bootstrapScriptContent` — a `<script>` body that assigns `initialData` to
+     *   `window.__INITIAL_DATA__`. The JSON is escaped to prevent `</script>` injection.
+     * - `bootstrapScripts` — `src` URLs for classic (non-module) scripts extracted from
+     *   the HTML shell. React strips `<script>` tags during streaming, so these must
+     *   be re-injected through this mechanism.
+     * - `bootstrapModules` — same as above, for ES module scripts.
+     *
+     * @param props - The assembled component props (used to read `initialData` and `scriptElements`).
+     * @returns A merged options object safe to pass to either streaming API.
+     */
+    protected enrichRendererOptions(props: ServerEntrypointProps<InitialData>): RenderToPipeableStreamOptions;
+    /**
+     * Render the component to a web `ReadableStream`.
+     *
+     * Uses `react-dom/server.renderToReadableStream` for environments that support
+     * the Web Streams API (Bun, Deno, Cloudflare Workers, browsers). Supports
+     * Suspense and progressive rendering.
+     *
+     * On shell error, `statusCode` is set to 500 and a fallback HTML stream is
+     * returned. On success, `statusCode` is 200.
+     *
+     * @note This method is impure — it mutates `statusCode` and `statusReady`.
+     *
+     * @param signal - Optional `AbortSignal` for request cancellation.
+     * @returns A `ReadableStream` of the rendered HTML.
+     */
+    renderToReadableStream: (signal?: AbortSignal) => Promise<ReadableStream>;
+    /**
+     * Render the component to a Node.js pipeable stream.
+     *
+     * Uses `react-dom/server.renderToPipeableStream` for Node.js environments
+     * (Express, Fastify, plain `http.createServer`). Supports Suspense and
+     * progressive rendering.
+     *
+     * Returns `{ pipe, abort }` synchronously. The `statusCode` is set
+     * asynchronously when the shell is ready or errors — await `statusReady`
+     * before reading it.
+     *
+     * @note This method is impure — it mutates `statusCode` and `statusReady`.
+     *
+     * @returns The pipe/abort handles for the rendered stream.
+     */
+    renderToPipeableStream: () => PipeableStreamResult;
+    /**
+     * Render the component to a complete HTML string.
+     *
+     * Uses `react-dom/server.renderToString` to produce the full HTML
+     * synchronously. All Suspense boundaries resolve before the method returns.
+     * The output is cacheable and compatible with Vite's HMR in dev mode.
+     *
+     * Sets `statusCode` to 200 on success. On error, throws (consumer catches).
+     *
+     * @note This method is impure — it mutates `statusCode`.
+     *
+     * @returns The complete HTML string.
+     */
+    renderToString: () => string;
+}
+//# sourceMappingURL=JSXRenderer.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"JSXRenderer.d.ts","sourceRoot":"","sources":["../../../../src/lib/renderer/JSXRenderer.ts"],"names":[],"mappings":"AACA,OAAO,EACL,KAAK,6BAA6B,EAInC,MAAM,kBAAkB,CAAC;AAE1B,OAAO,SAAS,MAAM,gBAAgB,CAAC;AACvC,OAAO,KAAK,EACV,oBAAoB,EACpB,eAAe,EACf,gBAAgB,EAChB,qBAAqB,EACtB,MAAM,YAAY,CAAC;AAEpB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,MAAM,CAAC,OAAO,OAAO,WAAW,CAC9B,UAAU,SAAS,gBAAgB,CAAC,WAAW,CAAC,EAChD,WAAW,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAoCzC,SAAS,CAAC,QAAQ,CAAC,SAAS,EAAE,UAAU;IACxC,SAAS,CAAC,QAAQ,CAAC,WAAW,EAAE,WAAW;IAC3C,SAAS,CAAC,QAAQ,CAAC,OAAO,EAAE,eAAe;IApC7C,SAAS,CAAC,SAAS,EAAE,SAAS,GAAG,SAAS,CAAC;IAE3C;;;;;;;;OAQG;IACI,UAAU,SAAO;IAExB;;;;;;OAMG;IACI,WAAW,EAAE,OAAO,CAAC,IAAI,CAAC,CAAqB;IAEtD;;;;;;;;;;OAUG;gBAEkB,SAAS,EAAE,UAAU,EACrB,WAAW,GAAE,WAA+B,EAC5C,OAAO,GAAE,eAAoB;IAOlD;;;;;;OAMG;IACI,SAAS,IAAI,MAAM;IAI1B;;;;;;OAMG;IACH,SAAS,CAAC,iBAAiB,IAAI,qBAAqB,CAAC,WAAW,CAAC;IAUjE;;;;;;;;;;OAUG;IACH,SAAS,CAAC,sBAAsB,CAC9B,OAAO,EAAE,KAAK,CAAC,YAAY,EAAE,EAC7B,IAAI,EAAE,QAAQ,GAAG,SAAS,GACzB,MAAM,EAAE;IAmBX;;;;;;;;;;;;;;OAcG;IACH,SAAS,CAAC,qBAAqB,CAC7B,KAAK,EAAE,qBAAqB,CAAC,WAAW,CAAC,GACxC,6BAA6B;IA8BhC;;;;;;;;;;;;;;OAcG;IACH,sBAAsB,GACpB,SAAS,WAAW,KACnB,OAAO,CAAC,cAAc,CAAC,CAuCxB;IAEF;;;;;;;;;;;;;;OAcG;IACH,sBAAsB,QAAO,oBAAoB,CA0C/C;IAEF;;;;;;;;;;;;OAYG;IACH,cAAc,QAAO,MAAM,CAOzB;CACH"}