From 69039a2c66f210b4d8a49ac44db948b96b35d249 Mon Sep 17 00:00:00 2001
From: Taki Koutsomitis <koutst@protonmail.com>
Date: Tue, 3 Nov 2026 16:16:09 -0500
Subject: [PATCH] Show agent chat artifacts in a sandboxed viewer

---
 components/AgentChat/ActivityFeed.tsx         |  71 +++++-
 components/AgentChat/ChatTranscript.tsx       | 111 ++++-----
 .../AgentChat/artifacts/ArtifactCard.tsx      |  51 ++++
 .../AgentChat/artifacts/ArtifactFrame.tsx     |  61 +++++
 .../AgentChat/artifacts/ArtifactViewer.tsx    | 149 ++++++++++++
 .../AgentChat/artifacts/artifactDocument.ts   | 196 +++++++++++++++
 .../AgentChat/artifacts/artifactKinds.ts      |  64 +++++
 components/modals/ArtifactModal.tsx           | 226 ++++++++++++++++++
 hooks/useAgentChat.ts                         |  24 +-
 hooks/useArtifact.ts                          |  43 ++++
 services/artifact.service.ts                  |  13 +
 types/agentChat.ts                            |  25 ++
 types/artifact.ts                             |  29 +++
 13 files changed, 1007 insertions(+), 56 deletions(-)
 create mode 100644 components/AgentChat/artifacts/ArtifactCard.tsx
 create mode 100644 components/AgentChat/artifacts/ArtifactFrame.tsx
 create mode 100644 components/AgentChat/artifacts/ArtifactViewer.tsx
 create mode 100644 components/AgentChat/artifacts/artifactDocument.ts
 create mode 100644 components/AgentChat/artifacts/artifactKinds.ts
 create mode 100644 components/modals/ArtifactModal.tsx
 create mode 100644 hooks/useArtifact.ts
 create mode 100644 services/artifact.service.ts
 create mode 100644 types/artifact.ts

