@adecore/agents-react 0.37.2 → 0.37.3

package/src/chat/ui/composer/chips.ts

@@ -1,13 +1,20 @@
+import { createElement } from 'react';
+import { createRoot, type Root } from 'react-dom/client';
 import { syntaxTree } from '@codemirror/language';
-import { Facet, RangeSetBuilder, StateField, type EditorState, type Extension } from '@codemirror/state';
-import { Decoration, EditorView, type DecorationSet } from '@codemirror/view';
-import { chipRanges } from '../../mentions';
-import { CHIP_IN_EDITOR, MENTION_TONE, SKILL_TONE } from '../chips';
+import { Facet, StateField, type EditorState, type Extension, type Range } from '@codemirror/state';
+import { Decoration, EditorView, WidgetType, type DecorationSet } from '@codemirror/view';
+import { Icon } from '@adecore/ui';
+import type { ReferableKind } from '../../chat-references';
+import { chipRanges, type ReferenceToken } from '../../mentions';
+import { CHIP_IN_EDITOR, MENTION_TONE, REFERENCE_TONE, SKILL_TONE, TOKEN_ICON_IN_EDITOR } from '../chips';
+import { REFERENCE_ICONS } from '../reference-icons';
 import { codeRanges } from './editor';
 
 export interface ChipChoices {
     mentions: string[];
     skills: string[];
+    /* Null for a kind the host no longer names, which draws the chip without its mark. */
+    references?: ReadonlyArray<ReferenceToken & { kind: ReferableKind | null }>;
 }
 
 const NO_CHOICES: ChipChoices = { mentions: [], skills: [] };
