@phis/ui 0.1.0

package/plugins/runtime-modules/server-capabilities.js

@@ -0,0 +1,48 @@
+import { PHI_CORE_SERVER_PROVIDER_ID } from "../../types/server-capabilities";
+/**
+ * Whether a Module's server half is there, on this Site, in the shape it was built against.
+ *
+ * A binding naming no capability still says something, and only for Core does it say nothing worth
+ * checking: Core is the process doing the rendering, so it cannot be absent, and the snapshot is
+ * legitimately missing wherever there is no Site to take one of -- authoring tools, validation scripts.
+ * Requiring one there would take every built-in Module out of service in exactly those places.
+ *
+ * Anywhere else the provider is an Add-on, and "my server half is installed and enabled here" is a
+ * statement that can be false. Reading the empty list as "nothing to check" made it unfalsifiable: a
+ * Module bound to an Add-on that was never installed rendered anyway, and the failure arrived as every
+ * one of its requests missing a route.
+ */
+export function resolvePhiRuntimeModuleServerBinding(binding, snapshot) {
+    if (binding.providerId === PHI_CORE_SERVER_PROVIDER_ID
+        && binding.requiredCapabilities.length === 0) {
+        return { available: true };
+    }
+    if (!snapshot) {
+        return {
+            available: false,
+            state: "unavailable",
+            diagnosticCode: "capability_snapshot_unavailable",
+            missingCapabilities: binding.requiredCapabilities,
+        };
+    }
+    const provider = snapshot.providers.find(({ providerId }) => providerId === binding.providerId);
+    if (!provider) {
+        return {
+            available: false,
+            state: "missing",
+            diagnosticCode: "provider_missing",
+            missingCapabilities: binding.requiredCapabilities,
+        };
+    }
+    const availableCapabilities = new Set(provider.capabilities.map(({ id }) => id));
+    const missingCapabilities = binding.requiredCapabilities.filter((capability) => !availableCapabilities.has(capability));
+    if (provider.state !== "available" || missingCapabilities.length > 0) {
+        return {
+            available: false,
+            state: provider.state === "available" ? "missing" : provider.state,
+            diagnosticCode: provider.diagnosticCode ?? (missingCapabilities.length > 0 ? "capability_missing" : "provider_unavailable"),
+            missingCapabilities,
+        };
+    }
+    return { available: true };
+}

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

@@ -0,0 +1,57 @@
+import { type PhiDeclarableMediaSpaceKind, type PhiMediaKindValue } from "../../types/media";
+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;
+/** Why a stored Module id is not part of the selection this build can serve. */
+export type PhiUnresolvedRuntimeModuleReason = "not-installed" | "ineligible" | "locked";
+export type PhiRuntimeModuleSelectionReading = {
+    moduleIds: PhiRuntimeModuleId[];
+    unresolved: {
+        moduleId: PhiRuntimeModuleId;
+        reason: PhiUnresolvedRuntimeModuleReason;
+    }[];
+};
+/**
+ * The Modules an Area activates, as far as this build can serve them.
+ *
+ * A stored selection and an installed set are allowed to disagree, and they do so routinely: a deploy
+ * updates the configuration before the new build is rolled out, a rollback puts an older build under a
+ * newer configuration, and an operator removes a package a Site still names. None of those is a reason
+ * to stop answering -- the Area would go down over a Module that was optional in the first place.
+ *
+ * So the read drops what it cannot serve and says which ids it dropped; the caller decides whether that
+ * is worth a line in the log or a row in the Builder. Refusing stays where it belongs, on the write:
+ * `assertPhiRuntimeModuleIdsAllowedForArea` is what a Builder save still goes through, so nothing
+ * unresolvable is ever written back.
+ *
+ * The Area's own Base Module and the Platform Module are not part of this at all. They are implicit and
+ * added elsewhere; a build missing one of those cannot serve the Area, and that is a failure rather
+ * than a selection to trim.
+ */
+export declare function readPhiRuntimeModuleIdsForArea(area: string, moduleIds: readonly PhiRuntimeModuleId[] | null | undefined, moduleDefinitions: readonly PhiRuntimeModuleDefinition[]): PhiRuntimeModuleSelectionReading;
+export declare function describePhiUnresolvedRuntimeModules(area: string, unresolved: readonly {
+    moduleId: PhiRuntimeModuleId;
+    reason: PhiUnresolvedRuntimeModuleReason;
+}[]): string;
+export declare function resolvePhiRuntimeModuleIdsForArea(area: string, moduleIds: readonly PhiRuntimeModuleId[] | null | undefined, moduleDefinitions: readonly PhiRuntimeModuleDefinition[]): PhiRuntimeModuleId[];
+export type PhiDeclaredMediaSpaces = {
+    [Kind in PhiDeclarableMediaSpaceKind]?: {
+        kinds: PhiMediaKindValue[];
+    };
+};
+/**
+ * Derives the Media Spaces an Area needs from the Modules it activates, and what may go in them.
+ *
+ * Availability is a capability, not a quota, and it belongs to the Modules that need it. This is the
+ * only place the derivation happens: the result travels with the Area preset, and the control plane
+ * materializes the Site-wide availability as the union across published Areas. Ordering follows the
+ * declarable list rather than module order so an unchanged selection serializes byte-identically.
+ *
+ * Content kinds union the same way availability does, and for the same reason: two Modules sharing a
+ * Space each need what they declared, so the Space holds both. A Space kind present with an empty
+ * `kinds` is a Module that needs the Space without saying what for -- read as accepting nothing, which
+ * is the safe reading of an omission and the one that makes a Module state its purpose.
+ */
+export declare function resolvePhiDeclaredMediaSpaces(moduleIds: readonly PhiRuntimeModuleId[], moduleDefinitions: readonly PhiRuntimeModuleDefinition[]): PhiDeclaredMediaSpaces;

