@hienlh/ppm 0.17.57 → 0.18.1

package/src/web/components/os-explorer/can-open-in-ppm.ts

@@ -0,0 +1,89 @@
+/**
+ * Which files PPM can display, and in which viewer.
+ *
+ * The editor tab picks its renderer from the file extension. Keeping those sets here
+ * (rather than inside the editor component) lets the explorer answer "will a double-click
+ * do anything?" before it opens a tab, and guarantees the two never drift apart: the
+ * editor imports the very same sets.
+ */
+
+/** Image extensions renderable inline */
+export const IMAGE_EXTS = new Set(["png", "jpg", "jpeg", "gif", "webp", "svg", "ico"]);
+/** Video extensions playable inline */
+export const VIDEO_EXTS = new Set(["mp4", "webm", "mov", "ogg", "avi", "mkv"]);
+/** Audio extensions playable inline */
+export const AUDIO_EXTS = new Set(["mp3", "wav", "flac", "aac", "m4a", "wma"]);
+/** SQLite extensions — redirect to sqlite viewer */
+export const SQLITE_EXTS = new Set(["db", "sqlite", "sqlite3"]);
+/** Rendered as formatted markdown (with a raw edit mode) */
+export const MARKDOWN_EXTS = new Set(["md", "mdx"]);
+
+/**
+ * Extensions Monaco opens as editable text. Anything outside this list is assumed
+ * binary: the server would answer with a base64 body and the editor would only be able
+ * to say "cannot be displayed", so the explorer treats it as not openable instead.
+ */
+export const TEXT_EXTS = new Set([
+  "txt", "log", "ini", "cfg", "conf", "env", "properties", "editorconfig",
+  "js", "jsx", "mjs", "cjs", "ts", "tsx", "mts", "cts",
+  "json", "jsonc", "json5", "yaml", "yml", "toml", "xml", "svg",
+  "html", "htm", "css", "scss", "sass", "less", "vue", "svelte", "astro",
+  "py", "rb", "php", "go", "rs", "java", "kt", "kts", "swift", "c", "h",
+  "cpp", "cc", "hpp", "cs", "m", "mm", "scala", "lua", "dart", "r", "pl",
+  "sh", "bash", "zsh", "fish", "ps1", "psm1", "bat", "cmd",
+  "sql", "graphql", "gql", "proto", "prisma", "tf", "tfvars",
+  "dockerfile", "makefile", "gitignore", "gitattributes", "npmrc", "nvmrc",
+  "diff", "patch", "lock", "map", "srt", "vtt",
+]);
+
+/**
+ * Extensionless files that are conventionally plain text. Matched on the whole
+ * (lower-cased) name so `Dockerfile`, `LICENSE` and friends open in the editor.
+ */
+export const TEXT_FILENAMES = new Set([
+  "dockerfile", "makefile", "license", "licence", "readme", "changelog",
+  "authors", "contributing", "notice", "codeowners", "procfile", "brewfile",
+  "gemfile", "rakefile", "vagrantfile", "justfile",
+]);
+
+/** Which viewer an editor tab will render for this file. */
+export type ViewerKind =
+  | "image" | "video" | "audio" | "pdf" | "docx"
+  | "sqlite" | "markdown" | "csv" | "text";
+
+/** Lower-cased extension without the dot; empty string when there is none. */
+export function extensionOf(name: string): string {
+  const base = name.split(/[/\\]/).pop() ?? name;
+  const dot = base.lastIndexOf(".");
+  // A leading dot is part of the name (".gitignore"), not an extension separator.
+  if (dot <= 0) return "";
+  return base.slice(dot + 1).toLowerCase();
+}
+
+/** The viewer PPM would use for this file, or `null` when it cannot show it. */
+export function viewerKindOf(name: string): ViewerKind | null {
+  const base = (name.split(/[/\\]/).pop() ?? name).toLowerCase();
+  const ext = extensionOf(base);
+
+  if (IMAGE_EXTS.has(ext)) return "image";
+  if (VIDEO_EXTS.has(ext)) return "video";
+  if (AUDIO_EXTS.has(ext)) return "audio";
+  if (ext === "pdf") return "pdf";
+  if (ext === "docx") return "docx";
+  if (SQLITE_EXTS.has(ext)) return "sqlite";
+  if (MARKDOWN_EXTS.has(ext)) return "markdown";
+  if (ext === "csv") return "csv";
+  if (TEXT_EXTS.has(ext)) return "text";
+  // Dotfiles ('.gitignore') and extensionless names ('Dockerfile') carry their
+  // type in the name itself.
+  if (!ext) {
+    const stem = base.startsWith(".") ? base.slice(1) : base;
+    if (TEXT_FILENAMES.has(stem) || TEXT_EXTS.has(stem)) return "text";
+  }
+  return null;
+}
+
+/** True when double-clicking the file should open a PPM tab. */
+export function canOpenInPpm(name: string): boolean {
+  return viewerKindOf(name) !== null;
+}

