@phis/ui 0.1.0

package/theme/phi-button-shadow.js

@@ -0,0 +1,64 @@
+/**
+ * The shadow under each kind of Button, as a step rather than as CSS.
+ *
+ * Ant Design draws it with a component token per kind -- `defaultShadow`, `primaryShadow`,
+ * `dangerShadow` -- tinted from three different places: a fill, the primary outline, a fade of the error
+ * background that is also the ground of every error Alert and Tag. None of them is only the shadow, so a
+ * Theme that wants another one sets the component token.
+ *
+ * A component token has one value for both modes, and a shadow does not: the dark that reads as an edge
+ * on a light ground disappears into a dark one. So a Theme stores the step, and the step becomes CSS
+ * where the mode is known -- the root theme and the Theme workspace preview. A kind the Theme leaves
+ * unset keeps Ant Design's tinted line.
+ *
+ * The steps are Button shadows of their own rather than the Shadow presets a Card takes: those spread
+ * wide enough to lift a panel, and under something as small as a Button they read as a blur, not an edge.
+ */
+export const PHI_BUTTON_SHADOW_KINDS = ["default", "primary", "danger"];
+export const PHI_BUTTON_SHADOW_STEPS = ["none", "soft", "strong"];
+const PHI_BUTTON_SHADOW_CSS = {
+    light: {
+        none: "none",
+        soft: "0 1px 2px rgba(0, 0, 0, 0.16)",
+        strong: "0 2px 3px rgba(0, 0, 0, 0.28)",
+    },
+    dark: {
+        none: "none",
+        soft: "0 1px 2px rgba(0, 0, 0, 0.45)",
+        strong: "0 2px 3px rgba(0, 0, 0, 0.7)",
+    },
+};
+const PHI_BUTTON_SHADOW_TOKENS = {
+    default: "defaultShadow",
+    primary: "primaryShadow",
+    danger: "dangerShadow",
+};
+export function isPhiButtonShadowStep(value) {
+    return typeof value === "string" && PHI_BUTTON_SHADOW_STEPS.includes(value);
+}
+/** The Button component tokens a Theme's shadow steps stand for in one mode; empty when it sets none. */
+export function buildPhiButtonShadowComponentTokens(buttons, mode) {
+    const tokens = {};
+    for (const kind of PHI_BUTTON_SHADOW_KINDS) {
+        const step = buttons?.shadow?.[kind];
+        if (isPhiButtonShadowStep(step)) {
+            tokens[PHI_BUTTON_SHADOW_TOKENS[kind]] = PHI_BUTTON_SHADOW_CSS[mode][step];
+        }
+    }
+    return tokens;
+}
+/**
+ * The Theme's component overrides with its Button shadows laid in for one mode.
+ *
+ * Under the Site's own `components.Button`, so a token somebody set there by hand still wins.
+ */
+export function applyPhiButtonShadowComponentTokens(components, buttons, mode) {
+    const shadowTokens = buildPhiButtonShadowComponentTokens(buttons, mode);
+    if (Object.keys(shadowTokens).length === 0) {
+        return components ?? undefined;
+    }
+    return {
+        ...(components ?? {}),
+        Button: { ...shadowTokens, ...(components?.Button ?? {}) },
+    };
+}

package/theme/phi-container-breakpoints.d.ts

@@ -0,0 +1,2 @@
+export declare const PHI_CONTAINER_BREAKPOINT_COL2 = 144;
+export declare const PHI_CONTAINER_BREAKPOINT_COL3 = 377;

package/theme/phi-container-breakpoints.js

@@ -0,0 +1,2 @@
+export const PHI_CONTAINER_BREAKPOINT_COL2 = 144;
+export const PHI_CONTAINER_BREAKPOINT_COL3 = 377;

package/theme/phi-control-shape.d.ts

