@hienlh/ppm 0.17.57 → 0.18.1

package/src/web/components/os-explorer/mobile/mobile-tap-action.ts

@@ -0,0 +1,19 @@
+/**
+ * What a single tap does on the mobile sheet: there is no double-click on touch, so a
+ * directory or a PPM-viewable file must open on the first tap. A file with nothing to open
+ * it in has no useful "open" action, so a tap on it surfaces the same actions sheet a
+ * long-press would — never a silent no-op.
+ *
+ * Pure so the three-way decision (directory / viewable file / opaque file) is unit-testable
+ * without mounting a row.
+ */
+
+import { canOpenInPpm } from "../can-open-in-ppm";
+
+export type MobileTapAction = "open" | "sheet";
+
+/** `entry` only needs the two fields the decision actually reads. */
+export function mobileTapAction(entry: { type: "file" | "directory"; name: string }): MobileTapAction {
+  if (entry.type === "directory") return "open";
+  return canOpenInPpm(entry.name) ? "open" : "sheet";
+}

package/src/web/components/os-explorer/mobile/use-mobile-row-tap.ts

@@ -0,0 +1,50 @@
+/**
+ * Shared tap/select-mode decision for every row-level component (List, Icons — Column view
+ * keeps its own simpler single-select tap, see `column-view-column.tsx`), so List and Icons
+ * branch touch behavior identically instead of two near-copies of the same decision.
+ *
+ * Must be called from the component actually rendered *inside* the row's own
+ * `<ContextMenu>` (i.e. the JSX returned inside `<ContextMenuTrigger>`, not the component
+ * that renders `<ContextMenu>` itself) — that is the only position where
+ * `useContext(BottomSheetCtx)` resolves to that row's own sheet state instead of the
+ * default no-op value.
+ */
+
+import { useContext } from "react";
+import { BottomSheetCtx } from "@/components/ui/mobile-bottom-sheet";
+import { useIsMobile } from "@/hooks/use-is-mobile";
+import type { FsEntry } from "@/lib/fs-api";
+import type { ExplorerActions } from "../actions/use-explorer-actions";
+import type { EntrySelection } from "../views/use-entry-selection";
+import { useMobileExplorerOpenState } from "../use-explorer-open-state";
+import { mobileTapAction } from "./mobile-tap-action";
+
+export interface MobileRowTap {
+  /** True only inside the mobile sheet — desktop rows keep their existing click behavior. */
+  isMobile: boolean;
+  selectMode: boolean;
+  /** Call from the row's onClick; returns true once it has handled the tap (mobile branch). */
+  handleTap(entry: FsEntry, selected: boolean): boolean;
+}
+
+export function useMobileRowTap(actions: ExplorerActions, selection: EntrySelection): MobileRowTap {
+  const isMobile = useIsMobile();
+  const selectMode = useMobileExplorerOpenState((s) => s.selectMode);
+  const { setOpen } = useContext(BottomSheetCtx);
+
+  const handleTap = (entry: FsEntry, selected: boolean): boolean => {
+    if (!isMobile) return false;
+    if (selectMode) {
+      // Toggle membership like a ctrl-click — a plain tap in Select mode never replaces
+      // the whole selection with just this one row.
+      selection.onRowClick(entry.path, { shiftKey: false, ctrlKey: true, metaKey: false });
+      return true;
+    }
+    if (!selected) selection.selectOnly(entry.path);
+    if (mobileTapAction(entry) === "open") actions.openEntry(entry);
+    else setOpen(true); // No viewer for this file — surface the same sheet long-press would.
+    return true;
+  };
+
+  return { isMobile, selectMode, handleTap };
+}

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