package/src/web/components/os-explorer/dnd/drag-depth-counter.ts

@@ -0,0 +1,36 @@
+/**
+ * A drag-enter/leave depth counter shared by every hand-rolled dragenter/dragleave pair in
+ * the explorer and the project tree: nested children fire their own enter/leave pairs, so
+ * only a balanced count means "actually left". Both `enter` and `leave` take the same
+ * `accepted` gate the caller already computed for its own drag kind — a leave that forgot to
+ * apply that gate the way its own enter did is exactly what drove a counter negative and left
+ * a highlight that could never turn on again (a drag kind that never incremented the counter
+ * still decremented it on its way out).
+ */
+
+export interface DragDepthCounter {
+  current: number;
+}
+
+/** True the moment the count crosses from 0 to 1 — start showing the highlight. */
+export function enterDragDepth(counter: DragDepthCounter, accepted: boolean): boolean {
+  if (!accepted) return false;
+  counter.current++;
+  return counter.current === 1;
+}
+
+/**
+ * True once the count returns to 0 — stop showing the highlight. Clamped at 0 rather than
+ * trusting every caller's enter/leave pairing to be perfectly balanced; going negative would
+ * otherwise require more than one matching `enter` before the count could ever reach 0 again.
+ */
+export function leaveDragDepth(counter: DragDepthCounter, accepted: boolean): boolean {
+  if (!accepted) return false;
+  counter.current = Math.max(0, counter.current - 1);
+  return counter.current === 0;
+}
+
+/** Resets after a drop or cancel, when the browser will not send the matching leave. */
+export function resetDragDepth(counter: DragDepthCounter): void {
+  counter.current = 0;
+}

package/src/web/components/os-explorer/dnd/drag-ghost.ts

@@ -0,0 +1,44 @@
+/**
+ * The image dragged under the cursor: the entry's own name for a single item, a count badge
+ * ("3 items") for a multi-selection.
+ *
+ * The browser snapshots the element synchronously during `setDragImage`, but it must be in
+ * the document and painted at that moment — hence a real, off-screen node rather than a
+ * detached one, removed on the next frame once the snapshot is taken.
+ */
+
+const GHOST_OFFSET_X = 12;
+const GHOST_OFFSET_Y = 12;
+
+export function setEntryDragGhost(dataTransfer: DataTransfer, names: string[]): void {
+  if (typeof document === "undefined" || names.length === 0) return;
+
+  const label = names.length === 1 ? names[0]! : `${names.length} items`;
+  const ghost = document.createElement("div");
+  ghost.textContent = label;
+  // Inline styles, not classes: the node lives outside any themed subtree, and the snapshot
+  // is taken before a stylesheet-driven class could apply.
+  ghost.style.cssText = [
+    "position:fixed",
+    "top:-1000px",
+    "left:-1000px",
+    "padding:4px 10px",
+    "border-radius:6px",
+    "font:500 12px/1.4 var(--x-font, system-ui, sans-serif)",
+    "color:var(--text, #fff)",
+    "background:var(--panel-2, #2a2a2a)",
+    "border:1px solid var(--border, #444)",
+    "box-shadow:0 2px 8px rgba(0,0,0,.35)",
+    "white-space:nowrap",
+    "pointer-events:none",
+  ].join(";");
+  document.body.appendChild(ghost);
+
+  try {
+    dataTransfer.setDragImage(ghost, GHOST_OFFSET_X, GHOST_OFFSET_Y);
+  } catch {
+    /* setDragImage is unsupported in some embedded webviews — the default ghost is fine */
+  }
+  // The snapshot is synchronous, so the node can go as soon as this task yields.
+  requestAnimationFrame(() => ghost.remove());
+}

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

