@phis/ui 0.4.2 → 0.4.3

package/gateway/internal-references.d.ts

@@ -11,7 +11,12 @@ export type PhiResolvedInternalReferences = {
     pages: readonly PhiResolvedPageReference[];
     assets: ReadonlyMap<number, PhiPublicMediaAssetReference>;
 };
-/** One Asset of the public reference projection, as the server writes it; a shape it does not match throws. */
+/**
+ * One Asset of the public reference projection, as the server writes it; a shape it does not match throws.
+ *
+ * Every field, not five of them: what passed here went straight into a rendered page under a type that
+ * promised a focal rectangle and font metrics nobody had looked at.
+ */
 export declare function readPhiPublicMediaAssetReference(entry: unknown): PhiPublicMediaAssetReference;
 /**
  * Resolves both internal reference kinds, together with whatever else asks in the same turn.

package/gateway/internal-references.js

@@ -1,37 +1,62 @@
-import { isPhiRecord } from "../helpers/is-record";
 import "server-only";
 import { buildApiHeaders, buildApiUrl } from "../helpers/site-api";
+import { PhiMediaKind } from "../constants/media";
+import { readPhiFontMetricsFields } from "../components/media/media-font-metrics";
+import { createPhiResponseReader, requirePhiField } from "../components/widgets/config/strict-config-reader";
 import { readPhiPageReference } from "../types/references";
 import { throwPhiCmsGatewayError } from "./errors";
 import { peekPhiSiteReadCache, writePhiSiteReadCache } from "./site-read-cache";
 function readResolvedPage(entry) {
-    if (!isPhiRecord(entry)) {
-        throw new Error("Invalid internal Page reference projection.");
-    }
-    const value = entry;
-    const parsed = readPhiPageReference(value.reference);
-    if (!parsed || (value.path !== null && typeof value.path !== "string") || typeof value.deleted !== "boolean") {
-        throw new Error("Invalid internal Page reference projection.");
-    }
+    const reader = createPhiResponseReader(entry, "The internal reference projection");
+    const parsed = readPhiPageReference(reader.record.reference) ?? reader.fail("reference", "a Page reference");
+    const path = reader.record.path;
     return {
         reference: parsed.reference,
-        path: value.path,
-        deleted: value.deleted,
-        targetKind: value.targetKind === "module" ? "module" : "site",
+        path: path === null ? null : requirePhiField(reader, "path", "a path or null", reader.string),
+        deleted: requirePhiField(reader, "deleted", "true or false", reader.boolean),
+        targetKind: requirePhiField(reader, "targetKind", '"site" or "module"', (key) => reader.oneOf(key, ["site", "module"])),
     };
 }
-/** One Asset of the public reference projection, as the server writes it; a shape it does not match throws. */
+const PHI_MEDIA_KINDS = Object.values(PhiMediaKind);
+/**
+ * One Asset of the public reference projection, as the server writes it; a shape it does not match throws.
+ *
+ * Every field, not five of them: what passed here went straight into a rendered page under a type that
+ * promised a focal rectangle and font metrics nobody had looked at.
+ */
 export function readPhiPublicMediaAssetReference(entry) {
-    if (!isPhiRecord(entry)) {
-        throw new Error("Invalid internal Asset reference projection.");
-    }
-    const value = entry;
-    if (!Number.isSafeInteger(value.id) || value.id <= 0 ||
-        typeof value.deliveryUrl !== "string" || !Number.isSafeInteger(value.deliveryRevision) ||
-        typeof value.contentType !== "string" || typeof value.originalName !== "string") {
-        throw new Error("Invalid internal Asset reference projection.");
-    }
-    return value;
+    const reader = createPhiResponseReader(entry, "The internal reference projection");
+    const integer = (key) => requirePhiField(reader, key, "a whole number", reader.integer);
+    const text = (key) => requirePhiField(reader, key, "a text", reader.string);
+    const nullableNumber = (key) => reader.number(key) ?? null;
+    const nullableText = (key) => reader.string(key) ?? null;
+    const id = integer("id");
+    if (id <= 0)
+        reader.fail("id", "a positive whole number");
+    return {
+        id,
+        deliveryUrl: text("deliveryUrl"),
+        deliveryRevision: integer("deliveryRevision"),
+        variantVersion: reader.integer("variantVersion") ?? null,
+        contentType: text("contentType"),
+        kind: requirePhiField(reader, "kind", "a media kind", (key) => reader.oneOf(key, PHI_MEDIA_KINDS)),
+        originalName: text("originalName"),
+        width: nullableNumber("width"),
+        height: nullableNumber("height"),
+        blurDataUrl: nullableText("blurDataUrl"),
+        title: nullableText("title"),
+        altText: nullableText("altText"),
+        thumbnailUrl: nullableText("thumbnailUrl"),
+        previewUrl: nullableText("previewUrl"),
+        focalRect: reader.object("focalRect", (rect) => {
+            const fraction = (key) => {
+                const value = requirePhiField(rect, key, "a number from 0 to 1", rect.number);
+                return value >= 0 && value <= 1 ? value : rect.fail(key, "a number from 0 to 1");
+            };
+            return { x: fraction("x"), y: fraction("y"), width: fraction("width"), height: fraction("height") };
+        }) ?? null,
+        font: reader.object("font", readPhiFontMetricsFields) ?? null,
+    };
 }
 /** What the server takes per list in one request (`MAX_REFERENCES_PER_REQUEST`). */
 const PHI_REFERENCES_PER_REQUEST = 256;

