@brftech/filex-core 0.43.2 → 0.44.1

package/src/components/OperationsCenter.vue

@@ -70,6 +70,8 @@ const KIND_ICONS: Record<Operation['kind'], string> = {
   /* An app-plugin job — the puzzle piece its menu row wears (lib/actionIcons). */
   plugin:
     'M9.5 4.5a2 2 0 1 1 4 0h3a1.5 1.5 0 0 1 1.5 1.5v3a2 2 0 1 1 0 4v3a1.5 1.5 0 0 1-1.5 1.5h-3a2 2 0 1 1-4 0h-3A1.5 1.5 0 0 1 5 16v-3a2 2 0 1 1 0-4V6a1.5 1.5 0 0 1 1.5-1.5z',
+  'archive-create': 'M4 8V5h16v3zM5 8h14v12H5zM10 12h4',
+  'archive-extract': 'M4 8V5h16v3zM5 8h14v12H5zM10 12h4',
 };
 
 function kindLabel(o: Operation): string {
@@ -100,6 +102,7 @@ function outputModeTitle(o: Operation): string {
 
 function statusText(o: Operation): string {
   if (o.status === 'running') {
+    if (o.cancelling) return t('opc.cancelling');
     if (o.queued) return t('opc.queued');
     // A plugin job says what it is doing in its own words (`job_progress`
     // message); that beats a bare count.
@@ -107,6 +110,9 @@ function statusText(o: Operation): string {
     if (o.totalBytes && o.totalBytes > 0) {
       return `${formatSize(o.uploadedBytes ?? 0)} / ${formatSize(o.totalBytes)}`;
     }
+    if ((o.kind === 'archive-create' || o.kind === 'archive-extract') && o.percent !== null) {
+      return t('opc.percent', { n: o.percent });
+    }
     if (o.totalCount && o.totalCount > 0) {
       return `${o.doneCount ?? 0}/${o.totalCount}`;
     }

package/src/components/PendingOpsTray.vue

@@ -56,12 +56,12 @@ const emit = defineEmits<{
 
 function mapStatus(op: PendingOp): OperationStatus {
   if (op.status === 'done') return 'done';
-  if (op.status === 'error') return 'error';
   if (op.status === 'cancelled') return 'aborted';
+  if (op.status === 'error') return 'error';
   return 'running'; // pending | running
 }
 
-const DRAWN_KINDS: ReadonlySet<string> = new Set(['copy', 'move', 'delete', 'plugin']);
+const DRAWN_KINDS: ReadonlySet<string> = new Set(['copy', 'move', 'delete', 'plugin', 'archive-create', 'archive-extract']);
 
 /** A queue kind the center can draw. Anything it has no glyph for is shown as
  *  a generic job (`plugin`), never folded into delete. */
@@ -79,6 +79,7 @@ function isPluginJob(op: PendingOp): boolean {
  *  starts — for an administrator. */
 function mayCancel(op: PendingOp): boolean {
   if (op.status !== 'pending' && op.status !== 'running') return false;
+  if (op.op_type === 'archive-create' || op.op_type === 'archive-extract') return op.cancellable;
   if (isPluginJob(op)) return true;
   return op.op_type === 'trash-empty' && props.callerAdmin === true;
 }
@@ -103,6 +104,7 @@ watch(
           error: op.status === 'error' ? failureOf(op).text : null,
           errorDetail: op.status === 'error' ? (failureOf(op).detail ?? null) : null,
           queued: op.status === 'pending',
+          cancelling: op.status === 'cancelling',
           doneCount: op.progress_done,
           totalCount: op.progress_total,
           cancellable: mayCancel(op),
@@ -112,8 +114,8 @@ watch(
           outputMode: (isPluginJob(op) ? props.outputModeOf?.(op) : undefined) ?? null,
         },
         actions: {
-          dismiss: () => emit('dismiss', op.id),
           cancel: () => emit('cancel', op.id),
+          dismiss: () => emit('dismiss', op.id),
           open: (path: string) => emit('open', op.id, path),
         },
       })),

package/src/composables/useFileApi.ts

@@ -21,6 +21,7 @@
  * thinks about CSRF vs Bearer vs Basic — it just calls `index(path)`.
  */
 
+import type { StorageInfo } from '../lib/catalogCoverage';
 import type { ExplorerConfig, AuthConfig, EndpointMap } from '../types/ExplorerConfig';
 import { resolveLocale } from '../locales/resolve';
 import { listingAddress } from '../lib/internalPaths';
@@ -36,6 +37,7 @@ import type {
   UploadLimits,
   Capabilities,
   ArchiveEntry,
+  ArchiveCreateFormat,
   TrashEntry,
 } from '../types/FileNode';
 import type {
@@ -49,14 +51,15 @@ import type {
 /** Server-side PendingOp DTO (mirror of Modules\FishApp\Models\PendingOp::toApiArray). */
 export interface PendingOpDto {
   id: number;
-  op_type: 'copy' | 'move' | 'delete';
-  status: 'pending' | 'running' | 'done' | 'error';
+  op_type: 'copy' | 'move' | 'delete' | 'archive-create' | 'archive-extract';
+  status: 'pending' | 'running' | 'cancelling' | 'done' | 'error' | 'cancelled';
   progress_total: number;
   progress_done: number;
   target_path: string | null;
   source_dir: string | null;
   source_count: number;
   error_message: string | null;
+  cancellable: boolean;
   started_at: string | null;
   finished_at: string | null;
   created_at: string | null;
@@ -94,6 +97,10 @@ export interface ManagerResponse {
    *  list is not the whole answer. Absent on other actions and on servers
    *  older than the flag. */
   truncated?: boolean;
+  /** Every storage the caller can open, with how much of it the catalog
+   *  covers (`coverage`, absent when all of it — lib/catalogCoverage). Absent
+   *  on servers older than the lazy catalog. */
+  storage_info?: StorageInfo[];
 }
 
 /** A single ACL grant row (RBAC permissions panel). */
@@ -256,6 +263,7 @@ export function resolveEndpoints(config: ExplorerConfig): EndpointMap {
     capabilities: derive(config.capabilities, '/api/files/capabilities'),
     archiveList: derive(config.archiveList, '/api/files/archive/list'),
     archiveExtract: derive(config.archiveExtract, '/api/files/archive/extract'),
+    archiveCreate: derive(config.archiveCreate, '/api/files/archive/create'),
     archiveAdd: derive(config.archiveAdd, '/api/files/archive/add'),
     copy: derive(config.copy, '/api/files/copy'),
     moveAsync: derive(config.moveAsync, '/api/files/move'),
@@ -979,14 +987,14 @@ export function useFileApi(config: ExplorerConfig) {
     return jsonFetch(url, { method: 'DELETE' });
   }
 
-  async function archiveList(path: string): Promise<{ entries: ArchiveEntry[] }> {
+  async function archiveList(path: string, password?: string): Promise<{ entries: ArchiveEntry[] }> {
     if (!endpoints.archiveList) throw new Error('archiveList endpoint not configured');
     const raw = await jsonFetch<{ entries: Array<{ name: string; size: number; is_dir: boolean; mtime?: number }> }>(
       endpoints.archiveList,
       {
         method: 'POST',
         headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify({ path }),
+        body: JSON.stringify({ path, password }),
       },
     );
     return {
@@ -999,12 +1007,33 @@ export function useFileApi(config: ExplorerConfig) {
     };
   }
 
-  async function archiveExtract(path: string, members?: string[]): Promise<{ keys: string[]; count: number }> {
+  async function archiveExtract(
+    path: string,
+    options: { members?: string[]; password?: string; dest?: string } = {},
+  ): Promise<{ op?: PendingOpDto; keys?: string[]; count?: number }> {
     if (!endpoints.archiveExtract) throw new Error('archiveExtract endpoint not configured');
     return jsonFetch(endpoints.archiveExtract, {
       method: 'POST',
       headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify({ path, members }),
+      body: JSON.stringify({ path, ...options }),
+    });
+  }
+
+  async function archiveCreate(payload: {
+    dest: string;
+    sources: string[];
+    format: ArchiveCreateFormat;
+    password?: string;
+    encrypt_filenames?: boolean;
+    compression?: number;
+    solid?: boolean;
+    dictionary_size_mb?: number;
+  }): Promise<{ op: PendingOpDto }> {
+    if (!endpoints.archiveCreate) throw new Error('archiveCreate endpoint not configured');
+    return jsonFetch(endpoints.archiveCreate, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(payload),
     });
   }
 
@@ -1147,6 +1176,7 @@ export function useFileApi(config: ExplorerConfig) {
     revokeShare,
     archiveList,
     archiveExtract,
+    archiveCreate,
     archiveAdd,
     // Version history (koru:k1 inspector)
     listVersions,

package/src/composables/useLocale.ts

@@ -536,6 +536,30 @@ export function useLocale(
     });
   }
 
+  /**
+   * A listed item's size, the way every view draws it (list, inspector,
+   * multi-selection total).
+   *
+   * ⚠ `size_partial` is the server saying the catalog does not cover all of a
+   * folder yet (docs/LAZY-CATALOGUE.md): a lazily cataloged folder that is not
+   * cataloged below, or any folder while its storage's first sync runs. Its
+   * size is then a lower bound — "≥ 1.2 GB" — or, when nothing below it is
+   * known, not a number at all ("—"): printing "0 B" for a folder full of
+   * files nobody has cataloged yet would be a fact that is false. One helper,
+   * so the list and the inspector cannot disagree about it.
+   */
+  function formatNodeSize(n: { size?: number | null; size_partial?: boolean } | null | undefined): string {
+    if (!n) return formatSize(null);
+    if (!n.size_partial) return formatSize(n.size);
+    return typeof n.size === 'number' && n.size > 0 ? t('size.at_least', { size: formatSize(n.size) }) : '—';
+  }
+
+  /** The hover text of a size `formatNodeSize` drew as partial, or undefined. */
+  function nodeSizeHint(n: { size?: number | null; size_partial?: boolean } | null | undefined): string | undefined {
+    if (!n?.size_partial) return undefined;
+    return typeof n.size === 'number' && n.size > 0 ? t('size.partial_hint') : t('size.unknown_hint');
+  }
+
   /**
    * Render a FileNode's basename with locale-aware overrides:
    *   - `.trash` directory → "Çöp Kutusu" / "Trash"
@@ -627,6 +651,8 @@ export function useLocale(
   return {
     t,
     formatSize,
+    formatNodeSize,
+    nodeSizeHint,
     formatDate,
     formatDateFull,
     formatMonthYear,

package/src/composables/useOperations.ts

@@ -27,7 +27,9 @@ import { computed, getCurrentScope, onScopeDispose, ref } from 'vue';
 
 /** `plugin` — an app-plugin job (docs/APP-PLUGINS-API.md); also what any
  *  queue kind this package has no drawing for is shown as. */
-export type OperationKind = 'upload' | 'copy' | 'move' | 'delete' | 'convert' | 'archive' | 'plugin' | 'trash';
+export type OperationKind =
+  | 'upload' | 'copy' | 'move' | 'delete' | 'convert'
+  | 'archive' | 'archive-create' | 'archive-extract' | 'plugin' | 'trash';
 export type OperationStatus = 'running' | 'done' | 'error' | 'aborted';
 
 /** What a publisher hands to `sync()` for one row. */
@@ -47,6 +49,8 @@ export interface OperationInput {
   errorDetail?: string | null;
   /** Queue op accepted but not started yet ("Queued"). */
   queued?: boolean;
+  /** Cancellation was accepted and the worker is stopping/cleaning up. */
+  cancelling?: boolean;
   /** Progress counters for queue ops (3/5 items). */
   doneCount?: number;
   totalCount?: number;
@@ -90,6 +94,7 @@ export interface Operation {
   error: string | null;
   errorDetail: string | null;
   queued: boolean;
+  cancelling: boolean;
   doneCount: number | null;
   totalCount: number | null;
   uploadedBytes: number | null;
@@ -117,6 +122,7 @@ function toOperation(key: string, input: OperationInput, prev?: Operation): Oper
     error: input.error ?? null,
     errorDetail: input.errorDetail ?? null,
     queued: input.queued ?? false,
+    cancelling: input.cancelling ?? false,
     doneCount: input.doneCount ?? null,
     totalCount: input.totalCount ?? null,
     uploadedBytes: input.uploadedBytes ?? null,

package/src/composables/usePendingOps.ts

@@ -33,7 +33,7 @@ export interface PendingOp {
   id: number;
   op_type: PendingOpType;
   /** `cancelled` — somebody stopped it (POST /ops/{id}/cancel). */
-  status: 'pending' | 'running' | 'done' | 'error' | 'cancelled';
+  status: 'pending' | 'running' | 'cancelling' | 'done' | 'error' | 'cancelled';
   progress_total: number;
   progress_done: number;
   /** Running cross-storage transfer's bytes (issue #27); absent otherwise. */
@@ -48,6 +48,7 @@ export interface PendingOp {
   error_code?: string;
   /** The engine a job needed and the server lacks (`error_code: engine_missing`). */
   error_engine?: string;
+  cancellable: boolean;
   started_at: string | null;
   finished_at: string | null;
   created_at: string | null;
@@ -94,9 +95,11 @@ export function normalizeOp(raw: Record<string, unknown>): PendingOp {
         ? 'error'
         : rawStatus === 'cancelled'
           ? 'cancelled'
-          : rawStatus === 'running'
-            ? 'running'
-            : 'pending';
+          : rawStatus === 'cancelling'
+            ? 'cancelling'
+            : rawStatus === 'running'
+              ? 'running'
+              : 'pending';
   const sources = Array.isArray(raw.sources) ? raw.sources : [];
   // ⚠ Unknown kinds pass through. This used to fold everything that was not
   // copy/move into `delete`, which drew a bin beside a plugin job and read
@@ -124,6 +127,7 @@ export function normalizeOp(raw: Record<string, unknown>): PendingOp {
     error_message: str(raw.error_message, raw.error),
     error_code: str(raw.error_code) ?? undefined,
     error_engine: str(raw.error_engine) ?? undefined,
+    cancellable: raw.cancellable === true,
     started_at: str(raw.started_at),
     finished_at: str(raw.finished_at),
     created_at: str(raw.created_at),
@@ -155,7 +159,7 @@ export function usePendingOps(
   let firstPollDone = false;
 
   const hasActive = computed(() =>
-    ops.value.some((o) => o.status === 'pending' || o.status === 'running'),
+    ops.value.some((o) => o.status === 'pending' || o.status === 'running' || o.status === 'cancelling'),
   );
 
   let timer: ReturnType<typeof setInterval> | undefined;
@@ -197,7 +201,7 @@ export function usePendingOps(
       // is currently seeing them in the local tray.
       const localIds = new Set(ops.value.map((o) => o.id));
       const visibleIncoming = incoming.filter((op) => {
-        if (op.status === 'pending' || op.status === 'running') return true;
+        if (op.status === 'pending' || op.status === 'running' || op.status === 'cancelling') return true;
         if (!firstPollDone) return false;
         return localIds.has(op.id);
       });
@@ -211,7 +215,7 @@ export function usePendingOps(
       // Sweep: drop terminal ops past RETAIN_MS.
       const now = Date.now();
       const after = merged.filter((o) => {
-        if (o.status === 'pending' || o.status === 'running') return true;
+        if (o.status === 'pending' || o.status === 'running' || o.status === 'cancelling') return true;
         const at = settledAt.get(o.id);
         return at !== undefined && now - at < RETAIN_MS;
       });

package/src/index.ts

@@ -32,6 +32,17 @@ export { default as StarButton } from './components/StarButton.vue';
 export { default as TagPicker } from './components/TagPicker.vue';
 export { default as TagKindIcon } from './components/TagKindIcon.vue';
 export { tagItemsOf, tagKey, isTagKind, type TagItem, type TagKind } from './lib/tags';
+export {
+  coverageByStorage,
+  coverageMessage,
+  coverageNotice,
+  coveragePercent,
+  incomplete as coverageIncomplete,
+  type CatalogCoverage,
+  type CoverageNotice,
+  type CoverageReason,
+  type StorageInfo,
+} from './lib/catalogCoverage';
 // tablo:t3 — the row's ONE action control ("Actions" / "Aksiyon"). DataTable
 // draws it for every table (`rowActions`); it stays exported for a host that
 // needs the same control outside a table. A second menu built beside
@@ -333,6 +344,10 @@ export type { NavApp } from './components/SideNav.vue';
 export { opPercent } from './lib/opProgress';
 export type { OpProgressLike } from './lib/opProgress';
 
+/* #48 — how an archive format is written (ZIP, TAR.GZ, 7z), for the explorer's
+ * create dialog and a host's own archive settings alike. */
+export { archiveFormatLabel } from './lib/archiveFormats';
+
 /* tasi:m1 — "download the selection as one archive". Exported so a host that
  * draws its own selection bar gets the real two-step flow (authorized mint,
  * then a navigation that streams) instead of reaching for window.open per

package/src/lib/actionIcons.ts

@@ -66,6 +66,12 @@ const GLYPHS: Record<string, string> = {
     '<path d="M9.5 4.5v5"/>',
   preview: EYE,
   download: TRAY + '<path d="M12 4v11.5"/><path d="M7.5 11L12 15.5 16.5 11"/>',
+  'archive-create':
+    '<path d="M5 8.5h14v11H5z"/><path d="M4 4h16v4.5H4z"/>' +
+    '<path d="M12 11v5"/><path d="M9.5 13.5h5"/>',
+  'archive-extract':
+    '<path d="M5 8.5h14v11H5z"/><path d="M4 4h16v4.5H4z"/>' +
+    '<path d="M12 10.5v6"/><path d="M9.5 14l2.5 2.5 2.5-2.5"/>',
   upload:
     '<path d="M4.5 15.5v3A2 2 0 0 0 6.5 20.5h11a2 2 0 0 0 2-2v-3"/>' +
     '<path d="M12 15.5V4"/><path d="M7.5 8.5L12 4l4.5 4.5"/>',

package/src/lib/archiveFormats.ts

@@ -0,0 +1,12 @@
+/**
+ * archiveFormatLabel — how an archive format is written wherever a person
+ * reads it: the create dialog, the admin Archives page, its provider cards.
+ *
+ * Upper case (ZIP, TAR.GZ, RAR), except 7z, which its own project writes in
+ * lower case. One rule in one place: the dialog wrote "7z" while the admin
+ * page wrote "7Z" for the same format (measured, 0.44.0 integration of #48).
+ */
+export function archiveFormatLabel(format: string): string {
+  const f = format.trim().toLowerCase();
+  return f === '7z' ? '7z' : f.toUpperCase();
+}

package/src/lib/archivePreviewCache.ts

@@ -0,0 +1,61 @@
+export interface CachedArchiveEntry {
+  name: string;
+  size: number;
+  mtime?: string;
+  is_dir?: boolean;
+}
+
+export interface ArchivePreviewCache {
+  recall(path: string): CachedArchiveEntry[] | undefined;
+  remember(path: string, entries: CachedArchiveEntry[]): void;
+  forget(path: string): void;
+  clear(): void;
+}
+
+export const ARCHIVE_PREVIEW_CACHE_TTL_MS = 2 * 60 * 1000;
+
+export function createArchivePreviewCache(
+  ttlMs = ARCHIVE_PREVIEW_CACHE_TTL_MS,
+  now: () => number = Date.now,
+): ArchivePreviewCache {
+  type Cached = {
+    entries: CachedArchiveEntry[];
+    expiresAt: number;
+    timer: ReturnType<typeof setTimeout>;
+  };
+  const values = new Map<string, Cached>();
+
+  function forget(path: string): void {
+    const cached = values.get(path);
+    if (cached) clearTimeout(cached.timer);
+    values.delete(path);
+  }
+
+  return {
+    recall(path) {
+      const cached = values.get(path);
+      if (!cached) return undefined;
+      if (cached.expiresAt <= now()) {
+        forget(path);
+        return undefined;
+      }
+      return cached.entries.map((entry) => ({ ...entry }));
+    },
+    remember(path, entries) {
+      forget(path);
+      const cached: Cached = {
+        entries: entries.map((entry) => ({ ...entry })),
+        expiresAt: now() + ttlMs,
+        timer: setTimeout(() => {
+          if (values.get(path) === cached) values.delete(path);
+        }, ttlMs),
+      };
+      values.set(path, cached);
+    },
+    forget,
+    clear() {
+      for (const cached of values.values()) clearTimeout(cached.timer);
+      values.clear();
+    },
+  };
+}

package/src/lib/catalogCoverage.ts

@@ -0,0 +1,137 @@
+/**
+ * catalogCoverage — how much of a storage its catalog covers, as the server
+ * says it, and the one set of rules every view draws that by.
+ *
+ * filex keeps a catalog of every storage, and search, folder sizes and drive
+ * usage are answered from it. While it does not cover a storage in full the
+ * server says so (docs/LAZY-CATALOGUE.md → "Coverage in the UI"):
+ *
+ *   - `first_scan`   — any storage whose first sync has not finished;
+ *   - `lazy_filling` — a lazily cataloged storage whose background pass is
+ *                      still going (behaviour A);
+ *   - `lazy_on_open` — a lazily cataloged storage that catalogs only the
+ *                      folders people open (behaviour B).
+ *
+ * The listing and search responses carry it per storage in `storage_info`,
+ * drive usage per row. A folder row whose own size leaves something out
+ * carries `size_partial` (see useLocale `formatNodeSize`).
+ *
+ * ⚠ One module for the whole explorer: the banner over a listing, the banner
+ * over search results and Home's drive cards read the SAME object through the
+ * SAME rules, so they cannot tell a person two different things about one
+ * storage.
+ */
+
+/** Why a storage's catalog is not complete. */
+export type CoverageReason = 'first_scan' | 'lazy_filling' | 'lazy_on_open';
+
+/** The server's `coverage` object (sync.CatalogueCoverage). */
+export interface CatalogCoverage {
+  complete: boolean;
+  reason?: CoverageReason | string;
+  /** `lazy` for a lazily cataloged storage. */
+  mode?: string;
+  /** The lazy behaviour: `background` (A) or `on_open` (B). */
+  fill?: string;
+  catalogued_folders?: number;
+  pending_folders?: number;
+  watched_folders?: number;
+  max_watches?: number;
+  filler?: string;
+  held_back_folders?: number;
+  reconciles?: number;
+}
+
+/** One entry of a listing's `storage_info`. */
+export interface StorageInfo {
+  name: string;
+  read_only?: boolean;
+  coverage?: CatalogCoverage | null;
+}
+
+/** A coverage object worth telling anybody about, or null. */
+export function incomplete(c: CatalogCoverage | null | undefined): CatalogCoverage | null {
+  if (!c || typeof c !== 'object' || c.complete === true) return null;
+  return c;
+}
+
+/**
+ * The share of the folders found so far that are cataloged, 0–99 while any
+ * is still waiting (a floor, so "100%" is never shown beside a notice that
+ * says the work is not done).
+ */
+export function coveragePercent(c: CatalogCoverage): number {
+  const done = Math.max(0, c.catalogued_folders ?? 0);
+  const pending = Math.max(0, c.pending_folders ?? 0);
+  if (done + pending === 0) return 0;
+  const pct = Math.floor((done * 100) / (done + pending));
+  return pending > 0 ? Math.min(pct, 99) : pct;
+}
+
+/** The sentence one storage's coverage is told in: a catalog key and its values. */
+export function coverageMessage(c: CatalogCoverage): { key: string; vars: Record<string, number> } {
+  switch (c.reason) {
+    case 'lazy_on_open':
+      return { key: 'coverage.lazy_on_open', vars: {} };
+    case 'lazy_filling':
+      return { key: 'coverage.lazy_filling', vars: { pct: coveragePercent(c) } };
+    default:
+      return { key: 'coverage.first_scan', vars: {} };
+  }
+}
+
+/** `storage_info` → storage name → its incomplete coverage (null = complete). */
+export function coverageByStorage(info: unknown): Record<string, CatalogCoverage | null> {
+  const out: Record<string, CatalogCoverage | null> = {};
+  if (!Array.isArray(info)) return out;
+  for (const row of info as StorageInfo[]) {
+    if (!row || typeof row.name !== 'string' || row.name === '') continue;
+    out[row.name] = incomplete(row.coverage ?? null);
+  }
+  return out;
+}
+
+/** What the banner over a listing or a search says, and whether it offers an action. */
+export interface CoverageNotice {
+  key: string;
+  vars: Record<string, string | number>;
+  /** The storage the notice is about, when it is about one. */
+  storage?: string;
+  /** Offer "Catalog everything" (an administrator, behaviour B). */
+  offerCatalogAll: boolean;
+}
+
+/**
+ * The notice for what is on screen.
+ *
+ *   - A listing, or a search inside one storage: that storage's coverage.
+ *   - A search that spans every storage (the server searches them all when
+ *     the query is typed at a storage's root and there is more than one):
+ *     the names of the ones not fully cataloged.
+ *
+ * `admin` decides the action only; everybody reads the same sentence.
+ */
+export function coverageNotice(opts: {
+  map: Record<string, CatalogCoverage | null>;
+  adapter: string;
+  searching: boolean;
+  crossStorage: boolean;
+  admin: boolean;
+}): CoverageNotice | null {
+  const { map, adapter, searching, crossStorage, admin } = opts;
+  if (searching && crossStorage) {
+    const names = Object.keys(map)
+      .filter((n) => map[n] !== null)
+      .sort((a, b) => a.localeCompare(b));
+    if (names.length === 0) return null;
+    if (names.length === 1) return single(names[0], map[names[0]] as CatalogCoverage, admin);
+    return { key: 'coverage.search_some', vars: { names: names.join(', ') }, offerCatalogAll: false };
+  }
+  const c = map[adapter];
+  return c ? single(adapter, c, admin) : null;
+}
+
+function single(storage: string, c: CatalogCoverage, admin: boolean): CoverageNotice {
+  const m = coverageMessage(c);
+  return { key: m.key, vars: m.vars, storage, offerCatalogAll: admin && c.reason === 'lazy_on_open' };
+}