@@ -16,15 +23,58 @@ const choices = Facet.define<ChipChoices, ChipChoices>({ combine: (values) => va
 
 const mentionMark = Decoration.mark({ class: `${MENTION_TONE} ${CHIP_IN_EDITOR}` });
 const skillMark = Decoration.mark({ class: `${SKILL_TONE} ${CHIP_IN_EDITOR}` });
+// Inclusive at the start, so the pill opens before the mark of the kind that replaces its `#` and holds it.
+const referenceMark = Decoration.mark({ class: `${REFERENCE_TONE} ${CHIP_IN_EDITOR}`, inclusiveStart: true });
+
+const roots = new WeakMap<HTMLElement, Root>();
+
+/* The kind's mark in place of the `#`, the way a sent message draws it. */
+class ReferenceIcon extends WidgetType {
+    readonly kind: ReferableKind;
+
+    constructor(kind: ReferableKind) {
+        super();
+        this.kind = kind;
+    }
+
+    override eq(other: ReferenceIcon): boolean {
+        return other.kind === this.kind;
+    }
+
+    toDOM(): HTMLElement {
+        const holder = document.createElement('span');
+        holder.className = TOKEN_ICON_IN_EDITOR;
+        const root = createRoot(holder);
+        root.render(createElement(Icon, { icon: REFERENCE_ICONS[this.kind], size: 12 }));
+        roots.set(holder, root);
+        return holder;
+    }
+
+    override destroy(dom: HTMLElement): void {
+        const root = roots.get(dom);
+        roots.delete(dom);
+        // The editor drops a widget inside React's own commit, where a root may not unmount at once.
+        queueMicrotask(() => root?.unmount());
+    }
+}
 
 function chipMarks(state: EditorState): DecorationSet {
-    const { mentions, skills } = state.facet(choices);
-    const builder = new RangeSetBuilder<Decoration>();
+    const { mentions, skills, references = [] } = state.facet(choices);
+    const kinds = new Map(references.map((token) => [token.id, token.kind]));
+    const marks: Range<Decoration>[] = [];
     // `@a.ts` in backticks is code, not a mention.
-    for (const range of chipRanges(state.doc.toString(), mentions, skills, codeRanges(state))) {
-        builder.add(range.from, range.to, range.kind === 'skill' ? skillMark : mentionMark);
+    for (const range of chipRanges(state.doc.toString(), mentions, skills, codeRanges(state), references)) {
+        if (range.kind !== 'reference') {
+            marks.push((range.kind === 'skill' ? skillMark : mentionMark).range(range.from, range.to));
+            continue;
+        }
+        marks.push(referenceMark.range(range.from, range.to));
+        const kind = kinds.get(range.value);
+        if (kind !== undefined && kind !== null) {
+            marks.push(Decoration.replace({ widget: new ReferenceIcon(kind) }).range(range.from, range.from + 1));
+        }
     }
-    return builder.finish();
+    return Decoration.set(marks, true);
 }
 
 const chipField = StateField.define<DecorationSet>({
@@ -37,7 +87,7 @@ const chipField = StateField.define<DecorationSet>({
     provide: (field) => EditorView.decorations.from(field)
 });
 
-/* Draws the chosen `@path` and `$name` tokens as chips; a new `ChipChoices` object is what redraws them. */
+/* Draws the chosen `@path`, `$name` and `#name` tokens as chips; a new `ChipChoices` object is what redraws them. */
 export function chipDecorations(value: ChipChoices): Extension {
     return [choices.of(value), chipField];
 }

package/src/chat/ui/composer/key-handler.ts

@@ -84,6 +84,15 @@ function pickInMenu(e: KeyboardEvent, { menus, setText }: KeyHandlerInput): bool
             return true;
         }
     }
+    if (menus.referenceMenuOpen && menus.referenceMatches.length > 0) {
+        if (menus.moveInMenu(e.key, menus.referenceMatches.length)) {
+            return true;
+        }
+        if (e.key === 'Tab' || e.key === 'Enter') {
+            menus.chooseReferenceAt(activeIndex);
+            return true;
+        }
+    }
     return false;
 }
 

package/src/chat/ui/composer/use-composer-draft.ts

@@ -12,7 +12,6 @@ export interface ComposerDraft {
     setText(next: string, mentions?: string[], skills?: string[]): void;
     clear(): void;
     removeQuote(): void;
-    removeChat(id: string): void;
     removeAttachment(index: number): void;
 }
 
@@ -58,14 +57,9 @@ export function useComposerDraft(chatId: string, inputRef: RefObject<ComposerInp
         inputRef.current?.focus();
     };
 
-    const removeChat = (id: string): void => {
-        setDraft((current) => ({ ...current, chats: current.chats.filter((entry) => entry !== id) }));
-        inputRef.current?.focus();
-    };
-
     const removeAttachment = (index: number): void => {
         setDraft((current) => ({ ...current, attachments: current.attachments.filter((_, i) => i !== index) }));
     };
 
-    return { draft, setDraft, latest, setText, clear, removeQuote, removeChat, removeAttachment };
+    return { draft, setDraft, latest, setText, clear, removeQuote, removeAttachment };
 }

package/src/chat/ui/composer/use-composer-menus.ts

@@ -5,16 +5,19 @@ import type { EditorState } from '@codemirror/state';
 import type { ChatInfo, ChatSkill, ProviderCapabilities } from '@adecore/agent-contracts';
 import { useChatHost } from '../../../host';
 import { useChatScope } from '../../../scope';
-import { chatSuggestions } from '../../chat-references';
+import { referenceSuggestions, referenceTokens, type Referable } from '../../chat-references';
 import { usableSlashCommands } from '../../guards';
 import {
-    dropQuery,
+    chipRanges,
     findMentionQuery,
+    findReferenceQuery,
     findSkillQuery,
     insertMention,
+    insertReference,
     insertSkill,
     mentionPick,
     NO_MENTION_SEARCH,
+    queryOutsideChips,
     type MentionQuery,
     type MentionSearch,
     type TextRange
@@ -23,13 +26,12 @@ import type { ComposerInputHandle } from '../ComposerInput';
 import type { ComposerDraft } from './use-composer-draft';
 import { inCode } from './keys';
 import { clampMenuIndex, composerMenuAria } from './menu-aria';
-import { useHostReferableChats } from '../../../host-hooks';
+import { useHostReferables } from '../../../host-hooks';
 
 const SEARCH_DEBOUNCE_MS = 80;
 // What fits above the composer without turning the picker into a file tree.
 const MENTION_RESULTS = 8;
-// The chats go above the files, so a few leave the files in view.
-const CHAT_RESULTS = 4;
+const REFERENCE_RESULTS = 8;
 
 // Commands the composer handles itself; the CLI's own ones are sent through as text.
 export const LOCAL_COMMANDS = ['model', 'compact', 'clear'];
@@ -55,17 +57,19 @@ function sameQuery(left: MentionQuery | null, right: MentionQuery | null): boole
 }
 
 /*
- * The pickers over the box: `/` for a command, `$` for a skill and `@` for a file or another chat.
- * One is open at a time, and the arrow keys and the editor's ARIA attributes follow that one.
+ * The pickers over the box: `/` for a command, `$` for a skill, `@` for a file and `#` for a view,
+ * a node or another chat. One is open at a time, and the arrow keys and the editor's ARIA attributes
+ * follow that one.
  */
 export function useComposerMenus({ chatId, info, capabilities, providerName, draft: { draft, setDraft, setText }, inputRef }: MenusInput) {
     const { t } = useTranslation('agent-chat');
     const scope = useChatScope();
     const host = useChatHost();
     const { searchFiles } = host;
-    const chats = useHostReferableChats();
+    const referables = useHostReferables(scope.id, chatId);
     const [menuIndex, setMenuIndex] = useState(0);
     const [mention, setMention] = useState<MentionQuery | null>(null);
+    const [referenceQuery, setReferenceQuery] = useState<MentionQuery | null>(null);
     const [skillQuery, setSkillQuery] = useState<MentionQuery | null>(null);
     const [skills, setSkills] = useState<ChatSkill[]>([]);
     const [searched, setSearched] = useState<MentionSearch>(NO_MENTION_SEARCH);
@@ -157,26 +161,39 @@ export function useComposerMenus({ chatId, info, capabilities, providerName, dra
     const mentionMenuOpen = !commandMenuOpen && !skillMenuOpen && mention !== null;
     // Results belong to the query that asked for them; a closed picker shows none while the next answer is on its way.
     const files = mention === null ? [] : searched.files;
-    const chatMatches = mention === null ? [] : chatSuggestions(chats, mention.query, [chatId, ...draft.chats], CHAT_RESULTS);
-    const mentionCount = chatMatches.length + files.length;
+    const mentionCount = files.length;
+    // A host with nothing to point at keeps `#fff` out of the way rather than saying nothing matches.
+    const offersReferences = referables.items.some((item) => !referables.chatsOnly || item.kind === 'chat');
+    const referenceMenuOpen = !commandMenuOpen && !skillMenuOpen && !mentionMenuOpen && referenceQuery !== null && offersReferences;
+    const referenceMatches = referenceMenuOpen
+        ? referenceSuggestions(referables, referenceQuery.query, [chatId, ...draft.chats, ...draft.references], REFERENCE_RESULTS)
+        : [];
+    // What the editor draws as chips and the send checks are still in the text, under the name each was picked with.
+    const referenceChips = referenceTokens([...draft.chats, ...draft.references], referables.items, draft.referenceNames).map((token) => ({
+        ...token,
+        kind: referables.items.find((item) => item.id === token.id)?.kind ?? null
+    }));
     // One menu is open at a time, so they share an id.
     const listId = useId();
-    const menuOpen = commandMenuOpen || skillMenuOpen || mentionMenuOpen;
-    const menuCount = commandMenuOpen ? commands.length : skillMenuOpen ? skillMatches.length : mentionCount;
+    const menuOpen = commandMenuOpen || skillMenuOpen || mentionMenuOpen || referenceMenuOpen;
+    const menuCount = commandMenuOpen ? commands.length : skillMenuOpen ? skillMatches.length : mentionMenuOpen ? mentionCount : referenceMatches.length;
     // The list can shrink under a stale index; every reader takes the one that still points at an option.
     const activeIndex = clampMenuIndex(menuIndex, menuCount);
     const inputAria = composerMenuAria({ label: t('composer.inputLabel'), listId, open: menuOpen, activeIndex, count: menuCount });
 
-    /* Which picker the caret opens: `@` for a file, `$` for a skill, or neither. In code a sigil is just text. */
+    /* Which picker the caret opens: `@` for a file, `$` for a skill, `#` for a reference, or none. In code a sigil is just text. */
     const trackTriggers = (value: string, selection: TextRange, state: EditorState): void => {
         const empty = selection.from === selection.to;
         const tree = empty ? (ensureSyntaxTree(state, selection.from, 50) ?? syntaxTree(state)) : null;
         const caret = tree !== null && !inCode(tree, value, selection.from) ? selection.from : null;
-        const skill = caret === null ? null : findSkillQuery(value, caret);
+        const chips = caret === null ? [] : chipRanges(value, draft.mentions, draft.skills, [], referenceChips);
+        const skill = caret === null ? null : queryOutsideChips(findSkillQuery(value, caret), chips);
         setSkillQuery((current) => (sameQuery(current, skill) ? current : skill));
         // A CLI that does not expand `@path` gets the text as it is, so the picker stays out of the way.
-        const next = caret === null || capabilities?.mentions === false ? null : findMentionQuery(value, caret);
+        const next = caret === null || capabilities?.mentions === false ? null : queryOutsideChips(findMentionQuery(value, caret), chips);
         setMention((current) => (sameQuery(current, next) ? current : next));
+        const reference = caret === null ? null : queryOutsideChips(findReferenceQuery(value, caret), chips);
+        setReferenceQuery((current) => (sameQuery(current, reference) ? current : reference));
     };
 
     // The inserted text reaches the editor with the render it causes, so the caret waits a frame for it.
@@ -187,6 +204,7 @@ export function useComposerMenus({ chatId, info, capabilities, providerName, dra
     const close = (): void => {
         setMention(null);
         setSkillQuery(null);
+        setReferenceQuery(null);
     };
 
     const chooseMention = (path: string): void => {
@@ -199,23 +217,39 @@ export function useComposerMenus({ chatId, info, capabilities, providerName, dra
         moveCaret(result.caret);
     };
 
-    /* A picked chat sits beside the text as a chip, so the `@query` that found it goes. */
-    const chooseChat = (id: string): void => {
-        if (!mention) {
+    const chooseMentionAt = (index: number): void => {
+        const path = mention === null ? null : mentionPick(index, searched, mention.query);
+        if (path !== null) {
+            chooseMention(path);
+        }
+    };
+
+    /*
+     * A picked view, node or chat becomes a `#name` chip in the text. The draft keeps the name it was
+     * spelled with, since a rename would otherwise unmake the chip. A chat goes apart, as `chats`.
+     */
+    const chooseReference = (item: Referable): void => {
+        if (!referenceQuery) {
             return;
         }
-        const result = dropQuery(text, mention);
-        setDraft((current) => ({ ...current, text: result.text, chats: current.chats.includes(id) ? current.chats : [...current.chats, id] }));
-        setMention(null);
+        const result = insertReference(text, referenceQuery, item.name);
+        const chat = item.kind === 'chat';
+        const add = (ids: string[]): string[] => (ids.includes(item.id) ? ids : [...ids, item.id]);
+        setDraft((current) => ({
+            ...current,
+            text: result.text,
+            chats: chat ? add(current.chats) : current.chats,
+            references: chat ? current.references : add(current.references),
+            referenceNames: { ...current.referenceNames, [item.id]: item.name }
+        }));
+        setReferenceQuery(null);
         moveCaret(result.caret);
     };
 
-    const chooseMentionAt = (index: number): void => {
-        const pick = mention === null ? null : mentionPick(index, chatMatches, searched, mention.query);
-        if (pick?.kind === 'chat') {
-            chooseChat(pick.chat.id);
-        } else if (pick?.kind === 'file') {
-            chooseMention(pick.path);
+    const chooseReferenceAt = (index: number): void => {
+        const item = referenceMatches[index] ?? referenceMatches[0];
+        if (item !== undefined) {
+            chooseReference(item);
         }
     };
 
@@ -259,6 +293,7 @@ export function useComposerMenus({ chatId, info, capabilities, providerName, dra
         activeIndex,
         inputAria,
         hasSkills: skills.length > 0,
+        skillNames: skills.map((skill) => skill.name),
         commandQuery,
         commands,
         commandMenuOpen,
@@ -267,14 +302,18 @@ export function useComposerMenus({ chatId, info, capabilities, providerName, dra
         mention,
         mentionMenuOpen,
         mentionCount,
-        chatMatches,
         files,
+        referenceMenuOpen,
+        referenceMatches,
+        referables,
+        referenceChips,
         setMenuIndex,
         trackTriggers,
         close,
         chooseMention,
-        chooseChat,
         chooseMentionAt,
+        chooseReference,
+        chooseReferenceAt,
         chooseSkill,
         pickCommand,
         moveInMenu

package/src/chat/ui/composer/use-composer-submit.ts

@@ -8,7 +8,7 @@ import { registerComposerSender, type ComposerSend } from '../../composer-send';
 import { isEmptyDraft } from '../../drafts';
 import { CONTINUE_PROMPT } from '../../logic/continue-after-stop';
 import type { PromptGuard } from '../../guards';
-import { presentMentions, presentSkills } from '../../mentions';
+import { presentMentions, presentReferences, presentSkills } from '../../mentions';
 import { withQuote } from '../../quote';
 import { restorableChats, stashDraft, useStash, type StashedPrompt } from '../../stash';
 import { scrollTimelineToEnd } from '../../timeline-scroll';
@@ -19,7 +19,6 @@ import type { ComposerDraft } from './use-composer-draft';
 import type { ComposerMenus } from './use-composer-menus';
 import type { PromptHistory } from './use-prompt-history';
 import type { ComposerPromptHold } from './use-prompt-hold';
-import { useHostReferableChats } from '../../../host-hooks';
 
 interface SubmitInput {
     chatId: string;
@@ -59,7 +58,6 @@ export function useComposerSubmit({
     const host = useChatHost();
     const scope = useChatScope();
     const { draft, setDraft } = box;
-    const referable = useHostReferableChats();
 
     /* Opens the host's new chat once the host took the message; a host that answers nothing took it. */
     const afterSend = (sent: void | Promise<boolean>, andNew: boolean): void => {
@@ -111,13 +109,17 @@ export function useComposerSubmit({
             box.clear();
             return;
         }
+        const chats = presentReferences(trimmed, draft.chats, menus.referenceChips);
+        // A machine without `viewReferences` drops the field, so only the chats it does know reach it.
+        const references = menus.referables.chatsOnly ? [] : presentReferences(trimmed, draft.references, menus.referenceChips);
         const sent = onSend(withQuote(quote, trimmed), {
             delivery,
             mentions: presentMentions(trimmed, draft.mentions),
             skills: presentSkills(trimmed, draft.skills),
-            chats: draft.chats,
+            chats,
             quoteSource: quote !== '' && quoteSource !== null ? { itemId: quoteSource } : undefined,
-            attachments: draft.attachments
+            attachments: draft.attachments,
+            references: references.length > 0 ? references : undefined
         });
         afterSend(sent, how === 'and-new');
         box.clear();
@@ -140,13 +142,18 @@ export function useComposerSubmit({
     const restoreStashed = (prompt: StashedPrompt): void => {
         const stashedQuote = prompt.quote;
         const here = stashedQuote !== undefined && stashedQuote.chatId === chatId;
-        const { chats, dropped } = restorableChats(prompt.chats, new Set(referable.map((chat) => chat.id)), chatId);
+        const { chats, dropped } = restorableChats(
+            prompt.chats,
+            new Set(menus.referables.items.filter((item) => item.kind === 'chat').map((item) => item.id)),
+            chatId
+        );
         setDraft((current) => ({
             ...current,
             text: stashedQuote === undefined || here ? prompt.text : withQuote(stashedQuote.text, prompt.text),
             mentions: [...prompt.mentions],
             skills: [...prompt.skills],
             chats,
+            references: [...prompt.references],
             ...(here ? { quote: stashedQuote.text, quoteSource: stashedQuote.itemId } : {})
         }));
         if (dropped > 0) {

package/src/chat/ui/composer/use-draft-files.ts

@@ -5,8 +5,10 @@ import type { ProviderCapabilities } from '@adecore/agent-contracts';
 import { useChatHost } from '../../../host';
 import { checkAttachmentLimits, filesOf, readAttachments, uploadBytes } from '../../attachments';
 import { pasteBecomesAttachment, pastedTextName } from '../../guards';
-import { carriesMentions, droppedMentions, pastedMentions } from '../../mentions';
+import type { Referable } from '../../chat-references';
+import { carriesMentions, droppedMentions, pastedMentions, readClipboardChips, type ReferenceToken } from '../../mentions';
 import type { ComposerInputHandle } from '../ComposerInput';
+import { copyWithChipsFromEditor, pasteWithChips, withPastedChips, type PasteChoices } from './chip-paste';
 import type { ComposerDraft } from './use-composer-draft';
 
 /* The card turns dropped files and paths into attachments and chips; CodeMirror would also paste their text at the drop point. */
@@ -21,10 +23,28 @@ interface DraftFilesInput {
     draft: ComposerDraft;
     inputRef: RefObject<ComposerInputHandle | null>;
     setNotice(notice: string): void;
+    /* The skills there are and what `#` points at, which a paste makes chips of. */
+    skills: readonly string[];
+    referables: readonly Referable[];
+    /* The draft's `#` picks under the names the text spells them by. */
+    referenceChips: readonly ReferenceToken[];
 }
 
-/* What reaches the draft besides typing: files as attachments, dragged paths as mentions, and a long paste as a file of its own. */
-export function useDraftFiles({ capabilities, providerName, writable, draft: { draft, setDraft, setText }, inputRef, setNotice }: DraftFilesInput) {
+/*
+ * What reaches the draft besides typing: files as attachments, dragged paths as mentions, a long paste
+ * as a file of its own, and the chips a copy carried or a pasted text spells.
+ */
+export function useDraftFiles({
+    capabilities,
+    providerName,
+    writable,
+    draft: { draft, setDraft, setText },
+    inputRef,
+    setNotice,
+    skills,
+    referables,
+    referenceChips
+}: DraftFilesInput) {
     const { t } = useTranslation('agent-chat');
     const { isApplePlatform } = useChatHost();
     const [dragging, setDragging] = useState(false);
@@ -94,7 +114,19 @@ export function useDraftFiles({ capabilities, providerName, writable, draft: { d
         }
         // Without attachments there is nowhere else for the text to go, so it pastes as it always did.
         if (inline || capabilities?.attachments === false || !pasteBecomesAttachment(clip)) {
-            return false;
+            const choices: PasteChoices = {
+                skills,
+                referables,
+                referenced: [...draft.chats, ...draft.references],
+                mentions: capabilities?.mentions !== false
+            };
+            const chips = pasteWithChips(view, clip, readClipboardChips(data), choices);
+            if (chips === null) {
+                return false;
+            }
+            // After the editor's own change, which reads the draft as it was rendered.
+            setDraft((current) => withPastedChips(current, chips, choices));
+            return true;
         }
         // The paste still replaces what was selected; it just puts nothing in its place.
         const { from, to } = view.state.selection.main;
@@ -106,6 +138,8 @@ export function useDraftFiles({ capabilities, providerName, writable, draft: { d
         return true;
     };
 
+    const onCopy = (e: ClipboardEvent, view: EditorView): boolean => copyWithChipsFromEditor(e, view, draft, referenceChips);
+
     /* The whole card takes a dropped file, so a layout around it that takes drops of its own leaves it alone. */
     const dropTarget = {
         'data-takes-drop': 'all',
@@ -131,5 +165,5 @@ export function useDraftFiles({ capabilities, providerName, writable, draft: { d
         }
     };
 
-    return { dragging, dropTarget, addFiles, noteKey, onPaste };
+    return { dragging, dropTarget, addFiles, noteKey, onPaste, onCopy };
 }

package/src/chat/ui/composer/use-take-back.ts

@@ -58,7 +58,8 @@ export function useTakeBack({ chatId, draft: { latest, setDraft }, setNotice, on
                 mentions: message.mentions ?? [],
                 skills: message.skills ?? [],
                 chats: message.chats ?? [],
-                attachments: uploads
+                attachments: uploads,
+                references: message.references ?? []
             };
             // A file that would not fit is refused here, while the message still holds it on the machine.
             const wouldReject = takeBackIntoDraft(latest.current, taken).rejected[0];

package/src/chat/ui/index.ts

@@ -3,7 +3,6 @@ export { AccountPill } from './AccountPill';
 export { AnsiOutput } from './AnsiOutput';
 export { BookmarkSubmenu } from './BookmarkSubmenu';
 export { ChatActivity, StatusIcon } from './ChatActivity';
-export { ChatReferenceChip } from './ChatReferenceChip';
 export { CodeBlock } from './CodeBlock';
 export { Composer } from './Composer';
 export { type ComposerInputHandle, ComposerInput, type InputSelection } from './ComposerInput';

package/src/chat/ui/reference-icons.ts

@@ -0,0 +1,17 @@
+import { Database, FileText, Frame, Globe, MessageSquare, PenTool, Smartphone, StickyNote, Terminal, Type, Workflow, type LucideIcon } from 'lucide-react';
+import type { ReferableKind } from '../chat-references';
+
+/* The mark of what a `#` points at, in the picker and on its chip. */
+export const REFERENCE_ICONS: Record<ReferableKind, LucideIcon> = {
+    canvas: Frame,
+    chat: MessageSquare,
+    terminal: Terminal,
+    note: StickyNote,
+    text: Type,
+    drawing: PenTool,
+    diagram: Workflow,
+    browser: Globe,
+    device: Smartphone,
+    file: FileText,
+    database: Database
+};

package/src/chat/ui/reference-lookup.ts

@@ -0,0 +1,13 @@
+import { createContext } from 'react';
+import type { Referable } from '../chat-references';
+
+export interface ReferenceLookup {
+    items: readonly Referable[];
+    /* Null where the host opens nothing. */
+    open: ((id: string) => void) | null;
+    /* What a person pointed at with `#` in this thread, which a reply wins over another of the same name. */
+    referenced?: readonly string[];
+}
+
+/* What the views and nodes of a message stand for now, handed down by the row that draws it. */
+export const ReferenceLookupContext = createContext<ReferenceLookup>({ items: [], open: null });

package/src/chat/ui/rehype-chips.ts

@@ -1,4 +1,4 @@
-import { chipText, tokenizeChips, type ChipSegment } from '../mentions';
+import { chipText, tokenizeChips, tokenizeNamedReferences, type ChipSegment, type ReferenceToken } from '../mentions';
 
 /* Just the part of hast this plugin touches; the package's own types are not a dependency here. */
 interface HastText {
@@ -22,41 +22,66 @@ interface HastParent {
 export interface ChipOptions {
     mentions?: string[];
     skills?: string[];
+    references?: readonly ReferenceToken[];
+}
+
+export interface NamedReferenceOptions {
+    items: readonly ReferenceToken[];
+    /* Ids a person pointed at with `#` in the thread, which win over another of the same name. */
+    referenced?: readonly string[];
+}
+
+function valueOf(segment: Exclude<ChipSegment, { kind: 'text' }>): string {
+    if (segment.kind === 'mention') {
+        return segment.path;
+    }
+    return segment.kind === 'skill' ? segment.name : segment.id;
 }
 
 // Inline code overrules a chip: `@a.ts` between backticks is code, not a mention.
 const SKIPPED = new Set(['code', 'pre']);
 
-/* A chip as an element: the renderer reads `data-chip` and `data-value`, the text keeps the sigil. */
+// A link already leads somewhere of its own.
+const SKIPPED_IN_REPLIES = new Set(['code', 'pre', 'a']);
+
+/* A chip as an element: the renderer reads `data-chip` and `data-value` (a reference's id), the text keeps the sigil. */
 function chipElement(segment: Exclude<ChipSegment, { kind: 'text' }>): HastElement {
     return {
         type: 'element',
         tagName: 'span',
-        properties: { dataChip: segment.kind, dataValue: segment.kind === 'mention' ? segment.path : segment.name },
+        properties: { dataChip: segment.kind, dataValue: valueOf(segment) },
         children: [{ type: 'text', value: chipText(segment) }]
     };
 }
 
-function split(parent: HastParent, mentions: string[], skills: string[]): void {
+function split(parent: HastParent, tokenize: (text: string) => ChipSegment[], skipped: ReadonlySet<string>): void {
     parent.children = parent.children.flatMap((child): HastNode[] => {
         if (child.type === 'text') {
-            return tokenizeChips(child.value, mentions, skills).map((segment) =>
-                segment.kind === 'text' ? { type: 'text', value: segment.text } : chipElement(segment)
-            );
+            return tokenize(child.value).map((segment) => (segment.kind === 'text' ? { type: 'text', value: segment.text } : chipElement(segment)));
         }
-        if (child.type === 'element' && !SKIPPED.has(child.tagName)) {
-            split(child, mentions, skills);
+        if (child.type === 'element' && !skipped.has(child.tagName)) {
+            split(child, tokenize, skipped);
         }
         return [child];
     });
 }
 
-/* The `@path` and `$name` tokens a person picked in the composer, cut out of the text as chips. */
-export function rehypeChips({ mentions = [], skills = [] }: ChipOptions = {}) {
+/* The `@path`, `$name` and `#name` tokens a person picked in the composer, cut out of the text as chips. */
+export function rehypeChips({ mentions = [], skills = [], references = [] }: ChipOptions = {}) {
+    return (tree: HastParent) => {
+        if (mentions.length === 0 && skills.length === 0 && references.length === 0) {
+            return;
+        }
+        split(tree, (text) => tokenizeChips(text, mentions, skills, references), SKIPPED);
+    };
+}
+
+/* The `#Name` a reply spells for a view, node or chat by exactly its name, cut out of the text as chips. */
+export function rehypeNamedReferences({ items, referenced = [] }: NamedReferenceOptions) {
     return (tree: HastParent) => {
-        if (mentions.length === 0 && skills.length === 0) {
+        if (items.length === 0) {
             return;
         }
-        split(tree, mentions, skills);
+        split(tree, (text) => (text.includes('#') ? tokenizeNamedReferences(text, items, referenced) : [{ kind: 'text', text }]), SKIPPED_IN_REPLIES);
     };
 }