@estiva-app/ui 0.62.1 → 0.63.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@estiva-app/ui",
-  "version": "0.62.1",
+  "version": "0.63.0",
   "description": "Estiva's design tokens (the contract) and a small set of primitives (a convenience) for every Estiva app.",
   "type": "module",
   "license": "MIT",

package/registry.json

@@ -4,9 +4,9 @@
     "kind": "package",
     "repo": "estiva-ui",
     "package": "@estiva-app/ui",
-    "packageVersion": "0.62.1",
-    "exports": 134,
-    "typeExports": 141,
+    "packageVersion": "0.63.0",
+    "exports": 139,
+    "typeExports": 145,
     "files": null
   },
   "storybook": {
@@ -3228,6 +3228,68 @@
       "app": null,
       "looks": []
     },
+    {
+      "name": "KindIcon",
+      "repo": "estiva-ui",
+      "kind": "component",
+      "importPath": "@estiva-app/ui",
+      "sourceFile": "src/KindIcon.tsx",
+      "purpose": "The icon before a thing's name that says what kind of thing it is: a topic, a project, an issue, another app's file, or a message.",
+      "purposeFrom": "page",
+      "props": [
+        {
+          "name": "kind",
+          "takes": "topic | project | issue | file | message",
+          "required": true,
+          "note": null
+        },
+        {
+          "name": "size",
+          "takes": "14 | 16",
+          "required": false,
+          "note": "16 in a row or a list; 14 inside a chip."
+        },
+        {
+          "name": "tone",
+          "takes": "secondary | inherit",
+          "required": false,
+          "note": "`secondary`: the quieter grey a list row's icon wears."
+        },
+        {
+          "name": "className",
+          "takes": "text",
+          "required": false,
+          "note": "Space and position only."
+        }
+      ],
+      "variants": [
+        {
+          "prop": "kind",
+          "values": [
+            "topic",
+            "project",
+            "issue",
+            "file",
+            "message"
+          ]
+        },
+        {
+          "prop": "tone",
+          "values": [
+            "secondary",
+            "inherit"
+          ]
+        }
+      ],
+      "ownsBehaviours": [],
+      "status": "stable",
+      "migrationStage": null,
+      "docsId": "primitives-kindicon--docs",
+      "storyId": "primitives-kindicon--default",
+      "docPage": "src/KindIcon.mdx",
+      "app": null,
+      "looks": []
+    },
     {
       "name": "Lightbox",
       "repo": "estiva-ui",
@@ -4413,6 +4475,63 @@
       "app": null,
       "looks": []
     },
