@hienlh/ppm 0.17.57 → 0.18.0

package/src/web/components/floating-window/window-persistence.ts

@@ -0,0 +1,104 @@
+/**
+ * Manual localStorage persistence for floating windows.
+ *
+ * Hand-rolled instead of zustand's `persist` because the saved rects must be re-clamped
+ * against the *current* layer size on load (a rect saved on a 4K screen is off-screen on a
+ * laptop), and because only gesture-end commits should hit storage, not every drag frame.
+ */
+
+import { clampRect, type Bounds, type Rect } from "./window-geometry";
+import type { WindowKind, WindowRuntimeState, WindowVisualState } from "./window-store-types";
+
+const STORAGE_KEY = "ppm-windows";
+
+/** Only JSON-safe payloads survive a reload — anything else is dropped with the window. */
+export interface PersistedWindow {
+  id: string;
+  kind: WindowKind;
+  rect: Rect;
+  state: WindowVisualState;
+  payload?: Record<string, unknown>;
+}
+
+const KINDS: WindowKind[] = ["explorer"];
+const STATES: WindowVisualState[] = ["normal", "maximized", "minimized"];
+
+function isRect(v: unknown): v is Rect {
+  if (!v || typeof v !== "object") return false;
+  const r = v as Record<string, unknown>;
+  return (["x", "y", "w", "h"] as const).every((k) => typeof r[k] === "number" && Number.isFinite(r[k]));
+}
+
+function isSerialisable(payload: unknown): payload is Record<string, unknown> | undefined {
+  if (payload === undefined) return true;
+  if (!payload || typeof payload !== "object" || Array.isArray(payload)) return false;
+  try {
+    JSON.stringify(payload);
+    return true;
+  } catch {
+    return false; // cyclic or non-serialisable payload (e.g. a live handle)
+  }
+}
+
+function toPersisted(win: WindowRuntimeState): PersistedWindow | null {
+  if (!isSerialisable(win.payload)) return null;
+  return { id: win.id, kind: win.kind, rect: win.rect, state: win.state, payload: win.payload };
+}
+
+export function saveWindowRects(windows: WindowRuntimeState[]): void {
+  try {
+    // Persisted back-to-front so the restored rank order matches what the user last saw.
+    const ordered = [...windows].sort((a, b) => a.rank - b.rank);
+    const payload = ordered.map(toPersisted).filter((w): w is PersistedWindow => w !== null);
+    if (payload.length === 0) localStorage.removeItem(STORAGE_KEY);
+    else localStorage.setItem(STORAGE_KEY, JSON.stringify(payload));
+  } catch {
+    /* quota exceeded or storage disabled — geometry is cosmetic, never block the UI */
+  }
+}
+
+/** Read persisted windows, dropping anything malformed, and re-clamp to the current layer. */
+export function loadWindowRects(bounds: Bounds): PersistedWindow[] {
+  let raw: string | null = null;
+  try {
+    raw = localStorage.getItem(STORAGE_KEY);
+  } catch {
+    return [];
+  }
+  if (!raw) return [];
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return [];
+  }
+  if (!Array.isArray(parsed)) return [];
+
+  const out: PersistedWindow[] = [];
+  for (const item of parsed) {
+    if (!item || typeof item !== "object") continue;
+    const w = item as Record<string, unknown>;
+    if (typeof w.id !== "string" || !KINDS.includes(w.kind as WindowKind)) continue;
+    if (!isRect(w.rect) || !isSerialisable(w.payload)) continue;
+    const state = STATES.includes(w.state as WindowVisualState)
+      ? (w.state as WindowVisualState)
+      : "normal";
+    out.push({
+      id: w.id,
+      kind: w.kind as WindowKind,
+      rect: clampRect(w.rect, bounds),
+      state,
+      payload: w.payload as Record<string, unknown> | undefined,
+    });
+  }
+  return out;
+}
+
+export function clearWindowRects(): void {
+  try {
+    localStorage.removeItem(STORAGE_KEY);
+  } catch {
+    /* storage disabled */
+  }
+}

