@carlonicora/nextjs-jsonapi 2.0.2 → 2.1.0

package/src/features/assistant-action/data/__tests__/AssistantAction.spec.ts

@@ -0,0 +1,171 @@
+import { afterAll, beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
+import { AbstractService } from "../../../../core/abstracts/AbstractService";
+import { ApiRequestDataTypeInterface } from "../../../../core/interfaces/ApiRequestDataTypeInterface";
+import { ModuleRegistry } from "../../../../core/registry/ModuleRegistry";
+import { AssistantAction } from "../AssistantAction";
+import { AssistantActionService } from "../AssistantActionService";
+
+// ---------------------------------------------------------------------------
+// Setup / teardown — the services resolve their endpoints through the real
+// ModuleRegistry, so the two modules the feature touches must be registered.
+// ---------------------------------------------------------------------------
+const assistantActionModule: ApiRequestDataTypeInterface = {
+  name: "assistant-actions",
+  model: AssistantAction,
+} as any;
+
+const assistantMessageModule: ApiRequestDataTypeInterface = {
+  name: "assistant-messages",
+  model: class {},
+} as any;
+
+// `callApi` is protected static on AbstractService; spying on it there covers
+// every subclass through the static prototype chain.
+let callApiMock: ReturnType<typeof vi.fn>;
+
+const registerIfAbsent = (key: string, module: ApiRequestDataTypeInterface) => {
+  try {
+    ModuleRegistry.get(key as any);
+  } catch {
+    ModuleRegistry.register(key, module);
+  }
+};
+
+beforeAll(() => {
+  registerIfAbsent("AssistantAction", assistantActionModule);
+  registerIfAbsent("AssistantMessage", assistantMessageModule);
+  callApiMock = vi.spyOn(AbstractService as any, "callApi") as unknown as ReturnType<typeof vi.fn>;
+});
+
+afterAll(() => {
+  vi.restoreAllMocks();
+});
+
+function makeHydratedData(overrides: Record<string, any> = {}) {
+  return {
+    jsonApi: {
+      id: "action-1",
+      type: "assistant-actions",
+      attributes: {
+        status: "pending",
+        toolName: "createNpc",
+        toolArgs: '{"name":"A"}',
+        summary: "Create a new record",
+        threadId: "thread-1",
+        userModuleIds: ["module-1"],
+        expiresAt: "2026-06-10T12:00:00.000Z",
+        ...overrides,
+      },
+      meta: {},
+      relationships: {},
+    },
+    included: [],
+  };
+}
+
+describe("AssistantAction model", () => {
+  it("rehydrates status, toolName and summary", () => {
+    const action = new AssistantAction();
+    action.rehydrate(makeHydratedData() as any);
+
+    expect(action.id).toBe("action-1");
+    expect(action.status).toBe("pending");
+    expect(action.toolName).toBe("createNpc");
+    expect(action.summary).toBe("Create a new record");
+  });
+
+  it("parses expiresAt into a Date", () => {
+    const action = new AssistantAction();
+    action.rehydrate(makeHydratedData() as any);
+
+    expect(action.expiresAt).toBeInstanceOf(Date);
+    expect(action.expiresAt).toEqual(new Date("2026-06-10T12:00:00.000Z"));
+  });
+
+  it("parses resolvedAt into a Date when present", () => {
+    const action = new AssistantAction();
+    action.rehydrate(makeHydratedData({ status: "approved", resolvedAt: "2026-06-10T11:30:00.000Z" }) as any);
+
+    expect(action.status).toBe("approved");
+    expect(action.resolvedAt).toBeInstanceOf(Date);
+    expect(action.resolvedAt).toEqual(new Date("2026-06-10T11:30:00.000Z"));
+  });
+
+  it("leaves resolvedAt undefined when absent", () => {
+    const action = new AssistantAction();
+    action.rehydrate(makeHydratedData() as any);
+
+    expect(action.resolvedAt).toBeUndefined();
+  });
+
+  it("returns defaults for missing attributes", () => {
+    const action = new AssistantAction();
+    action.rehydrate({
+      jsonApi: {
+        id: "action-1",
+        type: "assistant-actions",
+        attributes: {},
+        meta: {},
+        relationships: {},
+      },
+      included: [],
+    } as any);
+
+    // Missing status defaults to the fail-safe, non-actionable "expired" — never the actionable "pending".
+    expect(action.status).toBe("expired");
+    expect(action.toolName).toBe("");
+    expect(action.summary).toBe("");
+    expect(action.resolvedAt).toBeUndefined();
+    expect(action.expiresAt).toBeUndefined();
+  });
+
+  it("creates a minimal JSON:API payload (id only)", () => {
+    const action = new AssistantAction();
+    const payload = action.createJsonApi({ id: "action-1" });
+
+    expect(payload.data.type).toBe("assistant-actions");
+    expect(payload.data.id).toBe("action-1");
+    expect(payload.data.attributes).toEqual({});
+  });
+});
+
+describe("AssistantActionService", () => {
+  beforeEach(() => {
+    // mockClear (not mockReset): on a spy, mockReset would restore the real
+    // callApi and the assertions would fire a network request.
+    callApiMock.mockClear();
+    callApiMock.mockResolvedValue({});
+  });
+
+  it("findOne GETs the action typed as Modules.AssistantAction", async () => {
+    await AssistantActionService.findOne({ id: "action-1" });
+
+    expect(callApiMock).toHaveBeenCalledTimes(1);
+    const call = callApiMock.mock.calls[0][0];
+    expect(call.type.name).toBe("assistant-actions");
+    expect(call.method).toBe("GET");
+    expect(call.endpoint).toBe("assistant-actions/action-1");
+  });
+
+  it("approve POSTs body-less to /approve typed as Modules.AssistantMessage", async () => {
+    await AssistantActionService.approve({ id: "action-1" });
+
+    expect(callApiMock).toHaveBeenCalledTimes(1);
+    const call = callApiMock.mock.calls[0][0];
+    expect(call.type.name).toBe("assistant-messages");
+    expect(call.method).toBe("POST");
+    expect(call.endpoint).toBe("assistant-actions/action-1/approve");
+    expect(call.input).toBeUndefined();
+  });
+
+  it("deny POSTs body-less to /deny typed as Modules.AssistantMessage", async () => {
+    await AssistantActionService.deny({ id: "action-1" });
+
+    expect(callApiMock).toHaveBeenCalledTimes(1);
+    const call = callApiMock.mock.calls[0][0];
+    expect(call.type.name).toBe("assistant-messages");
+    expect(call.method).toBe("POST");
+    expect(call.endpoint).toBe("assistant-actions/action-1/deny");
+    expect(call.input).toBeUndefined();
+  });
+});

package/src/features/assistant-action/data/index.ts

@@ -0,0 +1,3 @@
+export * from "./AssistantAction";
+export * from "./AssistantActionInterface";
+export * from "./AssistantActionService";

package/src/features/assistant-action/index.ts

@@ -0,0 +1,2 @@
+export * from "./AssistantActionModule";
+export * from "./data";

package/src/features/assistant-message/components/MessageItem.tsx

@@ -2,8 +2,8 @@
 
 import { useTranslations } from "next-intl";
 import { Sparkles, AlertCircle } from "lucide-react";
-import type { ReactNode } from "react";
-import ReactMarkdown from "react-markdown";
+import { useMemo, type ReactNode } from "react";
+import ReactMarkdown, { defaultUrlTransform } from "react-markdown";
 import remarkGfm from "remark-gfm";
 import type { AssistantMessageInterface } from "../data/AssistantMessageInterface";
 import { MessageSourcesContainer } from "./parts/MessageSourcesContainer";
@@ -15,6 +15,24 @@ import { MessageSourcesContainer } from "./parts/MessageSourcesContainer";
  */
 export type ApprovalActionRenderer = (message: AssistantMessageInterface) => ReactNode;
 
+/**
+ * Render slot for `mention://<type>/<id>` links inside assistant markdown. The
+ * consuming app owns the entity chip (avatar, hovercard, navigation), so the
+ * chat renderer receives it as a function instead of importing it.
+ */
+export type MentionRenderer = (p: { type: string; id: string; alias: string }) => ReactNode;
+
+const MENTION_HREF = /^mention:\/\/([^/]+)\/(.+)$/;
+
+/**
+ * `react-markdown` strips every href whose protocol is not in its safe list,
+ * which would empty `mention://…` before the custom `a` renderer ever sees it.
+ * Let that one scheme through and defer everything else to the default.
+ */
+function mentionUrlTransform(url: string): string {
+  return MENTION_HREF.test(url) ? url : defaultUrlTransform(url);
+}
+
 interface Props {
   message: AssistantMessageInterface;
   isLatestAssistant: boolean;
@@ -22,6 +40,7 @@ interface Props {
   failedMessageIds?: Set<string>;
   onRetry?: (tempId: string) => void;
   renderApprovalAction?: ApprovalActionRenderer;
+  renderMention?: MentionRenderer;
 }
 
 export function MessageItem({
@@ -31,16 +50,42 @@ export function MessageItem({
   failedMessageIds,
   onRetry,
   renderApprovalAction,
+  renderMention,
 }: Props) {
   const t = useTranslations();
   const isUser = message.role === "user";
   const isFailed = isUser && !!failedMessageIds?.has(message.id);
 
+  const markdownComponents = useMemo(
+    () => ({
+      a: ({ href, children }: { href?: string; children?: ReactNode }) => {
+        const match = href ? MENTION_HREF.exec(href) : null;
+        if (!match || !renderMention) return <a href={href}>{children}</a>;
+        return <>{renderMention({ type: match[1], id: match[2], alias: String(children ?? "") })}</>;
+      },
+    }),
+    [renderMention],
+  );
+
   if (isUser) {
     return (
       <div className="flex flex-col items-end gap-1">
-        <div className="bg-primary text-primary-foreground max-w-[72%] rounded-2xl rounded-br-sm px-3.5 py-2 text-sm">
-          {message.content}
+        {/*
+          Rendered as markdown, not raw text: a message composed with mentions
+          is stored as `[Alias](mention://<type>/<id>)`, which would otherwise
+          show the link markup and a bare uuid to the person who just wrote it.
+          `markdownComponents` routes those hrefs through `renderMention`.
+        */}
+        {/*
+          Links inside this bubble sit on `bg-primary`. The mention chip and any
+          markdown link default to `text-primary`, which is the same teal and
+          renders invisible here, so force the on-primary colour and lean on
+          weight for the affordance (links are never underlined in this UI).
+        */}
+        <div className="bg-primary text-primary-foreground max-w-[72%] rounded-2xl rounded-br-sm px-3.5 py-2 text-sm [&_a]:text-primary-foreground [&_a]:font-semibold [&_p]:m-0">
+          <ReactMarkdown remarkPlugins={[remarkGfm]} urlTransform={mentionUrlTransform} components={markdownComponents}>
+            {message.content}
+          </ReactMarkdown>
         </div>
         {isFailed && (
           <div className="text-destructive flex items-center gap-2 text-xs">
@@ -68,8 +113,14 @@ export function MessageItem({
       {isApprovalRequest ? (
         renderApprovalAction(message)
       ) : (
-        <div className="bg-muted text-foreground rounded-2xl rounded-bl-sm px-3.5 py-2.5 text-sm leading-relaxed">
-          <ReactMarkdown remarkPlugins={[remarkGfm]}>{message.content}</ReactMarkdown>
+        // Markdown blocks arrive unstyled under Tailwind preflight (all margins
+        // zeroed): restore flow spacing between sibling blocks and give
+        // blockquotes a callout treatment — assistant answers use them for
+        // proposals and asides that must stand apart from factual prose.
+        <div className="bg-muted text-foreground rounded-2xl rounded-bl-sm px-3.5 py-2.5 text-sm leading-relaxed [&>*+*]:mt-3 [&_blockquote]:border-l-2 [&_blockquote]:border-primary/50 [&_blockquote]:bg-primary/5 [&_blockquote]:rounded-md [&_blockquote]:px-3 [&_blockquote]:py-1.5">
+          <ReactMarkdown remarkPlugins={[remarkGfm]} components={markdownComponents} urlTransform={mentionUrlTransform}>
+            {message.content}
+          </ReactMarkdown>
         </div>
       )}
       <MessageSourcesContainer

package/src/features/assistant-message/components/MessageList.tsx

@@ -1,7 +1,7 @@
 "use client";
 
 import { AssistantMessageInterface } from "../data/AssistantMessageInterface";
-import { MessageItem, type ApprovalActionRenderer } from "./MessageItem";
+import { MessageItem, type ApprovalActionRenderer, type MentionRenderer } from "./MessageItem";
 
 interface Props {
   messages: AssistantMessageInterface[];
@@ -9,9 +9,17 @@ interface Props {
   failedMessageIds?: Set<string>;
   onRetry?: (tempId: string) => void;
   renderApprovalAction?: ApprovalActionRenderer;
+  renderMention?: MentionRenderer;
 }
 
-export function MessageList({ messages, onSelectFollowUp, failedMessageIds, onRetry, renderApprovalAction }: Props) {
+export function MessageList({
+  messages,
+  onSelectFollowUp,
+  failedMessageIds,
+  onRetry,
+  renderApprovalAction,
+  renderMention,
+}: Props) {
   const ordered = [...messages].sort((a, b) => a.position - b.position);
 
   let lastAssistantIndex = -1;
@@ -33,6 +41,7 @@ export function MessageList({ messages, onSelectFollowUp, failedMessageIds, onRe
           failedMessageIds={failedMessageIds}
           onRetry={onRetry}
           renderApprovalAction={renderApprovalAction}
+          renderMention={renderMention}
         />
       ))}
     </div>

package/src/features/assistant-message/components/__tests__/MessageItem.mentions.spec.tsx

@@ -0,0 +1,34 @@
+import { describe, expect, it, vi } from "vitest";
+import { renderWithProviders, screen } from "../../../../testing";
+import type { AssistantMessageInterface } from "../../data/AssistantMessageInterface";
+import { MessageItem } from "../MessageItem";
+
+const message = {
+  id: "m1",
+  type: "assistant-messages",
+  role: "assistant",
+  position: 1,
+  content: "Ask [The Quiet One](mention://npcs/npc-1) about it.",
+  references: [],
+  citations: [],
+  suggestedQuestions: [],
+} as unknown as AssistantMessageInterface;
+
+describe("MessageItem mention rendering", () => {
+  it("hands mention links to renderMention", () => {
+    renderWithProviders(
+      <MessageItem
+        message={message}
+        isLatestAssistant={false}
+        onSelectFollowUp={vi.fn()}
+        renderMention={({ type, id, alias }) => <span data-testid="mention">{`${type}:${id}:${alias}`}</span>}
+      />,
+    );
+    expect(screen.getByTestId("mention")).toHaveTextContent("npcs:npc-1:The Quiet One");
+  });
+
+  it("renders a plain link when no renderer is supplied", () => {
+    renderWithProviders(<MessageItem message={message} isLatestAssistant={false} onSelectFollowUp={vi.fn()} />);
+    expect(screen.getByText("The Quiet One")).toBeInTheDocument();
+  });
+});

package/src/features/assistant-message/components/parts/MessageSourcesContainer.tsx

@@ -18,19 +18,36 @@ class SourcesFetcher extends ClientAbstractService {
     idsParam: string;
     ids: string[];
   }): Promise<ApiDataInterface[]> {
-    const endpoint = new EndpointCreator({ endpoint: params.module });
-    endpoint.addAdditionalParam(params.idsParam, params.ids.join(","));
-    // The list endpoint paginates and does not honour the `<x>Ids` filter, so a cited
-    // entity beyond the default first page never comes back and its citation falls back
-    // to "<Type> <id>". Request the full set and resolve client-side by id.
-    endpoint.addAdditionalParam("fetchAll", "true");
-    if (params.module.inclusions?.lists?.fields) endpoint.limitToFields(params.module.inclusions.lists.fields);
-    if (params.module.inclusions?.lists?.types) endpoint.limitToType(params.module.inclusions.lists.types);
-    return this.callApi<ApiDataInterface[]>({
-      type: params.module,
-      method: ClientHttpMethod.GET,
-      endpoint: endpoint.generate(),
-    });
+    // Resolved one id at a time, deliberately.
+    //
+    // The obvious alternative — a single `GET /<type>?<type>Ids=…&fetchAll=true`
+    // — assumes every entity exposes a flat collection route. narr8 does not:
+    // it serves `/npcs/:id` and `/campaigns/:campaignId/npcs`, with no
+    // `GET /npcs`, so the bulk call 404s, every citation degrades to
+    // "<Type> <uuid>", and the browser logs a failed request for each source
+    // type on every message. Reading by id needs only the by-id route, which
+    // every entity has. Citation counts are small (a handful per message) and
+    // the reads run in parallel, so the extra round-trips are cheap.
+    return this.findEachById(params);
+  }
+
+  private static async findEachById(params: {
+    module: ApiRequestDataTypeInterface;
+    ids: string[];
+  }): Promise<ApiDataInterface[]> {
+    const settled = await Promise.allSettled(
+      params.ids.map((id) =>
+        this.callApi<ApiDataInterface>({
+          type: params.module,
+          method: ClientHttpMethod.GET,
+          endpoint: new EndpointCreator({ endpoint: params.module, id }).generate(),
+        }),
+      ),
+    );
+    // A deleted or unreadable source must not blank out the whole panel.
+    return settled
+      .filter((r): r is PromiseFulfilledResult<ApiDataInterface> => r.status === "fulfilled" && !!r.value)
+      .map((r) => r.value);
   }
 }
 

package/src/features/assistant-message/components/parts/tabs/CitationsTab.tsx

@@ -11,6 +11,7 @@ import { Table, TableBody, TableCell, TableHead, TableHeader, TableRow } from ".
 import { Tooltip, TooltipContent, TooltipTrigger } from "../../../../../shadcnui/ui/tooltip";
 import { cn } from "@/lib/utils";
 import { RelevanceMeter } from "../RelevanceMeter";
+import { useEntityLabel } from "./useEntityLabel";
 
 interface Props {
   citations: (ChunkInterface & ChunkRelationshipMeta)[];
@@ -24,6 +25,7 @@ interface Props {
 
 export function CitationsTab({ citations, sources }: Props) {
   const t = useTranslations();
+  const entityLabel = useEntityLabel();
   const [expanded, setExpanded] = useState<Set<string>>(new Set());
   if (citations.length === 0) return null;
 
@@ -50,9 +52,12 @@ export function CitationsTab({ citations, sources }: Props) {
         {sorted.map((chunk) => {
           const isOpen = expanded.has(chunk.id);
           const resolved = chunk.nodeId ? sources?.get(chunk.nodeId) : undefined;
-          const fallbackName = chunk.nodeId
-            ? `${chunk.nodeType ?? t("features.assistant.message.sources.source")} ${chunk.nodeId.slice(0, 8)}`
-            : (chunk.nodeType ?? t("features.assistant.message.sources.source"));
+          // `nodeType` is a JSON:API wire type (`npcs`), not UI copy — translate
+          // it the same way the References tab does before showing it.
+          const typeLabel = chunk.nodeType
+            ? entityLabel(chunk.nodeType)
+            : t("features.assistant.message.sources.source");
+          const fallbackName = chunk.nodeId ? `${typeLabel} ${chunk.nodeId.slice(0, 8)}` : typeLabel;
           const sourceName = (resolved as any)?.name ?? fallbackName;
           return (
             <Fragment key={chunk.id}>
@@ -89,8 +94,21 @@ export function CitationsTab({ citations, sources }: Props) {
               </TableRow>
               {isOpen && (
                 <TableRow>
-                  <TableCell colSpan={2} className="border-t-0 p-4">
-                    <div className="bg-card w-full max-w-full overflow-x-auto rounded border p-4 text-sm break-words">
+                  {/*
+                    `max-w-0` is the table-layout trick: without it the cell
+                    sizes to its widest line, so the panel either scrolls
+                    sideways or clips. Pinning the cell's intrinsic max width to
+                    zero makes the browser take its width from the table instead,
+                    which lets the content below actually wrap.
+                  */}
+                  <TableCell colSpan={2} className="w-full max-w-0 border-t-0 p-4">
+                    {/*
+                      Prose wraps; only genuinely wide children scroll. The
+                      wrapper used to be `overflow-x-auto`, which turned every
+                      long sentence into a horizontal scrollbar instead of
+                      breaking onto the next line.
+                    */}
+                    <div className="bg-card w-full min-w-0 rounded border p-4 text-sm break-words whitespace-pre-wrap [overflow-wrap:anywhere] [&_pre]:overflow-x-auto [&_table]:block [&_table]:overflow-x-auto">
                       <ReactMarkdown remarkPlugins={[remarkGfm]}>{chunk.content}</ReactMarkdown>
                     </div>
                   </TableCell>

package/src/features/assistant-message/components/parts/tabs/ContentsTab.tsx

@@ -7,6 +7,7 @@ import { ModuleRegistry } from "../../../../../core/registry/ModuleRegistry";
 import { usePageUrlGenerator } from "../../../../../hooks";
 import { Table, TableBody, TableCell, TableHead, TableHeader, TableRow } from "../../../../../shadcnui/ui/table";
 import type { ChunkInterface, ChunkRelationshipMeta } from "../../../../chunk/data/ChunkInterface";
+import { useEntityLabel } from "./useEntityLabel";
 
 interface Props {
   citations: (ChunkInterface & ChunkRelationshipMeta)[];
@@ -22,6 +23,7 @@ interface ContentRow {
 
 export function ContentsTab({ citations, sources }: Props) {
   const t = useTranslations();
+  const entityLabel = useEntityLabel();
   const generate = usePageUrlGenerator();
 
   // Group citations by nodeId, then materialise rows from the resolved sources
@@ -82,7 +84,7 @@ export function ContentsTab({ citations, sources }: Props) {
                   </span>
                 </Link>
               </TableCell>
-              <TableCell className="text-muted-foreground text-xs">{module.name}</TableCell>
+              <TableCell className="text-muted-foreground text-xs">{entityLabel(module.name)}</TableCell>
             </TableRow>
           );
         })}

package/src/features/assistant-message/components/parts/tabs/ReferencesTab.tsx

@@ -6,6 +6,7 @@ import type { ApiDataInterface } from "../../../../../core";
 import { ModuleRegistry } from "../../../../../core/registry/ModuleRegistry";
 import { usePageUrlGenerator } from "../../../../../hooks";
 import { Table, TableBody, TableCell, TableHead, TableHeader, TableRow } from "../../../../../shadcnui/ui/table";
+import { useEntityLabel } from "./useEntityLabel";
 
 interface Props {
   references: ApiDataInterface[];
@@ -15,6 +16,8 @@ export function ReferencesTab({ references }: Props) {
   const t = useTranslations();
   const generate = usePageUrlGenerator();
 
+  const entityLabel = useEntityLabel();
+
   if (references.length === 0) return null;
 
   return (
@@ -43,7 +46,7 @@ export function ReferencesTab({ references }: Props) {
                   {ref.identifier}
                 </Link>
               </TableCell>
-              <TableCell className="text-muted-foreground text-xs">{module.name}</TableCell>
+              <TableCell className="text-muted-foreground text-xs">{entityLabel(module.name)}</TableCell>
             </TableRow>
           );
         })}

package/src/features/assistant-message/components/parts/tabs/useEntityLabel.ts

@@ -0,0 +1,35 @@
+"use client";
+
+import { useTranslations } from "next-intl";
+import { useCallback } from "react";
+
+/**
+ * Turns a JSON:API type (`npcs`, `locations`) into UI copy.
+ *
+ * The source panels receive wire identifiers, not labels. Host apps translate
+ * entity names under `entities.<type>` with a plural count, so prefer that and
+ * fall back to the raw type when the app has no such key — the panel must
+ * still render for a type the app never localised.
+ */
+export function useEntityLabel(): (type: string) => string {
+  const t = useTranslations();
+
+  return useCallback(
+    (type: string): string => {
+      const key = `entities.${type}`;
+      // `t.has` is the only non-throwing probe: a plain `t()` on a missing key
+      // either throws or returns the key path, depending on the host app's
+      // next-intl error handler, and the key path reads worse than the type.
+      if (typeof t.has === "function" && !t.has(key as never)) return type;
+      try {
+        // Cast through the untyped call signature: the key is computed, so the
+        // generated message-key union cannot describe it, and the `count`
+        // parameter is only accepted on keys the union knows about.
+        return (t as unknown as (k: string, values?: Record<string, unknown>) => string)(key, { count: 1 });
+      } catch {
+        return type;
+      }
+    },
+    [t],
+  );
+}

package/src/features/assistant-message/data/AssistantMessage.ts

@@ -125,12 +125,21 @@ export class AssistantMessage extends AbstractApiData implements AssistantMessag
    * the append-to-thread endpoint derives those server-side, so we only send `content` and
    * the optional retrieval-mode flags.
    */
-  createAppendMessageJsonApi(params: { content: string; howToMode?: boolean; limitToHowToId?: string }) {
+  createAppendMessageJsonApi(params: {
+    content: string;
+    howToMode?: boolean;
+    limitToHowToId?: string;
+    contentBlocks?: unknown[];
+  }) {
     return {
       data: {
         type: Modules.AssistantMessage.name,
         attributes: {
-          content: params.content,
+          // narr8 convention for BlockNote-backed fields: the document travels
+          // as a JSON string in the field's own string attribute (see
+          // Npc.description). The server detects the shape and derives the
+          // stored markdown from it.
+          content: params.contentBlocks !== undefined ? JSON.stringify(params.contentBlocks) : params.content,
           ...(params.howToMode !== undefined ? { howToMode: params.howToMode } : {}),
           ...(params.limitToHowToId !== undefined ? { limitToHowToId: params.limitToHowToId } : {}),
         },

package/src/features/company/components/details/TokenStatusIndicator.tsx

@@ -121,20 +121,25 @@ export function TokenStatusIndicator({ className, size = "md", showExtraPages =
 
   return (
     <Tooltip>
-      <TooltipTrigger>
-        <div
-          className={cn("inline-flex items-center gap-1.5 cursor-default", className)}
-          aria-label={t("billing.tokens.status", { defaultValue: "Page Status" })}
-        >
-          {getBatteryIcon()}
-          <span className={cn(textSize, "text-muted-foreground font-medium")}>{availableMonthlyCredits}</span>
-          {showExtraPages && availableExtraCredits > 0 && (
-            <div className="inline-flex items-center gap-0.5">
-              <PlusCircle className={cn(smallIconSize, "text-blue-500")} />
-              <span className={cn(textSize, "text-blue-500 font-medium")}>{availableExtraCredits}</span>
-            </div>
-          )}
-        </div>
+      {/* The layout classes live on the trigger itself, which renders the
+          <button>. Wrapping them in a nested inline-flex div instead makes that
+          child sit on the button's text baseline, so the button reserves
+          descender space below it and the icons render ~2px above the centre of
+          any flex row the indicator is placed in (e.g. the app header). */}
+      <TooltipTrigger
+        className={cn("inline-flex items-center gap-1.5 cursor-default", className)}
+        aria-label={t("billing.tokens.status", { defaultValue: "Page Status" })}
+      >
+        {getBatteryIcon()}
+        <span className={cn(textSize, "text-muted-foreground font-medium leading-none")}>
+          {availableMonthlyCredits}
+        </span>
+        {showExtraPages && availableExtraCredits > 0 && (
+          <span className="inline-flex items-center gap-0.5">
+            <PlusCircle className={cn(smallIconSize, "text-blue-500")} />
+            <span className={cn(textSize, "text-blue-500 font-medium leading-none")}>{availableExtraCredits}</span>
+          </span>
+        )}
       </TooltipTrigger>
       <TooltipContent side="top" className="max-w-xs">
         {tooltipContent}

package/src/features/index.ts

@@ -1,4 +1,5 @@
 // S3 feature exports
+export * from "./assistant-action";
 export * from "./auth";
 export * from "./billing";
 export * from "./billing/stripe-customer";

package/dist/AssistantInterface-B56qznuH.d.mts

@@ -1,16 +0,0 @@
-import { A as ApiDataInterface } from './ApiDataInterface-BcZeXy5X.mjs';
-
-type AssistantInput = {
-    firstMessage: string;
-    title?: string;
-    howToMode?: boolean;
-    limitToHowToId?: string;
-};
-interface AssistantInterface extends ApiDataInterface {
-    get title(): string;
-    get messageCount(): number;
-    /** Agent engine the thread runs on — `"operator"` or undefined (responder). */
-    get engine(): string | undefined;
-}
-
-export type { AssistantInput as A, AssistantInterface as a };

package/dist/AssistantInterface-CHiJIYDY.d.ts

@@ -1,16 +0,0 @@
-import { A as ApiDataInterface } from './ApiDataInterface-BcZeXy5X.js';
-
-type AssistantInput = {
-    firstMessage: string;
-    title?: string;
-    howToMode?: boolean;
-    limitToHowToId?: string;
-};
-interface AssistantInterface extends ApiDataInterface {
-    get title(): string;
-    get messageCount(): number;
-    /** Agent engine the thread runs on — `"operator"` or undefined (responder). */
-    get engine(): string | undefined;
-}
-
-export type { AssistantInput as A, AssistantInterface as a };