@@ -0,0 +1,102 @@
+export declare const PHI_CONTROL_SHAPES: readonly ["square", "subtle", "rounded", "pill"];
+export type PhiControlShape = (typeof PHI_CONTROL_SHAPES)[number];
+/**
+ * The stored form of a Control shape: one of the four names per corner.
+ *
+ * Four corners from the start, although only four equal corners render today, so that a shape which
+ * rounds two opposite corners can arrive later without a stored Theme changing its form. Names rather
+ * than pixels per corner, because the names are what keeps a shape size-aware: a pill corner on a small
+ * Control is still half that Control's height.
+ */
+export declare const PHI_CONTROL_SHAPE_CORNER_KEYS: readonly ["topLeft", "topRight", "bottomRight", "bottomLeft"];
+export type PhiControlShapeCornerKey = (typeof PHI_CONTROL_SHAPE_CORNER_KEYS)[number];
+export type PhiControlShapeCorners = Record<PhiControlShapeCornerKey, PhiControlShape>;
+export declare function createPhiControlShapeCorners(shape: PhiControlShape): PhiControlShapeCorners;
+/**
+ * The corners a record states, or `null` where it states none.
+ *
+ * Absent means the Theme follows the style block, which is an ordinary state. Anything else that is
+ * not four known names is a closed vocabulary broken, and it throws rather than render some shape
+ * nobody chose.
+ */
+export declare function readPhiControlShapeCorners(value: unknown): PhiControlShapeCorners | null;
+/**
+ * The one shape four corners render as.
+ *
+ * Unequal corners are a valid record but not yet a drawable one: antd carries a single radius per
+ * size, and every Control that rounds itself from that token would need its own override. Until that
+ * exists, a Theme that asks for it fails loudly instead of quietly rendering all four alike.
+ */
+export declare function resolvePhiUniformControlShape(corners: PhiControlShapeCorners): PhiControlShape;
+/** The shape a resolved Theme renders; the runtime fold has already put the style block's under it. */
+export declare function resolvePhiControlShape(value: unknown): PhiControlShape;
+/**
+ * Radius scale a Control shape resolves to. `SITE-CONFIG.md` requires the adapter to resolve the
+ * preset "for the active `controlSize`", so a shape is a scale rather than a single number.
+ *
+ * - `square` and `pill` are ABSOLUTE statements about geometry. No size can make "no rounding" or
+ *   "capsule" partially true, so both flatten every step: a small pill Button that is not a pill is
+ *   simply wrong.
+ * - `rounded` and `subtle` are RELATIVE to the numeric radius scale the Style tab owns directly.
+ *   `rounded` is that scale unchanged; `subtle` is the same scale shifted one step toward the small
+ *   end. Flattening these two would silently discard the Small and Large values an author just typed
+ *   and leave two of the three numeric inputs dead for half the shapes.
+ *
+ * `inner*` is the radius of a box nested INSIDE a Control body -- the Segmented item and thumb. antd
+ * keeps it one step below the body so the item never overruns its container; an absolute shape has to
+ * reach it too, or a pill Segmented ends up with square items inside a capsule.
+ */
+export type PhiControlShapeRadii = {
+    sm: number;
+    md: number;
+    lg: number;
+    innerSm: number;
+    innerMd: number;
+    innerLg: number;
+};
+export type PhiControlShapeRadiusTokens = {
+    borderRadiusXS?: unknown;
+    borderRadiusSM?: unknown;
+    borderRadius?: unknown;
+    borderRadiusLG?: unknown;
+};
+export declare function resolvePhiControlShapeRadii(shape: PhiControlShape, tokens?: PhiControlShapeRadiusTokens): PhiControlShapeRadii;
+export declare function resolvePhiControlShapeRadius(shape: PhiControlShape, tokens: PhiControlShapeRadiusTokens): number;
+/**
+ * Custom properties `styles/control-shape.css` reads. They carry the resolved numbers rather than a
+ * reference to an adapter token so a nested preview -- which runs its own draft scale through a plain
+ * `ConfigProvider` and therefore never redefines the ambient `--ant-border-radius-*` -- still resolves
+ * its OWN shape. Inheritance is also what makes nesting work at all: two rules that both match a
+ * Control tie on specificity and source order decides, while an inherited custom property is always
+ * taken from the nearest ancestor that declares it.
+ *
+ * The default size is deliberately absent: it is already carried by the component tokens, and a CSS
+ * rule strong enough to set it would also have to outrank antd's own `-circle` and `-round` Button
+ * shapes, which stay authoritative.
+ */
+export type PhiControlShapeCssVarSlot = Exclude<keyof PhiControlShapeRadii, "md">;
+export declare const PHI_CONTROL_SHAPE_CSS_VARS: {
+    readonly sm: "--phi-control-radius-sm";
+    readonly lg: "--phi-control-radius-lg";
+    readonly innerSm: "--phi-control-radius-inner-sm";
+    readonly innerMd: "--phi-control-radius-inner-md";
+    readonly innerLg: "--phi-control-radius-inner-lg";
+};
+export declare function buildPhiControlShapeCssVars(shape: PhiControlShape, tokens?: PhiControlShapeRadiusTokens): Record<`--${string}`, string>;
+/**
+ * Applies the shape to the Control components, outranking a raw adapter-level radius override.
+ *
+ * `SITE-CONFIG.md` requires this direction: "the resolved semantic Control shape takes precedence over
+ * conflicting raw adapter-level component-radius overrides so there is one effective source of truth."
+ * Overriding a single corner is a different layer and never conflicts -- antd carries only scalar radius
+ * tokens, so a Widget config such as `borderTopLeftRadius` owns that case.
+ *
+ * Only the DEFAULT size is set here. antd reads `borderRadiusSM` and `borderRadiusLG` for the small and
+ * large variants, but those same two tokens also draw the Select dropdown, the DatePicker panel, and the
+ * ColorPicker swatches, so a component override cannot reach one without the other. The small and large
+ * Control bodies are covered by `styles/control-shape.css`, which targets the size classes and leaves
+ * every popup on the surface scale.
+ */
+export declare function applyPhiControlShapeComponentTokens(components: Record<string, Record<string, unknown>>, shape: PhiControlShape, tokens: PhiControlShapeRadiusTokens): {
+    [x: string]: Record<string, unknown>;
+};