+    {
+      "name": "pastedImageName",
+      "repo": "estiva-ui",
+      "kind": "helper",
+      "importPath": "@estiva-app/ui/editor",
+      "sourceFile": "src/PastedImages.ts",
+      "purpose": "`'Screenshot 2026-09-07 14-32-05.png'`: sortable, and readable on a file card.",
+      "purposeFrom": "comment",
+      "props": [],
+      "variants": [],
+      "ownsBehaviours": [],
+      "status": "stable",
+      "migrationStage": null,
+      "docsId": "primitives-pastedimages--docs",
+      "storyId": "primitives-pastedimages--in-an-editor",
+      "docPage": null,
+      "app": null,
+      "looks": []
+    },
+    {
+      "name": "pastedImages",
+      "repo": "estiva-ui",
+      "kind": "helper",
+      "importPath": "@estiva-app/ui/editor",
+      "sourceFile": "src/PastedImages.ts",
+      "purpose": "The pictures on the clipboard, named — `[]` when there is nothing to attach.",
+      "purposeFrom": "comment",
+      "props": [],
+      "variants": [],
+      "ownsBehaviours": [],
+      "status": "stable",
+      "migrationStage": null,
+      "docsId": "primitives-pastedimages--docs",
+      "storyId": "primitives-pastedimages--in-an-editor",
+      "docPage": null,
+      "app": null,
+      "looks": []
+    },
+    {
+      "name": "PastedImages",
+      "repo": "estiva-ui",
+      "kind": "component",
+      "importPath": "@estiva-app/ui/editor",
+      "sourceFile": "src/PastedImages.ts",
+      "purpose": "Pasting a picture into an editor attaches it.",
+      "purposeFrom": "page",
+      "props": [],
+      "variants": [],
+      "ownsBehaviours": [],
+      "status": "stable",
+      "migrationStage": null,
+      "docsId": "primitives-pastedimages--docs",
+      "storyId": "primitives-pastedimages--in-an-editor",
+      "docPage": "src/PastedImages.mdx",
+      "app": null,
+      "looks": []
+    },
     {
       "name": "peopleMenu",
       "repo": "estiva-ui",
@@ -5161,7 +5280,13 @@
           "name": "icon",
           "takes": "anything",
           "required": true,
-          "note": "At each row's start: a 16px icon — unless the row brings its own (`CaptionedItem.icon`)."
+          "note": "At each row's start: a 16px icon — unless the row brings its own (`CaptionedItem.icon`), or `iconFor` answers."
+        },
+        {
+          "name": "iconFor",
+          "takes": "a handler",
+          "required": false,
+          "note": "A row's 16px icon from what it points at — its `uri` — when the list holds several kinds of thing; `undefined` from it draws `icon`."
         }
       ],
       "variants": [],
@@ -6410,6 +6535,25 @@
         "bg-bg-field border border-border-field shadow-field hover:border-border-strong focus:border-border-focus rounded-lg text-caption text-text-primary placeholder:text-text-muted outline-none transition-colors disabled:pointer-events-none disabled:bg-bg-disabled disabled:text-text-disabled disabled:border-border-field signal:transition-shadow signal:focus:shadow-focus-ring"
       ]
     },