@@ -0,0 +1,46 @@
+/**
+ * The one pure function every drop target asks "may this land here, and as what?".
+ *
+ * It runs twice per drop: on `dragover`, where Chromium exposes only `dataTransfer.types`
+ * and the in-flight payload has to come from the module ref set at `dragstart`, and again
+ * on `drop`, where the real payload is readable. Keeping the rule in one testable place is
+ * what stops the highlight and the actual outcome from disagreeing.
+ */
+
+import {
+  allAlreadyIn, ENTRY_DRAG_MIME, isSelfOrDescendant, resolveDropOperation,
+  type DropOperation, type EntryDragPayload,
+} from "./entry-drag-payload";
+
+export type DropRejection = "not-an-entry-drag" | "no-target" | "self-or-descendant" | "same-directory";
+
+export type DropDecision =
+  | { accept: true; op: DropOperation }
+  | { accept: false; reason: DropRejection };
+
+export interface DropDecisionInput {
+  /** `dataTransfer.types` — the only thing readable during `dragover`. */
+  types: readonly string[];
+  /** Payload from the module ref (dragover) or from `dataTransfer` (drop); null when unknown. */
+  payload: EntryDragPayload | null;
+  /** Directory the drop would write into; null when this element is not a directory. */
+  targetDir: string | null;
+  modifiers: { ctrlKey: boolean; altKey: boolean };
+}
+
+export function decideDrop({ types, payload, targetDir, modifiers }: DropDecisionInput): DropDecision {
+  if (!types.includes(ENTRY_DRAG_MIME)) return { accept: false, reason: "not-an-entry-drag" };
+  if (targetDir == null || targetDir === "") return { accept: false, reason: "no-target" };
+
+  const op = resolveDropOperation(modifiers);
+  // A drag started in another browser tab has the MIME but no readable payload here; accept
+  // optimistically so the target still highlights, and let the drop handler re-check.
+  if (!payload) return { accept: true, op };
+
+  if (isSelfOrDescendant(payload.paths, targetDir)) return { accept: false, reason: "self-or-descendant" };
+  // Copying into the source folder is a legitimate "duplicate"; moving there is a no-op.
+  if (op === "move" && allAlreadyIn(payload.paths, targetDir)) {
+    return { accept: false, reason: "same-directory" };
+  }
+  return { accept: true, op };
+}

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

@@ -0,0 +1,7 @@
+/**
+ * The one highlight every claimed drop target draws — a row, a tile, a sidebar place, a
+ * breadcrumb crumb, a view background or a project-tree node all use this same ring so the
+ * user learns one visual cue instead of a different one per surface. Matches the ring the
+ * project tree's own internal drag-over state already drew before this module existed.
+ */
+export const DROP_TARGET_CLASS = "ring-1 ring-dashed ring-primary bg-primary/10";

package/src/web/components/os-explorer/dnd/entry-drag-payload.ts

