@hienlh/ppm 0.17.57 → 0.18.0

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

@@ -0,0 +1,117 @@
+/**
+ * The mobile toolbar's overflow sheet: view mode, sort, hidden files, permanent delete and
+ * properties of the *current folder* (not the selection — that's what the row/tile menu and
+ * the selection-mode toolbar are for).
+ *
+ * "Delete permanently" lives here rather than on the one-tap selection toolbar so the
+ * irreversible action never sits as close at hand as Trash.
+ */
+
+import {
+  Columns3, Eye, EyeOff, Info, LayoutGrid, List, Trash2,
+} from "lucide-react";
+import type { FsEntry } from "@/lib/fs-api";
+import { BottomSheet, BottomSheetItem, BottomSheetSeparator, BottomSheetSubLabel } from "@/components/ui/mobile-bottom-sheet";
+import type { ExplorerActions } from "../actions/use-explorer-actions";
+import { useExplorerStore, type ExplorerSlice, type ViewMode } from "../explorer-store";
+import { SORT_KEY_OPTIONS } from "../sort-options";
+import { activeEntries } from "../use-explorer-keyboard";
+import { AVAILABLE_VIEW_MODES } from "../views/explorer-view-registry";
+import { cn } from "@/lib/utils";
+
+const VIEW_ICON: Record<ViewMode, typeof List> = { list: List, icons: LayoutGrid, columns: Columns3 };
+const VIEW_LABEL: Record<ViewMode, string> = { list: "List", icons: "Icons", columns: "Columns" };
+
+/** The current folder, in the shape `showProperties`/`PropertiesDialog` need — the dialog
+ *  fetches everything else itself from `/api/fs/stat`. */
+function currentFolderEntry(slice: ExplorerSlice): FsEntry {
+  const name = slice.breadcrumbs[slice.breadcrumbs.length - 1]?.name ?? slice.path;
+  return { name, path: slice.path, type: "directory", kind: "directory", modified: "" };
+}
+
+export interface MobileMoreSheetProps {
+  open: boolean;
+  onClose(): void;
+  slice: ExplorerSlice;
+  actions: ExplorerActions;
+  entries: FsEntry[];
+}
+
+export function MobileMoreSheet({ open, onClose, slice, actions, entries }: MobileMoreSheetProps) {
+  const viewMode = useExplorerStore((s) => s.viewMode);
+  const sort = useExplorerStore((s) => s.sort);
+  const showHidden = useExplorerStore((s) => s.showHidden);
+  const setPrefs = useExplorerStore((s) => s.setPrefs);
+  const targets = activeEntries(slice, entries);
+
+  return (
+    <BottomSheet open={open} onClose={onClose} className="p-2">
+      <BottomSheetSubLabel>View</BottomSheetSubLabel>
+      <div className="flex gap-1 px-2 pb-2">
+        {AVAILABLE_VIEW_MODES.map((mode) => {
+          const Icon = VIEW_ICON[mode];
+          return (
+            <button
+              key={mode}
+              type="button"
+              aria-pressed={viewMode === mode}
+              onClick={() => { setPrefs({ viewMode: mode }); onClose(); }}
+              className={cn(
+                "flex flex-1 flex-col items-center gap-1 rounded-lg py-2 text-xs active:bg-surface-elevated",
+                viewMode === mode ? "bg-accent-wash text-primary" : "text-text-2",
+              )}
+            >
+              <Icon className="size-4" />
+              {VIEW_LABEL[mode]}
+            </button>
+          );
+        })}
+      </div>
+
+      <BottomSheetSeparator />
+      <BottomSheetSubLabel>Sort by</BottomSheetSubLabel>
+      <div className="flex flex-wrap gap-1 px-2 pb-2">
+        {SORT_KEY_OPTIONS.map(({ key, label }) => (
+          <button
+            key={key}
+            type="button"
+            aria-pressed={sort.key === key}
+            onClick={() => {
+              setPrefs({ sort: { key, dir: sort.key === key && sort.dir === "asc" ? "desc" : "asc" } });
+              onClose();
+            }}
+            className={cn(
+              // min-h-11 (44px) keeps the tap target compliant without inflating the pill's
+              // padding to match — inline-flex + items-center re-centers the small text
+              // inside the taller box.
+              "inline-flex min-h-11 items-center justify-center rounded-full border px-3 py-1.5 text-xs active:bg-surface-elevated",
+              sort.key === key ? "border-primary bg-accent-wash text-text" : "border-border text-text-2",
+            )}
+          >
+            {label}{sort.key === key ? (sort.dir === "asc" ? " ↑" : " ↓") : ""}
+          </button>
+        ))}
+      </div>
+
+      <BottomSheetSeparator />
+      <BottomSheetItem onClick={() => setPrefs({ showHidden: !showHidden })}>
+        {showHidden ? <Eye className="size-4" /> : <EyeOff className="size-4" />}
+        {showHidden ? "Hide hidden files" : "Show hidden files"}
+      </BottomSheetItem>
+
+      <BottomSheetSeparator />
+      <BottomSheetItem
+        variant="destructive"
+        disabled={targets.length === 0}
+        onClick={() => actions.confirmPermanentDelete(targets)}
+      >
+        <Trash2 className="size-4" />
+        Delete permanently{targets.length > 1 ? ` (${targets.length})` : ""}
+      </BottomSheetItem>
+      <BottomSheetItem onClick={() => actions.showProperties(currentFolderEntry(slice))}>
+        <Info className="size-4" />
+        Properties of this folder
+      </BottomSheetItem>
+    </BottomSheet>
+  );
+}

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

