For the complete documentation index, see llms.txt. Markdown variants are available by appending .md to any URL or sending an Accept: text/markdown header. An agent skill is available at /.well-known/agent-skills/site-skill.md.
FrakmentFrakment

Checkpoint

Restore a conversation to any earlier point with data-checkpoint parts.

Rename the button component to action.

Renamed Button to Action in components/ui/button.tsx.

Button renamed
Update the docs to match.

Updated the Button page to say Action.

checkpoint-demo.tsx
"use client";

import { useChat } from "@ai-sdk/react";
import type { UIMessage } from "ai";
import { motion, useReducedMotion } from "motion/react";
import { Button } from "@/components/ui/button";
import { Marker, MarkerContent } from "@/components/ui/marker";
import {
  Bubble,
  BubbleContent,
  Message,
  MessageContent,
} from "@/components/ui/message";
import { createChat, getMessageText } from "@/lib/ai";
import { messageAnimations } from "@/lib/message-animations";

type ChatMessage = UIMessage<
  unknown,
  {
    checkpoint: {
      label: string;
    };
  }
>;

type CheckpointPart = Extract<
  ChatMessage["parts"][number],
  { type: "data-checkpoint" }
>;

const chat = createChat<ChatMessage>()
  .user("Rename the button component to action.")
  .assistant(({ writer }) => {
    writer.text("Renamed Button to Action in components/ui/button.tsx.");
    writer.data({
      data: { label: "Button renamed" },
      id: "rename",
      type: "data-checkpoint",
    });
  })
  .user("Update the docs to match.")
  .assistant(({ writer }) => {
    writer.text("Updated the Button page to say Action.");
  });

const transcript = chat.get();
const transport = chat.transport({ delayMs: 20 });

export function CheckpointDemo() {
  const { messages, sendMessage, setMessages, status } = useChat<ChatMessage>({
    messages: transcript,
    transport,
  });
  const shouldReduceMotion = useReducedMotion();
  const nextMessage = chat.next(messages);
  const busy = status === "submitted" || status === "streaming";

  function restore(messageId: string) {
    const index = messages.findIndex((message) => message.id === messageId);

    if (index === -1) {
      return;
    }

    setMessages(messages.slice(0, index + 1));
  }

  return (
    <div className="flex min-h-72 w-full max-w-sm flex-col gap-4 py-6 text-sm">
      {messages.map((message) => {
        const checkpoint = message.parts.find(
          (part): part is CheckpointPart => part.type === "data-checkpoint"
        );
        const index = messages.findIndex((item) => item.id === message.id);
        const canRestore = index < messages.length - 1;

        return (
          <motion.div
            animate={shouldReduceMotion ? undefined : "animate"}
            className="flex flex-col gap-4"
            initial={shouldReduceMotion ? undefined : "initial"}
            key={message.id}
            variants={messageAnimations["slide-up"].variants}
          >
            {message.role === "user" ? (
              <Message align="end">
                <MessageContent>
                  <Bubble align="end" variant="muted">
                    <BubbleContent>{getMessageText(message)}</BubbleContent>
                  </Bubble>
                </MessageContent>
              </Message>
            ) : (
              <Message>
                <MessageContent>
                  <p>{getMessageText(message)}</p>
                </MessageContent>
              </Message>
            )}
            {checkpoint && (
              <motion.div
                animate={shouldReduceMotion ? undefined : "animate"}
                initial={shouldReduceMotion ? undefined : "initial"}
                variants={messageAnimations.fade.variants}
              >
                <Marker variant="separator">
                  <MarkerContent className="inline-flex items-center gap-2">
                    {checkpoint.data.label}
                    {canRestore && (
                      <Button
                        aria-label={`Restore to ${checkpoint.data.label}`}
                        className="h-6 rounded-full px-2.5 text-xs"
                        onClick={() => restore(message.id)}
                        size="sm"
                        variant="outline"
                      >
                        Restore
                      </Button>
                    )}
                  </MarkerContent>
                </Marker>
              </motion.div>
            )}
          </motion.div>
        );
      })}
      {!busy && nextMessage && (
        <Button
          className="mt-auto self-start"
          onClick={() => sendMessage(nextMessage)}
          size="sm"
          variant="outline"
        >
          Continue
        </Button>
      )}
    </div>
  );
}

