@hienlh/ppm 0.18.1 → 0.18.3

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

@@ -0,0 +1,96 @@
+/**
+ * Turns a dropped/picked file batch into `PUT /api/fs/upload` calls, streamed through
+ * `uploadFileXhr` with bounded concurrency. Mirrors `transfer()` in
+ * `explorer-actions-clipboard.ts`: the same collision prompt (`ctx.resolve`), the same
+ * trash-first "Replace" via the 409 `EEXIST` contract, and a `fsChanged` refresh once the
+ * batch settles — drag-to-upload and the picker both funnel through this one function.
+ */
+
+import { toast } from "sonner";
+import { FsError } from "@/lib/fs-api";
+import { uploadFileXhr } from "@/lib/fs-upload-xhr";
+import { dirnameOf, joinPath } from "../format-file-meta";
+import { fsChanged } from "../explorer-store";
+import type { DroppedEntry } from "../upload/collect-dropped-entries";
+import { runUploadQueue, type UploadJob } from "../upload/upload-queue";
+import type { TransferContext } from "./explorer-actions-clipboard";
+import { freeName } from "./explorer-actions-transfer-helpers";
+
+/** Uploads sitting behind a collision prompt or a slow connection should not all queue up
+ *  behind one giant file — three in flight matches the plan's chosen concurrency. */
+const CONCURRENCY = 3;
+
+function nameOf(relativePath: string): string {
+  return relativePath.split("/").pop() ?? relativePath;
+}
+
+/** Turns a "/"-joined relative path (as `collectDroppedEntries` produces) into a host path
+ *  under `dstDir`, using the destination's own separator. */
+function destinationFor(dstDir: string, relativePath: string, sep: string): string {
+  return joinPath(dstDir, relativePath.split("/").join(sep), sep);
+}
+
+async function uploadResolvingCollisions(
+  entry: DroppedEntry,
+  dstDir: string,
+  sep: string,
+  ctx: TransferContext,
+  onProgress: (bytesLoaded: number) => void,
+): Promise<void> {
+  const destination = destinationFor(dstDir, entry.relativePath, sep);
+  try {
+    await uploadFileXhr(destination, entry.file, false, (p) => onProgress(p.loaded));
+    return;
+  } catch (e) {
+    if (!(e instanceof FsError) || e.code !== "EEXIST") throw e;
+  }
+
+  const name = nameOf(entry.relativePath);
+  const choice = await ctx.resolve({ name, destination });
+  if (choice === "skip") return;
+  if (choice === "keep-both") {
+    const containingDir = dirnameOf(destination, sep);
+    const alternative = await freeName(containingDir, name, sep);
+    if (!alternative) throw new Error("No free name available");
+    await uploadFileXhr(joinPath(containingDir, alternative, sep), entry.file, false, (p) => onProgress(p.loaded));
+    return;
+  }
+  // Replace: the server upload route itself makes the overwrite atomic (tmp file + rename),
+  // so unlike the copy/move `transfer()` there is no separate trash-then-write step here.
+  await uploadFileXhr(destination, entry.file, true, (p) => onProgress(p.loaded));
+}
+
+function uploadLabel(entries: DroppedEntry[], fraction: number): string {
+  const label = entries.length === 1 ? entries[0]!.file.name : `${entries.length} files`;
+  return `Uploading ${label}… ${Math.round(fraction * 100)}%`;
+}
+
+export async function uploadEntries(
+  entries: DroppedEntry[],
+  dstDir: string,
+  sep: string,
+  ctx: TransferContext,
+): Promise<void> {
+  if (entries.length === 0) return;
+
+  const toastId = toast.loading(uploadLabel(entries, 0));
+  const jobs: UploadJob<void>[] = entries.map((entry, index) => ({
+    id: String(index),
+    size: entry.file.size,
+    run: (onProgress) => uploadResolvingCollisions(entry, dstDir, sep, ctx, onProgress),
+  }));
+
+  const results = await runUploadQueue(jobs, CONCURRENCY, (progress) => {
+    const fraction = progress.bytesTotal > 0 ? progress.bytesLoaded / progress.bytesTotal : 0;
+    toast.loading(uploadLabel(entries, fraction), { id: toastId });
+  });
+
+  fsChanged(dstDir);
+  const succeeded = results.filter((r) => r.ok).length;
+  const failed = results.length - succeeded;
+  if (failed === 0) {
+    toast.success(`Uploaded ${succeeded} item${succeeded === 1 ? "" : "s"}`, { id: toastId });
+  } else {
+    toast.error(`Uploaded ${succeeded}, ${failed} failed`, { id: toastId });
+  }
+}

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

