@phis/ui 0.4.2 → 0.4.4

package/plugins/runtime-modules/builder/developer-workspace-store.js

@@ -1,4 +1,5 @@
 "use client";
+import { PHI_WORKSPACE_CATALOG_SCOPE } from "../../../components/workspace/catalog-store";
 import { isPhiBuilderAreaKey } from "../../../constants/cms-areas";
 import { prunePhiSignalRoutesFromConfig, } from "../../../helpers/signal-route-lifecycle";
 import { createPhiSignalCorrelationId } from "../../../components/runtime/runtime-signal-bus";
@@ -6,6 +7,7 @@ import { useRef, useSyncExternalStore } from "react";
 import { createPhiPluginStateStore } from "../../../components/state/plugin-state-store";
 import { phiWorkspaceCatalogStore, } from "../../../components/workspace/catalog-store";
 import { phiBuilderHistory } from "./history";
+import { openPhiWorkspacePage, restorePhiWorkspaceCatalog, setPhiWorkspacePageKey, } from "./workspace-catalog-actions";
 export function normalizePhiDeveloperBuilderArea(scopeKey) {
     return isPhiBuilderAreaKey(scopeKey) ? scopeKey : "public";
 }
@@ -54,14 +56,14 @@ function createDefaultBuilderState() {
 }
 export const builderWorkspaceStore = createPhiPluginStateStore("@phis/ui/developer-workspace", createDefaultBuilderState);
 const builderEffectsCommitters = new Map();