package/plugins/runtime-modules/settings.js

@@ -0,0 +1,154 @@
+import { isPhiCmsAreaKey, } from "../../constants/cms-areas";
+import { PhiMediaKind } from "../../constants/media";
+import { PHI_DECLARABLE_MEDIA_SPACE_KINDS, } from "../../types/media";
+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;
+}
+export function readPhiRuntimeModuleIds(value) {
+    if (!Array.isArray(value)) {
+        return null;
+    }
+    const moduleIds = value.map((candidate, index) => {
+        if (!isPhiRuntimeModuleId(candidate)) {
+            throw new Error(`runtimeModules[${index}] must be a namespaced module id.`);
+        }
+        return candidate.trim();
+    });
+    const uniqueModuleIds = new Set(moduleIds);
+    if (uniqueModuleIds.size !== moduleIds.length) {
+        throw new Error("runtimeModules must not contain duplicate module ids.");
+    }
+    return moduleIds;
+}
+function resolveSelectionArea(area) {
+    const cmsArea = area === "public" ? "public" : area;
+    if (!isPhiCmsAreaKey(cmsArea)) {
+        throw new Error(`Unknown Area "${area}".`);
+    }
+    return cmsArea;
+}
+export function assertPhiRuntimeModuleIdsAllowedForArea(area, moduleIds, moduleDefinitions) {
+    const cmsArea = resolveSelectionArea(area);
+    const definitionsById = new Map(moduleDefinitions.map((definition) => [definition.moduleId, definition]));
+    for (const moduleId of moduleIds) {
+        const definition = definitionsById.get(moduleId);
+        if (!definition) {
+            throw new Error(`Runtime module "${moduleId}" is not installed.`);
+        }
+        if (!definition.eligibleAreas.includes(cmsArea)) {
+            throw new Error(`Runtime module "${moduleId}" is not eligible for Area "${cmsArea}".`);
+        }
+        if (definition.kind === "platform" || isPhiRuntimeAreaBaseModuleId(moduleId)) {
+            throw new Error(`Locked runtime module "${moduleId}" must not be persisted in Area settings.`);
+        }
+    }
+    const authUiProviderModuleIds = moduleIds.filter((moduleId) => definitionsById.get(moduleId)?.authUiProvider != null);
+    if (authUiProviderModuleIds.length > 1) {
+        throw new Error(`Area "${cmsArea}" must not activate more than one Auth UI provider: ${authUiProviderModuleIds.join(", ")}.`);
+    }
+}
+export function resolvePhiAuthUiProviderModuleId(moduleIds, moduleDefinitions) {
+    const selected = new Set(moduleIds);
+    return moduleDefinitions.find((definition) => selected.has(definition.moduleId) && definition.authUiProvider != null)?.moduleId ?? null;
+}
+/**
+ * The Modules an Area activates, as far as this build can serve them.
+ *
+ * A stored selection and an installed set are allowed to disagree, and they do so routinely: a deploy
+ * updates the configuration before the new build is rolled out, a rollback puts an older build under a
+ * newer configuration, and an operator removes a package a Site still names. None of those is a reason
+ * to stop answering -- the Area would go down over a Module that was optional in the first place.
+ *
+ * So the read drops what it cannot serve and says which ids it dropped; the caller decides whether that
+ * is worth a line in the log or a row in the Builder. Refusing stays where it belongs, on the write:
+ * `assertPhiRuntimeModuleIdsAllowedForArea` is what a Builder save still goes through, so nothing
+ * unresolvable is ever written back.
+ *
+ * The Area's own Base Module and the Platform Module are not part of this at all. They are implicit and
+ * added elsewhere; a build missing one of those cannot serve the Area, and that is a failure rather
+ * than a selection to trim.
+ */
+export function readPhiRuntimeModuleIdsForArea(area, moduleIds, moduleDefinitions) {
+    const cmsArea = resolveSelectionArea(area);
+    const definitionsById = new Map(moduleDefinitions.map((definition) => [definition.moduleId, definition]));
+    const reading = { moduleIds: [], unresolved: [] };
+    for (const moduleId of [...new Set(moduleIds ?? [])]) {
+        const definition = definitionsById.get(moduleId);
+        if (!definition) {
+            reading.unresolved.push({ moduleId, reason: "not-installed" });
+            continue;
+        }
+        if (!definition.eligibleAreas.includes(cmsArea)) {
+            reading.unresolved.push({ moduleId, reason: "ineligible" });
+            continue;
+        }
+        if (definition.kind === "platform" || isPhiRuntimeAreaBaseModuleId(moduleId)) {
+            reading.unresolved.push({ moduleId, reason: "locked" });
+            continue;
+        }
+        reading.moduleIds.push(moduleId);
+    }
+    return reading;
+}
+export function describePhiUnresolvedRuntimeModules(area, unresolved) {
+    return unresolved
+        .map(({ moduleId, reason }) => `${moduleId} (${reason})`)
+        .join(", ") + ` -- Area "${area}"`;
+}
+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 });
+    }
+    return reading.moduleIds;
+}
+/** Declaration order, so an unchanged selection serializes byte-identically. */
+const PHI_MEDIA_KIND_ORDER = Object.values(PhiMediaKind);
+/**
+ * Derives the Media Spaces an Area needs from the Modules it activates, and what may go in them.
+ *
+ * Availability is a capability, not a quota, and it belongs to the Modules that need it. This is the
+ * only place the derivation happens: the result travels with the Area preset, and the control plane
+ * materializes the Site-wide availability as the union across published Areas. Ordering follows the
+ * declarable list rather than module order so an unchanged selection serializes byte-identically.
+ *
+ * Content kinds union the same way availability does, and for the same reason: two Modules sharing a
+ * Space each need what they declared, so the Space holds both. A Space kind present with an empty
+ * `kinds` is a Module that needs the Space without saying what for -- read as accepting nothing, which
+ * is the safe reading of an omission and the one that makes a Module state its purpose.
+ */
+export function resolvePhiDeclaredMediaSpaces(moduleIds, moduleDefinitions) {
+    const selected = new Set(moduleIds);
+    const declared = new Map();
+    for (const definition of moduleDefinitions) {
+        if (!selected.has(definition.moduleId)) {
+            continue;
+        }
+        for (const spaceKind of PHI_DECLARABLE_MEDIA_SPACE_KINDS) {
+            const declaration = definition.mediaSpaces?.[spaceKind];
+            if (!declaration) {
+                continue;
+            }
+            const contentKinds = declared.get(spaceKind) ?? new Set();
+            for (const contentKind of declaration.kinds) {
+                contentKinds.add(contentKind);
+            }
+            declared.set(spaceKind, contentKinds);
+        }
+    }
+    const resolved = {};
+    for (const spaceKind of PHI_DECLARABLE_MEDIA_SPACE_KINDS) {
+        const contentKinds = declared.get(spaceKind);
+        if (!contentKinds) {
+            continue;
+        }
+        resolved[spaceKind] = { kinds: PHI_MEDIA_KIND_ORDER.filter((kind) => contentKinds.has(kind)) };
+    }
+    return resolved;
+}

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

