@antelopejs/dms-frontend 0.9.1 → 0.9.3

package/templates/vue/frontend-runtime/errors.ts

@@ -0,0 +1,145 @@
+import { router as inertiaRouter } from "@inertiajs/vue3";
+import { ofetch } from "ofetch";
+import { computed, nextTick, type Ref, readonly } from "vue";
+import {
+  type DmsErrorData,
+  type DmsPageProps,
+  type DmsSession,
+  type DmsUser,
+  type DmsUserSession,
+} from "./types";
+import { createDmsError } from "./dms-error";
+import { useDmsRuntime } from "./state";
+import { navigateDms } from "./route";
+import { endHydration, preloadDmsPage } from "./components";
+import { useDmsState } from "./payload";
+
+export function showDmsError(
+  input: string | DmsErrorData,
+): Error & DmsErrorData {
+  const error = createDmsError(input);
+  useDmsRuntime().currentError.value = error;
+  return error;
+}
+export function useDmsError(): Ref<(Error & DmsErrorData) | null> {
+  return useDmsRuntime().currentError as Ref<(Error & DmsErrorData) | null>;
+}
+export async function clearDmsError(options?: {
+  redirect?: string;
+}): Promise<void> {
+  useDmsRuntime().currentError.value = null;
+  if (options?.redirect) await navigateDms(options.redirect);
+}
+
+function sessionIdentity(session: unknown): string {
+  const { accountId, activeTenantId } = (session ?? {}) as Partial<DmsSession>;
+  return `${accountId ?? ""}\n${activeTenantId ?? ""}`;
+}
+
+/**
+ * Drops the pages Inertia prefetched (a hovered link) once the session is
+ * another account's or workspace's, or none: each carries the user, the page
+ * and the site layout of the session it was fetched with, and a visit would
+ * show them as current.
+ */
+function forgetPrefetchedPages(): void {
+  if (typeof window !== "undefined") inertiaRouter.flushAll();
+}
+
+/**
+ * Warms what a prefetched page renders (its page, layout and block
+ * components) once Inertia has its props, so following the link does not wait
+ * for those chunks after the props.
+ */
+export function preloadPrefetchedDmsPages(): () => void {
+  return inertiaRouter.on("prefetched", (event) => {
+    const data = event.detail.response.data as unknown;
+    let page: { props?: DmsPageProps } | undefined;
+    try {
+      page = (typeof data === "string" ? JSON.parse(data) : data) as
+        | { props?: DmsPageProps }
+        | undefined;
+    } catch {
+      return;
+    }
+    if (page?.props?.page) void preloadDmsPage(page.props).catch(() => {});
+  });
+}
+
+export function useDmsUserSession<
+  TUser = DmsUser,
+  TSession = DmsSession,
+>(): DmsUserSession<TUser, TSession> {
+  const user = useDmsState<TUser | null>("dms-user", () => null);
+  const session = useDmsState<TSession | null>("dms-session", () => null);
+  return {
+    user,
+    session,
+    loggedIn: computed(() => user.value !== null),
+    fetch: async () => {
+      const before = sessionIdentity(session.value);
+      const value = await ofetch<{
+        user?: TUser;
+        session?: TSession;
+      }>("/api/_auth/session", { method: "POST" });
+      user.value = value.user ?? null;
+      session.value = value.session ?? null;
+      if (sessionIdentity(session.value) !== before) forgetPrefetchedPages();
+    },
+    clear: async () => {
+      await ofetch("/api/_auth/session", { method: "DELETE" });
+      user.value = null;
+      session.value = null;
+      forgetPrefetchedPages();
+    },
+  };
+}
+
+/**
+ * Whether the page loaded by the current navigation is still pending: its
+ * chunk, or an async `setup` it awaits, has not resolved yet. A layout reads
+ * it to show its own placeholder in place of the page. Always `false` on the
+ * server and during hydration, which render the page resolved.
+ */
+export function useDmsPageLoading(): Readonly<Ref<boolean>> {
+  return readonly(useDmsRuntime().pageLoading);
+}
+
+/**
+ * Whether the browser is hydrating the page the server rendered, whose first
+ * render must match the server's HTML: from the start of the application to
+ * the tick the page's `<Suspense>` resolves. False on the server, in a page
+ * the server did not render, and after a client navigation. As Nuxt's
+ * `nuxtApp.isHydrating`; read once, it is not reactive.
+ */
+export function isDmsHydrating(): boolean {
+  return useDmsRuntime().hydrating;
+}
+
+/**
+ * The props of the `<Suspense>` around the page that keep `useDmsPageLoading`
+ * in step with it. Cleared before the boundary unmounts, so a page left while
+ * pending never leaves the state set.
+ *
+ * They also end the hydration: the page is on screen once its suspense
+ * resolves, and the components after it once the tick is over, so the
+ * browser has then hydrated what the server rendered. A hydrating suspense
+ * never reports itself pending: the server rendered the page resolved.
+ */
+export function dmsPageSuspenseProps(): Record<string, () => void> {
+  const runtime = useDmsRuntime();
+  const loading = runtime.pageLoading;
+  const settle = () => {
+    loading.value = false;
+  };
+  return {
+    onPending: () => {
+      loading.value = true;
+    },
+    onResolve: () => {
+      settle();
+      if (runtime.hydrating) void nextTick(() => endHydration(runtime));
+    },
+    onVnodeBeforeUnmount: settle,
+  };
+}

