@antelopejs/dms 0.8.3 → 0.9.0

package/frontend-vue/layers/dms-layout/app/plugins/dms-menu-sync.client.ts

@@ -1,8 +1,34 @@
+import { type Ref, watch } from "vue";
+
 const MENU_CHANGED_EVENT_TYPE = "menu-changed";
 
+/**
+ * Calls `onReconnect` each time the realtime stream opens again after it was
+ * lost: the events sent meanwhile never arrived. Not on its first opening,
+ * which follows the page load that brought the current menu.
+ *
+ * @param sessionId The stream's session id, unset while it is closed
+ * @param onReconnect What to run once it is back
+ */
+export function watchRealtimeReconnects(
+  sessionId: Ref<string | undefined>,
+  onReconnect: () => void,
+): void {
+  let hasConnected = !!sessionId.value;
+  watch(sessionId, (next, previous) => {
+    if (!next || next === previous) return;
+    if (hasConnected) onReconnect();
+    hasConnected = true;
+  });
+}
+
 // A module signalled that the data behind the menu changed (a project created,
-// an access scope edited). The event carries no data: the site layout and the
-// permission set are re-fetched, each resolved server-side against this user.
+// an access scope edited, a role or a membership changed): on the workspace's
+// topic, or on this member's own when only their access changed. The event
+// carries no data: the site layout, the page on screen and the permission set
+// are re-fetched, each resolved server-side against this user. The layout
+// comes back through Inertia, so the copy each visit carries over is the new
+// one. A stream that reconnects resyncs too: it missed what was sent meanwhile.
 export default defineDmsPlugin(() => {
   const realtime = useUserRealtime();
   const siteLayout = useSiteLayout();
@@ -16,7 +42,7 @@ export default defineDmsPlugin(() => {
         await Promise.all([
           // Background resync: a transient failure is logged below, never
           // escalated to the fatal error page over a working session.
-          siteLayout.refresh({ fatal: false }),
+          siteLayout.resync(),
           permissions.fetchPermissions(),
         ]);
       })
@@ -30,6 +56,8 @@ export default defineDmsPlugin(() => {
     void refresh();
   };
 
+  watchRealtimeReconnects(realtime.sessionId, () => void refresh());
+
   const unsubscribes: Array<() => void> = [];
 
   watch(

package/frontend-vue/layers/dms-layout/app/plugins/favicon.ts

@@ -0,0 +1,58 @@
+import { computed } from "vue";
+import type { DmsLogoSources } from "#dms-core/shared/types/app-config";
+
+const ICON_TYPES: Record<string, string> = {
+  svg: "image/svg+xml",
+  png: "image/png",
+  ico: "image/x-icon",
+  webp: "image/webp",
+};
+const FILE_EXTENSION = /\.([a-z0-9]+)(?:[?#]|$)/i;
+const LIGHT_SCHEME_MEDIA = "(prefers-color-scheme: light)";
+const DARK_SCHEME_MEDIA = "(prefers-color-scheme: dark)";
+
+// A type rather than an interface: unhead's link type carries an index
+// signature (`data-*`), which only a type alias satisfies implicitly.
+type IconLink = {
+  rel: "icon";
+  href: string;
+  type?: string;
+  media?: string;
+};
+
+function iconLink(href: string, media?: string): IconLink {
+  const extension = FILE_EXTENSION.exec(href)?.[1].toLowerCase() ?? "";
+  const type = ICON_TYPES[extension];
+  return {
+    rel: "icon",
+    href,
+    ...(type ? { type } : {}),
+    ...(media ? { media } : {}),
+  };
+}
+
+function faviconLinks(favicon: Partial<DmsLogoSources> = {}): IconLink[] {
+  const { light, dark } = favicon;
+  if (light && dark && light !== dark)
+    return [
+      iconLink(light, LIGHT_SCHEME_MEDIA),
+      iconLink(dark, DARK_SCHEME_MEDIA),
+    ];
+  const icon = light || dark;
+  return icon ? [iconLink(icon)] : [];
+}
+
+/**
+ * The browser tab icon, `branding.logo.favicon`. Its light and dark files
+ * follow the operating system's scheme: the browser draws the tab outside the
+ * page, where the dashboard's color mode does not reach. The app config is
+ * read inside the computed, so an edit applied in development without a
+ * reload replaces the icon too.
+ */
+export default defineDmsPlugin(() => {
+  useHead(
+    computed(() => ({
+      link: faviconLinks(useDmsAppConfig().branding.logo?.favicon),
+    })),
+  );
+});

package/frontend-vue/layers/dms-layout/app/plugins/notification-stream.client.ts

@@ -1,4 +1,7 @@
-import type { UserNotification } from "../composables/notification/useNotifications";
+import type {
+  FeedCounts,
+  UserNotification,
+} from "../composables/notification/useNotifications";
 
 const NOTIFICATION_TOPIC_PREFIX = "notifications:user:";
 const NOTIFICATION_NEW_TYPE = "notification:new";
@@ -9,6 +12,8 @@ const NOTIFICATION_UNREAD_TYPE = "notification:unread";
 interface IncomingPayload {
   notification?: UserNotification;
   ids?: string[];
+  /** The whole feed's counts after a read state change. */
+  counts?: FeedCounts;
 }
 
 const isNotificationEvent = (
@@ -21,7 +26,7 @@ const isNotificationEvent = (
 type Handler = (payload: IncomingPayload | undefined) => void | Promise<void>;
 
 export default defineDmsPlugin(() => {
-  const { user, loggedIn } = useUserSession();
+  const { user, loggedIn } = useDmsUserSession();
   const {
     handleIncomingNotification,
     handleRemoteRead,
@@ -32,16 +37,19 @@ export default defineDmsPlugin(() => {
 
   const handlers: Record<string, Handler> = {
     [NOTIFICATION_NEW_TYPE]: (payload) => {
-      if (payload?.notification) handleIncomingNotification(payload.notification);
+      if (payload?.notification)
+        handleIncomingNotification(payload.notification);
     },
     [NOTIFICATION_READ_TYPE]: async (payload) => {
-      if (Array.isArray(payload?.ids)) await handleRemoteRead(payload.ids);
+      if (Array.isArray(payload?.ids))
+        await handleRemoteRead(payload.ids, payload.counts);
     },
     [NOTIFICATION_UNREAD_TYPE]: async (payload) => {
-      if (Array.isArray(payload?.ids)) await handleRemoteUnread(payload.ids);
+      if (Array.isArray(payload?.ids))
+        await handleRemoteUnread(payload.ids, payload.counts);
     },
-    [NOTIFICATION_ALL_READ_TYPE]: async () => {
-      await handleRemoteAllRead();
+    [NOTIFICATION_ALL_READ_TYPE]: async (payload) => {
+      await handleRemoteAllRead(payload?.counts);
     },
   };
 

package/frontend-vue/layers/dms-layout/app/plugins/profile-sync.client.ts

@@ -1,3 +1,4 @@
+import { pageRoutePath } from "#dms-core/app/utils/pageRoutes";
 import { FormEvents } from "#dms-ui/app/composables/form/types/events";
 import type { ComponentEventData } from "#dms-core/app/types/component";
 
@@ -5,7 +6,10 @@ interface FormSubmitSuccessPayload {
   submitUrl?: string;
 }
 
-const REGION_PREFERENCES_ROUTE = "/settings/user/region/preferences";
+const REGION_PREFERENCES_ROUTE = pageRoutePath(
+  "/settings/user/region",
+  "/preferences",
+);
 
 /** The forms that edit the signed-in user's own record. */
 const SESSION_FORM_ROUTES = new Set([PROFILE_ROUTE, REGION_PREFERENCES_ROUTE]);

package/frontend-vue/layers/dms-layout/app/plugins/regional-preferences.ts

@@ -1,19 +1,25 @@
 import {
   readRegionalPreferences,
   type RegionalPreferenceFields,
+  setReaderTimeZoneSource,
   setRegionalPreferencesSource,
 } from "#dms-core/app/utils/regional";
+import { useTimeZoneCookie } from "#dms-core/app/composables/period/periodTimeZone";
 
 /**
  * Points the shared date formatters at the signed-in user's regional
- * preferences (time zone, clock, date format, first day of the week). Read on
- * every format, from the session of the request being rendered, so the server
- * HTML and the browser agree and a saved preference applies at once.
+ * preferences (time zone, clock, date format, first day of the week), and a
+ * server render at the browser's time zone. Read on every format, from the
+ * request being rendered, so the server HTML and the browser agree and a
+ * saved preference applies at once.
  */
 export default defineDmsPlugin(() => {
   setRegionalPreferencesSource(() =>
     readRegionalPreferences(
-      useUserSession<RegionalPreferenceFields>().user.value,
+      useDmsUserSession<RegionalPreferenceFields>().user.value,
     ),
   );
+  // A server render writes dates, and resolves periods, in the zone of the
+  // browser it renders for (its cookie), as the browser will.
+  setReaderTimeZoneSource(() => useTimeZoneCookie().value);
 });

package/frontend-vue/layers/dms-layout/app/plugins/time-zone-cookie.client.ts

@@ -0,0 +1,12 @@
+import { useTimeZoneCookie } from "#dms-core/app/composables/period/periodTimeZone";
+import { browserTimeZone } from "#dms-core/app/utils/regional";
+
+/**
+ * Keeps the browser's time zone in its cookie, so that the next server render
+ * resolves the dashboards' periods in it (see `usePeriodScope`).
+ */
+export default defineDmsPlugin(() => {
+  const cookie = useTimeZoneCookie();
+  const zone = browserTimeZone();
+  if (cookie.value !== zone) cookie.value = zone;
+});

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

@@ -41,6 +41,13 @@ export interface CategoryInfo extends Omit<MenuOptions, "category"> {
   fullSlug: string;
   hasAccess?: boolean;
   isModuleRoot?: boolean;
+  /**
+   * The full id of the category this entry sits in, listed once in
+   * `SiteLayout.categories`; none at the root.
+   */
+  categoryId?: string;
+  /** Answers at its parent's slug: never the target of a URL of its own. */
+  urlTransparent?: boolean;
 }
 
 // Mirror of ModuleInfo and MODULE_URL_PREFIX from @antelopejs/interface-dms/page.
@@ -120,7 +127,13 @@ export interface LayoutBanner {
 }
 
 export type SiteLayout = {
+  /** By slug, the key a URL is resolved against. */
   pages: Record<string, PageInfo>;
+  /**
+   * Every category, once, by full id: pages and categories name theirs by
+   * `categoryId`. A URL resolves against the ones that are not
+   * `urlTransparent`, by `fullSlug`.
+   */
   categories: Record<string, CategoryInfo>;
   /** Absent when the backend predates layout banners. */
   banners?: LayoutBanner[];

package/frontend-vue/layers/dms-layout/server/html-render.ts

@@ -0,0 +1,58 @@
+import type { DmsServerEvent } from "#dms/server";
+import { privateSecret } from "../../../server/private-options";
+import { validRenderToken } from "./render-token";
+
+const SERVICE_TOKEN_HEADER = "x-dms-service-token";
+
+interface RenderInput {
+  templateName?: unknown;
+  props?: unknown;
+}
+
+function failure(status: number, message: string): Response {
+  return Response.json({ message }, { status });
+}
+
+function renderSecret(event: DmsServerEvent): string | undefined {
+  return privateSecret(
+    event,
+    "htmlRender",
+    "serviceSecret",
+    "DMS_HTML_RENDER_SECRET",
+  );
+}
+
+/**
+ * `POST /api/html/render`: renders one of the application's email templates
+ * for the DMS backend (`GenerateHtml`), which authenticates with a
+ * single-use service token rather than a browser session.
+ */
+export async function renderHtml(event: DmsServerEvent): Promise<Response> {
+  if (
+    !validRenderToken(
+      event.request.headers.get(SERVICE_TOKEN_HEADER),
+      renderSecret(event),
+    )
+  )
+    return failure(401, "Invalid service token");
+  const input = await event.readJson<RenderInput>();
+  if (
+    typeof input.templateName !== "string" ||
+    input.templateName.trim() === "" ||
+    typeof input.props !== "object"
+  )
+    return failure(400, "Invalid request body");
+  try {
+    const html = await event.renderEmail(
+      input.templateName,
+      (input.props ?? {}) as Record<string, unknown>,
+      { locale: event.request.headers.get("x-content-language") ?? undefined },
+    );
+    return Response.json({ html });
+  } catch {
+    return failure(
+      404,
+      `Template "${input.templateName}" not found or render failed`,
+    );
+  }
+}

package/frontend-vue/layers/dms-layout/server/render-token.ts

@@ -0,0 +1,95 @@
+import { createHmac, timingSafeEqual } from "node:crypto";
+
+// The service token that guards the HTML render route, minted by the DMS
+// backend (`service-jwt.ts`) for its own render requests: its signature, its
+// claims and its single use.
+
+const RENDER_TOKEN_LIFETIME_SECONDS = 5 * 60;
+const RENDER_REPLAY_LIMIT = 10_000;
+
+interface RenderTokenClaims {
+  namespace?: unknown;
+  purpose?: unknown;
+  aud?: unknown;
+  jti?: unknown;
+  iat?: unknown;
+  exp?: unknown;
+}
+
+/** jti -> exp, for tokens already spent. Pruned on every accepted token. */
+const usedRenderTokens = new Map<string, number>();
+
+/**
+ * Constant-time check of the token's HMAC. The length comparison guards
+ * timingSafeEqual, which throws on mismatched lengths; it is not itself a
+ * timing leak, since the length of a base64url HMAC is fixed.
+ */
+function signatureValid(parts: string[], secret: string): boolean {
+  const expected = createHmac("sha256", secret)
+    .update(`${parts[0]}.${parts[1]}`)
+    .digest("base64url");
+  if (expected.length !== parts[2].length) return false;
+  return timingSafeEqual(Buffer.from(expected), Buffer.from(parts[2]));
+}
+
+/**
+ * The claims this service accepts. `exp - iat` is bounded so a token minted
+ * with a far-future expiry cannot outlive the intended window.
+ */
+function claimsValid(
+  payload: RenderTokenClaims,
+  now: number,
+): payload is RenderTokenClaims & { jti: string; exp: number } {
+  return (
+    payload.namespace === "html-render-service" &&
+    payload.purpose === "html-render" &&
+    payload.aud === "dms-frontend" &&
+    typeof payload.jti === "string" &&
+    payload.jti.length >= 16 &&
+    Number.isSafeInteger(payload.iat) &&
+    Number.isSafeInteger(payload.exp) &&
+    (payload.exp as number) > now &&
+    (payload.exp as number) - (payload.iat as number) <=
+      RENDER_TOKEN_LIFETIME_SECONDS &&
+    (payload.iat as number) <= now
+  );
+}
+
+/**
+ * Records a token as spent, dropping expired entries first and evicting the
+ * oldest if the map is at its cap, so a flood of tokens cannot grow it without
+ * bound.
+ */
+function rememberToken(jti: string, exp: number, now: number) {
+  for (const [spent, expiresAt] of usedRenderTokens)
+    if (expiresAt <= now) usedRenderTokens.delete(spent);
+  while (usedRenderTokens.size >= RENDER_REPLAY_LIMIT)
+    usedRenderTokens.delete(usedRenderTokens.keys().next().value as string);
+  usedRenderTokens.set(jti, exp);
+}
+
+/**
+ * Whether the token is well-formed, signed with `secret`, unexpired and not
+ * already spent. A token accepted here is immediately marked as spent.
+ */
+export function validRenderToken(
+  token: string | null,
+  secret: string | undefined,
+): boolean {
+  if (!token || !secret) return false;
+  const parts = token.split(".");
+  if (parts.length !== 3) return false;
+  if (!signatureValid(parts, secret)) return false;
+  try {
+    const payload = JSON.parse(
+      Buffer.from(parts[1], "base64url").toString("utf8"),
+    ) as RenderTokenClaims;
+    const now = Math.floor(Date.now() / 1000);
+    if (!claimsValid(payload, now)) return false;
+    if (usedRenderTokens.has(payload.jti)) return false;
+    rememberToken(payload.jti, payload.exp, now);
+    return true;
+  } catch {
+    return false;
+  }
+}

package/frontend-vue/layers/dms-onboarding/app/composables/onboarding/useOnboarding.ts

@@ -6,34 +6,38 @@ interface OnboardingInfoResponse {
   has_onboarded: boolean;
 }
 
+/**
+ * Transferred: the global middleware reads it while a server renders the
+ * page, and the browser's run of the middleware then finds it instead of
+ * asking again. It holds nothing private.
+ */
+function useOnboardingCache() {
+  return useDmsState<OnboardingInfo | null>("dms-onboarding-info", () => null, {
+    transfer: true,
+  });
+}
+
 export const useOnboarding = async (): Promise<OnboardingInfo> => {
-  const cache = useDmsState<OnboardingInfo | null>(
-    "dms-onboarding-info",
-    () => null,
-  );
+  const cache = useOnboardingCache();
 
-  if (cache.value) return cache.value;
+  const known = cache.value;
+  if (known) return known;
 
   const { $authFetch } = useAuthFetch();
 
-  const response = await $authFetch<OnboardingInfoResponse>(
-    "/api/onboarding/informations",
-    { method: "GET" },
-  );
-
-  const info: OnboardingInfo = {
-    hasOnboarded: response.has_onboarded,
-  };
-
-  cache.value = info;
-  return info;
+  // One request per app however many callers ask before it answers: the
+  // preload started with the app and the `onboarding` middleware share it.
+  await useTrailingDeduper("onboarding").join(async () => {
+    const response = await $authFetch<OnboardingInfoResponse>(
+      "/api/onboarding/informations",
+      { method: "GET" },
+    );
+    cache.value = { hasOnboarded: response.has_onboarded };
+  });
+  return cache.value as OnboardingInfo;
 };
 
 /** Release the cached onboarding guard after the backend creates the admin. */
 export const setOnboardingComplete = () => {
-  const cache = useDmsState<OnboardingInfo | null>(
-    "dms-onboarding-info",
-    () => null,
-  );
-  cache.value = { hasOnboarded: true };
+  useOnboardingCache().value = { hasOnboarded: true };
 };

package/frontend-vue/layers/dms-onboarding/app/middleware/onboarding.global.ts

@@ -5,7 +5,7 @@ const LOGIN_PATH = "/auth";
 // login page for anyone else rather than a homepage whose 401 would bounce
 // them there anyway.
 function completedOnboardingDestination(): string {
-  const { loggedIn } = useUserSession();
+  const { loggedIn } = useDmsUserSession();
   return loggedIn.value ? useHomepage() : LOGIN_PATH;
 }
 

package/frontend-vue/layers/dms-onboarding/app/plugins/onboarding-preload.ts

@@ -0,0 +1,9 @@
+/**
+ * Asks for the onboarding status as the app starts rather than when the
+ * `onboarding` middleware does, once the plugins and the page have set up:
+ * the request runs alongside the others the render makes, and the middleware
+ * joins it. A failure stays the middleware's to handle.
+ */
+export default defineDmsPlugin(() => {
+  useOnboarding().catch(() => undefined);
+});

package/frontend-vue/layers/dms-ui/app/build/composables/data-types/registerDefaults.ts

@@ -742,7 +742,9 @@ interface TextOptions {
 /**
  * `string`: the value as written, in the tone the row gives (`toneField`) when
  * it gives one; a row without one keeps the bare value, as a string column
- * always drew it.
+ * always drew it. An empty one is `null`: a cell rendering `""` as its root
+ * leaves no node in the server's HTML, which the browser hydrates as a
+ * mismatch, where `null` renders a placeholder both sides agree on.
  */
 function renderText(
   value: unknown,
@@ -750,6 +752,7 @@ function renderText(
   options?: unknown,
   row?: Row,
 ): unknown {
+  if (value === "") return null;
   const tone = readRowTone(
     row,
     (options as TextOptions | undefined)?.toneField,

package/frontend-vue/layers/dms-ui/app/build/composables/files/useFileMetadata.ts

@@ -0,0 +1,162 @@
+import {
+  effectScope,
+  getCurrentInstance,
+  inject,
+  onScopeDispose,
+  shallowReactive,
+  watch,
+} from "vue";
+import { FORM_CONTENT_LANGUAGE_KEY } from "../../../composables/form/types/content-language";
+import {
+  isDefinitiveMetadataFailure,
+  resolveMetadataRetryDelay,
+} from "../../../utils/metadataRetry";
+
+/** What `/api/files/metadata` answers for a stored file. */
+export interface FileMetadata {
+  resourceKey: string;
+  filename: string;
+  size: number;
+  mimetype: string;
+  url: string;
+  /** When `url` stops working, in milliseconds since the epoch. */
+  expiresAt?: number;
+}
+
+const METADATA_URL = "/api/files/metadata";
+// A read URL is read again this long before it expires.
+const URL_REFRESH_LEAD_MS = 5000;
+
+const isExpired = (metadata: FileMetadata): boolean =>
+  metadata.expiresAt !== undefined && metadata.expiresAt <= Date.now();
+
+/**
+ * The metadata of stored files (name, size, type, read URL), one read per
+ * file key, shared by every component showing that file.
+ *
+ * A key resolved during a component's setup (directly, or from an immediate
+ * watcher) is read with the page: a server render waits for it and hands it
+ * to the browser, which does not ask again. A key resolved later (a new
+ * value, an upload) is read in the browser. While a component shows a file,
+ * its URL is read again before it expires, and a failed read that may heal
+ * (network, 5xx, rate limiting) is retried with a growing delay; a refused or
+ * missing file (another 4xx) is not.
+ *
+ * @param storage The storage the keys live in (the field's `storage`)
+ */
+export function useFileMetadata(storage?: string) {
+  const contentLanguage = inject(FORM_CONTENT_LANGUAGE_KEY, undefined);
+  // Reads resolved past the setup run with the application's context.
+  const app = getCurrentInstance()?.appContext.app;
+  const scope = effectScope();
+  const reads = shallowReactive(new Map<string, ApiDataResult<FileMetadata>>());
+  const timers = new Map<string, ReturnType<typeof setTimeout>>();
+  const failures = new Map<string, number>();
+
+  function schedule(key: string, delay: number, read: () => Promise<void>) {
+    clearTimeout(timers.get(key));
+    timers.set(
+      key,
+      setTimeout(() => {
+        timers.delete(key);
+        void read();
+      }, delay),
+    );
+  }
+
+  /** The next read of `key` its last answer calls for, in the browser. */
+  function follow(key: string, result: ApiDataResult<FileMetadata>): void {
+    const refresh = () => result.refresh({ dedupe: "defer" });
+    watch(
+      [result.data, result.error, result.status],
+      ([metadata, error, status]) => {
+        if (status === "pending" || status === "idle") return;
+        clearTimeout(timers.get(key));
+        if (error) {
+          const attempts = (failures.get(key) ?? 0) + 1;
+          failures.set(key, attempts);
+          const delay = resolveMetadataRetryDelay(error, attempts);
+          if (delay !== null) schedule(key, delay, refresh);
+          return;
+        }
+        failures.delete(key);
+        if (metadata?.expiresAt === undefined) return;
+        const remaining = Math.max(metadata.expiresAt - Date.now(), 0);
+        const lead = Math.min(URL_REFRESH_LEAD_MS, remaining / 2);
+        schedule(key, remaining - lead, refresh);
+      },
+      { immediate: true },
+    );
+  }
+
+  function readOf(key: string): ApiDataResult<FileMetadata> {
+    const known = reads.get(key);
+    if (known) return known;
+    const read = () =>
+      useApiData<FileMetadata>(
+        `dms-file-metadata:${storage ?? ""}:${contentLanguage ?? ""}:${key}`,
+        ({ $authFetch, signal }) =>
+          $authFetch<FileMetadata>(METADATA_URL, {
+            query: { resourceKey: key, storage },
+            headers: contentLanguage
+              ? { [CONTENT_LANGUAGE_HEADER]: contentLanguage }
+              : undefined,
+            signal,
+          }),
+      );
+    const result = scope.run(() => {
+      const started =
+        getCurrentInstance() || !app ? read() : app.runWithContext(read);
+      if (!import.meta.env.SSR) follow(key, started);
+      return started;
+    })!;
+    reads.set(key, result);
+    return result;
+  }
+
+  /**
+   * Reads `key`'s metadata unless it is known; `force` reads it again (to
+   * open a file with a fresh URL).
+   */
+  async function resolve(key: string, force = false): Promise<void> {
+    const result = readOf(key);
+    if (force) await result.refresh({ dedupe: "defer" });
+    else await result;
+  }
+
+  /** The last metadata read for `key`, its URL possibly expired. */
+  const lastRead = (key: string): FileMetadata | undefined =>
+    reads.get(key)?.data.value ?? undefined;
+
+  /**
+   * Whether `key` cannot be shown: its last read failed and the server
+   * refused it for good, or nothing usable is left (never read, or expired).
+   */
+  function isUnavailable(key: string): boolean {
+    const result = reads.get(key);
+    // A failure stays until the next answer: a retry keeps the file marked.
+    if (!result?.error.value) return false;
+    const known = result.data.value;
+    return (
+      !known ||
+      isExpired(known) ||
+      isDefinitiveMetadataFailure(result.error.value)
+    );
+  }
+
+  /** The metadata to show for `key`: read, not expired, still available. */
+  function metadata(key: string): FileMetadata | undefined {
+    const known = lastRead(key);
+    return known && !isExpired(known) && !isUnavailable(key)
+      ? known
+      : undefined;
+  }
+
+  onScopeDispose(() => {
+    scope.stop();
+    timers.forEach(clearTimeout);
+    timers.clear();
+  });
+
+  return { resolve, metadata, lastRead, isUnavailable };
+}