@@ -0,0 +1,104 @@
+import type { PhiCmsRegionTypeValue } from "../../constants/phi-cms";
+import { type PhiCmsInstanceId } from "../../types/cms-instance-id";
+import type { PhiCmsPresetIdentity } from "../../types/cms-module-descriptors";
+import type { PhiResolvedCmsPageTree } from "../../types/cms";
+export declare function omitPhiCmsShellCompositionNodes(tree: PhiResolvedCmsPageTree, sourceIdentity: PhiCmsPresetIdentity, omitRegionTypes: readonly PhiCmsRegionTypeValue[], omitNodeKeys: readonly string[]): {
+    page: {
+        heroRootLayoutNodeId: PhiCmsInstanceId | null;
+        headerBottomRootLayoutNodeId: PhiCmsInstanceId | null;
+        siderRightRootLayoutNodeId: PhiCmsInstanceId | null;
+        footerTopRootLayoutNodeId: PhiCmsInstanceId | null;
+        drawerRightRootLayoutNodeId: PhiCmsInstanceId | null;
+        contentRootLayoutNodeId: PhiCmsInstanceId | null;
+        id: number;
+        siteId: number;
+        areaMask: number;
+        path: string;
+        pageType: number;
+        status: number;
+        flags: number;
+        visibilityMask: number;
+        accessPolicy: import("@phis/contracts/access").PhiViewerAccessPolicy;
+        titleMsgId: number | null;
+        descriptionMsgId: number | null;
+        layoutConfig: Record<string, unknown>;
+    };
+    regions: {
+        config: Record<string, unknown>;
+        id: number;
+        pageId: number;
+        areaPresetId?: number | null;
+        regionType: number;
+        rootLayoutNodeId: PhiCmsInstanceId;
+        status: number;
+        flags: number;
+        visibilityMask: number;
+        sortOrder: number;
+    }[];
+    overlays: ({
+        config: Record<string, unknown>;
+        id: PhiCmsInstanceId;
+        overlayType: import("../../types").PhiCmsOverlayType;
+        headerLayoutNodeId: PhiCmsInstanceId | null;
+        bodyLayoutNodeId: PhiCmsInstanceId;
+        status: number;
+        flags: number;
+        visibilityMask: number;
+        sortOrder: number;
+        label: string | null;
+        footerPresentation: Extract<import("../../types").PhiOverlayFooterPresentation, "none">;
+        footerLayoutNodeId: null;
+    } | {
+        config: Record<string, unknown>;
+        id: PhiCmsInstanceId;
+        overlayType: import("../../types").PhiCmsOverlayType;
+        headerLayoutNodeId: PhiCmsInstanceId | null;
+        bodyLayoutNodeId: PhiCmsInstanceId;
+        status: number;
+        flags: number;
+        visibilityMask: number;
+        sortOrder: number;
+        label: string | null;
+        footerPresentation: Exclude<import("../../types").PhiOverlayFooterPresentation, "none">;
+        footerLayoutNodeId: PhiCmsInstanceId;
+    })[];
+    layoutNodes: {
+        config: Record<string, unknown>;
+        id: PhiCmsInstanceId;
+        siteId: number;
+        widgetType: string;
+        slotIndex: number;
+        sortOrder: number;
+        status: number;
+        flags: number;
+        visibilityMask: number;
+        label: string | null;
+        parentLayoutNodeId: PhiCmsInstanceId | null;
+    }[];
+    contentWidgets: {
+        config: Record<string, unknown>;
+        id: PhiCmsInstanceId;
+        siteId: number;
+        widgetType: string;
+        slotIndex: number;
+        sortOrder: number;
+        status: number;
+        flags: number;
+        visibilityMask: number;
+        label: string | null;
+        parentLayoutNodeId: PhiCmsInstanceId;
+        contentId: number | null;
+        resolvedContent?: import("../../types").PhiCmsResolvedContent | null;
+    }[];
+    pageMeta?: import("../../types").PhiCmsResolvedPageMeta | null;
+    runtimeModuleIds?: import("./contracts").PhiRuntimeModuleId[] | null;
+};
+export declare function mergePhiCmsShellTrees(base: PhiResolvedCmsPageTree, overlay: PhiResolvedCmsPageTree): {
+    pageMeta: import("../../types").PhiCmsResolvedPageMeta | null | undefined;
+    runtimeModuleIds: `${string}/${string}`[] | null | undefined;
+    regions: import("../../types").PhiCmsRegionNode[];
+    overlays: import("../../types").PhiCmsOverlayNode[];
+    layoutNodes: import("../../types").PhiCmsLayoutNode[];
+    contentWidgets: import("../../types").PhiCmsContentWidgetNode[];
+    page: import("../../types").PhiCmsPageNode;
+};

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

