@hienlh/ppm 0.17.56 → 0.18.0

package/src/web/components/os-explorer/views/list-view.tsx

@@ -0,0 +1,177 @@
+/**
+ * List view: a sortable header plus virtualised rows.
+ *
+ * Virtualisation is not optional here — `C:\Windows\System32` is ~5 000 entries and the
+ * server hands all of them over in one listing, so only the visible slice may ever be in
+ * the DOM.
+ */
+
+import { useEffect, useMemo, useRef } from "react";
+import { useVirtualizer } from "@tanstack/react-virtual";
+import { ChevronDown, ChevronUp } from "lucide-react";
+import { ContextMenu, ContextMenuTrigger } from "@/components/ui/adaptive-context-menu";
+import { useFileStore } from "@/stores/file-store";
+import { cn } from "@/lib/utils";
+import { DROP_TARGET_CLASS } from "../dnd/drop-target-style";
+import { useDragAutoScroll } from "../dnd/use-drag-auto-scroll";
+import { usePathDropTarget } from "../dnd/use-path-drop-target";
+import { ExplorerContextMenu } from "../explorer-context-menu";
+import { useExplorerStore, type SortKey } from "../explorer-store";
+import { SORT_KEY_OPTIONS } from "../sort-options";
+import { useExplorerSkin } from "../skins/use-explorer-skin";
+import { activeEntries } from "../use-explorer-keyboard";
+import { usePrefersCoarsePointer } from "../use-coarse-long-press";
+import type { ExplorerViewProps } from "./explorer-view-registry";
+import { InlineNameInput } from "./inline-name-input";
+import { ListRow } from "./list-row";
+
+/** Layout per column; labels/keys come from the shared sort vocabulary. */
+const COLUMN_CLASSNAME: Record<SortKey, string> = {
+  name: "flex-1 text-left",
+  size: "w-20 text-right",
+  modified: "hidden w-24 text-right sm:block",
+  kind: "hidden w-16 text-right md:block",
+};
+const COLUMNS = SORT_KEY_OPTIONS.map((option) => ({ ...option, className: COLUMN_CLASSNAME[option.key] }));
+
+export function ListView({
+  slice, entries, actions, selection, inlineError, hasClipboard, isPinned, rowHeight, backgroundLongPress,
+}: ExplorerViewProps) {
+  const sort = useExplorerStore((s) => s.sort);
+  const setPrefs = useExplorerStore((s) => s.setPrefs);
+  const cutPaths = useFileStore((s) => (s.clipboard?.operation === "cut" ? s.clipboard.paths : null));
+  const scrollRef = useRef<HTMLDivElement>(null);
+  useDragAutoScroll(scrollRef);
+  const skin = useExplorerSkin();
+  const coarse = usePrefersCoarsePointer();
+
+  const virtualizer = useVirtualizer({
+    count: entries.length,
+    getScrollElement: () => scrollRef.current,
+    estimateSize: () => rowHeight,
+    overscan: 12,
+  });
+
+  // Keep the cursor row visible when it moved by keyboard rather than by click.
+  const anchorIndex = slice.anchor ? entries.findIndex((e) => e.path === slice.anchor) : -1;
+  useEffect(() => {
+    if (anchorIndex >= 0) virtualizer.scrollToIndex(anchorIndex, { align: "auto" });
+  }, [anchorIndex]); // eslint-disable-line react-hooks/exhaustive-deps
+
+  const menuTargets = useMemo(() => activeEntries(slice, entries), [slice, entries]);
+  const creating = slice.inlineEdit?.kind === "new-file" || slice.inlineEdit?.kind === "new-folder";
+  // The view background is the current directory itself — a row already claims the drop
+  // (and stops the event) when it is a directory, so this only ever fires over empty space.
+  const backgroundDrop = usePathDropTarget({ targetDir: slice.path, run: actions.transferInto });
+
+  const toggleSort = (key: SortKey) =>
+    setPrefs({ sort: { key, dir: sort.key === key && sort.dir === "asc" ? "desc" : "asc" } });
+
+  return (
+    <div className="flex h-full min-h-0 flex-col">
+      <div
+        role="row"
+        className={cn(
+          "flex shrink-0 items-center gap-2 border-b border-border bg-[var(--x-toolbar-bg,var(--panel-2))] px-2 py-1 text-[11px] font-medium text-text-subtle",
+          // Windows Explorer's details header separates columns with a thin divider.
+          skin.id === "windows" && "divide-x divide-border",
+        )}
+      >
+        {COLUMNS.map((column) => (
+          <button
+            key={column.key}
+            type="button"
+            aria-label={`Sort by ${column.label}`}
+            onClick={() => toggleSort(column.key)}
+            className={cn(
+              "relative flex items-center gap-0.5 can-hover:hover:text-text",
+              skin.id === "windows" && column.key !== "name" && "pl-2",
+              column.className,
+              column.key !== "name" && "justify-end",
+              // Header row stays visually unchanged — only the tap-registering area grows
+              // to the 44px minimum on a coarse pointer, via an invisible expanded hit box.
+              coarse && "before:absolute before:-inset-x-2 before:-inset-y-3 before:content-['']",
+            )}
+          >
+            {column.label}
+            {sort.key === column.key &&
+              (sort.dir === "asc" ? <ChevronUp className="size-3" /> : <ChevronDown className="size-3" />)}
+          </button>
+        ))}
+      </div>
+
+      <ContextMenu>
+        <ContextMenuTrigger asChild>
+          <div
+            ref={scrollRef}
+            role="grid"
+            tabIndex={0}
+            data-testid="explorer-list"
+            aria-label="File list"
+            // Clicking the empty area below the rows clears the selection, as in the OS.
+            onMouseDown={(e) => { if (e.target === e.currentTarget) selection.clear(); }}
+            className={cn("flex-1 overflow-auto outline-none", backgroundDrop.isOver && DROP_TARGET_CLASS)}
+            {...backgroundLongPress}
+            {...backgroundDrop.handlers}
+          >
+            {creating && (
+              <div className="flex items-center gap-2 px-2" style={{ height: rowHeight }}>
+                <span className="size-4 shrink-0" />
+                <InlineNameInput
+                  initial=""
+                  error={inlineError}
+                  onCommit={(value) => void actions.commitInline(value)}
+                  onCancel={actions.cancelInline}
+                />
+              </div>
+            )}
+            <div className="relative w-full" style={{ height: virtualizer.getTotalSize() }}>
+              {virtualizer.getVirtualItems().map((item) => {
+                const entry = entries[item.index]!;
+                return (
+                  <div
+                    key={entry.path}
+                    className={cn(
+                      "absolute left-0 top-0 w-full",
+                      // Finder's list view alternates row shading instead of a hover-only cue.
+                      skin.id === "macos" && item.index % 2 === 1 && "bg-panel-2/40",
+                    )}
+                    style={{ transform: `translateY(${item.start}px)` }}
+                  >
+                    <ListRow
+                      entry={entry}
+                      currentDir={slice.path}
+                      selected={slice.selection.has(entry.path)}
+                      focused={slice.anchor === entry.path}
+                      cut={cutPaths?.includes(entry.path) === true}
+                      renaming={slice.inlineEdit?.kind === "rename" && slice.inlineEdit.path === entry.path}
+                      height={rowHeight}
+                      menuTargets={slice.selection.has(entry.path) ? menuTargets : [entry]}
+                      actions={actions}
+                      selection={selection}
+                      hasClipboard={hasClipboard}
+                      isPinned={isPinned}
+                      inlineError={inlineError}
+                    />
+                  </div>
+                );
+              })}
+            </div>
+            {entries.length === 0 && !slice.loading && !creating && (
+              <p className="p-3 text-xs text-text-subtle">
+                {slice.filter ? "No entries match the filter." : "This folder is empty."}
+              </p>
+            )}
+          </div>
+        </ContextMenuTrigger>
+        <ExplorerContextMenu
+          targets={[]}
+          currentDir={slice.path}
+          hasClipboard={hasClipboard}
+          isPinned={isPinned}
+          actions={actions}
+        />
+      </ContextMenu>
+    </div>
+  );
+}