+    {
+      "name": "thingKindOf",
+      "repo": "estiva-ui",
+      "kind": "helper",
+      "importPath": "@estiva-app/ui",
+      "sourceFile": "src/KindIcon.tsx",
+      "purpose": "The kind of thing behind an event kind: a message is a message, a channel or a bare file is a topic, a project and an issue are themselves, and anything else is another app's file.",
+      "purposeFrom": "comment",
+      "props": [],
+      "variants": [],
+      "ownsBehaviours": [],
+      "status": "stable",
+      "migrationStage": null,
+      "docsId": "primitives-kindicon--docs",
+      "storyId": "primitives-kindicon--default",
+      "docPage": null,
+      "app": null,
+      "looks": []
+    },
     {
       "name": "Toast",
       "repo": "estiva-ui",

package/src/ComposerTriggers.mdx

@@ -92,10 +92,12 @@ const urgent = editor ? urgentPubkeys(editor) : undefined
   the same query; nothing waits for it. A row's `description` is its second
   line, which the chip does not wear. A row the person has arrowed to stays
   highlighted when the list is drawn again.
-- **Several kinds of thing in one `[` list:** a row's `icon` is drawn in
-  place of the list's, and the chip's `iconFor(uri)` picks the chip's from
-  what it points at, so the chip wears what its row wore. A row with no `icon`,
-  or a `uri` `iconFor` answers `undefined` for, keeps the one icon.
+- **Several kinds of thing in one `[` list:** give `ReferenceTrigger` and
+  `CaptionedReference` the same `iconFor(uri)` — at 16px for the rows, 14px
+  for the chip — and every row and the chip it inserts wear what they point
+  at. **KindIcon** is the answer for Estiva's own kinds. A row's own `icon`
+  wins over `iconFor`; a row with neither, or a `uri` `iconFor` answers
+  `undefined` for, keeps the list's one icon.
 
 <Canvas of={ComposerTriggersStories.ReferencesOfSeveralKinds} />
 

package/src/ComposerTriggers.test.tsx

@@ -145,6 +145,36 @@ describe('[', () => {
     expect(editor!.getHTML()).toContain('data-message-mention="true"')
   })
 
+  it('gives each row the icon `iconFor` answers for its uri; a row’s own icon wins, and no answer keeps the list’s', async () => {
+    const rows = [
+      { ...ITEMS[0], uri: 'nostr:a' },
+      { ...ITEMS[1], uri: 'nostr:b', icon: <i data-icon="own" /> },
+      { ...ITEMS[2], uri: 'nostr:c' },
+    ]
+    function Iconed() {
+      const made = useEditor({
+        extensions: [
+          StarterKit,
+          Chip,
+          ReferenceTrigger.configure({
+            items: () => rows,
+            nodeName: 'messageMention',
+            ariaLabel: 'Things',
+            sectionLabel: 'Things',
+            icon: <i data-icon="list" />,
+            iconFor: (uri) => (uri === 'nostr:a' ? <i data-icon="kind-a" /> : undefined),
+          }),
+        ],
+      })
+      editor = made
+      return <EditorContent editor={made} />
+    }
+    render(<Iconed />)
+    await type('[')
+    const icons = within(screen.getByRole('listbox')).getAllByRole('option').map((row) => row.querySelector('[data-icon]')?.getAttribute('data-icon'))
+    expect(icons).toEqual(['kind-a', 'own', 'list'])
+  })
+
   it('draws the app’s sections in order, skips an empty one, and redraws the open list when told', async () => {
     const listeners = new Set<() => void>()
     let late: CaptionedItem[] = []

package/src/ComposerTriggers.tsx

@@ -321,8 +321,14 @@ export interface ReferenceMenuOptions {
   ariaLabel: string
   /** The section's heading. */
   sectionLabel: string
-  /** At each row's start: a 16px icon — unless the row brings its own (`CaptionedItem.icon`). */
+  /** At each row's start: a 16px icon — unless the row brings its own (`CaptionedItem.icon`), or `iconFor` answers. */
   icon: ReactNode
+  /**
+   * A row's 16px icon from what it points at — its `uri` — when the list holds
+   * several kinds of thing; `undefined` from it draws `icon`. Give the chip the
+   * same answer at 14px (`CaptionedReference`'s `iconFor`), so a pick keeps it.
+   */
+  iconFor?: (uri: string) => ReactNode | undefined
 }
 
 /** A row as the list holds it: which section it is drawn under, when the list has several. */
@@ -333,7 +339,7 @@ type ListedItem = CaptionedItem & { section?: string }
  * One section headed `sectionLabel`, or — when the rows say which section they
  * are in — a heading for each, in the order the rows arrive.
  */
-export function referenceMenu({ ariaLabel, sectionLabel, icon }: ReferenceMenuOptions): SuggestionPopupOptions<CaptionedItem> {
+export function referenceMenu({ ariaLabel, sectionLabel, icon, iconFor }: ReferenceMenuOptions): SuggestionPopupOptions<CaptionedItem> {
   return {
     ariaLabel,
     width: 'w-[658px]',
@@ -349,7 +355,7 @@ export function referenceMenu({ ariaLabel, sectionLabel, icon }: ReferenceMenuOp
       return groups
     },
     itemKey: (item) => `reference-${item.id}`,
-    row: (item) => ({ leading: item.icon ?? icon, label: captionOf(item.label, item.snippet), description: item.description, hint: <EnterHint /> }),
+    row: (item) => ({ leading: item.icon ?? iconFor?.(item.uri) ?? icon, label: captionOf(item.label, item.snippet), description: item.description, hint: <EnterHint /> }),
   }
 }
 

package/src/KindIcon.mdx

@@ -0,0 +1,58 @@
+import { Meta, Canvas, Controls } from '@storybook/addon-docs/blocks'
+import * as KindIconStories from './KindIcon.stories'
+
+<Meta of={KindIconStories} />
+
+# KindIcon
+
+The icon before a thing's name that says what kind of thing it is: a topic, a
+project, an issue, another app's file, or a message. One table for every app,
+so the same thing wears the same icon wherever it is named.
+
+<Canvas of={KindIconStories.EveryKind} />
+
+## When
+
+- **Before a thing's name in a list row**, at 16px: a `[` list row, a recent
+  file, a search result.
+- **Inside a chip**, at 14px: `InlineChip`'s `icon` when a sentence names a
+  thing.
+- **As `iconFor` of the `[` list and its chip** (`ReferenceTrigger`,
+  `CaptionedReference`), so every row and every chip it inserts wears its own
+  kind.
+
+<Canvas of={KindIconStories.InAChip} />
+
+## When not
+
+- A person → **Avatar** or **Person**. A person is a face, not a kind.
+- A status (open, resolved) → **Chip**, or the app's own status mark.
+- An icon for an action → **IconButton** with the icon you need.
+
+## How
+
+```tsx
+import { KindIcon, thingKindOf } from '@estiva-app/ui'
+
+<KindIcon kind="issue" />                          // 16px, in a row
+<KindIcon kind={thingKindOf(event.kind)} size={14} tone="inherit" /> // inside a chip
+```
+
+- `thingKindOf(eventKind)` turns an event kind into a kind of thing. A pointer
+  written as `nostr:naddr…` carries its kind once decoded; a `nostr:nevent…`
+  is a message.
+- The icon is `aria-hidden`: the name beside it says what it is.
+- **Which icon is which kind is this part's.** An app never picks its own icon
+  for these. Its stroke is 1.5; it comes in two sizes and two tones: the
+  quieter grey of a list row, or `inherit`, the ink of the chip or row that
+  holds it.
+
+<Canvas of={KindIconStories.InAList} />
+
+## What it owns
+
+Nothing. It only draws. Clicks and keys are yours.
+
+## Props
+
+<Controls of={KindIconStories.Default} />

package/src/KindIcon.stories.tsx

@@ -0,0 +1,64 @@
+import type { Meta, StoryObj } from '@storybook/react-vite'
+import { InlineChip } from './InlineChip'
+import { KindIcon, type ThingKind } from './KindIcon'
+import { MenuItem, MenuPanel, MenuSection } from './Menu'
+
+const meta = {
+  title: 'Primitives/KindIcon',
+  component: KindIcon,
+  args: { kind: 'topic' },
+  argTypes: { kind: { control: 'select', options: ['topic', 'project', 'issue', 'file', 'message'] } },
+} satisfies Meta<typeof KindIcon>
+
+export default meta
+type Story = StoryObj<typeof meta>
+
+const KINDS: { kind: ThingKind; name: string }[] = [
+  { kind: 'topic', name: 'Topic' },
+  { kind: 'project', name: 'Project' },
+  { kind: 'issue', name: 'Issue' },
+  { kind: 'file', name: 'Another app’s file' },
+  { kind: 'message', name: 'Message' },
+]
+
+export const Default: Story = {}
+
+/** Every kind, at 16px, beside its name. */
+export const EveryKind: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <div className="flex flex-col gap-2 text-body-2 text-text-primary">
+      {KINDS.map(({ kind, name }) => (
+        <div key={kind} className="flex items-center gap-2">
+          <KindIcon kind={kind} />
+          {name}
+        </div>
+      ))}
+    </div>
+  ),
+}
+
+/** At 14px inside a chip, the way a sentence names a thing. */
+export const InAChip: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <p className="text-body-2 text-text-primary">
+      Tracked in <InlineChip icon={<KindIcon kind="issue" size={14} tone="inherit" />}>Ship the block model</InlineChip> and{' '}
+      <InlineChip icon={<KindIcon kind="topic" size={14} tone="inherit" />}>Planning</InlineChip> for now.
+    </p>
+  ),
+}
+
+/** At the start of list rows, each saying what it points at. */
+export const InAList: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <MenuPanel className="w-72">
+      <MenuSection label="Files">
+        {KINDS.map(({ kind, name }) => (
+          <MenuItem key={kind} label={name} leading={<KindIcon kind={kind} />} onClick={() => {}} />
+        ))}
+      </MenuSection>
+    </MenuPanel>
+  ),
+}

