@phis/ui 0.2.1 → 0.4.0

package/helpers/surface-presets.js

@@ -0,0 +1,65 @@
+import { PHI_COLOR } from "../theme/antd-css-var-contract";
+import { readPhiSurface } from "../types/surface";
+/**
+ * The looks a Surface can be given by name: plain Surface values, written into the Surface as they are.
+ *
+ * Nothing stores the name. A Preset writes the values, the Inspector's style switch writes the same
+ * values and reads back which of them a Surface still is -- so an author can start from a card and change
+ * its line, and the switch then says `custom` rather than claiming a card it no longer is.
+ */
+/** A card on the page: the Site's container ground, its quiet line, the soft shadow. */
+export const PHI_SURFACE_CARD = {
+    background: { base: { kind: "color", color: PHI_COLOR.bgContainer }, overlay: null, filter: null },
+    borderSource: "custom",
+    border: { borderWidth: 1, borderStyle: "solid", borderColor: PHI_COLOR.borderSecondary },
+    shadow: "soft",
+};
+/**
+ * The quietest ground the Theme has: a filling and nothing else -- no line, no depth. For a box that
+ * already stands on a container and only needs its content set off from it; the Form Widget's `wash`
+ * step, in Surface values. The fill is translucent, so on the page's own ground it all but disappears.
+ */
+export const PHI_SURFACE_WASH = {
+    background: { base: { kind: "color", color: PHI_COLOR.fillQuaternary }, overlay: null, filter: null },
+    borderSource: "none",
+    shadow: "none",
+};
+export const PHI_SURFACE_PRESETS = {
+    card: PHI_SURFACE_CARD,
+    wash: PHI_SURFACE_WASH,
+};
+export const PHI_SURFACE_PRESET_IDS = Object.keys(PHI_SURFACE_PRESETS);
+/*
+ * JSON with its keys in one order at every depth. A Surface that arrived with its keys in another
+ * order -- from storage, or rebuilt by a Control -- is the same look, and compared as written it read
+ * as `custom`.
+ */
+function stringifyCanonically(value) {
+    if (Array.isArray(value))
+        return `[${value.map(stringifyCanonically).join(",")}]`;
+    if (value !== null && typeof value === "object") {
+        const entries = Object.entries(value)
+            .filter(([, entry]) => entry !== undefined)
+            .sort(([left], [right]) => (left < right ? -1 : left > right ? 1 : 0));
+        return `{${entries.map(([key, entry]) => `${JSON.stringify(key)}:${stringifyCanonically(entry)}`).join(",")}}`;
+    }
+    return JSON.stringify(value) ?? "null";
+}
+function readLook(surface) {
+    const read = readPhiSurface(surface ?? null);
+    if (!read)
+        return null;
+    const { tone: _tone, ...look } = read;
+    void _tone;
+    return Object.keys(look).length > 0 ? stringifyCanonically(look) : null;
+}
+/**
+ * Which named look a Surface is, apart from its `tone`: `none` for no look at all, a preset's id where
+ * the values are exactly that preset's, `custom` for anything else.
+ */
+export function resolvePhiSurfacePresetId(surface) {
+    const look = readLook(surface);
+    if (look == null)
+        return "none";
+    return PHI_SURFACE_PRESET_IDS.find((id) => readLook(PHI_SURFACE_PRESETS[id]) === look) ?? "custom";
+}

package/helpers/surface-style.d.ts

