@phis/ui 0.2.1 → 0.3.0

package/next/site-proxy.d.ts

@@ -1,4 +1,4 @@
 import { NextRequest, NextResponse } from "next/server";
-/** Where the static route tree lives. Only the proxy may send a request there; see below. */
-export declare const PHI_STATIC_RENDER_PREFIX = "/static-render";
+import { PHI_STATIC_RENDER_PREFIX } from "../helpers/static-render-path";
+export { PHI_STATIC_RENDER_PREFIX };
 export declare function proxyPhiNextSiteRequest(request: NextRequest): Promise<NextResponse<unknown>>;

package/next/site-proxy.js

@@ -1,5 +1,6 @@
 import { NextRequest, NextResponse } from "next/server";
 import { isPhiAssetOrBackendPath } from "./static-asset-path";
+import { PHI_SITE_SESSION_COOKIE } from "../constants/site-cookies";
 import { PHI_CMS_SPECIAL_ROOTS } from "../helpers/cms-routing";
 import { localizePath } from "../helpers/locale";
 import { extractLocalePrefix, } from "../helpers/site-locale-config";
@@ -10,9 +11,8 @@ import { peekPhiAreaRootDoor } from "../gateway/area-root-door";
 import { readPhiServerApiCredentials } from "../helpers/phis-server-credentials";
 import { getResolvedSiteConfig } from "../gateway/site-config";
 import { PHI_COLOR_SCHEME_COOKIE, PHI_THEME_MODE_COOKIE, normalizePhiColorSchemeHint, normalizePhiThemeModePreference, resolvePhiThemeMode, } from "../theme/phi-theme-mode";
-/** Where the static route tree lives. Only the proxy may send a request there; see below. */
-export const PHI_STATIC_RENDER_PREFIX = "/static-render";
-const PHI_SITE_SESSION_COOKIE = "phis_session";
+import { PHI_STATIC_RENDER_PREFIX } from "../helpers/static-render-path";
+export { PHI_STATIC_RENDER_PREFIX };
 /*
  * Query parameters a static render may ignore: campaign tags nobody's page reads, and `_rsc`, which Next
  * adds to a client navigation's own request. Any other parameter can change what a page shows -- a
@@ -149,7 +149,17 @@ export async function proxyPhiNextSiteRequest(request) {
             : new NextResponse(null, { status: 404 });
     }
     if (isPhiAssetOrBackendPath(pathname)) {
-        return NextResponse.next();
+        /*
+         * `x-locale` is this proxy's word, set below from the path. A backend route resolves its locale
+         * through the same request reader as a page, so a value the browser sent under that name must not
+         * reach it either.
+         */
+        if (!request.headers.has("x-locale")) {
+            return NextResponse.next();
+        }
+        const backendHeaders = new Headers(request.headers);
+        backendHeaders.delete("x-locale");
+        return NextResponse.next({ request: { headers: backendHeaders } });
     }
     const runtimeConfig = readSiteRuntime();
     const localeConfig = await readLocaleConfig(runtimeConfig);
