@hienlh/ppm 0.17.57 → 0.18.1

package/src/web/components/os-explorer/explorer-store.ts

@@ -0,0 +1,179 @@
+/**
+ * Per-window explorer state, keyed by floating-window id.
+ *
+ * Each window browses independently (own path, history, selection, filter), so the state
+ * cannot live in a single global slice. View preferences are the exception: sort, view
+ * mode and the hidden-files toggle are user settings and are shared plus persisted.
+ *
+ * Windows also have to agree about the disk. After any mutation the acting window calls
+ * `fsChanged(dir)` and every window currently showing that directory refetches, which is
+ * what makes "cut here, paste there" look instantaneous in both frames.
+ */
+
+import { create } from "zustand";
+import type { FsBreadcrumb, FsEntry } from "@/lib/fs-api";
+
+export type SortKey = "name" | "size" | "modified" | "kind";
+export type SortDir = "asc" | "desc";
+export type ViewMode = "list" | "icons" | "columns";
+
+export interface ExplorerError {
+  message: string;
+  code: string;
+  hint?: string;
+}
+
+/** Inline editing state: renaming an existing entry, or naming a new one. */
+export type InlineEdit =
+  | { kind: "rename"; path: string; initial: string }
+  | { kind: "new-file" | "new-folder"; initial: string };
+
+export interface ExplorerSlice {
+  path: string;
+  /** Visited paths; `historyIndex` points at the current one. */
+  history: string[];
+  historyIndex: number;
+  entries: FsEntry[];
+  breadcrumbs: FsBreadcrumb[];
+  parent: string | null;
+  sep: string;
+  truncated: boolean;
+  loading: boolean;
+  error: ExplorerError | null;
+  selection: Set<string>;
+  /** Range-selection anchor; shift-click extends from here. */
+  anchor: string | null;
+  filter: string;
+  inlineEdit: InlineEdit | null;
+}
+
+export interface ExplorerViewPrefs {
+  sort: { key: SortKey; dir: SortDir };
+  viewMode: ViewMode;
+  showHidden: boolean;
+}
+
+const VIEW_PREFS_KEY = "ppm-explorer-view";
+
+const DEFAULT_PREFS: ExplorerViewPrefs = {
+  sort: { key: "name", dir: "asc" },
+  viewMode: "list",
+  showHidden: false,
+};
+
+function loadPrefs(): ExplorerViewPrefs {
+  try {
+    const raw = localStorage.getItem(VIEW_PREFS_KEY);
+    if (!raw) return DEFAULT_PREFS;
+    const parsed = JSON.parse(raw) as Partial<ExplorerViewPrefs>;
+    return {
+      sort: parsed.sort?.key ? parsed.sort : DEFAULT_PREFS.sort,
+      viewMode: parsed.viewMode ?? DEFAULT_PREFS.viewMode,
+      showHidden: parsed.showHidden ?? DEFAULT_PREFS.showHidden,
+    };
+  } catch {
+    return DEFAULT_PREFS;
+  }
+}
+
+function savePrefs(prefs: ExplorerViewPrefs): void {
+  try {
+    localStorage.setItem(VIEW_PREFS_KEY, JSON.stringify(prefs));
+  } catch {
+    /* quota or private mode — preferences simply do not persist */
+  }
+}
+
+function emptySlice(path: string): ExplorerSlice {
+  return {
+    path,
+    history: [path],
+    historyIndex: 0,
+    entries: [],
+    breadcrumbs: [],
+    parent: null,
+    sep: "/",
+    truncated: false,
+    loading: true,
+    error: null,
+    selection: new Set(),
+    anchor: null,
+    filter: "",
+    inlineEdit: null,
+  };
+}
+
+interface ExplorerStore extends ExplorerViewPrefs {
+  slices: Record<string, ExplorerSlice>;
+  /** Create the slice for a window if it does not exist yet. */
+  ensure(id: string, path: string): void;
+  /** Drop a window's slice when it closes. */
+  discard(id: string): void;
+  patch(id: string, partial: Partial<ExplorerSlice>): void;
+  setPrefs(partial: Partial<ExplorerViewPrefs>): void;
+}
+
+export const useExplorerStore = create<ExplorerStore>((set, get) => ({
+  ...loadPrefs(),
+  slices: {},
+
+  ensure: (id, path) => {
+    if (get().slices[id]) return;
+    set((s) => ({ slices: { ...s.slices, [id]: emptySlice(path) } }));
+  },
+
+  discard: (id) => {
+    set((s) => {
+      if (!s.slices[id]) return s;
+      const slices = { ...s.slices };
+      delete slices[id];
+      return { slices };
+    });
+  },
+
+  patch: (id, partial) => {
+    set((s) => {
+      const current = s.slices[id];
+      if (!current) return s;
+      return { slices: { ...s.slices, [id]: { ...current, ...partial } } };
+    });
+  },
+
+  setPrefs: (partial) => {
+    set((s) => {
+      const next: ExplorerViewPrefs = {
+        sort: partial.sort ?? s.sort,
+        viewMode: partial.viewMode ?? s.viewMode,
+        showHidden: partial.showHidden ?? s.showHidden,
+      };
+      savePrefs(next);
+      return next;
+    });
+  },
+}));
+
+/** Read a window's slice outside React (action modules, keyboard handlers). */
+export function sliceOf(id: string): ExplorerSlice | undefined {
+  return useExplorerStore.getState().slices[id];
+}
+
+// ── Cross-window refresh ───────────────────────────────────────────
+
+type DirListener = (dir: string) => void;
+const dirListeners = new Set<DirListener>();
+
+/**
+ * Announce that `dir`'s contents changed on disk. Every window showing that
+ * directory — including the one that caused the change — refetches.
+ */
+export function fsChanged(...dirs: (string | null | undefined)[]): void {
+  for (const dir of dirs) {
+    if (!dir) continue;
+    for (const listener of dirListeners) listener(dir);
+  }
+}
+
+export function onFsChanged(listener: DirListener): () => void {
+  dirListeners.add(listener);
+  return () => dirListeners.delete(listener);
+}

