@phis/ui 0.2.1 → 0.3.0

package/plugins/runtime-modules/builder/node-config-write.d.ts

@@ -0,0 +1,38 @@
+import type { PhiCmsContentWidgetNode, PhiCmsLayoutRenderNode } from "../../../types/cms";
+import type { PhiCmsInstanceId } from "../../../types/cms-instance-id";
+import type { PhiHistoryActionKey } from "../../../components/widgets/label-types/history";
+import type { PhiDeveloperBuilderArea, PhiDeveloperBuilderRegionDraft } from "./developer-workspace-types";
+type PhiBuilderTreeNode = PhiCmsLayoutRenderNode | PhiCmsContentWidgetNode;
+/** The node with `nodeId` in a Region's tree, root included, whichever kind it is. */
+export declare function findPhiBuilderTreeNode(rootNode: PhiCmsLayoutRenderNode, nodeId: PhiCmsInstanceId): PhiBuilderTreeNode | null;
+/**
+ * The kind of step a config edit was, read off the keys it changed. An edit that changed keys of more
+ * than one kind is a change of the node's settings.
+ */
+export declare function resolvePhiBuilderConfigEditAction(before: Record<string, unknown>, after: Record<string, unknown>): PhiHistoryActionKey;
+/** What a node is called in a history step: its own label, else what its type is called. */
+export declare function resolvePhiBuilderNodeHistorySubject(area: PhiDeveloperBuilderArea, node: PhiBuilderTreeNode): string;
+/**
+ * Writes one node of a Region draft: the config `patchConfig` makes of the node's config, or -- for an
+ * edit that is not a config, such as the translation flag -- the node `patchNode` makes of it.
+ *
+ * The result is checked against the fields the node's type declares. For a Widget, the subcontrols the
+ * new config no longer has take their signal routes with them, in the same step. The step is recorded
+ * in the Region's history as `actionKey`, or as the kind the changed keys say it was.
+ *
+ * Answers `false` when the draft or the node is not there, so the caller can tell a no-op from a write.
+ */
+export declare function writePhiBuilderNode({ area, pageKey, regionKey, draftKey, baseDraft, nodeId, patchConfig, patchNode, actionKey, coalesceKey, }: {
+    area: PhiDeveloperBuilderArea;
+    pageKey: string;
+    regionKey: string;
+    draftKey: string;
+    /** The draft as it stands; read from the store when not given. */
+    baseDraft?: PhiDeveloperBuilderRegionDraft | null;
+    nodeId: PhiCmsInstanceId;
+    patchConfig?: (config: Record<string, unknown>) => Record<string, unknown>;
+    patchNode?: <TNode extends PhiBuilderTreeNode>(node: TNode) => TNode;
+    actionKey?: PhiHistoryActionKey;
+    coalesceKey?: string;
+}): boolean;
+export {};

package/plugins/runtime-modules/builder/node-config-write.js