@@ -0,0 +1,63 @@
+import type { CSSProperties } from "react";
+import { type PhiCmsBackgroundWidgetConfig } from "../components/widgets/config/background";
+import { type PhiSurface } from "../types/surface";
+/**
+ * The paint of a Surface when it lives on a layer of its own rather than on the box.
+ *
+ * Two things need that layer. A softened paint (`blur`) must not soften the content in front of it, and
+ * a filter on the box would. A moving picture (`motion`) travels inside the box while the box stands
+ * still. Either way the box keeps its edge, its depth and any glass pane, and the layer carries the paint.
+ */
+export type PhiSurfaceGround = {
+    /** The paint, already free of the pane: what the layer draws. */
+    paint: CSSProperties;
+    /** The softening, applied to the layer and never to the box. */
+    filter: string | null;
+    /** The Background to move, when it moves; the motion layer draws it from the original picture. */
+    motion: PhiCmsBackgroundWidgetConfig | null;
+};
+export type PhiResolvedSurface = {
+    /** What goes on the box: paint (unless a layer carries it), edge, corner, depth, pane. */
+    style: CSSProperties;
+    /** The layer the paint lives on, or `null` when the box carries its own paint. */
+    ground: PhiSurfaceGround | null;
+    /** Whether the Surface paints a ground at all -- a pane over nothing does not. */
+    paintsGround: boolean;
+    /**
+     * The class the box carries for its `tone`, or nothing for `inherit`. The box carries it and renders
+     * `PhiSurfaceTone` around its content; the class alone draws nothing.
+     */
+    className?: string;
+};
+export type PhiSurfaceStyleOptions = {
+    /**
+     * The corner a Surface takes where it states none.
+     *
+     * A Layout or a card is a surface on the page and answers silence with the Site's step
+     * (`--phi-surface-radius`); a Region spans its part of the frame and has no corner of its own. Applied
+     * as four longhands, never as the shorthand: a configured corner arrives as longhands, and React
+     * refuses a shorthand standing beside them.
+     */
+    cornerFallback?: string | number | null;
+    /**
+     * Put the paint on a layer even when nothing in the Surface asks for one -- a card that zooms its
+     * ground under the pointer needs the paint apart from the box to move it.
+     */
+    forceGroundLayer?: boolean;
+    /**
+     * Whether the caller can render a ground layer at all. A box drawn by a primitive it does not own -- an
+     * Overlay's Drawer or Modal -- cannot, so its paint stays on the box: unsoftened and unmoving, but there.
+     */
+    groundLayer?: boolean;
+};
+/**
+ * A Surface as CSS, in one place for every box that has one.
+ *
+ * The edge follows `borderSource`: `custom` draws the configured line and corners, `theme` the Site's own
+ * line, `none` states no line -- explicitly, because a Surface may be laid over a style that carries one.
+ * A Surface that states nothing about its edge has the source `none`. Depth is the Background's own shadow
+ * (a pane's) combined with the configured one.
+ */
+export declare function resolvePhiSurfaceStyle(surface: PhiSurface | null | undefined, options?: PhiSurfaceStyleOptions): PhiResolvedSurface;
+/** Whether a Surface draws anything a reader could see: a ground, a line, or depth. */
+export declare function phiSurfaceDrawsChrome(surface: PhiSurface | null | undefined): boolean;

package/helpers/surface-style.js

@@ -0,0 +1,74 @@
+import { normalizePhiBackgroundWidgetConfig, phiBackgroundWidgetConfigPaintsGround, resolvePhiBackgroundGroundFilter, resolvePhiBackgroundMotion, resolvePhiBackgroundMotionHostStyle, resolvePhiBackgroundWidgetStyle, } from "../components/widgets/config/background";
+import { resolvePhiCmsBorderSource } from "../types/cms-border-source";
+import { resolvePhiSurfaceToneClassName } from "../types/surface";
+import { resolvePhiSourcedBorderStyle } from "./border-widget-style";
+import { combinePhiBoxShadows, resolvePhiShadow } from "./layout-style";
+const PHI_SURFACE_EMPTY = { style: {}, ground: null, paintsGround: false };
+function resolvePhiSurfaceCorners(fallback, configured) {
+    const corner = (value) => value ?? fallback ?? undefined;
+    const corners = {
+        borderTopLeftRadius: corner(configured.borderTopLeftRadius),
+        borderTopRightRadius: corner(configured.borderTopRightRadius),
+        borderBottomRightRadius: corner(configured.borderBottomRightRadius),
+        borderBottomLeftRadius: corner(configured.borderBottomLeftRadius),
+    };
+    return Object.fromEntries(Object.entries(corners).filter(([, value]) => value != null));
+}
+/**
+ * A Surface as CSS, in one place for every box that has one.
+ *
+ * The edge follows `borderSource`: `custom` draws the configured line and corners, `theme` the Site's own
+ * line, `none` states no line -- explicitly, because a Surface may be laid over a style that carries one.
+ * A Surface that states nothing about its edge has the source `none`. Depth is the Background's own shadow
+ * (a pane's) combined with the configured one.
+ */
+export function resolvePhiSurfaceStyle(surface, options = {}) {
+    if (!surface) {
+        return PHI_SURFACE_EMPTY;
+    }
+    const background = surface.background ? normalizePhiBackgroundWidgetConfig(surface.background) : null;
+    const paintsGround = phiBackgroundWidgetConfigPaintsGround(background);
+    const groundFilter = background ? resolvePhiBackgroundGroundFilter(background) : null;
+    const motion = background ? resolvePhiBackgroundMotion(background) : null;
+    const needsGroundLayer = options.groundLayer !== false
+        && paintsGround
+        && (groundFilter != null || motion != null || options.forceGroundLayer === true);
+    const paint = background ? resolvePhiBackgroundWidgetStyle(background) : {};
+    const hostPaint = needsGroundLayer
+        ? (background ? resolvePhiBackgroundMotionHostStyle(background) : {})
+        : paint;
+    const ground = needsGroundLayer && background
+        ? {
+            paint: resolvePhiBackgroundWidgetStyle({ ...background, filter: null, motion: null }),
+            filter: groundFilter,
+            motion: motion ? background : null,
+        }
+        : null;
+    const borderSource = resolvePhiCmsBorderSource(surface.borderSource, surface.border);
+    const edge = resolvePhiSourcedBorderStyle(borderSource, surface.border);
+    const { border: line, ...configuredCorners } = edge;
+    const boxShadow = combinePhiBoxShadows(paint.boxShadow, resolvePhiShadow(surface.shadow));
+    return {
+        style: {
+            ...hostPaint,
+            ...(line == null ? {} : { border: line }),
+            ...resolvePhiSurfaceCorners(options.cornerFallback, configuredCorners),
+            ...(boxShadow == null ? {} : { boxShadow }),
+            // The layer sits behind the content at `z-index: -1`; the box has to be the stacking context that
+            // keeps it there rather than behind the page.
+            ...(ground ? { position: "relative", isolation: "isolate" } : {}),
+        },
+        ground,
+        paintsGround,
+        ...(surface.tone ? { className: resolvePhiSurfaceToneClassName(surface.tone) } : {}),
+    };
+}
+/** Whether a Surface draws anything a reader could see: a ground, a line, or depth. */
+export function phiSurfaceDrawsChrome(surface) {
+    if (!surface) {
+        return false;
+    }
+    return phiBackgroundWidgetConfigPaintsGround(surface.background ?? null)
+        || resolvePhiCmsBorderSource(surface.borderSource, surface.border) !== "none"
+        || (surface.shadow != null && surface.shadow !== "none");
+}

