@phis/ui 0.2.1 → 0.3.0

package/controls.d.ts

@@ -43,6 +43,10 @@ export { PhiPaddingControl } from "./components/controls/phi-padding-control";
 export type { PhiPaddingControlProps } from "./components/controls/phi-padding-control";
 export { PhiShadowControl } from "./components/controls/phi-shadow-control";
 export type { PhiShadowControlProps } from "./components/controls/phi-shadow-control";
+export { PhiSurfaceControl } from "./components/controls/phi-surface-control";
+export type { PhiSurfaceControlLabels, PhiSurfaceControlProps } from "./components/controls/phi-surface-control";
+export { PhiImageControl } from "./components/controls/phi-image-control";
+export type { PhiImageControlProps, PhiImageControlSource } from "./components/controls/phi-image-control";
 export { PhiGeometryControl } from "./components/controls/phi-geometry-control";
 export type { PhiGeometryControlProps } from "./components/controls/phi-geometry-control";
 export { PhiSliderControl } from "./components/controls/phi-slider-control";
@@ -88,10 +92,22 @@ export { PhiCardControl } from "./components/controls/phi-card-control";
 export type { PhiCardControlProps } from "./components/controls/phi-card-control";
 export { PhiEmptyControl } from "./components/controls/phi-empty-control";
 export type { PhiEmptyControlProps } from "./components/controls/phi-empty-control";
+export { PhiFlexControl } from "./components/controls/phi-flex-control";
+export type { PhiFlexControlProps } from "./components/controls/phi-flex-control";
+export { PhiSkeletonControl } from "./components/controls/phi-skeleton-control";
+export type { PhiSkeletonControlProps } from "./components/controls/phi-skeleton-control";
+export { PhiTypographyControl } from "./components/controls/phi-typography-control";
+export type { PhiTypographyControlProps } from "./components/controls/phi-typography-control";
 export { PHI_CONFIRM_PLACEMENTS, PhiConfirmControl, } from "./components/controls/phi-confirm-control";
 export type { PhiConfirmControlProps, PhiConfirmPlacement, } from "./components/controls/phi-confirm-control";
 export { PhiToolbarControl } from "./components/controls/phi-toolbar-control";
 export type { PhiToolbarControlItem, PhiToolbarControlProps, } from "./components/controls/phi-toolbar-control";
+export { PhiFloatButtonControl } from "./components/controls/phi-float-button-control";
+export type { PhiFloatButtonControlGroup, PhiFloatButtonControlPlacement, PhiFloatButtonControlProps, } from "./components/controls/phi-float-button-control";
+export { PhiStepsControl } from "./components/controls/phi-steps-control";
+export type { PhiStepsControlItem, PhiStepsControlProps } from "./components/controls/phi-steps-control";
+export { PhiTimelineControl } from "./components/controls/phi-timeline-control";
+export type { PhiTimelineControlItem, PhiTimelineControlProps, } from "./components/controls/phi-timeline-control";
 export { PhiTableControl, readPhiTableControlValue } from "./components/controls/phi-table-control";
 export type { PhiTableControlColumn, PhiTableControlCellEditor, PhiTableControlPagination, PhiTableControlProps, PhiTableControlRowEditing, PhiTableControlRowMove, PhiTableControlRowReordering, PhiTableControlRowSelection, PhiTableControlTree, } from "./components/controls/phi-table-control";
 export { PhiTreeControl, PhiTreeActionButton } from "./components/controls/phi-tree-control";

package/controls.js

@@ -21,6 +21,8 @@ export { PhiBackgroundControl } from "./components/controls/phi-background-contr
 export { PhiBorderControl } from "./components/controls/phi-border-control";
 export { PhiPaddingControl } from "./components/controls/phi-padding-control";
 export { PhiShadowControl } from "./components/controls/phi-shadow-control";
+export { PhiSurfaceControl } from "./components/controls/phi-surface-control";
+export { PhiImageControl } from "./components/controls/phi-image-control";
 export { PhiGeometryControl } from "./components/controls/phi-geometry-control";
 export { PhiSliderControl } from "./components/controls/phi-slider-control";
 export { PhiRateControl } from "./components/controls/phi-rate-control";
@@ -58,8 +60,14 @@ export { PhiAlertControl } from "./components/controls/phi-alert-control";
  */
 export { PhiCardControl } from "./components/controls/phi-card-control";
 export { PhiEmptyControl } from "./components/controls/phi-empty-control";