diff --git a/components/AgentChat/ActivityFeed.tsx b/components/AgentChat/ActivityFeed.tsx
index cdd33c4be..1a1416781 100644
--- a/components/AgentChat/ActivityFeed.tsx
+++ b/components/AgentChat/ActivityFeed.tsx
@@ -2,6 +2,7 @@
 
 import { useMemo, useState, type ComponentType } from 'react';
 import {
+  AppWindow,
   Ban,
   BookOpen,
   Brain,
@@ -23,12 +24,15 @@ import { Loader } from '@/components/ui/Loader';
 import { cn } from '@/utils/styles';
 import { MarkdownMessage } from './MarkdownMessage';
 import { CodeExecutionPanel } from './CodeExecutionPanel';
+import { ArtifactCard } from './artifacts/ArtifactCard';
+import { useArtifactViewer } from './artifacts/ArtifactViewer';
 import { answerRevealKey, isRevealable, narrationRevealKey } from '@/hooks/useTextReveal';
 import type {
   ActivityCallStatus,
   ChatFeedItem,
   ChatActivitySource,
   ChatToolCallActivity,
+  ChatToolDraftActivity,
 } from '@/types/agentChat';
 
 /**
@@ -47,6 +51,9 @@ const TOOL_ICONS: Record<string, ComponentType<{ className?: string }>> = {
   get_work_fulltext: FileSearch,
   code_execution: SquareTerminal,
   bash_code_execution: SquareTerminal,
+  create_artifact: AppWindow,
+  update_artifact: AppWindow,
+  read_artifact: AppWindow,
 };
 
 /**
@@ -151,6 +158,8 @@ const TEXT_SHINE = cn(
  */
 function ToolCallRow({ call }: { readonly call: ChatToolCallActivity }) {
   const ToolIcon = TOOL_ICONS[call.tool] ?? Wrench;
+  const viewer = useArtifactViewer();
+  const artifact = call.artifact;
 
   return (
     <div className="flex items-start gap-2">
@@ -169,9 +178,18 @@ function ToolCallRow({ call }: { readonly call: ChatToolCallActivity }) {
             {humanizeLabel(call.label)}
           </span>
         </div>
-        {call.detail && (
+        {/* An artifact's card names it, so its title isn't repeated as detail. */}
+        {call.detail && !artifact && (
           <p className="mt-1.5 break-words leading-relaxed text-gray-500">{call.detail}</p>
         )}
+        {artifact && (
+          <ArtifactCard
+            title={artifact.title}
+            kind={artifact.kind}
+            caption={`Version ${artifact.version}`}
+            onOpen={viewer ? () => viewer.openArtifact(artifact) : undefined}
+          />
+        )}
         {call.code_execution && (
           <CodeExecutionPanel execution={call.code_execution} tool={call.tool} />
         )}
@@ -181,6 +199,54 @@ function ToolCallRow({ call }: { readonly call: ChatToolCallActivity }) {
   );
 }
 
+/**
+ * An artifact the agent is writing: its label with the sweep, and a card
+ * that opens the viewer on the content as it streams. The content is a page
+ * or a program, not prose, so it never unfolds into the feed.
+ */
+function ArtifactDraftRow({
+  draft,
+  streaming,
+  executionId,
+}: {
+  readonly draft: ChatToolDraftActivity & { id?: string };
+  readonly streaming: boolean;
+  readonly executionId?: number;
+}) {
+  const viewer = useArtifactViewer();
+  const lines = draft.text ? draft.text.split('\n').length : 0;
+  const itemId = draft.id;
+  return (
+    <div className="flex items-start gap-2">
+      <span className="mt-0.5 flex h-4 w-4 shrink-0 items-center justify-center" />
+      <div className="min-w-0 flex-1">
+        <div className="flex items-center gap-1.5 font-medium text-gray-800">
+          <AppWindow className="h-3.5 w-3.5 shrink-0 text-gray-400" aria-hidden="true" />
+          <span
+            className={cn(
+              'min-w-0 truncate',
+              streaming && cn('[--shine:theme(colors.gray.800)]', TEXT_SHINE)
+            )}
+          >
+            {humanizeLabel(draft.label)}
+          </span>
+        </div>
+        <ArtifactCard
+          title={draft.artifact?.title || 'Untitled artifact'}
+          kind={draft.artifact?.kind}
+          caption={lines === 1 ? '1 line' : `${lines} lines`}
+          live={streaming}
+          onOpen={
+            viewer && executionId != null && itemId
+              ? () => viewer.openDraft(executionId, itemId)
+              : undefined
+          }
+        />
+      </div>
+    </div>
+  );
+}
+
 /**
  * Markdown markers dropped for the collapsed one-line preview, where markup
  * can't render and would read as clutter. Underscores stay: intraword `_`
@@ -399,6 +465,9 @@ function ActivityItemBody({
       />
     );
   }
+  if (item.type === 'tool_draft' && item.tool === 'create_artifact') {
+    return <ArtifactDraftRow draft={item} streaming={streaming} executionId={executionId} />;
+  }
   if (item.type === 'tool_draft') {
     // Coloured and iconed like the tool row it becomes, so the draft and the
     // call it turns into read as one step rather than two.
diff --git a/components/AgentChat/ChatTranscript.tsx b/components/AgentChat/ChatTranscript.tsx
index 39ae761ff..7210a85d5 100644
--- a/components/AgentChat/ChatTranscript.tsx
+++ b/components/AgentChat/ChatTranscript.tsx
@@ -10,6 +10,7 @@ import { answerRevealKey, isRevealable } from '@/hooks/useTextReveal';
 import { ExecutionProgress } from './ExecutionProgress';
 import { PendingThinkingRow } from './ActivityFeed';
 import { RoutedModelNote } from './RoutedModelNote';
+import { ArtifactViewerProvider } from './artifacts/ArtifactViewer';
 
 type TranscriptEntry =
   | { key: string; kind: 'user'; message: ChatMessage }
@@ -207,61 +208,63 @@ export function ChatTranscript({
     // Turns are separated by whitespace alone now that neither the assistant
     // answer nor its tool activity carries a card, so the gap between them has
     // to be larger than the gap within one turn.
-    <div className="space-y-5">
-      {entries.map((entry) => {
-        switch (entry.kind) {
-          case 'user':
-            return (
-              <UserBubble
-                key={entry.key}
-                text={entry.message.content}
-                attachments={entry.message.attachments}
-              />
-            );
-          case 'pending-user':
-            // Two siblings, not one wrapper: the echo stands in for a user
-            // entry and the execution entry about to follow it, so it has to
-            // take the same between-entry gap that pair will. Boxed together
-            // they took the within-turn 12px where the real pair takes 20px,
-            // and the placeholder dropped 8px the moment the refetch landed.
-            return (
-              <Fragment key={entry.key}>
-                <UserBubble text={entry.text} attachments={entry.attachments} />
-                <PendingThinkingRow />
-              </Fragment>
-            );
-          case 'execution':
-            return (
-              <div key={entry.key} className="space-y-3">
-                <ExecutionProgress
-                  execution={entry.execution}
-                  failureActions={renderFailureActions?.(entry.execution)}
+    <ArtifactViewerProvider chat={chat}>
+      <div className="space-y-5">
+        {entries.map((entry) => {
+          switch (entry.kind) {
+            case 'user':
+              return (
+                <UserBubble
+                  key={entry.key}
+                  text={entry.message.content}
+                  attachments={entry.message.attachments}
                 />
-                {entry.execution.routed_model && (
-                  <RoutedModelNote
-                    model={entry.execution.model}
-                    routedModel={entry.execution.routed_model}
+              );
+            case 'pending-user':
+              // Two siblings, not one wrapper: the echo stands in for a user
+              // entry and the execution entry about to follow it, so it has to
+              // take the same between-entry gap that pair will. Boxed together
+              // they took the within-turn 12px where the real pair takes 20px,
+              // and the placeholder dropped 8px the moment the refetch landed.
+              return (
+                <Fragment key={entry.key}>
+                  <UserBubble text={entry.text} attachments={entry.attachments} />
+                  <PendingThinkingRow />
+                </Fragment>
+              );
+            case 'execution':
+              return (
+                <div key={entry.key} className="space-y-3">
+                  <ExecutionProgress
+                    execution={entry.execution}
+                    failureActions={renderFailureActions?.(entry.execution)}
                   />
-                )}
-                {entry.answer && (
-                  <AssistantBubble
-                    content={entry.answer.content}
-                    revealKey={
-                      isRevealable(answerRevealKey(entry.execution.id))
-                        ? answerRevealKey(entry.execution.id)
-                        : null
-                    }
-                  />
-                )}
-                {renderExecutionExtra?.(entry.execution)}
-              </div>
-            );
-          case 'assistant':
-            return <AssistantBubble key={entry.key} content={entry.message.content} />;
-          default:
-            return null;
-        }
-      })}
-    </div>
+                  {entry.execution.routed_model && (
+                    <RoutedModelNote
+                      model={entry.execution.model}
+                      routedModel={entry.execution.routed_model}
+                    />
+                  )}
+                  {entry.answer && (
+                    <AssistantBubble
+                      content={entry.answer.content}
+                      revealKey={
+                        isRevealable(answerRevealKey(entry.execution.id))
+                          ? answerRevealKey(entry.execution.id)
+                          : null
+                      }
+                    />
+                  )}
+                  {renderExecutionExtra?.(entry.execution)}
+                </div>
+              );
+            case 'assistant':
+              return <AssistantBubble key={entry.key} content={entry.message.content} />;
+            default:
+              return null;
+          }
+        })}
+      </div>
+    </ArtifactViewerProvider>
   );
 }
diff --git a/components/AgentChat/artifacts/ArtifactCard.tsx b/components/AgentChat/artifacts/ArtifactCard.tsx
new file mode 100644
index 000000000..0b0715eb9
--- /dev/null
+++ b/components/AgentChat/artifacts/ArtifactCard.tsx
@@ -0,0 +1,51 @@
+'use client';
+
+import { ChevronRight } from 'lucide-react';
+import { cn } from '@/utils/styles';
+import { artifactKindInfo } from './artifactKinds';
+
+interface ArtifactCardProps {
+  readonly title: string;
+  readonly kind: string | undefined;
+  /** The second line: the version, or how far a draft has got. */
+  readonly caption: string;
+  readonly live?: boolean;
+  /** Absent where no viewer is mounted; the card is then a plain label. */
+  readonly onOpen?: () => void;
+}
+
+/** An artifact in the activity feed, opening it in the viewer. */
+export function ArtifactCard({ title, kind, caption, live = false, onOpen }: ArtifactCardProps) {
+  const { icon: Icon, label } = artifactKindInfo(kind);
+  const body = (
+    <>
+      <span
+        className={cn(
+          'flex h-9 w-9 shrink-0 items-center justify-center rounded-md border border-gray-200 bg-gray-50',
+          live && 'motion-safe:animate-pulse'
+        )}
+      >
+        <Icon className="h-4 w-4 text-gray-500" aria-hidden="true" />
+      </span>
+      <span className="min-w-0 flex-1">
+        <span className="block truncate font-medium text-gray-900">{title}</span>
+        <span className="block truncate text-xs text-gray-500">
+          {label} · {caption}
+        </span>
+      </span>
+      {onOpen && <ChevronRight className="h-4 w-4 shrink-0 text-gray-400" aria-hidden="true" />}
+    </>
+  );
+  const className =
+    'mt-2 flex w-full max-w-sm items-center gap-3 rounded-lg border border-gray-200 bg-white px-3 py-2 text-left text-sm';
+  if (!onOpen) return <div className={className}>{body}</div>;
+  return (
+    <button
+      type="button"
+      onClick={onOpen}
+      className={cn(className, 'transition-colors hover:border-gray-300 hover:bg-gray-50')}
+    >
+      {body}
+    </button>
+  );
+}
diff --git a/components/AgentChat/artifacts/ArtifactFrame.tsx b/components/AgentChat/artifacts/ArtifactFrame.tsx
new file mode 100644
index 000000000..17e6b0760
--- /dev/null
+++ b/components/AgentChat/artifacts/ArtifactFrame.tsx
@@ -0,0 +1,61 @@
+'use client';
+
+import { useEffect, useMemo, useRef, useState } from 'react';
+import { TriangleAlert } from 'lucide-react';
+import { cn } from '@/utils/styles';
+import { ARTIFACT_ERROR_MESSAGE, buildArtifactDocument } from './artifactDocument';
+
+interface ArtifactFrameProps {
+  readonly kind: string;
+  readonly content: string;
+  readonly title: string;
+  readonly className?: string;
+}
+
+/**
+ * An artifact running in its sandbox (see `artifactDocument`). Errors the page
+ * reports are shown over its bottom edge; any other message from it is
+ * ignored, and only a message from this frame's own window counts.
+ */
+export function ArtifactFrame({ kind, content, title, className }: ArtifactFrameProps) {
+  const frameRef = useRef<HTMLIFrameElement>(null);
+  const srcDoc = useMemo(() => buildArtifactDocument(kind, content), [kind, content]);
+  const [error, setError] = useState<{ srcDoc: string | null; message: string } | null>(null);
+
+  useEffect(() => {
+    const onMessage = (event: MessageEvent) => {
+      if (event.source == null || event.source !== frameRef.current?.contentWindow) return;
+      const data = event.data as { type?: unknown; message?: unknown } | null;
+      if (data?.type !== ARTIFACT_ERROR_MESSAGE || typeof data.message !== 'string') return;
+      setError({ srcDoc, message: data.message });
+    };
+    window.addEventListener('message', onMessage);
+    return () => window.removeEventListener('message', onMessage);
+  }, [srcDoc]);
+
+  if (srcDoc == null) return null;
+  // An error belongs to the document that raised it; a new version starts clean.
+  const shownError = error?.srcDoc === srcDoc ? error.message : null;
+
+  return (
+    <div className={cn('relative h-full w-full bg-white', className)}>
+      <iframe
+        ref={frameRef}
+        // Scripts only: no same-origin access, top navigation, popups or forms.
+        sandbox="allow-scripts"
+        srcDoc={srcDoc}
+        title={title}
+        referrerPolicy="no-referrer"
+        className="h-full w-full border-0"
+      />
+      {shownError && (
+        <div className="absolute inset-x-3 bottom-3 flex items-start gap-2 rounded-lg border border-red-200 bg-red-50 px-3 py-2 text-sm text-red-700 shadow-sm">
+          <TriangleAlert className="mt-0.5 h-4 w-4 shrink-0" aria-hidden="true" />
+          <p className="min-w-0 break-words">
+            <span className="font-medium">This artifact hit an error:</span> {shownError}
+          </p>
+        </div>
+      )}
+    </div>
+  );
+}
diff --git a/components/AgentChat/artifacts/ArtifactViewer.tsx b/components/AgentChat/artifacts/ArtifactViewer.tsx
new file mode 100644
index 000000000..6bd6e1fb5
--- /dev/null
+++ b/components/AgentChat/artifacts/ArtifactViewer.tsx
@@ -0,0 +1,149 @@
+'use client';
+
+import { createContext, useContext, useEffect, useMemo, useState, type ReactNode } from 'react';
+import { ArtifactModal } from '@/components/modals/ArtifactModal';
+import { useArtifact } from '@/hooks/useArtifact';
+import type {
+  AgentChat,
+  ChatArtifactRef,
+  ChatExecution,
+  ChatToolDraftActivity,
+} from '@/types/agentChat';
+
+/** What the viewer shows: a saved version, or an artifact the agent is still writing. */
+type ViewerTarget =
+  | { type: 'saved'; id: number; version: number }
+  | { type: 'draft'; executionId: number; itemId: string };
+
+interface ArtifactViewerContextValue {
+  openArtifact: (artifact: ChatArtifactRef) => void;
+  openDraft: (executionId: number, itemId: string) => void;
+}
+
+const ArtifactViewerContext = createContext<ArtifactViewerContextValue | null>(null);
+
+/** Opens artifacts in the chat's viewer; null outside one, where cards don't open. */
+export function useArtifactViewer(): ArtifactViewerContextValue | null {
+  return useContext(ArtifactViewerContext);
+}
+
+function findDraft(
+  chat: AgentChat,
+  executionId: number,
+  itemId: string
+): ChatToolDraftActivity | null {
+  const stream = chat.executions.find((candidate) => candidate.id === executionId)?.stream;
+  // The feed namespaces stream item ids with their stream's (see ExecutionProgress).
+  const item = stream?.items.find((candidate) => `${stream.id}:${candidate.id}` === itemId);
+  return item?.type === 'tool_draft' ? item : null;
+}
+
+/**
+ * The artifact a finished draft became: the turn's newest one created under
+ * the draft's title, else its newest one created at all. The draft and the
+ * durable call it turns into share no id, and a turn rarely creates two.
+ */
+function savedFromDraft(
+  execution: ChatExecution | undefined,
+  title: string | undefined
+): ChatArtifactRef | null {
+  const created = (execution?.activity ?? []).flatMap((item) =>
+    item.type === 'tool_call' && item.tool === 'create_artifact' && item.artifact
+      ? [item.artifact]
+      : []
+  );
+  return created.findLast((artifact) => artifact.title === title) ?? created.at(-1) ?? null;
+}
+
+interface ArtifactViewerProviderProps {
+  readonly chat: AgentChat;
+  readonly children: ReactNode;
+}
+
+/**
+ * Hosts the artifact viewer for one chat transcript. A draft opened while the
+ * agent writes it follows the stream, then becomes the saved artifact once the
+ * turn's activity records it; until then it keeps showing what was streamed.
+ */
+export function ArtifactViewerProvider({ chat, children }: ArtifactViewerProviderProps) {
+  const [target, setTarget] = useState<ViewerTarget | null>(null);
+  const [lastDraft, setLastDraft] = useState<ChatToolDraftActivity | null>(null);
+
+  const draft =
+    target?.type === 'draft' ? findDraft(chat, target.executionId, target.itemId) : null;
+  if (draft != null && draft !== lastDraft) setLastDraft(draft);
+  const shownDraft = target?.type === 'draft' ? (draft ?? lastDraft) : null;
+
+  // Hand a finished draft over to the version it saved.
+  const draftExecutionId = target?.type === 'draft' ? target.executionId : null;
+  const saved =
+    target?.type === 'draft' && draft == null
+      ? savedFromDraft(
+          chat.executions.find((execution) => execution.id === draftExecutionId),
+          lastDraft?.artifact?.title
+        )
+      : null;
+  useEffect(() => {
+    if (saved) setTarget({ type: 'saved', id: saved.id, version: saved.version });
+  }, [saved?.id, saved?.version]); // eslint-disable-line react-hooks/exhaustive-deps
+
+  const { artifact, error } = useArtifact(
+    target?.type === 'saved' ? target.id : null,
+    target?.type === 'saved' ? target.version : null
+  );
+
+  const value = useMemo<ArtifactViewerContextValue>(
+    () => ({
+      openArtifact: (ref) => setTarget({ type: 'saved', id: ref.id, version: ref.version }),
+      openDraft: (executionId, itemId) => {
+        setLastDraft(null);
+        setTarget({ type: 'draft', executionId, itemId });
+      },
+    }),
+    []
+  );
+
+  const close = () => setTarget(null);
+  let modal: ReactNode = null;
+  if (target?.type === 'draft' && shownDraft) {
+    modal = (
+      <ArtifactModal
+        isOpen
+        onClose={close}
+        title={shownDraft.artifact?.title || 'Untitled artifact'}
+        kind={shownDraft.artifact?.kind}
+        language={shownDraft.artifact?.language}
+        content={shownDraft.text}
+        writing
+      />
+    );
+  } else if (target?.type === 'saved') {
+    modal = (
+      <ArtifactModal
+        isOpen
+        onClose={close}
+        title={artifact?.title ?? ''}
+        kind={artifact?.kind}
+        language={artifact?.language}
+        content={artifact?.version.content ?? null}
+        error={error ? 'This artifact could not be loaded.' : null}
+        version={
+          artifact
+            ? {
+                number: target.version,
+                latest: artifact.latest_version,
+                onSelect: (number) => setTarget({ ...target, version: number }),
+              }
+            : null
+        }
+      />
+    );
+  }
+
+  return (
+    <ArtifactViewerContext.Provider value={value}>
+      {children}
+      {modal}
+    </ArtifactViewerContext.Provider>
+  );
+}
diff --git a/components/AgentChat/artifacts/artifactDocument.ts b/components/AgentChat/artifacts/artifactDocument.ts
new file mode 100644
index 000000000..eb020528f
--- /dev/null
+++ b/components/AgentChat/artifacts/artifactDocument.ts
@@ -0,0 +1,196 @@
+/**
+ * Builds the page an artifact renders as, for an `<iframe sandbox="allow-scripts">`
+ * `srcdoc`. Without `allow-same-origin` the page gets an opaque origin: it
+ * cannot read the app's cookies, storage or DOM, navigate the app, or open
+ * windows. The CSP below closes the rest — it may load scripts, styles and
+ * fonts only from the listed CDNs, show only inline images, and make no
+ * network requests of its own — so content the model wrote (and anything a
+ * fetched page talked it into writing) cannot send data anywhere.
+ *
+ * Markdown and code are not pages: they render in the app itself, through
+ * its sanitizing renderers, and get no document here.
+ */
+
+import type { ArtifactKind } from '@/types/artifact';
+
+/** Kinds this build renders in the sandbox. */
+const FRAMED_KINDS: ReadonlySet<string> = new Set<ArtifactKind>([
+  'html',
+  'react',
+  'svg',
+  'mermaid',
+]);
+
+const SCRIPT_HOSTS = [
+  'https://cdnjs.cloudflare.com',
+  'https://cdn.jsdelivr.net',
+  'https://unpkg.com',
+  'https://esm.sh',
+  'https://cdn.tailwindcss.com',
+].join(' ');
+
+const CSP = [
+  "default-src 'none'",
+  `script-src 'unsafe-inline' 'unsafe-eval' blob: ${SCRIPT_HOSTS}`,
+  `style-src 'unsafe-inline' ${SCRIPT_HOSTS} https://fonts.googleapis.com`,
+  `font-src data: ${SCRIPT_HOSTS} https://fonts.gstatic.com`,
+  'img-src data: blob:',
+  'media-src data: blob:',
+  "base-uri 'none'",
+  "form-action 'none'",
+].join('; ');
+
+/** Message the page posts to its parent when it fails; the parent checks the source window. */
+export const ARTIFACT_ERROR_MESSAGE = 'researchhub-artifact-error';
+
+// Runs before the content: uncaught errors and rejections are reported to the
+// parent, which shows them, since the sandbox has no console the user sees.
+const ERROR_REPORTER = `<script>
+(function () {
+  function report(error) {
+    var message = error && error.message ? error.message : String(error);
+    parent.postMessage({ type: '${ARTIFACT_ERROR_MESSAGE}', message: message.slice(0, 2000) }, '*');
+  }
+  window.__reportArtifactError = report;
+  addEventListener('error', function (event) { report(event.error || event.message); });
+  addEventListener('unhandledrejection', function (event) { report(event.reason); });
+})();
+</script>`;
+
+const HEAD = `<!doctype html>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<meta http-equiv="Content-Security-Policy" content="${CSP}">
+${ERROR_REPORTER}`;
+
+const BASE_STYLE = `<style>
+  html, body { margin: 0; background: #fff; color: #111827;
+    font-family: ui-sans-serif, system-ui, -apple-system, 'Segoe UI', sans-serif; }
+  .artifact-loading { margin: 24px; font-size: 14px; color: #6b7280; }
+</style>`;
+
+/**
+ * Module versions a React artifact can import, matching what the tool
+ * description promises the model. React dependencies are left external so
+ * every module shares the one React the import map names.
+ */
+const REACT_IMPORTS = {
+  react: 'https://esm.sh/react@18.3.1',
+  'react/': 'https://esm.sh/react@18.3.1/',
+  'react-dom': 'https://esm.sh/react-dom@18.3.1?external=react',
+  'react-dom/client': 'https://esm.sh/react-dom@18.3.1/client?external=react',
+  recharts: 'https://esm.sh/recharts@2.15.0?external=react,react-dom',
+  'lucide-react': 'https://esm.sh/lucide-react@0.468.0?external=react',
+  d3: 'https://esm.sh/d3@7.9.0',
+  lodash: 'https://esm.sh/lodash@4.17.21',
+};
+
+const BABEL = 'https://cdnjs.cloudflare.com/ajax/libs/babel-standalone/7.26.4/babel.min.js';
+const TAILWIND = 'https://cdn.tailwindcss.com/3.4.16';
+const MERMAID = 'https://cdn.jsdelivr.net/npm/mermaid@11.4.1/dist/mermaid.esm.min.mjs';
+
+/** JSON for a `<script type="application/json">`, safe against `</script>` in the source. */
+function embeddedJson(value: unknown): string {
+  return JSON.stringify(value)
+    .replaceAll('<', String.raw`<`)
+    .replaceAll('
', String.raw`
`)
+    .replaceAll('
', String.raw`
`);
+}
+
+function sourceScript(content: string): string {
+  return `<script type="application/json" id="artifact-source">${embeddedJson(content)}</script>`;
+}
+
+function reactDocument(content: string): string {
+  return `${HEAD}
+<script type="importmap">${embeddedJson({ imports: REACT_IMPORTS })}</script>
+<script src="${BABEL}"></script>
+<script src="${TAILWIND}"></script>
+${BASE_STYLE}
+<div id="root"><p class="artifact-loading">Loading…</p></div>
+${sourceScript(content)}
+<script type="module">
+  const source = JSON.parse(document.getElementById('artifact-source').textContent);
+  try {
+    // JSX and TypeScript only: imports stay as they are, for the import map.
+    const { code } = Babel.transform(source, {
+      filename: 'artifact.tsx',
+      presets: [['react', { runtime: 'automatic' }], ['typescript', { isTSX: true, allExtensions: true }]],
+    });
+    const url = URL.createObjectURL(new Blob([code], { type: 'text/javascript' }));
+    const module = await import(url);
+    const Component = module.default;
+    if (typeof Component !== 'function') {
+      throw new Error('The component must be the default export.');
+    }
+    const [{ createElement }, { createRoot }] = await Promise.all([
+      import('react'),
+      import('react-dom/client'),
+    ]);
+    createRoot(document.getElementById('root')).render(createElement(Component));
+  } catch (error) {
+    document.getElementById('root').textContent = '';
+    window.__reportArtifactError(error);
+  }
+</script>`;
+}
+
+function mermaidDocument(content: string): string {
+  return `${HEAD}
+${BASE_STYLE}
+<style>#diagram { padding: 24px; display: flex; justify-content: center; }
+  #diagram svg { max-width: 100%; height: auto; }</style>
+<div id="diagram"><p class="artifact-loading">Drawing the diagram…</p></div>
+${sourceScript(content)}
+<script type="module">
+  const source = JSON.parse(document.getElementById('artifact-source').textContent);
+  try {
+    const { default: mermaid } = await import('${MERMAID}');
+    mermaid.initialize({ startOnLoad: false, securityLevel: 'strict', theme: 'neutral' });
+    const { svg } = await mermaid.render('artifact-diagram', source);
+    document.getElementById('diagram').innerHTML = svg;
+  } catch (error) {
+    document.getElementById('diagram').textContent = '';
+    window.__reportArtifactError(error);
+  }
+</script>`;
+}
+
+function svgDocument(content: string): string {
+  return `${HEAD}
+${BASE_STYLE}
+<style>body { min-height: 100vh; display: flex; align-items: center; justify-content: center; }
+  body > svg { max-width: 100%; max-height: 100vh; height: auto; }</style>
+${content}`;
+}
+
+/**
+ * The model's page goes after the reporter and the CSP, so the policy is in
+ * force before any of its markup is parsed. Its own doctype, `<html>` and
+ * `<head>` then merge into this document's as stray tags.
+ */
+function htmlDocument(content: string): string {
+  return `${HEAD}
+${content}`;
+}
+
+/** Whether `kind` renders in the sandbox rather than in the app. */
+export function rendersInFrame(kind: string): boolean {
+  return FRAMED_KINDS.has(kind);
+}
+
+/** The `srcdoc` for an artifact, or null for a kind that is not framed. */
+export function buildArtifactDocument(kind: string, content: string): string | null {
+  switch (kind) {
+    case 'html':
+      return htmlDocument(content);
+    case 'react':
+      return reactDocument(content);
+    case 'svg':
+      return svgDocument(content);
+    case 'mermaid':
+      return mermaidDocument(content);
+    default:
+      return null;
+  }
+}
diff --git a/components/AgentChat/artifacts/artifactKinds.ts b/components/AgentChat/artifacts/artifactKinds.ts
new file mode 100644
index 000000000..a855333fe
--- /dev/null
+++ b/components/AgentChat/artifacts/artifactKinds.ts
@@ -0,0 +1,64 @@
+import type { ComponentType } from 'react';
+import { AppWindow, Atom, Code, FileText, Image, Workflow } from 'lucide-react';
+
+interface KindInfo {
+  label: string;
+  icon: ComponentType<{ className?: string }>;
+  extension: string;
+  mimeType: string;
+}
+
+const KINDS: Record<string, KindInfo> = {
+  html: { label: 'Web page', icon: AppWindow, extension: 'html', mimeType: 'text/html' },
+  react: { label: 'React component', icon: Atom, extension: 'jsx', mimeType: 'text/javascript' },
+  svg: { label: 'SVG image', icon: Image, extension: 'svg', mimeType: 'image/svg+xml' },
+  mermaid: { label: 'Diagram', icon: Workflow, extension: 'mmd', mimeType: 'text/plain' },
+  markdown: { label: 'Document', icon: FileText, extension: 'md', mimeType: 'text/markdown' },
+  code: { label: 'Code', icon: Code, extension: 'txt', mimeType: 'text/plain' },
+};
+
+/** File extensions for the languages a code artifact is most likely in. */
+const LANGUAGE_EXTENSIONS: Record<string, string> = {
+  python: 'py',
+  r: 'R',
+  javascript: 'js',
+  typescript: 'ts',
+  julia: 'jl',
+  matlab: 'm',
+  bash: 'sh',
+  shell: 'sh',
+  sql: 'sql',
+  json: 'json',
+  yaml: 'yaml',
+  latex: 'tex',
+  tex: 'tex',
+  css: 'css',
+  html: 'html',
+  java: 'java',
+  c: 'c',
+  'c++': 'cpp',
+  cpp: 'cpp',
+  rust: 'rs',
+  go: 'go',
+};
+
+/** Display copy and file type for `kind`; a kind this build doesn't know reads as code. */
+export function artifactKindInfo(kind: string | undefined): KindInfo {
+  return KINDS[kind ?? ''] ?? KINDS.code;
+}
+
+/** A download filename for the artifact, from its title. */
+export function artifactFilename(title: string, kind: string, language: string): string {
+  const base =
+    title
+      .trim()
+      .toLowerCase()
+      .replaceAll(/[^a-z0-9]+/g, '-')
+      .replaceAll(/^-+|-+$/g, '')
+      .slice(0, 80) || 'artifact';
+  const extension =
+    kind === 'code'
+      ? (LANGUAGE_EXTENSIONS[language.trim().toLowerCase()] ?? 'txt')
+      : artifactKindInfo(kind).extension;
+  return `${base}.${extension}`;
+}
diff --git a/components/modals/ArtifactModal.tsx b/components/modals/ArtifactModal.tsx
new file mode 100644
index 000000000..e3a4185c8
--- /dev/null
+++ b/components/modals/ArtifactModal.tsx
@@ -0,0 +1,226 @@
+'use client';
+
+import { useEffect, useRef, useState } from 'react';
+import { Dialog, DialogPanel, DialogTitle } from '@headlessui/react';
+import { Check, ChevronLeft, ChevronRight, Copy, Download, X } from 'lucide-react';
+import { Button } from '@/components/ui/Button';
+import { Loader } from '@/components/ui/Loader';
+import { MarkdownMessage } from '@/components/AgentChat/MarkdownMessage';
+import { ArtifactFrame } from '@/components/AgentChat/artifacts/ArtifactFrame';
+import { rendersInFrame } from '@/components/AgentChat/artifacts/artifactDocument';
+import { artifactFilename, artifactKindInfo } from '@/components/AgentChat/artifacts/artifactKinds';
+import { cn } from '@/utils/styles';
+
+export interface ArtifactModalVersion {
+  number: number;
+  latest: number;
+  onSelect: (number: number) => void;
+}
+
+interface ArtifactModalProps {
+  readonly isOpen: boolean;
+  readonly onClose: () => void;
+  readonly title: string;
+  readonly kind?: string;
+  readonly language?: string;
+  /** Null while the content loads. */
+  readonly content: string | null;
+  readonly error?: string | null;
+  /** The agent is still writing it: the code streams in and there is no preview yet. */
+  readonly writing?: boolean;
+  readonly version?: ArtifactModalVersion | null;
+}
+
+type View = 'preview' | 'code';
+
+function hasPreview(kind: string | undefined): boolean {
+  return kind === 'markdown' || rendersInFrame(kind ?? '');
+}
+
+function download(content: string, filename: string, mimeType: string) {
+  const url = URL.createObjectURL(new Blob([content], { type: mimeType }));
+  const link = document.createElement('a');
+  link.href = url;
+  link.download = filename;
+  link.click();
+  URL.revokeObjectURL(url);
+}
+
+function CodeView({ content, follow }: { readonly content: string; readonly follow: boolean }) {
+  const ref = useRef<HTMLPreElement>(null);
+  // While the agent writes, keep the newest line in view.
+  useEffect(() => {
+    if (follow && ref.current) ref.current.scrollTop = ref.current.scrollHeight;
+  }, [content, follow]);
+  return (
+    <pre
+      ref={ref}
+      className="h-full overflow-auto whitespace-pre-wrap break-words bg-gray-50 p-4 font-mono text-xs leading-relaxed text-gray-800"
+    >
+      {content}
+    </pre>
+  );
+}
+
+/**
+ * An artifact from an agent chat, nearly full screen: its preview (sandboxed
+ * for pages, components, images and diagrams) or its source, with copy,
+ * download and its versions.
+ */
+export function ArtifactModal({
+  isOpen,
+  onClose,
+  title,
+  kind,
+  language = '',
+  content,
+  error,
+  writing = false,
+  version,
+}: ArtifactModalProps) {
+  const [view, setView] = useState<View>('preview');
+  const [copied, setCopied] = useState(false);
+  const previewable = hasPreview(kind);
+  const shown: View = previewable && !writing ? view : 'code';
+  const { icon: Icon, label, mimeType } = artifactKindInfo(kind);
+
+  useEffect(() => {
+    if (!copied) return;
+    const timer = setTimeout(() => setCopied(false), 1500);
+    return () => clearTimeout(timer);
+  }, [copied]);
+
+  const copy = () => {
+    if (content == null) return;
+    navigator.clipboard
+      .writeText(content)
+      .then(() => setCopied(true))
+      .catch(() => {});
+  };
+
+  let body;
+  if (error) {
+    body = <p className="p-6 text-sm text-gray-500">{error}</p>;
+  } else if (content == null) {
+    body = (
+      <div className="flex h-full items-center justify-center">
+        <Loader size="md" />
+      </div>
+    );
+  } else if (shown === 'code') {
+    body = <CodeView content={content} follow={writing} />;
+  } else if (kind === 'markdown') {
+    body = (
+      <div className="h-full overflow-auto px-6 py-5">
+        <MarkdownMessage content={content} className="mx-auto max-w-3xl text-gray-800" />
+      </div>
+    );
+  } else {
+    body = <ArtifactFrame kind={kind ?? ''} content={content} title={title} />;
+  }
+
+  return (
+    <Dialog open={isOpen} onClose={onClose} className="relative z-[9999]">
+      <div className="fixed inset-0 bg-black/30" aria-hidden="true" />
+      <div className="fixed inset-0 md:p-6">
+        <DialogPanel className="flex h-full w-full flex-col overflow-hidden bg-white shadow-xl md:rounded-xl">
+          <div className="flex items-center gap-3 border-b border-gray-200 px-4 py-2.5">
+            <Icon className="h-4 w-4 shrink-0 text-gray-500" aria-hidden="true" />
+            <div className="min-w-0 flex-1">
+              <DialogTitle className="truncate text-sm font-semibold text-gray-900">
+                {title}
+              </DialogTitle>
+              <p className="truncate text-xs text-gray-500">
+                {label}
+                {language && kind === 'code' ? ` · ${language}` : ''}
+                {writing ? ' · Writing…' : ''}
+              </p>
+            </div>
+
+            {version && version.latest > 1 && (
+              <div className="flex items-center gap-1 text-xs text-gray-600">
+                <button
+                  type="button"
+                  aria-label="Previous version"
+                  disabled={version.number <= 1}
+                  onClick={() => version.onSelect(version.number - 1)}
+                  className="rounded p-1 hover:bg-gray-100 disabled:opacity-40"
+                >
+                  <ChevronLeft className="h-4 w-4" />
+                </button>
+                <span className="whitespace-nowrap tabular-nums">
+                  Version {version.number} of {version.latest}
+                </span>
+                <button
+                  type="button"
+                  aria-label="Next version"
+                  disabled={version.number >= version.latest}
+                  onClick={() => version.onSelect(version.number + 1)}
+                  className="rounded p-1 hover:bg-gray-100 disabled:opacity-40"
+                >
+                  <ChevronRight className="h-4 w-4" />
+                </button>
+              </div>
+            )}
+
+            {previewable && (
+              <div className="flex rounded-md bg-gray-100 p-0.5 text-xs font-medium">
+                {(['preview', 'code'] as const).map((option) => (
+                  <button
+                    key={option}
+                    type="button"
+                    disabled={writing && option === 'preview'}
+                    onClick={() => setView(option)}
+                    aria-pressed={shown === option}
+                    className={cn(
+                      'rounded px-2.5 py-1 capitalize text-gray-600 disabled:opacity-40',
+                      shown === option && 'bg-white text-gray-900 shadow-sm'
+                    )}
+                  >
+                    {option}
+                  </button>
+                ))}
+              </div>
+            )}
+
+            <Button
+              variant="ghost"
+              size="icon"
+              className="h-8 w-8"
+              aria-label={copied ? 'Copied' : 'Copy'}
+              title={copied ? 'Copied' : 'Copy'}
+              disabled={content == null || writing}
+              onClick={copy}
+            >
+              {copied ? <Check className="h-4 w-4" /> : <Copy className="h-4 w-4" />}
+            </Button>
+            <Button
+              variant="ghost"
+              size="icon"
+              className="h-8 w-8"
+              aria-label="Download"
+              title="Download"
+              disabled={content == null || writing}
+              onClick={() =>
+                content != null &&
+                download(content, artifactFilename(title, kind ?? '', language), mimeType)
+              }
+            >
+              <Download className="h-4 w-4" />
+            </Button>
+            <Button
+              variant="ghost"
+              size="icon"
+              className="h-8 w-8"
+              aria-label="Close"
+              onClick={onClose}
+            >
+              <X className="h-4 w-4" />
+            </Button>
+          </div>
+          <div className="min-h-0 flex-1">{body}</div>
+        </DialogPanel>
+      </div>
+    </Dialog>
+  );
+}
diff --git a/hooks/useAgentChat.ts b/hooks/useAgentChat.ts
index e53e2d56c..8774f6c32 100644
--- a/hooks/useAgentChat.ts
+++ b/hooks/useAgentChat.ts
@@ -14,6 +14,7 @@ import { useAgentChatSocket, type ChatSocketStatus } from '@/hooks/useAgentChatS
 import {
   isChatStreamSocketEvent,
   isActiveExecutionStatus,
+  type ChatArtifactDraftFields,
   type ChatExecution,
   type ChatExecutionStream,
   type ChatStreamDelta,
@@ -37,6 +38,8 @@ const MAX_STREAM_NARRATION_CHARS = 100_000;
 const MAX_STREAM_THINKING_CHARS = 4_000;
 /** Matches the server's own cap on a draft's extracted prose. */
 const MAX_STREAM_TOOL_DRAFT_CHARS = 20_000;
+/** An artifact draft streams its whole content, up to what one version holds. */
+const MAX_STREAM_ARTIFACT_CHARS = 100_000;
 
 const STREAM_CHAR_CAPS: Record<ChatStreamDelta['type'], number> = {
   narration: MAX_STREAM_NARRATION_CHARS,
@@ -125,6 +128,13 @@ function phaseForDelta(delta: ChatStreamDelta | undefined): ExecutionPhase {
   return { state: 'thinking', label: 'Thinking' };
 }
 
+function streamCharCap(delta: ChatStreamDelta): number {
+  if (delta.type === 'tool_draft' && delta.tool === 'create_artifact') {
+    return MAX_STREAM_ARTIFACT_CHARS;
+  }
+  return STREAM_CHAR_CAPS[delta.type];
+}
+
 /** The item a delta opens; a draft's identity comes off the frame itself. */
 function newStreamItem(delta: ChatStreamDelta, maximum: number): ChatStreamItem {
   const base = { id: delta.id, text: delta.delta.slice(0, maximum), at: delta.at };
@@ -135,10 +145,15 @@ function newStreamItem(delta: ChatStreamDelta, maximum: number): ChatStreamItem
         tool: delta.tool,
         label: delta.label,
         blocks: Array.isArray(delta.blocks) ? delta.blocks : undefined,
+        artifact: isArtifactDraftFields(delta.artifact) ? delta.artifact : undefined,
       }
     : { ...base, type: delta.type };
 }
 
+function isArtifactDraftFields(value: unknown): value is ChatArtifactDraftFields {
+  return value != null && typeof value === 'object' && !Array.isArray(value);
+}
+
 /** Append one batch's deltas to a copy of `current`; null = corrupt frame. */
 function appendStreamDeltas(
   current: readonly ChatStreamItem[],
@@ -146,7 +161,7 @@ function appendStreamDeltas(
 ): ChatStreamItem[] | null {
   const items = current.map((item) => ({ ...item }));
   for (const delta of deltas) {
-    const maximum = STREAM_CHAR_CAPS[delta.type];
+    const maximum = streamCharCap(delta);
     const existing = items.find((item) => item.id === delta.id);
     if (existing == null) {
       items.push(newStreamItem(delta, maximum));
@@ -159,6 +174,13 @@ function appendStreamDeltas(
       ) {
         existing.blocks = delta.blocks;
       }
+      if (
+        existing.type === 'tool_draft' &&
+        delta.type === 'tool_draft' &&
+        isArtifactDraftFields(delta.artifact)
+      ) {
+        existing.artifact = delta.artifact;
+      }
     } else {
       // An id changing type indicates an incompatible/corrupt frame. Recover
       // from the server checkpoint instead of combining unlike content.
diff --git a/hooks/useArtifact.ts b/hooks/useArtifact.ts
new file mode 100644
index 000000000..c066e9b79
--- /dev/null
+++ b/hooks/useArtifact.ts
@@ -0,0 +1,43 @@
+'use client';
+
+import { useEffect, useState } from 'react';
+import { ArtifactService } from '@/services/artifact.service';
+import type { Artifact } from '@/types/artifact';
+
+// A version never changes once written, so one fetch per version per page load
+// is enough, however often a viewer reopens it.
+const versionCache = new Map<string, Artifact>();
+
+interface ArtifactState {
+  artifact: Artifact | null;
+  loading: boolean;
+  error: boolean;
+}
+
+/** Version `version` of artifact `id`; null `id` loads nothing. */
+export function useArtifact(id: number | null, version: number | null): ArtifactState {
+  const key = id == null || version == null ? null : `${id}:${version}`;
+  const [fetched, setFetched] = useState<{ key: string; artifact: Artifact | null } | null>(null);
+
+  useEffect(() => {
+    if (key == null || id == null || version == null || versionCache.has(key)) return;
+    let cancelled = false;
+    ArtifactService.getArtifact(id, version)
+      .then((artifact) => {
+        versionCache.set(key, artifact);
+        if (!cancelled) setFetched({ key, artifact });
+      })
+      .catch(() => {
+        if (!cancelled) setFetched({ key, artifact: null });
+      });
+    return () => {
+      cancelled = true;
+    };
+  }, [key, id, version]);
+
+  if (key == null) return { artifact: null, loading: false, error: false };
+  const cached = versionCache.get(key);
+  if (cached) return { artifact: cached, loading: false, error: false };
+  if (fetched?.key !== key) return { artifact: null, loading: true, error: false };
+  return { artifact: fetched.artifact, loading: false, error: fetched.artifact == null };
+}
diff --git a/services/artifact.service.ts b/services/artifact.service.ts
new file mode 100644
index 000000000..c93e1454d
--- /dev/null
+++ b/services/artifact.service.ts
@@ -0,0 +1,13 @@
+import { ApiClient } from './client';
+import type { Artifact } from '@/types/artifact';
+
+/** Read access to the artifacts the agent chats make; only the agent writes them. */
+export class ArtifactService {
+  private static readonly BASE_PATH = '/api/research_ai/artifacts/';
+
+  /** The artifact showing `version`, or its latest version when omitted. */
+  static async getArtifact(id: number, version?: number): Promise<Artifact> {
+    const query = version == null ? '' : `?version=${version}`;
+    return ApiClient.get<Artifact>(`${this.BASE_PATH}${id}/${query}`);
+  }
+}
diff --git a/types/agentChat.ts b/types/agentChat.ts
index 137c99fb5..729b7f247 100644
--- a/types/agentChat.ts
+++ b/types/agentChat.ts
@@ -64,6 +64,25 @@ export interface ChatCodeExecution {
   output_count?: number;
 }
 
+/** The artifact version a succeeded `create_artifact` or `update_artifact` wrote. */
+export interface ChatArtifactRef {
+  id: number;
+  version: number;
+  /** See `ArtifactKind`; open-ended. */
+  kind: string;
+  title: string;
+}
+
+/**
+ * What a `create_artifact` draft has written of its title, kind and language
+ * so far; each appears once the model has started writing it.
+ */
+export interface ChatArtifactDraftFields {
+  title?: string;
+  kind?: string;
+  language?: string;
+}
+
 export interface ChatToolCallActivity {
   type: 'tool_call';
   /** Machine name (e.g. `web_search`). Only used to pick an icon — new tools appear without notice. */
@@ -84,6 +103,8 @@ export interface ChatToolCallActivity {
   note_title?: string | null;
   /** Citations (≤5), only on success. */
   sources?: ChatActivitySource[] | null;
+  /** Present only on a succeeded artifact create or update. */
+  artifact?: ChatArtifactRef | null;
 }
 
 /**
@@ -99,6 +120,8 @@ export interface ChatToolDraftActivity {
   type: 'tool_draft';
   /** Complete formatted preview snapshot; replaces itself on each frame. */
   blocks?: JSONContent[];
+  /** `create_artifact` only; `text` is then the artifact's content so far. */
+  artifact?: ChatArtifactDraftFields;
   /**
    * The prose extracted from the arguments so far. Empty for tools whose
    * arguments aren't prose — a search query is written in an instant, so only
@@ -295,6 +318,8 @@ export type ChatStreamDelta =
       type: 'tool_draft';
       /** Complete formatted preview snapshot, not an appended delta. */
       blocks?: JSONContent[];
+      /** `create_artifact` only; replaces the item's fields, like `blocks`. */
+      artifact?: ChatArtifactDraftFields;
       /** Machine name; empty when the provider skipped the block-start event. */
       tool: string;
       /** Human copy supplied by the backend; always rendered verbatim. */
diff --git a/types/artifact.ts b/types/artifact.ts
new file mode 100644
index 000000000..d51349857
--- /dev/null
+++ b/types/artifact.ts
@@ -0,0 +1,29 @@
+/**
+ * Artifacts the agent chats make (`/api/research_ai/artifacts/`): standalone
+ * pages, components, diagrams, documents and code the user views beside the
+ * chat. Wire shapes stay snake_case, like the rest of the agent chat types.
+ */
+
+export type ArtifactKind = 'html' | 'react' | 'svg' | 'mermaid' | 'markdown' | 'code';
+
+export interface ArtifactVersion {
+  /** Versions count from 1; every agent create or update adds one. */
+  number: number;
+  content: string;
+  created_date: string;
+}
+
+export interface Artifact {
+  id: number;
+  conversation_id: number;
+  /** Open-ended: a newer backend may add kinds, which render as plain code. */
+  kind: ArtifactKind | string;
+  title: string;
+  /** Code artifacts only, e.g. `python`; blank otherwise. */
+  language: string;
+  latest_version: number;
+  created_date: string;
+  updated_date: string;
+  /** The version this response shows: the latest, or the one asked for. */
+  version: ArtifactVersion;
+}