# Document panel

> A conversation's document beside the chat — the version the model just wrote, the ones before it, and its code, preview, copy and download.

[A document beside the chat, with its versions](/preview/demo/artifact-panel/)

```html
<!-- 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](/components/artifact/). `<aparte-artifact-panel>` shows the same document where you put it: the other pane of a [split](/components/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.

## Usage

[Section titled “Usage”](#usage)

```bash
npm install @aparte/plugin-artifacts @aparte/core
```

* Vanilla

  ```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')!,
  });
  ```

* React

  In a `.tsx` file the panel’s tag is a compile error until you declare it once:

  ```ts
  import type { DetailedHTMLProps, HTMLAttributes } from 'react';

  declare module 'react' {
    namespace JSX {
      interface IntrinsicElements {
        'aparte-artifact-panel': DetailedHTMLProps<HTMLAttributes<HTMLElement>, HTMLElement> & { for?: string };
      }
    }
  }
  ```

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

* Vue

  ```vue
  <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>
  ```

* Svelte

  ```svelte
  <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>
  ```

* Angular

  ```ts
  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”](#open-it-by-itself)

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

### Documents and versions

[Section titled “Documents and versions”](#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.

* Vanilla

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

* React

  ```tsx
  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
  }
  ```

* Vue

  ```vue
  <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>
  ```

* Svelte

  ```svelte
  <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 />
  ```

* Angular

  ```ts
  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”](#customize)

### Another layout

[Section titled “Another layout”](#another-layout)

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

### Your own buttons

[Section titled “Your own buttons”](#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.

* Vanilla

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

* React

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

* Vue

  ```vue
  <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>
  ```

* Svelte

  ```svelte
  <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={…}`.

* Angular

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

```css
aparte-artifact-panel [data-action='download'] {
  display: none;
}
```

### Draw one kind yourself

[Section titled “Draw one kind yourself”](#draw-one-kind-yourself)

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

### Documents from your own store

[Section titled “Documents from your own store”](#documents-from-your-own-store)

```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 with its own tool

[Section titled “An agent with its own tool”](#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.

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

### Without the panel

[Section titled “Without the panel”](#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()`.

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

### Reading width and typography

[Section titled “Reading width and typography”](#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:

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

### Ask before a document is changed

[Section titled “Ask before a document is changed”](#ask-before-a-document-is-changed)

`create_artifact` is a tool, so the [approval policy](/components/approval-mode/) 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,
);
```

### With a server loop

[Section titled “With a server loop”](#with-a-server-loop)

The documents are read from the conversation, which is in the page. With [`createAparteAgentHandler`](/guides/server-loop/), 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”](#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](/frameworks/elements/#your-own-element-or-a-plugins): `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`.

## API

[Section titled “API”](#api)

`<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”](#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`, `artifactVersion` and `closeArtifact` locale keys.

## Related

[Section titled “Related”](#related)

* [Artifact](/components/artifact/) — the card in the reply, the tool and the tag.
* [Split](/components/split/) — two panes; it moves between one pane and two.
* [Approval mode](/components/approval-mode/) — which tool calls ask first.