package/helpers/table-binding.d.ts

@@ -1,8 +1,12 @@
-import type { PhiTableProviderRowMoveMutationRequest, PhiTableRowIdentity } from "../types/table-widget";
+import type { PhiTableProviderRowMoveMutationRequest, PhiTableQuery, PhiTableQueryValue, PhiTableRowIdentity } from "../types/table-widget";
 type TableRow = Record<string, unknown>;
+/**
+ * The filters a query is sent with: the reader's, then what the outside handed in, then what the Page
+ * fixed. Last wins, so nothing the reader or a signal does can lift a fixed filter.
+ */
+export declare function mergePhiTableQueryFilters(query: PhiTableQuery, externalQuery: PhiTableQuery | undefined, fixedFilters: Readonly<Record<string, PhiTableQueryValue>> | undefined): Readonly<Record<string, PhiTableQueryValue>>;
 export declare function readPhiTableRowValue(row: TableRow, path: string): unknown;
 export declare function readPhiTableRowIdentity(row: TableRow, path: string): PhiTableRowIdentity | null;
-export declare function patchPhiTableRowValue(row: TableRow, path: string, value: unknown): TableRow;
 export declare function patchPhiTableBindingRows(rows: readonly TableRow[], rowIdentityPath: string, rowIdentity: PhiTableRowIdentity, patch: Readonly<Record<string, unknown>>): TableRow[];
 export declare function movePhiTableBindingRows(rows: readonly TableRow[], rowIdentityPath: string, request: Pick<PhiTableProviderRowMoveMutationRequest, "movedRowIdentity" | "beforeRowIdentity" | "afterRowIdentity">): readonly TableRow[];
 export declare function movePhiTableBindingTreeRows(rows: readonly TableRow[], rowIdentityPath: string, parentRowIdentityPath: string, request: Pick<PhiTableProviderRowMoveMutationRequest, "movedRowIdentity" | "targetParentRowIdentity" | "beforeRowIdentity" | "afterRowIdentity">): TableRow[];

package/helpers/table-binding.js

@@ -1,5 +1,16 @@
 import { isPhiRecord } from "./is-record";
 import { readPhiDotPath } from "./dot-path";
+/**
+ * The filters a query is sent with: the reader's, then what the outside handed in, then what the Page
+ * fixed. Last wins, so nothing the reader or a signal does can lift a fixed filter.
+ */
+export function mergePhiTableQueryFilters(query, externalQuery, fixedFilters) {
+    return {
+        ...(query.filters ?? {}),
+        ...(externalQuery?.filters ?? {}),
+        ...(fixedFilters ?? {}),
+    };
+}
 export function readPhiTableRowValue(row, path) {
     return readPhiDotPath(row, path);
 }
@@ -9,7 +20,7 @@ export function readPhiTableRowIdentity(row, path) {
         ? value
         : null;
 }