package/src/KindIcon.tsx

@@ -0,0 +1,64 @@
+import { IconBox, IconCircleDashed, IconFile, IconListDetails, IconMessage } from '@tabler/icons-react'
+import { cn } from './cn'
+
+/**
+ * What a thing is, as the apps name it: a topic, a project, an issue, another
+ * app's file, or a message.
+ *
+ * The one part that names Estiva's own kinds of thing (Katerina, 8 October):
+ * every app draws the same icon for the same kind, so the table lives here once
+ * instead of in each app.
+ */
+export type ThingKind = 'topic' | 'project' | 'issue' | 'file' | 'message'
+
+const ICONS = {
+  topic: IconCircleDashed,
+  project: IconBox,
+  issue: IconListDetails,
+  file: IconFile,
+  message: IconMessage,
+} satisfies Record<ThingKind, unknown>
+
+/*
+  The event kinds behind them (SPEC §6.7 and each app's manifest). Numbers
+  rather than an import: this package depends on no protocol code.
+*/
+const KIND_MESSAGE = 9
+const KIND_CHANNEL = 39000
+const KIND_BARE_FILE = 30840
+const KIND_PROJECT = 30850
+const KIND_ISSUE = 30851
+
+/**
+ * The kind of thing behind an event kind: a message is a message, a channel or
+ * a bare file is a topic, a project and an issue are themselves, and anything
+ * else is another app's file.
+ */
+export function thingKindOf(eventKind: number | undefined): ThingKind {
+  if (eventKind === KIND_MESSAGE) return 'message'
+  if (eventKind === KIND_CHANNEL || eventKind === KIND_BARE_FILE) return 'topic'
+  if (eventKind === KIND_PROJECT) return 'project'
+  if (eventKind === KIND_ISSUE) return 'issue'
+  return 'file'
+}
+
+export interface KindIconProps {
+  kind: ThingKind
+  /** 16 in a row or a list; 14 inside a chip. Default 16. */
+  size?: 14 | 16
+  /**
+   * `secondary`: the quieter grey a list row's icon wears. `inherit`: the ink
+   * of what holds it — a chip, a selected row. Default `secondary`.
+   */
+  tone?: 'secondary' | 'inherit'
+  /** Space and position only. */
+  className?: string
+}
+
+const TONE_CLASSES = { secondary: 'text-text-secondary', inherit: '' } as const
+
+/** The icon before a thing's name that says what kind of thing it is. */
+export function KindIcon({ kind, size = 16, tone = 'secondary', className }: KindIconProps) {
+  const Icon = ICONS[kind]
+  return <Icon size={size} stroke={1.5} className={cn('shrink-0', TONE_CLASSES[tone], className)} aria-hidden />
+}