@@ -0,0 +1,103 @@
+import { prunePhiSignalRoutesFromConfig } from "../../helpers/signal-route-lifecycle";
+import { createPhiPresetCmsInstanceId, } from "../../types/cms-instance-id";
+import { PHI_SIGNAL_SCOPES, createPhiSignalAddress } from "../../types/signals";
+export function omitPhiCmsShellCompositionNodes(tree, sourceIdentity, omitRegionTypes, omitNodeKeys) {
+    const omittedTypes = new Set(omitRegionTypes);
+    const explicitOmittedIds = new Set(omitNodeKeys.map((nodeKey) => createPhiPresetCmsInstanceId({
+        domain: "area",
+        ...sourceIdentity,
+        nodeKey,
+    })));
+    const omittedLayoutIds = new Set([
+        ...tree.layoutNodes.filter((node) => explicitOmittedIds.has(node.id)).map((node) => node.id),
+        ...tree.regions.filter((region) => omittedTypes.has(region.regionType)).map((region) => region.rootLayoutNodeId),
+        ...tree.overlays.filter((overlay) => explicitOmittedIds.has(overlay.id)).flatMap((overlay) => [
+            overlay.headerLayoutNodeId,
+            overlay.bodyLayoutNodeId,
+            overlay.footerLayoutNodeId,
+        ].filter((id) => id != null)),
+    ]);
+    const omittedOverlayIds = new Set();
+    let changed = true;
+    while (changed) {
+        changed = false;
+        for (const node of tree.layoutNodes) {
+            if (node.parentLayoutNodeId != null && omittedLayoutIds.has(node.parentLayoutNodeId)) {
+                const previousSize = omittedLayoutIds.size;
+                omittedLayoutIds.add(node.id);
+                changed ||= omittedLayoutIds.size !== previousSize;
+            }
+        }
+        for (const overlay of tree.overlays) {
+            const rootLayoutNodeIds = [
+                overlay.headerLayoutNodeId,
+                overlay.bodyLayoutNodeId,
+                overlay.footerLayoutNodeId,
+            ].filter((id) => id != null);
+            if (explicitOmittedIds.has(overlay.id) || rootLayoutNodeIds.some((id) => omittedLayoutIds.has(id))) {
+                const previousOverlaySize = omittedOverlayIds.size;
+                omittedOverlayIds.add(overlay.id);
+                changed ||= omittedOverlayIds.size !== previousOverlaySize;
+                for (const id of rootLayoutNodeIds) {
+                    const previousLayoutSize = omittedLayoutIds.size;
+                    omittedLayoutIds.add(id);
+                    changed ||= omittedLayoutIds.size !== previousLayoutSize;
+                }
+            }
+        }
+    }
+    const omittedWidgetIds = new Set(tree.contentWidgets
+        .filter((node) => explicitOmittedIds.has(node.id) || omittedLayoutIds.has(node.parentLayoutNodeId))
+        .map((node) => node.id));
+    const omittedTargets = [...omittedOverlayIds, ...omittedLayoutIds, ...omittedWidgetIds].flatMap((id) => PHI_SIGNAL_SCOPES.map((scope) => ({ address: createPhiSignalAddress("cms", id), scope })));
+    const pruneConfig = (config) => prunePhiSignalRoutesFromConfig(config, omittedTargets);
+    const clearRoot = (value) => value != null && omittedLayoutIds.has(value) ? null : value;
+    return {
+        ...tree,
+        page: {
+            ...tree.page,
+            heroRootLayoutNodeId: clearRoot(tree.page.heroRootLayoutNodeId),
+            headerBottomRootLayoutNodeId: clearRoot(tree.page.headerBottomRootLayoutNodeId),
+            siderRightRootLayoutNodeId: clearRoot(tree.page.siderRightRootLayoutNodeId),
+            footerTopRootLayoutNodeId: clearRoot(tree.page.footerTopRootLayoutNodeId),
+            drawerRightRootLayoutNodeId: clearRoot(tree.page.drawerRightRootLayoutNodeId),
+            contentRootLayoutNodeId: clearRoot(tree.page.contentRootLayoutNodeId),
+        },
+        regions: tree.regions.filter((region) => !omittedTypes.has(region.regionType)).map((region) => ({
+            ...region,
+            config: pruneConfig(region.config),
+        })),
+        overlays: tree.overlays.filter((overlay) => !omittedOverlayIds.has(overlay.id)).map((overlay) => ({
+            ...overlay,
+            config: pruneConfig(overlay.config),
+        })),
+        layoutNodes: tree.layoutNodes.filter((node) => !omittedLayoutIds.has(node.id)).map((node) => ({
+            ...node,
+            config: pruneConfig(node.config),
+        })),
+        contentWidgets: tree.contentWidgets
+            .filter((node) => !omittedWidgetIds.has(node.id) && !omittedLayoutIds.has(node.parentLayoutNodeId))
+            .map((node) => ({ ...node, config: pruneConfig(node.config) })),
+    };
+}
+export function mergePhiCmsShellTrees(base, overlay) {
+    const regionTypes = new Set();
+    for (const region of [...base.regions, ...overlay.regions]) {
+        if (regionTypes.has(region.regionType)) {
+            throw new Error(`Area shell composition contains duplicate Region type "${String(region.regionType)}".`);
+        }
+        regionTypes.add(region.regionType);
+    }
+    return {
+        ...base,
+        ...overlay,
+        pageMeta: Object.prototype.hasOwnProperty.call(overlay, "pageMeta") ? overlay.pageMeta : base.pageMeta,
+        runtimeModuleIds: Object.prototype.hasOwnProperty.call(overlay, "runtimeModuleIds")
+            ? overlay.runtimeModuleIds
+            : base.runtimeModuleIds,
+        regions: [...base.regions, ...overlay.regions],
+        overlays: [...base.overlays, ...overlay.overlays],
+        layoutNodes: [...base.layoutNodes, ...overlay.layoutNodes],
+        contentWidgets: [...base.contentWidgets, ...overlay.contentWidgets],
+    };
+}

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