@@ -0,0 +1,35 @@
+/**
+ * The one way anything outside this folder opens a file-explorer window.
+ *
+ * Callers (command palette, nav rail, project-tree context menu) should not have to know
+ * about window kinds or payload keys, and passing no path should land somewhere sensible
+ * rather than at a hardcoded "/" that does not exist on Windows.
+ */
+
+import { useWindowStore } from "@/components/floating-window/window-store";
+import { isMobileDevice } from "@/hooks/use-is-mobile";
+import { cachedHomedir, getHostInfo } from "./use-host-info";
+import { MOBILE_EXPLORER_WINDOW_ID, openMobileExplorer } from "./use-explorer-open-state";
+
+/**
+ * Open an explorer at `path`, or at the host's home directory when omitted — a floating
+ * window on desktop, the full-screen sheet on mobile. Returns the window id (desktop),
+ * `MOBILE_EXPLORER_WINDOW_ID` (mobile), or null when the home lookup failed and no path
+ * was given.
+ */
+export async function openExplorer(path?: string): Promise<string | null> {
+  if (isMobileDevice()) {
+    await openMobileExplorer(path);
+    return MOBILE_EXPLORER_WINDOW_ID;
+  }
+
+  let target = path ?? cachedHomedir();
+  if (!target) {
+    try {
+      target = (await getHostInfo()).homedir;
+    } catch {
+      return null;
+    }
+  }
+  return useWindowStore.getState().open("explorer", { path: target });
+}

package/src/web/components/os-explorer/properties-dialog.tsx

@@ -0,0 +1,99 @@
+/**
+ * Properties for one entry, read fresh from `/api/fs/stat` rather than from the listing:
+ * the listing has no permissions, no symlink target and no child count, and it may be
+ * seconds old.
+ */
+
+import { useEffect, useState } from "react";
+import { Loader2 } from "lucide-react";
+import { fsApi, type FsEntry, type FsStatResult } from "@/lib/fs-api";
+import { Button } from "@/components/ui/button";
+import { ExplorerModalShell } from "./explorer-modal-shell";
+import { dirnameOf, formatDateTime, formatMode, formatSize } from "./format-file-meta";
+
+const KIND_LABEL: Record<FsStatResult["kind"], string> = {
+  file: "File",
+  directory: "Folder",
+  symlink: "Symbolic link",
+  unknown: "Unknown",
+};
+
+function Row({ label, value }: { label: string; value: string }) {
+  if (!value) return null;
+  return (
+    <div className="grid grid-cols-[7rem_1fr] gap-2 py-1 text-sm">
+      <span className="text-text-2">{label}</span>
+      <span className="break-all text-text">{value}</span>
+    </div>
+  );
+}
+
+export interface PropertiesDialogProps {
+  entry: FsEntry;
+  platform: string | undefined;
+  sep: string;
+  onClose(): void;
+}
+
+export function PropertiesDialog({ entry, platform, sep, onClose }: PropertiesDialogProps) {
+  const [stat, setStat] = useState<FsStatResult | null>(null);
+  const [error, setError] = useState<string | null>(null);
+
+  useEffect(() => {
+    let alive = true;
+    const controller = new AbortController();
+    setStat(null);
+    setError(null);
+    fsApi
+      .stat(entry.path, controller.signal)
+      .then((result) => { if (alive) setStat(result); })
+      .catch((e: unknown) => {
+        if (alive) setError(e instanceof Error ? e.message : "Could not read properties");
+      });
+    return () => { alive = false; controller.abort(); };
+  }, [entry.path]);
+
+  const sizeLabel = stat
+    ? stat.kind === "directory"
+      ? `${stat.childCount ?? 0}${stat.truncated ? "+" : ""} item${stat.childCount === 1 ? "" : "s"}`
+      : `${formatSize(stat.size)} (${stat.size.toLocaleString()} bytes)`
+    : "";
+
+  // Windows does not encode write permission in the mode bits, so the read-only flag is
+  // the meaningful answer there and the octal is the meaningful one everywhere else.
+  const permissions = stat
+    ? platform === "win32"
+      ? (stat.readonly ? "Read-only" : "Read / write")
+      : `${formatMode(stat.mode)}${stat.readonly ? " (read-only)" : ""}`
+    : "";
+
+  return (
+    <ExplorerModalShell
+      open
+      onClose={onClose}
+      title={entry.name}
+      description="Properties"
+      footer={<Button variant="outline" onClick={onClose}>Close</Button>}
+    >
+      {error && <p className="py-2 text-sm text-error">{error}</p>}
+      {!stat && !error && (
+        <div className="flex items-center gap-2 py-4 text-sm text-text-2">
+          <Loader2 className="size-4 animate-spin" /> Reading…
+        </div>
+      )}
+      {stat && (
+        <div className="divide-y divide-border">
+          <Row label="Name" value={stat.name} />
+          <Row label="Kind" value={KIND_LABEL[stat.kind]} />
+          <Row label="Location" value={dirnameOf(stat.path, sep)} />
+          <Row label={stat.kind === "directory" ? "Contains" : "Size"} value={sizeLabel} />
+          <Row label="Created" value={formatDateTime(stat.birthtime)} />
+          <Row label="Modified" value={formatDateTime(stat.mtime)} />
+          <Row label="Permissions" value={permissions} />
+          <Row label="Hidden" value={stat.isHidden ? "Yes" : ""} />
+          <Row label="Links to" value={stat.target ?? ""} />
+        </div>
+      )}
+    </ExplorerModalShell>
+  );
+}

