flea-qml 0.0.0-stage → 0.1.0

package/src/figure.js

@@ -0,0 +1,132 @@
+// Mermaid diagrams for both Markdown previews: the passive HTML page (src/markdown-html.js) and
+// the block view's figures (ui/FigureService.qml, through the backend's `figure` request).
+//
+// Pele runs in one Bun Worker (src/figure-thread.js), started on the first diagram and ended
+// after a quiet spell. Diagrams go to it one at a time, each under a deadline: a layout still
+// running then terminates the Worker, that diagram fails with a reason, and the next one starts
+// a fresh Worker. The answers are SVG checked against an allowlist (src/figure-svg.js) and
+// held in a small cache keyed by source and theme.
+import { MERMAID_LIMIT } from "./figure-svg.js";
+
+export const FIGURE_TIMEOUT_MS = 5000;
+const IDLE_MS = 30000;
+const CACHE_MAX = 64;
+// A Gantt chart draws today's date: it is asked for this day's noon UTC, so every zone draws the day it is.
+const MIDDAY_HOUR = 12;
+
+const HEX = /^#[0-9a-f]{6}$/i;
+const ADVANCES = 95; // printable ASCII, " " to "~"
+
+/**
+ * The theme a diagram is drawn under, from what a preview sends: colours as #rrggbb, a font
+ * family, a body size, and the font's advance tables (thousandths of an em per character from
+ * " " to "~", regular and bold) so every label is sized from the font that draws it. Anything
+ * else is dropped, so a theme cannot carry markup into the SVG.
+ */
+export function figureTheme(theme = {}, source = "", now = new Date()) {
+  const colour = (value, fallback) => (HEX.test(String(value ?? "")) ? String(value) : fallback);
+  const table = (value) => Array.isArray(value) && value.length === ADVANCES && value.every((n) => Number.isFinite(n) && n >= 0)
+    ? value.map(Number) : [];
+  const fg = colour(theme.fg ?? theme.foreground, "#d8dee9");
+  const out = {
+    bg: colour(theme.bg ?? theme.background, "#171b22"), fg,
+    accent: colour(theme.accent, fg), muted: colour(theme.muted, ""), surface: colour(theme.surface, ""),
+    font: /^[\p{L}\p{N} _.,'-]{1,80}$/u.test(String(theme.font ?? "")) ? String(theme.font) : "sans-serif",
+    bodyPx: Math.max(8, Math.min(40, Number(theme.bodyPx) || 14)),
+    advances: table(theme.advances), boldAdvances: table(theme.boldAdvances),
+  };
+  if (/(?:^|%%)\s*gantt\b/im.test(source))
+    out.today = Date.UTC(now.getFullYear(), now.getMonth(), now.getDate(), MIDDAY_HOUR);
+  return out;
+}
+
+const cache = new Map();
+const queue = [];
+let worker = null, active = null, idleTimer = null, nextId = 0;
+
+function stopWorker() {
+  clearTimeout(idleTimer);
+  idleTimer = null;
+  worker?.terminate();
+  worker = null;
+}
+
+function finish(job, answer) {
+  clearTimeout(job.timer);
+  if (answer.svg !== undefined) {
+    cache.set(job.key, answer);
+    if (cache.size > CACHE_MAX) cache.delete(cache.keys().next().value);
+  }
+  job.resolve(answer);
+}
+
+function pump() {
+  if (active || !queue.length) {
+    if (!active && worker && !idleTimer) idleTimer = setTimeout(stopWorker, IDLE_MS);
+    return;
+  }
+  clearTimeout(idleTimer);
+  idleTimer = null;
+  active = queue.shift();
+  if (!worker) {
+    worker = new Worker(new URL("./figure-thread.js", import.meta.url).href);
+    // The Worker never keeps the backend (or a test run) alive by itself.
+    worker.unref?.();
+    worker.onmessage = ({ data }) => {
+      if (!active || data.id !== active.id) return;
+      const job = active;
+      active = null;
+      finish(job, data.svg !== undefined ? { svg: data.svg } : { error: data.error || "render failed" });
+      pump();
+    };
+    worker.onerror = (event) => {
+      event.preventDefault?.();
+      const job = active;
+      active = null;
+      stopWorker();
+      if (job) finish(job, { error: String(event.message || "diagram engine failed") });
+      pump();
+    };
+  }
+  const job = active;
+  job.timer = setTimeout(() => {
+    if (active !== job) return;
+    active = null;
+    stopWorker();
+    finish(job, { error: `diagram took over ${job.timeout / 1000} s` });
+    pump();
+  }, job.timeout);
+  worker.postMessage({ id: job.id, source: job.source, theme: job.theme });
+}
+
+/**
+ * Draws one Mermaid diagram. Answers {svg} or {error}; never rejects. `theme` is what a preview
+ * sends (see figureTheme); `timeout` bounds the layout in ms.
+ */
+export function renderDiagram(source, theme = {}, { timeout = FIGURE_TIMEOUT_MS } = {}) {
+  source = String(source ?? "");
+  if (!source.trim()) return Promise.resolve({ error: "empty diagram" });
+  if (source.length > MERMAID_LIMIT) return Promise.resolve({ error: "diagram over 32 KiB" });
+  const drawn = figureTheme(theme, source);
+  const key = JSON.stringify([source, drawn]);
+  const hit = cache.get(key);
+  if (hit) {
+    cache.delete(key);
+    cache.set(key, hit);
+    return Promise.resolve(hit);
+  }
+  return new Promise((resolve) => {
+    queue.push({ id: ++nextId, key, source, theme: drawn, timeout, resolve });
+    pump();
+  });
+}
+
+/** Ends the Worker and forgets the cache; queued diagrams fail. For tests and shutdown. */
+export function stopFigures() {
+  const pending = active ? [active, ...queue] : [...queue];
+  active = null;
+  queue.length = 0;
+  stopWorker();
+  cache.clear();
+  for (const job of pending) finish(job, { error: "diagram engine stopped" });
+}

package/src/find.js

@@ -0,0 +1,55 @@
+// The commands Find runs (find for names, grep for contents) and folder sizes run (du), which ui/Backend.qml spawns itself and reads as a stream; the backend only
+// names it. Looked for the way src/highlight.js looks for jsmdcui: a bunmsh checkout beside this
+// repository runs its entry with Bun, then a `bunmsh` on PATH is spawned as it is, and last the
+// system's own `find`. Windows' find.exe searches text inside files and takes none of these
+// arguments, so there it is never the fallback.
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+
+const BUN = Bun.which("bun") || process.argv0;
+const REPO = join(import.meta.dir, "..");
+
+let found;
+/** The argv prefix a scope and its expression follow, or null when nothing can run Find. */
+export function findCommand() {
+  if (found !== undefined) return found;
+  found = null;
+  const beside = join(REPO, "..", "bunmsh", "index.js");
+  if (existsSync(beside)) return (found = [BUN, beside, "-cc", "builtin", "find"]);
+  const bunmsh = Bun.which("bunmsh");
+  if (bunmsh) return (found = [bunmsh, "-cc", "builtin", "find"]);
+  const system = process.platform === "win32" ? null : Bun.which("find");
+  if (system) return (found = [system]);
+  return found;
+}
+
+let grepFound;
+/** The argv prefix a content search's options follow, or null when nothing can run grep. The
+ * system's grep needs --line-buffered to stream into a pipe; Find always passes it. */
+export function grepCommand() {
+  if (grepFound !== undefined) return grepFound;
+  grepFound = null;
+  const beside = join(REPO, "..", "bunmsh", "index.js");
+  if (existsSync(beside)) return (grepFound = [BUN, beside, "-cc", "builtin", "grep"]);
+  const bunmsh = Bun.which("bunmsh");
+  if (bunmsh) return (grepFound = [bunmsh, "-cc", "builtin", "grep"]);
+  const system = process.platform === "win32" ? null : Bun.which("grep");
+  if (system) return (grepFound = [system]);
+  return grepFound;
+}
+
+let duFound;
+/** The argv prefix a folder size's options follow (src/dirsize.js), found in Find's order: bunmsh
+ * beside this repository, a `bunmsh` on PATH, then the system's own du. Windows' du, where one is
+ * installed (Sysinternals), takes none of GNU's options, so there it is never the fallback. */
+export function duCommand() {
+  if (duFound !== undefined) return duFound;
+  duFound = null;
+  const beside = join(REPO, "..", "bunmsh", "index.js");
+  if (existsSync(beside)) return (duFound = [BUN, beside, "-cc", "builtin", "du"]);
+  const bunmsh = Bun.which("bunmsh");
+  if (bunmsh) return (duFound = [bunmsh, "-cc", "builtin", "du"]);
+  const system = process.platform === "win32" ? null : Bun.which("du");
+  if (system) return (duFound = [system]);
+  return duFound;
+}

package/src/flea.js

@@ -0,0 +1,39 @@
+// flea-qml's `flea`: the one program ui/ runs for everything it asks of the outside, through
+// ui/js/FleaBin.js as `bun src/flea.js ARGS`. Upstream's equivalent is the `flea` binary's
+// src/main.rs, whose other modes (--open, --run, --favourites, ...) are not ported yet.
+import { runBackend } from "./backend.js";
+import { readState, updateState } from "./uistore.js";
+import { render } from "./uistate.js";
+
+const args = process.argv.slice(2);
+
+// --ui-state prints the settled document; --ui-state PATCH merges one JSON object under the lock
+// and prints the result. Every refusal is one "flea: " sentence on stderr, nothing on stdout, exit 2.
+function uiState(rest) {
+  try {
+    if (rest.length > 1) throw new Error("--ui-state takes nothing, or one JSON object");
+    if (rest.length === 0) {
+      process.stdout.write(render(readState()));
+      return 0;
+    }
+    let patch;
+    try {
+      patch = JSON.parse(rest[0]);
+    } catch (error) {
+      throw new Error(`the ui.json patch is not JSON (${error.message})`);
+    }
+    process.stdout.write(render(updateState(patch)));
+    return 0;
+  } catch (error) {
+    process.stderr.write(`flea: ${error.message}\n`);
+    return 2;
+  }
+}
+
+const [mode, ...rest] = args;
+if (mode === "--backend") runBackend();
+else if (mode === "--ui-state") process.exit(uiState(rest));
+else {
+  console.error(`flea-qml: not implemented yet: ${args.join(" ") || "(no arguments)"}`);
+  process.exit(1);
+}

package/src/fsinfo.js

@@ -0,0 +1,39 @@
+// The `fsinfo` line: the listed directory's filesystem name and free bytes
+// (docs/protocol.md "fsinfo"). Upstream: src/backend/fsinfo.rs.
+import { readFileSync, statSync, statfsSync } from "node:fs";
+
+// Kernel dev_t, as glibc's major() and minor() split it.
+const majorOf = (dev) => Number(((dev >> 8n) & 0xfffn) | ((dev >> 32n) & ~0xfffn));
+const minorOf = (dev) => Number((dev & 0xffn) | ((dev >> 12n) & ~0xffn));
+
+// The mount holding a device id, by its "major:minor" in /proc/self/mountinfo. Every system tries
+// the same read; where there is no mount table it fails and the name stays empty, which the status
+// bar draws as no filesystem name.
+export function fsTypeOf(dev) {
+  let text = "";
+  try {
+    text = readFileSync("/proc/self/mountinfo", "utf8");
+  } catch {
+    return "";
+  }
+  const id = `${majorOf(dev)}:${minorOf(dev)}`;
+  for (const line of text.split("\n")) {
+    const fields = line.split(" ");
+    if (fields[2] !== id) continue;
+    const separator = fields.indexOf("-");
+    if (separator > 0) return fields[separator + 1] ?? "";
+  }
+  return "";
+}
+
+// statfs exists on Linux, macOS and Windows in Node; a runtime without it lands in the catch.
+export function fsinfo(path) {
+  try {
+    const dev = statSync(path || ".", { bigint: true }).dev,
+      fs = statfsSync(path || ".");
+    return { t: "fsinfo", fs: fsTypeOf(dev), free: fs.bavail * fs.bsize, path, class: "", tagable: false };
+  } catch {
+    // An unreadable path answers an empty fs with a free of 0 rather than a wrong number.
+    return { t: "fsinfo", fs: "", free: 0, path, class: "", tagable: false };
+  }
+}

package/src/highlight.js

@@ -0,0 +1,141 @@
+// Syntax colours for `code` lines, from jsmdcui's `--cat --edit FILE`, whose truecolor ANSI output
+// is read back into the protocol's roles: 0 the foreground, then red, green, yellow, blue, magenta
+// and cyan (docs/protocol.md "code"). Upstream runs `bat` for the same lines.
+// jsmdcui is looked for beside this repository first, then as `jmi` or `jsmdcui` on PATH, and its
+// a sibling checkout runs with Bun while PATH commands keep their own launcher semantics.
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+
+const BUN = Bun.which("bun") || process.argv0;
+const REPO = join(import.meta.dir, "..");
+
+let found;
+/** The command argv prefix, or null when none can be found. Looked up once per process. */
+export function jsmdcui() {
+  if (found !== undefined) return found;
+  found = null;
+  const beside = join(REPO, "..", "jsmdcui", "src", "index.js");
+  if (existsSync(beside)) return (found = [BUN, beside]);
+  for (const name of ["jmi", "jsmdcui"]) {
+    const command = Bun.which(name);
+    if (command) return (found = [command]);
+  }
+  return found;
+}
+
+// The six ANSI hues the roles name, as angles on the colour wheel.
+const HUES = [[1, 0], [3, 60], [2, 120], [6, 180], [4, 240], [5, 300]];
+const BASIC = { 1: 1, 2: 2, 3: 3, 4: 4, 5: 5, 6: 6 };
+
+// The role nearest a 24-bit colour; greys and near-greys are the foreground.
+function roleOfRgb(r, g, b) {
+  const max = Math.max(r, g, b), min = Math.min(r, g, b);
+  if (max === 0 || (max - min) / max < 0.25) return 0;
+  const d = max - min;
+  let hue = max === r ? ((g - b) / d) % 6 : max === g ? (b - r) / d + 2 : (r - g) / d + 4;
+  hue = (hue * 60 + 360) % 360;
+  let best = 0, distance = Infinity;
+  for (const [role, angle] of HUES) {
+    const off = Math.min(Math.abs(hue - angle), 360 - Math.abs(hue - angle));
+    if (off < distance) [best, distance] = [role, off];
+  }
+  return best;
+}
+
+// xterm's 256 colours: the cube and the greys, by their RGB, and the first sixteen by name.
+function roleOf256(n) {
+  if (n < 16) return BASIC[n % 8] ?? 0;
+  if (n >= 232) return 0;
+  const i = n - 16, level = (v) => (v === 0 ? 0 : 55 + v * 40);
+  return roleOfRgb(level(Math.floor(i / 36)), level(Math.floor(i / 6) % 6), level(i % 6));
+}
+
+/** One line of ANSI text as a flat run list [role, text, role, text, ...]; [] when empty. */
+export function runsOf(line) {
+  const runs = [];
+  let role = 0;
+  const push = (text) => {
+    if (!text) return;
+    if (runs.length && runs[runs.length - 2] === role) runs[runs.length - 1] += text;
+    else runs.push(role, text);
+  };
+  const pattern = /\x1b\[([0-9;]*)m/g;
+  let at = 0;
+  for (let m; (m = pattern.exec(line)); at = pattern.lastIndex) {
+    push(line.slice(at, m.index));
+    const codes = m[1] === "" ? [0] : m[1].split(";").map(Number);
+    for (let i = 0; i < codes.length; i++) {
+      const c = codes[i];
+      if (c === 0 || c === 39) role = 0;
+      else if (c >= 30 && c <= 37) role = BASIC[c - 30] ?? 0;
+      else if (c >= 90 && c <= 97) role = BASIC[c - 90] ?? 0;
+      else if (c === 38 && codes[i + 1] === 2) {
+        role = roleOfRgb(codes[i + 2], codes[i + 3], codes[i + 4]);
+        i += 4;
+      } else if (c === 38 && codes[i + 1] === 5) {
+        role = roleOf256(codes[i + 2]);
+        i += 2;
+      } else if (c === 48 && codes[i + 1] === 2) i += 4;
+      else if (c === 48 && codes[i + 1] === 5) i += 2;
+    }
+  }
+  push(line.slice(at));
+  return runs;
+}
+
+/**
+ * The coloured lines of `path` as run lists, or null when jsmdcui is missing, fails or is
+ * cancelled through `signal`. Every line of the file is returned; the caller takes its window.
+ */
+export async function highlightFile(path, signal, filetype = null) {
+  const command = jsmdcui();
+  if (!command) return null;
+  // Each highlight is a whole Bun process; a document with many code blocks in view
+  // must not start them all at once, so at most HIGHLIGHT_LIMIT run and the rest wait.
+  // A request cancelled while waiting never starts one.
+  if (!(await acquire(signal))) return null;
+  try {
+    const args = [...command, "--cat", "--edit"];
+    // jsmdcui settings use one dash: --filetype would name a different setting.
+    if (filetype) args.push("-filetype", filetype);
+    args.push(path);
+    const child = Bun.spawn(args, { stdout: "pipe", stderr: "ignore", stdin: "ignore", signal });
+    const [text, code] = await Promise.all([new Response(child.stdout).text(), child.exited]);
+    if (code !== 0 || signal?.aborted) return null;
+    return text.split("\n").map(runsOf);
+  } catch {
+    return null;
+  } finally {
+    release();
+  }
+}
+
+/** Highlight processes allowed at once. */
+export const HIGHLIGHT_LIMIT = 2;
+let running = 0;
+const waiting = [];
+// Resolves true when a slot is taken, false when `signal` aborts first.
+function acquire(signal) {
+  if (signal?.aborted) return Promise.resolve(false);
+  if (running < HIGHLIGHT_LIMIT) {
+    running++;
+    return Promise.resolve(true);
+  }
+  return new Promise((resolve) => {
+    const entry = { resolve };
+    const abort = () => {
+      const index = waiting.indexOf(entry);
+      if (index >= 0) waiting.splice(index, 1);
+      resolve(false);
+    };
+    entry.resolve = (taken) => { signal?.removeEventListener("abort", abort); resolve(taken); };
+    signal?.addEventListener("abort", abort, { once: true });
+    waiting.push(entry);
+  });
+}
+// A finished highlight hands its slot straight to the oldest waiting one.
+function release() {
+  const next = waiting.shift();
+  if (next) next.resolve(true);
+  else running--;
+}

package/src/html.js

@@ -0,0 +1,52 @@
+// Rebuild a passive fragment. Never use HTMLRewriter's transformed source output.
+import { open, constants } from 'node:fs/promises';
+import { officeKind, officePreview } from './office.js';
+export const HTML_TAGS = new Set('div h1 h2 h3 h4 h5 h6 p br b strong i em u s del pre code ul ol li blockquote table thead tbody tr th td hr sub sup'.split(' '));
+const OMIT = new Set('script style iframe object embed template svg math noembed noframes head'.split(' '));
+export const HTML_LIMIT = 1 << 20;
+export function previewHtml(source) {
+  if (Buffer.byteLength(source) > HTML_LIMIT) throw Error('HTML preview exceeds size limit');
+  const result = []; let hidden = 0;
+  new HTMLRewriter().on('*', { element(el) {
+    const tag = el.tagName;
+    const omit = OMIT.has(tag) || el.namespaceURI !== 'http://www.w3.org/1999/xhtml';
+    if (omit && el.canHaveContent) { hidden++; el.onEndTag(() => hidden--); }
+    if (omit || hidden || !HTML_TAGS.has(tag)) return;
+    result.push('<' + tag + '>');
+    if (el.canHaveContent) el.onEndTag(() => result.push('</' + tag + '>'));
+  }}).onDocument({ text(chunk) {
+    // Text callbacks include literal markup inside textarea/xmp/plaintext. It
+    // must stay text on reparse. Entities are NOT decoded before reconstruction.
+    if (!hidden) result.push(chunk.text.replaceAll('<', '&lt;').replaceAll('>', '&gt;'));
+  }}).transform(source);
+  return result.join('');
+}
+export async function html(request) {
+  const answer = {t:'html', slot:request.slot, token:request.token, state:'failed', html:'', total:0};
+  if (request.cancel) return null;
+  // A document or a deck is converted to the same fixed tags (src/office.js) and rebuilt like any
+  // other source, so nothing reaches the page that an HTML file could not put there.
+  const kind = officeKind(request.path);
+  if (kind === 'document' || kind === 'slides') {
+    try {
+      const preview = officePreview(request.path);
+      return {...answer,state:'ready',html:previewHtml(preview.html),total:preview.text.split('\n').filter(Boolean).length};
+    } catch { return answer; }
+  }
+  let file;
+  try {
+    file = await open(request.path, constants.O_RDONLY | constants.O_NONBLOCK);
+    const stat = await file.stat();
+    if (!stat.isFile() || stat.size > HTML_LIMIT) return answer;
+    const bytes = Buffer.alloc(HTML_LIMIT + 1); let count = 0;
+    while (count < bytes.length) {
+      const {bytesRead} = await file.read(bytes, count, bytes.length-count, null);
+      if (!bytesRead) break;
+      count += bytesRead;
+    }
+    if (count > HTML_LIMIT) return answer;
+    const source = bytes.subarray(0,count).toString('utf8');
+    return {...answer,state:'ready',html:previewHtml(source),total:source ? source.split('\n').length : 0};
+  } catch { return answer; }
+  finally { await file?.close(); }
+}

package/src/kinds.js

@@ -0,0 +1,89 @@
+// What a row is, from its name and its own stat alone: the emoji the row draws (`i`), its Kind
+// description and the class kind ordering groups by. No MIME database or other system file is read,
+// so every platform answers the same. The emoji set starts from bunmsh's fancy ls (src/fancy-ls.js),
+// with 📁 for a folder so 📦 can mean a package and 🗜️ a compressed archive.
+
+const S_IFMT = 0o170000,
+  S_IFLNK = 0o120000,
+  ANY_EXECUTE_BIT = 0o111;
+
+// [group, emoji, extensions, Kind]. A Kind given as a function is built from the upper-case
+// extension; a string is used as it is.
+const TABLE = [
+  ["image", "🖼️", "png jpg jpeg gif webp svg bmp ico avif heic", (x) => `${x} image`],
+  ["audio", "🎵", "mp3 wav flac ogg m4a aac opus mid midi", (x) => `${x} audio`],
+  ["video", "🎬", "mp4 mkv webm mov avi m4v mpeg mpg", (x) => `${x} video`],
+  // A .tar.gz names its outer layer, gz, so it is compressed; a bare .tar only packs.
+  ["archive", "🗜️", "zip gz tgz xz txz bz2 tbz2 zst tzst 7z rar lz lz4 lzma z", (x) => `${x} archive`],
+  ["package", "📦", "tar deb rpm apk jar war whl appimage msi dmg pkg snap flatpak cpio", (x) => `${x} package`],
+  ["disc", "💿", "iso img qcow2 vhd vhdx vmdk", (x) => `${x} disk image`],
+  ["pdf", "📕", "pdf", "PDF document"],
+  ["document", "📘", "doc docx odt rtf", (x) => `${x} document`],
+  ["spreadsheet", "📗", "xls xlsx ods csv tsv", (x) => `${x} spreadsheet`],
+  ["presentation", "📙", "ppt pptx odp key", (x) => `${x} presentation`],
+  ["markdown", "📝", "md markdown", "Markdown document"],
+  ["text", "📄", "txt log", (x) => `${x} text`],
+  ["font", "🔤", "ttf otf woff woff2", (x) => `${x} font`],
+  ["database", "🐬", "sql db sqlite sqlite3 db3", (x) => `${x} database`],
+  ["config", "🔣", "json yaml yml toml ini xml conf cfg", (x) => `${x} data`],
+  ["shell", "💲", "sh bash zsh fish bat cmd ps1", (x) => `${x} script`],
+  ["binary", "💾", "bin dat o obj so a dll lib dylib class pyc wasm", (x) => `${x} binary`],
+  // Source code, one language per row.
+  ["code", "🟨", "js mjs cjs", "JavaScript"],
+  ["code", "🟦", "ts mts cts", "TypeScript"],
+  ["code", "🐍", "py", "Python script"],
+  ["code", "🔧", "c", "C source"],
+  ["code", "🧩", "h", "C header"],
+  ["code", "➕", "cpp cc cxx hpp hh hxx", "C++ source"],
+  ["code", "🔧", "cs", "C# source"],
+  ["code", "🦀", "rs", "Rust source"],
+  ["code", "🐹", "go", "Go source"],
+  ["code", "☕", "java", "Java source"],
+  ["code", "🟪", "kt kts", "Kotlin source"],
+  ["code", "💎", "rb", "Ruby script"],
+  ["code", "🐘", "php", "PHP script"],
+  ["code", "🌙", "lua", "Lua script"],
+  ["code", "🎯", "dart", "Dart source"],
+  ["code", "❄️", "nix", "Nix expression"],
+  ["code", "🌐", "html htm", "HTML document"],
+  ["code", "🎨", "css", "CSS stylesheet"],
+  ["code", "🐳", "dockerfile", "Dockerfile"],
+];
+const BY_EXTENSION = new Map();
+for (const [group, icon, extensions, kind] of TABLE)
+  for (const ext of extensions.split(" ")) BY_EXTENSION.set(ext, { group, icon, kind });
+// Files known by their whole name rather than an extension, compared case-insensitively.
+const BY_NAME = new Map([
+  ["dockerfile", BY_EXTENSION.get("dockerfile")],
+  ["containerfile", BY_EXTENSION.get("dockerfile")],
+]);
+
+export const FOLDER = "📁",
+  LINK = "🔗",
+  BROKEN_LINK = "🚫",
+  PROGRAM = "⚙️",
+  OTHER = "📄";
+
+export function extensionOf(name) {
+  const dot = name.lastIndexOf(".");
+  return dot > 0 && dot < name.length - 1 ? name.slice(dot + 1).toLowerCase() : "";
+}
+
+/**
+ * { icon, kind, group } for a row. `group` is the class kind ordering compares and kind grouping
+ * reads ("folder", "image", ...); `target` is a symlink's resolved stat, or null when it is broken.
+ */
+export function describeKind(name, isDir, mode, target) {
+  if (isDir) return { icon: FOLDER, kind: "Folder", group: "folder" };
+  const ext = extensionOf(name),
+    upper = ext.toUpperCase(),
+    known = BY_NAME.get(name.toLowerCase()) ?? BY_EXTENSION.get(ext);
+  let icon, kind, group;
+  if (known) [icon, kind, group] = [known.icon, typeof known.kind === "function" ? known.kind(upper) : known.kind, known.group];
+  else if ((mode & S_IFMT) !== S_IFLNK && mode & ANY_EXECUTE_BIT) [icon, kind, group] = [PROGRAM, "Program", "program"];
+  // An extension nothing names may still be text, so it keeps the plain page rather than the disk.
+  else [icon, kind, group] = [OTHER, ext ? `${upper} file` : "File", "file"];
+  // A link draws as a link, whatever it names; a link to a folder still sorts with files by its own name.
+  if ((mode & S_IFMT) === S_IFLNK) icon = target === null ? BROKEN_LINK : LINK;
+  return { icon, kind, group };
+}