@phis/ui 0.2.1 → 0.3.0

package/plugins/runtime-modules/builder/{draft-status-controller.js → controller/draft-status-controller.js}

@@ -1,12 +1,11 @@
 "use client";
 import { useCallback, useEffect, useState } from "react";
-import { PHI_SIGNAL_VALUE_SCHEMAS } from "../../../types/signals";
-import { usePhiSignalDispatcher, usePhiSignalListener } from "../../../components/runtime/runtime-signal-bus";
-import { resolvePhiBuilderCmsStoragePath } from "../../../helpers/cms-paths";
-import { resolvePhiBuilderActivePageCatalog } from "../../../helpers/cms-page-catalog";
-import { createPhiBuilderControllerAddress } from "./controller/address";
-import { createPhiBuilderHistoryContext, phiBuilderHistory } from "./history";
-/** A history scope nothing records into, for the screens that report no draft. */
+import { PHI_SIGNAL_VALUE_SCHEMAS } from "../../../../types/signals";
+import { usePhiSignalDispatcher, usePhiSignalListener } from "../../../../components/runtime/runtime-signal-bus";
+import { resolvePhiBuilderCmsStoragePath } from "../../../../helpers/cms-paths";
+import { resolvePhiBuilderActivePageCatalog, resolvePhiBuilderPagePresetSource, } from "../../../../helpers/cms-page-catalog";
+import { createPhiBuilderControllerAddress } from "../controller/address";
+import { createPhiBuilderHistoryContext, phiBuilderHistory } from "../history";
 const PHI_BUILDER_NO_DRAFT_HISTORY_CONTEXT = "draft-status:none";
 function resolveTarget(workspace, area, pageKey, navKey, state) {
     if (workspace === "navigation") {
@@ -22,8 +21,16 @@ function resolveTarget(workspace, area, pageKey, navKey, state) {
         }
         const pages = resolvePhiBuilderActivePageCatalog(area, state.modulePresetPagesByArea, state.customPages, state.persistedPageCatalogByArea);
         const storagePath = resolvePhiBuilderCmsStoragePath(area, pageKey, pages);
+        /*
+         * Addressed the way a save addresses it: a Module Page by its preset identity, which survives a
+         * changed path. Asking by path found nothing after a move and reported the Page as published.
+         */
+        const presetSource = resolvePhiBuilderPagePresetSource(pageKey, pages);
+        const address = presetSource
+            ? { area, ownerModuleId: presetSource.ownerModuleId, presetKey: presetSource.presetKey }
+            : { area, path: storagePath };
         return {
-            url: `/api/site/cms/page/draft?${new URLSearchParams({ area, path: storagePath }).toString()}`,
+            url: `/api/site/cms/page/draft?${new URLSearchParams(address).toString()}`,
             subject: area === "public" ? storagePath : `${area}${storagePath}`,
             historyContext: createPhiBuilderHistoryContext({ workspace, area, pageKey }),
         };
@@ -156,8 +163,17 @@ export function usePhiBuilderDraftStatusController({ commandWorkspace, effective
             emitTo(signal.sender, current, signal.correlationId);
         }
     }, undefined, createPhiBuilderControllerAddress());
-    /** A save or publish of the workspace on screen: the state it stored, and history as it stands. */
-    function reportSaved(status, revisionId) {
+    /**
+     * The head of the workspace's undo history, taken as a save or publish begins -- before the drafts
+     * are read for the payload. A save awaits the server, and an edit made while it waits is in no stored
+     * revision; stamping the head from after the await would have called that edit saved, and a reload
+     * would have dropped it without a word. The token goes back in through `reportSaved`.
+     */
+    const captureHistoryHead = useCallback(() => ({
+        head: historyContext === null ? null : phiBuilderHistory.getHead(historyContext),
+    }), [historyContext]);
+    /** A save or publish of the workspace on screen: the state it stored, and the head it was taken at. */
+    function reportSaved(status, revisionId, savedAt) {
         if (targetUrl === null) {
             return;
         }
@@ -166,8 +182,10 @@ export function usePhiBuilderDraftStatusController({ commandWorkspace, effective
             status,
             revisionId,
             error: null,
-            savedHead: historyContext === null ? null : phiBuilderHistory.getHead(historyContext),
+            savedHead: savedAt.head,
         });
     }
-    return { reportSaved };
+    /** Whether what is on screen is in no stored revision -- what a preview of the saved draft leaves out. */
+    const hasUnsavedChanges = current?.status === "unsaved";
+    return { captureHistoryHead, reportSaved, hasUnsavedChanges };
 }

package/plugins/runtime-modules/builder/controller/inspector-controller.d.ts

@@ -0,0 +1,3 @@
+import type { PhiBuilderInspectorAction } from "../inspector-actions";
+import type { PhiDeveloperBuilderArea } from "../developer-workspace-types";
+export declare function runPhiDeveloperBuilderInspectorAction(defaultArea: PhiDeveloperBuilderArea, action: PhiBuilderInspectorAction): void;

package/plugins/runtime-modules/builder/controller/inspector-controller.js

@@ -0,0 +1,207 @@
+import { isPhiRecord } from "../../../../helpers/is-record";
+import { PhiCmsFlags } from "../../../../constants/phi-cms";
+import { normalizePhiViewportFlags } from "../../../../types/access";
+import { findPhiBuilderTreeNode, writePhiBuilderNode } from "../node-config-write";
+import { getDefaultRegionDraft, resolveRegionDraftKey, } from "../developer-region-drafts";
+import { getPhiBuilderRegionDraftKey, isPhiBuilderPageScopedRegion, } from "../region-keys";
+import { createPhiBuilderRegionHistoryContext } from "../history";
+import { builderWorkspaceStore, getPhiDeveloperRegionDraftsSnapshot, setPhiDeveloperRegionDraft, getPhiDeveloperBuilderStateSnapshot, } from "../developer-workspace-store";
+function resolveWidgetSizeFromGeometry(geometry) {
+    return {
+        size: geometry.size ?? undefined,
+        minSize: geometry.minSize ?? undefined,
+        maxSize: geometry.maxSize ?? undefined,
+        ...(typeof geometry.zIndex === "number"
+            ? { zIndex: geometry.zIndex }
+            : {}),
+        viewportFlags: normalizePhiViewportFlags(geometry.viewportFlags),
+    };
+}
+function resolvePaddingPatch(padding) {
+    return padding == null
+        ? {
+            padding: undefined,
+            gap: undefined,
+            paddingTop: undefined,
+            paddingRight: undefined,
+            paddingBottom: undefined,
+            paddingLeft: undefined,
+        }
+        : {
+            padding: padding.padding,
+            gap: padding.gap,
+            paddingTop: padding.paddingTop,
+            paddingRight: padding.paddingRight,
+            paddingBottom: padding.paddingBottom,
+            paddingLeft: padding.paddingLeft,
+        };
+}
+/**
+ * One authoring gesture, one history entry. The field being edited and the node it belongs to are what
+ * separate a slider still being dragged from a second, considered edit; the store adds the timing.
+ */
+function resolveInspectorCoalesceKey(state, draftKey, field) {
+    return `${draftKey}:${state.nodeId ?? "root"}:${field}`;
+}
+/**
+ * The selected node, written through the one path every in-place node edit takes
+ * (`writePhiBuilderNode`): checked against its fields, its removed subcontrols' routes pruned, and
+ * recorded as one step of the gesture `field` belongs to.
+ */
+function patchSelectedNode(state, expectedKind, field, edit) {
+    if (!state.selectedRootRegionKey || state.nodeId == null) {
+        return false;
+    }
+    const draftKey = getPhiBuilderRegionDraftKey(state.area, state.selectedRootRegionKey, state.pageKey);
+    const selectedRootDraft = resolveRegionDraftKey(getPhiDeveloperRegionDraftsSnapshot(), state.area, state.selectedRootRegionKey, state.pageKey);
+    /*
+     * The selected node, wherever it stands: the Region's root Layout is found and patched the same way
+     * as every node below it, so both behave alike in the Inspector.
+     */
+    const rootNode = selectedRootDraft?.rootNode ?? null;
+    const node = rootNode ? findPhiBuilderTreeNode(rootNode, state.nodeId) : null;
+    if (!selectedRootDraft || !node || ("contentVersionId" in node ? "widget" : "layout") !== expectedKind) {
+        return false;
+    }
+    return writePhiBuilderNode({
+        area: state.area,
+        pageKey: state.pageKey,
+        regionKey: state.selectedRootRegionKey,
+        draftKey,
+        baseDraft: selectedRootDraft,
+        nodeId: state.nodeId,
+        ...edit,
+        coalesceKey: resolveInspectorCoalesceKey(state, draftKey, field),
+    });
+}
+function patchSelectedWidgetDraftConfig(state, field, patchConfig, actionKey) {
+    return patchSelectedNode(state, "widget", field, { patchConfig, actionKey });
+}
+function patchSelectedStructureDraftConfig(state, field, patchConfig) {
+    return patchSelectedNode(state, "layout", field, { patchConfig });
+}
+function readRecordPatch(value) {
+    return isPhiRecord(value)
+        ? value
+        : null;
+}
+export function runPhiDeveloperBuilderInspectorAction(defaultArea, action) {
+    const state = getPhiDeveloperBuilderStateSnapshot(defaultArea);
+    if (action.kind === "patchSelectedRegionDraft") {
+        const patch = readRecordPatch(action.patch);
+        const selectedRegionKey = state.nodeKind === "region" ? state.nodeKey.replace(/^region:/, "") : null;
+        const currentDraft = selectedRegionKey
+            ? resolveRegionDraftKey(getPhiDeveloperRegionDraftsSnapshot(), state.area, selectedRegionKey, state.pageKey) ?? getDefaultRegionDraft(selectedRegionKey)
+            : null;
+        if (!selectedRegionKey || !currentDraft || !patch) {
+            return;
+        }
+        setPhiDeveloperRegionDraft(getPhiBuilderRegionDraftKey(state.area, selectedRegionKey, state.pageKey), {
+            ...currentDraft,
+            ...patch,
+        }, {
+            history: {
+                context: createPhiBuilderRegionHistoryContext({
+                    area: state.area,
+                    pageKey: state.pageKey,
+                    pageScoped: isPhiBuilderPageScopedRegion(selectedRegionKey),
+                }),
+                action: { key: "changeRegion", regionKey: selectedRegionKey },
+                coalesceKey: resolveInspectorCoalesceKey(state, getPhiBuilderRegionDraftKey(state.area, selectedRegionKey, state.pageKey), Object.keys(patch).sort().join(",")),
+            },
+        });
+        return;
+    }
+    if (action.kind === "patchSelectedWidgetConfig") {
+        const patch = readRecordPatch(action.patch);
+        if (patch) {
+            patchSelectedWidgetDraftConfig(state, Object.keys(patch).sort().join(","), (config) => ({ ...config, ...patch }));
+        }
+        return;
+    }
+    if (action.kind === "patchSelectedWidgetGeometry") {
+        const geometry = readRecordPatch(action.geometry);
+        if (geometry) {
+            patchSelectedWidgetDraftConfig(state, "geometry", (config) => ({
+                ...config,
+                ...resolveWidgetSizeFromGeometry(geometry),
+            }), "resizeNode");
+        }
+        return;
+    }
+    if (action.kind === "patchSelectedWidgetSurface") {
+        const surface = action.surface;
+        patchSelectedWidgetDraftConfig(state, "surface", (config) => {
+            const next = { ...config };
+            if (surface == null) {
+                delete next.surface;
+            }
+            else {
+                next.surface = surface;
+            }
+            return next;
+        });
+        return;
+    }
+    if (action.kind === "setSelectedWidgetTranslate" || action.kind === "setSelectedLayoutTranslate") {
+        patchSelectedNode(state, action.kind === "setSelectedWidgetTranslate" ? "widget" : "layout", "translate", {
+            patchNode: (node) => ({
+                ...node,
+                flags: action.translate
+                    ? (node.flags ?? 0) & ~PhiCmsFlags.NoTranslate
+                    : (node.flags ?? 0) | PhiCmsFlags.NoTranslate,
+            }),
+            actionKey: "changeNodeTranslation",
+        });
+        return;
+    }
+    if (action.kind === "patchSelectedLayoutAnchor") {
+        const selectedLayoutAnchor = action.selectedLayoutAnchor;
+        if (typeof selectedLayoutAnchor !== "string") {
+            return;
+        }
+        patchSelectedStructureDraftConfig(state, "anchor", (config) => ({ ...config, anchor: selectedLayoutAnchor }));
+        builderWorkspaceStore.patch(defaultArea, (current) => ({
+            ...current,
+            selectedLayoutAnchor: selectedLayoutAnchor,
+        }));
+        return;
+    }
+    if (action.kind === "patchSelectedLayoutPadding") {
+        const padding = action.padding == null ? null : readRecordPatch(action.padding);
+        patchSelectedStructureDraftConfig(state, "padding", (config) => ({
+            ...config,
+            ...resolvePaddingPatch(padding),
+        }));
+        return;
+    }
+    if (action.kind === "patchSelectedLayoutSurface") {
+        const surface = action.surface;
+        patchSelectedStructureDraftConfig(state, "surface", (config) => {
+            const next = { ...config };
+            if (surface == null) {
+                delete next.surface;
+            }
+            else {
+                next.surface = surface;
+            }
+            return next;
+        });
+        return;
+    }
+    /*
+     * Every key the Layout Inspector changed in one gesture, written as one step: a padding control that
+     * answers four sides, or a grid placement that moves columns and placements together, used to send a
+     * key at a time and leave as many undo entries behind. A `null` takes the key away.
+     */
+    if (action.kind === "patchSelectedLayoutConfig") {
+        const entries = Object.entries(action.patch);
+        if (entries.length === 0) {
+            return;
+        }
+        patchSelectedStructureDraftConfig(state, entries.map(([key]) => key).sort().join(","), (config) => ({
+            ...config,
+            ...Object.fromEntries(entries.map(([key, value]) => [key, value ?? undefined])),
+        }));
+    }
+}

package/plugins/runtime-modules/builder/controller/mount.d.ts

@@ -1,2 +1,2 @@
-import type { PhiDeveloperBuilderWorkspaceControllerProps } from "../workspace-controller";
+import type { PhiDeveloperBuilderWorkspaceControllerProps } from "./workspace-controller";
 export declare function PhiDeveloperBuilderWorkspaceControllerMount(props: PhiDeveloperBuilderWorkspaceControllerProps): import("react").JSX.Element;

package/plugins/runtime-modules/builder/controller/mount.js

@@ -1,7 +1,7 @@
 "use client";
 import { jsx as _jsx } from "react/jsx-runtime";
 import { lazy } from "react";
-const PhiDeveloperBuilderWorkspaceController = lazy(() => import("../workspace-controller")
+const PhiDeveloperBuilderWorkspaceController = lazy(() => import("./workspace-controller")
     .then((module) => ({ default: module.PhiDeveloperBuilderWorkspaceController })));
 export function PhiDeveloperBuilderWorkspaceControllerMount(props) {
     return _jsx(PhiDeveloperBuilderWorkspaceController, { ...props });

package/plugins/runtime-modules/builder/{page-controller-helpers.d.ts → controller/page-controller-helpers.d.ts}

@@ -1,8 +1,6 @@
-import { type PhiPresetPageNode } from "../../../helpers/cms-page-catalog";
-import type { PhiDeveloperBuilderArea } from "./developer-workspace-types";
-import { type PhiCascaderOption } from "../../../components/controls/phi-cascader-control";
+import { type PhiPresetPageNode } from "../../../../helpers/cms-page-catalog";
+import type { PhiDeveloperBuilderArea } from "../developer-workspace-types";
 export declare function findPhiDeveloperBuilderPageNode(nodes: PhiPresetPageNode[], pageKey: string): PhiPresetPageNode | null;
 export declare function collectPhiDeveloperBuilderPageKeys(nodes: PhiPresetPageNode[], keys?: Set<string>): Set<string>;
-export declare function collectPhiDeveloperBuilderPagePathOptions(area: PhiDeveloperBuilderArea, nodes: PhiPresetPageNode[], paths?: Map<string, PhiCascaderOption>): PhiCascaderOption[];
 export declare function collectPhiDeveloperBuilderPageStoragePaths(area: PhiDeveloperBuilderArea, nodes: PhiPresetPageNode[]): Set<string>;
 export declare function resolveUniquePhiDeveloperBuilderPagePath(basePath: string, existingPaths: Set<string>): string;

package/plugins/runtime-modules/builder/{page-controller-helpers.js → controller/page-controller-helpers.js}

@@ -1,6 +1,6 @@
-import { normalizePhiBuilderCmsCatalogPath, } from "../../../helpers/cms-page-catalog";
-import { resolvePhiBuilderCmsStoragePath } from "../../../helpers/cms-paths";
-import { normalizePhiCascaderValue, } from "../../../components/controls/phi-cascader-control";
+import { normalizePhiBuilderCmsCatalogPath, } from "../../../../helpers/cms-page-catalog";
+import { resolvePhiBuilderCmsStoragePath } from "../../../../helpers/cms-paths";
+import { normalizePhiCascaderValue, } from "../../../../components/controls/phi-cascader-control";
 export function findPhiDeveloperBuilderPageNode(nodes, pageKey) {
     for (const node of nodes) {
         if (node.key === pageKey) {
@@ -22,7 +22,7 @@ export function collectPhiDeveloperBuilderPageKeys(nodes, keys = new Set()) {
     }
     return keys;
 }
-export function collectPhiDeveloperBuilderPagePathOptions(area, nodes, paths = new Map()) {
+function collectPhiDeveloperBuilderPagePathOptions(area, nodes, paths = new Map()) {
     for (const node of nodes) {
         const path = normalizePhiBuilderCmsCatalogPath(resolvePhiBuilderCmsStoragePath(area, node.key, nodes));
         paths.set(path, {

package/plugins/runtime-modules/builder/{page-controller.d.ts → controller/page-controller.d.ts}

@@ -1,8 +1,11 @@
-import type { PhiDeveloperBuilderArea, PhiDeveloperBuilderWorkspaceState } from "./developer-workspace-types";
-import type { PhiBuilderPageMetaPresentationLabels } from "./controller/definition";
+import type { PhiDeveloperBuilderArea, PhiDeveloperBuilderWorkspaceState } from "../developer-workspace-types";
+import { type PhiSignalValue } from "../../../../types/signals";
+import type { PhiBuilderPageMetaPresentationLabels } from "../controller/definition";
 type PhiBuilderPageControllerState = Pick<PhiDeveloperBuilderWorkspaceState, "customPages" | "modulePresetPagesByArea" | "pageMetaDrafts" | "persistedPageCatalogByArea">;
 type PhiPageMetaDialogMode = "create" | "update";
-export declare function usePhiBuilderPageController({ defaultArea, effectiveArea, effectivePageKey, pageMetaLabels, state, }: {
+export declare function usePhiBuilderPageController({ emitCapability, defaultArea, effectiveArea, effectivePageKey, pageMetaLabels, state, }: {
+    /** The Builder Controller's own output: the Page metadata dialog is routed by the Pages Page. */
+    emitCapability: (capabilityId: string, value: PhiSignalValue, correlationId?: string | null) => void;
     defaultArea: PhiDeveloperBuilderArea;
     effectiveArea: PhiDeveloperBuilderArea;
     effectivePageKey: string;

package/plugins/runtime-modules/builder/{page-controller.js → controller/page-controller.js}

@@ -1,82 +1,50 @@
 "use client";
-import { readPhiDeveloperBuilderWorkspaceKey } from "./route-scope";
+import { readPhiDeveloperBuilderWorkspaceKey } from "../route-scope";
 import { useCallback, useEffect, useState } from "react";
-import { usePathname, useRouter, useSearchParams } from "next/navigation";
-import {} from "../../../components/widgets/signals/page-title-signals";
-import { normalizePhiCascaderValue } from "../../../components/controls/phi-cascader-control";
-import { usePhiSignalDispatcher, usePhiSignalListener } from "../../../components/runtime/runtime-signal-bus";
-import { usePhiApplicationFeedback } from "../../../components/runtime/use-phi-application-feedback";
-import { normalizePhiBuilderCmsCatalogPath, resolvePhiBuilderActivePageCatalog, resolvePhiBuilderPageKeyFromCatalogPath, } from "../../../helpers/cms-page-catalog";
-import { changePhiBuilderPagePath, loadPhiBuilderPersistedPageCatalog } from "./page-catalog-client";
-import { resolvePhiBuilderCmsStoragePath } from "../../../helpers/cms-paths";
+import { useRouter, useSearchParams } from "next/navigation";
+import {} from "../../../../components/widgets/signals/page-title-signals";
+import { normalizePhiCascaderValue } from "../../../../components/controls/phi-cascader-control";
+import { usePhiSignalDispatcher, usePhiSignalListener } from "../../../../components/runtime/runtime-signal-bus";
+import { usePhiApplicationFeedback } from "../../../../components/runtime/use-phi-application-feedback";
+import { normalizePhiBuilderCmsCatalogPath, resolvePhiBuilderActivePageCatalog, resolvePhiBuilderPageKeyFromCatalogPath, } from "../../../../helpers/cms-page-catalog";
+import { changePhiBuilderPagePath, loadPhiBuilderPersistedPageCatalog } from "../page-catalog-client";
+import { resolvePhiBuilderCmsStoragePath } from "../../../../helpers/cms-paths";
 import { collectPhiDeveloperBuilderPageKeys, collectPhiDeveloperBuilderPageStoragePaths, findPhiDeveloperBuilderPageNode, resolveUniquePhiDeveloperBuilderPagePath, } from "./page-controller-helpers";
-import { createPhiDeveloperBuilderInitialPageDrafts, createPhiDeveloperBuilderPageDraft, PhiBuilderPageExistsError, } from "./persistence";
-import { describePhiBuilderPageAddressConflict, findPhiBuilderSitePageAddressConflict, } from "./page-address-rule";
-import { PHI_BUILDER_AREA_SEARCH_PARAM, PHI_BUILDER_PAGE_SEARCH_PARAM, } from "../../../helpers/cms-scope-search-params";
-import { builderWorkspaceStore, createDefaultBuilderChromeControls, mergePhiDeveloperRegionDrafts, getPhiDeveloperBuilderStateSnapshot, } from "./developer-workspace-store";
-import { getPhiBuilderRegionDraftKey } from "./region-keys";
-import { capturePhiBuilderWorkspaceHistoryState, createPhiBuilderHistoryContext, phiBuilderHistory, } from "./history";
-import { createPhiBuilderControllerAddress } from "./controller/address";
-import { PHI_BUILDER_PAGE_META_OVERLAY_IDS, PHI_BUILDER_PAGE_META_WIDGET_IDS, } from "./addresses";
-import { createPhiRuntimeFormControllerAddress } from "../../../components/forms/runtime-form-controller-address";
-import { createPhiSignalAddress, createPhiSignalSubcontrolAddress, PHI_SIGNAL_VALUE_SCHEMAS } from "../../../types/signals";
-import { readPhiRuntimeFormValuesSignalValue } from "../../../components/forms/runtime-form-state";
-import { emitPhiPageTitleInputSignal } from "./page-title-signal";
-import { phiWorkspaceCatalogStore } from "../../../components/workspace/catalog-store";
-export function usePhiBuilderPageController({ defaultArea, effectiveArea, effectivePageKey, pageMetaLabels, state, }) {
+import { createPhiDeveloperBuilderInitialPageDrafts, createPhiDeveloperBuilderPageDraft, PhiBuilderPageExistsError, } from "../persistence";
+import { describePhiBuilderPageAddressConflict, findPhiBuilderSitePageAddressConflict, } from "../page-address-rule";
+import { PHI_BUILDER_AREA_SEARCH_PARAM, PHI_BUILDER_PAGE_SEARCH_PARAM, } from "../../../../helpers/cms-scope-search-params";
+import { builderWorkspaceStore, mergePhiDeveloperRegionDrafts, resetPhiBuilderSelectionToPage, getPhiDeveloperBuilderStateSnapshot, } from "../developer-workspace-store";
+import { getPhiBuilderRegionDraftKey } from "../region-keys";
+import { capturePhiBuilderWorkspaceHistoryState, createPhiBuilderHistoryContext, phiBuilderHistory, } from "../history";
+import { createPhiBuilderControllerAddress } from "../controller/address";
+import { PHI_SIGNAL_VALUE_SCHEMAS } from "../../../../types/signals";
+import { readPhiRuntimeFormValuesSignalValue } from "../../../../components/forms/runtime-form-state";
+import { emitPhiPageTitleInputSignal } from "../page-title-signal";
+import { phiWorkspaceCatalogStore } from "../../../../components/workspace/catalog-store";
+import { usePhiPathname } from "../../../../components/runtime/use-phi-pathname";
+export function usePhiBuilderPageController({ emitCapability, defaultArea, effectiveArea, effectivePageKey, pageMetaLabels, state, }) {
     const { showMessage } = usePhiApplicationFeedback();
     const router = useRouter();
-    const pathname = usePathname();
+    const pathname = usePhiPathname();
     const searchParams = useSearchParams();
     const emitSignal = usePhiSignalDispatcher();
     const [pageMetaDialogMode, setPageMetaDialogMode] = useState("create");
     const [pageMetaDialogSaving, setPageMetaDialogSaving] = useState(false);
     const [pendingPageMetaInitialValues, setPendingPageMetaInitialValues] = useState(null);
-    const pageMetaFormControllerAddress = createPhiRuntimeFormControllerAddress(`widget-${PHI_BUILDER_PAGE_META_WIDGET_IDS.form}`);
-    const pageMetaOverlayAddress = createPhiSignalAddress("cms", PHI_BUILDER_PAGE_META_OVERLAY_IDS.editor);
-    const pageMetaSaveControlAddress = createPhiSignalSubcontrolAddress("cms", PHI_BUILDER_PAGE_META_WIDGET_IDS.commands, "save");
     const emitPageMetaTitle = useCallback((title) => {
-        emitSignal({
-            scope: "page",
-            channel: "title",
-            action: "change",
-            value: title,
-            valueType: "string",
-            sender: createPhiBuilderControllerAddress(),
-            receiver: pageMetaOverlayAddress,
-            timestamp: Date.now(),
-        });
-    }, [emitSignal, pageMetaOverlayAddress]);
+        emitCapability("overlayTitle", title);
+    }, [emitCapability]);
     const emitPageMetaActionLabel = useCallback((label) => {
-        emitSignal({
-            scope: "page",
-            channel: "label",
-            action: "change",
-            value: label,
-            valueType: "string",
-            sender: createPhiBuilderControllerAddress(),
-            receiver: pageMetaSaveControlAddress,
-            timestamp: Date.now(),
-        });
-    }, [emitSignal, pageMetaSaveControlAddress]);
+        emitCapability("commandLabel", label);
+    }, [emitCapability]);
     /*
      * `correlationId` is the exchange this opening or closing belongs to. Opening from a toolbar click
      * begins one and passes none; closing after a submit continues the one the submit arrived on, across
      * the await that saved the page.
      */
     const dispatchPageMetaOverlay = useCallback((action, correlationId) => {
-        emitSignal({
-            scope: "page",
-            channel: "dialog",
-            action,
-            value: null,
-            valueType: "none",
-            sender: createPhiBuilderControllerAddress(),
-            receiver: pageMetaOverlayAddress,
-            correlationId,
-            timestamp: Date.now(),
-        });
-    }, [emitSignal, pageMetaOverlayAddress]);
+        emitCapability(action === "activate" ? "pageMetaOpen" : "pageMetaClose", null, correlationId);
+    }, [emitCapability]);
     const currentPageTree = resolvePhiBuilderActivePageCatalog(effectiveArea, state.modulePresetPagesByArea, state.customPages, state.persistedPageCatalogByArea);
     const resolvePageTitleForInput = useCallback((pageKey) => {
         return findPhiDeveloperBuilderPageNode(currentPageTree, pageKey)?.title?.trim() || pageKey;
@@ -109,19 +77,7 @@ export function usePhiBuilderPageController({ defaultArea, effectiveArea, effect
             area: effectiveArea,
             pageKey,
         }));
-        builderWorkspaceStore.patch(defaultArea, (current) => ({
-            ...current,
-            nodeKey: `page:${pageKey}`,
-            nodeId: null,
-            nodeKind: "page",
-            selectedRegionType: null,
-            selectedRegionKey: null,
-            selectedRootRegionKey: null,
-            inspectorOpen: false,
-            sidebarKey: "pages",
-            pagesOpen: false,
-            builderChromeControls: createDefaultBuilderChromeControls(),
-        }));
+        builderWorkspaceStore.patch(defaultArea, (current) => resetPhiBuilderSelectionToPage(current, pageKey, { closePages: true }));
         if (typeof pathname === "string") {
             const nextSearchParams = new URLSearchParams(searchParams.toString());
             nextSearchParams.set(PHI_BUILDER_AREA_SEARCH_PARAM, effectiveArea);
@@ -169,34 +125,19 @@ export function usePhiBuilderPageController({ defaultArea, effectiveArea, effect
         dispatchPageMetaOverlay("activate");
     }
     useEffect(() => {
-        emitSignal({
-            scope: "page",
-            channel: "pageMetaSubmitting",
-            action: "change",
-            value: pageMetaDialogSaving,
-            valueType: "boolean",
-            sender: createPhiBuilderControllerAddress(),
-            receiver: pageMetaSaveControlAddress,
-            timestamp: Date.now(),
-        });
-    }, [emitSignal, pageMetaDialogSaving, pageMetaSaveControlAddress]);
+        emitCapability("pageMetaSubmitting", pageMetaDialogSaving);
+    }, [emitCapability, pageMetaDialogSaving]);
     useEffect(() => {
         if (!pendingPageMetaInitialValues)
             return;
-        emitSignal({
-            scope: "page",
-            channel: "values",
-            action: "change",
-            value: { values: pendingPageMetaInitialValues },
-            valueType: "json",
-            valueSchema: PHI_SIGNAL_VALUE_SCHEMAS.formValues,
-            sender: createPhiBuilderControllerAddress(),
-            receiver: pageMetaFormControllerAddress,
-            timestamp: Date.now(),
-        });
-    }, [emitSignal, pageMetaFormControllerAddress, pendingPageMetaInitialValues]);
+        emitCapability("pageMetaFormValues", { values: pendingPageMetaInitialValues });
+    }, [emitCapability, pendingPageMetaInitialValues]);
     async function submitPageMetaDialog(values, correlationId) {
-        const title = typeof values.title === "string" ? values.title.trim() || "New Page" : "New Page";
+        const enteredTitle = typeof values.title === "string" ? values.title.trim() : "";
+        // Only a new Page needs a name to start from; an emptied title on an existing one is no title of its
+        // own, not a Page renamed to "New Page".
+        const title = enteredTitle || "New Page";
+        const editedTitle = enteredTitle || null;
         const description = typeof values.description === "string" ? values.description.trim() : "";
         const requestedPath = normalizePhiBuilderCmsCatalogPath(normalizePhiCascaderValue(typeof values.path === "string" ? values.path : title, { normalize: "path" }));
         /*
@@ -248,7 +189,7 @@ export function usePhiBuilderPageController({ defaultArea, effectiveArea, effect
                         ...current.pageMetaDrafts,
                         [pageMetaDraftKey]: {
                             ...(current.pageMetaDrafts[pageMetaDraftKey] ?? {}),
-                            title,
+                            title: editedTitle,
                             description,
                             ...indexPatch,
                         },
@@ -260,7 +201,7 @@ export function usePhiBuilderPageController({ defaultArea, effectiveArea, effect
                     area: effectiveArea,
                     pageKey: effectivePageKey,
                 }), {
-                    label: "Update page metadata",
+                    action: { key: "changePageMeta", subject: editedTitle ?? effectivePageKey },
                     before: {
                         kind: "workspace",
                         state: historyBefore,
@@ -270,7 +211,7 @@ export function usePhiBuilderPageController({ defaultArea, effectiveArea, effect
                         state: capturePhiBuilderWorkspaceHistoryState(getPhiDeveloperBuilderStateSnapshot(defaultArea)),
                     },
                 });
-                emitPageTitleInputValue(effectivePageKey, title);
+                emitPageTitleInputValue(effectivePageKey, editedTitle);
                 if (pathResult) {
                     await reloadPersistedPageCatalog(effectiveArea);
                     const refreshed = getPhiDeveloperBuilderStateSnapshot(defaultArea);
@@ -404,17 +345,7 @@ export function usePhiBuilderPageController({ defaultArea, effectiveArea, effect
             signal.value === "save") {
             if (pageMetaDialogSaving)
                 return;
-            emitSignal({
-                scope: "page",
-                channel: "submit",
-                action: "activate",
-                value: null,
-                valueType: "none",
-                sender: createPhiBuilderControllerAddress(),
-                receiver: createPhiSignalAddress("cms", PHI_BUILDER_PAGE_META_WIDGET_IDS.form),
-                correlationId: signal.correlationId,
-                timestamp: Date.now(),
-            });
+            emitCapability("pageMetaSubmit", null, signal.correlationId);
             return;
         }
         if (signal.channel === "pageMeta" &&
@@ -424,17 +355,7 @@ export function usePhiBuilderPageController({ defaultArea, effectiveArea, effect
             if (pageMetaDialogSaving)
                 return;
             setPendingPageMetaInitialValues(null);
-            emitSignal({
-                scope: "page",
-                channel: "reset",
-                action: "activate",
-                value: null,
-                valueType: "none",
-                sender: createPhiBuilderControllerAddress(),
-                receiver: createPhiSignalAddress("cms", PHI_BUILDER_PAGE_META_WIDGET_IDS.form),
-                correlationId: signal.correlationId,
-                timestamp: Date.now(),
-            });
+            emitCapability("pageMetaReset", null, signal.correlationId);
             dispatchPageMetaOverlay("close", signal.correlationId);
             return;
         }
@@ -443,17 +364,7 @@ export function usePhiBuilderPageController({ defaultArea, effectiveArea, effect
             signal.value === false &&
             !pageMetaDialogSaving) {
             setPendingPageMetaInitialValues(null);
-            emitSignal({
-                scope: "page",
-                channel: "reset",
-                action: "activate",
-                value: null,
-                valueType: "none",
-                sender: createPhiBuilderControllerAddress(),
-                receiver: createPhiSignalAddress("cms", PHI_BUILDER_PAGE_META_WIDGET_IDS.form),
-                correlationId: signal.correlationId,
-                timestamp: Date.now(),
-            });
+            emitCapability("pageMetaReset", null, signal.correlationId);
             return;
         }
         if (signal.channel === "pageMetaForm" &&

package/plugins/runtime-modules/builder/controller/preview-controller.d.ts

@@ -0,0 +1,5 @@
+import type { PhiDeveloperBuilderWorkspaceState } from "../developer-workspace-types";
+export declare function usePhiDeveloperBuilderPreviewModeController(state: Pick<PhiDeveloperBuilderWorkspaceState, "area" | "pageKey" | "runtimeModuleIdsByArea">): {
+    enterEditor: () => void;
+    enterPreview: () => Promise<void>;
+};