@phis/ui 0.2.0 → 0.3.0

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

@@ -82,21 +82,83 @@ export function resolvePhiRootTheme({ siteTheme, mode, fonts, presets, }) {
     return {
         mode,
         theme: {
+            /*
+             * Ant Design's structure is not rendered: it comes from `@phis/ui/antd-static.css`, and only the
+             * custom properties a Theme decides are rendered here. Every nested provider inherits both flags --
+             * the tone scopes and the Theme workspace's, which inherits nothing else.
+             *
+             * Unhashed because that file is one file for development and production, and Ant Design hashes
+             * its class names differently in each. The hash only ever kept two Ant Design versions on one page
+             * apart, and it sat in `:where()`, so dropping it changes no specificity.
+             */
+            hashed: false,
+            zeroRuntime: true,
             cssVar: {
                 prefix: "ant",
-                key: createPhiAntdThemeCssVarKey("root", { mode, token, components }),
+                /*
+                 * Named after what the tokens are resolved from, not after the tokens: the same Theme record,
+                 * fonts, palette block and mode always resolve to the same tokens, and the record is a fraction
+                 * of their size. Hashing the resolved tokens and component tokens cost 1-2 ms per request
+                 * (measured 04.10.2026).
+                 */
+                key: createPhiAntdThemeCssVarKey("root", { mode, siteTheme, fonts, preset: themePreset }),
             },
             token,
             components,
         },
     };
 }
+/*
+ * Resolved states, by what they are resolved from.
+ *
+ * Every page resolves the Site's Theme for both modes, and for a Theme that has not changed the answer
+ * is the same every time: about 3-4 ms of derivation per request for nothing (measured 04.10.2026). The
+ * key is the content -- Theme record, fonts, the palette block it follows -- so a changed Theme is a new
+ * key, and nothing here has to be told about a publish or can go stale; it holds per process and needs
+ * no coordination between processes. A Site has one published Theme, and drafts from the Builder are
+ * resolved in the browser, so a handful of entries is all this ever holds; the bound only keeps it so.
+ */
+const PHI_ROOT_THEME_STATE_LIMIT = 16;
+const rootThemeStates = new Map();
+function freezeDeep(value) {
+    if (value && typeof value === "object" && !Object.isFrozen(value)) {
+        Object.freeze(value);
+        for (const entry of Object.values(value))
+            freezeDeep(entry);
+    }
+    return value;
+}
+/** Forget every resolved state. For tests. */
+export function clearPhiRootThemeStates() {
+    rootThemeStates.clear();
+}
 export function resolvePhiRootThemeState(input) {
-    return {
+    const key = createPhiAntdThemeCssVarKey("state", {
+        siteTheme: input.siteTheme,
+        fonts: input.fonts,
+        preset: resolvePhiThemePresetPlugin(input.presets, input.siteTheme?.preset),
+    });
+    const known = rootThemeStates.get(key);
+    if (known) {
+        // Read last, evicted last.
+        rootThemeStates.delete(key);
+        rootThemeStates.set(key, known);
+        return known;
+    }
+    /*
+     * Frozen, because every page that resolves this Theme is handed the same object: a reader that
+     * wrote into it would be writing into every other page's Theme.
+     */
+    const state = freezeDeep({
         themes: {
             light: resolvePhiRootTheme({ ...input, mode: "light" }).theme,
             dark: resolvePhiRootTheme({ ...input, mode: "dark" }).theme,
         },
         chromeOverlayVariables: resolvePhiShellChromeOverlayVariables(input.siteTheme.root),
-    };
+    });
+    rootThemeStates.set(key, state);
+    if (rootThemeStates.size > PHI_ROOT_THEME_STATE_LIMIT) {
+        rootThemeStates.delete(rootThemeStates.keys().next().value);
+    }
+    return state;
 }

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

@@ -1,8 +1,9 @@
 import type { CSSProperties } from "react";
 import { type PhiBackgroundImageSourceKind, type PhiBackgroundMotionMode, type PhiCmsBackgroundWidgetConfig } from "../widgets/config/background";