Checkpoint marks a point in a conversation that can be restored. It renders a data-checkpoint part as a separator marker with a restore action, and messages after that point are trimmed when the user clicks it.

Checkpoint is a composition — install the primitives, then wire them together the same way the demo does.

Installation

Usage

Emit a data-checkpoint part from the assistant turn. The part carries a label, which renders as a separator marker in the transcript.

chat.tsx
import { createChat } from "@frakment/ai";
import type { UIMessage } from "ai";
 
type ChatMessage = UIMessage<
  unknown,
  { checkpoint: { label: string } }
>;
 
const chat = createChat<ChatMessage>()
  .user("Rename the button component to action.")
  .assistant(({ writer }) => {
    writer.text("Renamed Button to Action.");
    writer.data({
      type: "data-checkpoint",
      id: "rename",
      data: { label: "Button renamed" },
    });
  });

Anatomy

checkpoint.tsx
<Message align="end">
  <MessageContent>
    <Bubble align="end" variant="muted">
      <BubbleContent>{userText}</BubbleContent>
    </Bubble>
  </MessageContent>
</Message>
 
<Message>
  <MessageContent>
    <p>{assistantText}</p>
  </MessageContent>
</Message>
 
<Marker variant="separator">
  <MarkerContent>
    {checkpoint.data.label}
    <Button size="xs" variant="outline" onClick={restore}>
      Restore
    </Button>
  </MarkerContent>
</Marker>
  • Message, Bubble — user and assistant turns.
  • Marker with variant="separator" — the visual checkpoint line.
  • Button — restore action, only shown when there is a later turn to trim.

Animation

Checkpoint rows animate through the same variants as chat messages.

checkpoint.tsx
import { MESSAGE_ANIMATIONS } from "@/lib/message-animations";
import { motion, useReducedMotion } from "motion/react";
 
const shouldReduceMotion = useReducedMotion();
 
<motion.div
  animate={shouldReduceMotion ? undefined : "animate"}
  initial={shouldReduceMotion ? undefined : "initial"}
  variants={MESSAGE_ANIMATIONS["slide-up"].variants}
>
  ...
</motion.div>

The checkpoint marker uses the fade variant, so it appears after the message it belongs to.

Restore semantics

restore(messageId) trims every message after the one that carried the checkpoint.

tsx
function restore(messageId: string) {
  const index = messages.findIndex((m) => m.id === messageId);
  if (index === -1) return;
  setMessages(messages.slice(0, index + 1));
}

The restore button hides when the checkpoint is already the last message. Send the next user turn to branch again from that point.

Next

  • Chat — full streaming chat surface.
  • Message — message row primitive.
  • Bubble — chat bubble surface.
  • Marker — separator and status line.
  • Button — restore action.

Accessibility

  • The checkpoint marker is a separator with a visible label. Provide aria-label on the restore button, e.g. "Restore to Button renamed".
  • Restore buttons are focusable and respond to Enter and Space.
  • When the checkpoint is the last message, restore is hidden to avoid a no-op for keyboard users.
  • Announce transcript length with role="status" if you track it elsewhere.

Best Practices

  • One checkpoint per logical step. Emit when the state is worth returning to.
  • Label with what changed. "Button renamed" beats "Checkpoint 3".
  • Hide restore on the last checkpoint. Nothing to trim means no button.
  • Combine with confirmation for destructive restores. Restoring over unsaved work should ask first.
  • Do not persist checkpoints across sessions. They belong to the current transcript.