From dd0377d3a9a39f6010c53bb8bfdfa63641ebb075 Mon Sep 17 00:00:00 2001
From: Kresna <kresna@usetada.com>
Date: Sat, 8 Aug 2026 14:40:14 +0700
Subject: [PATCH] feat(dev): Clipboard Inspector tool
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Inspect and save whatever is on the clipboard — text, HTML, images,
video, audio, and any file type:

- Read Clipboard button: uses navigator.clipboard.read() for text,
  HTML, and images (browser may prompt for clipboard-read permission)
- Paste zone (Cmd/Ctrl+V): captures any content via the paste event,
  including video and audio files copied from the file manager
- Session history: every read/paste is kept as a snapshot with a
  source badge, timestamp, and per-item preview + Save button
- Previews: <pre> for text, sandboxed <iframe> + source toggle for HTML,
  <img> for images, <video controls> for video, <audio controls> for
  audio, file info + download for binary/PDF
- Save to disk: per-item download via downloadService
- Memory-safe: blob URLs are revoked on entry removal and on unmount

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 src/islands/dev/ClipboardInspector.tsx | 301 +++++++++++++++++++++++++
 src/registry/tools.ts                  |  13 +-
 src/tools/dev/clipboard.lib.test.ts    | 138 ++++++++++++
 src/tools/dev/clipboard.lib.ts         | 144 ++++++++++++
 4 files changed, 595 insertions(+), 1 deletion(-)
 create mode 100644 src/islands/dev/ClipboardInspector.tsx
 create mode 100644 src/tools/dev/clipboard.lib.test.ts
 create mode 100644 src/tools/dev/clipboard.lib.ts

