@phis/ui 0.2.0 → 0.3.0

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

@@ -1,16 +1,20 @@
 import { PHI_CMS_DEFAULT_SLOT_INDEX, PHI_CMS_SEQUENTIAL_LAYOUT_SLOTS, PHI_CMS_THREE_COLUMN_LAYOUT_SLOT_INDEX, } from "../../../../constants/cms-layout-types";
-import { PhiCmsRegionType, PhiCmsStatus } from "../../../../constants/phi-cms";
+import { PhiCmsFlags, PhiCmsRegionType, PhiCmsStatus } from "../../../../constants/phi-cms";
 import { createPhiCmsPresetNodes } from "../../../../helpers/cms-preset-nodes";
 import { resolvePhiShellHeaderHeight } from "../../../../helpers/shell-region-style";
 import { readPhiServerApiCredentials } from "../../../../helpers/phis-server-credentials";
 import { PHI_SIGNAL_VALUE_SCHEMAS, createPhiSignalAddress, } from "../../../../types";
-import { PHI_COLOR, PHI_SPACE } from "../../../../theme/antd-css-var-contract";
+import { PHI_SPACE } from "../../../../theme/antd-css-var-contract";
 import { getPhiBuilderChromeWidgetLabels } from "../../../../components/widgets/label-sets/builder-chrome";
 import { getPhiBuilderRevisionsWidgetLabels } from "../../../../components/widgets/label-sets/revisions";
-import { createPhiRevisionsControllerAddress } from "../controller/address";
+import { createPhiRevisionsControllerAddress, PHI_REVISIONS_CONTROLLER_INSTANCE_KEY, PHI_REVISIONS_CONTROLLER_TYPE, } from "../controller/address";
 import { PHI_REVISIONS_FORM_IDS } from "../forms";
 import { PHI_REVISIONS_RUNTIME_DATA_PROVIDER_KEYS } from "../ids";
 import { PHI_REVISIONS_DELETE_AREA_LAYOUT_IDS, PHI_REVISIONS_DELETE_AREA_OVERLAY_IDS, PHI_REVISIONS_DELETE_AREA_WIDGET_IDS, PHI_REVISIONS_PAGE_LAYOUT_IDS, PHI_REVISIONS_PAGE_WIDGET_IDS, PHI_REVISIONS_TABLE_WIDGET_ID, } from "../page-ids";
+import { PHI_DIALOG_BODY_CONFIG, PHI_DIALOG_COMMANDS_CONFIG } from "../../../../helpers/cms-dialog";
+import { PHI_BUILDER_REVISIONS_KIND_SEARCH_PARAM } from "../../../../helpers/cms-scope-search-params";
+/** Where the history's kind stands in the address, for a `page` condition. */
+const KIND_QUERY_PATH = `query.${PHI_BUILDER_REVISIONS_KIND_SEARCH_PARAM}`;
 const PHI_REVISIONS_PAGE_REGION_IDS = {
     regionHeaderBottom: -511,
     regionContent: -513,
@@ -34,12 +38,51 @@ export async function buildPhiDefaultBuilderRevisionsPageTree({ page, runtime, }
         getPhiBuilderChromeWidgetLabels(credentials),
         getPhiBuilderRevisionsWidgetLabels(credentials),
     ]);
