@aphrody/m3-ai 3.3.2 → 3.3.5

package/src/chatIcons.tsx

@@ -0,0 +1,105 @@
+// SPDX-License-Identifier: Apache-2.0
+// Inline Material Symbols (Outlined, weight 400) used by the chat components, so they render
+// without the Material Symbols icon font. Paths from @material-symbols/svg-400 0.47.6
+// (Google Material Symbols, Apache-2.0).
+
+import { clsx } from "clsx";
+
+const CHAT_ICON_PATHS = {
+  arrow_upward: [
+    "0 -960 960 960",
+    "M450-160v-526L202-438l-42-42 320-320 320 320-42 42-248-248v526h-60Z",
+  ],
+  auto_awesome_filled: [
+    "0 96 960 960",
+    "m772 421-43-100-104-46 104-45 43-95 43 95 104 45-104 46-43 100Zm0 595-43-96-104-45 104-45 43-101 43 101 104 45-104 45-43 96ZM333 862l-92-197-201-90 201-90 92-196 93 196 200 90-200 90-93 197Z",
+  ],
+  auto_awesome: [
+    "0 -960 960 960",
+    "m772-635-43-100-104-46 104-45 43-95 43 95 104 45-104 46-43 100Zm0 595-43-96-104-45 104-45 43-101 43 101 104 45-104 45-43 96ZM333-194l-92-197-201-90 201-90 92-196 93 196 200 90-200 90-93 197Zm0-148 48-96 98-43-98-43-48-96-47 96-99 43 99 43 47 96Zm0-139Z",
+  ],
+  call_split: [
+    "0 -960 960 960",
+    "M452-160v-306L220-698v123h-60v-225h225v60H263l249 249v331h-60Zm113-364-42-42 174-174H575v-60h225v225h-60v-123L565-524Z",
+  ],
+  check: ["0 -960 960 960", "M378-246 154-470l43-43 181 181 384-384 43 43-427 427Z"],
+  cloud_off: [
+    "0 -960 960 960",
+    "M818-56 703-171H248q-88 0-148-59T40-377q0-80 50.5-134T217-577q2-14 6.5-31.5T236-640L70-806l42-42L861-99l-43 43ZM248-231h397L285-591q-11 15-14.5 34t-3.5 37h-19q-62 0-105 39.5t-43 101q0 61.5 43 105T248-231Zm216-181Zm390 210-47-47q25-17 39-38t14-50q0-43-31-73.5T755-441h-67v-81q0-88-61-147.5T478.47-729q-28.47 0-60.97 9T358-691l-42-42q36-29 77.5-42.5T478-789q111 0 190.5 79T748-520v21q72-1 122 45t50 117q0 35-16.5 73.5T854-202ZM583-470Z",
+  ],
+  content_copy: [
+    "0 -960 960 960",
+    "M300-200q-24 0-42-18t-18-42v-560q0-24 18-42t42-18h440q24 0 42 18t18 42v560q0 24-18 42t-42 18H300Zm0-60h440v-560H300v560ZM180-80q-24 0-42-18t-18-42v-620h60v620h500v60H180Zm120-180v-560 560Z",
+  ],
+  delete: [
+    "0 -960 960 960",
+    "M261-120q-24.75 0-42.37-17.63Q201-155.25 201-180v-570h-41v-60h188v-30h264v30h188v60h-41v570q0 24-18 42t-42 18H261Zm438-630H261v570h438v-570ZM367-266h60v-399h-60v399Zm166 0h60v-399h-60v399ZM261-750v570-570Z",
+  ],
+  edit: [
+    "0 -960 960 960",
+    "M180-180h44l472-471-44-44-472 471v44Zm-60 60v-128l575-574q8-8 19-12.5t23-4.5q11 0 22 4.5t20 12.5l44 44q9 9 13 20t4 22q0 11-4.5 22.5T823-694L248-120H120Zm659-617-41-41 41 41Zm-105 64-22-22 44 44-22-22Z",
+  ],
+  edit_square: [
+    "0 -960 960 960",
+    "M180-120q-24 0-42-18t-18-42v-600q0-24 18-42t42-18h405l-60 60H180v600h600v-348l60-60v408q0 24-18 42t-42 18H180Zm300-360ZM360-360v-170l382-382q9-9 20-13t22-4q11 0 22.32 4.5Q817.63-920 827-911l83 84q8.61 8.96 13.3 19.78 4.7 10.83 4.7 22.02 0 11.2-4.5 22.7T910-742L530-360H360Zm508-425-84-84 84 84ZM420-420h85l253-253-43-42-43-42-252 251v86Zm295-295-43-42 43 42 43 42-43-42Z",
+  ],
+  expand_more: ["0 -960 960 960", "M480-345 240-585l43-43 197 198 197-197 43 43-240 239Z"],
+  info: [
+    "0 -960 960 960",
+    "M453-280h60v-240h-60v240Zm50.5-323.2q9.5-9.2 9.5-22.8 0-14.45-9.48-24.22-9.48-9.78-23.5-9.78t-23.52 9.78Q447-640.45 447-626q0 13.6 9.48 22.8 9.48 9.2 23.5 9.2t23.52-9.2ZM480.27-80q-82.74 0-155.5-31.5Q252-143 197.5-197.5t-86-127.34Q80-397.68 80-480.5t31.5-155.66Q143-709 197.5-763t127.34-85.5Q397.68-880 480.5-880t155.66 31.5Q709-817 763-763t85.5 127Q880-563 880-480.27q0 82.74-31.5 155.5Q817-252 763-197.68q-54 54.31-127 86Q563-80 480.27-80Zm.23-60Q622-140 721-239.5t99-241Q820-622 721.19-721T480-820q-141 0-240.5 98.81T140-480q0 141 99.5 240.5t241 99.5Zm-.5-340Z",
+  ],
+  mic: [
+    "0 -960 960 960",
+    "M408-453.92q-29-30.91-29-75.08v-251q0-41.67 29.44-70.83Q437.88-880 479.94-880t71.56 29.17Q581-821.67 581-780v251q0 44.17-29 75.08Q523-423 480-423t-72-30.92ZM480-651Zm-30 531v-136q-106-11-178-89t-72-184h60q0 91 64.29 153t155.5 62q91.21 0 155.71-62Q700-438 700-529h60q0 106-72 184t-178 89v136h-60Zm59.5-376.5Q521-510 521-529v-251q0-17-11.79-28.5T480-820q-17.42 0-29.21 11.5T439-780v251q0 19 11.5 32.5T480-483q18 0 29.5-13.5Z",
+  ],
+  open_in_new: [
+    "0 -960 960 960",
+    "M180-120q-24 0-42-18t-18-42v-600q0-24 18-42t42-18h279v60H180v600h600v-279h60v279q0 24-18 42t-42 18H180Zm202-219-42-43 398-398H519v-60h321v321h-60v-218L382-339Z",
+  ],
+  refresh: [
+    "0 -960 960 960",
+    "M480-160q-133 0-226.5-93.5T160-480q0-133 93.5-226.5T480-800q85 0 149 34.5T740-671v-129h60v254H546v-60h168q-38-60-97-97t-137-37q-109 0-184.5 75.5T220-480q0 109 75.5 184.5T480-220q83 0 152-47.5T728-393h62q-29 105-115 169t-195 64Z",
+  ],
+  search: [
+    "0 -960 960 960",
+    "M796-121 533-384q-30 26-70 40.5T378-329q-108 0-183-75t-75-181q0-106 75-181t182-75q106 0 180.5 75T632-585q0 43-14 83t-42 75l264 262-44 44ZM377-389q81 0 138-57.5T572-585q0-81-57-138.5T377-781q-82 0-139.5 57.5T180-585q0 81 57.5 138.5T377-389Z",
+  ],
+  stop_filled: ["0 -960 960 960", "M240-240v-480h480v480H240Z"],
+  stop: ["0 -960 960 960", "M300-660v360-360Zm-60 420v-480h480v480H240Zm60-60h360v-360H300v360Z"],
+  thumb_down: [
+    "0 -960 960 960",
+    "M242-840h444v512L408-40l-39-31q-6-5-9-14t-3-22v-10l45-211H103q-24 0-42-18t-18-42v-81.84q0-7.16-1.5-14.66T43-499l126-290q8.88-21.25 29.59-36.13Q219.31-840 242-840Zm384 60H229L103-481v93h373l-53 249 203-214v-427Zm0 427v-427 427Zm60 25v-60h133v-392H686v-60h193v512H686Z",
+  ],
+} as const satisfies Record<string, readonly [string, string]>;
+
+export type ChatIconName = keyof typeof CHAT_ICON_PATHS;
+
+/** Names of the bundled chat icons. */
+export const chatIconNames = Object.keys(CHAT_ICON_PATHS) as ChatIconName[];
+
+export interface ChatIconProps {
+  name: ChatIconName;
+  /** Size in px. Default 24. */
+  size?: number;
+  className?: string;
+}
+
+/** A decorative inline SVG Material Symbol painted with `currentColor`. */
+export function ChatIcon({ name, size = 24, className }: ChatIconProps) {
+  const [viewBox, d] = CHAT_ICON_PATHS[name];
+  return (
+    <svg
+      xmlns="http://www.w3.org/2000/svg"
+      viewBox={viewBox}
+      width={size}
+      height={size}
+      fill="currentColor"
+      aria-hidden="true"
+      focusable="false"
+      data-m3-icon={name}
+      className={clsx("m3-icon shrink-0", className)}
+    >
+      <path d={d} />
+    </svg>
+  );
+}

