@alpaca-headless/dynamic-renderings 1.0.4694

package/dist/rich-text/sanitizeRichText.js

@@ -0,0 +1,99 @@
+import sanitizeHtml from "sanitize-html";
+// Allowlist for rich-text field HTML before it is rendered.
+//
+// The Alpaca SDK renders rich text with dangerouslySetInnerHTML, and in the
+// Parhelia editor this page is served through the CM proxy (same origin as the
+// editor), so any script in a field would run with the editing user's session.
+// Field values come from every write path (editor, agents, imports, Content
+// Editor, serialized items), so they are filtered here, where they reach the DOM.
+//
+// Every Alpaca head carries an identical copy of this file, because each head
+// installs and deploys on its own; hosts/playground-site/scripts/
+// test-rich-text-sanitizer.mjs tests it and checks that the copies match.
+// The editor bridge applies the same policy to values it writes into the canvas
+// (frontend/editor-bridge/host/rich-text-sanitizer.ts); change both together.
+const ALLOWED_TAGS = [
+    "a", "abbr", "b", "blockquote", "br", "caption", "cite", "code", "col",
+    "colgroup", "dd", "del", "dfn", "div", "dl", "dt", "em", "figcaption",
+    "figure", "h1", "h2", "h3", "h4", "h5", "h6", "hr", "i", "img", "ins", "kbd",
+    "li", "mark", "ol", "p", "pre", "q", "s", "samp", "small", "span", "strong",
+    "sub", "sup", "table", "tbody", "td", "tfoot", "th", "thead", "time", "tr",
+    "u", "ul", "wbr",
+];
+const TABLE_CELL_ATTRIBUTES = [
+    "colspan", "rowspan", "headers", "scope", "align", "valign", "width", "height",
+];
+const ALLOWED_ATTRIBUTES = {
+    "*": ["class", "id", "title", "lang", "dir", "style", "aria-*"],
+    // data-internal / data-item-id / data-querystring mark internal links for the
+    // editor (RichTextInternalLinkTagger / RichTextLinkNormalizer on the CM).
+    a: ["href", "target", "rel", "data-internal", "data-item-id", "data-querystring"],
+    img: ["src", "alt", "width", "height", "loading"],
+    table: ["border", "cellpadding", "cellspacing", "width", "align"],
+    tr: ["align", "valign"],
+    td: TABLE_CELL_ATTRIBUTES,
+    th: TABLE_CELL_ATTRIBUTES,
+    col: ["span", "width"],
+    colgroup: ["span", "width"],
+    ol: ["start", "reversed", "type"],
+    li: ["value"],
+    time: ["datetime"],
+    del: ["cite", "datetime"],
+    ins: ["cite", "datetime"],
+    blockquote: ["cite"],
+    q: ["cite"],
+};
+// Formatting only: nothing that positions content over the page (an overlay
+// inside the editor canvas) and no value that loads a resource.
+const STYLE_PROPERTIES = [
+    "color", "background-color", "font-family", "font-size", "font-style",
+    "font-weight", "letter-spacing", "line-height", "text-align",
+    "text-decoration", "text-decoration-line", "text-decoration-color",
+    "text-decoration-style", "text-indent", "text-transform", "vertical-align",
+    "white-space", "direction", "margin", "margin-top", "margin-right",
+    "margin-bottom", "margin-left", "padding", "padding-top", "padding-right",
+    "padding-bottom", "padding-left", "border", "border-top", "border-right",
+    "border-bottom", "border-left", "border-color", "border-style",
+    "border-width", "border-collapse", "border-spacing", "border-radius",
+    "width", "height", "min-width", "max-width", "min-height", "max-height",
+    "list-style-type", "float", "clear", "display",
+];
+const SAFE_STYLE_VALUE = /^(?![\s\S]*(?:url\s*\(|image-set\s*\(|image\s*\(|expression\s*\(|javascript:|vbscript:|@import|behavior|binding|\\))[\s\S]*$/i;
+// Leading underscores are what page scripts use for globals (__NEXT_DATA__,
+// __PARHELIA_EDITING_BRIDGE_RUNTIME__); an id there would shadow them.
+const SAFE_ID = /^[A-Za-z][\w:.-]*$/;
+const OPTIONS = {
+    allowedTags: ALLOWED_TAGS,
+    allowedAttributes: ALLOWED_ATTRIBUTES,
+    allowedSchemes: ["http", "https", "mailto", "tel"],
+    allowedSchemesByTag: { img: ["http", "https", "data"] },
+    allowedSchemesAppliedToAttributes: ["href", "src", "cite"],
+    allowProtocolRelative: true,
+    allowedStyles: {
+        "*": Object.fromEntries(STYLE_PROPERTIES.map((name) => [name, [SAFE_STYLE_VALUE]])),
+    },
+    // Dropped together with their content, not unwrapped into text.
+    nonTextTags: [
+        "script", "style", "textarea", "option", "noscript", "xmp", "noembed",
+        "noframes", "iframe", "template", "title",
+    ],
+    transformTags: {
+        "*": (tagName, attribs) => {
+            if (attribs.id === undefined || SAFE_ID.test(attribs.id))
+                return { tagName, attribs };
+            const rest = { ...attribs };
+            delete rest.id;
+            return { tagName, attribs: rest };
+        },
+    },
+};
+/** Filters rich-text HTML down to the formatting markup above. */
+export function sanitizeRichTextHtml(html) {
+    return sanitizeHtml(html, OPTIONS);
+}
+/** Same for a field value, which may be missing or not a string. */
+export function sanitizeRichTextValue(value) {
+    if (value === null || value === undefined)
+        return value;
+    return sanitizeRichTextHtml(typeof value === "string" ? value : String(value));
+}

package/dist/server/backend.d.ts

@@ -0,0 +1,25 @@
+import "server-only";
+import type { SourcesResponse } from "../protocol/types.js";
+import type { DynamicRenderingsConfig } from "./config.js";
+export type BackendIdentity = {
+    apiKey: string;
+    /** Forwarded Cookie / Authorization headers, or a sealed request's own headers. */
+    headers: Headers;
+};
+export type SourcesQuery = {
+    /** With a page: the page's renderings the caller may read, and its tenant's theme. */
+    pageId?: string;
+    ids: string[];
+    database?: string;
+    mode?: string;
+};
+/**
+ * The source of every requested dynamic rendering. With a page, those of the page's tenant that
+ * the caller may read, plus the tenant's theme tokens; without one (a bundle rebuilt after a
+ * cache miss), approved renderings only. On a publishing target the CM returns approved
+ * renderings only either way. `status` is the CM's answer, for callers that must tell a refusal
+ * from an outage.
+ */
+export declare function fetchSources(config: DynamicRenderingsConfig, identity: BackendIdentity, { pageId, ids, database, mode }: SourcesQuery): Promise<SourcesResponse & {
+    status: number;
+}>;

package/dist/server/backend.js

@@ -0,0 +1,36 @@
+import "server-only";
+async function getJson(config, route, identity) {
+    const headers = new Headers(identity.headers);
+    headers.set("x-api-key", identity.apiKey);
+    headers.set("accept", "application/json");
+    const response = await fetch(config.layoutServiceUrl() + route, { headers, redirect: "manual", cache: "no-store" });
+    if (response.status !== 200)
+        return { status: response.status };
+    const type = response.headers.get("content-type") || "";
+    if (!type.includes("json"))
+        return { status: 502 };
+    return { status: 200, data: (await response.json()) };
+}
+/**
+ * The source of every requested dynamic rendering. With a page, those of the page's tenant that
+ * the caller may read, plus the tenant's theme tokens; without one (a bundle rebuilt after a
+ * cache miss), approved renderings only. On a publishing target the CM returns approved
+ * renderings only either way. `status` is the CM's answer, for callers that must tell a refusal
+ * from an outage.
+ */
+export async function fetchSources(config, identity, { pageId, ids, database, mode }) {
+    const query = new URLSearchParams();
+    if (pageId)
+        query.set("page", pageId);
+    query.set("ids", ids.join(","));
+    if (database)
+        query.set("database", database);
+    if (mode)
+        query.set("mode", mode);
+    const { status, data } = await getJson(config, `/alpaca/headless/renderings/sources?${query}`, identity);
+    if (status !== 200 || !data || !Array.isArray(data.renderings)) {
+        console.warn(`[dynamic-renderings] sources for ${pageId ? `page ${pageId}` : `rendering ${ids.join(",")}`} answered ${status}; dynamic components are not shown.`);
+        return { renderings: [], status: status === 200 ? 502 : status };
+    }
+    return { ...data, status };
+}

package/dist/server/config.d.ts

@@ -0,0 +1,98 @@
+import { protocol } from "../protocol/protocol.js";
+/**
+ * Where the theme a head compiles rendering CSS against comes from. `load()` returns the CSS
+ * text, or throws when it cannot be read: a missing theme is an error, never empty CSS, so a
+ * packaging mistake cannot look healthy.
+ */
+export type ThemeSource = {
+    /** Where the theme lives, for diagnostics. */
+    describe: string;
+    load(): Promise<string>;
+};
+export declare class ThemeUnavailableError extends Error {
+    constructor(message: string);
+}
+/** For a head without design tokens: says so explicitly, instead of a missing file. */
+export declare function noTheme(): ThemeSource;
+/** A theme given as text, e.g. imported at build time. */
+export declare function inlineTheme(css: string, describe?: string): ThemeSource;
+/** The engine's threads. Defaults come from the protocol limits. */
+export type EngineSettings = {
+    /** Render threads, one per active tenant. Default 4. */
+    renderThreads?: number;
+    /** Compile threads. Default 2. */
+    compileThreads?: number;
+};
+/** Editor integration is supplied by the host; the runtime does not depend on an editor. */
+export type EditorMarkers = {
+    nonceAttribute: string;
+    slotAttribute: string;
+    /**
+     * In preview mode (not edit, not sealed) the page lists the renderings on it that have client
+     * code: `<script type="application/json" {attribute}="{id},{id}">`.
+     */
+    clientCodeHintAttribute?: string;
+};
+export type RequestRoute = {
+    route: string | string[];
+    prefix: string;
+    editing: boolean;
+    editorFrame: boolean;
+};
+export type RequestAdapter = (path: string[] | undefined, search: Record<string, string | string[] | undefined>) => RequestRoute;
+/**
+ * Recognises a sealed request: one that reaches the head through an editor's isolated preview.
+ * The returned headers are then its whole CM identity (no cookies are forwarded), the page is
+ * always a preview, and every client component on it loads its code.
+ */
+export type RequestAuth = (headers: Headers) => {
+    headers: HeadersInit;
+} | null;
+/** Adjusts the page data before anything renders it, e.g. media URLs in a sealed request. */
+export type PageTransform = <P>(page: P, info: {
+    sealed: boolean;
+    prefix: string;
+}) => P;
+export type DynamicRenderingsOptions = {
+    editor?: EditorMarkers;
+    requestAdapter?: RequestAdapter;
+    requestAuth?: RequestAuth;
+    transformPage?: PageTransform;
+    /** Required: the tokens renderings compile against. */
+    theme: ThemeSource;
+    /** Shared secret the CM presents to the build route. Default: ALPACA_RENDERING_BUILD_KEY. */
+    buildKey?: string;
+    /** API key for the CM calls. Default: ALPACA_HEADLESS_API_KEY, then API_KEY. */
+    apiKey?: string;
+    /**
+     * Tenants under this path are sandbox users: their reference fields are fenced to their own
+     * root. Unset for plain site heads.
+     */
+    sandboxRoot?: string;
+    /** Absolute media hosts allowed in `src`. Default: ALPACA_MEDIA_HOSTS, split on commas. */
+    mediaHosts?: string[];
+    /** The CM origin. Default: RUNTIME_LAYOUT_SERVICE_URL, then LAYOUT_SERVICE_URL, then http://localhost:5002, read per call. */
+    layoutServiceUrl?: string;
+    engine?: EngineSettings;
+};
+export type DynamicRenderingsConfig = {
+    readonly editor?: Readonly<EditorMarkers>;
+    readonly requestAdapter?: RequestAdapter;
+    readonly requestAuth?: RequestAuth;
+    readonly transformPage?: PageTransform;
+    readonly theme: ThemeSource;
+    readonly buildKey: string;
+    readonly apiKey: string;
+    readonly sandboxRoot?: string;
+    readonly mediaHosts: readonly string[];
+    /** Resolved per call, because heads may set the layout service URL at request time. */
+    layoutServiceUrl(): string;
+    readonly limits: {
+        readonly [K in keyof typeof protocol.limits]: number;
+    };
+    readonly engine: Readonly<EngineSettings>;
+};
+/** The one configured instance a head uses for its page and its build route. */
+export declare function defineDynamicRenderings(options: DynamicRenderingsOptions): DynamicRenderingsConfig;
+/** True when the tenant is a sandbox user (only with a configured sandbox root). */
+export declare function isSandboxTenant(config: Pick<DynamicRenderingsConfig, "sandboxRoot">, tenant: string): boolean;

package/dist/server/config.js

@@ -0,0 +1,49 @@
+import { protocol } from "../protocol/protocol.js";
+export class ThemeUnavailableError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "ThemeUnavailableError";
+    }
+}
+/** For a head without design tokens: says so explicitly, instead of a missing file. */
+export function noTheme() {
+    return { describe: "no theme", load: async () => "" };
+}
+/** A theme given as text, e.g. imported at build time. */
+export function inlineTheme(css, describe = "inline theme") {
+    return { describe, load: async () => css };
+}
+function env(name) {
+    return typeof process !== "undefined" ? process.env[name]?.trim() || undefined : undefined;
+}
+/** The one configured instance a head uses for its page and its build route. */
+export function defineDynamicRenderings(options) {
+    if (!options?.theme || typeof options.theme.load !== "function") {
+        throw new Error("defineDynamicRenderings: `theme` is required (use nextThemeFile(...) or noTheme()).");
+    }
+    const sandboxRoot = options.sandboxRoot?.trim() || undefined;
+    return Object.freeze({
+        theme: options.theme,
+        // Read per use: heads may set these variables after the config module was evaluated (a head
+        // that defaults its API key on the first request, for example).
+        get buildKey() {
+            return options.buildKey ?? env("ALPACA_RENDERING_BUILD_KEY") ?? "";
+        },
+        get apiKey() {
+            return options.apiKey ?? env("ALPACA_HEADLESS_API_KEY") ?? env("API_KEY") ?? "";
+        },
+        sandboxRoot: sandboxRoot ? (sandboxRoot.endsWith("/") ? sandboxRoot : `${sandboxRoot}/`) : undefined,
+        mediaHosts: Object.freeze((options.mediaHosts ?? (env("ALPACA_MEDIA_HOSTS") ?? "").split(",")).map((h) => h.trim().toLowerCase()).filter(Boolean)),
+        layoutServiceUrl: () => (options.layoutServiceUrl ?? env("RUNTIME_LAYOUT_SERVICE_URL") ?? env("LAYOUT_SERVICE_URL") ?? "http://localhost:5002").replace(/\/+$/, ""),
+        editor: options.editor ? Object.freeze({ ...options.editor }) : undefined,
+        requestAdapter: options.requestAdapter,
+        requestAuth: options.requestAuth,
+        transformPage: options.transformPage,
+        limits: protocol.limits,
+        engine: Object.freeze({ ...(options.engine ?? {}) }),
+    });
+}
+/** True when the tenant is a sandbox user (only with a configured sandbox root). */
+export function isSandboxTenant(config, tenant) {
+    return Boolean(config.sandboxRoot) && tenant.toLowerCase().startsWith(config.sandboxRoot.toLowerCase());
+}

package/dist/server/engine.d.ts

@@ -0,0 +1,83 @@
+import "server-only";
+import type { Diagnostic, Engine, EngineModuleSource } from "@alpaca-headless/dynamic-renderings-engine";
+import type { ComponentDto, RenderResult } from "../protocol/types.js";
+import type { DynamicRenderingsConfig } from "./config.js";
+export type CompiledClient = {
+    /** The browser ES module. */
+    browser: string;
+    /** The CommonJS module the render threads run for first paints. */
+    node: string;
+    exports: string[];
+    /** clientHash() of the client code: its name in bundle URLs. */
+    hash: string;
+    /** clientSourceHash() of the client code: what a rebuilt bundle is checked against. */
+    sourceHash: string;
+};
+export type CompiledRendering = {
+    ok: true;
+    buildId: string;
+    server: string;
+    client?: CompiledClient;
+    css: string | null;
+    cssRejected?: string;
+} | {
+    ok: false;
+    buildId: string;
+    diagnostics: Diagnostic[];
+    transient?: boolean;
+};
+export type ClientBundle = {
+    code: string;
+    sourceHash: string;
+    approved: boolean;
+};
+export declare function getEngine(config: DynamicRenderingsConfig): Promise<Engine>;
+/** SHA-256 of the LF-normalized source, as the CM computes it. */
+export declare function sourceHash(code: string): string;
+/** SHA-256 of the client code's LF-normalized text. */
+export declare function clientSourceHash(clientCode: string): string;
+/**
+ * The client code's name in bundle URLs: the first 16 hex digits of clientSourceHash(). Short,
+ * because the URL sits behind a proxy prefix that holds a token; a rebuilt bundle is checked
+ * against the full hash.
+ */
+export declare function clientHash(clientCode: string): string;
+export type CompileInput = {
+    renderingId: string;
+    kind?: string;
+    name?: string;
+    code: string;
+    clientCode?: string | null;
+    themeCss: string;
+    themeTokens?: string | null;
+    /** combineThemeHash(theme file hash, tokens). */
+    themeHash: string;
+};
+/** The compiled rendering, from the cache or a compile thread. Concurrent calls share one compile. */
+export declare function compileRendering(config: DynamicRenderingsConfig, input: CompileInput): Promise<CompiledRendering>;
+/** What the render threads need of a compiled rendering. */
+export declare function moduleOf(compiled: Extract<CompiledRendering, {
+    ok: true;
+}>): EngineModuleSource;
+/** Keeps a browser bundle, by rendering and client hash, with the approval the CM reported for it just now. */
+export declare function rememberClientBundle(renderingId: string, client: Pick<CompiledClient, "hash" | "sourceHash" | "browser">, approved: boolean): void;
+export declare function lookupClientBundle(renderingId: string, hash: string): ClientBundle | undefined;
+export type TenantComponent = {
+    key: string;
+    buildId: string;
+    dto: ComponentDto;
+};
+/** Renders the components of one tenant in that tenant's render thread. */
+export declare function renderTenant(config: DynamicRenderingsConfig, tenant: string, components: TenantComponent[], modules: Record<string, EngineModuleSource>, options?: {
+    deadlineMs?: number;
+    fresh?: boolean;
+}): Promise<RenderResult[]>;
+/** For tests: forget cached compiles and bundles (the engine keeps running). */
+export declare function clearCompileCache(): void;
+/** Cache figures, for diagnostics. */
+export declare function compileCacheStats(): {
+    entries: number;
+    bytes: number;
+    inflight: number;
+    bundles: number;
+};

package/dist/server/engine.js

@@ -0,0 +1,207 @@
+import "server-only";
+import { createHash } from "node:crypto";
+import { verifyScopedCss } from "../css-policy/css-policy.mjs";
+// The host compiles and runs renderings itself, through @alpaca-headless/dynamic-renderings-engine:
+// compile threads and QuickJS render threads inside this process (the main thread never runs
+// rendering code). The engine is an external package for Next (see withDynamicRenderings), so
+// its thread files load from disk instead of being bundled.
+//
+// Compiled renderings are cached per process, keyed by rendering id, source hashes and theme hash
+// (the stylesheet embeds the rendering id, so identical source in two items is two entries). The
+// cache is byte-counted and evicts the least recently used entry. Failures that say something
+// about the source are cached like successes; transient ones (queue full, deadline, a stopped
+// thread) are not.
+//
+// Browser bundles of client code are kept apart, by rendering id and client hash, with the
+// approval the CM last reported for them: the bundle route serves them from there.
+const MAX_CACHE_BYTES = 128 * 1024 * 1024;
+const MAX_BUNDLE_BYTES = 32 * 1024 * 1024;
+// Next can evaluate this module more than once in one process (dev reloads, separate route
+// bundles). One engine per process: the holder lives on globalThis.
+const HOLDER = Symbol.for("parhelia.dynamic-renderings.engine");
+function holder() {
+    const g = globalThis;
+    const h = (g[HOLDER] ??= { entries: new Map(), bytes: 0, inflight: new Map(), bundles: new Map(), bundleBytes: 0 });
+    // A holder an earlier version of this module created in the same process.
+    h.bundles ??= new Map();
+    h.bundleBytes ??= 0;
+    return h;
+}
+// The engine starts its threads from files next to its own module, so no bundler may touch it:
+// the import stays a runtime import, which Node resolves from the app's node_modules. Marking the
+// package external (serverExternalPackages) is not enough on its own, because Next bundles
+// linked packages that resolve outside node_modules anyway.
+const ENGINE_PACKAGE = "@alpaca-headless/dynamic-renderings-engine";
+export function getEngine(config) {
+    const h = holder();
+    h.engine ??= import(/* webpackIgnore: true */ /* turbopackIgnore: true */ ENGINE_PACKAGE).then((m) => m.createEngine({ renderThreads: config.engine.renderThreads, compileThreads: config.engine.compileThreads }));
+    return h.engine;
+}
+const sha256Hex = (text) => createHash("sha256").update(text).digest("hex");
+/** SHA-256 of the LF-normalized source, as the CM computes it. */
+export function sourceHash(code) {
+    return sha256Hex(code.replace(/\r\n/g, "\n"));
+}
+/** SHA-256 of the client code's LF-normalized text. */
+export function clientSourceHash(clientCode) {
+    return sha256Hex(clientCode.replace(/\r\n?/g, "\n"));
+}
+/**
+ * The client code's name in bundle URLs: the first 16 hex digits of clientSourceHash(). Short,
+ * because the URL sits behind a proxy prefix that holds a token; a rebuilt bundle is checked
+ * against the full hash.
+ */
+export function clientHash(clientCode) {
+    return clientSourceHash(clientCode).slice(0, 16);
+}
+function sizeOf(value) {
+    if (!value.ok)
+        return JSON.stringify(value.diagnostics).length;
+    return value.server.length + (value.css?.length ?? 0) + (value.client ? value.client.browser.length + value.client.node.length : 0);
+}
+function remember(key, value) {
+    const h = holder();
+    const bytes = sizeOf(value);
+    const previous = h.entries.get(key);
+    if (previous) {
+        h.entries.delete(key);
+        h.bytes -= previous.bytes;
+    }
+    h.entries.set(key, { value, bytes });
+    h.bytes += bytes;
+    while (h.bytes > MAX_CACHE_BYTES && h.entries.size > 1) {
+        const [oldest, entry] = h.entries.entries().next().value;
+        h.entries.delete(oldest);
+        h.bytes -= entry.bytes;
+    }
+}
+function lookup(key) {
+    const h = holder();
+    const entry = h.entries.get(key);
+    if (!entry)
+        return undefined;
+    h.entries.delete(key);
+    h.entries.set(key, entry);
+    return entry.value;
+}
+function toCompiled(buildId, renderingId, clientCode, result, cssBytes) {
+    if (!result.ok || typeof result.compiledServer !== "string") {
+        return { ok: false, buildId, diagnostics: result.diagnostics ?? [], transient: result.transient };
+    }
+    const client = typeof result.compiledClient === "string" && typeof result.compiledClientNode === "string"
+        ? {
+            browser: result.compiledClient,
+            node: result.compiledClientNode,
+            exports: result.clientExports ?? [],
+            hash: clientHash(clientCode),
+            sourceHash: clientSourceHash(clientCode),
+        }
+        : undefined;
+    const css = result.css || null;
+    if (css) {
+        // Defense in depth: the compiler scoped the stylesheet; check it again before it is ever inserted.
+        const verdict = verifyScopedCss(css, renderingId, cssBytes);
+        if (!verdict.ok) {
+            return { ok: true, buildId, server: result.compiledServer, client, css: null, cssRejected: verdict.errors.map((e) => e.message).join("; ") };
+        }
+    }
+    return { ok: true, buildId, server: result.compiledServer, client, css };
+}
+/** The compiled rendering, from the cache or a compile thread. Concurrent calls share one compile. */
+export function compileRendering(config, input) {
+    const clientCode = input.clientCode?.trim() ? input.clientCode : "";
+    const key = `${input.renderingId}:${sourceHash(input.code)}:${clientCode ? sourceHash(clientCode) : "-"}:${input.themeHash}`;
+    const cached = lookup(key);
+    if (cached)
+        return Promise.resolve(cached);
+    const h = holder();
+    let flight = h.inflight.get(key);
+    if (!flight) {
+        const buildId = sha256Hex(key).slice(0, 32);
+        flight = getEngine(config)
+            .then((engine) => engine.compile({
+            renderingId: input.renderingId,
+            kind: input.kind,
+            name: input.name,
+            code: input.code,
+            clientCode,
+            themeCss: input.themeCss,
+            themeTokens: input.themeTokens ?? "",
+        }))
+            .then((result) => {
+            const compiled = toCompiled(buildId, input.renderingId, clientCode, result, config.limits.cssBytes);
+            if (!(compiled.ok === false && compiled.transient))
+                remember(key, compiled);
+            return compiled;
+        })
+            .catch((err) => ({
+            ok: false,
+            buildId,
+            transient: true,
+            diagnostics: [{ severity: "error", file: "build", message: `The engine is not available: ${err instanceof Error ? err.message : String(err)}` }],
+        }))
+            .finally(() => h.inflight.delete(key));
+        h.inflight.set(key, flight);
+    }
+    return flight;
+}
+/** What the render threads need of a compiled rendering. */
+export function moduleOf(compiled) {
+    return compiled.client
+        ? { server: compiled.server, client: compiled.client.node, clientExports: compiled.client.exports }
+        : { server: compiled.server };
+}
+const bundleKey = (renderingId, hash) => `${renderingId}:${hash}`;
+/** Keeps a browser bundle, by rendering and client hash, with the approval the CM reported for it just now. */
+export function rememberClientBundle(renderingId, client, approved) {
+    const h = holder();
+    const key = bundleKey(renderingId, client.hash);
+    const previous = h.bundles.get(key);
+    if (previous) {
+        h.bundles.delete(key);
+        h.bundleBytes -= previous.code.length;
+    }
+    h.bundles.set(key, { code: client.browser, sourceHash: client.sourceHash, approved });
+    h.bundleBytes += client.browser.length;
+    while (h.bundleBytes > MAX_BUNDLE_BYTES && h.bundles.size > 1) {
+        const [oldest, entry] = h.bundles.entries().next().value;
+        h.bundles.delete(oldest);
+        h.bundleBytes -= entry.code.length;
+    }
+}
+export function lookupClientBundle(renderingId, hash) {
+    const h = holder();
+    const key = bundleKey(renderingId, hash);
+    const entry = h.bundles.get(key);
+    if (!entry)
+        return undefined;
+    h.bundles.delete(key);
+    h.bundles.set(key, entry);
+    return entry;
+}
+/** Renders the components of one tenant in that tenant's render thread. */
+export async function renderTenant(config, tenant, components, modules, options = {}) {
+    if (components.length === 0)
+        return [];
+    try {
+        const engine = await getEngine(config);
+        return (await engine.renderPage({ tenant, components, sources: modules, deadlineMs: options.deadlineMs, fresh: options.fresh }));
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : "The engine is not available.";
+        return components.map((c) => ({ key: c.key, ok: false, code: "render-error", message }));
+    }
+}
+/** For tests: forget cached compiles and bundles (the engine keeps running). */
+export function clearCompileCache() {
+    const h = holder();
+    h.entries.clear();
+    h.bytes = 0;
+    h.bundles.clear();
+    h.bundleBytes = 0;
+}
+/** Cache figures, for diagnostics. */
+export function compileCacheStats() {
+    const h = holder();
+    return { entries: h.entries.size, bytes: h.bytes, inflight: h.inflight.size, bundles: h.bundles.size };
+}

package/dist/server/index.d.ts

@@ -0,0 +1,12 @@
+import "server-only";
+export { defineDynamicRenderings, noTheme, inlineTheme, isSandboxTenant, ThemeUnavailableError } from "./config.js";
+export type { DynamicRenderingsConfig, DynamicRenderingsOptions, EngineSettings, ThemeSource, EditorMarkers, RequestAdapter, RequestRoute, RequestAuth, PageTransform, } from "./config.js";
+export { fetchSources } from "./backend.js";
+export type { BackendIdentity, SourcesQuery } from "./backend.js";
+export { prepareDynamicPage, prepareTheme, emptyDynamicPage, normalizeId, toDto } from "./page.js";
+export type { DynamicPageState, LayoutPage, LayoutComponent, PreparedTheme, ClientMode } from "./page.js";
+export { sanitizeTree, sanitizeProps, DENIED_DATA_ATTRIBUTE, isDeniedClass, ALLOWED_TAGS } from "./sanitize-tree.js";
+export type { SanitizeOptions } from "./sanitize-tree.js";
+export { loadTheme, hashThemeCss, combineThemeHash } from "./theme.js";
+export { getEngine, compileRendering, renderTenant, sourceHash, clientHash, clientSourceHash, moduleOf, rememberClientBundle, lookupClientBundle, clearCompileCache, compileCacheStats, } from "./engine.js";
+export type { CompiledRendering, CompiledClient, ClientBundle, CompileInput, TenantComponent } from "./engine.js";

package/dist/server/index.js

@@ -0,0 +1,8 @@
+// Server-only: the configuration, the CM client, page preparation and the engine client.
+import "server-only";
+export { defineDynamicRenderings, noTheme, inlineTheme, isSandboxTenant, ThemeUnavailableError } from "./config.js";
+export { fetchSources } from "./backend.js";
+export { prepareDynamicPage, prepareTheme, emptyDynamicPage, normalizeId, toDto } from "./page.js";
+export { sanitizeTree, sanitizeProps, DENIED_DATA_ATTRIBUTE, isDeniedClass, ALLOWED_TAGS } from "./sanitize-tree.js";
+export { loadTheme, hashThemeCss, combineThemeHash } from "./theme.js";
+export { getEngine, compileRendering, renderTenant, sourceHash, clientHash, clientSourceHash, moduleOf, rememberClientBundle, lookupClientBundle, clearCompileCache, compileCacheStats, } from "./engine.js";