@brftech/filex-core 0.39.1 → 0.41.0

package/src/styles/variables.css

@@ -4,29 +4,78 @@
  * Consumer overrides by setting `--fe-*` on a higher scope.
  */
 :root {
+  /* gorunum:v1 — the product's own palette and metrics. Everything below is a
+   * measured value, not a taste: the type scale, the control heights and the
+   * radii were read off the shell this look follows, in a real browser at
+   * 1440, and the palette clears the contrast bar in
+   * web/tests/api/themeContrast.test.ts in both variants. */
   --fe-bg: #ffffff;
-  --fe-bg-elev: #f7f8fa;
-  --fe-bg-hover: #edf0f5;
-  --fe-bg-selected: #dfe8ff;
-  --fe-border: #e2e6ed;
-  --fe-border-strong: #c7ced9;
-  --fe-text: #1a1e27;
-  --fe-text-muted: #5a6475;
+  --fe-bg-elev: #f7f8fb;
+  --fe-bg-hover: #f3f4f6;
+  --fe-bg-selected: #eef3ff;
+  --fe-border: #e5e7eb;
+  --fe-border-soft: #eef0f4;
+  --fe-border-strong: #d1d5db;
+  --fe-text: #1f2937;
+  --fe-text-muted: #6b7280;
   --fe-text-on-primary: #ffffff;
-  --fe-primary: #2f6fe0; /* ui-fix: beyaz metinle WCAG AA (eski #3b82f6 = 3.68) */
-  --fe-primary-hover: #2563eb;
+  --fe-primary: #2f6ceb;
+  --fe-primary-hover: #2559c9;
+  --fe-primary-soft: #e6ecfa;
+  /* Ink for text and icons ON the soft-primary ground — the active sidebar
+     row, the active scope tab, the active segment of a segmented control.
+     ⚠ It is a token of its own because `--fe-primary` cannot carry that job:
+     measured, the stock primary on the stock tint is 3.97:1, under the 4.5 the
+     palette file claims, and no tint rescues it (the primary is only 4.70:1 on
+     white to begin with). It is not `--fe-primary-hover` either, though that is
+     the value HERE: three of the shipped palettes darken their hover in dark
+     mode, toward the tint rather than away from it, and Night dark measures
+     3.78:1 that way. Each palette names the ink that clears the bar on its own
+     tint; web/tests/api/themeContrast.test.ts pins the pairing. */
+  --fe-primary-ink: #2559c9;
   --fe-danger: #dc2626;
   --fe-danger-hover: #b91c1c;
   --fe-keep-ok: #16a34a; /* selective-sync "on this computer" check */
-  --fe-shadow: 0 10px 32px rgba(15, 23, 42, 0.14);
-  --fe-shadow-sm: 0 2px 6px rgba(15, 23, 42, 0.08);
+  --fe-shadow: 0 20px 60px rgba(17, 24, 39, 0.18);
+  --fe-shadow-sm: 0 8px 24px rgba(17, 24, 39, 0.12);
   --fe-radius: 8px;
-  --fe-radius-sm: 4px;
+  --fe-radius-sm: 6px;
   --fe-radius-md: 10px;
   --fe-radius-lg: 12px;
-  --fe-font: system-ui, -apple-system, "Segoe UI", Roboto, sans-serif;
+  /* Control heights. A listing is a stack of rows and chips; when each one
+   * picks its own height the column edges wander and the page reads as
+   * hand-assembled. Three sizes, and every control picks one. */
+  --fe-h-sm: 28px;
+  --fe-h-md: 34px;
+  --fe-h-lg: 40px;
+  /* gorunum:v3-shell — the navigation panel's expanded width. A token because
+   * TWO places have to agree on it: the panel itself, and the gutter the top
+   * bar reserves at its left so the search field starts where the content
+   * area does. Written once in each place, they were one redesign away from
+   * disagreeing — and the failure is silent, a header that no longer lines up
+   * with the column under it.
+   * ⚠ The rail and the drawer keep their own widths; only the expanded column
+   * follows this.
+   * ⚠ 192px, not 255px (owner, 2026-09-13: "şu an default'ta çok açık geliyor
+   * yan menü, biraz kısaltabiliriz bence"). It is the reference build's own
+   * number, measured off it at 1280, and it is the WHOLE change: the top bar's
+   * gutter is `calc(this - 12px)`, so the search field moves left with the
+   * column instead of the header drifting out of line with it. Checked at the
+   * new width in Turkish, the longer of the two catalogues — the widest row
+   * label ("Paylaşılanlar") clears it, and so does the quota line. */
+  --fe-sidenav-w: 192px;
+  /* Type scale. Small and tight on purpose: the shell packs a filename, a
+   * size, a date and a menu into one row, and 14px with normal leading pushes
+   * that to two lines at any realistic column width. */
+  --fe-text-xs: 12px;
+  --fe-text-sm: 12.5px;
+  --fe-text-md: 13px;
+  --fe-font: Inter, system-ui, -apple-system, "Segoe UI", Roboto, sans-serif;
   --fe-font-mono: ui-monospace, "SF Mono", Consolas, Menlo, monospace;
+  --fe-gap-xs: 4px;
+  --fe-gap-sm: 8px;
   --fe-gap: 12px;
+  --fe-gap-lg: 16px;
 }
 
 .fe--theme-dark,
