@brftech/filex-core 0.39.1 → 0.41.0

package/src/lib/filePreview.ts

@@ -0,0 +1,605 @@
+/**
+ * filePreview — gorunum:v1-preview.
+ *
+ * The first lines of the REAL file, drawn inside the card's preview box when
+ * there is nothing better to put there.
+ *
+ * ## Why this exists at all
+ *
+ * The backend already answers `thumb_url` for a `.ts` or a `.csv` — but what
+ * it renders for them is `internal/thumb/generic.go`: a card tinted from a
+ * hash of the extension with the letters "TS" drawn in the middle. Measured
+ * on the local backend, `GET /api/files/thumb/6` (app.ts) is a 1,745-byte
+ * JPEG of exactly that. So the card was already spending a request to be told
+ * the same thing its own footer tile says, in a colour nobody chose.
+ *
+ * A code file's first five lines say what it is in a way no glyph can. That
+ * is the whole idea: for the kinds we can read as text we skip the generic
+ * thumbnail entirely and fetch a few kilobytes of the file instead — the same
+ * number of requests, a preview that means something.
+ *
+ * ⚠ This never competes with a REAL thumbnail. The kinds it claims (code,
+ * plain text, csv/tsv) are precisely the kinds this backend cannot render a
+ * content-derived thumbnail for; images, video, audio and PDFs are untouched
+ * and keep their `<img>`.
+ *
+ * ## What bounds the cost
+ *
+ * Four independent limits, because any one of them alone is a promise rather
+ * than a bound:
+ *
+ *   1. **Visibility.** Nothing is fetched until the card intersects the
+ *      viewport (IntersectionObserver, 150px of margin so a scroll does not
+ *      chase the reader). ⚠ `useThumbs` does NOT do this — it fires on first
+ *      render for every row the parent hands it — so there was nothing to
+ *      reuse here; a 400-file folder would have been 400 reads.
+ *   2. **A ranged request.** `Range: bytes=0-8191`. The preview endpoint
+ *      answers 206 through `http.ServeContent` whenever the driver can seek
+ *      (`vfStream`, manager.go).
+ *   3. **A bounded read.** ⚠ A driver that cannot seek answers 200 with the
+ *      WHOLE body and `Accept-Ranges: none` — the Range header is a request,
+ *      not a guarantee. So the body is consumed chunk by chunk and the reader
+ *      is cancelled the moment we have enough. This, not the header, is what
+ *      actually caps the bytes.
+ *   4. **A file-size ceiling + a concurrency cap.** 4 MB and 3 in flight.
+ *
+ * Results are cached per path AND per version (etag, else mtime, else size),
+ * so an edited file re-reads and an unchanged one never does.
+ */
+
+import { ref } from 'vue';
+import type { FileNode } from '../types/FileNode';
+import { iconFamilyFor } from './fileIcons';
+import { resolveEndpoints } from '../composables/useFileApi';
+
+/** What shape the preview takes. `null` = this node has no text preview. */
+export type PreviewKind = 'code' | 'text' | 'table';
+
+/**
+ * One rendered line. Split in three so the view can print it WITHOUT
+ * `v-html` — the content is somebody's file, and interpolation is the only
+ * honest way to put it on screen.
+ */
+export interface PreviewLine {
+  /** Leading whitespace, kept so nesting is visible. */
+  indent: string;
+  /** The opening token when it is worth tinting ('' = leave it plain). */
+  tint: string;
+  /** Everything after it, verbatim. */
+  text: string;
+}
+
+export interface FilePreview {
+  kind: PreviewKind;
+  /** `code` / `text`. Empty for a table. */
+  lines: PreviewLine[];
+  /**
+   * `table` only: first rows × first columns, already clipped and PADDED to a
+   * rectangle. The card lays them out as one CSS grid, so a short row has to
+   * carry its empty cells or every row below it shifts a column left.
+   */
+  rows: string[][];
+  /** `table` only: the grid's column count (0 otherwise). */
+  cols: number;
+}
+
+/* ---------------------------------------------------------------- limits */
+
+/** Bytes asked for, and the hard cap on bytes actually read. */
+const MAX_BYTES = 8 * 1024;
+/** Files bigger than this are left alone. See the header: the streaming
+ *  cancel is the real bound, this is the "never surprise the operator whose
+ *  driver cannot seek" guard. */
+const MAX_FILE_BYTES = 4 * 1024 * 1024;
+/** Concurrent reads. Three keeps a fast scroll responsive without turning a
+ *  folder of scripts into a thundering herd against one S3 bucket. */
+const MAX_INFLIGHT = 3;
+/**
+ * How much is parsed — NOT how much is shown.
+ *
+ * ⚠ These used to be 10 lines / 6 rows / 4 columns, and those numbers were
+ * chosen for one box: the 184×108 grid card. They are not that box's height
+ * in any other view, and a fixed count is the wrong shape of answer anyway.
+ * Measured on 2026-09-12, before this change:
+ *
+ *   grid card    184×108  · 10 lines parsed, ~9 fit          → close enough
+ *   gallery tile 220×220  · 10 lines parsed, 15 fit          → the bottom
+ *                                                              HALF of every
+ *                                                              tile was empty
+ *   csv, either  · 6 rows × 4 cols whatever the box was, and budget.csv has
+ *                  six columns, so two of them were simply never shown
+ *
+ * The owner's instruction is "as much as we can fit" (2026-09-12), so the box
+ * decides: the parser hands over more than any box can show and the box
+ * clips what it cannot, which is what `overflow: hidden` and the bottom fade
+ * on `.fe-fprev` have always been for. These are therefore CEILINGS on work
+ * and DOM, not layout constants — big enough for the largest tile we draw
+ * with room over it, small enough that a 400-file folder stays cheap.
+ */
+const MAX_LINES = 24;
+/** Characters kept per line. The box clips long lines anyway; this bounds
+ *  the DOM when a minified file arrives as one 8 KB line. */
+const MAX_LINE_CHARS = 120;
+const MAX_ROWS = 16;
+/** Columns parsed. How many are DRAWN follows the box: the grid lays the
+ *  cells out on tracks with a readable minimum width and clips the overflow,
+ *  so a wide tile shows more of the table than a narrow one without either
+ *  view knowing anything the other does not. */
+const MAX_COLS = 8;
+/** Cache ceiling, mirroring useThumbs' own. Parsed previews are a few hundred
+ *  bytes each, so this is generous. */
+const MAX_CACHED = 400;
+
+/* ------------------------------------------------------------ can we read */
+
+/** The two tabular extensions. `sheet` as a FAMILY also holds xls/xlsx/ods,
+ *  which are zip containers — reading their first bytes gives binary. */
+const TABLE_EXTS = new Set(['csv', 'tsv']);
+
+/**
+ * Is this row a deleted thing?
+ *
+ * ⚠ Two fields, because the two ways filex shows you a deleted file disagree.
+ * A normal listing marks a soft-deleted row with `trashed`. The TRASH VIEW
+ * does not: `FileExplorer.loadTrash` builds its rows from `TrashEntry` by hand
+ * and that literal sets neither `trashed` nor `size` — it writes `file_size`
+ * and stamps `extra_metadata.deleted_at`.
+ *
+ * Which means the size ceiling below was already excluding the whole trash
+ * view, by accident, because `size` came back undefined. That is not a guard,
+ * it is a coincidence one line in an unrelated file would end: the trash row's
+ * `path` points at the trash KEY, not at the file it used to be, so a content
+ * read there fetches a 404 for every row in the folder.
+ */
+function isTrashRow(node: FileNode): boolean {
+  if (node.trashed) return true;
+  const meta = node.extra_metadata;
+  return !!meta && typeof meta === 'object' && 'deleted_at' in meta;
+}
+
+/**
+ * Which preview this node could have, ignoring whether anything is wired up.
+ *
+ * Built on `iconFamilyFor` rather than on a second extension list: the
+ * families ARE the taxonomy (filex lesson #67), so a new extension registered
+ * for the icon set becomes previewable in the same edit. `svg` belongs to the
+ * `image` family and is therefore excluded here — it is text, but it has a
+ * real thumbnail, and the real one wins.
+ */
+export function previewKindFor(node: FileNode): PreviewKind | null {
+  if (node.type !== 'file') return null;
+  if (node.basename === '.trash' || node.mime_type === 'inode/storage') return null;
+  if (isTrashRow(node)) return null;
+  // ⚠ A node with NO size is excluded too, not just an empty one: the size is
+  // what the 4 MB ceiling is checked against, and "we don't know" is not a
+  // basis for deciding to read a file. Every row `projectFileNodes` emits
+  // carries one.
+  const size = node.size ?? 0;
+  if (size <= 0 || size > MAX_FILE_BYTES) return null;
+  const ext = (node.extension || '').trim().toLowerCase();
+  if (TABLE_EXTS.has(ext)) return 'table';
+  const family = iconFamilyFor(node);
+  if (family === 'code') return 'code';
+  if (family === 'text') return 'text';
+  return null;
+}
+
+/**
+ * Is this node's thumbnail a PAGE — the first page of a document, rather than
+ * a picture that was already the shape it wanted to be?
+ *
+ * It matters because of where the card crops. A thumbnail box is landscape
+ * (184×108 in the grid) and a page is portrait, so `object-fit: cover` has to
+ * throw away most of the height, and WHICH part it throws away is the whole
+ * question. Centred — the default, and what this did before — discards the
+ * top, which on a document is the letterhead, the title and the date: the
+ * only part that says which document it is. Measured on 2026-09-12 against a
+ * reference deployment carrying the same defect, five different PDFs sharing
+ * one template produced five cards nobody could tell apart, because the only
+ * thing that differed between them was the title that had been cropped away.
+ *
+ * So pages anchor to the top and photographs stay centred, and this is the
+ * one place that decides which is which. Built on `iconFamilyFor` rather than
+ * a private extension list, for the same reason the preview kinds are: the
+ * families ARE the taxonomy (filex lesson #67).
+ */
+export function drawsAsPage(node: FileNode): boolean {
+  if (node.type !== 'file') return false;
+  switch (iconFamilyFor(node)) {
+    case 'pdf':
+    case 'doc':
+    case 'sheet':
+    case 'slides':
+      return true;
+    default:
+      return false;
+  }
+}
+
+/**
+ * Is this node's thumbnail a still taken from a MOVING picture?
+ *
+ * A frame lifted out of a video is, on a card, indistinguishable from a
+ * photograph — which is the one thing a person needs to know before they
+ * click it. The views draw a play badge over these, so the answer lives here
+ * rather than in each of them.
+ */
+export function drawsAsVideo(node: FileNode): boolean {
+  return node.type === 'file' && iconFamilyFor(node) === 'video';
+}
+
+/* --------------------------------------------------------------- parsing */
+
+/**
+ * Openers worth a tint. Deliberately small and deliberately language-agnostic:
+ * the brief's own instruction is that plain text beats fake colour, so a token
+ * is tinted only when it really is a keyword. A JSON file opening on `{`, or a
+ * YAML file opening on a key, gets no colour at all — which is the correct
+ * answer, not a missing feature.
+ */
+const KEYWORDS = new Set([
+  'import', 'export', 'from', 'require', 'include', 'use', 'using', 'package',
+  'module', 'namespace', 'const', 'let', 'var', 'function', 'func', 'fn', 'def',
+  'class', 'struct', 'enum', 'interface', 'type', 'impl', 'trait',
+  'public', 'private', 'protected', 'static', 'async', 'await', 'return',
+  'if', 'else', 'for', 'while', 'switch', 'case', 'try', 'catch',
+  'select', 'insert', 'update', 'delete', 'create', 'alter', 'drop',
+]);
+
+/** Markdown-ish line markers — the only thing tinted in a `text` preview. */
+const TEXT_MARKER = /^(#{1,6}|[-*+]|>|\d+\.)$/;
+
+/** Strip the punctuation a keyword is usually wearing (`const,` `if(` `def:`). */
+function bareToken(token: string): string {
+  return token.replace(/[(){}[\];:,.]+$/, '').toLowerCase();
+}
+
+function toLine(raw: string, kind: PreviewKind): PreviewLine {
+  const clipped = raw.length > MAX_LINE_CHARS ? raw.slice(0, MAX_LINE_CHARS) : raw;
+  const m = /^(\s*)(\S+)([\s\S]*)$/.exec(clipped);
+  if (!m) return { indent: '', tint: '', text: clipped };
+  const [, indent, first, rest] = m;
+  const tintable =
+    kind === 'code' ? KEYWORDS.has(bareToken(first)) : TEXT_MARKER.test(first);
+  if (!tintable) return { indent: '', tint: '', text: clipped };
+  return { indent, tint: first, text: rest };
+}
+
+/**
+ * Split one delimited row into cells, honouring `"…"` quoting (and `""` as an
+ * escaped quote) so a value containing the separator does not become two
+ * columns. Small on purpose — this draws six rows on a 184px card, it is not
+ * a CSV parser and must never grow into one.
+ */
+export function splitCells(line: string, sep: string): string[] {
+  const out: string[] = [];
+  let cur = '';
+  let quoted = false;
+  for (let i = 0; i < line.length; i++) {
+    const c = line[i];
+    if (quoted) {
+      if (c === '"') {
+        if (line[i + 1] === '"') {
+          cur += '"';
+          i++;
+        } else {
+          quoted = false;
+        }
+      } else {
+        cur += c;
+      }
+    } else if (c === '"') {
+      quoted = true;
+    } else if (c === sep) {
+      out.push(cur);
+      cur = '';
+    } else {
+      cur += c;
+    }
+  }
+  out.push(cur);
+  return out;
+}
+
+/** `,` normally; `\t` for a .tsv; `;` when the first row clearly uses it —
+ *  the shape Excel writes in most of Europe, Turkey included. */
+function separatorFor(ext: string, firstLine: string): string {
+  if (ext === 'tsv') return '\t';
+  if (!firstLine.includes(',') && firstLine.includes(';')) return ';';
+  return ',';
+}
+
+/**
+ * Bytes → a drawable preview, or null when the bytes are not text after all
+ * (a `.json` that is really a binary blob, ciphertext, a mislabelled file).
+ *
+ * `truncated` says the byte cap cut the stream, in which case the last line is
+ * dropped: half a line of source looks like a bug, not like a preview.
+ */
+export function parsePreview(
+  bytes: Uint8Array,
+  kind: PreviewKind,
+  ext: string,
+  truncated: boolean,
+): FilePreview | null {
+  // A NUL in the first few KB is the cheapest reliable "this is not text".
+  for (let i = 0; i < bytes.length; i++) {
+    if (bytes[i] === 0) return null;
+  }
+  const text = new TextDecoder('utf-8', { fatal: false }).decode(bytes);
+  // A decode full of replacement characters is binary wearing a text
+  // extension — or a file in an encoding we are not going to guess at.
+  let bad = 0;
+  for (const ch of text) if (ch === '�') bad++;
+  if (text.length > 0 && bad / text.length > 0.1) return null;
+
+  const lines = text.split(/\r\n|\r|\n/);
+  if (truncated && lines.length > 1) lines.pop();
+  // Blank lines at either end waste a box that only holds eight — and every
+  // text file that ends in a newline has one. Interior blanks stay: they are
+  // part of how the file looks, which is the whole point.
+  while (lines.length && lines[0].trim() === '') lines.shift();
+  while (lines.length && lines[lines.length - 1].trim() === '') lines.pop();
+  if (lines.length === 0) return null;
+
+  if (kind === 'table') {
+    const sep = separatorFor(ext, lines[0]);
+    const rows = lines
+      .filter((l) => l.trim() !== '')
+      .slice(0, MAX_ROWS)
+      .map((l) => splitCells(l, sep).slice(0, MAX_COLS).map((c) => c.trim().slice(0, 24)));
+    if (rows.length === 0) return null;
+    const cols = rows.reduce((n, r) => Math.max(n, r.length), 0);
+    for (const r of rows) while (r.length < cols) r.push('');
+    return { kind, lines: [], rows, cols };
+  }
+
+  return {
+    kind,
+    lines: lines.slice(0, MAX_LINES).map((l) => toLine(l, kind)),
+    rows: [],
+    cols: 0,
+  };
+}
+
+/* ---------------------------------------------------------------- loading */
+
+export interface PreviewLoaderOptions {
+  /** Same prefix the explorer hands the views. `undefined` = no API wired
+   *  (a legacy embedder on an explicit `endpoint`) → the loader stays off. */
+  apiBase?: string;
+  /**
+   * ⚠ ASYNC, and it is the whole reason this signature is a function and not
+   * an object. Spreading a Promise into a headers literal yields `{}` — the
+   * request goes out with no Authorization and 401s with nothing in the
+   * console. Every call site here `await`s it.
+   */
+  authHeaders?: () => Record<string, string> | Promise<Record<string, string>>;
+  credentials?: RequestCredentials;
+  /**
+   * Answered on every decision, not once at construction: "is reading file
+   * bytes off right now?". The explorer passes its encrypted-folder state —
+   * inside one, every body on the wire is ciphertext, and fetching 8 KB of it
+   * to discover that it does not decode is a request spent to learn nothing.
+   */
+  disabled?: () => boolean;
+}
+
+export interface FilePreviewLoader {
+  /** False when nothing is wired — callers must then keep their old markup. */
+  readonly enabled: boolean;
+  /** The kind this node would get, or null (including when disabled). */
+  kindFor: (node: FileNode) => PreviewKind | null;
+  /** Reactive read. null = not loaded (yet), or never. */
+  get: (node: FileNode) => FilePreview | null;
+  /** Template-ref sink: hand it the preview box and its node. */
+  bind: (el: Element | null, node: FileNode) => void;
+  /** In-flight + queued, for tests and measurement. */
+  stats: () => { loaded: number; inflight: number; queued: number; failed: number };
+  dispose: () => void;
+}
+
+/** path + version: an edited file re-reads, an untouched one never does. */
+function keyOf(node: FileNode): string {
+  const etag = typeof node.etag === 'string' ? node.etag : '';
+  const version = etag || String(node.last_modified ?? '') || String(node.size ?? '');
+  return `${node.path}${version}`;
+}
+
+export function createFilePreviews(opts: PreviewLoaderOptions): FilePreviewLoader {
+  const enabled =
+    opts.apiBase !== undefined &&
+    typeof opts.authHeaders === 'function' &&
+    typeof IntersectionObserver !== 'undefined' &&
+    typeof fetch === 'function';
+
+  const cache = ref<Record<string, FilePreview>>({});
+  const order: string[] = [];
+  const failed = new Set<string>();
+  const queued = new Set<string>();
+  const queue: FileNode[] = [];
+  const controllers = new Set<AbortController>();
+  /** element → the key it is currently observed for, so a re-render of the
+   *  same card does not re-observe and a recycled row does. */
+  const bound = new WeakMap<Element, string>();
+  let inflight = 0;
+  let observer: IntersectionObserver | null = null;
+  /** The observed element's node, kept until the callback fires. */
+  const watching = new Map<Element, FileNode>();
+
+  function previewUrl(path: string): string {
+    // resolveEndpoints is the one place that knows how apiBase becomes a
+    // manager URL; `?q=` + `&action=` is the pair every other caller sends.
+    const manager = resolveEndpoints({ apiBase: opts.apiBase }).manager;
+    const sep = manager.includes('?') ? '&' : '?';
+    const query = new URLSearchParams({ q: 'preview', action: 'preview', path });
+    return `${manager}${sep}${query.toString()}`;
+  }
+
+  function remember(key: string, value: FilePreview) {
+    if (order.length >= MAX_CACHED) {
+      const evict = order.shift();
+      if (evict) {
+        const next = { ...cache.value };
+        delete next[evict];
+        cache.value = next;
+      }
+    }
+    order.push(key);
+    cache.value = { ...cache.value, [key]: value };
+  }
+
+  /**
+   * Read at most `MAX_BYTES` of the body, whatever the server decided to send.
+   * A 206 is already short; a 200 from a driver that cannot seek is the whole
+   * file, and cancelling the reader is what stops it.
+   */
+  async function readHead(res: Response): Promise<{ bytes: Uint8Array; truncated: boolean }> {
+    const body = res.body;
+    if (!body) {
+      const buf = new Uint8Array(await res.arrayBuffer());
+      return { bytes: buf.slice(0, MAX_BYTES), truncated: buf.length > MAX_BYTES };
+    }
+    const reader = body.getReader();
+    const chunks: Uint8Array[] = [];
+    let total = 0;
+    try {
+      while (total < MAX_BYTES) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        if (value && value.length) {
+          chunks.push(value);
+          total += value.length;
+        }
+      }
+    } finally {
+      try {
+        await reader.cancel();
+      } catch {
+        /* already closed */
+      }
+    }
+    const joined = new Uint8Array(Math.min(total, MAX_BYTES));
+    let at = 0;
+    for (const c of chunks) {
+      if (at >= joined.length) break;
+      joined.set(c.subarray(0, joined.length - at), at);
+      at += c.length;
+    }
+    return { bytes: joined, truncated: total >= MAX_BYTES };
+  }
+
+  async function load(node: FileNode, kind: PreviewKind): Promise<void> {
+    const key = keyOf(node);
+    const ctrl = new AbortController();
+    controllers.add(ctrl);
+    try {
+      // ⚠ The await. Without it this object holds a Promise under
+      // `authHeaders`, fetch drops it, and the request 401s silently.
+      const base = opts.authHeaders ? await opts.authHeaders() : {};
+      const res = await fetch(previewUrl(node.path), {
+        headers: { ...base, Accept: '*/*', Range: `bytes=0-${MAX_BYTES - 1}` },
+        credentials: opts.credentials,
+        signal: ctrl.signal,
+      });
+      if (!res.ok && res.status !== 206) throw new Error(String(res.status));
+      const { bytes, truncated } = await readHead(res);
+      ctrl.abort();
+      const ext = (node.extension || '').trim().toLowerCase();
+      const parsed = parsePreview(bytes, kind, ext, truncated);
+      if (!parsed) {
+        failed.add(key);
+        return;
+      }
+      remember(key, parsed);
+    } catch {
+      // 403/404/offline/not-really-text — the card keeps its type tile, and
+      // we do not retry inside this session (same policy as useThumbs).
+      failed.add(key);
+    } finally {
+      controllers.delete(ctrl);
+    }
+  }
+
+  function pump() {
+    while (inflight < MAX_INFLIGHT && queue.length > 0) {
+      const node = queue.shift()!;
+      const kind = previewKindFor(node);
+      queued.delete(keyOf(node));
+      if (!kind) continue;
+      inflight++;
+      void load(node, kind).finally(() => {
+        inflight--;
+        pump();
+      });
+    }
+  }
+
+  function enqueue(node: FileNode) {
+    const key = keyOf(node);
+    if (cache.value[key] || failed.has(key) || queued.has(key)) return;
+    queued.add(key);
+    queue.push(node);
+    pump();
+  }
+
+  function ensureObserver(): IntersectionObserver | null {
+    if (!enabled) return null;
+    if (!observer) {
+      observer = new IntersectionObserver(
+        (entries) => {
+          for (const entry of entries) {
+            if (!entry.isIntersecting) continue;
+            const node = watching.get(entry.target);
+            observer?.unobserve(entry.target);
+            watching.delete(entry.target);
+            if (node) enqueue(node);
+          }
+        },
+        { rootMargin: '150px' },
+      );
+    }
+    return observer;
+  }
+
+  function kindFor(node: FileNode): PreviewKind | null {
+    if (!enabled) return null;
+    if (opts.disabled?.()) return null;
+    return previewKindFor(node);
+  }
+
+  return {
+    enabled,
+    kindFor,
+    get(node: FileNode): FilePreview | null {
+      if (!enabled) return null;
+      return cache.value[keyOf(node)] ?? null;
+    },
+    bind(el: Element | null, node: FileNode) {
+      if (!el || !kindFor(node)) return;
+      const key = keyOf(node);
+      if (bound.get(el) === key) return;
+      bound.set(el, key);
+      if (cache.value[key] || failed.has(key)) return;
+      const io = ensureObserver();
+      if (!io) return;
+      watching.set(el, node);
+      io.observe(el);
+    },
+    stats: () => ({
+      loaded: order.length,
+      inflight,
+      queued: queue.length,
+      failed: failed.size,
+    }),
+    dispose() {
+      observer?.disconnect();
+      observer = null;
+      watching.clear();
+      for (const c of controllers) c.abort();
+      controllers.clear();
+      queue.length = 0;
+      queued.clear();
+    },
+  };
+}

