@hienlh/ppm 0.17.57 → 0.18.0

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;
+}

package/src/web/components/os-explorer/icons/thumbnail-image.tsx

@@ -0,0 +1,124 @@
+/**
+ * Lazy, viewport-gated thumbnail for image files.
+ *
+ * A bare `<img src="/api/fs/raw?...">` cannot carry the Authorization header the API
+ * requires, so the bytes are fetched manually and turned into an object URL — the same
+ * trick `useBlobUrl` uses — but gated by an `IntersectionObserver` (nothing fetches until
+ * the tile scrolls near the viewport) and a module-wide concurrency cap, so opening a
+ * folder of a thousand photos does not fire a thousand requests at once.
+ */
+
+import { useEffect, useRef, useState } from "react";
+import { getAuthToken } from "@/lib/api-client";
+import type { FsEntry } from "@/lib/fs-api";
+import { cn } from "@/lib/utils";
+import { FileTypeIcon } from "./file-type-icon";
+import { acquireSlot } from "./thumbnail-fetch-semaphore";
+
+export interface ThumbnailImageProps {
+  entry: Pick<FsEntry, "name" | "path" | "kind">;
+  /** Square box the thumbnail (or its icon fallback) renders into, in px. */
+  size: number;
+  className?: string;
+}
+
+export function ThumbnailImage({ entry, size, className }: ThumbnailImageProps) {
+  const [src, setSrc] = useState<string | null>(null);
+  const [failed, setFailed] = useState(false);
+  const rootRef = useRef<HTMLDivElement>(null);
+  const urlRef = useRef<string | null>(null);
+
+  // A different entry (row recycled by the virtualizer, or the user navigated) starts over.
+  useEffect(() => {
+    setSrc(null);
+    setFailed(false);
+  }, [entry.path]);
+
+  useEffect(() => {
+    const el = rootRef.current;
+    if (!el || src || failed) return;
+    // A scrolled-past tile must stop downloading (the server has no thumbnail endpoint —
+    // `/api/fs/raw` streams the whole original file) and give its semaphore slot back
+    // immediately rather than waiting for a fetch nobody will render.
+    const controller = new AbortController();
+    let release: (() => void) | null = null;
+
+    const observer = new IntersectionObserver(
+      (observed) => {
+        if (!observed[0]?.isIntersecting) return;
+        observer.disconnect();
+        void (async () => {
+          release = await acquireSlot();
+          if (controller.signal.aborted) {
+            release();
+            return;
+          }
+          try {
+            const token = getAuthToken();
+            const res = await fetch(`/api/fs/raw?path=${encodeURIComponent(entry.path)}`, {
+              headers: token ? { Authorization: `Bearer ${token}` } : {},
+              signal: controller.signal,
+            });
+            if (!res.ok) throw new Error(String(res.status));
+            const blob = await res.blob();
+            if (controller.signal.aborted) return;
+            const url = URL.createObjectURL(blob);
+            urlRef.current = url;
+            setSrc(url);
+          } catch {
+            if (!controller.signal.aborted) setFailed(true);
+          } finally {
+            // Idempotent: harmless if this fires again from the cleanup below for the same
+            // completed acquisition.
+            release?.();
+          }
+        })();
+      },
+      // Start the fetch a little before the tile is actually visible so it is usually
+      // ready by the time it scrolls fully into view.
+      { rootMargin: "200px" },
+    );
+    observer.observe(el);
+    return () => {
+      controller.abort();
+      observer.disconnect();
+      release?.();
+    };
+  }, [entry.path, src, failed]);
+
+  useEffect(
+    () => () => {
+      if (urlRef.current) URL.revokeObjectURL(urlRef.current);
+    },
+    [],
+  );
+
+  if (failed || !src) {
+    return (
+      <div
+        ref={rootRef}
+        className={cn("flex items-center justify-center", className)}
+        style={{ width: size, height: size }}
+      >
+        <FileTypeIcon name={entry.name} kind={entry.kind} className="size-1/2" />
+      </div>
+    );
+  }
+
+  return (
+    <div
+      ref={rootRef}
+      className={cn("flex items-center justify-center overflow-hidden", className)}
+      style={{ width: size, height: size }}
+    >
+      {/* eslint-disable-next-line @next/next/no-img-element -- plain img, not next/image */}
+      <img
+        src={src}
+        alt=""
+        loading="lazy"
+        className="max-h-full max-w-full rounded object-contain"
+        onError={() => setFailed(true)}
+      />
+    </div>
+  );
+}

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