@@ -0,0 +1,41 @@
+import type { PhiCmsAreaKey } from "../../constants/cms-areas";
+import { type PhiRuntimeModuleCalendarAdapterClientManifest } from "../../components/runtime/runtime-module-calendar-adapter-client-manifest";
+import { type PhiRuntimeModuleDataProviderClientManifest } from "../../components/runtime/runtime-module-data-provider-client-manifest";
+import { type PhiRuntimeModuleRenderClientManifest } from "../../components/runtime/runtime-module-render-client-manifest";
+import type { PhiRuntimeModuleControllerClientManifest } from "../../components/runtime/runtime-module-controller-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";
+/**
+ * Adding what a Site's own Modules contribute to the first-party Client manifests.
+ *
+ * Applied in the generic Area hosts, which is where a Site build's projection is meant to be consumed:
+ * the Skeleton imports only those hosts, and neither it nor the individual first-party manifests learn
+ * that Site Modules exist.
+ *
+ * Nothing is merged leniently. Every `extend...` refuses a key the first-party manifests already hold,
+ * so a Site Module claiming a Widget type, Provider key, or Controller that is already taken fails
+ * where it is composed rather than by quietly winning or quietly losing at render time.
+ *
+ * The projection is an argument throughout: the Area host receives it and passes it here.
+ */
+export type PhiSiteModuleClientManifests = {
+    controller: PhiRuntimeModuleControllerClientManifest;
+    render: PhiRuntimeModuleRenderClientManifest;
+    dataProvider: PhiRuntimeModuleDataProviderClientManifest;
+    calendarAdapter: PhiRuntimeModuleCalendarAdapterClientManifest;
+};
+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.
+ *
+ * One per Module and no Area dimension: the Builder wraps an Authoring Client around the canvas for
+ * every active Module so a Module can be authored inside an isolated target-Area Canvas without being
+ * mounted in the Builder Area itself.
+ *
+ * It takes the Authoring projection rather than the live one. That is the whole separation: only the
+ * Builder host imports the generated file this argument comes from, so no other Area's bundle can reach
+ * an Authoring implementation.
+ */
+export declare function readAllPhiSiteModuleAuthoringClientContributions(contributions: PhiSiteModuleAuthoringContributions): readonly PhiRuntimeModuleAuthoringClientContribution[];

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

