@phis/ui 0.4.2 → 0.4.4

package/plugins/runtime-modules/app/presets.js

@@ -0,0 +1,67 @@
+import { PHI_BASE_PAGE_LAYOUT_VERSION } from "../../../components/regions/presets/phi-base-page-layout";
+import { buildPhiAreaRootRoutePresetDescriptor } from "../area-root-route";
+import { PHI_APP_RUNTIME_MODULE_ID } from "./ids";
+/* What the App base Module brings: its Area shell, the Area root and the profile Page. */
+export const PHI_APP_RUNTIME_MODULE_AREA_SHELLS = [
+    {
+        ownerModuleId: PHI_APP_RUNTIME_MODULE_ID,
+        presetKey: "app-area-preset",
+        shellPresetVersion: 1,
+        area: "app",
+        /*
+         * The Site shell with a left sider added, rather than a shell of its own.
+         *
+         * App's header and footer are Public's -- one Brand, one account trigger, one description of both.
+         * What App has that Public does not is somewhere for the Modules a signed-in person works with,
+         * and that is the whole of the overlay. Nothing is omitted from the base, so the two trees cannot
+         * disagree about a Region: composition refuses a Region type stated twice.
+         */
+        loadTree: async ({ page, runtime }) => {
+            const [{ buildPhiDefaultSiteAreaPresetTree }, { buildPhiDefaultAppAreaPresetTree }, { mergePhiCmsShellTrees },] = await Promise.all([
+                import("../phi-default-site-area-preset-tree"),
+                import("./trees/phi-default-app-area-preset-tree"),
+                import("../shell-tree-composition"),
+            ]);
+            const [base, overlay] = await Promise.all([
+                buildPhiDefaultSiteAreaPresetTree({
+                    page,
+                    runtime,
+                    presetKey: "app-area-preset",
+                    ownerModuleId: PHI_APP_RUNTIME_MODULE_ID,
+                    runtimeModuleArea: "app",
+                }),
+                buildPhiDefaultAppAreaPresetTree({ page, runtime }),
+            ]);
+            return mergePhiCmsShellTrees(base, overlay);
+        },
+    },
+];
+export const PHI_APP_RUNTIME_MODULE_ROUTES = [
+    buildPhiAreaRootRoutePresetDescriptor({
+        ownerModuleId: PHI_APP_RUNTIME_MODULE_ID,
+        area: "app",
+        title: "App",
+    }),
+    /*
+     * What a person has settled about their own account: their name, the language they read in.
+     *
+     * It sat with the Auth Module, which owned the route while Core owned every Widget on it. Nothing
+     * about a name or a language depends on how somebody signs in -- a Site that switches to a
+     * directory, or switches Auth off while sessions keep working, would have lost the Page that says
+     * what they are called. AUTHENTICATION.md section 5 already said so: profile administration does
+     * not become Auth's merely by appearing in its menu.
+     *
+     * The Area's own Settings child, so it is declared here rather than injected -- SETTINGS.md section
+     * 5, the same standing Admin and Builder give their General page.
+     */
+    {
+        ownerModuleId: PHI_APP_RUNTIME_MODULE_ID,
+        presetKey: "app-profile-page",
+        presetVersion: 1 + PHI_BASE_PAGE_LAYOUT_VERSION,
+        area: "app",
+        title: "Profile",
+        path: "/settings/profile",
+        loadTree: ({ page, runtime }) => import("./trees/phi-default-app-profile-page-tree")
+            .then((module) => module.buildPhiDefaultAppProfilePageTree({ page, runtime })),
+    },
+];

package/plugins/runtime-modules/app/server.d.ts

@@ -1,5 +1,2 @@
-/**
- * The unselectable base module of its Area. Shells and routes come from the shared Area-base preset
- * list and are filtered by owner, so each base module states its own half of it.
- */
+/** The unselectable base module of its Area. Its shell and Pages are its own (`./presets`). */
 export declare const PHI_APP_RUNTIME_MODULE_SERVER_AREA_CONTRIBUTION: import("../area-contributions").PhiRuntimeModuleServerAreaContribution;

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

@@ -1,11 +1,8 @@
-import { PHI_AREA_BASE_RUNTIME_MODULE_AREA_SHELLS, PHI_AREA_BASE_RUNTIME_MODULE_ROUTES, } from "../area-base-presets";
+import { PHI_APP_RUNTIME_MODULE_AREA_SHELLS, PHI_APP_RUNTIME_MODULE_ROUTES, } from "./presets";
 import { definePhiRuntimeModuleServerAreaContribution } from "../area-contributions";
 import { PHI_APP_RUNTIME_MODULE_DEFINITION } from "../app/definition";
 import { PHI_APP_RUNTIME_MODULE_FORMS } from "./forms";
-/**
- * The unselectable base module of its Area. Shells and routes come from the shared Area-base preset
- * list and are filtered by owner, so each base module states its own half of it.
- */
+/** The unselectable base module of its Area. Its shell and Pages are its own (`./presets`). */
 export const PHI_APP_RUNTIME_MODULE_SERVER_AREA_CONTRIBUTION = definePhiRuntimeModuleServerAreaContribution({
     moduleId: PHI_APP_RUNTIME_MODULE_DEFINITION.moduleId,
     catalogEntry: {
@@ -13,8 +10,8 @@ export const PHI_APP_RUNTIME_MODULE_SERVER_AREA_CONTRIBUTION = definePhiRuntimeM
         widgets: [],
         forms: PHI_APP_RUNTIME_MODULE_FORMS,
         layouts: [],
-        areaShells: PHI_AREA_BASE_RUNTIME_MODULE_AREA_SHELLS.filter((descriptor) => descriptor.ownerModuleId === PHI_APP_RUNTIME_MODULE_DEFINITION.moduleId),
-        routes: PHI_AREA_BASE_RUNTIME_MODULE_ROUTES.filter((descriptor) => descriptor.ownerModuleId === PHI_APP_RUNTIME_MODULE_DEFINITION.moduleId),
+        areaShells: PHI_APP_RUNTIME_MODULE_AREA_SHELLS,
+        routes: PHI_APP_RUNTIME_MODULE_ROUTES,
         load: () => import("./module").then((module) => module.PHI_APP_RUNTIME_MODULE),
     },
 });