package/theme/phi-control-shape.js

@@ -0,0 +1,149 @@
+export const PHI_CONTROL_SHAPES = ["square", "subtle", "rounded", "pill"];
+/**
+ * The stored form of a Control shape: one of the four names per corner.
+ *
+ * Four corners from the start, although only four equal corners render today, so that a shape which
+ * rounds two opposite corners can arrive later without a stored Theme changing its form. Names rather
+ * than pixels per corner, because the names are what keeps a shape size-aware: a pill corner on a small
+ * Control is still half that Control's height.
+ */
+export const PHI_CONTROL_SHAPE_CORNER_KEYS = ["topLeft", "topRight", "bottomRight", "bottomLeft"];
+export function createPhiControlShapeCorners(shape) {
+    return { topLeft: shape, topRight: shape, bottomRight: shape, bottomLeft: shape };
+}
+/**
+ * The corners a record states, or `null` where it states none.
+ *
+ * Absent means the Theme follows the style block, which is an ordinary state. Anything else that is
+ * not four known names is a closed vocabulary broken, and it throws rather than render some shape
+ * nobody chose.
+ */
+export function readPhiControlShapeCorners(value) {
+    if (value === undefined || value === null) {
+        return null;
+    }
+    if (typeof value !== "object" || Array.isArray(value)) {
+        throw new Error(`Control shape must name its four corners, got ${JSON.stringify(value)}.`);
+    }
+    const record = value;
+    const unknownKeys = Object.keys(record).filter((key) => !PHI_CONTROL_SHAPE_CORNER_KEYS.includes(key));
+    if (unknownKeys.length > 0) {
+        throw new Error(`Control shape has unknown corners: ${unknownKeys.join(", ")}.`);
+    }
+    for (const key of PHI_CONTROL_SHAPE_CORNER_KEYS) {
+        if (!PHI_CONTROL_SHAPES.includes(record[key])) {
+            throw new Error(`Control shape corner "${key}" must be one of ${PHI_CONTROL_SHAPES.join(", ")}.`);
+        }
+    }
+    return record;
+}
+/**
+ * The one shape four corners render as.
+ *
+ * Unequal corners are a valid record but not yet a drawable one: antd carries a single radius per
+ * size, and every Control that rounds itself from that token would need its own override. Until that
+ * exists, a Theme that asks for it fails loudly instead of quietly rendering all four alike.
+ */
+export function resolvePhiUniformControlShape(corners) {
+    const shape = corners.topLeft;
+    if (PHI_CONTROL_SHAPE_CORNER_KEYS.some((key) => corners[key] !== shape)) {
+        throw new Error("Control shapes with differing corners are not rendered yet.");
+    }
+    return shape;
+}
+/** The shape a resolved Theme renders; the runtime fold has already put the style block's under it. */
+export function resolvePhiControlShape(value) {
+    const corners = readPhiControlShapeCorners(value);
+    if (!corners) {
+        throw new Error("A resolved Theme must state its Control shape; fold it through its style block first.");
+    }
+    return resolvePhiUniformControlShape(corners);
+}
+/**
+ * A capsule is derived from the rendered Control height, not persisted as `border-radius: 50%` --
+ * `SITE-CONFIG.md` rejects the percentage because it produces ellipses on a rectangular box. A radius
+ * far above any Control height clamps to exactly half the height in every browser, which is the
+ * implementation-native full radius the contract asks for.
+ */
+const PHI_CONTROL_SHAPE_FULL_RADIUS = 9999;
+function readTokenRadius(tokens, key, fallback) {
+    const value = tokens?.[key];
+    return typeof value === "number" && Number.isFinite(value) ? value : fallback;
+}
+export function resolvePhiControlShapeRadii(shape, tokens) {
+    const xs = readTokenRadius(tokens, "borderRadiusXS", 2);
+    const sm = readTokenRadius(tokens, "borderRadiusSM", 2);
+    const base = readTokenRadius(tokens, "borderRadius", 6);
+    const lg = readTokenRadius(tokens, "borderRadiusLG", base);
+    if (shape === "square") {
+        return { sm: 0, md: 0, lg: 0, innerSm: 0, innerMd: 0, innerLg: 0 };
+    }
+    if (shape === "pill") {
+        const full = PHI_CONTROL_SHAPE_FULL_RADIUS;
+        return { sm: full, md: full, lg: full, innerSm: full, innerMd: full, innerLg: full };
+    }
+    if (shape === "subtle") {
+        return { sm, md: sm, lg: base, innerSm: xs, innerMd: xs, innerLg: sm };
+    }
+    return { sm, md: base, lg, innerSm: xs, innerMd: sm, innerLg: base };
+}
+export function resolvePhiControlShapeRadius(shape, tokens) {
+    return resolvePhiControlShapeRadii(shape, tokens).md;
+}
+export const PHI_CONTROL_SHAPE_CSS_VARS = {
+    sm: "--phi-control-radius-sm",
+    lg: "--phi-control-radius-lg",
+    innerSm: "--phi-control-radius-inner-sm",
+    innerMd: "--phi-control-radius-inner-md",
+    innerLg: "--phi-control-radius-inner-lg",
+};
+export function buildPhiControlShapeCssVars(shape, tokens) {
+    const radii = resolvePhiControlShapeRadii(shape, tokens);
+    const vars = {};
+    for (const [slot, cssVar] of Object.entries(PHI_CONTROL_SHAPE_CSS_VARS)) {
+        vars[cssVar] = `${radii[slot]}px`;
+    }
+    return vars;
+}
+/**
+ * antd components whose component token styles the Control BODY.
+ *
+ * The four that used to sit here and were removed on 2026-08-20 -- `AutoComplete`, `Cascader`,
+ * `TimePicker`, and `TreeSelect` -- never did anything: AutoComplete and TimePicker ship no stylesheet
+ * of their own and render as `.ant-select` / `.ant-picker`, so the Select and DatePicker entries
+ * already cover their triggers, while Cascader's and TreeSelect's own stylesheets contain nothing but
+ * the dropdown panel. Cascader was worse than inert: its token reads the panel radius, so shaping it
+ * would round the POPUP, which `SITE-CONFIG.md` reserves for the surface scale.
+ */
+const PHI_SHAPED_ANTD_COMPONENTS = [
+    "Button",
+    "ColorPicker",
+    "DatePicker",
+    "Input",
+    "InputNumber",
+    "Mentions",
+    "Segmented",
+    "Select",
+];
+/**
+ * Applies the shape to the Control components, outranking a raw adapter-level radius override.
+ *
+ * `SITE-CONFIG.md` requires this direction: "the resolved semantic Control shape takes precedence over
+ * conflicting raw adapter-level component-radius overrides so there is one effective source of truth."
+ * Overriding a single corner is a different layer and never conflicts -- antd carries only scalar radius
+ * tokens, so a Widget config such as `borderTopLeftRadius` owns that case.
+ *
+ * Only the DEFAULT size is set here. antd reads `borderRadiusSM` and `borderRadiusLG` for the small and
+ * large variants, but those same two tokens also draw the Select dropdown, the DatePicker panel, and the
+ * ColorPicker swatches, so a component override cannot reach one without the other. The small and large
+ * Control bodies are covered by `styles/control-shape.css`, which targets the size classes and leaves
+ * every popup on the surface scale.
+ */
+export function applyPhiControlShapeComponentTokens(components, shape, tokens) {
+    const borderRadius = resolvePhiControlShapeRadius(shape, tokens);
+    const next = { ...components };
+    for (const component of PHI_SHAPED_ANTD_COMPONENTS) {
+        next[component] = { ...(next[component] ?? {}), borderRadius };
+    }
+    return next;
+}

