@phis/ui 0.2.1 → 0.4.0

package/server-helpers/cms-bound-content.js

@@ -0,0 +1,97 @@
+import "server-only";
+import { buildPhiCmsWidgetNamespacedTypeKey } from "../constants/cms-widget-types";
+import { getBoundWidgetContents } from "../gateway/site-content";
+import { resolvePhiCmsWidgetContentBindingForConfig } from "../helpers/cms-content-binding";
+import { readPhiServerApiCredentials } from "../helpers/phis-server-credentials";
+const bindingsByCatalog = new WeakMap();
+/** Which Widget types bind content, and how, across every Module the catalog knows. */
+function readPhiCmsContentBindingsByWidgetType(catalog) {
+    const known = bindingsByCatalog.get(catalog);
+    if (known)
+        return known;
+    const bindings = new Map();
+    for (const entry of catalog.values()) {
+        for (const { definition } of entry.widgets) {
+            if (definition.contentBinding) {
+                bindings.set(buildPhiCmsWidgetNamespacedTypeKey(definition.pluginKey, definition.typeKey), definition.contentBinding);
+            }
+        }
+    }
+    bindingsByCatalog.set(catalog, bindings);
+    return bindings;
+}
+async function readPresetTreeBoundContents(trees, options) {
+    const bindings = readPhiCmsContentBindingsByWidgetType(options.runtimeModuleCatalog);
+    const bound = new Map(trees.flatMap((tree) => tree.contentWidgets).flatMap((widget) => {
+        const binding = resolvePhiCmsWidgetContentBindingForConfig(bindings.get(widget.widgetType), widget.config);
+        return binding ? [[widget.id, binding]] : [];
+    }));
+    if (bound.size === 0)
+        return { bound, byInstance: new Map() };
+    const { apiBaseUrl, internalToken } = readPhiServerApiCredentials();
+    const contents = await getBoundWidgetContents({
+        apiBaseUrl,
+        internalToken,
+        siteKey: options.siteKey,
+        instanceIds: [...bound.keys()],
+        stage: options.stage,
+        locale: options.locale,
+        cookieHeader: options.cookieHeader,
+    });
+    return { bound, byInstance: new Map(contents.map((entry) => [entry.instanceId, entry])) };
+}
+/**
+ * Puts the published content of a preset tree's bound Widgets in (phis-server CONTENT.md).
+ *
+ * A preset node is the Module's until somebody writes content for it; once a row is bound, its published
+ * version is what the live Site shows. A row without a published version leaves the node as the preset
+ * ships it. Trees the Site stored are answered with their content by phi-server and need none of this.
+ */
+export async function applyPhiPresetTreePublishedContent(tree, options) {
+    const { byInstance } = await readPresetTreeBoundContents([tree], { ...options, stage: "published" });
+    if (![...byInstance.values()].some((entry) => entry.content))
+        return tree;
+    return {
+        ...tree,
+        contentWidgets: tree.contentWidgets.map((widget) => {
+            const entry = byInstance.get(widget.id);
+            return entry?.content
+                ? { ...widget, contentVersionId: entry.currentVersionId, resolvedContent: entry.content }
+                : widget;
+        }),
+    };
+}
+/**
+ * Puts the current content of a preset tree's bound Widgets in, for the Builder: into the bound field,
+ * where an editor shows it and from where a save hands it back, and with the version it builds on. A
+ * structure save that carried the preset's shipped text instead would read as an edit, and refuse.
+ */
+export async function applyPhiPresetTreeCurrentContent(tree, options) {
+    return (await applyPhiPresetTreesCurrentContent([tree], options))[0];
+}
+/**
+ * The same for several trees with one content read. The Builder holds every Area's Shell on every view,
+ * and a read per Area was a Core call per Area (AUDIT-2026-10-13, PM12).
+ */
+export async function applyPhiPresetTreesCurrentContent(trees, options) {
+    const { bound, byInstance } = await readPresetTreeBoundContents(trees, { ...options, stage: "current" });
+    if (byInstance.size === 0)
+        return [...trees];
+    return trees.map((tree) => ({
+        ...tree,
+        contentWidgets: tree.contentWidgets.map((widget) => {
+            const entry = byInstance.get(widget.id);
+            const binding = bound.get(widget.id);
+            if (!entry || !binding)
+                return widget;
+            return {
+                ...widget,
+                config: entry.value == null ? widget.config : { ...widget.config, [binding.sourceField]: entry.value },
+                // Carried by a save outside a Canvas, so that the value put in above goes back as content.
+                contentBinding: binding,
+                contentVersionId: entry.currentVersionId,
+                resolvedContent: entry.content,
+            };
+        }),
+    }));
+}