@@ -0,0 +1,31 @@
+"use client";
+import { extendPhiRuntimeModuleCalendarAdapterClientManifest, } from "../../components/runtime/runtime-module-calendar-adapter-client-manifest";
+import { extendPhiRuntimeModuleDataProviderClientManifest, } from "../../components/runtime/runtime-module-data-provider-client-manifest";
+import { extendPhiRuntimeModuleRenderClientManifest, } from "../../components/runtime/runtime-module-render-client-manifest";
+import { extendPhiRuntimeModuleControllerClientManifest } from "./area-contributions-controller-client";
+export function readPhiSiteModuleClientAreaContributions(contributions, area) {
+    return contributions.areas[area] ?? {};
+}
+export function extendWithPhiSiteModuleClientManifests(contributions, area, base) {
+    const areaContributions = readPhiSiteModuleClientAreaContributions(contributions, area);
+    return {
+        controller: extendPhiRuntimeModuleControllerClientManifest(base.controller, areaContributions.controllers ?? []),
+        render: extendPhiRuntimeModuleRenderClientManifest(base.render, areaContributions.renderClients ?? []),
+        dataProvider: extendPhiRuntimeModuleDataProviderClientManifest(base.dataProvider, areaContributions.dataProviders ?? []),
+        calendarAdapter: extendPhiRuntimeModuleCalendarAdapterClientManifest(base.calendarAdapter, contributions.calendarAdapters),
+    };
+}
+/**
+ * The Site's own Authoring contributions, for the Builder.
+ *
+ * One per Module and no Area dimension: the Builder wraps an Authoring Client around the canvas for
+ * every active Module so a Module can be authored inside an isolated target-Area Canvas without being
+ * mounted in the Builder Area itself.
+ *
+ * It takes the Authoring projection rather than the live one. That is the whole separation: only the
+ * Builder host imports the generated file this argument comes from, so no other Area's bundle can reach
+ * an Authoring implementation.
+ */
+export function readAllPhiSiteModuleAuthoringClientContributions(contributions) {
+    return contributions.authoring;
+}

