@alpaca-headless/dynamic-renderings 1.0.4695 → 1.0.4697

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
 
@@ -99,9 +100,11 @@ 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` |
+| anything else, edit mode included | islands of renderings the CM reports as `approved` |
+
+A loaded component always gets `editing: false`, in the edit canvas too; the first paint renders
+with `editing: true`.
 
 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
@@ -125,6 +128,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 +166,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/client/DynamicIsland.js

@@ -3,9 +3,11 @@ 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.
+// administrator approved (the edit canvas included), `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.
+// cannot reach the editor, a CM response or any cookie. The loaded component always gets
+// `editing: false` and runs as on the live page, in the edit canvas too; `editing: true` is the
+// first paint's (a static render).
 import { Component, useEffect, useState } from "react";
 class IslandBoundary extends Component {
     state = { failed: false };

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/dist/react/DynamicRendering.d.ts

@@ -22,7 +22,10 @@ export declare function ErrorBox({ title, detail }: {
  * which holds a token, it must fit the CM's URL length limit; the query has its own.
  */
 export declare function clientBundleUrl(state: Pick<DynamicPageState, "prefix" | "database" | "sealed" | "pageId">, renderingId: string, clientHash: string): string;
-/** Where this rendering's client code may run on this page, if anywhere. */
+/**
+ * Where this rendering's client code may run on this page, if anywhere: approved code everywhere,
+ * the edit canvas included (the approval is the review), and any code in the sealed preview.
+ */
 export declare function clientLoading(state: DynamicPageState, prepared: PreparedComponent, editing: boolean): ConvertContext["client"];
 /**
  * Returns the component the SDK's Placeholder mounts for every component whose layout JSON

package/dist/react/DynamicRendering.js

@@ -33,11 +33,14 @@ export function clientBundleUrl(state, renderingId, clientHash) {
         query.set("page", state.pageId);
     return `${state.prefix}/api/alpaca/renderings/client/${clientHash}-${protocol.compiledFormat}.js?${query}`;
 }
-/** Where this rendering's client code may run on this page, if anywhere. */
+/**
+ * Where this rendering's client code may run on this page, if anywhere: approved code everywhere,
+ * the edit canvas included (the approval is the review), and any code in the sealed preview.
+ */
 export function clientLoading(state, prepared, editing) {
-    if (editing || state.clientMode === "edit" || !prepared.clientHash)
+    if (!prepared.clientHash)
         return undefined;
-    if (state.clientMode === "sealed")
+    if (state.clientMode === "sealed" && !editing)
         return { mode: "sealed", src: clientBundleUrl(state, prepared.renderingId, prepared.clientHash) };
     return prepared.approved ? { mode: "approved", src: clientBundleUrl(state, prepared.renderingId, prepared.clientHash) } : undefined;
 }

package/dist/server/page.d.ts

@@ -39,10 +39,10 @@ export type PreparedTheme = {
     rejected?: string;
 };
 /**
- * Which client code loads in the browser: none in edit mode (first paints only), all of it in a
- * sealed request, and otherwise only that of approved renderings.
+ * Which client code loads in the browser: all of it in a sealed request (never in edit mode), and
+ * otherwise only that of approved renderings, the edit canvas included.
  */
-export type ClientMode = "edit" | "sealed" | "approved";
+export type ClientMode = "sealed" | "approved";
 export type DynamicPageState = {
     nonce: string;
     mode: string;

package/dist/server/page.js

@@ -16,7 +16,7 @@ export function emptyDynamicPage(mode, prefix = "", { sealed = false, pageId = "
         editing,
         preview: mode === "preview",
         sealed,
-        clientMode: editing ? "edit" : sealed ? "sealed" : "approved",
+        clientMode: sealed && !editing ? "sealed" : "approved",
         components: new Map(),
         prefix,
         pageId,

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.4695",
+  "version": "1.0.4697",
   "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.4695",
+    "@alpaca-headless/dynamic-renderings-engine": "1.0.4697",
     "lucide-react": "^1.38.0",
     "postcss": "^8.5.26",
     "postcss-selector-parser": "^7.1.6",