@@ -0,0 +1,115 @@
+/**
+ * The payload every PPM entry drag carries, and the pure path guards that decide whether a
+ * drop is allowed at all.
+ *
+ * One MIME type for the whole app: a tab drag (`application/ppm-tab`) and an entry drag are
+ * told apart by `dataTransfer.types` alone, so a tab dropped on a folder and a folder
+ * dropped on the tab bar both do nothing instead of doing the wrong thing.
+ *
+ * Paths are always absolute host paths, including the ones a project tree contributes —
+ * that is the only address space the explorer and the tree share.
+ */
+
+export const ENTRY_DRAG_MIME = "application/x-ppm-paths";
+
+/** Legacy single-path type the project tree already used for its own internal moves. */
+export const TREE_LEGACY_DRAG_MIME = "application/x-ppm-path";
+
+export type EntryDragOrigin = "explorer" | "tree";
+
+export type DropOperation = "copy" | "move";
+
+export interface EntryDragPayload {
+  /** Absolute host paths. */
+  paths: string[];
+  origin: EntryDragOrigin;
+  /** Present when the drag started in a project tree — a tree-internal drop keeps its own routes. */
+  projectName?: string;
+}
+
+/** Windows paths are case-insensitive; a drive letter or a UNC prefix is the cheap tell. */
+function isWindowsPath(path: string): boolean {
+  return /^[a-zA-Z]:[\\/]/.test(path) || path.startsWith("\\\\");
+}
+
+/**
+ * Comparable form of a path: one separator style, no trailing separator, case-folded on
+ * Windows. Only ever used for comparisons — never for building a path to send to the server.
+ */
+export function normalisePath(path: string): string {
+  const unified = path.replace(/\\/g, "/").replace(/\/+$/, "");
+  return isWindowsPath(path) ? unified.toLowerCase() : unified;
+}
+
+/** Host separator implied by a path, for the helpers that have no `HostInfo` at hand. */
+export function sepOf(path: string): string {
+  return isWindowsPath(path) || path.includes("\\") ? "\\" : "/";
+}
+
+export function encodeEntryDrag(payload: EntryDragPayload): string {
+  return JSON.stringify(payload);
+}
+
+/** Tolerant decode — a foreign or truncated payload is "not our drag", never a throw. */
+export function decodeEntryDrag(raw: string | null | undefined): EntryDragPayload | null {
+  if (!raw) return null;
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return null;
+  }
+  if (typeof parsed !== "object" || parsed === null) return null;
+  const candidate = parsed as Partial<EntryDragPayload>;
+  if (!Array.isArray(candidate.paths)) return null;
+  const paths = candidate.paths.filter((p): p is string => typeof p === "string" && p.length > 0);
+  if (paths.length === 0) return null;
+  const payload: EntryDragPayload = {
+    paths,
+    origin: candidate.origin === "tree" ? "tree" : "explorer",
+  };
+  if (typeof candidate.projectName === "string") payload.projectName = candidate.projectName;
+  return payload;
+}
+
+/**
+ * True when `targetDir` is one of the dragged entries or lives inside one — moving a folder
+ * into itself would either delete it or produce infinite nesting, so it is refused outright.
+ */
+export function isSelfOrDescendant(paths: string[], targetDir: string): boolean {
+  const target = normalisePath(targetDir);
+  return paths.some((path) => {
+    const source = normalisePath(path);
+    return target === source || target.startsWith(`${source}/`);
+  });
+}
+
+/** True when every dragged entry already sits directly in `targetDir` — a move would be a no-op. */
+export function allAlreadyIn(paths: string[], targetDir: string): boolean {
+  const target = normalisePath(targetDir);
+  return paths.every((path) => {
+    const source = normalisePath(path);
+    const cut = source.lastIndexOf("/");
+    const parent = cut <= 0 ? source.slice(0, cut + 1) : source.slice(0, cut);
+    return parent === target;
+  });
+}
+
+/**
+ * Move is the default; `Ctrl` (and `Alt`, which is macOS's own copy modifier) switches to
+ * copy. Read again at drop time, because the user is allowed to change their mind mid-drag.
+ */
+export function resolveDropOperation(modifiers: { ctrlKey: boolean; altKey: boolean }): DropOperation {
+  return modifiers.ctrlKey || modifiers.altKey ? "copy" : "move";
+}
+
+/** `text/uri-list` mirror of the payload, so non-PPM drop targets see something meaningful. */
+export function toFileUriList(paths: string[]): string {
+  return paths
+    .map((path) => {
+      const unified = path.replace(/\\/g, "/");
+      const absolute = unified.startsWith("/") ? unified : `/${unified}`;
+      return `file://${absolute.split("/").map(encodeURIComponent).join("/")}`;
+    })
+    .join("\r\n");
+}

package/src/web/components/os-explorer/dnd/entry-drag-state.ts

