@phis/ui 0.2.1 → 0.4.0

package/components/runtime/renderable-block-runtime.js

@@ -1,11 +1,14 @@
 "use client";
+import { isPhiRecord } from "../../helpers/is-record";
 import { useCallback, useEffect, useMemo, useState } from "react";
 import { PHI_SIGNAL_VALUE_SCHEMAS, createPhiSignalAddress, } from "../../types/signals";
-import { readPhiShadow } from "../../types/layout-style";
+import { readPhiSurface } from "../../types/surface";
 import { normalizeRenderableBlockAnchor } from "../../helpers/renderable-block-anchor";
+import { normalizePhiRenderableBlockCapabilities, normalizePhiRenderableBlockResponsiveSize, normalizePhiRenderableBlockRuntime, stripPhiRenderableBlockSize, } from "../../helpers/renderable-block-normalizers";
 import { inferPhiSignalValueType, usePhiSignalDispatcher, usePhiSignalListener, } from "./runtime-signal-bus";
 import { registerPhiSignalInstance } from "./runtime-signal-registry";
 import { usePhiSignalRuntimePartition } from "./runtime-signal-partition";
+import { usePhiSignalIdentity } from "./runtime-signal-identity";
 function resolvePhiRenderableBlockValueSchema(channel, valueType) {
     if (valueType !== "json") {
         return null;
@@ -74,104 +77,6 @@ function resolvePhiRenderableBlockSignalScope(receiver, explicitScope) {
         ? explicitScope ?? "widget"
         : resolvePhiRenderableBlockReceiverScope(receiver, explicitScope);
 }
-/*
- * Generic over the length, because the same stripping serves both pairs: a block's `size` may name a
- * value per profile, its `collapsedSizeHint` may not, and this only ever drops an empty pair.
- */
-function normalizePhiRenderableBlockSize(value) {
-    if (!value || typeof value !== "object") {
-        return undefined;
-    }
-    const width = value.width ?? undefined;
-    const height = value.height ?? undefined;
-    if (width == null && height == null) {
-        return undefined;
-    }
-    return {
-        ...(width == null ? {} : { width }),
-        ...(height == null ? {} : { height }),
-    };
-}
-function normalizePhiRenderableBlockCapabilities(value) {
-    if (!value || typeof value !== "object") {
-        return undefined;
-    }
-    const next = {};
-    let hasValue = false;
-    for (const key of ["selectable", "draggable", "hoverable", "activatable", "focusable", "droppable"]) {
-        const candidate = value[key];
-        if (typeof candidate === "boolean") {
-            next[key] = candidate;
-            hasValue = true;
-        }
-    }
-    return hasValue ? next : undefined;
-}
-function normalizePhiRenderableBlockRuntimeContext(value) {
-    if (!value || typeof value !== "object") {
-        return undefined;
-    }
-    const next = {};
-    let hasValue = false;
-    if (typeof value.siteKey === "string" || value.siteKey === null) {
-        next.siteKey = value.siteKey;
-        hasValue = true;
-    }
-    if (typeof value.publicUrl === "string" || value.publicUrl === null) {
-        next.publicUrl = value.publicUrl;
-        hasValue = true;
-    }
-    if (typeof value.defaultLang === "string" || value.defaultLang === null) {
-        next.defaultLang = value.defaultLang;
-        hasValue = true;
-    }
-    if (typeof value.area === "string" || value.area === null) {
-        next.area = value.area;
-        hasValue = true;
-    }
-    if (typeof value.pageKey === "string" || value.pageKey === null) {
-        next.pageKey = value.pageKey;
-        hasValue = true;
-    }
-    if (typeof value.regionKey === "string" || value.regionKey === null) {
-        next.regionKey = value.regionKey;
-        hasValue = true;
-    }
-    if (typeof value.blockId === "string" || typeof value.blockId === "number" || value.blockId === null) {
-        next.blockId = value.blockId;
-        hasValue = true;
-    }
-    return hasValue ? next : undefined;
-}
-function normalizePhiRenderableBlockInteractionState(value) {
-    if (!value || typeof value !== "object") {
-        return undefined;
-    }
-    const next = {};
-    let hasValue = false;
-    for (const key of ["selected", "hovered", "dragging", "focused", "active"]) {
-        const candidate = value[key];
-        if (typeof candidate === "boolean") {
-            next[key] = candidate;
-            hasValue = true;
-        }
-    }
-    return hasValue ? next : undefined;
-}
-function normalizePhiRenderableBlockRuntime(value) {
-    if (!value || typeof value !== "object") {
-        return undefined;
-    }
-    const context = normalizePhiRenderableBlockRuntimeContext(value);
-    const interaction = normalizePhiRenderableBlockInteractionState(value);
-    if (!context && !interaction) {
-        return undefined;
-    }
-    return {
-        ...context,
-        ...interaction,
-    };
-}
 function resolvePhiRenderableBlockRuntimeValue(blockId, value) {
     const normalized = normalizePhiRenderableBlockRuntime(value);
     if (normalized) {
@@ -189,10 +94,13 @@ function applyPhiRenderableBlockRuntimePatch(current, patch) {
     };
     return normalizePhiRenderableBlockRuntime(next) ?? next;
 }
+function patchPhiRenderableBlockSurface(current, patch) {
+    return readPhiSurface({ ...(current ?? {}), ...patch }) ?? undefined;
+}
 function canUseRenderableBlockCapability(state, capability) {
     return state.capabilities?.[capability] !== false;
 }
-function applyPhiRenderableBlockSignal(current, channel, action, value) {
+export function applyPhiRenderableBlockSignal(current, channel, action, value) {
     if (channel === "visibility") {
         if (action === "toggle") {
             return {
@@ -211,13 +119,19 @@ function applyPhiRenderableBlockSignal(current, channel, action, value) {
         }
         return { ...current, enabled: typeof value === "boolean" ? value : true };
     }
+    /*
+     * A Signal for one part of the Surface replaces that part and leaves the others as they stand; `null`
+     * takes the part away. The Surface is read again afterwards, so a value no part reads changes nothing.
+     */
     if (channel === "background" || channel === "border") {
-        if (value == null) {
-            return { ...current, [channel]: null };
+        if (value != null && (!isPhiRecord(value))) {
+            return current;
         }
-        return typeof value === "object" && !Array.isArray(value)
-            ? { ...current, [channel]: value }
-            : current;
+        // A line sent by Signal is drawn as sent, whatever source the stored Surface names for its edge.
+        const patch = channel === "border" && value != null
+            ? { border: value, borderSource: "custom" }
+            : { [channel]: value };
+        return { ...current, surface: patchPhiRenderableBlockSurface(current.surface, patch) };
     }
     if (channel === "selected" ||
         channel === "hovered" ||
@@ -236,7 +150,7 @@ function applyPhiRenderableBlockSignal(current, channel, action, value) {
         };
     }
     if (channel === "shadow") {
-        return { ...current, shadow: readPhiShadow(value) };
+        return { ...current, surface: patchPhiRenderableBlockSurface(current.surface, { shadow: value }) };
     }
     if (channel === "zIndex") {
         return { ...current, zIndex: typeof value === "number" ? value : current.zIndex };
@@ -263,12 +177,12 @@ function applyPhiRenderableBlockSignal(current, channel, action, value) {
         const sizeKey = channel === "size" ? "size" :
             channel === "minSize" ? "minSize" :
                 "maxSize";
-        const nextSize = normalizePhiRenderableBlockSize(value);
+        const nextSize = normalizePhiRenderableBlockResponsiveSize(value);
         return nextSize ? { ...current, [sizeKey]: nextSize } : current;
     }
     return current;
 }
-export function emitPhiRenderableBlockSignal(dispatchSignal, channel, receiver, action, value = null, valueType, signalScope) {
+function emitPhiRenderableBlockSignal(dispatchSignal, channel, receiver, action, value = null, valueType, signalScope) {
     const resolvedValueType = valueType ?? inferPhiSignalValueType(value);
     dispatchSignal({
         scope: resolvePhiRenderableBlockSignalScope(receiver, signalScope),
@@ -282,8 +196,24 @@ export function emitPhiRenderableBlockSignal(dispatchSignal, channel, receiver,
         timestamp: Date.now(),
     });
 }
-export function usePhiRenderableBlockSignalListener(receiver, handler, context, signalScope) {
+export function usePhiRenderableBlockSignalListener(receiver, handler, context, explicitSignalScope, 
+/**
+ * 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 = true) {
     const signalPartition = usePhiSignalRuntimePartition();
+    /*
+     * A Widget listening at its own block's address hears in the scope its frame registered that address
+     * under. One address is registered in one scope; the Widget registering it again as `widget` while
+     * the frame said `page` made delivery depend on which effect ran last, and a dialog's text sent by a
+     * Controller went to the frame's scope while the Widget filtered for its own.
+     */
+    const identity = usePhiSignalIdentity();
+    const signalScope = explicitSignalScope ??
+        (receiver != null && identity.receiver === receiver ? identity.scope ?? null : null);
     const signalFilter = useMemo(() => receiver == null
         ? undefined
         : {
@@ -309,7 +239,12 @@ export function usePhiRenderableBlockSignalListener(receiver, handler, context,
             context,
         });
     }, [context, receiver, signalPartition, signalScope]);
-    usePhiSignalListener(listener, signalFilter);
+    /*
+     * The address is named as the one this listener answers for. Without it the bus held a signal sent
+     * before the block mounted -- a Controller filling a dialog's text just before opening it -- for a
+     * listener it never saw arrive, and the text never came (`flushPendingPhiSignals`).
+     */
+    usePhiSignalListener(listener, signalFilter, answersHeldSignals ? receiver ?? null : null);
 }
 function resolvePhiRenderableBlockRuntimeState(input) {
     return {
@@ -323,16 +258,13 @@ function resolvePhiRenderableBlockRuntimeState(input) {
         anchor: normalizeRenderableBlockAnchor(input.anchor) ?? undefined,
         zIndex: input.zIndex ?? 0,
         opacity: input.opacity ?? 1,
-        effect: input.effect,
         className: input.className,
-        size: normalizePhiRenderableBlockSize(input.size),
-        minSize: normalizePhiRenderableBlockSize(input.minSize),
-        maxSize: normalizePhiRenderableBlockSize(input.maxSize),
-        collapsedSizeHint: normalizePhiRenderableBlockSize(input.collapsedSizeHint),
+        size: stripPhiRenderableBlockSize(input.size),
+        minSize: stripPhiRenderableBlockSize(input.minSize),
+        maxSize: stripPhiRenderableBlockSize(input.maxSize),
+        collapsedSizeHint: stripPhiRenderableBlockSize(input.collapsedSizeHint),
         capabilities: normalizePhiRenderableBlockCapabilities(input.capabilities),
-        background: input.background ?? undefined,
-        border: input.border ?? undefined,
-        shadow: input.shadow ?? undefined,
+        surface: input.surface ?? undefined,
         effects: input.effects ?? undefined,
         effectsState: input.effectsState,
         runtime: resolvePhiRenderableBlockRuntimeValue(input.blockId, input.runtime),
@@ -374,8 +306,8 @@ function resolvePhiRenderableBlockSignalOverrides(current, channel, action, valu
         channel === "active") {
         return { runtime: next.runtime };
     }
-    if (channel === "shadow") {
-        return { shadow: next.shadow };
+    if (channel === "background" || channel === "border" || channel === "shadow") {
+        return { surface: next.surface };
     }
     if (channel === "zIndex") {
         return { zIndex: next.zIndex };
@@ -441,7 +373,7 @@ export function usePhiRenderableBlockRuntime(input = {}) {
     const handleRenderableBlockSignal = useCallback((signal) => {
         applyRuntimeSignalOverride(signal.channel, signal.action, signal.value);
     }, [applyRuntimeSignalOverride]);
-    usePhiRenderableBlockSignalListener(receiver, handleRenderableBlockSignal, signalRuntimeContext, signalScope);
+    usePhiRenderableBlockSignalListener(receiver, handleRenderableBlockSignal, signalRuntimeContext, signalScope, false);
     const emit = useCallback((channel, action, value = null, valueType) => {
         if (receiver == null) {
             applyRuntimeSignalOverride(channel, action, value);

package/components/runtime/runtime-controller-config-overlays.d.ts

@@ -0,0 +1,19 @@
+import type { PhiSignalAddress } from "../../types/signals";
+export type PhiRuntimeControllerConfigOverlay = {
+    address: PhiSignalAddress;
+    config: Record<string, unknown>;
+};
+export declare function PhiRuntimeControllerConfigOverlays({ overlays, }: {
+    overlays: readonly PhiRuntimeControllerConfigOverlay[];
+}): null;
+/** The config the shown Page gives the Controller at this address, or null when it gives none. */
+export declare function usePhiRuntimeControllerConfigOverlay(address: PhiSignalAddress): Record<string, unknown> | null;
+/**
+ * The Area's config of a Controller with what the shown Page adds to it.
+ *
+ * A key the Page sets replaces the Area's, except `signalRoutes`: the Area's receivers -- its own
+ * Overlays, standing on every Page -- do not stop existing while a Page is shown, so the Page's routes
+ * join them rather than replace them. A Page route with the routeKey of an Area route is the Page's
+ * answer to the same question and takes its place.
+ */
+export declare function mergePhiRuntimeControllerConfigOverlay<TAreaConfig extends Record<string, unknown> | null | undefined>(areaConfig: TAreaConfig, pageConfig: Record<string, unknown> | null): TAreaConfig | Record<string, unknown>;

package/components/runtime/runtime-controller-config-overlays.js

@@ -0,0 +1,76 @@
+"use client";
+import { useCallback, useEffect, useSyncExternalStore } from "react";
+import { joinPhiSignalRouteSets } from "../../helpers/signal-route-set-join";
+import { usePhiSignalRuntimePartition, } from "./runtime-signal-partition";
+const storesByPartition = new WeakMap();
+function readStore(partition) {
+    let store = storesByPartition.get(partition);
+    if (!store) {
+        store = { entries: new Map(), listeners: new Set() };
+        storesByPartition.set(partition, store);
+    }
+    return store;
+}
+function notify(store) {
+    for (const listener of store.listeners)
+        listener();
+}
+export function PhiRuntimeControllerConfigOverlays({ overlays, }) {
+    const partition = usePhiSignalRuntimePartition();
+    useEffect(() => {
+        const store = readStore(partition);
+        const token = Symbol("phi-controller-config-overlay");
+        for (const overlay of overlays) {
+            store.entries.set(overlay.address, [
+                ...(store.entries.get(overlay.address) ?? []),
+                { config: overlay.config, token },
+            ]);
+        }
+        notify(store);
+        return () => {
+            for (const overlay of overlays) {
+                const remaining = (store.entries.get(overlay.address) ?? []).filter((entry) => entry.token !== token);
+                if (remaining.length > 0) {
+                    store.entries.set(overlay.address, remaining);
+                }
+                else {
+                    store.entries.delete(overlay.address);
+                }
+            }
+            notify(store);
+        };
+    }, [overlays, partition]);
+    return null;
+}
+/** The config the shown Page gives the Controller at this address, or null when it gives none. */
+export function usePhiRuntimeControllerConfigOverlay(address) {
+    const partition = usePhiSignalRuntimePartition();
+    const store = readStore(partition);
+    const subscribe = useCallback((listener) => {
+        store.listeners.add(listener);
+        return () => {
+            store.listeners.delete(listener);
+        };
+    }, [store]);
+    return useSyncExternalStore(subscribe, () => store.entries.get(address)?.at(-1)?.config ?? null, () => null);
+}
+/**
+ * The Area's config of a Controller with what the shown Page adds to it.
+ *
+ * A key the Page sets replaces the Area's, except `signalRoutes`: the Area's receivers -- its own
+ * Overlays, standing on every Page -- do not stop existing while a Page is shown, so the Page's routes
+ * join them rather than replace them. A Page route with the routeKey of an Area route is the Page's
+ * answer to the same question and takes its place.
+ */
+export function mergePhiRuntimeControllerConfigOverlay(areaConfig, pageConfig) {
+    if (!pageConfig)
+        return areaConfig;
+    const merged = { ...areaConfig, ...pageConfig };
+    const signalRoutes = joinPhiSignalRouteSets(areaConfig?.signalRoutes, pageConfig.signalRoutes, {
+        duplicate: "replace",
+        label: "A Page's Controller config",
+    });
+    if (signalRoutes)
+        merged.signalRoutes = signalRoutes;
+    return merged;
+}

package/components/runtime/runtime-controller-materialization.d.ts

@@ -11,7 +11,17 @@ export type PhiRuntimeControllerMaterializationOptions = {
     tree: PhiResolvedCmsRenderableTree;
     ownerMountScope: PhiRuntimeControllerMaterializationOwner;
     widgetPluginsByType: WidgetPluginRegistryLike;
+    /**
+     * What runs in this scope whatever the tree says: the Controllers whose Module mounts them for the
+     * whole Area (`areaControllerSettings`). The tree's own `controllerSettings` are read off `tree`.
+     */
     baseSettings?: readonly PhiRuntimeControllerSetting[] | null;
+    /**
+     * What the enclosing scope already runs. A Page that configures one of these does not mount a second
+     * copy at the same address; its config reaches the running one instead
+     * (`collectPhiRuntimeControllerConfigOverlays`).
+     */
+    enclosingSettings?: readonly PhiRuntimeControllerSetting[] | null;
     activeControllerTypes: ReadonlySet<string> | readonly string[];
     regionTypes?: readonly number[] | null;
     includeOverlays?: boolean;
@@ -25,13 +35,39 @@ export type PhiRuntimeControllerMaterializationOptions = {
      */
     excludedOverlayIds?: ReadonlySet<PhiCmsInstanceId>;
 };
+/**
+ * The configs a Page gives Controllers its Area already runs.
+ *
+ * The Asset Controller is mounted for the whole Area, and the Media Page is the one that knows which
+ * dialog and which Form it answers into. Mounting a second Asset Controller for the Page would put two
+ * listeners behind one address; instead the Page's config reaches the running one while the Page is
+ * shown (`PhiRuntimeControllerConfigOverlays`) and leaves with it.
+ */
+export declare function collectPhiRuntimeControllerConfigOverlays({ tree, ownerMountScope, enclosingSettings, }: Pick<PhiRuntimeControllerMaterializationOptions, "tree" | "ownerMountScope" | "enclosingSettings">): {
+    type: `${string}/${string}`;
+    instanceKey: string;
+    config: Record<string, unknown>;
+}[];
 export declare function materializePhiWidgetRuntimeControllerSettings({ widget, tree, ownerMountScope, plugin, }: {
     widget: PhiCmsContentWidgetNode;
     tree: PhiResolvedCmsRenderableTree;
     ownerMountScope: PhiRuntimeControllerMaterializationOwner;
     plugin: RuntimeControllerMaterializationWidgetMeta;
 }): PhiRuntimeControllerSetting[];
-export declare function materializePhiRuntimeControllerSettings({ tree, ownerMountScope, widgetPluginsByType, baseSettings, activeControllerTypes, regionTypes, includeOverlays, excludedOverlayIds, }: PhiRuntimeControllerMaterializationOptions): PhiRuntimeControllerSetting[];
+/**
+ * The Controllers one scope runs: what its Modules mount for it, what its Widgets ask for, and what its
+ * tree configures.
+ *
+ * A tree setting configures the Controller of its type and instance -- the tree's keys win over what a
+ * Widget asked with -- and mounts it when nothing else does, which is how a Page brings a `demand`
+ * Controller into being. Three exceptions, each because the Controller runs somewhere else:
+ * - one the enclosing scope runs is configured there (`collectPhiRuntimeControllerConfigOverlays`);
+ * - one only a deferred Overlay asks for arrives with that Overlay, and the tree's config with it
+ *   (`materializePhiOverlayRuntimeControllerSettings`);
+ * - one no active Module owns is not run at all. A Module switched off takes its Controller with it, and
+ *   what a tree said to that Controller is inert until the Module is back.
+ */
+export declare function materializePhiRuntimeControllerSettings({ tree, ownerMountScope, widgetPluginsByType, baseSettings, enclosingSettings, activeControllerTypes, regionTypes, includeOverlays, excludedOverlayIds, }: PhiRuntimeControllerMaterializationOptions): PhiRuntimeControllerSetting[];
 /**
  * The Controllers one Overlay's Widgets ask for, mounted with its zones when it first opens.
  *

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

@@ -1,6 +1,40 @@
 function buildSettingKey(setting) {
     return `${setting.mountScope}:${setting.type}:${setting.instanceKey}`;
 }
+/** Which Controller a setting is about, whatever scope says it: its address is type and instance. */
+function buildControllerKey(setting) {
+    return `${setting.type}:${setting.instanceKey}`;
+}
+/** What a tree tells a Controller, laid over what the Controller was asked with: the tree's keys win. */
+function withTreeConfig(setting, treeSetting) {
+    if (!treeSetting?.config)
+        return setting;
+    return { ...setting, config: { ...(setting.config ?? {}), ...treeSetting.config } };
+}
+function readTreeControllerSettings(tree, ownerMountScope) {
+    const settings = tree.controllerSettings ?? [];
+    for (const setting of settings) {
+        if (setting.mountScope !== ownerMountScope) {
+            throw new Error(`A ${ownerMountScope} tree configures "${buildControllerKey(setting)}" at ` +
+                `"${setting.mountScope}" scope; a tree configures its Controllers in its own scope.`);
+        }
+    }
+    return new Map(settings.map((setting) => [buildControllerKey(setting), setting]));
+}
+/**
+ * The configs a Page gives Controllers its Area already runs.
+ *
+ * The Asset Controller is mounted for the whole Area, and the Media Page is the one that knows which
+ * dialog and which Form it answers into. Mounting a second Asset Controller for the Page would put two
+ * listeners behind one address; instead the Page's config reaches the running one while the Page is
+ * shown (`PhiRuntimeControllerConfigOverlays`) and leaves with it.
+ */
+export function collectPhiRuntimeControllerConfigOverlays({ tree, ownerMountScope, enclosingSettings, }) {
+    const enclosingKeys = new Set((enclosingSettings ?? []).map(buildControllerKey));
+    return [...readTreeControllerSettings(tree, ownerMountScope).values()]
+        .filter((setting) => enclosingKeys.has(buildControllerKey(setting)) && setting.config != null)
+        .map((setting) => ({ type: setting.type, instanceKey: setting.instanceKey, config: setting.config }));
+}
 export function materializePhiWidgetRuntimeControllerSettings({ widget, tree, ownerMountScope, plugin, }) {
     if (!plugin.requiredRuntimeControllers) {
         return [];
@@ -79,23 +113,61 @@ function filterMaterializedWidgets(tree, regionTypes, includeOverlays = false, e
     const includedLayoutIds = collectIncludedLayoutIds(tree.layoutNodes, rootLayoutNodeIds);
     return withoutOverlayWidgets(tree, tree.contentWidgets.filter((widget) => includedLayoutIds.has(widget.parentLayoutNodeId)), excludedOverlayIds);
 }
-export function materializePhiRuntimeControllerSettings({ tree, ownerMountScope, widgetPluginsByType, baseSettings, activeControllerTypes, regionTypes, includeOverlays, excludedOverlayIds, }) {
+/**
+ * The Controllers one scope runs: what its Modules mount for it, what its Widgets ask for, and what its
+ * tree configures.
+ *
+ * A tree setting configures the Controller of its type and instance -- the tree's keys win over what a
+ * Widget asked with -- and mounts it when nothing else does, which is how a Page brings a `demand`
+ * Controller into being. Three exceptions, each because the Controller runs somewhere else:
+ * - one the enclosing scope runs is configured there (`collectPhiRuntimeControllerConfigOverlays`);
+ * - one only a deferred Overlay asks for arrives with that Overlay, and the tree's config with it
+ *   (`materializePhiOverlayRuntimeControllerSettings`);
+ * - one no active Module owns is not run at all. A Module switched off takes its Controller with it, and
+ *   what a tree said to that Controller is inert until the Module is back.
+ */
+export function materializePhiRuntimeControllerSettings({ tree, ownerMountScope, widgetPluginsByType, baseSettings, enclosingSettings, activeControllerTypes, regionTypes, includeOverlays, excludedOverlayIds, }) {
     const settingsByKey = new Map();
     const allowedControllerTypes = new Set(activeControllerTypes);
+    const treeSettings = readTreeControllerSettings(tree, ownerMountScope);
+    const enclosingKeys = new Set((enclosingSettings ?? []).map(buildControllerKey));
     for (const setting of baseSettings ?? []) {
         if (setting.mountScope !== ownerMountScope) {
             continue;
         }
-        settingsByKey.set(buildSettingKey(setting), { ...setting });
+        settingsByKey.set(buildSettingKey(setting), withTreeConfig({ ...setting }, treeSettings.get(buildControllerKey(setting))));
     }
-    return materializeWidgetSettings({
+    materializeWidgetSettings({
         tree,
         widgets: filterMaterializedWidgets(tree, regionTypes, includeOverlays, excludedOverlayIds),
         ownerMountScope,
         widgetPluginsByType,
         allowedControllerTypes,
         settingsByKey,
+        treeSettings,
     });
+    const deferredKeys = new Set(excludedOverlayIds && excludedOverlayIds.size > 0
+        ? tree.overlays
+            .filter((overlay) => excludedOverlayIds.has(overlay.id))
+            .flatMap((overlay) => materializePhiOverlayRuntimeControllerSettings({
+            tree,
+            overlay,
+            widgetPluginsByType,
+            activeControllerTypes: allowedControllerTypes,
+        }))
+            .map(buildControllerKey)
+        : []);
+    for (const [controllerKey, setting] of treeSettings) {
+        const key = buildSettingKey(setting);
+        if (settingsByKey.has(key) ||
+            enclosingKeys.has(controllerKey) ||
+            deferredKeys.has(controllerKey) ||
+            !allowedControllerTypes.has(setting.type)) {
+            continue;
+        }
+        settingsByKey.set(key, { ...setting });
+    }
+    return [...settingsByKey.values()];
 }
 /**
  * The Controllers one Overlay's Widgets ask for, mounted with its zones when it first opens.
@@ -113,9 +185,10 @@ export function materializePhiOverlayRuntimeControllerSettings({ tree, overlay,
         widgetPluginsByType,
         allowedControllerTypes: new Set(activeControllerTypes),
         settingsByKey: new Map(),
+        treeSettings: readTreeControllerSettings(tree, "area"),
     });
 }
-function materializeWidgetSettings({ tree, widgets, ownerMountScope, widgetPluginsByType, allowedControllerTypes, settingsByKey, }) {
+function materializeWidgetSettings({ tree, widgets, ownerMountScope, widgetPluginsByType, allowedControllerTypes, settingsByKey, treeSettings, }) {
     for (const widget of widgets) {
         const plugin = widgetPluginsByType.get(widget.widgetType);
         if (!plugin) {
@@ -128,18 +201,19 @@ function materializeWidgetSettings({ tree, widgets, ownerMountScope, widgetPlugi
             plugin,
         })) {
             if (!allowedControllerTypes.has(materializedSetting.type)) {
-                console.warn("[phi-runtime-controller-materialization] Missing runtime controller policy.", {
-                    ownerMountScope,
-                    controllerType: materializedSetting.type,
-                    controllerInstanceKey: materializedSetting.instanceKey,
-                    widgetId: widget.id,
-                    widgetType: widget.widgetType,
-                });
-                continue;
+                /*
+                 * A Widget asked for a Controller no active Module owns. Dropping the requirement renders the
+                 * Widget without the thing it declared it needs: its signals go to an address nobody holds, and
+                 * the page looks fine. The declaration is the Widget's contract with its Module, so this is a
+                 * contract error and is reported as one -- the renderer shows it in the Widget's place.
+                 */
+                throw new Error(`${widget.widgetType}.requiredRuntimeControllers: Controller "${materializedSetting.type}" ` +
+                    `(instance "${materializedSetting.instanceKey}") is not owned by an active Module in this ` +
+                    `${ownerMountScope} scope (Widget ${widget.id}).`);
             }
             const key = buildSettingKey(materializedSetting);
             if (!settingsByKey.has(key)) {
-                settingsByKey.set(key, materializedSetting);
+                settingsByKey.set(key, withTreeConfig(materializedSetting, treeSettings.get(buildControllerKey(materializedSetting))));
             }
         }
     }

package/components/runtime/runtime-controller-server-host.d.ts

@@ -1,6 +1,7 @@
 import type { PhiBlockRuntime, PhiRuntimeControllerPreloadMap, PhiRuntimeControllerSetting, PhiRuntimeModuleCatalog, PhiRuntimeModuleId } from "../../types";
 import { type PhiAnyRuntimeControllerDefinition } from "../../plugins/registries/runtime-controller-core";
 import type { PhiSignalRuntimeContext } from "../../types/signals";
+import type { PhiCapabilitySnapshot } from "../../types/server-capabilities";
 type RuntimeControllerDefinitionRegistryLike = Map<string, PhiAnyRuntimeControllerDefinition> | ReadonlyMap<string, PhiAnyRuntimeControllerDefinition>;
 export type PhiRuntimeControllerServerHostProps = {
     controllers?: readonly PhiRuntimeControllerSetting[] | null;
@@ -8,11 +9,12 @@ export type PhiRuntimeControllerServerHostProps = {
     registry: RuntimeControllerDefinitionRegistryLike;
     controllerModuleIdsByType: ReadonlyMap<string, PhiRuntimeModuleId>;
     runtimeModuleCatalog: PhiRuntimeModuleCatalog;
+    serverCapabilities: PhiCapabilitySnapshot | null;
     context?: PhiSignalRuntimeContext | null;
 };
-export declare function resolvePhiRuntimeControllerPreloads({ controllers, runtime, registry, runtimeModuleCatalog, }: Pick<PhiRuntimeControllerServerHostProps, "controllers" | "runtime" | "registry" | "runtimeModuleCatalog">): Promise<{
+export declare function resolvePhiRuntimeControllerPreloads({ controllers, runtime, registry, runtimeModuleCatalog, serverCapabilities, }: Pick<PhiRuntimeControllerServerHostProps, "controllers" | "runtime" | "registry" | "runtimeModuleCatalog" | "serverCapabilities">): Promise<{
     controllers: PhiRuntimeControllerSetting[];
     preloadDataByAddress: PhiRuntimeControllerPreloadMap;
 }>;
-export declare function PhiRuntimeControllerServerHost({ controllers, runtime, registry, controllerModuleIdsByType, runtimeModuleCatalog, context, }: PhiRuntimeControllerServerHostProps): Promise<import("react").JSX.Element | null>;
+export declare function PhiRuntimeControllerServerHost({ controllers, runtime, registry, controllerModuleIdsByType, runtimeModuleCatalog, serverCapabilities, context, }: PhiRuntimeControllerServerHostProps): Promise<import("react").JSX.Element | null>;
 export {};

package/components/runtime/runtime-controller-server-host.js

@@ -3,7 +3,7 @@ import { parsePhiRuntimeControllerConfig, resolvePhiRuntimeControllerMount, } fr
 import { PhiRuntimeModuleControllerClientHost } from "./runtime-module-controller-client-host";
 import { PhiPlatformRuntimeControllerClientHost } from "./platform-runtime-controller-client-host";
 import { PHI_FORM_CONTROLLER_TYPE } from "../forms/runtime-form-controller-address";
-export async function resolvePhiRuntimeControllerPreloads({ controllers, runtime, registry, runtimeModuleCatalog, }) {
+export async function resolvePhiRuntimeControllerPreloads({ controllers, runtime, registry, runtimeModuleCatalog, serverCapabilities, }) {
     const activeControllers = [];
     const preloadDataByAddress = {};
     const seenAddresses = new Set();
@@ -36,6 +36,7 @@ export async function resolvePhiRuntimeControllerPreloads({ controllers, runtime
             mountScope: setting.mountScope,
             runtime,
             runtimeModuleCatalog,
+            serverCapabilities,
             setting: resolvedSetting,
             config: parsedConfig,
         });
@@ -45,12 +46,13 @@ export async function resolvePhiRuntimeControllerPreloads({ controllers, runtime
         preloadDataByAddress,
     };
 }
-export async function PhiRuntimeControllerServerHost({ controllers, runtime, registry, controllerModuleIdsByType, runtimeModuleCatalog, context, }) {
+export async function PhiRuntimeControllerServerHost({ controllers, runtime, registry, controllerModuleIdsByType, runtimeModuleCatalog, serverCapabilities, context, }) {
     const { controllers: activeControllers, preloadDataByAddress, } = await resolvePhiRuntimeControllerPreloads({
         controllers,
         runtime,
         registry,
         runtimeModuleCatalog,
+        serverCapabilities,
     });
     if (activeControllers.length === 0) {
         return null;

package/components/runtime/runtime-module-authoring-host.js

@@ -3,7 +3,8 @@ import { PhiControlOptionsProviderIsolationBoundary } from "../controls/phi-opti
 import { PhiTableProviderIsolationBoundary } from "../widgets/client/shared/phi-table-provider";
 import { PhiTreeProviderIsolationBoundary } from "../widgets/client/shared/phi-tree-provider";
 import { PhiCollectionProviderIsolationBoundary } from "../widgets/client/shared/phi-collection-provider";
+import { PhiTimelineProviderIsolationBoundary } from "../widgets/client/shared/phi-timeline-provider";
 import { PhiRuntimeModuleDataProviderClientHost } from "./runtime-module-data-provider-client-manifest";
 export function PhiRuntimeModuleAuthoringDataProviderHost({ providerKeys, children, }) {
-    return (_jsx(PhiControlOptionsProviderIsolationBoundary, { children: _jsx(PhiTableProviderIsolationBoundary, { children: _jsx(PhiTreeProviderIsolationBoundary, { children: _jsx(PhiCollectionProviderIsolationBoundary, { children: _jsx(PhiRuntimeModuleDataProviderClientHost, { providerKeys: providerKeys, mode: "authoring", children: children }) }) }) }) }));
+    return (_jsx(PhiControlOptionsProviderIsolationBoundary, { children: _jsx(PhiTableProviderIsolationBoundary, { children: _jsx(PhiTreeProviderIsolationBoundary, { children: _jsx(PhiCollectionProviderIsolationBoundary, { children: _jsx(PhiTimelineProviderIsolationBoundary, { children: _jsx(PhiRuntimeModuleDataProviderClientHost, { providerKeys: providerKeys, mode: "authoring", children: children }) }) }) }) }) }));
 }

package/components/runtime/runtime-module-context.d.ts

@@ -3,7 +3,7 @@ import type { PhiRuntimeModuleDataProviderDescriptor, PhiRuntimeModuleClientWidg
 import type { PhiRuntimeDataProviderKey } from "../../types/runtime-data-provider";
 import type { PhiCalendarAdapterDescriptor, PhiCalendarAdapterKey } from "../../types/calendar";
 import type { PhiVideoProviderDescriptor, PhiVideoProviderKey } from "../../types/video";
-export type PhiRuntimeModuleClientState = {
+type PhiRuntimeModuleClientState = {
     moduleIds: ReadonlySet<string>;
     widgetTypes: ReadonlySet<string>;
     layoutTypes: ReadonlySet<string>;
@@ -30,3 +30,4 @@ export declare function PhiRuntimeModuleProvider({ moduleIds, widgetTypes, layou
     children: ReactNode;
 }): import("react").JSX.Element;
 export declare function usePhiRuntimeModuleState(): PhiRuntimeModuleClientState;
+export {};