package/src/web/components/os-explorer/explorer-toolbar.tsx

@@ -0,0 +1,139 @@
+/**
+ * Window toolbar: history navigation, the breadcrumb (switchable to a raw path field),
+ * a name filter, the view switch and the hidden-files toggle.
+ *
+ * The path field is a deliberate toggle rather than a click-to-edit breadcrumb: pasting a
+ * path is the fastest way to reach a deep folder, and a breadcrumb that turns into a field
+ * on click makes the crumbs themselves hard to hit.
+ */
+
+import { useEffect, useState } from "react";
+import {
+  ArrowLeft, ArrowRight, ArrowUp, Columns3, Eye, EyeOff, LayoutGrid, List, PencilLine, RefreshCw, Search, X,
+} from "lucide-react";
+import { cn } from "@/lib/utils";
+import { ExplorerBreadcrumb } from "./explorer-breadcrumb";
+import { ExplorerSortMenu } from "./explorer-sort-menu";
+import { useExplorerStore, type ExplorerSlice, type ViewMode } from "./explorer-store";
+import { toolbarButtonClass as buttonClass } from "./toolbar-icon-button";
+import { usePrefersCoarsePointer } from "./use-coarse-long-press";
+import type { ExplorerNavigation } from "./use-explorer-navigation";
+import { AVAILABLE_VIEW_MODES } from "./views/explorer-view-registry";
+
+const VIEW_ICON: Record<ViewMode, typeof List> = { list: List, icons: LayoutGrid, columns: Columns3 };
+const VIEW_LABEL: Record<ViewMode, string> = { list: "List view", icons: "Icons view", columns: "Column view" };
+
+export interface ExplorerToolbarProps {
+  windowId: string;
+  slice: ExplorerSlice;
+  nav: ExplorerNavigation;
+}
+
+export function ExplorerToolbar({ windowId, slice, nav }: ExplorerToolbarProps) {
+  const patch = useExplorerStore((s) => s.patch);
+  const showHidden = useExplorerStore((s) => s.showHidden);
+  const viewMode = useExplorerStore((s) => s.viewMode);
+  const setPrefs = useExplorerStore((s) => s.setPrefs);
+
+  const [editingPath, setEditingPath] = useState(false);
+  const [draftPath, setDraftPath] = useState(slice.path);
+  useEffect(() => setDraftPath(slice.path), [slice.path]);
+  const coarse = usePrefersCoarsePointer();
+
+  return (
+    <div className="flex shrink-0 flex-wrap items-center gap-1 border-b border-border bg-[var(--x-toolbar-bg,var(--panel-2))] px-1.5 py-1">
+      <button type="button" aria-label="Back" title="Back" disabled={!nav.canGoBack} onClick={nav.back} className={buttonClass(coarse)}>
+        <ArrowLeft className="size-4" />
+      </button>
+      <button type="button" aria-label="Forward" title="Forward" disabled={!nav.canGoForward} onClick={nav.forward} className={buttonClass(coarse)}>
+        <ArrowRight className="size-4" />
+      </button>
+      <button type="button" aria-label="Up one level" title="Up" disabled={!slice.parent} onClick={nav.up} className={buttonClass(coarse)}>
+        <ArrowUp className="size-4" />
+      </button>
+      <button type="button" aria-label="Refresh" title="Refresh" onClick={nav.refresh} className={buttonClass(coarse)}>
+        <RefreshCw className={cn("size-4", slice.loading && "animate-spin")} />
+      </button>
+
+      <div className="flex min-w-[8rem] flex-1 items-center gap-1 rounded border border-border bg-panel px-1">
+        {editingPath ? (
+          <input
+            autoFocus
+            aria-label="Path"
+            value={draftPath}
+            onChange={(e) => setDraftPath(e.target.value)}
+            onBlur={() => setEditingPath(false)}
+            onKeyDown={(e) => {
+              e.stopPropagation();
+              if (e.key === "Enter") { nav.go(draftPath.trim()); setEditingPath(false); }
+              else if (e.key === "Escape") { setDraftPath(slice.path); setEditingPath(false); }
+            }}
+            className="min-w-0 flex-1 bg-transparent py-1 font-mono text-xs text-text outline-none"
+          />
+        ) : (
+          <ExplorerBreadcrumb crumbs={slice.breadcrumbs} onNavigate={nav.go} sep={slice.sep} className="flex-1 overflow-hidden py-0.5" />
+        )}
+        <button
+          type="button"
+          aria-label={editingPath ? "Show breadcrumb" : "Edit path"}
+          title={editingPath ? "Show breadcrumb" : "Edit path"}
+          onClick={() => setEditingPath((v) => !v)}
+          className={buttonClass(coarse)}
+        >
+          <PencilLine className="size-3.5" />
+        </button>
+      </div>
+
+      <div className="flex items-center gap-1 rounded border border-border bg-panel px-1">
+        <Search className="size-3.5 shrink-0 text-text-subtle" />
+        <input
+          aria-label="Filter entries"
+          placeholder="Filter"
+          value={slice.filter}
+          onChange={(e) => patch(windowId, { filter: e.target.value })}
+          onKeyDown={(e) => {
+            e.stopPropagation();
+            if (e.key === "Escape") patch(windowId, { filter: "" });
+          }}
+          className="w-24 min-w-0 bg-transparent py-1 text-xs text-text outline-none placeholder:text-text-subtle"
+        />
+        {slice.filter && (
+          <button type="button" aria-label="Clear filter" onClick={() => patch(windowId, { filter: "" })} className={buttonClass(coarse)}>
+            <X className="size-3.5" />
+          </button>
+        )}
+      </div>
+
+      {AVAILABLE_VIEW_MODES.length > 1 &&
+        AVAILABLE_VIEW_MODES.map((mode) => {
+          const Icon = VIEW_ICON[mode];
+          return (
+            <button
+              key={mode}
+              type="button"
+              aria-label={VIEW_LABEL[mode]}
+              title={VIEW_LABEL[mode]}
+              aria-pressed={viewMode === mode}
+              onClick={() => setPrefs({ viewMode: mode })}
+              className={cn(buttonClass(coarse), viewMode === mode && "bg-accent-wash text-primary")}
+            >
+              <Icon className="size-4" />
+            </button>
+          );
+        })}
+
+      <ExplorerSortMenu coarse={coarse} />
+
+      <button
+        type="button"
+        aria-label={showHidden ? "Hide hidden files" : "Show hidden files"}
+        title={showHidden ? "Hide hidden files" : "Show hidden files"}
+        aria-pressed={showHidden}
+        onClick={() => setPrefs({ showHidden: !showHidden })}
+        className={cn(buttonClass(coarse), showHidden && "bg-accent-wash text-primary")}
+      >
+        {showHidden ? <Eye className="size-4" /> : <EyeOff className="size-4" />}
+      </button>
+    </div>
+  );
+}

