@tangle-network/agent-app 0.46.3 → 0.46.4

package/dist/web-react/chat-composer.d.ts

@@ -2,8 +2,10 @@
  * ChatComposer — the shared message input every agent app used to hand-roll:
  * an auto-resizing textarea (Enter sends, Shift+Enter inserts a newline), an
  * opt-in attach + drag-and-drop + clipboard-paste surface with pending-file
- * chips, a streaming Stop/Send toggle, a slot for inline controls (model
- * picker, reasoning effort), and a Cmd/Ctrl+L focus shortcut.
+ * chips, an opt-in `@`-mention mode (`mention`) that swaps the textarea for a
+ * lazily loaded rich input with atomic mention pills, a streaming Stop/Send
+ * toggle, a slot for inline controls (model picker, reasoning effort), and a
+ * Cmd/Ctrl+L focus shortcut.
  *
  * Files arrive by three routes — the picker dialog, a drop, and a paste — and
  * all three funnel through `accept` (`./composer-file-accept`) before they
@@ -35,6 +37,7 @@
 import { type ReactNode } from 'react';
 import { type ComposerFileRejection } from './composer-file-accept';
 import { type DictationAudio } from './use-dictation';
+import type { ComposerMentionProp } from './use-file-mentions';
 /** Prompt-part descriptor an uploaded file carries (the upload route's
  *  `UploadedChatFile.part`), echoed back in the turn body on send. Mirrors
  *  `/chat-routes`' wire shape structurally — no server import here. */