package/theme/phi-css-vars.d.ts

@@ -0,0 +1,10 @@
+import type { CSSProperties } from "react";
+import { type PhiShellRegionTheme } from "../helpers/shell-region-style";
+export type PhiCssVars = CSSProperties & Record<`--${string}`, string>;
+export type PhiShellCssVarsOptions = {
+    rootValue: number;
+    shellTheme?: PhiShellRegionTheme | undefined;
+    themeTokens?: Record<string, unknown>;
+};
+export declare function buildPhiCssVars(rootValue?: number, themeTokens?: Record<string, unknown>): PhiCssVars;
+export declare function buildPhiShellCssVars({ rootValue, shellTheme, themeTokens, }: PhiShellCssVarsOptions): PhiCssVars;

package/theme/phi-css-vars.js

@@ -0,0 +1,61 @@
+import { PHI_LAYOUT } from "./phi-tokens";
+import { resolvePhiShellMetric, resolvePhiShellSiderCollapsedWidth, resolvePhiShellSiderWidth, } from "../helpers/shell-region-style";
+function resolveFinitePositiveNumber(value, fallback) {
+    if (typeof value !== "number" || !Number.isFinite(value) || value <= 0) {
+        return fallback;
+    }
+    return value;
+}
+function pxToRem(value, rootValue) {
+    const effectiveRoot = resolveFinitePositiveNumber(rootValue, 16);
+    const remValue = value / effectiveRoot;
+    return `${Number(remValue.toFixed(6))}rem`;
+}
+function cssSizeToVar(value, rootValue) {
+    if (typeof value === "number" && Number.isFinite(value)) {
+        return pxToRem(value, rootValue);
+    }
+    if (typeof value === "string" && value.trim().length > 0) {
+        return value.trim();
+    }
+    return undefined;
+}
+function resolveTokenNumber(themeTokens, key, fallback) {
+    return resolveFinitePositiveNumber(themeTokens?.[key], fallback);
+}
+export function buildPhiCssVars(rootValue = 16, themeTokens) {
+    return {
+        "--phi-sidebar-width": pxToRem(resolveTokenNumber(themeTokens, "sidebarWidth", PHI_LAYOUT.sidebarWidth), rootValue),
+    };
+}
+function resolveThemeTokenNumber(themeTokens, key, fallback) {
+    return resolveFinitePositiveNumber(themeTokens?.[key], fallback);
+}
+export function buildPhiShellCssVars({ rootValue, shellTheme, themeTokens, }) {
+    const resolvedThemeTokens = themeTokens ?? {};
+    const shellGap = resolveThemeTokenNumber(resolvedThemeTokens, "margin", 13);
+    const shellPadding = resolveThemeTokenNumber(resolvedThemeTokens, "padding", 13);
+    const shellRadius = resolveThemeTokenNumber(resolvedThemeTokens, "borderRadius", 8);
+    const shellHeaderHeight = resolveFinitePositiveNumber(resolvePhiShellMetric(shellTheme, "height", { family: "header", region: "top" }) ??
+        resolvePhiShellMetric(shellTheme, "height", { family: "header", region: "main" }) ??
+        resolveThemeTokenNumber(resolvedThemeTokens, "controlHeight", 34), 34);
+    const shellFooterHeight = resolveFinitePositiveNumber(resolvePhiShellMetric(shellTheme, "height", { family: "footer", region: "main" }) ??
+        resolvePhiShellMetric(shellTheme, "height", { family: "footer", region: "top" }) ??
+        resolveThemeTokenNumber(resolvedThemeTokens, "controlHeight", 34), 34);
+    return {
+        "--phi-shell-gap": pxToRem(shellGap, rootValue),
+        "--phi-shell-padding": pxToRem(shellPadding, rootValue),
+        "--phi-shell-radius": pxToRem(shellRadius, rootValue),
+        "--phi-shell-header-height": pxToRem(shellHeaderHeight, rootValue),
+        "--phi-shell-footer-height": pxToRem(shellFooterHeight, rootValue),
+        "--phi-shell-content-min-height": "100dvh",
+        "--phi-shell-sider-width": cssSizeToVar(resolvePhiShellSiderWidth(shellTheme), rootValue) ?? pxToRem(200, rootValue),
+        "--phi-shell-sider-collapsed-width": cssSizeToVar(resolvePhiShellSiderCollapsedWidth(shellTheme), rootValue) ?? pxToRem(40, rootValue),
+        "--phi-shell-bg-image": "none",
+        "--phi-shell-bg-size": "cover",
+        "--phi-shell-bg-position": "center center",
+        "--phi-shell-bg-repeat": "no-repeat",
+        "--phi-shell-bg-opacity": "1",
+        "--phi-shell-bg-blur": "0px",
+    };
+}