-export function openPhiDeveloperBuilderEffectsEditor(scopeKey, effects, target, onCommit) {
+export function openPhiDeveloperBuilderEffectsEditor(effects, target, onCommit) {
     const correlationId = createPhiSignalCorrelationId();
-    const previousRequest = builderWorkspaceStore.getSnapshot(scopeKey).effectsEditorRequest;
+    const previousRequest = builderWorkspaceStore.getSnapshot(PHI_WORKSPACE_CATALOG_SCOPE).effectsEditorRequest;
     if (previousRequest) {
         builderEffectsCommitters.delete(previousRequest.correlationId);
     }
     builderEffectsCommitters.set(correlationId, onCommit);
-    builderWorkspaceStore.patch(scopeKey, (current) => ({
+    builderWorkspaceStore.patch(PHI_WORKSPACE_CATALOG_SCOPE, (current) => ({
         ...current,
         effectsEditorRequest: { correlationId, effects, target, preview: null },
     }));
@@ -74,8 +76,8 @@ export function openPhiDeveloperBuilderEffectsEditor(scopeKey, effects, target,
  * checked because the editor that sent this may already be closed -- a late message from a gesture that
  * ended must not put a picture back on a node whose editor is gone.
  */
-export function previewPhiDeveloperBuilderEffects(scopeKey, correlationId, preview) {
-    builderWorkspaceStore.patch(scopeKey, (current) => (current.effectsEditorRequest?.correlationId === correlationId
+export function previewPhiDeveloperBuilderEffects(correlationId, preview) {
+    builderWorkspaceStore.patch(PHI_WORKSPACE_CATALOG_SCOPE, (current) => (current.effectsEditorRequest?.correlationId === correlationId
         ? { ...current, effectsEditorRequest: { ...current.effectsEditorRequest, preview } }
         : current));
 }
@@ -91,10 +93,10 @@ export function readPhiDeveloperBuilderEffectsPreview(state, kind, blockId) {
         return null;
     return request.target.kind === kind && request.target.blockId === blockId ? request.preview : null;
 }
-export function completePhiDeveloperBuilderEffectsEditor(scopeKey, request, effects) {
+export function completePhiDeveloperBuilderEffectsEditor(request, effects) {
     const onCommit = builderEffectsCommitters.get(request.correlationId);
     builderEffectsCommitters.delete(request.correlationId);
-    builderWorkspaceStore.patch(scopeKey, (current) => ({
+    builderWorkspaceStore.patch(PHI_WORKSPACE_CATALOG_SCOPE, (current) => ({
         ...current,
         effectsEditorRequest: current.effectsEditorRequest?.correlationId === request.correlationId
             ? null
@@ -111,17 +113,17 @@ export function completePhiDeveloperBuilderEffectsEditor(scopeKey, request, effe
  * which Areas, and which addresses are contested -- and the answer is what enables the Module. A second
  * question replaces the first, because there is only one dialog and only one gesture behind it.
  */
-export function openPhiBuilderPublicRouteCollisionRequest(scopeKey, request) {
+export function openPhiBuilderPublicRouteCollisionRequest(request) {
     const correlationId = createPhiSignalCorrelationId();
-    builderWorkspaceStore.patch(scopeKey, (current) => ({
+    builderWorkspaceStore.patch(PHI_WORKSPACE_CATALOG_SCOPE, (current) => ({
         ...current,
         publicRouteCollisionRequest: { ...request, correlationId },
     }));
     return correlationId;
 }
 /** The address being typed for one contested route. */
-export function answerPhiBuilderPublicRouteCollision(scopeKey, presetKey, path) {
-    builderWorkspaceStore.patch(scopeKey, (current) => {
+export function answerPhiBuilderPublicRouteCollision(presetKey, path) {
+    builderWorkspaceStore.patch(PHI_WORKSPACE_CATALOG_SCOPE, (current) => {
         const request = current.publicRouteCollisionRequest;
         if (!request) {
             return current;
@@ -141,21 +143,21 @@ export function answerPhiBuilderPublicRouteCollision(scopeKey, presetKey, path)
  * Opened only when there is something to say: a Module nothing draws from is switched off without a
  * word, because a dialog that always says "nothing happens" is a dialog nobody reads.
  */
-export function openPhiBuilderModuleDeactivationRequest(scopeKey, request) {
+export function openPhiBuilderModuleDeactivationRequest(request) {
     const correlationId = createPhiSignalCorrelationId();
-    builderWorkspaceStore.patch(scopeKey, (current) => ({
+    builderWorkspaceStore.patch(PHI_WORKSPACE_CATALOG_SCOPE, (current) => ({
         ...current,
         moduleDeactivationRequest: { ...request, correlationId },
     }));
     return correlationId;
 }
-export function closePhiBuilderModuleDeactivationRequest(scopeKey) {
-    builderWorkspaceStore.patch(scopeKey, (current) => current.moduleDeactivationRequest === null
+export function closePhiBuilderModuleDeactivationRequest() {
+    builderWorkspaceStore.patch(PHI_WORKSPACE_CATALOG_SCOPE, (current) => current.moduleDeactivationRequest === null
         ? current
         : { ...current, moduleDeactivationRequest: null });
 }
-export function closePhiBuilderPublicRouteCollisionRequest(scopeKey) {
-    builderWorkspaceStore.patch(scopeKey, (current) => current.publicRouteCollisionRequest === null
+export function closePhiBuilderPublicRouteCollisionRequest() {
+    builderWorkspaceStore.patch(PHI_WORKSPACE_CATALOG_SCOPE, (current) => current.publicRouteCollisionRequest === null
         ? current
         : { ...current, publicRouteCollisionRequest: null });
 }
@@ -165,7 +167,7 @@ export function closePhiBuilderPublicRouteCollisionRequest(scopeKey) {
  * change, a new Page -- which used to be four copies that had drifted apart. `chrome` resets the
  * chrome controls as well, `closePages` folds the Pages panel.
  */
-export function resetPhiBuilderSelectionToPage(current, pageKey, options = {}) {
+function resetPhiBuilderSelectionToPage(current, pageKey, options = {}) {
     return {
         ...current,
         nodeKey: `page:${pageKey}`,
@@ -179,11 +181,9 @@ export function resetPhiBuilderSelectionToPage(current, pageKey, options = {}) {
         ...(options.closePages ? { pagesOpen: false } : {}),
     };
 }
-export function selectPhiDeveloperBuilderNode(scopeKey, selection) {
-    builderWorkspaceStore.patch(scopeKey, (current) => ({
+export function selectPhiDeveloperBuilderNode(selection) {
+    builderWorkspaceStore.patch(PHI_WORKSPACE_CATALOG_SCOPE, (current) => ({
         ...current,
-        ...(selection.area ? { area: selection.area } : {}),
-        ...(selection.pageKey ? { pageKey: selection.pageKey } : {}),
         nodeKey: selection.nodeKey,
         nodeId: selection.nodeId ?? null,
         nodeKind: selection.nodeKind,
@@ -220,8 +220,8 @@ export function selectPhiDeveloperBuilderNode(scopeKey, selection) {
     }));
 }
 const builderRegionDraftStore = createPhiPluginStateStore("@phis/ui/developer-region-drafts", () => ({}));
-export function patchPhiDeveloperBuilderState(scopeKey, next) {
-    builderWorkspaceStore.patch(scopeKey, (current) => ({
+export function patchPhiDeveloperBuilderState(next) {
+    builderWorkspaceStore.patch(PHI_WORKSPACE_CATALOG_SCOPE, (current) => ({
         ...current,
         ...next,
     }));
@@ -243,7 +243,7 @@ const PHI_WORKSPACE_CATALOG_KEYS = [
     "publicRouteClaims",
     "publicRoutePaths",
 ];
-export function splitWorkspacePatch(next) {
+function splitWorkspacePatch(next) {
     const catalog = {};
     const tool = {};
     for (const [key, value] of Object.entries(next)) {
@@ -410,7 +410,7 @@ export function setPhiDeveloperRegionDraftsWithHistory(drafts, options) {
  * of an older one beside half of a newer one would be a state no Site was ever in.
  */
 export function setPhiDeveloperBuilderAreaRootRoutes(areaRootRoutes) {
-    builderWorkspaceStore.patch("public", (current) => JSON.stringify(current.areaRootRoutes) === JSON.stringify(areaRootRoutes)
+    builderWorkspaceStore.patch(PHI_WORKSPACE_CATALOG_SCOPE, (current) => JSON.stringify(current.areaRootRoutes) === JSON.stringify(areaRootRoutes)
         ? current
         : { ...current, areaRootRoutes });
 }
@@ -437,7 +437,7 @@ export function readPhiBuilderEffectiveAreaRootRoute(state, area) {
  * rather than guessing at it: the value that was sent is the value the server now holds.
  */
 export function commitPhiDeveloperBuilderAreaConfig(area, committed) {
-    builderWorkspaceStore.patch("public", (current) => {
+    builderWorkspaceStore.patch(PHI_WORKSPACE_CATALOG_SCOPE, (current) => {
         const rootRoutes = { ...current.areaRootRoutes, [area]: committed.rootRoute };
         const areaMeta = { ...current.areaMeta, [area]: committed.meta };
         return JSON.stringify(current.areaRootRoutes) === JSON.stringify(rootRoutes) &&
@@ -469,7 +469,7 @@ export function readPhiBuilderStoredAreaRootRoute(state, area) {
  * default back and the write has to remove the stored config.
  */
 export function setPhiDeveloperBuilderAreaRootRoute(area, rootRoute) {
-    builderWorkspaceStore.patch("public", (current) => {
+    builderWorkspaceStore.patch(PHI_WORKSPACE_CATALOG_SCOPE, (current) => {
         const next = { ...current.areaRootRouteDrafts };
         if (rootRoute === undefined) {
             delete next[area];
@@ -482,19 +482,19 @@ export function setPhiDeveloperBuilderAreaRootRoute(area, rootRoute) {
 }
 /** What the Areas answered about being found, as the server sent it with the workspace. */
 export function setPhiDeveloperBuilderAreaMetaBaseline(areaMeta) {
-    builderWorkspaceStore.patch("public", (current) => JSON.stringify(current.areaMeta) === JSON.stringify(areaMeta)
+    builderWorkspaceStore.patch(PHI_WORKSPACE_CATALOG_SCOPE, (current) => JSON.stringify(current.areaMeta) === JSON.stringify(areaMeta)
         ? current
         : { ...current, areaMeta });
 }
 /** What each Area's Shell tells its Controllers, as the server sent it with the workspace. */
 export function setPhiDeveloperBuilderAreaControllerSettings(settingsByArea) {
-    builderWorkspaceStore.patch("public", (current) => JSON.stringify(current.areaControllerSettings) === JSON.stringify(settingsByArea)
+    builderWorkspaceStore.patch(PHI_WORKSPACE_CATALOG_SCOPE, (current) => JSON.stringify(current.areaControllerSettings) === JSON.stringify(settingsByArea)
         ? current
         : { ...current, areaControllerSettings: settingsByArea });
 }
 /** What a Page tells its Controllers, by its Page meta draft key, as the server sent it with the Page. */
 export function setPhiDeveloperBuilderPageControllerSettings(draftKey, settings) {
-    builderWorkspaceStore.patch("public", (current) => JSON.stringify(current.pageControllerSettings[draftKey]) === JSON.stringify(settings)
+    builderWorkspaceStore.patch(PHI_WORKSPACE_CATALOG_SCOPE, (current) => JSON.stringify(current.pageControllerSettings[draftKey]) === JSON.stringify(settings)
         ? current
         : { ...current, pageControllerSettings: { ...current.pageControllerSettings, [draftKey]: settings } });
 }
@@ -517,7 +517,7 @@ export function readPhiBuilderEffectiveAreaMeta(state, area) {
  * is an Area that stated it has nothing to say.
  */
 export function restorePhiDeveloperBuilderAreaMeta(area, meta) {
-    builderWorkspaceStore.patch("public", (current) => {
+    builderWorkspaceStore.patch(PHI_WORKSPACE_CATALOG_SCOPE, (current) => {
         const next = { ...current.areaMetaDrafts };
         if (meta === undefined) {
             delete next[area];
@@ -540,7 +540,7 @@ export function mergePhiDeveloperRegionDrafts(drafts) {
     });
 }
 export function mergePhiDeveloperPagePresetDrafts(drafts) {
-    builderWorkspaceStore.patch("public", (current) => ({
+    builderWorkspaceStore.patch(PHI_WORKSPACE_CATALOG_SCOPE, (current) => ({
         ...current,
         pagePresetDrafts: {
             ...current.pagePresetDrafts,
@@ -550,7 +550,7 @@ export function mergePhiDeveloperPagePresetDrafts(drafts) {
 }
 export function mergePhiDeveloperPageMetaDrafts(area, drafts) {
     void area;
-    builderWorkspaceStore.patch("public", (current) => {
+    builderWorkspaceStore.patch(PHI_WORKSPACE_CATALOG_SCOPE, (current) => {
         let hasChanges = false;
         const missingDrafts = {};
         for (const [draftKey, draft] of Object.entries(drafts)) {
@@ -573,7 +573,7 @@ export function mergePhiDeveloperPageMetaDrafts(area, drafts) {
 }
 export function mergePhiDeveloperDeletedPageDrafts(area, drafts) {
     void area;
-    builderWorkspaceStore.patch("public", (current) => {
+    builderWorkspaceStore.patch(PHI_WORKSPACE_CATALOG_SCOPE, (current) => {
         let hasChanges = false;
         const nextDrafts = { ...current.deletedPageDrafts };
         for (const [draftKey, deleted] of Object.entries(drafts)) {
@@ -604,51 +604,52 @@ export function usePhiDeveloperRegionDraft(draftKey) {
 export function usePhiDeveloperRegionDraftsValue(selector) {
     return builderRegionDraftStore.useStoreSelector("default", selector);
 }
-const mergedWorkspaceSnapshots = new Map();
+/*
+ * The Builder's state is one per workspace host, not one per Area (`PHI_WORKSPACE_CATALOG_SCOPE`). What
+ * belongs to an Area is keyed by Area inside it -- its Module selection, its Page catalog, its meta, its
+ * drafts -- and which Area is open is the catalog's `area`. A scope per Area was promised once and never
+ * used: every caller passed "public".
+ */
+let mergedWorkspaceSnapshot = null;
 /**
  * Merging on every read would hand `useSyncExternalStore` a new object each time and never settle, so
  * the merged view is kept until one of the two sources actually changes.
  */
-function readMergedWorkspaceSnapshot(area) {
-    const tool = builderWorkspaceStore.getSnapshot(area);
-    const catalog = phiWorkspaceCatalogStore.getSnapshot(area);
-    const cached = mergedWorkspaceSnapshots.get(area);
+function readMergedWorkspaceSnapshot() {
+    const tool = builderWorkspaceStore.getSnapshot(PHI_WORKSPACE_CATALOG_SCOPE);
+    const catalog = phiWorkspaceCatalogStore.getSnapshot(PHI_WORKSPACE_CATALOG_SCOPE);
+    const cached = mergedWorkspaceSnapshot;
     if (cached && Object.is(cached.tool, tool) && Object.is(cached.catalog, catalog)) {
         return cached.merged;
     }
     const merged = { ...tool, ...catalog };
-    mergedWorkspaceSnapshots.set(area, { tool, catalog, merged });
+    mergedWorkspaceSnapshot = { tool, catalog, merged };
     return merged;
 }
 /** The whole merged view, for the few places that work with the state as one object. */
-export function usePhiDeveloperBuilderWorkspaceState(area) {
-    return usePhiDeveloperBuilderStateValue(area, (state) => state);
+export function usePhiDeveloperBuilderWorkspaceState() {
+    return usePhiDeveloperBuilderStateValue((state) => state);
 }
-const mergedHydrationSnapshots = new Map();
+let mergedHydrationSnapshot = null;
 /** Hydration must render what the server rendered, so it merges the two hydration values, not the live ones. */
-function readMergedHydrationSnapshot(area) {
-    const cached = mergedHydrationSnapshots.get(area);
-    if (cached) {
-        return cached;
-    }
-    const merged = {
-        ...builderWorkspaceStore.getHydrationSnapshot(area),
-        ...phiWorkspaceCatalogStore.getHydrationSnapshot(area),
+function readMergedHydrationSnapshot() {
+    mergedHydrationSnapshot ??= {
+        ...builderWorkspaceStore.getHydrationSnapshot(PHI_WORKSPACE_CATALOG_SCOPE),
+        ...phiWorkspaceCatalogStore.getHydrationSnapshot(PHI_WORKSPACE_CATALOG_SCOPE),
     };
-    mergedHydrationSnapshots.set(area, merged);
-    return merged;
+    return mergedHydrationSnapshot;
 }
-export function usePhiDeveloperBuilderStateValue(area, selector) {
+export function usePhiDeveloperBuilderStateValue(selector) {
     const selectedRef = useRef(null);
     return useSyncExternalStore((listener) => {
-        const unsubscribeTool = builderWorkspaceStore.subscribe(area, listener);
-        const unsubscribeCatalog = phiWorkspaceCatalogStore.subscribe(area, listener);
+        const unsubscribeTool = builderWorkspaceStore.subscribe(PHI_WORKSPACE_CATALOG_SCOPE, listener);
+        const unsubscribeCatalog = phiWorkspaceCatalogStore.subscribe(PHI_WORKSPACE_CATALOG_SCOPE, listener);
         return () => {
             unsubscribeTool();
             unsubscribeCatalog();
         };
     }, () => {
-        const source = readMergedWorkspaceSnapshot(area);
+        const source = readMergedWorkspaceSnapshot();
         const cached = selectedRef.current;
         if (cached && Object.is(cached.source, source)) {
             return cached.selected;
@@ -656,11 +657,204 @@ export function usePhiDeveloperBuilderStateValue(area, selector) {
         const selected = selector(source);
         selectedRef.current = { source, selected };
         return selected;
-    }, () => selector(readMergedHydrationSnapshot(area)));
+    }, () => selector(readMergedHydrationSnapshot()));
 }
 export function getPhiDeveloperRegionDraftsSnapshot() {
     return builderRegionDraftStore.getSnapshot("default");
 }
-export function getPhiDeveloperBuilderStateSnapshot(area = "public") {
-    return readMergedWorkspaceSnapshot(area);
+export function getPhiDeveloperBuilderStateSnapshot() {
+    return readMergedWorkspaceSnapshot();
+}
+/*
+ * The Builder's own actions on its tool state.
+ *
+ * Everything that writes the tool store (`builderWorkspaceStore`) is in this file, by name: what a
+ * caller wants -- open a Page, show the Inspector, take the next node id -- not a patch of whatever
+ * fields it holds. Forty-two writes in nine files did this before, and the selection wrote an Area and a
+ * Page into a store whose merged view always took both from the catalog.
+ * `scripts/validate-builder-store-ownership.mjs` keeps it in one place.
+ */
+/** Opens a Page of an Area: the catalog says what is open, the selection starts at the Page itself. */
+export function openPhiBuilderPage(area, pageKey, options = {}) {
+    openPhiWorkspacePage(area, pageKey);
+    builderWorkspaceStore.patch(PHI_WORKSPACE_CATALOG_SCOPE, (current) => resetPhiBuilderSelectionToPage(current, pageKey, options));
+}
+/** Opens a Page of the Area that is open. */
+export function openPhiBuilderPageInOpenArea(pageKey, options = {}) {
+    setPhiWorkspacePageKey(pageKey);
+    builderWorkspaceStore.patch(PHI_WORKSPACE_CATALOG_SCOPE, (current) => resetPhiBuilderSelectionToPage(current, pageKey, options));
+}
+/** Points the selection at a Page the catalog opened by itself, leaving the rest of the tool as it is. */
+export function selectPhiBuilderPageNode(pageKey) {
+    builderWorkspaceStore.patch(PHI_WORKSPACE_CATALOG_SCOPE, (current) => ({ ...current, nodeKey: `page:${pageKey}` }));
+}
+function setToolField(key, value) {
+    builderWorkspaceStore.patch(PHI_WORKSPACE_CATALOG_SCOPE, (current) => (Object.is(current[key], value) ? current : { ...current, [key]: value }));
+}
+export function setPhiBuilderCommandWorkspace(commandWorkspace) {
+    setToolField("commandWorkspace", commandWorkspace);
+}
+export function setPhiBuilderMode(builderMode) {
+    setToolField("builderMode", builderMode);
+}
+export function setPhiBuilderDebugScaffold(debugScaffold) {
+    setToolField("debugScaffold", debugScaffold);
+}
+export function openPhiBuilderPagesPanel() {
+    setToolField("pagesOpen", true);
+}
+export function setPhiBuilderInspectorOpen(inspectorOpen) {
+    setToolField("inspectorOpen", inspectorOpen);
+}
+export function setPhiBuilderSelectedLayoutAnchor(anchor) {
+    setToolField("selectedLayoutAnchor", anchor);
+}
+/** A Page's meta as edited, laid over what its draft held. */
+export function setPhiBuilderPageMetaDraft(draftKey, meta) {
+    builderWorkspaceStore.patch(PHI_WORKSPACE_CATALOG_SCOPE, (current) => ({
+        ...current,
+        pageMetaDrafts: {
+            ...current.pageMetaDrafts,
+            [draftKey]: { ...(current.pageMetaDrafts[draftKey] ?? {}), ...meta },
+        },
+    }));
+}
+/** A Page created in the Builder: its meta, and that it is not deleted. */
+export function startPhiBuilderNewPageDrafts(input) {
+    builderWorkspaceStore.patch(PHI_WORKSPACE_CATALOG_SCOPE, (current) => ({
+        ...current,
+        pageMetaDrafts: { ...current.pageMetaDrafts, [input.metaDraftKey]: input.meta },
+        deletedPageDrafts: { ...current.deletedPageDrafts, [input.deleteDraftKey]: false },
+    }));
+}
+/** A Page marked for deletion with the next save. */
+export function markPhiBuilderPageDeleted(deleteDraftKey) {
+    builderWorkspaceStore.patch(PHI_WORKSPACE_CATALOG_SCOPE, (current) => ({
+        ...current,
+        deletedPageDrafts: { ...current.deletedPageDrafts, [deleteDraftKey]: true },
+    }));
+}
+/**
+ * The Areas whose Module selection has unsaved edits, kept as Builder tool state so the Modules
+ * workspace commands know which Areas a site-wide save or publish has to reach. Undo does not clear
+ * an Area from here -- a save of an unchanged selection is a no-op draft, while a missed Area would
+ * silently publish stale state.
+ */
+export function markPhiBuilderModuleAreasDirty(areas) {
+    builderWorkspaceStore.patch(PHI_WORKSPACE_CATALOG_SCOPE, (tool) => {
+        const next = new Set(tool.modulesDirtyAreas ?? []);
+        for (const area of areas)
+            next.add(area);
+        return next.size === (tool.modulesDirtyAreas ?? []).length ? tool : { ...tool, modulesDirtyAreas: [...next] };
+    });
+}
+export function clearPhiBuilderModuleAreasDirty() {
+    builderWorkspaceStore.patch(PHI_WORKSPACE_CATALOG_SCOPE, (tool) => (tool.modulesDirtyAreas?.length ?? 0) === 0 ? tool : { ...tool, modulesDirtyAreas: [] });
+}
+const EMPTY_SIGNAL_WIRING_SESSION = {
+    senderAddress: null,
+    senderCapabilityId: null,
+    receiverAddress: null,
+    receiverCapabilityId: null,
+    fieldKey: null,
+};
+function readWiringValue(value) {
+    return typeof value === "string" && value.trim().length > 0 ? value.trim() : null;
+}
+/** What the wiring dialog has chosen so far; a value that moved drops everything chosen below it. */
+export function patchPhiBuilderSignalWiringSession(values) {
+    builderWorkspaceStore.patch(PHI_WORKSPACE_CATALOG_SCOPE, (current) => {
+        const senderAddress = readWiringValue(values.senderAddress) ?? current.signalWiring.senderAddress;
+        // A cascade only holds if the values below the one that moved are dropped: keeping a capability that
+        // belongs to the previous endpoint would build a route the runtime silently ignores.
+        const senderChanged = senderAddress !== current.signalWiring.senderAddress;
+        const senderCapabilityId = senderChanged
+            ? null
+            : readWiringValue(values.senderCapabilityId) ?? current.signalWiring.senderCapabilityId;
+        const capabilityChanged = senderCapabilityId !== current.signalWiring.senderCapabilityId;
+        const receiverAddress = senderChanged || capabilityChanged
+            ? null
+            : readWiringValue(values.receiverAddress) ?? current.signalWiring.receiverAddress;
+        const receiverChanged = receiverAddress !== current.signalWiring.receiverAddress;
+        return {
+            ...current,
+            signalWiring: {
+                senderAddress,
+                senderCapabilityId,
+                receiverAddress,
+                receiverCapabilityId: senderChanged || capabilityChanged || receiverChanged
+                    ? null
+                    : readWiringValue(values.receiverCapabilityId) ?? current.signalWiring.receiverCapabilityId,
+                // The field belongs to the receiver's input, so it falls with everything above it.
+                fieldKey: senderChanged || capabilityChanged || receiverChanged
+                    ? null
+                    : readWiringValue(values.fieldKey) ?? current.signalWiring.fieldKey,
+            },
+        };
+    });
+}
+export function resetPhiBuilderSignalWiringSession() {
+    builderWorkspaceStore.patch(PHI_WORKSPACE_CATALOG_SCOPE, (current) => ({
+        ...current,
+        signalWiring: { ...EMPTY_SIGNAL_WIRING_SESSION },
+    }));
+}
+/**
+ * What a save or read answered about the Draft a region stands on. A later answer for the same revision
+ * never moves the version or the node sequence back.
+ */
+export function storePhiBuilderDraftAllocation(allocationKey, saved) {
+    builderWorkspaceStore.patch(PHI_WORKSPACE_CATALOG_SCOPE, (current) => {
+        const currentAllocation = current.draftAllocations[allocationKey];
+        const sameRevision = currentAllocation?.revisionId === saved.revisionId;
+        return {
+            ...current,
+            draftAllocations: {
+                ...current.draftAllocations,
+                [allocationKey]: {
+                    revisionId: saved.revisionId,
+                    version: sameRevision ? Math.max(currentAllocation.version, saved.version) : saved.version,
+                    nextNodeSequence: sameRevision
+                        ? Math.max(currentAllocation.nextNodeSequence, saved.nextNodeSequence)
+                        : saved.nextNodeSequence,
+                    sourcePreset: saved.sourcePreset,
+                },
+            },
+        };
+    });
+}
+export function clearPhiBuilderDraftAllocation(allocationKey) {
+    builderWorkspaceStore.patch(PHI_WORKSPACE_CATALOG_SCOPE, (current) => {
+        if (!current.draftAllocations[allocationKey])
+            return current;
+        const draftAllocations = { ...current.draftAllocations };
+        delete draftAllocations[allocationKey];
+        return { ...current, draftAllocations };
+    });
+}
+/** Takes the next node sequence of a Draft, answering the allocation it was taken from. */
+export function takePhiBuilderDraftNodeSequence(allocationKey) {
+    const allocation = builderWorkspaceStore.getSnapshot(PHI_WORKSPACE_CATALOG_SCOPE).draftAllocations[allocationKey];
+    if (!allocation) {
+        throw new Error(`Missing Draft allocation state for "${allocationKey}".`);
+    }
+    builderWorkspaceStore.patch(PHI_WORKSPACE_CATALOG_SCOPE, (current) => ({
+        ...current,
+        draftAllocations: {
+            ...current.draftAllocations,
+            [allocationKey]: { ...allocation, nextNodeSequence: allocation.nextNodeSequence + 1 },
+        },
+    }));
+    return allocation;
+}
+/**
+ * Puts a workspace snapshot back, each field into the store it lives in: the catalog's into the
+ * catalog, the Builder's here. An undo used to patch both stores from the command controller.
+ */
+export function restorePhiBuilderWorkspaceState(state) {
+    const { catalog, tool } = splitWorkspacePatch(state);
+    restorePhiWorkspaceCatalog(catalog);
+    if (Object.keys(tool).length > 0) {
+        builderWorkspaceStore.patch(PHI_WORKSPACE_CATALOG_SCOPE, (current) => ({ ...current, ...tool }));
+    }
 }

package/plugins/runtime-modules/builder/edit-scaffold-drawer.js

@@ -1,12 +1,13 @@
 "use client";
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { usePhiConfig } from "../../../components/root/phi-config-provider";
+import { usePhiPageModeToken } from "../../../components/root/phi-config-provider";
 import { PhiButtonControl } from "../../../components/controls/phi-button-control";
 import { usePhiDeveloperBuilderStateValue } from "./developer-workspace-store";
 import { PhiIcon } from "../../../components/shell/phi-icon";
 export function PhiEditScaffoldDrawer({ kind, nodeId, regionKey, scaffoldLabel, className, onOpenInsert, onClick, onKeyDown, children, chrome, style, }) {
-    const { token } = usePhiConfig();
-    const selected = usePhiDeveloperBuilderStateValue("public", (state) => state.selectedRootRegionKey === regionKey &&
+    // The editor's colours, not a tone's: a scaffold inside a toned Surface marks it in the page's mode.
+    const token = usePhiPageModeToken();
+    const selected = usePhiDeveloperBuilderStateValue((state) => state.selectedRootRegionKey === regionKey &&
         state.nodeId === nodeId &&
         (state.nodeKind === "layout"));
     const isEmpty = children == null;

package/plugins/runtime-modules/builder/history.d.ts

@@ -118,7 +118,9 @@ export declare const phiBuilderHistory: {
     } | null;
 };
 export declare function createPhiBuilderHistoryContext(input: {
-    workspace: PhiBuilderHistoryWorkspace;
+    workspace: "modules";
+} | {
+    workspace: Exclude<PhiBuilderHistoryWorkspace, "modules">;
     area: PhiDeveloperBuilderArea;
     pageKey?: string | null;
     navKey?: string | null;

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

@@ -1,4 +1,5 @@
 "use client";
+import { PHI_WORKSPACE_CATALOG_SCOPE } from "../../../components/workspace/catalog-store";
 import { resolvePhiBuilderAreaAsCmsArea } from "../../../constants/cms-areas";
 import { isPhiRuntimeAreaBaseModuleId, resolvePhiRuntimeAreaDefinition, } from "../../../plugins/runtime-modules/area-definitions";
 import { isPhiCmsErrorPagePath } from "../../../constants/cms-error-pages";
@@ -259,8 +260,8 @@ function resolveAreaRootRouteOptions(context) {
     };
 }
 const builderProviderStore = {
-    subscribe: (listener) => builderWorkspaceStore.subscribe("public", listener),
-    getSnapshot: () => getPhiDeveloperBuilderStateSnapshot("public"),
+    subscribe: (listener) => builderWorkspaceStore.subscribe(PHI_WORKSPACE_CATALOG_SCOPE, listener),
+    getSnapshot: () => getPhiDeveloperBuilderStateSnapshot(),
 };
 /**
  * The renderers on offer for whatever this Collection View is bound to.

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

@@ -1,4 +1,6 @@
 "use client";
+import { isPhiRecord } from "../../../helpers/is-record";
+import { createPhiResponseReader, requirePhiField } from "../../../components/widgets/config/strict-config-reader";
 import { resolvePhiBuilderCatalogApiArea, } from "../../../helpers/cms-page-catalog";
 const persistedPageCatalogRequests = new Map();
 export function loadPhiBuilderPersistedPageCatalog(area, options = {}) {
@@ -41,15 +43,25 @@ export async function changePhiBuilderPagePath(input) {
         credentials: "same-origin",
         body: JSON.stringify({ area: resolvePhiBuilderCatalogApiArea(input.area), path: input.path }),
     });
-    const body = (await response.json().catch(() => null));
-    if (!response.ok || typeof body?.path !== "string") {
-        throw new Error(body?.message ?? body?.error ?? `Page path change failed (${response.status}).`);
+    const body = await response.json().catch(() => null);
+    if (!response.ok) {
+        const failure = isPhiRecord(body) ? body : {};
+        const message = typeof failure.message === "string" ? failure.message : null;
+        const error = typeof failure.error === "string" ? failure.error : null;
+        throw new Error(message ?? error ?? `Page path change failed (${response.status}).`);
     }
+    /*
+     * Read, not cast. The server always counts the references that follow the Page (`references.total`);
+     * a missing count used to read as 0, which told the author nothing would follow a rename that moved
+     * links all over the Site.
+     */
+    const reader = createPhiResponseReader(body, "The Page path change");
+    const pendingPath = reader.record.pendingPath;
     return {
-        pageScopeId: body.pageScopeId ?? input.pageScopeId,
+        pageScopeId: requirePhiField(reader, "pageScopeId", "a whole number", reader.integer),
         /* Still the address the Page answers on: a rename is a pending change until somebody publishes. */
-        path: body.path,
-        pendingPath: typeof body.pendingPath === "string" ? body.pendingPath : null,
-        references: Number.isSafeInteger(body.references?.total) ? body.references.total : 0,
+        path: requirePhiField(reader, "path", "a path", reader.string),
+        pendingPath: pendingPath === null ? null : requirePhiField(reader, "pendingPath", "a path or null", reader.string),
+        references: requirePhiField(reader, "references", "the references that follow the Page", (key) => reader.object(key, (references) => requirePhiField(references, "total", "a whole number", references.integer))),
     };
 }

package/plugins/runtime-modules/builder/page-meta-form.js

@@ -91,6 +91,7 @@ const viewportPropertyOptions = [
 const viewportAxisOptions = [
     labelledOption("x", "viewport.x", "X"),
     labelledOption("y", "viewport.y", "Y"),
+    labelledOption("z", "viewport.z", "Z"),
 ];
 /* px, % and deg are the units themselves; only "no unit" is a word. */
 const viewportUnitOptions = [

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

@@ -7,7 +7,7 @@ import { buildPhiBuilderPageReferenceTree } from "../../../helpers/page-referenc
 import { usePhiDeveloperBuilderStateValue } from "./developer-workspace-store";
 /** Offers the edited Area's Pages to the authoring tools' page picker. */
 export function PhiBuilderPageReferencesProvider({ children }) {
-    const state = usePhiDeveloperBuilderStateValue("public", (value) => value);
+    const state = usePhiDeveloperBuilderStateValue((value) => value);
     const pages = usePhiBuilderOfferedPageCatalog(state, state.area);
     const options = useMemo(() => buildPhiBuilderPageReferenceTree(state.area, pages, pages), [pages, state.area]);
     return _jsx(PhiAuthoringPageReferencesProvider, { options: options, children: children });