@carlonicora/nextjs-jsonapi 1.79.0 → 1.81.0

package/dist/index.mjs

@@ -17,7 +17,7 @@ import {
   getWaitlistConfig,
   isReferralEnabled,
   isRolesConfigured
-} from "./chunk-MEWXQEVE.mjs";
+} from "./chunk-PV5V6CVW.mjs";
 import {
   AVAILABLE_OAUTH_SCOPES,
   AbstractApiData,
@@ -44,6 +44,8 @@ import {
   BillingService,
   BlockNoteDiffUtil,
   BlockNoteWordDiffRendererUtil,
+  Chunk,
+  ChunkModule,
   ClientAbstractService,
   ClientHttpMethod,
   Company,
@@ -195,7 +197,7 @@ import {
   useComposedRefs,
   useIsMobile,
   userObjectSchema
-} from "./chunk-BKM5U3DE.mjs";
+} from "./chunk-6UMB5LTQ.mjs";
 import "./chunk-AUXK7QSA.mjs";
 import "./chunk-C7C7VY4F.mjs";
 import {
@@ -238,6 +240,8 @@ export {
   BlockNoteDiffUtil,
   BlockNoteWordDiffRendererUtil,
   COMPANY_ADMINISTRATOR_ROLE_ID,
+  Chunk,
+  ChunkModule,
   ClientAbstractService,
   ClientHttpMethod,
   Company,

package/dist/server/index.js

@@ -15,7 +15,7 @@ var _chunk3ZPK4QOBjs = require('../chunk-3ZPK4QOB.js');
 
 
 
-var _chunk5IEWLLLDjs = require('../chunk-5IEWLLLD.js');
+var _chunkN4YZ45SKjs = require('../chunk-N4YZ45SK.js');
 require('../chunk-LXKSUWAV.js');
 require('../chunk-IBS6NI7D.js');
 
@@ -86,7 +86,7 @@ var ServerSession = class {
     if (!rawModules) return false;
     const modules = JSON.parse(_pako2.default.ungzip(Buffer.from(rawModules, "base64"), { to: "string" }));
     const selectedModule = modules.find((module) => module.id === params.module.moduleId);
-    return _chunk5IEWLLLDjs.checkPermissionsFromServer.call(void 0, {
+    return _chunkN4YZ45SKjs.checkPermissionsFromServer.call(void 0, {
       module: params.module,
       action: params.action,
       data: params.data,
@@ -296,5 +296,5 @@ _chunk7QVYU63Ejs.__name.call(void 0, ServerJsonApiDelete, "ServerJsonApiDelete")
 
 
 
-exports.ServerAuthService = _chunk5IEWLLLDjs.AuthService; exports.ServerCompanyService = _chunk5IEWLLLDjs.CompanyService; exports.ServerContentService = _chunk5IEWLLLDjs.ContentService; exports.ServerFeatureService = _chunk5IEWLLLDjs.FeatureService; exports.ServerJsonApiDelete = ServerJsonApiDelete; exports.ServerJsonApiGet = ServerJsonApiGet; exports.ServerJsonApiPatch = ServerJsonApiPatch; exports.ServerJsonApiPost = ServerJsonApiPost; exports.ServerJsonApiPut = ServerJsonApiPut; exports.ServerNotificationService = _chunk5IEWLLLDjs.NotificationService; exports.ServerPushService = _chunk5IEWLLLDjs.PushService; exports.ServerRoleService = _chunk5IEWLLLDjs.RoleService; exports.ServerS3Service = _chunk5IEWLLLDjs.S3Service; exports.ServerSession = ServerSession; exports.ServerUserService = _chunk5IEWLLLDjs.UserService; exports.configureServerJsonApi = configureServerJsonApi; exports.getServerApiUrl = getServerApiUrl; exports.getServerAppUrl = getServerAppUrl; exports.getServerToken = _chunkYUO55Q5Ajs.getServerToken; exports.getServerTrackablePages = getServerTrackablePages; exports.invalidateCacheTag = invalidateCacheTag; exports.invalidateCacheTags = invalidateCacheTags; exports.serverRequest = _chunk3ZPK4QOBjs.serverRequest;
+exports.ServerAuthService = _chunkN4YZ45SKjs.AuthService; exports.ServerCompanyService = _chunkN4YZ45SKjs.CompanyService; exports.ServerContentService = _chunkN4YZ45SKjs.ContentService; exports.ServerFeatureService = _chunkN4YZ45SKjs.FeatureService; exports.ServerJsonApiDelete = ServerJsonApiDelete; exports.ServerJsonApiGet = ServerJsonApiGet; exports.ServerJsonApiPatch = ServerJsonApiPatch; exports.ServerJsonApiPost = ServerJsonApiPost; exports.ServerJsonApiPut = ServerJsonApiPut; exports.ServerNotificationService = _chunkN4YZ45SKjs.NotificationService; exports.ServerPushService = _chunkN4YZ45SKjs.PushService; exports.ServerRoleService = _chunkN4YZ45SKjs.RoleService; exports.ServerS3Service = _chunkN4YZ45SKjs.S3Service; exports.ServerSession = ServerSession; exports.ServerUserService = _chunkN4YZ45SKjs.UserService; exports.configureServerJsonApi = configureServerJsonApi; exports.getServerApiUrl = getServerApiUrl; exports.getServerAppUrl = getServerAppUrl; exports.getServerToken = _chunkYUO55Q5Ajs.getServerToken; exports.getServerTrackablePages = getServerTrackablePages; exports.invalidateCacheTag = invalidateCacheTag; exports.invalidateCacheTags = invalidateCacheTags; exports.serverRequest = _chunk3ZPK4QOBjs.serverRequest;
 //# sourceMappingURL=index.js.map

package/dist/server/index.mjs

@@ -15,7 +15,7 @@ import {
   S3Service,
   UserService,
   checkPermissionsFromServer
-} from "../chunk-BKM5U3DE.mjs";
+} from "../chunk-6UMB5LTQ.mjs";
 import "../chunk-AUXK7QSA.mjs";
 import "../chunk-C7C7VY4F.mjs";
 import {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@carlonicora/nextjs-jsonapi",
-  "version": "1.79.0",
+  "version": "1.81.0",
   "description": "Next.js JSON:API client with server/client support and caching",
   "author": "Carlo Nicora",
   "license": "GPL-3.0-or-later",

package/src/components/index.ts

@@ -31,6 +31,7 @@ export * from "../features/user/components";
 export * from "../features/oauth/components";
 export * from "../features/waitlist/components";
 export { RbacContainer } from "../features/rbac/components/RbacContainer";
+export { RbacByRoleContainer } from "../features/rbac/components/RbacByRoleContainer";
 export { RbacPermissionCell } from "../features/rbac/components/RbacPermissionCell";
 export { RbacPermissionPicker } from "../features/rbac/components/RbacPermissionPicker";
 

package/src/core/index.ts

@@ -65,6 +65,8 @@ export * from "../features/assistant/AssistantModule";
 export * from "../features/assistant/data";
 export * from "../features/assistant-message/AssistantMessageModule";
 export * from "../features/assistant-message/data";
+export * from "../features/chunk/ChunkModule";
+export * from "../features/chunk/data";
 export * from "../features/feature/data";
 export * from "../features/feature/feature.module";
 export * from "../features/module";

package/src/core/registry/ModuleRegistry.ts

@@ -18,6 +18,7 @@ export interface FoundationModuleDefinitions {
   HowTo: ModuleWithPermissions;
   Assistant: ModuleWithPermissions;
   AssistantMessage: ModuleWithPermissions;
+  Chunk: ModuleWithPermissions;
   // Billing modules - READ: all users, UPDATE: CompanyAdministrator, ADMIN: Administrator
   Billing: ModuleWithPermissions;
   StripeCustomer: ModuleWithPermissions;

package/src/features/assistant/components/parts/AssistantThread.tsx

@@ -22,7 +22,7 @@ export function AssistantThread({ messages, sending, status, onSelectFollowUp, f
   }, [messages.length, sending]);
 
   return (
-    <div className="flex-1 overflow-y-auto px-6 py-5">
+    <div className="flex-1 min-w-0 overflow-x-hidden overflow-y-auto px-6 py-5">
       <MessageList
         messages={messages}
         onSelectFollowUp={onSelectFollowUp}

package/src/features/assistant-message/AssistantMessageModule.ts

@@ -12,6 +12,7 @@ export const AssistantMessageModule = (factory: ModuleFactory) =>
     icon: MessageSquareIcon,
     inclusions: {
       lists: {
+        types: [`references`, `citations`, `citations.source`, `citations.source.author`],
         fields: [
           createJsonApiInclusion("assistant-messages", [
             `role`,
@@ -21,7 +22,10 @@ export const AssistantMessageModule = (factory: ModuleFactory) =>
             `inputTokens`,
             `outputTokens`,
             `references`,
+            `citations`,
           ]),
+          createJsonApiInclusion("chunks", [`content`, `nodeId`, `nodeType`, `imagePath`, `source`]),
+          createJsonApiInclusion("users", [`name`, `avatar`]),
         ],
       },
     },

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

@@ -5,8 +5,7 @@ import { Sparkles, AlertCircle } from "lucide-react";
 import ReactMarkdown from "react-markdown";
 import remarkGfm from "remark-gfm";
 import type { AssistantMessageInterface } from "../data/AssistantMessageInterface";
-import { ReferenceBadges } from "./parts/ReferenceBadges";
-import { SuggestedFollowUps } from "./parts/SuggestedFollowUps";
+import { MessageSourcesContainer } from "./parts/MessageSourcesContainer";
 
 interface Props {
   message: AssistantMessageInterface;
@@ -41,7 +40,7 @@ export function MessageItem({ message, isLatestAssistant, onSelectFollowUp, fail
   }
 
   return (
-    <div className="flex max-w-[78%] flex-col gap-1.5">
+    <div className="flex min-w-0 max-w-[78%] flex-col gap-1.5">
       <div className="text-muted-foreground flex items-center gap-2 pl-1 text-xs">
         <span className="flex h-4 w-4 items-center justify-center rounded-full bg-gradient-to-br from-blue-400 to-violet-500 text-white">
           <Sparkles className="h-2.5 w-2.5" />
@@ -51,10 +50,11 @@ export function MessageItem({ message, isLatestAssistant, onSelectFollowUp, fail
       <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>
       </div>
-      <ReferenceBadges references={message.references} />
-      {isLatestAssistant && (
-        <SuggestedFollowUps questions={message.suggestedQuestions ?? []} onSelect={onSelectFollowUp} />
-      )}
+      <MessageSourcesContainer
+        message={message}
+        isLatestAssistant={isLatestAssistant}
+        onSelectFollowUp={onSelectFollowUp}
+      />
     </div>
   );
 }

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

@@ -22,7 +22,7 @@ export function MessageList({ messages, onSelectFollowUp, failedMessageIds, onRe
   }
 
   return (
-    <div className="flex flex-col gap-y-3">
+    <div className="flex min-w-0 flex-col gap-y-3">
       {ordered.map((m, i) => (
         <MessageItem
           key={m.id}

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

@@ -8,7 +8,7 @@ import type { ApiDataInterface } from "../../../../core";
 import type { AssistantMessageInterface } from "../../data/AssistantMessageInterface";
 import { MessageItem } from "../MessageItem";
 
-// Test-only account model to exercise ReferenceBadges
+// Test-only account model to exercise the sources panel references list
 class TestAccount extends AbstractApiData {
   static identifierFields: string[] = ["name"];
   rehydrate(data: any): this {
@@ -51,6 +51,7 @@ function buildMessageStub(p: {
     content: p.content ?? "",
     position: 0,
     references: p.references ?? [],
+    citations: [],
     suggestedQuestions: p.suggestedQuestions ?? [],
     createdAt: new Date(),
     updatedAt: new Date(),
@@ -66,7 +67,7 @@ describe("MessageItem", () => {
     expect(screen.queryByText("features.assistant.agent_name")).not.toBeInTheDocument();
   });
 
-  it("assistant message renders bubble, references, and suggestions toggle when latest", () => {
+  it("assistant message renders agent label and the sources panel toggle when sources exist", () => {
     const msg = buildMessageStub({
       role: "assistant",
       content: "**bold** reply",
@@ -75,14 +76,17 @@ describe("MessageItem", () => {
     });
     render(<MessageItem message={msg} isLatestAssistant={true} onSelectFollowUp={vi.fn()} />);
     expect(screen.getByText("features.assistant.agent_name")).toBeInTheDocument();
-    expect(screen.getByRole("link", { name: /acme/i })).toBeInTheDocument();
-    expect(screen.getByRole("button", { name: /show_suggestions/ })).toBeInTheDocument();
+    // The MessageSourcesPanel toggle uses the message.sources.toggle translation key.
+    expect(screen.getByRole("button", { name: /sources\.toggle/i })).toBeInTheDocument();
   });
 
-  it("assistant message NOT latest: no suggestions toggle", () => {
+  it("assistant message NOT latest with only suggestions: no sources panel rendered", () => {
     const msg = buildMessageStub({ role: "assistant", content: "prior", suggestedQuestions: ["x"] });
-    render(<MessageItem message={msg} isLatestAssistant={false} onSelectFollowUp={vi.fn()} />);
-    expect(screen.queryByRole("button", { name: /show_suggestions/ })).not.toBeInTheDocument();
+    const { container } = render(<MessageItem message={msg} isLatestAssistant={false} onSelectFollowUp={vi.fn()} />);
+    // No sources/citations/references and suggestions are gated by isLatestAssistant -> panel renders nothing.
+    expect(screen.queryByRole("button", { name: /sources\.toggle/i })).not.toBeInTheDocument();
+    // Sanity: the assistant bubble itself still rendered.
+    expect(container).not.toBeEmptyDOMElement();
   });
 
   it("failed user message: renders retry control and calls onRetry with the id", async () => {

package/src/features/assistant-message/components/index.ts

@@ -1,2 +1,3 @@
 export * from "./MessageItem";
 export * from "./MessageList";
+export { MessageSourcesPanel } from "./parts/MessageSourcesPanel";

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

@@ -0,0 +1,135 @@
+"use client";
+
+import { useEffect, useMemo, useState } from "react";
+import { ClientAbstractService, ClientHttpMethod, EndpointCreator, ModuleRegistry } from "../../../../core";
+import type { ApiDataInterface, ApiRequestDataTypeInterface } from "../../../../core";
+import type { AssistantMessageInterface } from "../../data/AssistantMessageInterface";
+import { MessageSourcesPanel } from "./MessageSourcesPanel";
+
+interface Props {
+  message: AssistantMessageInterface;
+  isLatestAssistant: boolean;
+  onSelectFollowUp: (q: string) => void;
+}
+
+class SourcesFetcher extends ClientAbstractService {
+  static async findManyByIds(params: {
+    module: ApiRequestDataTypeInterface;
+    idsParam: string;
+    ids: string[];
+  }): Promise<ApiDataInterface[]> {
+    const endpoint = new EndpointCreator({ endpoint: params.module });
+    endpoint.addAdditionalParam(params.idsParam, params.ids.join(","));
+    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(),
+    });
+  }
+}
+
+/**
+ * Library-level data wrapper around `MessageSourcesPanel`. Reads
+ * `chunk.nodeId` / `chunk.nodeType` from the message's citations, dynamically
+ * resolves the matching module via `ModuleRegistry.findByModelName(nodeType)`,
+ * fetches the entities in one request per type, and supplies them (plus their
+ * deduplicated `author` users) to the presentational panel.
+ */
+export function MessageSourcesContainer({ message, isLatestAssistant, onSelectFollowUp }: Props) {
+  // Group nodeIds per nodeType so we issue one request per source type.
+  const groups = useMemo(() => {
+    const map = new Map<string, Set<string>>();
+    for (const chunk of message.citations) {
+      if (!chunk.nodeType || !chunk.nodeId) continue;
+      let bucket = map.get(chunk.nodeType);
+      if (!bucket) {
+        bucket = new Set<string>();
+        map.set(chunk.nodeType, bucket);
+      }
+      bucket.add(chunk.nodeId);
+    }
+    return map;
+  }, [message.citations]);
+
+  // Flatten to a deterministic key so useEffect re-runs when ids change.
+  const groupsKey = useMemo(() => {
+    const parts: string[] = [];
+    for (const [nodeType, ids] of groups) {
+      parts.push(`${nodeType}:${Array.from(ids).sort().join(",")}`);
+    }
+    return parts.sort().join("|");
+  }, [groups]);
+
+  const [resolved, setResolved] = useState<ApiDataInterface[]>([]);
+
+  useEffect(() => {
+    if (groups.size === 0) {
+      setResolved([]);
+      return;
+    }
+    let cancelled = false;
+    const requests: Promise<ApiDataInterface[]>[] = [];
+    for (const [nodeType, idSet] of groups) {
+      let module: ApiRequestDataTypeInterface | undefined;
+      try {
+        module = ModuleRegistry.findByModelName(nodeType);
+      } catch {
+        continue; // No registered module for this nodeType — skip silently.
+      }
+      const idsParam = `${(module as any).nodeName ?? module.name.replace(/s$/, "")}Ids`;
+      requests.push(
+        SourcesFetcher.findManyByIds({
+          module,
+          idsParam,
+          ids: Array.from(idSet),
+        }).catch((error) => {
+          console.error(`Failed to load sources for ${nodeType}:`, error);
+          return [] as ApiDataInterface[];
+        }),
+      );
+    }
+    Promise.all(requests).then((results) => {
+      if (cancelled) return;
+      setResolved(results.flat());
+    });
+    return () => {
+      cancelled = true;
+    };
+  }, [groupsKey, groups]);
+
+  const sources = useMemo(() => {
+    const map = new Map<string, ApiDataInterface>();
+    for (const entity of resolved) map.set(entity.id, entity);
+    return map;
+  }, [resolved]);
+
+  const users = useMemo(() => {
+    const userMap = new Map<string, ApiDataInterface>();
+    for (const entity of resolved) {
+      // Content.author getter throws when missing; tolerate either shape.
+      const author =
+        (entity as any)._author ??
+        (() => {
+          try {
+            return (entity as any).author;
+          } catch {
+            return undefined;
+          }
+        })();
+      if (author?.id) userMap.set(author.id, author);
+    }
+    return Array.from(userMap.values());
+  }, [resolved]);
+
+  return (
+    <MessageSourcesPanel
+      message={message}
+      isLatestAssistant={isLatestAssistant}
+      onSelectFollowUp={onSelectFollowUp}
+      sources={sources}
+      users={users}
+    />
+  );
+}

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

@@ -0,0 +1,151 @@
+"use client";
+
+import { useMemo, useState } from "react";
+import { useTranslations } from "next-intl";
+import { ChevronDown, ChevronRight } from "lucide-react";
+import type { ApiDataInterface } from "../../../../core";
+import { ModuleRegistry } from "../../../../core/registry/ModuleRegistry";
+import type { AssistantMessageInterface } from "../../data/AssistantMessageInterface";
+import { Tabs, TabsContent, TabsList, TabsTrigger } from "../../../../shadcnui/ui/tabs";
+import { ReferencesTab } from "./tabs/ReferencesTab";
+import { CitationsTab } from "./tabs/CitationsTab";
+import { ContentsTab } from "./tabs/ContentsTab";
+import { UsersTab } from "./tabs/UsersTab";
+import { SuggestedQuestionsTab } from "./tabs/SuggestedQuestionsTab";
+
+interface Props {
+  message: AssistantMessageInterface;
+  isLatestAssistant: boolean;
+  onSelectFollowUp: (q: string) => void;
+  /**
+   * Map of resolved source entities keyed by `chunk.nodeId`. When provided, the
+   * Contents and Citations tabs use these to render real entity names. The
+   * library is presentational; the app fetches and supplies these.
+   */
+  sources?: Map<string, ApiDataInterface>;
+  /**
+   * Deduplicated list of authors derived from the resolved sources. When
+   * provided, the Users tab is populated from this list.
+   */
+  users?: ApiDataInterface[];
+}
+
+type TabKey = "suggested" | "references" | "citations" | "contents" | "users";
+
+export function MessageSourcesPanel({ message, isLatestAssistant, onSelectFollowUp, sources, users }: Props) {
+  const t = useTranslations();
+
+  // Filter out references whose module has no pageUrl: those are
+  // intermediary/relational nodes (e.g., BomItem, BomTreeNode) that the user
+  // shouldn't navigate to directly.
+  const visibleReferences = useMemo(
+    () =>
+      message.references.filter((ref) => {
+        try {
+          return !!ModuleRegistry.findByName(ref.type).pageUrl;
+        } catch {
+          return false;
+        }
+      }),
+    [message.references],
+  );
+
+  const refsCount = visibleReferences.length;
+  const citationsCount = message.citations.length;
+  const suggestionsCount = isLatestAssistant ? message.suggestedQuestions.length : 0;
+
+  const contentsCount = useMemo(() => {
+    if (sources) return sources.size;
+    // Fallback: derive from unique nodeId on chunks when sources haven't been
+    // supplied yet (e.g., during the initial fetch).
+    const ids = new Set<string>();
+    for (const c of message.citations) {
+      if (c.nodeId) ids.add(c.nodeId);
+    }
+    return ids.size;
+  }, [message.citations, sources]);
+
+  const usersCount = users?.length ?? 0;
+
+  const total = refsCount + citationsCount + contentsCount + usersCount + suggestionsCount;
+
+  const visibleTabs: TabKey[] = [];
+  if (suggestionsCount > 0) visibleTabs.push("suggested");
+  if (refsCount > 0) visibleTabs.push("references");
+  if (citationsCount > 0) visibleTabs.push("citations");
+  if (contentsCount > 0) visibleTabs.push("contents");
+  if (usersCount > 0) visibleTabs.push("users");
+
+  const autoOpen = isLatestAssistant && suggestionsCount > 0;
+  const initialTab: TabKey | undefined = autoOpen ? "suggested" : visibleTabs[0];
+  const [open, setOpen] = useState(autoOpen);
+  const [active, setActive] = useState<TabKey | undefined>(initialTab);
+
+  if (total === 0) return null;
+
+  const panelId = `sources-panel-${message.id}`;
+
+  return (
+    <div className="mt-2 w-full min-w-0">
+      <button
+        type="button"
+        onClick={() => setOpen((v) => !v)}
+        aria-expanded={open}
+        aria-controls={panelId}
+        className="text-primary inline-flex items-center gap-1 text-xs font-medium"
+      >
+        {open ? <ChevronDown className="h-3 w-3" /> : <ChevronRight className="h-3 w-3" />}
+        {open
+          ? t("features.assistant.message.sources.toggle_hide")
+          : t("features.assistant.message.sources.toggle", { count: total })}
+      </button>
+
+      {open && (
+        <div id={panelId} className="mt-2 w-full min-w-0">
+          <Tabs value={active} onValueChange={(v) => setActive(v as TabKey)}>
+            <TabsList>
+              {visibleTabs.map((key) => (
+                <TabsTrigger key={key} value={key}>
+                  {t(`features.assistant.message.sources.tabs.${key === "suggested" ? "suggested_questions" : key}`)}
+                  <span className="text-muted-foreground ml-1.5 text-[10px]">
+                    {key === "suggested" && suggestionsCount}
+                    {key === "references" && refsCount}
+                    {key === "citations" && citationsCount}
+                    {key === "contents" && contentsCount}
+                    {key === "users" && usersCount}
+                  </span>
+                </TabsTrigger>
+              ))}
+            </TabsList>
+
+            {suggestionsCount > 0 && (
+              <TabsContent value="suggested">
+                <SuggestedQuestionsTab questions={message.suggestedQuestions} onSelect={onSelectFollowUp} />
+              </TabsContent>
+            )}
+            {refsCount > 0 && (
+              <TabsContent value="references">
+                <ReferencesTab references={visibleReferences} />
+              </TabsContent>
+            )}
+            {citationsCount > 0 && (
+              <TabsContent value="citations">
+                <CitationsTab citations={message.citations} sources={sources} />
+              </TabsContent>
+            )}
+            {contentsCount > 0 && (
+              <TabsContent value="contents">
+                <ContentsTab citations={message.citations} sources={sources} />
+              </TabsContent>
+            )}
+            {usersCount > 0 && (
+              <TabsContent value="users">
+                <UsersTab users={users ?? []} citations={message.citations} sources={sources} />
+              </TabsContent>
+            )}
+          </Tabs>
+        </div>
+      )}
+    </div>
+  );
+}

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

@@ -0,0 +1,29 @@
+"use client";
+
+interface Props {
+  /** 0-1 (decimal) or 0-100 (percent). Auto-detected. */
+  value: number;
+  className?: string;
+}
+
+export function RelevanceMeter({ value, className = "" }: Props) {
+  const pct = Math.max(0, Math.min(100, value <= 1 ? value * 100 : value));
+  const label = `${Math.round(pct)}%`;
+  return (
+    <div
+      role="meter"
+      aria-valuenow={Math.round(pct)}
+      aria-valuemin={0}
+      aria-valuemax={100}
+      aria-label={`Relevance ${label}`}
+      className={`bg-muted relative mx-auto flex h-5 w-20 items-center justify-center overflow-hidden rounded border ${className}`}
+    >
+      <div className="bg-accent absolute top-0 left-0 h-full" style={{ width: `${pct}%` }} />
+      <span
+        className={`relative text-xs ${pct < 40 ? "text-muted-foreground" : "text-accent-foreground font-semibold"}`}
+      >
+        {label}
+      </span>
+    </div>
+  );
+}

package/src/features/assistant-message/components/parts/__tests__/MessageSourcesPanel.spec.tsx

@@ -0,0 +1,70 @@
+import { afterAll, beforeAll, describe, expect, it, vi } from "vitest";
+import { render, screen } from "@testing-library/react";
+import { ModuleRegistry } from "../../../../../core/registry/ModuleRegistry";
+import { MessageSourcesPanel } from "../MessageSourcesPanel";
+
+const baseMessage: any = {
+  id: "m1",
+  role: "assistant",
+  content: "x",
+  references: [],
+  citations: [],
+  suggestedQuestions: [],
+};
+
+beforeAll(() => {
+  // Register a stub Order module so reference filtering by `pageUrl` succeeds in tests.
+  ModuleRegistry.register("Order" as any, { name: "orders", pageUrl: "/orders" } as any);
+});
+
+afterAll(() => {
+  // No public unregister; safe to leave the stub since other suites do not collide on this name.
+});
+
+describe("MessageSourcesPanel", () => {
+  it("renders nothing when message has no sources", () => {
+    const { container } = render(
+      <MessageSourcesPanel message={baseMessage} isLatestAssistant={false} onSelectFollowUp={vi.fn()} />,
+    );
+    expect(container).toBeEmptyDOMElement();
+  });
+
+  it("renders the toggle when at least one source exists", () => {
+    const msg = {
+      ...baseMessage,
+      references: [{ id: "r1", type: "orders", identifier: "ORD-001" }],
+    };
+    render(<MessageSourcesPanel message={msg} isLatestAssistant={false} onSelectFollowUp={vi.fn()} />);
+    // Mocked next-intl returns the translation key verbatim,
+    // so the toggle button name contains "sources.toggle".
+    expect(screen.getByRole("button", { name: /sources\.toggle/i })).toBeInTheDocument();
+  });
+
+  it("hides references whose module has no pageUrl (middle entities)", () => {
+    ModuleRegistry.register("BomItem" as any, { name: "bom-items" } as any);
+    const msg = {
+      ...baseMessage,
+      references: [{ id: "b1", type: "bom-items", identifier: "BI-1" }],
+    };
+    const { container } = render(
+      <MessageSourcesPanel message={msg} isLatestAssistant={false} onSelectFollowUp={vi.fn()} />,
+    );
+    expect(container).toBeEmptyDOMElement();
+  });
+
+  it("auto-opens with Suggested questions tab when isLatestAssistant and questions exist", () => {
+    const msg = { ...baseMessage, suggestedQuestions: ["Why?"] };
+    render(<MessageSourcesPanel message={msg} isLatestAssistant={true} onSelectFollowUp={vi.fn()} />);
+    const tab = screen.getByRole("tab", { name: /suggested/i });
+    expect(tab).toBeInTheDocument();
+    // Base UI uses data-active on the active tab/panel; aria-selected reflects active state too.
+    expect(tab.getAttribute("aria-selected")).toBe("true");
+    expect(screen.getByText("Why?")).toBeInTheDocument();
+  });
+
+  it("does not show Suggested questions tab on non-latest message", () => {
+    const msg = { ...baseMessage, suggestedQuestions: ["Why?"] };
+    render(<MessageSourcesPanel message={msg} isLatestAssistant={false} onSelectFollowUp={vi.fn()} />);
+    expect(screen.queryByRole("tab", { name: /suggested/i })).not.toBeInTheDocument();
+  });
+});