@@ -259,8 +262,25 @@ export interface ChatComposerProps {
      *  status line. It sits outside the controls slot and never shrinks, so a
      *  wrapping picker set cannot push it away. */
     trailing?: ReactNode;
+    /**
+     * Opt-in `@`-mentions. Present ⇒ the textarea is swapped for a lazily
+     * loaded TipTap rich input that renders mentions as atomic pills and
+     * serializes them to `@<id>` in the value; absent ⇒ exactly the plain
+     * textarea, with no TipTap in the bundle. Wire `useFileMentions().mention`
+     * straight in. The six `@tiptap/*` packages (core, extension-mention, pm,
+     * react, starter-kit, suggestion) are OPTIONAL peers — a consumer installs
+     * them to use this prop.
+     *
+     * The rich input owns its own keyboard surface, so `slashCommands` is
+     * disabled while `mention` is set rather than left half-armed with a menu
+     * no key can reach; no shipped surface combines the two. Seed and
+     * failed-send drafts still apply in mention mode, but caret placement (a
+     * textarea affordance) degrades to content-only.
+     */
+    mention?: ComposerMentionProp;
     /** `/` commands offered when the draft is exactly a leading slash token.
-     *  Omit (or pass []) and `/` types as ordinary text. */
+     *  Omit (or pass []) and `/` types as ordinary text. Inert while `mention`
+     *  is set — see {@link mention}. */
     slashCommands?: SlashCommand[];
     /** Dictation is opt-in: pass `onDictate` and the action row gains a mic
      *  button (browsers without `MediaRecorder`/`getUserMedia` render none).
@@ -286,4 +306,4 @@ export interface ChatComposerProps {
     sendVariant?: 'pill' | 'icon';
     className?: string;
 }
-export declare function ChatComposer({ onSend, onSendParts, onSendFailed, sendFailureMessage, onCancel, isStreaming, disabled, placeholder, value, onValueChange, initialValue, seed, onSeedApplied, controls, controlsPlacement, onAttach, onAttachFolder, pendingFiles, onRemoveFile, onRetryFile, accept, onRejectFiles, dropTitle, dropDescription, contextItems, canSubmitAttachmentsOnly, attachmentsNotReadyMessage, canSubmitWhileBusy, autoFocus, minRows, maxHeight, trailing, slashCommands, onDictate, onDictateError, focusShortcut, floating, sendLabel, sendVariant, className, }: ChatComposerProps): import("react").JSX.Element;
+export declare function ChatComposer({ onSend, onSendParts, onSendFailed, sendFailureMessage, onCancel, isStreaming, disabled, placeholder, value, onValueChange, initialValue, seed, onSeedApplied, controls, controlsPlacement, onAttach, onAttachFolder, pendingFiles, onRemoveFile, onRetryFile, accept, onRejectFiles, dropTitle, dropDescription, contextItems, canSubmitAttachmentsOnly, attachmentsNotReadyMessage, canSubmitWhileBusy, autoFocus, minRows, maxHeight, trailing, mention, slashCommands, onDictate, onDictateError, focusShortcut, floating, sendLabel, sendVariant, className, }: ChatComposerProps): import("react").JSX.Element;

package/dist/web-react/index.d.ts

@@ -41,6 +41,7 @@ export * from './durable-interaction-submit';
 export * from './use-chat-interactions';
 export * from './use-file-mentions';
 export * from './chat-mentions';
+export * from './mention-pill';
 export * from './chat-attachments';
 export * from './message-attachments';
 export * from './use-composer-attachments';

package/dist/web-react/index.js

@@ -132,7 +132,7 @@ import {
   withoutRecordGridCreated,
   withoutRecordGridRemoved,
   withoutRecordGridUpdate
-} from "../chunk-RZ6MYWMJ.js";
+} from "../chunk-YTEUZXX2.js";
 import {
   SessionHistoryPanel,
   formatSessionTimestamp,
@@ -140,6 +140,9 @@ import {
   useSessionActions,
   useSessionHistory
 } from "../chunk-KKBTPZIE.js";
+import {
+  MENTION_PILL_CLASS
+} from "../chunk-RLOHIX5Y.js";
 import "../chunk-FBVLEGEG.js";
 import {
   EvidenceLineageTable,
@@ -288,6 +291,7 @@ export {
   InteractionBadge,
   InteractionPlanCard,
   InteractionQuestionCard,
+  MENTION_PILL_CLASS,
   MessageAttachments,
   MissionActivityLane,
   ModelPicker,

package/dist/web-react/mention-boundaries.d.ts

@@ -0,0 +1,33 @@
+/**
+ * The one boundary vocabulary for reading `@<path>` mention tokens out of
+ * plain text. Two inverse readings share it — the transcript segmenter
+ * (`chat-mentions.ts`) and editor-pill restore (`mention-serialize.ts`) — and
+ * they must agree, or a token one accepts the other mangles. Kept OUT of the
+ * `/web-react` barrel on purpose: these are internals of the grammar, not
+ * public API.
+ */
+/** A character that could plausibly continue the SAME path/filename past a
+ *  matched token. Without this lookahead a mention of `@a/b.md` would match
+ *  inside the unrelated `@a/b.md.bak` and split it mid-filename.
+ *
+ *  Unicode-aware because the wire validator (`validateSandboxMentionPath`)
+ *  deliberately ALLOWS non-ASCII paths — in-box filenames are arbitrary. An
+ *  ASCII-only class here would accept input the readers then mangle.
+ *  `\p{M}` keeps DECOMPOSED filenames whole: without it, a combining accent
+ *  (`a` + U+0301) reads as a boundary and splits the name after its base
+ *  letter. */
+export declare const PATH_CONTINUATION_CHAR: RegExp;
+/** A character that, immediately BEFORE an `@`, means the `@` is part of a
+ *  longer token (an email local part, a handle) rather than a mention start.
+ *  Unicode-aware for the same reasons, combining marks included. */
+export declare const WORD_CHAR: RegExp;
+/** The full character (code point) ENDING just before `index`, or undefined
+ *  at the start. Indexing `text[index - 1]` hands a lone UTF-16 surrogate to
+ *  the Unicode-aware classes above, which then misread every astral letter —
+ *  boundary checks must see whole characters. `index` must be a code-point
+ *  boundary (both callers derive it from `@` positions and id lengths, which
+ *  are). */
+export declare function charBefore(text: string, index: number): string | undefined;
+/** The full character (code point) starting at `index`, or undefined past the
+ *  end — same surrogate rationale and precondition as {@link charBefore}. */
+export declare function charAt(text: string, index: number): string | undefined;

package/dist/web-react/mention-editor.d.ts

@@ -0,0 +1,84 @@
+/**
+ * The mention-capable rich input behind `ChatComposer`'s `mention` prop.
+ *
+ * The five `@tiptap/*` packages are OPTIONAL peers, and every value access to
+ * them goes through `loadTiptapModules()`'s dynamic `import()` — never a
+ * static named import. A bundler resolves a missing optional peer to a stub
+ * module with a default export only, so a static `import { mergeAttributes }`
+ * fails the CONSUMER'S build even when nothing ever renders the mention path
+ * (measured against Vite 7's `__vite-optional-peer-dep` stub). The dynamic
+ * form builds clean and defers the failure to the first actual editor load,
+ * where it throws with the missing packages named — the same doctrine as
+ * `sequences-react`'s transcription peer. Type-only imports are erased and
+ * stay allowed.
+ */
+import type { MentionOptions } from '@tiptap/extension-mention';
+import type * as TiptapCore from '@tiptap/core';
+import type * as TiptapExtensionMention from '@tiptap/extension-mention';
+import type * as TiptapReact from '@tiptap/react';
+import type * as TiptapStarterKit from '@tiptap/starter-kit';
+import type * as TiptapSuggestion from '@tiptap/suggestion';
+import { type ComponentType } from 'react';
+import type { ComposerMentionProp } from './use-file-mentions';
+/** The loaded namespaces of the five optional peers, as one bag. */
+export interface TiptapModules {
+    core: typeof TiptapCore;
+    extensionMention: typeof TiptapExtensionMention;
+    react: typeof TiptapReact;
+    starterKit: typeof TiptapStarterKit;
+    suggestion: typeof TiptapSuggestion;
+}
+/** Resolve the optional peers, or throw naming every one of them. */
+export declare function loadTiptapModules(): Promise<TiptapModules>;
+export interface MentionEditorProps {
+    value: string;
+    onChange: (value: string) => void;
+    /** Fired when Enter (no Shift, popover closed, not composing) should send. */
+    onSubmit: () => void;
+    placeholder: string;
+    disabled?: boolean;
+    autoFocus?: boolean;
+    /** Pixel floor for the input box. The composer computes it from `minRows`
+     *  against its own line metrics, so the two input modes cannot drift. */
+    minHeight: number;
+    /** Pixel height the input grows to before it scrolls. */
+    maxHeight: number;
+    mention: ComposerMentionProp;
+    /** Registers a focus callback the composer wires to Cmd/Ctrl+L; called with
+     *  `null` on unmount so the composer never focuses a destroyed editor. */
+    registerFocus?: (focus: (() => void) | null) => void;
+    /**
+     * Clipboard files pulled off a paste. Returns true when consumed so the
+     * editor suppresses its default text paste — the same funnel the textarea
+     * path routes through to `onAttach`.
+     */
+    onPasteFiles?: (files: FileList) => boolean;
+}
+/** Only text, hard breaks, and atomic mention pills — no marks, no formatting. */
+export declare function buildComposerStarterKit(tiptap: TiptapModules): TiptapCore.Extension<TiptapStarterKit.StarterKitOptions, any>;
+/**
+ * The mention node: an inline atom (`inline: true, selectable: false,
+ * atom: true` from `@tiptap/extension-mention`) carrying `{ id, label, kind }`,
+ * rendered as a themed pill showing the label with the full id in `title`. Atom
+ * means the cursor can't enter it and a single backspace removes the whole
+ * thing. The `suggestion` config is supplied by the caller so the popover's
+ * fetch/keyboard wiring stays in the component.
+ */
+export declare function buildMentionExtension(tiptap: TiptapModules, trigger: string, suggestion: MentionOptions['suggestion']): TiptapCore.Node<MentionOptions<any, TiptapExtensionMention.MentionNodeAttrs>, any>;
+/** `React.lazy` payload: resolve the peers, then build the component. */
+export declare function loadMentionEditor(): Promise<{
+    default: ComponentType<MentionEditorProps>;
+}>;
+/**
+ * Builds the mention-capable rich input against loaded tiptap modules. Loaded
+ * lazily by `ChatComposer` so textarea-only consumers never pull TipTap into
+ * their initial bundle. It preserves every textarea behavior — controlled
+ * plain-text `value`, Enter to send / Shift+Enter for a newline, placeholder,
+ * disabled, autofocus, file-paste routing — and adds `@`-mention pills backed
+ * by an async provider.
+ *
+ * The suggestion list renders through `PopoverSurface` anchored to the input
+ * box, like the composer's slash menu: an in-place panel is a panel the host
+ * clips away (see the popover canon in AGENTS.md).
+ */
+export declare function createMentionEditor(tiptap: TiptapModules): ComponentType<MentionEditorProps>;

package/dist/web-react/mention-list.d.ts

@@ -0,0 +1,35 @@
+import type { ReactNode } from 'react';
+import type { MentionItem } from './use-file-mentions';
+/** Imperative surface the editor's suggestion keymap drives. */
+export interface MentionListHandle {
+    /** Returns true when the key was consumed — the editor must not also act. */
+    onKeyDown: (event: KeyboardEvent) => boolean;
+}
+export interface MentionListProps {
+    items: MentionItem[];
+    loading: boolean;
+    error: boolean;
+    /** Shown when the fetch resolved to zero items. Default "No matches". */
+    emptyText?: string;
+    renderItem?: (item: MentionItem) => ReactNode;
+    onSelect: (item: MentionItem) => void;
+    /** Root `role="listbox"` element id; option rows derive stable ids from it
+     *  (`<id>-opt-<index>`) so the editor can point `aria-activedescendant` at
+     *  the highlighted row. */
+    id?: string;
+    /** Fired whenever the highlight moves (keys, hover, or a result-set
+     *  re-home) — what keeps the editor's `aria-activedescendant` current. */
+    onActiveChange?: (index: number) => void;
+    /** Extra classes merged onto the panel's root element, applied last so
+     *  they win over the component's own. */
+    className?: string;
+}
+/**
+ * The mention suggestion list: a flat, keyboard-driven menu with loading,
+ * empty, and error states. Selection is owned here so ↑/↓ and Enter/Tab
+ * resolve against the highlighted row; every key it handles is reported
+ * consumed so the composer's Enter-to-send never fires while open. The panel
+ * carries its own surface classes but no positioning — the editor places it
+ * through `PopoverSurface`, per the popover canon.
+ */
+export declare const MentionList: import("react").ForwardRefExoticComponent<MentionListProps & import("react").RefAttributes<MentionListHandle>>;

package/dist/web-react/mention-pill.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Visual contract for a rendered mention pill. The TipTap extension in
+ * `mention-editor.tsx` styles its inline atom node with this, and any other
+ * surface that renders a resolved mention (e.g. a sent-message transcript)
+ * uses the same constant so the two stay one visual contract instead of
+ * silently drifting apart. Kept in its own module (no TipTap import) so
+ * importing it never pulls the lazily-loaded editor chunk into a consumer's
+ * bundle.
+ */
+export declare const MENTION_PILL_CLASS = "rounded-md bg-primary/10 px-1 py-0.5 font-medium text-primary";

package/dist/web-react/mention-serialize.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Round-trip between the mention editor's document and the composer's plain
+ * `value` string. A mention node serializes to `@<id>`; parsing restores a
+ * pill only for ids the session already knows (fetched, inserted, or
+ * restored), so unknown `@…` runs stay literal text.
+ *
+ * The document shape is kept structural (no TipTap import) so this round-trip
+ * is unit-testable on its own and never pulls the editor chunk into a bundle.
+ */
+import type { MentionItem } from './use-file-mentions';
+/**
+ * The subset of a TipTap/ProseMirror JSON document the mention editor
+ * produces: a `doc` of paragraphs, each holding text, hard breaks, and atomic
+ * mention nodes.
+ */
+export interface MentionDocNode {
+    type: string;
+    text?: string;
+    attrs?: {
+        id?: string | null;
+        label?: string | null;
+        kind?: string | null;
+    };
+    content?: MentionDocNode[];
+}
+/**
+ * Plain-text serialization of the editor document. Paragraphs join with a
+ * newline, hard breaks become a newline, and a mention node becomes `@<id>` —
+ * the stable text form the controlled `value` carries.
+ */
+export declare function serializeMentionDoc(doc: MentionDocNode): string;
+/** Every mention node in the document, in order, as `MentionItem`s. */
+export declare function collectMentions(doc: MentionDocNode): MentionItem[];
+/**
+ * Parse a controlled `value` string back into an editor document. `@<id>`
+ * runs that match a currently-known mention restore as atomic mention nodes;
+ * every other `@…` stays literal text. Each line becomes a paragraph — a
+ * deliberate asymmetry with `serializeMentionDoc`, which also flattens an
+ * in-paragraph `hardBreak` to `\n`: the string round-trips byte-identically,
+ * but a restored Shift+Enter comes back as a paragraph break. The two render
+ * identically under the composer's styling (no paragraph margins), so the
+ * plain-text `value` contract stays the source of truth.
+ */
+export declare function parseMentionValue(value: string, known: Map<string, MentionItem>): MentionDocNode;

package/dist/web-react/use-file-mentions.d.ts

@@ -1,7 +1,7 @@
 /**
- * `useFileMentions` — the glue a host passes straight into `AgentComposer`'s
- * `mention` prop (`@tangle-network/sandbox-ui#184`) to wire up `@`-file
- * mentions against `createSandboxFileIndexRoute` (`/chat-routes`).
+ * `useFileMentions` — the glue a host passes straight into `ChatComposer`'s
+ * `mention` prop to wire up `@`-file mentions against
+ * `createSandboxFileIndexRoute` (`/chat-routes`).
  *
  * Fetches the index once per session from `indexUrl`, refreshes it in the
  * background whenever the popover opens (a `fetchItems` call) if the cached
@@ -10,31 +10,45 @@
  * `refresh()` lets a caller force a re-fetch immediately instead of waiting
  * on `refreshAfterMs` — e.g. right after the agent creates a file mid-session.
  *
- * `MentionItem`/the `mention` prop shape mirror the FROZEN contract from
- * sandbox-ui#184 structurally (no import: `/web-react` stays dependency-free
- * beyond React, and `@tangle-network/sandbox-ui` is an optional peer).
+ * `MentionItem` and `ComposerMentionProp` are the mention contract this
+ * package defines and `mention-editor.tsx` renders. The shape stays
+ * structurally identical to sandbox-ui#184's `AgentComposerProps['mention']`,
+ * so the same value drives sandbox-ui's `AgentComposer` during migration
+ * (tangle-network/agent-dev-container#5934) without an import either way.
  */
 import type { ReactNode } from 'react';
 import type { FileMention } from '../chat-routes/wire';
-/** Mirrors sandbox-ui#184's `MentionItem` — the atomic pill's payload. For a
- *  file mention, `id` is the workspace-relative path (the pill's stable
- *  identity and the `@<id>` serialization sandbox-ui uses to round-trip
- *  `value`), `label` is the display name, and `detail` carries the full path
- *  for the popover row's secondary line. */
+/** The atomic pill's payload. For a file mention, `id` is the
+ *  workspace-relative path (the pill's stable identity and the `@<id>`
+ *  serialization the editor uses to round-trip `value`), `label` is the
+ *  display name, and `detail` carries the full path for the popover row's
+ *  secondary line. */
 export interface MentionItem {
     id: string;
     label: string;
     detail?: string;
     kind?: string;
 }
-/** Mirrors sandbox-ui#184's `AgentComposerProps['mention']` shape — plug the
- *  hook's `mention` return value straight into that prop. */
+/** `ChatComposer`'s `mention` prop shape — plug the hook's `mention` return
+ *  value straight into it. Structurally identical to sandbox-ui#184's
+ *  `AgentComposerProps['mention']`, so it also drives `AgentComposer`. */
 export interface ComposerMentionProp {
+    /** The character that opens the popover. Default "@". Read once when the
+     *  editor mounts — a runtime change does not re-key the editor. */
     trigger?: string;
+    /** Async provider called with the query typed after the trigger. */
     fetchItems(query: string): Promise<MentionItem[]>;
+    /** Fired with the mentions currently in the document whenever they change. */
     onMentionsChange?(mentions: MentionItem[]): void;
+    /** Custom row renderer for a popover item. */
     renderItem?(item: MentionItem): ReactNode;
+    /** Shown when a fetch resolves to zero items. Default "No matches". */
     emptyText?: string;
+    /** Extra classes merged onto the suggestion panel's root element
+     *  (`role="listbox"`), applied last so they win over the component's own —
+     *  the supported way to retheme the popover instead of targeting it by its
+     *  ARIA attributes. */
+    popoverClassName?: string;
 }
 /**
  * Ranks `files` against `query` (case-insensitive), capped to `limit`:
@@ -77,7 +91,7 @@ export interface UseFileMentionsOptions {
 }
 /** Provide properties and methods to manage and refresh file mentions in a composer interface */
 export interface UseFileMentionsResult {
-    /** Spread straight into `AgentComposer`'s `mention` prop. */
+    /** Spread straight into `ChatComposer`'s `mention` prop. */
     mention: ComposerMentionProp;
     /** The files currently referenced by mentions in the composer's value —
      *  the send-body list (map through `fileMentionsToParts`). */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tangle-network/agent-app",
-  "version": "0.46.3",
+  "version": "0.46.4",
   "packageManager": "pnpm@11.17.0",
   "description": "Build agent applications with typed chat, tools, sandboxes, integrations, billing, and evaluation.",
   "keywords": [
@@ -530,6 +530,13 @@
     "@tangle-network/ui": "^11.5.0",
     "@testing-library/dom": "^10.4.1",
     "@testing-library/react": "^16.3.2",
+    "@testing-library/user-event": "^14.6.1",
+    "@tiptap/core": "^3.28.0",
+    "@tiptap/extension-mention": "^3.28.0",
+    "@tiptap/pm": "^3.28.0",
+    "@tiptap/react": "^3.28.0",
+    "@tiptap/starter-kit": "^3.28.0",
+    "@tiptap/suggestion": "^3.28.0",
     "@types/better-sqlite3": "^7.6.13",
     "@types/node": "^22.20.1",
     "@types/react": "^19.0.0",
@@ -579,6 +586,12 @@
     "@tangle-network/sandbox": ">=0.29.0 <0.30.0",
     "@tangle-network/sandbox-ui": ">=0.105.0",
     "@tangle-network/ui": ">=11.5.0",
+    "@tiptap/core": ">=3.28.0 <4.0.0",
+    "@tiptap/extension-mention": ">=3.28.0 <4.0.0",
+    "@tiptap/pm": ">=3.28.0 <4.0.0",
+    "@tiptap/react": ">=3.28.0 <4.0.0",
+    "@tiptap/starter-kit": ">=3.28.0 <4.0.0",
+    "@tiptap/suggestion": ">=3.28.0 <4.0.0",
     "@xyflow/react": ">=12.0.0",
     "better-auth": ">=1.6.16",
     "drizzle-orm": ">=0.36",
@@ -634,6 +647,24 @@
     "@tangle-network/brand": {
       "optional": true
     },
+    "@tiptap/core": {
+      "optional": true
+    },
+    "@tiptap/extension-mention": {
+      "optional": true
+    },
+    "@tiptap/pm": {
+      "optional": true
+    },
+    "@tiptap/react": {
+      "optional": true
+    },
+    "@tiptap/starter-kit": {
+      "optional": true
+    },
+    "@tiptap/suggestion": {
+      "optional": true
+    },
     "@xyflow/react": {
       "optional": true
     },