package/plugins/runtime-modules/area-definitions.d.ts

@@ -34,20 +34,6 @@ export declare const PHI_PUBLIC_RUNTIME_AREA_DEFINITIONS: {
             readonly routePresetKey: "public-terms-page";
         }];
         readonly exportedItemKeys: readonly ["@phis/ui/modules/public/nav/terms"];
-    }, {
-        readonly navKey: "public:quicklinks";
-        readonly label: {
-            defaultMessage: string;
-        };
-        readonly items: readonly [{
-            readonly itemKey: "@phis/ui/modules/public/nav/terms";
-            readonly label: {
-                defaultMessage: string;
-            };
-            readonly icon: "antd:file-text";
-            readonly routePresetKey: "public-terms-page";
-        }];
-        readonly exportedItemKeys: readonly ["@phis/ui/modules/public/nav/terms"];
     }, PhiCmsNavigationSurfaceDescriptor];
 }[];
 export declare const PHI_APP_ACCOUNT_NAV_ITEM_KEY = "@phis/ui/modules/app/nav/account";
@@ -226,20 +212,6 @@ export declare const PHI_ALL_RUNTIME_AREA_DEFINITIONS: ({
             readonly routePresetKey: "public-terms-page";
         }];
         readonly exportedItemKeys: readonly ["@phis/ui/modules/public/nav/terms"];
-    }, {
-        readonly navKey: "public:quicklinks";
-        readonly label: {
-            defaultMessage: string;
-        };
-        readonly items: readonly [{
-            readonly itemKey: "@phis/ui/modules/public/nav/terms";
-            readonly label: {
-                defaultMessage: string;
-            };
-            readonly icon: "antd:file-text";
-            readonly routePresetKey: "public-terms-page";
-        }];
-        readonly exportedItemKeys: readonly ["@phis/ui/modules/public/nav/terms"];
     }, PhiCmsNavigationSurfaceDescriptor];
 } | {
     area: "app";
@@ -457,20 +429,6 @@ export declare function resolvePhiRuntimeAreaDefinition(area: PhiCmsAreaDefiniti
             readonly routePresetKey: "public-terms-page";
         }];
         readonly exportedItemKeys: readonly ["@phis/ui/modules/public/nav/terms"];
-    }, {
-        readonly navKey: "public:quicklinks";
-        readonly label: {
-            defaultMessage: string;
-        };
-        readonly items: readonly [{
-            readonly itemKey: "@phis/ui/modules/public/nav/terms";
-            readonly label: {
-                defaultMessage: string;
-            };
-            readonly icon: "antd:file-text";
-            readonly routePresetKey: "public-terms-page";
-        }];
-        readonly exportedItemKeys: readonly ["@phis/ui/modules/public/nav/terms"];
     }, PhiCmsNavigationSurfaceDescriptor];
 } | {
     area: "app";

package/plugins/runtime-modules/area-definitions.js

@@ -116,8 +116,9 @@ function sidebarAnchors(settingsItemKey) {
  * The Public surfaces carry one intrinsic entry, the terms, and export it as the one anchor.
  *
  * The terms are Core's, so their entry is; the contact entry hangs after it, and a Site package's
- * landing places its Home entry before it. Public has no sidebar surface: the Public Shell draws a
- * header and a footer, and a surface nothing renders is a promise nobody can see kept.
+ * landing places its Home entry before it. Public has no sidebar and no quick-links surface: the Public
+ * Shell draws a header and a footer -- the footer's Quick Links Widget reads `public:footer` -- and a
+ * surface nothing renders is a promise nobody can see kept.
  */
 const publicTermsItem = {
     itemKey: "@phis/ui/modules/public/nav/terms",
@@ -138,12 +139,6 @@ const publicNavigationSurfaces = [
         items: [publicTermsItem],
         exportedItemKeys: [publicTermsItem.itemKey],
     },
-    {
-        navKey: "public:quicklinks",
-        label: label("Public quick links"),
-        items: [publicTermsItem],
-        exportedItemKeys: [publicTermsItem.itemKey],
-    },
     accountNavigationSurface(PHI_PUBLIC_ACCOUNT_NAV_ITEM_KEY, "public:account"),
 ];
 export const PHI_PUBLIC_RUNTIME_AREA_DEFINITIONS = [

package/plugins/runtime-modules/asset/controller/runtime.js

@@ -271,11 +271,11 @@ export function usePhiAssetRuntimeController({ address, mountScope, config, }) {
             value: {
                 page: state.page,
                 pageSize: state.pageSize,
-                total: state.pagination?.total ?? state.assets.length,
+                total: state.pagination?.total ?? 0,
             },
             receiver: "broadcast",
             timestamp: Date.now(),
         });
-    }, [emitAssetSignal, mountScope, state.assets.length, state.page, state.pageSize, state.pagination?.total]);
+    }, [emitAssetSignal, mountScope, state.page, state.pageSize, state.pagination?.total]);
     return state;
 }

package/plugins/runtime-modules/asset/services/collection.js

@@ -62,10 +62,18 @@ async function queryMediaCollection(request) {
             signal: request.signal,
         });
         const payload = await readPhiImagePreviewResponse(response);