package/src/PastedImages.mdx

@@ -0,0 +1,61 @@
+import { Meta, Canvas } from '@storybook/addon-docs/blocks'
+import * as PastedImagesStories from './PastedImages.stories'
+
+<Meta of={PastedImagesStories} />
+
+# PastedImages
+
+Pasting a picture into an editor attaches it. A screenshot on the clipboard
+reaches the app as named files, the same as a pick from its file picker.
+
+<Canvas of={PastedImagesStories.InAnEditor} />
+
+## When
+
+- **Any editor that can attach files**: a message box, an edit box, a
+  description. Give it the same upload the paperclip uses.
+
+## When not
+
+- A box that cannot attach files → leave it out; a pasted picture then does
+  nothing, which is the honest answer.
+- Any file other than a picture → the app's file picker. A paste attaches
+  pictures only.
+- Drawing the attached file → **AttachmentCard**, `pending` while it uploads.
+
+## How
+
+```tsx
+import StarterKit from '@tiptap/starter-kit'
+import { PastedImages } from '@estiva-app/ui/editor'
+
+useEditor({
+  extensions: [
+    StarterKit,
+    PastedImages.configure({
+      // Return true when the upload started; false lets the editor paste as usual.
+      onImages: (files) => {
+        if (!canUpload) return false
+        uploads.add(files)
+        return true
+      },
+    }),
+  ],
+})
+```
+
+- **Text wins.** A copy from a spreadsheet or a document carries a picture of
+  the selection beside its text. That paste stays text.
+- **A screenshot gets a name**: `Screenshot 2026-09-07 14-32-05.png`, with
+  `(2)`, `(3)` when one paste holds several. A picture that already has a real
+  name keeps it.
+- A picture type the app does not accept keeps its own extension, so the app's
+  own check refuses it by name.
+- `pastedImages(clipboardData)` is the same rule as a function, for an editor
+  that handles its own `handlePaste`.
+- Which clipboard contents count as pictures, and their names, are this
+  part's. The upload, its limits and its messages are the app's.
+
+## What it owns
+
+Nothing. It draws nothing; it hands a pasted picture to the app, named.

