@lotics/ui 14.3.1 → 15.1.0

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");
+  });
+});

package/src/file_intake.ts

@@ -0,0 +1,148 @@
+// File INTAKE — the shared core behind every "a file arrived" path in the kit:
+// what counts as an acceptable file, and how to read files off a drag-drop or a
+// clipboard paste. Both payloads are a `DataTransfer`, so ONE extractor serves
+// the `drop` and the `paste` event; `FileDropzone`, `FileDropTarget` and
+// `usePasteFiles` all route through it and can never drift apart.
+//
+// Also the shared CONTRACT module for the two platform-split primitives
+// (`use_paste_files` / `file_drop_target`): their option and prop shapes live
+// here so the `.web` implementation and its native sibling declare them once.
+//
+// No react-native import — the components render this module's result, so the
+// logic stays unit-testable (Vitest cannot parse `react-native`).
+
+import type { ReactNode } from "react";
+import type { StyleProp, ViewStyle } from "react-native";
+
+/** The filter every intake path applies to what arrived. */
+export interface FileIntakeFilter {
+  /** Native `accept` filter (e.g. `"application/pdf,image/*"`) — matched against
+   *  the file's MIME type, or its extension for a `.ext` pattern. */
+  accept?: string;
+  /** Keep more than one file. Default true. */
+  multiple?: boolean;
+}
+
+/**
+ * The structural shape a `DataTransfer` satisfies — `DragEvent.dataTransfer`
+ * (a drop) and `ClipboardEvent.clipboardData` (a paste) are the same object.
+ * Declared structurally so the extractor is testable without a DOM.
+ */
+export interface FileTransferLike {
+  readonly files?: ArrayLike<File> | null;
+  readonly items?: ArrayLike<{ readonly kind: string; getAsFile: () => File | null }> | null;
+}
+
+/** The minimal ref shape `usePasteFiles`/`FileDropTarget` need to locate a
+ *  region — an RN `View` ref satisfies it (`useRef<View>(null)`); on web its
+ *  `.current` IS the region's DOM node. Declared structurally (readonly, so an
+ *  `RefObject<View | null>` assigns cleanly) to keep this module RN-free. */
+export interface RegionRef {
+  readonly current: unknown;
+}
+
+/** Options for `usePasteFiles` (`@lotics/ui/use_paste_files`). */
+export interface UsePasteFilesOptions extends FileIntakeFilter {
+  /** Receives the pasted files. Bytes/upload belong to the host. */
+  onFiles: (files: File[]) => void;
+  /** Subscribe only while true (default true) — scope the sink to "while this
+   *  surface is open" so a background screen never swallows a paste. */
+  enabled?: boolean;
+  /** The region this sink belongs to. When the paste happens while focus is
+   *  INSIDE this region, this sink wins over a later-mounted one (see
+   *  `selectPasteSink`). Omit for a region-less surface (a modal dialog) — the
+   *  sink then participates by stack order alone. */
+  region?: RegionRef;
+}
+
+/** Props for `FileDropTarget` (`@lotics/ui/file_drop_target`). */
+export interface FileDropTargetProps extends FileIntakeFilter {
+  /** Receives the dropped files. */
+  onFiles: (files: File[]) => void;
+  /** Also accept a clipboard PASTE, scoped to this region's focus: while focus
+   *  is inside the wrapped region, Ctrl/Cmd+V lands here. Wires `usePasteFiles`
+   *  with this region — so two peer file sections each win when focus is in
+   *  them, instead of the last-mounted one silently grabbing every paste. */
+  paste?: boolean;
+  /** Stop accepting drops/pastes (and drop the affordance). */
+  disabled?: boolean;
+  /**
+   * The region. A plain node lets the target paint the drag affordance itself;
+   * a FUNCTION receives the drag state and OWNS the visual (the target paints
+   * nothing) — how `FileDropzone` keeps its own well styling.
+   */
+  children: ReactNode | ((dragging: boolean) => ReactNode);
+  style?: StyleProp<ViewStyle>;
+}
+
+/**
+ * Does a file pass a native `accept` list? Each comma-separated pattern is an
+ * extension (`.pdf`), a wildcard type (`image/*`) or an exact MIME
+ * (`application/pdf`); an empty/absent list accepts everything.
+ */
+export 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;
+  });
+}
+
+/**
+ * The files a drop or a paste carries, filtered by `accept` and capped by
+ * `multiple`. Returns a new array; never throws on a missing/empty transfer.
+ */
+export function filesFromTransfer(
+  transfer: FileTransferLike | null | undefined,
+  filter: FileIntakeFilter = {},
+): File[] {
+  if (!transfer) return [];
+  // `files` carries a drop and most pastes. A pasted SCREENSHOT reaches some
+  // engines only through `items` (a `kind: "file"` entry), so fall back to it —
+  // never union the two, or an engine that populates both doubles every file.
+  const direct = transfer.files ? Array.from(transfer.files) : [];
+  const candidates =
+    direct.length > 0
+      ? direct
+      : Array.from(transfer.items ?? [])
+          .filter((item) => item.kind === "file")
+          .map((item) => item.getAsFile())
+          .filter((file): file is File => file !== null);
+
+  const accepted = candidates.filter((file) => matchesAccept(file, filter.accept));
+  return filter.multiple === false ? accepted.slice(0, 1) : accepted;
+}
+
+/** One registered paste sink for the routing decision: the payload to hand the
+ *  paste to, and whether its region currently contains focus. */
+export interface PasteSinkEntry<T> {
+  sink: T;
+  /** True when `document.activeElement` is inside this sink's region. A
+   *  region-less sink (a modal dialog) is always false — it routes by stack
+   *  order alone. */
+  focused: boolean;
+}
+
+/**
+ * Which sink gets the paste, given the active sinks in MOUNT order (oldest
+ * first, top of the stack last). The rule: the TOP-MOST focused region wins —
+ * so when two file targets are enabled on the same layer, the one the user is
+ * actually working in takes the file. With NO region focused it falls back to
+ * the top of the stack (the last-mounted surface), which is the right default
+ * for modal stacking (a dialog over a screen). Returns `undefined` for an empty
+ * stack.
+ *
+ * Pure so the DOM-free routing rule is unit-tested here; the `focused` flags are
+ * computed against live focus in the `.web` sink at dispatch time.
+ */
+export function selectPasteSink<T>(entries: readonly PasteSinkEntry<T>[]): T | undefined {
+  for (let i = entries.length - 1; i >= 0; i--) {
+    if (entries[i].focused) return entries[i].sink;
+  }
+  return entries.length > 0 ? entries[entries.length - 1].sink : undefined;
+}

