@phis/ui 0.2.1 → 0.4.0

package/types/form-submit-route.d.ts

@@ -0,0 +1,26 @@
+import type { PhiFormHandlerCredentialPolicy } from "./form-descriptor";
+export type PhiFormSubmitCategory = "auth" | "account" | "forms" | "site";
+export type PhiFormSubmitTransport = "relay" | "api" | "serverAction";
+export type PhiFormSubmitMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+/**
+ * Where a Form's submit goes: the route the gateway resolves from the Form id and its handler Provider.
+ *
+ * Not the Form's submit button -- that is `PhiFormSubmitDescriptor` in `@phis/contracts/forms`, the
+ * label, alignment and control an author declares. The two carried one name, one reachable through
+ * `@phis/ui/forms` and the other through `@phis/ui/types`, so a Module importing from the wrong door
+ * compiled against a type that meant something else. Declared here, in the contract layer, because the
+ * gateway that builds it is `server-only` and a type in `types/` must not lead there.
+ */
+export type PhiFormSubmitRoute = {
+    formId: string;
+    submitHandlerKey: string;
+    category: PhiFormSubmitCategory;
+    transport: PhiFormSubmitTransport;
+    method: PhiFormSubmitMethod;
+    endpointKey: string | null;
+    actionKey: string | null;
+    upstreamPath: string | null;
+    csrfPath: string | null;
+    requiresCsrf: boolean;
+    credentialPolicy: PhiFormHandlerCredentialPolicy;
+};

package/types/form-submit-route.js

@@ -0,0 +1 @@
+export {};

package/types/layout-style.d.ts

@@ -1,7 +1,5 @@
-export declare const PHI_LAYOUT_EFFECT_IDS: readonly ["glass", "haze", "blur", "dim"];
-export type PhiLayoutEffectId = (typeof PHI_LAYOUT_EFFECT_IDS)[number];
 /**
- * The Effects that are a pane rather than a treatment of the surface itself.
+ * The Background filters that are a pane rather than a treatment of the paint itself.
  *
  * `glass` and `haze` are the same thing at two strengths: a sheet that frosts what shows through it.
  * `glass` is the frosted pane, `haze` the barely clouded one -- both a smaller radius and more of the
@@ -19,6 +17,16 @@ export type PhiCustomShadow = {
     value: string;
 };
 export type PhiShadow = PhiShadowId | PhiCustomShadow;
-export declare function isPhiLayoutEffectId(value: unknown): value is PhiLayoutEffectId;
 export declare function isPhiShadowId(value: unknown): value is PhiShadowId;
 export declare function readPhiShadow(value: unknown): PhiShadow | undefined;
+/**
+ * What a Background does to the light that reaches it, beside what it paints.
+ *
+ * `glass` and `haze` are panes: they frost what shows THROUGH the surface, so they act on the backdrop and
+ * on a ground thinned enough to let it through. `blur` softens the Background's own paint -- the picture,
+ * the gradient, the pattern -- and nothing in front of it: the content a surface carries is never filtered.
+ * Darkening is not a filter; a colour Overlay at an opacity does it, and lets the colour be chosen.
+ */
+export declare const PHI_BACKGROUND_FILTERS: readonly ["glass", "haze", "blur"];
+export type PhiBackgroundFilter = (typeof PHI_BACKGROUND_FILTERS)[number];
+export declare function isPhiBackgroundFilter(value: unknown): value is PhiBackgroundFilter;

package/types/layout-style.js