@@ -0,0 +1,35 @@
+/**
+ * The payload of the drag currently in flight, kept in a module-level ref.
+ *
+ * Chromium refuses to read `dataTransfer` during `dragover` (only `types` is exposed, for
+ * privacy), so a drop target that has to decide "is this folder one of the dragged ones?"
+ * before the drop cannot get the paths from the event. Every drag in this app starts in
+ * this app, so stashing the payload here at `dragstart` and clearing it at `dragend` gives
+ * hover-time validation without weakening the drop-time check, which still reads the real
+ * `dataTransfer`.
+ */
+
+import type { EntryDragPayload } from "./entry-drag-payload";
+
+let inFlight: EntryDragPayload | null = null;
+
+export function setInFlightDrag(payload: EntryDragPayload): void {
+  inFlight = payload;
+}
+
+export function getInFlightDrag(): EntryDragPayload | null {
+  return inFlight;
+}
+
+export function clearInFlightDrag(): void {
+  inFlight = null;
+}
+
+// Last-resort net: a source row that unmounts mid-drag (e.g. a spring-load navigation) can
+// skip its own `dragend`, and the row would otherwise never clear this ref itself. A
+// window-level bubble listener still clears it for any drop/dragend that reaches this far —
+// every drop target that actually claims one already clears it itself first.
+if (typeof window !== "undefined") {
+  window.addEventListener("dragend", clearInFlightDrag);
+  window.addEventListener("drop", clearInFlightDrag);
+}

package/src/web/components/os-explorer/dnd/entry-drop-executor.ts

@@ -0,0 +1,43 @@
+/**
+ * The last gate a dropped payload passes before it touches the filesystem.
+ *
+ * Everything funnels through the clipboard module's `transfer()`, the same call Paste
+ * makes, so drag-and-drop inherits the collision prompt, the trash-first Replace, the
+ * cross-device (`EXDEV`) fallback handled server-side and the `fsChanged` refresh of both
+ * the source and the destination directory. There are deliberately no optimistic updates:
+ * the panes only move once the server has confirmed.
+ */
+
+import { toast } from "sonner";
+import { transfer, type TransferContext } from "../actions/explorer-actions-clipboard";
+import { isSelfOrDescendant, type DropOperation, type EntryDragPayload } from "./entry-drag-payload";
+
+/** How a surface performs the transfer — an explorer window passes its bound action. */
+export type DropRunner = (paths: string[], dstDir: string, op: DropOperation) => Promise<void>;
+
+/**
+ * Re-checks the self/descendant guard the hover-time decision already applied. The modifier
+ * and the pointer can both change between the last `dragover` and the `drop`, and a payload
+ * that arrives without ever having been hovered (a target reached by keyboard-driven drop in
+ * some browsers) never went through that check at all.
+ */
+export async function executeEntryDrop(
+  payload: EntryDragPayload,
+  dstDir: string,
+  op: DropOperation,
+  run: DropRunner,
+): Promise<void> {
+  if (payload.paths.length === 0) return;
+  if (isSelfOrDescendant(payload.paths, dstDir)) {
+    toast.error("Cannot place an item inside itself");
+    return;
+  }
+  await run(payload.paths, dstDir, op);
+}
+
+/** A `DropRunner` for surfaces that own a `TransferContext` instead of an explorer action set. */
+export function transferRunner(context: TransferContext): DropRunner {
+  return async (paths, dstDir, op) => {
+    await transfer(paths, dstDir, op, context);
+  };
+}

package/src/web/components/os-explorer/dnd/use-drag-auto-scroll.ts