package/gateway/site-cms-write-validation.d.ts

@@ -0,0 +1,9 @@
+import "server-only";
+import type { NextRequest } from "next/server";
+import type { PhiSiteAreaBridgeLoader } from "./site-area-bridges";
+/**
+ * The 422 for a write that carries an unreadable Widget config, or `null` to let it through.
+ *
+ * The body is read from a clone, so the request still goes upstream untouched.
+ */
+export declare function validatePhiCmsStructureWrite(request: NextRequest, loadAreaBridge: PhiSiteAreaBridgeLoader): Promise<Response | null>;

package/gateway/site-cms-write-validation.js

@@ -0,0 +1,78 @@
+import "server-only";
+import { isPhiCmsAreaKey } from "../constants/cms-areas";
+import { isPhiRecord } from "../helpers/is-record";
+import { buildPhiRuntimeModuleWidgetType } from "../plugins/runtime-modules/contracts";
+import { isPhiConfigError } from "../components/widgets/config/strict-config-reader";
+import { jsonResponse } from "./route-handler-helpers";
+function buildWidgetDefinitionsByType(catalog) {
+    const definitions = new Map();
+    for (const entry of catalog.values()) {
+        for (const widget of entry.widgets) {
+            definitions.set(buildPhiRuntimeModuleWidgetType(widget), widget.definition);
+        }
+    }
+    return definitions;
+}
+function findConfigIssue(body, definitions) {
+    const pending = [body];
+    while (pending.length > 0) {
+        const value = pending.pop();
+        if (Array.isArray(value)) {
+            pending.push(...value);
+            continue;
+        }
+        if (!isPhiRecord(value))
+            continue;
+        const widgetType = value.widgetType;
+        const config = value.config;
+        if (typeof widgetType === "string" && isPhiRecord(config)) {
+            const definition = definitions.get(widgetType);
+            if (definition) {
+                try {
+                    definition.parseConfig(config);
+                }
+                catch (error) {
+                    /*
+                     * Any error, not only the strict reader's: a Widget from another package may refuse its config
+                     * in its own words, and the live page leaves that Widget out just the same. Only the strict
+                     * reader can say which field it was.
+                     */
+                    return {
+                        widgetType,
+                        nodeId: value.id ?? null,
+                        path: isPhiConfigError(error) ? error.path : null,
+                        message: error instanceof Error ? error.message : String(error),
+                    };
+                }
+            }
+        }
+        pending.push(...Object.values(value));
+    }
+    return null;
+}
+/**
+ * The 422 for a write that carries an unreadable Widget config, or `null` to let it through.
+ *
+ * The body is read from a clone, so the request still goes upstream untouched.
+ */
+export async function validatePhiCmsStructureWrite(request, loadAreaBridge) {
+    const body = await request.clone().json().catch(() => null);
+    if (!isPhiRecord(body))
+        return null;
+    const area = typeof body.area === "string" ? body.area.trim().toLowerCase() : "";
+    if (!isPhiCmsAreaKey(area))
+        return null;
+    const bridge = await loadAreaBridge(area);
+    if (!bridge)
+        return null;
+    const issue = findConfigIssue(body, buildWidgetDefinitionsByType(bridge.runtimeModuleCatalog));
+    if (!issue)
+        return null;
+    return jsonResponse({
+        error: `${issue.widgetType}: ${issue.message}`,
+        code: "invalid-config",
+        widgetType: issue.widgetType,
+        nodeId: issue.nodeId,
+        field: issue.path,
+    }, 422);
+}