@@ -1,6 +1,6 @@
-export const PHI_LAYOUT_EFFECT_IDS = ["glass", "haze", "blur", "dim"];
+import { isPhiRecord } from "../helpers/is-record";
 /**
- * The Effects that are a pane rather than a treatment of the surface itself.
+ * The Background filters that are a pane rather than a treatment of the paint itself.
  *
  * `glass` and `haze` are the same thing at two strengths: a sheet that frosts what shows through it.
  * `glass` is the frosted pane, `haze` the barely clouded one -- both a smaller radius and more of the
@@ -13,9 +13,6 @@ export function isPhiGlassLayoutEffectId(value) {
     return typeof value === "string" && PHI_GLASS_LAYOUT_EFFECT_IDS.includes(value);
 }
 export const PHI_SHADOW_IDS = ["none", "soft", "strong"];
-export function isPhiLayoutEffectId(value) {
-    return typeof value === "string" && PHI_LAYOUT_EFFECT_IDS.includes(value);
-}
 export function isPhiShadowId(value) {
     return typeof value === "string" && PHI_SHADOW_IDS.includes(value);
 }
@@ -23,7 +20,7 @@ export function readPhiShadow(value) {
     if (isPhiShadowId(value)) {
         return value;
     }
-    if (!value || typeof value !== "object" || Array.isArray(value)) {
+    if (!isPhiRecord(value)) {
         return undefined;
     }
     const candidate = value;
@@ -32,3 +29,15 @@ export function readPhiShadow(value) {
         ? { kind: "custom", value: customValue }
         : undefined;
 }
+/**
+ * What a Background does to the light that reaches it, beside what it paints.
+ *
+ * `glass` and `haze` are panes: they frost what shows THROUGH the surface, so they act on the backdrop and
+ * on a ground thinned enough to let it through. `blur` softens the Background's own paint -- the picture,
+ * the gradient, the pattern -- and nothing in front of it: the content a surface carries is never filtered.
+ * Darkening is not a filter; a colour Overlay at an opacity does it, and lets the colour be chosen.
+ */
+export const PHI_BACKGROUND_FILTERS = ["glass", "haze", "blur"];
+export function isPhiBackgroundFilter(value) {
+    return typeof value === "string" && PHI_BACKGROUND_FILTERS.includes(value);
+}

package/types/media.d.ts