package/theme/phi-font-catalogue-contract.d.ts

@@ -0,0 +1,20 @@
+/**
+ * The part of the font catalogue that any tool may import.
+ *
+ * `phi-font-catalogue.ts` declares the core families through `next/font`, which is evaluated by a Next
+ * build and throws anywhere else. Everything a Module's boundary or a verify script needs in order to
+ * *state* a family -- the entry shape, the namespace rule, the names the core already claims -- lives
+ * here, without a loader in sight, so that `@phis/ui/module` can validate a contribution outside Next.
+ */
+export type PhiFontCatalogueEntry = {
+    /** The name a Theme writes in `fonts.body` and its siblings, and a fonts block names in a slot. */
+    family: string;
+    /** What that name resolves to in a `font-family` declaration. */
+    cssVariable: string;
+    /** The class that puts the variable in scope; belongs on the root element. */
+    className: string;
+};
+/** The families phis-ui declares itself; a Module names them, it does not declare them again. */
+export declare const PHI_CORE_FONT_FAMILIES: readonly string[];
+/** The variable a contributed family must use: its own namespace, never a core one. */
+export declare const PHI_MODULE_FONT_CSS_VARIABLE_PATTERN: RegExp;

package/theme/phi-font-catalogue-contract.js

@@ -0,0 +1,12 @@
+/**
+ * The part of the font catalogue that any tool may import.
+ *
+ * `phi-font-catalogue.ts` declares the core families through `next/font`, which is evaluated by a Next
+ * build and throws anywhere else. Everything a Module's boundary or a verify script needs in order to
+ * *state* a family -- the entry shape, the namespace rule, the names the core already claims -- lives
+ * here, without a loader in sight, so that `@phis/ui/module` can validate a contribution outside Next.
+ */
+/** The families phis-ui declares itself; a Module names them, it does not declare them again. */
+export const PHI_CORE_FONT_FAMILIES = ["Fira Sans", "Fira Mono", "Lora"];
+/** The variable a contributed family must use: its own namespace, never a core one. */
+export const PHI_MODULE_FONT_CSS_VARIABLE_PATTERN = /^var\(--phi-font-[a-z0-9]+(?:-[a-z0-9]+)+\)$/;

