@phis/ui 0.2.1 → 0.3.0

package/helpers/static-render-path.d.ts

@@ -0,0 +1,12 @@
+/** Where the static route tree lives. Only the proxy may send a request there (`next/site-proxy.ts`). */
+export declare const PHI_STATIC_RENDER_PREFIX = "/static-render";
+/**
+ * The address the visitor opened, given the path a render sees.
+ *
+ * The proxy rewrites an anonymous Public request to `/static-render/<marker>/<mode>/<locale>/<path>`, and
+ * a static render's `usePathname` answers that address while the browser answers `/<locale>/<path>`. A
+ * Client Widget deciding by the path -- the current navigation item, a breadcrumb, a locale link -- drew
+ * one thing on the server and another in the browser, and the page failed to hydrate (React #418,
+ * AUDIT-2026-10-13 PM14). Every other path is returned as it is.
+ */
+export declare function readPhiVisitorPathname(pathname: string): string;

package/helpers/static-render-path.js

@@ -0,0 +1,18 @@
+/** Where the static route tree lives. Only the proxy may send a request there (`next/site-proxy.ts`). */
+export const PHI_STATIC_RENDER_PREFIX = "/static-render";
+/**
+ * The address the visitor opened, given the path a render sees.
+ *
+ * The proxy rewrites an anonymous Public request to `/static-render/<marker>/<mode>/<locale>/<path>`, and
+ * a static render's `usePathname` answers that address while the browser answers `/<locale>/<path>`. A
+ * Client Widget deciding by the path -- the current navigation item, a breadcrumb, a locale link -- drew
+ * one thing on the server and another in the browser, and the page failed to hydrate (React #418,
+ * AUDIT-2026-10-13 PM14). Every other path is returned as it is.
+ */
+export function readPhiVisitorPathname(pathname) {
+    if (!pathname.startsWith(`${PHI_STATIC_RENDER_PREFIX}/`)) {
+        return pathname;
+    }
+    // "", "static-render", marker, mode, then the visitor's own segments.
+    return `/${pathname.split("/").slice(4).join("/")}`;
+}

package/helpers/structure-widget-swap.js

@@ -64,9 +64,9 @@ export function swapPhiStructureWidgetsInTree({ childLayouts, childWidgets, root
     const sourceExtracted = extractPhiStructureNode(childLayouts, childWidgets, sourceWidgetId, "widget");
     const targetExtracted = extractPhiStructureNode(sourceExtracted.childLayouts, sourceExtracted.childWidgets, targetWidgetId, "widget");
     if (!sourceExtracted.node ||
-        !("contentId" in sourceExtracted.node) ||
+        !("contentVersionId" in sourceExtracted.node) ||
         !targetExtracted.node ||
-        !("contentId" in targetExtracted.node)) {
+        !("contentVersionId" in targetExtracted.node)) {
         return null;
     }
     const withSourceAtTarget = insertWidgetAtStructurePosition(targetExtracted.childLayouts, targetExtracted.childWidgets, rootNodeId, sourceExtracted.node, targetExtracted.node);
@@ -76,9 +76,9 @@ export function swapPhiStructureWidgetsAcrossTrees({ source, target, }) {
     const sourceExtracted = extractPhiStructureNode(source.childLayouts, source.childWidgets, source.widgetId, "widget");
     const targetExtracted = extractPhiStructureNode(target.childLayouts, target.childWidgets, target.widgetId, "widget");
     if (!sourceExtracted.node ||
-        !("contentId" in sourceExtracted.node) ||
+        !("contentVersionId" in sourceExtracted.node) ||
         !targetExtracted.node ||
-        !("contentId" in targetExtracted.node)) {
+        !("contentVersionId" in targetExtracted.node)) {
         return null;
     }
     return {

package/helpers/surface-presets.d.ts

@@ -0,0 +1,81 @@
+import { type PhiSurface } 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 declare const PHI_SURFACE_CARD: {
+    readonly background: {
+        readonly base: {
+            readonly kind: "color";
+            readonly color: "var(--ant-color-bg-container)";
+        };
+        readonly overlay: null;
+        readonly filter: null;
+    };
+    readonly borderSource: "custom";
+    readonly border: {
+        readonly borderWidth: 1;
+        readonly borderStyle: "solid";
+        readonly borderColor: "var(--ant-color-border-secondary)";
+    };
+    readonly 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 declare const PHI_SURFACE_WASH: {
+    readonly background: {
+        readonly base: {
+            readonly kind: "color";
+            readonly color: "var(--ant-color-fill-quaternary)";
+        };
+        readonly overlay: null;
+        readonly filter: null;
+    };
+    readonly borderSource: "none";
+    readonly shadow: "none";
+};
+export declare const PHI_SURFACE_PRESETS: {
+    readonly card: {
+        readonly background: {
+            readonly base: {
+                readonly kind: "color";
+                readonly color: "var(--ant-color-bg-container)";
+            };
+            readonly overlay: null;
+            readonly filter: null;
+        };
+        readonly borderSource: "custom";
+        readonly border: {
+            readonly borderWidth: 1;
+            readonly borderStyle: "solid";
+            readonly borderColor: "var(--ant-color-border-secondary)";
+        };
+        readonly shadow: "soft";
+    };
+    readonly wash: {
+        readonly background: {
+            readonly base: {
+                readonly kind: "color";
+                readonly color: "var(--ant-color-fill-quaternary)";
+            };
+            readonly overlay: null;
+            readonly filter: null;
+        };
+        readonly borderSource: "none";
+        readonly shadow: "none";
+    };
+};
+export type PhiSurfacePresetId = keyof typeof PHI_SURFACE_PRESETS;
+export declare const PHI_SURFACE_PRESET_IDS: PhiSurfacePresetId[];
+/**
+ * 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 declare function resolvePhiSurfacePresetId(surface: PhiSurface | null | undefined): PhiSurfacePresetId | "none" | "custom";

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 = {}) {