@lotics/ui 15.0.0 → 15.1.0

package/examples/tpl_record.tsx

@@ -54,6 +54,7 @@ import { FileGalleryModal } from "@lotics/ui/file_gallery_modal";
 import { DangerZone } from "@lotics/ui/danger_zone";
 import { FileRow } from "@lotics/ui/file_row";
 import { pickFiles } from "@lotics/ui/file_picker";
+import { FileDropTarget } from "@lotics/ui/file_drop_target";
 import { Table, TableRow, TableCell, type TableColumn } from "@lotics/ui/table";
 import { cycleSort, sortBy, type SortState } from "@lotics/ui/sort_header";
 import { Finding, FindingComparison } from "@lotics/ui/finding";
@@ -881,6 +882,20 @@ export function TplRecord() {
   const [fieldDecisions, setFieldDecisions] = useState<Record<string, "kept" | "dropped">>({});
 
   const openAi = () => { setPicked(files.filter((f) => sel.has(f.id))); setUploadFlow(false); setAiOpen(true); };
+  // THE standard files intake — one handler, three ways in: the Documents
+  // section's Add-files CTA, a drag anywhere onto the record, and Ctrl/Cmd+V.
+  // The last two ride the WHOLE-RECORD `<FileDropTarget paste>` that wraps the
+  // section stack (see the render) — a drop/paste ANYWHERE on the surface, not
+  // only the Documents section, lands here. Every record surface should carry
+  // all three; the user never hunts for a dropzone. All three land in the same
+  // PENDING fork dialog — saving stays a decision. The target is `disabled`
+  // while the dialog is open so a paste can't start a SECOND one.
+  const intakeFiles = (chosen: File[]) => {
+    if (chosen.length === 0) return;
+    setPicked(chosen.map((f, i) => ({ id: `added-${f.name}-${i}`, name: f.name, mimeType: f.type || "application/pdf", kind: (f.type || "application/pdf").split("/")[1]?.toUpperCase().slice(0, 4) ?? "FILE", sizeKB: Math.round(f.size / 1024), added: "just now", addedAt: 999 })));
+    setUploadFlow(true);
+    setAiOpen(true);
+  };
   // The upload path's save: pending picked files land on the record only here.
   const commitUpload = () => setFiles((fs) => [...fs, ...picked.filter((p2) => !fs.some((f) => f.id === p2.id))]);
   const closeAi = () => {
@@ -1405,6 +1420,16 @@ export function TplRecord() {
         </View>
       ) : (
       <>
+      {/* WHOLE-SURFACE INTAKE — the standard this template DEMONSTRATES: the
+          ENTIRE record body is one `FileDropTarget`, so a file dropped or a
+          Ctrl/Cmd+V pasted ANYWHERE on the record (not just the Documents
+          section) is captured and routed to `intakeFiles` — the pending fork
+          dialog opens (extract vs save, a decision). `flex:1, minWidth:0`
+          preserves the reading column's flex/scroll; `disabled` while the
+          dialog is open so a paste can't start a SECOND one; the accent ring
+          frames the whole column on drag ("drop anywhere here"). A real app
+          author opts in per-app — the section stack is the reference shape. */}
+      <FileDropTarget onFiles={intakeFiles} accept="application/pdf,image/*" paste disabled={aiOpen} style={{ flex: 1, minWidth: 0 }}>
       {/* the page column is a SectionStack — it owns the 56px beat + the
           hairline BETWEEN top-level blocks (a conditional block that renders
           null never leaves a stray divider) */}
@@ -1868,11 +1893,16 @@ export function TplRecord() {
         </View>
 
         {/* DOCUMENTS — the document desk: the register Table (search · Create
-            documents · Add files) whose selection feeds the Use-AI fork below. */}
+            documents · Add files) whose selection feeds the Use-AI fork below.
+            No FileDropTarget of its OWN — the WHOLE-RECORD target above already
+            captures a drop/paste here (and everywhere else on the surface); this
+            section keeps only its explicit Add-files CTA and the affordance line. */}
         <View onLayout={nav.register("documents")}>
         <Section>
           <SectionHeading>
-            <SectionHeadingTitle>Documents</SectionHeadingTitle>
+            {/* The standard files-section affordance line — drag / paste / click
+                stay discoverable even though the drop target is the whole record. */}
+            <SectionHeadingTitle description="Drag, paste, or click to add files">Documents</SectionHeadingTitle>
           </SectionHeading>
           {/* toolbar — search LEFT, the CTAs RIGHT, one row (the register band). */}
           <View style={{ flexDirection: "row", alignItems: "center", gap: 8 }}>
@@ -1887,20 +1917,14 @@ export function TplRecord() {
             <View style={{ flex: 1 }} />
             {/* no Create here — GENERATION lives in the Document set section
                 below (this desk = intake) */}
+            {/* PENDING until the user chooses: saving is a decision the dialog
+                asks for (save only / run a task), never a side effect of
+                picking — closing the dialog discards. */}
             <Button
               title="Add files"
               color="secondary"
               onPress={() => {
-                void pickFiles({ accept: "application/pdf,image/*", multiple: true }).then((chosen) => {
-                  if (chosen.length === 0) return;
-                  const added = chosen.map((f, i) => ({ id: `added-${f.name}-${i}`, name: f.name, mimeType: f.type || "application/pdf", kind: (f.type || "application/pdf").split("/")[1]?.toUpperCase().slice(0, 4) ?? "FILE", sizeKB: Math.round(f.size / 1024), added: "just now", addedAt: 999 }));
-                  // PENDING until the user chooses: saving is a decision the
-                  // dialog asks for (save only / run a task), never a side
-                  // effect of picking — closing the dialog discards.
-                  setPicked(added);
-                  setUploadFlow(true);
-                  setAiOpen(true);
-                });
+                void pickFiles({ accept: "application/pdf,image/*", multiple: true }).then(intakeFiles);
               }}
             />
           </View>
@@ -2457,6 +2481,7 @@ export function TplRecord() {
         </Section>
         </View>
       </SectionStack>
+      </FileDropTarget>
       </>
       )}
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/ui",
-  "version": "15.0.0",
+  "version": "15.1.0",
   "type": "module",
   "exports": {
     "./vite": {
@@ -21,6 +21,15 @@
     "./comments_thread": "./src/comments_thread.tsx",
     "./file_badge": "./src/file_badge.tsx",
     "./file_dropzone": "./src/file_dropzone.tsx",
+    "./file_intake": "./src/file_intake.ts",
+    "./file_drop_target": {
+      "react-native": "./src/file_drop_target.tsx",
+      "default": "./src/file_drop_target.web.tsx"
+    },
+    "./use_paste_files": {
+      "react-native": "./src/use_paste_files.ts",
+      "default": "./src/use_paste_files.web.ts"
+    },
     "./file_thumbnail": "./src/file_thumbnail.tsx",
     "./file_row": "./src/file_row.tsx",
     "./file_rows": "./src/file_rows.tsx",

package/src/dom_region.ts

@@ -0,0 +1,14 @@
+import type { RegionRef } from "./file_intake";
+
+/**
+ * Native stand-in for the region → DOM-node resolver.
+ *
+ * There is no DOM on React Native, so there is no node to resolve — the drag
+ * and focus-routing paths this backs are web-only. The file exists purely as
+ * the typecheck-resolution base for the `.web` variant (the `.web` file is the
+ * only importer at runtime; Metro never reaches this on native, but the shared
+ * signature lives here).
+ */
+export function resolveRegionNode(_region: RegionRef | undefined): HTMLElement | null {
+  return null;
+}

package/src/dom_region.web.ts

@@ -0,0 +1,13 @@
+import type { RegionRef } from "./file_intake";
+
+/**
+ * A region ref → its DOM node. RN-web exposes a `View`'s underlying
+ * `HTMLElement` straight through the ref's `.current`, so this is the SINGLE
+ * place that unwraps it — shared by `FileDropTarget`'s drag listeners and
+ * `usePasteFiles`'s focus routing, so the two can never resolve the region two
+ * different ways. Returns null when the ref is empty or not yet an element.
+ */
+export function resolveRegionNode(region: RegionRef | undefined): HTMLElement | null {
+  const node = region?.current;
+  return node instanceof HTMLElement ? node : null;
+}

package/src/file_drop_target.tsx

@@ -0,0 +1,16 @@
+import { View } from "react-native";
+import type { FileDropTargetProps } from "./file_intake";
+
+/**
+ * Native stand-in for the drop region.
+ *
+ * React Native has no HTML5 drag-and-drop, so the region is simply its children
+ * and the surface's own Add-file CTA stays the intake path. The wrapper `View`
+ * is kept (and `style` still applies) so the tree and layout match web exactly.
+ *
+ * Web targets resolve `file_drop_target.web.tsx` instead (Metro's `.web`
+ * extension resolution; the package's `react-native` export condition).
+ */
+export function FileDropTarget({ children, style }: FileDropTargetProps) {
+  return <View style={style}>{typeof children === "function" ? children(false) : children}</View>;
+}

package/src/file_drop_target.web.tsx

@@ -0,0 +1,118 @@
+import { useEffect, useRef, useState } from "react";
+import { StyleSheet, View } from "react-native";
+import { colors } from "./colors";
+import { filesFromTransfer, type FileDropTargetProps } from "./file_intake";
+import { resolveRegionNode } from "./dom_region";
+import { usePasteFiles } from "./use_paste_files";
+
+/**
+ * Makes ANY region accept a file drag-drop — the region-wrapper half of file
+ * intake (`FileDropzone` stays the dedicated empty-state well; `usePasteFiles`
+ * is the clipboard half). Wrap a record's Files section, a card, a whole panel:
+ * a file dragged anywhere over it lands, so nobody has to hunt for a dropzone.
+ * Pass `paste` to ALSO take Ctrl/Cmd+V scoped to this region's focus.
+ *
+ * While a drag hovers, the region wears the kit's accent affordance — a blue
+ * ring + wash, the same tokens `FileDropzone` lights up with, painted as a
+ * box-shadow so nothing reflows. Pass a FUNCTION child to draw the drag state
+ * yourself instead (the target then paints nothing).
+ */
+export function FileDropTarget(props: FileDropTargetProps) {
+  const { onFiles, accept, multiple = true, paste = false, disabled = false, children, style } = props;
+
+  const regionRef = useRef<View>(null);
+  // dragenter/dragleave fire per descendant element, so a plain boolean flickers
+  // as the pointer crosses children — count depth and clear only at zero.
+  const dragDepth = useRef(0);
+  const [dragging, setDragging] = useState(false);
+
+  // The clipboard half, scoped to THIS region — the paste routes to whichever
+  // enabled target holds focus (see usePasteFiles). Region-scoped so two peer
+  // sections each win when focus is in them; a no-op unless `paste` is set.
+  usePasteFiles({ onFiles, accept, multiple, enabled: paste && !disabled, region: regionRef });
+
+  // The drop settings are read through a ref so the listeners subscribe ONCE.
+  // Keying the effect on `onFiles` instead would re-bind on every parent render
+  // — routine with an inline callback — and tear an in-progress drag's state
+  // down mid-hover.
+  const latest = useRef({ onFiles, accept, multiple });
+  useEffect(() => {
+    latest.current = { onFiles, accept, multiple };
+  });
+
+  // RN-web exposes the View's underlying HTMLElement through the ref — attach the
+  // DOM drag events there (resolved the same way the paste focus check is).
+  useEffect(() => {
+    if (disabled) {
+      // Disabled mid-drag: drop the affordance with the listeners.
+      dragDepth.current = 0;
+      setDragging(false);
+      return;
+    }
+    const node = resolveRegionNode(regionRef);
+    if (!node) return;
+
+    // Scope every drag/drop event to the INNERMOST target — stopPropagation so a
+    // FileDropTarget nested in another (e.g. a FileDropzone empty-state inside a
+    // Files-section drop target — a FileDropzone IS a FileDropTarget) fires only
+    // once: without it one drop bubbles to both handlers and adds the file twice,
+    // and both regions light their drag ring.
+    const onDragEnter = (e: DragEvent) => {
+      e.preventDefault();
+      e.stopPropagation();
+      dragDepth.current += 1;
+      setDragging(true);
+    };
+    // preventDefault is what makes the element a legal drop target.
+    const onDragOver = (e: DragEvent) => {
+      e.preventDefault();
+      e.stopPropagation();
+    };
+    const onDragLeave = (e: DragEvent) => {
+      e.stopPropagation();
+      dragDepth.current = Math.max(0, dragDepth.current - 1);
+      if (dragDepth.current === 0) setDragging(false);
+    };
+    const onDrop = (e: DragEvent) => {
+      e.preventDefault();
+      e.stopPropagation();
+      dragDepth.current = 0;
+      setDragging(false);
+      const settings = latest.current;
+      const dropped = filesFromTransfer(e.dataTransfer, settings);
+      if (dropped.length === 0) return;
+      settings.onFiles(dropped);
+    };
+
+    node.addEventListener("dragenter", onDragEnter);
+    node.addEventListener("dragover", onDragOver);
+    node.addEventListener("dragleave", onDragLeave);
+    node.addEventListener("drop", onDrop);
+    return () => {
+      node.removeEventListener("dragenter", onDragEnter);
+      node.removeEventListener("dragover", onDragOver);
+      node.removeEventListener("dragleave", onDragLeave);
+      node.removeEventListener("drop", onDrop);
+    };
+  }, [disabled]);
+
+  return (
+    <View
+      ref={regionRef}
+      style={[style, dragging && typeof children !== "function" ? styles.dragging : null]}
+    >
+      {typeof children === "function" ? children(dragging) : children}
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  // The drop invitation, restrained: the accent ring reads as the edge of the
+  // landing area and the wash tints the region behind its content. Both are
+  // box-shadow/background — zero layout impact, so nothing shifts mid-drag.
+  dragging: {
+    borderRadius: 12,
+    backgroundColor: colors.blue[50],
+    boxShadow: `0 0 0 1.5px ${colors.blue[500]}, 0 0 0 6px ${colors.blue[50]}`,
+  },
+});

package/src/file_dropzone.tsx

@@ -1,9 +1,10 @@
-import { useEffect, useRef, useState } from "react";
+import { useState } from "react";
 import { Pressable, StyleSheet, View, type StyleProp, type ViewStyle } from "react-native";
 import { colors } from "./colors";
 import { Icon } from "./icon";
 import { Text } from "./text";
 import { pickFiles } from "./file_picker";
+import { FileDropTarget } from "./file_drop_target";
 import { FOCUS_RING } from "./control_surface";
 import { useFocusRing } from "./use_focus_ring";
 import { useLoticsLocale } from "./locale";
@@ -34,25 +35,18 @@ export interface FileDropzoneProps {
   style?: StyleProp<ViewStyle>;
 }
 
-function matchesAccept(file: File, accept: string | undefined): boolean {
-  if (!accept) return true;
-  const patterns = accept.split(",").map((p) => p.trim().toLowerCase()).filter(Boolean);
-  if (patterns.length === 0) return true;
-  const mime = file.type.toLowerCase();
-  const name = file.name.toLowerCase();
-  return patterns.some((p) => {
-    if (p.startsWith(".")) return name.endsWith(p);
-    if (p.endsWith("/*")) return mime.startsWith(p.slice(0, -1));
-    return mime === p;
-  });
-}
-
 /**
- * Drag-and-drop upload zone — the capture half of the file story (display =
- * FileThumbnailGrid/FilePreview, picking = pickFiles, which also backs this
- * zone's click). A dashed well with an icon + invitation; while a drag
- * hovers it, the zone lights up in the accent and the label flips to
- * `dropLabel`. On native (no drag events) it degrades to press-to-pick.
+ * Drag-and-drop upload zone — the dedicated capture well of the file story
+ * (display = FileThumbnailGrid/FilePreview, picking = pickFiles, which also
+ * backs this zone's click). A dashed well with an icon + invitation; while a
+ * drag hovers it, the zone lights up in the accent and the label flips to
+ * `dropLabel`. It is ALSO a paste sink while mounted — Ctrl/Cmd+V drops a
+ * copied file or a screenshot straight in, scoped to the zone's own region so
+ * it wins while it holds focus (or as the top surface in a dialog). On native
+ * (no drag events, no clipboard event) it degrades to press-to-pick.
+ *
+ * For a region that is not a well — a record's Files section, a card, a panel —
+ * use `FileDropTarget`, which this composes.
  */
 export function FileDropzone(props: FileDropzoneProps) {
   const locale = useLoticsLocale();
@@ -69,93 +63,54 @@ export function FileDropzone(props: FileDropzoneProps) {
     style,
   } = props;
 
-  const zoneRef = useRef<View>(null);
-  const dragDepth = useRef(0);
-  const [dragging, setDragging] = useState(false);
   const [hovered, setHovered] = useState(false);
   const { focusVisible, focusProps } = useFocusRing();
 
-  // RN-web exposes the View's underlying HTMLElement through the ref — attach
-  // the DOM drag events there. Native platforms skip this entirely (press-to-
-  // pick still works).
-  useEffect(() => {
-    if (disabled) return;
-    if (typeof HTMLElement === "undefined") return;
-    const node = zoneRef.current;
-    if (!(node instanceof HTMLElement)) return;
-
-    const onDragEnter = (e: DragEvent) => {
-      e.preventDefault();
-      dragDepth.current += 1;
-      setDragging(true);
-    };
-    const onDragOver = (e: DragEvent) => {
-      // preventDefault is what makes the element a legal drop target.
-      e.preventDefault();
-    };
-    const onDragLeave = () => {
-      dragDepth.current = Math.max(0, dragDepth.current - 1);
-      if (dragDepth.current === 0) setDragging(false);
-    };
-    const onDrop = (e: DragEvent) => {
-      e.preventDefault();
-      dragDepth.current = 0;
-      setDragging(false);
-      const dropped = Array.from(e.dataTransfer?.files ?? []).filter((f) => matchesAccept(f, accept));
-      if (dropped.length === 0) return;
-      onFiles(multiple ? dropped : dropped.slice(0, 1));
-    };
-
-    node.addEventListener("dragenter", onDragEnter);
-    node.addEventListener("dragover", onDragOver);
-    node.addEventListener("dragleave", onDragLeave);
-    node.addEventListener("drop", onDrop);
-    return () => {
-      node.removeEventListener("dragenter", onDragEnter);
-      node.removeEventListener("dragover", onDragOver);
-      node.removeEventListener("dragleave", onDragLeave);
-      node.removeEventListener("drop", onDrop);
-    };
-  }, [accept, disabled, multiple, onFiles]);
-
   const handlePick = async () => {
     if (disabled) return;
     const picked = await pickFiles({ accept, multiple });
     if (picked.length > 0) onFiles(picked);
   };
 
+  // The well draws its OWN drag state (the dashed border turns accent), so the
+  // target paints nothing — hence the function child. `paste` scopes the
+  // clipboard sink to THIS well's region, so a well inside a dialog takes the
+  // paste while it holds focus and peer wells don't fight over it.
   return (
-    <Pressable
-      ref={zoneRef}
-      accessibilityRole="button"
-      accessibilityLabel={accessibilityLabel ?? label}
-      disabled={disabled}
-      onPress={handlePick}
-      {...focusProps}
-      onHoverIn={() => setHovered(true)}
-      onHoverOut={() => setHovered(false)}
-      style={[
-        styles.zone,
-        { minHeight: height },
-        hovered && !dragging ? styles.zoneHovered : null,
-        dragging ? styles.zoneDragging : null,
-        disabled ? styles.zoneDisabled : null,
-        style,
-        focusVisible && { boxShadow: FOCUS_RING },
-      ]}
-    >
-      <View style={[styles.iconWell, dragging ? styles.iconWellDragging : null]}>
-        <Icon name="upload" size={20} color={dragging ? colors.blue[600] : colors.zinc[500]} />
-      </View>
-      <Text size="sm" weight="medium" style={dragging ? { color: colors.blue[700] } : undefined}>
-        {dragging ? dropLabel : label}
-      </Text>
-      {!dragging && hint ? (
-        <Text size="xs" color="muted">
-          {hint}
-        </Text>
-      ) : null}
-    </Pressable>
+    <FileDropTarget onFiles={onFiles} accept={accept} multiple={multiple} disabled={disabled} paste>
+      {(dragging) => (
+        <Pressable
+          accessibilityRole="button"
+          accessibilityLabel={accessibilityLabel ?? label}
+          disabled={disabled}
+          onPress={handlePick}
+          {...focusProps}
+          onHoverIn={() => setHovered(true)}
+          onHoverOut={() => setHovered(false)}
+          style={[
+            styles.zone,
+            { minHeight: height },
+            hovered && !dragging ? styles.zoneHovered : null,
+            dragging ? styles.zoneDragging : null,
+            disabled ? styles.zoneDisabled : null,
+            style,
+            focusVisible && { boxShadow: FOCUS_RING },
+          ]}
+        >
+          <View style={[styles.iconWell, dragging ? styles.iconWellDragging : null]}>
+            <Icon name="upload" size={20} color={dragging ? colors.blue[600] : colors.zinc[500]} />
+          </View>
+          <Text size="sm" weight="medium" style={dragging ? { color: colors.blue[700] } : undefined}>
+            {dragging ? dropLabel : label}
+          </Text>
+          {!dragging && hint ? (
+            <Text size="xs" color="muted">
+              {hint}
+            </Text>
+          ) : null}
+        </Pressable>
+      )}
+    </FileDropTarget>
   );
 }
 

package/src/file_intake.test.ts

@@ -0,0 +1,124 @@
+import { describe, it, expect } from "vitest";
+import { matchesAccept, filesFromTransfer, selectPasteSink, type FileTransferLike, type PasteSinkEntry } from "./file_intake";
+
+const file = (name: string, type: string) => new File([new Uint8Array([1])], name, { type });
+
+/** A clipboard/drag payload that surfaces its files only through `items` —
+ *  what a pasted screenshot looks like on the engines that do that. */
+const itemsOnly = (files: File[]): FileTransferLike => ({
+  files: [],
+  items: files.map((f) => ({ kind: "file" as const, getAsFile: () => f })),
+});
+
+describe("matchesAccept", () => {
+  it("accepts everything when the list is absent or empty", () => {
+    expect(matchesAccept(file("a.pdf", "application/pdf"), undefined)).toBe(true);
+    expect(matchesAccept(file("a.pdf", "application/pdf"), "")).toBe(true);
+    expect(matchesAccept(file("a.pdf", "application/pdf"), " , ")).toBe(true);
+  });
+
+  it("matches an exact MIME, case-insensitively", () => {
+    expect(matchesAccept(file("a.pdf", "APPLICATION/PDF"), "application/pdf")).toBe(true);
+    expect(matchesAccept(file("a.png", "image/png"), "application/pdf")).toBe(false);
+  });
+
+  it("matches a wildcard type", () => {
+    expect(matchesAccept(file("a.png", "image/png"), "image/*")).toBe(true);
+    expect(matchesAccept(file("a.pdf", "application/pdf"), "image/*")).toBe(false);
+  });
+
+  it("matches an extension pattern by filename when the MIME is unknown", () => {
+    expect(matchesAccept(file("Report.CSV", ""), ".csv")).toBe(true);
+    expect(matchesAccept(file("report.csvx", ""), ".csv")).toBe(false);
+  });
+
+  it("accepts a file matching ANY pattern in the list", () => {
+    expect(matchesAccept(file("a.png", "image/png"), "application/pdf, image/*")).toBe(true);
+    expect(matchesAccept(file("a.zip", "application/zip"), "application/pdf, image/*")).toBe(false);
+  });
+});
+
+describe("filesFromTransfer", () => {
+  it("returns [] for a missing transfer", () => {
+    expect(filesFromTransfer(null)).toEqual([]);
+    expect(filesFromTransfer(undefined)).toEqual([]);
+    expect(filesFromTransfer({})).toEqual([]);
+  });
+
+  it("reads the direct file list", () => {
+    const a = file("a.pdf", "application/pdf");
+    expect(filesFromTransfer({ files: [a] })).toEqual([a]);
+  });
+
+  it("falls back to clipboard items when the file list is empty", () => {
+    const shot = file("image.png", "image/png");
+    expect(filesFromTransfer(itemsOnly([shot]))).toEqual([shot]);
+  });
+
+  it("never doubles a file present in BOTH files and items", () => {
+    const a = file("a.png", "image/png");
+    expect(filesFromTransfer({ files: [a], items: [{ kind: "file", getAsFile: () => a }] })).toEqual([a]);
+  });
+
+  it("skips non-file clipboard items and null getAsFile results", () => {
+    const a = file("a.png", "image/png");
+    const transfer: FileTransferLike = {
+      items: [
+        { kind: "string", getAsFile: () => null },
+        { kind: "file", getAsFile: () => null },
+        { kind: "file", getAsFile: () => a },
+      ],
+    };
+    expect(filesFromTransfer(transfer)).toEqual([a]);
+  });
+
+  it("filters by accept", () => {
+    const pdf = file("a.pdf", "application/pdf");
+    const zip = file("a.zip", "application/zip");
+    expect(filesFromTransfer({ files: [pdf, zip] }, { accept: "application/pdf" })).toEqual([pdf]);
+    expect(filesFromTransfer(itemsOnly([pdf, zip]), { accept: "application/pdf" })).toEqual([pdf]);
+  });
+
+  it("keeps every file by default and caps at one when multiple is false", () => {
+    const a = file("a.pdf", "application/pdf");
+    const b = file("b.pdf", "application/pdf");
+    expect(filesFromTransfer({ files: [a, b] })).toEqual([a, b]);
+    expect(filesFromTransfer({ files: [a, b] }, { multiple: false })).toEqual([a]);
+  });
+
+  it("caps AFTER filtering, so a rejected first file does not eat the slot", () => {
+    const zip = file("a.zip", "application/zip");
+    const pdf = file("b.pdf", "application/pdf");
+    expect(filesFromTransfer({ files: [zip, pdf] }, { accept: "application/pdf", multiple: false })).toEqual([pdf]);
+  });
+});
+
+describe("selectPasteSink", () => {
+  const entry = (sink: string, focused: boolean): PasteSinkEntry<string> => ({ sink, focused });
+
+  it("returns undefined for an empty stack", () => {
+    expect(selectPasteSink<string>([])).toBeUndefined();
+  });
+
+  it("falls back to the TOP of the stack when nothing is focused", () => {
+    expect(selectPasteSink([entry("a", false), entry("b", false), entry("c", false)])).toBe("c");
+  });
+
+  it("routes to a focused region over the (later-mounted) top of the stack", () => {
+    // b holds focus; c is on top but unfocused — b wins.
+    expect(selectPasteSink([entry("a", false), entry("b", true), entry("c", false)])).toBe("b");
+  });
+
+  it("picks the TOP-MOST focused region when several are focused", () => {
+    // Nested regions can both contain activeElement; the innermost/last wins.
+    expect(selectPasteSink([entry("a", true), entry("b", true), entry("c", false)])).toBe("b");
+  });
+
+  it("a single region-less sink still gets the paste (byte-for-byte old behavior)", () => {
+    expect(selectPasteSink([entry("only", false)])).toBe("only");
+  });
+
+  it("a focused region beats an unfocused one mounted after it", () => {
+    expect(selectPasteSink([entry("focused", true), entry("later", false)])).toBe("focused");
+  });
+});