@phis/ui 0.2.0 → 0.3.0

package/plugins/runtime-modules/builder/root-node-normalization.js

@@ -1,83 +1,86 @@
-import { mergePhiCmsConfigValues, normalizePhiPaddingWidgetConfig } from "../../../types/cms-config";
-import { resolvePhiRenderableBlockAnchor, } from "../../../components/controls/phi-anchor-control-contract";
-import { readPhiShadow } from "../../../types/layout-style";
-import { isPhiRecord } from "../../../helpers/is-record";
-/**
- * What a region draft says about its root node, as a root node draft reads it: every field but the ones
- * that name the node (`id`, `typeKey`, `kind`, `packageName`), which each caller answers for itself.
- */
-export function readPhiBuilderRootNodeDraftFields(draft) {
+import { PHI_VIEWER_ACCESS_ANYONE } from "../../../types/access";
+import { normalizePhiPaddingWidgetConfig } from "../../../types/cms-config";
+import { normalizePhiGeometryWidgetConfig, } from "../../../components/widgets/config/geometry";
+import { isPhiAnchorWidgetPlacement, } from "../../../components/controls/phi-anchor-control-contract";
+import { resolvePhiAnchorPlacement } from "../../../components/layouts/phi-layout-contract";
+import { readPhiSurface } from "../../../types/surface";
+/** The scaffold's input for one Layout node: the node itself, nothing derived. */
+export function readPhiBuilderRootNodeDraft(node) {
+    const segments = node.widgetType.split("/").filter(Boolean);
     return {
-        title: draft.rootNodeTitle ?? null,
-        rootNodeConfig: draft.rootNodeConfig ?? null,
-        rootNodeGeometry: draft.rootNodeGeometry ?? null,
-        rootNodeAnchor: draft.rootNodeAnchor ?? null,
-        rootNodePadding: draft.rootNodePadding ?? null,
-        rootNodeBackground: draft.rootNodeBackground ?? null,
-        rootNodeBorder: draft.rootNodeBorder ?? null,
-        rootNodeShadow: draft.rootNodeShadow ?? null,
-        childLayouts: draft.rootNodeChildLayouts ?? [],
-        childWidgets: draft.rootNodeChildWidgets ?? [],
-    };
-}
-export function resolvePhiBuilderRootNodeDefaults(resolvedConfig) {
-    return resolvePhiBuilderRootNodeDefaultsFromConfig(resolvedConfig ?? {});
-}
-export function resolvePhiBuilderRootNodeDefaultsFromConfig(resolvedConfig) {
-    const backgroundConfig = isPhiRecord(resolvedConfig.background) && !Array.isArray(resolvedConfig.background)
-        ? resolvedConfig.background
-        : isPhiRecord(resolvedConfig.rootNodeBackground) && !Array.isArray(resolvedConfig.rootNodeBackground)
-            ? resolvedConfig.rootNodeBackground
-            : null;
-    const borderConfig = isPhiRecord(resolvedConfig.border) && !Array.isArray(resolvedConfig.border)
-        ? resolvedConfig.border
-        : isPhiRecord(resolvedConfig.rootNodeBorder) && !Array.isArray(resolvedConfig.rootNodeBorder)
-            ? resolvedConfig.rootNodeBorder
-            : null;
-    return {
-        rootNodePadding: normalizePhiPaddingWidgetConfig(resolvedConfig),
-        rootNodeBackground: backgroundConfig,
-        rootNodeBorder: borderConfig,
+        id: node.id,
+        typeKey: node.widgetType,
+        kind: "layout",
+        title: node.label ?? null,
+        packageName: segments.length < 2 ? null : segments.slice(0, -1).join("/"),
+        rootNodeConfig: node.config ?? null,
+        childLayouts: node.childLayouts ?? [],
+        childWidgets: node.childWidgets ?? [],
     };
 }
 export function normalizePhiBuilderRootNodeDraft(rootNode) {
-    const defaults = resolvePhiBuilderRootNodeDefaults(rootNode.rootNodeConfig ?? null);
+    const config = rootNode.rootNodeConfig ?? {};
+    const anchor = config.anchor;
     return {
         ...rootNode,
-        rootNodeGeometry: rootNode.rootNodeGeometry ?? null,
-        rootNodeAnchor: rootNode.rootNodeAnchor ?? null,
-        rootNodePadding: mergePhiCmsConfigValues(defaults.rootNodePadding, rootNode.rootNodePadding),
-        rootNodeBackground: rootNode.rootNodeBackground ?? defaults.rootNodeBackground,
-        rootNodeBorder: rootNode.rootNodeBorder ?? defaults.rootNodeBorder,
-        rootNodeShadow: readPhiShadow(rootNode.rootNodeShadow) ?? null,
+        rootNodeConfig: config,
+        rootNodeGeometry: normalizePhiGeometryWidgetConfig(config),
+        rootNodeAnchor: (isPhiAnchorWidgetPlacement(anchor)
+            ? anchor
+            : resolvePhiAnchorPlacement(anchor)) ?? null,
+        rootNodePadding: normalizePhiPaddingWidgetConfig(config),
+        rootNodeSurface: readPhiSurface(config.surface),
         childLayouts: rootNode.childLayouts ?? [],
         childWidgets: rootNode.childWidgets ?? [],
     };
 }
+/** The node's config as its Layout plugin parses it: the stored config, in the render mode asked for. */
 export function buildPhiBuilderRootNodeRenderConfig(rootNode, renderMode) {
-    const normalizedRootNode = normalizePhiBuilderRootNodeDraft(rootNode);
-    const parsedRootNodeConfig = { ...(normalizedRootNode.rootNodeConfig ?? {}) };
-    delete parsedRootNodeConfig.renderMode;
-    delete parsedRootNodeConfig.shadow;
-    const geometry = normalizedRootNode.rootNodeGeometry;
-    const padding = normalizedRootNode.rootNodePadding;
-    const anchor = resolvePhiRenderableBlockAnchor(normalizedRootNode.rootNodeAnchor);
+    const config = { ...(rootNode.rootNodeConfig ?? {}) };
+    delete config.renderMode;
+    return { ...config, renderMode };
+}
+/**
+ * The root Layout as a render node: the Canvas, its update pass and the renderable tree each built this
+ * from the normalized draft, and only the config they put on it differed.
+ */
+export function buildPhiBuilderRootLayoutRenderNode(rootNode, config) {
+    return {
+        id: rootNode.id,
+        siteId: -1,
+        parentLayoutNodeId: null,
+        widgetType: rootNode.typeKey,
+        slotIndex: 0,
+        sortOrder: 0,
+        status: 0,
+        flags: 0,
+        visibilityMask: 0,
+        label: rootNode.title ?? "Root",
+        config,
+        childLayouts: rootNode.childLayouts ?? [],
+        childWidgets: rootNode.childWidgets ?? [],
+    };
+}
+/** The Page a Builder preview stands in: no Site, no path, every Region root unset but the content's. */
+export function buildPhiBuilderPreviewPageNode(contentRootLayoutNodeId) {
     return {
-        ...parsedRootNodeConfig,
-        renderMode,
-        ...(anchor == null ? {} : { anchor }),
-        ...(normalizedRootNode.rootNodeBackground == null ? {} : { rootNodeBackground: normalizedRootNode.rootNodeBackground }),
-        ...(normalizedRootNode.rootNodeBorder == null ? {} : { rootNodeBorder: normalizedRootNode.rootNodeBorder }),
-        ...(normalizedRootNode.rootNodeShadow == null ? {} : { rootNodeShadow: normalizedRootNode.rootNodeShadow }),
-        ...(geometry?.zIndex == null ? {} : { zIndex: geometry.zIndex }),
-        ...(geometry?.size == null ? {} : { size: geometry.size }),
-        ...(geometry?.minSize == null ? {} : { minSize: geometry.minSize }),
-        ...(geometry?.maxSize == null ? {} : { maxSize: geometry.maxSize }),
-        ...(padding?.padding == null ? {} : { padding: padding.padding }),
-        ...(padding?.gap == null ? {} : { gap: padding.gap }),
-        ...(padding?.paddingTop == null ? {} : { paddingTop: padding.paddingTop }),
-        ...(padding?.paddingRight == null ? {} : { paddingRight: padding.paddingRight }),
-        ...(padding?.paddingBottom == null ? {} : { paddingBottom: padding.paddingBottom }),
-        ...(padding?.paddingLeft == null ? {} : { paddingLeft: padding.paddingLeft }),
+        id: -1,
+        siteId: -1,
+        areaMask: 0,
+        path: "",
+        pageType: 0,
+        status: 0,
+        flags: 0,
+        visibilityMask: 0,
+        accessPolicy: PHI_VIEWER_ACCESS_ANYONE,
+        titleMsgId: null,
+        descriptionMsgId: null,
+        heroRootLayoutNodeId: null,
+        headerBottomRootLayoutNodeId: null,
+        siderRightRootLayoutNodeId: null,
+        footerTopRootLayoutNodeId: null,
+        drawerRightRootLayoutNodeId: null,
+        contentRootLayoutNodeId,
+        layoutConfig: {},
     };
 }

package/plugins/runtime-modules/builder/root-node-renderable-tree.d.ts

@@ -1,10 +1,8 @@
 import type { PhiResolvedCmsPageTree } from "../../../types/cms";
-import type { PhiCmsBackgroundWidgetConfig } from "../../../components/widgets/config/background";
 import { type PhiBuilderRootNodeDraft } from "./root-node-normalization";
-export declare function buildPhiBuilderRootNodeRenderableTree({ rootNode, regionType, renderMode, regionConfig, regionBackgroundConfig, }: {
+export declare function buildPhiBuilderRootNodeRenderableTree({ rootNode, regionType, renderMode, regionConfig, }: {
     rootNode: PhiBuilderRootNodeDraft;
     regionType: number;
     renderMode: "editor" | "preview";
     regionConfig?: Record<string, unknown> | null;
-    regionBackgroundConfig?: PhiCmsBackgroundWidgetConfig | null;
 }): PhiResolvedCmsPageTree | null;

package/plugins/runtime-modules/builder/root-node-renderable-tree.js

@@ -1,8 +1,7 @@
-import { PhiCmsRegionType } from "../../../constants/phi-cms";
-import { isPhiLayoutEffectId, readPhiShadow } from "../../../types/layout-style";
-import { PHI_VIEWER_ACCESS_ANYONE } from "../../../types/access";
+import { PhiCmsFlags, PhiCmsRegionType } from "../../../constants/phi-cms";
+import { readPhiSurface } from "../../../types/surface";
 import { normalizePhiPaddingWidgetConfig } from "../../../types/cms-config";
-import { buildPhiBuilderRootNodeRenderConfig, normalizePhiBuilderRootNodeDraft, } from "./root-node-normalization";
+import { buildPhiBuilderPreviewPageNode, buildPhiBuilderRootLayoutRenderNode, buildPhiBuilderRootNodeRenderConfig, normalizePhiBuilderRootNodeDraft, } from "./root-node-normalization";
 function collectLayoutNodes(node, nodes, parentLayoutNodeId) {
     nodes.push({
         id: node.id,
@@ -35,9 +34,7 @@ function collectWidgetNodes(node, widgets, renderMode) {
     }
 }
 function resolveRegionConfig(regionType, regionConfig) {
-    const background = typeof regionConfig?.background === "string" ? regionConfig.background : undefined;
-    const effect = isPhiLayoutEffectId(regionConfig?.effect) ? regionConfig.effect : undefined;
-    const shadow = readPhiShadow(regionConfig?.shadow) ?? "none";
+    const surface = readPhiSurface(regionConfig?.surface);
     const padding = normalizePhiPaddingWidgetConfig(regionConfig);
     const paddingConfig = padding == null
         ? {}
@@ -48,29 +45,24 @@ function resolveRegionConfig(regionType, regionConfig) {
             ...(padding.paddingBottom == null ? {} : { paddingBottom: padding.paddingBottom }),
             ...(padding.paddingLeft == null ? {} : { paddingLeft: padding.paddingLeft }),
         };
+    const surfaceConfig = surface == null ? {} : { surface };
     if (regionType === PhiCmsRegionType.SiderLeft || regionType === PhiCmsRegionType.SiderRight) {
         return {
-            fullHeight: true,
+            flags: PhiCmsFlags.FullHeight,
             size: {
                 width: "100%",
                 height: "100%",
             },
-            ...(background == null ? {} : { background }),
-            ...(effect == null ? {} : { effect }),
+            ...surfaceConfig,
             ...paddingConfig,
-            border: false,
-            shadow,
         };
     }
     return {
-        ...(background == null ? {} : { background }),
-        ...(effect == null ? {} : { effect }),
+        ...surfaceConfig,
         ...paddingConfig,
-        border: false,
-        shadow,
     };
 }
-export function buildPhiBuilderRootNodeRenderableTree({ rootNode, regionType, renderMode, regionConfig, regionBackgroundConfig, }) {
+export function buildPhiBuilderRootNodeRenderableTree({ rootNode, regionType, renderMode, regionConfig, }) {
     if (rootNode.kind === null || rootNode.kind === "widget") {
         return null;
     }
@@ -78,46 +70,13 @@ export function buildPhiBuilderRootNodeRenderableTree({ rootNode, regionType, re
     if (normalizedRootNode.id == null) {
         return null;
     }
-    const rootLayout = {
-        id: normalizedRootNode.id,
-        siteId: -1,
-        parentLayoutNodeId: null,
-        widgetType: normalizedRootNode.typeKey,
-        slotIndex: 0,
-        sortOrder: 0,
-        status: 0,
-        flags: 0,
-        visibilityMask: 0,
-        label: normalizedRootNode.title ?? "Root",
-        config: buildPhiBuilderRootNodeRenderConfig(normalizedRootNode, renderMode),
-        childLayouts: normalizedRootNode.childLayouts ?? [],
-        childWidgets: normalizedRootNode.childWidgets ?? [],
-    };
+    const rootLayout = buildPhiBuilderRootLayoutRenderNode({ ...normalizedRootNode, id: normalizedRootNode.id }, buildPhiBuilderRootNodeRenderConfig(normalizedRootNode, renderMode));
     const layoutNodes = [];
     const contentWidgets = [];
     collectLayoutNodes(rootLayout, layoutNodes, null);
     collectWidgetNodes(rootLayout, contentWidgets, renderMode);
     return {
-        page: {
-            id: -1,
-            siteId: -1,
-            areaMask: 0,
-            path: "",
-            pageType: 0,
-            status: 0,
-            flags: 0,
-            visibilityMask: 0,
-            accessPolicy: PHI_VIEWER_ACCESS_ANYONE,
-            titleMsgId: null,
-            descriptionMsgId: null,
-            heroRootLayoutNodeId: null,
-            headerBottomRootLayoutNodeId: null,
-            siderRightRootLayoutNodeId: null,
-            footerTopRootLayoutNodeId: null,
-            drawerRightRootLayoutNodeId: null,
-            contentRootLayoutNodeId: rootLayout.id,
-            layoutConfig: {},
-        },
+        page: buildPhiBuilderPreviewPageNode(rootLayout.id),
         regions: [
             {
                 id: -1,
@@ -130,7 +89,6 @@ export function buildPhiBuilderRootNodeRenderableTree({ rootNode, regionType, re
                 sortOrder: 0,
                 config: {
                     ...resolveRegionConfig(regionType, regionConfig),
-                    ...(regionBackgroundConfig == null ? {} : { backgroundConfig: regionBackgroundConfig }),
                 },
             },
         ],

package/plugins/runtime-modules/builder/runtime-module-selection.d.ts

@@ -1,20 +1,11 @@
-import type { PhiRuntimeModuleDefinition, PhiRuntimeModuleId } from "../../../types";
+import type { PhiRuntimeModuleId } from "../../../types";
 import type { PhiDeveloperBuilderArea } from "./developer-workspace-types";
 export declare function areRuntimeModuleIdsEqual(left: readonly PhiRuntimeModuleId[] | null | undefined, right: readonly PhiRuntimeModuleId[] | null | undefined): boolean;
-/**
- * Turns an arbitrary set of ids a viewer picked into the Area's persistable selection.
- *
- * Every id has to name an installed Module, and a Base Module id from a different Area is refused
- * outright -- selecting one would silently activate a foreign Area's own required Module. The Platform
- * Module and this Area's own Base Module are never taken from the input at all: they are implicit, and
- * `resolvePhiRuntimeModuleIdsForArea` adds them back regardless of what was asked for.
- */
-export declare function normalizeRuntimeModuleSelection(selectedIds: readonly string[], area: PhiDeveloperBuilderArea, definitions: readonly PhiRuntimeModuleDefinition[]): PhiRuntimeModuleId[];
 /**
  * Applies a new Module selection to one or more Areas: validates each Area's list, patches the
  * catalog, and records the whole gesture as ONE history entry -- the one place all of this happens,
- * so a Switch cell in the Modules table and the legacy `runtimeModules` signal channel stay in
- * perfect step rather than each growing its own copy of "what does changing this actually mean."
+ * so a Switch cell in the Modules table and the Controller's `moduleUsage` answers stay in perfect
+ * step rather than each growing its own copy of "what does changing this actually mean."
  *
  * One entry per gesture is the point of taking a list: the module-wide switch changes several Areas
  * at once, and recording those as separate entries would make undo restore exactly the partial state

package/plugins/runtime-modules/builder/runtime-module-selection.js

@@ -18,7 +18,7 @@ export function areRuntimeModuleIdsEqual(left, right) {
  * Module and this Area's own Base Module are never taken from the input at all: they are implicit, and
  * `resolvePhiRuntimeModuleIdsForArea` adds them back regardless of what was asked for.
  */
-export function normalizeRuntimeModuleSelection(selectedIds, area, definitions) {
+function normalizeRuntimeModuleSelection(selectedIds, area, definitions) {
     const definitionsById = new Map(definitions.map((definition) => [definition.moduleId, definition]));
     const selectedIdSet = new Set(selectedIds);
     const invalidIds = selectedIds.filter((moduleId) => !definitionsById.has(moduleId));
@@ -47,11 +47,32 @@ export function normalizeRuntimeModuleSelection(selectedIds, area, definitions)
     assertPhiRuntimeModuleIdsAllowedForArea(area, moduleIds, definitions);
     return moduleIds;
 }
+/**
+ * The Modules a selection change switched, by title, for the history step that records it. A Module
+ * switched on in one Area and off in another is named once; the step's sentence says that the
+ * selection of these changed, not which way.
+ */
+function describeModuleSelectionChange(effective, before, defaultArea) {
+    const definitions = getPhiDeveloperBuilderStateSnapshot(defaultArea).runtimeModuleDefinitions;
+    const titleById = new Map(definitions.map((definition) => [definition.moduleId, definition.title]));
+    const changed = new Set();
+    for (const { area, moduleIds } of effective) {
+        const previous = new Set(before.moduleIdsByArea[area] ?? []);
+        const next = new Set(moduleIds);
+        for (const moduleId of next)
+            if (!previous.has(moduleId))
+                changed.add(moduleId);
+        for (const moduleId of previous)
+            if (!next.has(moduleId))
+                changed.add(moduleId);
+    }
+    return [...changed].map((moduleId) => titleById.get(moduleId) ?? moduleId).join(", ");
+}
 /**
  * Applies a new Module selection to one or more Areas: validates each Area's list, patches the
  * catalog, and records the whole gesture as ONE history entry -- the one place all of this happens,
- * so a Switch cell in the Modules table and the legacy `runtimeModules` signal channel stay in
- * perfect step rather than each growing its own copy of "what does changing this actually mean."
+ * so a Switch cell in the Modules table and the Controller's `moduleUsage` answers stay in perfect
+ * step rather than each growing its own copy of "what does changing this actually mean."
  *
  * One entry per gesture is the point of taking a list: the module-wide switch changes several Areas
  * at once, and recording those as separate entries would make undo restore exactly the partial state
@@ -82,7 +103,7 @@ export function applyPhiBuilderRuntimeModuleSelectionChanges(changes, defaultAre
     }));
     markPhiBuilderModuleAreasDirty(changedAreas, defaultArea);
     phiBuilderHistory.record(createPhiBuilderHistoryContext({ workspace: "modules", area: defaultArea }), {
-        label: "Change runtime modules",
+        action: { key: "changeModules", subject: describeModuleSelectionChange(effective, historyBefore, defaultArea) },
         before: historyBefore,
         after: capturePhiBuilderModulesHistoryState(getPhiDeveloperBuilderStateSnapshot(defaultArea), changedAreas),
     });

package/plugins/runtime-modules/builder/selected-collection-source.d.ts

@@ -1,14 +1,6 @@
 import type { PhiCollectionProviderResourceDescriptor } from "../../../types/collection-provider";
 import type { PhiRuntimeModuleDataProviderDescriptor } from "../contracts";
 import type { PhiDeveloperBuilderWorkspaceState } from "./developer-workspace-types";
-/**
- * The Widget the Inspector is editing, as it stands in the draft.
- *
- * From the draft and not from what was published, because everything asked of it here -- which Provider
- * it is bound to, and therefore what it may emit and what may draw it -- changes while the author is
- * still editing, and a question answered from the published copy would answer for the wrong Widget.
- */
-export declare function findPhiBuilderSelectedWidgetNode(state: PhiDeveloperBuilderWorkspaceState): import("../../../types").PhiCmsContentWidgetNode | null;
 /**
  * The Collection resource a Widget's config is bound to, as its owning Module described it.
  *

package/plugins/runtime-modules/builder/selected-collection-source.js

@@ -1,5 +1,6 @@
 "use client";
-import { findPhiBuilderWidgetNodeByIdInLayouts, findPhiBuilderWidgetNodeByIdInWidgets, } from "./node-finders";
+import { isPhiRecord } from "../../../helpers/is-record";
+import { findPhiBuilderWidgetNodeByIdInLayouts, } from "./node-finders";
 import { resolveRegionDraftKey } from "./developer-region-drafts";
 import { getPhiDeveloperRegionDraftsSnapshot } from "./developer-workspace-store";
 /**
@@ -9,7 +10,7 @@ import { getPhiDeveloperRegionDraftsSnapshot } from "./developer-workspace-store
  * it is bound to, and therefore what it may emit and what may draw it -- changes while the author is
  * still editing, and a question answered from the published copy would answer for the wrong Widget.
  */
-export function findPhiBuilderSelectedWidgetNode(state) {
+function findPhiBuilderSelectedWidgetNode(state) {
     if (state.nodeKind !== "widget" || state.nodeId == null || !state.selectedRootRegionKey) {
         return null;
     }
@@ -17,9 +18,7 @@ export function findPhiBuilderSelectedWidgetNode(state) {
     if (!draft) {
         return null;
     }
-    return findPhiBuilderWidgetNodeByIdInWidgets(draft.rootNodeChildWidgets ?? [], state.nodeId) ??
-        findPhiBuilderWidgetNodeByIdInLayouts(draft.rootNodeChildLayouts ?? [], state.nodeId) ??
-        null;
+    return findPhiBuilderWidgetNodeByIdInLayouts(draft.rootNode ? [draft.rootNode] : [], state.nodeId) ?? null;
 }
 /**
  * The Collection resource a Widget's config is bound to, as its owning Module described it.
@@ -31,7 +30,7 @@ export function findPhiBuilderSelectedWidgetNode(state) {
  */
 export function readPhiBuilderBoundCollectionResource(config, dataProviders) {
     const source = config?.source;
-    if (!source || typeof source !== "object" || Array.isArray(source)) {
+    if (!isPhiRecord(source)) {
         return null;
     }
     const { providerKey, resourceKey } = source;

package/plugins/runtime-modules/builder/sequential-slot-helpers.d.ts

@@ -1,7 +1,4 @@
 import type { PhiCmsContentWidgetNode, PhiCmsLayoutRenderNode } from "../../../types/cms";
-export declare function isPhiCmsSequentialLayoutSlots(slots: readonly {
-    sequential?: boolean;
-}[] | null | undefined): boolean;
 /** Whether moving or removing a child renumbers the rest, which is what `slotPositions` decides. */
 export declare function compactsPhiCmsSequentialSlots(meta: {
     slots?: readonly {

package/plugins/runtime-modules/builder/sequential-slot-helpers.js

@@ -1,5 +1,5 @@
 import { comparePhiCmsInstanceIds } from "../../../types/cms-instance-id";
-export function isPhiCmsSequentialLayoutSlots(slots) {
+function isPhiCmsSequentialLayoutSlots(slots) {
     return Array.isArray(slots) && slots.length > 0 && slots.every((slot) => slot.sequential === true);
 }
 /** Whether moving or removing a child renumbers the rest, which is what `slotPositions` decides. */

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

@@ -24,6 +24,11 @@ export const PHI_BUILDER_RUNTIME_MODULE_SERVER_AREA_CONTRIBUTION = definePhiRunt
         areaShells: PHI_BUILDER_RUNTIME_MODULE_AREA_SHELLS,
         areaOverlays: PHI_BUILDER_RUNTIME_MODULE_AREA_OVERLAYS,
         routes: PHI_BUILDER_RUNTIME_MODULE_ROUTES,
+        dashboardCards: {
+            areas: ["builder"],
+            load: () => import("./cards")
+                .then((module) => module.PHI_BUILDER_RUNTIME_MODULE_DASHBOARD_CARDS),
+        },
         load: () => import("./module").then((module) => module.PHI_BUILDER_RUNTIME_MODULE),
     },
 });

package/plugins/runtime-modules/builder/services/navigation-table.js

@@ -1,5 +1,6 @@
 "use client";
 import { jsx as _jsx } from "react/jsx-runtime";
+import { flattenPhiPresetPages } from "../page-tree-walk";
 import { useMemo, useRef } from "react";
 import { useSearchParams } from "next/navigation";
 import { PHI_BUILDER_RUNTIME_DATA_PROVIDER_KEYS } from "../ids";
@@ -33,9 +34,6 @@ const PHI_NAVIGATION_NOT_FOUND_LABEL = "404";
 function resolveNavigationTableType(item) {
     return item.kind === "link" && item.external === true ? "external" : item.kind;
 }
-function flattenPages(pages) {
-    return pages.flatMap((page) => [page, ...flattenPages(page.children ?? [])]);
-}
 function flattenNavigationRows(items, moduleTitles, paths, parentId = null, hiddenByAncestor = false) {
     const pagePaths = paths.pagePaths;
     return items.flatMap((item) => {
@@ -124,16 +122,21 @@ function extractNavigationItem(items, id) {
 }
 function insertNavigationItem(items, parentId, beforeId, afterId, item) {
     if (parentId) {
+        // A parent that is gone would leave the tree as it was, and a moved item -- already taken out -- lost.
+        if (!findNavigationItem(items, parentId)) {
+            throw new Error(`Navigation parent "${parentId}" does not exist.`);
+        }
         return updateNavigationItem(items, parentId, (parent) => {
             if (parent.kind !== "container")
                 throw new Error("Navigation target cannot contain children.");
             return { ...parent, children: insertNavigationItem(parent.children, null, beforeId, afterId, item) };
         });
     }
+    // The Table rule (`movePhiTableBindingRows`): before the one it lands before, else just after the other.
     const next = [...items];
-    const anchorId = beforeId ?? afterId;
-    const anchorIndex = anchorId ? next.findIndex((candidate) => candidate.id === anchorId) : -1;
-    const index = anchorIndex < 0 ? next.length : anchorIndex + (afterId ? 1 : 0);
+    const beforeIndex = beforeId ? next.findIndex((candidate) => candidate.id === beforeId) : -1;
+    const afterIndex = afterId ? next.findIndex((candidate) => candidate.id === afterId) : -1;
+    const index = beforeIndex >= 0 ? beforeIndex : afterIndex >= 0 ? afterIndex + 1 : next.length;
     next.splice(index, 0, item);
     return next;
 }
@@ -172,7 +175,7 @@ function createPageNavigationItem(id, area, navigationArea, reference, pages) {
     const parsed = readPhiInternalReference(reference);
     const pageReference = parsed?.kind === "page" ? parsed.reference : null;
     const page = pageReference
-        ? flattenPages(pages).find((candidate) => candidate.reference === pageReference)
+        ? flattenPhiPresetPages(pages).find((candidate) => candidate.reference === pageReference)
         : null;
     return page ? {
         id, source: "custom", ownerModuleId: null, kind: "link", label: page.title,
@@ -187,8 +190,18 @@ function createPageNavigationItem(id, area, navigationArea, reference, pages) {
 export function PhiBuilderNavigationTableProviderClient({ children }) {
     const searchParams = useSearchParams();
     const navigationSearchValue = searchParams.get(PHI_BUILDER_NAVIGATION_KEY_SEARCH_PARAM);
-    const builderState = usePhiDeveloperBuilderStateValue("public", (state) => state);
-    const activeNavigationKey = resolvePhiBuilderNavigationWidgetNavKey(undefined, navigationSearchValue, builderState.area);
+    /*
+     * Only what the rows are built from is subscribed to. A new registration re-queries every table bound
+     * to this provider, and subscribed to the whole state it was renewed by every selection, every open
+     * Inspector and every slider step -- each one a reload of the navigation. The functions below read the
+     * state snapshot when they run; these subscriptions only say when a change is worth a new registration.
+     */
+    const area = usePhiDeveloperBuilderStateValue("public", (state) => state.area);
+    const customPages = usePhiDeveloperBuilderStateValue("public", (state) => state.customPages);
+    const modulePresetPagesByArea = usePhiDeveloperBuilderStateValue("public", (state) => state.modulePresetPagesByArea);
+    const persistedPageCatalogByArea = usePhiDeveloperBuilderStateValue("public", (state) => state.persistedPageCatalogByArea);
+    const navigationSurfacesByArea = usePhiDeveloperBuilderStateValue("public", (state) => state.navigationSurfacesByArea);
+    const activeNavigationKey = resolvePhiBuilderNavigationWidgetNavKey(undefined, navigationSearchValue, area);
     const activeNavigationDraft = usePhiBuilderNavigationDraft(activeNavigationKey);
     const loaded = useRef(new Map());
     const loading = useRef(new Map());
@@ -246,8 +259,10 @@ export function PhiBuilderNavigationTableProviderClient({ children }) {
             const navigation = { ...scope.navigation, key: requirePhiBuilderNavigationScopeKey(scope.navKey), items: refreshed };
             loaded.current.delete(scope.navKey);
             setPhiBuilderNavigationDraft(scope.navKey, navigation, {
-                historyContext: createPhiBuilderHistoryContext({ workspace: "navigation", area: scope.state.area, navKey: scope.navKey }),
-                historyLabel: "Update navigation",
+                history: {
+                    context: createPhiBuilderHistoryContext({ workspace: "navigation", area: scope.state.area, navKey: scope.navKey }),
+                    action: { key: "changeNavigation", subject: navigation.label?.trim() || navigation.key },
+                },
             });
             return navigation;
         };
@@ -515,13 +530,16 @@ export function PhiBuilderNavigationTableProviderClient({ children }) {
                 bindingFields: "bindingFields" in resource ? resource.bindingFields?.map((field) => field.key === "navKey"
                     ? {
                         ...field,
-                        defaultValue: resolvePhiBuilderNavigationWidgetNavKey(undefined, navigationSearchValue, builderState.area),
+                        defaultValue: resolvePhiBuilderNavigationWidgetNavKey(undefined, navigationSearchValue, area),
                     }
                     : field) : undefined,
             })) : [],
             query,
             mutate,
         };
-    }, [activeNavigationDraft, activeNavigationKey, builderState, navigationSearchValue]);
+        // The catalog slices are the identity of the rows; the functions read the snapshot, so the rule
+        // cannot see that they matter.
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [activeNavigationDraft, activeNavigationKey, area, customPages, modulePresetPagesByArea, navigationSearchValue, navigationSurfacesByArea, persistedPageCatalogByArea]);
     return _jsx(PhiTableProviderClient, { registration: registration, children: children });
 }

package/plugins/runtime-modules/builder/services/page-source-tree.js

@@ -9,7 +9,7 @@ import { resolvePhiBuilderCmsFetchPath } from "../../../../helpers/cms-paths";
 import { resolvePhiBuilderOfferedPageCatalog } from "../offered-page-catalog";
 import { buildPhiBuilderNavigationFolderDragSourceKey, buildPhiBuilderNavigationPageDragSourceKey, } from "../navigation-widget-runtime";
 import { hasPhiBuilderNavigableContent, isPhiBuilderNavigablePage } from "../navigation-folder-drop";
-import { usePhiDeveloperBuilderStateValue } from "../developer-workspace-store";
+import { getPhiDeveloperBuilderStateSnapshot, usePhiDeveloperBuilderStateValue } from "../developer-workspace-store";
 /*
  * Folders are nodes of their own. A folder has no route, but neither does a Navigation container, which
  * is what dropping one builds -- and leaving folders out hung every Page beneath one at the root.
@@ -43,7 +43,17 @@ function isBuilderArea(value) {
     return typeof value === "string" && PHI_BUILDER_AREA_KEYS.includes(value);
 }
 export function PhiBuilderPageSourceTreeProviderClient({ children }) {
-    const state = usePhiDeveloperBuilderStateValue("public", (value) => value);
+    /*
+     * The slices the offered catalog is built from; the query reads the state when it runs. Subscribed
+     * to the whole state, every selection renewed the registration and reloaded the tree.
+     */
+    const area = usePhiDeveloperBuilderStateValue("public", (state) => state.area);
+    const customPages = usePhiDeveloperBuilderStateValue("public", (state) => state.customPages);
+    const modulePresetPagesByArea = usePhiDeveloperBuilderStateValue("public", (state) => state.modulePresetPagesByArea);
+    const navigationSurfacesByArea = usePhiDeveloperBuilderStateValue("public", (state) => state.navigationSurfacesByArea);
+    const persistedPageCatalogByArea = usePhiDeveloperBuilderStateValue("public", (state) => state.persistedPageCatalogByArea);
+    const runtimeModuleIdsByArea = usePhiDeveloperBuilderStateValue("public", (state) => state.runtimeModuleIdsByArea);
+    const areaRootRoutes = usePhiDeveloperBuilderStateValue("public", (state) => state.areaRootRoutes);
     const registration = useMemo(() => {
         const descriptor = PHI_BUILDER_RUNTIME_DATA_PROVIDER_DESCRIPTORS.find((candidate) => candidate.key === PHI_BUILDER_RUNTIME_DATA_PROVIDER_KEYS.pageSourceTree);
         return {
@@ -51,19 +61,20 @@ export function PhiBuilderPageSourceTreeProviderClient({ children }) {
             resources: descriptor?.kind === "tree" ? descriptor.resources.map((resource) => ({
                 ...resource,
                 bindingFields: resource.bindingFields?.map((field) => field.key === "area"
-                    ? { ...field, defaultValue: state.area }
+                    ? { ...field, defaultValue: area }
                     : field),
             })) : [],
             query: async (request) => {
-                const area = isBuilderArea(request.params?.area) ? request.params.area : state.area;
+                const state = getPhiDeveloperBuilderStateSnapshot("public");
+                const requestedArea = isBuilderArea(request.params?.area) ? request.params.area : state.area;
                 /*
                  * What the Area answers with, not what is installed in it. The active catalog mirrors the route
                  * declarations, so a base Module Page that a Site package covers is still in it -- and this tree
                  * offered both, two rows reading `/home`, one of them an address nobody is ever served. Dragging
                  * that one into a Navigation authors a link to a Page the Site does not answer with.
                  */
-                const pages = resolvePhiBuilderOfferedPageCatalog(state, area);
-                const nodes = flattenPages(area, pages, pages);
+                const pages = resolvePhiBuilderOfferedPageCatalog(state, requestedArea);
+                const nodes = flattenPages(requestedArea, pages, pages);
                 const search = request.query.search?.trim().toLocaleLowerCase();
                 return {
                     nodes: search
@@ -76,6 +87,8 @@ export function PhiBuilderPageSourceTreeProviderClient({ children }) {
                 };
             },
         };
-    }, [state]);
+        // The catalog's identity; the query reads the snapshot, so the rule cannot see that these matter.
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [area, areaRootRoutes, customPages, modulePresetPagesByArea, navigationSurfacesByArea, persistedPageCatalogByArea, runtimeModuleIdsByArea]);
     return _jsx(PhiTreeProviderClient, { registration: registration, children: children });
 }