package/src/web/components/os-explorer/explorer-window-content.tsx

@@ -0,0 +1,36 @@
+/**
+ * `WINDOW_CONTENT["explorer"]` — the adapter between the generic floating-window frame and
+ * the explorer body.
+ *
+ * It owns only two things the body should not care about: turning the window payload into
+ * a starting path, and dropping the window's slice when the window closes.
+ */
+
+import { useEffect } from "react";
+import type { WindowContentProps } from "@/components/floating-window/window-content-registry";
+import { ExplorerBody } from "./explorer-body";
+import { useExplorerStore } from "./explorer-store";
+import { cachedHomedir, useHostInfo } from "./use-host-info";
+
+export default function ExplorerWindowContent({ id, payload }: WindowContentProps) {
+  const { host, error } = useHostInfo();
+  const discard = useExplorerStore((s) => s.discard);
+
+  // A window's state is per-window; leaving it behind would leak one slice per open.
+  useEffect(() => () => discard(id), [id, discard]);
+
+  const requested = typeof payload?.path === "string" ? payload.path : "";
+  // Without a path (or before host info lands) there is nothing safe to browse: "/" does
+  // not exist on Windows, so wait for the home directory rather than showing a bogus error.
+  const initialPath = requested || cachedHomedir() || host?.homedir || "";
+
+  if (!initialPath) {
+    return (
+      <div className="flex h-full items-center justify-center p-4 text-xs text-text-2">
+        {error ? `Could not reach the host: ${error}` : "Loading…"}
+      </div>
+    );
+  }
+
+  return <ExplorerBody windowId={id} initialPath={initialPath} />;
+}

