@adecore/agents-react 0.37.2 → 0.37.3

package/src/chat/ui/ReferenceChip.tsx

@@ -0,0 +1,74 @@
+import { useContext, type HTMLAttributes, type KeyboardEvent, type ReactNode } from 'react';
+import clsx from 'clsx';
+import { useTranslation } from 'react-i18next';
+import { CircleOff } from 'lucide-react';
+import { Icon } from '@adecore/ui';
+import { REFERENCE_GONE_TONE, REFERENCE_TONE, TOKEN_ICON, TOKEN_IN_MESSAGE } from './chips';
+import { REFERENCE_ICONS } from './reference-icons';
+import { ReferenceLookupContext } from './reference-lookup';
+
+interface TokenChipProps extends Omit<HTMLAttributes<HTMLSpanElement>, 'children'> {
+    /* `gone` for a reference that stands for nothing any more, which a copy leaves as text. */
+    kind: 'mention' | 'skill' | 'reference' | 'gone';
+    /* The path, the skill's name or the reference's id. */
+    value?: string;
+    /* The sigil the mark stands in for. Hidden, but a selection copies it with the name. */
+    sigil?: string;
+    icon: ReactNode;
+    label: string;
+    tone: string;
+    onOpen?: () => void;
+}
+
+/*
+ * One token in the transcript. One that opens is a span with a button's role rather than a button,
+ * since a button is a box with a baseline of its own and would not sit on the line the others sit on.
+ */
+export function TokenChip({ kind, value, sigil, icon, label, tone, onOpen, className, ...rest }: TokenChipProps) {
+    const onKeyDown = (e: KeyboardEvent<HTMLSpanElement>): void => {
+        if (onOpen !== undefined && (e.key === 'Enter' || e.key === ' ')) {
+            e.preventDefault();
+            onOpen();
+        }
+    };
+    return (
+        <span
+            {...rest}
+            className={clsx(TOKEN_IN_MESSAGE, tone, onOpen !== undefined && 'cursor-pointer focus-visible:outline-2 focus-visible:outline-accent', className)}
+            data-chip={kind}
+            data-chip-value={value}
+            data-chip-name={kind === 'reference' ? label : undefined}
+            role={onOpen === undefined ? undefined : 'button'}
+            tabIndex={onOpen === undefined ? undefined : 0}
+            onClick={onOpen}
+            onKeyDown={onOpen === undefined ? undefined : onKeyDown}
+        >
+            {icon}
+            {sigil !== undefined && <span className="sr-only">{sigil}</span>}
+            {label}
+        </span>
+    );
+}
+
+/* A view, node or chat a message points at, under the name it has now; one that went says so. */
+export function ReferenceChip({ id }: { id: string }) {
+    const { t } = useTranslation('agent-chat');
+    const { items, open } = useContext(ReferenceLookupContext);
+    const item = items.find((candidate) => candidate.id === id);
+    if (item === undefined) {
+        return (
+            <TokenChip kind="gone" icon={<Icon icon={CircleOff} size={14} className={TOKEN_ICON} />} label={t('references.gone')} tone={REFERENCE_GONE_TONE} />
+        );
+    }
+    return (
+        <TokenChip
+            kind="reference"
+            value={item.id}
+            sigil="#"
+            icon={<Icon icon={REFERENCE_ICONS[item.kind]} size={14} className={TOKEN_ICON} />}
+            label={item.name || t('references.untitled')}
+            tone={clsx(REFERENCE_TONE, open !== null && 'hover:bg-text/12')}
+            onOpen={open === null ? undefined : () => open(item.id)}
+        />
+    );
+}

package/src/chat/ui/Timeline.tsx

@@ -29,6 +29,7 @@ import {
     setTimelineAtEnd,
     wantsEarlier,
     type ItemJumpOptions,
+    type ReadingAnchor,
     type TurnTarget
 } from '../timeline-scroll';
 import { useTimelineFlash } from '../timeline-flash';