package/server-helpers/cms-link-targets.d.ts

@@ -1,4 +1,5 @@
 import "server-only";
+import { type PhiLinkTargetReference } from "../helpers/link-target";
 import type { PhiBlockRuntime } from "../types";
 import type { PhiResolvedLinkTargets } from "../types/references";
 import type { PhiResolvedCmsRenderableTree } from "../types/cms";
@@ -13,4 +14,10 @@ import type { PhiResolvedCmsRenderableTree } from "../types/cms";
  *
  * A page that links to nothing gets `null` and costs nothing, which is most pages.
  */
-export declare function resolvePhiCmsTreeLinkTargets(tree: Pick<PhiResolvedCmsRenderableTree, "layoutNodes" | "contentWidgets" | "overlays">, runtime: Pick<PhiBlockRuntime, "site" | "locale" | "area" | "viewer">): Promise<PhiResolvedLinkTargets | null>;
+export declare function resolvePhiCmsTreeLinkTargets(tree: Pick<PhiResolvedCmsRenderableTree, "regions" | "layoutNodes" | "contentWidgets" | "overlays">, runtime: Pick<PhiBlockRuntime, "site" | "locale" | "area" | "viewer">): Promise<PhiResolvedLinkTargets | null>;
+/**
+ * The same resolution for targets that are not in a tree -- a News entry's link, read while the list is
+ * drawn. Collect them with `collectPhiLinkTargetReferences` under a `linkTarget` key and resolve them
+ * here, once for all of them.
+ */
+export declare function resolvePhiLinkTargetReferences(references: ReadonlyMap<string, PhiLinkTargetReference>, runtime: Pick<PhiBlockRuntime, "site" | "locale" | "area" | "viewer">): Promise<PhiResolvedLinkTargets | null>;

package/server-helpers/cms-link-targets.js

