Skip to content
Open

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.

bash
npm install @aparte/plugin-artifacts @aparte/core
html
<aparte-split position="40" single>
  <aparte-chat id="chat">…</aparte-chat>
  <aparte-artifact-panel for="chat"></aparte-artifact-panel>
</aparte-split>
ts
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')!,
});

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.

ts
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.

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.

ts
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
}

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.

The split is optional. Without it, show and hide the panel yourself:

ts
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(),
});

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.

html
<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>
ts
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}`);
});

To hide a built-in button, hide it: the panel is light DOM.

css
aparte-artifact-panel [data-action='download'] {
  display: none;
}
ts
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.

ts
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 conversation

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.

ts
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 };
};

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().

ts
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);
});

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:

css
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.

create_artifact is a tool, so the approval policy rules on it. A call that passes an id changes a document that exists:

ts
import { aparteGlobalConfig } from '@aparte/core';

aparteGlobalConfig.setApprovalPolicy((call) =>
  call.name === 'create_artifact' && call.input['id'] ? { verdict: 'ask' } : undefined,
);

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.

@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

AttributeDescription
forThe id of the chat whose documents are shown: <aparte-chat>, its viewport, or any element with getMessages(). Or set the chat property.
document-idWhich document. Absent: the one the conversation touched last.
versionWhich version, from 1. Absent: the latest, and the panel follows new ones.
labelThe panel’s accessible name while it shows no title of its own.
data-emptyWritten BY the element while there is no document to show: it then draws nothing. Read-only; style or fold your layout against it.

Properties

PropertyTypeDescription
chatArtifactPanelSource | nullThe chat whose documents are shown, when it has no id for the for attribute: an element, or anything with getMessages().
documentsreadonly ArtifactDocument[] | nullThe 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.
readArtifactDocumentsOptions['read']Passed to artifactDocuments: read a document out of a segment the plugin does not know (an agent’s own tool).
toolsreadonly string[] | undefinedPassed to artifactDocuments: the names of the plugin’s tools, when the app renamed them.
renderArtifactPanelRender | nullDraw a version yourself: see ArtifactPanelRender. null goes back to the built-in rendering.
shownDocument (readonly)ArtifactDocument | nullThe document shown, or null while the panel is empty.
shownVersion (readonly)ArtifactVersion | nullThe version shown, or null while the panel is empty.

Methods

MethodDescription
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 }): voidShow 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(): voidMove focus to the panel’s title: what a caller does after opening the panel.
refresh(): voidRead the conversation again and draw what it says. Called on its own as the conversation changes.

Events

EventTypeDescription
aparte-artifact-panel-closeCustomEventThe Close button, or Escape inside the panel. The panel does not hide itself: the app owns the layout. Bubbles.
aparte-artifact-version-changeCustomEvent<ArtifactVersionChangeEventDetail>What the panel shows changed, the first document it shows included: { documentId, version, total }. Bubbles.
aparte-link-clickCustomEvent<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

VariableDefaultDescription
--aparte-artifact-panel-measure72chThe line length of a Markdown document shown for reading.
  • 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, artifactVersion and closeArtifact locale keys.
  • 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.