@agent-native/toolkit 0.16.16 → 0.17.0-nightly-20260826025507

package/src/composer/TiptapComposer.spec.ts

@@ -188,6 +188,69 @@ describe("createTiptapComposerExtensions", () => {
     editor.destroy();
   });
 
+  it.each([
+    [
+      "text",
+      {
+        type: "text",
+        text: "PK",
+        backgroundColor: "#4f46e5",
+      },
+    ],
+    [
+      "image",
+      {
+        type: "image",
+        src: "/agents/property.png",
+        fit: "cover",
+        backgroundColor: "#ffffff",
+      },
+    ],
+    ["none", { type: "none" }],
+  ] as const)(
+    "preserves %s mention media through HTML drafts",
+    (_type, media) => {
+      const first = new Editor({
+        element: document.createElement("div"),
+        extensions: createTiptapComposerExtensions(() => "Message agent..."),
+        content: {
+          type: "doc",
+          content: [
+            {
+              type: "paragraph",
+              content: [
+                {
+                  type: "mentionReference",
+                  attrs: {
+                    label: "Property agent",
+                    media,
+                  },
+                },
+              ],
+            },
+          ],
+        },
+      });
+      const html = first.getHTML();
+      first.destroy();
+
+      expect(html).toContain("data-media=");
+      expect(html).not.toContain("[object Object]");
+
+      const restored = new Editor({
+        element: document.createElement("div"),
+        extensions: createTiptapComposerExtensions(() => "Message agent..."),
+        content: html,
+      });
+      const mentionNode = restored.getJSON().content?.[0]?.content?.[0] as
+        | { attrs?: Record<string, unknown> }
+        | undefined;
+      restored.destroy();
+
+      expect(mentionNode?.attrs?.media).toEqual(media);
+    },
+  );
+
   it("allows sending an attachment-only prompt", () => {
     expect(
       canSubmitComposerContent({

package/src/composer/TiptapComposer.tsx

@@ -44,6 +44,7 @@ import { getComposerDraftKey } from "./draft-key.js";
 import { FileReference } from "./extensions/FileReference.js";
 import { MentionReference } from "./extensions/MentionReference.js";
 import { SkillReference } from "./extensions/SkillReference.js";
+import { MentionItemMedia } from "./MentionItemMedia.js";
 import { MentionPopover, type MentionPopoverRef } from "./MentionPopover.js";
 import {
   isClaudeCodeAgentId,
@@ -179,6 +180,7 @@ function composerReferenceFromMentionItem(
   return {
     label: item.label,
     icon: item.icon || "file",
+    media: item.media,
     source: item.source,
     refType: item.refType,
     refId: item.refId || null,
@@ -195,6 +197,7 @@ function mentionReferenceAttrs(ref: AgentComposerReference) {
   return {
     label: ref.label,
     icon: ref.icon || "file",
+    media: ref.media || null,
     source: ref.source,
     refType: ref.refType,
     refId: ref.refId || null,
@@ -3693,7 +3696,11 @@ export function TiptapComposer({
               key={ref.slotKey}
               className="inline-flex max-w-full items-center gap-1.5 rounded-md border border-border bg-background px-2 py-1 text-[11px] font-medium text-foreground shadow-sm"
             >
-              <IconClipboardList className="h-3 w-3 shrink-0 text-muted-foreground" />
+              <MentionItemMedia
+                media={ref.media}
+                size="sm"
+                fallbackIcon="clipboard"
+              />
               {ref.slotLabel && (
                 <span className="shrink-0 text-muted-foreground">
                   {ref.slotLabel}

package/src/composer/extensions/MentionReference.tsx

@@ -1,40 +1,46 @@
-import {
-  IconFile,
-  IconFolder,
-  IconFileText,
-  IconCheckbox,
-  IconMail,
-  IconUser,
-  IconPresentation,
-  IconStack2,
-  IconMessageChatbot,
-} from "@tabler/icons-react";
 import { mergeAttributes, Node } from "@tiptap/core";
 import { NodeViewWrapper, ReactNodeViewRenderer } from "@tiptap/react";
 
-const iconProps = { size: 14, className: "shrink-0 text-muted-foreground" };
+import { MentionItemMedia } from "../MentionItemMedia.js";
+import type { MentionItemMedia as MentionItemMediaValue } from "../types.js";
 
-function MentionIcon({ icon }: { icon?: string }) {
-  switch (icon) {
-    case "folder":
-      return <IconFolder {...iconProps} />;
-    case "document":
-      return <IconFileText {...iconProps} />;
-    case "form":
-      return <IconCheckbox {...iconProps} />;
-    case "email":
-      return <IconMail {...iconProps} />;
-    case "user":
-      return <IconUser {...iconProps} />;
-    case "deck":
-      return <IconPresentation {...iconProps} />;
-    case "agent":
-      return <IconMessageChatbot {...iconProps} />;
-    case "file":
-      return <IconFile {...iconProps} />;
-    default:
-      return <IconStack2 {...iconProps} />;
-  }
+function parseMentionItemMedia(
+  value: string | null,
+): MentionItemMediaValue | null {
+  if (!value) return null;
+  try {
+    const parsed: unknown = JSON.parse(value);
+    if (
+      typeof parsed !== "object" ||
+      parsed === null ||
+      Array.isArray(parsed)
+    ) {
+      return null;
+    }
+    const candidate = parsed as Record<string, unknown>;
+    const backgroundColor =
+      typeof candidate.backgroundColor === "string"
+        ? candidate.backgroundColor
+        : undefined;
+    if (candidate.type === "none") return { type: "none" };
+    if (candidate.type === "text" && typeof candidate.text === "string") {
+      return {
+        type: "text",
+        text: candidate.text,
+        ...(backgroundColor ? { backgroundColor } : {}),
+      };
+    }
+    if (candidate.type === "image" && typeof candidate.src === "string") {
+      return {
+        type: "image",
+        src: candidate.src,
+        ...(candidate.fit === "cover" ? { fit: "cover" } : {}),
+        ...(backgroundColor ? { backgroundColor } : {}),
+      };
+    }
+    // coercion-ok: Malformed optional media must preserve legacy draft rendering.
+  } catch {}
+  return null;
 }
 
 const MentionReferenceComponent = ({ node }: { node: any }) => {
@@ -44,7 +50,12 @@ const MentionReferenceComponent = ({ node }: { node: any }) => {
         className="inline-flex items-center gap-1 rounded-md border border-input bg-muted/50 px-1.5 py-0.5 text-xs font-medium text-foreground align-middle mx-0.5 max-w-[200px] select-none"
         title={node.attrs.refPath || node.attrs.refId || node.attrs.label}
       >
-        <MentionIcon icon={node.attrs.icon} />
+        <MentionItemMedia
+          icon={node.attrs.icon}
+          media={node.attrs.media}
+          size="sm"
+          fallbackIcon="stack"
+        />
         <span className="truncate">{node.attrs.label}</span>
       </span>
     </NodeViewWrapper>
@@ -62,6 +73,15 @@ export const MentionReference = Node.create({
     return {
       label: { default: null },
       icon: { default: "file" },
+      media: {
+        default: null,
+        parseHTML: (element) =>
+          parseMentionItemMedia(element.getAttribute("data-media")),
+        renderHTML: (attributes) =>
+          attributes.media
+            ? { "data-media": JSON.stringify(attributes.media) }
+            : {},
+      },
       source: { default: "" },
       refType: { default: "file" },
       refId: { default: null },

package/src/composer/index.ts

@@ -81,6 +81,8 @@ export type {
   FileResult,
   SkillResult,
   MentionItem,
+  MentionItemMedia,
+  MentionReferenceInsert,
   Reference,
   SlashCommand,
 } from "./types.js";

package/src/composer/runtime-adapters.tsx

@@ -6,6 +6,8 @@ import {
   type ReactNode,
 } from "react";
 
+import type { MentionItemMedia } from "./types.js";
+
 export type ComposerTranslate = (
   key: string,
   options?: Record<string, unknown>,
@@ -86,6 +88,7 @@ export interface ComposerBuilderConnectFlowOptions {
 export interface AgentComposerReference {
   label: string;
   icon?: string;
+  media?: MentionItemMedia;
   source?: string;
   refType: string;
   refId?: string | null;

package/src/composer/types.ts

@@ -12,11 +12,32 @@ export interface SkillResult {
   source: "codebase" | "resource";
 }
 
+export type MentionItemMedia =
+  | {
+      type: "text";
+      /** Short text shown inside the media frame, such as an emoji or initials. */
+      text: string;
+      /** Optional CSS color used behind the text. */
+      backgroundColor?: string;
+    }
+  | {
+      type: "image";
+      /** Image URL shown inside the media frame. Relative URLs are supported. */
+      src: string;
+      /** How the image fits the frame. Defaults to contain. */
+      fit?: "contain" | "cover";
+      /** Optional CSS color visible behind contained images. */
+      backgroundColor?: string;
+    }
+  | { type: "none" };
+
 export interface MentionItem {
   id: string;
   label: string;
   description?: string;
   icon?: string;
+  /** Optional presentation that takes precedence over the legacy icon. */
+  media?: MentionItemMedia;
   source: string;
   refType: string;
   refPath?: string;
@@ -44,6 +65,8 @@ export interface Reference {
 export interface MentionReferenceInsert {
   label: string;
   icon?: string;
+  /** Optional presentation that takes precedence over the legacy icon. */
+  media?: MentionItemMedia;
   source?: string;
   refType: string;
   refId?: string | null;