diff --git a/src/islands/dev/ClipboardInspector.tsx b/src/islands/dev/ClipboardInspector.tsx
new file mode 100644
index 0000000..41c7b14
--- /dev/null
+++ b/src/islands/dev/ClipboardInspector.tsx
@@ -0,0 +1,301 @@
+import { useEffect, useRef, useState } from 'react';
+import { ClipboardPaste, Download, Trash2, RefreshCw, FileVideo, FileAudio, FileImage, FileText, File, Code } from 'lucide-react';
+import { Button } from '@/components/ui/Button';
+import { Alert } from '@/components/ui/Alert';
+import {
+  readClipboard, parseDataTransfer, previewKindOf, formatSize, mimeToExtension,
+  type ClipboardSnapshot, type ClipboardItemEntry, type PreviewKind,
+} from '@/tools/dev/clipboard.lib';
+import { downloadService } from '@/services/download.service';
+import type { Lang } from '@/i18n/config';
+
+let _snapshotCounter = 0;
+
+const KIND_ICON: Record<PreviewKind, React.ElementType> = {
+  text: FileText,
+  html: Code,
+  image: FileImage,
+  video: FileVideo,
+  audio: FileAudio,
+  pdf: File,
+  binary: File,
+};
+
+const KIND_LABEL: Record<PreviewKind, string> = {
+  text: 'Text',
+  html: 'HTML',
+  image: 'Image',
+  video: 'Video',
+  audio: 'Audio',
+  pdf: 'PDF',
+  binary: 'Binary',
+};
+
+function TypeBadge({ kind, type }: { kind: PreviewKind; type: string }) {
+  const Icon = KIND_ICON[kind];
+  const colors: Record<PreviewKind, string> = {
+    text:   'bg-blue-100 text-blue-800 dark:bg-blue-900/40 dark:text-blue-300',
+    html:   'bg-orange-100 text-orange-800 dark:bg-orange-900/40 dark:text-orange-300',
+    image:  'bg-green-100 text-green-800 dark:bg-green-900/40 dark:text-green-300',
+    video:  'bg-purple-100 text-purple-800 dark:bg-purple-900/40 dark:text-purple-300',
+    audio:  'bg-pink-100 text-pink-800 dark:bg-pink-900/40 dark:text-pink-300',
+    pdf:    'bg-red-100 text-red-800 dark:bg-red-900/40 dark:text-red-300',
+    binary: 'bg-muted text-muted-foreground',
+  };
+  return (
+    <span className={`inline-flex items-center gap-1 px-2 py-0.5 text-xs font-semibold rounded ${colors[kind]}`}>
+      <Icon className="h-3 w-3" />
+      {KIND_LABEL[kind]}
+      <span className="opacity-60 font-normal">{type}</span>
+    </span>
+  );
+}
+
+function ItemPreview({ item }: { item: ClipboardItemEntry }) {
+  const [showHtml, setShowHtml] = useState<'source' | 'render'>('render');
+
+  function handleDownload() {
+    const ext = item.filename
+      ? item.filename.split('.').pop() ?? mimeToExtension(item.type)
+      : mimeToExtension(item.type);
+    const name = item.filename ?? `clipboard.${ext}`;
+    if (item.blobUrl) {
+      downloadService.download(item.blobUrl, name);
+    } else if (item.text != null) {
+      const blob = new Blob([item.text], { type: item.type });
+      const url = URL.createObjectURL(blob);
+      downloadService.download(url, name);
+      setTimeout(() => URL.revokeObjectURL(url), 5000);
+    }
+  }
+
+  return (
+    <div className="border-2 border-border bg-background">
+      {/* Item header */}
+      <div className="flex items-center justify-between gap-2 px-3 py-2 bg-muted border-b-2 border-border">
+        <div className="flex items-center gap-2 min-w-0">
+          <TypeBadge kind={item.kind} type={item.type} />
+          <span className="text-xs text-muted-foreground shrink-0">
+            {formatSize(item.size)}
+            {item.filename && <> · {item.filename}</>}
+          </span>
+        </div>
+        <div className="flex items-center gap-1 shrink-0">
+          {item.kind === 'html' && (
+            <button
+              onClick={() => setShowHtml(v => v === 'render' ? 'source' : 'render')}
+              className="text-xs px-2 py-1 border-2 border-border hover:bg-muted"
+            >
+              {showHtml === 'render' ? 'Source' : 'Render'}
+            </button>
+          )}
+          <Button variant="secondary" onClick={handleDownload} title="Save to disk">
+            <Download className="h-3.5 w-3.5" />
+            Save
+          </Button>
+        </div>
+      </div>
+
+      {/* Preview */}
+      <div className="p-3">
+        {item.kind === 'text' && (
+          <pre className="text-sm whitespace-pre-wrap break-all max-h-48 overflow-y-auto font-mono leading-relaxed">
+            {item.text}
+          </pre>
+        )}
+
+        {item.kind === 'html' && showHtml === 'render' && (
+          <iframe
+            srcDoc={item.text}
+            sandbox=""
+            className="w-full border-0 min-h-[120px] max-h-64 bg-white dark:bg-zinc-900"
+            title="HTML preview"
+          />
+        )}
+        {item.kind === 'html' && showHtml === 'source' && (
+          <pre className="text-xs whitespace-pre-wrap break-all max-h-48 overflow-y-auto font-mono leading-relaxed text-muted-foreground">
+            {item.text}
+          </pre>
+        )}
+
+        {item.kind === 'image' && item.blobUrl && (
+          <img src={item.blobUrl} alt="Clipboard image" className="max-w-full max-h-80 object-contain" />
+        )}
+
+        {item.kind === 'video' && item.blobUrl && (
+          <video
+            src={item.blobUrl}
+            controls
+            className="max-w-full max-h-80"
+            preload="metadata"
+          />
+        )}
+
+        {item.kind === 'audio' && item.blobUrl && (
+          <audio src={item.blobUrl} controls className="w-full" preload="metadata" />
+        )}
+
+        {(item.kind === 'pdf' || item.kind === 'binary') && (
+          <p className="text-sm text-muted-foreground">
+            {item.filename ?? item.type} — {formatSize(item.size)}
+            <br />
+            <span className="text-xs">Use Save to download this file.</span>
+          </p>
+        )}
+      </div>
+    </div>
+  );
+}
+
+function SnapshotCard({ snapshot, onRemove }: { snapshot: ClipboardSnapshot; onRemove: () => void }) {
+  const time = new Date(snapshot.timestamp).toLocaleTimeString(undefined, {
+    hour: '2-digit', minute: '2-digit', second: '2-digit',
+  });
+  return (
+    <div className="border-2 border-border space-y-0">
+      <div className="flex items-center justify-between gap-2 px-3 py-2 bg-muted border-b-2 border-border">
+        <div className="flex items-center gap-2">
+          <span className={`text-xs font-bold px-2 py-0.5 ${
+            snapshot.source === 'paste'
+              ? 'bg-foreground text-background'
+              : 'bg-border text-foreground'
+          }`}>
+            {snapshot.source === 'paste' ? 'PASTE' : 'READ'}
+          </span>
+          <span className="text-xs text-muted-foreground font-mono">{time}</span>
+          <span className="text-xs text-muted-foreground">
+            {snapshot.items.length} item{snapshot.items.length !== 1 ? 's' : ''}
+          </span>
+        </div>
+        <button onClick={onRemove} title="Remove" className="text-muted-foreground hover:text-foreground">
+          <Trash2 className="h-3.5 w-3.5" />
+        </button>
+      </div>
+      <div className="p-3 space-y-3">
+        {snapshot.items.map((item, i) => (
+          <ItemPreview key={i} item={item} />
+        ))}
+      </div>
+    </div>
+  );
+}
+
+export default function ClipboardInspector({ lang: _lang = 'en' }: { lang?: Lang }) {
+  const [snapshots, setSnapshots] = useState<ClipboardSnapshot[]>([]);
+  const [error, setError] = useState('');
+  const [reading, setReading] = useState(false);
+  const blobUrls = useRef<Set<string>>(new Set());
+
+  function trackUrls(items: ClipboardItemEntry[]) {
+    items.forEach(i => { if (i.blobUrl) blobUrls.current.add(i.blobUrl); });
+  }
+
+  function addSnapshot(source: ClipboardSnapshot['source'], items: ClipboardItemEntry[]) {
+    if (!items.length) return;
+    trackUrls(items);
+    const snap: ClipboardSnapshot = {
+      id: String(++_snapshotCounter),
+      timestamp: Date.now(),
+      source,
+      items,
+    };
+    setSnapshots(prev => [snap, ...prev]);
+  }
+
+  function removeSnapshot(id: string) {
+    setSnapshots(prev => {
+      const snap = prev.find(s => s.id === id);
+      snap?.items.forEach(i => {
+        if (i.blobUrl) { URL.revokeObjectURL(i.blobUrl); blobUrls.current.delete(i.blobUrl); }
+      });
+      return prev.filter(s => s.id !== id);
+    });
+  }
+
+  function clearAll() {
+    blobUrls.current.forEach(u => URL.revokeObjectURL(u));
+    blobUrls.current.clear();
+    setSnapshots([]);
+  }
+
+  async function handleRead() {
+    setError('');
+    setReading(true);
+    try {
+      const items = await readClipboard();
+      if (!items.length) setError('Clipboard appears empty or no readable content was found.');
+      else addSnapshot('read', items);
+    } catch (e: unknown) {
+      const msg = e instanceof Error ? e.message : String(e);
+      if (msg.includes('denied') || msg.includes('permission')) {
+        setError('Clipboard access was denied. Please allow clipboard access when the browser asks.');
+      } else {
+        setError(`Could not read clipboard: ${msg}`);
+      }
+    } finally {
+      setReading(false);
+    }
+  }
+
+  useEffect(() => {
+    function onPaste(e: ClipboardEvent) {
+      if (!e.clipboardData) return;
+      e.preventDefault();
+      const items = parseDataTransfer(e.clipboardData);
+      if (!items.length) setError('No readable content found in this paste.');
+      else { setError(''); addSnapshot('paste', items); }
+    }
+    document.addEventListener('paste', onPaste);
+    return () => document.removeEventListener('paste', onPaste);
+  }, []);
+
+  useEffect(() => {
+    return () => {
+      blobUrls.current.forEach(u => URL.revokeObjectURL(u));
+    };
+  }, []);
+
+  return (
+    <div className="space-y-4">
+      {/* Controls */}
+      <div className="flex flex-wrap items-center gap-3">
+        <Button variant="primary" onClick={handleRead} disabled={reading}>
+          <RefreshCw className={`h-4 w-4 ${reading ? 'animate-spin' : ''}`} />
+          Read Clipboard
+        </Button>
+        {snapshots.length > 0 && (
+          <Button variant="secondary" onClick={clearAll}>
+            <Trash2 className="h-4 w-4" />
+            Clear All
+          </Button>
+        )}
+      </div>
+
+      {/* Paste zone hint */}
+      <div className="border-2 border-dashed border-border p-4 text-center space-y-1">
+        <ClipboardPaste className="h-6 w-6 mx-auto text-muted-foreground" />
+        <p className="text-sm font-medium">Press <kbd className="px-1.5 py-0.5 border-2 border-border font-mono text-xs">⌘V</kbd> / <kbd className="px-1.5 py-0.5 border-2 border-border font-mono text-xs">Ctrl+V</kbd> anywhere on this page</p>
+        <p className="text-xs text-muted-foreground">
+          Paste captures any content — including video, audio, and files copied from your file manager.
+          <br />
+          <strong>Read Clipboard</strong> works for text, HTML, and images without pressing paste.
+        </p>
+      </div>
+
+      {error && <Alert variant="error">{error}</Alert>}
+
+      {/* Snapshots */}
+      {snapshots.length === 0 && !error && (
+        <p className="text-sm text-muted-foreground text-center py-6">
+          No clipboard contents yet — hit <strong>Read Clipboard</strong> or press <strong>⌘V / Ctrl+V</strong>.
+        </p>
+      )}
+
+      <div className="space-y-4">
+        {snapshots.map(snap => (
+          <SnapshotCard key={snap.id} snapshot={snap} onRemove={() => removeSnapshot(snap.id)} />
+        ))}
+      </div>
+    </div>
+  );
+}
diff --git a/src/registry/tools.ts b/src/registry/tools.ts
index 588f06d..2a8572d 100644
--- a/src/registry/tools.ts
+++ b/src/registry/tools.ts
@@ -1,4 +1,4 @@
-import { Hash, Braces, Binary, Link, KeyRound, Fingerprint, KeySquare, FileDiff, Table, FileText, QrCode, ScanLine, Clock, Calculator, Palette, FilePlus2, Scissors, RotateCw, FileImage, FileX, Stamp, Image, Replace, Minimize2, Maximize2, Eraser, Archive, Lock, Unlock, Crop, Droplet, PenTool, Combine, ShieldCheck, FileCode, FileCode2, FileCog, FileArchive, FolderArchive, Sparkles, ScanFace, Scaling, Aperture, Wand2, PenLine, Shapes, Film, FileVideo, Music, AudioLines, MonitorPlay, Camera, Code2, Database, Keyboard, Contrast, Eye, ScanText, Receipt, Webcam, Mic, Send, Video, Wrench, Compass, Map, Waypoints, ImageDown, ScrollText, Ghost, FileSpreadsheet, BookOpen, FileType2, FileDown, GitCompare, FileOutput, CalendarClock } from 'lucide-react';
+import { Hash, Braces, Binary, Link, KeyRound, Fingerprint, KeySquare, FileDiff, Table, FileText, QrCode, ScanLine, Clock, Calculator, Palette, FilePlus2, Scissors, RotateCw, FileImage, FileX, Stamp, Image, Replace, Minimize2, Maximize2, Eraser, Archive, Lock, Unlock, Crop, Droplet, PenTool, Combine, ShieldCheck, FileCode, FileCode2, FileCog, FileArchive, FolderArchive, Sparkles, ScanFace, Scaling, Aperture, Wand2, PenLine, Shapes, Film, FileVideo, Music, AudioLines, MonitorPlay, Camera, Code2, Database, Keyboard, Contrast, Eye, ScanText, Receipt, Webcam, Mic, Send, Video, Wrench, Compass, Map, Waypoints, ImageDown, ScrollText, Ghost, FileSpreadsheet, BookOpen, FileType2, FileDown, GitCompare, FileOutput, CalendarClock, ClipboardPaste } from 'lucide-react';
 import type { ToolDef } from '@/types/tool';
 
 export const tools: ToolDef[] = [
@@ -190,6 +190,17 @@ export const tools: ToolDef[] = [
     load: () => import('@/islands/dev/CronExplainer'),
     status: 'beta'
   },
+  {
+    id: 'clipboard-inspector',
+    name: 'Clipboard Inspector',
+    category: 'Dev',
+    route: '/tools/clipboard-inspector',
+    keywords: ['clipboard', 'paste', 'copy', 'inspect', 'viewer', 'image', 'video', 'audio', 'text', 'html', 'file', 'binary', 'content'],
+    icon: ClipboardPaste,
+    summary: 'Inspect and save clipboard contents — text, images, video, audio, and files',
+    load: () => import('@/islands/dev/ClipboardInspector'),
+    status: 'beta'
+  },
   {
     id: 'docx-viewer',
     name: 'Word (DOCX) Viewer',
diff --git a/src/tools/dev/clipboard.lib.test.ts b/src/tools/dev/clipboard.lib.test.ts
new file mode 100644
index 0000000..edc4cd2
--- /dev/null
+++ b/src/tools/dev/clipboard.lib.test.ts
@@ -0,0 +1,138 @@
+import { describe, it, expect } from 'vitest';
+import {
+  previewKindOf, formatSize, mimeToExtension, parseDataTransfer,
+} from './clipboard.lib';
+
+// ─── previewKindOf ────────────────────────────────────────────────────────────
+
+describe('previewKindOf', () => {
+  it.each([
+    ['text/plain',          'text'],
+    ['text/html',           'html'],
+    ['image/png',           'image'],
+    ['image/jpeg',          'image'],
+    ['image/gif',           'image'],
+    ['image/webp',          'image'],
+    ['video/mp4',           'video'],
+    ['video/webm',          'video'],
+    ['audio/mpeg',          'audio'],
+    ['audio/wav',           'audio'],
+    ['application/pdf',     'pdf'],
+    ['application/zip',     'binary'],
+    ['application/octet-stream', 'binary'],
+    ['text/csv',            'binary'],
+  ] as const)('%s → %s', (mime, expected) => {
+    expect(previewKindOf(mime)).toBe(expected);
+  });
+
+  it('handles MIME types with parameters', () => {
+    expect(previewKindOf('text/plain; charset=utf-8')).toBe('text');
+    expect(previewKindOf('image/png; name=foo.png')).toBe('image');
+  });
+});
+
+// ─── formatSize ──────────────────────────────────────────────────────────────
+
+describe('formatSize', () => {
+  it.each([
+    [0,          '0 B'],
+    [512,        '512 B'],
+    [1023,       '1023 B'],
+    [1024,       '1.0 KB'],
+    [1536,       '1.5 KB'],
+    [1048576,    '1.0 MB'],
+    [1572864,    '1.5 MB'],
+  ])('%i bytes → %s', (bytes, expected) => {
+    expect(formatSize(bytes)).toBe(expected);
+  });
+});
+
+// ─── mimeToExtension ──────────────────────────────────────────────────────────
+
+describe('mimeToExtension', () => {
+  it.each([
+    ['text/plain',   'txt'],
+    ['text/html',    'html'],
+    ['image/png',    'png'],
+    ['image/jpeg',   'jpg'],
+    ['video/mp4',    'mp4'],
+    ['audio/mpeg',   'mp3'],
+    ['application/pdf', 'pdf'],
+    ['application/octet-stream', 'octet-stream'],
+  ])('%s → %s', (mime, ext) => {
+    expect(mimeToExtension(mime)).toBe(ext);
+  });
+});
+
+// ─── parseDataTransfer ───────────────────────────────────────────────────────
+
+function makeDataTransfer(items: { kind: 'string' | 'file'; type: string; value: string | File }[]): DataTransfer {
+  const dtItems: DataTransferItem[] = items.map(({ kind, type, value }) => ({
+    kind,
+    type,
+    getAsFile: () => (kind === 'file' ? (value as File) : null),
+    getAsString: () => {},
+    webkitGetAsEntry: () => null,
+  } as unknown as DataTransferItem));
+
+  const types = items.map(i => (i.kind === 'file' ? 'Files' : i.type));
+  const stringMap = new Map(
+    items.filter(i => i.kind === 'string').map(i => [i.type, i.value as string]),
+  );
+
+  return {
+    items: dtItems as unknown as DataTransferItemList,
+    files: { length: 0 } as unknown as FileList,
+    types,
+    getData: (t: string) => stringMap.get(t) ?? '',
+  } as unknown as DataTransfer;
+}
+
+describe('parseDataTransfer', () => {
+  it('extracts plain text', () => {
+    const dt = makeDataTransfer([{ kind: 'string', type: 'text/plain', value: 'hello world' }]);
+    const result = parseDataTransfer(dt);
+    expect(result).toHaveLength(1);
+    expect(result[0].kind).toBe('text');
+    expect(result[0].text).toBe('hello world');
+    expect(result[0].type).toBe('text/plain');
+  });
+
+  it('extracts HTML alongside plain text, deduplicates types', () => {
+    const dt = makeDataTransfer([
+      { kind: 'string', type: 'text/plain', value: 'plain' },
+      { kind: 'string', type: 'text/html', value: '<b>bold</b>' },
+    ]);
+    const result = parseDataTransfer(dt);
+    expect(result).toHaveLength(2);
+    expect(result.find(r => r.kind === 'html')?.text).toBe('<b>bold</b>');
+  });
+
+  it('extracts a file item and creates a blobUrl placeholder', () => {
+    // jsdom doesn't implement URL.createObjectURL — stub it
+    (globalThis as Record<string, unknown>).URL = {
+      createObjectURL: () => 'blob:mock',
+      revokeObjectURL: () => {},
+    };
+    const file = new File(['data'], 'clip.mp4', { type: 'video/mp4' });
+    const dt = makeDataTransfer([{ kind: 'file', type: 'video/mp4', value: file }]);
+    const result = parseDataTransfer(dt);
+    expect(result).toHaveLength(1);
+    expect(result[0].kind).toBe('video');
+    expect(result[0].blobUrl).toBeDefined();
+    expect(result[0].filename).toBe('clip.mp4');
+  });
+
+  it('returns empty array for empty DataTransfer', () => {
+    const dt = makeDataTransfer([]);
+    expect(parseDataTransfer(dt)).toHaveLength(0);
+  });
+
+  it('deduplicates entries with the same MIME type', () => {
+    const dt = makeDataTransfer([
+      { kind: 'string', type: 'text/plain', value: 'a' },
+      { kind: 'string', type: 'text/plain', value: 'b' },
+    ]);
+    expect(parseDataTransfer(dt)).toHaveLength(1);
+  });
+});
diff --git a/src/tools/dev/clipboard.lib.ts b/src/tools/dev/clipboard.lib.ts
new file mode 100644
index 0000000..77dc71d
--- /dev/null
+++ b/src/tools/dev/clipboard.lib.ts
@@ -0,0 +1,144 @@
+/**
+ * Clipboard Inspector — reads the system clipboard via the Clipboard API
+ * and paste events, returning typed, previewable entries.
+ *
+ * Two paths:
+ *  - navigator.clipboard.read()  → text, HTML, images (needs permission)
+ *  - DataTransfer from paste evt → any file type (video, audio, binary…)
+ */
+
+export type PreviewKind = 'text' | 'html' | 'image' | 'video' | 'audio' | 'pdf' | 'binary';
+
+export interface ClipboardItemEntry {
+  /** MIME type reported by the clipboard / file */
+  type: string;
+  kind: PreviewKind;
+  /** Populated for text/plain and text/html */
+  text?: string;
+  /** Populated for binary types — caller owns this URL and must revoke it */
+  blobUrl?: string;
+  size: number;
+  /** Set when the item originated from a file (paste of a file from disk) */
+  filename?: string;
+}
+
+export interface ClipboardSnapshot {
+  id: string;
+  timestamp: number;
+  source: 'read' | 'paste';
+  items: ClipboardItemEntry[];
+}
+
+// ─── Utilities ────────────────────────────────────────────────────────────────
+
+export function previewKindOf(mimeType: string): PreviewKind {
+  const t = mimeType.toLowerCase().split(';')[0].trim();
+  if (t === 'text/plain') return 'text';
+  if (t === 'text/html') return 'html';
+  if (t.startsWith('image/')) return 'image';
+  if (t.startsWith('video/')) return 'video';
+  if (t.startsWith('audio/')) return 'audio';
+  if (t === 'application/pdf') return 'pdf';
+  return 'binary';
+}
+
+export function formatSize(bytes: number): string {
+  if (bytes < 1024) return `${bytes} B`;
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
+  return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}
+
+export function mimeToExtension(mimeType: string): string {
+  const map: Record<string, string> = {
+    'text/plain': 'txt',
+    'text/html': 'html',
+    'image/png': 'png',
+    'image/jpeg': 'jpg',
+    'image/gif': 'gif',
+    'image/webp': 'webp',
+    'image/svg+xml': 'svg',
+    'image/bmp': 'bmp',
+    'video/mp4': 'mp4',
+    'video/webm': 'webm',
+    'video/ogg': 'ogv',
+    'audio/mpeg': 'mp3',
+    'audio/wav': 'wav',
+    'audio/ogg': 'ogg',
+    'audio/webm': 'weba',
+    'audio/flac': 'flac',
+    'application/pdf': 'pdf',
+  };
+  const t = mimeType.toLowerCase().split(';')[0].trim();
+  return map[t] ?? t.split('/')[1] ?? 'bin';
+}
+
+// ─── Clipboard API read ───────────────────────────────────────────────────────
+
+/**
+ * Read the current clipboard using the Clipboard API.
+ * Requires clipboard-read permission (browser may prompt).
+ * Only exposes types the browser allows (typically text, HTML, images).
+ */
+export async function readClipboard(): Promise<ClipboardItemEntry[]> {
+  const entries: ClipboardItemEntry[] = [];
+  const clipItems = await navigator.clipboard.read();
+  for (const ci of clipItems) {
+    for (const type of ci.types) {
+      const blob = await ci.getType(type);
+      const kind = previewKindOf(type);
+      if (kind === 'text' || kind === 'html') {
+        const text = await blob.text();
+        entries.push({ type, kind, text, size: blob.size });
+      } else {
+        entries.push({ type, kind, blobUrl: URL.createObjectURL(blob), size: blob.size });
+      }
+    }
+  }
+  return entries;
+}
+
+// ─── DataTransfer (paste event) ──────────────────────────────────────────────
+
+/**
+ * Extract all items from a DataTransfer (paste event).
+ * Files (video, audio, etc.) come from dt.items[].getAsFile().
+ * Text types are read synchronously via dt.getData().
+ */
+export function parseDataTransfer(dt: DataTransfer): ClipboardItemEntry[] {
+  const entries: ClipboardItemEntry[] = [];
+  const seenTypes = new Set<string>();
+
+  // File items — covers images, video, audio, documents pasted from disk
+  for (const item of Array.from(dt.items)) {
+    if (item.kind !== 'file') continue;
+    const file = item.getAsFile();
+    if (!file) continue;
+    const mimeType = (item.type || file.type || 'application/octet-stream').toLowerCase();
+    if (seenTypes.has(mimeType)) continue;
+    seenTypes.add(mimeType);
+    entries.push({
+      type: mimeType,
+      kind: previewKindOf(mimeType),
+      blobUrl: URL.createObjectURL(file),
+      size: file.size,
+      filename: file.name || undefined,
+    });
+  }
+
+  // String items — text/plain, text/html, and any other text types
+  for (const rawType of Array.from(dt.types)) {
+    if (rawType === 'Files' || seenTypes.has(rawType)) continue;
+    const data = dt.getData(rawType);
+    if (!data) continue;
+    seenTypes.add(rawType);
+    const encoder = new TextEncoder();
+    entries.push({
+      type: rawType,
+      kind: previewKindOf(rawType),
+      text: data,
+      size: encoder.encode(data).length,
+    });
+  }
+
+  return entries;
+}