+        /*
+         * The server counts the listing on every read (`pagination.total`), and the paging below is drawn
+         * from it. Without it the count is unknown, which the assets of one page would only pretend to answer.
+         */
+        const total = payload.pagination?.total;
+        if (typeof total !== "number" || !Number.isFinite(total) || total < 0) {
+            throw new Error("The media listing answered no total.");
+        }
         return {
             resourceKey: request.resourceKey,
             items: payload.assets.map((asset) => ({ ...asset })),
-            total: payload.pagination?.total ?? payload.assets.length,
+            total,
             loading: false,
             error: null,
             meta: {

package/plugins/runtime-modules/asset/services/options.js

@@ -2,6 +2,7 @@
 import { isPhiRecord } from "../../../../helpers/is-record";
 import { createPhiControlOptionsProviderClient, } from "../../../../components/controls/phi-options-provider";
 import { PHI_ASSET_RUNTIME_DATA_PROVIDER_KEYS } from "../ids";
+import { readPhiMediaFolders } from "../../../../components/media/phi-image-preview-data";
 import { PHI_ASSET_CONTROLLER_STORE_KEY } from "../../../../components/media/asset-controller-signals";
 import { phiImagePreviewStore } from "../../../../components/media/phi-image-preview-store";
 import { buildPhiMediaFolderCascaderOptions, buildPhiMediaFolderNamesById, buildPhiMediaFolderValueById, } from "../../../../components/media/media-folder-options";
@@ -59,8 +60,7 @@ async function loadFolders() {
     const payload = await response.json().catch(() => null);
     if (!response.ok)
         throw new Error("Failed to load the Site's media folders.");
-    const folders = isPhiRecord(payload) && Array.isArray(payload.folders) ? payload.folders : [];
-    return folders.filter(isPhiRecord);
+    return readPhiMediaFolders(isPhiRecord(payload) ? payload.folders : undefined, "The media folders route");
 }
 export const PhiMediaFolderChoicesOptionsProviderClient = createPhiControlOptionsProviderClient({
     key: PHI_ASSET_RUNTIME_DATA_PROVIDER_KEYS.mediaFolderChoices,

package/plugins/runtime-modules/builder/area-settings-answer.js

@@ -1,3 +1,4 @@
+import { PHI_WORKSPACE_CATALOG_SCOPE } from "../../../components/workspace/catalog-store";
 import { PHI_AREA_META_PUBLIC_DEFAULTS, } from "../../../helpers/cms-area-config";
 import { isPhiRecord } from "../../../helpers/is-record";
 import { builderWorkspaceStore, readPhiBuilderEffectiveAreaMeta, readPhiBuilderEffectiveAreaRootRoute, restorePhiDeveloperBuilderAreaMeta, setPhiDeveloperBuilderAreaRootRoute, } from "./developer-workspace-store";
@@ -54,7 +55,7 @@ function isSamePhiBuilderAreaAnswer(left, right) {
  * unsaved. `rootRoute` is `undefined` when the dialog did not ask it.
  */
 export function applyPhiBuilderAreaSettingsAnswer({ area, historyContext, rootRoute, meta, }) {
-    const current = builderWorkspaceStore.getSnapshot("public");
+    const current = builderWorkspaceStore.getSnapshot(PHI_WORKSPACE_CATALOG_SCOPE);
     const before = [];
     const after = [];
     if (rootRoute !== undefined && !isSamePhiBuilderAreaAnswer(readPhiBuilderEffectiveAreaRootRoute(current, area), rootRoute)) {

package/plugins/runtime-modules/builder/authoring-canvas.js

@@ -13,12 +13,12 @@ import { getPhiBuilderNavigationDraftSnapshot } from "./navigation-store";
  * learn which Area they are being edited in.
  */
 export function usePhiBuilderAuthoringCanvas() {
-    const area = usePhiDeveloperBuilderStateValue("public", (state) => state.area);
-    const catalogHydrated = usePhiDeveloperBuilderStateValue("public", (state) => state.catalogHydrated);
-    const navigationSurfaces = usePhiDeveloperBuilderStateValue("public", (state) => state.navigationSurfacesByArea[state.area] ?? null);
-    const modulePresetPagesByArea = usePhiDeveloperBuilderStateValue("public", (state) => state.modulePresetPagesByArea);
-    const customPages = usePhiDeveloperBuilderStateValue("public", (state) => state.customPages);
-    const persistedPageCatalogByArea = usePhiDeveloperBuilderStateValue("public", (state) => state.persistedPageCatalogByArea);
+    const area = usePhiDeveloperBuilderStateValue((state) => state.area);
+    const catalogHydrated = usePhiDeveloperBuilderStateValue((state) => state.catalogHydrated);
+    const navigationSurfaces = usePhiDeveloperBuilderStateValue((state) => state.navigationSurfacesByArea[state.area] ?? null);
+    const modulePresetPagesByArea = usePhiDeveloperBuilderStateValue((state) => state.modulePresetPagesByArea);
+    const customPages = usePhiDeveloperBuilderStateValue((state) => state.customPages);
+    const persistedPageCatalogByArea = usePhiDeveloperBuilderStateValue((state) => state.persistedPageCatalogByArea);
     return useMemo(() => ({
         area,
         catalogHydrated,

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

@@ -2,7 +2,6 @@ import "server-only";
 import { PHI_TR_CTX_WEB_UI_LABEL } from "../../../gateway/tr";
 import { definePhiRuntimeModuleLabelSet, getPhiLabelSet } from "../../../gateway/label-set";
 import { getPhiBuilderModulesPageLabels } from "../../../components/widgets/label-sets/builder-modules";
-import { PHI_FIRST_PARTY_RUNTIME_MODULE_CATALOG } from "../catalog";
 import { createPhiDashboardCardId, } from "../../../types/dashboard-cards";
 import { readPhiBuilderAreasWithOpenDraft } from "./area-shell-presets.server";
 import { PHI_BUILDER_RUNTIME_MODULE_ID, PHI_BUILDER_RUNTIME_MODULE_IDENTITY } from "./ids";
@@ -12,9 +11,8 @@ import { PHI_BUILDER_RUNTIME_MODULE_ID, PHI_BUILDER_RUNTIME_MODULE_IDENTITY } fr
  * The first `list` card. A structure author opening the Builder wants to know where they left off,
  * which is a set of names rather than a count -- "Public and App" says where to go, "2" does not.
  *
- * The Area shells are read from the first-party catalog. A provider is handed no catalog, and every
- * Area's shell is contributed by its first-party base Module, so the Builder's catalog and this one name
- * the same shell sources; a Site's own Modules add Pages, not Areas.
+ * The Area shells are read from the catalog of the Area the Dashboard stands in -- the Builder's, which
+ * carries every Area's base Module, because the Builder edits them all.
  */
 const PHI_BUILDER_DASHBOARD_CARD_LABEL_SET = definePhiRuntimeModuleLabelSet(PHI_BUILDER_RUNTIME_MODULE_IDENTITY, {
     key: "cards:builder-drafts",
@@ -59,7 +57,7 @@ export const PHI_BUILDER_RUNTIME_MODULE_DASHBOARD_CARDS = {
         const [labels, areaLabels, drafted] = await Promise.all([
             getPhiLabelSet(options, PHI_BUILDER_DASHBOARD_CARD_LABEL_SET),
             getPhiBuilderModulesPageLabels(options).then((page) => page.areas),
-            readPhiBuilderAreasWithOpenDraft(PHI_FIRST_PARTY_RUNTIME_MODULE_CATALOG, {
+            readPhiBuilderAreasWithOpenDraft(context.runtimeModuleCatalog, {
                 siteKey: context.siteKey,
                 locale: context.locale,
                 apiBaseUrl: context.apiBaseUrl,

package/plugins/runtime-modules/builder/clients/builder-region-overrides.js

@@ -8,9 +8,9 @@ import { PhiAuthoringRegionOverridesProvider } from "../../../../components/runt
 import { getDefaultRegionDraft, resolveRegionDraftKey } from "../developer-region-drafts";
 import { usePhiDeveloperBuilderStateValue, usePhiDeveloperRegionDrafts } from "../developer-workspace-store";
 export function PhiBuilderCanvasRegionOverrides({ children }) {
-    const builderMode = usePhiDeveloperBuilderStateValue("public", (state) => state.builderMode);
-    const area = usePhiDeveloperBuilderStateValue("public", (state) => state.area);
-    const pageKey = usePhiDeveloperBuilderStateValue("public", (state) => state.pageKey);
+    const builderMode = usePhiDeveloperBuilderStateValue((state) => state.builderMode);
+    const area = usePhiDeveloperBuilderStateValue((state) => state.area);
+    const pageKey = usePhiDeveloperBuilderStateValue((state) => state.pageKey);
     const regionDrafts = usePhiDeveloperRegionDrafts();
     const value = useMemo(() => {
         const siderRight = resolveRegionDraftKey(regionDrafts, area, "sider_right", pageKey) ?? getDefaultRegionDraft("sider_right");

package/plugins/runtime-modules/builder/clients/canvas-widget.js

@@ -1,75 +1,36 @@
 "use client";
 import { jsx as _jsx } from "react/jsx-runtime";
-import { useCallback, useEffect, useMemo } from "react";
+import { useMemo } from "react";
 import { PhiDeveloperBuilderStructureCanvas, } from "./structure-canvas";
-import { getPhiDeveloperRegionDraftsSnapshot, mergePhiDeveloperRegionDrafts, usePhiDeveloperBuilderStateValue, usePhiDeveloperRegionDraftsValue, } from "../developer-workspace-store";
+import { usePhiDeveloperBuilderStateValue } from "../developer-workspace-store";
+import { usePhiBuilderRegionDraftHydration } from "./use-region-draft-hydration";
 import { getPhiBuilderRegionDraftKey, PHI_BUILDER_PAGE_REGION_KEYS, PHI_BUILDER_SHELL_REGION_KEYS, } from "../region-keys";
 import { usePhiBuilderModuleMetas } from "../plugin-meta-store";
 import { buildPhiStructureRegionPickItems } from "../structure-region-pick-items";
 export function PhiDeveloperBuilderCanvasWidgetClient({ workspace, serverPreviewRegions, structureShellDraftsByArea, pageDraftsByScope, previewRegionDrafts = null, shellTheme, disabled: _disabled = false, targetArea, regionLabels, pickerLabels, }) {
     void _disabled;
-    const area = usePhiDeveloperBuilderStateValue("public", (state) => state.area);
-    const pageKey = usePhiDeveloperBuilderStateValue("public", (state) => state.pageKey);
-    const builderMode = usePhiDeveloperBuilderStateValue("public", (state) => state.builderMode);
+    const area = usePhiDeveloperBuilderStateValue((state) => state.area);
+    const pageKey = usePhiDeveloperBuilderStateValue((state) => state.pageKey);
+    const builderMode = usePhiDeveloperBuilderStateValue((state) => state.builderMode);
     const builderModuleMetas = usePhiBuilderModuleMetas(targetArea);
     const pickItems = useMemo(() => buildPhiStructureRegionPickItems(builderModuleMetas.plugins), [builderModuleMetas.plugins]);
     const isStructureWorkspace = workspace === "structure";
     const isPagesWorkspace = workspace === "pages";
-    /*
-     * Which of this workspace's drafts are not in the store, as one string. The Canvas used to subscribe
-     * to the whole draft map for this question, so every write to any draft re-rendered it and, below it,
-     * every Region scaffold on the canvas with its whole tree. The Regions read their own draft now
-     * (`structure-canvas.tsx`); this widget renders when the set of missing drafts changes and not before.
-     */
     const hydrationDraftKeys = useMemo(() => (isStructureWorkspace
         ? PHI_BUILDER_SHELL_REGION_KEYS.map((regionKey) => getPhiBuilderRegionDraftKey(area, regionKey, pageKey))
         : isPagesWorkspace
             ? PHI_BUILDER_PAGE_REGION_KEYS.map((regionKey) => getPhiBuilderRegionDraftKey(area, regionKey, pageKey))
             : []), [area, isPagesWorkspace, isStructureWorkspace, pageKey]);
-    const missingDraftKeys = usePhiDeveloperRegionDraftsValue(useCallback((drafts) => hydrationDraftKeys.filter((draftKey) => drafts[draftKey] == null).join("\u0000"), [hydrationDraftKeys]));
-    useEffect(() => {
-        if (!isStructureWorkspace && !isPagesWorkspace) {
-            return;
-        }
-        if (builderMode === "preview" && previewRegionDrafts && Object.keys(previewRegionDrafts).length > 0) {
-            mergePhiDeveloperRegionDrafts(previewRegionDrafts);
-        }
-        const regionDrafts = getPhiDeveloperRegionDraftsSnapshot();
-        const shellDraftKeys = PHI_BUILDER_SHELL_REGION_KEYS
-            .map((regionKey) => getPhiBuilderRegionDraftKey(area, regionKey, pageKey));
-        const pageDraftKeys = PHI_BUILDER_PAGE_REGION_KEYS
-            .map((regionKey) => getPhiBuilderRegionDraftKey(area, regionKey, pageKey));
-        const needsShellHydration = isStructureWorkspace && shellDraftKeys.some((draftKey) => regionDrafts[draftKey] == null);
-        const needsPageHydration = isPagesWorkspace &&
-            pageDraftKeys.some((draftKey) => regionDrafts[draftKey] == null);
-        if (needsShellHydration) {
-            const nextShellDrafts = structureShellDraftsByArea?.[area] ?? {};
-            const missingShellDrafts = Object.fromEntries(Object.entries(nextShellDrafts).filter(([draftKey]) => regionDrafts[draftKey] == null));
-            if (Object.keys(missingShellDrafts).length > 0) {
-                mergePhiDeveloperRegionDrafts(missingShellDrafts);
-            }
-        }
-        if (!needsPageHydration) {
-            return;
-        }
-        const nextPageDrafts = pageDraftsByScope?.[area]?.[pageKey] ?? {};
-        const missingPageDrafts = Object.fromEntries(Object.entries(nextPageDrafts).filter(([draftKey]) => regionDrafts[draftKey] == null));
-        if (Object.keys(missingPageDrafts).length > 0) {
-            mergePhiDeveloperRegionDrafts(missingPageDrafts);
-            return;
-        }
-        // `missingDraftKeys` is the reason to run again; the snapshot inside is what is read.
-    }, [
-        isPagesWorkspace,
-        isStructureWorkspace,
-        missingDraftKeys,
-        pageDraftsByScope,
-        previewRegionDrafts,
-        area,
+    usePhiBuilderRegionDraftHydration({
+        draftKeys: hydrationDraftKeys,
+        serverDrafts: isStructureWorkspace
+            ? structureShellDraftsByArea?.[area]
+            : isPagesWorkspace
+                ? pageDraftsByScope?.[area]?.[pageKey] ?? undefined
+                : undefined,
         builderMode,
-        pageKey,
-        structureShellDraftsByArea,
-    ]);
+        previewRegionDrafts: isStructureWorkspace || isPagesWorkspace ? previewRegionDrafts : null,
+    });
     if (isStructureWorkspace) {
         return (_jsx(PhiDeveloperBuilderStructureCanvas, { workspace: "structure", builderMode: builderMode, area: area, pageKey: pageKey, shellTheme: shellTheme, pageDraftsByScope: pageDraftsByScope, serverPreviewRegions: serverPreviewRegions, pickItems: pickItems, regionLabels: regionLabels, pickerLabels: pickerLabels }));
     }

package/plugins/runtime-modules/builder/clients/inspector-config-field.d.ts

@@ -1,4 +1,5 @@
 import { type ReactNode } from "react";
+import type { PhiBackgroundControlProps } from "../../../../components/controls/phi-background-control";
 import type { PhiCmsConfigField, PhiRuntimeModuleDataProviderDescriptor } from "../../../../types/cms-plugins";
 import type { PhiCalendarAdapterDescriptor } from "../../../../types/calendar";
 import type { PhiVideoProviderDescriptor } from "../../../../types/video";
@@ -69,7 +70,7 @@ export declare function renderPhiInspectorPaddingConfigControl({ field, config,
     onChange?: (nextPadding: PhiCmsPaddingWidgetConfig | null, patch: Record<string, unknown>) => void;
 }): import("react").JSX.Element;
 export declare function renderPhiInspectorConfigField(args: Parameters<typeof renderPhiInspectorConfigFieldBody>[0]): import("react").JSX.Element | null;
-declare function renderPhiInspectorConfigFieldBody({ field, value, defaultValue, config, defaultConfig, disabled, onChange, widgetReferenceOptions, paddingLabels, backgroundLabels, borderLabels, colorPickerLabels, iconPickerLabels, fieldLabels, dataProviderDescriptors, calendarAdapterDescriptors, videoProviderDescriptors, blockId, }: {
+declare function renderPhiInspectorConfigFieldBody({ field, value, defaultValue, config, defaultConfig, disabled, onChange, widgetReferenceOptions, paddingLabels, backgroundLabels, borderLabels, renderMediaPicker, colorPickerLabels, iconPickerLabels, fieldLabels, dataProviderDescriptors, calendarAdapterDescriptors, videoProviderDescriptors, blockId, }: {
     field: PhiCmsConfigField;
     value: unknown;
     defaultValue: unknown;
@@ -82,6 +83,8 @@ declare function renderPhiInspectorConfigFieldBody({ field, value, defaultValue,
     paddingLabels?: PhiPaddingWidgetLabels;
     backgroundLabels?: PhiBackgroundWidgetLabels;
     borderLabels?: PhiBorderWidgetLabels;
+    /** The Media library's picker, so a Surface field can take a background image like a block's own. */
+    renderMediaPicker?: PhiBackgroundControlProps["renderMediaPicker"];
     colorPickerLabels?: PhiColorPickerLabels;
     iconPickerLabels?: PhiIconPickerControlLabels;
     /** The Inspector's own words in its field controls, from the `widget:inspector` label set. */

package/plugins/runtime-modules/builder/clients/inspector-config-field.js

@@ -7,8 +7,6 @@ import { PhiDividerControl } from "../../../../components/controls/phi-divider-c
 import { usePhiConfig } from "../../../../components/root/phi-config-provider";
 import { readPhiLengthValue } from "../../../../types";
 import { normalizePhiPaddingWidgetConfig, } from "../../../../types/cms-config";
-import { PhiBackgroundControl } from "../../../../components/controls/phi-background-control";
-import { PhiBorderControl } from "../../../../components/controls/phi-border-control";
 import { PhiColorFieldControl } from "../../../../components/controls/phi-color-field-control";
 import { PhiInspectorLinkTargetFieldControl, } from "./inspector-link-target-field";
 import { PhiInspectorImageFieldControl } from "./inspector-image-field";
@@ -30,10 +28,8 @@ import { PhiDialogControl } from "../../../../components/controls/phi-dialog-con
 import { PhiIcon } from "../../../../components/shell/phi-icon";
 import { PhiPaddingControl } from "../../../../components/controls/phi-padding-control";
 import { PHI_INSPECTOR_FIELD_LABEL_WIDTH, PhiInspectorFieldRow } from "../../../../components/widgets/inspector-field-row";
-import { PhiShadowControl } from "../../../../components/controls/phi-shadow-control";
 import { PhiSurfaceControl } from "../../../../components/controls/phi-surface-control";
 import { readPhiSurface } from "../../../../types/surface";
-import { readPhiShadow } from "../../../../types/layout-style";
 import { readInspectorChoiceMultiValue, readInspectorChoiceSingleValue, } from "./inspector-choice-values";
 import { PhiFlexControl } from "../../../../components/controls/phi-flex-control";
 import { PhiTypographyControl } from "../../../../components/controls/phi-typography-control";
@@ -248,12 +244,6 @@ function resolveInspectorColorMode(mode) {
     }
     return "single";
 }
-function normalizeInspectorBorderValue(value) {
-    if (!isPhiRecord(value)) {
-        return null;
-    }
-    return value;
-}
 function readPhiInspectorCollectionItems(value) {
     return Array.isArray(value)
         ? value.filter(isPhiRecord)
@@ -377,7 +367,7 @@ function PhiInspectorChoiceFieldControl({ field, config, value, defaultValue, di
             });
         } }));
 }
-function PhiInspectorCollectionFieldControl({ field, config, labels, value, defaultValue, disabled, widgetReferenceOptions, paddingLabels, backgroundLabels, borderLabels, colorPickerLabels, iconPickerLabels, dataProviderDescriptors, calendarAdapterDescriptors, videoProviderDescriptors, onChange, }) {
+function PhiInspectorCollectionFieldControl({ field, config, labels, value, defaultValue, disabled, widgetReferenceOptions, paddingLabels, backgroundLabels, borderLabels, renderMediaPicker, colorPickerLabels, iconPickerLabels, dataProviderDescriptors, calendarAdapterDescriptors, videoProviderDescriptors, onChange, }) {
     const { token } = usePhiConfig();
     const popup = usePhiWidgetScaffoldPopup();
     const [overlayOpen, setOverlayOpen] = useState(false);
@@ -440,6 +430,7 @@ function PhiInspectorCollectionFieldControl({ field, config, labels, value, defa
                     paddingLabels,
                     backgroundLabels,
                     borderLabels,
+                    renderMediaPicker,
                     colorPickerLabels,
                     iconPickerLabels,
                     fieldLabels: labels,
@@ -521,7 +512,7 @@ export function renderPhiInspectorConfigField(args) {
         return body;
     return (_jsxs(Fragment, { children: [_jsx(PhiDividerControl, { titlePlacement: "start", style: { marginBlock: 0 }, children: args.field.heading }), body] }, args.field.key));
 }
-function renderPhiInspectorConfigFieldBody({ field, value, defaultValue, config, defaultConfig, disabled, onChange, widgetReferenceOptions, paddingLabels, backgroundLabels, borderLabels, colorPickerLabels, iconPickerLabels, fieldLabels = PHI_INSPECTOR_WIDGET_DEFAULT_LABELS.fields, dataProviderDescriptors = [], calendarAdapterDescriptors = [], videoProviderDescriptors = [], blockId, }) {
+function renderPhiInspectorConfigFieldBody({ field, value, defaultValue, config, defaultConfig, disabled, onChange, widgetReferenceOptions, paddingLabels, backgroundLabels, borderLabels, renderMediaPicker, colorPickerLabels, iconPickerLabels, fieldLabels = PHI_INSPECTOR_WIDGET_DEFAULT_LABELS.fields, dataProviderDescriptors = [], calendarAdapterDescriptors = [], videoProviderDescriptors = [], blockId, }) {
     if (field.type === "readonly") {
         const displayValue = value ?? defaultValue;
         return renderPhiInspectorConfigFieldControl(field, _jsx(PhiTextControl, { value: displayValue == null ? "" : String(displayValue), readOnly: true, allowClear: false, style: { width: "100%" } }));
@@ -720,35 +711,15 @@ function renderPhiInspectorConfigFieldBody({ field, value, defaultValue, config,
         return (_jsx(PhiInspectorChoiceFieldControl, { field: field, config: config, value: value, defaultValue: defaultValue, disabled: disabled || !onChange, widgetReferenceOptions: widgetReferenceOptions ?? [], labels: fieldLabels, onChange: onChange }, field.key));
     }
     if (field.type === "collection") {
-        return (_jsx(PhiInspectorCollectionFieldControl, { field: field, config: config, labels: fieldLabels, value: value, defaultValue: defaultValue, disabled: disabled || !onChange, widgetReferenceOptions: widgetReferenceOptions ?? [], paddingLabels: paddingLabels, backgroundLabels: backgroundLabels, borderLabels: borderLabels, colorPickerLabels: colorPickerLabels, iconPickerLabels: iconPickerLabels, dataProviderDescriptors: dataProviderDescriptors, calendarAdapterDescriptors: calendarAdapterDescriptors, videoProviderDescriptors: videoProviderDescriptors, onChange: onChange }, field.key));
+        return (_jsx(PhiInspectorCollectionFieldControl, { field: field, config: config, labels: fieldLabels, value: value, defaultValue: defaultValue, disabled: disabled || !onChange, widgetReferenceOptions: widgetReferenceOptions ?? [], paddingLabels: paddingLabels, backgroundLabels: backgroundLabels, borderLabels: borderLabels, renderMediaPicker: renderMediaPicker, colorPickerLabels: colorPickerLabels, iconPickerLabels: iconPickerLabels, dataProviderDescriptors: dataProviderDescriptors, calendarAdapterDescriptors: calendarAdapterDescriptors, videoProviderDescriptors: videoProviderDescriptors, onChange: onChange }, field.key));
     }
     if (field.type === "color") {
         return renderPhiInspectorConfigFieldControl(field, _jsx(PhiColorFieldControl, { value: value, defaultValue: defaultValue, ...(field.defaultToken ? { defaultToken: field.defaultToken } : {}), disabled: disabled || !onChange, mode: resolveInspectorColorMode(field.mode), placement: "left", labels: colorPickerLabels, onChange: (nextValue) => onChange?.({ [field.key]: nextValue || undefined }) }));
     }
-    if (field.type === "background") {
-        const usesSelfStorage = field.storage === "self";
-        const currentValue = (usesSelfStorage ? config : value);
-        const currentDefaultValue = (usesSelfStorage ? defaultConfig : defaultValue);
-        return renderPhiInspectorConfigFieldControl(field, _jsx(PhiBackgroundControl, { mode: "control", disabled: disabled || !onChange, value: currentValue ?? null, config: currentDefaultValue ?? null, labels: backgroundLabels, colorPickerLabels: colorPickerLabels, colorPickerPlacement: "left", onChange: (nextValue) => usesSelfStorage
-                ? onChange?.(nextValue)
-                : onChange?.({ [field.key]: nextValue }) }));
-    }
-    if (field.type === "border") {
-        const usesSelfStorage = field.storage === "self";
-        const currentValue = normalizeInspectorBorderValue(usesSelfStorage ? config : value);
-        const currentDefaultValue = normalizeInspectorBorderValue(usesSelfStorage ? defaultConfig : defaultValue);
-        return renderPhiInspectorConfigFieldControl(field, _jsx(PhiBorderControl, { mode: "control", disabled: disabled || !onChange, value: currentValue, config: currentDefaultValue, labels: borderLabels, colorPickerLabels: colorPickerLabels, colorPickerPlacement: "left", onChange: (nextValue) => usesSelfStorage
-                ? onChange?.(nextValue)
-                : onChange?.({ [field.key]: nextValue }) }));
-    }
     if (field.type === "surface") {
         return renderPhiInspectorConfigFieldBlock(field, _jsx(PhiSurfaceControl, { disabled: disabled || !onChange, value: value === null ? null : readPhiSurface(value) ?? readPhiSurface(defaultValue), tone: field.tone !== false, 
             // A box inside a Widget has no layer of its own to blur.
-            backgroundFilters: ["glass", "haze"], backgroundLabels: backgroundLabels, borderLabels: borderLabels, colorPickerLabels: colorPickerLabels, onChange: (nextValue) => onChange?.({ [field.key]: nextValue }) }));
-    }
-    if (field.type === "shadow") {
-        const currentValue = readPhiShadow(value) ?? readPhiShadow(defaultValue) ?? null;
-        return renderPhiInspectorConfigFieldControl(field, _jsx(PhiShadowControl, { mode: "control", disabled: disabled || !onChange, value: currentValue, onChange: (nextValue) => onChange?.({ [field.key]: nextValue }) }));
+            backgroundFilters: ["glass", "haze"], backgroundLabels: backgroundLabels, borderLabels: borderLabels, colorPickerLabels: colorPickerLabels, renderMediaPicker: renderMediaPicker, onChange: (nextValue) => onChange?.({ [field.key]: nextValue }) }));
     }
     if (field.type === "icon") {
         const iconValue = typeof value === "string"
@@ -765,7 +736,7 @@ function renderPhiInspectorConfigFieldBody({ field, value, defaultValue, config,
                 ? String(value)
                 : typeof defaultValue === "string" || typeof defaultValue === "number"
                     ? String(defaultValue)
-                    : "", disabled: disabled || !onChange, inputType: field.type === "url" ? "url" : "text", style: { width: "100%" }, onChange: (nextValue) => onChange?.({
+                    : "", disabled: disabled || !onChange, inputType: field.type === "url" ? "url" : "text", ...("placeholder" in field && field.placeholder ? { placeholder: field.placeholder } : {}), style: { width: "100%" }, onChange: (nextValue) => onChange?.({
                 [field.key]: nextValue || ("emptyValue" in field ? field.emptyValue : undefined),
             }) }));
     }
@@ -784,6 +755,25 @@ function renderPhiInspectorConfigFieldBody({ field, value, defaultValue, config,
     }
     if (field.type === "flags") {
         const mask = typeof value === "number" ? value : typeof defaultValue === "number" ? defaultValue : 0;
+        /*
+         * One flag is a yes or no, and reads as one: the field's name with a switch behind it on its row,
+         * like a boolean field, rather than a group of a single checkbox under a heading. The other bits of
+         * the mask stay as they are.
+         */
+        const [onlyOption] = field.options.length === 1 ? field.options : [];
+        if (onlyOption) {
+            return renderPhiInspectorSwitchRow({
+                key: field.key,
+                label: renderPhiInspectorConfigFieldLabel(field),
+                checked: (mask & onlyOption.value) !== 0,
+                disabled: disabled || !onChange,
+                ...(onChange
+                    ? {
+                        onChange: (checked) => onChange({ [field.key]: checked ? mask | onlyOption.value : mask & ~onlyOption.value }),
+                    }
+                    : {}),
+            });
+        }
         return renderPhiInspectorConfigFieldBlock(field, _jsx(PhiCheckboxGroupControl, { vertical: true, value: field.options.filter((option) => (mask & option.value) !== 0).map((option) => option.value), options: field.options.map((option) => ({ value: option.value, label: option.label })), disabled: disabled || !onChange, onChange: (ticked) => onChange?.({ [field.key]: ticked.reduce((next, flag) => next | flag, 0) }) }));
     }
     if (field.type === "number-list") {

package/plugins/runtime-modules/builder/clients/inspector-link-target-field.js

@@ -13,7 +13,7 @@ import { PHI_INSPECTOR_WIDGET_DEFAULT_LABELS, } from "../../../../components/wid
  * of the Area the Builder is working on.
  */
 export function PhiInspectorLinkTargetFieldControl({ value, disabled, labels = PHI_INSPECTOR_WIDGET_DEFAULT_LABELS.fields.linkTarget, onChange, }) {
-    const state = usePhiDeveloperBuilderStateValue("public", (current) => current);
+    const state = usePhiDeveloperBuilderStateValue((current) => current);
     const pages = usePhiBuilderOfferedPageCatalog(state, state.area);
     const options = useMemo(() => buildPhiBuilderPageReferenceTree(state.area, pages, pages, { landing: labels.landingPage }), [labels.landingPage, pages, state.area]);
     return (_jsx(PhiLinkTargetControl, { value: value, options: options, labels: labels, disabled: disabled, onChange: onChange, 

package/plugins/runtime-modules/builder/clients/inspector-section-widget.js

@@ -76,14 +76,14 @@ function resolveDraftFromLayoutNode(node, meta) {
 }
 function usePhiBuilderInspectorSectionState(signalRoutes) {
     const dispatchSignal = usePhiSignalDispatcher();
-    const area = usePhiDeveloperBuilderStateValue("public", (state) => state.area);
-    const pageKey = usePhiDeveloperBuilderStateValue("public", (state) => state.pageKey);
-    const builderMode = usePhiDeveloperBuilderStateValue("public", (state) => state.builderMode);
-    const nodeId = usePhiDeveloperBuilderStateValue("public", (state) => state.nodeId);
-    const nodeKey = usePhiDeveloperBuilderStateValue("public", (state) => state.nodeKey);
-    const nodeKind = usePhiDeveloperBuilderStateValue("public", (state) => state.nodeKind);
-    const selectedLayoutAnchor = usePhiDeveloperBuilderStateValue("public", (state) => state.selectedLayoutAnchor);
-    const selectedRootRegionKey = usePhiDeveloperBuilderStateValue("public", (state) => state.selectedRootRegionKey);
+    const area = usePhiDeveloperBuilderStateValue((state) => state.area);
+    const pageKey = usePhiDeveloperBuilderStateValue((state) => state.pageKey);
+    const builderMode = usePhiDeveloperBuilderStateValue((state) => state.builderMode);
+    const nodeId = usePhiDeveloperBuilderStateValue((state) => state.nodeId);
+    const nodeKey = usePhiDeveloperBuilderStateValue((state) => state.nodeKey);
+    const nodeKind = usePhiDeveloperBuilderStateValue((state) => state.nodeKind);
+    const selectedLayoutAnchor = usePhiDeveloperBuilderStateValue((state) => state.selectedLayoutAnchor);
+    const selectedRootRegionKey = usePhiDeveloperBuilderStateValue((state) => state.selectedRootRegionKey);
     const activeModuleMetas = usePhiBuilderModuleMetas(area);
     const activeBuilderPlugins = activeModuleMetas.plugins;
     const activeDataProviderDescriptors = activeModuleMetas.dataProviders;