# Checkpoint

Marks a point in the conversation you can return to.

Source: https://webjs.dev/ui/docs/ai-elements/checkpoint

```ts
import { html } from '@webjsdev/core';
import { cn } from '#lib/utils/cn.ts';
import { bubbleClass, bubbleContentClass } from '#components/ui/bubble.ts';
import { buttonClass } from '#components/ui/button.ts';
import { markerClass, markerContentClass } from '#components/ui/marker.ts';
import { messageClass, messageContentClass } from '#components/ui/message.ts';

function user(text: string) {
  return html`
    <div data-slot="message" data-align="end" class=${messageClass()}>
      <div data-slot="message-content" class=${messageContentClass()}>
        <div data-slot="bubble" data-variant="muted" data-align="end" class=${bubbleClass({ variant: 'muted' })}>
          <div data-slot="bubble-content" class=${bubbleContentClass()}>${text}</div>
        </div>
      </div>
    </div>
  `;
}

function agent(text: string) {
  return html`
    <div data-slot="message" data-align="start" class=${messageClass()}>
      <div data-slot="message-content" class=${messageContentClass()}>
        <p>${text}</p>
      </div>
    </div>
  `;
}

// The whole conversation. The checkpoint after the first turn offers Restore,
// since there are later turns to drop. Restoring is the reader's to wire.
export default function CheckpointDemo() {
  return html`
    <div class="flex min-h-72 w-full max-w-sm flex-col gap-4 py-6 text-sm">
      ${user('Rename the button component to action.')}
      ${agent('Renamed Button to Action in components/ui/button.tsx.')}
      <div data-slot="marker" data-variant="separator" class=${markerClass({ variant: 'separator' })}>
        <span data-slot="marker-content" class=${cn(markerContentClass(), 'inline-flex items-center gap-2')}>
          Button renamed
          <button type="button" aria-label="Restore to Button renamed" data-slot="button" data-variant="outline" data-size="xs" class=${buttonClass({ variant: 'outline', size: 'xs' })}>
            Restore
          </button>
        </span>
      </div>
      ${user('Update the docs to match.')}
      ${agent('Updated the Button page to say Action.')}
    </div>
  `;
}
```