-import type { PhiLayoutEffectId, PhiShadow } from "../../types/layout-style";
+import type { PhiBackgroundFilter, PhiGlassLayoutEffectId, PhiShadow } from "../../types/layout-style";
 import type { PhiSiteThemeRoot } from "../../types/site-theme";
 import type { PhiThemeMode } from "../../theme/phi-theme-presets";
+import type { PhiCmsRegionReveal } from "../../types/cms-presets";
 /**
  * The Shell Chrome Overlay (SHELL.md "Root Background and Shell Backdrop Layers").
  *
@@ -18,16 +19,17 @@ import type { PhiThemeMode } from "../../theme/phi-theme-presets";
  * seam.
  */
 /**
- * The Effects the overlay offers and honours, which are the two glass panes.
+ * The Filters the overlay offers and honours, which are the two glass panes.
  *
- * The overlay is not a layer above the Chrome, it is the Chrome's own ground, so an Effect here acts on
- * the Region itself: `blur` and `dim` are `filter`, which would blur and darken the Header's own text.
- * A pane acts on what is behind the Region instead, which is exactly what a shared frame over a
- * scrolling Page wants, and both strengths of it belong to a frame -- `glass` where the Page should
- * read as frosted underneath, `haze` where it should stay almost legible. A wash of colour over the
- * frame is an Overlay rather than an Effect, and the overlay offers those unnarrowed.
+ * The overlay is not a layer above the Chrome, it is the Chrome's own ground, handed to the Regions as
+ * custom properties rather than as a layer of its own -- so there is no separate paint for `blur` to
+ * soften without softening the Header's text. A pane acts on what is behind the Region instead, which is
+ * exactly what a shared frame over a scrolling Page wants, and both strengths of it belong to a frame --
+ * `glass` where the Page should read as frosted underneath, `haze` where it should stay almost legible.
+ * A wash of colour over the frame is an Overlay rather than a Filter, and the overlay offers those
+ * unnarrowed.
  */
-export declare const PHI_SHELL_CHROME_OVERLAY_EFFECTS: readonly PhiLayoutEffectId[];
+export declare const PHI_SHELL_CHROME_OVERLAY_FILTERS: readonly PhiBackgroundFilter[];
 /**
  * The Base kinds the overlay offers and honours, which is the whole contract.
  *
@@ -55,33 +57,25 @@ 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>;
-/**
- * The Regions that paint the overlay.
- *
- * The Shell grid tiles completely, so once Content and Hero are taken out what is left is exactly the
- * frame. Content and Hero stay out because the overlay would paint over their content, and a Drawer is
- * an Overlay surface rather than Shell chrome.
- */
-export declare const PHI_SHELL_CHROME_OVERLAY_REGION_KEYS: readonly string[];
 /**
  * Whether this Region paints the shared overlay, which it does only while it authored nothing itself.
  *
  * 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 structured Background config, the plain
- * ground string a Region or the Shell record can set, and the Region's own Effect. Reading only the
+ * 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.
  */
