@aleph-alpha/chat-kit 3.1.3 → 3.3.0

package/dist/{useChatKitLabels-Ctz1dHpx.js → useChatKitLabels-BM2I7-9o.js}

@@ -28468,6 +28468,100 @@ function rehypeStringify(options) {
     return toHtml(tree, settings);
   }
 }
+const PLACEHOLDER_PREFIX = "PH_";
+const PLACEHOLDER_SUFFIX = "";
+const PLACEHOLDER_RE = /\uE000PH_(\d+)\uE000/g;
+const FENCE_START_RE = /^[ \t]{0,3}(`{3,}|~{3,})/;
+const INLINE_CODE_RE = /`[^`\n]+`/g;
+const LATEX_BLOCK_RE = /\\\[([\s\S]+?)\\\]/g;
+const LATEX_INLINE_RE = /\\\(([^\n]+?)\\\)/g;
+const SINGLE_LINE_DOUBLE_DOLLAR_RE = /\$\$([^\n$]+?)\$\$/g;
+function isClosingFence(line, fenceChar, minLen) {
+  let i = 0;
+  let indent2 = 0;
+  while (i < line.length && (line[i] === " " || line[i] === "	") && indent2 < 4) {
+    indent2++;
+    i++;
+  }
+  if (indent2 >= 4) return false;
+  let runLen = 0;
+  while (i < line.length && line[i] === fenceChar) {
+    runLen++;
+    i++;
+  }
+  if (runLen < minLen) return false;
+  while (i < line.length) {
+    if (line[i] !== " " && line[i] !== "	") return false;
+    i++;
+  }
+  return true;
+}
+function protectFencedCode(input, stash) {
+  const lines = input.split("\n");
+  const out = [];
+  let i = 0;
+  while (i < lines.length) {
+    const match = FENCE_START_RE.exec(lines[i]);
+    if (match) {
+      const fence = match[1];
+      const fenceChar = fence[0];
+      const minLen = fence.length;
+      const block = [lines[i]];
+      i++;
+      while (i < lines.length) {
+        const current = lines[i];
+        block.push(current);
+        i++;
+        if (isClosingFence(current, fenceChar, minLen)) break;
+      }
+      out.push(stash(block.join("\n")));
+    } else {
+      out.push(lines[i]);
+      i++;
+    }
+  }
+  return out.join("\n");
+}
+function normalizeMathDelimiters(input) {
+  if (!input) return input;
+  const placeholders = [];
+  const stash = (value) => {
+    const id = placeholders.length;
+    placeholders.push(value);
+    return `${PLACEHOLDER_PREFIX}${id}${PLACEHOLDER_SUFFIX}`;
+  };
+  let s2 = protectFencedCode(input, stash);
+  s2 = s2.replace(INLINE_CODE_RE, stash);
+  s2 = s2.replace(
+    LATEX_BLOCK_RE,
+    (_m, body2) => `
+
+$$
+${body2.trim()}
+$$
+
+`
+  );
+  s2 = s2.replace(LATEX_INLINE_RE, (_m, body2) => `$${body2.trim()}$`);
+  s2 = s2.replace(
+    SINGLE_LINE_DOUBLE_DOLLAR_RE,
+    (_m, body2) => `
+
+$$
+${body2.trim()}
+$$
+
+`
+  );
+  s2 = s2.replace(PLACEHOLDER_RE, (_m, id) => placeholders[Number(id)]);
+  return s2;
+}
+const remarkNormalizeMath = function() {
+  const processor = this;
+  const originalParser = processor.parser;
+  if (typeof originalParser !== "function") return;
+  processor.parser = (document2, file) => originalParser(normalizeMathDelimiters(document2), file);
+};
 const KATEX_MATHML_TAGS = [
   "math",
   "semantics",
@@ -28527,9 +28621,9 @@ const SANITIZE_CONFIG = {
   ADD_ATTR: [...KATEX_MATHML_ATTRS]
 };
 function buildProcessor(plugins) {
-  let proc = unified().use(remarkParse).use(remarkGfm).use(remarkMath);
-  for (const plugin of plugins) {
-    proc = proc.use(plugin);
+  let proc = unified().use(remarkParse).use(remarkNormalizeMath).use(remarkGfm).use(remarkMath);
+  if (plugins.length > 0) {
+    proc = proc.use(plugins);
   }
   return proc.use(remarkRehype).use(rehypeKatex).use(rehypeStringify);
 }
@@ -28556,6 +28650,30 @@ function useMarkdownParser(source, plugins) {
   });
   return { html: html2 };
 }
+const CITATION_RE = /\[(\d+)\]/g;
+const remarkCitations = (options = {}) => {
+  const { indices } = options;
+  return (tree) => {
+    findAndReplace(tree, [
+      CITATION_RE,
+      (_match, digits) => {
+        const index2 = Number(digits);
+        if (index2 < 1) return false;
+        if (indices && !indices.has(index2)) return false;
+        return {
+          type: "citationReference",
+          data: {
+            hName: "span",
+            // Use the literal attribute name so the placeholder contract matches
+            // the renderer's `getAttribute('data-citation-index')` lookup exactly.
+            hProperties: { "data-citation-index": index2 },
+            hChildren: [{ type: "text", value: String(index2) }]
+          }
+        };
+      }
+    ]);
+  };
+};
 const defaultChatKitLabels = {
   agentAvatarAlt: "Agent avatar",
   agentLoadingAvatarAlt: "Agent loading",
@@ -28580,6 +28698,8 @@ const defaultChatKitLabels = {
   modelSelectorListAriaLabel: "Models",
   modelSelectorPlaceholder: "Select model",
   markdownTableLabel: "Table",
+  citationOpenSource: "Open source",
+  citationSourceLabel: "Source",
   historyItemUntitled: "Untitled conversation",
   historyItemActionAriaLabel: "Conversation options",
   historyItemEditAction: "Edit",
@@ -28602,7 +28722,10 @@ function useChatKitLabels() {
 export {
   CHAT_KIT_LABELS as C,
   useMarkdownParser as a,
+  remarkNormalizeMath as b,
   defaultChatKitLabels as d,
+  normalizeMathDelimiters as n,
   provideChatKitLabels as p,
+  remarkCitations as r,
   useChatKitLabels as u
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aleph-alpha/chat-kit",
-  "version": "3.1.3",
+  "version": "3.3.0",
   "description": "Chat kit package for building chat interfaces with Vue",
   "type": "module",
   "main": "./dist/index.js",
@@ -68,6 +68,7 @@
     "@aleph-alpha/ui-library": "^2.8.3",
     "dompurify": "^3.3.2",
     "katex": "^0.17.0",
+    "mdast-util-find-and-replace": "^3.0.2",
     "rehype-katex": "^7.0.1",
     "rehype-stringify": "^10.0.1",
     "remark-gfm": "^4.0.1",
@@ -77,7 +78,6 @@
     "unified": "^11.0.5"
   },
   "devDependencies": {
-    "@aleph-alpha/config-css": "^1.2.0",
     "@storybook/addon-a11y": "10.2.17",
     "@storybook/addon-docs": "10.2.17",
     "@storybook/addon-themes": "10.2.17",
@@ -85,6 +85,7 @@
     "@testing-library/jest-dom": "6.9.1",
     "@testing-library/vue": "8.1.0",
     "@types/dompurify": "^3.2.0",
+    "@types/mdast": "^4.0.4",
     "@types/node": "^25.1.0",
     "@unocss/preset-wind4": "^66.6.2",
     "@unocss/reset": "^66.6.2",
@@ -101,7 +102,9 @@
     "vitest": "3.2.6",
     "vue": "^3.5.27",
     "vue-tsc": "^3.2.4",
-    "@aleph-alpha/tsconfig-frontend": "0.7.0"
+    "@aleph-alpha/tsconfig-frontend": "0.7.0",
+    "@aleph-alpha/prettier-config-frontend": "2.1.0",
+    "@aleph-alpha/eslint-config-frontend": "0.7.0"
   },
   "scripts": {
     "build": "vite build && vue-tsc --project tsconfig.build.json --declaration --emitDeclarationOnly --outDir dist",

package/src/adapters/responses-api.spec.ts

@@ -441,6 +441,162 @@ describe('responsesToTree', () => {
     }
   });
 
+  it('merges a tool-loop continuation (response with no user input) into the same assistant turn', () => {
+    // One user turn that runs a multi-step tool loop is persisted as several
+    // chained responses: the first carries the user input, each follow-up
+    // carries a tool result (no user input). They are one assistant turn and
+    // must render as one message with a single thinking trail (SPHER-5147).
+    const tree = responsesToTree([
+      makeResponse({
+        id: 'r1',
+        request_input: [userInput('Compare Tokyo and Delhi populations')],
+        output: [
+          reasoningOutput('rs-1', 'search for Tokyo'),
+          toolOutput({ id: 'fc-1', type: 'function_call', name: 'search' }),
+        ],
+      }),
+      makeResponse({
+        id: 'r2',
+        previous_response_id: 'r1',
+        // Tool-result continuation — no user input on the wire.
+        request_input: [],
+        completed_at: 1_777_456_999,
+        output: [
+          reasoningOutput('rs-2', 'now search for Delhi'),
+          toolOutput({ id: 'fc-2', type: 'function_call', name: 'search' }),
+          assistantOutput('msg-final', 'Tokyo is larger'),
+        ],
+      }),
+    ]);
+
+    // Exactly one user node and one (merged) assistant node — not two
+    // assistant bubbles. r1 has no message output, so its assistant node id
+    // falls back to `assistant-r1`.
+    expect(Object.keys(tree.nodes)).toHaveLength(2);
+    expect(tree.nodes['msg-final']).toBeUndefined();
+
+    const assistant = tree.nodes['assistant-r1']!;
+    expect(assistant.role).toBe('assistant');
+    expect(tree.nodes['user-r1-0']!.childrenIds).toEqual(['assistant-r1']);
+    // Reasoning + tool from both round-trips, in wire order, then final text.
+    expect(assistant.content.map((c) => c.type)).toEqual([
+      'reasoning',
+      'tool',
+      'reasoning',
+      'tool',
+      'text',
+    ]);
+    // responseId stays the originating round-trip (the one that opened the
+    // turn), preserving the documented "originating StoredResponse.id" stamp.
+    expect(assistant.metadata.responseId).toBe('r1');
+    // createdAt advances to the latest folded round-trip so it is never
+    // stamped earlier than content it now holds.
+    expect(assistant.createdAt).toEqual(new Date(1_777_456_999 * 1000));
+  });
+
+  it('merges a tool-loop continuation in a later turn, leaving earlier turns intact', () => {
+    // The fix must work for any turn, not just the first: a simple turn,
+    // followed by a second turn that runs a tool loop. The second turn's
+    // continuation folds into its own assistant node; turn one is untouched.
+    const tree = responsesToTree([
+      makeResponse({
+        id: 'r1',
+        request_input: [userInput('Hi')],
+        output: [assistantOutput('msg-a1', 'Hello!')],
+      }),
+      makeResponse({
+        id: 'r2',
+        previous_response_id: 'r1',
+        request_input: [userInput('Now compare Tokyo and Delhi')],
+        output: [
+          reasoningOutput('rs-2', 'search Tokyo'),
+          toolOutput({ id: 'fc-2', type: 'function_call', name: 'search' }),
+        ],
+      }),
+      makeResponse({
+        id: 'r3',
+        previous_response_id: 'r2',
+        request_input: [], // tool-result continuation of turn two
+        output: [
+          reasoningOutput('rs-3', 'search Delhi'),
+          toolOutput({ id: 'fc-3', type: 'function_call', name: 'search' }),
+          assistantOutput('msg-a3', 'Tokyo is larger'),
+        ],
+      }),
+    ]);
+
+    // Turn one: untouched, single reply.
+    const a1 = tree.nodes['msg-a1']!;
+    expect(getText(a1.content)).toBe('Hello!');
+    expect(a1.parentId).toBe('user-r1-0');
+
+    // Turn two: its continuation (r3) merged into turn two's assistant node
+    // (id falls back to `assistant-r2` since r2 has no message output).
+    expect(tree.nodes['msg-a3']).toBeUndefined();
+    const a2 = tree.nodes['assistant-r2']!;
+    expect(a2.parentId).toBe('user-r2-0');
+    expect(tree.nodes['user-r2-0']!.parentId).toBe('msg-a1');
+    expect(a2.content.map((c) => c.type)).toEqual([
+      'reasoning',
+      'tool',
+      'reasoning',
+      'tool',
+      'text',
+    ]);
+    // Four message nodes total: two user, two assistant (one per turn).
+    expect(Object.keys(tree.nodes)).toHaveLength(4);
+  });
+
+  it('still starts a new assistant turn when a follow-up response carries a user input', () => {
+    // Guard against over-merging: a genuine next turn (user input present)
+    // must remain its own message, not fold into the previous answer.
+    const tree = responsesToTree([
+      makeResponse({
+        id: 'r1',
+        request_input: [userInput('First')],
+        output: [assistantOutput('msg-a1', 'A1')],
+      }),
+      makeResponse({
+        id: 'r2',
+        previous_response_id: 'r1',
+        request_input: [userInput('Second')],
+        output: [assistantOutput('msg-a2', 'A2')],
+      }),
+    ]);
+
+    expect(tree.nodes['user-r2-0']!.parentId).toBe('msg-a1');
+    expect(tree.nodes['msg-a2']!.parentId).toBe('user-r2-0');
+    expect(tree.nodes['msg-a2']!.metadata.responseId).toBe('r2');
+  });
+
+  it('does not merge a response that carries a user input even when its content is empty', () => {
+    // A user-role input with empty content produces no user node, so a
+    // node-shape-only check would wrongly treat this as a continuation. The
+    // merge keys off `request_input` directly, so the assistant reply stays
+    // its own node rather than folding into the previous turn.
+    const tree = responsesToTree([
+      makeResponse({
+        id: 'r1',
+        request_input: [userInput('First')],
+        output: [assistantOutput('msg-a1', 'A1')],
+      }),
+      makeResponse({
+        id: 'r2',
+        previous_response_id: 'r1',
+        request_input: [{ role: 'user', content: '' }],
+        output: [assistantOutput('msg-a2', 'A2')],
+      }),
+    ]);
+
+    const a1 = tree.nodes['msg-a1']!;
+    const a2 = tree.nodes['msg-a2']!;
+    expect(a2).toBeDefined();
+    expect(getText(a2.content)).toBe('A2');
+    // a2 is its own node, not merged into a1's content.
+    expect(getText(a1.content)).toBe('A1');
+    expect(a2.parentId).toBe('msg-a1');
+  });
+
   it('chains the next response under a reasoning-only assistant turn', () => {
     const tree = responsesToTree([
       makeResponse({

package/src/adapters/responses-api.ts

@@ -513,6 +513,124 @@ function responseToMessageNodes(resp: StoredResponse): ResponseMessageNode[] {
   return nodes;
 }
 
+// Insert a node and wire it under `parentId`; latest child wins as the active
+// branch (surfaces the most recent sibling branch by default).
+function appendNode(
+  treeNodes: Record<string, ResponseTreeMessage>,
+  node: ResponseMessageNode,
+  parentId: string | null,
+): void {
+  treeNodes[node.id] = {
+    id: node.id,
+    parentId,
+    childrenIds: [],
+    activeChildIndex: 0,
+    role: node.role,
+    content: node.content,
+    status: 'completed',
+    createdAt: node.createdAt,
+    metadata: node.metadata,
+  };
+  if (parentId === null) return;
+  const parent = treeNodes[parentId];
+  if (!parent) return;
+  parent.childrenIds.push(node.id);
+  parent.activeChildIndex = parent.childrenIds.length - 1;
+}
+
+// A user-role input on the wire delimits a turn. Read from `request_input`
+// directly: `responseToMessageNodes` drops empty user inputs, so a node-shape
+// check could misread an empty new turn as a continuation.
+function responseHasUserInput(resp: StoredResponse): boolean {
+  return (resp.request_input ?? []).some(
+    (input) => (input as { role?: string }).role === 'user',
+  );
+}
+
+// True when `resp` continues the assistant turn anchored at `parentNode`: a
+// tool-loop round-trip (assistant-only output, no new user input) rather than a
+// new turn. The Responses API stores each round-trip as its own response, but
+// they are one turn. New turns and regeneration branches carry a user input.
+function isAssistantContinuation(
+  parentNode: ResponseTreeMessage,
+  messageNodes: ResponseMessageNode[],
+  resp: StoredResponse,
+): boolean {
+  return (
+    parentNode.role === 'assistant' &&
+    messageNodes.length > 0 &&
+    messageNodes.every((node) => node.role === 'assistant') &&
+    !responseHasUserInput(resp)
+  );
+}
+
+// Fold a continuation round-trip's output onto the turn it extends, so the turn
+// stays one message with one "thinking" trail — matching the live path;
+// otherwise the trail splits on reload (SPHER-5147). `responseId` is left as the
+// originating response, per ResponseTreeMessageMetadata's contract.
+function foldContinuation(
+  parentNode: ResponseTreeMessage,
+  messageNodes: ResponseMessageNode[],
+): void {
+  for (const node of messageNodes) {
+    parentNode.content.push(...node.content);
+    // Advance the turn's timestamp as later round-trips fold in, so it is
+    // never stamped earlier than content it now holds (consistent with the
+    // per-response `completed_at` stamp used elsewhere). Only moves forward.
+    if (node.createdAt.getTime() > parentNode.createdAt.getTime()) {
+      parentNode.createdAt = node.createdAt;
+    }
+  }
+}
+
+// Mutable accumulators threaded through the single build pass.
+interface TreeBuildState {
+  treeNodes: Record<string, ResponseTreeMessage>;
+  // For each response, the id of its last visible message — the attachment
+  // point for any future child response that chains onto it. Empty responses
+  // fall back to their parent's attachment point so the chain stays connected.
+  tailMessageByResponse: Map<string, string | null>;
+  rootMessageId: string | null;
+}
+
+// Wire one response into the tree, extending `state` in place. Tool-loop
+// continuations fold onto the turn they extend; everything else appends under
+// the chain parent resolved from `previous_response_id`.
+function linkResponse(state: TreeBuildState, resp: StoredResponse): void {
+  const { treeNodes, tailMessageByResponse } = state;
+  const parentResponseId =
+    resp.previous_response_id &&
+    tailMessageByResponse.has(resp.previous_response_id)
+      ? resp.previous_response_id
+      : null;
+  let chainParent =
+    parentResponseId !== null
+      ? (tailMessageByResponse.get(parentResponseId) ?? null)
+      : null;
+
+  const messageNodes = responseToMessageNodes(resp);
+
+  const parentNode = chainParent !== null ? treeNodes[chainParent] : null;
+  if (parentNode && isAssistantContinuation(parentNode, messageNodes, resp)) {
+    foldContinuation(parentNode, messageNodes);
+    tailMessageByResponse.set(resp.id, parentNode.id);
+    return;
+  }
+
+  let firstId: string | null = null;
+  for (const node of messageNodes) {
+    appendNode(treeNodes, node, chainParent);
+    if (firstId === null) firstId = node.id;
+    chainParent = node.id;
+  }
+
+  if (state.rootMessageId === null && firstId !== null) {
+    state.rootMessageId = firstId;
+  }
+
+  tailMessageByResponse.set(resp.id, chainParent);
+}
+
 /**
  * Convert an OpenAI Responses API list (already ordered by `created_at`
  * ascending) into a chat-kit `ConversationTree`.
@@ -535,66 +653,15 @@ export function responsesToTree(
     return { nodes: {}, rootId: null };
   }
 
-  const treeNodes: Record<string, ResponseTreeMessage> = {};
-  // For each response, the id of its last visible message — that's the
-  // attachment point for any future child response that chains onto it.
-  // Empty responses fall back to their parent's attachment point so the
-  // chain stays connected.
-  const tailMessageByResponse = new Map<string, string | null>();
-  let rootMessageId: string | null = null;
-
-  function appendNode(node: ResponseMessageNode, parentId: string | null) {
-    treeNodes[node.id] = {
-      id: node.id,
-      parentId,
-      childrenIds: [],
-      activeChildIndex: 0,
-      role: node.role,
-      content: node.content,
-      status: 'completed',
-      createdAt: node.createdAt,
-      metadata: node.metadata,
-    };
-    if (parentId !== null) {
-      const parent = treeNodes[parentId];
-      if (parent) {
-        parent.childrenIds.push(node.id);
-        // Latest insertion wins as the active branch — within a single
-        // response there's only one push, so this is a no-op there; for
-        // sibling branches it surfaces the most recent one by default.
-        parent.activeChildIndex = parent.childrenIds.length - 1;
-      }
-    }
-  }
+  const state: TreeBuildState = {
+    treeNodes: {},
+    tailMessageByResponse: new Map<string, string | null>(),
+    rootMessageId: null,
+  };
 
   for (const resp of responses) {
-    const parentResponseId =
-      resp.previous_response_id &&
-      tailMessageByResponse.has(resp.previous_response_id)
-        ? resp.previous_response_id
-        : null;
-    let chainParent =
-      parentResponseId !== null
-        ? (tailMessageByResponse.get(parentResponseId) ?? null)
-        : null;
-
-    const messageNodes = responseToMessageNodes(resp);
-    let firstId: string | null = null;
-    for (const node of messageNodes) {
-      appendNode(node, chainParent);
-      if (firstId === null) firstId = node.id;
-      chainParent = node.id;
-    }
-
-    if (rootMessageId === null && firstId !== null) {
-      rootMessageId = firstId;
-    }
-
-    // Track the attachment point for descendants. If the response had no
-    // visible messages, pass through the parent's tail so children of this
-    // response still land in the right place.
-    tailMessageByResponse.set(resp.id, chainParent);
+    linkResponse(state, resp);
   }
 
-  return { nodes: treeNodes, rootId: rootMessageId };
+  return { nodes: state.treeNodes, rootId: state.rootMessageId };
 }

package/src/components/base/CkAgentMessage/CkAgentMessage.stories.ts

@@ -1,4 +1,6 @@
 import CkAgentMessage from './CkAgentMessage.vue';
+import { CkMarkdownRenderer } from '../CkMarkdownRenderer';
+import type { CkCitationSource } from '../CkCitation';
 import type { Meta, StoryObj } from '@storybook/vue3-vite';
 
 const meta: Meta<typeof CkAgentMessage> = {
@@ -213,3 +215,113 @@ export const WithoutIcon: Story = {
   }),
   parameters: { docs: { source: { code: withoutIconTemplateSource } } },
 };
+
+const CITATIONS: CkCitationSource[] = [
+  {
+    index: 1,
+    fileName: 'Q2_Business_Plan.pdf',
+    snippet:
+      'Departments that received customized training saw a 25% higher adoption rate of the new tools compared to those with generic training.',
+    locationLabel: 'Page 3',
+    url: '/api/v1/search-stores/ss_abc/files/file_123/public-urls',
+  },
+  {
+    index: 2,
+    fileName: 'Support-Metrics-Q1.csv',
+    snippet:
+      'Ticket volume fell 18% quarter-over-quarter for the tailored-training cohorts versus the control group.',
+    locationLabel: 'Row 42',
+    url: '/api/v1/search-stores/ss_abc/files/file_456/public-urls',
+  },
+];
+
+const CITED_MARKDOWN = [
+  'Based on the internal documents, customized training drove measurably better outcomes.',
+  '',
+  'Departments with tailored sessions saw a **25% higher adoption rate** [1],',
+  'and reported markedly fewer support tickets in the first quarter [2].',
+].join('\n');
+
+const withCitationsTemplateSource = `<script setup lang="ts">
+import { CkAgentMessage, CkMarkdownRenderer } from '@aleph-alpha/chat-kit';
+import type { CkCitationSource } from '@aleph-alpha/chat-kit';
+
+// The reply body is markdown that contains inline [n] references.
+const content = [
+  'Based on the internal documents, customized training drove measurably better outcomes.',
+  '',
+  'Departments with tailored sessions saw a **25% higher adoption rate** [1],',
+  'and reported markedly fewer support tickets in the first quarter [2].',
+].join('\\n');
+
+// The numbered sources, mapped from the backend citations manifest.
+const citations: CkCitationSource[] = [
+  {
+    index: 1,
+    fileName: 'Q2_Business_Plan.pdf',
+    snippet: 'Departments that received customized training saw a 25% higher adoption rate…',
+    locationLabel: 'Page 3',
+    url: '/api/v1/search-stores/ss_abc/files/file_123/public-urls',
+  },
+  {
+    index: 2,
+    fileName: 'Support-Metrics-Q1.csv',
+    snippet: 'Ticket volume fell 18% quarter-over-quarter for the tailored-training cohorts.',
+    locationLabel: 'Row 42',
+    url: '/api/v1/search-stores/ss_abc/files/file_456/public-urls',
+  },
+];
+
+function openSource(url: string) {
+  // Source URLs are auth-proxied; the host performs the navigation.
+  window.open(url, '_blank', 'noopener');
+}
+</script>
+
+<template>
+  <CkAgentMessage>
+    <template #icon>
+      <div class="bg-core-bg-tertiary flex size-6 items-center justify-center rounded-full text-xs">
+        AI
+      </div>
+    </template>
+    <CkMarkdownRenderer
+      :content="content"
+      :citations="citations"
+      @open-source="openSource"
+    />
+  </CkAgentMessage>
+</template>`;
+
+/**
+ * An assistant reply whose body is markdown containing inline `[n]` citations,
+ * rendered through `CkMarkdownRenderer` inside the message. Each `[n]` becomes
+ * an interactive `CkCitation` — hover a marker to preview its source. This is
+ * the end-to-end shape of a cited answer in a conversation.
+ */
+export const WithCitations: Story = {
+  render: () => ({
+    components: { CkAgentMessage, CkMarkdownRenderer },
+    setup() {
+      function openSource(url: string) {
+        window.open(url, '_blank', 'noopener');
+      }
+      return { content: CITED_MARKDOWN, citations: CITATIONS, openSource };
+    },
+    template: `
+      <CkAgentMessage>
+        <template #icon>
+          <div class="bg-core-bg-tertiary flex size-6 items-center justify-center rounded-full text-xs">
+            AI
+          </div>
+        </template>
+        <CkMarkdownRenderer
+          :content="content"
+          :citations="citations"
+          @open-source="openSource"
+        />
+      </CkAgentMessage>
+    `,
+  }),
+  parameters: { docs: { source: { code: withCitationsTemplateSource } } },
+};