@@ -0,0 +1,134 @@
+import { assertPhiCmsConfigFields } from "../../../helpers/cms-config-field-validation";
+import { resolvePhiWidgetSignalSubcontrolAddresses } from "../../../components/widgets/signals/signal-endpoints";
+import { getPhiBuilderModuleMetasSnapshot } from "./plugin-meta-store";
+import { getPhiDeveloperRegionDraftsSnapshot, setPhiDeveloperRegionDraft, setPhiDeveloperRegionDraftAndPruneSignalRoutes, } from "./developer-workspace-store";
+import { createPhiBuilderRegionHistoryContext } from "./history";
+import { isPhiBuilderPageScopedRegion } from "./region-keys";
+function isWidgetNode(node) {
+    return "contentVersionId" in node;
+}
+/** The node with `nodeId` in a Region's tree, root included, whichever kind it is. */
+export function findPhiBuilderTreeNode(rootNode, nodeId) {
+    if (rootNode.id === nodeId)
+        return rootNode;
+    const widget = (rootNode.childWidgets ?? []).find((child) => child.id === nodeId);
+    if (widget)
+        return widget;
+    for (const layout of rootNode.childLayouts ?? []) {
+        const found = findPhiBuilderTreeNode(layout, nodeId);
+        if (found)
+            return found;
+    }
+    return null;
+}
+/** The tree with the node `nodeId` replaced by what `patch` makes of it; untouched branches are kept. */
+function patchPhiBuilderTreeNode(rootNode, nodeId, patch) {
+    if (rootNode.id === nodeId) {
+        return patch(rootNode);
+    }
+    let changed = false;
+    const childWidgets = (rootNode.childWidgets ?? []).map((child) => {
+        if (child.id !== nodeId)
+            return child;
+        changed = true;
+        return patch(child);
+    });
+    const childLayouts = (rootNode.childLayouts ?? []).map((child) => {
+        const next = patchPhiBuilderTreeNode(child, nodeId, patch);
+        if (next !== child)
+            changed = true;
+        return next;
+    });
+    return changed ? { ...rootNode, childLayouts, childWidgets } : rootNode;
+}
+const PADDING_KEYS = new Set(["padding", "gap", "paddingTop", "paddingRight", "paddingBottom", "paddingLeft"]);
+const GEOMETRY_KEYS = new Set(["size", "minSize", "maxSize", "zIndex", "viewportFlags"]);
+/**
+ * The kind of step a config edit was, read off the keys it changed. An edit that changed keys of more
+ * than one kind is a change of the node's settings.
+ */
+export function resolvePhiBuilderConfigEditAction(before, after) {
+    const changed = [...new Set([...Object.keys(before), ...Object.keys(after)])]
+        .filter((key) => JSON.stringify(before[key] ?? null) !== JSON.stringify(after[key] ?? null));
+    const kinds = new Set(changed.map((key) => key === "effects" ? "changeNodeEffects"
+        : key === "surface" ? "changeNodeSurface"
+            : key === "anchor" ? "changeNodeAnchor"
+                : key === "signalRoutes" ? "changeNodeSignals"
+                    : key === "slotTitles" ? "renameSlot"
+                        : PADDING_KEYS.has(key) ? "changeNodePadding"
+                            : GEOMETRY_KEYS.has(key) ? "resizeNode"
+                                : "changeNodeSettings"));
+    return kinds.size === 1 ? [...kinds][0] : "changeNodeSettings";
+}
+/** What a node is called in a history step: its own label, else what its type is called. */
+export function resolvePhiBuilderNodeHistorySubject(area, node) {
+    const label = node.label?.trim();
+    if (label)
+        return label;
+    const meta = getPhiBuilderModuleMetasSnapshot(area).plugins
+        .find((candidate) => `${candidate.pluginKey}/${candidate.typeKey}` === node.widgetType);
+    return meta?.title ?? node.widgetType;
+}
+/**
+ * Writes one node of a Region draft: the config `patchConfig` makes of the node's config, or -- for an
+ * edit that is not a config, such as the translation flag -- the node `patchNode` makes of it.
+ *
+ * The result is checked against the fields the node's type declares. For a Widget, the subcontrols the
+ * new config no longer has take their signal routes with them, in the same step. The step is recorded
+ * in the Region's history as `actionKey`, or as the kind the changed keys say it was.
+ *
+ * Answers `false` when the draft or the node is not there, so the caller can tell a no-op from a write.
+ */
+export function writePhiBuilderNode({ area, pageKey, regionKey, draftKey, baseDraft, nodeId, patchConfig, patchNode, actionKey, coalesceKey, }) {
+    const draft = baseDraft ?? getPhiDeveloperRegionDraftsSnapshot()[draftKey] ?? null;
+    const rootNode = draft?.rootNode ?? null;
+    const node = rootNode ? findPhiBuilderTreeNode(rootNode, nodeId) : null;
+    if (!draft || !rootNode || !node) {
+        return false;
+    }
+    const currentConfig = node.config ?? {};
+    const nextConfig = patchConfig ? patchConfig(currentConfig) : currentConfig;
+    const meta = getPhiBuilderModuleMetasSnapshot(area).plugins
+        .find((candidate) => `${candidate.pluginKey}/${candidate.typeKey}` === node.widgetType);
+    /*
+     * A type with no metadata in the active Canvas is left alone rather than refused: the catalogue is
+     * per Area, and a node from elsewhere is a question about scope, not about this value.
+     */
+    if (meta?.fields) {
+        assertPhiCmsConfigFields(meta.fields, nextConfig, meta.title ?? node.widgetType, currentConfig);
+    }
+    const patchedNode = patchNode ? patchNode({ ...node, config: nextConfig }) : { ...node, config: nextConfig };
+    const nextDraft = { ...draft, rootNode: patchPhiBuilderTreeNode(rootNode, nodeId, () => patchedNode) };
+    const pageScoped = isPhiBuilderPageScopedRegion(regionKey);
+    const history = {
+        context: createPhiBuilderRegionHistoryContext({ area, pageKey, pageScoped }),
+        action: {
+            key: actionKey ?? resolvePhiBuilderConfigEditAction(currentConfig, nextConfig),
+            subject: resolvePhiBuilderNodeHistorySubject(area, node),
+        },
+        ...(coalesceKey ? { coalesceKey } : {}),
+    };
+    const signalSubcontrols = isWidgetNode(node) && meta?.kind === "widget" ? meta.signalSubcontrols : null;
+    const keptSubcontrols = new Set(signalSubcontrols
+        ? resolvePhiWidgetSignalSubcontrolAddresses({ blockId: node.id, config: nextConfig, signalSubcontrols })
+        : []);
+    const removedSubcontrols = signalSubcontrols
+        ? resolvePhiWidgetSignalSubcontrolAddresses({ blockId: node.id, config: currentConfig, signalSubcontrols })
+            .filter((address) => !keptSubcontrols.has(address))
+        : [];
+    if (removedSubcontrols.length > 0) {
+        const scope = pageScoped ? "page" : "area";
+        setPhiDeveloperRegionDraftAndPruneSignalRoutes({
+            draftKey,
+            draft: nextDraft,
+            area,
+            pageKey,
+            targets: removedSubcontrols.map((address) => ({ address, scope })),
+            history,
+        });
+    }
+    else {
+        setPhiDeveloperRegionDraft(draftKey, nextDraft, { history });
+    }
+    return true;
+}