package/src/lib/listing.ts

@@ -17,6 +17,27 @@ export function stripAdapter(p: string): string {
   return idx === -1 ? p : p.slice(idx + 3);
 }
 
+/**
+ * The folder a row sits in, without its storage: `My files://Photos/a.jpg` →
+ * `Photos`, and `''` for a row at a storage's root.
+ *
+ * ⚠⚠ Split on the FIRST `://` (`stripAdapter`), never with a URL-scheme
+ * pattern. The list, the grid and the gallery each carried their own copy that
+ * stripped `[a-z][a-z0-9+.-]*` followed by `://` — the RFC 3986 shape of a SCHEME, which a
+ * storage name is not. A name with a space in it (`My files`, the one the
+ * screenshot fixtures use, and a perfectly ordinary thing to call a drive)
+ * does not match it, so nothing was stripped, the "folder" became
+ * `My files://Photos`, and the Location column printed
+ * `My files/My files://Photos` — the storage twice and the scheme on show.
+ * Measured on Starred, 2026-09-14. An underscore or a leading digit broke it
+ * the same way.
+ */
+export function parentDirOf(path: string): string {
+  const rel = stripAdapter(String(path ?? ''));
+  const idx = rel.lastIndexOf('/');
+  return idx === -1 ? '' : rel.slice(0, idx);
+}
+
 /**
  * Hide system/internal entries the user must never see as files:
  * thumbnails, version history, the soft-delete store, keepdir markers,
@@ -220,6 +241,11 @@ export async function hydrateTrashRow(
  * 2026-09-04). A second copy of a mapping is a second chance to forget it.
  */
 export const VIRTUAL_SEGMENTS: Record<string, string> = {
+  /* gorunum:v3-shell — Home is a destination like the rest, so it gets a
+     sentinel like the rest: a restored tab, a reload and a pasted `#.home`
+     all have to reopen the overview instead of asking the backend for a
+     folder called `.home` and landing on "not found". */
+  '.home': 'node.home',
   '.trash': 'node.trash',
   '.recent': 'node.recent',
   '.starred': 'node.starred',
@@ -285,3 +311,49 @@ export function virtualSegmentLabel(segment: string, t: (key: string) => string)
   const tag = tagOfSegment(segment);
   return tag ? `#${tag}` : '';
 }
