@phis/ui 0.1.0 → 0.2.1

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

@@ -2,7 +2,7 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { ConfigProvider as AntdConfigProvider, theme as antdTheme, } from "antd";
 import { createContext, useContext, useEffect, useMemo, } from "react";
-import { buildPhiControlShapeCssVars, } from "../../theme/phi-control-shape";
+import { buildPhiControlShapeCssVars, PHI_SURFACE_SHAPE_CSS_VAR, resolvePhiSurfaceShapeRadius, } from "../../theme/phi-control-shape";
 const PhiConfigContext = createContext(null);
 function PhiConfigValueProvider({ children, customColors, fonts, fontFamilies, heroHeight, mode, controlShape, presets, rootClassName, rootStyle, remRootValue, themeCssVarKey, }) {
     const { token, cssVar } = antdTheme.useToken();
@@ -11,7 +11,15 @@ function PhiConfigValueProvider({ children, customColors, fonts, fontFamilies, h
      * `styles/control-shape.css` reads. They are resolved from the LIVE tokens, so a Style tab edit moves
      * them the same request the numeric scale moves.
      */
-    const controlShapeVars = useMemo(() => buildPhiControlShapeCssVars(controlShape, token), [controlShape, token]);
+    const controlShapeVars = useMemo(() => ({
+        ...buildPhiControlShapeCssVars(controlShape, token),
+        /*
+         * The Table's corner rides along rather than living in the map above: that map is what
+         * `styles/control-shape.css` reads, and this one is read by a CSS Module beside the Control it
+         * belongs to. Same element, same source, different reader.
+         */
+        [PHI_SURFACE_SHAPE_CSS_VAR]: `${resolvePhiSurfaceShapeRadius(controlShape, token)}px`,
+    }), [controlShape, token]);
     /*
      * antd renders Modals, Drawers, and every popup into a portal on `document.body`, outside this
      * element, so a Control inside one would not inherit the properties above. Mirroring them onto the

package/components/root/phi-dayjs-locale.d.ts

@@ -5,8 +5,15 @@ type PhiDayjsLocaleResolution = {
     localeName: string;
 };
 export declare function resolvePhiDayjsLocale(locale: string | null | undefined): PhiDayjsLocaleResolution;
-export declare function PhiDayjsLocale({ locale, children }: {
+/**
+ * The page's locale for Client code: dayjs switched to it, and the Intl locale provided below it.
+ *
+ * Both sit in this one Client reference because the root layout is under every route, and each Client
+ * reference it reaches is paid for by every page (`validate-area-client-reach.mjs`).
+ */
+export declare function PhiDayjsLocale({ locale, intlLocale, children, }: {
     locale?: string | null;
+    intlLocale: string;
     children: ReactNode;
-}): ReactNode;
+}): import("react").JSX.Element;
 export {};

package/components/root/phi-dayjs-locale.js

@@ -1,6 +1,7 @@
 "use client";
+import { jsx as _jsx } from "react/jsx-runtime";
 import { useEffect } from "react";
-import dayjs from "dayjs";
+import { PhiIntlLocaleProvider } from "./phi-intl-locale";
 const PHI_DAYJS_LOCALE_LOADERS = {
     ar: () => import("dayjs/locale/ar"),
     bg: () => import("dayjs/locale/bg"),
@@ -46,6 +47,12 @@ const PHI_DAYJS_LOCALE_LOADERS = {
     "zh-hant": () => import("dayjs/locale/zh-tw"),
     "zh-tw": () => import("dayjs/locale/zh-tw"),
 };
+/*
+ * The locale dayjs holds now. It starts as its own default, English, and English pages leave it there:
+ * dayjs is loaded only to switch it, so a page in English does not download it at all -- the date controls
+ * that use it bring it with them and find it already set to the page's locale.
+ */
+let appliedDayjsLocaleName = "en";
 function normalizeLocaleKey(input) {
     return input?.trim().replace(/_/g, "-").toLowerCase() ?? "";
 }
@@ -111,15 +118,24 @@ export function resolvePhiDayjsLocale(locale) {
     const base = normalized.split("-")[0];
     return PHI_DAYJS_LOCALE_RESOLUTIONS.get(base) ?? { key: "en", localeName: "en" };
 }
-export function PhiDayjsLocale({ locale, children }) {
+/**
+ * The page's locale for Client code: dayjs switched to it, and the Intl locale provided below it.
+ *
+ * Both sit in this one Client reference because the root layout is under every route, and each Client
+ * reference it reaches is paid for by every page (`validate-area-client-reach.mjs`).
+ */
+export function PhiDayjsLocale({ locale, intlLocale, children, }) {
     useEffect(() => {
         let active = true;
         async function applyLocale() {
             const resolved = resolvePhiDayjsLocale(locale);
+            if (resolved.localeName === appliedDayjsLocaleName)
+                return;
             const loader = PHI_DAYJS_LOCALE_LOADERS[resolved.key] ?? PHI_DAYJS_LOCALE_LOADERS.en;
-            await loader();
+            const [{ default: dayjs }] = await Promise.all([import("dayjs"), loader()]);
             if (active) {
                 dayjs.locale(resolved.localeName);
+                appliedDayjsLocaleName = resolved.localeName;
             }
         }
         void applyLocale();
@@ -127,5 +143,5 @@ export function PhiDayjsLocale({ locale, children }) {
             active = false;
         };
     }, [locale]);
-    return children;
+    return _jsx(PhiIntlLocaleProvider, { locale: intlLocale, children: children });
 }

package/components/root/phi-intl-locale.d.ts

@@ -0,0 +1,6 @@
+import { type ReactNode } from "react";
+export declare function PhiIntlLocaleProvider({ locale, children }: {
+    locale: string;
+    children: ReactNode;
+}): import("react").JSX.Element;
+export declare function usePhiIntlLocale(): string;

package/components/root/phi-intl-locale.js

@@ -0,0 +1,21 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { createContext, useContext } from "react";
+/**
+ * The page's Intl locale for Client code that formats dates and numbers.
+ *
+ * The browser's own locale is the visitor's machine, not the page they are reading: an English browser on
+ * `/de/...` would show English dates in a German page, and the server's render would show a third. The
+ * Root Layout sets it once from the resolved locale, the same value `<html lang>` carries.
+ */
+const PhiIntlLocaleContext = createContext(null);
+export function PhiIntlLocaleProvider({ locale, children }) {
+    return _jsx(PhiIntlLocaleContext.Provider, { value: locale, children: children });
+}
+export function usePhiIntlLocale() {
+    const locale = useContext(PhiIntlLocaleContext);
+    if (!locale) {
+        throw new Error("usePhiIntlLocale needs a PhiIntlLocaleProvider above it; the Root Layout sets one.");
+    }
+    return locale;
+}

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

@@ -7,9 +7,9 @@ import type { PhiThemeMode } from "../../theme/phi-theme-presets";
  *
  * Painted exactly once, fixed to the viewport so it does not scroll with Page content, and behind
  * everything else in the Root Layout: `z-index: -1` keeps it under the in-flow content, and the
- * `.ant-app` ground above it is transparent (styles/root.css) so this layer owns the page ground.
- * An unconfigured mode falls back to the resolved Ant Design layout background, which is what the
- * `.ant-app` rule painted before this layer existed -- the fallback look is unchanged.
+ * ground above it is transparent (styles/root.css) so this layer owns the page ground. An
+ * unconfigured mode falls back to the resolved Ant Design layout background, which is what the
+ * ground's own rule painted before this layer existed -- the fallback look is unchanged.
  *
  * Motion is the one part this layer resolves differently from a Region: it is the canonical Background
  * contract throughout, but only `parallax` describes something this layer can do. See

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

@@ -8,9 +8,9 @@ import { normalizePhiBackgroundWidgetConfig, resolvePhiBackgroundMotion, resolve
  *
  * Painted exactly once, fixed to the viewport so it does not scroll with Page content, and behind
  * everything else in the Root Layout: `z-index: -1` keeps it under the in-flow content, and the
- * `.ant-app` ground above it is transparent (styles/root.css) so this layer owns the page ground.
- * An unconfigured mode falls back to the resolved Ant Design layout background, which is what the
- * `.ant-app` rule painted before this layer existed -- the fallback look is unchanged.
+ * ground above it is transparent (styles/root.css) so this layer owns the page ground. An
+ * unconfigured mode falls back to the resolved Ant Design layout background, which is what the
+ * ground's own rule painted before this layer existed -- the fallback look is unchanged.
  *
  * Motion is the one part this layer resolves differently from a Region: it is the canonical Background
  * contract throughout, but only `parallax` describes something this layer can do. See

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

@@ -3,7 +3,8 @@ import "antd/dist/reset.css";
 import "../../styles/root.css";
 import "../../styles/layout.css";
 import "../../styles/control-shape.css";
-import type { PhiSiteConfig } from "../../gateway/site-config";
+import "../../styles/controls.css";
+import type { PhiSiteConfig } from "../../types/site-config";
 import type { PhiResolvedLocale } from "../../helpers/site-locale-config";
 import { type PhiThemeMode, type PhiThemePresetPlugin } from "../../theme/phi-theme-presets";
 import { type PhiFontCatalogue } from "../../theme/phi-font-catalogue";

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

@@ -1,18 +1,20 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { preload } from "react-dom";
 import { AntdRegistry } from "@ant-design/nextjs-registry";
-import AntdApp from "antd/es/app";
 import "antd/dist/reset.css";
 import "../../styles/root.css";
 import "../../styles/layout.css";
 import "../../styles/control-shape.css";
+import "../../styles/controls.css";
 import { getResolvedSiteConfig } from "../../gateway/site-config";
 import { loadPhiAntdLocale } from "../../helpers/antd-locale";
 import { PhiDayjsLocale } from "./phi-dayjs-locale";
 import { PhiRootRemProvider } from "./phi-root-rem-provider";
 import { PhiRootLiveThemeProvider } from "./phi-root-live-theme-provider";
+import { resolvePhiRootThemeState } from "./phi-root-theme-resolver";
 import { PhiSignalRuntimePartitionProvider } from "../runtime/runtime-signal-partition";
 import { PhiCoreRuntimeApplicationAdapter } from "../runtime/core-runtime-application-adapter";
+import { getPhiSessionLabels } from "../widgets/label-sets/session";
 import { PHI_CORE_THEME_PRESET_PLUGINS, } from "../../theme/phi-theme-presets";
 import { resolvePhiPublishedRootTheme } from "../../theme/phi-published-root-style";
 import { resolvePhiSiteThemeFonts } from "../../theme/phi-theme-fonts.server";
@@ -53,6 +55,12 @@ export async function PhiRootLayout({ children, apiBaseUrl, internalToken, siteK
     const siteTheme = await projectPhiSiteThemeRootBackground(siteThemeRecord, { apiBaseUrl, internalToken, siteKey });
     const antdLocale = await loadPhiAntdLocale(resolvedLocale?.locale ?? resolvedLocale?.intlLocale);
     const resolvedThemeMode = resolvePhiThemeMode(themeModePreference, browserColorScheme);
+    // What the Core Runtime Controller says when a sign-out it was asked for fails.
+    const sessionLabels = await getPhiSessionLabels({
+        apiBaseUrl,
+        internalToken,
+        locale: resolvedLocale?.locale ?? site.defaultLocale,
+    });
     // Keep the basiset explicit and self-hosted; accent/display stay as open slots for later.
     /*
      * A slot naming an Asset is answered before the catalogue is consulted: that is a typeface the Site
@@ -97,13 +105,14 @@ export async function PhiRootLayout({ children, apiBaseUrl, internalToken, siteK
         serif: serifFont,
         display: displayFont,
     });
+    const themeState = resolvePhiRootThemeState({ siteTheme, fonts: themeFonts, presets: themePresets });
     const publishedRootTheme = resolvePhiPublishedRootTheme({
         siteTheme: siteThemeRecord,
         mode: resolvedThemeMode,
         remRootValue,
         themePresets,
     });
-    return (_jsxs(PhiRootRemProvider, { rootValue: remRootValue, children: [assetFonts.css ? (_jsx("style", { href: `phi-site-fonts:${site.key}`, precedence: "default", dangerouslySetInnerHTML: { __html: assetFonts.css } })) : null, _jsx(AntdRegistry, { children: _jsx(PhiSignalRuntimePartitionProvider, { id: `site:${site.key}`, kind: "site", context: { siteKey: site.key }, children: _jsx(PhiRootLiveThemeProvider, { siteKey: site.key, siteTheme: siteTheme, locale: antdLocale, initialMode: resolvedThemeMode, themeModePreference: themeModePreference, initialLocale: resolvedLocale?.locale ?? site.defaultLocale, availableLocales: site.availableLocales.map((option) => option.code), fonts: themeFonts, fontFamilies: fontCatalogue.entries.map(({ family, cssVariable }) => ({ family, cssVariable })), presets: themePresets, rootClassName: fontCatalogue.className, rootStyle: headingFontFamily
+    return (_jsxs(PhiRootRemProvider, { rootValue: remRootValue, children: [assetFonts.css ? (_jsx("style", { href: `phi-site-fonts:${site.key}`, precedence: "default", dangerouslySetInnerHTML: { __html: assetFonts.css } })) : null, _jsx(AntdRegistry, { children: _jsx(PhiSignalRuntimePartitionProvider, { id: `site:${site.key}`, kind: "site", context: { siteKey: site.key }, children: _jsx(PhiRootLiveThemeProvider, { siteKey: site.key, siteName: site.name, siteTheme: siteTheme, locale: antdLocale, initialMode: resolvedThemeMode, themeModePreference: themeModePreference, initialLocale: resolvedLocale?.locale ?? site.defaultLocale, availableLocales: site.availableLocales.map((option) => option.code), fonts: themeFonts, themeState: themeState, fontFamilies: fontCatalogue.entries.map(({ family, cssVariable }) => ({ family, cssVariable })), presets: themePresets, rootClassName: fontCatalogue.className, rootStyle: headingFontFamily
                             ? { ...publishedRootTheme.style, [PHI_THEME_HEADING_FONT_VARIABLE]: headingFontFamily }
-                            : publishedRootTheme.style, remRootValue: remRootValue, children: _jsxs(AntdApp, { children: [_jsx(PhiCoreRuntimeApplicationAdapter, {}), _jsx(PhiDayjsLocale, { locale: resolvedLocale?.locale ?? resolvedLocale?.intlLocale, children: children })] }) }) }) })] }));
+                            : publishedRootTheme.style, remRootValue: remRootValue, children: _jsxs("div", { "data-phi-app-ground": "true", children: [_jsx(PhiCoreRuntimeApplicationAdapter, { labels: sessionLabels }), _jsx(PhiDayjsLocale, { locale: resolvedLocale?.locale ?? resolvedLocale?.intlLocale, intlLocale: resolvedLocale?.intlLocale ?? site.defaultLocale, children: children })] }) }) }) })] }));
 }

package/components/root/phi-root-live-theme-provider.d.ts

@@ -1,15 +1,18 @@
 import type { ConfigProviderProps } from "antd";
 import { type CSSProperties, type ReactNode } from "react";
-import type { PhiSiteTheme } from "../../gateway/site-config";
+import type { PhiSiteTheme } from "../../types/site-config";
 import type { PhiSiteThemeBrand } from "../../types/site-theme";
-import { type PhiRootThemeFonts } from "./phi-root-theme-resolver";
+import type { PhiRootThemeFonts, PhiRootThemeState } from "./phi-root-theme-resolver";
 import type { PhiThemeMode, PhiThemePresetPlugin } from "../../theme/phi-theme-presets";
 import { type PhiThemeModePreference } from "../../theme/phi-theme-mode";
 import { type PhiFontCatalogueFamily } from "./phi-config-provider";
 export declare function usePhiSiteBrand(): PhiSiteThemeBrand | null;
-export declare function PhiRootLiveThemeProvider({ children, siteKey, siteTheme, locale, initialMode, themeModePreference, initialLocale, availableLocales, fonts, fontFamilies, presets, rootClassName, rootStyle, remRootValue, }: {
+export declare function usePhiSiteWordmarkText(): string;
+export declare function PhiRootLiveThemeProvider({ children, siteKey, siteName, siteTheme, locale, initialMode, themeModePreference, initialLocale, availableLocales, fonts, themeState, fontFamilies, presets, rootClassName, rootStyle, remRootValue, }: {
     children: ReactNode;
     siteKey: string;
+    /** The name the Site is filed under, which is what its Wordmark says where none is set. */
+    siteName?: string | null;
     siteTheme: PhiSiteTheme;
     locale: ConfigProviderProps["locale"];
     initialMode: PhiThemeMode;
@@ -18,6 +21,8 @@ export declare function PhiRootLiveThemeProvider({ children, siteKey, siteTheme,
     initialLocale: string;
     availableLocales: readonly string[];
     fonts: PhiRootThemeFonts;
+    /** The Theme resolved on the Server for both modes, with the Shell Chrome Overlay's properties. */
+    themeState: PhiRootThemeState;
     /** The families an author may choose from: this package's plus the installed Modules'. */
     fontFamilies: readonly PhiFontCatalogueFamily[];
     presets: readonly PhiThemePresetPlugin[];

package/components/root/phi-root-live-theme-provider.js

@@ -1,13 +1,12 @@
 "use client";
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
 import { createContext, useContext, useEffect, useMemo, useRef, useState } from "react";
+import { resolvePhiBrandWordmarkTextFrom } from "../../helpers/brand-wordmark";
 import { usePhiSignalListener } from "../runtime/runtime-signal-bus";
-import { resolvePhiRootTheme, } from "./phi-root-theme-resolver";
-import { applyPhiThemeModeToDocument, writePhiColorSchemeHint, } from "../../theme/phi-theme-mode";
+import { applyPhiThemeModeToDocument, resolvePhiMountedThemeModePreference, writePhiColorSchemeHint, storePhiThemeModePreferenceOnAccount, writePhiThemeModePreference, } from "../../theme/phi-theme-mode";
 import { resolvePhiPublishedThemeCustomColors } from "../../theme/phi-theme-palette";
 import { PhiConfigProvider } from "./phi-config-provider";
 import { PhiRootBackgroundLayer } from "./phi-root-background";
-import { resolvePhiShellChromeOverlayVariables } from "./phi-shell-chrome-overlay";
 import { resolvePhiControlShape } from "../../theme/phi-control-shape";
 import { PHI_SIGNAL_VALUE_SCHEMAS, } from "../../types/signals";
 import { createPhiCoreRuntimeControllerAddress } from "../runtime/core-runtime-controller-address";
@@ -25,13 +24,27 @@ const PhiSiteBrandContext = createContext(null);
 export function usePhiSiteBrand() {
     return useContext(PhiSiteBrandContext);
 }
+/**
+ * What the Site is called in writing, held beside the Brand because the two answer together.
+ *
+ * The Wordmark falls back to the Site's name, and the name lives on the runtime -- which the Builder
+ * canvas does not have. Every authoring half there is handed a stub Site called "Preview", so a Widget
+ * that resolved the Wordmark from its runtime wrote "Preview" on the canvas while the Logo next to it,
+ * read from the Brand above, was the Site's own. Held here, both halves answer from the same place, and
+ * both follow a live Theme draft: clearing the last Wordmark part shows the name, at once.
+ */
+const PhiSiteWordmarkTextContext = createContext("");
+export function usePhiSiteWordmarkText() {
+    return useContext(PhiSiteWordmarkTextContext);
+}
 function resolveStringSignalValue(signal) {
     return typeof signal.value === "string" ? signal.value.trim() : "";
 }
-export function PhiRootLiveThemeProvider({ children, siteKey, siteTheme, locale, initialMode, themeModePreference, initialLocale, availableLocales, fonts, fontFamilies, presets, rootClassName, rootStyle, remRootValue, }) {
+export function PhiRootLiveThemeProvider({ children, siteKey, siteName, siteTheme, locale, initialMode, themeModePreference, initialLocale, availableLocales, fonts, themeState, fontFamilies, presets, rootClassName, rootStyle, remRootValue, }) {
     const signalPartition = usePhiSignalRuntimePartition();
     const coreAddress = createPhiCoreRuntimeControllerAddress();
     const [liveSiteTheme, setLiveSiteTheme] = useState(siteTheme);
+    const wordmarkText = resolvePhiBrandWordmarkTextFrom(liveSiteTheme.brand, siteName, siteKey);
     const [mode, setMode] = useState(initialMode);
     /*
      * A live Theme signal - the Builder's dark mode switch, or a Theme draft preview - states what the
@@ -39,17 +52,47 @@ export function PhiRootLiveThemeProvider({ children, siteKey, siteTheme, locale,
      * must not pull the page back out from under them.
      */
     const liveModeOverride = useRef(false);
+    /*
+     * And a mode the Server now states is taken, because the Server only states a new one when somebody
+     * asked for it.
+     *
+     * `useState(initialMode)` reads the prop once. Everything that switches the mode afterwards is a
+     * live signal or the operating system, so a viewer who changed the setting on their Profile page
+     * saw the page stay in the mode it had loaded in: the Page came back with the new one in the
+     * payload and this provider was already mounted and no longer listening.
+     *
+     * Compared against the last prop rather than against `mode`, so a live Theme draft in the Builder
+     * survives a re-render that carries the same answer as before.
+     */
+    const lastStatedMode = useRef(initialMode);
+    useEffect(() => {
+        if (lastStatedMode.current === initialMode) {
+            return;
+        }
+        lastStatedMode.current = initialMode;
+        setMode(initialMode);
+    }, [initialMode]);
     const [pageDescription, setPageDescription] = useState(null);
     const [openGraphImage, setOpenGraphImage] = useState(null);
     const [canonicalUrl, setCanonicalUrl] = useState(null);
-    const resolvedTheme = useMemo(() => resolvePhiRootTheme({ siteTheme: liveSiteTheme, mode, fonts, presets }), [fonts, liveSiteTheme, mode, presets]);
+    /*
+     * A live Theme draft, resolved in the browser -- the only case that needs the resolver here.
+     *
+     * The page arrives with both modes resolved on the Server, so switching modes only picks one. A draft
+     * from the Builder's Theme editor is a Theme the Server has never seen; the resolver is fetched for it
+     * then, and not shipped to every visitor of every page for that one moment. Until it is resolved, the
+     * frame keeps the Theme it has; a later draft outranks an earlier one still resolving.
+     */
+    const [liveThemeState, setLiveThemeState] = useState(null);
+    const liveThemeRequest = useRef(0);
+    const activeThemeState = liveThemeState ?? themeState;
     const customColors = useMemo(() => resolvePhiPublishedThemeCustomColors(liveSiteTheme, mode, presets), [liveSiteTheme, mode, presets]);
     /*
      * The Shell Chrome Overlay travels as custom properties on the Root Layout element, both modes at
      * once, because the Regions that paint it are rendered far below this provider and switch modes
      * through `data-phi-theme-mode` rather than through a re-render.
      */
-    const chromeOverlayStyle = useMemo(() => ({ ...rootStyle, ...resolvePhiShellChromeOverlayVariables(liveSiteTheme.root) }), [liveSiteTheme.root, rootStyle]);
+    const chromeOverlayStyle = useMemo(() => ({ ...rootStyle, ...activeThemeState.chromeOverlayVariables }), [activeThemeState.chromeOverlayVariables, rootStyle]);
     useEffect(() => registerPhiSignalInstance(signalPartition, {
         address: coreAddress,
         scope: "site",
@@ -73,7 +116,8 @@ export function PhiRootLiveThemeProvider({ children, siteKey, siteTheme, locale,
      * stored so the next server render starts in the right mode instead of correcting itself.
      */
     useEffect(() => {
-        if (themeModePreference !== "system") {
+        // A choice in the cookie outranks the `system` a static document hands everybody.
+        if (resolvePhiMountedThemeModePreference(themeModePreference, document.cookie) !== "system") {
             return;
         }
         const query = window.matchMedia("(prefers-color-scheme: dark)");
@@ -129,15 +173,37 @@ export function PhiRootLiveThemeProvider({ children, siteKey, siteTheme, locale,
              */
             const nextTheme = signal.value;
             setLiveSiteTheme(nextTheme);
+            const request = ++liveThemeRequest.current;
+            void import("./phi-root-theme-resolver").then(({ resolvePhiRootThemeState }) => {
+                if (request !== liveThemeRequest.current)
+                    return;
+                setLiveThemeState(resolvePhiRootThemeState({ siteTheme: nextTheme, fonts, presets }));
+            });
             liveModeOverride.current = true;
             setMode(nextTheme.mode === "dark" ? "dark" : "light");
             return;
         }
+        /*
+         * The mode switch is a viewer choosing, so the choice is kept rather than held until they leave.
+         *
+         * This is the one live channel that is a person stating a preference: the `theme` signal above is
+         * the Builder previewing a Theme, which is about the Site and belongs to nobody's browser. Written
+         * here rather than in the switch Control, because the Controls that offer it are several -- the
+         * Welcome Page, the Builder, Admin -- and every one of them would otherwise have to remember.
+         */
         if (signal.channel === "themeMode" &&
             signal.action === "change" &&
             signal.valueType === "boolean") {
+            const next = signal.value ? "dark" : "light";
             liveModeOverride.current = true;
-            setMode(signal.value ? "dark" : "light");
+            setMode(next);
+            writePhiThemeModePreference(next);
+            /*
+             * And on the account, for whoever has one. The cookie above is what this browser reads next; this
+             * is what every other browser reads. Not awaited, because the mode is already on screen and the
+             * person is not waiting for a round trip to see what they just chose.
+             */
+            void storePhiThemeModePreferenceOnAccount(next);
             return;
         }
         if (signal.channel === "locale" && signal.action === "change" && signal.valueType === "string") {
@@ -150,7 +216,7 @@ export function PhiRootLiveThemeProvider({ children, siteKey, siteTheme, locale,
         scopes: ["site"],
         receiver: coreAddress,
     });
-    return (_jsxs(_Fragment, { children: [pageDescription ? (_jsx("meta", { name: "description", content: pageDescription, "data-phi-runtime-metadata": "pageDescription" })) : null, openGraphImage ? (_jsx("meta", { property: "og:image", content: openGraphImage, "data-phi-runtime-metadata": "openGraphImage" })) : null, canonicalUrl ? (_jsx("link", { rel: "canonical", href: canonicalUrl, "data-phi-runtime-metadata": "canonicalUrl" })) : null, _jsxs(PhiConfigProvider, { customColors: customColors, fonts: fonts, fontFamilies: fontFamilies, locale: locale, mode: mode, controlShape: resolvePhiControlShape(liveSiteTheme.shape?.controls), theme: resolvedTheme.theme, presets: presets, rootClassName: rootClassName, rootStyle: chromeOverlayStyle, remRootValue: remRootValue, children: [_jsx(PhiRootBackgroundLayer, { root: liveSiteTheme.root, mode: mode }), _jsx(PhiSiteBrandContext.Provider, { value: liveSiteTheme.brand ?? null, children: children })] })] }));
+    return (_jsxs(_Fragment, { children: [pageDescription ? (_jsx("meta", { name: "description", content: pageDescription, "data-phi-runtime-metadata": "pageDescription" })) : null, openGraphImage ? (_jsx("meta", { property: "og:image", content: openGraphImage, "data-phi-runtime-metadata": "openGraphImage" })) : null, canonicalUrl ? (_jsx("link", { rel: "canonical", href: canonicalUrl, "data-phi-runtime-metadata": "canonicalUrl" })) : null, _jsxs(PhiConfigProvider, { customColors: customColors, fonts: fonts, fontFamilies: fontFamilies, locale: locale, mode: mode, controlShape: resolvePhiControlShape(liveSiteTheme.shape?.controls), theme: activeThemeState.themes[mode], presets: presets, rootClassName: rootClassName, rootStyle: chromeOverlayStyle, remRootValue: remRootValue, children: [_jsx(PhiRootBackgroundLayer, { root: liveSiteTheme.root, mode: mode }), _jsx(PhiSiteBrandContext.Provider, { value: liveSiteTheme.brand ?? null, children: _jsx(PhiSiteWordmarkTextContext.Provider, { value: wordmarkText, children: children }) })] })] }));
 }
 /**
  * The colour-scheme bootstrap script, written into the server's HTML and nowhere else.

package/components/root/phi-root-theme-resolver.d.ts

@@ -1,4 +1,5 @@
-import type { PhiSiteTheme } from "../../gateway/site-config";
+import type { PhiSiteTheme } from "../../types/site-config";
+import { type PhiShellChromeOverlayVariables } from "./phi-shell-chrome-overlay";
 import { type PhiThemeMode, type PhiThemePresetPlugin } from "../../theme/phi-theme-presets";
 export type PhiRootThemeFonts = {
     body?: string;
@@ -24,3 +25,22 @@ export declare function resolvePhiRootTheme({ siteTheme, mode, fonts, presets, }
     fonts: PhiRootThemeFonts;
     presets: readonly PhiThemePresetPlugin[];
 }): PhiResolvedRootTheme;
+export type PhiRootThemeByMode = Record<PhiThemeMode, PhiResolvedRootTheme["theme"]>;
+/**
+ * What the root needs of a Theme in the browser, resolved before it gets there.
+ *
+ * Both modes, because the mode switch changes the page without a round trip, and the Shell Chrome
+ * Overlay's custom properties, which carry both modes themselves. Everything here is plain data, so the
+ * Server resolves it for the page and the live provider only picks a mode. The resolution itself --
+ * this file, the Shell region styles, the Overlay, the component token builders -- is fetched by the
+ * browser only when a Theme draft arrives live from the Builder.
+ */
+export type PhiRootThemeState = {
+    themes: PhiRootThemeByMode;
+    chromeOverlayVariables: PhiShellChromeOverlayVariables;
+};
+export declare function resolvePhiRootThemeState(input: {
+    siteTheme: PhiSiteTheme;
+    fonts: PhiRootThemeFonts;
+    presets: readonly PhiThemePresetPlugin[];
+}): PhiRootThemeState;

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

@@ -1,9 +1,11 @@
+import { resolvePhiShellChromeOverlayVariables, } from "./phi-shell-chrome-overlay";
 import { resolvePhiShellRegionBackground, resolvePhiShellRegionColor, } from "../../helpers/shell-region-style";
 import { createPhiAntdThemeCssVarKey, resolvePhiAntdAliasTokens, } from "../../theme/phi-antd-token-resolver";
 import { buildPhiComponentTokens, buildPhiThemeStructuralTokens, } from "../../theme/phi-theme";
-import { resolvePhiThemePresetPlugin, resolvePhiThemeColorTokens, } from "../../theme/phi-theme-presets";
+import { PHI_THEME_PALETTE_MODE_SEED_KEYS, resolvePhiThemePresetPlugin, resolvePhiThemeColorTokens, } from "../../theme/phi-theme-presets";
+import { assertPhiThemeVocabulary } from "../../theme/phi-theme-tokens";
 import { applyPhiButtonShadowComponentTokens } from "../../theme/phi-button-shadow";
-import { applyPhiControlShapeComponentTokens, resolvePhiControlShape, } from "../../theme/phi-control-shape";
+import { applyPhiControlShapeComponentTokens, applyPhiSurfaceShapeComponentTokens, resolvePhiControlShape, } from "../../theme/phi-control-shape";
 const PHI_DEFAULT_DARK_NAV_BACKGROUND = "#001529";
 function mergeComponentThemes(defaults, overrides) {
     if (!overrides) {
@@ -25,6 +27,11 @@ export function resolvePhiRootTheme({ siteTheme, mode, fonts, presets, }) {
      * Site's proportions. The palette merge happens before the tokens resolve, so a shared seed the Site
      * owns is never undercut by a mode override the block declares.
      */
+    assertPhiThemeVocabulary({
+        styleToken: siteTheme?.style?.token,
+        modeSeedKeys: PHI_THEME_PALETTE_MODE_SEED_KEYS,
+        source: "The Site's own Theme",
+    });
     const colorTokens = resolvePhiThemeColorTokens(themePreset, siteTheme?.palette, mode);
     const sharedTokenDefaults = buildPhiThemeStructuralTokens();
     const resolvedThemeTokens = {
@@ -67,7 +74,8 @@ export function resolvePhiRootTheme({ siteTheme, mode, fonts, presets, }) {
                 : {}),
         },
     });
-    const components = applyPhiControlShapeComponentTokens(mergeComponentThemes(sharedComponentDefaults, applyPhiButtonShadowComponentTokens(siteTheme?.components, siteTheme?.buttons, mode)), resolvePhiControlShape(siteTheme.shape?.controls), effectiveThemeTokens);
+    const resolvedControlShape = resolvePhiControlShape(siteTheme.shape?.controls);
+    const components = applyPhiSurfaceShapeComponentTokens(applyPhiControlShapeComponentTokens(mergeComponentThemes(sharedComponentDefaults, applyPhiButtonShadowComponentTokens(siteTheme?.components, siteTheme?.buttons, mode)), resolvedControlShape, effectiveThemeTokens), resolvedControlShape, effectiveThemeTokens);
     const token = {
         ...effectiveThemeTokens,
     };
@@ -83,3 +91,12 @@ export function resolvePhiRootTheme({ siteTheme, mode, fonts, presets, }) {
         },
     };
 }
+export function resolvePhiRootThemeState(input) {
+    return {
+        themes: {
+            light: resolvePhiRootTheme({ ...input, mode: "light" }).theme,
+            dark: resolvePhiRootTheme({ ...input, mode: "dark" }).theme,
+        },
+        chromeOverlayVariables: resolvePhiShellChromeOverlayVariables(input.siteTheme.root),
+    };
+}

package/components/runtime/application-feedback-host.d.ts

@@ -0,0 +1,35 @@
+import type { PhiCoreRuntimeMessageValue, PhiCoreRuntimeNotificationValue } from "../../types/core-runtime-controller";
+/**
+ * One thing the runtime was asked to say, waiting to be said.
+ *
+ * Keyed, because the queue outlives the moment: what arrives while the host is still being fetched has
+ * to be told apart from what has already been shown, and a message is not unique by its own content --
+ * the same "Saved" twice is two announcements.
+ */
+export type PhiApplicationFeedbackRequest = {
+    key: number;
+    kind: "message";
+    value: PhiCoreRuntimeMessageValue;
+} | {
+    key: number;
+    kind: "notification";
+    value: PhiCoreRuntimeNotificationValue;
+};
+export type PhiApplicationFeedbackHostProps = {
+    requests: readonly PhiApplicationFeedbackRequest[];
+    onPlayed: (keys: readonly number[]) => void;
+};
+/**
+ * Ant Design's `App`, mounted when the Site first has something to say.
+ *
+ * It used to wrap every page from the root layout, which put the message, notification and modal
+ * runtimes into the first load of every route: measured on the Public landing page, 62 KB raw and
+ * 23 KB over the wire, on a page that draws four texts and one switch. Almost none of it is the
+ * `rc-*` packages -- 52 KB is Ant Design's own `app`, `message`, `notification` and `modal` with
+ * their style modules.
+ *
+ * It is a sibling of the page rather than its parent now, because it no longer has anything to
+ * provide to it: the Core application adapter is the only consumer of `App.useApp()`, and it is
+ * here. A confirmation with nothing to anchor to is `usePhiConfirmDialog`, not an imperative modal.
+ */
+export declare function PhiApplicationFeedbackHost({ requests, onPlayed }: PhiApplicationFeedbackHostProps): import("react").JSX.Element;

package/components/runtime/application-feedback-host.js

@@ -0,0 +1,66 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useEffect, useRef } from "react";
+import { App } from "antd";
+function PhiApplicationFeedbackPlayer({ requests, onPlayed }) {
+    const { message, notification } = App.useApp();
+    /*
+     * What has already been shown, remembered here rather than derived from the queue.
+     *
+     * The queue is a prop: it still holds a request during the render that follows showing it, and in
+     * development an effect runs twice on purpose. Either would announce the same thing again.
+     */
+    const played = useRef(new Set());
+    useEffect(() => {
+        const shown = [];
+        for (const request of requests) {
+            if (played.current.has(request.key))
+                continue;
+            played.current.add(request.key);
+            shown.push(request.key);
+            if (request.kind === "notification") {
+                notification[request.value.level]({
+                    title: request.value.title,
+                    ...(request.value.description ? { description: request.value.description } : {}),
+                    ...(request.value.durationSeconds != null
+                        ? { duration: request.value.durationSeconds }
+                        : {}),
+                    ...(request.value.placement ? { placement: request.value.placement } : {}),
+                    ...(request.value.showTimeoutProgress != null
+                        ? { showProgress: request.value.showTimeoutProgress }
+                        : {}),
+                    role: request.value.level === "error" || request.value.level === "warning"
+                        ? "alert"
+                        : "status",
+                });
+                continue;
+            }
+            message.open({
+                type: request.value.level,
+                content: request.value.content,
+                ...(request.value.durationSeconds != null
+                    ? { duration: request.value.durationSeconds }
+                    : {}),
+            });
+        }
+        if (shown.length > 0)
+            onPlayed(shown);
+    }, [message, notification, onPlayed, requests]);
+    return null;
+}
+/**
+ * Ant Design's `App`, mounted when the Site first has something to say.
+ *
+ * It used to wrap every page from the root layout, which put the message, notification and modal
+ * runtimes into the first load of every route: measured on the Public landing page, 62 KB raw and
+ * 23 KB over the wire, on a page that draws four texts and one switch. Almost none of it is the
+ * `rc-*` packages -- 52 KB is Ant Design's own `app`, `message`, `notification` and `modal` with
+ * their style modules.
+ *
+ * It is a sibling of the page rather than its parent now, because it no longer has anything to
+ * provide to it: the Core application adapter is the only consumer of `App.useApp()`, and it is
+ * here. A confirmation with nothing to anchor to is `usePhiConfirmDialog`, not an imperative modal.
+ */
+export function PhiApplicationFeedbackHost({ requests, onPlayed }) {
+    return (_jsx(App, { children: _jsx(PhiApplicationFeedbackPlayer, { requests: requests, onPlayed: onPlayed }) }));
+}

package/components/runtime/core-runtime-application-adapter.d.ts

@@ -1 +1,8 @@
-export declare function PhiCoreRuntimeApplicationAdapter(): null;
+/** The Controller's own words, translated on the server for the Site's locale. */
+export type PhiCoreRuntimeApplicationLabels = {
+    /** Said when a `session/clear` could not end the session. */
+    signOutFailed: string;
+};
+export declare function PhiCoreRuntimeApplicationAdapter({ labels, }: {
+    labels: PhiCoreRuntimeApplicationLabels;
+}): import("react").JSX.Element | null;