package/plugins/runtime-modules/builder/node-finders.d.ts

@@ -1,5 +1,4 @@
 import type { PhiCmsContentWidgetNode, PhiCmsLayoutRenderNode } from "../../../types/cms";
 import type { PhiCmsInstanceId } from "../../../types/cms-instance-id";
 export declare function findPhiBuilderLayoutNodeById(nodes: readonly PhiCmsLayoutRenderNode[], nodeId: PhiCmsInstanceId): PhiCmsLayoutRenderNode | null;
-export declare function findPhiBuilderWidgetNodeByIdInWidgets(nodes: readonly PhiCmsContentWidgetNode[], nodeId: PhiCmsInstanceId): PhiCmsContentWidgetNode | null;
 export declare function findPhiBuilderWidgetNodeByIdInLayouts(nodes: readonly PhiCmsLayoutRenderNode[], nodeId: PhiCmsInstanceId): PhiCmsContentWidgetNode | null;

package/plugins/runtime-modules/builder/node-finders.js

@@ -10,7 +10,7 @@ export function findPhiBuilderLayoutNodeById(nodes, nodeId) {
     }
     return null;
 }
-export function findPhiBuilderWidgetNodeByIdInWidgets(nodes, nodeId) {
+function findPhiBuilderWidgetNodeByIdInWidgets(nodes, nodeId) {
     return nodes.find((node) => node.id === nodeId) ?? null;
 }
 export function findPhiBuilderWidgetNodeByIdInLayouts(nodes, nodeId) {

package/plugins/runtime-modules/builder/offered-page-catalog.d.ts

@@ -1,5 +1,4 @@
 import { type PhiBuilderPageCatalogArea, type PhiPresetPageNode } from "../../../helpers/cms-page-catalog";
-import type { PhiRuntimeModuleId } from "../../../types/cms-module-descriptors";
 import type { PhiDeveloperBuilderWorkspaceState } from "./developer-workspace-types";
 /**
  * The part of the workspace this reads, named rather than taken whole.
@@ -9,18 +8,6 @@ import type { PhiDeveloperBuilderWorkspaceState } from "./developer-workspace-ty
  * fact rather than a coincidence.
  */
 export type PhiBuilderOfferedCatalogState = Pick<PhiDeveloperBuilderWorkspaceState, "modulePresetPagesByArea" | "customPages" | "persistedPageCatalogByArea" | "navigationSurfacesByArea" | "runtimeModuleIdsByArea" | "areaRootRoutes">;
-/**
- * Which Modules answer in this Area, and which Module the Area itself is.
- *
- * Switched on here, or the Area's own base Module -- which is never in the selection because it is
- * never switchable: the Area is its Module. Leaving it out would drop the landing every Site starts
- * with from the list of the landings it may choose, and would leave the root slot with no applicant
- * to fall back to.
- */
-export declare function resolvePhiBuilderAreaModuleActivation(state: Pick<PhiBuilderOfferedCatalogState, "runtimeModuleIdsByArea">, area: PhiBuilderPageCatalogArea): {
-    baseModuleId: `${string}/${string}`;
-    isActive: (moduleId: PhiRuntimeModuleId) => boolean;
-};
 /**
  * Every Page that could stand at this Area's root, whether or not it applied for the job.
  *

package/plugins/runtime-modules/builder/offered-page-catalog.js

@@ -14,7 +14,7 @@ import { readPhiBuilderStoredAreaRootRoute } from "./developer-workspace-store";
  * with from the list of the landings it may choose, and would leave the root slot with no applicant
  * to fall back to.
  */
-export function resolvePhiBuilderAreaModuleActivation(state, area) {
+function resolvePhiBuilderAreaModuleActivation(state, area) {
     const baseModuleId = resolvePhiRuntimeAreaDefinition(resolvePhiBuilderAreaAsCmsArea(area))?.baseModuleId ?? null;
     const selectedModuleIds = new Set(state.runtimeModuleIdsByArea?.[area] ?? []);
     return {
@@ -207,7 +207,7 @@ export function resolvePhiBuilderOfferedPageKey(state, area, requestedPageKey) {
     }
     const rootRoute = readPhiBuilderStoredAreaRootRoute(state, area);
     const forwardTargetKey = rootRoute?.mode === "redirect"
-        ? findPageKeyByReference(pages, rootRoute.target)
+        ? findPageKeyByReference(pages, rootRoute.targetLinkTarget.reference)
         : null;
     return {
         pages,

package/plugins/runtime-modules/builder/options-providers.js

@@ -22,18 +22,25 @@ function resolveProviderArea(context) {
 function collectPageOptions(area, nodes) {
     return nodes.flatMap((node) => {
         const path = resolvePhiBuilderCatalogPathForCatalog(area, node.key, nodes);
+        /*
+         * The root reads as the address, not as the title of whatever Page is standing in it.
+         *
+         * Which Page answers `/` is a decision taken elsewhere and it changes -- the Area's own Page,
+         * a Module's landing, or one the Builder constructs. Showing that Page's title here would put
+         * a name in the Page list that means "the front door" today and something else tomorrow, and
+         * would read as a second entry for a Page that is already listed under its own address.
+         */
+        const label = node.storagePath === "/" ? path : node.title;
+        /*
+         * The address beside the title, as the option's hint. A title is derived from the path or written
+         * by an author, and either way it hides where the Page answers: "Zz Nw Test" is `/zz-nw-test`.
+         */
+        const address = node.storagePath ?? path;
         return [
             {
                 value: path,
-                /*
-                 * The root reads as the address, not as the title of whatever Page is standing in it.
-                 *
-                 * Which Page answers `/` is a decision taken elsewhere and it changes -- the Area's own Page,
-                 * a Module's landing, or one the Builder constructs. Showing that Page's title here would put
-                 * a name in the Page list that means "the front door" today and something else tomorrow, and
-                 * would read as a second entry for a Page that is already listed under its own address.
-                 */
-                label: node.storagePath === "/" ? path : node.title,
+                label,
+                ...(address !== label ? { description: address } : {}),
             },
             ...collectPageOptions(area, node.children ?? []),
         ];

package/plugins/runtime-modules/builder/page-preset-catalog.server.js

@@ -1,12 +1,7 @@
 import "server-only";
 import { PHI_BUILDER_AREA_KEYS } from "../../../constants/cms-areas";
 import { resolvePhiCmsDescriptorCatalog } from "../../../plugins/runtime-modules/descriptor-compiler";
-import { createPhiPresetCmsPageId } from "../../../types/cms-instance-id";
-import { buildPhiRuntimeModulePackageRoutePrefix } from "../../../helpers/runtime-module-route-path";
-function humanizePageKey(value) {
-    const label = value.replace(/[-_]+/g, " ").trim();
-    return label ? label.replace(/\b\w/g, (letter) => letter.toUpperCase()) : value;
-}
+import { insertPhiPresetPageTarget } from "../../../helpers/cms-preset-page-tree";
 function resolveBuilderArea(area) {
     if (area === "public") {
         return "public";
@@ -15,62 +10,6 @@ function resolveBuilderArea(area) {
         ? area
         : null;
 }
-function insertPageTarget(roots, target) {
-    const sourcePreset = {
-        ownerModuleId: target.ownerModuleId,
-        presetKey: target.presetKey,
-        sourcePresetVersion: target.presetVersion,
-    };
-    const pageId = createPhiPresetCmsPageId({
-        ownerModuleId: target.ownerModuleId,
-        presetKey: target.presetKey,
-    });
-    /*
-     * The package namespace is an addressing device, not structure a person authored.
-     *
-     * Every Page of a Module outside Public answers under `/<scope>/<package>`, so leaving those segments
-     * in would bury every Page two folders deep under the same two words and say nothing about how the
-     * Pages relate. The tree shows what the Module arranged below its namespace; the address keeps it.
-     */
-    const namespace = target.area === "public"
-        ? ""
-        : buildPhiRuntimeModulePackageRoutePrefix(target.ownerModuleId);
-    const treePath = namespace && target.path.startsWith(`${namespace}/`)
-        ? target.path.slice(namespace.length)
-        : target.path;
-    const segments = treePath.split("/").filter(Boolean);
-    if (segments.length === 0) {
-        roots.push({
-            key: pageId,
-            title: target.title,
-            storagePath: target.path,
-            catalogPath: treePath,
-            sourcePreset,
-            ...(target.defaultPageFlags ? { defaultPageFlags: target.defaultPageFlags } : {}),
-            ...(target.landingPage ? { landingPage: true } : {}),
-        });
-        return;
-    }
-    let siblings = roots;
-    for (const segment of segments.slice(0, -1)) {
-        let group = siblings.find((node) => node.key === segment);
-        if (!group) {
-            group = { key: segment, title: humanizePageKey(segment), children: [] };
-            siblings.push(group);
-        }
-        group.children ??= [];
-        siblings = group.children;
-    }
-    siblings.push({
-        key: pageId,
-        title: target.title,
-        storagePath: target.path,
-        catalogPath: treePath,
-        sourcePreset,
-        ...(target.defaultPageFlags ? { defaultPageFlags: target.defaultPageFlags } : {}),
-        ...(target.landingPage ? { landingPage: true } : {}),
-    });
-}
 export function buildPhiBuilderModulePresetPagesByArea(runtimeModuleCatalog) {
     const pagesByArea = PHI_BUILDER_AREA_KEYS.reduce((current, area) => ({ ...current, [area]: [] }), {});
     const catalog = resolvePhiCmsDescriptorCatalog(runtimeModuleCatalog);
@@ -84,7 +23,7 @@ export function buildPhiBuilderModulePresetPagesByArea(runtimeModuleCatalog) {
             if (!area) {
                 continue;
             }
-            insertPageTarget(pagesByArea[area], descriptor);
+            insertPhiPresetPageTarget(pagesByArea[area], descriptor);
         }
     }
     return pagesByArea;

package/plugins/runtime-modules/builder/page-presets.server.d.ts

@@ -2,9 +2,10 @@ import "server-only";
 import type { PhiBlockRuntime } from "../../../types/widget-runtime";
 import type { PhiRuntimeModuleCatalog } from "../../../types";
 import type { PhiDeveloperBuilderArea, PhiDeveloperBuilderRegionDraft } from "./developer-workspace-types";
+import type { PhiCmsTreeControllerSettings } from "../../../types/cms";
 export type PhiBuilderPageDraftsByScope = Partial<Record<PhiDeveloperBuilderArea, Partial<Record<string, PhiDeveloperBuilderRegionDraft | null>>>>;
 export type PhiBuilderPageDraftsMapByScope = Partial<Record<PhiDeveloperBuilderArea, Partial<Record<string, Record<string, PhiDeveloperBuilderRegionDraft> | null>>>>;
-export type PhiBuilderCurrentPageDrafts = {
+type PhiBuilderCurrentPageDrafts = {
     area: PhiDeveloperBuilderArea;
     pageKey: string;
     drafts: Record<string, PhiDeveloperBuilderRegionDraft>;
@@ -22,6 +23,11 @@ export type PhiBuilderPageMeta = {
      * every place that reads it.
      */
     index: boolean;
+    /**
+     * What the Page tells its Controllers, from the same chain: the stored Page, else the route's tree.
+     * Carried into the Page's next save, which states the tree whole.
+     */
+    controllerSettings: PhiCmsTreeControllerSettings;
 };
 export declare const buildPhiBuilderPagesDraftsByScope: (runtime: PhiBlockRuntime, runtimeModuleCatalog: PhiRuntimeModuleCatalog) => Promise<PhiBuilderPageDraftsMapByScope>;
 export declare function resolvePhiBuilderCurrentPageScope(runtime: PhiBlockRuntime, runtimeModuleCatalog: PhiRuntimeModuleCatalog): Promise<{
@@ -31,3 +37,4 @@ export declare function resolvePhiBuilderCurrentPageScope(runtime: PhiBlockRunti
 export declare const buildPhiBuilderCurrentPageDrafts: (runtime: PhiBlockRuntime, runtimeModuleCatalog: PhiRuntimeModuleCatalog) => Promise<PhiBuilderCurrentPageDrafts>;
 export declare const buildPhiBuilderPageMetaForScope: (runtime: PhiBlockRuntime, area: PhiDeveloperBuilderArea, pageKey: string, runtimeModuleCatalog: PhiRuntimeModuleCatalog) => Promise<PhiBuilderPageMeta>;
 export declare const buildPhiBuilderPagePresetDrafts: (runtime: PhiBlockRuntime, area: PhiDeveloperBuilderArea, pageKey: string, runtimeModuleCatalog: PhiRuntimeModuleCatalog) => Promise<PhiBuilderCurrentPageDrafts>;
+export {};

package/plugins/runtime-modules/builder/page-presets.server.js

@@ -1,4 +1,5 @@
 import "server-only";
+import { applyPhiPresetTreeCurrentContent } from "../../../server-helpers/cms-bound-content";
 import { cache } from "react";
 import { cookies } from "next/headers";
 import { PhiCmsFlags, PhiCmsStatus } from "../../../constants/phi-cms";
@@ -74,14 +75,22 @@ async function resolvePhiRegistryPresetPageBinding({ runtime, runtimeModuleCatal
         : null;
     return binding ? { binding, activeModuleKeys } : null;
 }
-function buildPhiRegistryPresetPageTree({ runtime, runtimeModuleCatalog, binding, activeModuleKeys, path, }) {
-    return instantiatePhiCmsRoutePreset({
+/**
+ * A preset Page the Site has stored nothing for, as the Builder edits it: the preset's tree with the
+ * current content of every node somebody wrote content for (phis-server CONTENT.md).
+ */
+async function buildPhiRegistryPresetPageTree({ runtime, runtimeModuleCatalog, binding, activeModuleKeys, path, }) {
+    return applyPhiPresetTreeCurrentContent(await instantiatePhiCmsRoutePreset({
         binding,
         catalog: resolvePhiCmsDescriptorCatalog(runtimeModuleCatalog),
         activeModuleIds: activeModuleKeys,
         siteId: runtime.site.id,
         path,
         runtime,
+    }), {
+        runtimeModuleCatalog,
+        siteKey: runtime.site.key,
+        cookieHeader: (await cookies()).toString(),
     });
 }
 function resolvePresetFetchPath(area, storagePath) {
@@ -103,7 +112,11 @@ function resolvePresetFetchPath(area, storagePath) {
  * The presets belong in the catalog for the same reason the folder is in the tree: they are what put
  * it there. A preset Page cannot shadow anything by being here, because a binding is preferred above.
  */
-const resolvePhiBuilderPageStoragePath = cache(async function resolvePhiBuilderPageStoragePath({ apiBaseUrl, internalToken, siteKey, locale, cookieHeader, area, pageKey, runtimeModuleCatalog, }) {
+/*
+ * Positional and primitive, so React's `cache` sees the same question twice: it compares arguments by
+ * identity, and an options object built at each call site made every call a miss.
+ */
+const resolvePhiBuilderPageStoragePath = cache(async function resolvePhiBuilderPageStoragePath(apiBaseUrl, internalToken, siteKey, locale, cookieHeader, area, pageKey, runtimeModuleCatalog) {
     const persistedPages = await getSiteCmsPageCatalog({
         apiBaseUrl,
         internalToken,
@@ -115,32 +128,18 @@ const resolvePhiBuilderPageStoragePath = cache(async function resolvePhiBuilderP
     const catalog = resolvePhiBuilderActivePageCatalog(area, buildPhiBuilderModulePresetPagesByArea(runtimeModuleCatalog), null, { [area]: persistedPages });
     return resolvePhiBuilderCmsStoragePathForCatalog(area, pageKey, catalog);
 });
-const buildPageDraftsForScope = cache(async function buildPageDraftsForScope(runtime, siteKey, locale, apiBaseUrl, internalToken, area, pageKey, runtimeModuleCatalog) {
-    const presetResolution = await resolvePhiRegistryPresetPageBinding({
-        runtime,
-        runtimeModuleCatalog,
-        area,
-        pageKey,
-    });
-    const presetBinding = presetResolution?.binding ?? null;
+/**
+ * What the Site stores about one Page: the open draft, else what is published (read only where there is
+ * no draft), else nothing. One read per request for the drafts and the meta, which used to fetch it
+ * twice -- and, through `cache` keyed on fresh objects, could have read two revisions of it.
+ *
+ * The preset identity travels as two strings for the same reason the rest is positional: `cache`
+ * compares by identity, and an object would never match.
+ */
+const loadPhiBuilderPageSource = cache(async function loadPhiBuilderPageSource(apiBaseUrl, internalToken, siteKey, locale, area, pageKey, storagePath, fetchPath, sourcePresetOwnerModuleId, sourcePresetKey) {
     const cookieHeader = (await cookies()).toString();
-    const storagePath = presetBinding?.descriptor.path ??
-        await resolvePhiBuilderPageStoragePath({
-            apiBaseUrl,
-            internalToken,
-            siteKey,
-            locale,
-            cookieHeader,
-            area,
-            pageKey,
-            runtimeModuleCatalog,
-        });
-    const fetchPath = resolvePresetFetchPath(area, storagePath);
-    const sourcePreset = presetBinding
-        ? {
-            ownerModuleId: presetBinding.descriptor.ownerModuleId,
-            presetKey: presetBinding.descriptor.presetKey,
-        }
+    const sourcePreset = sourcePresetOwnerModuleId && sourcePresetKey
+        ? { ownerModuleId: sourcePresetOwnerModuleId, presetKey: sourcePresetKey }
         : null;
     const draftPage = await getCurrentCmsPageDraft({
         apiBaseUrl,
@@ -155,10 +154,7 @@ const buildPageDraftsForScope = cache(async function buildPageDraftsForScope(run
         throw new Error(`Failed to resolve builder draft page for area "${area}" page "${pageKey}" at "${storagePath}".`, { cause: error });
     });
     if (draftPage?.page) {
-        const drafts = await buildPhiProjectedBuilderRegionDrafts(runtime, draftPage.page, area, pageKey, PHI_BUILDER_PAGE_REGION_KEYS);
-        return {
-            [pageKey]: drafts,
-        };
+        return { draftPage, resolvedPage: null };
     }
     const resolvedPage = await getResolvedCmsPage({
         apiBaseUrl,
@@ -168,9 +164,32 @@ const buildPageDraftsForScope = cache(async function buildPageDraftsForScope(run
         locale,
         cookieHeader,
         sourcePreset,
+        // What is published, as the base of the next draft: with the current content in each bound field.
+        stage: "current",
     }).catch((error) => {
         throw new Error(`Failed to resolve builder page for area "${area}" page "${pageKey}" at "${fetchPath}".`, { cause: error });
     });
+    return { draftPage, resolvedPage };
+});
+const buildPageDraftsForScope = cache(async function buildPageDraftsForScope(runtime, siteKey, locale, apiBaseUrl, internalToken, area, pageKey, runtimeModuleCatalog) {
+    const presetResolution = await resolvePhiRegistryPresetPageBinding({
+        runtime,
+        runtimeModuleCatalog,
+        area,
+        pageKey,
+    });
+    const presetBinding = presetResolution?.binding ?? null;
+    const cookieHeader = (await cookies()).toString();
+    const storagePath = presetBinding?.descriptor.path ??
+        await resolvePhiBuilderPageStoragePath(apiBaseUrl, internalToken, siteKey, locale, cookieHeader, area, pageKey, runtimeModuleCatalog);
+    const fetchPath = resolvePresetFetchPath(area, storagePath);
+    const { draftPage, resolvedPage } = await loadPhiBuilderPageSource(apiBaseUrl, internalToken, siteKey, locale, area, pageKey, storagePath, fetchPath, presetBinding?.descriptor.ownerModuleId ?? null, presetBinding?.descriptor.presetKey ?? null);
+    if (draftPage?.page) {
+        const drafts = await buildPhiProjectedBuilderRegionDrafts(runtime, draftPage.page, area, pageKey, PHI_BUILDER_PAGE_REGION_KEYS);
+        return {
+            [pageKey]: drafts,
+        };
+    }
     if (resolvedPage?.page) {
         const drafts = await buildPhiProjectedBuilderRegionDrafts(runtime, resolvedPage.page, area, pageKey, PHI_BUILDER_PAGE_REGION_KEYS);
         return {
@@ -251,43 +270,16 @@ async function buildPageMetaForScope(runtime, area, pageKey, runtimeModuleCatalo
     const presetBinding = presetResolution?.binding ?? null;
     const cookieHeader = (await cookies()).toString();
     const storagePath = presetBinding?.descriptor.path ??
-        await resolvePhiBuilderPageStoragePath({
-            apiBaseUrl: readPhiServerApiCredentials().apiBaseUrl,
-            internalToken: readPhiServerApiCredentials().internalToken,
-            siteKey: runtime.site.key,
-            locale: runtime.locale.current,
-            cookieHeader,
-            area,
-            pageKey,
-            runtimeModuleCatalog,
-        });
+        await resolvePhiBuilderPageStoragePath(readPhiServerApiCredentials().apiBaseUrl, readPhiServerApiCredentials().internalToken, runtime.site.key, runtime.locale.current, cookieHeader, area, pageKey, runtimeModuleCatalog);
     const fetchPath = resolvePresetFetchPath(area, storagePath);
-    const sourcePreset = presetBinding
-        ? {
-            ownerModuleId: presetBinding.descriptor.ownerModuleId,
-            presetKey: presetBinding.descriptor.presetKey,
-        }
-        : null;
-    const draftPage = await getCurrentCmsPageDraft({
-        apiBaseUrl: readPhiServerApiCredentials().apiBaseUrl,
-        internalToken: readPhiServerApiCredentials().internalToken,
-        siteKey: runtime.site.key,
-        area,
-        path: storagePath,
-        locale: runtime.locale.current,
-        cookieHeader,
-        sourcePreset,
-    }).catch((error) => {
-        throw new Error(`Failed to resolve builder page draft meta for "${area}" at "${storagePath}".`, {
-            cause: error,
-        });
-    });
+    const { draftPage, resolvedPage } = await loadPhiBuilderPageSource(readPhiServerApiCredentials().apiBaseUrl, readPhiServerApiCredentials().internalToken, runtime.site.key, runtime.locale.current, area, pageKey, storagePath, fetchPath, presetBinding?.descriptor.ownerModuleId ?? null, presetBinding?.descriptor.presetKey ?? null);
     if (draftPage?.page?.pageMeta) {
         return {
             title: draftPage.page.pageMeta.title?.value ?? null,
             description: draftPage.page.pageMeta.description?.value ?? null,
             isDeleted: draftPage.page.page.status === PhiCmsStatus.Deleted,
             index: readPageIndexFlag(draftPage.page.page.flags),
+            controllerSettings: draftPage.page.controllerSettings ?? [],
         };
     }
     if (draftPage?.page) {
@@ -296,27 +288,16 @@ async function buildPageMetaForScope(runtime, area, pageKey, runtimeModuleCatalo
             description: null,
             isDeleted: draftPage.page.page.status === PhiCmsStatus.Deleted,
             index: readPageIndexFlag(draftPage.page.page.flags),
+            controllerSettings: draftPage.page.controllerSettings ?? [],
         };
     }
-    const resolvedPage = await getResolvedCmsPage({
-        apiBaseUrl: readPhiServerApiCredentials().apiBaseUrl,
-        internalToken: readPhiServerApiCredentials().internalToken,
-        siteKey: runtime.site.key,
-        path: fetchPath,
-        locale: runtime.locale.current,
-        cookieHeader,
-        sourcePreset,
-    }).catch((error) => {
-        throw new Error(`Failed to resolve builder page meta for "${area}" at "${fetchPath}".`, {
-            cause: error,
-        });
-    });
     if (resolvedPage?.page?.pageMeta) {
         return {
             title: resolvedPage.page.pageMeta.title?.value ?? null,
             description: resolvedPage.page.pageMeta.description?.value ?? null,
             isDeleted: resolvedPage.page.page.status === PhiCmsStatus.Deleted,
             index: readPageIndexFlag(resolvedPage.page.page.flags),
+            controllerSettings: resolvedPage.page.controllerSettings ?? [],
         };
     }
     const presetTree = presetResolution
@@ -336,13 +317,19 @@ async function buildPageMetaForScope(runtime, area, pageKey, runtimeModuleCatalo
     const presetIndex = presetTree
         ? readPageIndexFlag(presetTree.page.flags)
         : readPageIndexFlag(0);
+    /*
+     * A stored Page without titles answers for its Controllers all the same: the chain above returns at
+     * the first source that holds titles, and a resolved Page without them still holds the tree.
+     */
+    const controllerSettings = resolvedPage?.page?.controllerSettings ?? presetTree?.controllerSettings ?? [];
     if (!presetTree?.pageMeta) {
-        return { title: null, description: null, index: presetIndex };
+        return { title: null, description: null, index: presetIndex, controllerSettings };
     }
     return {
         title: presetTree.pageMeta.title?.value ?? null,
         description: presetTree.pageMeta.description?.value ?? null,
         index: presetIndex,
+        controllerSettings,
     };
 }
 function readPageIndexFlag(flags) {

package/plugins/runtime-modules/builder/page-references-provider.js

@@ -3,7 +3,7 @@ import { jsx as _jsx } from "react/jsx-runtime";
 import { useMemo } from "react";
 import { PhiAuthoringPageReferencesProvider } from "../../../components/widgets/client/shared/phi-page-reference-picker";
 import { usePhiBuilderOfferedPageCatalog } from "./use-offered-page-catalog";
-import { buildPhiBuilderPageReferenceTree } from "./page-reference-tree";
+import { buildPhiBuilderPageReferenceTree } from "../../../helpers/page-reference-tree";
 import { usePhiDeveloperBuilderStateValue } from "./developer-workspace-store";
 /** Offers the edited Area's Pages to the authoring tools' page picker. */
 export function PhiBuilderPageReferencesProvider({ children }) {

package/plugins/runtime-modules/builder/page-tree-walk.d.ts

@@ -0,0 +1,3 @@
+import type { PhiPresetPageNode } from "../../../helpers/cms-page-catalog";
+/** Every Page of a Page tree, parents before their children, as one list. */
+export declare function flattenPhiPresetPages(pages: readonly PhiPresetPageNode[]): PhiPresetPageNode[];

package/plugins/runtime-modules/builder/page-tree-walk.js

@@ -0,0 +1,4 @@
+/** Every Page of a Page tree, parents before their children, as one list. */
+export function flattenPhiPresetPages(pages) {
+    return pages.flatMap((page) => [page, ...flattenPhiPresetPages(page.children ?? [])]);
+}