@adecore/agents-react 0.37.2 → 0.38.0

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);
     };
 }

package/src/chat/ui/rows/GeneratedImageRow.tsx

@@ -13,6 +13,7 @@ import { attachmentAspect, generatedImageView, type GeneratedImageFailure } from
 import { toolStartedAt } from '../../logic/tools';
 import { CHIP_IN_MESSAGE, MENTION_TONE } from '../chips';
 import { useFileLinkCwd, useOpenFileLink } from '../file-links';
+import { HostMenuItems } from '../HostMenuItems';
 import { ImageThumb } from '../ImageView';
 import { ROW_GUTTER } from '../icons';
 import { RunningFor, WorkRow } from './WorkRows';
@@ -104,6 +105,7 @@ function ReadyImage({ chatId, attachment, prompt, transparent }: { chatId: strin
     const missing = source.failure !== null;
     const aspect = attachmentAspect(attachment);
     const { open, saveToProject } = attachments;
+    const extra = attachments.actions?.(scopeId, chatId, attachment) ?? [];
 
     const detail = [
         attachment.width !== undefined && attachment.height !== undefined
@@ -171,13 +173,16 @@ function ReadyImage({ chatId, attachment, prompt, transparent }: { chatId: strin
                         >
                             <ButtonGroup>
                                 <IconButton icon={Maximize2} size="sm" label={t('generatedImage.openLarge')} onClick={() => setLightbox(true)} />
-                                {prompt !== null && (
+                                {(prompt !== null || extra.length > 0) && (
                                     <Menu.Root>
                                         <IconButton icon={Ellipsis} size="sm" label={t('generatedImage.more')} render={<Menu.Trigger />} />
                                         <Menu.Popup align="end">
-                                            <Menu.Item onClick={() => copyText(prompt)}>
-                                                <Icon icon={Copy} size={14} /> {t('generatedImage.copyPrompt')}
-                                            </Menu.Item>
+                                            {prompt !== null && (
+                                                <Menu.Item onClick={() => copyText(prompt)}>
+                                                    <Icon icon={Copy} size={14} /> {t('generatedImage.copyPrompt')}
+                                                </Menu.Item>
+                                            )}
+                                            <HostMenuItems actions={extra} />
                                         </Menu.Popup>
                                     </Menu.Root>
                                 )}

package/src/chat/ui/rows/MessageRows.tsx

@@ -18,7 +18,10 @@ import { useChatScope } from '../../../scope';
 import { splitQuote } from '../../quote';
 import { jumpToTimelineItem } from '../../timeline-scroll';
 import { useProviders } from '../../../state/providers';
-import { ChatReferenceChip } from '../ChatReferenceChip';
+import { referenceTokens } from '../../chat-references';
+import { presentReferences } from '../../mentions';
+import { ReferenceChip } from '../ReferenceChip';
+import { ReferenceLookupContext } from '../reference-lookup';
 import { ImageThumb } from '../ImageView';
 import { Markdown, MessageMarkdown, ReplyMarkdown } from '../Markdown';
 import { FadingWords } from '../FadingWords';
@@ -34,6 +37,8 @@ import { useOpenForFind } from '../find-reveal';
 import { ReplyContext, UiReplyNavigationContext } from '../reply-context';
 import { UiReply } from '../intelligent-ui/UiReply';
 import { useHostAttachmentUrl, useHostChatPlace, useHostReplyAuthor, useHostStreaming } from '../../../host-hooks';
+import { copySelectionWithChips } from '../chip-clipboard';
+import { useReferenceLookup } from '../thread-references';
 
 // A long prompt folds so the answer stays in view; the reader can open it.
 const USER_FOLD_LINES = 8;
@@ -89,9 +94,14 @@ export function UserRow({ chatId, item }: { chatId: string; item: ChatUserItem }
     const [open, setOpen] = useState(false);
     const long = item.text.split('\n').length > USER_FOLD_LINES || item.text.length > USER_FOLD_CHARS;
     const attachments = item.attachments ?? [];
-    const chats = item.chats ?? [];
     const [missing, setMissing] = useState(false);
     const { keyOf } = useChatScope();
+    const lookup = useReferenceLookup(chatId);
+    const referenced = [...(item.chats ?? []), ...(item.references ?? [])];
+    const references = referenceTokens(referenced, lookup.items);
+    // A chat attached before `#` existed, or a view renamed or gone since, is not in the text; it stands beside it.
+    const placed = presentReferences(item.text, referenced, references);
+    const beside = referenced.filter((id) => !placed.includes(id));
     useOpenForFind(item.id, 'text', setOpen);
     // A quote only leads somewhere when the message still opens with the blockquote it was sent with.
     const quoted = item.quoteSource === undefined ? null : splitQuote(item.text);
@@ -104,65 +114,69 @@ export function UserRow({ chatId, item }: { chatId: string; item: ChatUserItem }
         }
     }
     return (
-        <div data-find-item={item.id} className="flex flex-col items-end">
-            <MessageHeading>{t('rows.user.heading')}</MessageHeading>
-            {attachments.length > 0 && (
-                <div className="mb-1.5 flex max-w-[80%] flex-wrap justify-end gap-1.5">
-                    {attachments.map((attachment) =>
-                        isImageAttachment(attachment.mime) ? (
-                            <AttachmentThumb key={attachment.id} chatId={chatId} attachment={attachment} />
-                        ) : (
-                            <AttachmentLink key={attachment.id} chatId={chatId} attachment={attachment} />
-                        )
-                    )}
-                </div>
-            )}
-            {chats.length > 0 && (
-                <div className="mb-1.5 flex max-w-[80%] flex-wrap justify-end gap-1.5">
-                    {chats.map((id) => (
-                        <ChatReferenceChip key={id} chatId={id} />
-                    ))}
-                </div>
-            )}
-            {item.uiChoice !== undefined && <ChoiceLine chatId={chatId} choice={item.uiChoice} />}
-            {item.text !== '' && (
-                <div className="relative max-w-[80%] rounded-2xl bg-surface-active px-3.5 py-2.5 text-sm wrap-anywhere text-text select-text">
-                    <div data-find-field="text" className={clsx(long && !open && FOLD)}>
-                        {quoted !== null && source !== undefined ? (
-                            <>
-                                {/* A div, since the quote is block markdown and a button holds none. */}
-                                <Tooltip label={t('composer.quote.goToSource')}>
-                                    <div
-                                        role="button"
-                                        tabIndex={0}
-                                        className="mb-2 cursor-pointer rounded-sm border-l-2 border-border-strong pl-2.5 text-text-muted hover:bg-text/5 hover:text-text focus-visible:outline-2 focus-visible:outline-accent"
-                                        onClick={goToSource}
-                                        onKeyDown={(e) => {
-                                            if (e.key === 'Enter' || e.key === ' ') {
-                                                e.preventDefault();
-                                                goToSource();
-                                            }
-                                        }}
-                                    >
-                                        <MessageMarkdown text={quoted.quote} />
-                                    </div>
-                                </Tooltip>
-                                {missing && <div className="mb-2 text-xs text-text-faint">{t('rows.user.quoteGone')}</div>}
-                                {quoted.rest !== '' && <MessageMarkdown text={quoted.rest} mentions={item.mentions} skills={item.skills} />}
-                            </>
-                        ) : (
-                            <MessageMarkdown text={item.text} mentions={item.mentions} skills={item.skills} />
+        <ReferenceLookupContext value={lookup}>
+            <div data-find-item={item.id} className="flex flex-col items-end" onCopy={(e) => copySelectionWithChips(e.nativeEvent)}>
+                <MessageHeading>{t('rows.user.heading')}</MessageHeading>
+                {attachments.length > 0 && (
+                    <div className="mb-1.5 flex max-w-[80%] flex-wrap justify-end gap-1.5">
+                        {attachments.map((attachment) =>
+                            isImageAttachment(attachment.mime) ? (
+                                <AttachmentThumb key={attachment.id} chatId={chatId} attachment={attachment} />
+                            ) : (
+                                <AttachmentLink key={attachment.id} chatId={chatId} attachment={attachment} />
+                            )
                         )}
                     </div>
-                    {long && (
-                        <button className="mt-1 flex items-center gap-1 text-xs text-text-muted hover:text-text" onClick={() => setOpen((o) => !o)}>
-                            <Icon icon={ChevronDown} size={12} className={clsx('transition-transform', open && 'rotate-180')} />{' '}
-                            {open ? t('rows.user.showLess') : t('rows.user.showAll')}
-                        </button>
-                    )}
-                </div>
-            )}
-        </div>
+                )}
+                {beside.length > 0 && (
+                    <div className="mb-1.5 flex max-w-[80%] flex-wrap justify-end gap-1.5">
+                        {beside.map((id) => (
+                            <ReferenceChip key={id} id={id} />
+                        ))}
+                    </div>
+                )}
+                {item.uiChoice !== undefined && <ChoiceLine chatId={chatId} choice={item.uiChoice} />}
+                {item.text !== '' && (
+                    <div className="relative max-w-[80%] rounded-2xl bg-surface-active px-3.5 py-2.5 text-sm wrap-anywhere text-text select-text">
+                        <div data-find-field="text" className={clsx(long && !open && FOLD)}>
+                            {quoted !== null && source !== undefined ? (
+                                <>
+                                    {/* A div, since the quote is block markdown and a button holds none. */}
+                                    <Tooltip label={t('composer.quote.goToSource')}>
+                                        <div
+                                            role="button"
+                                            tabIndex={0}
+                                            className="mb-2 cursor-pointer rounded-sm border-l-2 border-border-strong pl-2.5 text-text-muted hover:bg-text/5 hover:text-text focus-visible:outline-2 focus-visible:outline-accent"
+                                            onClick={goToSource}
+                                            onKeyDown={(e) => {
+                                                if (e.key === 'Enter' || e.key === ' ') {
+                                                    e.preventDefault();
+                                                    goToSource();
+                                                }
+                                            }}
+                                        >
+                                            <MessageMarkdown text={quoted.quote} />
+                                        </div>
+                                    </Tooltip>
+                                    {missing && <div className="mb-2 text-xs text-text-faint">{t('rows.user.quoteGone')}</div>}
+                                    {quoted.rest !== '' && (
+                                        <MessageMarkdown text={quoted.rest} mentions={item.mentions} skills={item.skills} references={references} />
+                                    )}
+                                </>
+                            ) : (
+                                <MessageMarkdown text={item.text} mentions={item.mentions} skills={item.skills} references={references} />
+                            )}
+                        </div>
+                        {long && (
+                            <button className="mt-1 flex items-center gap-1 text-xs text-text-muted hover:text-text" onClick={() => setOpen((o) => !o)}>
+                                <Icon icon={ChevronDown} size={12} className={clsx('transition-transform', open && 'rotate-180')} />{' '}
+                                {open ? t('rows.user.showLess') : t('rows.user.showAll')}
+                            </button>
+                        )}
+                    </div>
+                )}
+            </div>
+        </ReferenceLookupContext>
     );
 }
 
@@ -262,10 +276,12 @@ function Writing() {
  * A reply. A word at a time, it follows the text as it arrives. A block at a time, the blocks that
  * closed are drawn and fade in as they land, with "Writing…" where the next one will stand. Whole,
  * it says it is being written and fades in once it is done. Only a row that saw the reply being
- * written fades anything: an old reply scrolled back into view just stands there.
+ * written fades anything: an old reply scrolled back into view just stands there. A `#Name` it
+ * spells for a view, node or chat of the project is a chip that opens it.
  */
 export function AssistantRow({ chatId, item: derived }: { chatId: string; item: ChatAssistantItem }) {
     const item = useCurrentItem(chatId, derived);
+    const lookup = useReferenceLookup(chatId);
     const scope = useChatScope();
     const context = useContext(ReplyContext);
     const reply = context === null && !item.parentToolUseId ? { scopeId: scope.id, chatId, itemId: item.id, streaming: item.streaming } : undefined;
@@ -295,11 +311,13 @@ export function AssistantRow({ chatId, item: derived }: { chatId: string; item:
     if (mode === 'blocks') {
         const settled = item.streaming ? settledBlocksText(item.text) : item.text;
         return (
-            <div data-find-item={item.id} className="-mx-1 px-1 pb-2">
+            <div data-find-item={item.id} className="-mx-1 px-1 pb-2" onCopy={(e) => copySelectionWithChips(e.nativeEvent)}>
                 <ReplyHeading chatId={chatId} />
                 {settled !== '' && (
                     <div data-find-field="text" data-quote-answer className="contents">
-                        <ReplyMarkdown text={settled} streaming={false} arriving={sawWriting} reply={reply} />
+                        <ReferenceLookupContext value={lookup}>
+                            <ReplyMarkdown text={settled} streaming={false} arriving={sawWriting} reply={reply} />
+                        </ReferenceLookupContext>
                     </div>
                 )}
                 {item.streaming && <Writing />}
@@ -315,10 +333,16 @@ export function AssistantRow({ chatId, item: derived }: { chatId: string; item:
         );
     }
     return (
-        <div data-find-item={item.id} className={clsx('-mx-1 px-1 pb-2', mode === 'whole' && sawWriting && WHOLE_FADE_CLASS)}>
+        <div
+            data-find-item={item.id}
+            className={clsx('-mx-1 px-1 pb-2', mode === 'whole' && sawWriting && WHOLE_FADE_CLASS)}
+            onCopy={(e) => copySelectionWithChips(e.nativeEvent)}
+        >
             <ReplyHeading chatId={chatId} />
             <div data-find-field="text" data-quote-answer className="contents">
-                <ReplyMarkdown text={reveal.text} streaming={reveal.active} reply={reply} />
+                <ReferenceLookupContext value={lookup}>
+                    <ReplyMarkdown text={reveal.text} streaming={reveal.active} reply={reply} />
+                </ReferenceLookupContext>
             </div>
             {live && item.text === '' && <span className="inline-block h-3.5 w-1.5 animate-pulse rounded-sm bg-text-faint align-middle" />}
         </div>

package/src/chat/ui/rows/VisualRow.tsx

@@ -5,6 +5,7 @@ import { ButtonGroup, ErrorBoundary, Icon, IconButton, Menu, Surface } from '@ad
 import { useChatHost } from '../../../host';
 import { useChatScope } from '../../../scope';
 import { useVisualDialog } from '../../visuals';
+import { HostMenuItems } from '../HostMenuItems';
 import { VisualFrame } from '../VisualFrame';
 
 /*
@@ -16,10 +17,11 @@ import { VisualFrame } from '../VisualFrame';
 export function VisualRow({ chatId, visual }: { chatId: string; visual: ChatVisual }) {
     const host = useChatHost();
     const { t } = useTranslation('agent-chat');
-    const { keyOf } = useChatScope();
+    const { id: scopeId, keyOf } = useChatScope();
     if (host.visuals === null) {
         return null;
     }
+    const extra = host.visuals.actions?.(scopeId, chatId, visual) ?? [];
     const open = (kind: 'expand' | 'remove'): void => useVisualDialog.getState().open(keyOf(chatId), visual.id, kind);
     return (
         <ErrorBoundary label={t('visuals.renderFailed')} resetKeys={[visual]} compact className="relative rounded-lg">
@@ -35,6 +37,8 @@ export function VisualRow({ chatId, visual }: { chatId: string; visual: ChatVisu
                         <Menu.Root>
                             <IconButton icon={Ellipsis} size="sm" label={t('visuals.more')} render={<Menu.Trigger />} />
                             <Menu.Popup align="end">
+                                <HostMenuItems actions={extra} />
+                                {extra.length > 0 && <Menu.Separator />}
                                 <Menu.Item onClick={() => open('remove')}>
                                     <Icon icon={Trash2} size={14} /> {t('visuals.remove')}
                                 </Menu.Item>

package/src/chat/ui/rows/row-rhythm.ts

@@ -7,13 +7,15 @@ export const FOLLOW_THRESHOLD_PX = 40;
 
 /*
  * The gaps a row wears for where it sits: a question is followed by its answer gap, and a seam where
- * the list rhythm of tool lines meets the block rhythm of prose gets the block gap. A visual has no
- * margin of its own like prose does, so the row under one takes the block gap too. A question
- * already carries the gap before it, and the row after one is the answer, so neither takes a seam.
+ * the list rhythm of tool lines meets the block rhythm of prose gets the block gap. A visual and an
+ * app's card have no margin of their own like prose does, so the row under one takes the block gap
+ * too. A question already carries the gap before it, and the row after one is the answer, so neither
+ * takes a seam.
  */
 export function rowRhythm(row: TimelineRow, previous: TimelineRow | null): string {
     const question = row.kind === 'user';
-    const seam = !question && previous !== null && previous.kind !== 'user' && (isBlock(row) !== isBlock(previous) || previous.kind === 'visual');
+    const bare = previous?.kind === 'visual' || previous?.kind === 'app-card';
+    const seam = !question && previous !== null && previous.kind !== 'user' && (isBlock(row) !== isBlock(previous) || bare);
     return clsx(question && 'pb-(--chat-answer-gap)', seam && 'pt-(--chat-block-gap)');
 }
 

package/src/chat/ui/thread-references.ts

@@ -0,0 +1,47 @@
+import type { ChatItem } from '@adecore/agent-contracts';
+import { useChatHost } from '../../host';
+import { useHostReferables } from '../../host-hooks';
+import { useChatScope } from '../../scope';
+import { useChatRow } from '../../state/chats';
+import type { ReferenceLookup } from './reference-lookup';
+
+const referencedOf = new WeakMap<Record<string, ChatItem>, string>();
+
+/*
+ * The ids a person pointed at with `#` in a thread, one per line. A string, so the selector that reads
+ * it answers the same value until a message with another one comes; the structure a streamed word
+ * leaves alone is what it is cached on.
+ */
+export function threadReferencedKey(structure: Record<string, ChatItem> | undefined): string {
+    if (structure === undefined) {
+        return '';
+    }
+    const cached = referencedOf.get(structure);
+    if (cached !== undefined) {
+        return cached;
+    }
+    const ids = new Set<string>();
+    for (const item of Object.values(structure)) {
+        if (item.kind === 'user') {
+            for (const id of [...(item.chats ?? []), ...(item.references ?? [])]) {
+                ids.add(id);
+            }
+        }
+    }
+    const key = [...ids].join('\n');
+    referencedOf.set(structure, key);
+    return key;
+}
+
+/* What the views, nodes and chats of a thread stand for now, and how one opens, for the rows that draw chips. */
+export function useReferenceLookup(chatId: string): ReferenceLookup {
+    const { id: scopeId } = useChatScope();
+    const { openReference } = useChatHost();
+    const referables = useHostReferables(scopeId, chatId);
+    const key = useChatRow(chatId, (chat) => threadReferencedKey(chat?.structure));
+    return {
+        items: referables.items,
+        open: openReference ? (id: string) => openReference(scopeId, id) : null,
+        referenced: key === '' ? [] : key.split('\n')
+    };
+}

package/src/host-hooks.ts

@@ -6,6 +6,7 @@
  * key, so they never change under a mounted view; only these wrappers go uncompiled for it.
  */
 import type { ProviderPlatform } from '@adecore/agent-contracts';
+import { referablesOfChats, type Referables } from './chat/chat-references';
 import { useChatHost, type ChatHost, type CommandLook } from './host';
 
 export function useHostCodeMode(): 'light' | 'dark' {
@@ -48,6 +49,14 @@ export function useHostReferableChats(): ReturnType<ChatHost['useReferableChats'
     return useChatHost().useReferableChats();
 }
 
+const useReferablesFromChats = (_scopeId: string, _chatId: string): Referables => referablesOfChats(useHostReferableChats());
+
+/* A host without views of its own offers its chats. */
+export function useHostReferables(scopeId: string, chatId: string): Referables {
+    const useReferables = useChatHost().useReferables ?? useReferablesFromChats;
+    return useReferables(scopeId, chatId);
+}
+
 export function useHostLoginBlocked(...args: Parameters<ChatHost['useLoginBlocked']>): ReturnType<ChatHost['useLoginBlocked']> {
     return useChatHost().useLoginBlocked(...args);
 }

package/src/host.ts

@@ -2,9 +2,11 @@ import { createContext, createElement, useContext, useState, type ComponentProps
 import type { Extension } from '@codemirror/state';
 import type { EditorView } from '@codemirror/view';
 import type { Highlighter, ThemeRegistration } from 'shiki';
+import type { LucideIcon } from 'lucide-react';
 import type { EditorEngine } from '@adecore/editor';
 import type {
     AgentKind,
+    ChatAttachment,
     ChatCheckpointDiff,
     ChatConfigurePayload,
     ChatGoalAction,
@@ -15,9 +17,11 @@ import type {
     ChatUiQueryReading,
     ChatUiLinkPayload,
     ChatUiLinkReading,
+    ChatVisual,
     ProviderPlatform
 } from '@adecore/agent-contracts';
 import { isApplePlatform } from '@adecore/ui';
+import type { Referables } from './chat/chat-references';
 import type { TimelineRow } from './chat/logic/timeline';
 import type { FindReveal } from './chat/ui/find-reveal';
 import type { PromptAction } from './prompts/logic/prompts';
@@ -187,6 +191,19 @@ export interface VisualHost {
     frameUrl: string;
     /* Opens an http or https link a person followed in a visual, outside the app. */
     openLink(url: string): void;
+    /* Actions of the app's own in a visual's menu, above Remove; left out, the menu holds Remove alone. */
+    actions?(scopeId: string, chatId: string, visual: ChatVisual): readonly HostMenuAction[];
+}
+
+/* An action of the app's own in the menu of something a chat made, such as keeping a copy somewhere of the app's. */
+export interface HostMenuAction {
+    /* Unique among the actions of one menu. */
+    id: string;
+    label: string;
+    icon?: LucideIcon;
+    disabled?: boolean;
+    /* Runs once a person picks it; the host shows a failure itself. */
+    run(): void;
 }
 
 /* Who writes a chat's replies, as the header over each one names them. */
@@ -328,6 +345,8 @@ export interface ChatHost {
          * Resolves with the path as a file link opens it, or null when the person cancels; left out, a generated image offers no Save.
          */
         saveToProject?(scopeId: string, chatId: string, attachmentId: string, suggestedName: string): Promise<string | null>;
+        /* Actions of the app's own in a generated image's menu, after the chat's own; left out, the menu holds those alone. */
+        actions?(scopeId: string, chatId: string, attachment: ChatAttachment): readonly HostMenuAction[];
     };
     /* The image a tool read, drawn under its row; null draws none. */
     ReadImage: ComponentType<{ path: string }> | null;
@@ -379,8 +398,12 @@ export interface ChatHost {
         render(prompt: HostPrompt, props: PromptViewProps): ReactNode;
         answer(prompt: HostPrompt, action: PromptAction): Promise<void>;
     };
-    /* Other chats a message may point at with `@`, beside the files. */
+    /* Other chats a message may point at with `#`, for a host that has no views; `useReferables` takes over where it is given. */
     useReferableChats(): ReadonlyArray<{ id: string; title: string }>;
+    /* The views and nodes a message of this chat may point at with `#`, under the names they have right now. */
+    useReferables?(scopeId: string, chatId: string): Referables;
+    /* Opens a view or zooms to a node a message points at; left out, a chip opens nothing. */
+    openReference?(scopeId: string, id: string): void;
     /* Opens the CLI's own login for an account, somewhere the app can run a command; null offers none. */
     openLogin: ((scopeId: string, kind: AgentKind, accountId: string, name: string) => Promise<void>) | null;
     /* Why a login cannot start from here right now, or null when it can. */

package/src/index.ts

@@ -12,6 +12,7 @@ export {
     type SubagentSlotProps,
     type ThreadCard,
     type VisualHost,
+    type HostMenuAction,
     type ReplyAuthor,
     type ChatHost,
     type UiMapSource,

package/src/locales/en/agent-chat.ts

@@ -16,10 +16,9 @@ export default {
         unreadable: 'Could not read {{name}}',
         unreadableThumbnail: 'Could not read the thumbnail'
     },
-    chatReference: {
-        gone: 'Chat not in this project',
-        untitled: 'Untitled chat',
-        remove: 'Remove {{title}}'
+    references: {
+        gone: 'Not in this project',
+        untitled: 'Untitled'
     },
     fork: {
         refusal: {
@@ -304,7 +303,8 @@ export default {
         menu: {
             commands: 'Commands',
             skills: 'Skills',
-            mentions: 'Mentions'
+            mentions: 'Mentions',
+            references: 'Views and nodes'
         },
         held: {
             question: 'Question waiting. Opens when you pause typing.',
@@ -349,10 +349,27 @@ export default {
         mentions: {
             here: 'Files in this folder',
             files: 'Files',
-            chats: 'Chats in this project',
-            noMatch: 'No files or chats match',
+            noMatch: 'No files match',
             empty: 'No files here'
         },
+        references: {
+            canvas: 'On this canvas',
+            views: 'Views',
+            noMatch: 'No view or node matches',
+            kinds: {
+                canvas: 'canvas',
+                chat: 'chat',
+                terminal: 'terminal',
+                note: 'note',
+                text: 'text',
+                drawing: 'drawing',
+                diagram: 'diagram',
+                browser: 'browser',
+                device: 'device',
+                file: 'file',
+                database: 'table'
+            }
+        },
         queue: {
             attachments_one: '{{count}} attachment',
             attachments_other: '{{count}} attachments',

package/src/locales/nl/agent-chat.ts

@@ -16,10 +16,9 @@ export default {
         unreadable: 'Kon {{name}} niet lezen',
         unreadableThumbnail: 'Kon de miniatuur niet lezen'
     },
-    chatReference: {
-        gone: 'Chat niet in dit project',
-        untitled: 'Naamloze chat',
-        remove: '{{title}} verwijderen'
+    references: {
+        gone: 'Niet in dit project',
+        untitled: 'Naamloos'
     },
     fork: {
         refusal: {
@@ -304,7 +303,8 @@ export default {
         menu: {
             commands: "Commando's",
             skills: 'Skills',
-            mentions: 'Vermeldingen'
+            mentions: 'Vermeldingen',
+            references: 'Views en nodes'
         },
         held: {
             question: 'Er wacht een vraag. Opent zodra je stopt met typen.',
@@ -349,10 +349,27 @@ export default {
         mentions: {
             here: 'Bestanden in deze map',
             files: 'Bestanden',
-            chats: 'Chats in dit project',
-            noMatch: 'Geen bestanden of chats gevonden',
+            noMatch: 'Geen bestanden gevonden',
             empty: 'Hier staan geen bestanden'
         },
+        references: {
+            canvas: 'Op dit canvas',
+            views: 'Views',
+            noMatch: 'Geen view of node gevonden',
+            kinds: {
+                canvas: 'canvas',
+                chat: 'chat',
+                terminal: 'terminal',
+                note: 'notitie',
+                text: 'tekst',
+                drawing: 'tekening',
+                diagram: 'diagram',
+                browser: 'browser',
+                device: 'apparaat',
+                file: 'bestand',
+                database: 'tabel'
+            }
+        },
         queue: {
             attachments_one: '{{count}} bijlage',
             attachments_other: '{{count}} bijlagen',