package/src/web/components/os-explorer/skins/explorer-skin-chrome.tsx

@@ -0,0 +1,17 @@
+/**
+ * The one thing `window-content-registry.ts` needs to import to give explorer windows a
+ * skinned titlebar: a plain (non-lazy) component matching `WindowChromeProps` that picks
+ * the current skin and delegates to its real chrome. `FloatingWindow` renders `chrome`
+ * directly with no `<Suspense>` around it, so this entry point cannot be `lazy()` the way
+ * the window body is — it has to resolve synchronously, which is exactly what a small
+ * wrapper component (rather than the whole explorer body) affords.
+ */
+
+import type { WindowChromeProps } from "@/components/floating-window/window-chrome-contract";
+import { useExplorerSkin } from "./use-explorer-skin";
+
+export function ExplorerSkinChrome(props: WindowChromeProps) {
+  const skin = useExplorerSkin();
+  const Chrome = skin.chrome;
+  return <Chrome {...props} />;
+}

package/src/web/components/os-explorer/skins/folder-icon-macos.tsx

@@ -0,0 +1,42 @@
+/**
+ * Hand-drawn Finder-flavoured folder glyphs (closed/open) — an original blue-gradient
+ * rounded folder, not a copy of Apple's proprietary folder artwork.
+ *
+ * Gradient ids are per-instance (`useId`) since a folder-heavy listing renders dozens of
+ * these at once — a hardcoded id would make every icon after the first reuse the first
+ * instance's `<linearGradient>` (SVG `url(#id)` resolves to the first match in the DOM).
+ */
+
+import { useId, type ComponentProps } from "react";
+
+export function MacFolderIcon(props: ComponentProps<"svg">) {
+  const gradientId = `mac-folder-${useId()}`;
+  return (
+    <svg viewBox="0 0 24 24" fill="none" xmlns="http://www.w3.org/2000/svg" {...props}>
+      <defs>
+        <linearGradient id={gradientId} x1="0" y1="0" x2="0" y2="1">
+          <stop offset="0" stopColor="#7FC1FF" />
+          <stop offset="1" stopColor="#3E92E5" />
+        </linearGradient>
+      </defs>
+      <path d="M2.5 8a2 2 0 0 1 2-2h5.2l1.7 2H19.5a2 2 0 0 1 2 2v7.5a2 2 0 0 1-2 2h-15a2 2 0 0 1-2-2V8Z" fill={`url(#${gradientId})`} />
+      <path d="M2.5 10.5h19V9.8H4.7A2 2 0 0 0 2.5 10.5Z" fill="#FFFFFF" fillOpacity=".3" />
+    </svg>
+  );
+}
+
+export function MacFolderOpenIcon(props: ComponentProps<"svg">) {
+  const gradientId = `mac-folder-open-${useId()}`;
+  return (
+    <svg viewBox="0 0 24 24" fill="none" xmlns="http://www.w3.org/2000/svg" {...props}>
+      <defs>
+        <linearGradient id={gradientId} x1="0" y1="0" x2="0" y2="1">
+          <stop offset="0" stopColor="#8FCBFF" />
+          <stop offset="1" stopColor="#2F82D9" />
+        </linearGradient>
+      </defs>
+      <path d="M2.5 8a2 2 0 0 1 2-2h5.2l1.7 2H19.5a2 2 0 0 1 2 2v.3H5.9a2 2 0 0 0-1.94 1.51L2.5 17.9V8Z" fill="#7FC1FF" />
+      <path d="M2.13 18.36 3.98 11.1A2 2 0 0 1 5.92 9.6H21l-2.16 8a2 2 0 0 1-1.93 1.48H4.06a2 2 0 0 1-1.93-2.52Z" fill={`url(#${gradientId})`} />
+    </svg>
+  );
+}