@@ -7,9 +7,10 @@
  * plain async functions with no React inside them.
  */
 
-import { useCallback, useMemo, useRef, useState } from "react";
+import { useCallback, useMemo, useRef, useState, type ReactNode } from "react";
 import { toast } from "sonner";
 import type { FsEntry } from "@/lib/fs-api";
+import { openTerminalAt } from "@/lib/open-terminal-at";
 import { useExplorerPinsStore } from "../explorer-pins-store";
 import { useExplorerStore, type ExplorerSlice } from "../explorer-store";
 import type { ExplorerNavigation } from "../use-explorer-navigation";
@@ -19,10 +20,14 @@ import {
   type CollisionChoice, type CollisionRequest,
 } from "./explorer-actions-clipboard";
 import { createEntry, deleteEntries, renameEntry, validateEntryName } from "./explorer-actions-mutate";
+import { useExplorerUploadActions } from "./use-explorer-upload-actions";
+import type { DroppedEntry } from "../upload/collect-dropped-entries";
 
 export interface ExplorerActions {
   openEntry(entry: FsEntry): void;
   openInNewWindow(entry: FsEntry): void;
+  /** Shell in the dock starting in the given directory (or the file's parent). */
+  openInTerminal(entry?: FsEntry): void;
   cut(entries: FsEntry[]): void;
   copy(entries: FsEntry[]): void;
   paste(targetDir?: string): void;
@@ -39,6 +44,11 @@ export interface ExplorerActions {
   showProperties(entry: FsEntry): void;
   /** Move or copy arbitrary paths into a directory — also the drag-and-drop entry point. */
   transferInto(paths: string[], dstDir: string, op: "copy" | "move"): Promise<void>;
+  /** Upload dropped/picked OS files into a directory — the upload counterpart of `transferInto`. */
+  uploadInto(entries: DroppedEntry[], dstDir: string): Promise<void>;
+  openUploadPicker(): void;
+  openUploadFolderPicker(): void;
+  supportsFolderUpload: boolean;
 }
 
 export interface ExplorerDialogState {
@@ -51,6 +61,8 @@ export interface ExplorerDialogState {
   closeDelete(): void;
   runPermanentDelete(): void;
   closeProperties(): void;
+  /** Hidden upload `<input>`s — render once per window. */
+  uploadInputs: ReactNode;
 }
 
 export function useExplorerActions(
@@ -99,6 +111,7 @@ export function useExplorerActions(
   );
 
   const currentDir = () => sliceRef.current?.path ?? "";
+  const upload = useExplorerUploadActions(context, currentDir);
 
   const actions = useMemo<ExplorerActions>(() => ({
     openEntry: (entry) => {
@@ -108,6 +121,9 @@ export function useExplorerActions(
     openInNewWindow: (entry) => {
       openPathInNewWindow(entry.type === "directory" ? entry.path : (sliceRef.current?.path ?? entry.path));
     },
+    openInTerminal: (entry) => {
+      openTerminalAt(entry?.type === "directory" ? entry.path : currentDir());
+    },
     cut: (entries) => setClipboardPaths(entries.map((e) => e.path), "cut"),
     copy: (entries) => setClipboardPaths(entries.map((e) => e.path), "copy"),
     paste: (targetDir) => void pasteInto(targetDir ?? currentDir(), context),
@@ -120,6 +136,10 @@ export function useExplorerActions(
         toast.success(`${verb} ${result.succeeded} item${result.succeeded === 1 ? "" : "s"}`);
       }
     },
+    uploadInto: upload.uploadInto,
+    openUploadPicker: upload.openUploadPicker,
+    openUploadFolderPicker: upload.openUploadFolderPicker,
+    supportsFolderUpload: upload.supportsFolderUpload,
 
     startRename: (entry) => {
       setInlineError(null);
@@ -180,7 +200,7 @@ export function useExplorerActions(
       else pins.pin({ path, name });
     },
     showProperties: (entry) => setProperties(entry),
-  }), [windowId, patch, nav, context, platform]);
+  }), [windowId, patch, nav, context, platform, upload]);
 
   const runPermanentDelete = useCallback(() => {
     const target = pendingDelete;
@@ -200,6 +220,7 @@ export function useExplorerActions(
       closeDelete: () => setPendingDelete(null),
       runPermanentDelete,
       closeProperties: () => setProperties(null),
+      uploadInputs: upload.uploadInputs,
     },
   };
 }

package/src/web/components/os-explorer/actions/use-explorer-upload-actions.tsx

@@ -0,0 +1,41 @@
+/**
+ * Upload wiring for one explorer window: the hidden file/folder pickers and the action that
+ * turns a drop or a pick into `uploadEntries` calls. Split out of `use-explorer-actions.ts` to
+ * keep that file under the line cap — uploads are one more interruption-owning concern
+ * alongside collision/delete/properties, not a different architecture.
+ */
+
+import { useCallback, type ReactNode } from "react";
+import type { DroppedEntry } from "../upload/collect-dropped-entries";
+import { useUploadPicker } from "../upload/use-upload-picker";
+import type { TransferContext } from "./explorer-actions-clipboard";
+import { uploadEntries } from "./explorer-actions-upload";
+
+export interface ExplorerUploadActions {
+  uploadInto(entries: DroppedEntry[], dstDir: string): Promise<void>;
+  openUploadPicker(): void;
+  openUploadFolderPicker(): void;
+  supportsFolderUpload: boolean;
+  /** Render once per window — the hidden `<input>` elements the pickers click. */
+  uploadInputs: ReactNode;
+}
+
+export function useExplorerUploadActions(
+  context: TransferContext,
+  currentDir: () => string,
+): ExplorerUploadActions {
+  const uploadInto = useCallback(
+    (entries: DroppedEntry[], dstDir: string) => uploadEntries(entries, dstDir, context.sep, context),
+    [context],
+  );
+
+  const picker = useUploadPicker((entries) => void uploadInto(entries, currentDir()));
+
+  return {
+    uploadInto,
+    openUploadPicker: picker.openFilePicker,
+    openUploadFolderPicker: picker.openFolderPicker,
+    supportsFolderUpload: picker.supportsFolderPicker,
+    uploadInputs: picker.inputs,
+  };
+}

package/src/web/components/os-explorer/dnd/use-drop-transfer.tsx

@@ -10,12 +10,16 @@
 
 import { useEffect, useMemo, useRef, useState, type ReactNode } from "react";
 import type { CollisionChoice, CollisionRequest, TransferContext } from "../actions/explorer-actions-clipboard";
+import { uploadEntries } from "../actions/explorer-actions-upload";
 import type { ExplorerDialogState } from "../actions/use-explorer-actions";
 import { ExplorerDialogs } from "../explorer-dialogs";
+import type { DroppedEntry } from "../upload/collect-dropped-entries";
 import { transferRunner, type DropRunner } from "./entry-drop-executor";
 
 export interface DropTransfer {
   run: DropRunner;
+  /** Upload dropped OS files into a directory, through the same collision prompt as `run`. */
+  uploadRun: (entries: DroppedEntry[], dstDir: string) => Promise<void>;
   /** Render this somewhere inside the surface — it is empty until a prompt is raised. */
   prompts: ReactNode;
 }
@@ -60,6 +64,10 @@ export function useDropTransfer(sep: string, platform?: string): DropTransfer {
   );
 
   const run = useMemo<DropRunner>(() => transferRunner(context), [context]);
+  const uploadRun = useMemo(
+    () => (entries: DroppedEntry[], dstDir: string) => uploadEntries(entries, dstDir, sepRef.current, context),
+    [context],
+  );
 
   const prompts = (
     <ExplorerDialogs
@@ -72,11 +80,12 @@ export function useDropTransfer(sep: string, platform?: string): DropTransfer {
         closeDelete: () => {},
         runPermanentDelete: () => {},
         closeProperties: () => {},
+        uploadInputs: null,
       }}
       platform={platform}
       sep={sep}
     />
   );
 
-  return { run, prompts };
+  return { run, uploadRun, prompts };
 }

