@alpaca-headless/dynamic-renderings 1.0.4694

package/LICENSE

@@ -0,0 +1,8 @@
+Parhelia - AI-Powered Editor for Sitecore
+
+Copyright © 2025 Canvas REPLY GmbH. All rights reserved.
+
+For full license terms and legal notice, please visit:
+https://parhelia.ai/license
+
+This software is proprietary and confidential.

package/README.md

@@ -0,0 +1,147 @@
+# @alpaca-headless/dynamic-renderings
+
+Optional dynamic renderings for Alpaca Headless: React components stored as
+source on Sitecore items, compiled and run by the host itself through
+`@alpaca-headless/dynamic-renderings-engine` (compile threads and QuickJS render threads inside the
+head's process), and turned back into React. Design and threat model:
+`Headless/dynamic-renderings.md` in the Alpaca repository. No Parhelia installation is required.
+
+## Requirements
+
+- **React Server Components.** The Alpaca SDK's `Placeholder` is an async server component, so
+  every Alpaca head is an RSC app. Render trees become React elements on the server only; the
+  browser gets a rendering's client code only where it may run (see [Client code](#client-code)).
+- **Node.js server runtime**, Node 22.13 or later: the engine uses worker threads.
+- **React 19.2 or later** (`>=19.2.0 <20`).
+- **Next.js** for the ready-made adapter (`/next`, `/next/config`). Other RSC frameworks can mount
+  the framework-neutral handlers (`/handlers`) at the same paths and must load the engine unbundled.
+
+## Adopting it in a Next.js head
+
+1. Dependencies: `@alpaca-headless/dynamic-renderings` and `@alpaca-headless/dynamic-renderings-engine` (same
+   version).
+2. `src/dynamic.config.ts`, the one configured instance for the page and the routes:
+
+   ```ts
+   import { defineDynamicRenderings } from "@alpaca-headless/dynamic-renderings/server";
+   import { nextThemeFile } from "@alpaca-headless/dynamic-renderings/next";
+
+   export const dynamicConfig = defineDynamicRenderings({
+     theme: nextThemeFile("src/app/[[...path]]/theme.css"),
+   });
+   ```
+
+3. The build route, at exactly this path (the CM calls it when a rendering is checked or saved):
+
+   ```ts
+   // src/app/api/alpaca/renderings/build/route.ts
+   import { buildRoute } from "@alpaca-headless/dynamic-renderings/next";
+   import { dynamicConfig } from "../../../../../dynamic.config";
+   export const { POST } = buildRoute(dynamicConfig);
+   ```
+
+   A root `.gitignore` with a `build/` rule hides it; add
+   `!src/app/api/alpaca/renderings/build/` (or the head's path to it).
+
+4. The client bundle route, at exactly this path (pages name it in their bundle URLs):
+
+   ```ts
+   // src/app/api/alpaca/renderings/client/[file]/route.ts
+   import { clientRoute } from "@alpaca-headless/dynamic-renderings/next";
+   import { dynamicConfig } from "../../../../../../dynamic.config";
+   export const { GET } = clientRoute(dynamicConfig);
+   ```
+
+5. `next.config.js`:
+
+   ```js
+   const { withDynamicRenderings } = require("@alpaca-headless/dynamic-renderings/next/config");
+   module.exports = withDynamicRenderings(nextConfig);
+   ```
+
+   It loads the engine unbundled (`serverExternalPackages`: its threads start from files next to
+   it), traces the engine and `src/app/**/theme.css` into standalone output
+   (`withDynamicRenderings(nextConfig, { themeFile })` for another location), and keeps a catch-all
+   CORS rule off `/api/alpaca/*`, also under a prefix. When a proxy serves the head's pages under a
+   path prefix, pass its patterns as `routePrefixes` (e.g. `["/editor/proxy/:host"]`): bundle URLs
+   under them are rewritten to the bundle route. The head's own settings are kept.
+
+6. The page:
+
+   ```tsx
+   const renderer = createRenderer(dynamicConfig); // from "@alpaca-headless/dynamic-renderings/react"
+
+   const request = await readRequest(dynamicConfig, params, searchParams);   // before the layout call
+   const routeData = await resolveRoute({ path: request.route, searchParams: request.searchParams, ..., apiConfig: request.identity });
+   // ...redirects, errors, the head's own edit-mode context override (request.editing)...
+   const dynamic = await renderer.attach(context, routeData.result.page, request);
+   // render with dynamic.page and dynamic.context, never routeData's:
+   {dynamic.head}
+   {renderer.frame(dynamic, <Placeholder name="ph-content" content={dynamic.page} context={dynamic.context} />)}
+   ```
+
+   `renderer.frame` puts the tenant's theme tokens in front of the page body. `dynamic.head` holds
+   what client code needs on the page. The page must not be served from a page cache while a
+   rendering is still being compiled (`dynamic.state.preparing`); reading the request makes the
+   route dynamic already.
+
+The CM side uses the Alpaca Site Root, its Headless API key and Rendering Host settings,
+and `ALPACA_RENDERING_BUILD_KEY` (or the CM setting `Alpaca.Headless.DynamicRenderings.BuildKey`).
+The same secret must be configured on the CM and host. See `Headless/dynamic-renderings.md`.
+Nothing else runs next to the head.
+
+## Client code
+
+A rendering's `Client Code` is imported by its code as `./client`. Each client component the
+server code renders arrives as an island: a first paint the engine rendered in QuickJS (initial
+state, no effects), sanitized like any markup, with the server code's children in its place.
+Whether the browser also loads the real component is decided per page:
+
+| Page | Client code |
+| --- | --- |
+| edit mode | never: the first paint only |
+| a sealed request (`requestAuth` recognised it) | every island loads, inside an opaque-origin frame only |
+| anything else | islands of renderings the CM reports as `approved` |
+
+A bundle URL is `{prefix}/api/alpaca/renderings/client/{clientHash}-{compiledFormat}.js?id={renderingId}&database={db}`
+(plus `&page={pageId}` when sealed), where `clientHash` is the first 16 hex digits of the SHA-256
+of the LF-normalized client code. The path is kept short because a proxy prefix with a token may
+precede it and the CM limits URL paths to 260 characters. The URL names everything needed to
+build the bundle again, so any process serves it: from its compile cache when the bundle is
+approved, otherwise after asking the CM for that rendering (approved ones only without a page; a
+sealed request asks with its page and its own identity). A client code that no longer matches the
+URL's hash answers 404, and a cached bundle is reused only for exactly the code the CM returned;
+misses are remembered for a minute. Approved bundles are `public, immutable`, sealed ones
+`private, no-store`.
+The bundles take React from `globalThis.__alpaca_dynamic_react`, which `dynamic.head` sets on pages
+that load them.
+
+Editor integrations configure the rest in `defineDynamicRenderings`:
+
+- `requestAuth(headers)`: returns the CM identity of a sealed request (headers only, no cookies);
+  such a page is always a preview.
+- `transformPage(page, { sealed, prefix })`: adjusts the page data before it renders, e.g. media
+  URLs a sealed frame cannot load.
+- `editor.clientCodeHintAttribute`: in preview mode, `dynamic.head` lists the renderings with
+  client code in `<script type="application/json" {attribute}="{id},...">`.
+
+## Subpaths
+
+| Subpath | Contents | Loads in |
+| --- | --- | --- |
+| `/protocol` | limits, node types, allowed imports, compiler format, types | plain Node |
+| `/css-policy` | the stylesheet policy shared with the engine | plain Node |
+| `/rich-text` | the rich-text sanitizer | plain Node |
+| `/server` | `defineDynamicRenderings`, CM client, engine client and compile cache, page preparation, sanitizer | server (`server-only`) |
+| `/react` | `createRenderer`, render-tree conversion, trusted components | server components |
+| `/client` | the island loader and the React global for client code bundles | browser (`"use client"` per file) |
+| `/handlers` | the framework-neutral build and client bundle handlers | server |
+| `/handlers/rewrites` | the CORS exclusion source and the bundle route rewrites | plain Node |
+| `/next` | `readRequest`, `requestIdentity`, `buildRoute`, `clientRoute`, `nextThemeFile` | Next.js server |
+| `/next/config` | `withDynamicRenderings` (CommonJS and ESM) | plain Node |
+
+## Versions
+
+The head compiles and runs renderings itself, so the two packages always come from the same
+release: install them at the same version. The build route reports the compiler format
+(`compiledFormat`, 3 since client code), so the CM can tell whether a head runs client code.

package/dist/client/ClientIslandRuntime.d.ts

@@ -0,0 +1 @@
+export declare function ClientIslandRuntime(): null;

package/dist/client/ClientIslandRuntime.js

@@ -0,0 +1,12 @@
+"use client";
+// Browser bundles of client code are compiled with react, react-dom and react/jsx-runtime
+// resolved from this global, so they share the host's single React. Set once, at module
+// evaluation, before any island's effect runs. Rendered only on pages that load bundles.
+import * as React from "react";
+import * as ReactDOM from "react-dom";
+import * as jsxRuntime from "react/jsx-runtime";
+const globals = globalThis;
+globals.__alpaca_dynamic_react ??= Object.freeze({ React, ReactDOM, jsxRuntime });
+export function ClientIslandRuntime() {
+    return null;
+}

package/dist/client/DynamicIsland.d.ts

@@ -0,0 +1,12 @@
+import { type ReactNode } from "react";
+type Props = {
+    src: string;
+    exportName: string;
+    props: Record<string, unknown>;
+    firstPaint: ReactNode;
+    mode: "approved" | "sealed";
+    children?: ReactNode;
+};
+export declare function isOpaqueOrigin(): boolean;
+export declare function DynamicIsland({ src, exportName, props, firstPaint, mode, children }: Props): import("react").JSX.Element;
+export {};

package/dist/client/DynamicIsland.js

@@ -0,0 +1,55 @@
+"use client";
+import { Fragment as _Fragment, jsx as _jsx } from "react/jsx-runtime";
+// A component of a rendering's client code. It always shows the first paint the engine rendered
+// (static, sanitized) and replaces it with the real component once the browser bundle loaded.
+// The server passes this only where client code may run: `approved` for a rendering an
+// administrator approved (never in the edit canvas), `sealed` for an editor's isolated preview.
+// A sealed island also checks that it really runs in an opaque-origin document, where its code
+// cannot reach the editor, a CM response or any cookie.
+import { Component, useEffect, useState } from "react";
+class IslandBoundary extends Component {
+    state = { failed: false };
+    static getDerivedStateFromError() {
+        return { failed: true };
+    }
+    componentDidCatch(error) {
+        console.warn("[dynamic-renderings] a client component failed", error);
+    }
+    render() {
+        return this.state.failed ? this.props.fallback : this.props.children;
+    }
+}
+export function isOpaqueOrigin() {
+    return typeof self !== "undefined" && self.origin === "null";
+}
+export function DynamicIsland({ src, exportName, props, firstPaint, mode, children }) {
+    const [Loaded, setLoaded] = useState(null);
+    useEffect(() => {
+        if (mode !== "approved" && !(mode === "sealed" && isOpaqueOrigin()))
+            return;
+        // Set by ClientIslandRuntime, which the page renders whenever it loads bundles.
+        if (!globalThis.__alpaca_dynamic_react)
+            return;
+        let cancelled = false;
+        // The URL is built by the host, never by the rendering. The bundler must not rewrite it.
+        // Absolute, because Chromium does not resolve a root-relative specifier in an opaque-origin
+        // document (the sealed frame).
+        const url = new URL(src, document.baseURI).href;
+        import(/* webpackIgnore: true */ /* turbopackIgnore: true */ url)
+            .then((mod) => {
+            if (cancelled)
+                return;
+            const candidate = exportName === "default" ? mod.default : mod[exportName];
+            if (typeof candidate === "function" || (candidate && typeof candidate === "object")) {
+                setLoaded(() => candidate);
+            }
+        })
+            .catch((err) => console.warn("[dynamic-renderings] could not load client code", err));
+        return () => {
+            cancelled = true;
+        };
+    }, [src, exportName, mode]);
+    if (!Loaded)
+        return _jsx(_Fragment, { children: firstPaint });
+    return (_jsx(IslandBoundary, { fallback: firstPaint, children: _jsx(Loaded, { ...props, editing: false, children: children }) }));
+}

package/dist/client/index.d.ts

@@ -0,0 +1,2 @@
+export { DynamicIsland, isOpaqueOrigin } from "./DynamicIsland.js";
+export { ClientIslandRuntime } from "./ClientIslandRuntime.js";

package/dist/client/index.js

@@ -0,0 +1,4 @@
+// Client components. This index is deliberately not a client module itself: each file carries
+// its own "use client", so nothing server-callable ends up behind a client boundary.
+export { DynamicIsland, isOpaqueOrigin } from "./DynamicIsland.js";
+export { ClientIslandRuntime } from "./ClientIslandRuntime.js";

package/dist/css-policy/css-policy.d.mts

@@ -0,0 +1 @@
+export * from "@alpaca-headless/dynamic-renderings-engine/css-policy";

package/dist/css-policy/css-policy.mjs

@@ -0,0 +1 @@
+export * from "@alpaca-headless/dynamic-renderings-engine/css-policy";

package/dist/handlers/build.d.ts

@@ -0,0 +1,4 @@
+import "server-only";
+import type { DynamicRenderingsConfig } from "../server/config.js";
+/** POST: compile one rendering against this host's theme and try it once. */
+export declare function handleBuild(config: DynamicRenderingsConfig, request: Request): Promise<Response>;

package/dist/handlers/build.js

@@ -0,0 +1,99 @@
+import "server-only";
+import { timingSafeEqual } from "node:crypto";
+import { compileRendering, moduleOf, renderTenant } from "../server/engine.js";
+import { combineThemeHash, loadTheme } from "../server/theme.js";
+import { protocol } from "../protocol/protocol.js";
+// The CM asks this host to check a rendering before or when it is saved (the agent tools report
+// the answer). The request carries the shared build key; the host compiles against its own theme
+// and renders the result once with empty fields, in a context of its own. This route is not
+// reachable through the CM's proxies: withDynamicRenderings rewrites only the client bundle
+// route under a proxy prefix, and the head's catch-all page answers everything else there.
+//
+// compiledFormat tells the CM what this host's compiler supports: 3 and later run client code.
+function authorized(config, request) {
+    const expected = config.buildKey;
+    const given = request.headers.get("x-alpaca-build-key");
+    if (!expected || !given)
+        return false;
+    const a = Buffer.from(expected);
+    const b = Buffer.from(given);
+    return a.length === b.length && timingSafeEqual(a, b);
+}
+function failure(status, file, message) {
+    return Response.json({ ok: false, compiledFormat: protocol.compiledFormat, diagnostics: [{ severity: "error", file, message }] }, { status });
+}
+/** POST: compile one rendering against this host's theme and try it once. */
+export async function handleBuild(config, request) {
+    if (!config.buildKey)
+        return new Response(null, { status: 404 });
+    if (!authorized(config, request))
+        return new Response(null, { status: 401 });
+    let body;
+    try {
+        body = await request.json();
+    }
+    catch {
+        return Response.json({ error: "Body is not JSON." }, { status: 400 });
+    }
+    if (typeof body.renderingId !== "string" || typeof body.code !== "string") {
+        return Response.json({ error: "renderingId and code are required." }, { status: 400 });
+    }
+    let theme;
+    try {
+        theme = await loadTheme(config);
+    }
+    catch (err) {
+        return failure(500, "theme.css", `The theme file was not found or could not be read: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    const started = Date.now();
+    const renderingId = body.renderingId.replace(/[{}]/g, "").toLowerCase();
+    const kind = typeof body.kind === "string" ? body.kind.trim().toLowerCase() : undefined;
+    const clientCode = typeof body.clientCode === "string" && body.clientCode.trim() ? body.clientCode : "";
+    const themeTokens = typeof body.themeTokens === "string" ? body.themeTokens : "";
+    const themeHash = combineThemeHash(theme.hash, themeTokens);
+    if (kind === "layout") {
+        return Response.json({
+            ok: false,
+            compiledFormat: protocol.compiledFormat,
+            themeHash,
+            diagnostics: [{ severity: "error", file: "rendering.tsx", message: "Layouts are not supported." }],
+            ms: Date.now() - started,
+        });
+    }
+    const compiled = await compileRendering(config, {
+        renderingId,
+        kind,
+        name: typeof body.name === "string" ? body.name : undefined,
+        code: body.code,
+        clientCode,
+        themeCss: theme.css,
+        themeTokens,
+        themeHash,
+    });
+    if (!compiled.ok) {
+        return Response.json({ ok: false, compiledFormat: protocol.compiledFormat, themeHash, diagnostics: compiled.diagnostics, ms: Date.now() - started }, { status: compiled.transient ? 503 : 200 });
+    }
+    // One trial render with empty fields, in a fresh context that is discarded afterwards. Real
+    // pages carry field values this trial does not have, so a failure here is a warning; that
+    // includes the first paints of the client components it renders.
+    const diagnostics = [];
+    const [trial] = await renderTenant(config, "__check__", [{ key: "check", buildId: compiled.buildId, dto: { id: renderingId, language: "en", editing: false, fields: {}, placeholders: [] } }], { [compiled.buildId]: moduleOf(compiled) }, { fresh: true });
+    if (trial && !trial.ok) {
+        const file = /\(client\.tsx\)/.test(trial.message) ? "client.tsx" : "rendering.tsx";
+        diagnostics.push({ severity: "warning", file, message: `With empty fields the rendering fails (${trial.code}): ${trial.message}` });
+    }
+    if (compiled.cssRejected)
+        diagnostics.push({ severity: "error", file: "styles.css", message: compiled.cssRejected });
+    const ok = !diagnostics.some((d) => d.severity === "error");
+    return Response.json({
+        ok,
+        compiledFormat: protocol.compiledFormat,
+        themeHash,
+        compiledServer: ok ? compiled.server : undefined,
+        compiledClient: ok ? (compiled.client?.browser ?? null) : undefined,
+        clientExports: ok ? (compiled.client?.exports ?? []) : [],
+        css: ok ? compiled.css : undefined,
+        diagnostics,
+        ms: Date.now() - started,
+    });
+}

package/dist/handlers/client.d.ts

@@ -0,0 +1,6 @@
+import "server-only";
+import type { DynamicRenderingsConfig } from "../server/config.js";
+/** GET: the browser bundle of one rendering's client code. */
+export declare function handleClientBundle(config: DynamicRenderingsConfig, request: Request, file: string): Promise<Response>;
+/** For tests: forget remembered misses. */
+export declare function clearClientBundleMisses(): void;

package/dist/handlers/client.js

@@ -0,0 +1,159 @@
+import "server-only";
+import { createHash } from "node:crypto";
+import { fetchSources } from "../server/backend.js";
+import { clientSourceHash, compileRendering, lookupClientBundle, rememberClientBundle } from "../server/engine.js";
+import { combineThemeHash, loadTheme } from "../server/theme.js";
+import { normalizeId } from "../server/page.js";
+import { protocol } from "../protocol/protocol.js";
+// The browser bundle of a rendering's client code:
+//   GET /api/alpaca/renderings/client/{clientHash}-{compiledFormat}.js?id={renderingId}&database=...[&page=...]
+// The path is short on purpose: behind the sealed preview's proxy prefix, which holds a token, it
+// must stay within the CM's URL length limit (the query has a limit of its own). The URL names
+// everything needed to build the bundle again, so any head process serves it, also after its
+// compile cache evicted it or it restarted:
+//   1. an approved bundle in this process's cache is served at once;
+//   2. otherwise the CM is asked for that one rendering: without a page it answers only for
+//      approved renderings; a sealed request asks with its page and its own identity, and the
+//      CM decides whether that preview may read it;
+//   3. the returned client code must hash to the URL's (the rendering may have changed since the
+//      page was rendered; its first paint stays), and outside a sealed request it must be approved;
+//      a cached bundle is reused only for exactly that code (its full hash), else it is rebuilt;
+//   4. it is compiled, and approved bundles are served as immutable: the URL names the source and
+//      the compiler format, so its content never changes.
+// Unapproved bundles only ever reach sealed requests, and never from the cache alone. Misses are
+// remembered for a minute, so made-up URLs cannot keep the CM busy.
+const RENDERING_ID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+const BUNDLE_FILE = /^([0-9a-f]{16})-(\d{1,6})\.js$/;
+const MISS_MS = 60_000;
+const MAX_MISSES = 10_000;
+const misses = new Map();
+function missed(key) {
+    const at = misses.get(key);
+    if (at === undefined)
+        return false;
+    if (Date.now() - at < MISS_MS)
+        return true;
+    misses.delete(key);
+    return false;
+}
+function rememberMiss(key) {
+    if (misses.size >= MAX_MISSES) {
+        const now = Date.now();
+        for (const [k, at] of misses)
+            if (now - at >= MISS_MS)
+                misses.delete(k);
+        // Still full: the oldest go first (a Map iterates in insertion order).
+        for (const k of misses.keys()) {
+            if (misses.size < MAX_MISSES)
+                break;
+            misses.delete(k);
+        }
+    }
+    misses.set(key, Date.now());
+}
+function notFound() {
+    return new Response(null, { status: 404, headers: { "cache-control": "no-store" } });
+}
+function unavailable() {
+    return new Response(null, { status: 503, headers: { "cache-control": "no-store", "retry-after": "5" } });
+}
+function serve(code, sealed) {
+    return new Response(code, {
+        status: 200,
+        headers: {
+            "content-type": "text/javascript; charset=utf-8",
+            "x-content-type-options": "nosniff",
+            "cache-control": sealed ? "private, no-store" : "public, max-age=31536000, immutable",
+        },
+    });
+}
+/** The caller's own Sitecore credentials, as the page forwards them. */
+function forwardedIdentity(config, request) {
+    const headers = new Headers();
+    for (const name of ["cookie", "authorization"]) {
+        const value = request.headers.get(name);
+        if (value)
+            headers.set(name, value);
+    }
+    return { apiKey: config.apiKey, headers };
+}
+/** GET: the browser bundle of one rendering's client code. */
+export async function handleClientBundle(config, request, file) {
+    const url = new URL(request.url);
+    const renderingId = normalizeId(url.searchParams.get("id") ?? "");
+    const match = BUNDLE_FILE.exec(file);
+    if (!RENDERING_ID.test(renderingId) || !match || Number(match[2]) !== protocol.compiledFormat)
+        return notFound();
+    const hash = match[1];
+    const database = url.searchParams.get("database") || undefined;
+    const auth = config.requestAuth?.(request.headers) ?? null;
+    const sealed = auth !== null;
+    const pageId = sealed ? url.searchParams.get("page") || undefined : undefined;
+    const cached = lookupClientBundle(renderingId, hash);
+    if (cached?.approved)
+        return serve(cached.code, sealed);
+    const authHeaders = sealed ? new Headers(auth.headers) : null;
+    const missKey = [
+        renderingId,
+        file,
+        database ?? "",
+        pageId ?? "",
+        authHeaders ? createHash("sha256").update(JSON.stringify([...authHeaders])).digest("hex").slice(0, 16) : "",
+    ].join("|");
+    if (missed(missKey))
+        return notFound();
+    let response;
+    try {
+        const identity = authHeaders ? { apiKey: config.apiKey, headers: authHeaders } : forwardedIdentity(config, request);
+        response = await fetchSources(config, identity, { pageId, ids: [renderingId], database, mode: sealed ? "preview" : undefined });
+    }
+    catch (err) {
+        console.warn("[dynamic-renderings] sources call for a client bundle failed", err);
+        return unavailable();
+    }
+    if (response.status >= 500)
+        return unavailable();
+    const source = response.renderings.find((r) => normalizeId(r.id) === renderingId);
+    const code = source?.clientCode ?? "";
+    const sourceHash = clientSourceHash(code);
+    if (!source || !code.trim() || !sourceHash.startsWith(hash) || (!sealed && source.approved !== true)) {
+        rememberMiss(missKey);
+        return notFound();
+    }
+    const approved = source.approved === true;
+    if (cached && cached.sourceHash === sourceHash) {
+        rememberClientBundle(renderingId, { hash, sourceHash, browser: cached.code }, approved);
+        return serve(cached.code, sealed);
+    }
+    let theme;
+    try {
+        theme = await loadTheme(config);
+    }
+    catch (err) {
+        console.error("[dynamic-renderings] a client bundle cannot be built without the theme", err);
+        return unavailable();
+    }
+    const tokens = response.theme?.tokens ?? "";
+    const compiled = await compileRendering(config, {
+        renderingId,
+        kind: source.kind,
+        name: source.name,
+        code: source.code,
+        clientCode: code,
+        themeCss: theme.css,
+        themeTokens: tokens,
+        themeHash: combineThemeHash(theme.hash, tokens),
+    });
+    if (!compiled.ok && compiled.transient)
+        return unavailable();
+    if (!compiled.ok || !compiled.client) {
+        rememberMiss(missKey);
+        return notFound();
+    }
+    rememberClientBundle(renderingId, compiled.client, approved);
+    return serve(compiled.client.browser, sealed);
+}
+/** For tests: forget remembered misses. */
+export function clearClientBundleMisses() {
+    misses.clear();
+}

package/dist/handlers/index.d.ts

@@ -0,0 +1,3 @@
+import "server-only";
+export { handleBuild } from "./build.js";
+export { handleClientBundle, clearClientBundleMisses } from "./client.js";

package/dist/handlers/index.js

@@ -0,0 +1,6 @@
+// Framework-neutral route handlers (Web Request/Response). Mount them at exactly these paths:
+// POST /api/alpaca/renderings/build, which the CM calls, and
+// GET /api/alpaca/renderings/client/{file}?id={renderingId}&..., which the page's bundle URLs name.
+import "server-only";
+export { handleBuild } from "./build.js";
+export { handleClientBundle, clearClientBundleMisses } from "./client.js";

package/dist/next/index.d.ts

@@ -0,0 +1,5 @@
+import "server-only";
+export { readRequest, requestIdentity, splitProxyPrefix, normalizeRouteSearchParams } from "./request.js";
+export type { DynamicRequest, RouteSearchParams } from "./request.js";
+export { buildRoute, clientRoute } from "./routes.js";
+export { nextThemeFile } from "./theme.js";

package/dist/next/index.js

@@ -0,0 +1,6 @@
+// Next.js adapter (server). The next.config.js wrapper lives in "./next/config", which must stay
+// loadable from ordinary Node and therefore imports none of this.
+import "server-only";
+export { readRequest, requestIdentity, splitProxyPrefix, normalizeRouteSearchParams } from "./request.js";
+export { buildRoute, clientRoute } from "./routes.js";
+export { nextThemeFile } from "./theme.js";

package/dist/next/prefix.d.ts

@@ -0,0 +1,8 @@
+export type RouteSearchParams = URLSearchParams | Record<string, string | string[] | undefined>;
+/** The sc_* aliases the Alpaca SDK expects under their short names. */
+export declare function normalizeRouteSearchParams(searchParams: RouteSearchParams): Record<string, string | string[] | undefined>;
+/** Plain Alpaca routes have no editor proxy prefix. An editor can supply a request adapter. */
+export declare function splitProxyPrefix(path: string[] | undefined): {
+    route: string | string[];
+    prefix: string;
+};

package/dist/next/prefix.js

@@ -0,0 +1,25 @@
+// Pure helpers of the Next adapter (no Next or SDK imports), shared by readRequest and tests.
+function getSearchParamValue(searchParams, key) {
+    const value = typeof searchParams.get === "function"
+        ? searchParams.get(key)
+        : searchParams[key];
+    if (value === null)
+        return undefined;
+    return Array.isArray(value) ? value[0] : value;
+}
+/** The sc_* aliases the Alpaca SDK expects under their short names. */
+export function normalizeRouteSearchParams(searchParams) {
+    const entries = typeof searchParams.entries === "function"
+        ? Object.fromEntries(searchParams.entries())
+        : { ...searchParams };
+    const normalized = { ...entries };
+    normalized.mode ??= getSearchParamValue(searchParams, "sc_mode");
+    normalized.itemid ??= getSearchParamValue(searchParams, "sc_itemid");
+    normalized.lang ??= getSearchParamValue(searchParams, "sc_lang");
+    normalized.version ??= getSearchParamValue(searchParams, "sc_version");
+    return normalized;
+}
+/** Plain Alpaca routes have no editor proxy prefix. An editor can supply a request adapter. */
+export function splitProxyPrefix(path) {
+    return { route: path?.length ? path : "/", prefix: "" };
+}

package/dist/next/request.d.ts

@@ -0,0 +1,31 @@
+import "server-only";
+import type { DynamicRenderingsConfig } from "../server/config.js";
+import type { BackendIdentity } from "../server/backend.js";
+import type { DynamicRequestInfo } from "../react/renderer.js";
+import { normalizeRouteSearchParams, splitProxyPrefix, type RouteSearchParams } from "./prefix.js";
+export { normalizeRouteSearchParams, splitProxyPrefix, type RouteSearchParams };
+type Awaitable<T> = T | Promise<T>;
+export type DynamicRequest = DynamicRequestInfo & {
+    /** The route after any host-provided request adapter. */
+    route: string | string[];
+    /** Search params with the sc_* aliases filled in; a sealed request is always a preview. */
+    searchParams: Record<string, string | string[] | undefined>;
+    /** Whether the request is in edit mode. */
+    editing: boolean;
+    sealed: boolean;
+};
+/**
+ * Step 4 alone: the CM identity of this request. In a sealed request (the config's requestAuth
+ * recognised it) that is exactly the headers requestAuth returned, and no cookie; otherwise the
+ * forwarded Sitecore credentials. For heads that resolve their route in a cached function and
+ * need the identity there; readRequest() uses the same function. Reading request headers also
+ * opts the route out of static rendering.
+ */
+export declare function requestIdentity(config: DynamicRenderingsConfig): Promise<{
+    identity: BackendIdentity;
+    sealed: boolean;
+}>;
+/** Splits the proxy prefix, applies the search-param aliases, builds the CM identity and decides edit mode. */
+export declare function readRequest(config: DynamicRenderingsConfig, params: Awaitable<{
+    path?: string[];
+}>, searchParams: Awaitable<RouteSearchParams>): Promise<DynamicRequest>;