package/templates/vue/frontend-runtime/fetch.ts

@@ -0,0 +1,306 @@
+import { type FetchOptions, ofetch } from "ofetch";
+import { isRef, type MaybeRefOrGetter, toValue, watch } from "vue";
+import { type DmsFrontendRuntime } from "./module-registration";
+import { useDmsRuntime } from "./state";
+import {
+  type DmsAsyncDataHandler,
+  type DmsAsyncDataResult,
+  type UseAsyncDataOptions,
+  type UseFetchOptions,
+} from "./types";
+import { useDmsAsyncData } from "./async-data";
+
+/**
+ * The options of a request a runtime makes. A server render does not retry a
+ * failed read, as ofetch would once: the page waits for it, and a backend
+ * failing once mostly fails twice. A browser keeps ofetch's retries, and a
+ * caller that names its own keeps them everywhere.
+ */
+function runtimeFetchOptions(
+  runtime: DmsFrontendRuntime,
+  options: FetchOptions,
+): FetchOptions {
+  return runtime.isServer && options.retry === undefined
+    ? { ...options, retry: 0 }
+    : options;
+}
+
+const warnedServerReads = new Set<string>();
+
+/**
+ * Warns, in a development server render, about a backend read no async data
+ * handler makes: an immediate watcher's, a setup's own `await $fetch`, a
+ * middleware's. The server waits for it, but the page carries none of it, so
+ * the browser reads it again and may hydrate with other data. Code that hands
+ * the answer over itself (`useDmsState` with `transfer: true`) looks the same
+ * from here, so the message names that exception rather than guess.
+ */
+function warnUntransferredRead(
+  runtime: DmsFrontendRuntime,
+  request: string,
+): void {
+  if (
+    !runtime.isServer ||
+    !runtime.devWarnings ||
+    !runtime.inAsyncDataHandler ||
+    runtime.inAsyncDataHandler() ||
+    warnedServerReads.has(request)
+  )
+    return;
+  warnedServerReads.add(request);
+  console.warn(
+    `DMS: ${request} was read during a server render outside useDmsFetch and useDmsAsyncData ` +
+      "(an immediate watcher, a setup's own await, a middleware): unless the code hands the " +
+      "answer over (useDmsState with transfer: true), the page does not carry it and the " +
+      "browser reads it again. Load it with useDmsFetch or useDmsAsyncData, in a middleware " +
+      "or a plugin too, or leave it to the browser (server: false, onMounted).",
+  );
+}
+
+function createDmsFetch(defaults: FetchOptions = {}): typeof ofetch {
+  const configuredFetch = ofetch.create(defaults);
+  const execute = (request: string, options?: FetchOptions) => {
+    const runtime = useDmsRuntime();
+    warnUntransferredRead(runtime, request);
+    return (runtime.serverFetch ?? ofetch)(
+      request,
+      runtimeFetchOptions(runtime, { ...defaults, ...options }),
+    );
+  };
+  return Object.assign(execute, {
+    create: (options: FetchOptions) =>
+      createDmsFetch({ ...defaults, ...options }),
+    native: configuredFetch.native,
+    raw: configuredFetch.raw,
+  }) as typeof ofetch;
+}
+
+export const $fetch = createDmsFetch();
+
+/** JSON with sorted keys, or nothing for a value JSON cannot stand for. */
+function stableJson(value: unknown): string | undefined {
+  if (value === undefined || value === null) return "null";
+  if (value instanceof Date) return JSON.stringify(value);
+  if (typeof value !== "object")
+    return ["string", "number", "boolean"].includes(typeof value)
+      ? JSON.stringify(value)
+      : undefined;
+  if (Array.isArray(value)) {
+    const items = value.map(stableJson);
+    return items.includes(undefined) ? undefined : `[${items.join(",")}]`;
+  }
+  const prototype = Object.getPrototypeOf(value) as unknown;
+  if (prototype !== Object.prototype && prototype !== null) return undefined;
+  const record = value as Record<string, unknown>;
+  const members = Object.keys(record)
+    .filter((name) => record[name] !== undefined)
+    .sort()
+    .map((name) => {
+      const member = stableJson(record[name]);
+      return member === undefined
+        ? undefined
+        : `${JSON.stringify(name)}:${member}`;
+    });
+  return members.includes(undefined) ? undefined : `{${members.join(",")}}`;
+}
+
+const FETCH_KEY_PREFIX = "$dmsfetch:";
+const DEFAULT_FETCH_METHOD = "GET";
+
+// cyrb53's mixing constants, with its two 32-bit lanes both kept: a 64-bit
+// digest, as short as Nuxt's keys and as unlikely to collide within a page.
+const HASH_SEEDS = [0xdeadbeef, 0x41c6ce57];
+const HASH_MULTIPLIERS = [2654435761, 1597334677];
+const HASH_FINALIZERS = [2246822507, 3266489909];
+const HASH_SHIFTS = [16, 13];
+const HASH_RADIX = 36;
+const HASH_LANE_LENGTH = 7;
+
+/**
+ * A short digest of a text, the same in a server and in a browser: pure
+ * JavaScript, so no `node:crypto` reaches a browser bundle.
+ */
+function hashText(text: string): string {
+  let [first, second] = HASH_SEEDS;
+  for (let index = 0; index < text.length; index++) {
+    const code = text.charCodeAt(index);
+    first = Math.imul(first ^ code, HASH_MULTIPLIERS[0]);
+    second = Math.imul(second ^ code, HASH_MULTIPLIERS[1]);
+  }
+  first = Math.imul(first ^ (first >>> HASH_SHIFTS[0]), HASH_FINALIZERS[0]);
+  first ^= Math.imul(second ^ (second >>> HASH_SHIFTS[1]), HASH_FINALIZERS[1]);
+  second = Math.imul(second ^ (second >>> HASH_SHIFTS[0]), HASH_FINALIZERS[0]);
+  second ^= Math.imul(first ^ (first >>> HASH_SHIFTS[1]), HASH_FINALIZERS[1]);
+  return [second, first]
+    .map((lane) =>
+      (lane >>> 0).toString(HASH_RADIX).padStart(HASH_LANE_LENGTH, "0"),
+    )
+    .join("");
+}
+
+/**
+ * The key a request's response is shared and transferred under: a digest of
+ * its method, base URL, URL, query and params, and body, the headers aside. A
+ * server render writes the key into its HTML, which must not show the URL, a
+ * token in its query or a body. A body only a request can read, such as a
+ * FormData, gives none.
+ */
+function requestKey(url: string, options: FetchOptions): string | undefined {
+  // ofetch sends the params and the query together, the query winning.
+  const query =
+    options.query || options.params
+      ? { ...options.params, ...options.query }
+      : null;
+  const request = stableJson([
+    (options.method ?? DEFAULT_FETCH_METHOD).toUpperCase(),
+    options.baseURL ?? "",
+    url,
+    query,
+    options.body ?? null,
+  ]);
+  return request === undefined
+    ? undefined
+    : `${FETCH_KEY_PREFIX}${hashText(request)}`;
+}
+
+/** The parts of a request its key is computed from. */
+export type DmsRequestKeyOptions = Pick<
+  FetchOptions,
+  "method" | "baseURL" | "query" | "params" | "body"
+>;
+
+/**
+ * The key `useDmsFetch` loads a request's response under, without the scope
+ * (`setDmsAsyncDataScope`): what `refreshDmsData(keys)` takes, and what a
+ * test compares with the keys it finds. `undefined` for a body only a
+ * request can read, such as a FormData.
+ *
+ * @param url The URL as given to `useDmsFetch`, before the base URL and the query
+ * @param options The method, base URL, query, params and body of the request
+ */
+export function dmsRequestKey(
+  url: string,
+  options: DmsRequestKeyOptions = {},
+): string | undefined {
+  return requestKey(url, options);
+}
+
+/** A URL to request, or nothing to request while it is null or undefined. */
+type DmsFetchRequest = string | null | undefined;
+
+function isReactiveSource(value: unknown): boolean {
+  return isRef(value) || typeof value === "function";
+}
+
+/** The options given, without the ones left undefined. */
+function definedOptions(options: FetchOptions): FetchOptions {
+  return Object.fromEntries(
+    Object.entries(options).filter(([, value]) => value !== undefined),
+  ) as FetchOptions;
+}
+
+/**
+ * Fetches a URL as `useDmsAsyncData` loads its data, under the key of the
+ * request, so that the callers of one request share it and a server render
+ * transfers it. A ref or a getter for the URL, the method, the query, the
+ * params or the body moves the caller to the key of each request; a URL that
+ * is null or undefined requests nothing.
+ */
+export function useDmsFetch<T>(
+  request: MaybeRefOrGetter<DmsFetchRequest>,
+  options: UseFetchOptions<T> = {},
+): DmsAsyncDataResult<T> {
+  const runtime = useDmsRuntime();
+  const {
+    key,
+    immediate,
+    lazy,
+    server,
+    watch: sources,
+    default: fallback,
+    transform,
+    pick,
+    deep,
+    dedupe,
+    refreshOnPageRefresh,
+    refreshInterval,
+    $fetch: fetcher,
+    method,
+    query,
+    params,
+    body,
+    ...fixedOptions
+  } = options;
+  const url = () => toValue(request);
+  const requestOptions = (): FetchOptions =>
+    definedOptions({
+      ...fixedOptions,
+      method: toValue(method),
+      query: toValue(query),
+      params: toValue(params),
+      body: toValue(body),
+    });
+  // A `$fetch` of the caller's own applies its own retries. The transform
+  // runs here, where the request a response answers is known: a reactive URL
+  // may have changed since it was sent.
+  const handler: DmsAsyncDataHandler<T> = async ({ signal }) => {
+    const target = url() as string;
+    const sent = requestOptions();
+    const runKey =
+      key === undefined
+        ? requestKey(target, sent)
+        : (toValue(key) ?? undefined);
+    const value: unknown = await (fetcher
+      ? fetcher(target, { ...sent, signal })
+      : (runtime.serverFetch ?? ofetch)(
+          target,
+          runtimeFetchOptions(runtime, { ...sent, signal }),
+        ));
+    if (!transform) return value as T;
+    return transform(value, { key: runKey, url: target });
+  };
+  const asyncOptions: UseAsyncDataOptions<T> = {
+    immediate,
+    lazy,
+    server,
+    watch: sources,
+    default: fallback,
+    pick,
+    deep,
+    dedupe,
+    refreshOnPageRefresh,
+    refreshInterval,
+  };
+  const reactiveSources = [request, method, query, params, body].filter(
+    isReactiveSource,
+  );
+  const isReactive = reactiveSources.length > 0;
+  // The request gives its key, which follows the request as it changes.
+  const derived = (): string | null | undefined => {
+    const target = url();
+    return target == null ? null : requestKey(target, requestOptions());
+  };
+  if (key === undefined && derived() !== undefined)
+    return useDmsAsyncData(
+      isReactive ? derived : derived(),
+      handler,
+      asyncOptions,
+    );
+  // The key the caller names, or none for a body without one, stays put while
+  // the request changes: the request is watched instead.
+  const watched =
+    isReactive && sources !== false
+      ? [...reactiveSources, ...(sources ?? [])]
+      : sources;
+  if (key === undefined)
+    return useDmsAsyncData(handler, undefined, {
+      ...asyncOptions,
+      watch: watched,
+    });
+  const named = () => (url() == null ? null : toValue(key));
+  const followsKey = isReactiveSource(request) || isReactiveSource(key);
+  return useDmsAsyncData(followsKey ? named : named(), handler, {
+    ...asyncOptions,
+    watch: watched,
+  });
+}