Checkpoint is a point in the conversation you can return to. It is a [Marker](https://webjs.dev/ui/docs/components/marker) after a turn, with a Restore button. Restore keeps that turn and drops every message after it.

## Installation

Checkpoint is built with the [Marker](https://webjs.dev/ui/docs/components/marker) and [Button](https://webjs.dev/ui/docs/components/button) components.

```bash
npx @webjsdev/ui add marker button
```

### Install the following dependencies:

```bash
npx @webjsdev/ui add marker button
```

### Copy and paste the following code into your project.

````ts title="components/ui/marker.ts"
/**
 * Marker: a small inline note in a stream of content, such as "Today" between
 * chat messages or "Edited" under a post, with an optional icon. Tier-1
 * class helper; compose with a plain element.
 *
 * shadcn parity:
 *   Marker (variant: default | separator | border)
 *                    → markerClass({ variant }), alias markerVariants
 *   MarkerIcon       → markerIconClass()
 *   MarkerContent    → markerContentClass()
 *
 * The `separator` variant draws a rule on both sides of the content, and
 * `border` underlines the whole marker. Set `data-variant` to the variant you
 * pass, which is what the content's centring keys on.
 *
 * A11y (required for accessible output): a marker is text, so it needs no
 * role. When it announces a change in a live log (a date divider inside a
 * chat), it is read in order with the messages around it, which is usually
 * right. Hide a purely decorative icon with `aria-hidden="true"`.
 *
 * Design tokens used: --muted-foreground, --foreground, --border.
 *
 * @example
 * ```html
 * <div class=${markerClass({ variant: 'separator' })} data-variant="separator">
 *   <span class=${markerContentClass()}>Today</span>
 * </div>
 * ```
 */
import { cn } from '../lib/utils.ts';

const BASE = "min-h-4 gap-2 text-start text-sm text-muted-foreground [&_svg:not([class*='size-'])]:size-4 [a]:underline [a]:underline-offset-3 [a]:hover:text-foreground group/marker relative flex w-full items-center";

const VARIANTS = {
  default: '',
  separator: 'before:me-1 before:h-px before:min-w-0 before:flex-1 before:bg-border after:ms-1 after:h-px after:min-w-0 after:flex-1 after:bg-border',
  border: 'border-b border-border pb-2',
} as const;

export type MarkerVariant = keyof typeof VARIANTS;

/** The marker row. Pair with `data-variant` set to the same variant. */
export function markerClass(opts: { variant?: MarkerVariant } & { className?: string } = {}): string {
  return cn(BASE, VARIANTS[opts.variant ?? 'default'], opts.className);
}

/**
 * shadcn's name for {@link markerClass}, so shadcn code ports verbatim. Like
 * cva, it merges a `className` into the result.
 */
export function markerVariants(opts: { variant?: MarkerVariant } & { className?: string } = {}): string {
  return markerClass(opts);
}

/** The leading icon. */
export function markerIconClass(): string {
  return "size-4 [&_svg:not([class*='size-'])]:size-4 shrink-0";
}

/** The marker's text. */
export function markerContentClass(): string {
  return 'group-data-[variant=separator]/marker:flex-none group-data-[variant=separator]/marker:text-center *:[a]:underline *:[a]:underline-offset-3 *:[a]:hover:text-foreground min-w-0 wrap-break-word';
}
````

### Update the import paths to match your project setup.

## Usage

Render a marker after the turn, with a button that restores it.

```ts
<div data-slot="marker" data-variant="separator" class=${markerClass({ variant: 'separator' })}>
  <span data-slot="marker-content" class=${cn(markerContentClass(), 'inline-flex items-center gap-2')}>
    ${label}
    <button type="button" data-slot="button" data-variant="outline" data-size="xs" class=${buttonClass({ variant: 'outline', size: 'xs' })} @click=${() => this.restore(messageId)}>
      Restore
    </button>
  </span>
</div>
```

See [Marker](https://webjs.dev/ui/docs/components/marker#separator).

## AI SDK

Restore replaces the thread with the messages up to and including that turn. Every later turn is removed. Send a new message to continue from there.

```ts
restore(messageId: string) {
  const index = this.messages.findIndex((message) => message.id === messageId);
  this.messages = this.messages.slice(0, index + 1);
}
```

`messages` is your component's own state, a reactive property or a signal. Restoring is a change in the browser only. If the server keeps the thread, call a `'use server'` action to drop the later turns there too.

## AI SDK Helper

Write the checkpoint as a data part on the agent's turn, from the `'use server'` action that streams the reply. Send the same `id` again only when you mean to update that checkpoint. See [AI SDK](https://webjs.dev/ui/docs/helpers/ai-sdk) for streaming the parts to a component.

```ts
'use server';

export async function* renameButton() {
  yield { type: 'text', text: 'Renamed Button to Action in components/ui/button.tsx.' };
  yield {
    type: 'data-checkpoint',
    id: 'rename',
    data: { label: 'Button renamed' },
  };
}
```

Render the marker after the turn whose parts hold one:

```ts
const checkpoint = message.parts.find((part) => part.type === 'data-checkpoint');
```

## Migrating from AI SDK Elements

If you used Checkpoint from [AI SDK Elements](https://elements.ai-sdk.dev), its wrapper lives in `components/ai-elements/checkpoint.tsx`. In a WebJs app it becomes this pattern, built from WebJs UI components. Each export of the wrapper maps onto a part:

| AI SDK Elements | WebJs UI |
| --- | --- |
| `Checkpoint` | A marker with `markerClass({ variant: 'separator' })` and a marker content, in place of a Separator. |
| `CheckpointIcon` | A marker icon, `markerIconClass()`. |
| `CheckpointTrigger` | A button with `buttonClass({ variant: 'outline', size: 'xs' })`, like "Restore". For its tooltip, wrap it in a [`<ui-tooltip>`](https://webjs.dev/ui/docs/components/tooltip). |
