@hienlh/ppm 0.17.57 → 0.18.0

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

@@ -0,0 +1,109 @@
+/**
+ * Disk mutations: new file / new folder, rename, and the two delete flavours.
+ *
+ * Deleting goes to the OS trash by default. When the host has no trash backend the server
+ * answers `NO_TRASH` and the caller is told to offer a permanent delete instead of failing
+ * with a message the user cannot act on.
+ */
+
+import { toast } from "sonner";
+import { fsApi, FsError } from "@/lib/fs-api";
+import { dirnameOf, errorDescription, joinPath } from "../format-file-meta";
+import { fsChanged } from "../explorer-store";
+
+/** Characters Windows refuses in a file name. */
+const WINDOWS_ILLEGAL = /[<>:"|?*]/;
+/** Control characters are illegal in a name on every platform. */
+const CONTROL_CHARS = /[\u0000-\u001f]/;
+/** Device names Windows reserves, with or without an extension. */
+const WINDOWS_RESERVED = /^(con|prn|aux|nul|com[1-9]|lpt[1-9])(\..*)?$/i;
+
+/**
+ * Validate a bare entry name. Returns an error message, or null when the name is usable.
+ * The server enforces the same rules; checking here keeps the inline input responsive.
+ */
+export function validateEntryName(name: string, platform: string | undefined): string | null {
+  if (!name) return "Name cannot be empty";
+  if (name === "." || name === "..") return "Reserved name";
+  if (name.includes("/") || name.includes("\\")) return "Name cannot contain path separators";
+  if (CONTROL_CHARS.test(name)) return "Invalid character in name";
+  if (platform === "win32") {
+    if (WINDOWS_ILLEGAL.test(name)) return 'Cannot contain < > : " | ? *';
+    if (WINDOWS_RESERVED.test(name)) return `"${name}" is a reserved Windows name`;
+    // Windows silently strips these, so the created entry would not be the one asked for.
+    if (name.endsWith(".") || name.endsWith(" ")) return "Cannot end with a dot or space";
+  }
+  return null;
+}
+
+export async function createEntry(
+  dir: string,
+  name: string,
+  kind: "file" | "folder",
+  sep: string,
+): Promise<boolean> {
+  const path = joinPath(dir, name, sep);
+  try {
+    // `gitInit: false` — an explorer folder is a folder, not a new repository.
+    if (kind === "folder") await fsApi.mkdir(path, false);
+    else await fsApi.touch(path);
+    fsChanged(dir);
+    return true;
+  } catch (e) {
+    toast.error(kind === "folder" ? "Could not create folder" : "Could not create file", {
+      description: errorDescription(e),
+    });
+    return false;
+  }
+}
+
+export async function renameEntry(path: string, newName: string, sep: string): Promise<boolean> {
+  try {
+    await fsApi.rename(path, newName);
+    fsChanged(dirnameOf(path, sep));
+    return true;
+  } catch (e) {
+    toast.error("Rename failed", { description: errorDescription(e) });
+    return false;
+  }
+}
+
+export interface DeleteOutcome {
+  removed: number;
+  /** Paths the host could not trash — the caller offers a permanent delete for these. */
+  needsPermanent: string[];
+}
+
+/**
+ * Delete `paths`. With `permanent` false this moves them to the OS trash and any path the
+ * host cannot trash is reported back rather than removed behind the user's back.
+ */
+export async function deleteEntries(
+  paths: string[],
+  permanent: boolean,
+  sep: string,
+): Promise<DeleteOutcome> {
+  const outcome: DeleteOutcome = { removed: 0, needsPermanent: [] };
+  const touched = new Set<string>();
+
+  for (const path of paths) {
+    touched.add(dirnameOf(path, sep));
+    try {
+      await fsApi.remove(path, permanent);
+      outcome.removed++;
+    } catch (e) {
+      if (e instanceof FsError && e.code === "NO_TRASH") {
+        outcome.needsPermanent.push(path);
+        continue;
+      }
+      toast.error("Delete failed", { description: errorDescription(e) });
+    }
+  }
+
+  fsChanged(...touched);
+  if (outcome.removed > 0) {
+    const noun = `${outcome.removed} item${outcome.removed === 1 ? "" : "s"}`;
+    toast.success(permanent ? `Deleted ${noun}` : `Moved ${noun} to Trash`);
+  }
+  return outcome;
+}

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

@@ -0,0 +1,67 @@
+/**
+ * Opening entries and the read-only menu commands: open in a PPM tab, open a folder in a
+ * second explorer window, download, copy path / name.
+ */
+
+import { toast } from "sonner";
+import type { FsEntry } from "@/lib/fs-api";
+import { fsApi } from "@/lib/fs-api";
+import { copyToClipboard } from "@/lib/clipboard";
+import { triggerDownload } from "@/lib/file-download";
+import { useTabStore } from "@/stores/tab-store";
+import { useWindowStore } from "@/components/floating-window/window-store";
+import { canOpenInPpm, viewerKindOf } from "../can-open-in-ppm";
+
+/**
+ * Open a file in the tab that can display it.
+ *
+ * `projectName` is deliberately absent: these are absolute host paths, and the viewers
+ * branch on that to reach `/api/fs/*` instead of the project-scoped routes.
+ */
+export function openEntryInPpm(entry: FsEntry): boolean {
+  if (!canOpenInPpm(entry.name)) return false;
+  useTabStore.getState().openTab({
+    type: viewerKindOf(entry.name) === "sqlite" ? "sqlite" : "editor",
+    title: entry.name,
+    projectId: null,
+    metadata: { filePath: entry.path },
+    closable: true,
+  });
+  return true;
+}
+
+/** Spawn another explorer window rooted at `path`. */
+export function openPathInNewWindow(path: string): string {
+  return useWindowStore.getState().open("explorer", { path });
+}
+
+/**
+ * Download files one at a time. Each download needs its own single-use token, and
+ * directories have no zip route outside a project, so folders are reported rather than
+ * silently skipped.
+ */
+export async function downloadEntries(entries: FsEntry[]): Promise<void> {
+  const files = entries.filter((e) => e.type === "file");
+  const skipped = entries.length - files.length;
+  if (skipped > 0) {
+    toast.warning(skipped === 1 ? "Folders cannot be downloaded" : `${skipped} folders skipped`);
+  }
+  for (const file of files) {
+    try {
+      triggerDownload(await fsApi.downloadUrl(file.path), file.name);
+    } catch (e) {
+      toast.error(`Download failed: ${file.name}`, {
+        description: e instanceof Error ? e.message : undefined,
+      });
+    }
+  }
+}
+
+/** Copy plain text to the system clipboard, one value per line, and confirm it. */
+export async function copyTextLines(values: string[], noun: "Path" | "Name"): Promise<void> {
+  if (values.length === 0) return;
+  await copyToClipboard(values.join("\n"));
+  toast.success(
+    values.length === 1 ? `${noun} copied` : `${values.length} ${noun.toLowerCase()}s copied`,
+  );
+}

package/src/web/components/os-explorer/actions/explorer-actions-transfer-helpers.ts

@@ -0,0 +1,35 @@
+/**
+ * Pure helpers shared by `transfer()`: finding a free "name (n)" for Keep-both/same-folder
+ * copy, running one copy/move call, and turning a failure into a toast description. Split
+ * out of `explorer-actions-clipboard.ts` to keep that file under the line cap.
+ */
+
+import { fsApi, FsError } from "@/lib/fs-api";
+import { joinPath, suffixName } from "../format-file-meta";
+
+/** Highest "name (n)" suffix tried before giving up on a free name. */
+const MAX_KEEP_BOTH_ATTEMPTS = 99;
+
+async function pathExists(path: string): Promise<boolean> {
+  try {
+    await fsApi.stat(path);
+    return true;
+  } catch (e) {
+    if (e instanceof FsError && e.code === "ENOENT") return false;
+    // Anything else (permission, protected root) is not a free name either.
+    return true;
+  }
+}
+
+export async function freeName(dir: string, name: string, sep: string): Promise<string | null> {
+  for (let n = 2; n <= MAX_KEEP_BOTH_ATTEMPTS; n++) {
+    const candidate = suffixName(name, n);
+    if (!(await pathExists(joinPath(dir, candidate, sep)))) return candidate;
+  }
+  return null;
+}
+
+export async function runOne(source: string, destination: string, op: "copy" | "move"): Promise<void> {
+  if (op === "copy") await fsApi.copy(source, destination);
+  else await fsApi.move(source, destination);
+}

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

@@ -0,0 +1,205 @@
+/**
+ * Binds the action modules to one window's slice and owns the state of the three
+ * interruptions they need: the collision prompt, the permanent-delete confirmation and
+ * the properties dialog.
+ *
+ * Prompts are modelled as promises resolved by the dialog, so the action modules stay
+ * plain async functions with no React inside them.
+ */
+
+import { useCallback, useMemo, useRef, useState } from "react";
+import { toast } from "sonner";
+import type { FsEntry } from "@/lib/fs-api";
+import { useExplorerPinsStore } from "../explorer-pins-store";
+import { useExplorerStore, type ExplorerSlice } from "../explorer-store";
+import type { ExplorerNavigation } from "../use-explorer-navigation";
+import { copyTextLines, downloadEntries, openEntryInPpm, openPathInNewWindow } from "./explorer-actions-open";
+import {
+  pasteInto, setClipboardPaths, transfer,
+  type CollisionChoice, type CollisionRequest,
+} from "./explorer-actions-clipboard";
+import { createEntry, deleteEntries, renameEntry, validateEntryName } from "./explorer-actions-mutate";
+
+export interface ExplorerActions {
+  openEntry(entry: FsEntry): void;
+  openInNewWindow(entry: FsEntry): void;
+  cut(entries: FsEntry[]): void;
+  copy(entries: FsEntry[]): void;
+  paste(targetDir?: string): void;
+  startRename(entry: FsEntry): void;
+  startCreate(kind: "new-file" | "new-folder"): void;
+  commitInline(value: string): Promise<void>;
+  cancelInline(): void;
+  trash(entries: FsEntry[]): void;
+  confirmPermanentDelete(entries: FsEntry[]): void;
+  download(entries: FsEntry[]): void;
+  copyPath(paths: string[]): void;
+  copyName(names: string[]): void;
+  togglePin(path: string, name: string): void;
+  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>;
+}
+
+export interface ExplorerDialogState {
+  collision: (CollisionRequest & { resolve(choice: CollisionChoice): void }) | null;
+  pendingDelete: { paths: string[]; names: string[] } | null;
+  /** "Replace" hit a host with no trash backend — confirm a permanent overwrite instead. */
+  permanentOverwrite: { name: string; resolve(proceed: boolean): void } | null;
+  properties: FsEntry | null;
+  inlineError: string | null;
+  closeDelete(): void;
+  runPermanentDelete(): void;
+  closeProperties(): void;
+}
+
+export function useExplorerActions(
+  windowId: string,
+  slice: ExplorerSlice | undefined,
+  nav: ExplorerNavigation,
+  platform: string | undefined,
+): { actions: ExplorerActions; dialogs: ExplorerDialogState } {
+  const patch = useExplorerStore((s) => s.patch);
+  const [collision, setCollision] = useState<ExplorerDialogState["collision"]>(null);
+  const [pendingDelete, setPendingDelete] = useState<ExplorerDialogState["pendingDelete"]>(null);
+  const [permanentOverwrite, setPermanentOverwrite] = useState<ExplorerDialogState["permanentOverwrite"]>(null);
+  const [properties, setProperties] = useState<FsEntry | null>(null);
+  const [inlineError, setInlineError] = useState<string | null>(null);
+
+  const sliceRef = useRef(slice);
+  sliceRef.current = slice;
+
+  const context = useMemo(
+    () => ({
+      get sep() {
+        return sliceRef.current?.sep ?? "/";
+      },
+      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 currentDir = () => sliceRef.current?.path ?? "";
+
+  const actions = useMemo<ExplorerActions>(() => ({
+    openEntry: (entry) => {
+      if (entry.type === "directory") nav.go(entry.path);
+      else openEntryInPpm(entry);
+    },
+    openInNewWindow: (entry) => {
+      openPathInNewWindow(entry.type === "directory" ? entry.path : (sliceRef.current?.path ?? entry.path));
+    },
+    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),
+    transferInto: async (paths, dstDir, op) => {
+      // Paste toasts its own result; a drag-move/copy silently completing otherwise gives no
+      // feedback at all for a long multi-file drag.
+      const result = await transfer(paths, dstDir, op, context);
+      if (result.succeeded > 0) {
+        const verb = op === "copy" ? "Copied" : "Moved";
+        toast.success(`${verb} ${result.succeeded} item${result.succeeded === 1 ? "" : "s"}`);
+      }
+    },
+
+    startRename: (entry) => {
+      setInlineError(null);
+      patch(windowId, { inlineEdit: { kind: "rename", path: entry.path, initial: entry.name } });
+    },
+    startCreate: (kind) => {
+      setInlineError(null);
+      patch(windowId, { inlineEdit: { kind, initial: "" } });
+    },
+    cancelInline: () => {
+      setInlineError(null);
+      patch(windowId, { inlineEdit: null });
+    },
+    commitInline: async (value) => {
+      const current = sliceRef.current;
+      const edit = current?.inlineEdit;
+      if (!current || !edit) return;
+      const name = value.trim();
+      if (edit.kind === "rename" && name === edit.initial) {
+        patch(windowId, { inlineEdit: null });
+        return;
+      }
+      const problem = validateEntryName(name, platform);
+      if (problem) {
+        setInlineError(problem);
+        return;
+      }
+      setInlineError(null);
+      const done = edit.kind === "rename"
+        ? await renameEntry(edit.path, name, current.sep)
+        : await createEntry(current.path, name, edit.kind === "new-folder" ? "folder" : "file", current.sep);
+      if (done) patch(windowId, { inlineEdit: null });
+    },
+
+    trash: (entries) => {
+      void deleteEntries(entries.map((e) => e.path), false, sliceRef.current?.sep ?? "/").then((outcome) => {
+        // The host has no trash backend for these paths; permanent deletion is the only
+        // remaining option, so offer it instead of leaving the entries in place silently.
+        if (outcome.needsPermanent.length > 0) {
+          setPendingDelete({
+            paths: outcome.needsPermanent,
+            names: outcome.needsPermanent.map((p) => p.split(/[/\\]/).pop() ?? p),
+          });
+        }
+      });
+    },
+    confirmPermanentDelete: (entries) => {
+      if (entries.length === 0) return;
+      setPendingDelete({ paths: entries.map((e) => e.path), names: entries.map((e) => e.name) });
+    },
+
+    download: (entries) => void downloadEntries(entries),
+    copyPath: (paths) => void copyTextLines(paths, "Path"),
+    copyName: (names) => void copyTextLines(names, "Name"),
+    togglePin: (path, name) => {
+      const pins = useExplorerPinsStore.getState();
+      if (pins.isPinned(path)) pins.unpin(path);
+      else pins.pin({ path, name });
+    },
+    showProperties: (entry) => setProperties(entry),
+  }), [windowId, patch, nav, context, platform]);
+
+  const runPermanentDelete = useCallback(() => {
+    const target = pendingDelete;
+    setPendingDelete(null);
+    if (!target) return;
+    void deleteEntries(target.paths, true, sliceRef.current?.sep ?? "/");
+  }, [pendingDelete]);
+
+  return {
+    actions,
+    dialogs: {
+      collision,
+      pendingDelete,
+      permanentOverwrite,
+      properties,
+      inlineError,
+      closeDelete: () => setPendingDelete(null),
+      runPermanentDelete,
+      closeProperties: () => setProperties(null),
+    },
+  };
+}

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";