@antelopejs/dms 0.8.3 → 0.9.0

package/frontend-vue/layers/dms-layout/app/composables/page/useSiteLayout.ts

@@ -1,7 +1,11 @@
+import { router as inertiaRouter } from "@inertiajs/vue3";
 import { layoutUrlWithQuery } from "../../utils/pageQuery";
+import { onBeforeMount, toRaw } from "vue";
 import { withoutTrailingSlash } from "ufo";
 
 const STALE_THRESHOLD_MS = 300_000;
+const SITE_LAYOUT_ENDPOINT = "/dms/sitelayout";
+const RENDERED_SITE_LAYOUT_KEY = "dms-rendered-site-layout";
 const IN_FLIGHT_SITE_LAYOUT_KEY = "__dmsInFlightSiteLayout";
 const IN_FLIGHT_PAGE_LAYOUTS_KEY = "__dmsInFlightPageLayouts";
 
@@ -10,28 +14,35 @@ interface PageLayoutRequest {
   promise: Promise<PageLayout>;
 }
 
-function getCachedLayoutUrls(
-  previousSite: SiteLayout | undefined,
-  previousCache: Record<string, PageLayout>,
-  nextSite: SiteLayout,
-): string[] {
-  const urls = Object.entries(previousSite?.pages ?? {}).flatMap(
-    ([path, page]) => {
-      const nextPage = nextSite.pages[path];
-      return previousCache[page.layoutUrl] &&
-        nextPage?.layoutUrl &&
-        nextPage.hasAccess !== false
-        ? [nextPage.layoutUrl]
-        : [];
-    },
-  );
-  return [...new Set(urls)];
-}
-
 interface MatchRouteOptions {
   includeCategories: boolean;
 }
 