package/plugins/runtime-modules/site-module-contributions.d.ts

@@ -0,0 +1,28 @@
+import { type PhiCmsAreaKey } from "../../constants/cms-areas";
+import { type PhiRuntimeModuleServerAreaContribution } from "./area-contributions";
+import type { PhiSiteModuleServerAreaContributions } from "./site-modules";
+/**
+ * Reading what the Site's own Modules contribute.
+ *
+ * These live here rather than in `site-modules.ts` because that module is the one a Site build resolves
+ * to a generated file; logic placed beside the data would have to be reproduced by whatever generates
+ * the replacement.
+ *
+ * They take the projection rather than reaching for one: what a Site installed arrives as an argument
+ * at the Area host, so there is nothing here to be bound to.
+ */
+export declare function readPhiSiteModuleServerAreaContributions(contributions: PhiSiteModuleServerAreaContributions, area: PhiCmsAreaKey): readonly PhiRuntimeModuleServerAreaContribution[];
+/**
+ * Every Area's contributions at once, for the Builder.
+ *
+ * The Builder projection receives the complete installed union, so a Module can be authored inside an
+ * isolated target-Area Canvas without being mounted in the Builder Area itself. One Module may
+ * contribute to several Areas, so the same id legitimately appears more than once here and the
+ * contributions are merged rather than rejected.
+ *
+ * Within a single Area they are not merged. A Site Module carrying a first-party module id is a
+ * collision, and `createPhiRuntimeModuleCatalogFromAreaContributions` refuses it -- a Module quietly
+ * losing to a built-in of the same id is the kind of fault that surfaces much later, in the Area that
+ * stopped offering it.
+ */
+export declare function readAllPhiSiteModuleServerAreaContributions(contributions: PhiSiteModuleServerAreaContributions): readonly PhiRuntimeModuleServerAreaContribution[];