@@ -165,8 +175,9 @@ export async function proxyPhiNextSiteRequest(request) {
     requestHeaders.set(PHIS_CLIENT_NAVIGATION_HEADER, isPhiClientNavigation(request) ? "1" : "0");
     const prefixedLocale = extractLocalePrefix(pathname, localeConfig);
     if (prefixedLocale) {
-        // The static tree names the locale by its own segment, so only an exact one goes there.
-        const localeSegment = pathname.split("/").filter(Boolean)[0]?.toLowerCase();
+        // The static tree names the locale by its own segment, so only an exact one goes there -- in the
+        // Site's own spelling, which is how `prefixedLocale` comes back; lowercasing kept `pt-BR` out.
+        const localeSegment = pathname.split("/").filter(Boolean)[0];
         if (localeSegment === prefixedLocale && isPhiStaticRenderRequest(request)) {
             const passHeaders = new Headers(request.headers);
             passHeaders.set(PHI_STATIC_RENDER_PASS_HEADER, readPhiStaticRenderPass());

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phis/ui",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "license": "Apache-2.0",
   "publishConfig": {
     "access": "public"
@@ -112,6 +112,11 @@
       "import": "./next/cache-handler.mjs",
       "default": "./next/cache-handler.mjs"
     },
+    "./next/config": {
+      "types": "./next/config.d.mts",
+      "import": "./next/config.mjs",
+      "default": "./next/config.mjs"
+    },
     "./next/overlay-zones-client": {
       "types": "./components/overlays/phi-overlay-zones-loader.d.ts",
       "import": "./components/overlays/phi-overlay-zones-loader.js",
@@ -122,6 +127,11 @@
       "import": "./next/overlay-zones.js",
       "default": "./next/overlay-zones.js"
     },
+    "./next/root-error-page": {
+      "types": "./next/root-error-page.d.ts",
+      "import": "./next/root-error-page.js",
+      "default": "./next/root-error-page.js"
+    },
     "./next/route-handlers": {
       "types": "./next/route-handlers.d.ts",
       "import": "./next/route-handlers.js",
@@ -262,6 +272,16 @@
       "import": "./module-labels.js",
       "default": "./module-labels.js"
     },
+    "./module/dashboard-cards": {
+      "types": "./module-dashboard-cards.d.ts",
+      "import": "./module-dashboard-cards.js",
+      "default": "./module-dashboard-cards.js"
+    },
+    "./module/records": {
+      "types": "./module-records.d.ts",
+      "import": "./module-records.js",
+      "default": "./module-records.js"
+    },
     "./module/projection": {
       "types": "./module-projection.d.ts",
       "import": "./module-projection.js",
@@ -470,6 +490,7 @@
   "dependencies": {
     "@ant-design/colors": "^8.0.1",
     "@ant-design/cssinjs": "^2.1.2",
+    "@ant-design/icons-svg": "^4.6.0",
     "@dnd-kit/core": "^6.3.1",
     "@dnd-kit/sortable": "^10.0.0",
     "@dnd-kit/utilities": "^3.2.2",
@@ -482,7 +503,7 @@
     "@lexical/rich-text": "0.50.0",
     "@lexical/selection": "0.50.0",
     "@lexical/utils": "0.50.0",
-    "@phis/contracts": "^0.5.0",
+    "@phis/contracts": "^0.6.0",
     "dayjs": "^1.11.23",
     "dom-serializer": "^2.0.0",
     "htmlparser2": "^10.1.0",

package/plugins/factories/widget-builder-plugin.js

@@ -1,9 +1,8 @@
 "use client";
 export function createPhiCmsBuilderWidgetPlugin(definition, renderEditor) {
-    const { contentBinding: _contentBinding, ...builderDefinition } = definition;
-    void _contentBinding;
+    // The definition whole: the Builder plugin is the declaration plus its editor, nothing taken away.
     return {
-        ...builderDefinition,
+        ...definition,
         renderEditor,
     };
 }

package/plugins/registries/runtime-controllers.js

@@ -1,7 +1,10 @@
 import { isPhiRecord } from "../../helpers/is-record";
 export { buildPhiRuntimeControllerDefinitionMap, buildPhiRuntimeControllerDefinitionType, buildPhiRuntimeControllerPluginMap, buildPhiRuntimeControllerPluginType, hasPhiRuntimeControllerFlag, parsePhiRuntimeControllerConfig, resolvePhiRuntimeControllerInstanceKey, resolvePhiRuntimeControllerMount, resolvePhiRuntimeControllerSignalScope, } from "./runtime-controller-core";
+const PHI_RUNTIME_CONTROLLER_MOUNT_SCOPES = ["site", "area", "page"];
 function readMountScope(value) {
-    return value === "site" || value === "area" || value === "page" ? value : null;
+    return PHI_RUNTIME_CONTROLLER_MOUNT_SCOPES.includes(value)
+        ? value
+        : null;
 }
 export function readPhiRuntimeControllerSettings(value) {
     if (!Array.isArray(value)) {

package/plugins/runtime/phi-slot-child-frame-client.js

@@ -7,9 +7,13 @@ import { PhiSlotChildViewportEffectsObserver } from "./phi-slot-child-viewport-e
 import { createPhiRenderableBlockReceiver, usePhiRenderableBlockRuntime, } from "../../components/runtime/renderable-block-runtime";
 import { PhiRuntimeSignalEmissionBoundary, PhiSignalIdentityProvider, } from "../../components/runtime/runtime-signal-identity";
 import { PhiSlotChildFrameView, } from "./phi-slot-child-frame-view";
+import { PhiLayoutSignalSurfaceProvider } from "../../components/layouts/phi-layout-signal-surface";
+import { usePhiVisualAnchor } from "../../components/runtime/runtime-visual-anchors";
 export function PhiSlotChildFrameClient({ kind, blockId, config, runtime, signalScope, runtimeSignalEmissionsEnabled = true, chrome, children, ...viewProps }) {
     const receiver = createPhiRenderableBlockReceiver(kind === "widget" ? "widget" : "layout", blockId);
     const resolvedSignalScope = signalScope ?? (kind === "widget" ? "widget" : "layout");
+    // The frame is where an instance is drawn, so it is what a Tour step pointing at `cms:<id>` finds.
+    const anchorRef = usePhiVisualAnchor(receiver);
     const blockRuntime = usePhiRenderableBlockRuntime({
         blockId,
         receiver,
@@ -24,9 +28,7 @@ export function PhiSlotChildFrameClient({ kind, blockId, config, runtime, signal
         minSize: config?.minSize,
         maxSize: config?.maxSize,
         collapsedSizeHint: config?.collapsedSizeHint,
-        background: config?.background,
-        border: config?.border,
-        shadow: config?.shadow,
+        surface: config?.surface,
         opacity: config?.opacity,
         effects: config?.effects,
         capabilities: config?.capabilities,
@@ -46,9 +48,7 @@ export function PhiSlotChildFrameClient({ kind, blockId, config, runtime, signal
         minSize: blockRuntime.state.minSize,
         maxSize: blockRuntime.state.maxSize,
         collapsedSizeHint: blockRuntime.state.collapsedSizeHint,
-        background: blockRuntime.state.background,
-        border: blockRuntime.state.border,
-        shadow: blockRuntime.state.shadow,
+        surface: blockRuntime.state.surface,
         zIndex: blockRuntime.state.zIndex,
         opacity: blockRuntime.state.opacity,
         effects: blockRuntime.state.effects,
@@ -63,10 +63,19 @@ export function PhiSlotChildFrameClient({ kind, blockId, config, runtime, signal
     const effectsTrigger = effectsAttributes?.["data-phi-effects-trigger"];
     const shouldObserveVisibility = effectsTrigger === "on_visible";
     const shouldWaitForReady = effectsTrigger === "on_ready";
+    /*
+     * A Layout draws its Surface itself, so what Signals set for it is handed to the Layout rather than
+     * drawn here -- and only once a Signal has set something, so until then the Layout's own config (in the
+     * Builder, the draft being edited) stays the answer.
+     */
+    const signalledLayoutSurface = kind !== "widget" && blockId != null
+        && blockRuntime.state.surface !== (config?.surface ?? undefined)
+        ? { blockId, surface: blockRuntime.state.surface ?? null }
+        : null;
     const enhancedChildren = (_jsxs(PhiSignalIdentityProvider, { value: {
             sender: receiver,
             receiver,
             scope: resolvedSignalScope,
-        }, children: [_jsx(PhiRuntimeSignalEmissionBoundary, { enabled: runtimeSignalEmissionsEnabled, children: children }), chrome, shouldObserveVisibility ? (_jsx(PhiSlotChildEffectsVisibilityObserver, { once: effectsAttributes?.["data-phi-effects-once"] !== "false" })) : null, shouldWaitForReady ? _jsx(PhiEffectsReadyTrigger, {}) : null, viewportEffects.length > 0 ? (_jsx(PhiSlotChildViewportEffectsObserver, { effects: viewportEffects })) : null] }));
-    return (_jsx(PhiSlotChildFrameView, { ...viewProps, kind: kind, blockId: blockId, receiver: receiver, config: resolvedConfig, effectsState: blockRuntime.state.effectsState, children: enhancedChildren }));
+        }, children: [_jsx(PhiRuntimeSignalEmissionBoundary, { enabled: runtimeSignalEmissionsEnabled, children: _jsx(PhiLayoutSignalSurfaceProvider, { value: signalledLayoutSurface, children: children }) }), chrome, shouldObserveVisibility ? (_jsx(PhiSlotChildEffectsVisibilityObserver, { once: effectsAttributes?.["data-phi-effects-once"] !== "false" })) : null, shouldWaitForReady ? _jsx(PhiEffectsReadyTrigger, {}) : null, viewportEffects.length > 0 ? (_jsx(PhiSlotChildViewportEffectsObserver, { effects: viewportEffects })) : null] }));
+    return (_jsx(PhiSlotChildFrameView, { ...viewProps, kind: kind, blockId: blockId, receiver: receiver, config: resolvedConfig, effectsState: blockRuntime.state.effectsState, anchorRef: anchorRef, children: enhancedChildren }));
 }

package/plugins/runtime/phi-slot-child-frame-view.d.ts

@@ -1,10 +1,16 @@
-import type { CSSProperties, MouseEventHandler, PointerEventHandler, ReactNode } from "react";
+import type { CSSProperties, MouseEventHandler, PointerEventHandler, ReactNode, Ref } from "react";
 import type { PhiRenderableBlock, PhiSlotSizePolicy, PhiCmsInstanceId } from "../../types";
+import type { PhiSurfacePolicy } from "../../types/surface";
 import { type PhiSlotChildKind } from "./slot-size-policy";
 import type { PhiRenderableBlockReceiver } from "../../components/runtime/renderable-block-runtime";
 export type PhiSlotChildFrameViewProps = {
     kind: PhiSlotChildKind;
     slotSizePolicy?: PhiSlotSizePolicy | null;
+    /**
+     * Who draws a Widget's Surface, from its plugin; the frame draws it only under `frame`, the answer
+     * when nothing is said. A Layout's frame never draws one -- the Layout draws its own.
+     */
+    surfacePolicy?: PhiSurfacePolicy | null;
     blockId?: PhiCmsInstanceId | null;
     receiver?: PhiRenderableBlockReceiver | null;
     config?: Partial<PhiRenderableBlock> | null;
@@ -20,7 +26,9 @@ export type PhiSlotChildFrameViewProps = {
     onClick?: MouseEventHandler<HTMLDivElement>;
     onClickCapture?: MouseEventHandler<HTMLDivElement>;
     onPointerLeave?: PointerEventHandler<HTMLDivElement>;
+    /** The live frame's element, for its visual anchor; the static frame has none to register. */
+    anchorRef?: Ref<HTMLDivElement>;
     children: ReactNode;
 };
 export declare function requiresPhiSlotChildEffectsObserver(config: Partial<PhiRenderableBlock> | null | undefined, disableEffects?: boolean): boolean;
-export declare function PhiSlotChildFrameView({ kind, slotSizePolicy, blockId, receiver, config, explicitInlineSize, explicitBlockSize, disableEffects, effectsState, className, style, builderWidgetTitle, builderWidgetSelected, builderWidgetPopupOpen, onClick, onClickCapture, onPointerLeave, children, }: PhiSlotChildFrameViewProps): import("react").JSX.Element;
+export declare function PhiSlotChildFrameView({ kind, slotSizePolicy, surfacePolicy, blockId, receiver, config, explicitInlineSize, explicitBlockSize, disableEffects, effectsState, className, style, builderWidgetTitle, builderWidgetSelected, builderWidgetPopupOpen, onClick, onClickCapture, onPointerLeave, anchorRef, children, }: PhiSlotChildFrameViewProps): import("react").JSX.Element;

package/plugins/runtime/phi-slot-child-frame-view.js

@@ -1,21 +1,11 @@
-import { jsx as _jsx } from "react/jsx-runtime";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { resolveRenderableBlockEffectsAttributes, resolveRenderableBlockEffectsStyle, resolveRenderableBlockStaticEffectsStyle, resolveRenderableBlockViewportEffects, } from "../../helpers/renderable-block-effects";
-import { resolvePhiBorderWidgetStyle } from "../../helpers/border-widget-style";
-import { resolvePhiBackgroundWidgetStyle } from "../../components/widgets/config/background";
-import { combinePhiBoxShadows, resolvePhiShadow } from "../../helpers/layout-style";
+import { resolvePhiSurfaceStyle } from "../../helpers/surface-style";
+import { PHI_LAYOUT_SURFACE_RADIUS } from "../../components/layouts/phi-layout-contract";
+import { PhiSurfaceGroundLayer } from "../../components/surface/phi-surface-ground";
+import { PhiSurfaceTone } from "../../components/surface/phi-surface-tone";
 import { buildPhiSlotChildClassName, buildPhiSlotChildDataAttributes, resolvePhiEffectiveSlotSizePolicy, resolvePhiSlotChildBaseStyle, resolvePhiSlotChildExplicitAxes, resolvePhiSlotChildSizeConstraints, resolvePhiSlotChildSizeStyle, resolvePhiSlotSizePolicy, } from "./slot-size-policy";
 import { resolvePhiRenderableBlockGeometry } from "../../types/renderable-block-geometry";
-function resolvePhiSlotChildBorderStyle(border) {
-    if (border == null) {
-        return {};
-    }
-    if (typeof border === "string") {
-        return { border };
-    }
-    return typeof border === "object" && !Array.isArray(border)
-        ? resolvePhiBorderWidgetStyle(border)
-        : {};
-}
 export function requiresPhiSlotChildEffectsObserver(config, disableEffects = false) {
     if (disableEffects) {
         return false;
@@ -26,7 +16,7 @@ export function requiresPhiSlotChildEffectsObserver(config, disableEffects = fal
         trigger === "on_ready" ||
         resolveRenderableBlockViewportEffects(config).length > 0);
 }
-export function PhiSlotChildFrameView({ kind, slotSizePolicy, blockId, receiver, config, explicitInlineSize, explicitBlockSize, disableEffects = false, effectsState, className, style, builderWidgetTitle, builderWidgetSelected, builderWidgetPopupOpen, onClick, onClickCapture, onPointerLeave, children, }) {
+export function PhiSlotChildFrameView({ kind, slotSizePolicy, surfacePolicy, blockId, receiver, config, explicitInlineSize, explicitBlockSize, disableEffects = false, effectsState, className, style, builderWidgetTitle, builderWidgetSelected, builderWidgetPopupOpen, onClick, onClickCapture, onPointerLeave, anchorRef, children, }) {
     const resolvedVisibility = config?.visibility ?? "visible";
     const resolvedEnabled = config?.enabled ?? true;
     const resolvedConfig = { ...config, visibility: resolvedVisibility };
@@ -49,24 +39,18 @@ export function PhiSlotChildFrameView({ kind, slotSizePolicy, blockId, receiver,
     const effectsAttributes = disableEffects
         ? undefined
         : resolveRenderableBlockEffectsAttributes(resolvedConfig);
-    const resolvedBackgroundStyle = resolvedConfig.background == null
-        ? {}
-        : resolvePhiBackgroundWidgetStyle(resolvedConfig.background);
-    return (_jsx("div", { hidden: resolvedVisibility === "hidden", className: [buildPhiSlotChildClassName(policy), className, resolvedConfig.className].filter(Boolean).join(" "), "data-phi-slot-child-frame": "true", "data-phi-renderable-block": "true", "data-phi-slot-child-kind": kind, "data-phi-block-id": blockId ?? undefined, "data-phi-signal-receiver": receiver ?? undefined, "data-phi-block-render-mode": resolvedConfig.renderMode, "data-phi-block-visibility": resolvedVisibility, "data-phi-viewport-flags": resolvedConfig.viewportFlags || undefined, "data-phi-block-enabled": resolvedEnabled ? "true" : "false", "data-phi-debug-scaffold": resolvedConfig.debugMode ? "on" : undefined, "data-phi-builder-widget-title": builderWidgetTitle?.trim() || undefined, "data-phi-builder-widget-selected": builderWidgetSelected ? "true" : undefined, "data-phi-builder-popup-open": builderWidgetPopupOpen ? "true" : undefined, ...effectsAttributes, "data-phi-effects-state": effectsState ?? effectsAttributes?.["data-phi-effects-state"], ...buildPhiSlotChildDataAttributes(policy, {
+    const surface = kind === "widget" && surfacePolicy === "frame"
+        ? resolvePhiSurfaceStyle(resolvedConfig.surface, { cornerFallback: PHI_LAYOUT_SURFACE_RADIUS })
+        : null;
+    return (_jsxs("div", { ref: anchorRef, hidden: resolvedVisibility === "hidden", className: [buildPhiSlotChildClassName(policy), className, resolvedConfig.className, surface?.className].filter(Boolean).join(" "), "data-phi-slot-child-frame": "true", "data-phi-renderable-block": "true", "data-phi-slot-child-kind": kind, "data-phi-block-id": blockId ?? undefined, "data-phi-signal-receiver": receiver ?? undefined, "data-phi-block-render-mode": resolvedConfig.renderMode, "data-phi-block-visibility": resolvedVisibility, "data-phi-viewport-flags": resolvedConfig.viewportFlags || undefined, "data-phi-block-enabled": resolvedEnabled ? "true" : "false", "data-phi-debug-scaffold": resolvedConfig.debugMode ? "on" : undefined, "data-phi-builder-widget-title": builderWidgetTitle?.trim() || undefined, "data-phi-builder-widget-selected": builderWidgetSelected ? "true" : undefined, "data-phi-builder-popup-open": builderWidgetPopupOpen ? "true" : undefined, ...effectsAttributes, "data-phi-effects-state": effectsState ?? effectsAttributes?.["data-phi-effects-state"], ...buildPhiSlotChildDataAttributes(policy, {
             explicitInlineSize: resolvedExplicitInlineSize,
             explicitBlockSize: resolvedExplicitBlockSize,
             ...resolvePhiSlotChildSizeConstraints(geometry),
         }), style: {
             ...resolvePhiSlotChildBaseStyle(policy),
             ...resolvePhiSlotChildSizeStyle(geometry, policy),
-            ...resolvedBackgroundStyle,
-            ...resolvePhiSlotChildBorderStyle(resolvedConfig.border),
+            ...surface?.style,
             ...(resolvedConfig.zIndex == null ? {} : { zIndex: resolvedConfig.zIndex }),
-            ...(kind !== "widget"
-                ? {}
-                : {
-                    boxShadow: combinePhiBoxShadows(resolvedBackgroundStyle.boxShadow, resolvePhiShadow(resolvedConfig.shadow)),
-                }),
             ...(resolvedConfig.opacity == null ? {} : { opacity: resolvedConfig.opacity }),
             ...(resolvedEnabled
                 ? {}
@@ -77,5 +61,5 @@ export function PhiSlotChildFrameView({ kind, slotSizePolicy, blockId, receiver,
             ...(resolvedVisibility === "collapsed" ? { overflow: "hidden" } : {}),
             ...effectsStyle,
             ...style,
-        }, onClick: onClick, onClickCapture: onClickCapture, onPointerLeave: onPointerLeave, children: children }));
+        }, onClick: onClick, onClickCapture: onClickCapture, onPointerLeave: onPointerLeave, children: [_jsx(PhiSurfaceGroundLayer, { ground: surface?.ground ?? null }), surface?.className ? (_jsx(PhiSurfaceTone, { tone: resolvedConfig.surface?.tone, children: children })) : children] }));
 }

package/plugins/runtime/phi-slot-child-frame.d.ts

@@ -1,9 +1,11 @@
 import type { CSSProperties, MouseEventHandler, PointerEventHandler, ReactNode } from "react";
 import type { PhiRenderableBlock, PhiRenderableBlockRuntime, PhiSignalScope, PhiSlotSizePolicy, PhiCmsInstanceId } from "../../types";
+import type { PhiSurfacePolicy } from "../../types/surface";
 import { type PhiSlotChildKind } from "./slot-size-policy";
 export type PhiSlotChildFrameProps = {
     kind: PhiSlotChildKind;
     slotSizePolicy?: PhiSlotSizePolicy | null;
+    surfacePolicy?: PhiSurfacePolicy | null;
     blockId?: PhiCmsInstanceId | null;
     config?: Partial<PhiRenderableBlock> | null;
     runtime?: PhiRenderableBlockRuntime;

package/plugins/runtime/phi-slot-child-frame.js

@@ -22,5 +22,5 @@ export function PhiSlotChildFrame(props) {
         return (_jsx(PhiRuntimeModuleRenderClientHost, { type: PhiRuntimeRenderClientType.SlotChildFrameEnhancer, componentProps: { ...props }, slotChildSizing: resolvePhiSlotChildSizingForConfig(kind, props.slotSizePolicy, config) }));
     }
     const receiver = createPhiSlotChildReceiver(blockId);
-    return (_jsx(PhiSlotChildFrameView, { kind: kind, slotSizePolicy: props.slotSizePolicy, blockId: blockId, receiver: receiver, config: config, explicitInlineSize: props.explicitInlineSize, explicitBlockSize: props.explicitBlockSize, disableEffects: props.disableEffects, className: props.className, style: props.style, builderWidgetTitle: props.builderWidgetTitle, builderWidgetSelected: props.builderWidgetSelected, builderWidgetPopupOpen: props.builderWidgetPopupOpen, onClick: props.onClick, onClickCapture: props.onClickCapture, onPointerLeave: props.onPointerLeave, children: children }));
+    return (_jsx(PhiSlotChildFrameView, { kind: kind, slotSizePolicy: props.slotSizePolicy, surfacePolicy: props.surfacePolicy, blockId: blockId, receiver: receiver, config: config, explicitInlineSize: props.explicitInlineSize, explicitBlockSize: props.explicitBlockSize, disableEffects: props.disableEffects, className: props.className, style: props.style, builderWidgetTitle: props.builderWidgetTitle, builderWidgetSelected: props.builderWidgetSelected, builderWidgetPopupOpen: props.builderWidgetPopupOpen, onClick: props.onClick, onClickCapture: props.onClickCapture, onPointerLeave: props.onPointerLeave, children: children }));
 }

package/plugins/runtime/phi-slot-child-viewport-effects-observer.js

@@ -1,6 +1,6 @@
 "use client";
 import { jsx as _jsx } from "react/jsx-runtime";
-import { useEffect, useRef } from "react";
+import { useEffect, useMemo, useRef } from "react";
 import { PHI_RENDERABLE_BLOCK_DEFAULT_VIEWPORT_EFFECT } from "../../helpers/renderable-block-defaults";
 function resolveRangePoint(point, rect, viewportWidth, viewportHeight, axis) {
     const viewportSize = axis === "x" ? viewportWidth : viewportHeight;
@@ -108,10 +108,17 @@ function applyViewportEffectValues(target, values) {
 }
 export function PhiSlotChildViewportEffectsObserver({ effects, }) {
     const markerRef = useRef(null);
+    /*
+     * The frame resolves the effects anew on every render, so the list is a new array each time. Keyed by
+     * what it says, the observer and its listeners are built once per set of effects instead of per
+     * render -- which also reset the scale to 1 every time.
+     */
+    const effectsKey = JSON.stringify(effects);
+    const stableEffects = useMemo(() => JSON.parse(effectsKey), [effectsKey]);
     useEffect(() => {
         const marker = markerRef.current;
         const target = marker?.parentElement;
-        if (!target || effects.length === 0 || typeof IntersectionObserver === "undefined") {
+        if (!target || stableEffects.length === 0 || typeof IntersectionObserver === "undefined") {
             return undefined;
         }
         let active = false;
@@ -121,7 +128,7 @@ export function PhiSlotChildViewportEffectsObserver({ effects, }) {
             if (!active) {
                 return;
             }
-            applyViewportEffectValues(target, resolveViewportEffectValues(effects, target));
+            applyViewportEffectValues(target, resolveViewportEffectValues(stableEffects, target));
         };
         const scheduleUpdate = () => {
             if (frameId != null) {
@@ -142,7 +149,7 @@ export function PhiSlotChildViewportEffectsObserver({ effects, }) {
             }
         }, { rootMargin: "50% 50% 50% 50%", threshold: 0 });
         const handleScrollOrResize = () => scheduleUpdate();
-        target.style.setProperty("--phi-effects-viewport-scale", "1");
+        target.style.setProperty("--phi-stableEffects-viewport-scale", "1");
         observer.observe(target);
         window.addEventListener("scroll", handleScrollOrResize, { passive: true });
         window.addEventListener("resize", handleScrollOrResize);
@@ -155,6 +162,6 @@ export function PhiSlotChildViewportEffectsObserver({ effects, }) {
                 window.cancelAnimationFrame(frameId);
             }
         };
-    }, [effects]);
+    }, [stableEffects]);
     return _jsx("span", { ref: markerRef, hidden: true, "data-phi-effects-viewport-observer": "true" });
 }

package/plugins/runtime/slot-size-policy.d.ts

@@ -1,6 +1,6 @@
 import { type CSSProperties, type ReactNode } from "react";
 import type { PhiSlotAxisSizePolicy, PhiSlotSizePolicy, PhiNormalizedSlotSizePolicy } from "../../types";
-import { type PhiRenderableBlockGeometryInput, type PhiResolvedBlockGeometry, type PhiResolvedBlockLength } from "../../types/renderable-block-geometry";
+import { type PhiRenderableBlockGeometryInput, type PhiResolvedBlockGeometry } from "../../types/renderable-block-geometry";
 export type PhiSlotChildKind = "widget" | "layout";
 export type PhiSlotChildSizing = {
     policy: PhiNormalizedSlotSizePolicy;
@@ -79,5 +79,4 @@ export declare function buildPhiSlotChildDataAttributes(policy: PhiNormalizedSlo
 };
 export declare function resolvePhiSlotChildSizing(child: ReactNode, fallbackKind?: PhiSlotChildKind): PhiSlotChildSizing;
 export declare function resolvePhiSlotChildBaseStyle(policy: PhiNormalizedSlotSizePolicy): CSSProperties;
-export declare function resolvePhiSlotChildInlineMaximum(max: PhiResolvedBlockLength | null, inlinePolicy: PhiSlotAxisSizePolicy): string | undefined;
 export declare function resolvePhiSlotChildSizeStyle(geometry: PhiResolvedBlockGeometry, policy: PhiNormalizedSlotSizePolicy): CSSProperties;

package/plugins/runtime/slot-size-policy.js

@@ -169,14 +169,25 @@ export function resolvePhiSlotChildSizing(child, fallbackKind = "widget") {
     if (sizingProps?.policy) {
         return sizingProps;
     }
-    const configConstraints = resolvePhiSlotChildSizeConstraints(resolvePhiRenderableBlockGeometry(props.config));
+    const configGeometry = resolvePhiRenderableBlockGeometry(props.config);
+    const configConstraints = resolvePhiSlotChildSizeConstraints(configGeometry);
+    /*
+     * A size stated in the child's config is as explicit as one stated in its flags. A bare frame handed
+     * only `config` used to read as unsized here while the frame itself drew it fixed, so the Layout
+     * stretched what the frame had sized.
+     */
+    const configExplicit = resolvePhiSlotChildExplicitAxes(configGeometry);
     if (props.slotSizePolicy != null || props.kind != null) {
         const resolvedKind = props.kind === "widget" || props.kind === "layout"
             ? props.kind
             : fallbackKind;
         const explicit = {
-            explicitInlineSize: props.explicitInlineSize === true || props["data-phi-layout-explicit-width"] === "true",
-            explicitBlockSize: props.explicitBlockSize === true || props["data-phi-layout-explicit-height"] === "true",
+            explicitInlineSize: props.explicitInlineSize === true
+                || props["data-phi-layout-explicit-width"] === "true"
+                || configExplicit.explicitInlineSize,
+            explicitBlockSize: props.explicitBlockSize === true
+                || props["data-phi-layout-explicit-height"] === "true"
+                || configExplicit.explicitBlockSize,
         };
         return {
             policy: resolvePhiEffectiveSlotSizePolicy(resolvePhiSlotSizePolicy(props.slotSizePolicy, resolvedKind), explicit),
@@ -197,8 +208,8 @@ export function resolvePhiSlotChildSizing(child, fallbackKind = "widget") {
             : undefined,
     }, fallbackKind);
     const explicit = {
-        explicitInlineSize: props["data-phi-layout-explicit-width"] === "true",
-        explicitBlockSize: props["data-phi-layout-explicit-height"] === "true",
+        explicitInlineSize: props["data-phi-layout-explicit-width"] === "true" || configExplicit.explicitInlineSize,
+        explicitBlockSize: props["data-phi-layout-explicit-height"] === "true" || configExplicit.explicitBlockSize,
     };
     return {
         // Idempotent: an element that already wrote the effective policy into its attributes says the same again.
@@ -281,7 +292,7 @@ export function resolvePhiSlotChildBaseStyle(policy) {
  * as it did before.
  */
 const PHI_SLOT_CHILD_CAPPED_MAX_UNITS = ["px", "em", "rem", "vw", "vh"];
-export function resolvePhiSlotChildInlineMaximum(max, inlinePolicy) {
+function resolvePhiSlotChildInlineMaximum(max, inlinePolicy) {
     if (max == null) {
         return undefined;
     }

package/plugins/runtime-modules/accounting/module.d.ts

@@ -4,9 +4,9 @@
  * to the Core Runtime Controller; a Module's own goes into that Module's Controller, mounted on demand.
  */
 export declare const PHI_ACCOUNTING_RUNTIME_MODULE: {
-    description: string;
     icon: string;
     category: "foundation";
+    description: string;
     moduleId: "@phis/ui/modules/accounting";
     serverBinding: import("../../../types").PhiRuntimeModuleServerBinding;
     kind: "module";

package/plugins/runtime-modules/accounting/trees/phi-default-accounting-page-tree.js

@@ -1,4 +1,5 @@
 import { createPhiPresetCmsInstanceIdMap } from "../../../../types/cms-instance-id";
+import { PHI_SURFACE_CARD } from "../../../../helpers/surface-presets";
 import { PHI_ACCOUNTING_RUNTIME_MODULE_ID } from "../ids";
 import { PHI_CMS_SEQUENTIAL_LAYOUT_SLOTS } from "../../../../constants/cms-layout-types";
 import { PhiCmsPageType } from "../../../../constants/phi-cms";
@@ -38,6 +39,7 @@ export async function buildPhiDefaultAccountingPageTree({ page, }) {
                     title: "Accounting",
                     description: "Invoices and billing workflows for this site.",
                     variant: "compact",
+                    surface: PHI_SURFACE_CARD,
                 },
             }),
         ],

package/plugins/runtime-modules/admin/definition.d.ts

@@ -1,13 +1,8 @@
 export declare const PHI_ADMIN_RUNTIME_MODULE_DEFINITION: Omit<{
-    area: "admin";
-    moduleId: "@phis/ui/modules/admin";
     serverBinding: import("../../../types").PhiRuntimeModuleServerBinding;
-    controllerType: "@phis/ui/modules/admin/controller/default";
-    controller: import("../contracts").PhiRuntimeModuleControllerDescriptor;
     description: string;
     category: "foundation";
     iconFamily: string;
-    controllerMountPolicy: "area";
     formProviders: {
         handlers: {
             key: `${string}/${string}`;
@@ -25,6 +20,8 @@ export declare const PHI_ADMIN_RUNTIME_MODULE_DEFINITION: Omit<{
             credentialPolicy: "site-session";
         }[];
     };
+    moduleId: "@phis/ui/modules/admin";
+    area: "admin";
 }, "area"> & {
     kind: "module";
     eligibleAreas: readonly ["public" | "app" | "admin" | "builder" | "editor" | "accounting"];

package/plugins/runtime-modules/admin/definition.js

@@ -1,19 +1,13 @@
-import { PHI_ADMIN_RUNTIME_CONTROLLER_DEFINITION } from "../../../plugins/runtime-modules/admin/controller/definition";
-import { PHI_ADMIN_CONTROLLER_TYPE } from "../../../plugins/runtime-modules/admin/controller/address";
-import { buildPhiRuntimeModuleControllerDescriptor } from "../contracts";
 import { definePhiAreaBaseRuntimeModuleDefinition } from "../area-base-definition";
-import { PHI_ADMIN_RUNTIME_MODULE_ID } from "./ids";
+import { PHI_ADMIN_RUNTIME_MODULE_IDENTITY } from "./ids";
 import { PHI_CORE_SERVER_BINDING } from "../../../types/server-capabilities";
 import { PHI_ADMIN_SETTINGS_FORM_HANDLER_PROVIDER_DESCRIPTORS } from "../../../plugins/runtime-modules/admin/forms";
 export const PHI_ADMIN_RUNTIME_MODULE_DEFINITION = definePhiAreaBaseRuntimeModuleDefinition({
     area: "admin",
-    moduleId: PHI_ADMIN_RUNTIME_MODULE_ID,
+    ...PHI_ADMIN_RUNTIME_MODULE_IDENTITY,
     serverBinding: PHI_CORE_SERVER_BINDING,
-    controllerType: PHI_ADMIN_CONTROLLER_TYPE,
-    controller: buildPhiRuntimeModuleControllerDescriptor(PHI_ADMIN_RUNTIME_CONTROLLER_DEFINITION),
     description: "Locked Admin Area shell, navigation surface, root route, and Admin settings.",
     category: "foundation",
     iconFamily: "admin",
-    controllerMountPolicy: "area",
     formProviders: { handlers: PHI_ADMIN_SETTINGS_FORM_HANDLER_PROVIDER_DESCRIPTORS },
 });

package/plugins/runtime-modules/admin/forms.d.ts

@@ -1,9 +1,6 @@
 export declare const PHI_ADMIN_SETTINGS_FORM_IDS: {
     readonly general: `${string}/forms/${string}`;
 };
-export declare const PHI_ADMIN_SETTINGS_FORM_HANDLER_KEYS: {
-    readonly general: "site.admin.settings";
-};
 export declare const PHI_ADMIN_RUNTIME_MODULE_FORMS: readonly [import("../contracts").PhiRuntimeModuleFormDefinition];
 export declare const PHI_ADMIN_SETTINGS_FORM_HANDLER_PROVIDER_DESCRIPTORS: {
     key: `${string}/${string}`;

package/plugins/runtime-modules/admin/forms.js

@@ -1,14 +1,13 @@
+import { createPhiFormLabelSetLoader } from "../../../components/forms/shared-form-loaders";
 import { PHI_ADMIN_RUNTIME_MODULE_ID } from "../../../plugins/runtime-modules/admin/ids";
 import { createPhiFormId } from "../../../types/form-id";
 import { PHI_SHARED_PACKAGE_NAME } from "../../../types/signals";
-import { flattenPhiFormLabels } from "../../../components/forms/form-labels";
 import { PHI_FORM_FIELD_PROVIDER_KEYS, PHI_FORM_VALIDATION_PROVIDER_KEYS, createPhiSharedFormProviderKey, } from "../../../components/forms/form-provider-contract";
 import { definePhiRuntimeModuleForm } from "../../../components/forms/form-registry";
-import { readPhiServerApiCredentials } from "../../../helpers/phis-server-credentials";
 export const PHI_ADMIN_SETTINGS_FORM_IDS = {
     general: createPhiFormId(PHI_SHARED_PACKAGE_NAME, "admin/settings-general"),
 };
-export const PHI_ADMIN_SETTINGS_FORM_HANDLER_KEYS = {
+const PHI_ADMIN_SETTINGS_FORM_HANDLER_KEYS = {
     general: "site.admin.settings",
 };
 const LABEL_SET_KEY = "@phis/ui/modules/admin/labels/settings";
@@ -67,27 +66,19 @@ const PHI_ADMIN_SETTINGS_GENERAL_FORM_DESCRIPTOR = {
         gap: { compact: "sm", medium: "base" },
     },
 };
-async function loadLabels(context) {
-    const { getPhiAdminSettingsWidgetLabels } = await import("../../../components/widgets/label-sets/admin-settings");
-    const labels = await getPhiAdminSettingsWidgetLabels({
-        apiBaseUrl: readPhiServerApiCredentials().apiBaseUrl,
-        internalToken: readPhiServerApiCredentials().internalToken,
-        locale: context.runtime.locale.current,
-    });
-    return flattenPhiFormLabels({
-        name: labels.fields.siteName,
-        nameRequired: labels.fields.siteName,
-        hostname: labels.fields.hostname,
-        hostnameRequired: labels.fields.hostname,
-        publicBaseUrl: labels.fields.publicBaseUrl,
-        publicBaseUrlRequired: labels.fields.publicBaseUrl,
-        publicBaseUrlInvalid: labels.feedback.errorInvalidPublicBaseUrl,
-        supportEmail: labels.fields.supportEmail,
-        supportEmailRequired: labels.fields.supportEmail,
-        supportEmailInvalid: labels.feedback.errorInvalidSupportEmail,
-        actions: { submitLabel: labels.submitLabel },
-    });
-}
+const loadLabels = createPhiFormLabelSetLoader(() => import("../../../components/widgets/label-sets/admin-settings").then((module) => module.getPhiAdminSettingsWidgetLabels), (labels) => ({
+    name: labels.fields.siteName,
+    nameRequired: labels.feedback.requiredSiteName,
+    hostname: labels.fields.hostname,
+    hostnameRequired: labels.feedback.requiredHostname,
+    publicBaseUrl: labels.fields.publicBaseUrl,
+    publicBaseUrlRequired: labels.feedback.requiredPublicBaseUrl,
+    publicBaseUrlInvalid: labels.feedback.errorInvalidPublicBaseUrl,
+    supportEmail: labels.fields.supportEmail,
+    supportEmailRequired: labels.feedback.requiredSupportEmail,
+    supportEmailInvalid: labels.feedback.errorInvalidSupportEmail,
+    actions: { submitLabel: labels.submitLabel },
+}));
 export const PHI_ADMIN_RUNTIME_MODULE_FORMS = [
     definePhiRuntimeModuleForm({
         ownerModuleId: PHI_ADMIN_RUNTIME_MODULE_ID,

package/plugins/runtime-modules/admin/ids.d.ts

@@ -1 +1,10 @@
 export declare const PHI_ADMIN_RUNTIME_MODULE_ID: "@phis/ui/modules/admin";
+/**
+ * The Module's identity as its Label Sets inherit it (`definePhiRuntimeModuleLabelSet`): the id and,
+ * where a Module declares one, its source locale. Stated here beside the id and spread into the
+ * definition, so a Label Set a tree or a form reads does not import the definition that imports the
+ * tree -- and a Module that writes in another language says so once.
+ */
+export declare const PHI_ADMIN_RUNTIME_MODULE_IDENTITY: {
+    readonly moduleId: "@phis/ui/modules/admin";
+};

package/plugins/runtime-modules/admin/ids.js

@@ -1,2 +1,11 @@
 import { PHI_SHARED_PACKAGE_NAME } from "../../../types/signals";
 export const PHI_ADMIN_RUNTIME_MODULE_ID = `${PHI_SHARED_PACKAGE_NAME}/modules/admin`;
+/**
+ * The Module's identity as its Label Sets inherit it (`definePhiRuntimeModuleLabelSet`): the id and,
+ * where a Module declares one, its source locale. Stated here beside the id and spread into the
+ * definition, so a Label Set a tree or a form reads does not import the definition that imports the
+ * tree -- and a Module that writes in another language says so once.
+ */
+export const PHI_ADMIN_RUNTIME_MODULE_IDENTITY = {
+    moduleId: PHI_ADMIN_RUNTIME_MODULE_ID,
+};