+export { PhiFlexControl } from "./components/controls/phi-flex-control";
+export { PhiSkeletonControl } from "./components/controls/phi-skeleton-control";
+export { PhiTypographyControl } from "./components/controls/phi-typography-control";
 export { PHI_CONFIRM_PLACEMENTS, PhiConfirmControl, } from "./components/controls/phi-confirm-control";
 export { PhiToolbarControl } from "./components/controls/phi-toolbar-control";
+export { PhiFloatButtonControl } from "./components/controls/phi-float-button-control";
+export { PhiStepsControl } from "./components/controls/phi-steps-control";
+export { PhiTimelineControl } from "./components/controls/phi-timeline-control";
 export { PhiTableControl, readPhiTableControlValue } from "./components/controls/phi-table-control";
 export { PhiTreeControl, PhiTreeActionButton } from "./components/controls/phi-tree-control";
 export { PhiTreeSelectControl } from "./components/controls/phi-tree-select-control";

package/forms.d.ts

@@ -18,7 +18,7 @@ export { PHI_SHARED_FORM_IDS } from "./components/forms/shared-form-ids";
 export { flattenPhiFormLabels } from "./components/forms/form-labels";
 export { PHI_RUNTIME_FORM_CONTROLLER_DEFINITION, parsePhiRuntimeFormControllerConfig, } from "./components/forms/runtime-form-controller-definition";
 export { fetchFormRegistry, getResolvedFormDefinition, listResolvedFormDefinitions, } from "./gateway/form-registry";
-export { buildPhiFormSubmitDescriptor, buildPhiFormPreviewDescriptor, buildPhiFormPreviewDescriptorFromDefinition, resolvePhiFormSubmitTarget, } from "./gateway/form-submit";
+export { buildPhiFormSubmitRoute, buildPhiFormPreviewDescriptor, buildPhiFormPreviewDescriptorFromDefinition, resolvePhiFormSubmitTarget, } from "./gateway/form-submit";
 export { buildPhiDataSourceUrl, normalizePhiDataSourceCacheMode, normalizePhiDataSourceTags, } from "./gateway/data-source";
 export { buildPhiMutationUrl, normalizePhiMutationMethod, normalizePhiMutationResponseShape, normalizePhiMutationTransport, } from "./gateway/mutation";
 export type { PhiRuntimeModuleFormDefinition, PhiRuntimeModuleFormDefinitionInput, } from "./components/forms/form-registry";