package/src/web/components/os-explorer/skins/folder-icon-windows.tsx

@@ -0,0 +1,25 @@
+/**
+ * Hand-drawn Windows-11-flavoured folder glyphs (closed/open) — an original flat-yellow
+ * rounded-rect with a tab, not a copy of Microsoft's proprietary folder artwork.
+ */
+
+import type { ComponentProps } from "react";
+
+export function WindowsFolderIcon(props: ComponentProps<"svg">) {
+  return (
+    <svg viewBox="0 0 24 24" fill="none" xmlns="http://www.w3.org/2000/svg" {...props}>
+      <path d="M3 7.5a1.5 1.5 0 0 1 1.5-1.5H10l1.6 2H19.5A1.5 1.5 0 0 1 21 9.5v8A1.5 1.5 0 0 1 19.5 19h-15A1.5 1.5 0 0 1 3 17.5v-10Z" fill="#FFC93E" />
+      <path d="M3 9.5h18v8A1.5 1.5 0 0 1 19.5 19h-15A1.5 1.5 0 0 1 3 17.5v-8Z" fill="#FFCE49" />
+      <path d="M4 9.2h16" stroke="#FFFFFF" strokeOpacity=".35" strokeWidth="1" />
+    </svg>
+  );
+}
+
+export function WindowsFolderOpenIcon(props: ComponentProps<"svg">) {
+  return (
+    <svg viewBox="0 0 24 24" fill="none" xmlns="http://www.w3.org/2000/svg" {...props}>
+      <path d="M3 7.5a1.5 1.5 0 0 1 1.5-1.5H10l1.6 2H19.5A1.5 1.5 0 0 1 21 9.5v.5H5.2a1.5 1.5 0 0 0-1.45 1.13L2 18.2V7.5Z" fill="#FFC93E" />
+      <path d="M2.62 18.66 4.3 12.1A1.5 1.5 0 0 1 5.75 11H21l-1.86 6.63A1.5 1.5 0 0 1 17.7 18.7H4.06a1.5 1.5 0 0 1-1.44-1.9Z" fill="#FFB92E" />
+    </svg>
+  );
+}

package/src/web/components/os-explorer/skins/macos-skin.ts

@@ -0,0 +1,14 @@
+import { MacFolderIcon, MacFolderOpenIcon } from "./folder-icon-macos";
+import { MacosWindowChrome } from "./macos-window-chrome";
+import type { ExplorerSkin } from "./skin-types";
+
+export const macosSkin: ExplorerSkin = {
+  id: "macos",
+  // Finder's sidebar shows one "Locations" group in principle, but this sidebar renders
+  // known folders and drives as two separate sections — reusing the same title would look
+  // like a duplicated header, so drives get their own distinct label.
+  vocab: { home: "Home", pinned: "Favorites", known: "Locations", drives: "Devices" },
+  FolderIcon: MacFolderIcon,
+  FolderOpenIcon: MacFolderOpenIcon,
+  chrome: MacosWindowChrome,
+};

package/src/web/components/os-explorer/skins/macos-window-chrome.tsx