+// The categories a URL resolves against, by slug, per served layout: the
+// layout lists them by full id, and a `urlTransparent` one answers at its
+// parent's slug, so it is never a URL's target.
+const navigableCategoriesByLayout = new WeakMap<
+  SiteLayout,
+  Map<string, CategoryInfo>
+>();
+
+/** The category of the layout a URL resolves to, by its slug. */
+export function findNavigableCategory(
+  layout: SiteLayout,
+  slug: string,
+): CategoryInfo | undefined {
+  let bySlug = navigableCategoriesByLayout.get(layout);
+  if (!bySlug) {
+    bySlug = new Map(
+      Object.values(layout.categories)
+        .filter((category) => !category.urlTransparent)
+        .map((category) => [category.fullSlug, category]),
+    );
+    navigableCategoriesByLayout.set(layout, bySlug);
+  }
+  return bySlug.get(slug);
+}
+
 interface MatchRouteResult {
   pattern: string;
   metadata: PageInfo | CategoryInfo;
@@ -99,24 +110,84 @@ export function extractRouteParams(
   return buildParamBag(paramNames, match.slice(1));
 }
 
+/**
+ * A partial reload of the page on screen: the server sends the site layout
+ * and the page fresh, and they replace the browser's copies, the layout
+ * Inertia carries from page to page included. A failure rejects and leaves
+ * the page as it is: Inertia would otherwise show the error in its place.
+ */
+function reloadSiteLayoutAndPage(): Promise<void> {
+  return new Promise((resolve, reject) => {
+    let failure: unknown;
+    inertiaRouter.reload({
+      only: ["shared", "page"],
+      onHttpException: (response) => {
+        failure = new Error(`Site layout reload failed (${response.status})`);
+        return false;
+      },
+      onNetworkError: (error) => {
+        failure = error;
+        return false;
+      },
+      onFinish: () => (failure ? reject(failure) : resolve()),
+    });
+  });
+}
+
+interface SiteLayoutResponse {
+  siteLayout: SiteLayout;
+  siteLayoutTree: SiteLayoutTree;
+  quickActions: QuickActionsPayload;
+  modules: Record<string, ModuleWithAccess>;
+  isOwner: boolean;
+}
+
+/** The shared site layout, as a page's props or `/dms/sitelayout` set it. */
+function useSiteLayoutState() {
+  return {
+    siteLayout: useDmsState<SiteLayout | undefined>(
+      "dms-siteLayout",
+      () => undefined,
+    ),
+    siteLayoutTree: useDmsState<SiteLayoutTree | undefined>(
+      "dms-pageTree",
+      () => undefined,
+    ),
+    quickActions: useDmsState<QuickActionsPayload | undefined>(
+      "dms-quickActions",
+      () => undefined,
+    ),
+    modules: useDmsState<Record<string, ModuleWithAccess> | undefined>(
+      "dms-modules",
+      () => undefined,
+    ),
+    isOwner: useDmsState<boolean>("dms-isOwner", () => false),
+    lastRefreshTime: useDmsState<number>("dms-lastRefreshTime", () => 0),
+  };
+}
+
+function applySiteLayoutResponse(
+  state: ReturnType<typeof useSiteLayoutState>,
+  result: SiteLayoutResponse,
+): void {
+  state.siteLayout.value = result.siteLayout;
+  state.siteLayoutTree.value = result.siteLayoutTree;
+  state.quickActions.value = result.quickActions;
+  state.modules.value = result.modules;
+  state.isOwner.value = result.isOwner;
+  state.lastRefreshTime.value = Date.now();
+}
+
 export const useSiteLayout = () => {
-  const siteLayout = useDmsState<SiteLayout | undefined>(
-    "dms-siteLayout",
-    () => undefined,
-  );
-  const siteLayoutTree = useDmsState<SiteLayoutTree | undefined>(
-    "dms-pageTree",
-    () => undefined,
-  );
-  const quickActions = useDmsState<QuickActionsPayload | undefined>(
-    "dms-quickActions",
-    () => undefined,
-  );
-  const modules = useDmsState<Record<string, ModuleWithAccess> | undefined>(
-    "dms-modules",
-    () => undefined,
-  );
-  const isOwner = useDmsState<boolean>("dms-isOwner", () => false);
+  const state = useSiteLayoutState();
+  const {
+    siteLayout,
+    siteLayoutTree,
+    quickActions,
+    modules,
+    isOwner,
+    lastRefreshTime,
+  } = state;
 
   const isLoading = useDmsState<boolean>("dms-loading", () => false);
   const loadingError = useDmsState<string | null>("dms-error", () => null);
@@ -125,7 +196,6 @@ export const useSiteLayout = () => {
     "dms-pageLayouts",
     () => ({}),
   );
-  const lastRefreshTime = useDmsState<number>("dms-lastRefreshTime", () => 0);
 
   // Held on the DMS app rather than in a per-call ref: every caller of
   // useSiteLayout writes the same shared layout state, so they have to see the
@@ -148,79 +218,40 @@ export const useSiteLayout = () => {
     },
   };
 
-  interface SiteLayoutResponse {
-    siteLayout: SiteLayout;
-    siteLayoutTree: SiteLayoutTree;
-    quickActions: QuickActionsPayload;
-    modules: Record<string, ModuleWithAccess>;
-    isOwner: boolean;
-  }
-
-  const SITE_LAYOUT_ENDPOINT = "/dms/sitelayout";
   const SITE_LAYOUT_ERROR_MESSAGE = "Error loading siteLayout";
   const UNKNOWN_SITE_LAYOUT_ERROR = "Unknown error loading siteLayout";
   const HTTP_INTERNAL_ERROR = 500;
 
-  const applySiteLayoutResponse = (result: SiteLayoutResponse) => {
-    siteLayout.value = result.siteLayout;
-    siteLayoutTree.value = result.siteLayoutTree;
-    quickActions.value = result.quickActions;
-    modules.value = result.modules;
-    isOwner.value = result.isOwner;
-    lastRefreshTime.value = Date.now();
-  };
-
   const handleSiteLayoutError = (error: unknown) => {
     const errorMessage =
       error instanceof Error ? error.message : UNKNOWN_SITE_LAYOUT_ERROR;
     loadingError.value = errorMessage;
-    showError({
+    showDmsError({
       statusCode: HTTP_INTERNAL_ERROR,
       statusMessage: SITE_LAYOUT_ERROR_MESSAGE,
       message: errorMessage,
     });
   };
 
-  const requestSiteLayout = async (fatal: boolean): Promise<boolean> => {
+  const requestSiteLayout = async (): Promise<boolean> => {
     const initialLayout = siteLayout.value;
     const initialCache = pageLayouts.value;
+    // A layout another request committed meanwhile is newer than this one.
     const isCurrent = () =>
       siteLayout.value === initialLayout && pageLayouts.value === initialCache;
     const { $authFetch } = useAuthFetch();
     try {
       const result = await $authFetch<SiteLayoutResponse>(SITE_LAYOUT_ENDPOINT);
-      const nextCache: Record<string, PageLayout> = {};
-      // Initial page loads mutate this cache in place; identity guards cannot detect those additions.
-      while (isCurrent()) {
-        const urls = fatal
-          ? []
-          : getCachedLayoutUrls(
-              initialLayout,
-              initialCache,
-              result.siteLayout,
-            ).filter((url) => !nextCache[url]);
-        if (!urls.length) {
-          if (!fatal) pageLayouts.value = nextCache;
-          applySiteLayoutResponse(result);
-          return true;
-        }
-        const layouts = await Promise.all(
-          urls.map(
-            async (url) => [url, await $authFetch<PageLayout>(url)] as const,
-          ),
-        );
-        Object.assign(nextCache, Object.fromEntries(layouts));
-      }
+      if (isCurrent()) applySiteLayoutResponse(state, result);
       return true;
     } catch (error) {
-      // Failed background refreshes must not leave a fatal error for the next navigation.
-      if (fatal && isCurrent()) handleSiteLayoutError(error);
+      if (isCurrent()) handleSiteLayoutError(error);
       throw error;
     }
   };
 
-  const startSiteLayoutFetch = (fatal = true): Promise<boolean> => {
-    const started = requestSiteLayout(fatal).finally(() => {
+  const startSiteLayoutFetch = (): Promise<boolean> => {
+    const started = requestSiteLayout().finally(() => {
       isLoading.value = false;
       // A waiting refresh may already have started its replacement request.
       if (loadingPromise.value === started) loadingPromise.value = null;
@@ -246,12 +277,9 @@ export const useSiteLayout = () => {
     pageLayouts.value = {};
   }
 
-  // `fatal: false` keeps a failed refetch from swapping the app for the error
-  // page — for background resyncs (a realtime menu invalidation), where a
-  // network blip must not destroy a working session.
-  const refresh = async (options?: { fatal?: boolean }) => {
-    // Background refreshes stage page layouts before committing; identity refreshes clear immediately.
-    if (options?.fatal !== false) clearPageLayoutCaches();
+  // A background resync (a realtime menu invalidation) goes through `resync`.
+  const refresh = async () => {
+    clearPageLayoutCaches();
 
     // A fetch already in flight was started before whatever prompted this
     // call, so its answer cannot contain the change: joining it would report
@@ -270,11 +298,26 @@ export const useSiteLayout = () => {
     if (!loadingPromise.value) {
       isLoading.value = true;
       loadingError.value = null;
-      loadingPromise.value = startSiteLayoutFetch(options?.fatal ?? true);
+      loadingPromise.value = startSiteLayoutFetch();
     }
     await loadingPromise.value;
   };
 
+  /**
+   * Re-reads the menu and the page on screen from the server, for a change
+   * the backend announced (a realtime menu invalidation) or a switch of
+   * session. The pages prefetched on hover are dropped first: each carries
+   * the layout and the access of before. A navigation that starts meanwhile
+   * drops the reload's answer, and the page it opens still carries the layout
+   * the reload meant to replace: that page is reloaded in turn.
+   */
+  const resync = async (): Promise<void> => {
+    inertiaRouter.flushAll();
+    const path = window.location.pathname;
+    await reloadSiteLayoutAndPage();
+    if (window.location.pathname !== path) await reloadSiteLayoutAndPage();
+  };
+
   const refreshIfStale = async () => {
     const elapsed = Date.now() - lastRefreshTime.value;
     if (elapsed < STALE_THRESHOLD_MS) {
@@ -335,12 +378,11 @@ export const useSiteLayout = () => {
       };
     }
 
-    if (options.includeCategories && layout.categories[normalizedPath]) {
-      return {
-        pattern: normalizedPath,
-        metadata: layout.categories[normalizedPath],
-        params: {},
-      };
+    const category = options.includeCategories
+      ? findNavigableCategory(layout, normalizedPath)
+      : undefined;
+    if (category) {
+      return { pattern: normalizedPath, metadata: category, params: {} };
     }
 
     for (const [pattern, metadata] of Object.entries(layout.pages)) {
@@ -420,7 +462,7 @@ export const useSiteLayout = () => {
         return false;
       }
       clearPageLayoutCaches();
-      applySiteLayoutResponse(result);
+      applySiteLayoutResponse(state, result);
       return true;
     } catch {
       return false;
@@ -440,9 +482,48 @@ export const useSiteLayout = () => {
     loadSiteLayout,
     loadPageLayout,
     refresh,
+    resync,
     refreshIfStale,
     findMatchingRoute,
     findMatchingRouteOrCategory,
     probeAndCommitRoute,
   };
 };
+
+/**
+ * The site layout for the component rendering it (the sidebar), called in
+ * its setup. A page the backend describes brings it with its props; a page
+ * only a frontend layer knows (a custom page) does not, and this loads it
+ * with the page then: a server render waits for it before rendering the
+ * component, and hands it to the browser, which takes it over before the
+ * component mounts instead of asking again.
+ */
+export function useRenderedSiteLayout(): void {
+  const state = useSiteLayoutState();
+  if (state.siteLayout.value) return;
+  const layout = useSiteLayout();
+  // Through `loadSiteLayout`, which sets the state: a middleware loading it
+  // at the same time (the auth guard of a custom page) joins this request.
+  const { data } = useApiData<SiteLayoutResponse | null>(
+    RENDERED_SITE_LAYOUT_KEY,
+    async () => {
+      await layout.loadSiteLayout();
+      const { siteLayout, siteLayoutTree, quickActions, modules, isOwner } =
+        state;
+      // What the page payload carries: the plain values, not the state.
+      return siteLayout.value
+        ? {
+            siteLayout: toRaw(siteLayout.value),
+            siteLayoutTree: toRaw(siteLayoutTree.value!),
+            quickActions: toRaw(quickActions.value!),
+            modules: toRaw(modules.value!),
+            isOwner: isOwner.value,
+          }
+        : null;
+    },
+  );
+  onBeforeMount(() => {
+    if (data.value && !state.siteLayout.value)
+      applySiteLayoutResponse(state, data.value);
+  });
+}

package/frontend-vue/layers/dms-layout/app/composables/profile/useUserLanguage.ts

@@ -1,4 +1,5 @@
-const PROFILE_ENDPOINT = "/settings/user/profile";
+import { pageRoutePath } from "#dms-core/app/utils/pageRoutes";
+const PROFILE_ENDPOINT = pageRoutePath("/settings/user/profile");
 
 /**
  * Switches the interface language and stores it on the user's profile, then
@@ -9,7 +10,7 @@ const PROFILE_ENDPOINT = "/settings/user/profile";
 export function useUserLanguage() {
   const dmsApp = useDmsApp();
   const { $authFetch } = useAuthFetch();
-  const { user, fetch: refreshUser } = useUserSession();
+  const { user, fetch: refreshUser } = useDmsUserSession();
 
   async function changeLanguage(language: string): Promise<void> {
     await dmsApp.$i18n.setLocale(language);

package/frontend-vue/layers/dms-layout/app/custom-pages/modules.vue

@@ -36,7 +36,6 @@ import {
 import DmsSearchInput from "#dms-ui/app/build/components/form/SearchInput.vue";
 
 const SKELETON_PLACEHOLDER_COUNT = 6;
-const MODULES_LISTING_DATA_KEY = "modules-page-listing";
 
 const { t } = useI18n();
 const { processI18n } = useTranslation();
@@ -85,37 +84,16 @@ if (!siteLayout.siteLayout.value) {
 // 403 page, the same answer as any page they may not open (the entry is not in
 // their menu either).
 if (!isOwner.value) {
-  throw showError({
+  throw showDmsError({
     statusCode: HTTP_FORBIDDEN,
     statusMessage: "Access denied",
   });
 }
 
-// Whatever is cached from an earlier visit shows at once; stale live figures
-// are then refreshed in the background on mount. The hydration reuses the
-// listing the server rendered: fetched again before hydrating, its live
-// readouts (an uptime a minute on) would no longer match the markup.
-if (isOwner.value) {
-  const { data: renderedListing } = await useDmsAsyncData<
-    ModuleCatalogEntry[] | null
-  >(MODULES_LISTING_DATA_KEY, async () => {
-    await modulesListing.loadModulesListing();
-    return modulesListing.modules.value ?? null;
-  });
-  if (modulesListing.modules.value === undefined) {
-    if (renderedListing.value) {
-      modulesListing.modules.value = renderedListing.value;
-    } else {
-      await modulesListing.loadModulesListing();
-    }
-  }
-}
-
-onMounted(() => {
-  if (isOwner.value && modulesListing.modules.value !== undefined) {
-    void modulesListing.revalidate();
-  }
-});
+// Read with the page, which the server renders and hands over: the
+// hydration reuses the listing the server rendered (read again, its live
+// readouts, an uptime a minute on, would no longer match the markup).
+await modulesListing.loadModulesListing();
 
 const isForbidden = computed(
   () =>
@@ -204,7 +182,7 @@ const trimmedQuery = computed(() => query.value.trim());
 const pageMatch = computed(() => {
   if (visibleModules.value.length > 0 || !trimmedQuery.value) return null;
   const match = findModulePageMatch(
-    siteLayout.siteLayout.value?.pages,
+    siteLayout.siteLayout.value,
     trimmedQuery.value,
     new Set(modules.value.map((entry) => entry.id)),
     processI18n,

package/frontend-vue/layers/dms-layout/app/emails/components/EmailLayout.vue

@@ -1,16 +1,20 @@
 <script setup lang="ts">
+import type { DmsLogoSources } from "#dms-core/shared/types/app-config";
 import { emailLogoUrl, emailStyles } from "./index";
 
+interface EmailLogoConfig {
+  default?: Partial<DmsLogoSources>;
+  email?: Partial<DmsLogoSources>;
+}
+
 interface EmailAppConfig {
   branding?: {
-    logo?: {
-      default?: {
-        light?: string;
-      };
-    };
+    logo?: EmailLogoConfig;
   };
 }
 
+const DARK_SCHEME_MEDIA = "(prefers-color-scheme: dark)";
+
 const props = withDefaults(
   defineProps<{
     /** Shown as the email's heading; no heading when omitted. */
@@ -33,13 +37,20 @@ const props = withDefaults(
 const appConfig = useDmsAppConfig() as EmailAppConfig;
 const runtimeConfig = useDmsRuntimeConfig();
 
-const logoPath = appConfig.branding?.logo?.default?.light;
+const logo = appConfig.branding?.logo;
 const clientBaseUrl = runtimeConfig.public.dms?.clientBaseUrl ?? "";
-const logoUrl = props.publicLogoOnly
-  ? emailLogoUrl(logoPath, clientBaseUrl)
-  : logoPath?.startsWith("/")
-    ? `${clientBaseUrl}${logoPath}`
-    : logoPath;
+
+function logoSource(path: string | undefined): string {
+  if (props.publicLogoOnly) return emailLogoUrl(path, clientBaseUrl);
+  return path?.startsWith("/") ? `${clientBaseUrl}${path}` : (path ?? "");
+}
+
+const logoUrl = logoSource(logo?.email?.light || logo?.default?.light);
+// Offered to the mail clients that follow the reader's dark mode; the others
+// skip the picture's source and draw the light image. Taken from the email
+// slot only, so an instance that sets none keeps its single image.
+const darkCandidate = logoSource(logo?.email?.dark);
+const darkLogoUrl = darkCandidate === logoUrl ? "" : darkCandidate;
 </script>
 
 <template>
@@ -52,7 +63,16 @@ const logoUrl = props.publicLogoOnly
       <EContainer :style="emailStyles.container">
         <ESection :style="emailStyles.card">
           <ESection v-if="logoUrl" :style="emailStyles.logo">
+            <picture v-if="darkLogoUrl">
+              <source :media="DARK_SCHEME_MEDIA" :srcset="darkLogoUrl" />
+              <EImg
+                :src="logoUrl"
+                :alt="logoAlt"
+                :style="emailStyles.logoImage"
+              />
+            </picture>
             <EImg
+              v-else
               :src="logoUrl"
               :alt="logoAlt"
               :style="emailStyles.logoImage"

package/frontend-vue/layers/dms-layout/app/error.vue

@@ -4,6 +4,7 @@ import StageCard, {
   type StageCardTone,
 } from "./build/components/layout/StageCard.vue";
 import EmptyLayout from "./custom-layouts/EmptyLayout.vue";
+import { publicErrorMessage } from "./build/utils/publicErrorMessage";
 
 interface ErrorConfig {
   icon: string;
@@ -66,10 +67,12 @@ const statusCode = computed(
   () => props.error.statusCode || DEFAULT_STATUS_CODE,
 );
 
+// Never the backend's address a failed request names (see
+// `publicErrorMessage`).
 const visibleErrorMessage = computed(() =>
   STATUSES_WITHOUT_ERROR_MESSAGE.has(statusCode.value)
     ? undefined
-    : props.error.message,
+    : publicErrorMessage(props.error.message),
 );
 
 const errorConfig = computed(
@@ -89,7 +92,7 @@ const description = computed(() =>
 );
 
 const handleError = async () => {
-  clearError();
+  clearDmsError();
   if (!loggedIn.value) {
     await redirectToAuth(homepage);
   } else {

package/frontend-vue/layers/dms-layout/app/middleware/module-routing.global.ts

@@ -89,7 +89,7 @@ export default defineDmsMiddleware(async (to, from) => {
   const moduleEntry = siteLayout.modules.value?.[moduleId];
 
   if (!moduleId || !moduleEntry) {
-    throw createError({
+    throw createDmsError({
       statusCode: MODULE_NOT_FOUND_STATUS,
       statusMessage: MODULE_NOT_FOUND_MESSAGE,
       data: { kind: MODULE_NOT_FOUND_KIND },

package/frontend-vue/layers/dms-layout/app/middleware/page-leave-guard.global.ts

@@ -8,7 +8,7 @@ export default defineDmsMiddleware(async (to, from) => {
   // Unsaved changes anywhere (the page's forms, an open drawer or modal, a
   // settings panel): one warning dialog, whatever holds them.
   if (!(await confirmLeave())) {
-    return abortNavigation();
+    return abortDmsNavigation();
   }
 
   const { executeGuards } = useLeaveGuard();
@@ -17,6 +17,6 @@ export default defineDmsMiddleware(async (to, from) => {
   const canLeave = await executeGuards(pageKey);
 
   if (!canLeave) {
-    return abortNavigation();
+    return abortDmsNavigation();
   }
 });

package/frontend-vue/layers/dms-layout/app/pages/[...slug].vue

@@ -3,6 +3,7 @@ import { withoutTrailingSlash } from "ufo";
 import { holdPageHeaderActions } from "../composables/layout/usePageHeaderActions";
 import { useDevReloading } from "../build/composables/dev-reload/useDevReloadHolder";
 import { usePageLiveHost } from "#dms-ui/app/build/composables/live/usePageLiveHost";
+import { usePageDataRefresh } from "#dms-ui/app/build/composables/live/usePageDataRefresh";
 import { pageValidationRedirect } from "../build/utils/pageValidationRedirect";
 
 defineOptions({ inheritAttrs: false });
@@ -42,7 +43,7 @@ async function checkPageMetadata(
     if (import.meta.env.DEV && devReloading.value) {
       return;
     }
-    throw showError({
+    throw showDmsError({
       statusCode: HTTP_NOT_FOUND,
       statusMessage: "Page not found",
     });
@@ -76,7 +77,7 @@ async function recheckAccessWithFreshSession(): Promise<void> {
     if (import.meta.env.DEV && devReloading.value) {
       return;
     }
-    throw showError({
+    throw showDmsError({
       statusCode: HTTP_NOT_FOUND,
       statusMessage: "Page not found",
     });
@@ -90,7 +91,7 @@ async function recheckAccessWithFreshSession(): Promise<void> {
     return;
   }
 
-  throw showError({
+  throw showDmsError({
     statusCode: HTTP_FORBIDDEN,
     statusMessage: "Access denied",
   });
@@ -140,7 +141,7 @@ async function enforcePageValidation(): Promise<void> {
     routeQuery: query,
   });
   if (!redirect) {
-    throw createError({
+    throw createDmsError({
       statusCode: HTTP_NOT_FOUND,
       statusMessage: "Page not found",
     });
@@ -172,7 +173,7 @@ const pagelayoutMetadata = computed(() => routeMatch.value?.metadata);
 const routeParams = computed(() => routeMatch.value?.params || {});
 
 if (siteLayout.loadingError && siteLayout.loadingError.value) {
-  throw createError({
+  throw createDmsError({
     statusCode: HTTP_INTERNAL_SERVER_ERROR,
     statusMessage: "Error loading site layout",
     message: siteLayout.loadingError.value || "Unknown error occurred",
@@ -186,7 +187,7 @@ await checkPageMetadata(pagelayoutMetadata.value);
 // flight the page is unregistered for a moment, and the plugin is already
 // waiting for it to come back.
 if (!pagelayoutMetadata.value && !(import.meta.env.DEV && devReloading.value)) {
-  throw createError({
+  throw createDmsError({
     statusCode: HTTP_NOT_FOUND,
     statusMessage: "Page not found",
   });
@@ -202,9 +203,9 @@ if (import.meta.env.DEV) {
   // the flag back with nobody watching.
   watch(devReloading, (reloading) => {
     if (!reloading && !pagelayoutMetadata.value) {
-      // `showError` commits the error itself; throwing on top of it would only
+      // `showDmsError` commits the error itself; throwing on top of it would only
       // add a second report of the same thing.
-      showError({
+      showDmsError({
         statusCode: HTTP_NOT_FOUND,
         statusMessage: "Page not found",
       });
@@ -246,6 +247,8 @@ usePageLiveHost(
   }),
   { isStreamConnected: () => !!realtime.sessionId.value },
 );
+// The page's `useApiData` reads follow its refreshes and its realtime events.
+usePageDataRefresh(realtime);
 
 function buildPageSetupContext(
   pageInfo: PageInfo,
@@ -495,7 +498,7 @@ if (import.meta.env.DEV) {
         void navigateDms(moved[0]);
         return;
       }
-      showError({
+      showDmsError({
         statusCode: HTTP_NOT_FOUND,
         statusMessage: "Page not found",
       });