package/src/web/components/os-explorer/format-file-meta.ts

@@ -0,0 +1,74 @@
+/** Presentation helpers for file metadata, shared by the explorer views, the
+ *  properties dialog and the directory picker. */
+
+import { FsError } from "@/lib/fs-api";
+
+/**
+ * Description for a failure toast: the server's remediation hint (`EPROTECTED`/`EDENIED`)
+ * beats the raw message, matching the inline banner shown for a failed directory listing.
+ */
+export function errorDescription(e: unknown): string | undefined {
+  if (e instanceof FsError) return e.hint ?? e.message;
+  return e instanceof Error ? e.message : undefined;
+}
+
+/** Human-readable byte count. Undefined size renders as an empty cell. */
+export function formatSize(bytes?: number): string {
+  if (bytes == null) return "";
+  if (bytes < 1024) return `${bytes} B`;
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
+  if (bytes < 1024 * 1024 * 1024) return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+  return `${(bytes / (1024 * 1024 * 1024)).toFixed(2)} GB`;
+}
+
+/** Coarse "how long ago" label; good enough for a list column. */
+export function formatRelativeTime(iso: string): string {
+  const diff = Date.now() - new Date(iso).getTime();
+  const mins = Math.floor(diff / 60000);
+  if (mins < 1) return "now";
+  if (mins < 60) return `${mins}m ago`;
+  const hrs = Math.floor(mins / 60);
+  if (hrs < 24) return `${hrs}h ago`;
+  const days = Math.floor(hrs / 24);
+  return `${days}d ago`;
+}
+
+/** Absolute local timestamp for the properties dialog. Invalid dates render blank. */
+export function formatDateTime(iso?: string): string {
+  if (!iso) return "";
+  const date = new Date(iso);
+  if (Number.isNaN(date.getTime())) return "";
+  return date.toLocaleString();
+}
+
+/**
+ * POSIX permission bits as the familiar three-digit octal. Windows does not encode
+ * write permission in the mode, so callers show the read-only flag there instead.
+ */
+export function formatMode(mode?: number): string {
+  if (mode == null) return "";
+  return (mode & 0o777).toString(8).padStart(3, "0");
+}
+
+/** Directory name of an absolute path, using the host separator. Root maps to itself. */
+export function dirnameOf(path: string, sep: string): string {
+  const trimmed = path.endsWith(sep) && path.length > sep.length ? path.slice(0, -sep.length) : path;
+  const idx = trimmed.lastIndexOf(sep);
+  if (idx < 0) return trimmed;
+  if (idx === 0) return sep; // POSIX root
+  const head = trimmed.slice(0, idx);
+  // "C:" alone is not browsable — a Windows drive root needs its trailing separator.
+  return head.endsWith(":") ? head + sep : head;
+}
+
+/** Join a directory and a child name with the host separator. */
+export function joinPath(dir: string, name: string, sep: string): string {
+  return dir.endsWith(sep) ? `${dir}${name}` : `${dir}${sep}${name}`;
+}
+
+/** Insert a " (2)" style suffix before the extension, for "Keep both" pastes. */
+export function suffixName(name: string, n: number): string {
+  const dot = name.lastIndexOf(".");
+  if (dot <= 0) return `${name} (${n})`;
+  return `${name.slice(0, dot)} (${n})${name.slice(dot)}`;
+}