@@ -32,6 +32,7 @@ export type { PhiRuntimeFormSubmitSignalValue, PhiRuntimeFormResultSignalValue,
 export type { PhiRuntimeFormClient, PhiRuntimeFormSubmitOptions, PhiRuntimeFormSubmitResult, } from "./components/forms/runtime-form-client";
 export type { PhiRuntimeFormFieldSignalValue, PhiRuntimeFormTouchedSignalValue, PhiRuntimeFormValiditySignalValue, PhiRuntimeFormValuesSignalValue, } from "./components/forms/runtime-form-state";
 export type { PhiFormRegistryRecord, GetResolvedFormDefinitionOptions, ListResolvedFormDefinitionsOptions, } from "./gateway/form-registry";
-export type { PhiFormSubmitCategory, PhiFormPreviewDescriptor, PhiFormSubmitDescriptor, PhiFormSubmitMethod, PhiFormSubmitTarget, PhiFormSubmitTransport, } from "./gateway/form-submit";
+export type { PhiFormPreviewDescriptor, PhiFormSubmitTarget, } from "./gateway/form-submit";
+export type { PhiFormSubmitCategory, PhiFormSubmitMethod, PhiFormSubmitRoute, PhiFormSubmitTransport, } from "./types/form-submit-route";
 export type { PhiDataLoadOptions, PhiDataQuery, PhiDataQueryValue, PhiDataResult, PhiDataSource, PhiDataSourceApiTransport, PhiDataSourceCache, PhiDataSourceCacheMode, PhiDataSourceRequestShape, PhiDataSourceResponseShape, } from "./gateway/data-source";
 export type { PhiMutation, PhiMutationFetchContext, PhiMutationLoadOptions, PhiMutationMethod, PhiMutationQuery, PhiMutationQueryValue, PhiMutationRequestShape, PhiMutationResponseShape, PhiMutationTransport, } from "./gateway/mutation";

package/forms.js

@@ -20,6 +20,6 @@ export { PHI_SHARED_FORM_IDS } from "./components/forms/shared-form-ids";
 export { flattenPhiFormLabels } from "./components/forms/form-labels";
 export { PHI_RUNTIME_FORM_CONTROLLER_DEFINITION, parsePhiRuntimeFormControllerConfig, } from "./components/forms/runtime-form-controller-definition";
 export { fetchFormRegistry, getResolvedFormDefinition, listResolvedFormDefinitions, } from "./gateway/form-registry";
-export { buildPhiFormSubmitDescriptor, buildPhiFormPreviewDescriptor, buildPhiFormPreviewDescriptorFromDefinition, resolvePhiFormSubmitTarget, } from "./gateway/form-submit";
+export { buildPhiFormSubmitRoute, buildPhiFormPreviewDescriptor, buildPhiFormPreviewDescriptorFromDefinition, resolvePhiFormSubmitTarget, } from "./gateway/form-submit";
 export { buildPhiDataSourceUrl, normalizePhiDataSourceCacheMode, normalizePhiDataSourceTags, } from "./gateway/data-source";
 export { buildPhiMutationUrl, normalizePhiMutationMethod, normalizePhiMutationResponseShape, normalizePhiMutationTransport, } from "./gateway/mutation";

package/gateway/auth-public-manifest.js

@@ -2,6 +2,8 @@ import "server-only";
 import { PHIS_SITE_KEY_HEADER } from "../constants/http-headers";
 import { isPhiRecord } from "../helpers/is-record";
 import { throwPhiCmsGatewayError } from "./errors";
+import { fetchPhiSiteApi } from "./site-api-request";
+import { readPhiSiteReadCache } from "./site-read-cache";
 function buildHeaders(options, userAgent, cookieHeader) {
     const headers = {
         Accept: "application/json",
@@ -29,21 +31,26 @@ function readManifest(value) {
  * first paint.
  */
 export async function fetchPhiPublicAuthManifest(options) {
-    if (!options.apiBaseUrl.trim()) {
-        throw new Error("Missing apiBaseUrl for fetchPhiPublicAuthManifest.");
-    }
-    if (!options.siteKey.trim()) {
-        throw new Error("Missing siteKey for fetchPhiPublicAuthManifest.");
+    /*
+     * Kept in the read cache outside development, like the Site config it sits beside: it is the same for
+     * every visitor, and a change to it moves the Site's read marker in Core (the auth config is one of
+     * the tables that does), which empties this cache in every process at the next config refresh.
+     */
+    if (process.env.NODE_ENV === "development") {
+        return loadPhiPublicAuthManifest(options);
     }
-    const response = await fetch(`${options.apiBaseUrl}/api/v1/auth/manifest`, {
-        method: "GET",
-        headers: buildHeaders(options, "phis-ui-auth-manifest/1.0"),
-        cache: "no-store",
-    });
-    if (!response.ok) {
-        throwPhiCmsGatewayError(`Auth manifest fetch failed (${response.status}).`, response.status);
-    }
-    const manifest = readManifest(await response.json().catch(() => null));
+    return readPhiSiteReadCache(`auth-manifest:${options.siteKey.trim().toLowerCase()}`, () => loadPhiPublicAuthManifest(options));
+}
+async function loadPhiPublicAuthManifest(options) {
+    const manifest = readManifest(await fetchPhiSiteApi({
+        context: "fetchPhiPublicAuthManifest",
+        apiBaseUrl: options.apiBaseUrl,
+        internalToken: options.internalToken,
+        siteKey: options.siteKey,
+        path: "/api/v1/auth/manifest",
+        failure: "Auth manifest fetch failed",
+        userAgent: "phis-ui-auth-manifest/1.0",
+    }));
     if (!manifest) {
         throw new Error("Missing auth manifest payload.");
     }

package/gateway/content-entries.d.ts

@@ -0,0 +1,57 @@
+import "server-only";
+import type { PhiContentEntryKind } from "../constants/content-entry-kinds";
+import type { PhiSiteContentEntry, PhiSiteContentEntryPage } from "../types/content-entries";
+type FetchPhiSiteContentEntryBase = {
+    kind: PhiContentEntryKind;
+    apiBaseUrl: string;
+    internalToken: string;
+    siteKey: string;
+    /** The language the page is being drawn in; Core resolves each entry's text for it. */
+    locale: string;
+};
+export type FetchPhiSiteContentEntriesOptions = FetchPhiSiteContentEntryBase & {
+    /**
+     * How many entries the caller will show, newest first. Core cuts the list there before it translates,
+     * so a Site with years of entries does not pay for translating all of them to draw ten.
+     */
+    limit: number;
+    /**
+     * Which categories, by id, and `none` for the entries filed under no category; absent or empty is every
+     * entry. Core filters before it cuts at `limit`, so a list of ten still shows ten.
+     */
+    categories?: readonly string[];
+};
+/**
+ * One kind's published entries, read while the page is being rendered.
+ *
+ * A gateway read rather than a browser one, which the endpoint enforces anyway: it wants the internal
+ * token, which a browser must never hold. It also means an entry that has expired is absent from the HTML
+ * instead of appearing and then vanishing.
+ *
+ * `no-store` is right here despite the page being cached: on a Public page this fetch runs inside the
+ * static render, which is itself kept and renewed at most once a minute
+ * ([STATIC_RENDERING.md](../STATIC_RENDERING.md)). A second cache underneath it would only add a second
+ * age to reason about.
+ */
+export declare function fetchPhiSiteContentEntries(options: FetchPhiSiteContentEntriesOptions): Promise<PhiSiteContentEntry[]>;
+type FetchPhiSiteContentEntryPageOptions = FetchPhiSiteContentEntryBase & {
+    slug: string;
+    /** How many related entries to answer beside it; absent asks for none. Core allows 1 to 12. */
+    relatedLimit?: number;
+};
+/**
+ * One published entry by its address and, where asked, the entries closest to it -- everything a detail
+ * Page shows, in one question; `null` where the kind has none answering there: never published, expired,
+ * or a slug nobody wrote. The detail route answers 404 on `null`.
+ *
+ * Once per request for the same question (`definePhiRequestMemo`): the detail route's tree reads it for
+ * the Page's title and status, and the header, the body and the related list read it again while the page
+ * is drawn. All of them ask with the same options, so Core is asked once.
+ */
+export declare const fetchPhiSiteContentEntryPage: (options: FetchPhiSiteContentEntryPageOptions) => Promise<PhiSiteContentEntryPage | null>;
+/**
+ * How many relatives a detail Page asks for. One number for the whole Page, because every part asks the
+ * same question and a part asking for four while another asks for three would be two questions to Core.
+ */
+export declare const PHI_CONTENT_ENTRY_RELATED_LIMIT = 3;
+export {};

package/gateway/content-entries.js

@@ -0,0 +1,141 @@
+import "server-only";
+import { isPhiRecord } from "../helpers/is-record";
+import { readPhiLinkTarget } from "../types/references";
+import { definePhiRequestMemo } from "../server-helpers/request-memo";
+import { fetchPhiSiteApi } from "./site-api-request";
+function readString(value) {
+    return typeof value === "string" ? value : "";
+}
+function readTerm(value) {
+    if (!isPhiRecord(value))
+        return null;
+    const slug = readString(value.slug).trim();
+    const label = readString(value.label).trim();
+    return slug && label ? { slug, label } : null;
+}
+function readAuthor(value) {
+    if (!isPhiRecord(value))
+        return null;
+    const name = readString(value.name).trim();
+    if (!name)
+        return null;
+    const url = isPhiRecord(value.avatar) ? readString(value.avatar.url).trim() : "";
+    return { name, avatar: url ? { url } : null };
+}
+function readContentEntry(value) {
+    if (!isPhiRecord(value)) {
+        return null;
+    }
+    const title = readString(value.title).trim();
+    const created = readString(value.created).trim();
+    // An entry without a title or a date has nothing to show and nothing to sort by. Dropped rather than
+    // rendered as a gap, and dropped alone rather than taking the rest of the list with it.
+    if (!title || !created) {
+        return null;
+    }
+    return {
+        id: readString(value.id) || readString(value.slug),
+        slug: readString(value.slug),
+        created,
+        outdated: readString(value.outdated) || null,
+        title,
+        subtitle: readString(value.subtitle),
+        content: readString(value.content),
+        link: readPhiLinkTarget(value.link),
+        category: readTerm(value.category),
+        tags: Array.isArray(value.tags)
+            ? value.tags.map(readTerm).filter((tag) => tag !== null)
+            : [],
+        author: readAuthor(value.author),
+        sourceLocale: readString(value.sourceLocale).trim() || null,
+        // Absent means yes, which is the default everywhere this switch appears.
+        translate: value.translate !== false,
+    };
+}
+async function fetchEntries(options, searchParams) {
+    const payload = await fetchPhiSiteApi({
+        context: "fetchPhiSiteContentEntries",
+        apiBaseUrl: options.apiBaseUrl,
+        internalToken: options.internalToken,
+        siteKey: options.siteKey,
+        path: `/api/v1/entries/${options.kind}`,
+        searchParams,
+        locale: options.locale,
+        failure: `Entries fetch failed (${options.kind})`,
+        userAgent: "phis-ui-entries/1.0",
+    });
+    if (!isPhiRecord(payload) || !Array.isArray(payload.entries)) {
+        throw new Error("Entries answered without a list.");
+    }
+    return payload.entries
+        .map((entry) => readContentEntry(entry))
+        .filter((entry) => entry !== null);
+}
+/**
+ * One kind's published entries, read while the page is being rendered.
+ *
+ * A gateway read rather than a browser one, which the endpoint enforces anyway: it wants the internal
+ * token, which a browser must never hold. It also means an entry that has expired is absent from the HTML
+ * instead of appearing and then vanishing.
+ *
+ * `no-store` is right here despite the page being cached: on a Public page this fetch runs inside the
+ * static render, which is itself kept and renewed at most once a minute
+ * ([STATIC_RENDERING.md](../STATIC_RENDERING.md)). A second cache underneath it would only add a second
+ * age to reason about.
+ */
+export async function fetchPhiSiteContentEntries(options) {
+    if (!Number.isInteger(options.limit) || options.limit <= 0) {
+        throw new Error("fetchPhiSiteContentEntries needs a positive integer limit.");
+    }
+    return fetchEntries(options, {
+        limit: String(options.limit),
+        ...(options.categories?.length ? { categories: options.categories.join(",") } : {}),
+    });
+}
+/**
+ * One published entry by its address and, where asked, the entries closest to it -- everything a detail
+ * Page shows, in one question; `null` where the kind has none answering there: never published, expired,
+ * or a slug nobody wrote. The detail route answers 404 on `null`.
+ *
+ * Once per request for the same question (`definePhiRequestMemo`): the detail route's tree reads it for
+ * the Page's title and status, and the header, the body and the related list read it again while the page
+ * is drawn. All of them ask with the same options, so Core is asked once.
+ */
+export const fetchPhiSiteContentEntryPage = definePhiRequestMemo(async (options) => {
+    const slug = options.slug.trim();
+    if (!slug)
+        return null;
+    const payload = await fetchPhiSiteApi({
+        context: "fetchPhiSiteContentEntryPage",
+        apiBaseUrl: options.apiBaseUrl,
+        internalToken: options.internalToken,
+        siteKey: options.siteKey,
+        path: `/api/v1/entries/${options.kind}/${encodeURIComponent(slug)}`,
+        searchParams: options.relatedLimit
+            ? { include: "related", relatedLimit: String(options.relatedLimit) }
+            : {},
+        locale: options.locale,
+        failure: `Entry fetch failed (${options.kind})`,
+        userAgent: "phis-ui-entries/1.0",
+        notFoundIsNull: true,
+    });
+    if (payload === null)
+        return null;
+    if (!isPhiRecord(payload)) {
+        throw new Error("The entry answered without a body.");
+    }
+    const entry = readContentEntry(payload.entry);
+    if (!entry)
+        return null;
+    return {
+        entry,
+        related: Array.isArray(payload.related)
+            ? payload.related.map(readContentEntry).filter((item) => item !== null)
+            : null,
+    };
+});
+/**
+ * How many relatives a detail Page asks for. One number for the whole Page, because every part asks the
+ * same question and a part asking for four while another asks for three would be two questions to Core.
+ */
+export const PHI_CONTENT_ENTRY_RELATED_LIMIT = 3;

package/gateway/dashboard-cards-route.js

@@ -1,3 +1,4 @@
+import { jsonResponse, readPhiInternalRequestPath, splitPhiRequestPath } from "./route-handler-helpers";
 import "server-only";
 import { isPhiCmsAreaKey, resolvePhiCmsAreaMask, } from "../constants/cms-areas";
 import { canPhiViewerAccess } from "../types/access";
@@ -9,38 +10,8 @@ import { getPhiExactSiteArea } from "../server-helpers/cms";
 import { resolveCmsRootRoute } from "../server-helpers/cms-route";
 import { buildPhiBlockRuntime, loadPhiSiteRequestContext, } from "../server-helpers/runtime";
 import { runWithPhiRequestRuntime } from "../server-helpers/request-runtime";
-import { isPhiDashboardCardId, } from "../types/dashboard-cards";
-function json(payload, status = 200) {
-    return Response.json(payload, {
-        status,
-        headers: { "cache-control": "no-store" },
-    });
-}
-/** An internal path, and only one: a card request never leaves this Site. */
-function readInternalPath(value, requestUrl) {
-    const normalized = value?.trim() ?? "";
-    if (!normalized.startsWith("/") || normalized.startsWith("//")) {
-        return null;
-    }
-    try {
-        return new URL(normalized, requestUrl).pathname;
-    }
-    catch {
-        return null;
-    }
-}
-function splitTargetPath(pathname) {
-    const segments = pathname.split("/").filter(Boolean).map((segment) => {
-        try {
-            return decodeURIComponent(segment);
-        }
-        catch {
-            return segment;
-        }
-    });
-    const [root, ...path] = segments;
-    return root ? { root, path } : null;
-}
+import { logRuntimeEvent } from "../net/log";
+import { createPhiDashboardCardId, isPhiDashboardCardId, } from "../types/dashboard-cards";
 /**
  * The path a card's target resolves to, or none.
  *
@@ -120,27 +91,60 @@ async function resolveDashboardCardScope({ bridge, area, locale, path, cookieHea
     return { activeModuleIds, routeTable, cardContext, scopeRuntime };
 }
 /**
- * The card providers of the Modules this Area actually runs.
+ * The card providers of the Modules this Area actually runs, and the Modules whose provider did not load.
  *
  * Keyed by Module so a payload request can find the one that owns a card without asking the other
  * eleven, and loaded here rather than at module scope because a Site whose Dashboard nobody opens
- * should never pull a provider into its graph.
+ * should never pull a provider into its graph. A contribution that fails to load is kept by name: the
+ * list answers for it with one error card (`buildContributorFailureRow`) rather than with silence.
  */
-async function loadActiveCardProviders(bridge, activeModuleIds) {
-    const loaded = await Promise.all([...activeModuleIds].map(async (moduleId) => {
+async function loadActiveCardProviders(bridge, area, activeModuleIds) {
+    const providers = [];
+    const failures = new Map();
+    await Promise.all([...activeModuleIds].map(async (moduleId) => {
         const contribution = bridge.runtimeModuleCatalog.get(moduleId)?.dashboardCards;
-        if (!contribution) {
-            return null;
+        // An Area the contribution does not name never loads its provider (`dashboardCards.areas`).
+        if (!contribution || !contribution.areas.includes(area)) {
+            return;
         }
         try {
-            return [moduleId, await contribution.load()];
+            providers.push([moduleId, await contribution.load()]);
         }
         catch (error) {
-            console.warn("[phi-dashboard-cards] Card provider failed to load.", { moduleId, error });
-            return null;
+            failures.set(moduleId, describeError(error, "The card provider could not be loaded."));
+            logRuntimeEvent("warn", "dashboard.cards.provider_load_failed", {
+                message: "Card provider failed to load.",
+                pluginKey: moduleId,
+                error,
+            });
         }
     }));
-    return loaded.filter((entry) => entry !== null);
+    return { providers, failures };
+}
+function describeError(error, fallback) {
+    return error instanceof Error && error.message ? error.message : fallback;
+}
+/**
+ * The one row a Module gets when it could not say which cards it has.
+ *
+ * A contributor whose provider did not load, or whose list threw, used to leave nothing behind -- and a
+ * Dashboard with a gap where a Module's cards should be reads as "this Module has no cards", which is a
+ * different statement from "this Module is broken". The row is in the Module's own namespace, carries
+ * its first payload already, and that payload is the error, so the card View draws it the way it draws
+ * any card whose payload failed (DASHBOARD.md, "A failure is one card").
+ */
+function buildContributorFailureRow(moduleId, message) {
+    const cardId = createPhiDashboardCardId(moduleId, "unavailable");
+    return {
+        cardId,
+        form: "stat",
+        title: moduleId,
+        payload: {
+            cardId,
+            error: message,
+            resolvedAt: new Date().toISOString(),
+        },
+    };
 }
 /**
  * A card belongs to the Module that offered it, and says so in its own id.
@@ -153,19 +157,45 @@ async function loadActiveCardProviders(bridge, activeModuleIds) {
 function ownsCardId(moduleId, cardId) {
     return isPhiDashboardCardId(cardId) && cardId.startsWith(`${moduleId}/cards/`);
 }
+/**
+ * One card's payload, from the Module that owns it.
+ *
+ * A payload that throws is this card saying so, not the request failing. The card is on screen
+ * already -- it was in the list -- so the honest answer is an error in it rather than a status the
+ * browser can only report as "unavailable". The same answer whether the card came with the list or was
+ * asked for on its own.
+ */
+async function resolveCardPayload(provider, cardId, cardContext, scopeRuntime) {
+    try {
+        return await runWithPhiRequestRuntime(scopeRuntime, () => provider.resolveCard(cardId, cardContext));
+    }
+    catch (error) {
+        logRuntimeEvent("warn", "dashboard.cards.payload_failed", {
+            message: "Card payload failed.",
+            targetType: "dashboard-card",
+            targetId: cardId,
+            error,
+        });
+        return {
+            cardId,
+            error: describeError(error, "This card could not be resolved."),
+            resolvedAt: new Date().toISOString(),
+        };
+    }
+}
 export function buildPhiDashboardCardsRouteHandler({ loadAreaBridge, }) {
     return async function GET(request) {
         const requestUrl = new URL(request.url);
         const area = requestUrl.searchParams.get("area")?.trim().toLowerCase() ?? "";
-        const pathname = readInternalPath(requestUrl.searchParams.get("path"), request.url);
+        const pathname = readPhiInternalRequestPath(requestUrl.searchParams.get("path"), request.url);
         const card = requestUrl.searchParams.get("card")?.trim() ?? "";
         if (!isPhiCmsAreaKey(area) || !pathname || (card && !isPhiDashboardCardId(card))) {
-            return json({ error: "bad_request" }, 400);
+            return jsonResponse({ error: "bad_request" }, 400);
         }
         const bridge = await loadAreaBridge(area);
-        const target = splitTargetPath(pathname);
+        const target = splitPhiRequestPath(pathname);
         if (!bridge?.runtime || !target) {
-            return json({ cards: [] });
+            return jsonResponse({ cards: [] });
         }
         try {
             /*
@@ -175,7 +205,7 @@ export function buildPhiDashboardCardsRouteHandler({ loadAreaBridge, }) {
              */
             const resolvedRoute = await resolveCmsRootRoute(target.root, target.path, bridge.runtime);
             if (resolvedRoute.area !== area) {
-                return json({ cards: [] });
+                return jsonResponse({ cards: [] });
             }
             const scope = await resolveDashboardCardScope({
                 bridge,
@@ -185,46 +215,32 @@ export function buildPhiDashboardCardsRouteHandler({ loadAreaBridge, }) {
                 cookieHeader: request.headers.get("cookie") ?? "",
             });
             if (!scope) {
-                return json({ cards: [] });
+                return jsonResponse({ cards: [] });
             }
             const { activeModuleIds, routeTable, cardContext, scopeRuntime } = scope;
-            const providers = await loadActiveCardProviders(bridge, activeModuleIds);
+            const { providers, failures } = await loadActiveCardProviders(bridge, area, activeModuleIds);
             if (card) {
                 const owner = providers.find(([moduleId]) => ownsCardId(moduleId, card));
                 if (!owner) {
-                    return json({ error: "unknown_card" }, 404);
-                }
-                /*
-                 * A payload that throws is this card saying so, not the request failing. The card is on screen
-                 * already -- it was in the list -- so the honest answer is an error in it rather than a status
-                 * the browser can only report as "unavailable".
-                 */
-                try {
-                    const payload = await runWithPhiRequestRuntime(scopeRuntime, () => owner[1].resolveCard(card, cardContext));
-                    return json(payload);
-                }
-                catch (error) {
-                    console.warn("[phi-dashboard-cards] Card payload failed.", { card, error });
-                    return json({
-                        cardId: card,
-                        error: error instanceof Error ? error.message : "This card could not be resolved.",
-                        resolvedAt: new Date().toISOString(),
-                    });
+                    return jsonResponse({ error: "unknown_card" }, 404);
                 }
+                return jsonResponse(await resolveCardPayload(owner[1], card, cardContext, scopeRuntime));
             }
             /*
              * Every Module is asked at once. One that throws loses its own cards and nobody else's, which is
-             * the list-half of the same promise the payloads keep: a broken contributor is a gap, not a blank
-             * Dashboard.
+             * the list-half of the same promise the payloads keep: a broken contributor is one error card in
+             * its own name, not a blank Dashboard and not a quiet gap.
              */
             const lists = await Promise.all(providers.map(async ([moduleId, provider]) => {
                 try {
                     const cards = await runWithPhiRequestRuntime(scopeRuntime, () => provider.listCards(cardContext));
                     return cards.filter((descriptor) => {
                         if (!ownsCardId(moduleId, descriptor.cardId)) {
-                            console.warn("[phi-dashboard-cards] Module offered a card it does not own.", {
-                                moduleId,
-                                cardId: descriptor.cardId,
+                            logRuntimeEvent("warn", "dashboard.cards.foreign_card_refused", {
+                                message: "Module offered a card it does not own.",
+                                pluginKey: moduleId,
+                                targetType: "dashboard-card",
+                                targetId: descriptor.cardId,
                             });
                             return false;
                         }
@@ -232,7 +248,12 @@ export function buildPhiDashboardCardsRouteHandler({ loadAreaBridge, }) {
                     });
                 }
                 catch (error) {
-                    console.warn("[phi-dashboard-cards] Card list failed.", { moduleId, error });
+                    logRuntimeEvent("warn", "dashboard.cards.list_failed", {
+                        message: "Card list failed.",
+                        pluginKey: moduleId,
+                        error,
+                    });
+                    failures.set(moduleId, describeError(error, "The card list could not be read."));
                     return [];
                 }
             }));
@@ -244,7 +265,7 @@ export function buildPhiDashboardCardsRouteHandler({ loadAreaBridge, }) {
              * is the one order that is stable across restarts and decided by nobody, and it holds until the
              * Site's own decisions arrive to replace it.
              */
-            const cards = lists
+            const rows = lists
                 .flat()
                 .sort((left, right) => left.cardId.localeCompare(right.cardId))
                 .map((descriptor) => ({
@@ -259,11 +280,34 @@ export function buildPhiDashboardCardsRouteHandler({ loadAreaBridge, }) {
                     return href ? { href } : {};
                 })(),
             }));
-            return json({ cards });
+            /*
+             * Each card's first payload, with the list and from the context this request already resolved.
+             *
+             * Asked for one by one from the browser, every card re-resolved the locale, the viewer, the
+             * capabilities and the Area for itself -- five cards, six request chains, some thirty Core calls
+             * for one Dashboard. Resolved here they share one context and run side by side; a payload that
+             * throws is still an error in its own row. The card endpoint above stays for what comes later,
+             * one card at a time: a refresh.
+             */
+            const cards = await Promise.all(rows.map(async (row) => {
+                const owner = providers.find(([moduleId]) => ownsCardId(moduleId, row.cardId));
+                return owner
+                    ? { ...row, payload: await resolveCardPayload(owner[1], row.cardId, cardContext, scopeRuntime) }
+                    : row;
+            }));
+            const failureRows = [...failures.entries()]
+                .sort(([left], [right]) => left.localeCompare(right))
+                .map(([moduleId, message]) => buildContributorFailureRow(moduleId, message));
+            return jsonResponse({ cards: [...cards, ...failureRows] });
         }
         catch (error) {
-            console.warn("[phi-dashboard-cards] Request failed.", { area, card, error });
-            return json({ error: "unavailable" }, 503);
+            logRuntimeEvent("warn", "dashboard.cards.request_failed", {
+                message: "Dashboard cards request failed.",
+                area,
+                error,
+                meta: { card },
+            });
+            return jsonResponse({ error: "unavailable" }, 503);
         }
     };
 }

package/gateway/errors.d.ts

@@ -3,6 +3,5 @@ export declare class PhiCmsGatewayError extends Error {
     readonly status: number;
     constructor(message: string, status: number);
 }
-export declare function isPhiCmsGatewayError(error: unknown): error is PhiCmsGatewayError;
 export declare function isPhiCmsGatewayAuthError(error: unknown): error is PhiCmsGatewayError;
 export declare function throwPhiCmsGatewayError(message: string, status: number): never;

package/gateway/errors.js

@@ -7,7 +7,7 @@ export class PhiCmsGatewayError extends Error {
         this.status = status;
     }
 }
-export function isPhiCmsGatewayError(error) {
+function isPhiCmsGatewayError(error) {
     return error instanceof PhiCmsGatewayError;
 }
 export function isPhiCmsGatewayAuthError(error) {