@phis/ui 0.4.2 → 0.4.4

package/components/media/phi-site-font-assets.js

@@ -1,10 +1,12 @@
 "use client";
-import { isPhiRecord } from "../../helpers/is-record";
 import { useEffect, useMemo, useState } from "react";
 import { PhiMediaKind } from "../../constants/media";
 import { createPhiAssetUri } from "../../types/references";
 import { usePhiCollectionProvider } from "../widgets/client/shared/phi-collection-provider";
 import { PHI_ASSET_COLLECTION_DATA_SOURCE } from "./asset-collection-runtime";
+import { readPhiFontMetricsFields } from "./media-font-metrics";
+import { readPhiMediaAssetTiles } from "./phi-image-preview-data";
+import { createPhiResponseReader } from "../widgets/config/strict-config-reader";
 /**
  * The typefaces a Site owns, as something a font slot can be set to.
  *
@@ -19,12 +21,9 @@ import { PHI_ASSET_COLLECTION_DATA_SOURCE } from "./asset-collection-runtime";
 /** Enough for any Site's own lettering; a ceiling rather than a page size. */
 const PHI_SITE_FONT_ASSET_LIMIT = 100;
 function readFontAssetMetrics(asset) {
-    const meta = asset.meta?.font;
-    if (!isPhiRecord(meta))
-        return null;
-    const record = meta;
-    // The management tile carries `meta` as stored; only a shape with its unit grid is worth drawing from.
-    return typeof record.unitsPerEm === "number" && record.unitsPerEm > 0 ? record : null;
+    // The management tile carries `meta` as stored, and the server stored every field of the metrics.
+    return createPhiResponseReader(asset.meta ?? {}, `The stored metrics of Asset ${asset.id}`, "meta")
+        .object("font", readPhiFontMetricsFields) ?? null;
 }
 function readFontAssetLabel(asset) {
     const family = readFontAssetMetrics(asset)?.familyName;
@@ -68,7 +67,7 @@ export function usePhiSiteFontAssets(enabled = true) {
                 setError(data.error);
                 return;
             }
-            setAssets(data.items.filter((item) => Boolean(item)));
+            setAssets(readPhiMediaAssetTiles(data.items));
         }).catch((cause) => {
             if (abortController.signal.aborted)
                 return;

package/components/navigation/phi-link.js

@@ -10,10 +10,15 @@ export function PhiLink({ href, children, external, newTab, prefetch, className,
     const [active, setActive] = useState(false);
     const useAnchor = external ?? isPhiExternalHref(href);
     const linkStyle = useMemo(() => ({
-        color: active ? token.colorLinkActive : hovered ? token.colorLinkHover : token.colorLink,
         textDecoration: "none",
         cursor: "pointer",
         ...style,
+        /*
+         * A colour the caller states is the link at rest -- a Header's text colour, a list's inherited one --
+         * and never more: pointed at and pressed, a link answers in the Theme's link colours whatever it
+         * rests in. Spread after `style`, a stated colour had silenced the hover of every link that set one.
+         */
+        color: active ? token.colorLinkActive : hovered ? token.colorLinkHover : style?.color ?? token.colorLink,
     }), [active, hovered, style, token.colorLink, token.colorLinkActive, token.colorLinkHover]);
     const interactionProps = {
         onMouseEnter: () => setHovered(true),

package/components/overlays/phi-overlay-container-client.js

@@ -60,6 +60,13 @@ export function PhiOverlayContainerClient({ overlayId, overlayType, config: rawC
     const [runtimeControlSizeOverride, setRuntimeControlSizeOverride] = useState(null);
     const [runtimeSizeOverride, setRuntimeSizeOverride] = useState(null);
     const [runtimeTitleOverride, setRuntimeTitleOverride] = useState(null);
+    /*
+     * Whether work the Overlay holds is under way -- a Form in the Body saving. While it is, a reader's
+     * dismissal (close button, mask, Escape) is not taken: closing would abandon the save's answer. A
+     * `close` sent on purpose still closes, which is how a Form that went through ends its dialog. Told
+     * through the `busy` input by whoever knows, so a dialog needs no Controller to refuse a close.
+     */
+    const [busy, setBusy] = useState(false);
     const runtimeControlSize = runtimeControlSizeOverride?.config === config
         ? runtimeControlSizeOverride.value
         : null;
@@ -106,6 +113,9 @@ export function PhiOverlayContainerClient({ overlayId, overlayType, config: rawC
         // A failed load is forgotten on close, so the next open asks the server again.
         if (!nextOpen)
             setLoadedZones((current) => current && "failure" in current ? null : current);
+        // A closed Overlay holds no work; a busy state left behind would refuse the next dismissal.
+        if (!nextOpen)
+            setBusy(false);
         setOpen(nextOpen);
     }, []);
     /*
@@ -200,6 +210,9 @@ export function PhiOverlayContainerClient({ overlayId, overlayType, config: rawC
         else if (route.capabilityId === "close") {
             updateOpen(false);
         }
+        else if (route.capabilityId === "busy" && signal.valueType === "boolean") {
+            setBusy(signal.value === true);
+        }
         else if (route.capabilityId === "toggle") {
             updateOpen(typeof signal.value === "boolean" ? signal.value : !open);
         }
@@ -229,12 +242,14 @@ export function PhiOverlayContainerClient({ overlayId, overlayType, config: rawC
         receiver,
     }), [receiver, signalScope]), receiver);
     const requestClose = useCallback((source) => {
+        if (busy)
+            return;
         if (config.closeMode === "request") {
             emitCapability("closeRequest", { source });
             return;
         }
         updateOpen(false);
-    }, [config.closeMode, emitCapability, updateOpen]);
+    }, [busy, config.closeMode, emitCapability, updateOpen]);
     // An Overlay's window is simply "open", which is why it can share the rule with a Carousel whose
     // window is several slots wide.
     const shouldRenderContent = shouldPhiCmsContentStayMounted({

package/components/regions/clients/cms-region-container-client.js

@@ -17,7 +17,8 @@ import { PhiEffectsReadyTrigger } from "../../../plugins/runtime/phi-effects-rea
 import { PhiSlotChildEffectsVisibilityObserver } from "../../../plugins/runtime/phi-slot-child-effects-visibility-observer";
 import { PhiSlotChildViewportEffectsObserver } from "../../../plugins/runtime/phi-slot-child-viewport-effects-observer";
 import { PhiFlexControl } from "../../controls/phi-flex-control";
-import { resolvePhiCmsRegionShell } from "../phi-cms-region-shell";
+import { phiCmsRegionSiderSticks, resolvePhiCmsRegionShell, } from "../phi-cms-region-shell";
+import { usePhiShellStickyTop } from "../../shell/use-phi-shell-sticky-top";
 import { usePhiVisualAnchor } from "../../runtime/runtime-visual-anchors";
 import { usePhiPathname } from "../../runtime/use-phi-pathname";
 import { stripLocaleAndAreaFromPathname } from "../../../helpers/locale";
@@ -100,6 +101,10 @@ export function PhiCmsRegionContainerClient({ children, className, regionKey, co
         elementRef,
         placeholderRef,
     });
+    usePhiShellStickyTop({
+        active: !previewMode && inScope && phiCmsRegionSiderSticks(regionKey, initialConfig),
+        elementRef,
+    });
     /*
      * Off this Page, the Region leaves a hidden marker rather than nothing: `header_top` still has to tell
      * the Shell it holds no room, and it finds the Shell from here.

package/components/regions/phi-cms-region-container.js

@@ -3,6 +3,7 @@ import { isPhiCmsPageOwnedRegion } from "../../helpers/cms-region-keys";
 import { hasPhiFlag } from "../../helpers/flags";
 import { PhiCmsFlags } from "../../constants/phi-cms";
 import { PhiCmsRegionStatic } from "./phi-cms-region-static";
+import { phiCmsRegionSiderSticks } from "./phi-cms-region-shell";
 import { resolveRenderableBlockEffectsAttributes, resolveRenderableBlockViewportEffects, } from "../../helpers/renderable-block-effects";
 import { PhiRuntimeModuleRenderClientHost } from "../runtime/runtime-module-render-client-manifest";
 import { PhiRuntimeRenderClientType } from "../../constants/runtime-render-client-types";
@@ -21,6 +22,8 @@ export function PhiCmsRegionContainer({ children, className, regionKey, config,
     const requiresClientEnhancement = signalParticipant ||
         pageScoped ||
         (!previewMode && readPhiCmsRegionReveal(regionKey, config) !== "always") ||
+        // A stuck Sider stands under the Header as measured, and only the browser can measure it.
+        (!previewMode && phiCmsRegionSiderSticks(regionKey, config)) ||
         hasPhiFlag(config?.flags, PhiCmsFlags.Collapsible) ||
         requiresEffectsObserver ||
         resolvePhiBackgroundMotion(config?.surface?.background) != null;

package/components/regions/phi-cms-region-shell.d.ts

@@ -3,7 +3,7 @@ import type { CSSProperties } from "react";
 import { type PhiRenderableBlockEffectsAttributes } from "../../helpers/renderable-block-effects";
 import { resolvePhiShellRegionChrome } from "../../helpers/shell-region-style";
 import type { PhiBlockRuntime, PhiCmsRegionConfig, PhiCmsRegionKey, PhiRenderableBlock } from "../../types";
-import type { PhiSurfaceGround } from "../../helpers/surface-style";
+import { type PhiSurfaceGround } from "../../helpers/surface-style";
 import type { PhiCmsRegionReveal } from "../../types/cms-presets";
 import { type PhiCmsBackgroundWidgetConfig } from "../widgets/config/background";
 /**
@@ -92,6 +92,17 @@ export type PhiCmsRegionShell = {
     /** The content wrapper's style, which is where Region padding lives (LAYOUTING.md "Regions"). */
     contentStyle: CSSProperties;
 };
+/**
+ * Whether a Region is a Sider that sticks under the Header, and so needs the Header's measured bottom.
+ *
+ * Two kinds of Sider stick, and only one of them under the Header. A `FullHeight` Sider is a column of the
+ * Shell from the viewport's top to its bottom -- an Admin or Builder navigation beside the Header, not
+ * below it -- and stands at its configured `offsetTop`. A `Sticky` Sider without it stands in the page
+ * below the Header -- a contents beside a text -- and sticks under the line the Shell publishes as
+ * `--phi-shell-sticky-top` (`usePhiShellStickyTop`), with its offset added. The Region renderer runs that
+ * measurement for such a Sider, which is why this is asked before the Region renders.
+ */
+export declare function phiCmsRegionSiderSticks(regionKey: PhiCmsRegionKey, config: Pick<PhiCmsRegionConfig, "flags"> | null | undefined): boolean;
 /**
  * The Region's shell, or null where the Region renders nothing: hidden, or collapsed in a preview.
  * `header_bottom` is exempt from the preview collapse because the Page, not the Area, owns its content.

package/components/regions/phi-cms-region-shell.js

@@ -6,11 +6,12 @@ import { resolveRenderableBlockEffectsAttributes, resolveRenderableBlockEffectsS
 import { resolvePhiShellRegionChrome, resolvePhiShellRegionGroundStyle, resolvePhiShellRegionTypography, resolvePhiShellRegionZIndex, resolvePhiShellSiderCollapsedWidth, resolvePhiShellSiderWidth, } from "../../helpers/shell-region-style";
 import { PhiCmsFlags } from "../../constants/phi-cms";
 import { resolvePhiCmsBorderSource } from "../../types/cms-border-source";
+import { PHI_SURFACE_TONE_GROUND, phiSurfaceTakesToneGround, } from "../../helpers/surface-style";
 import { resolvePhiRenderableBlockGeometry } from "../../types/renderable-block-geometry";
 import { createPhiSignalAddress } from "../../types/signals";
 import { readPhiCmsRegionReveal } from "../../helpers/region-page-scope";
 import { resolvePhiPaddingStyle } from "../layouts/phi-layout-contract";
-import { phiRegionUsesShellChromeOverlay } from "../root/phi-shell-chrome-overlay";
+import { PHI_SHELL_STICKY_TOP_PROPERTY, phiRegionUsesShellChromeOverlay } from "../root/phi-shell-chrome-overlay";
 import { normalizePhiBackgroundWidgetConfig, phiBackgroundWidgetConfigPaintsGround, resolvePhiBackgroundGroundFilter, resolvePhiBackgroundMotion, resolvePhiBackgroundMotionHostStyle, resolvePhiBackgroundPane, resolvePhiBackgroundWidgetStyle, } from "../widgets/config/background";
 /*
  * The longhands every Region that paints the Shell Chrome Overlay (SHELL.md) carries, read from the
@@ -45,6 +46,25 @@ function resolvePhiCmsRegionShellFamily(regionKey) {
     }
     return "other";
 }
+/**
+ * Whether a Region is a Sider that sticks under the Header, and so needs the Header's measured bottom.
+ *
+ * Two kinds of Sider stick, and only one of them under the Header. A `FullHeight` Sider is a column of the
+ * Shell from the viewport's top to its bottom -- an Admin or Builder navigation beside the Header, not
+ * below it -- and stands at its configured `offsetTop`. A `Sticky` Sider without it stands in the page
+ * below the Header -- a contents beside a text -- and sticks under the line the Shell publishes as
+ * `--phi-shell-sticky-top` (`usePhiShellStickyTop`), with its offset added. The Region renderer runs that
+ * measurement for such a Sider, which is why this is asked before the Region renders.
+ */
+export function phiCmsRegionSiderSticks(regionKey, config) {
+    return resolvePhiCmsRegionShellFamily(regionKey) === "sider"
+        && hasPhiFlag(config?.flags, PhiCmsFlags.Sticky)
+        && !hasPhiFlag(config?.flags, PhiCmsFlags.FullHeight);
+}
+/** The line a stuck Sider stands at: under the Header as measured, plus its own offset. */
+function resolvePhiCmsRegionSiderStuckTop(topCss) {
+    return `calc(var(${PHI_SHELL_STICKY_TOP_PROPERTY}, 0px) + ${topCss})`;
+}
 /*
  * A Region's edge, from its Surface.
  *
@@ -123,15 +143,24 @@ export function resolvePhiCmsRegionShell({ regionKey, config, shellTheme, paint,
      * `scroll-up` band ever publishes it (SHELL.md "Region visibility per Page"), so for every other Shell
      * it is unset and the offset is the one configured.
      */
+    /*
+     * A full-height Sider is a Shell column from the viewport's top and stands at its own offset; a sticky
+     * one stands under the Header as it is measured right now (`phiCmsRegionSiderSticks`) and is at most as
+     * tall as what is left of the viewport below that line.
+     */
+    const siderUnderHeader = isSider && sticky && !fullHeight;
     const stuckTop = !stuck
         ? undefined
         : isHeader && regionKey !== "header_top"
             ? `calc(${topCss} + var(--phi-shell-header-top-stack, 0px))`
-            : top;
+            : siderUnderHeader
+                ? resolvePhiCmsRegionSiderStuckTop(topCss)
+                : top;
     const blockSize = geometry.block.size?.css;
     const fullHeightSize = fullHeight && !blockSize
         ? `calc(100dvh - ${topCss})`
         : blockSize;
+    const underHeaderMaxSize = siderUnderHeader ? `calc(100dvh - ${resolvePhiCmsRegionSiderStuckTop(topCss)})` : undefined;
     const zIndex = config.zIndex ?? resolvePhiShellRegionZIndex(regionKey, hasPhiFlag(config.flags, PhiCmsFlags.FullHeight));
     /*
      * A Background config that paints nothing is not an authored ground. The Builder writes one onto every
@@ -143,12 +172,31 @@ export function resolvePhiCmsRegionShell({ regionKey, config, shellTheme, paint,
         ? normalizePhiBackgroundWidgetConfig(surface.background)
         : null;
     const backgroundConfig = phiBackgroundWidgetConfigPaintsGround(surfaceBackground) ? surfaceBackground : null;
+    /*
+     * A tone turns the ground as well, by the rule every Surface follows (LAYOUTING.md "Surface tone"):
+     * where the Background paints nothing, the Region takes its tone's container ground, which resolves
+     * under the tone class the root element carries. That is a ground of the Region's own, so the Shell's
+     * -- the Theme's record, the Chrome Overlay, a pane frosting either -- does not show beneath it.
+     */
+    const toneGround = phiSurfaceTakesToneGround(surface?.tone, backgroundConfig != null);
+    /*
+     * The Theme's Overlay as the ground (`base.kind: "theme"`). Without a tone a Chrome Region takes it the
+     * way a Region without a Background does -- the `data-phi-shell-chrome` marker, so that where the Shell
+     * draws its panes the pane behind shows through instead of a second frosting -- but over any ground the
+     * Shell record sets. Every other Region, and a toned one, paints it itself, which under a tone's class
+     * is the Overlay of the tone's mode.
+     */
+    const themeGround = backgroundConfig?.base.kind === "theme";
+    const themeGroundIsShellChrome = themeGround
+        && resolvePhiSurfaceToneClassName(surface?.tone) == null
+        && phiRegionUsesShellChromeOverlay({ regionKey, backgroundConfig, grounds: [] });
     /*
      * A pane on a Region without a ground of its own frosts the Shell's ground for this Region -- the
      * Theme's record, or the family's fallback -- which is what glass on a bare Header has always meant.
-     * A Region that paints its own ground carries its pane inside that Background, as every Surface does.
+     * A Region that paints its own ground carries its pane inside that Background, as every Surface does;
+     * the tone's ground is one, so its pane stays on the box under that ground, as on a toned Layout.
      */
-    const shellPane = backgroundConfig == null ? resolvePhiBackgroundPane(surfaceBackground) : null;
+    const shellPane = backgroundConfig == null && !toneGround ? resolvePhiBackgroundPane(surfaceBackground) : null;
     const backgroundMoves = animatesBackground &&
         backgroundConfig != null &&
         resolvePhiBackgroundMotion(backgroundConfig) != null;
@@ -160,11 +208,18 @@ export function resolvePhiCmsRegionShell({ regionKey, config, shellTheme, paint,
             motion: null,
         }
         : null;
-    const backgroundStyle = backgroundConfig == null || ground != null
+    const backgroundStyle = themeGroundIsShellChrome
         ? null
-        : backgroundMoves
-            ? resolvePhiBackgroundMotionHostStyle(backgroundConfig)
-            : resolvePhiBackgroundWidgetStyle(backgroundConfig);
+        : toneGround
+            ? {
+                ...(surfaceBackground ? resolvePhiBackgroundWidgetStyle(surfaceBackground) : {}),
+                backgroundColor: PHI_SURFACE_TONE_GROUND,
+            }
+            : backgroundConfig == null || ground != null
+                ? null
+                : backgroundMoves
+                    ? resolvePhiBackgroundMotionHostStyle(backgroundConfig)
+                    : resolvePhiBackgroundWidgetStyle(backgroundConfig);
     const chromeInput = {
         shadow: surface?.shadow ?? undefined,
         effect: shellPane ?? undefined,
@@ -184,12 +239,14 @@ export function resolvePhiCmsRegionShell({ regionKey, config, shellTheme, paint,
      * the stored one: the Builder persists an empty Background record for every Region an author has ever
      * opened, and the raw value is never null for those.
      */
-    const usesShellChromeOverlay = phiRegionUsesShellChromeOverlay({
-        regionKey,
-        backgroundConfig,
-        pane: shellPane,
-        grounds: [chrome.light.background, chrome.dark.background],
-    });
+    const usesShellChromeOverlay = themeGround
+        ? themeGroundIsShellChrome
+        : !toneGround && phiRegionUsesShellChromeOverlay({
+            regionKey,
+            backgroundConfig,
+            pane: shellPane,
+            grounds: [chrome.light.background, chrome.dark.background],
+        });
     /*
      * The ground. Published, it is the pair of custom properties `shell.css` paints from, because it may
      * be a colour or a gradient and only CSS can tell which without guessing; nothing inline may name a
@@ -203,13 +260,18 @@ export function resolvePhiCmsRegionShell({ regionKey, config, shellTheme, paint,
      * drop one of those from an element whose `background` shorthand is still set.
      */
     const liveChrome = paint.kind === "live" ? chrome[paint.mode] : null;
+    /*
+     * A toned Region publishes no Shell ground: `shell.css` would paint a gradient one beneath its own. Nor
+     * does one whose ground is the Theme's: the Overlay stands where the Shell record's ground would.
+     */
+    const withoutShellGround = toneGround || themeGround;
     const modeStyle = liveChrome
         ? {}
         : {
-            ...(chrome.light.background == null
+            ...(chrome.light.background == null || withoutShellGround
                 ? {}
                 : { "--phi-region-background-light": String(chrome.light.background) }),
-            ...(chrome.dark.background == null
+            ...(chrome.dark.background == null || withoutShellGround
                 ? {}
                 : { "--phi-region-background-dark": String(chrome.dark.background) }),
             "--phi-region-color-light": String(chrome.light.color),
@@ -219,7 +281,7 @@ export function resolvePhiCmsRegionShell({ regionKey, config, shellTheme, paint,
     const effectStyle = liveChrome || paintedChrome.effectStyle?.backgroundColor == null
         ? paintedChrome.effectStyle
         : { ...paintedChrome.effectStyle, backgroundColor: "var(--phi-region-background)" };
-    const groundStyle = liveChrome && backgroundStyle == null
+    const groundStyle = liveChrome && backgroundStyle == null && !themeGround
         ? resolvePhiShellRegionGroundStyle(liveChrome.background)
         : {};
     const typography = resolvePhiShellRegionTypography(regionKey, shellTheme, {
@@ -258,11 +320,11 @@ export function resolvePhiCmsRegionShell({ regionKey, config, shellTheme, paint,
             maxWidth: geometry.inline.max?.css ?? siderWidth,
             height: fullHeightSize,
             minHeight: geometry.block.min?.css ?? (fullHeight ? fullHeightSize : undefined),
-            maxHeight: geometry.block.max?.css,
+            maxHeight: geometry.block.max?.css ?? underHeaderMaxSize,
             alignSelf: fullHeight ? "stretch" : "start",
             flex: fullHeight ? "1 1 auto" : undefined,
             overflowX: "visible",
-            overflowY: fullHeight ? "auto" : "visible",
+            overflowY: fullHeight || siderUnderHeader ? "auto" : "visible",
         }
         : {
             width: geometry.inline.size?.css ?? "100%",

package/components/regions/presets/phi-settings-page-shell-tree.js

@@ -4,7 +4,7 @@ import { createPhiCmsPresetNodes } from "../../../helpers/cms-preset-nodes";
 import { PHI_SPACE } from "../../../theme/antd-css-var-contract";
 import { PHI_LAYOUT } from "../../../theme/phi-tokens";
 import { createPhiPresetCmsInstanceIdMap } from "../../../types/cms-instance-id";
-import { PHI_SIGNAL_VALUE_SCHEMAS, createPhiSignalAddress } from "../../../types/signals";
+import { PHI_SIGNAL_VALUE_SCHEMAS, createPhiSignalAddress, createPhiSignalSubcontrolAddress, } from "../../../types/signals";
 import { buildPhiBasePageContentScaffold, PHI_BASE_PAGE_LAYOUT_NODE_ID } from "./phi-base-page-layout";
 import { PHI_DIALOG_BODY_CONFIG, PHI_DIALOG_COMMANDS_CONFIG } from "../../../helpers/cms-dialog";
 /**
@@ -252,6 +252,29 @@ export function buildPhiSettingsPageShellTree({ page, ownerModuleId, presetKey,
                                     valueType: "none",
                                     receiver: overlayAddress,
                                 },
+                                /*
+                                 * While the save is under way the dialog refuses a reader's dismissal, and the Save
+                                 * button shows that it is working -- the two things a Controller would otherwise be
+                                 * mounted for (OVERLAYS.md, "Runtime and signaling").
+                                 */
+                                {
+                                    routeKey: `${overlay.nodeKey}-busy`,
+                                    capabilityId: "submitting",
+                                    scope: "page",
+                                    channel: "busy",
+                                    action: "change",
+                                    valueType: "boolean",
+                                    receiver: overlayAddress,
+                                },
+                                {
+                                    routeKey: `${overlay.nodeKey}-submit-loading`,
+                                    capabilityId: "submitting",
+                                    scope: "page",
+                                    channel: "loading",
+                                    action: "change",
+                                    valueType: "boolean",
+                                    receiver: createPhiSignalSubcontrolAddress("cms", widgets[`${overlay.nodeKey}Commands`], "submit"),
+                                },
                                 ...(extraSignalRoutes?.emits ?? []),
                             ],
                             listens: [
@@ -315,6 +338,17 @@ export function buildPhiSettingsPageShellTree({ page, ownerModuleId, presetKey,
                                     receiver: formAddress,
                                 },
                             ],
+                            listens: [
+                                {
+                                    routeKey: `${overlay.nodeKey}-commands-submit-loading`,
+                                    capabilityId: "loading",
+                                    scope: "page",
+                                    channel: "loading",
+                                    action: "change",
+                                    valueType: "boolean",
+                                    receiver: createPhiSignalSubcontrolAddress("cms", widgets[`${overlay.nodeKey}Commands`], "submit"),
+                                },
+                            ],
                         },
                     },
                 }),
@@ -344,6 +378,10 @@ export function buildPhiSettingsPageShellTree({ page, ownerModuleId, presetKey,
                  * the provider somebody looked at before.
                  */
                 mountPolicy: "remount",
+                /*
+                 * `immediate`, because nothing is mounted to answer a close request; while the Form saves, its
+                 * `submitting` route sets this Overlay `busy`, and a busy Overlay does not take a dismissal.
+                 */
                 closeMode: "immediate",
                 openActionKey: overlay.openActionKey,
                 signalRoutes: {
@@ -371,6 +409,15 @@ export function buildPhiSettingsPageShellTree({ page, ownerModuleId, presetKey,
                             valueType: "none",
                             receiver: createPhiSignalAddress("cms", overlayIds[overlay.nodeKey]),
                         },
+                        {
+                            routeKey: `${overlay.nodeKey}-busy`,
+                            capabilityId: "busy",
+                            scope: "page",
+                            channel: "busy",
+                            action: "change",
+                            valueType: "boolean",
+                            receiver: createPhiSignalAddress("cms", overlayIds[overlay.nodeKey]),
+                        },
                     ],
                 },
             },

package/components/root/phi-config-provider.d.ts

@@ -30,6 +30,11 @@ export type PhiConfig = {
      * the reader rather than quietly working until the day the Theme is computed by something else.
      */
     token: PhiThemeTokens;
+    /**
+     * The page's Theme where `token` is a Surface tone's (`PhiNestedModeConfigProvider`): set only inside
+     * a tone scope, so outside one the page's Theme is `token` itself. Read through `usePhiPageModeToken`.
+     */
+    pageToken?: PhiThemeTokens;
 };
 export type PhiFontCatalogueFamily = {
     family: string;
@@ -49,6 +54,14 @@ export declare function PhiConfigProvider({ children, locale, fonts, fontFamilie
     controlShape: PhiControlShape;
 }): import("react").JSX.Element;
 export declare function usePhiConfig(): PhiConfig;
+/**
+ * The Theme of the page's own mode, wherever this is asked -- inside a Surface tone too.
+ *
+ * What draws the page's tools rather than its content takes its colours from here: the Builder's scaffolds
+ * mark Layouts and Widgets in the editor's mode, and a Region turned inverse leaves them as they were
+ * instead of turning them with the content they stand around.
+ */
+export declare function usePhiPageModeToken(): PhiThemeTokens;
 /** The locale the root adapter configures Ant Design with, for whoever hands it on. */
 export type PhiConfigLocale = ConfigProviderProps["locale"];
 /**

package/components/root/phi-config-provider.js

@@ -70,6 +70,17 @@ export function usePhiConfig() {
     }
     return config;
 }
+/**
+ * The Theme of the page's own mode, wherever this is asked -- inside a Surface tone too.
+ *
+ * What draws the page's tools rather than its content takes its colours from here: the Builder's scaffolds
+ * mark Layouts and Widgets in the editor's mode, and a Region turned inverse leaves them as they were
+ * instead of turning them with the content they stand around.
+ */
+export function usePhiPageModeToken() {
+    const config = usePhiConfig();
+    return config.pageToken ?? config.token;
+}
 /**
  * The page's config in another mode: Ant Design's Theme for `mode` and the house config with that mode's
  * colours and tokens.
@@ -89,6 +100,6 @@ export function PhiNestedModeConfigProvider({ mode, theme, cssVarKey, locale, cu
 function PhiNestedModeConfigValue({ mode, customColors, children, }) {
     const outer = usePhiConfig();
     const { token } = antdTheme.useToken();
-    const value = useMemo(() => ({ ...outer, mode, customColors, token }), [customColors, mode, outer, token]);
+    const value = useMemo(() => ({ ...outer, mode, customColors, token, pageToken: outer.pageToken ?? outer.token }), [customColors, mode, outer, token]);
     return _jsx(PhiConfigContext.Provider, { value: value, children: children });
 }

package/components/root/phi-root-background.d.ts

@@ -53,6 +53,13 @@ export declare const PHI_ROOT_BACKGROUND_IMAGE_SOURCE_KINDS: readonly PhiBackgro
  * simply resolves away.
  */
 export declare const PHI_ROOT_BACKGROUND_FILTERS: readonly PhiBackgroundFilter[];
+/**
+ * The Base kinds the Theme Root Background offers and honours: every one but `theme`.
+ *
+ * `theme` is the Chrome Overlay standing in for a box's ground, and the Root Background is no box on the
+ * page but the ground beneath all of them. A stored value outside the offer resolves to `none`.
+ */
+export declare const PHI_ROOT_BACKGROUND_BASE_KINDS: readonly PhiCmsBackgroundWidgetConfig["base"]["kind"][];
 /**
  * What the ground paints, without the geometry of the layer that paints it.
  *

package/components/root/phi-root-background.js

@@ -59,8 +59,27 @@ export const PHI_ROOT_BACKGROUND_FILTERS = [];
 function withoutPhiRootBackgroundFilter(config) {
     return config ? { ...normalizePhiBackgroundWidgetConfig(config), filter: null } : null;
 }
+/**
+ * The Base kinds the Theme Root Background offers and honours: every one but `theme`.
+ *
+ * `theme` is the Chrome Overlay standing in for a box's ground, and the Root Background is no box on the
+ * page but the ground beneath all of them. A stored value outside the offer resolves to `none`.
+ */
+export const PHI_ROOT_BACKGROUND_BASE_KINDS = [
+    "none",
+    "color",
+    "gradient",
+    "image",
+];
 function readPhiRootBackgroundConfig(root, mode) {
-    return (mode === "dark" ? root?.background?.dark : root?.background?.light) ?? null;
+    const configured = (mode === "dark" ? root?.background?.dark : root?.background?.light) ?? null;
+    if (configured == null) {
+        return null;
+    }
+    const normalized = normalizePhiBackgroundWidgetConfig(configured);
+    return PHI_ROOT_BACKGROUND_BASE_KINDS.includes(normalized.base.kind)
+        ? configured
+        : { ...normalized, base: { kind: "none" } };
 }
 /**
  * What the ground paints, without the geometry of the layer that paints it.

package/components/root/phi-root-theme-resolver.js

@@ -53,6 +53,9 @@ export function resolvePhiRootTheme({ siteTheme, mode, fonts, presets, }) {
     const resolvedShellHeaderMainBackground = resolvePhiShellRegionBackground(siteTheme?.shell, mode, { family: "header", region: "main" }) ??
         (mode === "dark" ? PHI_DEFAULT_DARK_NAV_BACKGROUND : undefined);
     const sharedComponentDefaults = buildPhiComponentTokens({
+        ...(typeof effectiveThemeTokens.fontSizeSM === "number" ? { fontSizeSM: effectiveThemeTokens.fontSizeSM } : {}),
+        ...(typeof effectiveThemeTokens.fontSize === "number" ? { fontSize: effectiveThemeTokens.fontSize } : {}),
+        ...(typeof effectiveThemeTokens.lineHeight === "number" ? { lineHeight: effectiveThemeTokens.lineHeight } : {}),
         layout: {
             ...(resolvedShellSiderBackground ? { siderBg: resolvedShellSiderBackground } : {}),
             ...(resolvedShellHeaderMainBackground ? { headerBg: resolvedShellHeaderMainBackground } : {}),

package/components/root/phi-shell-chrome-overlay.d.ts

@@ -58,13 +58,18 @@ export declare const PHI_SHELL_CHROME_OVERLAY_IMAGE_SOURCE_KINDS: readonly PhiBa
 export declare const PHI_SHELL_CHROME_OVERLAY_MOTION_MODES: readonly PhiBackgroundMotionMode[];
 export type PhiShellChromeOverlayVariables = Record<`--phi-shell-chrome-${string}`, string>;
 /**
- * Whether this Region paints the shared overlay, which it does only while it authored nothing itself.
+ * Whether this Region paints the shared overlay, which it does while it authored nothing itself -- or
+ * while what it authored is the overlay.
  *
  * A Region that authored its own chrome paints over the Theme, and that is how an Area keeps a look of
  * its own. Authored means every carrier, not just one: the Region Surface's Background, the ground the
  * Shell record sets, and a glass pane the Region asks for over that ground. Reading only the
  * first let the Builder's Sider take the Site's overlay on top of the container ground it paints on
  * purpose, which is what this exists to prevent.
+ *
+ * A Background whose Base is `theme` states the overlay, so a Chrome Region takes it whatever the Shell
+ * record says. The caller asks this only for a Region without a tone: a toned one wants the overlay of
+ * its tone's mode, which it paints itself (`PHI_BACKGROUND_THEME_STYLE`).
  */
 export declare function phiRegionUsesShellChromeOverlay({ regionKey, backgroundConfig, pane, grounds, }: {
     regionKey: string;
@@ -125,6 +130,12 @@ export declare function resolvePhiShellChromePaneStickyTop(bands: readonly PhiSh
  */
 export declare const PHI_SHELL_HEADER_TOP_EXTENT_PROPERTY = "--phi-shell-header-top-extent";
 export declare const PHI_SHELL_HEADER_TOP_STACK_PROPERTY = "--phi-shell-header-top-stack";
+/**
+ * The Header's measured bottom: the lowest bottom of every Header band stuck right now, written on the
+ * Shell by `usePhiShellStickyTop` (components/shell/use-phi-shell-sticky-top.ts). A sticky Table header
+ * and a stuck Sider stand under it; unset, it reads `0px`.
+ */
+export declare const PHI_SHELL_STICKY_TOP_PROPERTY = "--phi-shell-sticky-top";
 /**
  * How `header_top` behaves where the browser decides it, as far as the Header pane is concerned.
  */

package/components/root/phi-shell-chrome-overlay.js

@@ -76,17 +76,27 @@ const PHI_SHELL_CHROME_OVERLAY_REGION_KEYS = [
     "footer_bottom",
 ];
 /**
- * Whether this Region paints the shared overlay, which it does only while it authored nothing itself.
+ * Whether this Region paints the shared overlay, which it does while it authored nothing itself -- or
+ * while what it authored is the overlay.
  *
  * A Region that authored its own chrome paints over the Theme, and that is how an Area keeps a look of
  * its own. Authored means every carrier, not just one: the Region Surface's Background, the ground the
  * Shell record sets, and a glass pane the Region asks for over that ground. Reading only the
  * first let the Builder's Sider take the Site's overlay on top of the container ground it paints on
  * purpose, which is what this exists to prevent.
+ *
+ * A Background whose Base is `theme` states the overlay, so a Chrome Region takes it whatever the Shell
+ * record says. The caller asks this only for a Region without a tone: a toned one wants the overlay of
+ * its tone's mode, which it paints itself (`PHI_BACKGROUND_THEME_STYLE`).
  */
 export function phiRegionUsesShellChromeOverlay({ regionKey, backgroundConfig, pane, grounds, }) {
-    return (PHI_SHELL_CHROME_OVERLAY_REGION_KEYS.includes(regionKey) &&
-        backgroundConfig == null &&
+    if (!PHI_SHELL_CHROME_OVERLAY_REGION_KEYS.includes(regionKey)) {
+        return false;
+    }
+    if (backgroundConfig != null && normalizePhiBackgroundWidgetConfig(backgroundConfig).base.kind === "theme") {
+        return true;
+    }
+    return (backgroundConfig == null &&
         pane == null &&
         grounds.every((ground) => ground == null));
 }
@@ -223,6 +233,12 @@ export function resolvePhiShellChromePaneStickyTop(bands) {
  */
 export const PHI_SHELL_HEADER_TOP_EXTENT_PROPERTY = "--phi-shell-header-top-extent";
 export const PHI_SHELL_HEADER_TOP_STACK_PROPERTY = "--phi-shell-header-top-stack";
+/**
+ * The Header's measured bottom: the lowest bottom of every Header band stuck right now, written on the
+ * Shell by `usePhiShellStickyTop` (components/shell/use-phi-shell-sticky-top.ts). A sticky Table header
+ * and a stuck Sider stand under it; unset, it reads `0px`.
+ */
+export const PHI_SHELL_STICKY_TOP_PROPERTY = "--phi-shell-sticky-top";
 /**
  * Where the Header pane sticks when `header_top` may come and go.
  *