@brftech/filex-core 0.42.1 → 0.43.0

package/src/composables/usePendingOps.ts

@@ -17,10 +17,23 @@ import { computed, ref, onBeforeUnmount } from 'vue';
 import type { ExplorerConfig } from '../types/ExplorerConfig';
 import type { FileApi } from './useFileApi';
 
+/**
+ * The queue kinds this package knows by name. A server may emit others (an
+ * app-plugin job is `plugin-action` on the wire and `plugin` here); anything
+ * unknown is carried through verbatim rather than being read as a delete.
+ */
+export type PendingOpType = 'copy' | 'move' | 'delete' | 'plugin' | 'trash-empty' | (string & {});
+
+/** One produced file of a finished plugin job, as an adapter-qualified path. */
+export interface PendingOpOutput {
+  path: string;
+}
+
 export interface PendingOp {
   id: number;
-  op_type: 'copy' | 'move' | 'delete';
-  status: 'pending' | 'running' | 'done' | 'error';
+  op_type: PendingOpType;
+  /** `cancelled` — somebody stopped it (POST /ops/{id}/cancel). */
+  status: 'pending' | 'running' | 'done' | 'error' | 'cancelled';
   progress_total: number;
   progress_done: number;
   /** Running cross-storage transfer's bytes (issue #27); absent otherwise. */
@@ -30,9 +43,24 @@ export interface PendingOp {
   source_dir: string | null;
   source_count: number;
   error_message: string | null;
+  /** A failed APP job, classified by the server (lib/errorWords `jobFailure`
+   *  says it); absent on copy/move/delete rows and on an older server. */
+  error_code?: string;
+  /** The engine a job needed and the server lacks (`error_code: engine_missing`). */
+  error_engine?: string;
   started_at: string | null;
   finished_at: string | null;
   created_at: string | null;
+  /* App-plugin jobs (`op_type: "plugin-action"` on the wire) — absent on
+   * copy/move/delete rows. See docs/APP-PLUGINS-API.md → Ops rows. */
+  plugin?: string;
+  action?: string;
+  /** The action's label in the caller's locale — the tray's row title. */
+  label?: string;
+  /** The last `job_progress` message. */
+  message?: string;
+  /** Files the job committed, once finished. */
+  outputs?: PendingOpOutput[];
 }
 
 const POLL_MS = 2000;
@@ -46,7 +74,7 @@ const RETAIN_MS = 8000;
  * running op (progress_* were undefined) and never treated an 'ok'/'failed'
  * row as terminal. Tolerant of an already-normalized shape (idempotent).
  */
-function normalizeOp(raw: Record<string, unknown>): PendingOp {
+export function normalizeOp(raw: Record<string, unknown>): PendingOp {
   const num = (...vals: unknown[]): number => {
     for (const v of vals) if (typeof v === 'number') return v;
     return 0;
@@ -56,19 +84,35 @@ function normalizeOp(raw: Record<string, unknown>): PendingOp {
     return null;
   };
   const rawStatus = String(raw.status ?? 'pending');
+  // ⚠ `cancelled` is an ending of its own. It used to fall through to
+  // 'pending', so a job somebody cancelled sat in the operations centre as
+  // "Queued" for as long as the list still carried the row.
   const status: PendingOp['status'] =
     rawStatus === 'ok' || rawStatus === 'done'
       ? 'done'
       : rawStatus === 'failed' || rawStatus === 'partial' || rawStatus === 'error'
         ? 'error'
-        : rawStatus === 'running'
-          ? 'running'
-          : 'pending';
+        : rawStatus === 'cancelled'
+          ? 'cancelled'
+          : 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
+  // "Deleted (1)" when it finished. `plugin-action` (the wire name) becomes
+  // `plugin`; a row with no kind at all is the one case still read as delete
+  // (the legacy delete endpoint's rows carried none).
   const opType = str(raw.op_type, raw.kind) ?? 'delete';
+  const outputs = Array.isArray(raw.outputs)
+    ? (raw.outputs as unknown[])
+        .map((o) => (o && typeof o === 'object' ? str((o as { path?: unknown }).path) : null))
+        .filter((p): p is string => p !== null)
+        .map((path) => ({ path }))
+    : undefined;
   return {
     id: num(raw.id),
-    op_type: (opType === 'copy' || opType === 'move' ? opType : 'delete') as PendingOp['op_type'],
+    op_type: opType === 'plugin-action' ? 'plugin' : opType,
     status,
     progress_total: num(raw.progress_total, raw.total, sources.length),
     progress_done: num(raw.progress_done, raw.done),
@@ -78,9 +122,16 @@ function normalizeOp(raw: Record<string, unknown>): PendingOp {
     source_dir: str(raw.source_dir),
     source_count: num(raw.source_count, sources.length),
     error_message: str(raw.error_message, raw.error),
+    error_code: str(raw.error_code) ?? undefined,
+    error_engine: str(raw.error_engine) ?? undefined,
     started_at: str(raw.started_at),
     finished_at: str(raw.finished_at),
     created_at: str(raw.created_at),
+    plugin: str(raw.plugin) ?? undefined,
+    action: str(raw.action) ?? undefined,
+    label: str(raw.label) ?? undefined,
+    message: str(raw.message) ?? undefined,
+    outputs,
   };
 }
 
@@ -133,7 +184,7 @@ export function usePendingOps(
       const incoming = (res.ops || []).map(normalizeOp);
 
       for (const op of incoming) {
-        if ((op.status === 'done' || op.status === 'error') && !announced.has(op.id)) {
+        if ((op.status === 'done' || op.status === 'error' || op.status === 'cancelled') && !announced.has(op.id)) {
           announced.add(op.id);
           settledAt.set(op.id, Date.now());
           if (firstPollDone) {

package/src/composables/usePluginActions.ts

@@ -0,0 +1,121 @@
+/**
+ * usePluginActions — the file-menu rows app plugins add, and how to run one.
+ *
+ * `GET /api/files/plugins/actions` is fetched once per endpoint URL and
+ * shared by every explorer instance on the page (the admin explorer, a split
+ * pane, an embedded web component all ask the same server), and re-asked
+ * after five minutes — the contract's client cache. Nothing is requested
+ * until `enabled()` says so: with `capabilities.app_plugins.enabled` false the
+ * explorer makes zero plugin calls.
+ *
+ * The composable holds no menu logic of its own: which rows a selection gets
+ * is `lib/pluginMenu`, the rule is `lib/pluginApplies`, both pure.
+ */
+import { computed, ref, watch, type Ref } from 'vue';
+import type { FileApi } from './useFileApi';
+import type { FileNode } from '../types/FileNode';
+import type { PluginActionRow, PluginActionsResponse, PluginRunResult, PluginViewRow } from '../types/Plugins';
+import { pluginActionsFor, pluginActionKey } from '../lib/pluginMenu';
+
+export const PLUGIN_ACTIONS_TTL_MS = 5 * 60 * 1000;
+
+interface CacheEntry {
+  at: number;
+  data: Ref<PluginActionsResponse>;
+  inflight: Promise<PluginActionsResponse> | null;
+}
+
+/** One entry per actions URL, shared across every instance on the page. */
+const cache = new Map<string, CacheEntry>();
+
+/** Forget every cached answer — tests, and a host that just installed a plugin. */
+export function invalidatePluginActions(): void {
+  cache.clear();
+}
+
+function entryFor(url: string): CacheEntry {
+  let e = cache.get(url);
+  if (!e) {
+    e = { at: 0, data: ref<PluginActionsResponse>({ actions: [], views: [] }), inflight: null };
+    cache.set(url, e);
+  }
+  return e;
+}
+
+export function usePluginActions(api: FileApi, enabled: () => boolean) {
+  const url = api.endpoints.pluginActions ?? '';
+  const entry = entryFor(url || '(none)');
+  const loaded = ref(false);
+  const error = ref<string | null>(null);
+
+  const isEnabled = computed(() => enabled() && url !== '');
+
+  const actions = computed<PluginActionRow[]>(() => (isEnabled.value ? entry.data.value.actions : []));
+  const views = computed<PluginViewRow[]>(() => (isEnabled.value ? entry.data.value.views : []));
+
+  /** Fetch (or reuse the shared answer) — a no-op while the feature is off. */
+  async function refresh(force = false): Promise<PluginActionsResponse> {
+    if (!isEnabled.value) return { actions: [], views: [] };
+    const fresh = entry.at > 0 && Date.now() - entry.at < PLUGIN_ACTIONS_TTL_MS;
+    if (fresh && !force) {
+      loaded.value = true;
+      return entry.data.value;
+    }
+    if (entry.inflight) return entry.inflight;
+    entry.inflight = api
+      .pluginActions()
+      .then((res) => {
+        entry.data.value = { actions: res.actions ?? [], views: res.views ?? [] };
+        entry.at = Date.now();
+        error.value = null;
+        return entry.data.value;
+      })
+      .catch((e: unknown) => {
+        error.value = String((e as Error)?.message ?? e);
+        return entry.data.value;
+      })
+      .finally(() => {
+        entry.inflight = null;
+        loaded.value = true;
+      });
+    return entry.inflight;
+  }
+
+  // The first time the feature turns on (capabilities answered), ask once.
+  watch(
+    isEnabled,
+    (on) => {
+      if (on) void refresh();
+    },
+    { immediate: true },
+  );
+
+  /** Action rows whose rule accepts this selection. */
+  function actionsFor(selection: FileNode[]): PluginActionRow[] {
+    return pluginActionsFor(actions.value, selection);
+  }
+
+  /** The action row behind a menu key, if any. */
+  function byKey(key: string): PluginActionRow | undefined {
+    return actions.value.find((a) => pluginActionKey(a) === key);
+  }
+
+  /**
+   * Run an action on wire paths. `{op}` when the server queued a job, or
+   * `{surface}` when the action opens a view first.
+   */
+  function run(
+    action: PluginActionRow,
+    targets: FileNode[],
+    params?: Record<string, unknown>,
+  ): Promise<PluginRunResult> {
+    return api.pluginActionRun(action.plugin, action.id, {
+      paths: targets.map((n) => n.path),
+      params,
+    });
+  }
+
+  return { enabled: isEnabled, actions, views, loaded, error, refresh, actionsFor, byKey, run };
+}
+
+export type PluginActionsStore = ReturnType<typeof usePluginActions>;

package/src/composables/usePluginSurface.ts

@@ -0,0 +1,223 @@
+/**
+ * usePluginSurface — one plugin view's conversation with the server.
+ *
+ * A `modal` view (PluginViewModal) and an `inspector` section
+ * (PluginInspectorSection) draw the same kind of screen and post the same
+ * events; what differs is only the frame around it. So the conversation
+ * lives here, once: the current surface, the values its nodes hold, the
+ * debounced `change`, the footer press, the list row action, and what an
+ * answer does — a new screen, a toast, `done`, or `{op}` (the server queued
+ * a job; the caller registers the row and closes).
+ *
+ * Values: seeded from every fresh surface (`lib/surfaceValues.initialValues`),
+ * replaced as the components edit them, and sent whole on every event as
+ * `data.values`. After a `change` answer the person's current entries WIN
+ * over the echo — they may have typed more while the request was out.
+ */
+import { computed, getCurrentInstance, onBeforeUnmount, ref } from 'vue';
+import type { FileApi } from './useFileApi';
+import type {
+  PluginSurface,
+  PluginViewEventBody,
+  PluginViewEventData,
+  SurfaceAction,
+  SurfaceOpenRequest,
+} from '../types/Plugins';
+import { foreignText } from '../lib/direction';
+import { isOpenRequest } from '../lib/surfaceOpen';
+import { labelOf } from '../lib/pluginLabel';
+import { initialValues } from '../lib/surfaceValues';
+import { missingRequired, stripHiddenValues } from '../lib/surfaceConditions';
+
+/** The contract's debounce for `form` edits → `event: "change"`. */
+export const SURFACE_CHANGE_DEBOUNCE_MS = 300;
+
+export interface PluginSurfaceHost {
+  api: Pick<FileApi, 'pluginViewEvent'>;
+  plugin: string;
+  view: string;
+  /** Adapter-qualified path the view was opened on — echoed on every event. */
+  path?: () => string | undefined;
+  locale: () => string;
+  /** The words for an answer without a surface. */
+  errorText: () => string;
+}
+
+export interface PluginSurfaceEvents {
+  /** The server enqueued a job: the raw ops row. */
+  onOp: (op: Record<string, unknown>) => void;
+  /** The conversation is over (`done`, or after `{op}`). */
+  onDone: () => void;
+  onToast: (message: string) => void;
+  /**
+   * v3 §3.0 — the answer says "go to this file" (`lib/surfaceOpen`).
+   *
+   * ⚠ Raised AFTER `onDone` when the answer also carries `done: true`: the
+   * screen that asked for the navigation is closed first, or the person
+   * arrives at the new one with the old one still over it.
+   *
+   * ⚠ A frame with nowhere to navigate (a public page has no explorer
+   * behind it) simply does not pass this in, and the request is dropped.
+   */
+  onOpen?: (req: SurfaceOpenRequest) => void;
+}
+
+export function usePluginSurface(host: PluginSurfaceHost, events: PluginSurfaceEvents) {
+  const current = ref<PluginSurface | null>(null);
+  const values = ref<Record<string, unknown>>({});
+  const busy = ref(false);
+  const failure = ref('');
+  /**
+   * v3 §2.1 — the visible, required fields a blocked submit is waiting for.
+   *
+   * ⚠ Pointed at, not merely refused. A submit that does nothing and says
+   * nothing is the worst of the three possible behaviours; this list is what
+   * puts the star and the "required" line on the fields themselves.
+   */
+  const invalidKeys = ref<string[]>([]);
+
+  const footer = computed<SurfaceAction[]>(() => current.value?.actions ?? []);
+  const errors = computed(() => current.value?.errors);
+
+  /** A new screen. `keepValues` overlays what the person already entered. */
+  function setSurface(s: PluginSurface | null, keepValues = false): void {
+    current.value = s;
+    failure.value = '';
+    invalidKeys.value = [];
+    const seeded = initialValues(s?.nodes);
+    values.value = keepValues ? { ...seeded, ...values.value } : seeded;
+  }
+
+  function updateValues(v: Record<string, unknown>): void {
+    values.value = v;
+    // Answering one of them clears its mark as it is typed, rather than on
+    // the next press: a field that has been filled must not stay red.
+    if (invalidKeys.value.length) {
+      const still = missingRequired(current.value?.nodes, v).map((f) => f.key);
+      if (still.length !== invalidKeys.value.length) invalidKeys.value = still;
+    }
+  }
+
+  let changeTimer: ReturnType<typeof setTimeout> | null = null;
+  function cancelChange(): void {
+    if (changeTimer !== null) clearTimeout(changeTimer);
+    changeTimer = null;
+  }
+  /** A form edit: one `change` event 300 ms after the last keystroke. */
+  function scheduleChange(): void {
+    cancelChange();
+    changeTimer = setTimeout(() => {
+      changeTimer = null;
+      void post('change');
+    }, SURFACE_CHANGE_DEBOUNCE_MS);
+  }
+
+  let seq = 0;
+
+  async function post(
+    event: PluginViewEventBody['event'],
+    actionId?: string,
+    extra: Omit<PluginViewEventData, 'values'> = {},
+  ): Promise<void> {
+    if (!current.value) return;
+    const blocking = event !== 'change';
+    if (blocking) {
+      cancelChange();
+      if (busy.value) return;
+      busy.value = true;
+    }
+    const mine = ++seq;
+    failure.value = '';
+    try {
+      const res = await host.api.pluginViewEvent(host.plugin, host.view, {
+        path: host.path?.(),
+        state: current.value?.state ?? {},
+        event,
+        action_id: actionId,
+        // ⚠⚠ The values a HIDDEN field holds are dropped here, not blanked
+        // (v3 §2.1: "a value belonging to a hidden field is dropped before
+        // the job runs — it cannot arrive as a surprise"). The plugin is
+        // re-asked the same question by the host at submit; this is the
+        // client half of the same promise, and it also keeps a `change`
+        // event from echoing back a field the step no longer shows.
+        data: { values: stripHiddenValues(current.value?.nodes, values.value), ...extra },
+      });
+      // A `change` answer that arrives after a later event started is stale:
+      // the later event's answer is the screen that counts.
+      if (!blocking && mine !== seq) return;
+      if (res.op) {
+        events.onOp(res.op);
+        events.onDone();
+        return;
+      }
+      const next = res.surface;
+      if (!next) {
+        failure.value = host.errorText();
+        return;
+      }
+      const toast = labelOf(next.toast, host.locale());
+      if (toast) events.onToast(toast);
+      // ⚠ The order is the contract's: `done` closes the screen, and only
+      // then does the navigation happen. Reversed, the person lands on the
+      // new screen with the finished one still drawn over it.
+      const go = isOpenRequest(next.open) ? next.open : null;
+      if (next.done) {
+        events.onDone();
+        if (go) events.onOpen?.(go);
+        return;
+      }
+      setSurface(next, !blocking);
+      if (go) events.onOpen?.(go);
+    } catch (e) {
+      if (!blocking && mine !== seq) return;
+      // ⚠ An app's own error text never met the catalogue — isolate it.
+      failure.value = foreignText(host.locale(), String((e as Error)?.message ?? e)) || host.errorText();
+    } finally {
+      if (blocking) busy.value = false;
+    }
+  }
+
+  /**
+   * A footer button: `submit` when it is the primary one, `action` otherwise.
+   *
+   * ⚠ A submit is refused locally while a visible, required field is empty.
+   * The server refuses it too — that is the boundary — but a round trip to
+   * be told "this is required" about a box that is on the screen is a round
+   * trip the person should not have to make.
+   */
+  function press(a: SurfaceAction): Promise<void> {
+    if (busy.value || a.disabled) return Promise.resolve();
+    if (a.primary) {
+      const missing = missingRequired(current.value?.nodes, values.value);
+      invalidKeys.value = missing.map((f) => f.key);
+      if (missing.length) return Promise.resolve();
+    }
+    return post(a.primary ? 'submit' : 'action', a.id);
+  }
+
+  /** A `list` row's button. */
+  function rowAction(p: { action_id: string; row_id: string }): Promise<void> {
+    return post('action', p.action_id, { row_id: p.row_id });
+  }
+
+  if (getCurrentInstance()) onBeforeUnmount(cancelChange);
+
+  return {
+    current,
+    values,
+    busy,
+    failure,
+    footer,
+    errors,
+    invalidKeys,
+    setSurface,
+    updateValues,
+    scheduleChange,
+    post,
+    press,
+    rowAction,
+    dispose: cancelChange,
+  };
+}
+
+export type PluginSurfaceStore = ReturnType<typeof usePluginSurface>;

package/src/composables/usePublicBranding.ts

@@ -0,0 +1,172 @@
+/**
+ * usePublicBranding — whose product the visitor thinks they are looking at.
+ *
+ * ⚠⚠ v3 §1.2: whitelabel means whitelabel. A share, a file request and a
+ * signature request are the surfaces an OUTSIDER sees, and until now they
+ * were the only ones that ignored the instance's own name, logo and colour
+ * — so an operator who had renamed filex everywhere still sent out links
+ * that said filex. The branding record is the same one the admin
+ * "Corporate identity" page writes; this composable is how the public shell
+ * wears it.
+ *
+ * ⚠ It is a PUBLIC fetch, and the page must be usable before it lands: the
+ * shell paints with the stock palette and re-paints when the answer arrives.
+ * Nothing waits on it and a failure is not an error — an older server has no
+ * such route, and the product's own name is a perfectly good answer.
+ *
+ * ⚠ The accent is written as `--fe-*` custom properties on the SHELL's root
+ * element, never on `:root`. The same shell is mounted inside other pages
+ * (an embed, a test harness), and a public link must not repaint the host
+ * around it.
+ */
+import { computed, ref } from 'vue';
+import type { PublicBranding } from '../types/Public';
+import { setLocalesFromBranding } from '../lib/uiLocales';
+
+/** The product's own name, used until (and unless) an operator renames it. */
+export const DEFAULT_BRAND_NAME = 'filex';
+
+export interface PublicBrandingOptions {
+  /** API origin; empty = same origin. */
+  base?: string;
+  fetchImpl?: typeof fetch;
+}
+
+const HEX = /^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6})$/;
+
+/** `#abc` → `#aabbcc`; anything that is not a hex colour → ''. */
+export function normalizeAccent(raw: string | undefined | null): string {
+  const v = String(raw ?? '').trim();
+  if (!HEX.test(v)) return '';
+  if (v.length === 4) return `#${v[1]}${v[1]}${v[2]}${v[2]}${v[3]}${v[3]}`.toLowerCase();
+  return v.toLowerCase();
+}
+
+/** The same colour, `k` of the way to black (0.85 = the hover state). */
+export function shade(hex: string, k: number): string {
+  const v = normalizeAccent(hex);
+  if (!v) return '';
+  const n = parseInt(v.slice(1), 16);
+  const part = (shift: number) => Math.max(0, Math.min(255, Math.round(((n >> shift) & 0xff) * k)));
+  const hx = (x: number) => x.toString(16).padStart(2, '0');
+  return `#${hx(part(16))}${hx(part(8))}${hx(part(0))}`;
+}
+
+/**
+ * Black or white on this colour, by luminance.
+ *
+ * ⚠ Not a constant. An operator who picks a pale accent gets white text on
+ * pale yellow if the ink is hardcoded — which is what "unreadable button"
+ * looks like to the person reporting it, and it is only ever seen on
+ * somebody else's instance.
+ */
+export function inkOn(hex: string): string {
+  const v = normalizeAccent(hex);
+  if (!v) return '';
+  const n = parseInt(v.slice(1), 16);
+  const lin = (c: number) => {
+    const x = c / 255;
+    return x <= 0.04045 ? x / 12.92 : ((x + 0.055) / 1.055) ** 2.4;
+  };
+  const L = 0.2126 * lin((n >> 16) & 0xff) + 0.7152 * lin((n >> 8) & 0xff) + 0.0722 * lin(n & 0xff);
+  return L > 0.42 ? '#0b0f14' : '#ffffff';
+}
+
+/**
+ * The `--fe-*` properties an accent colour becomes on the public shell — the
+ * ONE derivation, used by the real page (usePublicBranding) and by the admin
+ * page's live preview (PublicLinkPreview), so the preview cannot paint a
+ * button the page itself would not. `{}` for no (or no valid) accent.
+ */
+export function accentStyleOf(raw: string | undefined | null): Record<string, string> {
+  const accent = normalizeAccent(raw);
+  if (!accent) return {} as Record<string, string>;
+  const n = parseInt(accent.slice(1), 16);
+  const rgb = `${(n >> 16) & 0xff}, ${(n >> 8) & 0xff}, ${n & 0xff}`;
+  return {
+    '--fe-primary': accent,
+    '--fe-primary-hover': shade(accent, 0.85),
+    '--fe-text-on-primary': inkOn(accent),
+    // ⚠ The TINT and the ink on it, or the accent only half arrives: the
+    // button turned orange while the round badge behind the padlock, the
+    // focus ring on the PIN box and the row hover stayed the stock blue
+    // (measured on the first after-shot of the restored gate). The old
+    // Go-rendered page derived exactly these from the same colour
+    // (`--px-accent-soft: rgba(r,g,b,0.14)`, `color: var(--px-accent)`), and
+    // a translucent tint is right rather than a solid: it composites onto
+    // the card in light and in dark without a second value.
+    '--fe-primary-soft': `rgba(${rgb}, 0.14)`,
+    '--fe-primary-ink': accent,
+  };
+}
+
+export function usePublicBranding(opts: PublicBrandingOptions = {}) {
+  const branding = ref<PublicBranding | null>(null);
+  const loaded = ref(false);
+
+  const name = computed(() => branding.value?.name?.trim() || DEFAULT_BRAND_NAME);
+  /** True when the operator has named the instance something of their own. */
+  const whitelabel = computed(() => !!branding.value?.name?.trim() && name.value !== DEFAULT_BRAND_NAME);
+  const logo = computed(() => branding.value?.logo_url?.trim() || '');
+  const footerText = computed(() => branding.value?.footer_text?.trim() || '');
+  const hidePoweredBy = computed(() => branding.value?.hide_powered_by === true);
+
+  /**
+   * The instance's light/dark default for a visitor who has chosen nothing.
+   *
+   * ⚠ The server's word is `system`; this package's is `auto`. They mean
+   * the same thing and the translation happens HERE, once, rather than in
+   * every component that compares the string.
+   */
+  const themeDefault = computed<'light' | 'dark' | 'auto'>(() => {
+    const t = branding.value?.theme;
+    return t === 'light' || t === 'dark' ? t : 'auto';
+  });
+
+  /** The languages this instance offers, as the branding answer lists them. */
+  const locales = computed<string[]>(() => branding.value?.locales ?? []);
+
+  /** The accent, as the `--fe-*` properties the shell's root carries. */
+  const accentStyle = computed<Record<string, string>>(() => accentStyleOf(branding.value?.accent));
+
+  /**
+   * Ask the server.
+   *
+   * ⚠ `/api/public/branding` first, `/api/branding` second. The second is
+   * the route this product has served since wiring:e1 and answers a
+   * compatible record; asking only for the new address and giving up on a
+   * 404 would mean a whitelabelled instance goes back to saying "filex" the
+   * moment it is updated in the wrong order.
+   *
+   * ⚠ The languages ride along: `locales` / `ui_locales` are on this payload,
+   * so the picker is filled by the fetch the shell already makes
+   * (`lib/uiLocales.setLocalesFromBranding`). Only the language somebody
+   * actually reads has its strings fetched, once.
+   */
+  async function load(): Promise<PublicBranding | null> {
+    const doFetch = opts.fetchImpl ?? (typeof fetch === 'function' ? fetch : null);
+    if (!doFetch) return null;
+    const origin = (opts.base ?? '').replace(/\/+$/, '');
+    for (const path of ['/api/public/branding', '/api/branding']) {
+      try {
+        const res = await doFetch(`${origin}${path}`, {
+          method: 'GET',
+          headers: { Accept: 'application/json' },
+          credentials: 'same-origin',
+        });
+        if (!res.ok) continue;
+        branding.value = (await res.json()) as PublicBranding;
+        loaded.value = true;
+        // ⚠ With the same origin and fetch: a language's STRINGS are fetched
+        // later from `/api/public/ui-locales/{code}` on this same server.
+        setLocalesFromBranding(branding.value, { base: opts.base, fetchImpl: opts.fetchImpl });
+        return branding.value;
+      } catch {
+        /* try the next address; the default name is already on screen */
+      }
+    }
+    return null;
+  }
+
+  return { branding, loaded, name, whitelabel, logo, footerText, hidePoweredBy, themeDefault, locales, accentStyle, load };
+}