package/theme/phi-font-catalogue.d.ts

@@ -0,0 +1,30 @@
+import { type PhiFontCatalogueEntry } from "./phi-font-catalogue-contract";
+export type { PhiFontCatalogueEntry } from "./phi-font-catalogue-contract";
+/** The families phis-ui itself declares: the floor, and what the core fonts block names. */
+export declare const PHI_FONT_CATALOGUE: readonly PhiFontCatalogueEntry[];
+export type PhiFontCatalogue = {
+    entries: readonly PhiFontCatalogueEntry[];
+    /**
+     * The classes that put every catalogue variable in scope.
+     *
+     * All of them, on every page, and that costs nothing: a class name declares where a variable is
+     * readable, not that a file must be fetched. Only a `font-family` that actually resolves to one makes
+     * the browser ask for bytes.
+     */
+    className: string;
+    /** Family name to the variable it resolves to; a name not in here reaches the browser as it is. */
+    familyVariables: ReadonlyMap<string, string>;
+};
+/**
+ * The catalogue a Site renders with: the core families, then what its installed Modules declared.
+ *
+ * Composed once per Site rather than per request, because what goes into it is fixed at build time --
+ * the declarations are `next/font` calls at module scope -- and the only per-request question, which
+ * family a page uses, is answered by the Theme against the map this returns.
+ *
+ * A family declared twice is refused rather than resolved: two declarations of "Inter" would be two
+ * variables, and the map could keep only one of them, so whichever Module lost would render in a face
+ * it never asked for. That includes the core families -- a Module wanting Lora names it, it does not
+ * declare it again.
+ */
+export declare function composePhiFontCatalogue(contributed?: readonly PhiFontCatalogueEntry[]): PhiFontCatalogue;

