akanjs 3.0.0-beta.13 → 3.0.0-beta.15

package/ui/Agent/Chat.tsx

@@ -28,7 +28,7 @@ import { agentSessionOf } from "./agentSessionOf";
 import type { AttachLimits, AttachReader } from "./attachment";
 import Bubble from "./Bubble";
 import { type ChatCommand, ChatCommands } from "./ChatCommands";
-import { Composer } from "./Composer";
+import { Composer, type ComposerHandle } from "./Composer";
 import { Launcher } from "./Launcher";
 import Menu from "./Menu";
 import Question from "./Question";
@@ -36,6 +36,7 @@ import Queued from "./Queued";
 import Steps from "./Steps";
 import type { PersistOption } from "./sessionHistory";
 import type { BuiltinOption } from "./sessionView";
+import ToolCard from "./ToolCard";
 import { tokenCount } from "./tokenCount";
 import { useChatAttachments } from "./useChatAttachments";
 import { type QueuedMessage, useChatQueue } from "./useChatQueue";
@@ -138,6 +139,12 @@ export interface ChatProps {
    * field reads as a paragraph rather than as the editor document it is stored as.
    */
   reference?: readonly ReferenceSource[];
+  /**
+   * Draws each pointer in the composer as the name it points at rather than as the `@[…](mention:…)` token that
+   * carries it. On wherever `reference` sources are declared, and `false` keeps the plain textarea — for an app
+   * that overrides the composer, or one that would rather see the tokens it is sending.
+   */
+  mentions?: boolean;
   /**
    * Raises or lowers what the composer accepts — per file, per message, and how many. The defaults are what one
    * turn's JSON safely carries to a conservative provider; an app pointed at a larger request limit, or one whose
@@ -199,6 +206,7 @@ export const DefaultChat = ({
   attach,
   attachLimits,
   reference,
+  mentions,
   voice,
 }: ChatProps) => {
   const { l } = usePage();
@@ -249,7 +257,13 @@ export const DefaultChat = ({
   const listRef = useRef<HTMLDivElement>(null);
   const inputRef = useRef<HTMLTextAreaElement>(null);
   const launcherRef = useRef<HTMLButtonElement>(null);
-  const refs = useChatReferences({ session, draft, version, inputRef, onDraft: setDraft });
+  const handleRef = useRef<ComposerHandle | null>(null);
+
+  const focusComposer = () => {
+    if (handleRef.current) handleRef.current.focus();
+    else inputRef.current?.focus();
+  };
+  const refs = useChatReferences({ session, draft, version, handleRef, onDraft: setDraft });
   
   const sticky = useRef(true);
   const returning = useRef(false);
@@ -274,7 +288,7 @@ export const DefaultChat = ({
       event.preventDefault();
       sticky.current = true;
       setOpen(true);
-      inputRef.current?.focus();
+      focusComposer();
     };
     
     window.addEventListener("keydown", onKeyDown, true);
@@ -287,7 +301,7 @@ export const DefaultChat = ({
       returning.current = false;
       return;
     }
-    inputRef.current?.focus();
+    focusComposer();
   }, [open, session.pendingQuestion?.callId]);
   useEffect(
     () => () => {
@@ -299,7 +313,7 @@ export const DefaultChat = ({
   const write = (text: string) => {
     setDraft(text);
     menu.reopen();
-    mentions.reopen();
+    mentionMenu.reopen();
   };
 
   const closable = openProp === undefined || !!onOpenChange;
@@ -349,9 +363,9 @@ export const DefaultChat = ({
     speech.hold(message.byVoice);
   };
   const menu = useSlashMenu({ draft, l, onCommand: runCommand });
-  const mentions = useReferenceMenu({ draft, sources: reference ?? [], session, l, onWrite: write });
+  const mentionMenu = useReferenceMenu({ draft, sources: reference ?? [], session, l, onWrite: write });
 
-  const list = menu.at() ? menu : mentions;
+  const list = menu.at() ? menu : mentionMenu;
   const send = () => {
     const text = draft.trim();
     if (!text && !files.attached.length) return;
@@ -558,6 +572,7 @@ export const DefaultChat = ({
         ) : null}
       </div>
       {session.pendingApproval ? <Approval approval={session.pendingApproval} /> : null}
+      {session.pendingCard ? <ToolCard card={session.pendingCard} key={session.pendingCard.callId} /> : null}
       {session.pendingQuestion ? (
         <Question key={session.pendingQuestion.callId} question={session.pendingQuestion} />
       ) : null}
@@ -567,7 +582,9 @@ export const DefaultChat = ({
         attached={files.attached}
         pending={files.pending}
         draft={draft}
+        handleRef={handleRef}
         inputRef={inputRef}
+        mentions={mentions ?? !!reference?.length}
         {...(speech.canListen ? { mic: { listening: speech.listening, onToggle: speech.toggle } } : {})}
         onDraft={write}
         onFiles={(picked) => void files.add(picked)}

package/ui/Agent/Composer.tsx

@@ -1,5 +1,6 @@
 "use client";
 import { cn, usePage } from "akanjs/client";
+import { lazy } from "akanjs/webkit";
 import { type KeyboardEvent, type RefObject, useEffect } from "react";
 import type { AgentSession, MessageAttachment, MessageReference } from "../../vendor/use-agentic";
 import { Button } from "../Button";
@@ -9,6 +10,16 @@ import { Attach, Chips } from "./Attach";
 import { Mic } from "./Mic";
 import { ReferenceChips } from "./Refer";
 
+/**
+ * What the chat needs of whatever the composer draws into — a textarea, or the mention editor. Every offset is an
+ * offset into the draft string, tokens included, because that is the text the chat reasons about.
+ */
+export interface ComposerHandle {
+  focus: () => void;
+  caret: () => number | null;
+  setCaret: (at: number) => void;
+}
+
 export interface ComposerProps {
   className?: string;
   session: AgentSession;
@@ -32,8 +43,21 @@ export interface ComposerProps {
   onSend: () => void;
   onStop: () => void;
   inputRef?: RefObject<HTMLTextAreaElement | null>;
+  /**
+   * Draws each `@` pointer as the name it points at instead of as its token. On only where the chat was given
+   * `reference` sources, so an app that declared none never fetches the editor's chunk.
+   */
+  mentions?: boolean;
+  /** Filled by whichever input is drawn. An override that draws its own textarea leaves it null and `inputRef` answers. */
+  handleRef?: RefObject<ComposerHandle | null>;
 }
 
+const RichInput = lazy(() => import("./RichInput"), {
+  ssr: false,
+  suspense: true,
+  loading: () => <div className="flex-1" />,
+});
+
 /** Where the box stops growing and starts scrolling: a chat composer is a paragraph at most. */
 const maxComposerHeight = 128;
 
@@ -54,9 +78,31 @@ export const DefaultComposer = ({
   onSend,
   onStop,
   inputRef,
+  mentions = false,
+  handleRef,
 }: ComposerProps) => {
   const { l } = usePage();
   const surface = useUiRecipe("input") ?? inputRecipe;
+  const field = surface({ kind: "area", size: "sm" }, "max-h-32 flex-1 resize-none py-1.5");
+  const placeholder = session.pendingQuestion
+    ? l("base.agentAnswer")
+    : session.isRunning
+      ? l("base.agentQueuePlaceholder")
+      : l("base.agentPlaceholder");
+  useEffect(() => {
+    if (!handleRef || mentions) return;
+    handleRef.current = {
+      focus: () => inputRef?.current?.focus(),
+      caret: () => inputRef?.current?.selectionStart ?? null,
+      setCaret: (at) => {
+        inputRef?.current?.focus();
+        inputRef?.current?.setSelectionRange(at, at);
+      },
+    };
+    return () => {
+      handleRef.current = null;
+    };
+  }, [handleRef, inputRef, mentions]);
   useEffect(() => {
     const area = inputRef?.current;
     if (!area) return;
@@ -87,27 +133,33 @@ export const DefaultComposer = ({
           <Mic className="pb-2" label={l("base.agentListen")} listening={mic.listening} onToggle={mic.onToggle} />
         ) : null}
         <Attach className="pb-2" label={l("base.agentAttach")} onPick={onFiles} />
-        <textarea
-          className={surface({ kind: "area", size: "sm" }, "max-h-32 flex-1 resize-none py-1.5")}
-          onChange={(event) => onDraft(event.target.value)}
-          onKeyDown={onKeyDown}
-          onPaste={(event) => {
-            const pasted = [...event.clipboardData.files];
-            if (!pasted.length) return;
-            event.preventDefault();
-            onFiles(pasted);
-          }}
-          placeholder={
-            session.pendingQuestion
-              ? l("base.agentAnswer")
-              : session.isRunning
-                ? l("base.agentQueuePlaceholder")
-                : l("base.agentPlaceholder")
-          }
-          ref={inputRef}
-          rows={1}
-          value={draft}
-        />
+        {mentions ? (
+          <RichInput
+            className={field}
+            draft={draft}
+            handleRef={handleRef}
+            onDraft={onDraft}
+            onFiles={onFiles}
+            onKeyDown={onKeyDown}
+            placeholder={placeholder}
+          />
+        ) : (
+          <textarea
+            className={field}
+            onChange={(event) => onDraft(event.target.value)}
+            onKeyDown={onKeyDown}
+            onPaste={(event) => {
+              const pasted = [...event.clipboardData.files];
+              if (!pasted.length) return;
+              event.preventDefault();
+              onFiles(pasted);
+            }}
+            placeholder={placeholder}
+            ref={inputRef}
+            rows={1}
+            value={draft}
+          />
+        )}
         {/* A parked question is not a turn to stop: the loop is waiting on the card, and the card has its own out. */}
         {session.isRunning && !session.pendingQuestion ? (
           <>

package/ui/Agent/Markdown.tsx

@@ -1,10 +1,10 @@
 "use client";
 import { cn } from "akanjs/client";
+import type { Align, MarkdownBlock, MarkdownItem, TableBlock } from "akanjs/common";
+import { MarkdownBlocks } from "akanjs/common";
 import type { ReactNode } from "react";
 import { createOverridable } from "../UiOverride";
-import { type MarkdownBlock, MarkdownBlocks, type MarkdownItem } from "./markdownBlocks";
 import { spans } from "./markdownSpans";
-import type { Align, TableBlock } from "./markdownTable";
 
 const alignClass: { [key in Align]: string } = { left: "text-left", center: "text-center", right: "text-right" };
 

package/ui/Agent/MentionNode.ts

@@ -0,0 +1,62 @@
+"use client";
+import { $applyNodeReplacement, type LexicalNode, type NodeKey, type SerializedTextNode, TextNode } from "lexical";
+import { type MessageReference, Reference } from "../../vendor/use-agentic";
+
+export interface SerializedMentionNode extends SerializedTextNode {
+  reference: MessageReference;
+}
+
+/**
+ * One `@` pointer inside the composer: the label is what the node draws, and `getTextContent()` is the
+ * `@[label](mention:…)` token — so the editor's own text is the draft string the rest of the chat already reads,
+ * pointers and all, while the person sees a name.
+ *
+ * `token` mode is what makes it one thing: the caret never lands inside it, a backspace takes the whole pointer
+ * rather than a character of a label that would then name nothing, and a paste over it replaces it entirely.
+ */
+export class MentionNode extends TextNode {
+  #reference: MessageReference;
+
+  static override getType() {
+    return "mention";
+  }
+
+  static override clone(node: MentionNode): MentionNode {
+    return new MentionNode(node.#reference, node.__key);
+  }
+
+  static override importJSON(json: Parameters<typeof TextNode.importJSON>[0]): MentionNode {
+    return new MentionNode((json as Partial<SerializedMentionNode>).reference);
+  }
+
+  constructor(reference: MessageReference = { refName: "", refId: "", label: "" }, key?: NodeKey) {
+    super(reference.label || Reference.keyOf(reference), key);
+    this.#reference = reference;
+    this.setMode("token");
+  }
+
+  get reference(): MessageReference {
+    return this.#reference;
+  }
+
+  override getTextContent(): string {
+    return Reference.token(this.#reference);
+  }
+
+  override createDOM(...args: Parameters<TextNode["createDOM"]>): HTMLElement {
+    const dom = super.createDOM(...args);
+    dom.className = "rounded-field bg-primary/10 px-1 text-primary";
+    dom.title = Reference.keyOf(this.#reference);
+    return dom;
+  }
+
+  override exportJSON(): SerializedMentionNode {
+    return { ...super.exportJSON(), reference: this.#reference };
+  }
+}
+
+export const $createMentionNode = (reference: MessageReference): MentionNode =>
+  $applyNodeReplacement(new MentionNode(reference));
+
+export const $isMentionNode = (node: LexicalNode | null | undefined): node is MentionNode =>
+  node instanceof MentionNode;

package/ui/Agent/RichInput.tsx

@@ -0,0 +1,154 @@
+"use client";
+import { registerPlainText } from "@lexical/plain-text";
+import { cn } from "akanjs/client";
+import {
+  COMMAND_PRIORITY_HIGH,
+  createEditor,
+  KEY_ARROW_DOWN_COMMAND,
+  KEY_ARROW_UP_COMMAND,
+  KEY_ENTER_COMMAND,
+  KEY_ESCAPE_COMMAND,
+  KEY_TAB_COMMAND,
+  type LexicalCommand,
+  PASTE_COMMAND,
+} from "lexical";
+import { type KeyboardEvent as ReactKeyboardEvent, type RefObject, useEffect, useRef, useState } from "react";
+import type { ComposerHandle } from "./Composer";
+import { MentionNode } from "./MentionNode";
+import { MentionDraft } from "./mentionDraft";
+
+interface RichInputProps {
+  className?: string;
+  draft: string;
+  placeholder: string;
+  onDraft: (text: string) => void;
+  /** The textarea's own handler, unchanged: the chat reads a key off the draft and the caret, not off the DOM. */
+  onKeyDown: (event: ReactKeyboardEvent<HTMLTextAreaElement>) => void;
+  onFiles: (files: File[]) => void;
+  handleRef?: RefObject<ComposerHandle | null>;
+}
+
+/**
+ * The composer's input when the chat has `@` sources: the same draft string, drawn with each pointer as the name
+ * it points at instead of as the token that carries it.
+ *
+ * Lexical rather than a contenteditable of our own, for one reason — a Korean or Japanese IME composing into a
+ * contenteditable React also re-renders is the bug class the library exists to own, and it is not one an app can
+ * work around from outside.
+ */
+export const RichInput = ({
+  className,
+  draft,
+  placeholder,
+  onDraft,
+  onKeyDown,
+  onFiles,
+  handleRef,
+}: RichInputProps) => {
+  const [editor] = useState(() =>
+    createEditor({
+      namespace: "akanAgentComposer",
+      nodes: [MentionNode],
+      onError: (error: Error) => console.error(error),
+    }),
+  );
+  const rootRef = useRef<HTMLDivElement>(null);
+  const live = useRef({ draft, onDraft, onKeyDown, onFiles });
+  live.current = { draft, onDraft, onKeyDown, onFiles };
+
+  const settled = useRef(draft);
+  useEffect(() => {
+    const root = rootRef.current;
+    if (!root) return;
+    editor.setRootElement(root);
+    const forward = (key: string, event: KeyboardEvent | null) => {
+      const value = MentionDraft.read();
+      const caret = MentionDraft.caret() ?? value.length;
+      let prevented = false;
+      live.current.onKeyDown({
+        key,
+        shiftKey: !!event?.shiftKey,
+        nativeEvent: { isComposing: !!event?.isComposing },
+        currentTarget: { value, selectionStart: caret, selectionEnd: caret },
+        preventDefault: () => {
+          prevented = true;
+          event?.preventDefault();
+        },
+      } as unknown as ReactKeyboardEvent<HTMLTextAreaElement>);
+      return prevented;
+    };
+
+    const onKey = <T extends KeyboardEvent | null>(command: LexicalCommand<T>, key: string) =>
+      editor.registerCommand<T>(command, (event) => forward(key, event), COMMAND_PRIORITY_HIGH);
+    const teardowns = [
+      registerPlainText(editor),
+      editor.registerUpdateListener(({ editorState }) => {
+        const text = editorState.read(() => MentionDraft.read());
+        if (text === settled.current) return;
+
+        settled.current = text;
+        live.current.onDraft(text);
+      }),
+      onKey(KEY_ENTER_COMMAND, "Enter"),
+      onKey(KEY_TAB_COMMAND, "Tab"),
+      onKey(KEY_ARROW_UP_COMMAND, "ArrowUp"),
+      onKey(KEY_ARROW_DOWN_COMMAND, "ArrowDown"),
+      onKey(KEY_ESCAPE_COMMAND, "Escape"),
+      editor.registerCommand(
+        PASTE_COMMAND,
+        (event) => {
+          const files = [...(("clipboardData" in event ? event.clipboardData?.files : null) ?? [])];
+          if (!files.length) return false;
+          event.preventDefault();
+          live.current.onFiles(files);
+          return true;
+        },
+        COMMAND_PRIORITY_HIGH,
+      ),
+    ];
+    if (live.current.draft) editor.update(() => MentionDraft.write(live.current.draft), { discrete: true });
+    return () => {
+      for (const teardown of teardowns) teardown();
+      editor.setRootElement(null);
+    };
+  }, [editor]);
+  useEffect(() => {
+    if (draft === settled.current) return;
+    settled.current = draft;
+    editor.update(() => MentionDraft.write(draft), { discrete: true });
+  }, [draft, editor]);
+  useEffect(() => {
+    if (!handleRef) return;
+    handleRef.current = {
+      focus: () => editor.focus(),
+      caret: () => editor.getEditorState().read(() => MentionDraft.caret()),
+      setCaret: (at) => {
+        editor.update(() => MentionDraft.place(at), { discrete: true });
+        editor.focus();
+      },
+    };
+    return () => {
+      handleRef.current = null;
+    };
+  }, [editor, handleRef]);
+  return (
+    <div className="relative flex-1">
+      <div
+        aria-label={placeholder}
+        aria-multiline
+        className={cn("max-h-32 overflow-y-auto whitespace-pre-wrap break-words outline-none", className)}
+        contentEditable
+        ref={rootRef}
+        role="textbox"
+        suppressContentEditableWarning
+      />
+      {draft ? null : (
+        <span className="pointer-events-none absolute inset-0 select-none px-3 py-1.5 text-foreground/40 text-sm">
+          {placeholder}
+        </span>
+      )}
+    </div>
+  );
+};
+
+export default RichInput;

package/ui/Agent/ToolCard.tsx

@@ -0,0 +1,39 @@
+"use client";
+import { cn, usePage } from "akanjs/client";
+import type { PendingCard } from "../../vendor/use-agentic";
+import { createOverridable } from "../UiOverride";
+
+export interface ToolCardProps {
+  className?: string;
+  card: PendingCard;
+}
+
+/**
+ * A call the user answers, parked above the composer where the approval and the question cards sit. What it draws
+ * is the app's own — the declaration that published the tool also said what filling it in looks like — so this
+ * frame owns only the placement and the way out of it.
+ *
+ * The way out is not the app's to forget: a card that renders no cancel of its own would otherwise park the turn
+ * on a component the user cannot dismiss, so the frame always draws one.
+ */
+export const DefaultToolCard = ({ className, card }: ToolCardProps) => {
+  const { l } = usePage();
+  return (
+    <div
+      aria-label={l("base.agentToolCard")}
+      className={cn("flex flex-col gap-2 border-primary/30 border-t bg-primary/5 px-4 py-3", className)}
+      role="group"
+    >
+      {card.render({ args: card.args, submit: card.submit, cancel: card.dismiss })}
+      <button
+        className="self-end text-foreground/50 text-xs hover:text-foreground"
+        onClick={() => card.dismiss()}
+        type="button"
+      >
+        {l("base.skip")}
+      </button>
+    </div>
+  );
+};
+
+export default createOverridable("AgentToolCard", DefaultToolCard);

package/ui/Agent/markdownSpans.tsx

@@ -1,49 +1,39 @@
 "use client";
+import { type MarkdownSpan, MarkdownSpans } from "akanjs/common";
 import type { ReactNode } from "react";
 
-const inline =
-  /(!?)\[([^\]]*)\]\(((?:[^\s()]|\([^\s()]*\))+)\)|`([^`]+)`|\*\*([\s\S]+?)\*\*|\*([^*\n]+?)\*|~~([\s\S]+?)~~/g;
+/** The browser rendering of {@link MarkdownSpans}; the scanner, and which hrefs are refused, live there. */
+export const spans = (text: string): ReactNode[] => MarkdownSpans.of(text).map((span, at) => node(span, at));
 
-const isSafeHref = (href: string) => !/^[a-z][a-z0-9+.-]*:/i.test(href) || /^(?:https?|mailto|tel):/i.test(href);
-
-export const spans = (text: string): ReactNode[] => {
-  const nodes: ReactNode[] = [];
-  let cut = 0;
-  for (const match of text.matchAll(inline)) {
-    const at = match.index;
-    const [, image, label, href, code, strong, em, del] = match;
-    if (at > cut) nodes.push(text.slice(cut, at));
-    cut = at + match[0].length;
-    if (href)
-      nodes.push(
-        image || !isSafeHref(href) ? (
-          label
-        ) : (
-          <a className="underline" href={href} key={at} rel="noreferrer" target="_blank">
-            {spans(label)}
-          </a>
-        ),
+const node = (span: MarkdownSpan, at: number): ReactNode => {
+  switch (span.kind) {
+    case "link":
+      return (
+        <a className="underline" href={span.href} key={at} rel="noreferrer" target="_blank">
+          {spans(span.text)}
+        </a>
       );
-    else if (code)
-      nodes.push(
+    case "code":
+      return (
         <code className="rounded-field bg-muted px-1 font-mono text-[11px]" key={at}>
-          {code}
-        </code>,
+          {span.text}
+        </code>
       );
-    else if (strong)
-      nodes.push(
+    case "strong":
+      return (
         <strong className="font-semibold" key={at}>
-          {spans(strong)}
-        </strong>,
+          {spans(span.text)}
+        </strong>
       );
-    else if (em) nodes.push(<em key={at}>{spans(em)}</em>);
-    else if (del)
-      nodes.push(
+    case "em":
+      return <em key={at}>{spans(span.text)}</em>;
+    case "del":
+      return (
         <del className="opacity-60" key={at}>
-          {spans(del)}
-        </del>,
+          {span.text}
+        </del>
       );
+    default:
+      return span.text;
   }
-  if (cut < text.length) nodes.push(text.slice(cut));
-  return nodes;
 };