package/src/web/components/os-explorer/icons/file-type-icon-map.ts

@@ -0,0 +1,106 @@
+/**
+ * Extension → icon component, using the Symbols set (the VS Code icon theme by Miguel
+ * Solorio) so an explorer window reads like a real file manager.
+ *
+ * Imports come from the `/files` and `/folders` subpaths only. The root barrel pulls the
+ * whole library (900+ icons) into the graph, and `/utils` drags in a lookup table that
+ * defeats tree-shaking; naming each icon explicitly keeps the built chunk to the ~45
+ * glyphs actually referenced here.
+ *
+ * The map is deliberately curated rather than exhaustive: rare extensions fall back to a
+ * neutral glyph, which costs nothing and keeps the chunk inside its size budget.
+ */
+
+import type { FC, ComponentProps } from "react";
+import {
+  Astro, Audio, BracketsYellow, CLang, CodeBlue, CodeOrange, Cplus, Csharp, Csv, Dart,
+  Database, Docker, Document, Exe, Font, Gear, Gif, Git, Go, Image, Java, Js, Kotlin,
+  License, Lock, Lua, Markdown, Notebook, PDF, PHP, Python, Reactjs, Reactts, Ruby,
+  Rust, Sass, Shell, SVG, Svelte, Swift, Text, TypeScript, Video, Vue, XML, Yaml, Zip,
+} from "@react-symbols/icons/files";
+import { Folder, FolderOpen } from "@react-symbols/icons/folders";
+
+export type SymbolIcon = FC<ComponentProps<"svg">>;
+
+export const FOLDER_ICON: SymbolIcon = Folder;
+export const FOLDER_OPEN_ICON: SymbolIcon = FolderOpen;
+
+/** One entry per icon; the key list is the set of extensions that share that glyph. */
+const GROUPS: [SymbolIcon, string[]][] = [
+  [TypeScript, ["ts", "mts", "cts"]],
+  [Reactts, ["tsx"]],
+  [Js, ["js", "mjs", "cjs"]],
+  [Reactjs, ["jsx"]],
+  [Vue, ["vue"]],
+  [Svelte, ["svelte"]],
+  [Astro, ["astro"]],
+  [BracketsYellow, ["json", "jsonc", "json5"]],
+  [Markdown, ["md", "mdx"]],
+  [CodeOrange, ["html", "htm"]],
+  [CodeBlue, ["css"]],
+  [Sass, ["scss", "sass", "less"]],
+  [Yaml, ["yaml", "yml"]],
+  [XML, ["xml", "plist"]],
+  [Gear, ["toml", "ini", "cfg", "conf", "env", "properties"]],
+  [Python, ["py", "pyi"]],
+  [Ruby, ["rb"]],
+  [Go, ["go"]],
+  [Rust, ["rs"]],
+  [Java, ["java", "jar"]],
+  [Kotlin, ["kt", "kts"]],
+  [Swift, ["swift"]],
+  [CLang, ["c", "h"]],
+  [Cplus, ["cpp", "cc", "cxx", "hpp"]],
+  [Csharp, ["cs"]],
+  [PHP, ["php"]],
+  [Lua, ["lua"]],
+  [Dart, ["dart"]],
+  [Shell, ["sh", "bash", "zsh", "fish", "ps1", "psm1", "bat", "cmd"]],
+  [Database, ["sql", "db", "sqlite", "sqlite3"]],
+  [Csv, ["csv", "tsv"]],
+  [PDF, ["pdf"]],
+  [Document, ["doc", "docx", "rtf", "odt", "pages"]],
+  [Notebook, ["ipynb"]],
+  [Text, ["txt", "log", "text"]],
+  [Image, ["png", "jpg", "jpeg", "webp", "bmp", "ico", "tif", "tiff", "avif"]],
+  [Gif, ["gif"]],
+  [SVG, ["svg"]],
+  [Video, ["mp4", "webm", "mov", "avi", "mkv", "m4v"]],
+  [Audio, ["mp3", "wav", "flac", "aac", "m4a", "ogg", "wma"]],
+  [Zip, ["zip", "rar", "7z", "tar", "gz", "tgz", "bz2", "xz"]],
+  [Exe, ["exe", "msi", "dmg", "appimage", "deb", "rpm"]],
+  [Font, ["ttf", "otf", "woff", "woff2", "eot"]],
+  [Lock, ["lock"]],
+];
+
+const BY_EXTENSION = new Map<string, SymbolIcon>();
+for (const [icon, extensions] of GROUPS) {
+  for (const ext of extensions) BY_EXTENSION.set(ext, icon);
+}
+
+/** Whole-name matches, for files whose type lives in the name rather than an extension. */
+const BY_FILENAME = new Map<string, SymbolIcon>([
+  [".gitignore", Git],
+  [".gitattributes", Git],
+  [".gitmodules", Git],
+  ["dockerfile", Docker],
+  [".dockerignore", Docker],
+  ["license", License],
+  ["licence", License],
+  ["makefile", Gear],
+  [".editorconfig", Gear],
+  [".npmrc", Gear],
+  [".env", Gear],
+]);
+
+/** Icon for a file name, or `null` when nothing in the curated set matches. */
+export function fileIconFor(name: string): SymbolIcon | null {
+  const base = (name.split(/[/\\]/).pop() ?? name).toLowerCase();
+  const byName = BY_FILENAME.get(base);
+  if (byName) return byName;
+  // Compound extensions ("archive.tar.gz") resolve on the last segment, which is right
+  // for every entry above.
+  const dot = base.lastIndexOf(".");
+  if (dot <= 0) return null;
+  return BY_EXTENSION.get(base.slice(dot + 1)) ?? null;
+}