package/src/web/components/floating-window/window-resize-handles.tsx

@@ -0,0 +1,81 @@
+/**
+ * The eight invisible grab strips around a window. Corners sit on top of the edges, matching
+ * the hit areas desktop window managers use.
+ *
+ * A window at this size can be reached with a finger — a tablet past the `md` breakpoint gets
+ * the desktop layer — and a 6 px strip is far below any touch target, so the grab areas grow
+ * on coarse pointers. They are transparent, so nothing about the window's look changes.
+ */
+
+import { useMediaQuery } from "@/hooks/use-media-query";
+import { RESIZE_HANDLES, type ResizeHandle } from "./window-geometry";
+
+type HandleBinder = (handle: ResizeHandle) => Record<string, unknown>;
+
+interface HandleSizes {
+  edge: number;
+  corner: number;
+}
+
+const MOUSE_SIZES: HandleSizes = { edge: 6, corner: 12 };
+const TOUCH_SIZES: HandleSizes = { edge: 12, corner: 20 };
+
+const CURSORS: Record<ResizeHandle, string> = {
+  n: "cursor-n-resize",
+  s: "cursor-s-resize",
+  e: "cursor-e-resize",
+  w: "cursor-w-resize",
+  ne: "cursor-ne-resize",
+  nw: "cursor-nw-resize",
+  se: "cursor-se-resize",
+  sw: "cursor-sw-resize",
+};
+
+/**
+ * Absolute placement per handle, expressed in the same units the frame uses. Each strip is
+ * centred on its border, so half of the extra width grows outwards and half inwards — the
+ * window's own border never moves.
+ */
+function styleFor(handle: ResizeHandle, sizes: HandleSizes): React.CSSProperties {
+  const corner = handle.length === 2;
+  const s: React.CSSProperties = { position: "absolute", touchAction: "none", zIndex: 1 };
+  if (handle.includes("n")) s.top = -sizes.edge / 2;
+  if (handle.includes("s")) s.bottom = -sizes.edge / 2;
+  if (handle.includes("w")) s.left = -sizes.edge / 2;
+  if (handle.includes("e")) s.right = -sizes.edge / 2;
+  if (corner) {
+    s.width = sizes.corner;
+    s.height = sizes.corner;
+    return s;
+  }
+  // Edge strips stop short of the corners so the corner handles keep their full hit area.
+  if (handle === "n" || handle === "s") {
+    s.left = sizes.corner;
+    s.right = sizes.corner;
+    s.height = sizes.edge;
+  } else {
+    s.top = sizes.corner;
+    s.bottom = sizes.corner;
+    s.width = sizes.edge;
+  }
+  return s;
+}
+
+export function WindowResizeHandles({ bind }: { bind: HandleBinder }) {
+  const coarsePointer = useMediaQuery("(pointer: coarse)");
+  const sizes = coarsePointer ? TOUCH_SIZES : MOUSE_SIZES;
+  return (
+    <>
+      {RESIZE_HANDLES.map((handle) => (
+        <div
+          key={handle}
+          {...bind(handle)}
+          data-resize-handle={handle}
+          aria-hidden
+          className={CURSORS[handle]}
+          style={styleFor(handle, sizes)}
+        />
+      ))}
+    </>
+  );
+}

package/src/web/components/floating-window/window-store-types.ts

@@ -0,0 +1,20 @@
+/** Shared window types — split out so the store and the persistence layer do not import each other. */
+
+import type { Rect } from "./window-geometry";
+
+/** Content families the layer can host. The registry maps each kind to its body component. */
+export type WindowKind = "explorer";
+
+export type WindowVisualState = "normal" | "maximized" | "minimized";
+
+export interface WindowRuntimeState {
+  id: string;
+  kind: WindowKind;
+  /** Geometry in layer coordinates. While maximized this holds the restore rect. */
+  rect: Rect;
+  /** Dense stacking order, 0 = backmost, renormalised on every focus. */
+  rank: number;
+  state: WindowVisualState;
+  /** Kind-specific, must stay JSON-serialisable to survive a reload. */
+  payload?: Record<string, unknown>;
+}

