@alpaca-headless/dynamic-renderings 1.0.4694 → 1.0.4696

package/README.md

@@ -4,7 +4,8 @@ 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.
+`Headless/dynamic-renderings.md` in the Alpaca repository. No Parhelia installation is required; a head
+the Parhelia editor serves adds the `/parhelia` subpaths (see below).
 
 ## Requirements
 
@@ -125,6 +126,30 @@ Editor integrations configure the rest in `defineDynamicRenderings`:
 - `editor.clientCodeHintAttribute`: in preview mode, `dynamic.head` lists the renderings with
   client code in `<script type="application/json" {attribute}="{id},...">`.
 
+## Heads the Parhelia editor serves
+
+Everything Parhelia-specific lives under `/parhelia`: the editor's markers, the CM's proxy
+prefixes (`/parhelia/proxy/{name}/...`, `/parhelia/preview/{token}/{name}/...`) and the sealed
+"Run client code" preview (its token as the request's identity, and its media). Use its
+`defineDynamicRenderings` in place of the one from `/server`, and its `withDynamicRenderings`:
+
+```ts
+// src/dynamic.config.ts
+import { defineDynamicRenderings } from "@alpaca-headless/dynamic-renderings/parhelia";
+
+// src/app/api/parhelia/media/[code]/[...path]/route.ts
+import { previewMediaRoute } from "@alpaca-headless/dynamic-renderings/parhelia/next";
+export const { GET } = previewMediaRoute(dynamicConfig);
+```
+
+```js
+// next.config.js
+const { withDynamicRenderings } = require("@alpaca-headless/dynamic-renderings/parhelia/next/config");
+```
+
+Everything else (`readRequest`, `buildRoute`, `clientRoute`, `createRenderer`) comes from the
+subpaths below as in any head.
+
 ## Subpaths
 
 | Subpath | Contents | Loads in |
@@ -139,6 +164,9 @@ Editor integrations configure the rest in `defineDynamicRenderings`:
 | `/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 |
+| `/parhelia` | the Parhelia editor preset: `defineDynamicRenderings`, the preview token's `requestAuth`, `rewriteMediaUrls`, `splitProxyPrefix`, `handlePreviewMedia` | server |
+| `/parhelia/next` | `previewMediaRoute` | Next.js server |
+| `/parhelia/next/config` | `withDynamicRenderings` with the Parhelia CM's proxy prefixes and the preview media rewrite | plain Node |
 
 ## Versions
 

package/dist/parhelia/index.d.ts

@@ -0,0 +1,22 @@
+import { type DynamicRenderingsConfig, type DynamicRenderingsOptions } from "../server/config.js";
+export { splitProxyPrefix } from "./prefix.js";
+export { rewriteMediaUrls } from "./preview-media.js";
+export { handlePreviewMedia } from "./media.js";
+/** The header the CM's preview proxy adds to every request of the sealed preview frame. */
+export declare const PREVIEW_TOKEN_HEADER = "x-parhelia-preview-token";
+/**
+ * The sealed preview ("Run client code"): a request carrying the preview token reads the CM as the
+ * token's subject and nothing else. The proxy strips every cookie; the token is the whole identity.
+ */
+export declare function parheliaRequestAuth(headers: Headers): {
+    headers: {
+        "X-Parhelia-Preview-Token": string;
+    };
+} | null;
+/**
+ * defineDynamicRenderings as the Parhelia editor needs it: its nonce and slot markers, the
+ * client-code hint for the preview strip, pages served through the CM's proxies
+ * (/parhelia/proxy/{name}/..., /parhelia/preview/{token}/{name}/...), and the sealed preview's
+ * token identity and media URLs. Options given here win.
+ */
+export declare function defineDynamicRenderings(options: DynamicRenderingsOptions): DynamicRenderingsConfig;

package/dist/parhelia/index.js

@@ -0,0 +1,42 @@
+// Dynamic renderings in a head the Parhelia CM and editor serve. Everything Parhelia-specific about
+// the runtime is here: the editor's markers, the CM's proxy prefixes and the sealed "Run client
+// code" preview. The rest of the package knows no editor.
+import { defineDynamicRenderings as defineAlpacaDynamicRenderings } from "../server/config.js";
+import { splitProxyPrefix } from "./prefix.js";
+import { rewriteMediaUrls } from "./preview-media.js";
+export { splitProxyPrefix } from "./prefix.js";
+export { rewriteMediaUrls } from "./preview-media.js";
+export { handlePreviewMedia } from "./media.js";
+/** The header the CM's preview proxy adds to every request of the sealed preview frame. */
+export const PREVIEW_TOKEN_HEADER = "x-parhelia-preview-token";
+/**
+ * The sealed preview ("Run client code"): a request carrying the preview token reads the CM as the
+ * token's subject and nothing else. The proxy strips every cookie; the token is the whole identity.
+ */
+export function parheliaRequestAuth(headers) {
+    const token = headers.get(PREVIEW_TOKEN_HEADER);
+    return token ? { headers: { "X-Parhelia-Preview-Token": token } } : null;
+}
+/**
+ * defineDynamicRenderings as the Parhelia editor needs it: its nonce and slot markers, the
+ * client-code hint for the preview strip, pages served through the CM's proxies
+ * (/parhelia/proxy/{name}/..., /parhelia/preview/{token}/{name}/...), and the sealed preview's
+ * token identity and media URLs. Options given here win.
+ */
+export function defineDynamicRenderings(options) {
+    return defineAlpacaDynamicRenderings({
+        editor: { nonceAttribute: "data-parhelia-nonce", slotAttribute: "data-parhelia-slot", clientCodeHintAttribute: "data-parhelia-has-client-code" },
+        // The editor appends ?parhelia=1 in both edit and preview mode, so edit mode is only forced
+        // when the requested mode is not explicitly preview or normal. A sealed request is never an
+        // editor frame; readRequest overrides this for it.
+        requestAdapter(path, search) {
+            const editorFrame = search.parhelia === "1";
+            return { ...splitProxyPrefix(path), editorFrame, editing: editorFrame && search.mode !== "preview" && search.mode !== "normal" };
+        },
+        requestAuth: parheliaRequestAuth,
+        // The sealed frame sends no cookies, so its media URLs go through the head's media route,
+        // which reads them from the CM with the preview token.
+        transformPage: (page, { sealed, prefix }) => (sealed ? rewriteMediaUrls(page, prefix) : page),
+        ...options,
+    });
+}

package/dist/parhelia/media.d.ts

@@ -0,0 +1,3 @@
+import type { DynamicRenderingsConfig } from "../server/config.js";
+/** GET /api/parhelia/media/{code}/{...path}: one media file of the sealed preview. */
+export declare function handlePreviewMedia(config: DynamicRenderingsConfig, request: Request, code: string, path: string[]): Promise<Response>;

package/dist/parhelia/media.js

@@ -0,0 +1,37 @@
+// Media for the sealed preview. That frame has an opaque origin and sends no cookies, so its
+// page's media URLs point here (see server/preview-media.ts), and this route reads the original
+// media path from the CM with the preview token. The CM serves it as the token's subject with the
+// media item's own access rules. Reached only through the CM's preview proxy, which adds the token
+// header; without it the route answers 404.
+const PREFIXES = {
+    s: "/sitecore/shell/-/media/",
+    m: "/-/media/",
+    j: "/-/jssmedia/",
+};
+const PASS_HEADERS = ["content-type", "content-length", "content-range", "accept-ranges", "last-modified", "etag"];
+/** GET /api/parhelia/media/{code}/{...path}: one media file of the sealed preview. */
+export async function handlePreviewMedia(config, request, code, path) {
+    const auth = config.requestAuth?.(request.headers) ?? null;
+    const prefix = PREFIXES[code];
+    if (!auth || !prefix || !path?.length || path.some((segment) => !segment || segment === "." || segment === ".." || /[\\\0]/.test(segment))) {
+        return new Response(null, { status: 404 });
+    }
+    const headers = new Headers(auth.headers);
+    const range = request.headers.get("range");
+    if (range)
+        headers.set("range", range);
+    const search = new URL(request.url).search;
+    // Redirects (a login page) are failures, never followed.
+    const upstream = await fetch(config.layoutServiceUrl() + prefix + path.map(encodeURIComponent).join("/") + search, { headers, redirect: "manual", cache: "no-store" });
+    const type = upstream.headers.get("content-type") || "";
+    if ((upstream.status !== 200 && upstream.status !== 206) || type.includes("text/html")) {
+        return new Response(null, { status: upstream.status === 401 || upstream.status === 403 ? upstream.status : 404 });
+    }
+    const out = new Headers({ "cache-control": "private, max-age=300", "x-content-type-options": "nosniff" });
+    for (const name of PASS_HEADERS) {
+        const value = upstream.headers.get(name);
+        if (value)
+            out.set(name, value);
+    }
+    return new Response(upstream.body, { status: upstream.status, headers: out });
+}

package/dist/parhelia/next.d.ts

@@ -0,0 +1,10 @@
+import type { DynamicRenderingsConfig } from "../server/config.js";
+/** src/app/api/parhelia/media/[code]/[...path]/route.ts */
+export declare function previewMediaRoute(config: DynamicRenderingsConfig): {
+    GET: (request: Request, { params }: {
+        params: Promise<{
+            code: string;
+            path: string[];
+        }>;
+    }) => Promise<Response>;
+};

package/dist/parhelia/next.js

@@ -0,0 +1,10 @@
+import { handlePreviewMedia } from "./media.js";
+/** src/app/api/parhelia/media/[code]/[...path]/route.ts */
+export function previewMediaRoute(config) {
+    return {
+        GET: async (request, { params }) => {
+            const { code, path } = await params;
+            return handlePreviewMedia(config, request, code, path);
+        },
+    };
+}

package/dist/parhelia/prefix.d.ts

@@ -0,0 +1,10 @@
+/**
+ * The Parhelia CM's proxies are prefix-preserving: editor requests arrive as
+ * /parhelia/proxy/{name}/{route}, the sealed preview's as /parhelia/preview/{token}/{name}/{route}.
+ * Editor requests carry sc_itemid and resolve by item ID regardless of path; stripping the prefix
+ * also makes bare navigation under the proxy resolve the right route.
+ */
+export declare function splitProxyPrefix(path: string[] | undefined): {
+    route: string | string[];
+    prefix: string;
+};

package/dist/parhelia/prefix.js

@@ -0,0 +1,21 @@
+// Pure helper (no Next or SDK imports), shared by the Parhelia preset and tests.
+/**
+ * The Parhelia CM's proxies are prefix-preserving: editor requests arrive as
+ * /parhelia/proxy/{name}/{route}, the sealed preview's as /parhelia/preview/{token}/{name}/{route}.
+ * Editor requests carry sc_itemid and resolve by item ID regardless of path; stripping the prefix
+ * also makes bare navigation under the proxy resolve the right route.
+ */
+export function splitProxyPrefix(path) {
+    const routePath = path ?? [];
+    const head = routePath[0]?.toLowerCase();
+    const kind = routePath[1]?.toLowerCase();
+    const prefixLength = head === "parhelia" ? (kind === "proxy" ? 3 : kind === "preview" ? 4 : 0) : 0;
+    if (prefixLength && routePath.length >= prefixLength) {
+        const strippedPath = routePath.slice(prefixLength);
+        return {
+            route: strippedPath.length > 0 ? strippedPath : "/",
+            prefix: "/" + routePath.slice(0, prefixLength).map(encodeURIComponent).join("/"),
+        };
+    }
+    return { route: routePath.length > 0 ? routePath : "/", prefix: "" };
+}

package/dist/parhelia/preview-media.d.ts

@@ -0,0 +1 @@
+export declare function rewriteMediaUrls<T>(value: T, prefix: string): T;

package/dist/parhelia/preview-media.js

@@ -0,0 +1,24 @@
+// The sandboxed interactive preview has an opaque origin and sends no cookies, so a master
+// media URL (/sitecore/shell/-/media/...) would reach the CM anonymously and end on the login
+// page. In that mode every root-relative media URL in the page data is moved under the preview
+// prefix; the CM's preview proxy passes it to this host, and the media route
+// (the head's route src/app/api/parhelia/media, previewMediaRoute) reads the original path from the CM with the preview token, so
+// the request reads as the token's subject. The query, including the media hash, is untouched.
+//
+// The moved URL must not contain "-/media/": Sitecore treats any request path containing a media
+// trigger as a media request, so the original prefix is encoded as a short letter instead
+// (s = /sitecore/shell/-/media/, m = /-/media/, j = /-/jssmedia/).
+const MEDIA_URL = /(?<![\w/.:-])\/(sitecore\/shell\/-\/media\/|-\/media\/|-\/jssmedia\/)/g;
+const CODES = {
+    "sitecore/shell/-/media/": "s",
+    "-/media/": "m",
+    "-/jssmedia/": "j",
+};
+export function rewriteMediaUrls(value, prefix) {
+    if (!prefix || value === null || value === undefined)
+        return value;
+    const json = JSON.stringify(value);
+    if (!json.includes("-/media/") && !json.includes("-/jssmedia/"))
+        return value;
+    return JSON.parse(json.replace(MEDIA_URL, (_match, kind) => `${prefix}/_media/${CODES[kind]}/`));
+}

package/next-config/parhelia.cjs

@@ -0,0 +1,35 @@
+"use strict";
+// next.config.js wrapper for heads the Parhelia CM serves: withDynamicRenderings with the CM's
+// proxy prefixes, plus the sealed preview's media rewrite. Plain CommonJS, like index.cjs: it loads
+// in ordinary Node.
+const alpaca = require("./index.cjs");
+
+/** The editor proxy and the sealed preview proxy; bundle URLs under them reach the bundle route. */
+const ROUTE_PREFIXES = ["/parhelia/proxy/:host", "/parhelia/preview/:token/:host"];
+
+/** A sealed preview page's media URLs (see rewriteMediaUrls) go to the head's media route. */
+const PREVIEW_MEDIA_REWRITE = {
+  source: "/parhelia/preview/:token/:host/_media/:code/:path*",
+  destination: "/api/parhelia/media/:code/:path*",
+};
+
+/**
+ * @param {import("next").NextConfig} nextConfig
+ * @param {{ themeFile?: string, routePrefixes?: string[] }} [options] as withDynamicRenderings';
+ *   routePrefixes adds to the Parhelia prefixes.
+ */
+function withDynamicRenderings(nextConfig = {}, options = {}) {
+  const own = nextConfig.rewrites;
+  return alpaca.withDynamicRenderings(
+    {
+      ...nextConfig,
+      async rewrites() {
+        const rules = typeof own === "function" ? await own() : own;
+        return alpaca.prependRewrites(rules, [PREVIEW_MEDIA_REWRITE]);
+      },
+    },
+    { ...options, routePrefixes: [...ROUTE_PREFIXES, ...(options.routePrefixes || [])] },
+  );
+}
+
+module.exports = { ...alpaca, withDynamicRenderings, ROUTE_PREFIXES, PREVIEW_MEDIA_REWRITE };

package/next-config/parhelia.d.cts

@@ -0,0 +1,14 @@
+import type { NextConfig } from "next";
+import type { DynamicRenderingsNextOptions } from "./index.cjs";
+
+export { prependRewrites, corsExclusionSource, ENGINE_PACKAGE } from "./index.cjs";
+export type { DynamicRenderingsNextOptions };
+
+/**
+ * withDynamicRenderings for a head the Parhelia CM serves: the CM's proxy prefixes
+ * (/parhelia/proxy/:host, /parhelia/preview/:token/:host) and the sealed preview's media rewrite
+ * to /api/parhelia/media.
+ */
+export declare function withDynamicRenderings(nextConfig?: NextConfig, options?: DynamicRenderingsNextOptions): NextConfig;
+export declare const ROUTE_PREFIXES: readonly string[];
+export declare const PREVIEW_MEDIA_REWRITE: { source: string; destination: string };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alpaca-headless/dynamic-renderings",
-  "version": "1.0.4694",
+  "version": "1.0.4696",
   "description": "Optional Alpaca Headless dynamic renderings: source client, safe React rendering, client code and Next.js integration.",
   "type": "module",
   "publishConfig": {
@@ -47,6 +47,18 @@
       "types": "./next-config/index.d.cts",
       "default": "./next-config/index.cjs"
     },
+    "./parhelia": {
+      "types": "./dist/parhelia/index.d.ts",
+      "import": "./dist/parhelia/index.js"
+    },
+    "./parhelia/next": {
+      "types": "./dist/parhelia/next.d.ts",
+      "import": "./dist/parhelia/next.js"
+    },
+    "./parhelia/next/config": {
+      "types": "./next-config/parhelia.d.cts",
+      "default": "./next-config/parhelia.cjs"
+    },
     "./package.json": "./package.json"
   },
   "files": [
@@ -67,7 +79,7 @@
     "acceptance": "node scripts/acceptance.mjs"
   },
   "dependencies": {
-    "@alpaca-headless/dynamic-renderings-engine": "1.0.4694",
+    "@alpaca-headless/dynamic-renderings-engine": "1.0.4696",
     "lucide-react": "^1.38.0",
     "postcss": "^8.5.26",
     "postcss-selector-parser": "^7.1.6",