@@ -14,9 +14,21 @@ import { resolvePhiWidgetInternalReferences } from "../components/widgets/helper
  */
 export async function resolvePhiCmsTreeLinkTargets(tree, runtime) {
     const references = new Map();
-    for (const node of [...tree.overlays, ...tree.layoutNodes, ...tree.contentWidgets]) {
+    /*
+     * The Regions as well: a Shell Region names the Pages it stands on by reference (SHELL.md "Region
+     * visibility per Page"), and those resolve in the same batch as every link on the page.
+     */
+    for (const node of [...tree.regions, ...tree.overlays, ...tree.layoutNodes, ...tree.contentWidgets]) {
         collectPhiLinkTargetReferences(node.config, references);
     }
+    return resolvePhiLinkTargetReferences(references, runtime);
+}
+/**
+ * The same resolution for targets that are not in a tree -- a News entry's link, read while the list is
+ * drawn. Collect them with `collectPhiLinkTargetReferences` under a `linkTarget` key and resolve them
+ * here, once for all of them.
+ */
+export async function resolvePhiLinkTargetReferences(references, runtime) {
     if (references.size === 0) {
         return null;
     }

package/server-helpers/cms-lookup.d.ts

@@ -0,0 +1,22 @@
+import "server-only";
+import { type PhiCmsAreaKey } from "../constants/cms-areas";
+import type { PhiCmsSiteBridge } from "../types/cms-plugins";
+import type { PhiSiteRequestContext } from "../types/site-request-context";
+/**
+ * The request resolution run as a lookup: same routing table, same access checks, same Builder-configured
+ * root route, binding no request state.
+ *
+ * A route handler and a sitemap have no request runtime bound, and a lookup deliberately binds none --
+ * but the helpers under the resolution (translations, locale fetches) read one globally. The scope here
+ * gives them a runtime for exactly this unit of work, isolated from everything outside it. Two callers
+ * built this scaffold for themselves, lambda for lambda, differing only in the cookie they carried.
+ */
+export declare function resolvePhiCmsLookup({ bridge, area, locale, path, cookieHeader, requestContext, }: {
+    bridge: PhiCmsSiteBridge;
+    area: PhiCmsAreaKey;
+    locale: string;
+    path: string;
+    /** The viewer's cookies, or none for a question asked on nobody's behalf (a crawler's). */
+    cookieHeader: string;
+    requestContext: PhiSiteRequestContext;
+}): Promise<import("../types").PhiResolvedCmsRequest | null>;

package/server-helpers/cms-lookup.js

@@ -0,0 +1,56 @@
+import "server-only";
+import { resolvePhiCmsAreaMask } from "../constants/cms-areas";
+import { getPhiCmsPage, getPhiExactSiteArea } from "./cms";
+import { resolvePhiCmsRequest } from "./cms-request";
+import { runWithPhiRequestRuntime } from "./request-runtime";
+import { buildPhiBlockRuntime } from "./runtime";
+/**
+ * The request resolution run as a lookup: same routing table, same access checks, same Builder-configured
+ * root route, binding no request state.
+ *
+ * A route handler and a sitemap have no request runtime bound, and a lookup deliberately binds none --
+ * but the helpers under the resolution (translations, locale fetches) read one globally. The scope here
+ * gives them a runtime for exactly this unit of work, isolated from everything outside it. Two callers
+ * built this scaffold for themselves, lambda for lambda, differing only in the cookie they carried.
+ */
+export async function resolvePhiCmsLookup({ bridge, area, locale, path, cookieHeader, requestContext, }) {
+    const bridgeRuntime = bridge.runtime;
+    if (!bridgeRuntime) {
+        throw new Error("A CMS lookup needs the Site Bridge's runtime.");
+    }
+    const { siteKey, apiBaseUrl, internalToken } = bridgeRuntime;
+    const scopeRuntime = buildPhiBlockRuntime({
+        requestContext,
+        areaMask: resolvePhiCmsAreaMask(area),
+    });
+    return runWithPhiRequestRuntime(scopeRuntime, () => resolvePhiCmsRequest({
+        siteKey,
+        locale,
+        area,
+        path,
+        cookieHeader,
+        apiBaseUrl,
+        internalToken,
+        requestContext,
+        runtimeModuleCatalog: bridge.runtimeModuleCatalog,
+        purpose: "lookup",
+        loadExactCmsArea: (requestPath, sourcePreset) => getPhiExactSiteArea({
+            path: requestPath,
+            siteKey,
+            apiBaseUrl,
+            internalToken,
+            locale,
+            cookieHeader,
+            sourcePreset,
+        }),
+        loadResolvedCmsPage: (requestPath, sourcePreset) => getPhiCmsPage({
+            path: requestPath,
+            siteKey,
+            apiBaseUrl,
+            internalToken,
+            locale,
+            cookieHeader,
+            sourcePreset,
+        }),
+    }));
+}

package/server-helpers/cms-node-features.d.ts

@@ -1,5 +1,5 @@
 import "server-only";
-import { type PhiRuntimeFeatureState } from "../types/runtime-condition";
+import type { PhiRuntimeFeatureState } from "../types/runtime-condition";
 import type { PhiBlockRuntime } from "../types";
 import type { PhiCmsRuntimeRenderRegistry } from "../types/cms-plugins";
 import type { PhiResolvedCmsRenderableTree } from "../types/cms";
@@ -10,11 +10,25 @@ import type { PhiResolvedCmsRenderableTree } from "../types/cms";
  * Module's own configuration, and reading them means asking that Module's server half.
  */
 export declare function collectPhiCmsFeatureNamespaces(tree: Pick<PhiResolvedCmsRenderableTree, "layoutNodes" | "contentWidgets" | "overlays">): Set<string>;
+/**
+ * What the Modules answered, and which of them could not be asked.
+ *
+ * `features` is null when the tree asks nothing. `failures` names every namespace the tree asked about
+ * that has no answer -- no active Module publishes it, its loader threw, or its resolver did -- with
+ * the reason, so the renderer can say so where the node would have stood instead of leaving a hole
+ * that reads as "the Module has nothing to show".
+ */
+export type PhiCmsTreeFeatureResolution = {
+    features: PhiRuntimeFeatureState | null;
+    failures: ReadonlyMap<string, string>;
+};
 /**
  * What the active Modules say about this Site, for the namespaces this page asked about.
  *
  * A Module that cannot answer is left out rather than guessed at: its namespace stays absent, every
  * condition over it reads `unavailable`, and the node it guards stays hidden. For a sign-in that is the
- * right way round -- a method whose configuration could not be read is not a method to offer.
+ * right way round -- a method whose configuration could not be read is not a method to offer. The
+ * failure itself is not swallowed: it is logged with the namespace, and handed back in `failures` for
+ * the renderer to show the author (`renderCmsDiagnostic`, code `feature-unavailable`).
  */
-export declare function resolvePhiCmsTreeFeatures(tree: Pick<PhiResolvedCmsRenderableTree, "layoutNodes" | "contentWidgets" | "overlays">, registry: Pick<PhiCmsRuntimeRenderRegistry, "featureResolverLoadersByNamespace">, runtime: Pick<PhiBlockRuntime, "site" | "locale">): Promise<PhiRuntimeFeatureState | null>;
+export declare function resolvePhiCmsTreeFeatures(tree: Pick<PhiResolvedCmsRenderableTree, "layoutNodes" | "contentWidgets" | "overlays">, registry: Pick<PhiCmsRuntimeRenderRegistry, "featureResolverLoadersByNamespace">, runtime: Pick<PhiBlockRuntime, "site" | "locale" | "area">): Promise<PhiCmsTreeFeatureResolution>;

package/server-helpers/cms-node-features.js

@@ -1,10 +1,7 @@
 import "server-only";
 import { phiRuntime } from "./phi-runtime";
-import { readPhiCmsNodeVisibleWhen } from "../helpers/cms-node-visibility";
-import { collectPhiRuntimeValueConditions, } from "../types/runtime-condition";
-function readNamespace(valuePath) {
-    return valuePath.split(".")[0]?.trim() ?? "";
-}
+import { logRuntimeEvent } from "../net/log";
+import { collectPhiCmsNodeFeatureNamespaces, readPhiCmsNodeVisibleWhen, } from "../helpers/cms-node-visibility";
 /**
  * Which Modules this page needs an answer from, read off the conditions it actually carries.
  *
@@ -14,12 +11,8 @@ function readNamespace(valuePath) {
 export function collectPhiCmsFeatureNamespaces(tree) {
     const namespaces = new Set();
     for (const node of [...tree.overlays, ...tree.layoutNodes, ...tree.contentWidgets]) {
-        for (const condition of collectPhiRuntimeValueConditions(readPhiCmsNodeVisibleWhen(node.config))) {
-            if (condition.source !== "feature")
-                continue;
-            const namespace = readNamespace(condition.valuePath);
-            if (namespace)
-                namespaces.add(namespace);
+        for (const namespace of collectPhiCmsNodeFeatureNamespaces(readPhiCmsNodeVisibleWhen(node.config))) {
+            namespaces.add(namespace);
         }
     }
     return namespaces;
@@ -29,12 +22,15 @@ export function collectPhiCmsFeatureNamespaces(tree) {
  *
  * A Module that cannot answer is left out rather than guessed at: its namespace stays absent, every
  * condition over it reads `unavailable`, and the node it guards stays hidden. For a sign-in that is the
- * right way round -- a method whose configuration could not be read is not a method to offer.
+ * right way round -- a method whose configuration could not be read is not a method to offer. The
+ * failure itself is not swallowed: it is logged with the namespace, and handed back in `failures` for
+ * the renderer to show the author (`renderCmsDiagnostic`, code `feature-unavailable`).
  */
 export async function resolvePhiCmsTreeFeatures(tree, registry, runtime) {
     const namespaces = collectPhiCmsFeatureNamespaces(tree);
+    const failures = new Map();
     if (namespaces.size === 0) {
-        return null;
+        return { features: null, failures };
     }
     const rt = phiRuntime(runtime);
     const context = {
@@ -45,14 +41,24 @@ export async function resolvePhiCmsTreeFeatures(tree, registry, runtime) {
     };
     const resolved = await Promise.all([...namespaces].map(async (namespace) => {
         const load = registry.featureResolverLoadersByNamespace.get(namespace);
-        if (!load)
+        if (!load) {
+            failures.set(namespace, `No active Module publishes the "${namespace}" features.`);
             return null;
+        }
         try {
             const resolve = await load();
             return [namespace, await resolve(context)];
         }
         catch (error) {
-            console.error(`Failed to resolve "${namespace}" features for this render.`, error);
+            const message = error instanceof Error ? error.message : String(error);
+            failures.set(namespace, message);
+            logRuntimeEvent("error", "cms.features.resolve_failed", {
+                message: `Failed to resolve "${namespace}" features for this render.`,
+                siteKey: rt.siteKey,
+                area: runtime.area,
+                error,
+                meta: { namespace },
+            });
             return null;
         }
     }));
@@ -61,5 +67,5 @@ export async function resolvePhiCmsTreeFeatures(tree, registry, runtime) {
         if (entry)
             features[entry[0]] = entry[1];
     }
-    return features;
+    return { features, failures };
 }

package/server-helpers/cms-request.js

@@ -10,8 +10,10 @@ import { hasPhiFlag } from "../helpers/flags";
 import { resolvePhiRuntimeModuleServerBinding } from "../plugins/runtime-modules/server-capabilities";
 import { resolvePhiAuthUiRuntimeProjection } from "./auth-ui-provider";
 import { applyPhiBackgroundAssetProjection, resolvePhiBackgroundAssetProjection, } from "../components/widgets/helpers/background-reference-resolver.server";
+import { logRuntimeEvent } from "../net/log";
 import { getPhiCmsPage, getPhiExactSiteArea } from "./cms";
 import { buildPhiLocalCmsAreaPayload } from "./cms-area";
+import { applyPhiPresetTreePublishedContent } from "./cms-bound-content";
 import { resolvePhiAreaPageReferencePath, resolvePhiAreaRootRouteDecision } from "./area-root-route";
 import { fetchSiteNavigationFolderTarget } from "../gateway/site-nav";
 import { applyPhiAreaRootRouteDecision, buildPhiFolderAddressRedirectPage } from "../helpers/cms-area-root-route";
@@ -31,15 +33,16 @@ async function instantiatePhiRoutePresetPage({ binding, requestedPath, areaMask,
             presetKey: binding.descriptor.presetKey,
             sourcePresetVersion: binding.descriptor.presetVersion,
         },
-        page: await instantiatePhiCmsRoutePreset({
+        page: await applyPhiPresetTreePublishedContent(await instantiatePhiCmsRoutePreset({
             binding,
             catalog,
             activeModuleIds: activeModuleKeys,
             siteId,
             path: requestedPath,
             runtime,
-            resolveMissingPageTitle: (sourceTitle) => trForLocale(runtime.locale.current, sourceTitle),
-        }),
+            // The route's title is the owning Module's text, written in that Module's language.
+            resolveMissingPageTitle: (sourceTitle) => trForLocale(runtime.locale.current, sourceTitle, 0, 0, "text", catalog.sourceLocaleByModuleId.get(binding.descriptor.ownerModuleId)),
+        }), { runtimeModuleCatalog, siteKey: runtime.site.key, locale: runtime.locale.current }),
     };
 }
 function resolveAreaOwnedStoragePath(path, areaMask) {
@@ -76,12 +79,19 @@ export function resolveActivePresetModuleKeys(runtimeModuleCatalog, area, areaPr
             // what its Widgets show may differ per person, that it is loaded may not.
             const bindingResolution = resolvePhiRuntimeModuleServerBinding(definition.serverBinding, serverCapabilities);
             if (!bindingResolution.available) {
-                console.warn("[phi-runtime-modules] Server capability requirement unavailable.", {
-                    moduleId: moduleKey,
-                    providerId: definition.serverBinding.providerId,
-                    state: bindingResolution.state,
-                    diagnosticCode: bindingResolution.diagnosticCode,
-                    missingCapabilities: bindingResolution.missingCapabilities,
+                // The Module is selected and installed, and the server half it needs is not there. It stays off
+                // for the whole Area -- and the log names it, because the page it leaves looks like a page the
+                // Site chose.
+                logRuntimeEvent("warn", "runtime_modules.server_capability.unavailable", {
+                    message: "A selected Module is off: its server capability requirement is unavailable.",
+                    area,
+                    pluginKey: moduleKey,
+                    meta: {
+                        providerId: definition.serverBinding.providerId,
+                        state: bindingResolution.state,
+                        diagnosticCode: bindingResolution.diagnosticCode,
+                        missingCapabilities: bindingResolution.missingCapabilities,
+                    },
                 });
                 continue;
             }
@@ -154,16 +164,17 @@ export async function resolvePhiCmsRequest({ siteKey, locale, area, path, cookie
         ownerModuleId: areaShellBinding.descriptor.ownerModuleId,
         presetKey: areaShellBinding.descriptor.presetKey,
     };
-    const [exactAreaPreset, localAreaPreset] = await Promise.all([
-        loadExactCmsArea(path, areaSourcePreset),
-        buildPhiLocalCmsAreaPayload({
+    const exactAreaPreset = await loadExactCmsArea(path, areaSourcePreset);
+    // Only where nothing is stored; see the same step in `cms-root.ts`.
+    const localAreaPreset = exactAreaPreset
+        ? null
+        : await buildPhiLocalCmsAreaPayload({
             areaMask,
             siteId: resolvedRequestContext.site.id,
             path,
             runtime,
             runtimeModuleCatalog,
-        }),
-    ]);
+        });
     const effectiveAreaPreset = exactAreaPreset ?? localAreaPreset;
     const siteId = localAreaPreset?.preset.preset.siteId ?? resolvedRequestContext.site.id;
     const areaOwnedStoragePath = resolveAreaOwnedStoragePath(path, areaMask);
@@ -172,13 +183,6 @@ export async function resolvePhiCmsRequest({ siteKey, locale, area, path, cookie
         ...runtime,
         authUiProvider: resolvePhiAuthUiRuntimeProjection(runtimeModuleCatalog, activeModuleKeys, requestedAreaKey),
     };
-    if (ownsRequestState) {
-        setPhiRequestRuntime(runtimeWithAuthProvider);
-        setPhiRequestNavigationContext(requestedAreaKey, catalog, activeModuleKeys);
-    }
-    const areaAllowed = canPhiViewerAccess(runtime.viewer, areaShellBinding.descriptor.area === requestedAreaKey
-        ? catalog.areaDefinitions.get(requestedAreaKey)?.accessPolicy
-        : undefined);
     const routeTable = compilePhiCmsActiveRouteTable({
         catalog,
         area: requestedAreaKey,
@@ -186,6 +190,13 @@ export async function resolvePhiCmsRequest({ siteKey, locale, area, path, cookie
         publicRoutePaths: readPhiAreaPublicRoutePaths(effectiveAreaPreset?.preset.preset.config),
         landingSelection: readPhiAreaLandingSelection(effectiveAreaPreset?.preset.preset.config),
     });
+    if (ownsRequestState) {
+        setPhiRequestRuntime(runtimeWithAuthProvider);
+        setPhiRequestNavigationContext(requestedAreaKey, catalog, activeModuleKeys, routeTable);
+    }
+    const areaAllowed = canPhiViewerAccess(runtime.viewer, areaShellBinding.descriptor.area === requestedAreaKey
+        ? catalog.areaDefinitions.get(requestedAreaKey)?.accessPolicy
+        : undefined);
     const routeBinding = areaOwnedStoragePath && areaAllowed
         ? resolvePhiCmsRoutePreset(routeTable, areaOwnedStoragePath)
         : null;
@@ -216,8 +227,7 @@ export async function resolvePhiCmsRequest({ siteKey, locale, area, path, cookie
             requestedStoragePath: areaOwnedStoragePath,
             runtime: runtimeWithAuthProvider,
             area: requestedAreaKey,
-            catalog,
-            activeModuleIds: activeModuleKeys,
+            routeTable,
         })
         : null;
     /*
@@ -239,8 +249,7 @@ export async function resolvePhiCmsRequest({ siteKey, locale, area, path, cookie
             runtime: runtimeWithAuthProvider,
             reference: folderTargetReference,
             area: requestedAreaKey,
-            catalog,
-            activeModuleIds: activeModuleKeys,
+            routeTable,
         })
         : null;
     const folderRedirectPage = folderTargetPath && folderTargetPath !== areaOwnedStoragePath
@@ -293,11 +302,28 @@ export async function resolvePhiCmsRequest({ siteKey, locale, area, path, cookie
         runtime: resolvedRuntime,
         trees: [resolvedContent.page, areaPresetTree],
     });
+    /*
+     * The route's Tour, read from the binding rather than the tree: a Page the Site edited is loaded from
+     * its record and never runs the preset's loader, and it is still the Page the Tour was written for.
+     * Not for a dynamic route -- an exact Site Page may answer its address -- nor for a root that forwards.
+     */
+    const routeTour = routeBinding?.descriptor.tour
+        && Object.keys(routeBinding.params).length === 0
+        && resolvedPage === loadedPage
+        ? routeBinding.descriptor.tour
+        : null;
     return {
         areaPreset: areaPresetTree && applyPhiBackgroundAssetProjection(areaPresetTree, backgroundAssets),
         page: applyPhiBackgroundAssetProjection(resolvedContent.page, backgroundAssets),
         runtime: resolvedRuntime,
         serverCapabilities: resolvedRequestContext.serverCapabilities,
+        pageTour: routeTour
+            ? {
+                definition: routeTour,
+                ownerModuleId: routeBinding.descriptor.ownerModuleId,
+                sourceLocale: catalog.sourceLocaleByModuleId.get(routeBinding.descriptor.ownerModuleId),
+            }
+            : null,
     };
 }
 export const loadPhiResolvedCmsRequest = cache(async function loadPhiResolvedCmsRequest(siteKey, locale, area, path, cookieHeader, apiBaseUrl, internalToken, requestContext, searchParams, runtimeModuleCatalog, purpose = "render") {

package/server-helpers/cms-review.d.ts

@@ -1,6 +1,7 @@
 import "server-only";
 import type { PhiSiteRequestContext } from "../types/site-request-context";
-export type PhiCmsReviewKind = "area" | "page" | "navigation" | "theme";
+import { type PhiCmsReviewKind } from "../helpers/cms-scope-search-params";
+export type { PhiCmsReviewKind };
 export type PhiCmsReviewParams = {
     kind: PhiCmsReviewKind;
     revisionId: number;
@@ -11,6 +12,18 @@ export type PhiCmsReviewParams = {
 };
 export declare function resolvePhiCmsReviewParams(searchParams?: Record<string, string | undefined>): PhiCmsReviewParams | null;
 export declare function getPhiCmsReviewRevision(review: PhiCmsReviewParams | null | undefined, kind: PhiCmsReviewKind): number | null;
+/**
+ * Whether this request reads the Area or the Page as a revision Core had to authorize.
+ *
+ * `revision` and a review of kind `area` or `page` are passed on to Core's Area and Page reads, and
+ * Core answers them only to a viewer it allows to preview (`requireSiteCmsPreviewApiContext`); a
+ * refusal comes back as 401/403 before anything renders. That is what lets the Area access guard step
+ * aside for such a request: somebody else has already decided. A review of kind `navigation` or
+ * `theme` changes neither read -- the Area and the Page come back live, unauthorized -- so it is no
+ * reason to step aside. Deciding on "any valid review" did exactly that, and
+ * `?reviewKind=navigation&reviewRevision=1` showed an anonymous visitor a staff Area's shell.
+ */
+export declare function hasPhiCmsAuthorizedPreviewRead(searchParams?: Record<string, string | undefined>): boolean;
 export declare function resolvePhiCmsRevisionFromSearchParams(searchParams?: Record<string, string | undefined>): number | null;
 export declare function resolvePhiCmsThemeReviewRequestContext({ requestContext, searchParams, cookieHeader, }: {
     requestContext: PhiSiteRequestContext;

package/server-helpers/cms-review.js

@@ -1,14 +1,10 @@
 import "server-only";
 import { getSiteThemeRevision } from "../gateway/site-theme";
 import { readPhiServerApiCredentials } from "../helpers/phis-server-credentials";
+import { isPhiCmsReviewKind } from "../helpers/cms-scope-search-params";
 function normalizeReviewKind(value) {
     const normalized = value?.trim().toLowerCase();
-    return normalized === "area" ||
-        normalized === "page" ||
-        normalized === "navigation" ||
-        normalized === "theme"
-        ? normalized
-        : null;
+    return isPhiCmsReviewKind(normalized) ? normalized : null;
 }
 function normalizeOptionalString(value) {
     const normalized = value?.trim();
@@ -33,6 +29,24 @@ export function resolvePhiCmsReviewParams(searchParams) {
 export function getPhiCmsReviewRevision(review, kind) {
     return review?.kind === kind ? review.revisionId : null;
 }
+/**
+ * Whether this request reads the Area or the Page as a revision Core had to authorize.
+ *
+ * `revision` and a review of kind `area` or `page` are passed on to Core's Area and Page reads, and
+ * Core answers them only to a viewer it allows to preview (`requireSiteCmsPreviewApiContext`); a
+ * refusal comes back as 401/403 before anything renders. That is what lets the Area access guard step
+ * aside for such a request: somebody else has already decided. A review of kind `navigation` or
+ * `theme` changes neither read -- the Area and the Page come back live, unauthorized -- so it is no
+ * reason to step aside. Deciding on "any valid review" did exactly that, and
+ * `?reviewKind=navigation&reviewRevision=1` showed an anonymous visitor a staff Area's shell.
+ */
+export function hasPhiCmsAuthorizedPreviewRead(searchParams) {
+    if (resolvePhiCmsRevisionFromSearchParams(searchParams) != null) {
+        return true;
+    }
+    const review = resolvePhiCmsReviewParams(searchParams);
+    return review?.kind === "area" || review?.kind === "page";
+}
 export function resolvePhiCmsRevisionFromSearchParams(searchParams) {
     const rawValue = searchParams?.revision;
     if (!rawValue?.trim()) {

package/server-helpers/cms-root.d.ts

@@ -1,3 +1,4 @@
+import { type PhiRequestSearchParams } from "./request-search-params";
 import "server-only";
 import type { PhiCmsSiteBridge } from "../types/cms-plugins";
 import type { PhiResolvedCmsRequest } from "../types/cms-plugins";
@@ -7,7 +8,7 @@ export type LoadPhiCmsRootRequestArgs = {
     path?: string[];
     cmsBridge: PhiCmsSiteBridge;
 };
-type PhiCmsRequestSearchParams = Record<string, string | undefined>;
+type PhiCmsRequestSearchParams = PhiRequestSearchParams;
 type PhiCmsServerRequest = {
     pathname?: string;
     searchParams?: PhiCmsRequestSearchParams;
@@ -19,6 +20,7 @@ type PhiCmsServerRequest = {
      */
     clientNavigation?: boolean;
 };
+/** Whether the Area access guard may step aside: only where Core authorized the read (cms-review.ts). */
 export declare function hasPhiCmsRevisionPreview(searchParams?: PhiCmsRequestSearchParams): boolean;
 export declare function loadPhiCmsRootScope({ root, path, cmsBridge, }: LoadPhiCmsRootRequestArgs): Promise<{
     resolvedRoute: import("./cms-route").PhiResolvedRootRoute;