@@ -0,0 +1,120 @@
+/**
+ * Full places list behind the chip strip's "All places" chip: PPM pins, OS pinned folders,
+ * known folders and drives, each sectioned exactly like the desktop sidebar — the strip only
+ * condenses the *common case*, this sheet is where everything still lives.
+ */
+
+import type { ReactNode } from "react";
+import { HardDrive, Network, Pin, Usb } from "lucide-react";
+import type { Drive, HostInfo } from "../../../../types/system";
+import { BottomSheet } from "@/components/ui/mobile-bottom-sheet";
+import { useExplorerPinsStore } from "../explorer-pins-store";
+import { FileTypeIcon } from "../icons/file-type-icon";
+import type { SkinVocab } from "../skins/skin-types";
+import { cn } from "@/lib/utils";
+
+const ICON_CLASS = "size-4 shrink-0 text-text-subtle";
+const DRIVE_ICON: Record<Drive["kind"], typeof HardDrive> = {
+  fixed: HardDrive,
+  removable: Usb,
+  network: Network,
+  unknown: HardDrive,
+};
+
+/** Folder-type place rows draw the current skin's folder glyph, same as the desktop sidebar. */
+function folderIcon(): ReactNode {
+  return <FileTypeIcon name="" kind="directory" className={ICON_CLASS} />;
+}
+
+function Row({
+  label, path, active, icon, onNavigate,
+}: {
+  label: string; path: string; active: boolean; icon: ReactNode; onNavigate(path: string): void;
+}) {
+  return (
+    <button
+      type="button"
+      title={path}
+      onClick={() => onNavigate(path)}
+      className={cn(
+        "flex min-h-[44px] w-full items-center gap-2.5 rounded-lg px-3 text-left text-sm active:bg-surface-elevated",
+        active ? "bg-accent-wash text-text" : "text-text-2",
+      )}
+    >
+      {icon}
+      <span className="truncate">{label}</span>
+    </button>
+  );
+}
+
+function Section({ title, children }: { title: string; children: ReactNode }) {
+  return (
+    <div className="pb-2">
+      <p className="px-3 pb-1 pt-3 text-[11px] font-semibold uppercase tracking-wide text-text-subtle">{title}</p>
+      {children}
+    </div>
+  );
+}
+
+export interface MobilePlacesSheetProps {
+  open: boolean;
+  onClose(): void;
+  host: HostInfo | null;
+  currentPath: string;
+  vocab: SkinVocab;
+  onNavigate(path: string): void;
+}
+
+export function MobilePlacesSheet({ open, onClose, host, currentPath, vocab, onNavigate }: MobilePlacesSheetProps) {
+  const pins = useExplorerPinsStore((s) => s.pins);
+  const isActive = (path: string) => path === currentPath;
+
+  return (
+    <BottomSheet open={open} onClose={onClose} zIndex={65} className="p-1">
+      <div className="max-h-[70vh] overflow-y-auto px-1 pb-2">
+        {pins.length > 0 && (
+          <Section title="Pinned">
+            {pins.map((pin) => (
+              <Row key={pin.path} label={pin.name} path={pin.path} icon={<Pin className={ICON_CLASS} />} active={isActive(pin.path)} onNavigate={onNavigate} />
+            ))}
+          </Section>
+        )}
+
+        {host && host.pinned.length > 0 && (
+          <Section title={vocab.pinned}>
+            {host.pinned.map((entry) => (
+              <Row key={entry.path} label={entry.name} path={entry.path} icon={folderIcon()} active={isActive(entry.path)} onNavigate={onNavigate} />
+            ))}
+          </Section>
+        )}
+
+        {host && (
+          <Section title={vocab.known}>
+            <Row label={vocab.home} path={host.homedir} icon={folderIcon()} active={isActive(host.homedir)} onNavigate={onNavigate} />
+            {host.knownFolders.map((folder) => (
+              <Row key={folder.path} label={folder.name} path={folder.path} icon={folderIcon()} active={isActive(folder.path)} onNavigate={onNavigate} />
+            ))}
+          </Section>
+        )}
+
+        {host && host.drives.length > 0 && (
+          <Section title={vocab.drives}>
+            {host.drives.map((drive) => {
+              const DriveIcon = DRIVE_ICON[drive.kind];
+              return (
+                <Row
+                  key={drive.path}
+                  label={drive.label ? `${drive.label} (${drive.name})` : drive.name}
+                  path={drive.path}
+                  icon={<DriveIcon className={ICON_CLASS} />}
+                  active={isActive(drive.path)}
+                  onNavigate={onNavigate}
+                />
+              );
+            })}
+          </Section>
+        )}
+      </div>
+    </BottomSheet>
+  );
+}