package/gateway/site-proxy.js

@@ -76,6 +76,22 @@ function clearingReadCacheOnWrite(handler) {
         return response;
     };
 }
+/**
+ * A CMS structure write is checked against the Widgets' own parsers before it goes upstream
+ * (`site-cms-write-validation.ts`), so a config no Widget can read is refused with the field it is in
+ * rather than stored and left out of the live page. Loaded with the first such write.
+ */
+function validatingCmsStructureWrite(handler, loadAreaBridge) {
+    return async (request, context) => {
+        if ((await context.params).path?.[0] === "cms") {
+            const { validatePhiCmsStructureWrite } = await import("./site-cms-write-validation");
+            const refusal = await validatePhiCmsStructureWrite(request, loadAreaBridge);
+            if (refusal)
+                return refusal;
+        }
+        return handler(request, context);
+    };
+}
 export function buildPhiSiteProxyHandlers(options) {
     const { upstreamBaseUrl, timeoutMs, buildHeaders, logLabel = "[phis-ui][/api/site proxy]", missingBaseUrlMessage = "Missing apiBaseUrl for /api/site proxy.", } = options;
     const handlers = PhiNextProxy({
@@ -122,9 +138,9 @@ export function buildPhiSiteProxyHandlers(options) {
         GET: answeringLocally("GET", handlers.GET),
         HEAD: answeringLocally("HEAD", handlers.HEAD),
         OPTIONS: answeringLocally("OPTIONS", handlers.OPTIONS),
-        POST: answeringLocally("POST", clearingReadCacheOnWrite(handlers.POST)),
-        PUT: answeringLocally("PUT", clearingReadCacheOnWrite(handlers.PUT)),
-        PATCH: answeringLocally("PATCH", clearingReadCacheOnWrite(handlers.PATCH)),
+        POST: answeringLocally("POST", validatingCmsStructureWrite(clearingReadCacheOnWrite(handlers.POST), options.loadAreaBridge)),
+        PUT: answeringLocally("PUT", validatingCmsStructureWrite(clearingReadCacheOnWrite(handlers.PUT), options.loadAreaBridge)),
+        PATCH: answeringLocally("PATCH", validatingCmsStructureWrite(clearingReadCacheOnWrite(handlers.PATCH), options.loadAreaBridge)),
         DELETE: answeringLocally("DELETE", clearingReadCacheOnWrite(handlers.DELETE)),
     };
 }

package/helpers/renderable-block-serialization.js

@@ -65,7 +65,7 @@ function normalizeRenderableBlockTransitionTrigger(value) {
         : undefined;
 }
 function normalizeRenderableBlockViewportEffectAxis(value) {
-    return value === "x" || value === "y" ? value : undefined;
+    return value === "x" || value === "y" || value === "z" ? value : undefined;
 }
 function normalizeRenderableBlockViewportEffectProperty(value) {
     return value === "translate" ||

package/next/config.d.mts

@@ -15,6 +15,9 @@ export declare function generatePhiAntdStaticCss(projectDir?: string): {
 /** The generated file for the Ant Design installed for `projectDir`, written once per input. */
 export declare function ensurePhiAntdStaticCss(projectDir?: string): string;
 
+/** The host in `config/site-runtime.json`'s `site.publicUrl` under `dir`, or `null` where there is none. */
+export declare function readPhiSitePublicHost(dir?: string): string | null;
+
 /**
  * A Site's `next.config`, with `@phis/ui/antd-static.css` resolved to the structure generated for its
  * Ant Design. `dir` is the Site's root, the directory its `package.json` is in.

package/next/config.mjs

@@ -257,15 +257,42 @@ export function ensurePhiAntdStaticCss(projectDir = process.cwd()) {
   return file;
 }
 
+/**
+ * The host the Site is reached at, from `config/site-runtime.json` (`site.publicUrl`), or `null` where the
+ * file or the field is absent -- a build outside a Site checkout has neither.
+ *
+ * The dev server serves its own resources only to the hosts in `allowedDevOrigins`; a page opened through
+ * any other host arrives as HTML and never hydrates -- no menu opens, nothing measured in the browser lays
+ * out. The public host was a list a person had to keep, and the one Site that moved to `dev.phis.dev`
+ * was missing from it. The CLI writes the file when it scaffolds a Site, so the host is known here.
+ */
+export function readPhiSitePublicHost(dir = process.cwd()) {
+  const file = path.join(dir, "config", "site-runtime.json");
+  if (!existsSync(file)) return null;
+  const publicUrl = JSON.parse(readFileSync(file, "utf8"))?.site?.publicUrl;
+  if (publicUrl === undefined || publicUrl === null || publicUrl === "") return null;
+  if (typeof publicUrl !== "string" || !URL.canParse(publicUrl)) {
+    throw new Error(`config/site-runtime.json: site.publicUrl must be a URL, found ${JSON.stringify(publicUrl)}.`);
+  }
+  return new URL(publicUrl).hostname;
+}
+
 /**
  * A Site's `next.config`, with `@phis/ui/antd-static.css` resolved to the structure generated for its
- * Ant Design. `dir` is the Site's root, the directory its `package.json` is in.
+ * Ant Design, and the Site's own public host allowed to reach the dev server. `dir` is the Site's root,
+ * the directory its `package.json` is in.
  */
 export function withPhiNextConfig(nextConfig, { dir = process.cwd() } = {}) {
   // Turbopack takes no absolute path as an alias target; a relative one is read from the Site's root.
   const file = `./${path.relative(dir, ensurePhiAntdStaticCss(dir)).split(path.sep).join("/")}`;
+  const publicHost = readPhiSitePublicHost(dir);
+  const allowedDevOrigins = [...new Set([
+    ...(nextConfig.allowedDevOrigins ?? []),
+    ...(publicHost ? [publicHost] : []),
+  ])];
   return {
     ...nextConfig,
+    ...(allowedDevOrigins.length > 0 ? { allowedDevOrigins } : {}),
     turbopack: {
       ...nextConfig.turbopack,
       resolveAlias: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phis/ui",
-  "version": "0.4.2",
+  "version": "0.4.3",
   "license": "Apache-2.0",
   "publishConfig": {
     "access": "public"
@@ -503,7 +503,7 @@
     "@lexical/rich-text": "0.50.0",
     "@lexical/selection": "0.50.0",
     "@lexical/utils": "0.50.0",
-    "@phis/contracts": "^0.6.0",
+    "@phis/contracts": "^0.7.0",
     "dayjs": "^1.11.23",
     "dom-serializer": "^2.0.0",
     "htmlparser2": "^10.1.0",

package/plugins/runtime/phi-slot-child-viewport-effects-observer.js

@@ -29,7 +29,8 @@ function applyEasing(progress, easing) {
     return progress;
 }
 function resolveProgress(effect, rect, viewportWidth, viewportHeight) {
-    const axis = effect.axis ?? PHI_RENDERABLE_BLOCK_DEFAULT_VIEWPORT_EFFECT.axis ?? "y";
+    // `z` has no extent on the page, so a turn about it follows the page's own scroll direction.
+    const axis = (effect.axis ?? PHI_RENDERABLE_BLOCK_DEFAULT_VIEWPORT_EFFECT.axis) === "x" ? "x" : "y";
     const targetStart = axis === "x" ? rect.left : rect.top;
     const rangeStart = resolveRangePoint(effect.rangeStart ?? PHI_RENDERABLE_BLOCK_DEFAULT_VIEWPORT_EFFECT.rangeStart, rect, viewportWidth, viewportHeight, axis);
     const rangeEnd = resolveRangePoint(effect.rangeEnd ?? PHI_RENDERABLE_BLOCK_DEFAULT_VIEWPORT_EFFECT.rangeEnd, rect, viewportWidth, viewportHeight, axis);
@@ -77,6 +78,9 @@ function resolveViewportEffectValues(effects, target) {
             if (axis === "x") {
                 values.rotateX = rotateValue;
             }
+            else if (axis === "z") {
+                values.rotateZ = rotateValue;
+            }
             else {
                 values.rotateY = rotateValue;
             }

package/plugins/runtime-modules/accounting/presets.d.ts

@@ -0,0 +1,9 @@
+import type { PhiCmsDescriptorBuildContext, PhiCmsRoutePresetDescriptor } from "../../../types/cms-module-descriptors";
+export declare const PHI_ACCOUNTING_RUNTIME_MODULE_AREA_SHELLS: {
+    ownerModuleId: "@phis/ui/modules/accounting";
+    presetKey: string;
+    shellPresetVersion: number;
+    area: "accounting";
+    loadTree: ({ page, runtime }: PhiCmsDescriptorBuildContext) => Promise<import("../../../types").PhiResolvedCmsPageTree>;
+}[];
+export declare const PHI_ACCOUNTING_RUNTIME_MODULE_ROUTES: PhiCmsRoutePresetDescriptor[];

package/plugins/runtime-modules/accounting/presets.js

@@ -0,0 +1,37 @@
+import { PHI_BASE_PAGE_LAYOUT_VERSION } from "../../../components/regions/presets/phi-base-page-layout";
+import { buildPhiAreaRootRoutePresetDescriptor } from "../area-root-route";
+import { PHI_ACCOUNTING_RUNTIME_MODULE_ID } from "./ids";
+/* What the Accounting base Module brings: the Site shell for its Area, the Area root and the overview. */
+export const PHI_ACCOUNTING_RUNTIME_MODULE_AREA_SHELLS = [
+    {
+        ownerModuleId: PHI_ACCOUNTING_RUNTIME_MODULE_ID,
+        presetKey: "accounting-area-preset",
+        shellPresetVersion: 1,
+        area: "accounting",
+        loadTree: ({ page, runtime }) => import("../phi-default-site-area-preset-tree")
+            .then((module) => module.buildPhiDefaultSiteAreaPresetTree({
+            page,
+            runtime,
+            presetKey: "accounting-area-preset",
+            ownerModuleId: PHI_ACCOUNTING_RUNTIME_MODULE_ID,
+            runtimeModuleArea: "accounting",
+        })),
+    },
+];
+export const PHI_ACCOUNTING_RUNTIME_MODULE_ROUTES = [
+    buildPhiAreaRootRoutePresetDescriptor({
+        ownerModuleId: PHI_ACCOUNTING_RUNTIME_MODULE_ID,
+        area: "accounting",
+        title: "Accounting",
+    }),
+    {
+        ownerModuleId: PHI_ACCOUNTING_RUNTIME_MODULE_ID,
+        presetKey: "accounting-overview-page",
+        presetVersion: 1 + PHI_BASE_PAGE_LAYOUT_VERSION,
+        area: "accounting",
+        title: "Overview",
+        path: "/overview",
+        loadTree: ({ page, runtime }) => import("./trees/phi-default-accounting-page-tree")
+            .then((module) => module.buildPhiDefaultAccountingPageTree({ page, runtime })),
+    },
+];

package/plugins/runtime-modules/accounting/server.d.ts

@@ -1,5 +1,2 @@
-/**
- * The unselectable base module of its Area. Shells and routes come from the shared Area-base preset
- * list and are filtered by owner, so each base module states its own half of it.
- */
+/** The unselectable base module of its Area. Its shell and Pages are its own (`./presets`). */
 export declare const PHI_ACCOUNTING_RUNTIME_MODULE_SERVER_AREA_CONTRIBUTION: import("../area-contributions").PhiRuntimeModuleServerAreaContribution;

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

@@ -1,18 +1,15 @@
-import { PHI_AREA_BASE_RUNTIME_MODULE_AREA_SHELLS, PHI_AREA_BASE_RUNTIME_MODULE_ROUTES, } from "../area-base-presets";
+import { PHI_ACCOUNTING_RUNTIME_MODULE_AREA_SHELLS, PHI_ACCOUNTING_RUNTIME_MODULE_ROUTES, } from "./presets";
 import { definePhiRuntimeModuleServerAreaContribution } from "../area-contributions";
 import { PHI_ACCOUNTING_RUNTIME_MODULE_DEFINITION } from "../accounting/definition";
-/**
- * The unselectable base module of its Area. Shells and routes come from the shared Area-base preset
- * list and are filtered by owner, so each base module states its own half of it.
- */
+/** The unselectable base module of its Area. Its shell and Pages are its own (`./presets`). */
 export const PHI_ACCOUNTING_RUNTIME_MODULE_SERVER_AREA_CONTRIBUTION = definePhiRuntimeModuleServerAreaContribution({
     moduleId: PHI_ACCOUNTING_RUNTIME_MODULE_DEFINITION.moduleId,
     catalogEntry: {
         definition: PHI_ACCOUNTING_RUNTIME_MODULE_DEFINITION,
         widgets: [],
         layouts: [],
-        areaShells: PHI_AREA_BASE_RUNTIME_MODULE_AREA_SHELLS.filter((descriptor) => descriptor.ownerModuleId === PHI_ACCOUNTING_RUNTIME_MODULE_DEFINITION.moduleId),
-        routes: PHI_AREA_BASE_RUNTIME_MODULE_ROUTES.filter((descriptor) => descriptor.ownerModuleId === PHI_ACCOUNTING_RUNTIME_MODULE_DEFINITION.moduleId),
+        areaShells: PHI_ACCOUNTING_RUNTIME_MODULE_AREA_SHELLS,
+        routes: PHI_ACCOUNTING_RUNTIME_MODULE_ROUTES,
         load: () => import("./module").then((module) => module.PHI_ACCOUNTING_RUNTIME_MODULE),
     },
 });

package/plugins/runtime-modules/app/presets.d.ts

@@ -0,0 +1,18 @@
+import type { PhiCmsDescriptorBuildContext, PhiCmsRoutePresetDescriptor } from "../../../types/cms-module-descriptors";
+export declare const PHI_APP_RUNTIME_MODULE_AREA_SHELLS: {
+    ownerModuleId: "@phis/ui/modules/app";
+    presetKey: string;
+    shellPresetVersion: number;
+    area: "app";
+    loadTree: ({ page, runtime }: PhiCmsDescriptorBuildContext) => Promise<{
+        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[];
+        controllerSettings: import("../../../types/cms").PhiCmsTreeControllerSettings;
+        page: import("../../../types").PhiCmsPageNode;
+    }>;
+}[];
+export declare const PHI_APP_RUNTIME_MODULE_ROUTES: PhiCmsRoutePresetDescriptor[];

package/plugins/runtime-modules/app/presets.js

@@ -0,0 +1,67 @@
+import { PHI_BASE_PAGE_LAYOUT_VERSION } from "../../../components/regions/presets/phi-base-page-layout";
+import { buildPhiAreaRootRoutePresetDescriptor } from "../area-root-route";
+import { PHI_APP_RUNTIME_MODULE_ID } from "./ids";
+/* What the App base Module brings: its Area shell, the Area root and the profile Page. */
+export const PHI_APP_RUNTIME_MODULE_AREA_SHELLS = [
+    {
+        ownerModuleId: PHI_APP_RUNTIME_MODULE_ID,
+        presetKey: "app-area-preset",
+        shellPresetVersion: 1,
+        area: "app",
+        /*
+         * The Site shell with a left sider added, rather than a shell of its own.
+         *
+         * App's header and footer are Public's -- one Brand, one account trigger, one description of both.
+         * What App has that Public does not is somewhere for the Modules a signed-in person works with,
+         * and that is the whole of the overlay. Nothing is omitted from the base, so the two trees cannot
+         * disagree about a Region: composition refuses a Region type stated twice.
+         */
+        loadTree: async ({ page, runtime }) => {
+            const [{ buildPhiDefaultSiteAreaPresetTree }, { buildPhiDefaultAppAreaPresetTree }, { mergePhiCmsShellTrees },] = await Promise.all([
+                import("../phi-default-site-area-preset-tree"),
+                import("./trees/phi-default-app-area-preset-tree"),
+                import("../shell-tree-composition"),
+            ]);
+            const [base, overlay] = await Promise.all([
+                buildPhiDefaultSiteAreaPresetTree({
+                    page,
+                    runtime,
+                    presetKey: "app-area-preset",
+                    ownerModuleId: PHI_APP_RUNTIME_MODULE_ID,
+                    runtimeModuleArea: "app",
+                }),
+                buildPhiDefaultAppAreaPresetTree({ page, runtime }),
+            ]);
+            return mergePhiCmsShellTrees(base, overlay);
+        },
+    },
+];
+export const PHI_APP_RUNTIME_MODULE_ROUTES = [
+    buildPhiAreaRootRoutePresetDescriptor({
+        ownerModuleId: PHI_APP_RUNTIME_MODULE_ID,
+        area: "app",
+        title: "App",
+    }),
+    /*
+     * What a person has settled about their own account: their name, the language they read in.
+     *
+     * It sat with the Auth Module, which owned the route while Core owned every Widget on it. Nothing
+     * about a name or a language depends on how somebody signs in -- a Site that switches to a
+     * directory, or switches Auth off while sessions keep working, would have lost the Page that says
+     * what they are called. AUTHENTICATION.md section 5 already said so: profile administration does
+     * not become Auth's merely by appearing in its menu.
+     *
+     * The Area's own Settings child, so it is declared here rather than injected -- SETTINGS.md section
+     * 5, the same standing Admin and Builder give their General page.
+     */
+    {
+        ownerModuleId: PHI_APP_RUNTIME_MODULE_ID,
+        presetKey: "app-profile-page",
+        presetVersion: 1 + PHI_BASE_PAGE_LAYOUT_VERSION,
+        area: "app",
+        title: "Profile",
+        path: "/settings/profile",
+        loadTree: ({ page, runtime }) => import("./trees/phi-default-app-profile-page-tree")
+            .then((module) => module.buildPhiDefaultAppProfilePageTree({ page, runtime })),
+    },
+];

package/plugins/runtime-modules/app/server.d.ts

@@ -1,5 +1,2 @@
-/**
- * The unselectable base module of its Area. Shells and routes come from the shared Area-base preset
- * list and are filtered by owner, so each base module states its own half of it.
- */
+/** The unselectable base module of its Area. Its shell and Pages are its own (`./presets`). */
 export declare const PHI_APP_RUNTIME_MODULE_SERVER_AREA_CONTRIBUTION: import("../area-contributions").PhiRuntimeModuleServerAreaContribution;

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

@@ -1,11 +1,8 @@
-import { PHI_AREA_BASE_RUNTIME_MODULE_AREA_SHELLS, PHI_AREA_BASE_RUNTIME_MODULE_ROUTES, } from "../area-base-presets";
+import { PHI_APP_RUNTIME_MODULE_AREA_SHELLS, PHI_APP_RUNTIME_MODULE_ROUTES, } from "./presets";
 import { definePhiRuntimeModuleServerAreaContribution } from "../area-contributions";
 import { PHI_APP_RUNTIME_MODULE_DEFINITION } from "../app/definition";
 import { PHI_APP_RUNTIME_MODULE_FORMS } from "./forms";
-/**
- * The unselectable base module of its Area. Shells and routes come from the shared Area-base preset
- * list and are filtered by owner, so each base module states its own half of it.
- */
+/** The unselectable base module of its Area. Its shell and Pages are its own (`./presets`). */
 export const PHI_APP_RUNTIME_MODULE_SERVER_AREA_CONTRIBUTION = definePhiRuntimeModuleServerAreaContribution({
     moduleId: PHI_APP_RUNTIME_MODULE_DEFINITION.moduleId,
     catalogEntry: {
@@ -13,8 +10,8 @@ export const PHI_APP_RUNTIME_MODULE_SERVER_AREA_CONTRIBUTION = definePhiRuntimeM
         widgets: [],
         forms: PHI_APP_RUNTIME_MODULE_FORMS,
         layouts: [],
-        areaShells: PHI_AREA_BASE_RUNTIME_MODULE_AREA_SHELLS.filter((descriptor) => descriptor.ownerModuleId === PHI_APP_RUNTIME_MODULE_DEFINITION.moduleId),
-        routes: PHI_AREA_BASE_RUNTIME_MODULE_ROUTES.filter((descriptor) => descriptor.ownerModuleId === PHI_APP_RUNTIME_MODULE_DEFINITION.moduleId),
+        areaShells: PHI_APP_RUNTIME_MODULE_AREA_SHELLS,
+        routes: PHI_APP_RUNTIME_MODULE_ROUTES,
         load: () => import("./module").then((module) => module.PHI_APP_RUNTIME_MODULE),
     },
 });

package/plugins/runtime-modules/asset/controller/runtime.js

@@ -271,11 +271,11 @@ export function usePhiAssetRuntimeController({ address, mountScope, config, }) {
             value: {
                 page: state.page,
                 pageSize: state.pageSize,
-                total: state.pagination?.total ?? state.assets.length,
+                total: state.pagination?.total ?? 0,
             },
             receiver: "broadcast",
             timestamp: Date.now(),
         });
-    }, [emitAssetSignal, mountScope, state.assets.length, state.page, state.pageSize, state.pagination?.total]);
+    }, [emitAssetSignal, mountScope, state.page, state.pageSize, state.pagination?.total]);
     return state;
 }

package/plugins/runtime-modules/asset/services/collection.js

@@ -62,10 +62,18 @@ async function queryMediaCollection(request) {
             signal: request.signal,
         });
         const payload = await readPhiImagePreviewResponse(response);
+        /*
+         * The server counts the listing on every read (`pagination.total`), and the paging below is drawn
+         * from it. Without it the count is unknown, which the assets of one page would only pretend to answer.
+         */
+        const total = payload.pagination?.total;
+        if (typeof total !== "number" || !Number.isFinite(total) || total < 0) {
+            throw new Error("The media listing answered no total.");
+        }
         return {
             resourceKey: request.resourceKey,
             items: payload.assets.map((asset) => ({ ...asset })),
-            total: payload.pagination?.total ?? payload.assets.length,
+            total,
             loading: false,
             error: null,
             meta: {

package/plugins/runtime-modules/asset/services/options.js

@@ -2,6 +2,7 @@
 import { isPhiRecord } from "../../../../helpers/is-record";
 import { createPhiControlOptionsProviderClient, } from "../../../../components/controls/phi-options-provider";
 import { PHI_ASSET_RUNTIME_DATA_PROVIDER_KEYS } from "../ids";
+import { readPhiMediaFolders } from "../../../../components/media/phi-image-preview-data";
 import { PHI_ASSET_CONTROLLER_STORE_KEY } from "../../../../components/media/asset-controller-signals";
 import { phiImagePreviewStore } from "../../../../components/media/phi-image-preview-store";
 import { buildPhiMediaFolderCascaderOptions, buildPhiMediaFolderNamesById, buildPhiMediaFolderValueById, } from "../../../../components/media/media-folder-options";
@@ -59,8 +60,7 @@ async function loadFolders() {
     const payload = await response.json().catch(() => null);
     if (!response.ok)
         throw new Error("Failed to load the Site's media folders.");
-    const folders = isPhiRecord(payload) && Array.isArray(payload.folders) ? payload.folders : [];
-    return folders.filter(isPhiRecord);
+    return readPhiMediaFolders(isPhiRecord(payload) ? payload.folders : undefined, "The media folders route");
 }
 export const PhiMediaFolderChoicesOptionsProviderClient = createPhiControlOptionsProviderClient({
     key: PHI_ASSET_RUNTIME_DATA_PROVIDER_KEYS.mediaFolderChoices,

package/plugins/runtime-modules/builder/area-settings-answer.js

@@ -1,3 +1,4 @@
+import { PHI_WORKSPACE_CATALOG_SCOPE } from "../../../components/workspace/catalog-store";
 import { PHI_AREA_META_PUBLIC_DEFAULTS, } from "../../../helpers/cms-area-config";
 import { isPhiRecord } from "../../../helpers/is-record";
 import { builderWorkspaceStore, readPhiBuilderEffectiveAreaMeta, readPhiBuilderEffectiveAreaRootRoute, restorePhiDeveloperBuilderAreaMeta, setPhiDeveloperBuilderAreaRootRoute, } from "./developer-workspace-store";
@@ -54,7 +55,7 @@ function isSamePhiBuilderAreaAnswer(left, right) {
  * unsaved. `rootRoute` is `undefined` when the dialog did not ask it.
  */
 export function applyPhiBuilderAreaSettingsAnswer({ area, historyContext, rootRoute, meta, }) {
-    const current = builderWorkspaceStore.getSnapshot("public");
+    const current = builderWorkspaceStore.getSnapshot(PHI_WORKSPACE_CATALOG_SCOPE);
     const before = [];
     const after = [];
     if (rootRoute !== undefined && !isSamePhiBuilderAreaAnswer(readPhiBuilderEffectiveAreaRootRoute(current, area), rootRoute)) {

package/plugins/runtime-modules/builder/authoring-canvas.js

@@ -13,12 +13,12 @@ import { getPhiBuilderNavigationDraftSnapshot } from "./navigation-store";
  * learn which Area they are being edited in.
  */
 export function usePhiBuilderAuthoringCanvas() {
-    const area = usePhiDeveloperBuilderStateValue("public", (state) => state.area);
-    const catalogHydrated = usePhiDeveloperBuilderStateValue("public", (state) => state.catalogHydrated);
-    const navigationSurfaces = usePhiDeveloperBuilderStateValue("public", (state) => state.navigationSurfacesByArea[state.area] ?? null);
-    const modulePresetPagesByArea = usePhiDeveloperBuilderStateValue("public", (state) => state.modulePresetPagesByArea);
-    const customPages = usePhiDeveloperBuilderStateValue("public", (state) => state.customPages);
-    const persistedPageCatalogByArea = usePhiDeveloperBuilderStateValue("public", (state) => state.persistedPageCatalogByArea);
+    const area = usePhiDeveloperBuilderStateValue((state) => state.area);
+    const catalogHydrated = usePhiDeveloperBuilderStateValue((state) => state.catalogHydrated);
+    const navigationSurfaces = usePhiDeveloperBuilderStateValue((state) => state.navigationSurfacesByArea[state.area] ?? null);
+    const modulePresetPagesByArea = usePhiDeveloperBuilderStateValue((state) => state.modulePresetPagesByArea);
+    const customPages = usePhiDeveloperBuilderStateValue((state) => state.customPages);
+    const persistedPageCatalogByArea = usePhiDeveloperBuilderStateValue((state) => state.persistedPageCatalogByArea);
     return useMemo(() => ({
         area,
         catalogHydrated,