npm - @canonical/react-ssr - Versions diffs - 0.22.0 → 0.23.0 - Mend

@canonical/react-ssr 0.22.0 → 0.23.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (83) hide show

package/dist/esm/bin/serve-express.js +86 -0
package/dist/esm/bin/serve-express.js.map +1 -0
package/dist/esm/index.js +2 -2
package/dist/esm/index.js.map +1 -1
package/dist/esm/lib/index.js +3 -0
package/dist/esm/lib/index.js.map +1 -0
package/dist/esm/lib/renderer/Extractor.js +172 -0
package/dist/esm/lib/renderer/Extractor.js.map +1 -0
package/dist/esm/lib/renderer/JSXRenderer.js +283 -0
package/dist/esm/lib/renderer/JSXRenderer.js.map +1 -0
package/dist/esm/lib/renderer/SitemapRenderer.js +241 -0
package/dist/esm/lib/renderer/SitemapRenderer.js.map +1 -0
package/dist/esm/lib/renderer/TextRenderer.js +124 -0
package/dist/esm/lib/renderer/TextRenderer.js.map +1 -0
package/dist/esm/lib/renderer/constants.js.map +1 -0
package/dist/esm/lib/renderer/index.js +6 -0
package/dist/esm/lib/renderer/index.js.map +1 -0
package/dist/esm/lib/renderer/types.js +10 -0
package/dist/esm/lib/renderer/types.js.map +1 -0
package/dist/esm/lib/server/index.js +3 -0
package/dist/esm/lib/server/index.js.map +1 -0
package/dist/esm/lib/server/serveStream.js +53 -0
package/dist/esm/lib/server/serveStream.js.map +1 -0
package/dist/esm/lib/server/serveString.js +49 -0
package/dist/esm/lib/server/serveString.js.map +1 -0
package/dist/types/bin/serve-express.d.ts +24 -0
package/dist/types/bin/serve-express.d.ts.map +1 -0
package/dist/types/index.d.ts +2 -2
package/dist/types/index.d.ts.map +1 -1
package/dist/types/lib/index.d.ts +3 -0
package/dist/types/lib/index.d.ts.map +1 -0
package/dist/types/lib/renderer/Extractor.d.ts +93 -0
package/dist/types/lib/renderer/Extractor.d.ts.map +1 -0
package/dist/types/lib/renderer/JSXRenderer.d.ts +163 -0
package/dist/types/lib/renderer/JSXRenderer.d.ts.map +1 -0
package/dist/types/lib/renderer/SitemapRenderer.d.ts +153 -0
package/dist/types/lib/renderer/SitemapRenderer.d.ts.map +1 -0
package/dist/types/lib/renderer/TextRenderer.d.ts +83 -0
package/dist/types/lib/renderer/TextRenderer.d.ts.map +1 -0
package/dist/types/lib/renderer/constants.d.ts.map +1 -0
package/dist/types/lib/renderer/index.d.ts +7 -0
package/dist/types/lib/renderer/index.d.ts.map +1 -0
package/dist/types/lib/renderer/types.d.ts +161 -0
package/dist/types/lib/renderer/types.d.ts.map +1 -0
package/dist/types/lib/server/index.d.ts +3 -0
package/dist/types/lib/server/index.d.ts.map +1 -0
package/dist/types/lib/server/serveStream.d.ts +41 -0
package/dist/types/lib/server/serveStream.d.ts.map +1 -0
package/dist/types/lib/server/serveString.d.ts +37 -0
package/dist/types/lib/server/serveString.d.ts.map +1 -0
package/package.json +32 -17
package/dist/esm/renderer/Extractor.js +0 -127
package/dist/esm/renderer/Extractor.js.map +0 -1
package/dist/esm/renderer/JSXRenderer.js +0 -168
package/dist/esm/renderer/JSXRenderer.js.map +0 -1
package/dist/esm/renderer/constants.js.map +0 -1
package/dist/esm/renderer/index.js +0 -4
package/dist/esm/renderer/index.js.map +0 -1
package/dist/esm/renderer/types.js +0 -2
package/dist/esm/renderer/types.js.map +0 -1
package/dist/esm/server/index.js +0 -2
package/dist/esm/server/index.js.map +0 -1
package/dist/esm/server/serve-express.js +0 -58
package/dist/esm/server/serve-express.js.map +0 -1
package/dist/esm/server/serve.js +0 -41
package/dist/esm/server/serve.js.map +0 -1
package/dist/types/renderer/Extractor.d.ts +0 -68
package/dist/types/renderer/Extractor.d.ts.map +0 -1
package/dist/types/renderer/JSXRenderer.d.ts +0 -71
package/dist/types/renderer/JSXRenderer.d.ts.map +0 -1
package/dist/types/renderer/constants.d.ts.map +0 -1
package/dist/types/renderer/index.d.ts +0 -5
package/dist/types/renderer/index.d.ts.map +0 -1
package/dist/types/renderer/types.d.ts +0 -35
package/dist/types/renderer/types.d.ts.map +0 -1
package/dist/types/server/index.d.ts +0 -2
package/dist/types/server/index.d.ts.map +0 -1
package/dist/types/server/serve-express.d.ts +0 -3
package/dist/types/server/serve-express.d.ts.map +0 -1
package/dist/types/server/serve.d.ts +0 -30
package/dist/types/server/serve.d.ts.map +0 -1
/package/dist/esm/{renderer → lib/renderer}/constants.js +0 -0
/package/dist/types/{renderer → lib/renderer}/constants.d.ts +0 -0

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

@@ -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 ADDED Viewed

@@ -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 ADDED Viewed

@@ -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 ADDED Viewed

@@ -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"}

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

@@ -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 ADDED Viewed

@@ -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 ADDED Viewed

@@ -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 ADDED Viewed

@@ -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 ADDED Viewed

	@@ -0,0 +1 @@
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 ADDED Viewed

@@ -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 ADDED Viewed

@@ -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"}