package/src/PastedImages.stories.tsx

@@ -0,0 +1,53 @@
+import { useState } from 'react'
+import type { Meta, StoryObj } from '@storybook/react-vite'
+import { EditorContent, useEditor } from '@tiptap/react'
+import StarterKit from '@tiptap/starter-kit'
+import { AttachmentCard } from './AttachmentCard'
+import { Card } from './Card'
+import { PastedImages } from './PastedImages'
+import { richTextClassName } from './RichText'
+
+/**
+ * Paste a screenshot into the box: it arrives as a named file under the text,
+ * the way the app's file picker would hand it. Copy some text and paste it:
+ * the text wins.
+ */
+const meta = {
+  title: 'Primitives/PastedImages',
+  parameters: { layout: 'padded' },
+} satisfies Meta
+
+export default meta
+type Story = StoryObj
+
+function Box() {
+  const [files, setFiles] = useState<File[]>([])
+  const editor = useEditor({
+    extensions: [
+      StarterKit,
+      PastedImages.configure({
+        onImages: (pasted) => {
+          setFiles((held) => [...held, ...pasted])
+          return true
+        },
+      }),
+    ],
+    content: '<p>Paste a screenshot here.</p>',
+    editorProps: { attributes: { class: richTextClassName('default', 'outline-none'), 'aria-label': 'Text' } },
+  })
+  return (
+    <Card fill="surface" className="flex w-[520px] flex-col gap-2 p-3">
+      <EditorContent editor={editor} />
+      {files.length > 0 && (
+        <div className="flex flex-wrap gap-2">
+          {files.map((file, i) => (
+            <AttachmentCard key={`${file.name}-${i}`} name={file.name} size={file.size} contentType={file.type} />
+          ))}
+        </div>
+      )}
+    </Card>
+  )
+}
+
+/** A box that attaches what is pasted. Try it with a screenshot on the clipboard. */
+export const InAnEditor: Story = { render: () => <Box /> }

package/src/PastedImages.test.ts