@@ -0,0 +1,102 @@
+/**
+ * Bottom toolbar: every frequent action lives here, in the thumb zone. Two rows share the
+ * one bar — the normal row (navigate / create / paste / enter Select) and, once "Select" is
+ * tapped, a row of bulk actions over the current selection. "Delete permanently" is
+ * deliberately not here (it lives in the More sheet) — Trash is the default and the one-tap
+ * row should not make the irreversible action as easy to reach as the reversible one.
+ */
+
+import { useState } from "react";
+import {
+  ArrowLeft, Check, ClipboardPaste, Copy, Download, FilePlus, FolderPlus, Info, MoreHorizontal, Plus, Scissors, Trash2, X,
+} from "lucide-react";
+import type { FsEntry } from "@/lib/fs-api";
+import { BottomSheet, BottomSheetItem } from "@/components/ui/mobile-bottom-sheet";
+import type { ExplorerActions } from "../actions/use-explorer-actions";
+import type { ExplorerSlice } from "../explorer-store";
+import type { ExplorerNavigation } from "../use-explorer-navigation";
+import { useMobileExplorerOpenState } from "../use-explorer-open-state";
+import { MobileMoreSheet } from "./mobile-more-sheet";
+
+function ToolbarButton({
+  icon: Icon, label, onClick, disabled, destructive,
+}: {
+  icon: typeof Plus; label: string; onClick(): void; disabled?: boolean; destructive?: boolean;
+}) {
+  return (
+    <button
+      type="button"
+      aria-label={label}
+      title={label}
+      disabled={disabled}
+      onClick={onClick}
+      className={`flex min-w-[44px] flex-1 flex-col items-center gap-0.5 rounded-lg py-1.5 text-[10px] active:bg-surface-elevated disabled:opacity-30 ${destructive ? "text-error" : "text-text-2"}`}
+    >
+      <Icon className="size-5" />
+      <span className="truncate">{label}</span>
+    </button>
+  );
+}
+
+export interface MobileBottomToolbarProps {
+  slice: ExplorerSlice;
+  nav: ExplorerNavigation;
+  actions: ExplorerActions;
+  entries: FsEntry[];
+  hasClipboard: boolean;
+}
+
+export function MobileBottomToolbar({ slice, nav, actions, entries, hasClipboard }: MobileBottomToolbarProps) {
+  const selectMode = useMobileExplorerOpenState((s) => s.selectMode);
+  const setSelectMode = useMobileExplorerOpenState((s) => s.setSelectMode);
+  const [newOpen, setNewOpen] = useState(false);
+  const [moreOpen, setMoreOpen] = useState(false);
+
+  const selected = entries.filter((e) => slice.selection.has(e.path));
+
+  if (selectMode) {
+    const exitSelect = () => { setSelectMode(false); };
+    return (
+      <div className="flex shrink-0 items-center gap-1 border-t border-border px-1 py-1">
+        <ToolbarButton icon={X} label="Cancel" onClick={exitSelect} />
+        <span className="px-1 text-xs text-text-subtle">{selected.length} selected</span>
+        <div className="flex-1" />
+        <ToolbarButton icon={Scissors} label="Cut" disabled={selected.length === 0} onClick={() => actions.cut(selected)} />
+        <ToolbarButton icon={Copy} label="Copy" disabled={selected.length === 0} onClick={() => actions.copy(selected)} />
+        <ToolbarButton icon={Trash2} label="Trash" disabled={selected.length === 0} destructive onClick={() => actions.trash(selected)} />
+        <ToolbarButton
+          icon={Download}
+          label="Download"
+          disabled={!selected.some((e) => e.type === "file")}
+          onClick={() => actions.download(selected)}
+        />
+        {selected.length === 1 && (
+          <ToolbarButton icon={Info} label="Info" onClick={() => actions.showProperties(selected[0]!)} />
+        )}
+      </div>
+    );
+  }
+
+  return (
+    <>
+      <div className="flex shrink-0 items-center gap-1 border-t border-border px-1 py-1">
+        <ToolbarButton icon={ArrowLeft} label="Back" disabled={!nav.canGoBack} onClick={nav.back} />
+        <ToolbarButton icon={Plus} label="New" onClick={() => setNewOpen(true)} />
+        <ToolbarButton icon={ClipboardPaste} label="Paste" disabled={!hasClipboard} onClick={() => actions.paste()} />
+        <ToolbarButton icon={Check} label="Select" onClick={() => setSelectMode(true)} />
+        <ToolbarButton icon={MoreHorizontal} label="More" onClick={() => setMoreOpen(true)} />
+      </div>
+
+      <BottomSheet open={newOpen} onClose={() => setNewOpen(false)} className="p-2">
+        <BottomSheetItem onClick={() => actions.startCreate("new-file")}>
+          <FilePlus className="size-4" /> New File
+        </BottomSheetItem>
+        <BottomSheetItem onClick={() => actions.startCreate("new-folder")}>
+          <FolderPlus className="size-4" /> New Folder
+        </BottomSheetItem>
+      </BottomSheet>
+
+      <MobileMoreSheet open={moreOpen} onClose={() => setMoreOpen(false)} slice={slice} actions={actions} entries={entries} />
+    </>
+  );
+}

package/src/web/components/os-explorer/mobile/mobile-explorer-sheet.tsx