package/theme/phi-font-catalogue.js

@@ -0,0 +1,75 @@
+import { Fira_Mono, Fira_Sans, Lora } from "next/font/google";
+import { PHI_CORE_FONT_FAMILIES } from "./phi-font-catalogue-contract";
+/**
+ * The self-hosted families a Theme may name, and which of them a page pays for before it paints.
+ *
+ * `next/font` is a build-time loader: the call stands at module scope with literal arguments, and Next
+ * fetches the files once and serves them from this origin. What is not fixed is *which* declared family
+ * a page uses -- that is a CSS variable the Theme sets per request. So this is a catalogue of what a
+ * Site may choose from, not a set of fonts every page wears.
+ *
+ * `preload` is the one part that cannot be decided per request. `next/font` hands back a class name, a
+ * style, and a variable -- never a file URL -- so a `<link rel="preload">` for the family a Theme
+ * happens to pick cannot be written by hand. The decision is therefore taken here, per family, by what
+ * a page needs before it paints: body text always, a code face and a serif only where something asks
+ * for them, and those then arrive with `font-display: swap` rather than holding up the first paint.
+ *
+ * It was all three before, on every page: measured in the Skeleton's build, 236 KB of preloaded Latin
+ * faces, of which 183 KB were a serif and a code face that a Site running on the body font alone never
+ * names. The files are still built and self-hosted either way; what falls away is the browser being
+ * told to fetch them before it knows whether anything needs them.
+ */
+const firaSans = Fira_Sans({
+    variable: "--phi-font-source-body",
+    weight: ["400", "600", "700"],
+    subsets: ["latin"],
+});
+const firaMono = Fira_Mono({
+    variable: "--phi-font-source-mono",
+    weight: ["400", "500", "700"],
+    subsets: ["latin"],
+    preload: false,
+});
+const lora = Lora({
+    variable: "--phi-font-source-serif",
+    weight: ["400", "500", "600", "700"],
+    subsets: ["latin"],
+    preload: false,
+});
+/** The families phis-ui itself declares: the floor, and what the core fonts block names. */
+export const PHI_FONT_CATALOGUE = [
+    { family: "Fira Sans", cssVariable: "var(--phi-font-source-body)", className: firaSans.variable },
+    { family: "Fira Mono", cssVariable: "var(--phi-font-source-mono)", className: firaMono.variable },
+    { family: "Lora", cssVariable: "var(--phi-font-source-serif)", className: lora.variable },
+];
+if (PHI_FONT_CATALOGUE.some((entry, index) => entry.family !== PHI_CORE_FONT_FAMILIES[index]) || PHI_FONT_CATALOGUE.length !== PHI_CORE_FONT_FAMILIES.length) {
+    throw new Error("The core font catalogue and its contract name different families.");
+}
+/**
+ * The catalogue a Site renders with: the core families, then what its installed Modules declared.
+ *
+ * Composed once per Site rather than per request, because what goes into it is fixed at build time --
+ * the declarations are `next/font` calls at module scope -- and the only per-request question, which
+ * family a page uses, is answered by the Theme against the map this returns.
+ *
+ * A family declared twice is refused rather than resolved: two declarations of "Inter" would be two
+ * variables, and the map could keep only one of them, so whichever Module lost would render in a face
+ * it never asked for. That includes the core families -- a Module wanting Lora names it, it does not
+ * declare it again.
+ */
+export function composePhiFontCatalogue(contributed = []) {
+    const entries = [...PHI_FONT_CATALOGUE, ...contributed];
+    const familyVariables = new Map();
+    for (const entry of entries) {
+        const family = entry.family.trim();
+        if (familyVariables.has(family)) {
+            throw new Error(`Font family "${family}" is declared twice in the font catalogue.`);
+        }
+        familyVariables.set(family, entry.cssVariable);
+    }
+    return {
+        entries,
+        className: entries.map((entry) => entry.className).filter(Boolean).join(" "),
+        familyVariables,
+    };
+}