package/src/web/components/floating-window/window-store.ts

@@ -0,0 +1,192 @@
+/**
+ * Floating window state: geometry, stacking order and lifecycle for the desktop window layer.
+ *
+ * Content-agnostic on purpose — the store knows a `kind` and an opaque payload, the registry
+ * decides what renders inside. Ranks are kept dense (0..n-1) so the inline z-index never
+ * escapes the band reserved below the app's click-away backdrops.
+ */
+
+import { create } from "zustand";
+import {
+  cascadeSpawnRect,
+  clampRect,
+  MAX_WINDOWS,
+  type Bounds,
+  type Rect,
+} from "./window-geometry";
+import { loadWindowRects, saveWindowRects } from "./window-persistence";
+import type { WindowKind, WindowRuntimeState, WindowVisualState } from "./window-store-types";
+
+export type { WindowKind, WindowRuntimeState, WindowVisualState };
+
+/** Fallback layer size used before the container has been measured. */
+const DEFAULT_BOUNDS: Bounds = { w: 1280, h: 800 };
+
+interface WindowStore {
+  windows: Record<string, WindowRuntimeState>;
+  /** Measured size of the layer container; all rects are clamped against it. */
+  bounds: Bounds;
+  /** True once persisted windows have been read, so restore runs exactly once. */
+  restored: boolean;
+
+  open(kind: WindowKind, payload?: Record<string, unknown>, rect?: Rect): string;
+  close(id: string): void;
+  focus(id: string): void;
+  move(id: string, position: { x: number; y: number }): void;
+  resize(id: string, rect: Rect): void;
+  setState(id: string, state: WindowVisualState): void;
+  /** Merge into a window's payload; persisted so a reload restores the latest state. */
+  setPayload(id: string, payload: Record<string, unknown>): void;
+  setBounds(bounds: Bounds): void;
+  /** Re-hydrate persisted windows into the layer (no-op after the first call). */
+  restoreAll(bounds: Bounds): void;
+}
+
+const sortedByRank = (windows: Record<string, WindowRuntimeState>): WindowRuntimeState[] =>
+  Object.values(windows).sort((a, b) => a.rank - b.rank);
+
+/** Rewrite ranks to 0..n-1 in the given order (last = frontmost). */
+function densify(ordered: WindowRuntimeState[]): Record<string, WindowRuntimeState> {
+  const out: Record<string, WindowRuntimeState> = {};
+  ordered.forEach((win, rank) => {
+    out[win.id] = win.rank === rank ? win : { ...win, rank };
+  });
+  return out;
+}
+
+function persist(windows: Record<string, WindowRuntimeState>): void {
+  saveWindowRects(Object.values(windows));
+}
+
+function newId(): string {
+  return `win-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
+}
+
+export const useWindowStore = create<WindowStore>((set, get) => ({
+  windows: {},
+  bounds: DEFAULT_BOUNDS,
+  restored: false,
+
+  open: (kind, payload, rect) => {
+    const { windows, bounds } = get();
+    const ordered = sortedByRank(windows);
+
+    // At the cap the layer would leave its z band, so the oldest window is raised instead
+    // of silently dropping the request.
+    if (ordered.length >= MAX_WINDOWS) {
+      const oldest = ordered[0]!;
+      get().focus(oldest.id);
+      return oldest.id;
+    }
+
+    const id = newId();
+    const spawn = rect ? clampRect(rect, bounds) : cascadeSpawnRect(ordered.map((w) => w.rect), bounds);
+    const next = densify([
+      ...ordered,
+      { id, kind, rect: spawn, rank: ordered.length, state: "normal" as const, payload },
+    ]);
+    set({ windows: next });
+    persist(next);
+    return id;
+  },
+
+  close: (id) => {
+    const { windows } = get();
+    if (!windows[id]) return;
+    const next = densify(sortedByRank(windows).filter((w) => w.id !== id));
+    set({ windows: next });
+    persist(next);
+  },
+
+  focus: (id) => {
+    const { windows } = get();
+    const target = windows[id];
+    if (!target) return;
+    const ordered = sortedByRank(windows);
+    if (ordered[ordered.length - 1]?.id === id) return; // already frontmost
+    const next = densify([...ordered.filter((w) => w.id !== id), target]);
+    set({ windows: next });
+    persist(next); // stacking order is part of the restored layout
+  },
+
+  move: (id, position) => {
+    const { windows, bounds } = get();
+    const win = windows[id];
+    if (!win) return;
+    const rect = clampRect({ ...win.rect, ...position }, bounds);
+    const next = { ...windows, [id]: { ...win, rect } };
+    set({ windows: next });
+    persist(next);
+  },
+
+  resize: (id, rect) => {
+    const { windows, bounds } = get();
+    const win = windows[id];
+    if (!win) return;
+    const next = { ...windows, [id]: { ...win, rect: clampRect(rect, bounds) } };
+    set({ windows: next });
+    persist(next);
+  },
+
+  setState: (id, state) => {
+    const { windows } = get();
+    const win = windows[id];
+    if (!win || win.state === state) return;
+    const next = { ...windows, [id]: { ...win, state } };
+    set({ windows: next });
+    persist(next);
+  },
+
+  setPayload: (id, payload) => {
+    const { windows } = get();
+    const win = windows[id];
+    if (!win) return;
+    const merged = { ...win.payload, ...payload };
+    // Content re-renders on every keystroke in some bodies; skip the write when the
+    // payload is unchanged so persistence is not hit for nothing.
+    const unchanged = Object.entries(merged).every(
+      ([key, value]) => win.payload?.[key] === value,
+    );
+    if (unchanged && Object.keys(merged).length === Object.keys(win.payload ?? {}).length) return;
+    const next = { ...windows, [id]: { ...win, payload: merged } };
+    set({ windows: next });
+    persist(next);
+  },
+
+  setBounds: (bounds) => {
+    const current = get();
+    if (current.bounds.w === bounds.w && current.bounds.h === bounds.h) return;
+    // A shrinking content area (sidebar opened, browser resized) would otherwise strand
+    // windows outside the layer with no way to drag them back.
+    const windows: Record<string, WindowRuntimeState> = {};
+    for (const win of Object.values(current.windows)) {
+      const rect = clampRect(win.rect, bounds);
+      windows[win.id] =
+        rect.x === win.rect.x && rect.y === win.rect.y && rect.w === win.rect.w && rect.h === win.rect.h
+          ? win
+          : { ...win, rect };
+    }
+    set({ bounds, windows });
+  },
+
+  restoreAll: (bounds) => {
+    if (get().restored) return;
+    const saved = loadWindowRects(bounds).slice(0, MAX_WINDOWS);
+    const windows = densify(
+      saved.map((w, rank) => ({
+        id: w.id,
+        kind: w.kind,
+        rect: w.rect,
+        rank,
+        state: w.state,
+        payload: w.payload,
+      })),
+    );
+    set({ bounds, windows, restored: true });
+  },
+}));
+
+/** Windows in paint order (backmost first) — stable identity per store update. */
+export function windowsInRankOrder(windows: Record<string, WindowRuntimeState>): WindowRuntimeState[] {
+  return sortedByRank(windows);
+}

package/src/web/components/layout/command-palette.tsx

@@ -18,7 +18,9 @@ import {
   Plus,
   Columns2,
   Cloud,
+  AppWindow,
 } from "lucide-react";
+import { openExplorer } from "@/components/os-explorer/open-explorer";
 import { useTabStore, type TabType } from "@/stores/tab-store";
 import { useProjectStore } from "@/stores/project-store";
 import { useSettingsStore } from "@/stores/settings-store";
@@ -232,6 +234,14 @@ export function CommandPalette({ open, onClose, initialQuery = "" }: { open: boo
         group: "action",
         shortcut: formatShortcut(getBinding("open-settings")),
       },
+      {
+        id: "open-file-explorer", label: "Open File Explorer", icon: AppWindow, group: "action",
+        keywords: "open file explorer finder browse files folders disk drive window",
+        action: () => {
+          void openExplorer();
+          onClose();
+        },
+      },
     ];
 
     // Append extension-contributed commands (with keybinding shortcuts, respecting user overrides)

package/src/web/components/layout/mobile-drawer.tsx

@@ -1,5 +1,5 @@
 import { useState, useCallback, useEffect, useMemo } from "react";
-import { X, Bug as BugIcon, Cloud } from "lucide-react";
+import { X, Bug as BugIcon, Cloud, FolderTree } from "lucide-react";
 import { useShallow } from "zustand/react/shallow";
 import { useProjectStore } from "@/stores/project-store";
 import { useSettingsStore, type SidebarActiveTab } from "@/stores/settings-store";
@@ -22,6 +22,7 @@ import { UpgradeButton } from "@/components/layout/upgrade-button";
 import { CloudSharePopover } from "@/components/layout/cloud-share-popover";
 import { BottomSheet } from "@/components/ui/mobile-bottom-sheet";
 import { isMobileDevice } from "@/hooks/use-is-mobile";
+import { openExplorer } from "@/components/os-explorer/open-explorer";
 import { cn } from "@/lib/utils";
 
 // Tab ids the mobile drawer can render content for. `search` is desktop-only for now;
@@ -136,10 +137,18 @@ export function MobileDrawer({ isOpen, onClose, initialTab }: MobileDrawerProps)
             onReorder={setSidebarTabOrder}
           />
 
-          {/* Report Bug + Cloud & Share + Version / Upgrade */}
+          {/* Files (OS explorer) + Report Bug + Cloud & Share + Version / Upgrade */}
           <div className="flex items-center justify-between px-4 py-2 border-t border-border text-[11px]">
             <UpgradeButton align="left" />
             <div className="flex items-center gap-3">
+              {/* Not a sidebar tab — the explorer opens as its own full-screen sheet. */}
+              <button
+                onClick={() => { onClose(); void openExplorer(); }}
+                className="flex items-center gap-1 text-[10px] text-text-subtle hover:text-text-secondary transition-colors"
+              >
+                <FolderTree className="size-3" />
+                <span>Files</span>
+              </button>
               <button
                 onClick={() => setCloudOpen(true)}
                 className="flex items-center gap-1 text-[10px] text-text-subtle hover:text-text-secondary transition-colors"

package/src/web/components/layout/nav-section-rail.tsx

@@ -1,6 +1,7 @@
 import { useState, useRef, useEffect, useMemo, memo } from "react";
 import { createPortal } from "react-dom";
-import { Settings, Bug, Cloud } from "lucide-react";
+import { Settings, Bug, Cloud, FolderTree } from "lucide-react";
+import { openExplorer } from "@/components/os-explorer/open-explorer";
 import { useSettingsStore, type SidebarActiveTab } from "@/stores/settings-store";
 import { getAvailableTabs } from "@/lib/sidebar-tabs/tab-registry";
 import { resolveTabOrder } from "@/lib/sidebar-tabs/resolve-tab-order";
@@ -71,6 +72,9 @@ function FooterUtil({ icon: Icon, label, onClick, active }: {
 }) {
   return (
     <button
+      type="button"
+      aria-label={label}
+      title={label}
       onClick={onClick}
       className={cn(
         "group relative flex items-center justify-center size-8 rounded-[7px] transition-colors shrink-0",
@@ -206,6 +210,8 @@ export const NavSectionRail = memo(function NavSectionRail({ className }: { clas
           </>,
           document.body,
         )}
+        {/* Not a sidebar tab — the explorer lives in its own floating window. */}
+        <FooterUtil icon={FolderTree} label="File Explorer" onClick={() => void openExplorer()} />
         <FooterUtil icon={Bug} label="Report Bug" onClick={handleReportBug} />
         <FooterUtil icon={Settings} label="Settings" active={sidebarActiveTab === "settings"} onClick={() => handleTabClick("settings")} />
       </div>

package/src/web/components/os-explorer/actions/explorer-actions-clipboard.ts

@@ -0,0 +1,186 @@
+/**
+ * Cut / copy / paste against the real filesystem, plus the collision prompt.
+ *
+ * The clipboard itself lives in `file-store` and holds absolute paths, so a cut in the
+ * project tree can be pasted into an explorer window and the other way round. Everything
+ * here goes through `/api/fs/*`; the tree keeps its project-scoped routes for the case
+ * where both ends are inside the same project.
+ */
+
+import { toast } from "sonner";
+import { fsApi, FsError } from "@/lib/fs-api";
+import { useFileStore, type ClipboardState } from "@/stores/file-store";
+import { dirnameOf, errorDescription, joinPath } from "../format-file-meta";
+import { fsChanged } from "../explorer-store";
+import { freeName, runOne } from "./explorer-actions-transfer-helpers";
+
+export type CollisionChoice = "replace" | "keep-both" | "skip";
+
+export interface CollisionRequest {
+  name: string;
+  destination: string;
+}
+
+/** Asks the user what to do about an existing file. Returning "skip" is always safe. */
+export type CollisionResolver = (request: CollisionRequest) => Promise<CollisionChoice>;
+
+export interface TransferContext {
+  sep: string;
+  resolve: CollisionResolver;
+  /**
+   * Asked only when "Replace" cannot trash the existing entry (`NO_TRASH`) — the dialog copy
+   * promises a recoverable trash-first replace, so silently falling back to a permanent
+   * delete would contradict what the user just agreed to. Returning false skips the item.
+   */
+  confirmPermanentOverwrite(name: string): Promise<boolean>;
+}
+
+export interface TransferResult {
+  succeeded: number;
+  skipped: number;
+  failed: number;
+}
+
+/**
+ * Copy or move `sources` into `dstDir`.
+ *
+ * Exported on its own (not just through the clipboard) because drag-and-drop performs the
+ * exact same operation with a different trigger.
+ */
+export async function transfer(
+  sources: string[],
+  dstDir: string,
+  op: "copy" | "move",
+  ctx: TransferContext,
+): Promise<TransferResult> {
+  const result: TransferResult = { succeeded: 0, skipped: 0, failed: 0 };
+  const touched = new Set<string>([dstDir]);
+
+  for (const source of sources) {
+    const name = source.split(/[/\\]/).filter(Boolean).pop() ?? source;
+    const sourceDir = dirnameOf(source, ctx.sep);
+    touched.add(sourceDir);
+    // Moving an entry into the folder it already lives in is a no-op, not an error.
+    if (op === "move" && sourceDir === dstDir) {
+      result.skipped++;
+      continue;
+    }
+
+    let destination = joinPath(dstDir, name, ctx.sep);
+    // A copy into the same folder always collides with itself (destination === source),
+    // which the server refuses as self-nesting (EINVAL), not EEXIST — so the collision
+    // prompt would never open. Every OS instead makes this "name (2)" directly.
+    if (op === "copy" && sourceDir === dstDir) {
+      const alternative = await freeName(dstDir, name, ctx.sep);
+      if (!alternative) {
+        result.failed++;
+        toast.error(`Copy failed: ${name}`, { description: "No free name available" });
+        continue;
+      }
+      destination = joinPath(dstDir, alternative, ctx.sep);
+      try {
+        await runOne(source, destination, op);
+        result.succeeded++;
+      } catch (e) {
+        result.failed++;
+        toast.error(`Copy failed: ${name}`, { description: errorDescription(e) });
+      }
+      continue;
+    }
+
+    try {
+      await runOne(source, destination, op);
+      result.succeeded++;
+      continue;
+    } catch (e) {
+      if (!(e instanceof FsError) || e.code !== "EEXIST") {
+        result.failed++;
+        toast.error(`${op === "copy" ? "Copy" : "Move"} failed: ${name}`, { description: errorDescription(e) });
+        continue;
+      }
+    }
+
+    const choice = await ctx.resolve({ name, destination });
+    if (choice === "skip") {
+      result.skipped++;
+      continue;
+    }
+    if (choice === "keep-both") {
+      try {
+        const alternative = await freeName(dstDir, name, ctx.sep);
+        if (!alternative) throw new Error("No free name available");
+        destination = joinPath(dstDir, alternative, ctx.sep);
+        await runOne(source, destination, op);
+        result.succeeded++;
+      } catch (e) {
+        result.failed++;
+        toast.error(`${op === "copy" ? "Copy" : "Move"} failed: ${name}`, { description: errorDescription(e) });
+      }
+      continue;
+    }
+
+    // Replace: trash the existing entry first so the overwrite stays recoverable, matching
+    // the collision dialog's own copy.
+    try {
+      await fsApi.remove(destination, false);
+    } catch (e) {
+      if (!(e instanceof FsError) || e.code !== "NO_TRASH") {
+        result.failed++;
+        toast.error(`Could not remove existing ${name}`, { description: errorDescription(e) });
+        continue;
+      }
+      // No trash backend on this host — the dialog's "moves to Trash" promise cannot be
+      // kept, so ask explicitly before doing something permanent instead of silently
+      // downgrading to it.
+      const proceed = await ctx.confirmPermanentOverwrite(name);
+      if (!proceed) {
+        result.skipped++;
+        continue;
+      }
+      try {
+        await fsApi.remove(destination, true);
+      } catch (removeErr) {
+        result.failed++;
+        toast.error(`Could not remove existing ${name}`, { description: errorDescription(removeErr) });
+        continue;
+      }
+    }
+    try {
+      await runOne(source, destination, op);
+      result.succeeded++;
+    } catch (e) {
+      result.failed++;
+      // The existing entry is already gone (trashed or deleted above) but the replacement
+      // was never written — say so explicitly rather than a generic "Copy/Move failed".
+      toast.error(`${name} was removed but the replacement could not be written`, { description: errorDescription(e) });
+    }
+  }
+
+  fsChanged(...touched);
+  return result;
+}
+
+/** Put absolute paths on the shared clipboard. `origin` lets the tree keep its own routes. */
+export function setClipboardPaths(
+  paths: string[],
+  operation: "cut" | "copy",
+  origin?: ClipboardState["origin"],
+): void {
+  if (paths.length === 0) return;
+  useFileStore.getState().setClipboard({ paths: [...paths], operation, origin });
+}
+
+/** Paste the shared clipboard into `dstDir`. A cut clipboard is consumed on success. */
+export async function pasteInto(dstDir: string, ctx: TransferContext): Promise<void> {
+  const clipboard = useFileStore.getState().clipboard;
+  if (!clipboard || clipboard.paths.length === 0) return;
+
+  const result = await transfer(clipboard.paths, dstDir, clipboard.operation === "cut" ? "move" : "copy", ctx);
+  if (clipboard.operation === "cut" && result.failed === 0) {
+    useFileStore.getState().setClipboard(null);
+  }
+  if (result.succeeded > 0) {
+    const verb = clipboard.operation === "cut" ? "Moved" : "Copied";
+    toast.success(`${verb} ${result.succeeded} item${result.succeeded === 1 ? "" : "s"}`);
+  }
+}