@djangocfg/ui-tools 2.1.411 → 2.1.413

package/src/tools/{Chat → chat}/composer/Composer.tsx

@@ -1,6 +1,6 @@
 'use client';
 
-import { forwardRef, useEffect, useRef } from 'react';
+import { forwardRef, useEffect, useRef, useState } from 'react';
 
 import { Textarea } from '@djangocfg/ui-core/components';
 import { cn } from '@djangocfg/ui-core/lib';
@@ -8,13 +8,16 @@ import { cn } from '@djangocfg/ui-core/lib';
 import { useChatContextOptional } from '../context';
 import type { UseChatComposerReturn } from '../hooks/useChatComposer';
 import { Attachments } from '../messages/Attachments';
+import { AttachProvider } from './AttachContext';
 import { ComposerActionBar } from './ComposerActionBar';
 import { ComposerButton } from './ComposerButton';
 import { ComposerFooter } from './ComposerFooter';
 import { ComposerSizeProvider } from './size-context';
 import { useComposerActions } from './useComposerActions';
+import { useComposerAttach } from './useComposerAttach';
 import type {
   ComposerAppearance,
+  ComposerAttachConfig,
   ComposerFooterProps,
   ComposerLayout,
   ComposerSize,
@@ -29,7 +32,16 @@ export interface ComposerProps {
   composer: UseChatComposerReturn;
   placeholder?: string;
   disabled?: boolean;
+  /** Render the paperclip attach button. The composer ships a built-in
+   *  file picker — paperclip, `+` menu, drag-drop and Ctrl+V paste all
+   *  funnel through one validated pipeline. */
   showAttachmentButton?: boolean;
+  /** Tune the built-in attach pipeline — accepted types, size / count
+   *  caps, paste, and the optional upload transport. */
+  attach?: ComposerAttachConfig;
+  /** Override the built-in file picker. When set, the paperclip and the
+   *  `+`-menu attach item call this instead of opening the native picker
+   *  — for hosts that drive their own (e.g. a Wails native dialog). */
   onPickFiles?: () => void;
   className?: string;
   textareaClassName?: string;
@@ -130,6 +142,7 @@ export const Composer = forwardRef<HTMLDivElement, ComposerProps>(function Compo
     placeholder = 'Type a message...',
     disabled,
     showAttachmentButton = false,
+    attach,
     onPickFiles,
     className,
     textareaClassName,
@@ -220,13 +233,60 @@ export const Composer = forwardRef<HTMLDivElement, ComposerProps>(function Compo
     editable.focus();
   };
 
+  // ── Attach pipeline ────────────────────────────────────────────────────
+  // The built-in file picker is mounted whenever the host renders the
+  // paperclip OR passes an `attach` config. `onPickFiles` (if given)
+  // overrides it — a host driving its own picker (e.g. a Wails dialog).
+  const attachEnabled = showAttachmentButton || attach != null;
+  const attachHandle = useComposerAttach({
+    composer,
+    config: attach ?? {},
+    disabled: isDisabled,
+    pasteScopeRef: surfaceRef,
+  });
+  // The resolved click handler: host override wins, else the built-in
+  // picker. `undefined` when attaching is not enabled at all.
+  const pickFiles = !attachEnabled
+    ? undefined
+    : (onPickFiles ?? attachHandle.openPicker);
+
+  // Drag-drop onto the input surface — same validated path as the picker.
+  const [isDragging, setIsDragging] = useState(false);
+  const dragDepth = useRef(0);
+  const handleDragEnter = (e: React.DragEvent) => {
+    if (!attachEnabled || isDisabled) return;
+    if (!e.dataTransfer.types.includes('Files')) return;
+    e.preventDefault();
+    dragDepth.current += 1;
+    setIsDragging(true);
+  };
+  const handleDragOver = (e: React.DragEvent) => {
+    if (attachEnabled && !isDisabled && e.dataTransfer.types.includes('Files')) {
+      e.preventDefault();
+    }
+  };
+  const handleDragLeave = (e: React.DragEvent) => {
+    if (!attachEnabled || isDisabled) return;
+    e.preventDefault();
+    dragDepth.current = Math.max(0, dragDepth.current - 1);
+    if (dragDepth.current === 0) setIsDragging(false);
+  };
+  const handleDrop = (e: React.DragEvent) => {
+    if (!attachEnabled || isDisabled) return;
+    e.preventDefault();
+    dragDepth.current = 0;
+    setIsDragging(false);
+    const dropped = Array.from(e.dataTransfer.files ?? []);
+    if (dropped.length > 0) attachHandle.attachFiles(dropped);
+  };
+
   // Merge built-in send/stop/attach descriptors with host arrays.
   const { actionsStart, actionsEnd } = useComposerActions({
     composer,
     isStreaming,
     isDisabled,
     showAttachmentButton,
-    onPickFiles,
+    onPickFiles: pickFiles,
     actionsStart: composerSlots?.actionsStart,
     actionsEnd: composerSlots?.actionsEnd,
     onSend: () => void composer.submit(),
@@ -311,11 +371,19 @@ export const Composer = forwardRef<HTMLDivElement, ComposerProps>(function Compo
       <AttachSlot
         disabled={isDisabled}
         size={size}
-        onClick={() => onPickFiles?.()}
+        onClick={() => pickFiles?.()}
         {...slotProps?.attach}
       />
     ) : null;
 
+  // Hidden native file input — the picker the paperclip + `+` menu open.
+  // Rendered once per composer; only present when the pipeline is active
+  // and no host override is in play (an override owns its own picker).
+  const hiddenFileInput =
+    attachEnabled && !onPickFiles ? (
+      <input {...attachHandle.inputProps} />
+    ) : null;
+
   // ── Footer ─────────────────────────────────────────────────────────────
   const footerNode =
     footer === false ? null : (
@@ -331,25 +399,53 @@ export const Composer = forwardRef<HTMLDivElement, ComposerProps>(function Compo
     (composer.attachments.length > 0 ? (
       <Attachments
         attachments={composer.attachments}
-        onRemove={(a) => composer.removeAttachment(a.id)}
+        // Route through the attach pipeline so a removed attachment's
+        // object-URL is revoked; falls back to a plain remove when the
+        // pipeline is not mounted (host-managed attachments).
+        onRemove={(a) =>
+          attachEnabled
+            ? attachHandle.removeAttachment(a.id)
+            : composer.removeAttachment(a.id)
+        }
       />
     ) : null);
 
   // ── Inline (compact single-row) layout ─────────────────────────────────
+  // Drag-drop handlers shared by both layouts. No-op when attaching is
+  // disabled — the handlers themselves early-return.
+  const dragProps = {
+    onDragEnter: handleDragEnter,
+    onDragOver: handleDragOver,
+    onDragLeave: handleDragLeave,
+    onDrop: handleDrop,
+  };
+  // A faint accent wash + ring while a file is dragged over the composer.
+  const dragOverlay =
+    isDragging ? (
+      <div
+        aria-hidden
+        className="pointer-events-none absolute inset-0 z-10 rounded-[inherit] bg-primary/5 ring-2 ring-inset ring-primary/40"
+      />
+    ) : null;
+
   // Start cluster sits left of the textarea, end cluster right of it —
   // `[📎][actionsStart] [textarea] [actionsEnd][🎙][▶]` (§3.6).
   if (layout === 'inline') {
     return (
       <ComposerSizeProvider value={size}>
+       <AttachProvider value={attachHandle}>
         <div
           ref={ref}
+          {...dragProps}
           className={cn(
-            'border-t border-border bg-background/95',
+            'relative border-t border-border bg-background/95',
             sz.containerPadding,
             ap.containerPadding,
             className,
           )}
         >
+          {hiddenFileInput}
+          {dragOverlay}
           {trayNode ? <div className="mb-1.5">{trayNode}</div> : null}
           <div
             className={cn(
@@ -385,6 +481,7 @@ export const Composer = forwardRef<HTMLDivElement, ComposerProps>(function Compo
           </div>
           {footerNode}
         </div>
+       </AttachProvider>
       </ComposerSizeProvider>
     );
   }
@@ -453,19 +550,24 @@ export const Composer = forwardRef<HTMLDivElement, ComposerProps>(function Compo
 
   return (
     <ComposerSizeProvider value={size}>
+     <AttachProvider value={attachHandle}>
       <div
         ref={ref}
+        {...dragProps}
         className={cn(
-          'border-t border-border bg-background/95',
+          'relative border-t border-border bg-background/95',
           sz.containerPadding,
           ap.containerPadding,
           className,
         )}
       >
+        {hiddenFileInput}
+        {dragOverlay}
         {trayNode ? <div className="mb-2">{trayNode}</div> : null}
         {surfaceWrapper}
         {footerNode}
       </div>
+     </AttachProvider>
     </ComposerSizeProvider>
   );
 });

package/src/tools/{Chat → chat}/composer/ComposerMenuButton.tsx

@@ -1,17 +1,32 @@
 'use client';
 
-import { Plus } from 'lucide-react';
+import { Paperclip, Plus } from 'lucide-react';
 
 import { MenuBuilder, type MenuItem } from '@djangocfg/ui-core/components';
 import { cn } from '@djangocfg/ui-core/lib';
 
+import { useComposerAttachContext } from './AttachContext';
 import { BUTTON_SIZE } from './ComposerButton';
 import { useResolvedComposerSize } from './size-context';
 import type { ComposerSize } from './types';
 
+/**
+ * Built-in "Attach" menu item config. When `attachItem` is set, the
+ * menu button prepends a row wired to the composer's attach pipeline —
+ * the SAME `openPicker` the paperclip button uses. Pass `true` for
+ * defaults, or an object to override the label / icon.
+ */
+export type ComposerMenuAttachItem =
+  | boolean
+  | { label?: string };
+
 export interface ComposerMenuButtonProps {
   /** Declarative menu tree (see `MenuBuilder`). */
   items: MenuItem[];
+  /** Prepend a built-in "Attach" row wired to the composer's attach
+   *  pipeline. Requires an attach-enabled `<Composer>` ancestor;
+   *  silently omitted otherwise. */
+  attachItem?: ComposerMenuAttachItem;
   /** Omit to inherit the composer's size. */
   size?: ComposerSize;
   disabled?: boolean;
@@ -30,15 +45,37 @@ export interface ComposerMenuButtonProps {
  */
 export function ComposerMenuButton({
   items,
+  attachItem,
   size,
   disabled,
   label = 'Add files and more',
   icon,
 }: ComposerMenuButtonProps) {
   const sz = BUTTON_SIZE[useResolvedComposerSize(size)];
+  const attach = useComposerAttachContext();
+
+  // Prepend the built-in "Attach" row when requested AND an attach
+  // pipeline is in scope — it reuses the exact same `openPicker` as the
+  // paperclip button, so both inputs are one unified path.
+  const attachLabel =
+    typeof attachItem === 'object' ? (attachItem.label ?? 'Attach files') : 'Attach files';
+  const resolvedItems: MenuItem[] =
+    attachItem && attach
+      ? [
+          {
+            kind: 'item',
+            id: '__composer_attach',
+            label: attachLabel,
+            icon: Paperclip,
+            disabled: attach.disabled,
+            onSelect: () => attach.openPicker(),
+          },
+          ...items,
+        ]
+      : items;
 
   return (
-    <MenuBuilder items={items} side="top" align="start">
+    <MenuBuilder items={resolvedItems} side="top" align="start">
       <button
         type="button"
         disabled={disabled}

package/src/tools/chat/composer/fileToAttachment.ts

@@ -0,0 +1,53 @@
+/**
+ * `File → ChatAttachment` — the engine-side producer that was missing.
+ *
+ * Before this, every host re-implemented the conversion (see the fake
+ * stub in `apps/storybook/.../SpeechAndAttachments`). It lives here so
+ * the picker, drag-drop and paste paths all mint identical attachments.
+ */
+
+import { createId } from '../core/ids';
+import { getAssetTypeFromMime } from '../../forms/Uploader';
+import type { ChatAttachment } from '../types';
+
+/** Map a MIME type to the `ChatAttachment.type` discriminant. */
+function attachmentTypeFromMime(mime: string): ChatAttachment['type'] {
+  if (mime.startsWith('image/')) return 'image';
+  if (mime.startsWith('audio/')) return 'audio';
+  if (mime.startsWith('video/')) return 'video';
+  // getAssetTypeFromMime returns 'document' for everything else; the
+  // ChatAttachment union has no 'document' member — collapse to 'file'.
+  const asset = getAssetTypeFromMime(mime);
+  return asset === 'document' ? 'file' : asset;
+}
+
+/**
+ * Convert a picked/dropped/pasted `File` into a `ChatAttachment`.
+ *
+ * The `url` is an object-URL (`URL.createObjectURL`) — instantly usable
+ * for previews. When a host uploads the file via `uploadFn`, it replaces
+ * `url` with the remote URL and flips `status` to `'ready'`.
+ *
+ * `status` defaults to `'ready'`: with no `uploadFn` the attachment is
+ * immediately usable (current behaviour). The attach pipeline overrides
+ * it to `'uploading'` when an upload is in flight.
+ */
+export function fileToAttachment(file: File): ChatAttachment {
+  const mime = file.type || 'application/octet-stream';
+  return {
+    id: createId('att'),
+    type: attachmentTypeFromMime(mime),
+    url: URL.createObjectURL(file),
+    name: file.name,
+    mimeType: mime,
+    sizeBytes: file.size,
+    status: 'ready',
+  };
+}
+
+/** Revoke an attachment's object-URL, if it holds one. Call on remove. */
+export function revokeAttachmentUrl(attachment: Pick<ChatAttachment, 'url'>): void {
+  if (attachment.url.startsWith('blob:')) {
+    URL.revokeObjectURL(attachment.url);
+  }
+}

package/src/tools/{Chat → chat}/composer/index.ts

@@ -9,7 +9,11 @@ export {
   type ComposerAppearance,
 } from './Composer';
 export { ComposerButton, BUTTON_SIZE, type ComposerButtonProps } from './ComposerButton';
-export { ComposerMenuButton, type ComposerMenuButtonProps } from './ComposerMenuButton';
+export {
+  ComposerMenuButton,
+  type ComposerMenuButtonProps,
+  type ComposerMenuAttachItem,
+} from './ComposerMenuButton';
 export { ComposerRichTextarea, type ComposerRichTextareaProps } from './ComposerRichTextarea';
 export { ComposerActionBar } from './ComposerActionBar';
 export { ComposerToolPill, type ComposerToolPillProps } from './ComposerToolPill';
@@ -30,6 +34,12 @@ export {
   type UseComposerActionsParams,
   type ComposerActionClusters,
 } from './useComposerActions';
+export {
+  useComposerAttach,
+  type UseComposerAttachParams,
+} from './useComposerAttach';
+export { useComposerAttachContext } from './AttachContext';
+export { fileToAttachment, revokeAttachmentUrl } from './fileToAttachment';
 export type {
   ComposerAction,
   ComposerActionVisibility,
@@ -42,4 +52,9 @@ export type {
   AttachButtonProps,
   ComposerTextareaProps,
   ActionBarProps,
+  ComposerAcceptType,
+  ComposerAttachConfig,
+  ComposerAttachHandle,
+  ComposerUploadFn,
+  ComposerUploadResult,
 } from './types';

package/src/tools/{Chat → chat}/composer/types.ts

@@ -3,6 +3,7 @@
 import type { ComponentType, ReactNode } from 'react';
 
 import type { UseChatComposerReturn } from '../hooks/useChatComposer';
+import type { ChatAttachment } from '../types';
 
 /** Composer visual size — shared across the `<Composer>` API. */
 export type ComposerSize = 'sm' | 'md' | 'lg';
@@ -141,3 +142,73 @@ export interface ComposerFooterProps {
   size?: ComposerSize;
   className?: string;
 }
+
+// ── Attach pipeline ─────────────────────────────────────────────────────────
+
+/** Asset categories the picker accepts. Maps to MIME prefixes / extensions. */
+export type ComposerAcceptType = 'image' | 'audio' | 'video' | 'document';
+
+/**
+ * Result a host's `uploadFn` resolves to — the remote location the
+ * attachment's `url` is rewritten to once the upload completes.
+ */
+export interface ComposerUploadResult {
+  url: string;
+  thumbnailUrl?: string;
+}
+
+/**
+ * Optional upload transport. The single environment-specific seam:
+ * - omitted  → attachments stay local (`blob:` object-URL, `status:'ready'`).
+ * - web      → multipart POST to a CDN.
+ * - Wails    → a Wails-bound upload method.
+ *
+ * `onProgress` receives 0..1; call it to drive the staging-tray progress.
+ */
+export type ComposerUploadFn = (
+  file: File,
+  onProgress: (fraction: number) => void,
+) => Promise<ComposerUploadResult>;
+
+/**
+ * Declarative config for the built-in attach pipeline. When present (or
+ * when `showAttachmentButton` is set), the composer mounts its own file
+ * picker — paperclip, `+` menu, drag-drop and paste all funnel through it.
+ */
+export interface ComposerAttachConfig {
+  /** Accepted asset categories. Default: all four. */
+  accept?: ComposerAcceptType[];
+  /** Max files per message. Falls back to the composer's `maxAttachments`. */
+  maxFiles?: number;
+  /** Per-file size cap in bytes. Default: unlimited. */
+  maxSizeBytes?: number;
+  /** Allow selecting more than one file at once. Default `true`. */
+  multiple?: boolean;
+  /** Upload transport — see {@link ComposerUploadFn}. */
+  uploadFn?: ComposerUploadFn;
+  /** Enable Ctrl+V / Cmd+V paste-to-attach. Default `true`. */
+  pasteEnabled?: boolean;
+  /** Called when a file is rejected (size / type / count). */
+  onReject?: (file: File, reason: 'size' | 'type' | 'count') => void;
+}
+
+/** Imperative handle the attach pipeline exposes to the composer + menu. */
+export interface ComposerAttachHandle {
+  /** Open the native file picker. */
+  openPicker: () => void;
+  /** Funnel already-resolved files (drop / paste) through validation. */
+  attachFiles: (files: File[]) => void;
+  /** Remove a staged attachment, revoking its object-URL first. */
+  removeAttachment: (id: string) => void;
+  /** True when attaching is unavailable (disabled / at file cap). */
+  disabled: boolean;
+  /** Hidden `<input type=file>` props — the composer renders this node. */
+  inputProps: {
+    ref: React.RefObject<HTMLInputElement | null>;
+    type: 'file';
+    accept: string;
+    multiple: boolean;
+    hidden: true;
+    onChange: (e: React.ChangeEvent<HTMLInputElement>) => void;
+  };
+}

package/src/tools/chat/composer/useComposerAttach.tsx

@@ -0,0 +1,218 @@
+'use client';
+
+import { useCallback, useEffect, useMemo, useRef, type RefObject } from 'react';
+
+import { buildAcceptString, useClipboardPaste } from '../../forms/Uploader';
+import type { UseChatComposerReturn } from '../hooks/useChatComposer';
+import { fileToAttachment, revokeAttachmentUrl } from './fileToAttachment';
+import type {
+  ComposerAcceptType,
+  ComposerAttachConfig,
+  ComposerAttachHandle,
+} from './types';
+
+const ALL_ACCEPT: ComposerAcceptType[] = ['image', 'audio', 'video', 'document'];
+
+/** True when a file's MIME is allowed by the accepted asset categories. */
+function isAcceptedType(file: File, accept: ComposerAcceptType[]): boolean {
+  const mime = file.type;
+  if (mime.startsWith('image/')) return accept.includes('image');
+  if (mime.startsWith('audio/')) return accept.includes('audio');
+  if (mime.startsWith('video/')) return accept.includes('video');
+  // No / other MIME — treat as a document.
+  return accept.includes('document');
+}
+
+export interface UseComposerAttachParams {
+  composer: UseChatComposerReturn;
+  config: ComposerAttachConfig;
+  disabled?: boolean;
+  /** Paste listener scope. Defaults to `document` when omitted. */
+  pasteScopeRef?: RefObject<HTMLElement | null>;
+}
+
+/**
+ * The unified attach pipeline. One validated path that the paperclip
+ * button, the `+` menu, drag-drop and Ctrl+V paste all funnel into:
+ *
+ *   openPicker() / attachFiles(File[])
+ *     → validate (size / type / count)
+ *     → fileToAttachment()
+ *     → composer.addAttachment()
+ *
+ * Phase 2 stops at `status:'ready'` (object-URL). The `uploadFn`
+ * lifecycle lands in phase 5 — `config.uploadFn` is accepted here but
+ * not yet consumed.
+ *
+ * Reuses `useClipboardPaste` + `buildAcceptString` from the Uploader
+ * tool rather than re-implementing clipboard / mime handling.
+ */
+export function useComposerAttach({
+  composer,
+  config,
+  disabled = false,
+  pasteScopeRef,
+}: UseComposerAttachParams): ComposerAttachHandle {
+  const {
+    accept = ALL_ACCEPT,
+    maxFiles,
+    maxSizeBytes,
+    multiple = true,
+    pasteEnabled = true,
+    uploadFn,
+    onReject,
+  } = config;
+
+  const inputRef = useRef<HTMLInputElement>(null);
+
+  // Stable refs so the paste listener / handlers never go stale without
+  // forcing the consumer to memoize anything.
+  const composerRef = useRef(composer);
+  composerRef.current = composer;
+  const onRejectRef = useRef(onReject);
+  onRejectRef.current = onReject;
+  const uploadFnRef = useRef(uploadFn);
+  uploadFnRef.current = uploadFn;
+
+  const acceptString = useMemo(() => {
+    // buildAcceptString expects the Uploader's AssetType — same string
+    // union as ComposerAcceptType, so the cast is safe.
+    return buildAcceptString(accept as Parameters<typeof buildAcceptString>[0]);
+  }, [accept]);
+
+  // Drive one file through the host `uploadFn`: flip the attachment to
+  // `uploading`, stream progress, then settle on `ready` (url rewritten
+  // to the remote location) or `error`. Fire-and-forget — failures are
+  // surfaced on the attachment, never thrown.
+  const runUpload = useCallback(
+    (file: File, attachmentId: string, localUrl: string) => {
+      const fn = uploadFnRef.current;
+      if (!fn) return;
+      const c = composerRef.current;
+      c.updateAttachment(attachmentId, { status: 'uploading', progress: 0 });
+      fn(file, (fraction) => {
+        composerRef.current.updateAttachment(attachmentId, {
+          progress: Math.max(0, Math.min(1, fraction)),
+        });
+      })
+        .then((result) => {
+          composerRef.current.updateAttachment(attachmentId, {
+            status: 'ready',
+            progress: 1,
+            url: result.url,
+            thumbnailUrl: result.thumbnailUrl,
+          });
+          // The remote URL replaced the object-URL — free it.
+          revokeAttachmentUrl({ url: localUrl });
+        })
+        .catch(() => {
+          composerRef.current.updateAttachment(attachmentId, { status: 'error' });
+        });
+    },
+    [],
+  );
+
+  // The single validated entry point. Drop / paste / picker all land here.
+  const attachFiles = useCallback(
+    (files: File[]) => {
+      if (disabled || files.length === 0) return;
+      const c = composerRef.current;
+      const cap = maxFiles ?? Number.POSITIVE_INFINITY;
+
+      let slots = cap - c.attachments.length;
+      for (const file of files) {
+        if (slots <= 0) {
+          onRejectRef.current?.(file, 'count');
+          continue;
+        }
+        if (maxSizeBytes != null && file.size > maxSizeBytes) {
+          onRejectRef.current?.(file, 'size');
+          continue;
+        }
+        if (!isAcceptedType(file, accept)) {
+          onRejectRef.current?.(file, 'type');
+          continue;
+        }
+        const attachment = fileToAttachment(file);
+        c.addAttachment(attachment);
+        // With an uploadFn the attachment starts local then uploads in
+        // the background; without one it stays `ready` immediately.
+        if (uploadFnRef.current) {
+          runUpload(file, attachment.id, attachment.url);
+        }
+        slots -= 1;
+      }
+    },
+    [disabled, maxFiles, maxSizeBytes, accept, runUpload],
+  );
+
+  const openPicker = useCallback(() => {
+    if (disabled) return;
+    inputRef.current?.click();
+  }, [disabled]);
+
+  // Remove a staged attachment, freeing its object-URL first so a
+  // discarded blob does not leak.
+  const removeAttachment = useCallback((id: string) => {
+    const c = composerRef.current;
+    const found = c.attachments.find((a) => a.id === id);
+    if (found) revokeAttachmentUrl(found);
+    c.removeAttachment(id);
+  }, []);
+
+  const onInputChange = useCallback(
+    (e: React.ChangeEvent<HTMLInputElement>) => {
+      const picked = e.target.files;
+      if (picked && picked.length > 0) attachFiles(Array.from(picked));
+      // Reset so picking the same file twice still fires `change`.
+      e.target.value = '';
+    },
+    [attachFiles],
+  );
+
+  // Ctrl+V / Cmd+V — reuse the Uploader's clipboard resolver. It already
+  // skips text fields when the clipboard carries text, so pasting an
+  // image into the composer textarea attaches without hijacking typing.
+  const pasteAccept = useMemo(
+    () => accept.filter((a) => a !== 'document'),
+    [accept],
+  );
+  useClipboardPaste(
+    {
+      enabled: pasteEnabled && !disabled,
+      acceptTypes: pasteAccept.length > 0 ? pasteAccept : undefined,
+      maxBytes: maxSizeBytes,
+      onFiles: attachFiles,
+    },
+    pasteScopeRef,
+  );
+
+  // On unmount, free any object-URLs still held by staged attachments
+  // (drafts abandoned without sending). `composerRef` gives the latest
+  // list without re-running the effect on every attach.
+  useEffect(() => {
+    return () => {
+      for (const a of composerRef.current.attachments) {
+        revokeAttachmentUrl(a);
+      }
+    };
+  }, []);
+
+  const atCap =
+    maxFiles != null && composer.attachments.length >= maxFiles;
+
+  return {
+    openPicker,
+    attachFiles,
+    removeAttachment,
+    disabled: disabled || atCap,
+    inputProps: {
+      ref: inputRef,
+      type: 'file',
+      accept: acceptString,
+      multiple,
+      hidden: true,
+      onChange: onInputChange,
+    },
+  };
+}