package/plugins/runtime-modules/site-module-contributions.js

@@ -0,0 +1,33 @@
+import { PHI_CMS_AREA_KEYS } from "../../constants/cms-areas";
+import { mergePhiRuntimeModuleServerAreaContributions, } from "./area-contributions";
+/**
+ * Reading what the Site's own Modules contribute.
+ *
+ * These live here rather than in `site-modules.ts` because that module is the one a Site build resolves
+ * to a generated file; logic placed beside the data would have to be reproduced by whatever generates
+ * the replacement.
+ *
+ * They take the projection rather than reaching for one: what a Site installed arrives as an argument
+ * at the Area host, so there is nothing here to be bound to.
+ */
+export function readPhiSiteModuleServerAreaContributions(contributions, area) {
+    return contributions[area] ?? [];
+}
+/**
+ * Every Area's contributions at once, for the Builder.
+ *
+ * The Builder projection receives the complete installed union, so a Module can be authored inside an
+ * isolated target-Area Canvas without being mounted in the Builder Area itself. One Module may
+ * contribute to several Areas, so the same id legitimately appears more than once here and the
+ * contributions are merged rather than rejected.
+ *
+ * Within a single Area they are not merged. A Site Module carrying a first-party module id is a
+ * collision, and `createPhiRuntimeModuleCatalogFromAreaContributions` refuses it -- a Module quietly
+ * losing to a built-in of the same id is the kind of fault that surfaces much later, in the Area that
+ * stopped offering it.
+ */
+export function readAllPhiSiteModuleServerAreaContributions(contributions) {
+    return mergePhiRuntimeModuleServerAreaContributions(PHI_CMS_AREA_KEYS.flatMap((area) => [
+        ...readPhiSiteModuleServerAreaContributions(contributions, area),
+    ]));
+}

package/plugins/runtime-modules/site-modules-authoring-client.d.ts

@@ -0,0 +1,18 @@
+import type { PhiRuntimeModuleAuthoringClientContribution } from "./authoring-contributions-client";
+/**
+ * The Authoring half of a Site build's Client projection, and a file of its own on purpose.
+ *
+ * Authoring implementations must not reach a live Area graph -- `module-authoring-client.ts` states
+ * that rule, and MODULES.md requires the same of first-party Modules. Keeping the type apart is not
+ * what enforces it; keeping the *value* apart is. While one projection object carried both, every Area
+ * host that imported it imported the Authoring contributions with it, and a bundler has to pack a value
+ * it can reach whether or not anything reads it. Public paid for the Builder's table controls that way.
+ *
+ * So: two projections, two generated files, and only the Builder imports this one.
+ */
+export type PhiSiteModuleAuthoringContributions = {
+    /** One per Module. No Area dimension -- the Builder wraps one around the canvas per active Module. */
+    authoring: readonly PhiRuntimeModuleAuthoringClientContribution[];
+};
+/** A Site that installed no Modules of its own. */
+export declare const PHI_NO_SITE_MODULE_AUTHORING_CONTRIBUTIONS: PhiSiteModuleAuthoringContributions;

package/plugins/runtime-modules/site-modules-authoring-client.js

@@ -0,0 +1,5 @@
+"use client";
+/** A Site that installed no Modules of its own. */
+export const PHI_NO_SITE_MODULE_AUTHORING_CONTRIBUTIONS = {
+    authoring: [],
+};