@@ -0,0 +1,83 @@
+// @vitest-environment jsdom
+import { describe, expect, it, vi } from 'vitest'
+import { Editor } from '@tiptap/core'
+import StarterKit from '@tiptap/starter-kit'
+import { PastedImages, pastedImageName, pastedImages, type ClipboardSource } from './PastedImages'
+
+const AT = new Date(2026, 8, 7, 14, 32, 5) // 2026-09-07 14:32:05, local
+
+/** A clipboard as the paste sees it. */
+function clipboard(text: string, files: File[] = []): ClipboardSource {
+  return { files, getData: (format) => (format === 'text/plain' ? text : '') }
+}
+
+const png = (name = 'image.png', type = 'image/png') => new File([new Uint8Array([1, 2, 3])], name, { type })
+
+describe('pastedImages', () => {
+  it('names a screenshot after the moment it was pasted', () => {
+    expect(pastedImageName('image/png', AT)).toBe('Screenshot 2026-09-07 14-32-05.png')
+    expect(pastedImageName('image/jpeg', AT)).toBe('Screenshot 2026-09-07 14-32-05.jpg')
+    expect(pastedImageName('image/png', AT, 1)).toBe('Screenshot 2026-09-07 14-32-05 (2).png')
+  })
+
+  it('gives an unlisted picture its own extension, so the app can refuse it by name', () => {
+    expect(pastedImageName('image/tiff', AT)).toBe('Screenshot 2026-09-07 14-32-05.tiff')
+  })
+
+  it('attaches a screenshot, renamed, its bytes and type kept', () => {
+    const [file] = pastedImages(clipboard('', [png()]), AT)
+    expect(file.name).toBe('Screenshot 2026-09-07 14-32-05.png')
+    expect(file.type).toBe('image/png')
+    expect(file.size).toBe(3)
+  })
+
+  it('leaves the clipboard to the editor when it carries text', () => {
+    expect(pastedImages(clipboard('Q3 revenue\t120', [png()]), AT)).toEqual([])
+    expect(pastedImages(clipboard('   ', [png()]), AT)).toHaveLength(1)
+  })
+
+  it('keeps a real filename', () => {
+    const [file] = pastedImages(clipboard('', [png('quarterly-chart.png')]), AT)
+    expect(file.name).toBe('quarterly-chart.png')
+  })
+
+  it('names several pictures in one paste apart', () => {
+    const files = pastedImages(clipboard('', [png(), png(), png('kept.png')]), AT)
+    expect(files.map((f) => f.name)).toEqual(['Screenshot 2026-09-07 14-32-05.png', 'Screenshot 2026-09-07 14-32-05 (2).png', 'kept.png'])
+  })
+
+  it('ignores anything that is not a picture, and an empty clipboard', () => {
+    const pdf = new File([new Uint8Array([1])], 'report.pdf', { type: 'application/pdf' })
+    expect(pastedImages(clipboard('', [pdf]), AT)).toEqual([])
+    expect(pastedImages(clipboard(''), AT)).toEqual([])
+    expect(pastedImages(null, AT)).toEqual([])
+  })
+})
+
+describe('PastedImages', () => {
+  /** A paste event as ProseMirror hands it to `handlePaste`. */
+  const paste = (editor: Editor, data: ClipboardSource) => {
+    const event = new Event('paste', { bubbles: true, cancelable: true }) as ClipboardEvent
+    Object.defineProperty(event, 'clipboardData', { value: data })
+    let handled = false
+    editor.view.someProp('handlePaste', (f) => (handled = !!f(editor.view, event, editor.state.doc.slice(0, 0)) || handled))
+    return handled
+  }
+
+  it('hands a pasted screenshot to the app, named, and stops the editor pasting it', () => {
+    const onImages = vi.fn(() => true)
+    const editor = new Editor({ extensions: [StarterKit, PastedImages.configure({ onImages })] })
+    expect(paste(editor, clipboard('', [png()]))).toBe(true)
+    expect(onImages).toHaveBeenCalledWith([expect.objectContaining({ name: expect.stringMatching(/^Screenshot .*\.png$/) })])
+    editor.destroy()
+  })
+
+  it('lets the editor paste when the app declines, or when there is text', () => {
+    const onImages = vi.fn(() => false)
+    const editor = new Editor({ extensions: [StarterKit, PastedImages.configure({ onImages })] })
+    expect(paste(editor, clipboard('', [png()]))).toBe(false)
+    expect(paste(editor, clipboard('a sentence', [png()]))).toBe(false)
+    expect(onImages).toHaveBeenCalledTimes(1)
+    editor.destroy()
+  })
+})