package/src/chatLabels.ts

@@ -0,0 +1,243 @@
+// SPDX-License-Identifier: Apache-2.0
+// Injectable labels of the chat surface: every visible string (aria-label included) of the chat
+// components comes from this dictionary. French, English and Japanese are complete; a partial
+// dictionary falls back key by key on the English defaults.
+
+/** Every visible string of the chat components. `{name}` placeholders go through `formatLabel`. */
+export interface ChatLabels {
+  // Composer
+  composerPlaceholder: string;
+  send: string;
+  stop: string;
+  openVoice: string;
+  projects: string;
+  // Model selector
+  models: string;
+  selectModel: string;
+  searchModels: string;
+  noModels: string;
+  /** `{count}`: context window, already formatted. */
+  contextTokens: string;
+  // Message actions
+  copyMessage: string;
+  copyStreamingMessage: string;
+  dislike: string;
+  fork: string;
+  assistantThinking: string;
+  // Code blocks
+  copy: string;
+  copyCode: string;
+  copied: string;
+  // Conversations
+  conversations: string;
+  newConversation: string;
+  searchConversations: string;
+  noConversations: string;
+  noSearchResults: string;
+  untitledConversation: string;
+  renameConversation: string;
+  deleteConversation: string;
+  // Model state
+  modelUnavailable: string;
+  modelDownloading: string;
+  modelLoading: string;
+  /** `{percent}`: integer 0..100. */
+  progressPercent: string;
+  retry: string;
+  // Citations and refusal
+  sources: string;
+  /** `{n}`: citation number. */
+  citation: string;
+  openSource: string;
+  refusalTitle: string;
+  refusalBody: string;
+  // Memory
+  memory: string;
+  memoryEmpty: string;
+  memoryLoading: string;
+  deleteMemory: string;
+  clearMemory: string;
+  clearMemoryConfirm: string;
+  confirm: string;
+  cancel: string;
+  // Generic
+  loading: string;
+  errorGeneric: string;
+}
+
+/** English labels: the fallback of every key. */
+export const chatLabelsEn: ChatLabels = {
+  composerPlaceholder: "Ask something...",
+  send: "Send",
+  stop: "Stop",
+  openVoice: "Open Voice Input",
+  projects: "Projects",
+  models: "Models",
+  selectModel: "Select model...",
+  searchModels: "Search models...",
+  noModels: "No models found",
+  contextTokens: "{count} tokens",
+  copyMessage: "Copy Message",
+  copyStreamingMessage: "Copy Streaming Message",
+  dislike: "Dislike",
+  fork: "Fork",
+  assistantThinking: "Thinking",
+  copy: "Copy",
+  copyCode: "Copy code",
+  copied: "Copied!",
+  conversations: "Conversations",
+  newConversation: "New conversation",
+  searchConversations: "Search conversations",
+  noConversations: "No conversations yet",
+  noSearchResults: "No matching conversation",
+  untitledConversation: "Untitled conversation",
+  renameConversation: "Rename conversation",
+  deleteConversation: "Delete conversation",
+  modelUnavailable: "Model unavailable",
+  modelDownloading: "Downloading the model",
+  modelLoading: "Loading the model",
+  progressPercent: "{percent}%",
+  retry: "Retry",
+  sources: "Sources",
+  citation: "Source {n}",
+  openSource: "Open source",
+  refusalTitle: "Not established in the sources",
+  refusalBody: "The available sources do not support an answer to this question.",
+  memory: "Memory",
+  memoryEmpty: "No memories saved",
+  memoryLoading: "Loading memories",
+  deleteMemory: "Delete memory",
+  clearMemory: "Clear all memories",
+  clearMemoryConfirm: "Delete every saved memory? This cannot be undone.",
+  confirm: "Confirm",
+  cancel: "Cancel",
+  loading: "Loading",
+  errorGeneric: "Something went wrong",
+};
+
+/** French labels. */
+export const chatLabelsFr: ChatLabels = {
+  composerPlaceholder: "Posez une question...",
+  send: "Envoyer",
+  stop: "Arrêter",
+  openVoice: "Saisie vocale",
+  projects: "Projets",
+  models: "Modèles",
+  selectModel: "Choisir un modèle...",
+  searchModels: "Rechercher un modèle...",
+  noModels: "Aucun modèle trouvé",
+  contextTokens: "{count} jetons",
+  copyMessage: "Copier le message",
+  copyStreamingMessage: "Copier le message en cours",
+  dislike: "Je n'aime pas",
+  fork: "Bifurquer à partir de ce tour",
+  assistantThinking: "Réflexion",
+  copy: "Copier",
+  copyCode: "Copier le code",
+  copied: "Copié !",
+  conversations: "Conversations",
+  newConversation: "Nouvelle conversation",
+  searchConversations: "Rechercher une conversation",
+  noConversations: "Aucune conversation pour l'instant",
+  noSearchResults: "Aucune conversation ne correspond",
+  untitledConversation: "Conversation sans titre",
+  renameConversation: "Renommer la conversation",
+  deleteConversation: "Supprimer la conversation",
+  modelUnavailable: "Modèle indisponible",
+  modelDownloading: "Téléchargement du modèle",
+  modelLoading: "Chargement du modèle",
+  progressPercent: "{percent} %",
+  retry: "Réessayer",
+  sources: "Sources",
+  citation: "Source {n}",
+  openSource: "Ouvrir la source",
+  refusalTitle: "Non établi dans les sources",
+  refusalBody: "Les sources disponibles ne permettent pas de répondre à cette question.",
+  memory: "Mémoire",
+  memoryEmpty: "Aucun souvenir enregistré",
+  memoryLoading: "Chargement des souvenirs",
+  deleteMemory: "Supprimer ce souvenir",
+  clearMemory: "Effacer tous les souvenirs",
+  clearMemoryConfirm: "Supprimer tous les souvenirs enregistrés ? Cette action est définitive.",
+  confirm: "Confirmer",
+  cancel: "Annuler",
+  loading: "Chargement",
+  errorGeneric: "Une erreur est survenue",
+};
+
+/** Japanese labels. */
+export const chatLabelsJa: ChatLabels = {
+  composerPlaceholder: "質問を入力...",
+  send: "送信",
+  stop: "停止",
+  openVoice: "音声入力",
+  projects: "プロジェクト",
+  models: "モデル",
+  selectModel: "モデルを選択...",
+  searchModels: "モデルを検索...",
+  noModels: "モデルが見つかりません",
+  contextTokens: "{count} トークン",
+  copyMessage: "メッセージをコピー",
+  copyStreamingMessage: "生成中のメッセージをコピー",
+  dislike: "低評価",
+  fork: "このターンから分岐",
+  assistantThinking: "思考中",
+  copy: "コピー",
+  copyCode: "コードをコピー",
+  copied: "コピーしました",
+  conversations: "会話",
+  newConversation: "新しい会話",
+  searchConversations: "会話を検索",
+  noConversations: "まだ会話はありません",
+  noSearchResults: "一致する会話はありません",
+  untitledConversation: "無題の会話",
+  renameConversation: "会話の名前を変更",
+  deleteConversation: "会話を削除",
+  modelUnavailable: "モデルを利用できません",
+  modelDownloading: "モデルをダウンロード中",
+  modelLoading: "モデルを読み込み中",
+  progressPercent: "{percent}%",
+  retry: "再試行",
+  sources: "出典",
+  citation: "出典 {n}",
+  openSource: "出典を開く",
+  refusalTitle: "出典では確認できません",
+  refusalBody: "利用できる出典では、この質問に回答できません。",
+  memory: "メモリー",
+  memoryEmpty: "保存されたメモリーはありません",
+  memoryLoading: "メモリーを読み込み中",
+  deleteMemory: "メモリーを削除",
+  clearMemory: "すべてのメモリーを消去",
+  clearMemoryConfirm: "保存されたすべてのメモリーを削除しますか？この操作は元に戻せません。",
+  confirm: "確認",
+  cancel: "キャンセル",
+  loading: "読み込み中",
+  errorGeneric: "エラーが発生しました",
+};
+
+/** The fallback dictionary (English). */
+export const defaultChatLabels: ChatLabels = chatLabelsEn;
+
+/** The complete dictionaries by language tag. */
+export const chatLabelsByLang = { fr: chatLabelsFr, en: chatLabelsEn, ja: chatLabelsJa } as const;
+
+/** Complete a partial dictionary with the defaults; empty strings fall back too. */
+export function resolveChatLabels(
+  partial?: Partial<ChatLabels>,
+  base: ChatLabels = defaultChatLabels,
+): ChatLabels {
+  if (!partial) return base;
+  const out = { ...base };
+  for (const key of Object.keys(partial) as (keyof ChatLabels)[]) {
+    const value = partial[key];
+    if (typeof value === "string" && value.length > 0) out[key] = value;
+  }
+  return out;
+}
+
+/** Replace `{name}` placeholders of a label. Unknown placeholders stay as written. */
+export function formatLabel(template: string, values: Record<string, string | number>): string {
+  return template.replace(/\{(\w+)\}/g, (match, name: string) =>
+    name in values ? String(values[name]) : match,
+  );
+}