package/src/web/components/os-explorer/dnd/use-entry-row-dnd.ts

@@ -10,6 +10,7 @@
 
 import { useMemo, type DragEvent } from "react";
 import type { FsEntry } from "@/lib/fs-api";
+import type { DroppedEntry } from "../upload/collect-dropped-entries";
 import type { DropRunner } from "./entry-drop-executor";
 import type { EntryDragOrigin } from "./entry-drag-payload";
 import { useEntryDragSource } from "./use-entry-drag-source";
@@ -36,6 +37,9 @@ export interface EntryRowDndOptions {
   projectName?: string;
   extraData?: Record<string, string>;
   onDragStarted?(): void;
+  /** Also accept a native OS file drag onto this row when it is a directory. Omitted where
+   *  the caller has no upload destination (e.g. a surface with no window action set). */
+  onFiles?: (entries: DroppedEntry[], targetDir: string) => void;
 }
 
 export interface EntryRowDnd {
@@ -45,7 +49,9 @@ export interface EntryRowDnd {
 }
 
 export function useEntryRowDnd(options: EntryRowDndOptions): EntryRowDnd {
-  const { entry, dragPaths, run, springLoad, origin = "explorer", projectName, extraData, onDragStarted } = options;
+  const {
+    entry, dragPaths, run, springLoad, origin = "explorer", projectName, extraData, onDragStarted, onFiles,
+  } = options;
 
   const source = useEntryDragSource({ paths: dragPaths, origin, projectName, extraData, onDragStarted });
 
@@ -55,6 +61,7 @@ export function useEntryRowDnd(options: EntryRowDndOptions): EntryRowDnd {
     targetDir: entry.type === "directory" ? entry.path : null,
     run,
     springLoad: entry.type === "directory" ? springLoad : undefined,
+    onFiles,
   });
 
   const props = useMemo<EntryRowDndProps>(

package/src/web/components/os-explorer/dnd/use-external-file-drop.ts

@@ -0,0 +1,84 @@
+/**
+ * Drop target for a native OS `Files` drag — the upload counterpart to `useEntryDropTarget`
+ * (PPM's own entry drags). The two never overlap: an entry drag carries `ENTRY_DRAG_MIME` but
+ * never `Files` (see `use-entry-drag-source.ts`), so a caller wires both hooks' handlers onto
+ * the same element — see `usePathDropTarget` — and whichever drag kind is actually happening
+ * is the only one that ever calls `preventDefault`.
+ *
+ * `isExternalFileDrag` is the project tree's own check (`use-tree-row-dnd.ts`), reused rather
+ * than redeclared: it excludes the tree's legacy single-path MIME, which an entry drag never
+ * carries either, so the same test is exactly as correct here.
+ */
+
+import { useCallback, useRef, useState, type DragEvent } from "react";
+import { isExternalFileDrag } from "@/components/explorer/use-tree-row-dnd";
+import { collectDroppedEntries, type DroppedEntry } from "../upload/collect-dropped-entries";
+import type { EntryDropTargetResult } from "./use-entry-drop-target";
+
+export interface ExternalFileDropOptions {
+  /** Directory a drop uploads into; null disables the target. */
+  targetDir: string | null;
+  onFiles(entries: DroppedEntry[], targetDir: string): void;
+  disabled?: boolean;
+}
+
+export function useExternalFileDrop(options: ExternalFileDropOptions): EntryDropTargetResult {
+  const { targetDir, onFiles, disabled } = options;
+  const [isOver, setIsOver] = useState(false);
+  // Nested children fire their own enter/leave pairs; only a balanced count means "left".
+  const depth = useRef(0);
+
+  const reset = useCallback(() => {
+    depth.current = 0;
+    setIsOver(false);
+  }, []);
+
+  const applies = useCallback(
+    (event: DragEvent) => !disabled && targetDir != null && isExternalFileDrag(event),
+    [disabled, targetDir],
+  );
+
+  const onDragEnter = useCallback(
+    (event: DragEvent) => {
+      if (!applies(event)) return;
+      event.preventDefault();
+      event.stopPropagation();
+      depth.current++;
+      setIsOver(true);
+    },
+    [applies],
+  );
+
+  const onDragOver = useCallback(
+    (event: DragEvent) => {
+      if (!applies(event)) return;
+      event.preventDefault();
+      event.stopPropagation();
+      event.dataTransfer.dropEffect = "copy";
+    },
+    [applies],
+  );
+
+  const onDragLeave = useCallback((event: DragEvent) => {
+    if (depth.current === 0) return;
+    event.stopPropagation();
+    depth.current--;
+    if (depth.current === 0) setIsOver(false);
+  }, []);
+
+  const onDrop = useCallback(
+    (event: DragEvent) => {
+      if (!applies(event) || targetDir == null) return;
+      event.preventDefault();
+      event.stopPropagation();
+      const dataTransfer = event.dataTransfer;
+      reset();
+      void collectDroppedEntries(dataTransfer).then((entries) => {
+        if (entries.length > 0) onFiles(entries, targetDir);
+      });
+    },
+    [applies, targetDir, onFiles, reset],
+  );
+
+  return { isOver, handlers: { onDragEnter, onDragOver, onDragLeave, onDrop } };
+}

package/src/web/components/os-explorer/dnd/use-path-drop-target.ts

@@ -1,12 +1,19 @@
 /**
  * Drop target for a surface that already knows its destination directory and has no drag
  * source of its own: a view background, a sidebar place, a breadcrumb crumb, the tree root.
+ *
+ * When `onFiles` is supplied this also accepts a native OS `Files` drag on the same element —
+ * the drag-to-upload entry point. The two hooks underneath are mutually exclusive by MIME
+ * type (see `use-external-file-drop.ts`), so merging their handlers is safe: whichever drag
+ * kind is actually happening is the only one that ever calls `preventDefault`.
  */
 
-import { useCallback } from "react";
+import { useCallback, type DragEvent } from "react";
 import { executeEntryDrop, type DropRunner } from "./entry-drop-executor";
 import type { DropOperation, EntryDragPayload } from "./entry-drag-payload";
 import { useEntryDropTarget, type EntryDropTargetResult } from "./use-entry-drop-target";
+import { useExternalFileDrop } from "./use-external-file-drop";
+import type { DroppedEntry } from "../upload/collect-dropped-entries";
 
 export interface PathDropTargetOptions {
   targetDir: string | null;
@@ -14,10 +21,15 @@ export interface PathDropTargetOptions {
   /** Opens this destination after a rest — the project tree and Column view use it. */
   springLoad?: () => void;
   disabled?: boolean;
+  /** Also accept a native OS file drag on this same target. Omitted where the caller has no
+   *  upload destination context to hand the dropped files to. */
+  onFiles?: (entries: DroppedEntry[], targetDir: string) => void;
 }
 
+function noopFiles(): void {}
+
 export function usePathDropTarget(options: PathDropTargetOptions): EntryDropTargetResult {
-  const { targetDir, run, springLoad, disabled } = options;
+  const { targetDir, run, springLoad, disabled, onFiles } = options;
 
   const onDropEntries = useCallback(
     (payload: EntryDragPayload, op: DropOperation, dstDir: string) => {
@@ -26,5 +38,36 @@ export function usePathDropTarget(options: PathDropTargetOptions): EntryDropTarg
     [run],
   );
 
-  return useEntryDropTarget({ targetDir, onDropEntries, springLoad, disabled });
+  const entryDrop = useEntryDropTarget({ targetDir, onDropEntries, springLoad, disabled });
+  // Always called (Rules of Hooks) — `disabled` is what actually turns it off when the
+  // caller has no upload destination for this target.
+  const fileDrop = useExternalFileDrop({
+    targetDir,
+    onFiles: onFiles ?? noopFiles,
+    disabled: disabled || !onFiles,
+  });
+
+  if (!onFiles) return entryDrop;
+
+  return {
+    isOver: entryDrop.isOver || fileDrop.isOver,
+    handlers: {
+      onDragEnter: (event: DragEvent) => {
+        entryDrop.handlers.onDragEnter(event);
+        fileDrop.handlers.onDragEnter(event);
+      },
+      onDragOver: (event: DragEvent) => {
+        entryDrop.handlers.onDragOver(event);
+        fileDrop.handlers.onDragOver(event);
+      },
+      onDragLeave: (event: DragEvent) => {
+        entryDrop.handlers.onDragLeave(event);
+        fileDrop.handlers.onDragLeave(event);
+      },
+      onDrop: (event: DragEvent) => {
+        entryDrop.handlers.onDrop(event);
+        fileDrop.handlers.onDrop(event);
+      },
+    },
+  };
 }

package/src/web/components/os-explorer/explorer-body.tsx

@@ -99,7 +99,7 @@ export function ExplorerBody({ windowId, initialPath, variant = "window" }: Expl
           <MobilePlacesStrip host={host} currentPath={slice.path} onNavigate={nav.go} vocab={skin.vocab} />
         </>
       ) : (
-        <ExplorerToolbar windowId={windowId} slice={slice} nav={nav} />
+        <ExplorerToolbar windowId={windowId} slice={slice} nav={nav} actions={actions} />
       )}
 
       {slice.error && (

package/src/web/components/os-explorer/explorer-context-menu.tsx

@@ -54,6 +54,13 @@ export function ExplorerContextMenu({
         <ContextMenuSeparator />
         <ContextMenuItem disabled={!hasClipboard} onClick={() => actions.paste()}>Paste</ContextMenuItem>
         <ContextMenuSeparator />
+        <ContextMenuItem onClick={() => actions.openUploadPicker()}>Upload Files…</ContextMenuItem>
+        {actions.supportsFolderUpload && (
+          <ContextMenuItem onClick={() => actions.openUploadFolderPicker()}>Upload Folder…</ContextMenuItem>
+        )}
+        <ContextMenuSeparator />
+        <ContextMenuItem onClick={() => actions.openInTerminal()}>Open in Terminal</ContextMenuItem>
+        <ContextMenuSeparator />
         <ContextMenuSub>
           <ContextMenuSubTrigger>Sort by</ContextMenuSubTrigger>
           <ContextMenuSubContent>
@@ -92,6 +99,9 @@ export function ExplorerContextMenu({
           Open in New Window
         </ContextMenuItem>
       )}
+      {onlyDirs && single && (
+        <ContextMenuItem onClick={() => actions.openInTerminal(single)}>Open in Terminal</ContextMenuItem>
+      )}
       <ContextMenuSeparator />
 
       <ContextMenuItem onClick={() => actions.cut(targets)}>Cut{suffix}</ContextMenuItem>

package/src/web/components/os-explorer/explorer-dialogs.tsx

@@ -23,6 +23,8 @@ export function ExplorerDialogs({ dialogs, platform, sep }: ExplorerDialogsProps
 
   return (
     <>
+      {dialogs.uploadInputs}
+
       {collision && (
         <ExplorerModalShell
           open

package/src/web/components/os-explorer/explorer-sidebar.tsx

@@ -14,7 +14,7 @@ import { cn } from "@/lib/utils";
 import { DROP_TARGET_CLASS } from "./dnd/drop-target-style";
 import type { DropRunner } from "./dnd/entry-drop-executor";
 import { usePathDropTarget } from "./dnd/use-path-drop-target";
-import { useDropTransfer } from "./dnd/use-drop-transfer";
+import { useDropTransfer, type DropTransfer } from "./dnd/use-drop-transfer";
 import { useExplorerPinsStore } from "./explorer-pins-store";
 import { FileTypeIcon } from "./icons/file-type-icon";
 import type { SkinVocab } from "./skins/skin-types";
@@ -43,13 +43,14 @@ interface PlaceProps {
   onUnpin?(): void;
   /** Every place is a directory, so a drop always has somewhere valid to land. */
   run: DropRunner;
+  uploadRun: DropTransfer["uploadRun"];
 }
 
-function Place({ label, path, active, icon: Icon, onNavigate, onUnpin, run }: PlaceProps) {
+function Place({ label, path, active, icon: Icon, onNavigate, onUnpin, run, uploadRun }: PlaceProps) {
   // Gated on real pointer coarseness, not a `md:` breakpoint — an iPad is ≥768px but has no
   // mouse, so a breakpoint-only rule was silently dropping the 44px minimum for it.
   const coarse = usePrefersCoarsePointer();
-  const drop = usePathDropTarget({ targetDir: path, run });
+  const drop = usePathDropTarget({ targetDir: path, run, onFiles: uploadRun });
   return (
     <div className="group/place relative flex items-center">
       <button
@@ -112,7 +113,7 @@ export function ExplorerSidebar({ host, currentPath, onNavigate, vocab = DEFAULT
   const isActive = (path: string) => path === currentPath;
   // One drop-transfer context for the whole sidebar — every place lands through the same
   // collision prompt rather than each row owning its own dialog state.
-  const { run, prompts } = useDropTransfer(host?.sep ?? "/", host?.platform);
+  const { run, uploadRun, prompts } = useDropTransfer(host?.sep ?? "/", host?.platform);
 
   return (
     <aside
@@ -132,6 +133,7 @@ export function ExplorerSidebar({ host, currentPath, onNavigate, vocab = DEFAULT
               onNavigate={onNavigate}
               onUnpin={() => unpin(pin.path)}
               run={run}
+              uploadRun={uploadRun}
             />
           ))}
         </Section>
@@ -148,6 +150,7 @@ export function ExplorerSidebar({ host, currentPath, onNavigate, vocab = DEFAULT
               active={isActive(entry.path)}
               onNavigate={onNavigate}
               run={run}
+              uploadRun={uploadRun}
             />
           ))}
         </Section>
@@ -155,7 +158,7 @@ export function ExplorerSidebar({ host, currentPath, onNavigate, vocab = DEFAULT
 
       {host && (
         <Section title={vocab.known}>
-          <Place label={vocab.home} path={host.homedir} icon={FolderPlaceIcon} active={isActive(host.homedir)} onNavigate={onNavigate} run={run} />
+          <Place label={vocab.home} path={host.homedir} icon={FolderPlaceIcon} active={isActive(host.homedir)} onNavigate={onNavigate} run={run} uploadRun={uploadRun} />
           {host.knownFolders.map((folder) => (
             <Place
               key={folder.path}
@@ -165,6 +168,7 @@ export function ExplorerSidebar({ host, currentPath, onNavigate, vocab = DEFAULT
               active={isActive(folder.path)}
               onNavigate={onNavigate}
               run={run}
+              uploadRun={uploadRun}
             />
           ))}
         </Section>
@@ -181,6 +185,7 @@ export function ExplorerSidebar({ host, currentPath, onNavigate, vocab = DEFAULT
               active={isActive(drive.path)}
               onNavigate={onNavigate}
               run={run}
+              uploadRun={uploadRun}
             />
           ))}
         </Section>

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

@@ -9,9 +9,14 @@
 
 import { useEffect, useState } from "react";
 import {
-  ArrowLeft, ArrowRight, ArrowUp, Columns3, Eye, EyeOff, LayoutGrid, List, PencilLine, RefreshCw, Search, X,
+  ArrowLeft, ArrowRight, ArrowUp, Columns3, Eye, EyeOff, LayoutGrid, List, PencilLine, RefreshCw, Search,
+  Upload, X,
 } from "lucide-react";
+import {
+  DropdownMenu, DropdownMenuContent, DropdownMenuItem, DropdownMenuTrigger,
+} from "@/components/ui/dropdown-menu";
 import { cn } from "@/lib/utils";
+import type { ExplorerActions } from "./actions/use-explorer-actions";
 import { ExplorerBreadcrumb } from "./explorer-breadcrumb";
 import { ExplorerSortMenu } from "./explorer-sort-menu";
 import { useExplorerStore, type ExplorerSlice, type ViewMode } from "./explorer-store";
@@ -27,9 +32,10 @@ export interface ExplorerToolbarProps {
   windowId: string;
   slice: ExplorerSlice;
   nav: ExplorerNavigation;
+  actions: ExplorerActions;
 }
 
-export function ExplorerToolbar({ windowId, slice, nav }: ExplorerToolbarProps) {
+export function ExplorerToolbar({ windowId, slice, nav, actions }: ExplorerToolbarProps) {
   const patch = useExplorerStore((s) => s.patch);
   const showHidden = useExplorerStore((s) => s.showHidden);
   const viewMode = useExplorerStore((s) => s.viewMode);
@@ -124,6 +130,30 @@ export function ExplorerToolbar({ windowId, slice, nav }: ExplorerToolbarProps)
 
       <ExplorerSortMenu coarse={coarse} />
 
+      {actions.supportsFolderUpload ? (
+        <DropdownMenu>
+          <DropdownMenuTrigger asChild>
+            <button type="button" aria-label="Upload" title="Upload" className={buttonClass(coarse)}>
+              <Upload className="size-4" />
+            </button>
+          </DropdownMenuTrigger>
+          <DropdownMenuContent align="end">
+            <DropdownMenuItem onClick={() => actions.openUploadPicker()}>Upload Files…</DropdownMenuItem>
+            <DropdownMenuItem onClick={() => actions.openUploadFolderPicker()}>Upload Folder…</DropdownMenuItem>
+          </DropdownMenuContent>
+        </DropdownMenu>
+      ) : (
+        <button
+          type="button"
+          aria-label="Upload"
+          title="Upload"
+          onClick={() => actions.openUploadPicker()}
+          className={buttonClass(coarse)}
+        >
+          <Upload className="size-4" />
+        </button>
+      )}
+
       <button
         type="button"
         aria-label={showHidden ? "Hide hidden files" : "Show hidden files"}

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

@@ -8,7 +8,8 @@
 
 import { useState } from "react";
 import {
-  ArrowLeft, Check, ClipboardPaste, Copy, Download, FilePlus, FolderPlus, Info, MoreHorizontal, Plus, Scissors, Trash2, X,
+  ArrowLeft, Check, ClipboardPaste, Copy, Download, FilePlus, FolderPlus, Info, MoreHorizontal, Plus, Scissors,
+  Trash2, Upload, X,
 } from "lucide-react";
 import type { FsEntry } from "@/lib/fs-api";
 import { BottomSheet, BottomSheetItem } from "@/components/ui/mobile-bottom-sheet";
@@ -94,6 +95,9 @@ export function MobileBottomToolbar({ slice, nav, actions, entries, hasClipboard
         <BottomSheetItem onClick={() => actions.startCreate("new-folder")}>
           <FolderPlus className="size-4" /> New Folder
         </BottomSheetItem>
+        <BottomSheetItem onClick={() => { setNewOpen(false); actions.openUploadPicker(); }}>
+          <Upload className="size-4" /> Upload Files…
+        </BottomSheetItem>
       </BottomSheet>
 
       <MobileMoreSheet open={moreOpen} onClose={() => setMoreOpen(false)} slice={slice} actions={actions} entries={entries} />