@@ -17,7 +17,6 @@ type PhiMediaImageAssetSourceConfig = {
 export type PhiMediaImageSourceConfig = (PhiMediaImageSourceUrlConfig | PhiMediaImageAssetSourceConfig) & {
     trusted?: boolean;
     alt?: string;
-    blurDataUrl?: string;
     previewMode?: "none" | "native" | "lightbox";
     sizes?: string;
     preload?: boolean;

package/types/record-provider.d.ts

@@ -0,0 +1,23 @@
+import type { PhiRuntimeDataProviderKey } from "./runtime-data-provider";
+import type { PhiBlockRuntime } from "./widget-runtime";
+/** What a record Provider is asked with, besides its parameters: whose Site, in which language. */
+export type PhiRuntimeRecordProviderContext = {
+    apiBaseUrl: string;
+    internalToken: string;
+    siteKey: string;
+    locale: string;
+    /** The render's own runtime, for a Provider that prepares what it read the way the page reads it. */
+    runtime: PhiBlockRuntime;
+};
+/**
+ * One record for the parameters given, or `null` where they name none.
+ *
+ * `null` is an answer -- "there is no such entry" -- and a throw is not: a Provider that cannot reach its
+ * store throws, and the Widget says the record is unavailable rather than that it does not exist.
+ */
+export type PhiRuntimeRecordProviderResolver = (params: Readonly<Record<string, unknown>>, context: PhiRuntimeRecordProviderContext) => Promise<unknown>;
+/** The server half of a `record` descriptor, loaded only when a page binds it. */
+export type PhiRuntimeModuleRecordProviderServerDefinition = {
+    key: PhiRuntimeDataProviderKey;
+    load: () => Promise<PhiRuntimeRecordProviderResolver>;
+};

package/types/record-provider.js

@@ -0,0 +1 @@
+export {};

package/types/references.d.ts

@@ -6,7 +6,7 @@
  * form landed, which is exactly the arrangement the CMS instance id was moved out of for the same
  * reason. What stays here is the one type only the render side has a use for.
  */
-export { PHIS_INTERNAL_ASSET_SCHEME, PHIS_INTERNAL_PAGE_SCHEME, PHI_LINK_TARGET_CONFIG_KEY, createPhiAssetUri, createPhiPageReference, createPhiPageUri, createPhiPresetCmsPageId, isPhiLinkTargetConfigKey, isPhiStorableExternalHref, readPhiInternalReference, readPhiLinkTarget, readPhiPageReference, type PhiInternalReference, type PhiLinkTarget, type PhiPageReference, type PhiPageTarget, type PhiPageTargetInput, } from "@phis/contracts/references";
+export { PHIS_INTERNAL_ASSET_SCHEME, PHIS_INTERNAL_PAGE_SCHEME, PHI_LINK_TARGET_CONFIG_KEY, createPhiAssetUri, createPhiPageReference, createPhiPageUri, createPhiPresetCmsPageId, fillPhiRouteParams, isPhiLinkTargetConfigKey, isPhiStorableExternalHref, readPhiInternalReference, readPhiLinkTarget, readPhiPageReference, type PhiInternalReference, type PhiLinkTarget, type PhiPageReference, type PhiPageTarget, type PhiPageTargetInput, } from "@phis/contracts/references";
 import type { PhiPageReference } from "@phis/contracts/references";
 /**
  * The addresses this render's Page targets answer on, resolved once before anything draws.

package/types/references.js

@@ -6,4 +6,4 @@
  * form landed, which is exactly the arrangement the CMS instance id was moved out of for the same
  * reason. What stays here is the one type only the render side has a use for.
  */
-export { PHIS_INTERNAL_ASSET_SCHEME, PHIS_INTERNAL_PAGE_SCHEME, PHI_LINK_TARGET_CONFIG_KEY, createPhiAssetUri, createPhiPageReference, createPhiPageUri, createPhiPresetCmsPageId, isPhiLinkTargetConfigKey, isPhiStorableExternalHref, readPhiInternalReference, readPhiLinkTarget, readPhiPageReference, } from "@phis/contracts/references";
+export { PHIS_INTERNAL_ASSET_SCHEME, PHIS_INTERNAL_PAGE_SCHEME, PHI_LINK_TARGET_CONFIG_KEY, createPhiAssetUri, createPhiPageReference, createPhiPageUri, createPhiPresetCmsPageId, fillPhiRouteParams, isPhiLinkTargetConfigKey, isPhiStorableExternalHref, readPhiInternalReference, readPhiLinkTarget, readPhiPageReference, } from "@phis/contracts/references";

package/types/renderable-block-geometry.d.ts

@@ -69,10 +69,6 @@ export type PhiRenderableBlockGeometryInput = {
     maxSize?: PhiRenderableBlockResponsiveSize | null;
     collapsedSizeHint?: PhiRenderableBlockSize | null;
 };
-/** The three rooms a block may answer differently, smaller to larger. */
-export declare const PHI_BLOCK_PROFILES: readonly ["compact", "medium", "wide"];
-export type PhiBlockProfile = (typeof PHI_BLOCK_PROFILES)[number];
-export declare const PHI_EMPTY_BLOCK_GEOMETRY: PhiResolvedBlockGeometry;
 /**
  * One stored length as a stylesheet receives it.
  *

package/types/renderable-block-geometry.js

@@ -1,8 +1,8 @@
 import { readPhiCssLengthPart } from "./length";
 /** The three rooms a block may answer differently, smaller to larger. */
-export const PHI_BLOCK_PROFILES = ["compact", "medium", "wide"];
+const PHI_BLOCK_PROFILES = ["compact", "medium", "wide"];
 const EMPTY_AXIS = { size: null, min: null, max: null };
-export const PHI_EMPTY_BLOCK_GEOMETRY = {
+const PHI_EMPTY_BLOCK_GEOMETRY = {
     inline: EMPTY_AXIS,
     block: EMPTY_AXIS,
     explicitInline: false,

package/types/renderable-block.d.ts

@@ -1,9 +1,8 @@
 import type { PhiMotionEasing } from "../helpers/motion";
-import type { CSSProperties } from "react";
 import type { PhiCmsInstanceId } from "./cms-instance-id";
 import type { PhiViewerAccessPolicy, PhiViewportFlags } from "./access";
-import type { PhiShadow, PhiLayoutEffectId } from "./layout-style";
 import type { PhiResponsiveValue } from "./responsive";
+import type { PhiSurface } from "./surface";
 export type PhiRenderableBlockRenderMode = "live" | "preview" | "editor";
 export type PhiRenderableBlockVisibility = "hidden" | "collapsed" | "visible";
 /**
@@ -116,10 +115,14 @@ export type PhiRenderableBlockBase = {
     anchor?: PhiRenderableBlockAnchor;
     zIndex?: number;
     opacity?: number;
-    background?: CSSProperties["background"] | Record<string, unknown> | null;
-    border?: CSSProperties["border"] | Record<string, unknown> | null;
-    effect?: PhiLayoutEffectId;
-    shadow?: PhiShadow;
+    /**
+     * What the block's box looks like: ground, edge, depth, and the mode its content takes.
+     *
+     * Who draws it depends on the block: a Layout and a Region draw their own, a Widget's is drawn by its
+     * slot frame when its plugin says `surface: "frame"`, by the Widget itself when it says `"own"`, and by
+     * nobody otherwise.
+     */
+    surface?: PhiSurface;
     className?: string;
     size?: PhiRenderableBlockResponsiveSize;
     minSize?: PhiRenderableBlockResponsiveSize;

package/types/runtime-data-provider.d.ts

@@ -1,6 +1,11 @@
 export { isPhiNamespacedRuntimeKey, isPhiRuntimeDataProviderKey, type PhiRuntimeDataProviderKey, } from "@phis/contracts/controls";
 import { type PhiRuntimeDataProviderKey } from "@phis/contracts/controls";
-export type PhiRuntimeDataProviderKind = "options" | "table" | "tree" | "collection";
+/**
+ * What a Provider serves. Every kind but `record` is read in the browser, through the Client half a
+ * Module registers (`loadLive`); a `record` is one thing read on the server while the page is drawn
+ * (`types/record-provider.ts`), so it reaches the HTML and the Page's own status.
+ */
+export type PhiRuntimeDataProviderKind = "options" | "table" | "tree" | "collection" | "timeline" | "record";
 export type PhiRuntimeDataProviderExecutionMode = "static" | "live";
 export type PhiRuntimeDataProviderAuthoringMode = "none" | "read" | "edit";
 export type PhiRuntimeDataProviderBinding = {
@@ -17,5 +22,10 @@ export type PhiRuntimeDataProviderBinding = {
 export type PhiProviderResourceSource = PhiRuntimeDataProviderBinding & {
     resourceKey: string;
 };
+/**
+ * Reads a stored binding of a Provider that serves one thing and needs no resource -- a Timeline
+ * Provider. Anything without a namespaced Provider key is no binding.
+ */
+export declare function readPhiRuntimeDataProviderBinding(value: unknown): PhiRuntimeDataProviderBinding | null;
 /** Reads a stored source; anything without a namespaced Provider key and a resource is no source. */
 export declare function readPhiProviderResourceSource(value: unknown): PhiProviderResourceSource | null;

package/types/runtime-data-provider.js

@@ -3,10 +3,33 @@
  * is read from `@phis/contracts/controls` with the check that goes with it.
  */
 export { isPhiNamespacedRuntimeKey, isPhiRuntimeDataProviderKey, } from "@phis/contracts/controls";
+import { isPhiRecord } from "../helpers/is-record";
 import { isPhiRuntimeDataProviderKey as isProviderKey } from "@phis/contracts/controls";
+/**
+ * Reads a stored binding of a Provider that serves one thing and needs no resource -- a Timeline
+ * Provider. Anything without a namespaced Provider key is no binding.
+ */
+export function readPhiRuntimeDataProviderBinding(value) {
+    if (!isPhiRecord(value)) {
+        return null;
+    }
+    const record = value;
+    if (!isProviderKey(record.providerKey)) {
+        return null;
+    }
+    const scopeKey = typeof record.scopeKey === "string" && record.scopeKey.trim() ? record.scopeKey.trim() : undefined;
+    const params = isPhiRecord(record.params)
+        ? record.params
+        : undefined;
+    return {
+        providerKey: record.providerKey,
+        ...(scopeKey ? { scopeKey } : {}),
+        ...(params ? { params } : {}),
+    };
+}
 /** Reads a stored source; anything without a namespaced Provider key and a resource is no source. */
 export function readPhiProviderResourceSource(value) {
-    if (!value || typeof value !== "object" || Array.isArray(value)) {
+    if (!isPhiRecord(value)) {
         return null;
     }
     const record = value;
@@ -15,7 +38,7 @@ export function readPhiProviderResourceSource(value) {
         return null;
     }
     const scopeKey = typeof record.scopeKey === "string" && record.scopeKey.trim() ? record.scopeKey.trim() : undefined;
-    const params = record.params && typeof record.params === "object" && !Array.isArray(record.params)
+    const params = isPhiRecord(record.params)
         ? record.params
         : undefined;
     return {

package/types/signals.d.ts

@@ -20,7 +20,6 @@ export declare const PHI_SIGNAL_VALUE_SCHEMAS: {
     readonly backgroundConfig: `${string}/signals/${string}`;
     readonly borderConfig: `${string}/signals/${string}`;
     readonly brandTheme: `${string}/signals/${string}`;
-    readonly builderChrome: `${string}/signals/${string}`;
     readonly builderInspector: `${string}/signals/${string}`;
     readonly builderLayout: `${string}/signals/${string}`;
     readonly builderNavigation: `${string}/signals/${string}`;
@@ -60,8 +59,11 @@ export declare const PHI_SIGNAL_VALUE_SCHEMAS: {
     readonly tableState: `${string}/signals/${string}`;
     readonly tableMutation: `${string}/signals/${string}`;
     readonly threadSelection: `${string}/signals/${string}`;
+    readonly tourAvailability: `${string}/signals/${string}`;
+    readonly tourProgress: `${string}/signals/${string}`;
     readonly treeAction: `${string}/signals/${string}`;
     readonly treeBindingParams: `${string}/signals/${string}`;
+    readonly timelineBindingParams: `${string}/signals/${string}`;
     readonly treeState: `${string}/signals/${string}`;
     readonly treeMutation: `${string}/signals/${string}`;
     readonly temporalSelection: `${string}/signals/${string}`;

package/types/signals.js

@@ -37,7 +37,6 @@ export const PHI_SIGNAL_VALUE_SCHEMAS = {
     backgroundConfig: createPhiSharedSignalValueSchema("background-config"),
     borderConfig: createPhiSharedSignalValueSchema("border-config"),
     brandTheme: createPhiSharedSignalValueSchema("brand-theme"),
-    builderChrome: createPhiSharedSignalValueSchema("builder-chrome"),
     builderInspector: createPhiSharedSignalValueSchema("builder-inspector"),
     builderLayout: createPhiSharedSignalValueSchema("builder-layout"),
     builderNavigation: createPhiSharedSignalValueSchema("builder-navigation"),
@@ -77,8 +76,11 @@ export const PHI_SIGNAL_VALUE_SCHEMAS = {
     tableState: createPhiSharedSignalValueSchema("table-state"),
     tableMutation: createPhiSharedSignalValueSchema("table-mutation"),
     threadSelection: createPhiSharedSignalValueSchema("thread-selection"),
+    tourAvailability: createPhiSharedSignalValueSchema("tour-availability"),
+    tourProgress: createPhiSharedSignalValueSchema("tour-progress"),
     treeAction: createPhiSharedSignalValueSchema("tree-action"),
     treeBindingParams: createPhiSharedSignalValueSchema("tree-binding-params"),
+    timelineBindingParams: createPhiSharedSignalValueSchema("timeline-binding-params"),
     treeState: createPhiSharedSignalValueSchema("tree-state"),
     treeMutation: createPhiSharedSignalValueSchema("tree-mutation"),
     temporalSelection: createPhiSharedSignalValueSchema("temporal-selection"),

package/types/site-config.d.ts

@@ -1,7 +1,9 @@
 import type { PhiShellTheme } from "../components/shell/shell-types";
-import type { PhiSiteFontSlots, PhiSiteRemSettings, PhiSiteThemeBrand, PhiSiteThemeContact, PhiSiteThemeRoot } from "./site-theme";
+import type { PhiSiteFontSlots, PhiSiteThemeBrand, PhiSiteThemeContact, PhiSiteThemeRoot } from "./site-theme";
+import type { PhiLocaleCapability } from "../helpers/site-locale-config";
 import type { PhiThemePalette } from "../theme/phi-theme-presets";
 import type { PhiThemeBlockSelection } from "../theme/phi-theme-composition";
+import type { PhiThemeDerivation } from "../theme/phi-theme-selection";
 import type { PhiControlShapeCorners } from "../theme/phi-control-shape";
 import type { PhiThemeButtons } from "../theme/phi-button-shadow";
 import type { PhiThemeTypography } from "../theme/phi-theme-typography";
@@ -12,6 +14,8 @@ export type PhiSiteTheme = {
      * a Theme had three parts, where `preset` alone named the palette and still does.
      */
     blocks?: PhiThemeBlockSelection | null;
+    /** The Set this Theme was derived from; a record for the Theme workspace, never read to render. */
+    derivedFrom?: PhiThemeDerivation | null;
     preset?: string | null;
     presetVersion?: number | null;
     shape?: {
@@ -33,7 +37,6 @@ export type PhiSiteTheme = {
     } | null;
     shell?: PhiShellTheme;
     root?: PhiSiteThemeRoot | null;
-    rem?: PhiSiteRemSettings | null;
     /**
      * The colour the Site owns: a palette in the shape a Module ships one (theme/phi-theme-presets.ts),
      * laid over the palette block the Site follows. Seeds shared by both modes under `seed`; the base
@@ -64,8 +67,17 @@ export type PhiSiteConfig = {
     name: string;
     hostname: string;
     defaultLocale: string;
+    /**
+     * The language the Site's own words are written in: what a Builder types, what an entry is written in
+     * where nobody says otherwise, and what every translation starts from. The operator's setting, not the
+     * language a visitor is shown first, which is `defaultLocale` and may differ.
+     */
+    sourceLocale: string;
     availableLocales: PhiSiteLocaleOption[];
-    store?: {
+    /** What each served locale means, so a request naming one is resolved without asking Core. */
+    localeCapabilities: PhiLocaleCapability[];
+    /** Whether the Site runs a store; the server computes it for every Site, so it is never absent. */
+    store: {
         enabled: boolean;
     };
     theme: PhiSiteTheme;

package/types/site-request-context.d.ts

@@ -1,165 +1,8 @@
 import type { PhiCapabilitySnapshot } from "./server-capabilities";
-import type { PhiSiteFontSlots, PhiSiteRemSettings } from "./site-theme";
-import type { PhiBlockRuntime, PhiWidgetThemeMode } from "./widget-runtime";
+import type { PhiBlockRuntime, PhiResolvedBlockRuntimeSite } from "./widget-runtime";
 export type PhiSiteRequestContext = {
     serverCapabilities: PhiCapabilitySnapshot;
-    site: {
-        id: number;
-        key: string;
-        publicUrl?: string;
-        name: string;
-        hostname: string;
-        availableLocales: Array<{
-            code: string;
-            label: string;
-        }>;
-        defaultLocale: string;
-        themeRevision: {
-            publishedRevisionId: number | null;
-            workingDraftRevisionId: number | null;
-        };
-        theme: {
-            mode: PhiWidgetThemeMode;
-            fonts?: PhiSiteFontSlots | null;
-            rem?: PhiSiteRemSettings | null;
-            brand?: {
-                slogan?: {
-                    label?: string | null;
-                    icon?: string | null;
-                } | null;
-                location?: {
-                    label?: string | null;
-                    icon?: string | null;
-                } | null;
-                wordmark?: {
-                    parts?: Array<{
-                        text: string;
-                        color?: string | null;
-                        fontWeight?: number | string | null;
-                    }> | null;
-                } | null;
-            };
-            contact?: {
-                label?: string | null;
-                href?: string | null;
-                icon?: string | null;
-            };
-            shell?: {
-                light?: {
-                    background?: string | null;
-                    color?: string | null;
-                } | null;
-                dark?: {
-                    background?: string | null;
-                    color?: string | null;
-                } | null;
-                header?: {
-                    light?: {
-                        background?: string | null;
-                        color?: string | null;
-                    } | null;
-                    dark?: {
-                        background?: string | null;
-                        color?: string | null;
-                    } | null;
-                    top?: {
-                        light?: {
-                            background?: string | null;
-                            color?: string | null;
-                        } | null;
-                        dark?: {
-                            background?: string | null;
-                            color?: string | null;
-                        } | null;
-                    } | null;
-                    main?: {
-                        light?: {
-                            background?: string | null;
-                            color?: string | null;
-                        } | null;
-                        dark?: {
-                            background?: string | null;
-                            color?: string | null;
-                        } | null;
-                    } | null;
-                    bottom?: {
-                        light?: {
-                            background?: string | null;
-                            color?: string | null;
-                        } | null;
-                        dark?: {
-                            background?: string | null;
-                            color?: string | null;
-                        } | null;
-                    } | null;
-                } | null;
-                sider?: {
-                    light?: {
-                        background?: string | null;
-                        color?: string | null;
-                    } | null;
-                    dark?: {
-                        background?: string | null;
-                        color?: string | null;
-                    } | null;
-                    left?: {
-                        light?: {
-                            background?: string | null;
-                            color?: string | null;
-                        } | null;
-                        dark?: {
-                            background?: string | null;
-                            color?: string | null;
-                        } | null;
-                        sticky?: boolean | null;
-                        width?: number | null;
-                    } | null;
-                    right?: {
-                        light?: {
-                            background?: string | null;
-                            color?: string | null;
-                        } | null;
-                        dark?: {
-                            background?: string | null;
-                            color?: string | null;
-                        } | null;
-                        sticky?: boolean | null;
-                        width?: number | null;
-                    } | null;
-                } | null;
-                footer?: {
-                    light?: {
-                        background?: string | null;
-                        color?: string | null;
-                    } | null;
-                    dark?: {
-                        background?: string | null;
-                        color?: string | null;
-                    } | null;
-                    main?: {
-                        light?: {
-                            background?: string | null;
-                            color?: string | null;
-                        } | null;
-                        dark?: {
-                            background?: string | null;
-                            color?: string | null;
-                        } | null;
-                    } | null;
-                    bottom?: {
-                        light?: {
-                            background?: string | null;
-                            color?: string | null;
-                        } | null;
-                        dark?: {
-                            background?: string | null;
-                            color?: string | null;
-                        } | null;
-                    } | null;
-                } | null;
-            };
-        };
-    };
+    site: PhiResolvedBlockRuntimeSite;
     locale: {
         current: string;
     };

package/types/site-theme.d.ts

@@ -1,8 +1,5 @@
 import type { PhiShadow } from "./layout-style";
 import type { PhiCmsBackgroundWidgetConfig } from "../components/widgets/config/background";
-export type PhiSiteRemSettings = {
-    rootValue?: number | null;
-};
 /**
  * The Theme Root Background (SHELL.md "Root Background and Shell Backdrop Layers"): painted once at
  * the document root, independently per mode, using the canonical structured Phi Background contract.
@@ -143,7 +140,7 @@ export type PhiSiteThemeContact = {
     icon?: string | null;
 };
 export type PhiWidgetFontFamilyKey = "inherit" | "system" | "body" | "mono" | "serif" | "accent" | "display";
-export type PhiWidgetFontSizeKey = "inherit" | "xs" | "sm" | "base" | "lg" | "xl";
+export type PhiWidgetFontSizeKey = "inherit" | "xs" | "sm" | "base" | "lg" | "xl" | "xxl";
 export type PhiSiteFontSlots = {
     body?: string | null;
     mono?: string | null;

package/types/surface.d.ts

@@ -0,0 +1,59 @@
+import { type PhiCmsBackgroundWidgetConfig } from "../components/widgets/config/background";
+import { type PhiCmsBorderSource } from "./cms-border-source";
+import type { PhiCmsBorderWidgetConfig } from "./cms-config";
+import { type PhiShadow } from "./layout-style";
+/**
+ * The mode a Surface's content is drawn in, against the mode the page wears.
+ *
+ * `inherit` follows the page. `light` and `dark` hold one mode whatever the page wears -- a dark picture
+ * behind a card keeps the card's text light on a light page. `inverse` is always the other mode, so a
+ * Surface contrasts with the page in both without the author stating either.
+ */
+export declare const PHI_SURFACE_TONES: readonly ["inherit", "light", "dark", "inverse"];
+export type PhiSurfaceTone = (typeof PHI_SURFACE_TONES)[number];
+/**
+ * What a box looks like as a thing standing on the page: its ground, its edge, its depth, and the mode
+ * its content is drawn in.
+ *
+ * One shape for every box that has one -- a Region, an Overlay, a Layout, a Widget. Padding is not part
+ * of it, because how far content stands from the edge is geometry, not appearance; nor are a block's
+ * `effects`, which say how it arrives rather than what it is.
+ *
+ * - `background` carries its own Filter: a glass pane or a softened paint is something the ground does.
+ * - `borderSource` says where the line comes from. Only `custom` reads `border`, corners included; under
+ *   `theme` and `none` the corner is the Site's surface step, so a shape change is seen at once.
+ * - `shadow` is depth.
+ * - `tone` is the mode the content takes, for a ground the page's own text would not read on.
+ *
+ * Absent means nothing: a block without a Surface paints nothing and states no edge.
+ */
+export type PhiSurface = {
+    background?: PhiCmsBackgroundWidgetConfig | null;
+    borderSource?: PhiCmsBorderSource;
+    border?: PhiCmsBorderWidgetConfig | null;
+    shadow?: PhiShadow | null;
+    tone?: PhiSurfaceTone;
+};
+/**
+ * Who draws a block's Surface, as a Widget declares it.
+ *
+ * `frame` is the ordinary case: the slot frame around the Widget paints it, and the Widget never knows.
+ * `own` is a Widget whose look IS a surface -- a card with a picture clipped to its corners -- so the frame
+ * leaves it alone and hands the resolved Surface in. `none` is a Widget a Surface makes no sense on; it
+ * is neither offered nor drawn.
+ */
+export declare const PHI_SURFACE_POLICIES: readonly ["frame", "own", "none"];
+export type PhiSurfacePolicy = (typeof PHI_SURFACE_POLICIES)[number];
+/**
+ * A stored Surface, read once.
+ *
+ * Each part is read by the reader that owns it, so a Surface holds exactly what a Background, a border or
+ * a shadow would hold on its own. A Surface that states nothing reads as `null`, and the box paints
+ * nothing.
+ */
+export declare function readPhiSurface(value: unknown): PhiSurface | null;
+/**
+ * The class a box carries for its tone, or nothing for `inherit`. Fixed per tone, so the server writes it
+ * without knowing the mode; the tone scope inside writes the other mode's variables under it.
+ */
+export declare function resolvePhiSurfaceToneClassName(tone: PhiSurfaceTone | null | undefined): string | undefined;