@@ -226,6 +227,8 @@ export function Timeline({ chatId, composer, overlay }: { chatId: string; compos
     const [frame, setFrame] = useState({ width: 0, height: 0, column: false });
     const [loadingEarlier, setLoadingEarlier] = useState(false);
     const loadingEarlierRef = useRef(false);
+    const anchorRef = useRef<ReadingAnchor | null>(null);
+    const headRef = useRef<string | undefined>(undefined);
 
     const loadEarlier = useCallback(() => {
         if (cursor === null || loadingEarlierRef.current) {
@@ -355,7 +358,7 @@ export function Timeline({ chatId, composer, overlay }: { chatId: string; compos
     // Changing this callback invalidates every cached measurement, including on a scroll.
     const getItemKey = useCallback((index: number) => rows[index]!.id, [rows]);
 
-    // Nothing here builds with the React Compiler, so its memoization rule has nothing to break.
+    // Follow the browser's actual end below. Virtual end anchoring drifts when growth still fits without scrolling.
     // oxlint-disable-next-line react/incompatible-library
     const virtualizer = useVirtualizer({
         count: loadingHistory ? 0 : rows.length,
@@ -363,7 +366,6 @@ export function Timeline({ chatId, composer, overlay }: { chatId: string; compos
         estimateSize: () => ESTIMATED_ROW_PX,
         getItemKey,
         overscan: 8,
-        anchorTo: 'end',
         // Include the end before the first pin, so its actual heights are known before revealing it.
         rangeExtractor: (range) => {
             const indexes = defaultRangeExtractor(range);
@@ -414,6 +416,26 @@ export function Timeline({ chatId, composer, overlay }: { chatId: string; compos
         scrollGeometry.current = { top: element.scrollTop, height: element.scrollHeight, viewport: element.clientHeight };
     }, [rows.length, totalSize, composerHeight, frame.height]);
 
+    // Prepending history moves rows; keep the reader on the same row at the same height.
+    useLayoutEffect(() => {
+        const element = scrollRef.current;
+        const head = order?.[0];
+        const moved = head !== headRef.current;
+        headRef.current = head;
+        if (element === null) {
+            return;
+        }
+        const anchor = anchorRef.current;
+        const index = moved && anchor !== null && !followRef.current ? rows.findIndex((row) => row.id === anchor.id) : -1;
+        if (anchor !== null && index !== -1) {
+            virtualizer.getTotalSize();
+            element.scrollTop = virtualizer.measurementsCache[index]!.start - anchor.offset;
+            return;
+        }
+        const row = virtualizer.getVirtualItemForOffset(element.scrollTop);
+        anchorRef.current = row === undefined ? null : { id: String(row.key), offset: row.start - element.scrollTop };
+    });
+
     // Close to the top, the page before goes in; again after each page that left too little above the reader.
     useEffect(() => {
         const element = scrollRef.current;

package/src/chat/ui/TimelineMenu.tsx

@@ -10,7 +10,9 @@ import type { TimelineTarget } from '../logic/timeline-target';
 import { useChatHost } from '../../host';
 import { useChatScope } from '../../scope';
 import { useChatRow } from '../../state/chats';
+import { copyWithChips, rowClipboardChips } from './chip-clipboard';
 import { useFileLinkCwd, useFileLinkScopeId, useOpenFileLink } from './file-links';
+import { useReferenceLookup } from './thread-references';
 import { ContextMenu, copyText, DisabledReason, EDIT_SHORTCUTS, Icon, Kbd, selectAllWithin } from '@adecore/ui';
 
 /* The menu behind a right-click in a thread, mostly for copying: a whole message, a code block or an answer's markdown. */
@@ -28,7 +30,8 @@ export function TimelineMenuPopup({
     column?: boolean;
 }) {
     const { t } = useTranslation('agent-chat');
-    const message = target.row === null ? null : messageTextOf(target.row);
+    const row = target.row;
+    const message = row === null ? null : messageTextOf(row);
     const turnId = chatId === null || target.row === null ? null : turnIdOfRow(target.row);
     const forkBlocked = useChatRow(chatId ?? '', (row) => (turnId === null ? null : forkRefusal(row?.info ?? null, row?.structure[turnId])));
     const markdown = target.row === null ? null : markdownOf(target.row);
@@ -36,6 +39,7 @@ export function TimelineMenuPopup({
     // A thread outside a chat (a sub-agent's transcript) has no cwd of its own; the app answers for it then.
     const cwd = useFileLinkCwd();
     const scopeId = useFileLinkScopeId();
+    const lookup = useReferenceLookup(chatId ?? '');
     const { fork, fileLinks } = useChatHost();
     const openFileLink = useOpenFileLink();
     const openInPreview = (): void => {
@@ -50,8 +54,8 @@ export function TimelineMenuPopup({
             <ContextMenu.Item disabled={target.selection === ''} onClick={() => copyText(target.selection)}>
                 <Icon icon={Copy} size={14} /> {t('common.action.copy')} <Kbd shortcut={EDIT_SHORTCUTS.copy} />
             </ContextMenu.Item>
-            {message !== null && (
-                <ContextMenu.Item onClick={() => copyText(message)}>
+            {row !== null && message !== null && (
+                <ContextMenu.Item onClick={() => copyWithChips(rowClipboardChips(row, message, lookup))}>
                     <Icon icon={MessageSquare} size={14} /> {t('timeline.menu.copyMessage')}
                 </ContextMenu.Item>
             )}

package/src/chat/ui/chip-clipboard.ts

@@ -0,0 +1,115 @@
+import type { ChatAssistantItem, ChatUserItem } from '@adecore/agent-contracts';
+import { copyText } from '@adecore/ui';
+import { referenceTokens } from '../chat-references';
+import {
+    clipboardChipsOf,
+    hasClipboardChips,
+    tokenizeChips,
+    tokenizeNamedReferences,
+    writeClipboardChips,
+    type ChipSegment,
+    type ClipboardChips
+} from '../mentions';
+import type { TimelineRow } from '../logic/timeline';
+import type { ReferenceLookup } from './reference-lookup';
+
+/* The chips a copy of a whole message carries: what the person picked, or what a reply names. */
+export function messageClipboardChips(
+    item: ChatUserItem | ChatAssistantItem,
+    text: string,
+    lookup: Pick<ReferenceLookup, 'items' | 'referenced'>
+): ClipboardChips {
+    if (item.kind === 'assistant') {
+        return clipboardChipsOf(text, tokenizeNamedReferences(text, lookup.items, lookup.referenced));
+    }
+    const tokens = referenceTokens([...(item.chats ?? []), ...(item.references ?? [])], lookup.items);
+    return clipboardChipsOf(text, tokenizeChips(text, item.mentions ?? [], item.skills ?? [], tokens));
+}
+
+/* The chips a copy of a row of the thread carries; only a message has any. */
+export function rowClipboardChips(row: TimelineRow, text: string, lookup: Pick<ReferenceLookup, 'items' | 'referenced'>): ClipboardChips {
+    if (row.kind === 'user' || row.kind === 'assistant') {
+        return messageClipboardChips(row.item, text, lookup);
+    }
+    return clipboardChipsOf(text, []);
+}
+
+/* What a chip the transcript drew stands for, read back from the attributes `TokenChip` writes. */
+function segmentOf(chip: Element): ChipSegment | null {
+    const value = chip.getAttribute('data-chip-value');
+    if (value === null) {
+        return null;
+    }
+    switch (chip.getAttribute('data-chip')) {
+        case 'mention':
+            return { kind: 'mention', path: value };
+        case 'skill':
+            return { kind: 'skill', name: value };
+        case 'reference': {
+            const name = chip.getAttribute('data-chip-name');
+            return name === null || name === '' ? null : { kind: 'reference', id: value, name };
+        }
+        default:
+            return null;
+    }
+}
+
+/* The chips a selection holds whole, beside the text it copies; a chip cut in half is only text. */
+export function selectionChips(selection: Selection): ClipboardChips {
+    const segments: ChipSegment[] = [];
+    for (let i = 0; i < selection.rangeCount; i++) {
+        const container = selection.getRangeAt(i).commonAncestorContainer;
+        const root = container instanceof Element ? container : container.parentElement;
+        const own = root?.closest('[data-chip]');
+        const candidates = own ? [own] : [...(root?.querySelectorAll('[data-chip]') ?? [])];
+        for (const chip of candidates) {
+            const segment = selection.containsNode(chip, false) ? segmentOf(chip) : null;
+            if (segment !== null) {
+                segments.push(segment);
+            }
+        }
+    }
+    return clipboardChipsOf(selection.toString(), segments);
+}
+
+/* A copy of a selection in the thread, which carries the chips in it as well when it holds any. */
+export function copySelectionWithChips(event: ClipboardEvent): void {
+    const selection = document.getSelection();
+    if (event.defaultPrevented || event.clipboardData === null || selection === null || selection.isCollapsed) {
+        return;
+    }
+    const chips = selectionChips(selection);
+    if (!hasClipboardChips(chips)) {
+        return;
+    }
+    writeClipboardChips(event.clipboardData, chips);
+    event.preventDefault();
+}
+
+/*
+ * Copies a text and its chips. The asynchronous clipboard writes no type of an app's own that a paste
+ * can read, so the copy goes through a copy event, which only a page with the user's gesture gets.
+ */
+export function copyWithChips(chips: ClipboardChips): void {
+    if (!hasClipboardChips(chips) || typeof document.execCommand !== 'function') {
+        void copyText(chips.text);
+        return;
+    }
+    let written = false;
+    const write = (event: ClipboardEvent): void => {
+        if (event.clipboardData !== null) {
+            writeClipboardChips(event.clipboardData, chips);
+            event.preventDefault();
+            written = true;
+        }
+    };
+    document.addEventListener('copy', write, true);
+    try {
+        document.execCommand('copy');
+    } finally {
+        document.removeEventListener('copy', write, true);
+    }
+    if (!written) {
+        void copyText(chips.text);
+    }
+}

package/src/chat/ui/chips.ts

@@ -1,4 +1,4 @@
-/* An `@file` or `$skill` token drawn as a pill: the tone says which of the two it is, the shape
+/* An `@file`, `$skill` or `#reference` token drawn as a pill: the tone says which it is, the shape
    says where it is drawn. */
 
 export const MENTION_TONE = 'bg-accent-soft text-accent shadow-[inset_0_0_0_1px_color-mix(in_srgb,var(--accent)_25%,transparent)]';
@@ -6,10 +6,29 @@ export const MENTION_TONE = 'bg-accent-soft text-accent shadow-[inset_0_0_0_1px_
 /* A skill is the same token shape as a file mention, in its own hue. */
 export const SKILL_TONE = 'bg-skill-soft text-skill shadow-[inset_0_0_0_1px_color-mix(in_srgb,var(--skill)_25%,transparent)]';
 
+/* A `#` to a view, node or chat is neutral, so it never reads as a file or a skill. */
+export const REFERENCE_TONE = 'bg-text/8 text-text shadow-[inset_0_0_0_1px_var(--border-strong)]';
+
+/* A `#` whose view or node is no longer in the project. */
+export const REFERENCE_GONE_TONE = 'bg-text/4 text-text-faint shadow-[inset_0_0_0_1px_var(--border)]';
+
 /* The pill in the composer's editor, around the token's own characters: the editor places the caret
    from what it drew, so padding is safe, and a chip that wraps keeps it on every fragment. */
 export const CHIP_IN_EDITOR = 'box-decoration-clone rounded-md px-1 py-0.5';
 
+/* A picked or named token in a message or a reply, a shade smaller than the text around it. Inline like
+   the editor's pill, so its name sits on the baseline of the sentence, and a selection copies it on the
+   same line as the words around it, where a flex box would put it on lines of its own. */
+export const TOKEN_IN_MESSAGE = 'box-decoration-clone rounded-md px-1.5 py-0.5 text-xs font-medium';
+
+/* The mark in place of the sigil, a 14px icon. Inline, since the base styles make an svg a block of its
+   own. Its middle goes on the middle of the name's capitals, where a mark reads as centered; the middle
+   of the x-height `Icon` aligns on sits low next to a capital. */
+export const TOKEN_ICON = 'mr-1 inline align-[calc(0.5cap-7px)]!';
+
+/* The same middle for the 12px mark the composer draws, in a box whose bottom edge is its baseline. */
+export const TOKEN_ICON_IN_EDITOR = 'mr-1 inline-block align-[calc(0.5cap-6px)]';
+
 /* The same pill in the transcript: a real inline box a shade smaller than the text around it, with
    the icon in place of the sigil. */
 export const CHIP_IN_MESSAGE = 'inline-flex h-5 max-w-full items-center gap-1 rounded-md px-1.5 align-[-3px] text-xs/none font-medium';

package/src/chat/ui/composer/ComposerMenu.tsx

@@ -1,8 +1,9 @@
 import type { ReactNode } from 'react';
 import { useTranslation } from 'react-i18next';
 import clsx from 'clsx';
-import { MessageSquare, SquareSlash, Zap } from 'lucide-react';
+import { SquareSlash, Zap } from 'lucide-react';
 import { FileIcon, Icon, Menu, MiddleTruncate } from '@adecore/ui';
+import { REFERENCE_ICONS } from '../reference-icons';
 import type { ComposerMenus as Menus } from './use-composer-menus';
 import { optionIdOf } from './menu-aria';
 
@@ -72,52 +73,64 @@ function SkillMenu({ menus }: { menus: Menus }) {
 
 function MentionMenu({ menus, query }: { menus: Menus; query: string }) {
     const { t } = useTranslation('agent-chat');
-    const { listId, chatMatches, files, mentionCount } = menus;
-    const mentionsLabelId = `${listId}-chats`;
+    const { listId, files, mentionCount } = menus;
     const filesLabelId = `${listId}-files`;
-    const filesLabelShown = query === '' || chatMatches.length > 0;
+    const filesLabelShown = query === '';
     return (
         <div className="border-b border-border px-1.5 py-1.5">
             {mentionCount > 0 && (
-                <div id={listId} role="listbox" aria-label={t('composer.menu.mentions')}>
-                    {chatMatches.length > 0 && (
-                        <div role="group" aria-labelledby={mentionsLabelId}>
-                            <Menu.Label id={mentionsLabelId}>{t('composer.mentions.chats')}</Menu.Label>
-                            {chatMatches.map((chat, index) => (
-                                <MenuOption key={chat.id} menus={menus} index={index} className="items-center" onPick={() => menus.chooseChat(chat.id)}>
-                                    <Icon icon={MessageSquare} size={14} className="shrink-0 text-text-faint" />
-                                    <span className="truncate text-text">{chat.title || t('chatReference.untitled')}</span>
-                                </MenuOption>
-                            ))}
-                        </div>
-                    )}
-                    {files.length > 0 && (
-                        <div role="group" {...(filesLabelShown ? { 'aria-labelledby': filesLabelId } : { 'aria-label': t('composer.mentions.files') })}>
-                            {filesLabelShown && (
-                                <Menu.Label id={filesLabelId}>{query === '' ? t('composer.mentions.here') : t('composer.mentions.files')}</Menu.Label>
-                            )}
-                            {files.map((path, index) => {
-                                const { name, dir } = splitPath(path);
+                <div id={listId} role="listbox" {...(filesLabelShown ? { 'aria-labelledby': filesLabelId } : { 'aria-label': t('composer.mentions.files') })}>
+                    {filesLabelShown && <Menu.Label id={filesLabelId}>{t('composer.mentions.here')}</Menu.Label>}
+                    {files.map((path, index) => {
+                        const { name, dir } = splitPath(path);
+                        return (
+                            <MenuOption key={path} menus={menus} index={index} className="items-center" onPick={() => menus.chooseMention(path)}>
+                                <FileIcon path={path} size={14} />
+                                <span className="truncate font-mono text-text">{name}</span>
+                                {dir && <MiddleTruncate text={dir} tooltip={false} className="text-text-faint" />}
+                            </MenuOption>
+                        );
+                    })}
+                </div>
+            )}
+            {mentionCount === 0 && (
+                <div className="px-2 py-1 text-xs text-text-faint">{query ? t('composer.mentions.noMatch') : t('composer.mentions.empty')}</div>
+            )}
+        </div>
+    );
+}
+
+/* The views, nodes and chats a `#` offers, what stands on this canvas first, each with its kind or what tells it apart. */
+function ReferenceMenu({ menus }: { menus: Menus }) {
+    const { t } = useTranslation('agent-chat');
+    const { listId, referenceMatches } = menus;
+    const groups = (['canvas', 'views'] as const)
+        .map((group) => ({ group, items: referenceMatches.filter((item) => item.group === group) }))
+        .filter((entry) => entry.items.length > 0);
+    return (
+        <div className="border-b border-border px-1.5 py-1.5">
+            {referenceMatches.length > 0 ? (
+                <div id={listId} role="listbox" aria-label={t('composer.menu.references')}>
+                    {groups.map(({ group, items }) => (
+                        <div key={group} role="group" aria-labelledby={`${listId}-${group}`}>
+                            <Menu.Label id={`${listId}-${group}`}>{t(`composer.references.${group}`)}</Menu.Label>
+                            {items.map((item) => {
+                                const index = referenceMatches.indexOf(item);
                                 return (
-                                    <MenuOption
-                                        key={path}
-                                        menus={menus}
-                                        index={chatMatches.length + index}
-                                        className="items-center"
-                                        onPick={() => menus.chooseMention(path)}
-                                    >
-                                        <FileIcon path={path} size={14} />
-                                        <span className="truncate font-mono text-text">{name}</span>
-                                        {dir && <MiddleTruncate text={dir} tooltip={false} className="text-text-faint" />}
+                                    <MenuOption key={item.id} menus={menus} index={index} className="items-center" onPick={() => menus.chooseReference(item)}>
+                                        <Icon icon={REFERENCE_ICONS[item.kind]} size={14} className="shrink-0 text-text-faint" />
+                                        <span className="truncate text-text">{item.name}</span>
+                                        <span className="ml-auto shrink-0 truncate pl-2 text-text-faint">
+                                            {item.detail ?? t(`composer.references.kinds.${item.kind}`)}
+                                        </span>
                                     </MenuOption>
                                 );
                             })}
                         </div>
-                    )}
+                    ))}
                 </div>
-            )}
-            {mentionCount === 0 && (
-                <div className="px-2 py-1 text-xs text-text-faint">{query ? t('composer.mentions.noMatch') : t('composer.mentions.empty')}</div>
+            ) : (
+                <div className="px-2 py-1 text-xs text-text-faint">{t('composer.references.noMatch')}</div>
             )}
         </div>
     );
@@ -134,5 +147,8 @@ export function ComposerMenu({ menus }: { menus: Menus }) {
     if (menus.mentionMenuOpen && menus.mention !== null) {
         return <MentionMenu menus={menus} query={menus.mention.query} />;
     }
+    if (menus.referenceMenuOpen) {
+        return <ReferenceMenu menus={menus} />;
+    }
     return null;
 }

package/src/chat/ui/composer/DraftParts.tsx

@@ -5,7 +5,6 @@ import { Icon, IconButton, Tooltip } from '@adecore/ui';
 import { useChatScope } from '../../../scope';
 import { formatBytes, isImageAttachment, uploadBytes } from '../../attachments';
 import { jumpToTimelineItem } from '../../timeline-scroll';
-import { ChatReferenceChip } from '../ChatReferenceChip';
 import { UploadThumb } from '../UploadThumb';
 
 const ROW = 'px-5 pt-4 @max-md/composer:px-3.5 @max-md/composer:pt-3';
@@ -43,17 +42,6 @@ export function DraftQuote({ chatId, quote, source, onRemove, onSourceGone }: Dr
     );
 }
 
-/* Other chats the message points at, beside the text rather than in it. */
-export function DraftChats({ chats, onRemove }: { chats: readonly string[]; onRemove(id: string): void }) {
-    return (
-        <div className={`flex flex-wrap gap-1.5 ${ROW}`}>
-            {chats.map((id) => (
-                <ChatReferenceChip key={id} chatId={id} onRemove={() => onRemove(id)} />
-            ))}
-        </div>
-    );
-}
-
 /* The files the message carries: an image as a thumbnail, anything else by its name and size. */
 export function DraftAttachments({ attachments, onRemove }: { attachments: readonly ChatAttachmentUpload[]; onRemove(index: number): void }) {
     const { t } = useTranslation('agent-chat');

package/src/chat/ui/composer/chip-paste.ts

@@ -0,0 +1,122 @@
+import type { EditorView } from '@codemirror/view';
+import type { ChatDraft } from '../../drafts';
+import type { Referable } from '../../chat-references';
+import {
+    chipRanges,
+    clipboardChipsOf,
+    hasClipboardChips,
+    namedReferenceRanges,
+    tokenizeChips,
+    writeClipboardChips,
+    type ClipboardChips,
+    type ReferenceToken,
+    type TextRange
+} from '../../mentions';
+import { codeRanges } from './editor';
+
+/* What a composer knows of the chips a paste may make: the skills there are and what `#` points at. */
+export interface PasteChoices {
+    skills: readonly string[];
+    referables: readonly Referable[];
+    /* Ids the draft already points at, which win over another of the same name. */
+    referenced: readonly string[];
+    /* False for a CLI that does not read `@path`, which gets the text as it is. */
+    mentions: boolean;
+}
+
+/*
+ * The chips a plain paste spells between `from` and `to` of the text it landed in: `$name` for a skill
+ * there is, `#Name` by the reply rule. Code spans and code blocks keep what they hold.
+ */
+export function pastedChipsIn(text: string, from: number, to: number, code: readonly TextRange[], choices: PasteChoices): ClipboardChips {
+    const outside = [...code, { from: 0, to: from }, { from: to, to: text.length }];
+    const skills = chipRanges(text, [], [...choices.skills], outside);
+    const references = namedReferenceRanges(text, choices.referables, choices.referenced, outside);
+    return clipboardChipsOf(
+        text.slice(from, to),
+        [...skills, ...references].map((range) =>
+            range.kind === 'skill' ? { kind: 'skill', name: range.value } : { kind: 'reference', id: range.value, name: text.slice(range.from + 1, range.to) }
+        )
+    );
+}
+
+/* Whether a plain paste could make a chip at all, before it goes in as text. */
+export function mayHoldChips(text: string): boolean {
+    return /(^|[\s([{"'“‘])[$#]\p{L}/u.test(text);
+}
+
+/* The draft with the chips of a paste added, a chat beside the views and nodes as the picker keeps it. */
+export function withPastedChips(draft: ChatDraft, chips: ClipboardChips, choices: PasteChoices): ChatDraft {
+    const add = (ids: readonly string[], more: readonly string[]): string[] => [
+        ...ids,
+        ...more.filter((id, index) => !ids.includes(id) && more.indexOf(id) === index)
+    ];
+    const isChat = (token: ReferenceToken): boolean => choices.referables.some((item) => item.id === token.id && item.kind === 'chat');
+    const chats = chips.references.filter(isChat);
+    const references = chips.references.filter((token) => !isChat(token));
+    return {
+        ...draft,
+        mentions: choices.mentions ? add(draft.mentions, chips.mentions) : draft.mentions,
+        skills: add(draft.skills, chips.skills),
+        chats: add(
+            draft.chats,
+            chats.map((token) => token.id)
+        ),
+        references: add(
+            draft.references,
+            references.map((token) => token.id)
+        ),
+        referenceNames:
+            chips.references.length === 0
+                ? draft.referenceNames
+                : { ...draft.referenceNames, ...Object.fromEntries(chips.references.map((token) => [token.id, token.name])) }
+    };
+}
+
+/*
+ * Puts a paste in the editor and says which chips it brings: the ones it was copied with, or the ones
+ * its plain text spells. Null when there are none, so the editor pastes it as it always does.
+ */
+export function pasteWithChips(view: EditorView, clip: string, copied: ClipboardChips | null, choices: PasteChoices): ClipboardChips | null {
+    if (copied !== null && hasClipboardChips(copied)) {
+        view.dispatch(view.state.replaceSelection(copied.text), { scrollIntoView: true, userEvent: 'input.paste' });
+        return copied;
+    }
+    if (!mayHoldChips(clip)) {
+        return null;
+    }
+    const from = view.state.selection.main.from;
+    const inserted = view.state.replaceSelection(clip);
+    const state = view.state.update(inserted).state;
+    const to = state.selection.main.head;
+    const found = pastedChipsIn(state.doc.toString(), from, to, codeRanges(state), choices);
+    if (!hasClipboardChips(found)) {
+        return null;
+    }
+    view.dispatch(inserted, { scrollIntoView: true, userEvent: 'input.paste' });
+    return found;
+}
+
+/* A copy or a cut of a selection that holds chips, which carries them beside its text. False leaves it to the editor. */
+export function copyWithChipsFromEditor(
+    event: ClipboardEvent,
+    view: EditorView,
+    draft: Pick<ChatDraft, 'mentions' | 'skills'>,
+    references: readonly ReferenceToken[]
+): boolean {
+    const { from, to } = view.state.selection.main;
+    if (from === to || event.clipboardData === null) {
+        return false;
+    }
+    const text = view.state.sliceDoc(from, to);
+    const chips = clipboardChipsOf(text, tokenizeChips(text, draft.mentions, draft.skills, references));
+    if (!hasClipboardChips(chips)) {
+        return false;
+    }
+    writeClipboardChips(event.clipboardData, chips);
+    event.preventDefault();
+    if (event.type === 'cut') {
+        view.dispatch({ changes: { from, to }, scrollIntoView: true, userEvent: 'delete.cut' });
+    }
+    return true;
+}