@@ -0,0 +1,69 @@
+/**
+ * Finder-flavoured unified titlebar: traffic lights left (grey when unfocused, hover
+ * reveals the glyph), title centred. Height matches the shared `TITLEBAR_HEIGHT` contract
+ * constant (not the real Finder 38px) so a minimised window's collapsed height agrees with
+ * what `FloatingWindow` reserves for it. The toolbar row (back/forward/view-switch/search)
+ * is the existing `ExplorerToolbar` in the window body, tinted by `skins.css` — the chrome
+ * slot is only the titlebar itself.
+ *
+ * `data-skin` is set here (not only on the explorer body) because this titlebar is a
+ * sibling of the body in the window tree — the `--x-*` vars it reads only resolve on an
+ * element that itself carries the attribute.
+ */
+
+import { Minus, Plus, X } from "lucide-react";
+import { cn } from "@/lib/utils";
+import { TITLEBAR_HEIGHT, type WindowChromeProps } from "@/components/floating-window/window-chrome-contract";
+
+/** The traffic-light colours, plus the unfocused grey — the documented hardcoded hexes. */
+const LIGHTS = [
+  { color: "#FF5F57", label: "Close window", Icon: X },
+  { color: "#FEBC2E", label: "Minimize window", Icon: Minus },
+  { color: "#28C840", label: "Maximize window", Icon: Plus },
+] as const;
+
+export function MacosWindowChrome({
+  title, focused, titlebarProps, onMinimize, onToggleMaximize, onClose,
+}: WindowChromeProps) {
+  const { className, style, ...rest } = titlebarProps;
+  const actions = [onClose, onMinimize, onToggleMaximize];
+  return (
+    <div
+      {...rest}
+      data-skin="macos"
+      style={{ height: TITLEBAR_HEIGHT, fontFamily: "var(--x-font)", ...style }}
+      className={cn(
+        "group/titlebar relative flex items-center shrink-0 rounded-t-[var(--x-radius)] overflow-hidden",
+        "bg-[var(--x-titlebar-bg)] border-b border-border",
+        "outline-none focus-visible:ring-1 focus-visible:ring-primary focus-visible:ring-inset",
+        className,
+      )}
+    >
+      <div className="flex items-center gap-2 pl-3">
+        {LIGHTS.map(({ color, label, Icon }, i) => (
+          <button
+            key={label}
+            type="button"
+            aria-label={label}
+            onClick={actions[i]}
+            className="grid size-3 place-items-center rounded-full"
+            style={{ backgroundColor: focused ? color : "#8E8E93" }}
+          >
+            <Icon
+              className="size-2 text-black/60 can-hover:opacity-0 can-hover:group-hover/titlebar:opacity-100"
+              strokeWidth={3}
+            />
+          </button>
+        ))}
+      </div>
+      <span
+        className={cn(
+          "pointer-events-none absolute inset-x-0 truncate text-center text-[13px]",
+          focused ? "text-text" : "text-text-2",
+        )}
+      >
+        {title}
+      </span>
+    </div>
+  );
+}

package/src/web/components/os-explorer/skins/skin-types.ts

@@ -0,0 +1,40 @@
+/**
+ * A skin is everything that makes the explorer window look native to a host OS: the
+ * titlebar/toolbar chrome, the sidebar section names, and the folder glyph. Views, the
+ * toolbar body and the sidebar rows themselves stay skin-agnostic — they read `vocab` and
+ * the folder icon slot, nothing else changes.
+ *
+ * Colours are deliberately not part of this type: skin-specific CSS lives in `skins.css`
+ * scoped under `[data-skin]`, reusing PPM's existing semantic tokens (`bg-panel`,
+ * `text-text`, …) so both PPM dark and light modes fall out for free instead of needing a
+ * second light/dark table here.
+ */
+
+import type { ComponentProps, FC } from "react";
+import type { WindowChrome } from "@/components/floating-window/window-chrome-contract";
+
+export type SkinId = "windows" | "macos";
+
+/** Sidebar section labels that differ between a Windows and a Mac/Linux file manager. */
+export interface SkinVocab {
+  /** "Home" on both, kept explicit in case a future skin wants to drop it. */
+  home: string;
+  /** "Quick access" (Windows) vs "Favorites" (macOS). */
+  pinned: string;
+  /** "Folders" (Windows) vs "Locations" (macOS) — the known-folders section. */
+  known: string;
+  /** "Drives" (Windows) vs "Devices" (macOS) — rendered as its own section, so it needs a
+   *  label distinct from `known` even though Finder visually groups both under Locations. */
+  drives: string;
+}
+
+export type FolderIconComponent = FC<ComponentProps<"svg">>;
+
+export interface ExplorerSkin {
+  id: SkinId;
+  vocab: SkinVocab;
+  FolderIcon: FolderIconComponent;
+  FolderOpenIcon: FolderIconComponent;
+  /** Window titlebar/toolbar chrome for this skin. */
+  chrome: WindowChrome;
+}