package/src/web/components/os-explorer/views/use-column-view-state.ts

@@ -0,0 +1,158 @@
+/**
+ * Column (Miller) view fetch state: one entry per breadcrumb ancestor, each cached and
+ * fetched independently so drilling one level deeper never re-fetches the columns already
+ * on screen. The deepest column always mirrors the window's own (already fetched, sorted,
+ * filtered) entries instead of fetching a second time.
+ *
+ * The reducer is a plain function — given the same paths/state it does the same thing —
+ * so "selecting a divergent branch truncates and aborts every column after it" is
+ * unit-testable without a DOM or a real network call. It does not call `.abort()` itself
+ * (that would be a side effect inside a reducer, and React may invoke a reducer more than
+ * once per dispatch under StrictMode); it only *identifies* which controllers went stale,
+ * and the hook's effect is the one thing that actually aborts them. The hook is likewise
+ * the only thing that calls `fsApi.browse`.
+ */
+
+import { useEffect, useReducer, useRef } from "react";
+import { fsApi, type FsEntry } from "@/lib/fs-api";
+
+export interface ColumnState {
+  path: string;
+  entries: FsEntry[];
+  loading: boolean;
+  error: string | null;
+  abort: AbortController;
+}
+
+interface ColumnsState {
+  columns: ColumnState[];
+  /** Controllers the last `sync` replaced or truncated; consumed once by an effect. */
+  staleControllers: AbortController[];
+}
+
+type ColumnsAction =
+  | { type: "sync"; paths: string[]; lastEntries: FsEntry[]; lastLoading: boolean; makeAbort(): AbortController }
+  | { type: "loaded"; path: string; entries: FsEntry[] }
+  | { type: "error"; path: string; message: string };
+
+export function reduceColumns(state: ColumnsState, action: ColumnsAction): ColumnsState {
+  switch (action.type) {
+    case "sync": {
+      const { paths, lastEntries, lastLoading, makeAbort } = action;
+      const lastIndex = paths.length - 1;
+      const next: ColumnState[] = paths.map((path, index) => {
+        const existing = state.columns[index];
+        const isLast = index === lastIndex;
+        if (existing && existing.path === path) {
+          // Unchanged column: keep its cache. The deepest column still mirrors the
+          // caller's live copy since sort/filter/hidden-toggle may have changed it.
+          return isLast ? { ...existing, entries: lastEntries, loading: lastLoading, error: null } : existing;
+        }
+        return isLast
+          ? { path, entries: lastEntries, loading: lastLoading, error: null, abort: makeAbort() }
+          : { path, entries: [], loading: true, error: null, abort: makeAbort() };
+      });
+      // Anything at an index whose path changed — including a truncated tail, where there
+      // is no replacement at all — had its own fetch in flight and must stop. Collected
+      // here, aborted by the hook's effect (this function stays a pure computation).
+      const staleControllers: AbortController[] = [];
+      for (let i = 0; i < state.columns.length; i++) {
+        const stale = state.columns[i]!;
+        const replacement = next[i];
+        if (!replacement || replacement.path !== stale.path) staleControllers.push(stale.abort);
+      }
+      return { columns: next, staleControllers };
+    }
+    case "loaded": {
+      return {
+        columns: state.columns.map((c) =>
+          c.path === action.path ? { ...c, entries: action.entries, loading: false, error: null } : c,
+        ),
+        staleControllers: [],
+      };
+    }
+    case "error": {
+      return {
+        columns: state.columns.map((c) =>
+          c.path === action.path ? { ...c, loading: false, error: action.message } : c,
+        ),
+        staleControllers: [],
+      };
+    }
+  }
+}
+
+export interface UseColumnViewState {
+  columns: ColumnState[];
+}
+
+/**
+ * Ties the reducer to real fetches. `paths` is the breadcrumb chain (root … current); the
+ * last path's entries always come from `lastEntries`/`lastLoading`, already owned by the
+ * window's own navigation hook.
+ */
+export function useColumnViewState(
+  paths: string[],
+  lastEntries: FsEntry[],
+  lastLoading: boolean,
+): UseColumnViewState {
+  const [state, dispatch] = useReducer(reduceColumns, { columns: [], staleControllers: [] });
+  // Keyed by controller identity, not path: re-entering a path whose earlier attempt was
+  // aborted (drill A -> B -> back to A before B's abort settles) gets a *fresh* controller
+  // from the reducer, so it must not be blocked by the guard entry the stale attempt left
+  // behind — a path-keyed Set left that fresh column stuck on "Loading…" forever.
+  const fetching = useRef(new Set<AbortController>());
+
+  // A literal NUL separator (never a legal path character on any OS PPM targets) so two
+  // paths whose own text happens to contain a space still produce distinct keys.
+  const pathsKey = paths.join("\u0000");
+  useEffect(() => {
+    dispatch({ type: "sync", paths, lastEntries, lastLoading, makeAbort: () => new AbortController() });
+    // `pathsKey` is the real dependency for `paths`; `lastEntries`/`lastLoading` are objects
+    // that change on every fetch tick, which is exactly when this should re-run too.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [pathsKey, lastEntries, lastLoading]);
+
+  // The one place that actually aborts a stale fetch — the reducer only identified it.
+  useEffect(() => {
+    for (const controller of state.staleControllers) controller.abort();
+  }, [state.staleControllers]);
+
+  // Whatever is still live when this view unmounts (switched to List/Icons, window closed)
+  // must stop fetching too; nothing else ever aborts a column that simply falls out of view.
+  const columnsRef = useRef(state.columns);
+  columnsRef.current = state.columns;
+  useEffect(() => {
+    return () => {
+      for (const column of columnsRef.current) column.abort.abort();
+    };
+  }, []);
+
+  useEffect(() => {
+    const lastIndex = state.columns.length - 1;
+    state.columns.forEach((column, index) => {
+      // The deepest column is never fetched here — it mirrors the window's own listing.
+      if (index === lastIndex) return;
+      if (!column.loading || fetching.current.has(column.abort)) return;
+      fetching.current.add(column.abort);
+      fsApi
+        .browse(column.path, { signal: column.abort.signal })
+        .then((result) => {
+          fetching.current.delete(column.abort);
+          if (column.abort.signal.aborted) return;
+          dispatch({ type: "loaded", path: column.path, entries: result.entries });
+        })
+        .catch((e: unknown) => {
+          fetching.current.delete(column.abort);
+          if (column.abort.signal.aborted || (e instanceof DOMException && e.name === "AbortError")) return;
+          dispatch({
+            type: "error",
+            path: column.path,
+            message: e instanceof Error ? e.message : "Failed to read directory",
+          });
+        });
+    });
+  }, [state.columns]);
+
+  return { columns: state.columns };
+}

package/src/web/components/os-explorer/views/use-entry-selection.ts

@@ -0,0 +1,178 @@
+/**
+ * Selection semantics for the explorer views — plain click, ctrl/cmd toggle, shift range,
+ * arrow-key cursor and type-ahead.
+ *
+ * The reducer is pure and separate from the hook so the fiddly parts (which row does
+ * shift-click extend from after a ctrl-click? does type-ahead wrap?) are unit-testable
+ * without a DOM.
+ */
+
+import { useCallback, useMemo, useRef } from "react";
+import { useExplorerStore } from "../explorer-store";
+
+export interface SelectionState {
+  selection: Set<string>;
+  /** The cursor row: shift-range extends from here and arrows move it. */
+  anchor: string | null;
+}
+
+export type SelectionEvent =
+  | { type: "click"; path: string; shift?: boolean; ctrl?: boolean }
+  | { type: "select-all" }
+  | { type: "clear" }
+  | { type: "set"; paths: string[]; anchor?: string | null };
+
+/** How long a type-ahead buffer stays alive between keystrokes. */
+export const TYPE_AHEAD_RESET_MS = 800;
+
+function rangeBetween(order: string[], from: string | null, to: string): string[] {
+  const start = from == null ? -1 : order.indexOf(from);
+  const end = order.indexOf(to);
+  if (end < 0) return [];
+  if (start < 0) return [to];
+  const [lo, hi] = start <= end ? [start, end] : [end, start];
+  return order.slice(lo, hi + 1);
+}
+
+/** Apply a selection event against the current visible row order. */
+export function applySelection(
+  state: SelectionState,
+  order: string[],
+  event: SelectionEvent,
+): SelectionState {
+  switch (event.type) {
+    case "clear":
+      return { selection: new Set(), anchor: null };
+
+    case "select-all":
+      return { selection: new Set(order), anchor: state.anchor ?? order[0] ?? null };
+
+    case "set":
+      return {
+        selection: new Set(event.paths),
+        anchor: event.anchor !== undefined ? event.anchor : (event.paths[event.paths.length - 1] ?? null),
+      };
+
+    case "click": {
+      if (event.ctrl) {
+        const selection = new Set(state.selection);
+        if (selection.has(event.path)) selection.delete(event.path);
+        else selection.add(event.path);
+        // Ctrl-click moves the anchor so a following shift-click extends from the row
+        // the user just touched — matching Explorer and Finder.
+        return { selection, anchor: event.path };
+      }
+      if (event.shift) {
+        const range = rangeBetween(order, state.anchor, event.path);
+        // The anchor stays put: repeated shift-clicks grow and shrink one range.
+        return { selection: new Set(range), anchor: state.anchor ?? event.path };
+      }
+      return { selection: new Set([event.path]), anchor: event.path };
+    }
+  }
+}
+
+/** Row the cursor moves to for an arrow key. Clamps at both ends (no wrap). */
+export function moveCursor(order: string[], anchor: string | null, delta: number): string | null {
+  if (order.length === 0) return null;
+  const current = anchor == null ? -1 : order.indexOf(anchor);
+  if (current < 0) return delta > 0 ? order[0]! : order[order.length - 1]!;
+  const next = Math.min(order.length - 1, Math.max(0, current + delta));
+  return order[next]!;
+}
+
+/**
+ * First name matching the typed prefix, searching after the current row and wrapping.
+ * Returns the index in `names`, or -1.
+ */
+export function typeAheadIndex(names: string[], buffer: string, currentIndex: number): number {
+  if (!buffer) return -1;
+  const needle = buffer.toLowerCase();
+  // A repeated single character cycles through the matches instead of sticking on one.
+  const start = currentIndex < 0 ? 0 : currentIndex + 1;
+  for (let i = 0; i < names.length; i++) {
+    const index = (start + i) % names.length;
+    if (names[index]!.toLowerCase().startsWith(needle)) return index;
+  }
+  return -1;
+}
+
+export interface EntrySelection {
+  onRowClick(path: string, event: { shiftKey: boolean; ctrlKey: boolean; metaKey: boolean }): void;
+  selectOnly(path: string): void;
+  selectAll(): void;
+  clear(): void;
+  setSelection(paths: string[], anchor?: string | null): void;
+  moveTo(delta: number, extend: boolean): void;
+  /** Feed a printable key; returns the path it landed on, if any. */
+  typeAhead(key: string): string | null;
+}
+
+/** Binds the reducer to one window's slice. `order` is the visible row order. */
+export function useEntrySelection(windowId: string, order: string[]): EntrySelection {
+  const patch = useExplorerStore((s) => s.patch);
+  const orderRef = useRef(order);
+  orderRef.current = order;
+  const bufferRef = useRef({ text: "", at: 0 });
+
+  const dispatch = useCallback(
+    (event: SelectionEvent) => {
+      const slice = useExplorerStore.getState().slices[windowId];
+      if (!slice) return;
+      patch(windowId, applySelection(slice, orderRef.current, event));
+    },
+    [windowId, patch],
+  );
+
+  const moveTo = useCallback(
+    (delta: number, extend: boolean) => {
+      const slice = useExplorerStore.getState().slices[windowId];
+      if (!slice) return;
+      const target = moveCursor(orderRef.current, slice.anchor, delta);
+      if (target == null) return;
+      dispatch({ type: "click", path: target, shift: extend });
+    },
+    [windowId, dispatch],
+  );
+
+  const typeAhead = useCallback(
+    (key: string) => {
+      const slice = useExplorerStore.getState().slices[windowId];
+      if (!slice) return null;
+      const now = Date.now();
+      const buffer = now - bufferRef.current.at > TYPE_AHEAD_RESET_MS ? key : bufferRef.current.text + key;
+      bufferRef.current = { text: buffer, at: now };
+
+      const paths = orderRef.current;
+      const names = paths.map((p) => p.split(/[/\\]/).pop() ?? p);
+      // With a one-character buffer the search starts after the cursor so pressing the
+      // same letter walks through every match.
+      const from = buffer.length === 1 && slice.anchor ? paths.indexOf(slice.anchor) : -1;
+      const index = typeAheadIndex(names, buffer, from);
+      if (index < 0) return null;
+      dispatch({ type: "click", path: paths[index]! });
+      return paths[index]!;
+    },
+    [windowId, dispatch],
+  );
+
+  const onRowClick = useCallback(
+    (path: string, event: { shiftKey: boolean; ctrlKey: boolean; metaKey: boolean }) =>
+      dispatch({ type: "click", path, shift: event.shiftKey, ctrl: event.ctrlKey || event.metaKey }),
+    [dispatch],
+  );
+  const selectOnly = useCallback((path: string) => dispatch({ type: "click", path }), [dispatch]);
+  const selectAll = useCallback(() => dispatch({ type: "select-all" }), [dispatch]);
+  const clear = useCallback(() => dispatch({ type: "clear" }), [dispatch]);
+  const setSelection = useCallback(
+    (paths: string[], anchor?: string | null) => dispatch({ type: "set", paths, anchor }),
+    [dispatch],
+  );
+
+  // A fresh object every render would defeat memo(ListRow) (this is a prop several levels
+  // down) even though every method here is already a stable useCallback.
+  return useMemo(
+    () => ({ onRowClick, selectOnly, selectAll, clear, setSelection, moveTo, typeAhead }),
+    [onRowClick, selectOnly, selectAll, clear, setSelection, moveTo, typeAhead],
+  );
+}

package/src/web/components/settings/settings-tab.tsx

@@ -9,7 +9,7 @@ import { Switch } from "@/components/ui/switch";
 import { ScrollArea } from "@/components/ui/scroll-area";
 import { Separator } from "@/components/ui/separator";
 import { useShallow } from "zustand/react/shallow";
-import { useSettingsStore, type EditorTabStyle } from "@/stores/settings-store";
+import { useSettingsStore, type EditorTabStyle, type ExplorerSkinPref } from "@/stores/settings-store";
 import { cn } from "@/lib/utils";
 import { AISettingsSection } from "./ai-settings-section";
 import { KeyboardShortcutsSection } from "./keyboard-shortcuts-section";
@@ -30,6 +30,12 @@ const TAB_STYLE_OPTIONS: { value: EditorTabStyle; label: string }[] = [
   { value: "pill", label: "Pill" },
 ];
 
+const EXPLORER_SKIN_OPTIONS: { value: ExplorerSkinPref; label: string }[] = [
+  { value: "auto", label: "Auto" },
+  { value: "windows", label: "Windows" },
+  { value: "macos", label: "macOS" },
+];
+
 type SettingsCategory = "ai" | "notifications" | "clawbot" | "schedules" | "jira" | "proxy" | "shortcuts" | "extensions" | "files" | "queryAudit";
 
 const CATEGORIES: { value: SettingsCategory; label: string; subtitle: string; icon: React.ElementType }[] = [
@@ -46,7 +52,7 @@ const CATEGORIES: { value: SettingsCategory; label: string; subtitle: string; ic
 ];
 
 export function SettingsTab() {
-  const { theme, setTheme, deviceName, setDeviceName, version, jiraEnabled, setJiraEnabled, tabWrap, toggleTabWrap, editorTabStyle, setEditorTabStyle } = useSettingsStore(useShallow((s) => ({ theme: s.themeMode, setTheme: s.setThemeMode, deviceName: s.deviceName, setDeviceName: s.setDeviceName, version: s.version, jiraEnabled: s.jiraEnabled, setJiraEnabled: s.setJiraEnabled, tabWrap: s.tabWrap, toggleTabWrap: s.toggleTabWrap, editorTabStyle: s.editorTabStyle, setEditorTabStyle: s.setEditorTabStyle })));
+  const { theme, setTheme, deviceName, setDeviceName, version, jiraEnabled, setJiraEnabled, tabWrap, toggleTabWrap, editorTabStyle, setEditorTabStyle, explorerSkin, setExplorerSkin } = useSettingsStore(useShallow((s) => ({ theme: s.themeMode, setTheme: s.setThemeMode, deviceName: s.deviceName, setDeviceName: s.setDeviceName, version: s.version, jiraEnabled: s.jiraEnabled, setJiraEnabled: s.setJiraEnabled, tabWrap: s.tabWrap, toggleTabWrap: s.toggleTabWrap, editorTabStyle: s.editorTabStyle, setEditorTabStyle: s.setEditorTabStyle, explorerSkin: s.explorerSkin, setExplorerSkin: s.setExplorerSkin })));
   const [activeCategory, setActiveCategory] = useState<SettingsCategory | null>(null);
   const [nameInput, setNameInput] = useState(deviceName ?? "");
   const [nameSaving, setNameSaving] = useState(false);
@@ -223,6 +229,27 @@ export function SettingsTab() {
             </div>
           </section>
 
+          {/* Explorer Skin — chrome the OS File Explorer window wears; Auto follows platform */}
+          <section className="space-y-2">
+            <h3 className="text-xs font-medium text-muted-foreground">Explorer Skin</h3>
+            <div className="flex gap-1.5">
+              {EXPLORER_SKIN_OPTIONS.map((opt) => (
+                <Button
+                  key={opt.value}
+                  variant={explorerSkin === opt.value ? "default" : "outline"}
+                  size="sm"
+                  onClick={() => setExplorerSkin(opt.value)}
+                  className={cn(
+                    "flex-1 text-xs h-8 cursor-pointer",
+                    explorerSkin === opt.value && "ring-2 ring-primary",
+                  )}
+                >
+                  {opt.label}
+                </Button>
+              ))}
+            </div>
+          </section>
+
           <Separator />
 
           {/* Category navigation list */}

package/src/web/components/sqlite/sqlite-viewer.tsx

@@ -33,7 +33,10 @@ export function SqliteViewer({ metadata }: SqliteViewerProps) {
     );
   }
 
-  if (!filePath || !projectName) {
+  // A database opened from a file-explorer window has no project; its absolute path is
+  // enough for the host filesystem SQLite routes, so only a missing path is fatal.
+  const isExternalPath = !!filePath && !projectName && /^(\/|[A-Za-z]:[/\\])/.test(filePath);
+  if (!filePath || (!projectName && !isExternalPath)) {
     return (
       <div className="flex items-center justify-center h-full text-text-secondary text-sm">
         <Database className="size-5 mr-2" /> No database file selected.
@@ -43,7 +46,7 @@ export function SqliteViewer({ metadata }: SqliteViewerProps) {
 
   return (
     <SqliteViewerInner
-      projectName={projectName}
+      projectName={projectName ?? ""}
       dbPath={filePath}
       queryPanelOpen={queryPanelOpen}
       onToggleQueryPanel={() => setQueryPanelOpen((v) => !v)}

package/src/web/components/sqlite/use-sqlite.ts

@@ -19,9 +19,14 @@ export function useSqlite(projectName: string, dbPath: string, connectionId?: nu
   const [queryError, setQueryError] = useState<string | null>(null);
   const [queryLoading, setQueryLoading] = useState(false);
 
-  // When connectionId present, use unified API; otherwise use project-scoped API
+  // Three sources, in order of specificity:
+  //  - a saved connection      → the unified /api/db routes, no path in the query
+  //  - a file inside a project → the project-scoped route, path relative to the project
+  //  - an absolute path with no project (opened from a file-explorer window)
+  //                            → the host filesystem route, path absolute
   const unifiedBase = connectionId ? `/api/db/connections/${connectionId}` : null;
-  const base = unifiedBase ?? `${projectUrl(projectName)}/sqlite`;
+  const isExternalPath = !connectionId && !projectName && /^(\/|[A-Za-z]:[/\\])/.test(dbPath);
+  const base = unifiedBase ?? (isExternalPath ? "/api/fs/sqlite" : `${projectUrl(projectName)}/sqlite`);
   const qs = unifiedBase ? "" : `path=${encodeURIComponent(dbPath)}`;
 
   // Fetch tables on mount — use cache when connectionId (sidebar handles live sync)