@estiva-app/ui 0.62.1 → 0.64.0

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/Link.mdx

@@ -14,7 +14,7 @@ the app decides how it navigates.
 
 - **It takes the size and colour of the text around it**: put it inside that
   text.
-- **`text`** — a link written inside text: the info colour, always
+- **`text`** — a link written inside text: the theme's link colour, always
   underlined, dimming on hover.
 - **`quiet`** — a title or a time that is also a link. It takes the colour and
   size of the text it sits in, and underlines on hover.

package/src/Link.stories.tsx

@@ -15,7 +15,7 @@ const meta = {
 export default meta
 type Story = StoryObj<typeof meta>
 
-/** Inside written text: the info colour, always underlined. Hover dims it. */
+/** Inside written text: the theme's link colour, always underlined. Hover dims it. */
 export const Text: Story = {
   render: (args) => (
     <p className="max-w-[480px] text-body-2 text-text-primary">

package/src/Link.test.tsx

@@ -53,10 +53,10 @@ describe('Link', () => {
     expect(screen.getByRole('link', { name: 'Documents' }).getAttribute('href')).toBe('/documents')
   })
 
-  it('text is the info colour, always underlined, and is the default', () => {
+  it('text is the link colour, always underlined, and is the default', () => {
     render(<Link href="#">Label</Link>)
     const classes = classesOf(screen.getByRole('link'))
-    expect(classes).toContain('text-info-default')
+    expect(classes).toContain('text-text-interactive')
     expect(classes).toContain('underline')
     expect(classes).toContain('underline-offset-2')
   })

package/src/Link.tsx

@@ -9,7 +9,7 @@ import { cn } from './cn'
  * on 13 September 2026, in three jobs (UIG-27). The looks are the ones those
  * links already had, reduced by Katerina's ruling:
  *
- * - `text` — a link inside written text: the info colour, always underlined,
+ * - `text` — a link inside written text: the theme's link colour, always underlined,
  *   dimming on hover. The look a link in a body of text already had.
  * - `quiet` — a title or a timestamp that is also a link. It takes the colour
  *   and size of the text it sits in and underlines on hover. Two looks that
@@ -43,7 +43,7 @@ export type LinkVariant = 'text' | 'quiet' | 'underlined' | 'plain'
 const COVER_CLASSES = 'after:absolute after:inset-0 after:rounded-md focus-visible:outline-none focus-visible:after:[outline-style:auto]'
 
 const VARIANT_CLASSES: Record<LinkVariant, string> = {
-  text: 'text-info-default underline underline-offset-2 hover:opacity-80',
+  text: 'text-text-interactive underline underline-offset-2 hover:opacity-80',
   quiet: 'hover:underline',
   underlined: 'underline underline-offset-2 hover:text-text-primary',
   plain: '',

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()
+  })
+})

package/src/PastedImages.ts

@@ -0,0 +1,105 @@
+import { Extension } from '@tiptap/core'
+import { Plugin, PluginKey } from '@tiptap/pm/state'
+
+/** As much of a `DataTransfer` as the paste reads. */
+export interface ClipboardSource {
+  files?: ArrayLike<File> | null
+  getData(format: string): string
+}
+
+/** MIME type → the extension a pasted picture is named with. */
+const IMAGE_EXTENSIONS: Record<string, string> = {
+  'image/png': 'png',
+  'image/jpeg': 'jpg',
+  'image/gif': 'gif',
+  'image/webp': 'webp',
+  'image/heic': 'heic',
+  'image/heif': 'heif',
+  'image/svg+xml': 'svg',
+}
+
+/** Names a browser invents for a clipboard picture. A made-up one is better. */
+const GENERIC_STEMS = new Set(['image', 'blob', 'unknown', 'untitled', 'screenshot'])
+
+/*
+  An unlisted type keeps its own subtype rather than becoming `png`, so a
+  picture the app does not accept is refused by the app's own message instead
+  of arriving disguised as one it does.
+*/
+function extensionFor(contentType: string): string {
+  const type = contentType.toLowerCase()
+  return IMAGE_EXTENSIONS[type] ?? type.split('/')[1]?.split('+')[0] ?? 'png'
+}
+
+/** `'Screenshot 2026-09-07 14-32-05.png'`: sortable, and readable on a file card. */
+export function pastedImageName(contentType: string, at: Date = new Date(), index = 0): string {
+  const pad = (n: number) => String(n).padStart(2, '0')
+  const stamp =
+    `${at.getFullYear()}-${pad(at.getMonth() + 1)}-${pad(at.getDate())} ` +
+    `${pad(at.getHours())}-${pad(at.getMinutes())}-${pad(at.getSeconds())}`
+  const nth = index > 0 ? ` (${index + 1})` : ''
+  return `Screenshot ${stamp}${nth}.${extensionFor(contentType)}`
+}
+
+/** A real filename is kept; `image.png`, `blob` and '' are not names. */
+function hasUsableName(name: string): boolean {
+  const dot = name.lastIndexOf('.')
+  if (dot <= 0 || dot === name.length - 1) return false
+  return !GENERIC_STEMS.has(name.slice(0, dot).toLowerCase())
+}
+
+/**
+ * The pictures on the clipboard, named — `[]` when there is nothing to attach.
+ *
+ * **Text wins.** A copy from a spreadsheet or a document puts a rendered
+ * picture of the selection beside the text; attaching the picture instead of
+ * pasting the text is wrong every time. So a clipboard holding text is left to
+ * the editor, and a screenshot, which holds none, lands here. Pictures only:
+ * any other file comes through the app's own file picker.
+ */
+export function pastedImages(source: ClipboardSource | null | undefined, at: Date = new Date()): File[] {
+  if (!source) return []
+  if (source.getData('text/plain').trim() !== '') return []
+  const images = Array.from(source.files ?? []).filter((f) => f.type.toLowerCase().startsWith('image/'))
+  let generated = 0
+  return images.map((file) =>
+    hasUsableName(file.name)
+      ? file
+      : new File([file], pastedImageName(file.type, at, generated++), { type: file.type, lastModified: file.lastModified }),
+  )
+}
+
+export interface PastedImagesOptions {
+  /**
+   * The pictures a paste carried, named. Return `true` when the app took them
+   * (an upload started), `false` to let the editor paste as it would have —
+   * for a box that cannot upload right now.
+   */
+  onImages: (files: File[]) => boolean
+}
+
+/**
+ * Pasting a picture attaches it: a screenshot pasted into the editor reaches
+ * the app as named files, the way the app's own file picker would hand them.
+ * Text on the clipboard wins (see {@link pastedImages}).
+ */
+export const PastedImages = Extension.create<PastedImagesOptions>({
+  name: 'pastedImages',
+  addOptions() {
+    return { onImages: () => false }
+  },
+  addProseMirrorPlugins() {
+    const options = this.options
+    return [
+      new Plugin({
+        key: new PluginKey('pastedImages'),
+        props: {
+          handlePaste: (_view, event) => {
+            const files = pastedImages(event.clipboardData)
+            return files.length > 0 && options.onImages(files)
+          },
+        },
+      }),
+    ]
+  },
+})

package/src/RichText.stories.tsx

@@ -57,6 +57,7 @@ export const Links: Story = {
     blocks: [
       p(t('A link with its own words: [the guide](https://example.com/guide). A bare address: https://example.com/a/long/address/that/breaks/where/it/must.')),
       p(t('Inside code it stays text: '), t('[not a link](https://example.com)', 'code')),
+      p(t('An '), t('underlined', 'underline'), t(' word beside [a link](https://example.com), and '), t('item.count', 'code'), t(' in a sentence.')),
     ],
   },
 }
@@ -89,3 +90,26 @@ export const UnknownBlock: Story = {
     blocks: [p(t('The block below is of a kind this part does not know.')), { type: 'unknown', typeName: 'later', inline: [t('Its words are still here.')] }],
   },
 }