@@ -0,0 +1,61 @@
+/**
+ * Full-screen mobile presentation of the explorer: a `BottomSheet` sized to the whole
+ * visible viewport, hosting the exact same `ExplorerBody` every desktop window uses
+ * (`variant="sheet"`), so file-type icons, the active OS skin's vocabulary and every mutation
+ * action are shared code, not a parallel mobile implementation.
+ *
+ * Self-gated singleton, mounted once at the app root next to the other overlay singletons
+ * (`ComparePicker`, `ImageOverlay`, …) — renders nothing until `openMobileExplorer` is called.
+ */
+
+import { useEffect, type TouchEvent } from "react";
+import { BottomSheet } from "@/components/ui/mobile-bottom-sheet";
+import { ExplorerBody } from "../explorer-body";
+import { useExplorerStore } from "../explorer-store";
+import { MOBILE_EXPLORER_WINDOW_ID, useMobileExplorerOpenState } from "../use-explorer-open-state";
+
+export function MobileExplorerSheet() {
+  const isOpen = useMobileExplorerOpenState((s) => s.isOpen);
+  const close = useMobileExplorerOpenState((s) => s.close);
+  const setSelectMode = useMobileExplorerOpenState((s) => s.setSelectMode);
+  const path = useExplorerStore((s) => s.slices[MOBILE_EXPLORER_WINDOW_ID]?.path);
+  const renaming = useExplorerStore(
+    (s) => s.slices[MOBILE_EXPLORER_WINDOW_ID]?.inlineEdit?.kind === "rename",
+  );
+
+  // Navigating (forward, back, or via a place/breadcrumb) already clears the shared
+  // selection — Select mode's own checkbox/bottom-bar state must follow it, or the toolbar
+  // is left on Cut/Copy/Trash with 0 items and no way back short of the explicit Cancel.
+  useEffect(() => {
+    setSelectMode(false);
+  }, [path, setSelectMode]);
+
+  // Swallowed only while an inline rename is active: a drag meant to clear the soft keyboard
+  // (or just reach a field below it) would otherwise also read as a swipe-to-dismiss, since
+  // `BottomSheet` wires its drag handlers on the panel — an ancestor of everything here.
+  const suppressSwipe = (e: TouchEvent) => {
+    if (renaming) e.stopPropagation();
+  };
+
+  if (!isOpen) return null;
+
+  return (
+    // Below the default sheet z-index (50): the explorer opens further sheets on top of
+    // itself (row actions, "New", "More", "Places") that all rely on that default, and a
+    // higher value here would silently sit above every one of them instead. 45 still clears
+    // the mobile bottom nav (z-40) so the sheet reads as full-screen underneath it.
+    <BottomSheet open={isOpen} onClose={close} zIndex={45} className="flex h-[var(--sheet-vh)] flex-col p-0">
+      <div
+        className="flex min-h-0 flex-1 flex-col"
+        onTouchStart={suppressSwipe}
+        onTouchMove={suppressSwipe}
+      >
+        {path ? (
+          <ExplorerBody windowId={MOBILE_EXPLORER_WINDOW_ID} initialPath={path} variant="sheet" />
+        ) : (
+          <div className="flex flex-1 items-center justify-center text-sm text-text-2">Loading…</div>
+        )}
+      </div>
+    </BottomSheet>
+  );
+}

package/src/web/components/os-explorer/mobile/mobile-explorer-top-bar.tsx

@@ -0,0 +1,41 @@
+/**
+ * Mobile sheet header: current folder name, nothing else. Every frequent action lives in
+ * the bottom toolbar (the thumb zone) — putting anything interactive up here would be the
+ * one part of a one-handed grip that is hardest to reach.
+ *
+ * The close button is the one addition beyond "title only": a sheet that fills the whole
+ * screen leaves no backdrop to tap, so swipe-to-dismiss would otherwise be the only way out.
+ */
+
+import { X } from "lucide-react";
+import type { ExplorerSlice } from "../explorer-store";
+
+export interface MobileExplorerTopBarProps {
+  slice: ExplorerSlice;
+  onClose(): void;
+}
+
+/** The folder name to show for the current path — the last breadcrumb is the folder itself. */
+function currentFolderName(slice: ExplorerSlice): string {
+  const last = slice.breadcrumbs[slice.breadcrumbs.length - 1];
+  return last?.name ?? slice.path;
+}
+
+export function MobileExplorerTopBar({ slice, onClose }: MobileExplorerTopBarProps) {
+  return (
+    <div className="flex shrink-0 items-center gap-2 border-b border-border px-3 py-2.5">
+      <span className="min-w-0 flex-1 truncate text-[15px] font-semibold text-text">
+        {currentFolderName(slice)}
+      </span>
+      <button
+        type="button"
+        aria-label="Close file explorer"
+        title="Close"
+        onClick={onClose}
+        className="flex size-11 shrink-0 items-center justify-center rounded-full text-text-2 active:bg-surface-elevated"
+      >
+        <X className="size-5" />
+      </button>
+    </div>
+  );
+}