package/src/web/components/os-explorer/skins/skins.css

@@ -0,0 +1,25 @@
+/*
+ * OS Explorer skin tokens, scoped to `[data-skin]` set on the explorer root
+ * (`ExplorerBody`). Colours stay derived from PPM's existing semantic tokens
+ * (`--panel-2`, `--border`, `--accent-2`, …) via `color-mix()` rather than a second
+ * light/dark table, so both PPM themes stay legible without duplicating that logic here.
+ * Layout metrics (radius, font stack) are the only skin-owned constants.
+ */
+
+[data-skin="windows"] {
+  --x-radius: 8px;
+  --x-font: "Segoe UI Variable Text", "Segoe UI", system-ui, -apple-system, sans-serif;
+  --x-titlebar-bg: var(--panel-2);
+  --x-toolbar-bg: var(--panel-2);
+  /* A flat "Mica-ish" wash: a touch lighter than the base panel, same on any theme. */
+  --x-sidebar-bg: color-mix(in srgb, var(--panel-2) 90%, white 10%);
+}
+
+[data-skin="macos"] {
+  --x-radius: 10px;
+  --x-font: -apple-system, "SF Pro Text", "SF Pro", system-ui, sans-serif;
+  --x-titlebar-bg: var(--panel-2);
+  --x-toolbar-bg: var(--panel-2);
+  /* Finder's sidebar reads a hair cooler than its content pane. */
+  --x-sidebar-bg: color-mix(in srgb, var(--panel-2) 85%, var(--accent-2) 6%);
+}

package/src/web/components/os-explorer/skins/use-explorer-skin.ts

@@ -0,0 +1,21 @@
+/**
+ * Resolves which skin an explorer window should wear: the user's Settings override when
+ * set, otherwise the host `platform` — Linux gets the macOS look since there is no single
+ * dominant Linux file-manager chrome to imitate (same call the plan made for pinned
+ * folders and known folders).
+ */
+
+import { useSettingsStore } from "@/stores/settings-store";
+import { useHostInfo } from "../use-host-info";
+import { macosSkin } from "./macos-skin";
+import type { ExplorerSkin } from "./skin-types";
+import { windowsSkin } from "./windows-skin";
+
+export function useExplorerSkin(): ExplorerSkin {
+  const override = useSettingsStore((s) => s.explorerSkin);
+  const { host } = useHostInfo();
+
+  if (override === "windows") return windowsSkin;
+  if (override === "macos") return macosSkin;
+  return host?.platform === "win32" ? windowsSkin : macosSkin;
+}

package/src/web/components/os-explorer/skins/windows-skin.ts

@@ -0,0 +1,11 @@
+import { WindowsFolderIcon, WindowsFolderOpenIcon } from "./folder-icon-windows";
+import { WindowsWindowChrome } from "./windows-window-chrome";
+import type { ExplorerSkin } from "./skin-types";
+
+export const windowsSkin: ExplorerSkin = {
+  id: "windows",
+  vocab: { home: "Home", pinned: "Quick access", known: "Folders", drives: "Drives" },
+  FolderIcon: WindowsFolderIcon,
+  FolderOpenIcon: WindowsFolderOpenIcon,
+  chrome: WindowsWindowChrome,
+};