+
+/** A code block in a named language. */
+export const CodeInALanguage: Story = {
+  args: {
+    blocks: [
+      {
+        type: 'codeBlock',
+        language: 'ts',
+        inline: [
+          t(
+            [
+              '// Count the items that are done',
+              'export function countDone(items: Item[]): number {',
+              "  const done = items.filter((item) => item.state === 'done')",
+              '  return done.length + 0',
+              '}',
+            ].join('\n'),
+          ),
+        ],
+      },
+    ],
+  },
+}

package/src/RichText.tsx

@@ -1,6 +1,7 @@
 import type { MouseEvent, ReactNode } from 'react'
 import { cn } from './cn'
 import { Link } from './Link'
+import { codeColours } from './codeColours'
 
 /**
  * Formatted text, drawn: headings, paragraphs, lists, a quote, code, a divider,
@@ -11,7 +12,8 @@ import { Link } from './Link'
  * and the two had drifted: headings, list markers, quotes and code differed,
  * one app had tables and the other dropped them, one had links and the other
  * printed the brackets (UIG-30). The look here is Katerina's picks of
- * 28 September, one per difference, most of them Peek's.
+ * 28 September, one per difference, most of them Peek's, with the room and
+ * colours she changed on 9 October.
  *
  * **It takes the tree, not the text.** The caller parses (the format comes from
  * the item's tag, never from the body) and hands the blocks in. So this package
@@ -84,21 +86,32 @@ export interface RichTextProps {
  * paragraph inside each list item, quote and table cell (the `> p` lines).
  */
 const RICH_TEXT_CLASSES = {
-  base: 'flex flex-col gap-1 break-words text-text-secondary',
-  /* A heading binds to what follows it: 12px above (8 and the 4px gap), 8px below (4 and the gap); two headings in a row, 12px apart. Level 3 keeps the text's colour, one step lower. */
-  headings: '[&>:is(h1,h2,h3)]:mb-1 [&>:is(h1,h2,h3)]:mt-2 [&>:is(h1,h2,h3):first-child]:mt-0 [&>:is(h1,h2,h3):last-child]:mb-0 [&>:is(h1,h2,h3)+:is(h1,h2,h3)]:mt-1 [&>:is(h1,h2)]:text-text-primary',
-  lists: '[&_:is(ul,ol)]:pl-5 [&_li>p]:m-0 [&_li]:break-words [&_li]:marker:text-text-muted [&_ol]:list-decimal [&_ul]:list-disc',
+  /* Blocks 8px apart (Katerina, 9 October; 4 before). A list's own items stay together. */
+  base: 'flex flex-col gap-2 break-words text-text-secondary',
+  /* A heading binds to what follows it: 12px above (4 and the 8px gap), 8px below (the gap); two headings in a row, 12px apart. The same as before the gap grew (Katerina, 9 October: headings do not change). Level 3 keeps the text's colour, one step lower: at the same size as level 2, colour is what tells them apart (Katerina, 9 October). */
+  headings: '[&>:is(h1,h2,h3)]:mt-1 [&>:is(h1,h2,h3):first-child]:mt-0 [&>:is(h1,h2)]:text-text-primary',
+  /* Bullets and numbers in the text's own colour, so a number can be read (Katerina, 9 October; they were the muted grey, 2.4 : 1 in Leaf). */
+  lists: '[&_:is(ul,ol)]:pl-5 [&_li>p]:m-0 [&_li]:break-words [&_li]:marker:text-text-secondary [&_ol]:list-decimal [&_ul]:list-disc',
+  /* The line in the muted text grey, not the border grey: a border grey was 1.3 : 1 in Leaf (Katerina, 9 October). */
   // eslint-disable-next-line token-spacing/no-restricted-classes -- @estiva-escape: the quote line is Peek's, 3px, between the ramp's 2 and 4
-  quote: '[&_blockquote>p]:m-0 [&_blockquote]:border-l-[3px] [&_blockquote]:border-border-strong [&_blockquote]:pl-2.5',
-  // eslint-disable-next-line token-values/no-restricted-classes -- @estiva-escape: code is 0.9 of the text around it, so it scales with a heading and with `small`; a named size is fixed
-  code: '[&_:not(pre)>code]:rounded-sm [&_:not(pre)>code]:bg-bg-code [&_:not(pre)>code]:px-1 [&_:not(pre)>code]:py-0.5 [&_code]:font-mono [&_code]:text-[0.9em] [&_code]:text-text-primary',
-  // eslint-disable-next-line token-values/no-restricted-classes -- @estiva-escape: code is 0.9 of the text around it; the code inside the block is the block's own size, not 0.9 of it again
-  codeBlock: '[&_pre>code]:text-[1em] [&_pre]:whitespace-pre-wrap [&_pre]:break-words [&_pre]:rounded-md [&_pre]:bg-bg-code [&_pre]:p-2 [&_pre]:font-mono [&_pre]:text-[0.9em] [&_pre]:text-text-primary',
-  divider: '[&_hr]:border-border-default',
+  quote: '[&_blockquote>p]:m-0 [&_blockquote]:border-l-[3px] [&_blockquote]:border-text-muted [&_blockquote]:pl-2.5',
+  /* Code in a sentence is amber, its own colour (Katerina, 9 October: option I). */
+  // eslint-disable-next-line token-values/no-restricted-classes -- @estiva-escape: code is 0.85 of the text around it, so it scales with a heading and with `small`; a named size is fixed
+  code: '[&_:not(pre)>code]:rounded-sm [&_:not(pre)>code]:bg-bg-code [&_:not(pre)>code]:px-1 [&_:not(pre)>code]:py-0.5 [&_:not(pre)>code]:text-text-code [&_code]:font-mono [&_code]:text-[0.85em] [&_code]:text-text-primary',
+  /* 12px either side, 10px above and below, looser lines than the text (Katerina, 9 October; 8px all round before). */
+  // eslint-disable-next-line token-values/no-restricted-classes -- @estiva-escape: code is 0.85 of the text around it; the code inside the block is the block's own size, not 0.85 of it again
+  codeBlock: '[&_pre>code]:text-[1em] [&_pre]:whitespace-pre-wrap [&_pre]:break-words [&_pre]:rounded-md [&_pre]:bg-bg-code [&_pre]:px-3 [&_pre]:py-2.5 [&_pre]:font-mono [&_pre]:text-[0.85em] [&_pre]:leading-relaxed [&_pre]:text-text-primary',
+  /* Colours inside a code block, by language: the classes `codeColours` gives each word, after highlight.js's own GitHub theme (Katerina, 9 October). */
+  syntax: '[&_:is(.hljs-keyword,.hljs-doctag,.hljs-type,.hljs-template-tag,.hljs-template-variable)]:text-syntax-keyword [&_.hljs-title]:text-syntax-function [&_:is(.hljs-number,.hljs-literal,.hljs-attr,.hljs-attribute,.hljs-meta,.hljs-variable,.hljs-selector-attr,.hljs-selector-class,.hljs-selector-id)]:text-syntax-constant [&_:is(.hljs-string,.hljs-regexp)]:text-syntax-string [&_:is(.hljs-built_in,.hljs-symbol)]:text-syntax-variable [&_.hljs-comment]:text-syntax-comment [&_:is(.hljs-name,.hljs-quote,.hljs-selector-tag,.hljs-selector-pseudo)]:text-syntax-tag',
+  /* A divider splits the text in two: 16px either side (Katerina, 9 October; 4 before). */
+  divider: '[&_hr]:my-2 [&_hr]:border-border-default',
   table: '[&_:is(th,td)>p]:m-0 [&_:is(th,td)]:border [&_:is(th,td)]:border-border-default [&_:is(th,td)]:px-2 [&_:is(th,td)]:py-1 [&_:is(th,td)]:text-left [&_:is(th,td)]:align-top [&_table]:w-full [&_table]:border-collapse [&_th]:bg-bg-code [&_th]:font-medium [&_th]:text-text-primary',
-  marks: '[&_em]:italic [&_strong]:font-semibold [&_u]:underline [&_u]:underline-offset-2',
-  default: 'text-body-2 [&>:is(h2,h3)]:text-body-2 [&>:is(h2,h3)]:font-semibold [&>h1]:text-h4',
-  small: 'text-caption leading-snug [&>:is(h2,h3)]:text-caption [&>:is(h2,h3)]:font-semibold [&>h1]:text-body-2 [&>h1]:font-semibold',
+  /* Bold in the heading colour, not only heavier. An underlined word draws a faint line, so it does not read as a link (Katerina, 9 October). */
+  marks: '[&_em]:italic [&_strong]:font-semibold [&_strong]:text-text-primary [&_u]:underline [&_u]:decoration-text-muted [&_u]:underline-offset-2',
+  /* Lines 1.5 apart (Katerina, 9 October; 1.4 before). */
+  default: 'text-body-2 leading-normal [&>:is(h2,h3)]:text-body-2 [&>:is(h2,h3)]:font-semibold [&>h1]:text-h4',
+  /* Blocks 6px apart; a heading keeps its 12px above and 8px below. */
+  small: 'gap-1.5 text-caption leading-snug [&>:is(h1,h2,h3)]:mb-0.5 [&>:is(h1,h2,h3)]:mt-1.5 [&>:is(h1,h2,h3)+:is(h1,h2,h3)]:mt-1 [&>:is(h1,h2,h3):last-child]:mb-0 [&>:is(h2,h3)]:text-caption [&>:is(h2,h3)]:font-semibold [&>h1]:text-body-2 [&>h1]:font-semibold',
 }
 
 /**
@@ -106,8 +119,8 @@ const RICH_TEXT_CLASSES = {
  * being written looks the same as what is read. Put it on the editor's root.
  */
 export function richTextClassName(size: RichTextSize = 'default', className?: string) {
-  const { base, headings, lists, quote, code, codeBlock, divider, table, marks } = RICH_TEXT_CLASSES
-  return cn(base, headings, lists, quote, code, codeBlock, divider, table, marks, RICH_TEXT_CLASSES[size], className)
+  const { base, headings, lists, quote, code, codeBlock, syntax, divider, table, marks } = RICH_TEXT_CLASSES
+  return cn(base, headings, lists, quote, code, codeBlock, syntax, divider, table, marks, RICH_TEXT_CLASSES[size], className)
 }
 
 /**
@@ -251,9 +264,10 @@ function Block({ block, draw }: { block: RichTextBlock; draw: Draw }): ReactNode
       return <blockquote data-block-id={block.id}>{runs}</blockquote>
     case 'codeBlock':
       // Literal: no marks, no links, no chips. A long line wraps; nothing scrolls sideways.
+      // In a language highlight.js knows, each word takes its colour; in any other, the text as it is.
       return (
         <pre data-block-id={block.id} data-language={block.language}>
-          <code>{(block.inline ?? []).map((run) => run.text).join('')}</code>
+          <code>{codeColours((block.inline ?? []).map((run) => run.text).join(''), block.language)}</code>
         </pre>
       )
     case 'horizontalRule':

package/src/codeColours.ts

@@ -0,0 +1,33 @@
+import { createElement, type ReactNode } from 'react'
+import { common, createLowlight } from 'lowlight'
+
+/**
+ * Colours inside a code block, by language (Katerina, 9 October).
+ *
+ * highlight.js reads the code and names each word (a keyword, a string, a
+ * comment); RichText's class list gives each name its colour from the theme's
+ * `syntax-*` tokens. The same instance colours the editor's code block
+ * (`CodeBlockColours`), so what is written looks the same as what is read.
+ *
+ * `common` is highlight.js's 37 everyday languages. A language outside them, or
+ * none, leaves the code in one colour.
+ */
+export const lowlight = createLowlight(common)
+
+interface HastNode {
+  type: string
+  value?: string
+  properties?: { className?: string[] }
+  children?: HastNode[]
+}
+
+function draw(node: HastNode, key: number): ReactNode {
+  if (node.type === 'text') return node.value
+  return createElement('span', { key, className: node.properties?.className?.join(' ') }, (node.children ?? []).map(draw))
+}
+
+/** The code, its words wrapped in highlight.js's classes; the text as it is when the language is unknown. */
+export function codeColours(text: string, language?: string): ReactNode {
+  if (!language || !lowlight.registered(language)) return text
+  return (lowlight.highlight(language, text).children as HastNode[]).map(draw)
+}