package/theme/phi-font-face.d.ts

@@ -0,0 +1,72 @@
+import { type PhiFontMetrics } from "@phis/contracts/media";
+/**
+ * The two `@font-face` rules a Site-owned typeface needs, and the family stack that uses them.
+ *
+ * A font from the Media library cannot go through `next/font`, which is a build-time loader, so nothing
+ * writes its rules but this. The first rule is the face itself. The second is the one that matters
+ * before it arrives: a local substitute, re-proportioned with `size-adjust` and the three overrides so
+ * the page it paints is the page the real font will paint. Without it the substitute sets at its own
+ * proportions and every line moves when the file lands -- measured on the three families this package
+ * ships, a substitute runs between 3% and 35% off.
+ */
+/**
+ * What a browser is asked to stand in with, and how those faces measure.
+ *
+ * Three fonts that are on essentially every desktop, one per category. The numbers are the published
+ * metrics of those faces -- the same figures `next/font` computes its own overrides against -- and they
+ * are constants here because a server cannot measure a font on somebody else's machine.
+ */
+declare const PHI_LOCAL_FALLBACK_FONTS: {
+    readonly "sans-serif": {
+        readonly name: "Arial";
+        readonly unitsPerEm: 2048;
+        readonly xWidthAvg: 913;
+    };
+    readonly serif: {
+        readonly name: "Times New Roman";
+        readonly unitsPerEm: 2048;
+        readonly xWidthAvg: 832;
+    };
+    readonly monospace: {
+        readonly name: "Courier New";
+        readonly unitsPerEm: 2048;
+        readonly xWidthAvg: 1229;
+    };
+};
+export type PhiFontFaceCategory = keyof typeof PHI_LOCAL_FALLBACK_FONTS;
+export type PhiFontFaceSource = {
+    /** The family the CSS declares and the stack asks for. */
+    family: string;
+    /** Where the file is, already a delivery URL. */
+    url: string;
+    contentType: string;
+    metrics: PhiFontMetrics | null;
+    /** What to stand in with where the file does not classify itself. */
+    fallbackCategory?: PhiFontFaceCategory;
+    /**
+     * The Asset behind `url`, for a font whose unicode cuts are known. With it, the face is declared once
+     * per cut with `unicode-range`, and a page fetches only the cuts it renders; without it, whole.
+     */
+    asset?: {
+        id: number;
+        deliveryRevision?: number | null;
+    };
+};
+/** The name of the re-proportioned substitute; `Lora Fallback` beside `Lora`, as next/font names it. */
+export declare function buildPhiFontFallbackFamily(family: string): string;
+export declare function resolvePhiFontFaceCategory(source: PhiFontFaceSource): PhiFontFaceCategory;
+/**
+ * Both rules for one Site-owned face, or nothing where the file is not one we can name a format for.
+ *
+ * `font-display: swap` rather than `block`: the substitute below is proportioned to stand in, so
+ * showing it immediately costs a repaint and hiding the text would cost the reader the sentence.
+ */
+export declare function buildPhiFontFaceCss(source: PhiFontFaceSource): string | null;
+/**
+ * What a `font-family` declaration should say once both rules exist.
+ *
+ * The adjusted substitute stands between the real face and the generic, so the browser reaches it
+ * before falling all the way through to whatever the platform would have picked unproportioned.
+ */
+export declare function buildPhiFontFamilyStack(source: PhiFontFaceSource): string | null;
+export {};