-export declare function phiRegionUsesShellChromeOverlay({ regionKey, backgroundConfig, effect, grounds, }: {
+export declare function phiRegionUsesShellChromeOverlay({ regionKey, backgroundConfig, pane, grounds, }: {
     regionKey: string;
     backgroundConfig?: unknown;
-    effect?: PhiLayoutEffectId | null;
+    pane?: PhiGlassLayoutEffectId | null;
     grounds: readonly (string | number | null | undefined)[];
 }): boolean;
 /**
  * The overlay as this surface renders it, narrowed to what it offers.
  *
- * A stored value is never rewritten. A Base or an Effect the overlay does not offer simply resolves
+ * A stored value is never rewritten. A Base or a Filter the overlay does not offer simply resolves
  * away, which is what the Control shows for it too.
  */
 export declare function resolvePhiShellChromeOverlayConfig(config: unknown): PhiCmsBackgroundWidgetConfig;
@@ -105,6 +99,7 @@ export type PhiShellChromePaneBand = {
     offsetTop?: string | number | null;
     height?: string | number | null;
 } | null | undefined;
+export declare function readPhiShellChromePanePixels(value: string | number | null | undefined): number | null;
 /**
  * Where the Header pane sticks, which is the one thing about it the grid cannot answer.
  *
@@ -123,6 +118,36 @@ export type PhiShellChromePaneBand = {
  * scrolling; a pane that sticks at a guessed offset is wrong the whole time.
  */
 export declare function resolvePhiShellChromePaneStickyTop(bands: readonly PhiShellChromePaneBand[]): string | null;
+/**
+ * The room `header_top` holds, published on the Shell element while the browser decides it (SHELL.md
+ * "Region visibility per Page"): `extent` is the height of its track, `stack` the part of the viewport's
+ * top a `scroll-up` band holds right now.
+ */
+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";
+/**
+ * How `header_top` behaves where the browser decides it, as far as the Header pane is concerned.
+ */
+export type PhiShellHeaderTopBehaviour = {
+    /** It stands on some Pages and not on others. */
+    scoped: boolean;
+    reveal: PhiCmsRegionReveal;
+};
+/**
+ * Where the Header pane sticks when `header_top` may come and go.
+ *
+ * The server knows the first Page and nothing after it, so the band's travel is written as the room
+ * the browser publishes, with the server's own answer as the fallback until it does:
+ *
+ * - `hover` takes no room at all, and the pane is the bands below it.
+ * - `scroll-up` sticks, and the pane rises by exactly the part of the band that has left.
+ * - A scoped band that scrolls away travels its published extent, which is nothing on a Page it is not
+ *   on. A scoped band that sticks needs nothing: absent, the next sticky band stands where it stood.
+ */
+export declare function resolvePhiShellHeaderPaneStickyTop(headerTop: PhiShellChromePaneBand, headerMain: PhiShellChromePaneBand, behaviour: PhiShellHeaderTopBehaviour | null, initial: {
+    extent: number;
+    stack: number;
+}): string | null;
 /**
  * Which pane a Shadow belongs to, and therefore which way it points.
  */

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

@@ -1,4 +1,4 @@
-import { normalizePhiBackgroundWidgetConfig, resolvePhiBackgroundEffect, resolvePhiBackgroundWidgetStyle, } from "../widgets/config/background";
+import { normalizePhiBackgroundWidgetConfig, resolvePhiBackgroundFilter, resolvePhiBackgroundWidgetStyle, } from "../widgets/config/background";
 /**
  * The Shell Chrome Overlay (SHELL.md "Root Background and Shell Backdrop Layers").
  *
@@ -14,16 +14,17 @@ import { normalizePhiBackgroundWidgetConfig, resolvePhiBackgroundEffect, resolve
  * seam.
  */
 /**
- * The Effects the overlay offers and honours, which are the two glass panes.
+ * The Filters the overlay offers and honours, which are the two glass panes.
  *
- * The overlay is not a layer above the Chrome, it is the Chrome's own ground, so an Effect here acts on
- * the Region itself: `blur` and `dim` are `filter`, which would blur and darken the Header's own text.
- * A pane acts on what is behind the Region instead, which is exactly what a shared frame over a
- * scrolling Page wants, and both strengths of it belong to a frame -- `glass` where the Page should
- * read as frosted underneath, `haze` where it should stay almost legible. A wash of colour over the
- * frame is an Overlay rather than an Effect, and the overlay offers those unnarrowed.
+ * The overlay is not a layer above the Chrome, it is the Chrome's own ground, handed to the Regions as
+ * custom properties rather than as a layer of its own -- so there is no separate paint for `blur` to
+ * soften without softening the Header's text. A pane acts on what is behind the Region instead, which is
+ * exactly what a shared frame over a scrolling Page wants, and both strengths of it belong to a frame --
+ * `glass` where the Page should read as frosted underneath, `haze` where it should stay almost legible.
+ * A wash of colour over the frame is an Overlay rather than a Filter, and the overlay offers those
+ * unnarrowed.
  */
-export const PHI_SHELL_CHROME_OVERLAY_EFFECTS = ["glass", "haze"];
+export const PHI_SHELL_CHROME_OVERLAY_FILTERS = ["glass", "haze"];
 /**
  * The Base kinds the overlay offers and honours, which is the whole contract.
  *
@@ -64,7 +65,7 @@ export const PHI_SHELL_CHROME_OVERLAY_MOTION_MODES = ["static"];
  * frame. Content and Hero stay out because the overlay would paint over their content, and a Drawer is
  * an Overlay surface rather than Shell chrome.
  */
-export const PHI_SHELL_CHROME_OVERLAY_REGION_KEYS = [
+const PHI_SHELL_CHROME_OVERLAY_REGION_KEYS = [
     "header_top",
     "header_main",
     "header_bottom",
@@ -78,15 +79,15 @@ export const PHI_SHELL_CHROME_OVERLAY_REGION_KEYS = [
  * Whether this Region paints the shared overlay, which it does only while it authored nothing itself.
  *
  * 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 structured Background config, the plain
- * ground string a Region or the Shell record can set, and the Region's own Effect. Reading only the
+ * 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.
  */
-export function phiRegionUsesShellChromeOverlay({ regionKey, backgroundConfig, effect, grounds, }) {
+export function phiRegionUsesShellChromeOverlay({ regionKey, backgroundConfig, pane, grounds, }) {
     return (PHI_SHELL_CHROME_OVERLAY_REGION_KEYS.includes(regionKey) &&
         backgroundConfig == null &&
-        effect == null &&
+        pane == null &&
         grounds.every((ground) => ground == null));
 }
 function readPhiShellChromeOverlayConfig(root, mode) {
@@ -95,14 +96,14 @@ function readPhiShellChromeOverlayConfig(root, mode) {
 /**
  * The overlay as this surface renders it, narrowed to what it offers.
  *
- * A stored value is never rewritten. A Base or an Effect the overlay does not offer simply resolves
+ * A stored value is never rewritten. A Base or a Filter the overlay does not offer simply resolves
  * away, which is what the Control shows for it too.
  */
 export function resolvePhiShellChromeOverlayConfig(config) {
     const normalized = normalizePhiBackgroundWidgetConfig(config);
     /*
-     * The Base is narrowed first and the Effect resolved against the result, not against what is stored.
-     * The narrowing can only ever take a Base away, and an Effect that needed the Base it took has to go
+     * The Base is narrowed first and the Filter resolved against the result, not against what is stored.
+     * The narrowing can only ever take a Base away, and a Filter that needed the Base it took has to go
      * with it -- `glass` on a picture is the case, and the shared resolver already answers it.
      */
     const narrowed = {
@@ -112,10 +113,10 @@ export function resolvePhiShellChromeOverlayConfig(config) {
             : { kind: "none" },
         motion: null,
     };
-    const effect = resolvePhiBackgroundEffect(narrowed);
+    const filter = resolvePhiBackgroundFilter(narrowed);
     return {
         ...narrowed,
-        effect: effect && PHI_SHELL_CHROME_OVERLAY_EFFECTS.includes(effect) ? effect : null,
+        filter: filter && PHI_SHELL_CHROME_OVERLAY_FILTERS.includes(filter) ? filter : null,
     };
 }
 /**
@@ -169,7 +170,7 @@ export function resolvePhiShellChromeOverlayVariables(root) {
     }
     return variables;
 }
-function readPhiShellChromePanePixels(value) {
+export function readPhiShellChromePanePixels(value) {
     if (typeof value === "number") {
         return Number.isFinite(value) ? value : null;
     }
@@ -215,6 +216,46 @@ export function resolvePhiShellChromePaneStickyTop(bands) {
     const offsetTop = readPhiShellChromePanePixels(bands[firstSticky]?.offsetTop) ?? 0;
     return `${offsetTop - travel}px`;
 }
+/**
+ * The room `header_top` holds, published on the Shell element while the browser decides it (SHELL.md
+ * "Region visibility per Page"): `extent` is the height of its track, `stack` the part of the viewport's
+ * top a `scroll-up` band holds right now.
+ */
+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";
+/**
+ * Where the Header pane sticks when `header_top` may come and go.
+ *
+ * The server knows the first Page and nothing after it, so the band's travel is written as the room
+ * the browser publishes, with the server's own answer as the fallback until it does:
+ *
+ * - `hover` takes no room at all, and the pane is the bands below it.
+ * - `scroll-up` sticks, and the pane rises by exactly the part of the band that has left.
+ * - A scoped band that scrolls away travels its published extent, which is nothing on a Page it is not
+ *   on. A scoped band that sticks needs nothing: absent, the next sticky band stands where it stood.
+ */
+export function resolvePhiShellHeaderPaneStickyTop(headerTop, headerMain, behaviour, initial) {
+    if (headerTop == null || behaviour == null || (!behaviour.scoped && behaviour.reveal === "always")) {
+        return resolvePhiShellChromePaneStickyTop([headerTop, headerMain]);
+    }
+    if (behaviour.reveal === "hover") {
+        return resolvePhiShellChromePaneStickyTop([null, headerMain]);
+    }
+    const extent = `var(${PHI_SHELL_HEADER_TOP_EXTENT_PROPERTY}, ${initial.extent}px)`;
+    if (behaviour.reveal === "scroll-up") {
+        const offsetTop = readPhiShellChromePanePixels(headerTop.offsetTop) ?? 0;
+        return `calc(${offsetTop}px - ${extent} + var(${PHI_SHELL_HEADER_TOP_STACK_PROPERTY}, ${initial.stack}px))`;
+    }
+    if (headerTop.sticky === true) {
+        return resolvePhiShellChromePaneStickyTop([headerTop, headerMain]);
+    }
+    // Unknown travel stays unknown: the same refusal as for a band without a pixel height.
+    if (readPhiShellChromePanePixels(headerTop.height) == null) {
+        return null;
+    }
+    const below = resolvePhiShellChromePaneStickyTop([null, headerMain]);
+    return below == null ? null : `calc(${below} - ${extent})`;
+}
 /*
  * The offsets a preset takes per family.
  *

package/components/root/phi-theme-tone-source.d.ts

@@ -0,0 +1,19 @@
+import type { PhiConfigLocale } from "./phi-config-provider";
+import type { PhiRootThemeByMode } from "./phi-root-theme-resolver";
+import type { PhiThemeCustomColorPalette, PhiThemeMode } from "../../theme/phi-theme-presets";
+/**
+ * What a Surface needs to draw its content in another mode (`tone`, LAYOUTING.md "Surface tone").
+ *
+ * The root resolves both modes before the page reaches the browser -- the mode switch needs them anyway
+ * -- so a tone scope takes the other one from here instead of resolving a Theme of its own. `pageMode` is
+ * the mode the page is in; `inverse` is read against it, not against the nearest scope, so every inverse
+ * Surface on a page is the same mode and they all share one set of variables.
+ */
+export type PhiThemeToneSource = {
+    pageMode: PhiThemeMode;
+    themes: PhiRootThemeByMode;
+    customColorsByMode: Record<PhiThemeMode, PhiThemeCustomColorPalette>;
+    locale: PhiConfigLocale;
+};
+export declare const PhiThemeToneSourceProvider: import("react").Provider<PhiThemeToneSource | null>;
+export declare function usePhiThemeToneSource(): PhiThemeToneSource | null;

package/components/root/phi-theme-tone-source.js

@@ -0,0 +1,7 @@
+"use client";
+import { createContext, useContext } from "react";
+const PhiThemeToneSourceContext = createContext(null);
+export const PhiThemeToneSourceProvider = PhiThemeToneSourceContext.Provider;
+export function usePhiThemeToneSource() {
+    return useContext(PhiThemeToneSourceContext);
+}

package/components/runtime/core-runtime-controller-address.d.ts

@@ -1,7 +1,6 @@
 export declare const PHI_CORE_RUNTIME_CONTROLLER_PLUGIN_KEY = "@phis/ui/modules/core/controller";
 export declare const PHI_CORE_RUNTIME_CONTROLLER_KEY = "default";
 export declare const PHI_CORE_RUNTIME_CONTROLLER_TYPE: "@phis/ui/modules/core/controller/default";
-export declare const PHI_CORE_RUNTIME_CONTROLLER_INSTANCE_KEY = "default";
 /**
  * The address built from this package's own constants, which has to be the string the contract names.
  *

package/components/runtime/core-runtime-controller-address.js

@@ -3,7 +3,7 @@ import { PHI_SHARED_PACKAGE_NAME, createPhiControllerSignalAddress, } from "../.
 export const PHI_CORE_RUNTIME_CONTROLLER_PLUGIN_KEY = `${PHI_SHARED_PACKAGE_NAME}/modules/core/controller`;
 export const PHI_CORE_RUNTIME_CONTROLLER_KEY = "default";
 export const PHI_CORE_RUNTIME_CONTROLLER_TYPE = `${PHI_CORE_RUNTIME_CONTROLLER_PLUGIN_KEY}/${PHI_CORE_RUNTIME_CONTROLLER_KEY}`;
-export const PHI_CORE_RUNTIME_CONTROLLER_INSTANCE_KEY = "default";
+const PHI_CORE_RUNTIME_CONTROLLER_INSTANCE_KEY = "default";
 /**
  * The address built from this package's own constants, which has to be the string the contract names.
  *

package/components/runtime/mounted-runtime-controller.js

@@ -1,12 +1,15 @@
 "use client";
-import { useEffect } from "react";
+import { useEffect, useMemo } from "react";
 import { parsePhiRuntimeControllerConfig, resolvePhiRuntimeControllerMount, resolvePhiRuntimeControllerSignalScope, } from "../../plugins/registries/runtime-controller-core";
 import { registerPhiSignalInstance } from "./runtime-signal-registry";
 import { usePhiSignalRuntimePartition } from "./runtime-signal-partition";
+import { mergePhiRuntimeControllerConfigOverlay, usePhiRuntimeControllerConfigOverlay, } from "./runtime-controller-config-overlays";
 export function PhiMountedRuntimeController({ plugin, setting, runtime, context, preloadDataByAddress, }) {
     const signalPartition = usePhiSignalRuntimePartition();
     const { instanceKey, address } = resolvePhiRuntimeControllerMount(plugin, setting);
-    const parsedConfig = parsePhiRuntimeControllerConfig(plugin, setting.config);
+    // What the shown Page tells this Controller, when the Area runs it (runtime-controller-config-overlays).
+    const pageConfig = usePhiRuntimeControllerConfigOverlay(address);
+    const parsedConfig = useMemo(() => parsePhiRuntimeControllerConfig(plugin, mergePhiRuntimeControllerConfigOverlay(setting.config, pageConfig)), [pageConfig, plugin, setting.config]);
     const preloadData = preloadDataByAddress?.[address] ?? null;
     useEffect(() => {
         return registerPhiSignalInstance(signalPartition, {

package/components/runtime/phi-restored-request-runtime.d.ts

@@ -0,0 +1,12 @@
+import "server-only";
+import { type PhiCapturedRequestRuntime } from "../../server-helpers/request-runtime";
+/**
+ * Puts the request runtime a Server Action resolved back in place for the render of what it returned.
+ *
+ * Next renders an Action's returned nodes after the Action has returned, outside the request scope it
+ * ran in; whatever below reads the runtime would otherwise find an empty store.
+ */
+export declare function PhiRestoredRequestRuntime({ captured, children, }: {
+    captured: PhiCapturedRequestRuntime;
+    children: React.ReactNode;
+}): import("react").ReactNode;

package/components/runtime/phi-restored-request-runtime.js

@@ -0,0 +1,12 @@
+import "server-only";
+import { restorePhiRequestRuntimeStore, } from "../../server-helpers/request-runtime";
+/**
+ * Puts the request runtime a Server Action resolved back in place for the render of what it returned.
+ *
+ * Next renders an Action's returned nodes after the Action has returned, outside the request scope it
+ * ran in; whatever below reads the runtime would otherwise find an empty store.
+ */
+export function PhiRestoredRequestRuntime({ captured, children, }) {
+    restorePhiRequestRuntimeStore(captured);
+    return children;
+}

package/components/runtime/renderable-block-runtime.d.ts

@@ -1,15 +1,21 @@
-import { type PhiSignal, type PhiSignalAction, type PhiSignalAddress, type PhiSignalRuntimeContext, type PhiSignalScope, type PhiSignalValue, type PhiSignalValueType } from "../../types/signals";
+import { type PhiSignal, type PhiSignalAction, type PhiSignalAddress, type PhiSignalRuntimeContext, type PhiSignalScope, type PhiSignalValue } from "../../types/signals";
 import type { PhiRenderableBlock, PhiRenderableBlockCapabilities, PhiRenderableBlockRuntime, PhiRenderableBlockSize, PhiRenderableBlockVisibility } from "../../types/renderable-block";
 import type { PhiCmsInstanceId } from "../../types/cms-instance-id";
-import { usePhiSignalDispatcher } from "./runtime-signal-bus";
 type PhiRenderableBlockSignalChannel = "visibility" | "enabled" | "background" | "border" | "selected" | "hovered" | "dragging" | "focused" | "active" | "layout" | "size" | "minSize" | "maxSize" | "shadow" | "zIndex" | "opacity" | "effects" | "text" | "content" | "html" | "markdown" | "markdownToc" | "descriptionConfig" | "icon" | "imageConfig" | "color" | "textColor" | "style" | "fontFamily" | "fontSize" | "textStyle" | "drag" | "drop" | "flush";
 type PhiRenderableBlockSignal = PhiSignal;
 export type PhiRenderableBlockReceiver = Extract<PhiSignalAddress, `cms:${string}` | `region:${string}`>;
 export type PhiRenderableBlockReceiverKind = "widget" | "layout" | "region";
 export declare function createPhiRenderableBlockReceiver(kind: "region", id: string | null | undefined): PhiRenderableBlockReceiver | null;
 export declare function createPhiRenderableBlockReceiver(kind: Exclude<PhiRenderableBlockReceiverKind, "region">, id: PhiCmsInstanceId | null | undefined): PhiRenderableBlockReceiver | null;
-export declare function emitPhiRenderableBlockSignal(dispatchSignal: ReturnType<typeof usePhiSignalDispatcher>, channel: PhiRenderableBlockSignalChannel, receiver: PhiRenderableBlockReceiver | null | undefined, action: PhiSignalAction, value?: PhiSignalValue, valueType?: PhiSignalValueType, signalScope?: PhiSignalScope | null): void;
-export declare function usePhiRenderableBlockSignalListener(receiver: PhiRenderableBlockReceiver | null | undefined, handler: (signal: PhiRenderableBlockSignal) => void, context?: PhiSignalRuntimeContext, signalScope?: PhiSignalScope | null): void;
+export declare function applyPhiRenderableBlockSignal(current: PhiRenderableBlockRuntimeState, channel: PhiRenderableBlockSignalChannel, action: PhiSignalAction, value: PhiSignalValue): PhiRenderableBlockRuntimeState;
+export declare function usePhiRenderableBlockSignalListener(receiver: PhiRenderableBlockReceiver | null | undefined, handler: (signal: PhiRenderableBlockSignal) => void, context?: PhiSignalRuntimeContext, explicitSignalScope?: PhiSignalScope | null, 
+/**
+ * Whether a signal held for this address may be released to this listener. A Widget answering its
+ * content channels says yes; the frame around it says no, because it answers only the shared ones and
+ * mounts before the Widget's client has loaded -- released to the frame, a dialog's text was gone by
+ * the time the text Widget subscribed.
+ */
+answersHeldSignals?: boolean): void;
 export type PhiRenderableBlockRuntimeState = PhiRenderableBlock & {
     capabilities?: PhiRenderableBlockCapabilities;
     runtime?: PhiRenderableBlockRuntime;