package/src/editor.ts

@@ -8,6 +8,8 @@
  * `Toolbar`, `MenuItem`, `SuggestionMenu` — is the main entry's own, not a copy.
  */
 export { KeptSelection, SelectionToolbar, normalizeHref, type MarkId, type SelectionToolbarProps } from './SelectionToolbar'
+export { PastedImages, pastedImages, pastedImageName, type PastedImagesOptions, type ClipboardSource } from './PastedImages'
+export { CodeBlockColours } from './CodeBlockColours'
 export { suggestionPopup, isSuggestionActive, isSuggestionOpen, type SuggestionPopupOptions } from './suggestionPopup'
 export { EditorBlockHandle, blockDropCursor, deleteBlock, moveBlock, duplicateBlock, startBlockDrag, type EditorBlockHandleProps, type BlockTurnInto } from './EditorBlockHandle'
 export {

package/src/eslint/no-restyled-part.ts

@@ -131,6 +131,7 @@ export const PART_LOOK_PROPS: Record<string, string[]> = {
   Card: ['fill', 'hover', 'attention', 'selected', 'active', 'hovered', 'quietUntilHover', 'unreadable', 'clip'],
   Checkbox: ['row'],
   Chip: ['type'],
+  KindIcon: ['tone'],
   CollapsibleSection: ['look'],
   Divider: ['tone', 'orientation'],
   EmptyState: ['scope'],

package/src/index.ts

@@ -55,6 +55,7 @@ export { Link, type LinkProps, type LinkVariant } from './Link'
 export { RichText, richTextClassName, type RichTextProps, type RichTextBlock, type RichTextRun, type RichTextSize } from './RichText'
 export { IconButton, type IconButtonProps, type IconButtonVariant } from './IconButton'
 export { Kbd, type KbdProps } from './Kbd'
+export { KindIcon, thingKindOf, type KindIconProps, type ThingKind } from './KindIcon'
 export { IdentityMenu, IdentityPanel, type Identity, type IdentityMenuProps, type IdentityPanelProps } from './IdentityMenu'
 export { Tooltip, TooltipProvider, WithTooltip, type TooltipProps, type TooltipProviderProps, type WithTooltipProps } from './Tooltip'
 export { Field, FieldLine, type FieldLineProps, type FieldLineTone, type FieldProps } from './Field'

package/src/pages.test.ts

@@ -38,7 +38,11 @@ const WAITING: string[] = []
 
 const NOTHING = 'Nothing. It only draws. Clicks and keys are yours.'
 /** A part that draws nothing at all says so instead: it only holds what the parts below it ask for. */
-const HOLDS_ONLY: Record<string, string> = { AppProvider: 'Nothing. It draws nothing; it holds two answers for the parts below it.' }
+const HOLDS_ONLY: Record<string, string> = {
+  AppProvider: 'Nothing. It draws nothing; it holds two answers for the parts below it.',
+  PastedImages: 'Nothing. It draws nothing; it hands a pasted picture to the app, named.',
+  CodeBlockColours: 'Nothing. It names each word of a code block; the RichText class list colours them.',
+}
 
 const dir = new URL('.', import.meta.url)
 const read = (file: string) => readFileSync(new URL(file, dir), 'utf8').replace(/\r\n/g, '\n')