+
+/**
+ * True when a USER PATH is one of the virtual views rather than a folder that
+ * lives in a storage — `.trash`, `.recent`, `.starred`, `.shared`, `.home`,
+ * `.tag~<name>`.
+ *
+ * ⚠⚠ Why a predicate and not just "call `virtualSegmentLabel` and see". The
+ * caller that needs this is deciding whether to QUALIFY the path, and
+ * qualifying a sentinel destroys it: in multi-storage mode `qualify('.starred')`
+ * splits the first segment off as the adapter and answers `.starred://`, so
+ * from there on the sentinel is a STORAGE NAME. A storage name is not a path
+ * segment, `virtualSegmentLabel` is never asked about it, and the breadcrumb
+ * prints `.starred` — which is exactly what the owner saw on 2026-09-13, in
+ * every virtual view at once, the night the pane was extracted into
+ * `FilePane.vue` and each pane began deriving its own crumb inputs. The
+ * resolver was being called the whole time, with an argument that could not
+ * match.
+ *
+ * ⚠ One definition, here beside the map and the tag prefix it asks about, so
+ * "is this a view or a folder?" cannot be answered two ways: `FileExplorer`'s
+ * `virtualViewOf()` (which also names the KIND) is built on this one.
+ */
+export function isVirtualViewPath(path: string): boolean {
+  const clean = String(path ?? '').replace(/^\/+|\/+$/g, '');
+  if (!clean) return false;
+  return !!VIRTUAL_SEGMENTS[clean] || !!tagOfSegment(clean);
+}
+
+/**
+ * gorunum:v1 — folders before files, whatever the sort column is.
+ *
+ * Every file manager a person has used puts directories first, and the reason
+ * is not taste: a directory is a place and a file is a thing, and a listing
+ * that interleaves them makes the reader check the icon of every row to find
+ * out where they can go next. Sorting by size or date interleaves them worst
+ * of all, because a folder has neither.
+ *
+ * Applied as the PRIMARY comparator by both views, so it cannot mean one
+ * thing in the list and another in the grid — the two sorts are separate code
+ * and this is the rule they have to share (filex lesson #67).
+ */
+export function byFoldersFirst(a: { type?: string }, b: { type?: string }): number {
+  const ad = a.type === 'dir' ? 0 : 1;
+  const bd = b.type === 'dir' ? 0 : 1;
+  return ad - bd;
+}