package/src/locale.tsx

@@ -129,10 +129,19 @@ export interface LoticsLocale {
   scrollToBottom: { tooltip: string };
   /** `TextInputField`: the clear-button tooltip. */
   textInputField: { clear: string };
-  /** `AgentRun`: the reasoning disclosure's label (settled / streaming) and the
-   *  auto-built tool peek's Input / Error / Output panel titles. (Tool-step labels
-   *  and the "{n} steps" suffix stay prop-localized — `labelForTool` / `stepsLabel`.) */
-  agentRun: { thinking: string; thinkingStreaming: string; input: string; error: string; output: string };
+  /** `AgentRun`: the reasoning disclosure's label (settled / streaming), the
+   *  auto-built tool peek's Input / Error / Output panel titles, the `awaiting`
+   *  annotation on a call parked on a human decision, and the terminal error's
+   *  `retry` action. (Tool-step labels and the "{n} steps" suffix stay
+   *  prop-localized — `labelForCall` / `stepsLabel`.) */
+  agentRun: { thinking: string; thinkingStreaming: string; input: string; error: string; output: string; awaiting: string; retry: string };
+  /** `ApprovalPrompt`: the default prompt line (overridable per instance) and
+   *  the Approve / Deny button labels — the surface that ANSWERS `AgentRun`'s
+   *  read-only `awaiting` row (approve/deny = the ai-sdk approval vocabulary). */
+  approvalPrompt: { message: string; approve: string; deny: string };
+  /** `MessageActions`: the copy tooltip + its flipped "copied" confirmation, the
+   *  regenerate and edit tooltips, and the branch pager's prev/next names. */
+  messageActions: { copy: string; copied: string; regenerate: string; edit: string; previousVersion: string; nextVersion: string };
 }
 
 /** The platform default — English. Every component's hardcoded default lives
@@ -221,14 +230,16 @@ export const en: LoticsLocale = {
   chart: { noData: "No data", total: "Total" },
   composer: { send: "Send", stop: "Stop" },
   overlay: { close: "Close" },
-  fileDropzone: { label: "Drag files here", hint: "or click to browse", drop: "Drop to upload" },
+  fileDropzone: { label: "Drag files here", hint: "or click, or paste (⌘V)", drop: "Drop to upload" },
   fileThumbnail: { remove: "Remove" },
   imageGallery: { empty: "No images.", rotateLeft: "Rotate left", rotateRight: "Rotate right", zoom: "Zoom image" },
   infoPopover: { more: "More information" },
   matrix: { total: "Total", less: "Less", more: "More" },
   scrollToBottom: { tooltip: "Scroll to bottom" },
   textInputField: { clear: "Clear" },
-  agentRun: { thinking: "Thinking", thinkingStreaming: "Thinking…", input: "Input", error: "Error", output: "Output" },
+  agentRun: { thinking: "Thinking", thinkingStreaming: "Thinking…", input: "Input", error: "Error", output: "Output", awaiting: "Awaiting", retry: "Retry" },
+  approvalPrompt: { message: "The assistant wants to perform an action that needs your approval.", approve: "Approve", deny: "Deny" },
+  messageActions: { copy: "Copy", copied: "Copied", regenerate: "Regenerate", edit: "Edit", previousVersion: "Previous version", nextVersion: "Next version" },
 };
 
 /** Vietnamese. Maintained once here so every app (and the frontend) shares one
@@ -317,14 +328,16 @@ export const vi: LoticsLocale = {
   chart: { noData: "Không có dữ liệu", total: "Tổng" },
   composer: { send: "Gửi", stop: "Dừng" },
   overlay: { close: "Đóng" },
-  fileDropzone: { label: "Kéo tệp vào đây", hint: "hoặc bấm để chọn", drop: "Thả để tải lên" },
+  fileDropzone: { label: "Kéo tệp vào đây", hint: "hoặc bấm chọn, hoặc dán (Ctrl+V)", drop: "Thả để tải lên" },
   fileThumbnail: { remove: "Xóa" },
   imageGallery: { empty: "Chưa có ảnh.", rotateLeft: "Xoay trái", rotateRight: "Xoay phải", zoom: "Phóng to ảnh" },
   infoPopover: { more: "Thông tin thêm" },
   matrix: { total: "Tổng", less: "Ít", more: "Nhiều" },
   scrollToBottom: { tooltip: "Cuộn xuống cuối" },
   textInputField: { clear: "Xóa" },
-  agentRun: { thinking: "Suy nghĩ", thinkingStreaming: "Đang suy nghĩ…", input: "Đầu vào", error: "Lỗi", output: "Kết quả" },
+  agentRun: { thinking: "Suy nghĩ", thinkingStreaming: "Đang suy nghĩ…", input: "Đầu vào", error: "Lỗi", output: "Kết quả", awaiting: "Chờ duyệt", retry: "Thử lại" },
+  approvalPrompt: { message: "Trợ lý muốn thực hiện thao tác cần bạn duyệt.", approve: "Cho phép", deny: "Từ chối" },
+  messageActions: { copy: "Sao chép", copied: "Đã sao chép", regenerate: "Tạo lại", edit: "Chỉnh sửa", previousVersion: "Phiên bản trước", nextVersion: "Phiên bản sau" },
 };
 
 const LoticsLocaleContext = createContext<LoticsLocale>(en);