-export function patchPhiTableRowValue(row, path, value) {
+function patchPhiTableRowValue(row, path, value) {
     const segments = path.split(".").filter(Boolean);
     if (segments.length === 0)
         return row;

package/helpers/text-placeholders.d.ts

@@ -1,23 +1,4 @@
 import type { PhiBlockRuntime } from "../types";
-/**
- * The few facts a Site's own copy may name instead of spelling out, filled in when the page renders.
- *
- * A Preset is followed by every Site that adopts it, so a sentence in one cannot contain any Site's
- * name -- and a sentence that resolved the name while the Preset was being built kept whatever the
- * Site was called that day. The year is the same mistake with a clock attached: "© 2026" written into
- * a Widget's config is still 2026 next January.
- *
- * Deliberately a handful of names rather than a path into the runtime. Anything addressable turns Site
- * copy into a template language, with its escaping, its error cases and its reach into whatever the
- * runtime happens to carry; these are the ones sentences actually need. A name nothing answers is left
- * standing -- `{jahr}` renders as `{jahr}`, which is how a typo gets noticed and found.
- *
- * `site.wordmark` and `site.name` are not the same answer and both are worth having. The wordmark is
- * what the Site calls itself in writing, the name is what it is filed under, and a Site that has set a
- * wordmark means the first one when it writes its own name into a sentence. Where none is set the
- * wordmark resolver falls back to the name, so asking for it is never the emptier question.
- */
-export declare function buildPhiTextPlaceholders(runtime: PhiBlockRuntime): Record<string, string | number>;
 /**
  * What the translator gets to see, with every name taken out of its reach.
  *
@@ -32,7 +13,12 @@ export declare function buildPhiTextPlaceholders(runtime: PhiBlockRuntime): Reco
  * Every name is masked, not only the ones something answers. A typo has to survive the round trip to
  * still be a recognizable typo: masked, `{jahr}` comes back as `%2` and is put back as `{jahr}`.
  */
-export declare function maskPhiTextPlaceholders(text: string): {
+export declare function maskPhiTextPlaceholders(text: string, 
+/**
+ * How many tokens the text already carries: a list entry's values stand as `%1` to `%k`, so its names
+ * count on from `%k+1` (see `resolvePhiTextPlaceholders`).
+ */
+offset?: number): {
     text: string;
     names: readonly string[];
 };
@@ -44,7 +30,11 @@ export declare function maskPhiTextPlaceholders(text: string): {
  * that came back, not to the text that went in. It is the order the Table footer already keeps
  * (TABLES.md, "Footer"), and the reason a value is never itself translated.
  *
+ * `values` are the text's own: a list entry that reads "Site key: %1" carries the key beside it, so the
+ * sentence is translated once for every Site and the key is never sent along. They take the first
+ * tokens, and the masked names the ones after them.
+ *
  * Read in one pass rather than token by token, because `%1` is the start of `%10` and a sentence with
  * ten names would have had its tenth eaten by its first.
  */
-export declare function resolvePhiTextPlaceholders(text: string, names: readonly string[], runtime: PhiBlockRuntime | undefined): string;
+export declare function resolvePhiTextPlaceholders(text: string, names: readonly string[], runtime: PhiBlockRuntime | undefined, values?: readonly string[]): string;

package/helpers/text-placeholders.js

@@ -19,7 +19,7 @@ const PHI_TEXT_PLACEHOLDER_TOKEN_PATTERN = /%(\d+)/g;
  * wordmark means the first one when it writes its own name into a sentence. Where none is set the
  * wordmark resolver falls back to the name, so asking for it is never the emptier question.
  */
-export function buildPhiTextPlaceholders(runtime) {
+function buildPhiTextPlaceholders(runtime) {
     const placeholders = {
         "site.name": runtime.site.name?.trim() || runtime.site.key,
         "site.wordmark": resolvePhiBrandWordmarkText(runtime),
@@ -45,14 +45,19 @@ export function buildPhiTextPlaceholders(runtime) {
  * Every name is masked, not only the ones something answers. A typo has to survive the round trip to
  * still be a recognizable typo: masked, `{jahr}` comes back as `%2` and is put back as `{jahr}`.
  */
-export function maskPhiTextPlaceholders(text) {
+export function maskPhiTextPlaceholders(text, 
+/**
+ * How many tokens the text already carries: a list entry's values stand as `%1` to `%k`, so its names
+ * count on from `%k+1` (see `resolvePhiTextPlaceholders`).
+ */
+offset = 0) {
     if (!text.includes("{")) {
         return { text, names: [] };
     }
     const names = [];
     const masked = text.replace(PHI_TEXT_PLACEHOLDER_PATTERN, (_match, name) => {
         names.push(name);
-        return `%${names.length}`;
+        return `%${offset + names.length}`;
     });
     return { text: masked, names };
 }
@@ -64,20 +69,31 @@ export function maskPhiTextPlaceholders(text) {
  * that came back, not to the text that went in. It is the order the Table footer already keeps
  * (TABLES.md, "Footer"), and the reason a value is never itself translated.
  *
+ * `values` are the text's own: a list entry that reads "Site key: %1" carries the key beside it, so the
+ * sentence is translated once for every Site and the key is never sent along. They take the first
+ * tokens, and the masked names the ones after them.
+ *
  * Read in one pass rather than token by token, because `%1` is the start of `%10` and a sentence with
  * ten names would have had its tenth eaten by its first.
  */
-export function resolvePhiTextPlaceholders(text, names, runtime) {
-    if (names.length === 0) {
+export function resolvePhiTextPlaceholders(text, names, runtime, values = []) {
+    if (names.length === 0 && values.length === 0) {
         return text;
     }
-    const values = runtime ? buildPhiTextPlaceholders(runtime) : {};
+    const placeholders = names.length > 0 && runtime ? buildPhiTextPlaceholders(runtime) : {};
     return text.replace(PHI_TEXT_PLACEHOLDER_TOKEN_PATTERN, (token, digits) => {
-        const name = names[Number(digits) - 1];
+        const index = Number(digits) - 1;
+        if (index < 0) {
+            return token;
+        }
+        if (index < values.length) {
+            return values[index];
+        }
+        const name = names[index - values.length];
         if (name === undefined) {
             return token;
         }
-        const value = values[name];
+        const value = placeholders[name];
         return value === undefined ? `{${name}}` : String(value);
     });
 }

package/helpers/translation-cache.js

@@ -100,7 +100,9 @@ export function clearPhiTranslationCache(options) {
     }
     for (const key of [...TRANSLATION_CACHE.keys()]) {
         const [keyScope = "", , keyTargetLocale = ""] = key.split(SEPARATOR);
-        if ((scope == null || keyScope === scope) && (!targetLocale || keyTargetLocale === targetLocale)) {
+        // A locale tag is case-insensitive, and the keys carry the canonical spelling (`pt-BR`) while a
+        // caller may name it however it read it -- so both sides are compared in one case.
+        if ((scope == null || keyScope === scope) && (!targetLocale || keyTargetLocale.toLowerCase() === targetLocale)) {
             TRANSLATION_CACHE.delete(key);
         }
     }

package/helpers.d.ts

@@ -10,4 +10,7 @@ export * from "./helpers/widget-dimension-plugin-fields";
 export * from "./helpers/translation-format";
 export { buildPhiCmsLayoutNode, buildPhiCmsWidgetNode, } from "./helpers/cms-node-factories";
 export * from "./helpers/cms-preset-nodes";
+export * from "./helpers/cms-dialog";
+export { buildPhiSettingsPageShellTree, type PhiSettingsPageShellFormSection, type PhiSettingsPageShellOverlay, type PhiSettingsPageShellPanel, type PhiSettingsPageShellSection, type PhiSettingsPageShellWidgetSection, } from "./components/regions/presets/phi-settings-page-shell-tree";
 export * from "./helpers/format-date-time";
+export { PHI_SURFACE_CARD, PHI_SURFACE_WASH } from "./helpers/surface-presets";

package/helpers.js

@@ -10,4 +10,12 @@ export * from "./helpers/widget-dimension-plugin-fields";
 export * from "./helpers/translation-format";
 export { buildPhiCmsLayoutNode, buildPhiCmsWidgetNode, } from "./helpers/cms-node-factories";
 export * from "./helpers/cms-preset-nodes";
+export * from "./helpers/cms-dialog";
+/*
+ * The one Settings page shell (SETTINGS.md section 4). Public because the contract holds for every
+ * Module alike: an installed package's Settings page composes through the same builder a first-party one
+ * does, and could not if only the first-party could reach it.
+ */
+export { buildPhiSettingsPageShellTree, } from "./components/regions/presets/phi-settings-page-shell-tree";
 export * from "./helpers/format-date-time";
+export { PHI_SURFACE_CARD, PHI_SURFACE_WASH } from "./helpers/surface-presets";

package/module-dashboard-cards.d.ts

@@ -0,0 +1,15 @@
+/**
+ * What a Module package needs to put cards on a Dashboard, and nothing else.
+ *
+ * Narrow for the reason `@phis/ui/module/labels` is: a package outside this one reads it from the Server
+ * half every route of the Site imports, and a wider barrel would pull its graph in with it. The
+ * first-party Modules import `types/dashboard-cards` and `gateway/site-api-request` by relative path;
+ * this is the same reach, for a Module that has only the package's exports.
+ *
+ * `fetchPhiSiteApi` is here because a card's payload is almost always one question to Core, asked with
+ * the credentials the card context carries. Without it a package writes the token, Site key and cookie
+ * headers itself, which is a copy of a protocol that is this package's to change. See DASHBOARD.md.
+ */
+import "server-only";
+export { createPhiDashboardCardId, isPhiDashboardCardId, type PhiDashboardCardContext, type PhiDashboardCardDescriptor, type PhiDashboardCardForm, type PhiDashboardCardId, type PhiDashboardCardPayload, type PhiDashboardCardProvider, } from "./types/dashboard-cards";
+export { fetchPhiSiteApi, type PhiSiteApiRequest } from "./gateway/site-api-request";

package/module-dashboard-cards.js

@@ -0,0 +1,15 @@
+/**
+ * What a Module package needs to put cards on a Dashboard, and nothing else.
+ *
+ * Narrow for the reason `@phis/ui/module/labels` is: a package outside this one reads it from the Server
+ * half every route of the Site imports, and a wider barrel would pull its graph in with it. The
+ * first-party Modules import `types/dashboard-cards` and `gateway/site-api-request` by relative path;
+ * this is the same reach, for a Module that has only the package's exports.
+ *
+ * `fetchPhiSiteApi` is here because a card's payload is almost always one question to Core, asked with
+ * the credentials the card context carries. Without it a package writes the token, Site key and cookie
+ * headers itself, which is a copy of a protocol that is this package's to change. See DASHBOARD.md.
+ */
+import "server-only";
+export { createPhiDashboardCardId, isPhiDashboardCardId, } from "./types/dashboard-cards";
+export { fetchPhiSiteApi } from "./gateway/site-api-request";

package/module-records.d.ts

@@ -0,0 +1,14 @@
+/**
+ * What a Module package needs to serve a record Provider and to draw what one answers, and nothing else
+ * (MODULES.md, Record Providers).
+ *
+ * Narrow for the reason `@phis/ui/module/dashboard-cards` is: a package outside this one reads it from the
+ * Server half every route of the Site imports. A Provider's resolver is the package's own function; the
+ * types say what it is asked with, `fetchPhiSiteApi` asks Core with the credentials the context carries,
+ * and `resolvePhiRecordSource` is how one of the package's Server Widgets reads the record its binding
+ * names -- once per request, however many Widgets are bound to it.
+ */
+import "server-only";
+export type { PhiRuntimeModuleRecordProviderServerDefinition, PhiRuntimeRecordProviderContext, PhiRuntimeRecordProviderResolver, } from "./types/record-provider";
+export { resolvePhiRecordSource, type PhiRecordSourceResult } from "./server-helpers/record-source";
+export { fetchPhiSiteApi, type PhiSiteApiRequest } from "./gateway/site-api-request";

package/module-records.js

@@ -0,0 +1,13 @@
+/**
+ * What a Module package needs to serve a record Provider and to draw what one answers, and nothing else
+ * (MODULES.md, Record Providers).
+ *
+ * Narrow for the reason `@phis/ui/module/dashboard-cards` is: a package outside this one reads it from the
+ * Server half every route of the Site imports. A Provider's resolver is the package's own function; the
+ * types say what it is asked with, `fetchPhiSiteApi` asks Core with the credentials the context carries,
+ * and `resolvePhiRecordSource` is how one of the package's Server Widgets reads the record its binding
+ * names -- once per request, however many Widgets are bound to it.
+ */
+import "server-only";
+export { resolvePhiRecordSource } from "./server-helpers/record-source";
+export { fetchPhiSiteApi } from "./gateway/site-api-request";

package/net/log.d.ts

@@ -1,4 +1,3 @@
 export type { PhiLogEvent, PhiLogLevel, PhiLogService, PhiLogger, PhiLoggerContext, } from "@phis/contracts/logging";
-import type { PhiLogEvent, PhiLogLevel, PhiLoggerContext, PhiLogger } from "@phis/contracts/logging";
-export declare function createLogger(context: Partial<PhiLoggerContext>): PhiLogger;
+import type { PhiLogEvent, PhiLogLevel, PhiLoggerContext } from "@phis/contracts/logging";
 export declare function logRuntimeEvent(level: PhiLogLevel, event: string, input?: PhiLogEvent & Partial<PhiLoggerContext>): void;

package/net/log.js

@@ -95,7 +95,7 @@ function createLoggerFromContext(context) {
         },
     };
 }
-export function createLogger(context) {
+function createLogger(context) {
     return createLoggerFromContext(normalizeContext(context));
 }
 export function logRuntimeEvent(level, event, input = {}) {

package/next/area-route.d.ts

@@ -1,6 +1,7 @@
 import "server-only";
 import type { Metadata } from "next";
 import type { PhiCmsErrorPageProps } from "../components/cms/phi-cms-error-page";
+import { type PhiCmsRootErrorPageLoader } from "../components/cms/phi-cms-deferred-error-page";
 import { type PhiCmsAreaChrome } from "../components/cms/phi-cms-root-layout";
 import { PhiCmsRootSlotPage } from "../components/cms/phi-cms-root-slot-page";
 import type { PhiCmsSiteBridge } from "../types/cms-plugins";
@@ -102,7 +103,7 @@ export type PhiNextRootErrorArea = {
  * the Public landing page's script payload with them. Deciding here rather than redirecting still
  * keeps both the status line and the address the visitor asked for.
  */
-export declare function createPhiNextRootErrorPage(code: PhiCmsErrorPageProps["code"], area: PhiNextRootErrorArea): () => Promise<import("react").JSX.Element>;
+export declare function createPhiNextRootErrorPage(code: PhiCmsErrorPageProps["code"], loadErrorPage: PhiCmsRootErrorPageLoader): () => import("react").JSX.Element;
 /** The Public Area's boundary. Its root segment is a locale, so it only reaches it through `params`. */
 export declare function createPhiNextDynamicRootBoundary(cmsBridge: PhiCmsSiteBridge, Provider?: React.ComponentType<{
     children: React.ReactNode;
@@ -129,7 +130,16 @@ type PhiNextStaticPublicLayoutProps = PhiNextStaticAreaLayoutProps & {
     }>;
 };
 /** One branch of the static tree: the Area boundary and the Shell, for the page its segments name. */
-export declare function createPhiNextStaticPublicLayout(cmsBridge: PhiCmsSiteBridge, chrome?: PhiCmsAreaChrome): ({ children, headerBottom, hero, siderRight, footerTop, drawer, params, }: PhiNextStaticPublicLayoutProps) => Promise<import("react").JSX.Element>;
+export declare function createPhiNextStaticPublicLayout(cmsBridge: PhiCmsSiteBridge, chrome: PhiCmsAreaChrome, 
+/**
+ * The Client boundary of the Public Area, mounted here as the dynamic tree mounts it in its `[root]`
+ * Layout. Mounted in the root Layout instead, the Widget clients it loads were split against what the
+ * root segment alone holds, and every one carried its own copy of what the deeper segments already
+ * load: 37 kB gzip more on an anonymous `/de` than on a signed-in one (AUDIT-2026-10-13, PM14).
+ */
+Provider: React.ComponentType<{
+    children: React.ReactNode;
+}>): ({ children, headerBottom, hero, siderRight, footerTop, drawer, params, }: PhiNextStaticPublicLayoutProps) => Promise<import("react").JSX.Element>;
 export declare function createPhiNextStaticPublicPage(cmsBridge: PhiCmsSiteBridge): {
     Page: ({ params }: PhiNextDynamicRootPageProps) => Promise<import("react").JSX.Element>;
     generateMetadata: ({ params }: PhiNextDynamicRootPageProps) => Promise<Metadata>;
@@ -141,7 +151,11 @@ export declare function createPhiNextStaticPublicSlotPage(cmsBridge: PhiCmsSiteB
  * Next gives a `not-found.tsx` no params, so the Site's file reads the locale from `next/root-params` --
  * a module whose getters Next generates from that Site's own segment names -- and hands it in.
  */
-export declare function createPhiNextStaticPublicNotFound(cmsBridge: PhiCmsSiteBridge): ({ locale }: {
+export declare function createPhiNextStaticPublicNotFound(cmsBridge: PhiCmsSiteBridge, 
+/** The Public Area's Client boundary, which the root Layout no longer holds; see the Layout above. */
+Provider: React.ComponentType<{
+    children: React.ReactNode;
+}>): ({ locale }: {
     locale: string;
 }) => import("react").JSX.Element;
 export {};

package/next/area-route.js

@@ -5,6 +5,7 @@ import { buildPhiAreaPageMetadata } from "../helpers/phi-metadata";
 import { resolvePhiSitePublicBase } from "../helpers/phi-seo";
 import { readPhiSiteRuntimeConfigSync } from "../helpers/site-runtime";
 import { PhiCmsErrorPage } from "../components/cms/phi-cms-error-page";
+import { PhiCmsDeferredErrorPage, } from "../components/cms/phi-cms-deferred-error-page";
 import { PhiCmsAreaBoundary, PhiCmsAreaShell, } from "../components/cms/phi-cms-root-layout";
 import { PhiCmsRootPage } from "../components/cms/phi-cms-root-page";
 import { PhiThemeBlockCatalogProvider } from "../components/root/phi-theme-block-catalog-provider";
@@ -120,24 +121,22 @@ export function createPhiNextStaticAreaSlotPage(root, cmsBridge, regionType) {
  * the Public landing page's script payload with them. Deciding here rather than redirecting still
  * keeps both the status line and the address the visitor asked for.
  */
-export function createPhiNextRootErrorPage(code, area) {
-    const { loadBridge, Boundary } = area;
-    return async function PhiNextRootErrorPage() {
-        const cmsBridge = await loadBridge();
-        /*
-         * A refusal draws no Shell at all, and asks for none later.
-         *
-         * Next renders every refusal boundary of the matched segments into the response whether one is
-         * shown or not, so a Shell resolved here was paid for by every successful Page as well -- measured
-         * at three resolutions and roughly 56 KB per request, for output almost no visitor sees. Fetching
-         * it from the client afterwards moved that cost rather than removing it, and bought a page that
-         * changed shape after it had appeared.
-         *
-         * The Client boundary is still mounted, because the error page renders a page tree like any other
-         * and cannot resolve its Runtime Module Clients without one. What the visitor loses is the
-         * navigation, which is why the 404 result carries a link to the Area root.
-         */
-        return (_jsx(Boundary, { children: _jsx(PhiCmsErrorPage, { code: code, cmsBridge: cmsBridge, area: "public" }) }));
+export function createPhiNextRootErrorPage(code, loadErrorPage) {
+    /*
+     * A refusal draws no Shell at all, and resolves its page only once it is shown.
+     *
+     * Next renders every refusal boundary of the matched segments into the response whether one is
+     * shown or not. A Shell resolved here was paid for by every successful Page -- measured at three
+     * resolutions and roughly 56 KB per request -- and so was the error page itself: Area and Page for
+     * 404, 403 and 401, six of the sixteen server calls of a plain page view (measured 03.10.2026). The
+     * route now carries a code and the Site's Action; the page is rendered when a refusal is on screen
+     * (`PhiCmsDeferredErrorPage`, `renderPhiCmsRootErrorPage`), and the plain copy stands until then.
+     *
+     * What the visitor loses is the navigation, which is why the 404 result carries a link to the Area
+     * root, and the moment before the Site's page arrives -- on a page that answers almost no request.
+     */
+    return function PhiNextRootErrorPage() {
+        return _jsx(PhiCmsDeferredErrorPage, { code: code, load: loadErrorPage });
     };
 }
 /** The Public Area's boundary. Its root segment is a locale, so it only reaches it through `params`. */
@@ -200,11 +199,18 @@ export function createPhiNextDynamicRootSlotPage(cmsBridge, regionType) {
     };
 }
 /** One branch of the static tree: the Area boundary and the Shell, for the page its segments name. */
-export function createPhiNextStaticPublicLayout(cmsBridge, chrome = "shell") {
+export function createPhiNextStaticPublicLayout(cmsBridge, chrome, 
+/**
+ * The Client boundary of the Public Area, mounted here as the dynamic tree mounts it in its `[root]`
+ * Layout. Mounted in the root Layout instead, the Widget clients it loads were split against what the
+ * root segment alone holds, and every one carried its own copy of what the deeper segments already
+ * load: 37 kB gzip more on an anonymous `/de` than on a signed-in one (AUDIT-2026-10-13, PM14).
+ */
+Provider) {
     const staticBridge = toPhiStaticCmsSiteBridge(cmsBridge);
     return async function PhiNextStaticPublicLayout({ children, headerBottom, hero, siderRight, footerTop, drawer, params, }) {
         const { root, path } = await params;
-        return (_jsx(PhiCmsAreaBoundary, { root: root, cmsBridge: staticBridge, pagePath: path, children: _jsx(PhiCmsAreaShell, { root: root, cmsBridge: staticBridge, chrome: chrome, pagePath: path, headerBottom: headerBottom, hero: hero, siderRight: siderRight, footerTop: footerTop, drawer: drawer, children: children }) }));
+        return (_jsx(Provider, { children: _jsx(PhiCmsAreaBoundary, { root: root, cmsBridge: staticBridge, pagePath: path, children: _jsx(PhiCmsAreaShell, { root: root, cmsBridge: staticBridge, chrome: chrome, pagePath: path, headerBottom: headerBottom, hero: hero, siderRight: siderRight, footerTop: footerTop, drawer: drawer, children: children }) }) }));
     };
 }
 export function createPhiNextStaticPublicPage(cmsBridge) {
@@ -219,9 +225,11 @@ export function createPhiNextStaticPublicSlotPage(cmsBridge, regionType) {
  * Next gives a `not-found.tsx` no params, so the Site's file reads the locale from `next/root-params` --
  * a module whose getters Next generates from that Site's own segment names -- and hands it in.
  */
-export function createPhiNextStaticPublicNotFound(cmsBridge) {
+export function createPhiNextStaticPublicNotFound(cmsBridge, 
+/** The Public Area's Client boundary, which the root Layout no longer holds; see the Layout above. */
+Provider) {
     const staticBridge = toPhiStaticCmsSiteBridge(cmsBridge);
     return function PhiNextStaticPublicNotFound({ locale }) {
-        return _jsx(PhiCmsErrorPage, { code: 404, cmsBridge: staticBridge, area: "public", locale: locale });
+        return (_jsx(Provider, { children: _jsx(PhiCmsErrorPage, { code: 404, cmsBridge: staticBridge, area: "public", locale: locale }) }));
     };
 }