@@ -0,0 +1,70 @@
+/**
+ * Scrolls a container while an entry drag hovers near its edge, so a destination that is
+ * off-screen is still reachable without letting go.
+ *
+ * Listens natively on the element rather than through React props: `dragover` bubbles from
+ * whatever row the pointer is really over, and the row's own React handler stops the
+ * synthetic event — which would hide every edge hover from a JSX-level handler here.
+ */
+
+import { useEffect, type RefObject } from "react";
+import { ENTRY_DRAG_MIME } from "./entry-drag-payload";
+
+/** Distance from an edge at which scrolling starts. */
+const EDGE_ZONE_PX = 48;
+/** Fastest scroll step per frame, reached at the very edge. */
+const MAX_STEP_PX = 16;
+
+function stepFor(distance: number): number {
+  if (distance >= EDGE_ZONE_PX) return 0;
+  const intensity = Math.min(1, Math.max(0, (EDGE_ZONE_PX - distance) / EDGE_ZONE_PX));
+  return Math.ceil(intensity * MAX_STEP_PX);
+}
+
+export function useDragAutoScroll(ref: RefObject<HTMLElement | null>): void {
+  useEffect(() => {
+    const element = ref.current;
+    if (!element) return;
+
+    let frame: number | null = null;
+    let velocity = { x: 0, y: 0 };
+
+    const stop = () => {
+      if (frame !== null) cancelAnimationFrame(frame);
+      frame = null;
+      velocity = { x: 0, y: 0 };
+    };
+
+    const tick = () => {
+      if (velocity.x === 0 && velocity.y === 0) {
+        frame = null;
+        return;
+      }
+      element.scrollBy(velocity.x, velocity.y);
+      frame = requestAnimationFrame(tick);
+    };
+
+    const onDragOver = (event: DragEvent) => {
+      if (!event.dataTransfer?.types.includes(ENTRY_DRAG_MIME)) return;
+      const box = element.getBoundingClientRect();
+      const up = stepFor(event.clientY - box.top);
+      const down = stepFor(box.bottom - event.clientY);
+      const left = stepFor(event.clientX - box.left);
+      const right = stepFor(box.right - event.clientX);
+      velocity = { x: right - left, y: down - up };
+      if (frame === null && (velocity.x !== 0 || velocity.y !== 0)) frame = requestAnimationFrame(tick);
+    };
+
+    element.addEventListener("dragover", onDragOver);
+    element.addEventListener("dragleave", stop);
+    element.addEventListener("drop", stop);
+    window.addEventListener("dragend", stop);
+    return () => {
+      stop();
+      element.removeEventListener("dragover", onDragOver);
+      element.removeEventListener("dragleave", stop);
+      element.removeEventListener("drop", stop);
+      window.removeEventListener("dragend", stop);
+    };
+  }, [ref]);
+}

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

@@ -0,0 +1,82 @@
+/**
+ * A self-contained transfer runner for the drop surfaces that live outside an explorer
+ * window's action set: the places sidebar, the breadcrumb and the project file tree.
+ *
+ * Those three are rendered by components that never receive `ExplorerActions`, so they own
+ * the two interruptions `transfer()` can raise (name collision, and a Replace on a host with
+ * no Trash) themselves. The dialogs are the very same components the window body renders —
+ * only the promise wiring is local — so a collision looks identical wherever the drop landed.
+ */
+
+import { useEffect, useMemo, useRef, useState, type ReactNode } from "react";
+import type { CollisionChoice, CollisionRequest, TransferContext } from "../actions/explorer-actions-clipboard";
+import type { ExplorerDialogState } from "../actions/use-explorer-actions";
+import { ExplorerDialogs } from "../explorer-dialogs";
+import { transferRunner, type DropRunner } from "./entry-drop-executor";
+
+export interface DropTransfer {
+  run: DropRunner;
+  /** Render this somewhere inside the surface — it is empty until a prompt is raised. */
+  prompts: ReactNode;
+}
+
+export function useDropTransfer(sep: string, platform?: string): DropTransfer {
+  const [collision, setCollision] = useState<ExplorerDialogState["collision"]>(null);
+  const [permanentOverwrite, setPermanentOverwrite] = useState<ExplorerDialogState["permanentOverwrite"]>(null);
+
+  // The separator can change under a long-lived surface (the tree follows the active
+  // project), so the context reads it live rather than closing over the first value.
+  // Assigned in an effect, not during render — React may discard a render before commit.
+  const sepRef = useRef(sep);
+  useEffect(() => { sepRef.current = sep; }, [sep]);
+
+  const context = useMemo<TransferContext>(
+    () => ({
+      get sep() {
+        return sepRef.current;
+      },
+      resolve: (request: CollisionRequest) =>
+        new Promise<CollisionChoice>((resolve) => {
+          setCollision({
+            ...request,
+            resolve: (choice) => {
+              setCollision(null);
+              resolve(choice);
+            },
+          });
+        }),
+      confirmPermanentOverwrite: (name: string) =>
+        new Promise<boolean>((resolve) => {
+          setPermanentOverwrite({
+            name,
+            resolve: (proceed) => {
+              setPermanentOverwrite(null);
+              resolve(proceed);
+            },
+          });
+        }),
+    }),
+    [],
+  );
+
+  const run = useMemo<DropRunner>(() => transferRunner(context), [context]);
+
+  const prompts = (
+    <ExplorerDialogs
+      dialogs={{
+        collision,
+        permanentOverwrite,
+        pendingDelete: null,
+        properties: null,
+        inlineError: null,
+        closeDelete: () => {},
+        runPermanentDelete: () => {},
+        closeProperties: () => {},
+      }}
+      platform={platform}
+      sep={sep}
+    />
+  );
+
+  return { run, prompts };
+}

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