package/src/citations.tsx

@@ -0,0 +1,286 @@
+// SPDX-License-Identifier: Apache-2.0
+// Grounded answers: `[n]` markers rendered as citation chips, the numbered source list, and the
+// refusal notice of a backend that declined to answer outside its sources.
+
+"use client";
+
+import { clsx } from "clsx";
+import { useMemo } from "react";
+import type { Components } from "react-markdown";
+
+import { type ChatLabels, formatLabel, resolveChatLabels } from "./chatLabels";
+import { ChatIcon } from "./chatIcons";
+import { focusRing } from "./internal";
+import { Markdown, type MarkdownLinkHandler, externalLinkProps, isExternalHref } from "./Markdown";
+
+/** One numbered passage an answer cites (`citations` of a grounded chat response). */
+export interface Citation {
+  /** Marker number used in the text as `[n]`. */
+  n: number;
+  id?: string;
+  title: string;
+  url?: string;
+  sourceId?: string;
+}
+
+const CITATION_HREF = "#citation-";
+const CODE_SPANS = /(```[\s\S]*?```|`[^`\n]*`)/;
+const MARKER = /(?<![\]\\!])\[(\d{1,4})\](?!\()/g;
+
+/**
+ * Rewrite the `[n]` markers of `content` whose number is cited into markdown links
+ * `[[n]](#citation-n)`. Code spans and fenced blocks are left untouched, as are markers
+ * without a matching citation.
+ */
+export function linkCitationMarkers(content: string, citations: readonly Citation[]): string {
+  if (citations.length === 0) return content;
+  const known = new Set(citations.map((citation) => citation.n));
+  return content
+    .split(CODE_SPANS)
+    .map((part, index) =>
+      index % 2 === 1
+        ? part
+        : part.replace(MARKER, (match, digits: string) =>
+            known.has(Number(digits)) ? `[\\[${digits}\\]](${CITATION_HREF}${digits})` : match,
+          ),
+    )
+    .join("");
+}
+
+/** The numbers cited in `content`, in order of first appearance. */
+export function citedNumbers(content: string): number[] {
+  const seen: number[] = [];
+  for (const part of content.split(CODE_SPANS).filter((_, index) => index % 2 === 0)) {
+    for (const match of part.matchAll(MARKER)) {
+      const n = Number(match[1]);
+      if (!seen.includes(n)) seen.push(n);
+    }
+  }
+  return seen;
+}
+
+export interface CitationChipProps {
+  citation: Citation;
+  labels?: Partial<ChatLabels>;
+  onSelect?: (citation: Citation) => void;
+  className?: string;
+}
+
+/** Inline citation marker: a dense M3 assist chip showing `n`, labelled with the source title. */
+export function CitationChip({ citation, labels, onSelect, className }: CitationChipProps) {
+  const l = resolveChatLabels(labels);
+  const label = `${formatLabel(l.citation, { n: citation.n })}: ${citation.title}`;
+  const chipClass = clsx(
+    "mx-0.5 inline-flex h-5 min-w-5 items-center justify-center rounded-small px-1 align-baseline",
+    "bg-secondary-container text-label-small text-on-secondary-container no-underline",
+    "transition-colors duration-200 ease-standard hover:bg-secondary-container/80",
+    focusRing,
+    className,
+  );
+  if (!onSelect && citation.url) {
+    return (
+      <a
+        href={citation.url}
+        target="_blank"
+        rel="noreferrer noopener"
+        className={chipClass}
+        aria-label={label}
+        title={citation.title}
+      >
+        {citation.n}
+      </a>
+    );
+  }
+  return (
+    <button
+      type="button"
+      className={chipClass}
+      aria-label={label}
+      title={citation.title}
+      onClick={() => onSelect?.(citation)}
+    >
+      {citation.n}
+    </button>
+  );
+}
+
+/** Markdown overrides of `CitedMarkdown`: citation links become chips, other links stay safe. */
+function citationComponents(
+  citations: readonly Citation[],
+  labels: Partial<ChatLabels> | undefined,
+  onCitationSelect: ((citation: Citation) => void) | undefined,
+  onLinkClick: MarkdownLinkHandler | undefined,
+): Components {
+  const byNumber = new Map(citations.map((citation) => [citation.n, citation]));
+  return {
+    a: ({ node: _node, href, children, onClick, ...props }) => {
+      if (href?.startsWith(CITATION_HREF)) {
+        const citation = byNumber.get(Number(href.slice(CITATION_HREF.length)));
+        if (citation)
+          return <CitationChip citation={citation} labels={labels} onSelect={onCitationSelect} />;
+      }
+      return (
+        <a
+          href={href}
+          {...(isExternalHref(href) ? externalLinkProps : {})}
+          onClick={(event) => {
+            onClick?.(event);
+            if (href) onLinkClick?.(href, event);
+          }}
+          className={clsx(
+            "rounded-extra-small text-primary underline underline-offset-2 hover:decoration-2",
+            focusRing,
+          )}
+          {...props}
+        >
+          {children}
+        </a>
+      );
+    },
+  };
+}
+
+export interface CitedMarkdownProps {
+  content: string;
+  citations: readonly Citation[];
+  labels?: Partial<ChatLabels>;
+  /** Called when a marker is activated; without it, markers with a `url` open it. */
+  onCitationSelect?: (citation: Citation) => void;
+  /** Activation of an ordinary link (not a citation marker); see `Markdown.onLinkClick`. */
+  onLinkClick?: MarkdownLinkHandler;
+  size?: "small" | "medium" | "large";
+  className?: string;
+}
+
+/** Markdown whose `[n]` markers become citation chips. */
+export function CitedMarkdown({
+  content,
+  citations,
+  labels,
+  onCitationSelect,
+  onLinkClick,
+  size = "large",
+  className,
+}: CitedMarkdownProps) {
+  const components = useMemo(
+    () => citationComponents(citations, labels, onCitationSelect, onLinkClick),
+    [citations, labels, onCitationSelect, onLinkClick],
+  );
+  return (
+    <Markdown
+      content={linkCitationMarkers(content, citations)}
+      components={components}
+      labels={labels}
+      size={size}
+      className={className}
+    />
+  );
+}
+
+export interface CitationListProps {
+  citations: readonly Citation[];
+  labels?: Partial<ChatLabels>;
+  onSelect?: (citation: Citation) => void;
+  className?: string;
+}
+
+/** The numbered sources of an answer, as an M3 list on `surface-container-low`. */
+export function CitationList({ citations, labels, onSelect, className }: CitationListProps) {
+  if (citations.length === 0) return null;
+  const l = resolveChatLabels(labels);
+  const sorted = [...citations];
+  sorted.sort((a, b) => a.n - b.n);
+  return (
+    <section
+      aria-label={l.sources}
+      className={clsx(
+        "m3-citation-list mt-2 rounded-medium bg-surface-container-low py-2",
+        className,
+      )}
+    >
+      <h3 className="px-4 pb-1 text-label-large text-on-surface-variant">{l.sources}</h3>
+      <ol className="m-0 list-none p-0">
+        {sorted.map((citation) => {
+          const body = (
+            <>
+              <span className="flex size-6 shrink-0 items-center justify-center rounded-small bg-secondary-container text-label-small text-on-secondary-container">
+                {citation.n}
+              </span>
+              <span className="min-w-0 flex-1 truncate text-body-medium text-on-surface">
+                {citation.title}
+              </span>
+              {citation.url || onSelect ? (
+                <ChatIcon name="open_in_new" size={18} className="text-on-surface-variant" />
+              ) : null}
+            </>
+          );
+          const rowClass = clsx(
+            "flex min-h-12 w-full items-center gap-3 px-4 py-1 text-left",
+            "transition-colors duration-200 ease-standard hover:bg-on-surface/8",
+            focusRing,
+            "focus-visible:outline-offset-[-3px]",
+          );
+          const name = `${formatLabel(l.citation, { n: citation.n })}: ${citation.title}`;
+          return (
+            <li
+              key={`${citation.n}-${citation.id ?? citation.title}`}
+              id={`citation-${citation.n}`}
+            >
+              {onSelect ? (
+                <button
+                  type="button"
+                  className={rowClass}
+                  aria-label={name}
+                  onClick={() => onSelect(citation)}
+                >
+                  {body}
+                </button>
+              ) : citation.url ? (
+                <a
+                  href={citation.url}
+                  target="_blank"
+                  rel="noreferrer noopener"
+                  className={rowClass}
+                  aria-label={`${name} (${l.openSource})`}
+                >
+                  {body}
+                </a>
+              ) : (
+                <div className="flex min-h-12 items-center gap-3 px-4 py-1">{body}</div>
+              )}
+            </li>
+          );
+        })}
+      </ol>
+    </section>
+  );
+}
+
+export interface RefusalNoticeProps {
+  labels?: Partial<ChatLabels>;
+  /** Backend explanation, shown under the title instead of the generic body. */
+  detail?: string;
+  className?: string;
+}
+
+/** `refusal: true`: the answer is not established in the sources (M3 tonal note, not an error). */
+export function RefusalNotice({ labels, detail, className }: RefusalNoticeProps) {
+  const l = resolveChatLabels(labels);
+  return (
+    <div
+      role="note"
+      className={clsx(
+        "m3-refusal-notice flex items-start gap-3 rounded-medium bg-surface-container-high px-4 py-3",
+        className,
+      )}
+    >
+      <ChatIcon name="info" size={20} className="mt-0.5 text-on-surface-variant" />
+      <div className="min-w-0">
+        <p className="m-0 text-title-small text-on-surface">{l.refusalTitle}</p>
+        <p className="m-0 mt-0.5 text-body-medium text-on-surface-variant">
+          {detail || l.refusalBody}
+        </p>
+      </div>
+    </div>
+  );
+}