@agent-native/toolkit 0.209.0 → 0.209.1-nightly-20261015005848

package/src/app/review/InlineMarkdown.tsx

@@ -44,6 +44,8 @@ export interface InlineMarkdownProtectedSpan {
   label: string;
   className?: string;
   title?: string;
+  /** Protect only the occurrence of `source` starting at this offset. */
+  at?: number;
 }
 
 export function InlineMarkdown({
@@ -137,23 +139,37 @@ export function InlineMarkdown({
 
 const PROTECTED_SPAN_PREFIX = "https://inline-markdown-protected.invalid/span/";
 
+// One pass over the original text: replacing span by span would match a
+// shorter source again inside the link label a longer one just produced.
 function protectInlineMarkdownSpans(
   content: string,
   spans: readonly InlineMarkdownProtectedSpan[],
 ): string {
-  return [...spans]
-    .map((span, index) => ({ span, index }))
-    .filter(({ span }) => span.source.length > 0)
-    .sort((a, b) => b.span.source.length - a.span.source.length)
-    .reduce(
-      (markdown, { span, index }) =>
-        markdown
-          .split(span.source)
-          .join(
-            `[${escapeProtectedSpanLabel(span.label)}](${PROTECTED_SPAN_PREFIX}${index})`,
-          ),
-      content,
-    );
+  const matches: { start: number; end: number; index: number }[] = [];
+  spans.forEach(({ source, at }, index) => {
+    if (!source) return;
+    if (at !== undefined) {
+      if (content.startsWith(source, at))
+        matches.push({ start: at, end: at + source.length, index });
+      return;
+    }
+    for (
+      let start = content.indexOf(source);
+      start !== -1;
+      start = content.indexOf(source, start + source.length)
+    ) {
+      matches.push({ start, end: start + source.length, index });
+    }
+  });
+  matches.sort((a, b) => a.start - b.start || b.end - a.end);
+  let markdown = "";
+  let cursor = 0;
+  for (const { start, end, index } of matches) {
+    if (start < cursor) continue;
+    markdown += `${content.slice(cursor, start)}[${escapeProtectedSpanLabel(spans[index]!.label)}](${PROTECTED_SPAN_PREFIX}${index})`;
+    cursor = end;
+  }
+  return markdown + content.slice(cursor);
 }
 
 function escapeProtectedSpanLabel(label: string): string {

package/src/composer/MentionChip.tsx

@@ -0,0 +1,46 @@
+import type { ComponentPropsWithRef, ReactNode } from "react";
+
+import { cn } from "../utils.js";
+import { MentionItemMedia } from "./MentionItemMedia.js";
+import type { MentionItemMedia as MentionItemMediaValue } from "./types.js";
+
+export interface MentionChipProps extends Omit<
+  ComponentPropsWithRef<"span">,
+  "children"
+> {
+  label: ReactNode;
+  icon?: string;
+  media?: MentionItemMediaValue | null;
+  fallbackIcon?: "clipboard" | "file" | "stack";
+}
+
+/**
+ * The inline chip a mention is drawn as, in the composer and wherever a sent
+ * message shows its mentions, so the two always look the same.
+ */
+export function MentionChip({
+  label,
+  icon,
+  media,
+  fallbackIcon = "stack",
+  className,
+  ...props
+}: MentionChipProps) {
+  return (
+    <span
+      {...props}
+      className={cn(
+        "mx-0.5 inline-flex max-w-[200px] items-center gap-1 rounded-md border border-input bg-muted/50 px-1.5 py-0.5 align-middle text-xs font-medium text-foreground",
+        className,
+      )}
+    >
+      <MentionItemMedia
+        icon={icon}
+        media={media}
+        size="sm"
+        fallbackIcon={fallbackIcon}
+      />
+      <span className="truncate">{label}</span>
+    </span>
+  );
+}

package/src/composer/MentionPopover.tsx

@@ -33,6 +33,8 @@ export interface MentionPopoverRef {
   getSelectedIndex: () => number;
   getSelectedMention: () => MentionItem | null;
   getSelectedCommand: () => SlashCommand | null;
+  /** Runs Retry if it is the highlighted row; false when it is not. */
+  activateRetry: () => boolean;
 }
 
 interface MentionPopoverProps {
@@ -43,6 +45,9 @@ interface MentionPopoverProps {
   commands?: SlashCommand[];
   hint?: string;
   isLoading: boolean;
+  /** Why some @ items could not load; shown above the items that did. */
+  error?: string;
+  onRetry?: () => void;
   query: string;
   onSelectMention: (item: MentionItem) => void;
   onSelectSkill: (skill: SkillResult) => void;
@@ -158,6 +163,8 @@ export const MentionPopover = forwardRef<
     commands = [],
     hint,
     isLoading,
+    error,
+    onRetry,
     query,
     onSelectMention,
     onSelectSkill,
@@ -168,7 +175,7 @@ export const MentionPopover = forwardRef<
   const stacked = density === "stacked";
 
   const [selectedIndex, setSelectedIndex] = useState(0);
-  const listRef = useRef<HTMLDivElement>(null);
+  const containerRef = useRef<HTMLDivElement>(null);
   const t = useComposerRuntimeAdapters().translate!;
 
   const sectionLabel = (section: string) => {
@@ -196,6 +203,10 @@ export const MentionPopover = forwardRef<
 
   const itemCount =
     type === "@" ? mentionItems.length : commands.length + skills.length;
+  // Focus stays in the editor, so Retry is a row above the items, at -1,
+  // for the arrow keys to reach.
+  const retryable = type === "@" && !!error && !!onRetry;
+  const firstIndex = retryable ? -1 : 0;
   const itemIdentitySignature =
     type === "@"
       ? mentionItems.map((item) => item.id).join("\0")
@@ -250,10 +261,10 @@ export const MentionPopover = forwardRef<
 
   useEffect(() => {
     setSelectedIndex((current) => (current === 0 ? current : 0));
-  }, [itemIdentitySignature, query]);
+  }, [itemIdentitySignature, query, retryable]);
 
   useEffect(() => {
-    const container = listRef.current;
+    const container = containerRef.current;
     if (!container) return;
     const selected = container.querySelector(
       `[data-mention-index="${selectedIndex}"]`,
@@ -266,11 +277,13 @@ export const MentionPopover = forwardRef<
   useImperativeHandle(ref, () => ({
     moveUp: () => {
       setSelectedIndex((prev) =>
-        prev <= 0 ? Math.max(0, itemCount - 1) : prev - 1,
+        prev <= firstIndex ? Math.max(firstIndex, itemCount - 1) : prev - 1,
       );
     },
     moveDown: () => {
-      setSelectedIndex((prev) => (prev >= itemCount - 1 ? 0 : prev + 1));
+      setSelectedIndex((prev) =>
+        prev >= itemCount - 1 ? firstIndex : prev + 1,
+      );
     },
     getSelectedIndex: () => selectedIndex,
     getSelectedMention: () => flatMentionItems[selectedIndex] ?? null,
@@ -278,6 +291,11 @@ export const MentionPopover = forwardRef<
       if (type !== "/" || selectedIndex >= commands.length) return null;
       return commands[selectedIndex] ?? null;
     },
+    activateRetry: () => {
+      if (!retryable || selectedIndex !== -1) return false;
+      onRetry!();
+      return true;
+    },
   }));
 
   if (!position) return null;
@@ -287,6 +305,7 @@ export const MentionPopover = forwardRef<
       {/* Backdrop to capture outside clicks */}
       <div className="fixed inset-0 z-[9998]" onClick={onClose} />
       <div
+        ref={containerRef}
         data-agent-native-composer-popover="true"
         data-agent-native-mention-popover="true"
         className="fixed z-[9999] overflow-y-auto rounded-lg border border-border/80 bg-popover p-1 shadow-2xl"
@@ -308,9 +327,32 @@ export const MentionPopover = forwardRef<
           ),
         }}
       >
+        {type === "@" && error && (
+          <div
+            role="alert"
+            className="flex items-center justify-between gap-2 px-3 py-2 text-xs text-destructive"
+          >
+            <span>{error}</span>
+            {onRetry && (
+              <button
+                type="button"
+                data-mention-index={-1}
+                className={`shrink-0 rounded px-1.5 py-0.5 font-medium text-foreground ${
+                  selectedIndex === -1 ? "bg-muted" : "hover:bg-accent"
+                }`}
+                onMouseEnter={() => setSelectedIndex(-1)}
+                onMouseDown={(event) => event.preventDefault()}
+                onClick={onRetry}
+              >
+                {t("agentChat.common.retry", { defaultValue: "Retry" })}
+              </button>
+            )}
+          </div>
+        )}
         {isLoading && itemCount === 0 ? (
           <LoadingSkeleton />
-        ) : itemCount === 0 ? (
+        ) : itemCount === 0 && type === "@" && error ? null : itemCount ===
+          0 ? (
           <div className="px-3 py-4 text-center text-xs text-muted-foreground">
             {type === "@" ? (
               query ? (
@@ -331,7 +373,7 @@ export const MentionPopover = forwardRef<
             )}
           </div>
         ) : (
-          <div ref={listRef}>
+          <div>
             {isLoading && <LoadingSkeletonRow />}
             {type === "@"
               ? (() => {

package/src/composer/PromptComposer.text-references.spec.tsx

@@ -0,0 +1,198 @@
+// @vitest-environment happy-dom
+
+import React, { act } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import { PromptComposer, type PromptComposerProps } from "./PromptComposer.js";
+import type {
+  ComposerTextReference,
+  TiptapComposerHandle,
+} from "./TiptapComposer.js";
+import type { Reference } from "./types.js";
+
+let container: HTMLDivElement;
+let root: Root;
+let composerRef: React.RefObject<TiptapComposerHandle | null>;
+let reported: Reference[];
+
+beforeEach(() => {
+  vi.stubGlobal("IS_REACT_ACT_ENVIRONMENT", true);
+  container = document.createElement("div");
+  document.body.appendChild(container);
+  root = createRoot(container);
+  composerRef = React.createRef<TiptapComposerHandle>();
+  reported = [];
+});
+
+afterEach(() => {
+  act(() => root.unmount());
+  container.remove();
+  vi.unstubAllGlobals();
+});
+
+function person(start: number, end: number, email: string, label: string) {
+  return {
+    start,
+    end,
+    reference: { label, source: "test", refType: "person", refId: email },
+  } satisfies ComposerTextReference;
+}
+
+async function render(props: Partial<PromptComposerProps> = {}) {
+  await act(async () => {
+    root.render(
+      <PromptComposer
+        composerRef={composerRef}
+        onSubmit={vi.fn()}
+        onReferencesChange={(references) => (reported = references)}
+        showModelSelector={false}
+        modelStatusChecksEnabled={false}
+        includeDefaultMentionSearch={false}
+        includeDefaultSlashSkills={false}
+        voiceEnabled={false}
+        {...props}
+      />,
+    );
+  });
+  await act(async () => new Promise((resolve) => setTimeout(resolve, 0)));
+}
+
+/** Each line, with every chip written as [refId]. */
+function lines() {
+  return [...container.querySelectorAll(".ProseMirror > p")].map((line) =>
+    [...line.childNodes]
+      .map((node) => {
+        const chip =
+          node instanceof Element
+            ? (node.closest("[data-mention-ref-id]") ??
+              node.querySelector("[data-mention-ref-id]"))
+            : null;
+        return chip
+          ? `[${chip.getAttribute("data-mention-ref-id")}]`
+          : node.textContent;
+      })
+      .join(""),
+  );
+}
+
+describe("composer text with chips", () => {
+  it("seeds the initial text with each chip in place of its range", async () => {
+    await render({
+      initialText: "@Sam Lee and @Sam Lee, thanks",
+      initialTextKey: "seeded",
+      initialReferences: [
+        person(0, 8, "b@example.test", "Sam Lee"),
+        person(13, 21, "a@example.test", "Sam Lee"),
+      ],
+    });
+
+    expect(lines()).toEqual(["[b@example.test] and [a@example.test], thanks"]);
+    expect(reported.map((reference) => reference.refId)).toEqual([
+      "b@example.test",
+      "a@example.test",
+    ]);
+  });
+
+  it("replaces the draft with chips across lines, leaving an overlapping range as text and a space after a final chip", async () => {
+    await render({ initialText: "Old draft", initialTextKey: "old" });
+
+    await act(async () =>
+      composerRef.current!.setText("Hi @Ana\n@Bo and @Cy", [
+        person(3, 7, "ana@example.test", "Ana"),
+        person(16, 19, "cy@example.test", "Cy"),
+        person(8, 11, "bo@example.test", "Bo"),
+        person(9, 12, "overlap@example.test", "o a"),
+      ]),
+    );
+
+    expect(lines()).toEqual([
+      "Hi [ana@example.test]",
+      "[bo@example.test] and [cy@example.test] ",
+    ]);
+    expect(reported.map((reference) => reference.refId)).toEqual([
+      "ana@example.test",
+      "bo@example.test",
+      "cy@example.test",
+    ]);
+  });
+
+  it("reports each chip as its own @name, apart from the words beside it", async () => {
+    let text = "";
+    await render({ onTextChange: (next) => (text = next) });
+
+    await act(async () =>
+      composerRef.current!.setText("word@Sam@Bo and @Cyx", [
+        person(4, 8, "sam@example.test", "Sam"),
+        person(8, 11, "bo@example.test", "Bo"),
+        person(16, 19, "cy@example.test", "Cy"),
+      ]),
+    );
+
+    expect(lines()).toEqual([
+      "word[sam@example.test][bo@example.test] and [cy@example.test]x",
+    ]);
+    expect(text).toBe("word @Sam @Bo and @Cy x");
+  });
+
+  it("spaces a chip from a combining mark and a letter past U+FFFF", async () => {
+    let text = "";
+    await render({ onTextChange: (next) => (text = next) });
+
+    await act(async () =>
+      composerRef.current!.setText("José@Sam\u{10400}", [
+        person(5, 9, "sam@example.test", "Sam"),
+      ]),
+    );
+
+    expect(text).toBe("José @Sam \u{10400}");
+  });
+});
+
+describe("inserting @ at the cursor", () => {
+  afterEach(() => {
+    delete (document as { execCommand?: unknown }).execCommand;
+  });
+
+  it("filters and picks a mention without touching the text before the @", async () => {
+    await render({
+      initialText: "Ping",
+      initialTextKey: "ping",
+      mentionItems: [
+        {
+          id: "person:sam",
+          label: "Sam Lee",
+          source: "test",
+          refType: "person",
+          refId: "sam@example.test",
+        },
+      ],
+    });
+    const editor = () =>
+      (
+        container.querySelector(".ProseMirror") as HTMLElement & {
+          editor: { commands: { insertContent(text: string): boolean } };
+        }
+      ).editor;
+    // A browser applies execCommand's edit to the DOM, and ProseMirror only
+    // reads it back after the call returns.
+    Object.defineProperty(document, "execCommand", {
+      configurable: true,
+      value: (_command: string, _showUi: boolean, text: string) => {
+        queueMicrotask(() => editor().commands.insertContent(text));
+        return true;
+      },
+    });
+
+    await act(async () => composerRef.current!.insertTextAtCursor!(" "));
+    await act(async () => composerRef.current!.insertTextAtCursor!("@"));
+    await act(async () => void editor().commands.insertContent("Sa"));
+    const option = [
+      ...document.querySelectorAll<HTMLElement>("[data-mention-index]"),
+    ].find((item) => item.textContent?.includes("Sam Lee"));
+    expect(option).toBeDefined();
+    await act(async () => option!.click());
+
+    expect(lines()).toEqual(["Ping [sam@example.test] "]);
+  });
+});

package/src/composer/PromptComposer.tsx

@@ -55,6 +55,7 @@ import {
   isLocalRuntimeEngine,
   TiptapComposer,
   type ComposerAgentOption,
+  type ComposerTextReference,
   type ComposerTextSelection,
   type ComposerImageModelMenu,
   type ComposerSubmitIntent,
@@ -188,6 +189,8 @@ export interface PromptComposerProps {
   initialText?: string;
   /** Stable key used to re-apply `initialText` when the host picks a preset. */
   initialTextKey?: string | number;
+  /** Chips placed into `initialText`, as the composer handle's `setText` takes them. */
+  initialReferences?: readonly ComposerTextReference[];
   /** Optional host-owned control rendered directly after the "+" button. */
   modeControl?: ReactNode;
   /** Current agent execution mode shown in the shared composer toolbar. */
@@ -244,6 +247,9 @@ export interface PromptComposerProps {
   /** Called whenever the plain editor text changes. */
   onTextChange?: (text: string) => void;
   mentionItems?: MentionItem[];
+  /** Why some of `mentionItems` could not load, shown in the @ popover. */
+  mentionItemsError?: string;
+  onRetryMentionItems?: () => void;
   mentionPopoverDensity?: "default" | "stacked";
   includeDefaultMentionSearch?: boolean;
   onReferencesChange?: (references: Reference[]) => void;
@@ -657,6 +663,7 @@ function PromptComposerInner({
   extensionTools = false,
   initialText,
   initialTextKey,
+  initialReferences,
   modeControl,
   requireAgentEngine = false,
   execMode,
@@ -689,6 +696,8 @@ function PromptComposerInner({
   modelStatusChecksEnabled,
   onTextChange,
   mentionItems,
+  mentionItemsError,
+  onRetryMentionItems,
   mentionPopoverDensity,
   includeDefaultMentionSearch,
   onReferencesChange,
@@ -978,6 +987,7 @@ function PromptComposerInner({
           placeholder={placeholder}
           initialText={initialText}
           initialTextKey={initialTextKey}
+          initialReferences={initialReferences}
           onSubmit={handleSubmit}
           onEmptySubmit={onEmptySubmit}
           onBeforeSubmit={beforeSubmit}
@@ -1014,6 +1024,8 @@ function PromptComposerInner({
           voiceEnabled={voiceEnabled}
           onTextChange={onTextChange}
           mentionItems={mentionItems}
+          mentionItemsError={mentionItemsError}
+          onRetryMentionItems={onRetryMentionItems}
           mentionPopoverDensity={mentionPopoverDensity}
           includeDefaultMentionSearch={includeDefaultMentionSearch}
           onReferencesChange={onReferencesChange}