+    const deleteAreaOverlay = createPhiSignalAddress("cms", PHI_REVISIONS_DELETE_AREA_OVERLAY_IDS.overlayDeleteArea);
     return {
         page: nodes.page(),
         pageMeta: {
             title: { msgId: 0, source: "Revisions", value: chromeLabels.pageTitles.revisions },
             description: null,
         },
+        /*
+         * Whom the Revisions Controller answers into on this Page: the history Table it hands the scope,
+         * and the delete-Area dialog with the warning in its Body. The Area runs the Controller for every
+         * Builder Page; while this one is shown it is told (`collectPhiRuntimeControllerConfigOverlays`).
+         */
+        controllerSettings: [{
+                type: PHI_REVISIONS_CONTROLLER_TYPE,
+                instanceKey: PHI_REVISIONS_CONTROLLER_INSTANCE_KEY,
+                mountScope: "page",
+                config: {
+                    signalRoutes: {
+                        emits: [
+                            {
+                                routeKey: "builder-revisions-controller-binding",
+                                capabilityId: "bindingParamsChange",
+                                scope: "area",
+                                channel: "bindingParams",
+                                action: "change",
+                                valueType: "json",
+                                valueSchema: PHI_SIGNAL_VALUE_SCHEMAS.tableBindingParams,
+                                receiver: createPhiSignalAddress("cms", PHI_REVISIONS_TABLE_WIDGET_ID),
+                            },
+                            {
+                                routeKey: "builder-revisions-controller-delete-area-warning",
+                                capabilityId: "deleteAreaWarning",
+                                scope: "area",
+                                channel: "text",
+                                action: "change",
+                                valueType: "string",
+                                receiver: createPhiSignalAddress("cms", PHI_REVISIONS_DELETE_AREA_WIDGET_IDS.deleteAreaWarning),
+                            },
+                            { routeKey: "builder-revisions-controller-delete-area-open", capabilityId: "deleteAreaOpen", scope: "area", channel: "dialog", action: "activate", valueType: "none", receiver: deleteAreaOverlay },
+                            { routeKey: "builder-revisions-controller-delete-area-close", capabilityId: "deleteAreaClose", scope: "area", channel: "dialog", action: "close", valueType: "none", receiver: deleteAreaOverlay },
+                            { routeKey: "builder-revisions-controller-history-reload", capabilityId: "historyReload", scope: "page", channel: "reload", action: "activate", valueType: "none", receiver: createPhiSignalAddress("cms", PHI_REVISIONS_TABLE_WIDGET_ID) },
+                        ],
+                    },
+                },
+            }],
         overlays: [
             nodes.overlay({
                 id: PHI_REVISIONS_DELETE_AREA_OVERLAY_IDS.overlayDeleteArea,
@@ -91,7 +134,7 @@ export async function buildPhiDefaultBuilderRevisionsPageTree({ page, runtime, }
                 rootLayoutNodeId: PHI_REVISIONS_PAGE_LAYOUT_IDS.layoutHeaderBottom,
                 sortOrder: 5,
                 config: {
-                    sticky: true,
+                    flags: PhiCmsFlags.Sticky,
                     size: { height: `${resolvePhiShellHeaderHeight(runtime.site.theme?.shell, "bottom")}px` },
                     offsetTop: resolvePhiShellHeaderHeight(runtime.site.theme?.shell, "main"),
                 },
@@ -121,7 +164,6 @@ export async function buildPhiDefaultBuilderRevisionsPageTree({ page, runtime, }
                 config: {
                     balancedSides: true,
                     contentAlign: "center",
-                    style: { height: "100%" },
                 },
             }),
             // No ground of its own: the Theme's Root Background is what the table stands on.
@@ -140,12 +182,9 @@ export async function buildPhiDefaultBuilderRevisionsPageTree({ page, runtime, }
                         horizontal: "center",
                         vertical: "top",
                     },
-                    gap: PHI_SPACE.base,
+                    gap: PHI_SPACE.sm,
                     margin: 0,
                     padding: PHI_SPACE.base,
-                    background: "transparent",
-                    border: "none",
-                    borderRadius: 0,
                 },
             }),
             nodes.layout({
@@ -157,10 +196,7 @@ export async function buildPhiDefaultBuilderRevisionsPageTree({ page, runtime, }
                 sortOrder: 0,
                 label: "Builder delete area body",
                 config: {
-                    gap: PHI_SPACE.base,
-                    padding: PHI_SPACE.base,
-                    background: PHI_COLOR.bgLayout,
-                    border: "none",
+                    ...PHI_DIALOG_BODY_CONFIG,
                 },
             }),
             nodes.layout({
@@ -191,6 +227,7 @@ export async function buildPhiDefaultBuilderRevisionsPageTree({ page, runtime, }
                 label: "dev revisions area shell delete",
                 config: {
                     key: "revisions-area-shell-delete",
+                    controlSize: "small",
                     compact: true,
                     showLabels: true,
                     buttons: [
@@ -233,7 +270,12 @@ export async function buildPhiDefaultBuilderRevisionsPageTree({ page, runtime, }
                 slotIndex: PHI_CMS_DEFAULT_SLOT_INDEX,
                 sortOrder: 0,
                 label: "Builder delete area warning",
-                config: { text: "", tone: "danger" },
+                /*
+                 * Never empty: a text Widget with no text of its own counts as content nobody published and is
+                 * left out of the live render (`isPhiCmsWidgetContentUnpublished`), and then there is nothing
+                 * for the Controller's sentence naming the Area to arrive at.
+                 */
+                config: { text: revisionsLabels.deleteArea.warning, tone: "danger" },
             }),
             nodes.widget({
                 typeKey: "simple-text",
@@ -275,6 +317,23 @@ export async function buildPhiDefaultBuilderRevisionsPageTree({ page, runtime, }
                                 receiver: createPhiRevisionsControllerAddress(),
                             },
                         ],
+                        /*
+                         * The footer's confirm button sends `submit` here. A route on the sender alone delivers
+                         * nothing: the Form has to say it takes the signal, or the button presses into silence.
+                         * In `page` scope, because that is where a Widget of this Page registers, and the bus
+                         * hands a signal over in its receiver's scope -- a listen route in `area` filtered it out.
+                         */
+                        listens: [
+                            {
+                                routeKey: "builder-delete-area-submit-form",
+                                capabilityId: "submit",
+                                scope: "page",
+                                channel: "submit",
+                                action: "activate",
+                                valueType: "none",
+                                receiver: createPhiSignalAddress("cms", PHI_REVISIONS_DELETE_AREA_WIDGET_IDS.deleteAreaForm),
+                            },
+                        ],
                     },
                 },
             }),
@@ -287,13 +346,13 @@ export async function buildPhiDefaultBuilderRevisionsPageTree({ page, runtime, }
                 label: "Builder delete area commands",
                 config: {
                     key: "delete-area-commands",
-                    compact: true,
-                    showLabels: true,
+                    ...PHI_DIALOG_COMMANDS_CONFIG,
                     buttons: [
                         {
                             key: "cancel",
                             emits: [{ capabilityId: "close", value: null }],
                             label: revisionsLabels.deleteArea.cancel,
+                            icon: "cancel",
                         },
                         {
                             key: "confirm",
@@ -316,7 +375,7 @@ export async function buildPhiDefaultBuilderRevisionsPageTree({ page, runtime, }
                             {
                                 routeKey: "builder-delete-area-submit",
                                 capabilityId: "submit",
-                                scope: "area",
+                                scope: "page",
                                 channel: "submit",
                                 action: "activate",
                                 valueType: "none",
@@ -336,7 +395,7 @@ export async function buildPhiDefaultBuilderRevisionsPageTree({ page, runtime, }
                     source: {
                         providerKey: PHI_REVISIONS_RUNTIME_DATA_PROVIDER_KEYS.table,
                         resourceKey: "history",
-                        params: { labels: revisionsLabels },
+                        params: { labels: revisionsLabels, locale: runtime.locale.current },
                     },
                     presentation: {
                         borders: true,
@@ -412,7 +471,45 @@ export async function buildPhiDefaultBuilderRevisionsPageTree({ page, runtime, }
                             reset: false,
                             reload: true,
                         },
-                        actions: { row: [
+                        actions: {
+                            /*
+                             * Back to the Module's preset, for a Module's Page: the Site's override goes with every
+                             * revision listed here, so the act sits beside them (phis-server CONTENT.md, Reset). Away
+                             * from a Page it is greyed out with the reason beside it; a Page of the Site's own has no
+                             * preset either, and that one the Provider refuses with the same sentence.
+                             */
+                            toolbar: [
+                                {
+                                    key: "resetPage",
+                                    label: revisionsLabels.actions.resetPage,
+                                    /*
+                                     * Greyed out unless a Page's history is shown. The kind is read from the address,
+                                     * which the Controller keeps in step with the Table's own selector; asking the
+                                     * Controller instead would mount it at Page scope, which it refuses
+                                     * (design/STATE_MACHINES.md). Every kind but `page` is listed, because a condition
+                                     * has no "not equals"; an absent kind is the Area.
+                                     */
+                                    disabledWhen: {
+                                        match: "any",
+                                        conditions: [null, "area", "navigation", "theme"].map((kind) => ({
+                                            source: "page",
+                                            valuePath: KIND_QUERY_PATH,
+                                            ...(kind ? { operator: "equals", value: kind } : { operator: "falsy" }),
+                                            reason: revisionsLabels.actions.resetPageUnavailable,
+                                        })),
+                                    },
+                                    icon: "antd:undo",
+                                    display: "icon",
+                                    mode: "danger",
+                                    execution: "provider",
+                                    confirm: {
+                                        title: revisionsLabels.confirm.resetPageTitle,
+                                        description: revisionsLabels.confirm.resetPageDescription,
+                                        okText: revisionsLabels.actions.resetPage,
+                                    },
+                                },
+                            ],
+                            row: [
                                 {
                                     key: "review",
                                     label: revisionsLabels.actions.review,
@@ -452,7 +549,7 @@ export async function buildPhiDefaultBuilderRevisionsPageTree({ page, runtime, }
                                     key: "deleteSelected",
                                     label: revisionsLabels.actions.deleteSelected,
                                     icon: "antd:delete",
-                                    display: "icon-label",
+                                    display: "icon",
                                     mode: "danger",
                                     execution: "provider",
                                     confirm: {
@@ -461,7 +558,8 @@ export async function buildPhiDefaultBuilderRevisionsPageTree({ page, runtime, }
                                         okText: revisionsLabels.actions.deleteSelected,
                                     },
                                 },
-                            ] },
+                            ]
+                        },
                     },
                     signalRoutes: {
                         emits: [
@@ -487,10 +585,19 @@ export async function buildPhiDefaultBuilderRevisionsPageTree({ page, runtime, }
                             },
                         ],
                         listens: [
+                            {
+                                routeKey: "builder-revisions-table-reload",
+                                capabilityId: "reload",
+                                scope: "page",
+                                channel: "reload",
+                                action: "activate",
+                                valueType: "none",
+                                receiver: createPhiSignalAddress("cms", PHI_REVISIONS_TABLE_WIDGET_ID),
+                            },
                             {
                                 routeKey: "builder-revisions-table-binding-input",
                                 capabilityId: "bindingParamsChange",
-                                scope: "area",
+                                scope: "page",
                                 channel: "bindingParams",
                                 action: "change",
                                 valueType: "json",

package/plugins/runtime-modules/revisions/types.d.ts

@@ -15,6 +15,9 @@ export type PhiBuilderRevisionHistoryRow = {
     createdAt: string;
     createdByUserId: number | null;
     createdByLabel: string | null;
+    /** When and by whom a Working Draft was last rewritten in place; null if it never was. */
+    savedAt: string | null;
+    savedByLabel: string | null;
     message: string | null;
     meta?: Record<string, unknown>;
     sourceRevisionId: number | null;

package/plugins/runtime-modules/settings.d.ts

@@ -2,7 +2,6 @@ import { type PhiDeclarableMediaSpaceKind, type PhiMediaKindValue } from "../../
 import type { PhisDeclarableThreadKind } from "../../types/threads";
 import type { PhiDeclaredModuleSeed } from "../../types/seed";
 import type { PhiRuntimeModuleDefinition, PhiRuntimeModuleId } from "./contracts";
-export declare function isPhiRuntimeModuleId(value: unknown): value is PhiRuntimeModuleId;
 export declare function readPhiRuntimeModuleIds(value: unknown): PhiRuntimeModuleId[] | null;
 export declare function assertPhiRuntimeModuleIdsAllowedForArea(area: string, moduleIds: readonly PhiRuntimeModuleId[], moduleDefinitions: readonly PhiRuntimeModuleDefinition[]): void;
 export declare function resolvePhiAuthUiProviderModuleId(moduleIds: readonly PhiRuntimeModuleId[], moduleDefinitions: readonly PhiRuntimeModuleDefinition[]): PhiRuntimeModuleId | null;
@@ -33,6 +32,15 @@ export type PhiRuntimeModuleSelectionReading = {
  * than a selection to trim.
  */
 export declare function readPhiRuntimeModuleIdsForArea(area: string, moduleIds: readonly PhiRuntimeModuleId[] | null | undefined, moduleDefinitions: readonly PhiRuntimeModuleDefinition[]): PhiRuntimeModuleSelectionReading;
+/**
+ * The stored selection, cut to what this build can serve.
+ *
+ * The tolerant reader, for a selection that was written by an earlier build or another Site: a Module
+ * that is gone, ineligible or locked is left out and named in the log, and the Builder shows it as an
+ * unresolved row ("Not in this build") until the next save drops it. Writes go through
+ * `assertPhiRuntimeModuleIdsAllowedForArea`, which refuses the same cases outright -- a selection may
+ * be read past what it names, never written past it (MODULES.md, "Module selection").
+ */
 export declare function resolvePhiRuntimeModuleIdsForArea(area: string, moduleIds: readonly PhiRuntimeModuleId[] | null | undefined, moduleDefinitions: readonly PhiRuntimeModuleDefinition[]): PhiRuntimeModuleId[];
 export type PhiDeclaredMediaSpaces = {
     [Kind in PhiDeclarableMediaSpaceKind]?: {

package/plugins/runtime-modules/settings.js

@@ -3,23 +3,19 @@ import { PhiMediaKind } from "../../constants/media";
 import { PHI_DECLARABLE_MEDIA_SPACE_KINDS, } from "../../types/media";
 import { PHIS_DECLARABLE_THREAD_KINDS } from "../../constants/threads";
 import { isPhiRuntimeAreaBaseModuleId } from "./area-definitions";
-export function isPhiRuntimeModuleId(value) {
-    if (typeof value !== "string") {
-        return false;
-    }
-    const trimmed = value.trim();
-    const separatorIndex = trimmed.lastIndexOf("/");
-    return separatorIndex > 0 && separatorIndex < trimmed.length - 1;
-}
+import { isPhiRuntimeModuleId } from "../../constants/module-identity";
+import { logRuntimeEvent } from "../../net/log";
 export function readPhiRuntimeModuleIds(value) {
     if (!Array.isArray(value)) {
         return null;
     }
     const moduleIds = value.map((candidate, index) => {
+        // The one reading of a Module id (`constants/module-identity.ts`): a bare `<package>/<key>` used to
+        // pass here and fail in the catalog, which read the marker this did not ask for.
         if (!isPhiRuntimeModuleId(candidate)) {
             throw new Error(`runtimeModules[${index}] must be a namespaced module id.`);
         }
-        return candidate.trim();
+        return candidate;
     });
     const uniqueModuleIds = new Set(moduleIds);
     if (uniqueModuleIds.size !== moduleIds.length) {
@@ -97,10 +93,23 @@ export function readPhiRuntimeModuleIdsForArea(area, moduleIds, moduleDefinition
     }
     return reading;
 }
+/**
+ * The stored selection, cut to what this build can serve.
+ *
+ * The tolerant reader, for a selection that was written by an earlier build or another Site: a Module
+ * that is gone, ineligible or locked is left out and named in the log, and the Builder shows it as an
+ * unresolved row ("Not in this build") until the next save drops it. Writes go through
+ * `assertPhiRuntimeModuleIdsAllowedForArea`, which refuses the same cases outright -- a selection may
+ * be read past what it names, never written past it (MODULES.md, "Module selection").
+ */
 export function resolvePhiRuntimeModuleIdsForArea(area, moduleIds, moduleDefinitions) {
     const reading = readPhiRuntimeModuleIdsForArea(area, moduleIds, moduleDefinitions);
     if (reading.unresolved.length > 0) {
-        console.warn("[phi-runtime-modules] Stored Module selection names Modules this build cannot serve.", { area, unresolved: reading.unresolved });
+        logRuntimeEvent("warn", "runtime_modules.selection.unresolved", {
+            message: "Stored Module selection names Modules this build cannot serve.",
+            area,
+            meta: { unresolved: reading.unresolved },
+        });
     }
     return reading.moduleIds;
 }

package/plugins/runtime-modules/shell-tree-composition.d.ts

@@ -87,13 +87,13 @@ export declare function omitPhiCmsShellCompositionNodes(tree: PhiResolvedCmsPage
         visibilityMask: number;
         label: string | null;
         parentLayoutNodeId: PhiCmsInstanceId;
-        contentId: number | null;
-        contentVersionId?: number | null;
+        contentVersionId: number | null;
+        contentBinding?: import("../../types").PhiCmsWidgetContentBinding | null;
         resolvedContent?: import("../../types").PhiCmsResolvedContent | null;
     }[];
     pageMeta?: import("../../types").PhiCmsResolvedPageMeta | null;
     runtimeModuleIds?: import("./contracts").PhiRuntimeModuleId[] | null;
-    controllerSettings?: readonly import("../../types").PhiRuntimeControllerSetting[] | null;
+    controllerSettings?: import("../../types/cms").PhiCmsTreeControllerSettings | null;
 };
 export declare function mergePhiCmsShellTrees(base: PhiResolvedCmsPageTree, overlay: PhiResolvedCmsPageTree): {
     pageMeta: import("../../types").PhiCmsResolvedPageMeta | null | undefined;
@@ -102,6 +102,6 @@ export declare function mergePhiCmsShellTrees(base: PhiResolvedCmsPageTree, over
     overlays: import("../../types").PhiCmsOverlayNode[];
     layoutNodes: import("../../types").PhiCmsLayoutNode[];
     contentWidgets: import("../../types").PhiCmsContentWidgetNode[];
+    controllerSettings: import("../../types/cms").PhiCmsTreeControllerSettings;
     page: import("../../types").PhiCmsPageNode;
-    controllerSettings?: readonly import("../../types").PhiRuntimeControllerSetting[] | null;
 };

package/plugins/runtime-modules/shell-tree-composition.js

@@ -1,6 +1,7 @@
 import { prunePhiSignalRoutesFromConfig } from "../../helpers/signal-route-lifecycle";
 import { createPhiPresetCmsInstanceId, } from "../../types/cms-instance-id";
 import { PHI_SIGNAL_SCOPES, createPhiSignalAddress } from "../../types/signals";
+import { concatPhiCmsTreeControllerSettings } from "../../helpers/cms-tree-controller-settings";
 export function omitPhiCmsShellCompositionNodes(tree, sourceIdentity, omitRegionTypes, omitNodeKeys) {
     const omittedTypes = new Set(omitRegionTypes);
     const explicitOmittedIds = new Set(omitNodeKeys.map((nodeKey) => createPhiPresetCmsInstanceId({
@@ -99,5 +100,6 @@ export function mergePhiCmsShellTrees(base, overlay) {
         overlays: [...base.overlays, ...overlay.overlays],
         layoutNodes: [...base.layoutNodes, ...overlay.layoutNodes],
         contentWidgets: [...base.contentWidgets, ...overlay.contentWidgets],
+        controllerSettings: concatPhiCmsTreeControllerSettings(base.controllerSettings, overlay.controllerSettings, "Area shell composition"),
     };
 }

package/plugins/runtime-modules/sidebar-route.d.ts

@@ -32,8 +32,8 @@ export type PhiSidebarAreaKey = keyof typeof PHI_SIDEBAR_AREA_ROUTE_DEFAULTS;
  * A Page a Module contributes together with its entry in an Area sidebar.
  *
  * The entry is placed by role, never by somebody else's item key: `start`, `main`, `settings` or `end`,
- * and the Area decides where that is. `settings` also mounts the route in the Area's Settings mount,
- * as every Settings Page does, and takes the Area's policy for who sees Settings entries.
+ * and the Area decides where that is. `settings` is the Area's Settings container, and an entry there
+ * takes the Area's policy for who sees Settings entries.
  *
  * The entry's label is the Page's title, and it names the route by its preset key. Further entries for
  * the same Page -- one in the account menu, say -- follow it unchanged.

package/plugins/runtime-modules/sidebar-route.js

@@ -22,8 +22,8 @@ const PHI_SIDEBAR_AREA_ROUTE_DEFAULTS = {
  * A Page a Module contributes together with its entry in an Area sidebar.
  *
  * The entry is placed by role, never by somebody else's item key: `start`, `main`, `settings` or `end`,
- * and the Area decides where that is. `settings` also mounts the route in the Area's Settings mount,
- * as every Settings Page does, and takes the Area's policy for who sees Settings entries.
+ * and the Area decides where that is. `settings` is the Area's Settings container, and an entry there
+ * takes the Area's policy for who sees Settings entries.
  *
  * The entry's label is the Page's title, and it names the route by its preset key. Further entries for
  * the same Page -- one in the account menu, say -- follow it unchanged.
@@ -39,7 +39,6 @@ export function buildPhiSidebarRoutePresetDescriptor({ area, anchor, ownerModule
         area,
         title,
         path,
-        ...(settings ? { mount: { mountKey: "settings" } } : {}),
         navigation: [{
                 navKey: resolvePhiAreaRootRouteNavKey(area),
                 anchor,

package/plugins/runtime-modules/site-module-client-manifests.d.ts

@@ -6,7 +6,7 @@ import type { PhiRuntimeModuleControllerClientManifest } from "../../components/
 import { type PhiRuntimeModuleUiProviderClientManifest } from "../../components/runtime/runtime-module-ui-provider-client-manifest";
 import type { PhiRuntimeModuleAuthoringClientContribution } from "./authoring-contributions-client";
 import type { PhiSiteModuleAuthoringContributions } from "./site-modules-authoring-client";
-import type { PhiSiteModuleClientAreaContributions, PhiSiteModuleClientContributions } from "./site-modules-client";
+import type { PhiSiteModuleClientContributions } from "./site-modules-client";
 /**
  * Adding what a Site's own Modules contribute to the first-party Client manifests.
  *
@@ -27,7 +27,6 @@ export type PhiSiteModuleClientManifests = {
     calendarAdapter: PhiRuntimeModuleCalendarAdapterClientManifest;
     uiProvider: PhiRuntimeModuleUiProviderClientManifest;
 };
-export declare function readPhiSiteModuleClientAreaContributions(contributions: PhiSiteModuleClientContributions, area: PhiCmsAreaKey): PhiSiteModuleClientAreaContributions;
 export declare function extendWithPhiSiteModuleClientManifests(contributions: PhiSiteModuleClientContributions, area: PhiCmsAreaKey, base: PhiSiteModuleClientManifests): PhiSiteModuleClientManifests;
 /**
  * The Site's own Authoring contributions, for the Builder.

package/plugins/runtime-modules/site-module-client-manifests.js

@@ -4,7 +4,7 @@ import { extendPhiRuntimeModuleDataProviderClientManifest, } from "../../compone
 import { extendPhiRuntimeModuleRenderClientManifest, } from "../../components/runtime/runtime-module-render-client-manifest";
 import { extendPhiRuntimeModuleUiProviderClientManifest, } from "../../components/runtime/runtime-module-ui-provider-client-manifest";
 import { extendPhiRuntimeModuleControllerClientManifest } from "./area-contributions-controller-client";
-export function readPhiSiteModuleClientAreaContributions(contributions, area) {
+function readPhiSiteModuleClientAreaContributions(contributions, area) {
     return contributions.areas[area] ?? {};
 }
 export function extendWithPhiSiteModuleClientManifests(contributions, area, base) {

package/plugins/runtime-modules/theme/brand-theme-model.d.ts

@@ -0,0 +1,170 @@
+import type { PhiBlockRuntime } from "../../../types/widget-runtime";
+import type { PhiCmsAreaKey } from "../../../constants/cms-areas";
+import { type PhiThemePresetPlugin } from "../../../theme/phi-theme-presets";
+import type { PhiBuilderBrandWidgetConfig } from "./widgets/brand-controls/config";
+import type { PhiHistoryAction, PhiHistoryLabels } from "../../../components/widgets/label-types/history";
+export type ThemePayload = NonNullable<PhiBlockRuntime["site"]["theme"]>;
+export declare const phiThemeHistory: {
+    clear: (scopeKey: string) => void;
+    endGesture: (scopeKey?: string) => void;
+    getAvailability: (scopeKey: string) => {
+        canUndo: boolean;
+        canRedo: boolean;
+        undoAction: PhiHistoryAction | null;
+        redoAction: PhiHistoryAction | null;
+    };
+    getHead: (scopeKey: string) => {
+        action: PhiHistoryAction;
+        before: Omit<import("../../../types/site-config").PhiSiteTheme, "mode"> & {
+            mode: import("../../../types").PhiWidgetThemeMode;
+        };
+        after: Omit<import("../../../types/site-config").PhiSiteTheme, "mode"> & {
+            mode: import("../../../types").PhiWidgetThemeMode;
+        };
+        coalesceKey?: string;
+    } | null;
+    record: (scopeKey: string, entry: {
+        action: PhiHistoryAction;
+        before: Omit<import("../../../types/site-config").PhiSiteTheme, "mode"> & {
+            mode: import("../../../types").PhiWidgetThemeMode;
+        };
+        after: Omit<import("../../../types/site-config").PhiSiteTheme, "mode"> & {
+            mode: import("../../../types").PhiWidgetThemeMode;
+        };
+        coalesceKey?: string;
+    }) => void;
+    redo: (scopeKey: string, apply: (snapshot: Omit<import("../../../types/site-config").PhiSiteTheme, "mode"> & {
+        mode: import("../../../types").PhiWidgetThemeMode;
+    }) => void) => {
+        action: PhiHistoryAction;
+        before: Omit<import("../../../types/site-config").PhiSiteTheme, "mode"> & {
+            mode: import("../../../types").PhiWidgetThemeMode;
+        };
+        after: Omit<import("../../../types/site-config").PhiSiteTheme, "mode"> & {
+            mode: import("../../../types").PhiWidgetThemeMode;
+        };
+        coalesceKey?: string;
+    } | null;
+    subscribe: (scopeKey: import("../../../state").PhiPluginStateScope, listener: () => void) => () => void;
+    undo: (scopeKey: string, apply: (snapshot: Omit<import("../../../types/site-config").PhiSiteTheme, "mode"> & {
+        mode: import("../../../types").PhiWidgetThemeMode;
+    }) => void) => {
+        action: PhiHistoryAction;
+        before: Omit<import("../../../types/site-config").PhiSiteTheme, "mode"> & {
+            mode: import("../../../types").PhiWidgetThemeMode;
+        };
+        after: Omit<import("../../../types/site-config").PhiSiteTheme, "mode"> & {
+            mode: import("../../../types").PhiWidgetThemeMode;
+        };
+        coalesceKey?: string;
+    } | null;
+    useAvailability: (scopeKey: string) => {
+        canUndo: boolean;
+        canRedo: boolean;
+        undoAction: PhiHistoryAction | null;
+        redoAction: PhiHistoryAction | null;
+    };
+    useHead: (scopeKey: string) => {
+        action: PhiHistoryAction;
+        before: Omit<import("../../../types/site-config").PhiSiteTheme, "mode"> & {
+            mode: import("../../../types").PhiWidgetThemeMode;
+        };
+        after: Omit<import("../../../types/site-config").PhiSiteTheme, "mode"> & {
+            mode: import("../../../types").PhiWidgetThemeMode;
+        };
+        coalesceKey?: string;
+    } | null;
+};
+/**
+ * One Theme edit as a history step: the parts of the Theme it changed, named in the author's language.
+ * A field that was only reordered is not a change; fields are compared by value.
+ */
+export declare function resolvePhiThemeHistoryAction(before: ThemePayload, after: ThemePayload, labels: PhiHistoryLabels): PhiHistoryAction;
+export type ThemeReadResponse = {
+    key?: string;
+    published?: ThemePayload;
+    publishedRevisionId?: number | null;
+    workingDraftRevisionId?: number | null;
+    draft?: {
+        revisionId?: number | null;
+        theme?: {
+            theme?: ThemePayload;
+            key?: string;
+        } | null;
+    } | null;
+};
+export type ThemeWriteResponse = {
+    key?: string;
+    revisionId?: number | null;
+    theme?: {
+        theme?: ThemePayload;
+        key?: string;
+    } | null;
+    error?: string;
+};
+export type BrandThemeState = {
+    key: string;
+    published: ThemePayload;
+    draft: ThemePayload;
+    revisionId: number | null;
+    hasPublishedThemeRevision: boolean;
+    publishedRevisionId: number | null;
+};
+export declare const DEFAULT_THEME_KEY = "default";
+/** The record without the named fields, for the places where a part of the Theme is handed back to its block. */
+export declare function omitThemeFields(theme: ThemePayload, ...fields: ReadonlyArray<keyof ThemePayload>): ThemePayload;
+export declare function resolveThemeKey(config?: PhiBuilderBrandWidgetConfig | null): string;
+export declare function normalizeTheme(input: unknown, fallback: ThemePayload): ThemePayload;
+/**
+ * A fresh draft names its blocks and owns nothing: the proportions come from the style block at
+ * resolve time, the colour from the palette block, and nothing is copied in that a reset would later
+ * have to know how to take away.
+ */
+export declare function resolveInitialTheme(runtime: PhiBlockRuntime): ThemePayload;
+export declare function clearThemeControlShape(theme: ThemePayload): ThemePayload;
+export declare function resolveThemePayloadPreset(theme: ThemePayload, presets: readonly PhiThemePresetPlugin[]): PhiThemePresetPlugin;
+/**
+ * Picking a palette block drops the author's own palette, exactly as picking a ground or a style drops
+ * theirs: somebody choosing another palette means to see it, and their seeds laid over it would hide
+ * the very thing they asked for.
+ */
+export declare function applyThemePreset(theme: ThemePayload, preset: PhiThemePresetPlugin): ThemePayload;
+/** Back to the blocks alone: the palette, the proportions, the Button shadows and the component overrides all go. */
+export declare function resetThemeToPreset(theme: ThemePayload, presets: readonly PhiThemePresetPlugin[], preset?: PhiThemePresetPlugin): ThemePayload;
+export declare function buildThemeReviewHref({ area, revisionId, themeKey, }: {
+    area: PhiCmsAreaKey;
+    revisionId: number;
+    themeKey: string;
+}): string;
+/**
+ * What a Widget knows before the Controller has told it anything: the theme the Site was rendered with.
+ *
+ * It used to consult a module variable the Widgets kept between them, because a Widget mounting late
+ * had no other way to learn about an unsaved draft. That variable answered for the browser tab, while
+ * the draft belongs to the Area the Controller is mounted in -- so it was right by coincidence and
+ * silently wrong wherever the two differed. A Widget asks now, and this is only the starting point.
+ */
+export declare function createInitialBrandThemeState(themeKey: string, fallbackTheme: ThemePayload): BrandThemeState;
+export declare function isSameThemePayload(left: ThemePayload, right: ThemePayload): boolean;
+/**
+ * Where a draft stands in a continuous edit.
+ *
+ * A colour picker or a slider sends a draft for every value it passes over, and none of those is a
+ * decision: the decision is taking the value -- closing the picker, letting go of the slider -- or
+ * putting it back with Escape.
+ * `live` is a step shown in the preview and kept out of the history; `commit` ends the edit with one
+ * entry from where it started; `discard` ends it with none and the Theme as it was before it opened.
+ */
+export type PhiThemeDraftEdit = "live" | "commit" | "discard";
+/**
+ * A Set decides all three parts, so it clears all three: the parts picked one by one, because a Set is
+ * what somebody falls back on when they stop deciding each part, and the values authored on top of
+ * them, for the same reason picking a single block clears its own. The Control shape belongs to the
+ * style, so it goes with the style tokens.
+ */
+export declare function mergeThemeSetChoice(theme: ThemePayload, set: {
+    key: string;
+    version: number;
+}): ThemePayload;
+/** Every ground value an author set, in both modes, so the chosen block is what shows. */
+export declare function clearThemeAuthoredGround(theme: ThemePayload): ThemePayload;