package/src/web/components/os-explorer/icons/file-type-icon.tsx

@@ -0,0 +1,56 @@
+/**
+ * The icon shown next to an entry in every explorer view.
+ *
+ * Skins need to swap the folder glyph (a Windows 11 folder looks nothing like a Finder
+ * one) without touching the per-extension table, so the folder icon is read from a
+ * React context with the Symbols folder as the default. File icons stay shared: VS
+ * Code-style file glyphs are the same on all platforms.
+ */
+
+import { createContext, useContext, type ComponentProps, type FC } from "react";
+import { File as GenericFile, FolderSymlink, HelpCircle } from "lucide-react";
+import { cn } from "@/lib/utils";
+import { fileIconFor, FOLDER_ICON, FOLDER_OPEN_ICON, type SymbolIcon } from "./file-type-icon-map";
+
+export interface FolderIconSlot {
+  closed: SymbolIcon;
+  open: SymbolIcon;
+}
+
+const FolderIconContext = createContext<FolderIconSlot>({
+  closed: FOLDER_ICON,
+  open: FOLDER_OPEN_ICON,
+});
+
+/** Skin hook: wrap a subtree to replace the folder glyphs it renders. */
+export const FolderIconProvider = FolderIconContext.Provider;
+
+export interface FileTypeIconProps extends ComponentProps<"svg"> {
+  name: string;
+  kind: "file" | "directory" | "symlink" | "unknown";
+  /** Directories only — draws the open variant (column view, expanded rows). */
+  open?: boolean;
+}
+
+export function FileTypeIcon({ name, kind, open, className, ...rest }: FileTypeIconProps) {
+  const folder = useContext(FolderIconContext);
+  const classes = cn("shrink-0", className);
+
+  if (kind === "directory") {
+    const Icon = open ? folder.open : folder.closed;
+    return <Icon className={classes} {...rest} />;
+  }
+  if (kind === "symlink") {
+    // A link's target may be a file or a directory and is never followed, so it gets its
+    // own glyph rather than borrowing one of the two.
+    return <FolderSymlink className={cn(classes, "text-text-2")} {...rest} />;
+  }
+  if (kind === "unknown") {
+    // The server timed out reading this entry; showing a file icon would be a lie.
+    return <HelpCircle className={cn(classes, "text-text-subtle")} {...rest} />;
+  }
+
+  const Icon: FC<ComponentProps<"svg">> | null = fileIconFor(name);
+  if (!Icon) return <GenericFile className={cn(classes, "text-text-2")} {...rest} />;
+  return <Icon className={classes} {...rest} />;
+}

