<!-- In your app: import { setupArtifacts } from '@aparte/plugin-artifacts';
import { connectArtifactPanel } from '@aparte/plugin-artifacts/panel'. -->
<!-- breakpoint: under 24rem the split shows one pane (48rem by default; this frame is narrower). -->
<aparte-split position="38" breakpoint="24rem" single style="height: 26rem">
<aparte-chat id="chat">
<aparte-chat-viewport></aparte-chat-viewport>
</aparte-chat>
<aparte-artifact-panel for="chat"></aparte-artifact-panel>
</aparte-split>
<script>
const { setupArtifacts, connectArtifactPanel } = window.apartePlugins.artifacts;
const split = document.querySelector('aparte-split');
const panel = document.querySelector('aparte-artifact-panel');
setupArtifacts();
// A card's Open button shows its document in the panel and opens the pane; Close folds it.
connectArtifactPanel({ chat: document.querySelector('aparte-chat'), panel, split });
// Two replies that wrote the same document: the second call passed the first one's id back.
const wrote = (id, content) => ({
id, type: 'tool_call', status: 'resolved', result: 'Artifact created.',
toolCall: { id, name: 'create_artifact', input: {} },
structuredResult: { documentId: 'doc_4f2a91c0', mimeType: 'text/markdown', title: 'Launch note', content },
});
document.querySelector('aparte-chat-viewport').setMessages([
{ id: 'u1', role: 'user', content: 'Write the launch note.', timestamp: 1 },
{ id: 'a1', role: 'assistant', content: '', timestamp: 2, segments: [
wrote('s1', '# Launch note\n\nDocuments now open beside the chat.'),
] },
{ id: 'u2', role: 'user', content: 'Say what a version is.', timestamp: 3 },
{ id: 'a2', role: 'assistant', content: '', timestamp: 4, segments: [
wrote('s2', '# Launch note\n\nDocuments now open beside the chat.\n\n## Versions\n\nEach time the model rewrites a document, the panel keeps the one before. The arrows walk them.'),
] },
]);
// What a press on the last card's Open button does.
panel.show('doc_4f2a91c0');
split.single = false;
</script>When the model writes a document, the reply shows it as a card.
<aparte-artifact-panel> shows the same document where you put it: the other pane of a
split, a dialog, a drawer. It has the document’s versions, with arrows to
walk them, and the card’s own Code and Preview tabs, Copy and Download.
It reads the documents from the conversation and keeps nothing of its own. So the active branch shows its own versions, and a conversation you reload shows what was saved.
npm install @aparte/plugin-artifacts @aparte/core<aparte-split position="40" single>
<aparte-chat id="chat">…</aparte-chat>
<aparte-artifact-panel for="chat"></aparte-artifact-panel>
</aparte-split>import { setupArtifacts } from '@aparte/plugin-artifacts';
import { connectArtifactPanel, type AparteArtifactPanel, type ArtifactPanelSplit } from '@aparte/plugin-artifacts/panel';
setupArtifacts();
const disconnect = connectArtifactPanel({
chat: document.querySelector<HTMLElement>('aparte-chat')!,
panel: document.querySelector<AparteArtifactPanel>('aparte-artifact-panel')!,
split: document.querySelector<ArtifactPanelSplit>('aparte-split')!,
});In a .tsx file the panel’s tag is a compile error until you declare it once:
import type { DetailedHTMLProps, HTMLAttributes } from 'react';
declare module 'react' {
namespace JSX {
interface IntrinsicElements {
'aparte-artifact-panel': DetailedHTMLProps<HTMLAttributes<HTMLElement>, HTMLElement> & { for?: string };
}
}
}import { useEffect, useRef } from 'react';
import { AparteChat, useAparteChat } from '@aparte/react';
import { setupArtifacts } from '@aparte/plugin-artifacts';
import { connectArtifactPanel, type AparteArtifactPanel, type ArtifactPanelSplit } from '@aparte/plugin-artifacts/panel';
setupArtifacts();
export function Workspace() {
const chat = useAparteChat();
const panel = useRef<AparteArtifactPanel>(null);
const split = useRef<ArtifactPanelSplit>(null);
useEffect(
() => connectArtifactPanel({ chat: chat.getElement()!, panel: panel.current!, split: split.current! }),
[],
);
return (
<aparte-split ref={split} position="40" single="">
<AparteChat ref={chat.ref} messages={chat.messages} onMessagesChange={chat.setMessages} />
<aparte-artifact-panel ref={panel} />
</aparte-split>
);
}<script setup lang="ts">
import { onMounted, onUnmounted, ref } from 'vue';
import { AparteChat, useAparteChat } from '@aparte/vue';
import { setupArtifacts } from '@aparte/plugin-artifacts';
import { connectArtifactPanel, type AparteArtifactPanel, type ArtifactPanelSplit } from '@aparte/plugin-artifacts/panel';
setupArtifacts();
const chat = useAparteChat();
const panel = ref<AparteArtifactPanel>();
const split = ref<ArtifactPanelSplit>();
let disconnect: (() => void) | undefined;
onMounted(() => {
disconnect = connectArtifactPanel({ chat: chat.getElement()!, panel: panel.value!, split: split.value! });
});
onUnmounted(() => disconnect?.());
</script>
<template>
<aparte-split ref="split" position="40" single>
<AparteChat :ref="chat.chatRef" :messages="chat.messages.value" @messages-change="chat.onMessagesChange" />
<aparte-artifact-panel ref="panel" />
</aparte-split>
</template><script lang="ts">
import { onMount } from 'svelte';
import { AparteChat, type AparteChatImperativeApi } from '@aparte/svelte/runes';
import { setupArtifacts } from '@aparte/plugin-artifacts';
import { connectArtifactPanel, type AparteArtifactPanel, type ArtifactPanelSplit } from '@aparte/plugin-artifacts/panel';
setupArtifacts();
let chat = $state<AparteChatImperativeApi>();
let panel: AparteArtifactPanel;
let split: ArtifactPanelSplit;
// onMount hands back what connectArtifactPanel returns, which undoes the wiring
onMount(() => connectArtifactPanel({ chat: chat!.getElement()!, panel, split }));
</script>
<aparte-split bind:this={split} position="40" single>
<AparteChat bind:this={chat} />
<aparte-artifact-panel bind:this={panel}></aparte-artifact-panel>
</aparte-split>import { AfterViewInit, Component, CUSTOM_ELEMENTS_SCHEMA, ElementRef, OnDestroy, viewChild } from '@angular/core';
import { AparteChatComponent, AparteSplitDirective } from '@aparte/angular';
import { setupArtifacts } from '@aparte/plugin-artifacts';
import { connectArtifactPanel, type AparteArtifactPanel, type ArtifactPanelSplit } from '@aparte/plugin-artifacts/panel';
setupArtifacts();
@Component({
selector: 'app-workspace',
standalone: true,
imports: [AparteChatComponent, AparteSplitDirective],
schemas: [CUSTOM_ELEMENTS_SCHEMA],
template: `
<aparte-split #split position="40" single>
<aparte-chat></aparte-chat>
<aparte-artifact-panel #panel></aparte-artifact-panel>
</aparte-split>
`,
})
export class WorkspaceComponent implements AfterViewInit, OnDestroy {
private readonly chat = viewChild.required(AparteChatComponent);
private readonly panel = viewChild.required<ElementRef<AparteArtifactPanel>>('panel');
private readonly split = viewChild.required<ElementRef<ArtifactPanelSplit>>('split');
private disconnect?: () => void;
ngAfterViewInit() {
this.disconnect = connectArtifactPanel({
chat: this.chat().getElement()!,
panel: this.panel().nativeElement,
split: this.split().nativeElement,
});
}
ngOnDestroy() {
this.disconnect?.();
}
}The panel is a separate entry of the package, @aparte/plugin-artifacts/panel, so an app that
only wants the card does not ship it. Importing it defines the element.
connectArtifactPanel is the wiring between the three:
- It turns on the card’s Open button for this chat. A press shows that version in the panel, opens the split’s pane and moves the focus to the panel’s title.
- Close, or Escape in the panel, folds the pane and gives the focus back to the button that opened it.
- A conversation with no document shows the chat alone.
It returns a function that undoes all of it. Call setupArtifacts() first: a setup made
after the wiring turns the Open button off again.
Open it by itself
Section titled “Open it by itself”import { connectArtifactPanel, type AparteArtifactPanel, type ArtifactPanelSplit } from '@aparte/plugin-artifacts/panel';
declare const chat: HTMLElement;
declare const panel: AparteArtifactPanel;
declare const split: ArtifactPanelSplit;
connectArtifactPanel({ chat, panel, split, autoOpen: true });With autoOpen, the pane opens when a turn writes a document or a new version of one, without
taking the focus from the composer. It does not open for a conversation that is merely loaded,
and on a narrow screen, where the split shows one pane, the reader stays on the chat.
Documents and versions
Section titled “Documents and versions”A document has an id. The plugin gives it: create_artifact returns it in its result
(doc_4f2a91c0), and a document written with the <artifact> tag reads back to the model as
<artifact id="doc_4f2a91c0" …>. To change a document the model passes the id back, and the
call is a new version of that document. Nothing is overwritten: a version is added and the
earlier ones stay.
artifactDocuments() is that reading, for your own code. It takes the messages: the message list’s
in plain HTML, the chat’s messages in a framework.
import type { AparteChatViewport } from '@aparte/core';
import { artifactDocuments } from '@aparte/plugin-artifacts';
const viewport = document.querySelector<AparteChatViewport>('aparte-chat-viewport')!;
for (const doc of artifactDocuments(viewport.getMessages())) {
console.info(doc.id, doc.title, `${doc.versions.length} version(s)`);
console.info(doc.latest.content); // what the document is now
}import { useAparteChat } from '@aparte/react';
import { artifactDocuments } from '@aparte/plugin-artifacts';
const chat = useAparteChat(); // in your component, with messages={chat.messages} on <AparteChat>
for (const doc of artifactDocuments(chat.messages)) {
console.info(doc.id, doc.title, `${doc.versions.length} version(s)`);
console.info(doc.latest.content); // what the document is now
}<script setup lang="ts">
import { useAparteChat } from '@aparte/vue';
import { artifactDocuments } from '@aparte/plugin-artifacts';
const chat = useAparteChat(); // with :messages="chat.messages.value" on <AparteChat>
function logDocuments() {
for (const doc of artifactDocuments(chat.messages.value)) {
console.info(doc.id, doc.title, `${doc.versions.length} version(s)`);
console.info(doc.latest.content); // what the document is now
}
}
</script><script lang="ts">
import { AparteChat } from '@aparte/svelte/runes';
import type { AparteMessage } from '@aparte/core';
import { artifactDocuments } from '@aparte/plugin-artifacts';
let messages = $state<AparteMessage[]>([]);
function logDocuments() {
for (const doc of artifactDocuments(messages)) {
console.info(doc.id, doc.title, `${doc.versions.length} version(s)`);
console.info(doc.latest.content); // what the document is now
}
}
</script>
<AparteChat bind:messages />import type { AparteMessage } from '@aparte/core';
import { artifactDocuments } from '@aparte/plugin-artifacts';
// `messages` is the array bound with [messages] and (messagesChange) on <aparte-chat>
declare const messages: AparteMessage[];
for (const doc of artifactDocuments(messages)) {
console.info(doc.id, doc.title, `${doc.versions.length} version(s)`);
console.info(doc.latest.content); // what the document is now
}It is a pure function over getMessages(), also exported for Node. A call that was refused,
stopped or failed is not a version. A conversation saved before documents had ids reads as one
document per card.
Customize
Section titled “Customize”Another layout
Section titled “Another layout”The split is optional. Without it, show and hide the panel yourself:
import { connectArtifactPanel, type AparteArtifactPanel } from '@aparte/plugin-artifacts/panel';
declare const chat: HTMLElement;
declare const panel: AparteArtifactPanel;
declare const dialog: HTMLDialogElement; // the panel is inside it
connectArtifactPanel({
chat,
panel,
onOpen: () => dialog.showModal(),
onClose: () => dialog.close(),
});Your own buttons
Section titled “Your own buttons”Write one child with slot="actions". It sits in the header before Close, and it is left
where you wrote it, so a framework that owns it keeps owning it.
<aparte-artifact-panel for="chat">
<div slot="actions">
<button class="aparte-btn aparte-btn--sm" type="button" id="export">Export</button>
</div>
</aparte-artifact-panel>import type { AparteArtifactPanel } from '@aparte/plugin-artifacts/panel';
declare const panel: AparteArtifactPanel;
declare function exportAsPdf(title: string, markdown: string): void; // yours
document.querySelector('#export')?.addEventListener('click', () => {
const version = panel.shownVersion; // the version on screen, or null
if (version) exportAsPdf(version.title ?? 'Document', version.content);
});
// Whenever what the panel shows changes, the first document included.
panel.addEventListener('aparte-artifact-version-change', (event) => {
const { documentId, version, total } = event.detail;
console.info(documentId, `${version} of ${total}`);
});import { useRef } from 'react';
import { useAparteEvent } from '@aparte/react';
import type { AparteArtifactPanel } from '@aparte/plugin-artifacts/panel';
declare function exportAsPdf(title: string, markdown: string): void; // yours
export function DocumentPanel() {
const panel = useRef<AparteArtifactPanel>(null);
// Whenever what the panel shows changes, the first document included.
useAparteEvent(panel, 'aparte-artifact-version-change', (event) => {
const { documentId, version, total } = event.detail;
console.info(documentId, `${version} of ${total}`);
});
const exportShown = () => {
const version = panel.current?.shownVersion; // the version on screen, or null
if (version) exportAsPdf(version.title ?? 'Document', version.content);
};
return (
<aparte-artifact-panel ref={panel} for="chat">
<div slot="actions">
<button className="aparte-btn aparte-btn--sm" type="button" onClick={exportShown}>Export</button>
</div>
</aparte-artifact-panel>
);
}<script setup lang="ts">
import { ref } from 'vue';
import type { AparteArtifactPanel } from '@aparte/plugin-artifacts/panel';
declare function exportAsPdf(title: string, markdown: string): void; // yours
const panel = ref<AparteArtifactPanel>();
function exportShown() {
const version = panel.value?.shownVersion; // the version on screen, or null
if (version) exportAsPdf(version.title ?? 'Document', version.content);
}
</script>
<template>
<!-- Whenever what the panel shows changes, the first document included. -->
<aparte-artifact-panel
ref="panel"
for="chat"
@aparte-artifact-version-change="({ detail }) => console.info(detail.documentId, `${detail.version} of ${detail.total}`)"
>
<div slot="actions">
<button class="aparte-btn aparte-btn--sm" type="button" @click="exportShown">Export</button>
</div>
</aparte-artifact-panel>
</template><script lang="ts">
import type { AparteArtifactPanel } from '@aparte/plugin-artifacts/panel';
declare function exportAsPdf(title: string, markdown: string): void; // yours
let panel: AparteArtifactPanel;
function exportShown() {
const version = panel.shownVersion; // the version on screen, or null
if (version) exportAsPdf(version.title ?? 'Document', version.content);
}
</script>
<!-- Whenever what the panel shows changes, the first document included. -->
<aparte-artifact-panel
bind:this={panel}
for="chat"
onaparte-artifact-version-change={({ detail }) => console.info(detail.documentId, `${detail.version} of ${detail.total}`)}
>
<div slot="actions">
<button class="aparte-btn aparte-btn--sm" type="button" onclick={exportShown}>Export</button>
</div>
</aparte-artifact-panel>On Svelte 4, write the event as on:aparte-artifact-version-change={…}.
import { Component, CUSTOM_ELEMENTS_SCHEMA, ElementRef, viewChild } from '@angular/core';
import type { AparteArtifactPanel } from '@aparte/plugin-artifacts/panel';
declare function exportAsPdf(title: string, markdown: string): void; // yours
@Component({
selector: 'app-document-panel',
standalone: true,
schemas: [CUSTOM_ELEMENTS_SCHEMA],
template: `
<!-- Whenever what the panel shows changes, the first document included. -->
<aparte-artifact-panel #panel for="chat" (aparte-artifact-version-change)="changed($any($event).detail)">
<div slot="actions">
<button class="aparte-btn aparte-btn--sm" type="button" (click)="exportShown()">Export</button>
</div>
</aparte-artifact-panel>
`,
})
export class DocumentPanelComponent {
private readonly panel = viewChild.required<ElementRef<AparteArtifactPanel>>('panel');
changed({ documentId, version, total }: { documentId: string; version: number; total: number }) {
console.info(documentId, `${version} of ${total}`);
}
exportShown() {
const version = this.panel().nativeElement.shownVersion; // the version on screen, or null
if (version) exportAsPdf(version.title ?? 'Document', version.content);
}
}To hide a built-in button, hide it: the panel is light DOM.
aparte-artifact-panel [data-action='download'] {
display: none;
}Draw one kind yourself
Section titled “Draw one kind yourself”import type { AparteArtifactPanel } from '@aparte/plugin-artifacts/panel';
declare const panel: AparteArtifactPanel;
declare function tableFrom(csv: string): HTMLElement; // yours
panel.render = (version, container) => {
if (version.artifactType !== 'csv') return false; // everything else: the built-in rendering
container.replaceChildren(tableFrom(version.content));
return true;
};Return false to hand a version back, true once you drew it, or a function the panel calls
before it draws something else.
Documents from your own store
Section titled “Documents from your own store”import type { ArtifactDocument, ArtifactVersion } from '@aparte/plugin-artifacts';
import type { AparteArtifactPanel } from '@aparte/plugin-artifacts/panel';
declare const panel: AparteArtifactPanel;
declare const saved: { id: string; title: string; markdown: string }; // yours
const version: ArtifactVersion = {
documentId: saved.id,
index: 1,
author: 'user',
messageId: saved.id,
mimeType: 'text/markdown',
artifactType: 'markdown',
title: saved.title,
content: saved.markdown,
};
const mine: ArtifactDocument = { id: saved.id, title: saved.title, versions: [version], latest: version };
panel.documents = [mine]; // null goes back to the conversationAn agent with its own tool
Section titled “An agent with its own tool”An agent that writes documents with a tool of its own (write_report) is read through read,
on the panel and on artifactDocuments() alike. It is called for every segment; null leaves
the segment to the default reading.
import type { AparteArtifactPanel } from '@aparte/plugin-artifacts/panel';
declare const panel: AparteArtifactPanel;
panel.read = (segment) => {
if (segment.type !== 'tool_call' || segment.toolCall.name !== 'write_report' || segment.status !== 'resolved') return null;
const input = segment.toolCall.input as { name: string; body: string };
return { documentId: 'report', mimeType: 'text/markdown', title: input.name, content: input.body };
};Without the panel
Section titled “Without the panel”The panel is one reader of the documents. Your own needs two things: the card’s
aparte-artifact-open, which says which document and which appearance of it, and
artifactDocuments().
import type { AparteChatViewport } from '@aparte/core';
import { artifactDocuments, setupArtifacts } from '@aparte/plugin-artifacts';
declare const viewport: AparteChatViewport;
declare function showInMyPane(title: string, content: string, version: number, total: number): void; // yours
setupArtifacts({ open: true });
document.addEventListener('aparte-artifact-open', (event) => {
const { documentId, segmentId } = event.detail;
const doc = artifactDocuments(viewport.getMessages()).find((d) => d.id === documentId);
const version = doc?.versions.find((v) => v.segmentId === segmentId) ?? doc?.latest;
if (doc && version) showInMyPane(doc.title ?? '', version.content, version.index, doc.versions.length);
});Reading width and typography
Section titled “Reading width and typography”A Markdown document is shown rendered, for reading, at --aparte-artifact-panel-measure
(72ch). Its text wears the same prose recipe as a reply, so the prose variables apply:
aparte-artifact-panel {
--aparte-artifact-panel-measure: 46rem;
--aparte-prose-h1-size: 1.75em;
--aparte-prose-p-margin: 0.6em 0;
}A page or a component is the model’s code. It is shown as source and runs only when the reader presses Preview, as on the card.
Ask before a document is changed
Section titled “Ask before a document is changed”create_artifact is a tool, so the approval policy rules on it. A
call that passes an id changes a document that exists:
import { aparteGlobalConfig } from '@aparte/core';
aparteGlobalConfig.setApprovalPolicy((call) =>
call.name === 'create_artifact' && call.input['id'] ? { verdict: 'ask' } : undefined,
);With a server loop
Section titled “With a server loop”The documents are read from the conversation, which is in the page. With
createAparteAgentHandler, call setupArtifacts() in the page and do
not declare create_artifact on the server: the same tool on both sides is refused.
In a framework
Section titled “In a framework”@aparte/plugin-artifacts/panel exports artifactPanelElement, the element’s spec, and every
framework binds it as it binds any plugin’s element: createAparteElement(artifactPanelElement)
in React, whose props then include render, read and documents; the tag typed from the spec in
Vue and Svelte; CUSTOM_ELEMENTS_SCHEMA in Angular, where [render] sets the property. The class is exported as
AparteArtifactPanel.
<aparte-artifact-panel> · class AparteArtifactPanel
Attributes
| Attribute | Description |
|---|---|
for | The id of the chat whose documents are shown: <aparte-chat>, its viewport, or any element with getMessages(). Or set the chat property. |
document-id | Which document. Absent: the one the conversation touched last. |
version | Which version, from 1. Absent: the latest, and the panel follows new ones. |
label | The panel’s accessible name while it shows no title of its own. |
data-empty | Written BY the element while there is no document to show: it then draws nothing. Read-only; style or fold your layout against it. |
Properties
| Property | Type | Description |
|---|---|---|
chat | ArtifactPanelSource | null | The chat whose documents are shown, when it has no id for the for attribute: an element, or anything with getMessages(). |
documents | readonly ArtifactDocument[] | null | The documents to show, when they are not read from a conversation: an app that keeps its documents in its own store gives them here. null goes back to the conversation. |
read | ArtifactDocumentsOptions['read'] | Passed to artifactDocuments: read a document out of a segment the plugin does not know (an agent’s own tool). |
tools | readonly string[] | undefined | Passed to artifactDocuments: the names of the plugin’s tools, when the app renamed them. |
render | ArtifactPanelRender | null | Draw a version yourself: see ArtifactPanelRender. null goes back to the built-in rendering. |
shownDocument (readonly) | ArtifactDocument | null | The document shown, or null while the panel is empty. |
shownVersion (readonly) | ArtifactVersion | null | The version shown, or null while the panel is empty. |
Methods
| Method | Description |
|---|---|
readDocuments(): readonly ArtifactDocument[] | Every document the panel can show now, the one the conversation touched last coming last. |
show(documentId: string, options: { version?: number; segmentId?: string }): void | Show a document: its latest version, a version by number, or the version a card in the conversation draws (segmentId, as aparte-artifact-open gives it). |
focusTitle(): void | Move focus to the panel’s title: what a caller does after opening the panel. |
refresh(): void | Read the conversation again and draw what it says. Called on its own as the conversation changes. |
Events
| Event | Type | Description |
|---|---|---|
aparte-artifact-panel-close | CustomEvent | The Close button, or Escape inside the panel. The panel does not hide itself: the app owns the layout. Bubbles. |
aparte-artifact-version-change | CustomEvent<ArtifactVersionChangeEventDetail> | What the panel shows changed, the first document it shows included: { documentId, version, total }. Bubbles. |
aparte-link-click | CustomEvent<AparteLinkClickEventDetail> | A link in the document is about to be followed. Sent on the chat (for or chat; the panel itself when it names none), as a message sends its own, so the listener that routes a reply’s links routes these. Cancelable: preventDefault() keeps the browser from navigating. A link of yours in the header is yours, and not announced. |
CSS variables
| Variable | Default | Description |
|---|---|---|
--aparte-artifact-panel-measure | 72ch | The line length of a Markdown document shown for reading. |
Accessibility
Section titled “Accessibility”- The panel is a region named by the document’s title; with no document it draws nothing.
- Opening it from a card moves the focus to the title. Closing gives the focus back to the button that opened it, or to the composer when it opened by itself.
- Escape inside the panel closes it.
- The version arrows are buttons named “Previous version” and “Next version”; the group says
“Version 2 of 3”. The strings are the
previousVersion,nextVersion,artifactVersionandcloseArtifactlocale keys.
Related
Section titled “Related”- Artifact — the card in the reply, the tool and the tag.
- Split — two panes; it moves between one pane and two.
- Approval mode — which tool calls ask first.