@@ -54,16 +103,22 @@
  * as white-on-white inside dark hosts. */
 .fe-ctx-backdrop--theme-dark,
 .fe-ctx-backdrop--theme-auto[data-prefers-dark='1'] {
-  --fe-bg: #0f1419;
-  --fe-bg-elev: #161c25;
-  --fe-bg-hover: #1f2733;
-  --fe-bg-selected: #23324a;
-  --fe-border: #2a323e;
-  --fe-border-strong: #3a4453;
-  --fe-text: #e5e9f0;
-  --fe-text-muted: #8b95a7;
-  --fe-primary: #60a5fa;
-  --fe-primary-hover: #3b82f6;
+  --fe-bg: #15171c;
+  --fe-bg-elev: #1a1d23;
+  --fe-bg-hover: #1f232a;
+  --fe-bg-selected: #1c2740;
+  --fe-border: #2e333c;
+  --fe-border-soft: #262a32;
+  --fe-border-strong: #3d444f;
+  --fe-text: #e6e8ec;
+  --fe-text-muted: #888f9b;
+  /* Dark ink on the light-blue button. White measures 3.16:1 against it —
+   * the bar for text on a primary surface is 4.5, and #15171c measures 5.67. */
+  --fe-text-on-primary: #15171c;
+  --fe-primary: #5b8cff;
+  --fe-primary-hover: #7ba3ff;
+  --fe-primary-soft: #1c2740;
+  --fe-primary-ink: #7ba3ff;
   --fe-danger: #f87171;
   --fe-danger-hover: #ef4444;
     --fe-keep-ok: #4ade80;
@@ -75,16 +130,21 @@
   .fe:not(.fe--theme-light),
   /* Same trick for the teleported backdrop in auto mode. */
   .fe-ctx-backdrop--theme-auto:not(.fe-ctx-backdrop--theme-light) {
-    --fe-bg: #0f1419;
-    --fe-bg-elev: #161c25;
-    --fe-bg-hover: #1f2733;
-    --fe-bg-selected: #23324a;
-    --fe-border: #2a323e;
-    --fe-border-strong: #3a4453;
-    --fe-text: #e5e9f0;
-    --fe-text-muted: #8b95a7;
-    --fe-primary: #60a5fa;
-    --fe-primary-hover: #3b82f6;
+    --fe-bg: #15171c;
+    --fe-bg-elev: #1a1d23;
+    --fe-bg-hover: #1f232a;
+    --fe-bg-selected: #1c2740;
+    --fe-border: #2e333c;
+    --fe-border-soft: #262a32;
+    --fe-border-strong: #3d444f;
+    --fe-text: #e6e8ec;
+    --fe-text-muted: #888f9b;
+    /* See the note on the class-based dark block above. */
+    --fe-text-on-primary: #15171c;
+    --fe-primary: #5b8cff;
+    --fe-primary-hover: #7ba3ff;
+    --fe-primary-soft: #1c2740;
+    --fe-primary-ink: #7ba3ff;
     --fe-danger: #f87171;
     --fe-danger-hover: #ef4444;
     --fe-keep-ok: #4ade80;
@@ -95,18 +155,34 @@
 
 /* === cila:a — file-type icon accent tokens (lib/fileIcons families) === */
 :root {
-  --fe-icon-folder: #d97706;
-  --fe-icon-image: #7c3aed;
-  --fe-icon-video: #db2777;
+  /* gorunum:v1 — the folder yellow, same value in both variants. A folder is
+   * the only glyph that is filled, and the one people find by colour before
+   * they read the name; darkening it for the light theme made it read as an
+   * archive box. */
+  --fe-icon-folder: #f4b400;
+  /* gorunum:v1 — these are now the fill of a chip, not the stroke of a glyph,
+   * so they are read as a block of colour and a family has to be one glance
+   * apart from its neighbours. Documents and code share the blue on purpose:
+   * both are "something you open and read", and splitting them made every
+   * listing look like a paint chart. */
+  --fe-icon-image: #2f6ceb;
+  --fe-icon-video: #7c3aed;
   --fe-icon-audio: #0d9488;
   --fe-icon-pdf: #dc2626;
-  --fe-icon-doc: #2563eb;
+  --fe-icon-doc: #2f6ceb;
   --fe-icon-sheet: #16a34a;
   --fe-icon-slides: #ea580c;
-  --fe-icon-archive: #78716c;
-  --fe-icon-code: #4f46e5;
-  --fe-icon-text: #64748b;
-  --fe-icon-unknown: #64748b; /* ui-fix: 3:1 UI contrast on the light theme */
+  --fe-icon-archive: #6b7280;
+  --fe-icon-code: #2f6ceb;
+  --fe-icon-text: #374151;
+  --fe-icon-unknown: #6b7280;
+  /* Not file types: the two rows that are PLACES. A drive is infrastructure
+   * rather than content, so it takes a slate that sits beside the type
+   * colours without competing with any of them — it is the first thing on the
+   * multi-storage root and should read as a shelf, not as another document.
+   * The bin is deliberately the quietest chip in the set. */
+  --fe-icon-storage: #475569;
+  --fe-icon-trash: #6b7280;
 }
 
 /* Dark values — same selector strategy as the palette blocks above. */
@@ -120,34 +196,38 @@
 .fe-ctx-backdrop--theme-dark,
 .fe-ctx-backdrop--theme-auto[data-prefers-dark='1'] {
   --fe-icon-folder: #fbbf24;
-  --fe-icon-image: #a78bfa;
-  --fe-icon-video: #f472b6;
+  --fe-icon-image: #4d7ff0;
+  --fe-icon-video: #9061f0;
   --fe-icon-audio: #2dd4bf;
-  --fe-icon-pdf: #f87171;
-  --fe-icon-doc: #60a5fa;
-  --fe-icon-sheet: #4ade80;
+  --fe-icon-pdf: #e05252;
+  --fe-icon-doc: #4d7ff0;
+  --fe-icon-sheet: #2eab63;
   --fe-icon-slides: #fb923c;
-  --fe-icon-archive: #a8a29e;
-  --fe-icon-code: #818cf8;
-  --fe-icon-text: #94a3b8;
-  --fe-icon-unknown: #8b95a7;
+  --fe-icon-archive: #79808d;
+  --fe-icon-code: #4d7ff0;
+  --fe-icon-text: #5b6472;
+  --fe-icon-unknown: #79808d;
+  --fe-icon-storage: #8b95a6;
+  --fe-icon-trash: #79808d;
 }
 
 @media (prefers-color-scheme: dark) {
   .fe:not(.fe--theme-light),
   .fe-ctx-backdrop--theme-auto:not(.fe-ctx-backdrop--theme-light) {
-    --fe-icon-folder: #fbbf24;
-    --fe-icon-image: #a78bfa;
-    --fe-icon-video: #f472b6;
+    --fe-icon-folder: #f4b400;
+    --fe-icon-image: #4d7ff0;
+    --fe-icon-video: #9061f0;
     --fe-icon-audio: #2dd4bf;
-    --fe-icon-pdf: #f87171;
-    --fe-icon-doc: #60a5fa;
-    --fe-icon-sheet: #4ade80;
+    --fe-icon-pdf: #e05252;
+    --fe-icon-doc: #4d7ff0;
+    --fe-icon-sheet: #2eab63;
     --fe-icon-slides: #fb923c;
-    --fe-icon-archive: #a8a29e;
-    --fe-icon-code: #818cf8;
-    --fe-icon-text: #94a3b8;
-    --fe-icon-unknown: #8b95a7;
+    --fe-icon-archive: #79808d;
+    --fe-icon-code: #4d7ff0;
+    --fe-icon-text: #5b6472;
+    --fe-icon-unknown: #79808d;
+    --fe-icon-storage: #8b95a6;
+    --fe-icon-trash: #79808d;
   }
 }
 

package/src/types/Connections.ts

@@ -54,8 +54,17 @@ export interface StorageField {
   aliases?: string[];
 }
 
+/**
+ * A driver's runtime feature set, from `backend/internal/storage.Capabilities`.
+ *
+ * ⚠ `range` was missing from BOTH hand-written copies of this (here and in
+ * web/src/api/types.ts) while the server has always sent it — the exact way a
+ * type re-declared per package drifts from the struct it describes.
+ */
 export interface StorageDriverCapabilities {
   read?: boolean;
+  /** Ranged reads: the difference between 206/Content-Range and a whole-object copy. */
+  range?: boolean;
   write?: boolean;
   move?: boolean;
   copy?: boolean;

package/src/types/ExplorerConfig.ts

@@ -17,6 +17,10 @@
  * keeping the auto-derived rest).
  */
 
+import type { UiProfile } from '../lib/uiProfile';
+
+export type { UiProfile };
+
 /**
  * Auth strategy. Discriminated union so request building is type-safe.
  *
@@ -185,6 +189,21 @@ export interface ExplorerConfig {
   /** UI dil kodu */
   locale?: LocaleCode;
 
+  /**
+   * The clock this embed's visitors read dates on by default — an IANA id,
+   * `'Asia/Tokyo'`, `'Europe/Istanbul'`, `'UTC'`.
+   *
+   * Only which clock an instant is READ on changes; the instant itself does
+   * not. Unset, a visitor sees the zone of the account behind the credential
+   * when that credential is a person's, and otherwise their browser's own.
+   *
+   * ⚠ A default, not a lock. A visitor who picks a zone in the explorer's own
+   * "⋯" → Time zone keeps their pick, in their browser. The whole order, and
+   * why it is that order, is `TIME_ZONE_TIERS` in `lib/timezone`. An id the
+   * browser does not accept is ignored rather than guessed at.
+   */
+  timeZone?: string;
+
   /** OnlyOffice iframe base (e.g. `https://docs.example.com`). */
   onlyOfficeBase?: string;
 
@@ -259,7 +278,21 @@ export interface ExplorerConfig {
    */
   tabStrip?: 'auto' | 'always';
 
-  /** Initial path (storage-prefix included: `local://`). Default: root. */
+  /**
+   * Initial path (storage-prefix included: `local://`). Default: root.
+   *
+   * gorunum:v3-shell — a VIEW is addressable here too, by its sentinel:
+   * `'.home'` opens the overview (storages · recent · starred), and
+   * `'.recent'` / `'.starred'` / `'.shared'` / `'.trash'` / `'.tag~invoices'`
+   * open theirs. That is how our own `/home` route opens Home without a second
+   * mechanism — the sentinels are the same strings the address-bar hash, the
+   * tab strip and a restored session already speak (lib/listing
+   * VIRTUAL_SEGMENTS), so there is one answer to "where does this explorer
+   * start" rather than a path answer and a view answer that can disagree.
+   *
+   * ⚠ A sentinel this build does not know keeps going to the backend as a
+   * folder name, so a host cannot invent views by passing strings.
+   */
   initialPath?: string;
 
   /**
@@ -270,6 +303,42 @@ export interface ExplorerConfig {
    */
   rootPath?: string;
 
+  /**
+   * gorunum:v3-shell — the product mark at the far left of the top bar: the
+   * wordmark beside it, and an image for the mark itself.
+   *
+   * ⚠⚠ This exists because a `<slot>` IS NOT REACHABLE from a host that mounts
+   * `<filex-explorer>`, and that is not a bug anybody can fix in a line.
+   * Measured, 2026-09-13, in a real browser with Vue's own
+   * `defineCustomElement`: a `<span slot="brand">` placed inside the element
+   * leaves `Object.keys(slots)` EMPTY in the element's `setup` — with the
+   * wrapper forwarding slots, without it, when the node is added after mount,
+   * and with `shadowRoot: true` as well. Vue projects light DOM into a custom
+   * element only through a NATIVE `<slot>` element inside a shadow root, which
+   * this package cannot have: its entire look is one global stylesheet
+   * (`styles/base.css`), and a shadow root would leave every embed unstyled.
+   *
+   * So the slot is for hosts that mount the Vue SFC (our admin app does, and
+   * its `#brand` still wins when it is filled); this is for everybody else —
+   * and "everybody else" includes OUR OWN DESKTOP APP, which mounts the web
+   * component. A logo the web app has and the desktop app silently lacks is
+   * exactly the one-surface split this package exists to prevent.
+   *
+   * ⚠ An `<img src>`, not markup. The mark is drawn from a URL — a file, or a
+   * `data:image/svg+xml;base64,…` URI for an inline logo — so a host never
+   * hands this package a string to inject. There is no `v-html` on the path.
+   *
+   * ⚠ Both halves are optional and independent: a name with no mark renders
+   * the wordmark alone, a mark with no name renders the glyph alone, and
+   * neither renders nothing at all (the collapse control still sits there).
+   */
+  brand?: {
+    /** Wordmark text, e.g. `'filex'`. Printed verbatim, never translated. */
+    name?: string;
+    /** URL of the mark: a path, an absolute URL, or a `data:` URI. */
+    markUrl?: string;
+  };
+
   /**
    * Whether the info-panel (inspector) toggle is shown in the toolbar.
    * Default true. The inspector itself stays reachable from the context menu.
@@ -277,44 +346,42 @@ export interface ExplorerConfig {
   showInfoPanel?: boolean;
 
   /**
-   * Which set of chrome the explorer presents. A PRESET, not a feature switch:
-   * nothing is removed from the code, and every capability stays reachable —
-   * `'simple'` only changes what is on screen by default.
-   *
-   *   'standard' (default) — everything: tab strip, split pane, all three view
-   *                          modes. The tool the explorer has always been.
-   *   'simple'             — one pane, one folder, list/grid only. The
-   *                          navigation panel starts expanded, the tab strip
-   *                          and split pane are off, the gallery view mode and
-   *                          the host's "How to connect" surface are hidden.
-   *   'drive'              — everything `simple` does, plus the shell an end
-   *                          user already knows: one primary "New" menu, one
-   *                          search field in the header (with its ⌘K/Ctrl+K
-   *                          escalation into the command palette), a filter row
-   *                          under the breadcrumb, Folders and Files as
-   *                          labelled sections in grid view, the details panel
-   *                          split into Details / Activity, and a storage line
-   *                          under the navigation.
-   *
-   * ⚠ `drive` is a SUPERSET of `simple`, not a sibling: everything `simple`
-   * turns off stays off, and the code asks `simpleUi` for those questions so a
-   * later change to `simple` cannot silently miss `drive`. It is a third value
-   * rather than a second boolean because "which chrome" is ONE question with
-   * three answers — a `driveShell: true` next to `uiProfile: 'standard'` would
-   * be a combination nobody can describe, and keeping that question single is
-   * why `uiProfile` was a preset to begin with.
-   *
-   * Why it exists (GitHub #14): the reporter's users are not in IT and read
-   * split panes, tabs and mount instructions as a file manager they would have
-   * to relearn. The answer was NOT a second UI — one explorer, configured, so
-   * a fix lands in one place for every surface that mounts this package.
-   *
-   * ⚠ It does not gate the navigation panel. The panel ships in both profiles,
-   * for administrators too; only its default expanded/collapsed state and the
-   * rest of the chrome differ. A viewer's own collapse choice, once made,
-   * outranks the profile — it is a per-viewer preference, not a policy.
-   */
-  uiProfile?: 'standard' | 'simple' | 'drive';
+   * How much of the explorer to put on screen. A REDUCTION, and only that.
+   *
+   *   'standard' (default) — everything: the tab strip, the split pane and all
+   *                          three view modes, on top of the shell below.
+   *   'simple'             — one pane, one folder, list and grid only. The tab
+   *                          strip and the split pane are off, the gallery view
+   *                          mode is hidden, and the "How to connect" /
+   *                          "API keys" entries default to off.
+   *
+   * There is no third value and no alias. ⚠ Anything else that arrives here —
+   * a typo, or the `'drive'` profile that was REMOVED after v0.40.0 —
+   * resolves to `'standard'` and logs one console line naming it
+   * (`lib/uiProfile.resolveUiProfile`, which explains why that direction and
+   * not the other). **If you passed `'drive'`, pass `'simple'`.**
+   *
+   * ⚠⚠ IT DOES NOT DECIDE THE LOOK, and that is the whole of this option.
+   * The header with its one wide search field, the "+ New" menu, the filter
+   * row, the Folders/Files sections, the Details/Activity tabs and the storage
+   * line USED to be gated behind a profile. They are what filex is now — the
+   * admin panel, the desktop app and every `<filex-explorer>` embed draw them,
+   * with no string passed. Owner's decision, 2026-09-12, verbatim (translated
+   * from Turkish): "their app and our app will be one to one. The admin gets
+   * one extra button, nothing else. The things we have over them — tabs, split
+   * pane, theme choice, icon choice — stay."
+   *
+   * Why the reduction exists at all (GitHub #14): the reporter's users are not
+   * in IT and read split panes, tabs and mount instructions as a file manager
+   * they would have to relearn. The answer was NOT a second UI — one explorer,
+   * configured, so a fix lands in one place for every surface that mounts this
+   * package.
+   *
+   * ⚠ It does not gate the navigation panel. The panel ships in every profile,
+   * for administrators too; only a viewer's own collapse choice moves it, and
+   * that is a per-viewer preference, not a policy.
+   */
+  uiProfile?: UiProfile;
 
   /**
    * Render the navigation panel (Upload · Recent / Starred / Shared with me /
@@ -449,11 +516,49 @@ export interface ExplorerConfig {
    * + (optional) display label / read-only flag. The SFC mirrors
    * each entry as a virtual `dir` row at "/".
    */
+  /**
+   * tablo:t1 — remember how each folder was last viewed (view mode + sort),
+   * Windows Explorer style. Default ON.
+   *
+   * ⚠ The opt-out exists for embeds. A product mounting filex in a two-inch
+   * panel has one shape it wants and no room to argue with a gallery view
+   * arriving from the person's main window; setting this false makes every
+   * folder open in the host's chosen default and writes nothing. The columns
+   * are NOT covered by this flag — their widths are a global preference about
+   * the reader's screen, and a panel that narrow sheds them for want of room
+   * before any preference is consulted.
+   */
+  rememberFolderView?: boolean;
   storages?: Array<{
     name: string;
+    /**
+     * tablo:t1 — the storage's immutable uid, when the host knows it.
+     *
+     * ⚠ A storage's NAME is editable — that is the point of a name — so it is
+     * not a stable address, which is why every protocol also accepts the uid
+     * as a path's first segment (`backend/internal/storageref`, filex issue
+     * #21). Anything keyed on a storage for the long term should prefer this:
+     * per-folder view memory does (`lib/viewPrefs.folderKey`), and folders
+     * under a renamed storage keep their remembered view the moment a host
+     * starts filling it in. Absent = the name is used and a rename loses the
+     * memory, which is a mild, self-healing loss.
+     */
+    uid?: string;
     label?: string;
     driver?: string;
     readOnly?: boolean;
+    /**
+     * gorunum:v3-shell — bytes this storage holds, when the host knows. Drawn
+     * as the caption on the Home view's storage card; absent means the card
+     * names the kind of thing instead.
+     *
+     * ⚠ It must be the SAME quantity for every caller who gets it (in our own
+     * app: `/api/admin/storages` for an operator, the RBAC-filtered
+     * `/api/files/quota/storages` for everybody else). The per-USER quota is a
+     * sum across every storage, so passing that here would print a number
+     * about the person under a label about the drive.
+     */
+    usedBytes?: number;
   }>;
 
   /**

package/src/types/FileNode.ts

@@ -76,7 +76,31 @@ export interface ExternalServiceStatus {
   detail?: string;
 }
 
+/**
+ * One document type the SERVER can create, from `capabilities.newdoc_types`.
+ *
+ * ⚠ `requires` is the whole point of shipping this list instead of hardcoding
+ * one in the client. The server knows it holds template bytes for `.docx`; it
+ * does NOT know whether this deployment has a document server that can open
+ * one. So it names the dependency and the client — which already resolves
+ * OnlyOffice/drawio, config override included — answers it. A client that
+ * re-derived "docx needs OnlyOffice" from a list of its own would be a second
+ * source of truth, and the one that rots first.
+ */
+export interface NewDocType {
+  /** Extension without the dot, lowercase. Also the key the create call sends. */
+  ext: string;
+  /** Coarse family, used for the picker's section headings. */
+  group: 'document' | 'text' | 'diagram';
+  mime: string;
+  /** External service the editor for this type needs; absent = built-in. */
+  requires?: 'onlyoffice' | 'drawio';
+}
+
 export interface Capabilities {
+  /** Document types this build can create. Absent on a server older than the
+   *  "New document" feature — hosts must treat that as "offer nothing". */
+  newdoc_types?: NewDocType[];
   ffmpeg?: boolean;
   ghostscript?: boolean;
   libreoffice?: boolean;
@@ -94,6 +118,10 @@ export interface Capabilities {
    *  ExplorerConfig.callerKind. Absent on a server older than the app/user
    *  token split, which is why every reader treats "missing" as a person. */
   caller_kind?: 'user' | 'app';
+  /** The address this deployment is reached at — only when it is real (the
+   *  operator configured it, or the request came in on a tenant's host).
+   *  Read by the connection guides; see `connectionsOrigin`. */
+  public_url?: string;
   external?: {
     onlyoffice?: ExternalServiceStatus;
     drawio?: ExternalServiceStatus;

package/src/viewers/ArchiveViewer.vue

@@ -10,6 +10,8 @@
  * decide whether to extract or download.
  */
 import { computed, onMounted, ref, watch } from 'vue';
+import { actionIconSvg } from '../lib/actionIcons'; /* ikon:emoji */
+import { fileIconTile } from '../lib/fileIcons'; /* ikon:emoji */
 
 interface ArchiveEntry {
   name: string;
@@ -22,7 +24,7 @@ const props = defineProps<{
   url: string;
   filePath?: string;
   ext: string;
-  t?: (key: string) => string;
+  t?: (key: string, vars?: Record<string, string | number>) => string;
   authHeaders?: () => Record<string, string> | Promise<Record<string, string>>;
   authCredentials?: RequestCredentials;
   /** ⚠ Where to ask. This used to be the literal '/api/files/archive/list',
@@ -37,8 +39,11 @@ const entries = ref<ArchiveEntry[]>([]);
 const loading = ref(true);
 const error = ref<string | null>(null);
 
-function tt(key: string, fallback: string): string {
-  return props.t ? props.t(key) : fallback;
+/** ⚠ `vars` go THROUGH `t()`, not into a `.replace()` afterwards: `t()` is what
+ *  picks the singular (`viewer.archive.entries_one`) from the count, and it can
+ *  only do that if it is told the count. Same shape CsvViewer's helper has. */
+function tt(key: string, fallback: string, vars?: Record<string, string | number>): string {
+  return props.t ? props.t(key, vars) : fallback;
 }
 
 function fmtSize(n: number): string {
@@ -87,25 +92,54 @@ watch(() => props.filePath, load);
 
 const totalSize = computed(() => entries.value.reduce((sum, e) => sum + (e.size || 0), 0));
 const fileCount = computed(() => entries.value.filter((e) => !e.is_dir).length);
+
+/* === ikon:emoji — the fallback screen's mark ==========================
+ * Every viewer opened its "cannot show this" / "still loading" screen with a
+ * 48px colour emoji, one per format, each from whatever emoji font the OS
+ * shipped. The format mark is `lib/fileIcons`'s tile — the SAME tile the row
+ * the person just clicked is wearing, so the fallback is recognisably about
+ * that file — and "loading" is the stroked ring, spun by CSS, because no
+ * still picture can say "still going". */
+const typeTile = computed(() => fileIconTile({ type: 'file', extension: props.ext }));
+
+/** A row inside the archive, drawn the way the listing draws the same kind. */
+function entryTile(e: ArchiveEntry): string {
+  const name = e.name || '';
+  const dot = name.lastIndexOf('.');
+  return fileIconTile({
+    type: e.is_dir ? 'dir' : 'file',
+    extension: dot > 0 ? name.slice(dot + 1) : '',
+    basename: name,
+  });
+}
 </script>
 
 <template>
   <div class="filex-viewer-archive">
     <div v-if="error" class="filex-viewer-fallback">
-      <span class="filex-viewer-fallback__icon">🗜️</span>
+      <!-- eslint-disable-next-line vue/no-v-html -- static markup from lib/fileIcons + lib/actionIcons -->
+      <span class="filex-viewer-fallback__icon" aria-hidden="true" v-html="typeTile"></span>
       <p>{{ error }}</p>
     </div>
     <div v-else-if="loading" class="filex-viewer-fallback">
-      <span class="filex-viewer-fallback__icon">⏳</span>
+      <!-- eslint-disable-next-line vue/no-v-html -- static markup from lib/fileIcons + lib/actionIcons -->
+      <span
+        class="filex-viewer-fallback__icon filex-viewer-fallback__icon--spin"
+        aria-hidden="true"
+        v-html="actionIconSvg('progress')"
+      ></span>
       <p>{{ tt('viewer.loading', 'Loading…') }}</p>
     </div>
     <div v-else-if="entries.length === 0" class="filex-viewer-fallback">
-      <span class="filex-viewer-fallback__icon">🗜️</span>
+      <!-- eslint-disable-next-line vue/no-v-html -- static markup from lib/fileIcons + lib/actionIcons -->
+      <span class="filex-viewer-fallback__icon" aria-hidden="true" v-html="typeTile"></span>
       <p>{{ tt('viewer.archive.empty', 'Archive is empty.') }}</p>
     </div>
     <div v-else class="filex-viewer-archive__pane">
       <div class="filex-viewer-archive__summary">
-        {{ fileCount }} {{ tt('viewer.archive.entries', '{n} files').replace('{n}', String(fileCount)) }}
+        <!-- ⚠ The count is IN the message ("{n} files"). A `{{ fileCount }}`
+             printed in front of it read "3 3 files". -->
+        {{ tt('viewer.archive.entries', `${fileCount} files`, { n: fileCount }) }}
         · {{ fmtSize(totalSize) }}
       </div>
       <table class="filex-viewer-archive__table">
@@ -118,7 +152,11 @@ const fileCount = computed(() => entries.value.filter((e) => !e.is_dir).length);
         <tbody>
           <tr v-for="(e, i) in entries" :key="i" :data-dir="e.is_dir ? '1' : '0'">
             <td>
-              <span class="filex-viewer-archive__icon">{{ e.is_dir ? '📁' : '📄' }}</span>
+              <!-- ikon:emoji — the same tile the listing draws for the same
+                   kind of file, so an archive's contents and the folder it
+                   came from read as one product. -->
+              <!-- eslint-disable-next-line vue/no-v-html -- static markup from lib/fileIcons -->
+              <span class="filex-viewer-archive__icon" aria-hidden="true" v-html="entryTile(e)"></span>
               {{ e.name }}
             </td>
             <td class="filex-viewer-archive__size">{{ e.is_dir ? '' : fmtSize(e.size) }}</td>