package/src/web/components/os-explorer/skins/windows-window-chrome.tsx

@@ -0,0 +1,56 @@
+/**
+ * Windows 11 File Explorer-flavoured titlebar: window icon + title left, caption buttons
+ * right (46px wide, close hover red). Height matches the shared `TITLEBAR_HEIGHT` contract
+ * constant (not the real Win11 32px) so a minimised window's collapsed height agrees with
+ * what `FloatingWindow` reserves for it. The toolbar row (back/forward/breadcrumb/search) is
+ * the existing `ExplorerToolbar` in the window body, tinted by `skins.css` — the chrome slot
+ * is only the titlebar itself.
+ *
+ * `data-skin` is set here (not only on the explorer body) because this titlebar is a
+ * sibling of the body in the window tree — the `--x-*` vars it reads (`--x-titlebar-bg`,
+ * `--x-radius`, `--x-font`) only resolve on an element that itself carries the attribute.
+ */
+
+import { Minus, Square, Copy, X } from "lucide-react";
+import { cn } from "@/lib/utils";
+import { TITLEBAR_HEIGHT, type WindowChromeProps } from "@/components/floating-window/window-chrome-contract";
+import { WindowsFolderIcon } from "./folder-icon-windows";
+
+/** Windows metric: 46px wide caption buttons, full titlebar height. */
+const CAPTION_BUTTON =
+  "grid place-items-center w-[46px] self-stretch text-text-2 can-hover:hover:bg-surface-elevated can-hover:hover:text-text transition-colors";
+/** The one documented hardcoded hex: Windows' close-button hover red. */
+const CLOSE_BUTTON = cn(CAPTION_BUTTON, "can-hover:hover:!bg-[#c42b1c] can-hover:hover:!text-white");
+
+export function WindowsWindowChrome({
+  title, state, focused, titlebarProps, onMinimize, onToggleMaximize, onClose,
+}: WindowChromeProps) {
+  const { className, style, ...rest } = titlebarProps;
+  return (
+    <div
+      {...rest}
+      data-skin="windows"
+      style={{ height: TITLEBAR_HEIGHT, fontFamily: "var(--x-font)", ...style }}
+      className={cn(
+        "flex items-stretch shrink-0 rounded-t-[var(--x-radius)] overflow-hidden",
+        "bg-[var(--x-titlebar-bg)] border-b border-border",
+        "outline-none focus-visible:ring-1 focus-visible:ring-primary focus-visible:ring-inset",
+        className,
+      )}
+    >
+      <div className="flex flex-1 min-w-0 items-center gap-2 px-2.5 cursor-default">
+        <WindowsFolderIcon className="size-4 shrink-0" />
+        <span className={cn("truncate text-[12px]", focused ? "text-text" : "text-text-2")}>{title}</span>
+      </div>
+      <button type="button" aria-label="Minimize window" className={CAPTION_BUTTON} onClick={onMinimize}>
+        <Minus className="size-3.5" />
+      </button>
+      <button type="button" aria-label={state === "maximized" ? "Restore window" : "Maximize window"} className={CAPTION_BUTTON} onClick={onToggleMaximize}>
+        {state === "maximized" ? <Copy className="size-3" /> : <Square className="size-3" />}
+      </button>
+      <button type="button" aria-label="Close window" className={CLOSE_BUTTON} onClick={onClose}>
+        <X className="size-3.5" />
+      </button>
+    </div>
+  );
+}

package/src/web/components/os-explorer/sort-and-filter-entries.ts