package/src/web/components/os-explorer/mobile/mobile-places-strip.tsx

@@ -0,0 +1,109 @@
+/**
+ * Sidebar → horizontally scrollable "places" chip strip on mobile: PPM pins, the host's own
+ * pinned folders, Home, and drives — condensed to fit under the title instead of a side
+ * column. The full list (known folders included) lives in a "Places" sheet behind the last
+ * chip.
+ *
+ * `touch-pan-x` keeps the browser's native scroll-chaining to the horizontal axis only, so a
+ * drag that starts on a chip does not also read as a vertical page scroll.
+ */
+
+import { useState, type ComponentType } from "react";
+import { HardDrive, MoreHorizontal, Network, Pin, Usb } from "lucide-react";
+import type { Drive, HostInfo } from "../../../../types/system";
+import { cn } from "@/lib/utils";
+import { useExplorerPinsStore } from "../explorer-pins-store";
+import { FileTypeIcon } from "../icons/file-type-icon";
+import type { SkinVocab } from "../skins/skin-types";
+import { MobilePlacesSheet } from "./mobile-places-sheet";
+
+function FolderChipIcon({ className }: { className?: string }) {
+  return <FileTypeIcon name="" kind="directory" className={className} />;
+}
+
+const DRIVE_ICON: Record<Drive["kind"], ComponentType<{ className?: string }>> = {
+  fixed: HardDrive,
+  removable: Usb,
+  network: Network,
+  unknown: HardDrive,
+};
+
+interface Chip {
+  key: string;
+  label: string;
+  path: string;
+  icon: ComponentType<{ className?: string }>;
+}
+
+function Chip({ chip, active, onNavigate }: { chip: Chip; active: boolean; onNavigate(path: string): void }) {
+  const Icon = chip.icon;
+  return (
+    <button
+      type="button"
+      onClick={() => onNavigate(chip.path)}
+      title={chip.path}
+      className={cn(
+        "flex h-11 shrink-0 items-center gap-1.5 rounded-full border px-3 text-[13px] active:bg-surface-elevated",
+        active ? "border-primary bg-accent-wash text-text" : "border-border text-text-2",
+      )}
+    >
+      <Icon className="size-4 shrink-0 text-text-subtle" />
+      <span className="max-w-[9rem] truncate">{chip.label}</span>
+    </button>
+  );
+}
+
+export interface MobilePlacesStripProps {
+  host: HostInfo | null;
+  currentPath: string;
+  onNavigate(path: string): void;
+  vocab: SkinVocab;
+}
+
+export function MobilePlacesStrip({ host, currentPath, onNavigate, vocab }: MobilePlacesStripProps) {
+  const pins = useExplorerPinsStore((s) => s.pins);
+  const [placesOpen, setPlacesOpen] = useState(false);
+
+  const chips: Chip[] = [
+    ...pins.map((pin): Chip => ({ key: `pin:${pin.path}`, label: pin.name, path: pin.path, icon: Pin })),
+    ...(host ? [{ key: "home", label: vocab.home, path: host.homedir, icon: FolderChipIcon }] : []),
+    ...(host?.pinned.map((p): Chip => ({ key: `os:${p.path}`, label: p.name, path: p.path, icon: FolderChipIcon })) ?? []),
+    ...(host?.drives.map((d): Chip => ({
+      key: `drive:${d.path}`,
+      label: d.label ? `${d.label} (${d.name})` : d.name,
+      path: d.path,
+      icon: DRIVE_ICON[d.kind],
+    })) ?? []),
+  ];
+
+  return (
+    <>
+      <div className="flex shrink-0 items-center gap-1.5 overflow-x-auto touch-pan-x border-b border-border px-2 py-1.5">
+        {chips.map((chip) => (
+          <Chip key={chip.key} chip={chip} active={chip.path === currentPath} onNavigate={onNavigate} />
+        ))}
+        <button
+          type="button"
+          aria-label="All places"
+          title="All places"
+          onClick={() => setPlacesOpen(true)}
+          className="flex h-11 shrink-0 items-center gap-1 rounded-full border border-border px-3 text-[13px] text-text-2 active:bg-surface-elevated"
+        >
+          <MoreHorizontal className="size-4" />
+        </button>
+      </div>
+
+      <MobilePlacesSheet
+        open={placesOpen}
+        onClose={() => setPlacesOpen(false)}
+        host={host}
+        currentPath={currentPath}
+        vocab={vocab}
+        onNavigate={(path) => {
+          setPlacesOpen(false);
+          onNavigate(path);
+        }}
+      />
+    </>
+  );
+}

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