@phis/ui 0.1.0 → 0.2.1

package/helpers/cms-navigation-catalog.js

@@ -1,4 +1,4 @@
-import { isPhiCmsAreaKey } from "../constants/cms-areas";
+import { isPhiCmsAreaKey, resolvePhiCmsAreaAsBuilderArea, } from "../constants/cms-areas";
 import { readPhiCmsNavigationTargetPath } from "../helpers/navigation-target";
 import { resolvePhiCmsNavigationOverlay } from "../plugins/runtime-modules/descriptor-compiler";
 import { resolvePhiBuilderNavigationTargetPath } from "./cms-paths";
@@ -40,9 +40,6 @@ export function requirePhiBuilderNavigationScopeKey(value) {
     }
     return formatPhiBuilderNavigationScopeKey(parsed.area, parsed.key);
 }
-export function countPhiBuilderNavigationItems(items) {
-    return items.reduce((total, item) => total + 1 + countPhiBuilderNavigationItems(item.children), 0);
-}
 export function getPhiBuilderNavigationDefaultScopeKey(area, family) {
     const resolvedFamily = family ?? (area === "app" || area === "admin" || area === "builder" || area === "editor" || area === "accounting"
         ? "sidebar"
@@ -64,6 +61,7 @@ function materializeNavigationItem(item, tombstones, customItems, overrides) {
             : readPhiCmsNavigationTargetPath(item.target),
         ...(customTarget?.kind === "page" ? {
             targetReference: customTarget.reference,
+            ...(customTarget.area ? { targetArea: customTarget.area } : {}),
             targetDeleted: customTarget.deleted === true,
         } : {}),
         icon: item.icon ?? null,
@@ -119,28 +117,65 @@ export function resolvePhiBuilderNavigationSurface(surfaces, navKey) {
     }
     return surface;
 }
-export function resolvePhiBuilderNavigationPageTargets(area, items, pages) {
-    const pageByReference = new Map();
-    const collect = (nodes) => {
-        for (const node of nodes) {
-            if (node.reference)
-                pageByReference.set(node.reference, node);
-            if (node.children)
-                collect(node.children);
-        }
+/**
+ * Each link's address, worked out in the Area its target actually lives in.
+ *
+ * An item may name another Area, and then that Area's catalog is the only one holding its Page and the
+ * only one that can prefix its path. Resolving everything against the edited Area is what made a
+ * cross-Area link read as unresolvable the moment it was dropped: the reference was right, the catalog
+ * looked in was the wrong one, and a Page that is simply absent looks exactly like a Page that is gone.
+ *
+ * `pagesForArea` rather than one list, because the caller is the only one that can reach another Area's
+ * catalog -- and nearly every call asks for the same Area twice, so the cost is a cached lookup.
+ */
+/**
+ * A Page catalog lookup by CMS Area, for a caller that has one keyed by Builder Area.
+ *
+ * The two lists carry the same names and are still two questions -- the Areas a Site has, and the Areas
+ * the Builder can open -- so the translation is stated rather than assumed. An Area the Builder does not
+ * open has no catalog to show, and an empty list is the honest answer: a link into it resolves to
+ * nothing, which is what the reader sees.
+ */
+export function createPhiBuilderNavigationPageLookup(pageCatalogForArea) {
+    return (area) => {
+        const builderArea = resolvePhiCmsAreaAsBuilderArea(area);
+        return builderArea ? pageCatalogForArea(builderArea) : [];
+    };
+}
+export function resolvePhiBuilderNavigationPageTargets(area, items, pagesForArea) {
+    const readPages = typeof pagesForArea === "function"
+        ? pagesForArea
+        : () => pagesForArea;
+    const byArea = new Map();
+    const pageIndex = (targetArea) => {
+        const cached = byArea.get(targetArea);
+        if (cached)
+            return cached;
+        const index = new Map();
+        const collect = (nodes) => {
+            for (const node of nodes) {
+                if (node.reference)
+                    index.set(node.reference, node);
+                if (node.children)
+                    collect(node.children);
+            }
+        };
+        collect(readPages(targetArea));
+        byArea.set(targetArea, index);
+        return index;
     };
-    collect(pages);
     return items.map((item) => {
-        const page = item.targetReference ? pageByReference.get(item.targetReference) : null;
+        const targetArea = item.targetArea ?? area;
+        const page = item.targetReference ? pageIndex(targetArea).get(item.targetReference) : null;
         return {
             ...item,
             ...(item.targetReference ? {
                 href: page && page.tombstoned !== true
-                    ? resolvePhiBuilderNavigationTargetPath(area, page.key, pages)
+                    ? resolvePhiBuilderNavigationTargetPath(targetArea, page.key, readPages(targetArea))
                     : null,
                 targetDeleted: page == null || page.tombstoned === true,
             } : {}),
-            children: resolvePhiBuilderNavigationPageTargets(area, item.children, pages),
+            children: resolvePhiBuilderNavigationPageTargets(area, item.children, pagesForArea),
         };
     });
 }

package/helpers/cms-node-factories.d.ts

@@ -1,5 +1,6 @@
 import type { PhiCmsLayoutNode, PhiCmsContentWidgetNode } from "../types/cms";
 import type { PhiCmsInstanceId } from "../types/cms-instance-id";
+import type { PhiCoreWidgetPlacements, PhiCoreWidgetTypeKey } from "../types/core-widget-placements";
 import { type PhiLayoutCreationPreset } from "./cms-layout-defaults";
 import type { PhiLayoutKind } from "../components/layouts/phi-layout-contract";
 type PhiCmsLayoutNodeFactoryCommon = {
@@ -13,8 +14,26 @@ type PhiCmsLayoutNodeFactoryCommon = {
     visibilityMask: number;
     label: string | null;
 };
-type PhiCmsWidgetNodeFactoryCommon = Omit<PhiCmsLayoutNodeFactoryCommon, "parentLayoutNodeId"> & {
+export type PhiCmsWidgetNodeFactoryCommon = Omit<PhiCmsLayoutNodeFactoryCommon, "parentLayoutNodeId"> & {
     parentLayoutNodeId: PhiCmsInstanceId;
+    contentId?: number | null;
+};
+/**
+ * The config a Widget placement takes, read off its type key.
+ *
+ * A Core Widget listed in `PhiCoreWidgetPlacements` takes the placement Core promises to read, so a
+ * misspelt field or a value outside its vocabulary fails where the placement is written rather than
+ * being dropped by the parser at render. Everything else -- a Widget of another Module, named with its
+ * `pluginKey`, or a type key only known at runtime -- takes a plain record, because nothing here knows
+ * what it reads.
+ */
+export type PhiCmsWidgetPlacementConfig<TTypeKey extends string, TPluginKey extends string | undefined> = [TPluginKey] extends [undefined] ? TTypeKey extends PhiCoreWidgetTypeKey ? PhiCoreWidgetPlacements[TTypeKey] : Record<string, unknown> : Record<string, unknown>;
+/** What a Widget placement names: which Widget, and configured how. */
+export type PhiCmsWidgetPlacementFields<TTypeKey extends string, TPluginKey extends string | undefined = undefined> = {
+    /** Optional override; by default the owning module is resolved from the type key. */
+    pluginKey?: TPluginKey;
+    typeKey: TTypeKey;
+    config?: PhiCmsWidgetPlacementConfig<TTypeKey, TPluginKey>;
 };
 export declare function buildPhiCmsWidgetTypeKey(pluginKey: string, typeKey: string): string;
 export declare function buildPhiCmsLayoutNode({ pluginKey, typeKey, creationPreset, config, ...common }: PhiCmsLayoutNodeFactoryCommon & {
@@ -27,11 +46,5 @@ export declare function buildPhiCmsLayoutNode({ pluginKey, typeKey, creationPres
     };
     config?: Record<string, unknown>;
 }): PhiCmsLayoutNode;
-export declare function buildPhiCmsWidgetNode({ pluginKey, typeKey, config, contentId, ...common }: PhiCmsWidgetNodeFactoryCommon & {
-    /** Optional override; by default the owning module is resolved from the type key. */
-    pluginKey?: string;
-    typeKey: string;
-    config?: Record<string, unknown>;
-    contentId?: number | null;
-}): PhiCmsContentWidgetNode;
+export declare function buildPhiCmsWidgetNode<TTypeKey extends string, TPluginKey extends string | undefined = undefined>({ pluginKey, typeKey, config, contentId, ...common }: PhiCmsWidgetNodeFactoryCommon & PhiCmsWidgetPlacementFields<TTypeKey, TPluginKey>): PhiCmsContentWidgetNode;
 export {};

package/helpers/cms-node-factories.js

@@ -1,4 +1,5 @@
-import { buildPhiCmsLayoutNamespacedTypeKey, resolvePhiCmsLayoutPluginKey } from "../constants/cms-layout-types";
+import { buildPhiCmsLayoutNamespacedTypeKey } from "../constants/cms-layout-types";
+import { resolvePhiCmsLayoutPluginKey } from "../constants/cms-layout-type-keys";
 import { buildPhiCmsWidgetNamespacedTypeKey, resolvePhiCmsWidgetPluginKey } from "../constants/cms-widget-types";
 import { resolvePhiLayoutCreationPreset, } from "./cms-layout-defaults";
 export function buildPhiCmsWidgetTypeKey(pluginKey, typeKey) {
@@ -24,6 +25,11 @@ export function buildPhiCmsLayoutNode({ pluginKey, typeKey, creationPreset, conf
         },
     };
 }
+/*
+ * Generic over the type key rather than overloaded per Widget: an overload set picks the first
+ * signature a literal fits, and a config with a wrong field fits the untyped one, so the check would
+ * pass exactly when it should fail.
+ */
 export function buildPhiCmsWidgetNode({ pluginKey, typeKey, config, contentId = null, ...common }) {
     return {
         id: common.id,
@@ -36,7 +42,7 @@ export function buildPhiCmsWidgetNode({ pluginKey, typeKey, config, contentId =
         flags: common.flags ?? 0,
         visibilityMask: common.visibilityMask,
         label: common.label,
-        config: config ?? {},
+        config: (config ?? {}),
         contentId,
     };
 }

package/helpers/cms-page-catalog.d.ts

@@ -1,5 +1,4 @@
 import { type PhiBuilderAreaKey } from "../constants/cms-areas";
-import type { PhiTreeOption } from "../types/tree";
 import type { PhiCmsPresetSource } from "../types/cms-module-descriptors";
 import { type PhiPageReference } from "../types/references";
 export type PhiPresetPageNode = {
@@ -35,11 +34,9 @@ export type PhiPresetPageNode = {
 };
 export type PhiBuilderModulePresetPagesByArea = Record<PhiBuilderPageCatalogArea, PhiPresetPageNode[]>;
 export declare function createEmptyPhiBuilderModulePresetPagesByArea(): PhiBuilderModulePresetPagesByArea;
-export declare function mapPhiPresetPageNodesToTreeOptions(nodes: readonly PhiPresetPageNode[]): PhiTreeOption[];
 export type PhiBuilderPageCatalogArea = PhiBuilderAreaKey;
 export declare function mergePhiBuilderPageCatalogNodes(presetPages: PhiPresetPageNode[], customPages: PhiPresetPageNode[] | null | undefined): PhiPresetPageNode[];
 export declare function resolvePagePath(area: PhiBuilderPageCatalogArea, pageKey: string, pages: readonly PhiPresetPageNode[]): string;
-export declare function resolvePageNodePath(pageKey: string, pages: readonly PhiPresetPageNode[]): PhiPresetPageNode[] | null;
 export declare function resolvePhiBuilderActivePageKey(requestedPageKey: string | null | undefined, pages: readonly PhiPresetPageNode[]): string | null;
 export declare function resolvePhiBuilderPagePresetSource(pageKey: string, pages: readonly PhiPresetPageNode[]): PhiCmsPresetSource | null;
 export declare function resolvePhiBuilderPageDefaultFlags(pageKey: string, pages: readonly PhiPresetPageNode[]): number;

package/helpers/cms-page-catalog.js

@@ -3,13 +3,6 @@ import { createPhiPageReference, readPhiPageReference, } from "../types/referenc
 export function createEmptyPhiBuilderModulePresetPagesByArea() {
     return PHI_BUILDER_AREA_KEYS.reduce((current, area) => ({ ...current, [area]: [] }), {});
 }
-export function mapPhiPresetPageNodesToTreeOptions(nodes) {
-    return nodes.map((node) => ({
-        value: node.key,
-        label: node.title,
-        children: node.children ? mapPhiPresetPageNodesToTreeOptions(node.children) : undefined,
-    }));
-}
 function findPagePathSegments(pages, targetKey, prefix = []) {
     for (const page of pages) {
         const currentPath = [...prefix, page.key];
@@ -61,9 +54,6 @@ export function resolvePagePath(area, pageKey, pages) {
     const pathSegments = findPagePathSegments([...pages], pageKey) ?? [pageKey];
     return `/${area}/${pathSegments.join("/")}`;
 }
-export function resolvePageNodePath(pageKey, pages) {
-    return findPageNodePath([...pages], pageKey);
-}
 /** The first node in the tree that is a Page rather than a folder holding Pages. */
 function findFirstPhiBuilderPageNodeKey(pages) {
     for (const node of pages) {

package/helpers/cms-paths.d.ts

@@ -1,5 +1,5 @@
-import type { PhiDeveloperBuilderArea } from "../plugins/runtime-modules/builder/developer-workspace-types";
+import type { PhiBuilderAreaKey } from "../constants/cms-areas";
 import { type PhiPresetPageNode } from "./cms-page-catalog";
-export declare function resolvePhiBuilderCmsStoragePath(area: PhiDeveloperBuilderArea, pageKey: string, pages: readonly PhiPresetPageNode[]): string;
-export declare function resolvePhiBuilderCmsFetchPath(area: PhiDeveloperBuilderArea, pageKey: string, pages: readonly PhiPresetPageNode[]): string;
-export declare function resolvePhiBuilderNavigationTargetPath(area: PhiDeveloperBuilderArea, pageKey: string, pages: readonly PhiPresetPageNode[]): string;
+export declare function resolvePhiBuilderCmsStoragePath(area: PhiBuilderAreaKey, pageKey: string, pages: readonly PhiPresetPageNode[]): string;
+export declare function resolvePhiBuilderCmsFetchPath(area: PhiBuilderAreaKey, pageKey: string, pages: readonly PhiPresetPageNode[]): string;
+export declare function resolvePhiBuilderNavigationTargetPath(area: PhiBuilderAreaKey, pageKey: string, pages: readonly PhiPresetPageNode[]): string;

package/helpers/cms-paths.js

@@ -2,23 +2,14 @@ import { resolvePhiBuilderCmsStoragePathForCatalog, } from "./cms-page-catalog";
 export function resolvePhiBuilderCmsStoragePath(area, pageKey, pages) {
     return resolvePhiBuilderCmsStoragePathForCatalog(area, pageKey, pages);
 }
+/** A storage path under its Area's segment: `/` is the Area itself. */
+function prefixPhiBuilderAreaPath(area, storagePath) {
+    return storagePath === "/" ? `/${area}` : `/${area}${storagePath}`;
+}
 export function resolvePhiBuilderCmsFetchPath(area, pageKey, pages) {
     const storagePath = resolvePhiBuilderCmsStoragePath(area, pageKey, pages);
-    if (area === "public") {
-        return storagePath;
-    }
-    if (storagePath === "/") {
-        return `/${area}`;
-    }
-    return `/${area}${storagePath}`;
+    return area === "public" ? storagePath : prefixPhiBuilderAreaPath(area, storagePath);
 }
 export function resolvePhiBuilderNavigationTargetPath(area, pageKey, pages) {
-    const storagePath = resolvePhiBuilderCmsStoragePath(area, pageKey, pages);
-    if (area === "public") {
-        return storagePath === "/" ? "/public" : `/public${storagePath}`;
-    }
-    if (storagePath === "/") {
-        return `/${area}`;
-    }
-    return `/${area}${storagePath}`;
+    return prefixPhiBuilderAreaPath(area, resolvePhiBuilderCmsStoragePath(area, pageKey, pages));
 }

package/helpers/cms-preset-nodes.d.ts

@@ -1,6 +1,7 @@
-import { buildPhiCmsLayoutNode, buildPhiCmsWidgetNode } from "./cms-node-factories";
-import type { PhiCmsContentWidgetNode, PhiCmsLayoutNode } from "../types/cms";
+import { buildPhiCmsLayoutNode, type PhiCmsWidgetNodeFactoryCommon, type PhiCmsWidgetPlacementFields } from "./cms-node-factories";
+import type { PhiCmsContentWidgetNode, PhiCmsLayoutNode, PhiCmsOverlayNode, PhiCmsPageNode, PhiCmsRegionNode } from "../types/cms";
 import type { PhiCmsInstanceId } from "../types/cms-instance-id";
+import type { PhiCmsOverlayType, PhiOverlayFooterPresentation } from "../types/cms-overlay";
 type PhiCmsPresetNodeDefaults = {
     siteId: number;
     visibilityMask: number;
@@ -8,13 +9,58 @@ type PhiCmsPresetNodeDefaults = {
     flags?: number;
 };
 type PhiCmsPresetLayoutInput = Parameters<typeof buildPhiCmsLayoutNode>[0];
-type PhiCmsPresetWidgetInput = Parameters<typeof buildPhiCmsWidgetNode>[0];
 type PhiCmsPresetNodeInput<TInput> = Omit<TInput, "siteId" | "visibilityMask" | "status" | "flags" | "sortOrder"> & Partial<Pick<TInput & {
     sortOrder?: number;
 }, "sortOrder">> & {
     status?: number;
     flags?: number;
 };
+/** A Widget placement in a Preset: typed by its type key, like `buildPhiCmsWidgetNode`. */
+type PhiCmsPresetWidgetInput<TTypeKey extends string, TPluginKey extends string | undefined = undefined> = PhiCmsPresetNodeInput<PhiCmsWidgetNodeFactoryCommon> & PhiCmsWidgetPlacementFields<TTypeKey, TPluginKey>;
+/**
+ * An entry of a stack. It names no `pluginKey`: the type keys of a stack are read as one tuple, and a
+ * second tuple beside it stops the compiler from reading either -- every config would pass unchecked.
+ * A Widget of another Module is placed with `widget`.
+ */
+type PhiCmsPresetStackEntry<TTypeKey extends string> = Omit<PhiCmsPresetNodeInput<PhiCmsWidgetNodeFactoryCommon>, "parentLayoutNodeId" | "slotIndex"> & PhiCmsWidgetPlacementFields<TTypeKey>;
+/**
+ * What a Region placement decides: which Region, rooted where, in which order, configured how.
+ *
+ * `status`, `flags` and `visibilityMask` are there for the Preset that copies them from a Region it was
+ * handed rather than taking the frame's.
+ */
+export type PhiCmsPresetRegionInput = {
+    id: number;
+    regionType: number;
+    rootLayoutNodeId: PhiCmsInstanceId;
+    sortOrder: number;
+    config?: Record<string, unknown>;
+    status?: number;
+    flags?: number;
+    visibilityMask?: number;
+};
+/**
+ * What an Overlay decides. A header or footer it does not name is none: the footer's presentation and
+ * the Layout it presents are named together or not at all, because one without the other is not a
+ * footer. They keep the node's own field names, which the overlay contract scripts read in source.
+ */
+export type PhiCmsPresetOverlayInput = {
+    id: PhiCmsInstanceId;
+    overlayType: PhiCmsOverlayType;
+    headerLayoutNodeId?: PhiCmsInstanceId | null;
+    bodyLayoutNodeId: PhiCmsInstanceId;
+    sortOrder: number;
+    label: string | null;
+    config: Record<string, unknown>;
+} & ({
+    footerPresentation?: Extract<PhiOverlayFooterPresentation, "none">;
+    footerLayoutNodeId?: null;
+} | {
+    footerPresentation: Exclude<PhiOverlayFooterPresentation, "none">;
+    footerLayoutNodeId: PhiCmsInstanceId;
+});
+/** The two things a Preset changes about the Page row it was built for; everything else is kept. */
+export type PhiCmsPresetPageInput = Partial<Pick<PhiCmsPageNode, "pageType" | "layoutConfig">>;
 /**
  * The parts of a node that a Preset repeats rather than decides.
  *
@@ -26,16 +72,43 @@ type PhiCmsPresetNodeInput<TInput> = Omit<TInput, "siteId" | "visibilityMask" |
  *
  * `sortOrder` follows `slotIndex` unless it is given. Presets set them to the same number almost
  * everywhere, and where they differ it is deliberate and worth writing down.
+ *
+ * Given the Page itself rather than only its defaults, the factory also builds the rest of the frame:
+ * the Page the tree returns and its Regions. Overlays need no Page and are there either way. The frame
+ * does not take the Page row's `status` and `flags` the way Layouts and Widgets do: a Preset returns
+ * its Page published whatever row it was handed, and a Region or Overlay that followed a draft row
+ * would be the one part of a published tree that is not.
  */
-export declare function createPhiCmsPresetNodes(defaults: PhiCmsPresetNodeDefaults): {
+export declare function createPhiCmsPresetNodes(page: PhiCmsPageNode): PhiCmsPresetPageNodes;
+export declare function createPhiCmsPresetNodes(defaults: PhiCmsPresetNodeDefaults): PhiCmsPresetNodes;
+export type PhiCmsPresetNodes = ReturnType<typeof createPhiCmsPresetNodeSet>;
+export type PhiCmsPresetPageNodes = ReturnType<typeof createPhiCmsPresetPageNodeSet>;
+declare function createPhiCmsPresetNodeSet(defaults: PhiCmsPresetNodeDefaults): {
+    layout(input: PhiCmsPresetNodeInput<PhiCmsPresetLayoutInput>): PhiCmsLayoutNode;
+    widget<TTypeKey extends string, TPluginKey extends string | undefined = undefined>(input: PhiCmsPresetWidgetInput<TTypeKey, TPluginKey>): PhiCmsContentWidgetNode;
+    /**
+     * Widgets stacked in one Layout, in the order they are written.
+     *
+     * Slots are counted for them, because a stack is a sequence and renumbering one by hand after
+     * inserting something in the middle is exactly the kind of edit that goes wrong quietly.
+     */
+    stack<const TTypeKeys extends readonly string[]>(parentLayoutNodeId: PhiCmsInstanceId, entries: { [TIndex in keyof TTypeKeys]: PhiCmsPresetStackEntry<TTypeKeys[TIndex]>; }, startAt?: number): PhiCmsContentWidgetNode[];
+    overlay(input: PhiCmsPresetOverlayInput): PhiCmsOverlayNode;
+};
+declare function createPhiCmsPresetPageNodeSet(page: PhiCmsPageNode, nodes: PhiCmsPresetNodes): {
+    /** The Page the tree returns: the row it was built for, published, with what the Preset decides. */
+    page(input?: PhiCmsPresetPageInput): PhiCmsPageNode;
+    /** A Region of this Page. Preset Regions belong to no Area Preset row, so `areaPresetId` is null. */
+    region(input: PhiCmsPresetRegionInput): PhiCmsRegionNode;
     layout(input: PhiCmsPresetNodeInput<PhiCmsPresetLayoutInput>): PhiCmsLayoutNode;
-    widget(input: PhiCmsPresetNodeInput<PhiCmsPresetWidgetInput>): PhiCmsContentWidgetNode;
+    widget<TTypeKey extends string, TPluginKey extends string | undefined = undefined>(input: PhiCmsPresetWidgetInput<TTypeKey, TPluginKey>): PhiCmsContentWidgetNode;
     /**
      * Widgets stacked in one Layout, in the order they are written.
      *
      * Slots are counted for them, because a stack is a sequence and renumbering one by hand after
      * inserting something in the middle is exactly the kind of edit that goes wrong quietly.
      */
-    stack(parentLayoutNodeId: PhiCmsInstanceId, entries: readonly Omit<PhiCmsPresetNodeInput<PhiCmsPresetWidgetInput>, "parentLayoutNodeId" | "slotIndex">[], startAt?: number): PhiCmsContentWidgetNode[];
+    stack<const TTypeKeys extends readonly string[]>(parentLayoutNodeId: PhiCmsInstanceId, entries: { [TIndex in keyof TTypeKeys]: PhiCmsPresetStackEntry<TTypeKeys[TIndex]>; }, startAt?: number): PhiCmsContentWidgetNode[];
+    overlay(input: PhiCmsPresetOverlayInput): PhiCmsOverlayNode;
 };
 export {};

package/helpers/cms-preset-nodes.js

@@ -1,18 +1,10 @@
-import { buildPhiCmsLayoutNode, buildPhiCmsWidgetNode } from "./cms-node-factories";
+import { buildPhiCmsLayoutNode, buildPhiCmsWidgetNode, } from "./cms-node-factories";
 import { PhiCmsStatus } from "../constants/phi-cms";
-/**
- * The parts of a node that a Preset repeats rather than decides.
- *
- * A placement is four things -- what it is, where it sits, what it is called, how it is configured --
- * and it was written as eleven, because `siteId`, `visibilityMask`, `status`, `flags`, `contentId` and
- * `sortOrder` are the same for every node of a page and were spelled out on each of them. That is not
- * detail a reader of a Preset needs; it is noise they have to look past to find the four that matter,
- * and it is six chances to write the wrong page's `visibilityMask` on one node out of twenty.
- *
- * `sortOrder` follows `slotIndex` unless it is given. Presets set them to the same number almost
- * everywhere, and where they differ it is deliberate and worth writing down.
- */
 export function createPhiCmsPresetNodes(defaults) {
+    const nodes = createPhiCmsPresetNodeSet(defaults);
+    return "pageType" in defaults ? createPhiCmsPresetPageNodeSet(defaults, nodes) : nodes;
+}
+function createPhiCmsPresetNodeSet(defaults) {
     const common = {
         siteId: defaults.siteId,
         visibilityMask: defaults.visibilityMask,
@@ -42,7 +34,8 @@ export function createPhiCmsPresetNodes(defaults) {
          * inserting something in the middle is exactly the kind of edit that goes wrong quietly.
          */
         stack(parentLayoutNodeId, entries, startAt = 0) {
-            return entries.map((entry, index) => buildPhiCmsWidgetNode({
+            const stacked = entries;
+            return stacked.map((entry, index) => buildPhiCmsWidgetNode({
                 ...common,
                 contentId: null,
                 parentLayoutNodeId,
@@ -51,5 +44,55 @@ export function createPhiCmsPresetNodes(defaults) {
                 ...entry,
             }));
         },
+        overlay(input) {
+            const node = {
+                id: input.id,
+                overlayType: input.overlayType,
+                headerLayoutNodeId: input.headerLayoutNodeId ?? null,
+                bodyLayoutNodeId: input.bodyLayoutNodeId,
+                footerPresentation: "none",
+                footerLayoutNodeId: null,
+                status: PhiCmsStatus.Published,
+                flags: 0,
+                visibilityMask: defaults.visibilityMask,
+                sortOrder: input.sortOrder,
+                label: input.label,
+                config: input.config,
+            };
+            return hasPhiCmsPresetOverlayFooter(input)
+                ? {
+                    ...node,
+                    footerPresentation: input.footerPresentation,
+                    footerLayoutNodeId: input.footerLayoutNodeId,
+                }
+                : node;
+        },
+    };
+}
+function hasPhiCmsPresetOverlayFooter(input) {
+    return input.footerPresentation !== undefined && input.footerPresentation !== "none";
+}
+function createPhiCmsPresetPageNodeSet(page, nodes) {
+    return {
+        ...nodes,
+        /** The Page the tree returns: the row it was built for, published, with what the Preset decides. */
+        page(input = {}) {
+            return { ...page, ...input, status: PhiCmsStatus.Published };
+        },
+        /** A Region of this Page. Preset Regions belong to no Area Preset row, so `areaPresetId` is null. */
+        region(input) {
+            return {
+                id: input.id,
+                pageId: page.id,
+                areaPresetId: null,
+                regionType: input.regionType,
+                rootLayoutNodeId: input.rootLayoutNodeId,
+                status: input.status ?? PhiCmsStatus.Published,
+                flags: input.flags ?? 0,
+                visibilityMask: input.visibilityMask ?? page.visibilityMask,
+                sortOrder: input.sortOrder,
+                config: input.config ?? {},
+            };
+        },
     };
 }

package/helpers/cms-region-keys.d.ts

@@ -16,6 +16,23 @@ export declare const PHI_CMS_SHELL_OWNED_REGION_KEYS: readonly ["header_top", "h
 export declare const PHI_CMS_PAGE_OWNED_REGION_KEYS: readonly ["header_bottom", "hero", "content", "sider_right", "footer_top", "drawer_right"];
 export declare function isPhiCmsShellOwnedRegion(regionKey: string): regionKey is (typeof PHI_CMS_SHELL_OWNED_REGION_KEYS)[number];
 export declare function isPhiCmsPageOwnedRegion(regionKey: string): regionKey is (typeof PHI_CMS_PAGE_OWNED_REGION_KEYS)[number];
+/**
+ * Which of the two a Region is, as one value rather than two questions.
+ *
+ * A shell-owned Region belongs to the Area and outlives a move between its Pages; a page-owned one is
+ * built again for the Page being opened. That difference is what a Widget means when it says where it
+ * can stand: navigation that rebuilds itself on every step is navigation that flickers.
+ */
+export type PhiCmsRegionOwnership = "shell" | "page";
+export declare function resolvePhiCmsRegionOwnership(regionKey: string | null | undefined): PhiCmsRegionOwnership | undefined;
+/**
+ * Whether a Widget asking for one kind of Region may stand in this one.
+ *
+ * A Widget that asks for nothing stands anywhere, which is what nearly all of them do. An unknown
+ * Region key answers yes as well: the question is asked while authoring, and a key this build does not
+ * know is not a placement anybody chose -- refusing it would hide Widgets over a typo.
+ */
+export declare function phiCmsRegionAcceptsWidget(regionKey: string | null | undefined, required: PhiCmsRegionOwnership | null | undefined): boolean;
 export declare const PHI_CMS_REGION_KEY_BY_TYPE: Record<number, PhiCmsRegionKey>;
-export declare function resolvePhiCmsRegionType(regionKey: string | null | undefined): 10 | 21 | 12 | 25 | 11 | 20 | 30 | 39 | 40 | 41 | 50;
+export declare function resolvePhiCmsRegionType(regionKey: string | null | undefined): 10 | 40 | 50 | 11 | 12 | 20 | 21 | 25 | 30 | 39 | 41;
 export declare function resolvePhiCmsRegionKey(regionType: number | null | undefined): "content" | "header_top" | "header_main" | "header_bottom" | "sider_left" | "sider_right" | "hero" | "footer_top" | "footer_main" | "footer_bottom" | "drawer_right" | undefined;

package/helpers/cms-region-keys.js

@@ -33,6 +33,29 @@ export function isPhiCmsShellOwnedRegion(regionKey) {
 export function isPhiCmsPageOwnedRegion(regionKey) {
     return PHI_CMS_PAGE_OWNED_REGION_KEYS.includes(regionKey);
 }
+export function resolvePhiCmsRegionOwnership(regionKey) {
+    if (!regionKey) {
+        return undefined;
+    }
+    if (isPhiCmsShellOwnedRegion(regionKey)) {
+        return "shell";
+    }
+    return isPhiCmsPageOwnedRegion(regionKey) ? "page" : undefined;
+}
+/**
+ * Whether a Widget asking for one kind of Region may stand in this one.
+ *
+ * A Widget that asks for nothing stands anywhere, which is what nearly all of them do. An unknown
+ * Region key answers yes as well: the question is asked while authoring, and a key this build does not
+ * know is not a placement anybody chose -- refusing it would hide Widgets over a typo.
+ */
+export function phiCmsRegionAcceptsWidget(regionKey, required) {
+    if (!required) {
+        return true;
+    }
+    const ownership = resolvePhiCmsRegionOwnership(regionKey);
+    return ownership === undefined || ownership === required;
+}
 export const PHI_CMS_REGION_KEY_BY_TYPE = Object.fromEntries(Object.entries(PHI_CMS_REGION_TYPE_BY_KEY).map(([key, type]) => [type, key]));
 export function resolvePhiCmsRegionType(regionKey) {
     return regionKey && regionKey in PHI_CMS_REGION_TYPE_BY_KEY

package/helpers/cms-routing.d.ts

@@ -1,4 +1,21 @@
 export declare const PHI_CMS_SPECIAL_ROOTS: ("app" | "admin" | "builder" | "editor" | "accounting")[];
 export type PhiCmsSpecialRoot = (typeof PHI_CMS_SPECIAL_ROOTS)[number];
 export declare function isKnownSpecialCmsRoot(root: string): boolean;
+export declare function isPhiReservedCmsRoot(root: string): boolean;
 export declare function normalizePhiCmsRouteSegment(segment: string): string;
+/**
+ * The canonical address, unless it is the address that asked -- then there is nothing to say.
+ *
+ * A forward onto the path the request already names does not fail. The client applies it, asks again
+ * and is told the same thing; for a client navigation the forward is streamed rather than answered
+ * with a status, so the exchange repeats at request speed rather than stopping at a browser's redirect
+ * limit. `components/cms/phi-cms-page-redirect.ts` says the same thing about a Redirect Page and keeps
+ * its comparison in one place for the same reason given there: it had already drifted once, held by
+ * the Layout and not by the two Page entry points.
+ *
+ * The same drift is here. The Layout asks for this only at an Area's root (`!path`), the Page asks for
+ * it on every address, and a value that can never name its own caller makes the two agree without
+ * either having to remember. Deciding it here rather than at the four call sites is what makes it a
+ * property of the answer instead of a habit of whoever reads it.
+ */
+export declare function canonicalHrefUnlessCurrent(canonical: string, requested: string): string | null;

package/helpers/cms-routing.js

@@ -4,6 +4,43 @@ const SPECIAL_ROOT_SET = new Set(PHI_CMS_SPECIAL_ROOTS);
 export function isKnownSpecialCmsRoot(root) {
     return SPECIAL_ROOT_SET.has(root.trim().toLowerCase());
 }
+/**
+ * Roots a Site never owns.
+ *
+ * Every first segment that is neither an Area nor a locale is read as an unprefixed Public address and
+ * forwarded to the default locale -- which is what sends `/imprint` to `/en/imprint`. The framework's
+ * own trees sit at first segments too, and a static asset that is merely missing falls out of the file
+ * handler and into that same rule: `/_next/static/chunks/<hash>.js` was answered with a forward to the
+ * Site's home page, so a browser that asked for a script was handed HTML, and every stale chunk after a
+ * deploy paid for a CMS root resolution to say it.
+ *
+ * A reserved root is refused instead. The extension test is the same one `next/site-proxy.ts` uses to
+ * decide what middleware hands straight to Next: a first segment that names a file is a file that is
+ * not there, not a Page that wants a locale.
+ */
+const RESERVED_ROOT_SET = new Set(["_next", "api"]);
+export function isPhiReservedCmsRoot(root) {
+    const normalized = root.trim().toLowerCase();
+    return RESERVED_ROOT_SET.has(normalized) || /\.[\w-]+$/.test(normalized);
+}
 export function normalizePhiCmsRouteSegment(segment) {
     return segment.trim().replace(/%2b/gi, "+");
 }
+/**
+ * The canonical address, unless it is the address that asked -- then there is nothing to say.
+ *
+ * A forward onto the path the request already names does not fail. The client applies it, asks again
+ * and is told the same thing; for a client navigation the forward is streamed rather than answered
+ * with a status, so the exchange repeats at request speed rather than stopping at a browser's redirect
+ * limit. `components/cms/phi-cms-page-redirect.ts` says the same thing about a Redirect Page and keeps
+ * its comparison in one place for the same reason given there: it had already drifted once, held by
+ * the Layout and not by the two Page entry points.
+ *
+ * The same drift is here. The Layout asks for this only at an Area's root (`!path`), the Page asks for
+ * it on every address, and a value that can never name its own caller makes the two agree without
+ * either having to remember. Deciding it here rather than at the four call sites is what makes it a
+ * property of the answer instead of a habit of whoever reads it.
+ */
+export function canonicalHrefUnlessCurrent(canonical, requested) {
+    return canonical === requested ? null : canonical;
+}

package/helpers/csrf-token.d.ts

@@ -0,0 +1,33 @@
+/**
+ * The CSRF token a browser needs before it may change anything, fetched in one place.
+ *
+ * It was fetched in ten, with four spellings between them: two threw a hard-coded English sentence, one
+ * threw a `PhiTableProviderError`, and three gave up silently -- a logout that quietly did nothing, a
+ * theme preference that quietly stayed unsaved. The request is identical in all ten; only what to do
+ * about a failure differs, and that belongs to the caller.
+ *
+ * **It throws rather than returning null.** A null invites the `if` that was forgotten three times: the
+ * token comes back empty, the request goes out without it, the server refuses it, and nothing says so.
+ * A caller that means to stay quiet writes a `catch` and is visibly quiet on purpose.
+ */
+/**
+ * Core's CSRF endpoint for a browser, as `validate-form-gateway-contracts.ts` knows it.
+ *
+ * The `/api/v1/` spelling beside it in that script is the server-to-server one, which a browser never
+ * uses: this path forwards the visitor's session, the versioned one carries an internal token.
+ */
+export declare const PHI_CSRF_TOKEN_PATH = "/api/auth/csrf";
+export type FetchPhiCsrfTokenOptions = {
+    signal?: AbortSignal;
+    /** What the failure says, where a caller has a sentence from its own Label Set. */
+    unavailableMessage?: string;
+};
+export declare function fetchPhiCsrfToken(options?: FetchPhiCsrfTokenOptions): Promise<string>;
+/**
+ * The token this browser already holds, or a fresh one where it holds none.
+ *
+ * For a request that goes out for whoever sends it, such as a Form submit: reading the cookie keeps the
+ * pair Core may have rotated -- sign-in replaces it -- instead of minting another beside it, and a
+ * fetch only happens once per browser. What the server compares is the header against that same cookie.
+ */
+export declare function readPhiCsrfToken(options?: FetchPhiCsrfTokenOptions): Promise<string>;