@@ -0,0 +1,52 @@
+/**
+ * The visible row order: the filter text applied first, then the sort.
+ *
+ * Directories always come before files regardless of the sort column, which is what every
+ * desktop file manager does and what keyboard navigation assumes.
+ */
+
+import type { FsEntry } from "@/lib/fs-api";
+import { extensionOf } from "./can-open-in-ppm";
+import type { SortDir, SortKey } from "./explorer-store";
+
+/** Locale-aware, digit-aware name compare so "file10" sorts after "file9". */
+const collator = new Intl.Collator(undefined, { numeric: true, sensitivity: "base" });
+
+function compareBy(key: SortKey, a: FsEntry, b: FsEntry): number {
+  switch (key) {
+    case "size":
+      return (a.size ?? 0) - (b.size ?? 0);
+    case "modified":
+      return new Date(a.modified).getTime() - new Date(b.modified).getTime();
+    case "kind": {
+      const byExt = collator.compare(extensionOf(a.name), extensionOf(b.name));
+      return byExt !== 0 ? byExt : collator.compare(a.name, b.name);
+    }
+    case "name":
+      return collator.compare(a.name, b.name);
+  }
+}
+
+export function sortAndFilterEntries(
+  entries: FsEntry[],
+  filter: string,
+  sort: { key: SortKey; dir: SortDir },
+): FsEntry[] {
+  const needle = filter.trim().toLowerCase();
+  const visible = needle ? entries.filter((e) => e.name.toLowerCase().includes(needle)) : entries;
+  const sign = sort.dir === "asc" ? 1 : -1;
+
+  return [...visible].sort((a, b) => {
+    const aDir = a.type === "directory";
+    const bDir = b.type === "directory";
+    if (aDir !== bDir) return aDir ? -1 : 1;
+    const result = compareBy(sort.key, a, b);
+    // Equal keys fall back to the name so the order never depends on readdir sequence.
+    return (result !== 0 ? result : collator.compare(a.name, b.name)) * sign;
+  });
+}
+
+/** Total bytes of the given entries; directories contribute nothing (size unknown). */
+export function totalSize(entries: FsEntry[]): number {
+  return entries.reduce((sum, e) => sum + (e.type === "file" ? (e.size ?? 0) : 0), 0);
+}

package/src/web/components/os-explorer/sort-options.ts

@@ -0,0 +1,29 @@
+/**
+ * Shared sort vocabulary: the four sortable keys and the two directions, with the labels
+ * shown to the user. The toolbar sort menu, the background context menu's "Sort by"
+ * submenu, the List view's column headers and the mobile More sheet all read from here so
+ * the four surfaces can never say something different about what "Kind" or "Descending"
+ * means.
+ */
+
+import type { SortDir, SortKey } from "./explorer-store";
+
+export const SORT_KEY_OPTIONS: readonly { key: SortKey; label: string }[] = [
+  { key: "name", label: "Name" },
+  { key: "size", label: "Size" },
+  { key: "modified", label: "Modified" },
+  { key: "kind", label: "Kind" },
+];
+
+export const SORT_DIR_OPTIONS: readonly { dir: SortDir; label: string }[] = [
+  { dir: "asc", label: "Ascending" },
+  { dir: "desc", label: "Descending" },
+];
+
+export function sortKeyLabel(key: SortKey): string {
+  return SORT_KEY_OPTIONS.find((option) => option.key === key)?.label ?? key;
+}
+
+export function sortDirLabel(dir: SortDir): string {
+  return SORT_DIR_OPTIONS.find((option) => option.dir === dir)?.label ?? dir;
+}

package/src/web/components/os-explorer/toolbar-icon-button.ts

@@ -0,0 +1,18 @@
+/**
+ * Shared square icon-button styling for the window toolbar and any trigger that sits
+ * alongside it (e.g. the sort menu button) — one class builder keeps their hit-box
+ * behaviour identical instead of two toolbars drifting apart.
+ *
+ * The visible box stays `size-7` (28px) on every pointer type — only the tap-registering
+ * area grows to the 44px minimum on a coarse pointer, via an invisible expanded `::before`
+ * (a click anywhere in it still hits this element; nothing about the button's look moves).
+ */
+
+import { cn } from "@/lib/utils";
+
+export function toolbarButtonClass(coarse: boolean): string {
+  return cn(
+    "relative flex size-7 shrink-0 items-center justify-center rounded text-text-subtle can-hover:hover:bg-surface-elevated can-hover:hover:text-text disabled:opacity-30",
+    coarse && "before:absolute before:-inset-2 before:content-['']",
+  );
+}