package/src/web/components/os-explorer/icons/thumbnail-fetch-semaphore.ts

@@ -0,0 +1,44 @@
+/**
+ * Bounded concurrency gate for thumbnail fetches, shared by every `ThumbnailImage` instance
+ * on screen — a folder of a thousand photos must still cap at `MAX_CONCURRENT` in-flight
+ * `/api/fs/raw` requests rather than firing one per tile.
+ *
+ * `acquireSlot()` resolves once a slot is free; the returned release function is idempotent
+ * (safe to call more than once for the same acquisition) — a caller may release both from a
+ * `finally` block and from an effect cleanup that fires for the same completed fetch, and a
+ * second release must be a no-op rather than decrementing `active` twice.
+ */
+
+export const MAX_CONCURRENT = 24;
+
+let active = 0;
+const queue: (() => void)[] = [];
+
+export function acquireSlot(): Promise<() => void> {
+  return new Promise((resolve) => {
+    let released = false;
+    const run = () => {
+      active++;
+      resolve(() => {
+        if (released) return;
+        released = true;
+        active--;
+        const next = queue.shift();
+        if (next) next();
+      });
+    };
+    if (active < MAX_CONCURRENT) run();
+    else queue.push(run);
+  });
+}
+
+/** Current in-flight count — exposed for tests only. */
+export function activeCount(): number {
+  return active;
+}
+
+/** Resets module state between tests. */
+export function _resetSemaphore(): void {
+  active = 0;
+  queue.length = 0;
+}