package/templates/vue/frontend-runtime/module-registration.ts

@@ -0,0 +1,247 @@
+import { usePage } from "@inertiajs/vue3";
+import { ofetch } from "ofetch";
+import {
+  type Component,
+  type EffectScope,
+  type InjectionKey,
+  type Plugin,
+  type Ref,
+} from "vue";
+import type { DmsPublicOptionsById } from "../public-options";
+import {
+  type DmsAppContext,
+  type DmsAsyncData,
+  type DmsComponentPreloader,
+  type DmsComponentRegistrationOptions,
+  type DmsErrorData,
+  type DmsMiddlewareRegistrationOptions,
+  type DmsModuleOptions,
+  type DmsPluginRegistrationOptions,
+  type DmsPluginSetup,
+  type DmsRoute,
+  type DmsSharedPagePayload,
+  type RouteLocationRaw,
+} from "./types";
+
+export interface DmsFrontendSdk {
+  options: DmsModuleOptions;
+  registerComponent(
+    name: string,
+    component: Component,
+    options?: DmsComponentRegistrationOptions,
+  ): void;
+  registerPage(
+    name: string,
+    component: Component,
+    preload?: DmsComponentPreloader,
+  ): void;
+  registerDynamicPage(
+    name: string,
+    component: Component,
+    preload?: DmsComponentPreloader,
+  ): void;
+  registerLayout(
+    name: string,
+    component: Component,
+    preload?: DmsComponentPreloader,
+  ): void;
+  registerErrorPage(
+    component: Component,
+    preload?: DmsComponentPreloader,
+  ): void;
+  registerPlugin(
+    setup: DmsPluginSetup,
+    options?: DmsPluginRegistrationOptions,
+  ): void;
+  registerMiddleware(
+    name: string,
+    handler: DmsMiddleware,
+    options?: DmsMiddlewareRegistrationOptions,
+  ): void;
+  /**
+   * Sends a page visit the backend refuses with a typed 403 (its body is
+   * `code`) to `path` instead of the error page. The server answers with the
+   * redirect before anything renders, so a reload lands on `path` directly.
+   */
+  registerAccessRedirect(code: string, path: string): void;
+  provide<T>(key: string | InjectionKey<T>, value: T): void;
+  use(plugin: Plugin): void;
+}
+export interface DmsFrontendModule {
+  /**
+   * Put in front of the name of every component the module registers, so
+   * the components of two modules never collide: with `"Acme"`,
+   * `registerComponent("Banner", ...)` registers `AcmeBanner`, the name the
+   * backend sends and templates use.
+   */
+  componentPrefix?: string;
+  setup(sdk: DmsFrontendSdk): void | Promise<void>;
+}
+export interface DmsFrontendModuleRegistration {
+  /** The module's id in the generated module registry. */
+  id?: string;
+  /** The module's manifest name, which collision warnings name it by. */
+  name?: string;
+  module: DmsFrontendModule;
+  options: DmsModuleOptions;
+}
+
+/**
+ * The registrations with the public options the server runs with in place of
+ * the build's: `ajs dms start` computes them from the project's configuration
+ * and the deployment's variables. Unset, the build's options stand.
+ */
+export function withPublicOptions(
+  registrations: DmsFrontendModuleRegistration[],
+  byId: DmsPublicOptionsById | undefined,
+): DmsFrontendModuleRegistration[] {
+  if (!byId) return registrations;
+  return registrations.map((registration) => {
+    const options = registration.id ? byId[registration.id] : undefined;
+    return options
+      ? {
+          ...registration,
+          options: { ...registration.options, public: options },
+        }
+      : registration;
+  });
+}
+/** A layer's `app/app.config.ts`, as `app-configs.generated.ts` lists them. */
+export interface DmsLayerAppConfig {
+  /** The id of the frontend module the layer belongs to. */
+  module: string;
+  config: Record<string, unknown>;
+}
+// Async middleware without a redirect naturally infers Promise<void>.
+// biome-ignore lint/suspicious/noConfusingVoidType: preserve that valid handler signature.
+export type DmsMiddlewareResult = void | false | RouteLocationRaw;
+export type DmsMiddleware = (
+  to: DmsRoute,
+  from: DmsRoute,
+) => DmsMiddlewareResult | Promise<DmsMiddlewareResult>;
+export type DmsRuntimeHook = (...args: unknown[]) => void | Promise<void>;
+export interface DmsRuntimeHooks {
+  hook(name: string, callback: DmsRuntimeHook): () => void;
+  callHook(name: string, ...args: unknown[]): Promise<void>;
+}
+
+export interface DmsComponentRegistration {
+  name: string;
+  component: Component;
+  /** The registering module, for a collision warning. */
+  module?: string;
+  /** Registered without the module's prefix, to replace another module's. */
+  unprefixed?: boolean;
+}
+
+export interface DmsFrontendEntry {
+  component: Component;
+  preload?: DmsComponentPreloader;
+}
+
+export interface DmsAsyncComponent {
+  __asyncLoader?: DmsComponentPreloader;
+}
+
+interface DmsPluginRegistration {
+  setup: DmsPluginSetup;
+  clientOnly: boolean;
+  enforce: NonNullable<DmsPluginRegistrationOptions["enforce"]>;
+}
+
+export const PLUGIN_ORDER = { pre: 0, default: 1, post: 2 } as const;
+
+/**
+ * What the frontend modules registered through their SDK. Modules are set up
+ * by descending priority, so the first one to claim a name keeps it.
+ */
+export interface DmsFrontendRegistry {
+  components: Map<string, DmsComponentRegistration>;
+  pages: Map<string, DmsFrontendEntry>;
+  dynamicPages: Map<string, DmsFrontendEntry>;
+  layouts: Map<string, DmsFrontendEntry>;
+  errorPage?: DmsFrontendEntry;
+  plugins: Plugin[];
+  pluginSetups: DmsPluginRegistration[];
+  middleware: DmsMiddleware[];
+  namedMiddleware: Map<string, DmsMiddleware>;
+  /** The middlewares registered with `parallel: true`. */
+  parallelMiddleware: WeakSet<DmsMiddleware>;
+  accessRedirects: Map<string, string>;
+  injections: Map<string | symbol, unknown>;
+}
+
+export interface DmsFrontendRuntime {
+  sharedState: Map<string, Ref<unknown>>;
+  /** Reactive: `useDmsData` follows a key as it appears and is dropped. */
+  asyncData: Map<string, DmsAsyncData<unknown>>;
+  /** The server's data, which the browser takes over once per key. */
+  hydratedAsyncData: Map<string, unknown>;
+  /** The server's failures, which the browser takes over once per key. */
+  hydratedAsyncErrors: Map<string, DmsErrorData>;
+  /** The state keys a server render hands to the browser. */
+  transferredState: Set<string>;
+  /**
+   * Whether the browser is still hydrating the page the server rendered,
+   * whose first render must match the server's HTML.
+   */
+  hydrating: boolean;
+  /**
+   * The runs a server render started outside any component, which no
+   * `onServerPrefetch` waits for.
+   */
+  serverPrefetches: Set<Promise<void>>;
+  /** The runs in flight, which a server render aborts once it is over. */
+  asyncDataRuns: Set<AbortController>;
+  /** The data some component or caller shows: `refreshDmsPageData`'s. */
+  boundAsyncData: Set<{ pageRefresh(): Promise<void> | undefined }>;
+  /** Orders the data no caller shows, the least recently shown first. */
+  asyncDataClock: number;
+  /**
+   * The account and workspace the keys belong to (`setDmsAsyncDataScope`):
+   * the same key of another scope is another entry.
+   */
+  asyncDataScope?: string;
+  /**
+   * Runs an async data handler; a server render marks the requests it makes
+   * as transferred (see `inAsyncDataHandler`).
+   */
+  runAsyncDataHandler?: <R>(run: () => R) => R;
+  /** Whether the code running is an async data handler's. */
+  inAsyncDataHandler?: () => boolean;
+  /** Whether to warn about what a development render does wrong. */
+  devWarnings?: boolean;
+  runtimeHooks: Map<string, DmsRuntimeHook[]>;
+  serverFetch?: typeof ofetch;
+  currentError: Ref<Error | null>;
+  route: DmsRoute;
+  currentRoutePattern?: string;
+  appContext?: DmsAppContext;
+  isServer: boolean;
+  serverRedirect?: string;
+  pendingNavigation?: Promise<void>;
+  hasNavigationListener: boolean;
+  /** Whether the page `<Suspense>` waits on the page being navigated to. */
+  pageLoading: Ref<boolean>;
+  /** The site layout last copied into the state, as the page props hold it. */
+  appliedShared?: DmsSharedPagePayload;
+  /** Whether Inertia is putting back a page from the browser history. */
+  restoringHistory?: boolean;
+  /**
+   * Identifies the page on screen (its path, or the error page shown at that
+   * path), whose meta `route.meta` holds.
+   */
+  pageKey?: string;
+  /** The `Cookie` header of the request a server runtime renders. */
+  requestCookies?: string;
+  /**
+   * Owns the effects plugins create while they set up. A server render stops
+   * it once done: nothing else would, since a server app is never unmounted.
+   */
+  scope: EffectScope;
+  /** The Inertia page a server runtime renders: see `useDmsInertiaPage`. */
+  inertiaPage?: DmsInertiaPage;
+}
+
+/** Inertia's page, as `usePage()` returns it. */
+export type DmsInertiaPage = ReturnType<typeof usePage>;