@@ -0,0 +1,73 @@
+/**
+ * Makes a row, tile or tree node the source of an entry drag.
+ *
+ * Returns nothing at all on a coarse pointer: HTML5 drag has no touch equivalent, and the
+ * guideline reserves a long press for the context menu, so a phone must not even get the
+ * `draggable` attribute (it would swallow the press). Cut/Copy/Paste stays the touch path.
+ */
+
+import { useCallback, useMemo, type DragEvent } from "react";
+import { setEntryDragGhost } from "./drag-ghost";
+import { clearInFlightDrag, setInFlightDrag } from "./entry-drag-state";
+import {
+  encodeEntryDrag, ENTRY_DRAG_MIME, toFileUriList,
+  type EntryDragOrigin,
+} from "./entry-drag-payload";
+import { usePrefersCoarsePointer } from "../use-coarse-long-press";
+
+export interface EntryDragSourceOptions {
+  /** Absolute host paths this drag carries — the whole selection when the row is selected. */
+  paths: string[];
+  /** Ghost labels; defaults to the basenames of `paths`. */
+  names?: string[];
+  origin: EntryDragOrigin;
+  projectName?: string;
+  /**
+   * Extra `dataTransfer` entries written alongside the shared payload. The project tree
+   * keeps writing its own legacy single-path type here so tree-internal drops, which have
+   * their own project-scoped route, behave exactly as they did before.
+   */
+  extraData?: Record<string, string>;
+  disabled?: boolean;
+  /** Runs before the payload is written — used to make the dragged row the selected one. */
+  onDragStarted?(): void;
+}
+
+export interface EntryDragSourceProps {
+  draggable?: true;
+  onDragStart?(event: DragEvent): void;
+  onDragEnd?(event: DragEvent): void;
+}
+
+function basenameOf(path: string): string {
+  return path.split(/[/\\]/).filter(Boolean).pop() ?? path;
+}
+
+export function useEntryDragSource(options: EntryDragSourceOptions): EntryDragSourceProps {
+  const { paths, names, origin, projectName, extraData, disabled, onDragStarted } = options;
+  const coarse = usePrefersCoarsePointer();
+  const enabled = !coarse && !disabled && paths.length > 0;
+
+  const handleDragStart = useCallback(
+    (event: DragEvent) => {
+      onDragStarted?.();
+      const payload = { paths, origin, ...(projectName ? { projectName } : {}) };
+      const data = event.dataTransfer;
+      data.setData(ENTRY_DRAG_MIME, encodeEntryDrag(payload));
+      // Accessibility / interop mirror: anything that understands dropped files sees paths.
+      data.setData("text/uri-list", toFileUriList(paths));
+      data.setData("text/plain", paths.join("\n"));
+      for (const [type, value] of Object.entries(extraData ?? {})) data.setData(type, value);
+      data.effectAllowed = "copyMove";
+      setEntryDragGhost(data, names ?? paths.map(basenameOf));
+      // Hover-time validation cannot read `dataTransfer`; see `entry-drag-state.ts`.
+      setInFlightDrag(payload);
+    },
+    [paths, names, origin, projectName, extraData, onDragStarted],
+  );
+
+  return useMemo<EntryDragSourceProps>(
+    () => (enabled ? { draggable: true, onDragStart: handleDragStart, onDragEnd: clearInFlightDrag } : {}),
+    [enabled, handleDragStart],
+  );
+}