{
  "schemaVersion": 1,
  "target": "react",
  "name": "checkpoint",
  "version": "0.1.1",
  "category": "ai-elements",
  "title": "Checkpoint",
  "description": "A marker in a conversation that it can be restored to: a hairline divider with a label, the time, and a Restore action that asks for confirmation.",
  "tags": [
    "ai",
    "agent",
    "checkpoint",
    "restore",
    "undo",
    "conversation",
    "divider"
  ],
  "requires": {
    "projectTypes": [
      "next",
      "vite-react"
    ],
    "styling": "tailwind-v4"
  },
  "npmDependencies": {},
  "registryDependencies": [
    {
      "name": "button",
      "version": "0.2.1"
    },
    {
      "name": "popover",
      "version": "0.2.2"
    }
  ],
  "docsPath": "/components/checkpoint",
  "props": [
    {
      "name": "label",
      "type": "ReactNode",
      "default": "\"Checkpoint\"",
      "description": "What the checkpoint marks."
    },
    {
      "name": "time",
      "type": "Date | string",
      "description": "A Date renders as a local time in a <time> element; a string is shown as is."
    },
    {
      "name": "onRestore",
      "type": "() => void | Promise",
      "description": "Restores to this point. A promise keeps the confirm button busy; the confirmation closes on success and shows an error if it rejects. Without it, no action is shown."
    },
    {
      "name": "confirm",
      "type": "boolean",
      "default": "true",
      "description": "Asks in a small popover before restoring."
    },
    {
      "name": "confirmTitle / confirmDescription",
      "type": "ReactNode",
      "description": "Text of the confirmation. The default description names the time."
    },
    {
      "name": "current",
      "type": "boolean",
      "default": "false",
      "description": "This is the state the conversation is in now; the action reads \"Current\"."
    },
    {
      "name": "disabled",
      "type": "boolean",
      "default": "false",
      "description": "Disables the action, for example while the agent runs."
    }
  ],
  "accessibility": [
    "The row is a group labeled \"Checkpoint: <label>\"; the divider lines are decorative.",
    "Restore opens a Base UI Popover that moves focus inside, closes with Escape, and returns focus to the trigger. It has a title and description wired to aria-labelledby and aria-describedby.",
    "While restoring, the confirm button is aria-busy and keeps its width; a failure is announced with role=\"alert\".",
    "With reduced motion the popover appears without scale."
  ],
  "states": [
    "idle",
    "confirming",
    "restoring",
    "failed",
    "current"
  ],
  "files": [
    {
      "path": "agent/checkpoint.tsx",
      "content": "\"use client\";\n\nimport { type ComponentProps, type ReactNode, useState } from \"react\";\nimport { Button } from \"../ui/button\";\nimport { Popover, PopoverClose, PopoverContent, PopoverDescription, PopoverTitle, PopoverTrigger } from \"../ui/popover\";\n\nfunction cx(...classes: Array<string | false | null | undefined>) {\n  return classes.filter(Boolean).join(\" \");\n}\n\nexport interface CheckpointProps extends Omit<ComponentProps<\"div\">, \"children\" | \"role\"> {\n  /** What the checkpoint marks, for example \"Before the schema change\". @default \"Checkpoint\" */\n  label?: ReactNode;\n  /** When the checkpoint was taken. A Date shows as a local time (\"14:32\") in a `<time>` element. */\n  time?: Date | string;\n  /**\n   * Restores the conversation to this point. Return a promise to keep the confirm button busy\n   * until it settles; the confirmation closes when it resolves and stays open if it rejects.\n   * Without it, no restore action is shown.\n   */\n  onRestore?: () => void | Promise<unknown>;\n  /** Asks before restoring. @default true */\n  confirm?: boolean;\n  /** Heading of the confirmation. @default \"Restore this checkpoint?\" */\n  confirmTitle?: ReactNode;\n  /** Body of the confirmation. Defaults to a sentence naming the time, if there is one. */\n  confirmDescription?: ReactNode;\n  /** Marks this checkpoint as the state the conversation is in now; the action reads \"Current\". */\n  current?: boolean;\n  /** Disables the restore action, for example while the agent is still running. */\n  disabled?: boolean;\n}\n\nfunction formatTime(time: Date | string | undefined) {\n  if (time == null) return null;\n  if (typeof time === \"string\") return { text: time, iso: undefined };\n  return {\n    text: time.toLocaleTimeString(undefined, { hour: \"2-digit\", minute: \"2-digit\" }),\n    iso: time.toISOString(),\n  };\n}\n\n/**\n * A marker between messages that the conversation can go back to: a hairline divider with a\n * label, the time, and a Restore action that asks for confirmation first.\n */\nexport function Checkpoint({\n  label = \"Checkpoint\",\n  time,\n  onRestore,\n  confirm = true,\n  confirmTitle = \"Restore this checkpoint?\",\n  confirmDescription,\n  current = false,\n  disabled = false,\n  className,\n  ...props\n}: CheckpointProps) {\n  const [open, setOpen] = useState(false);\n  const [busy, setBusy] = useState(false);\n  const [failed, setFailed] = useState(false);\n  const stamp = formatTime(time);\n\n  async function restore() {\n    if (!onRestore) return;\n    setFailed(false);\n    const result = onRestore();\n    if (!(result instanceof Promise)) {\n      setOpen(false);\n      return;\n    }\n    setBusy(true);\n    try {\n      await result;\n      setOpen(false);\n    } catch {\n      setFailed(true);\n    } finally {\n      setBusy(false);\n    }\n  }\n\n  const action = cx(\n    \"inline-flex h-7 shrink-0 cursor-pointer items-center gap-1.5 rounded-md px-2 text-xs font-medium\",\n    \"text-zinc-600 transition-[background-color,color,scale] duration-150 ease-out active:duration-100 motion-safe:active:scale-[0.97] motion-reduce:transition-none\",\n    \"hover:bg-zinc-950/[0.04] hover:text-zinc-950 data-[popup-open]:bg-zinc-950/[0.06] data-[popup-open]:text-zinc-950\",\n    \"dark:text-zinc-400 dark:hover:bg-white/[0.06] dark:hover:text-white dark:data-[popup-open]:bg-white/[0.09] dark:data-[popup-open]:text-white\",\n    \"focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-sky-500\",\n    \"disabled:pointer-events-none disabled:opacity-45\",\n  );\n\n  const description =\n    confirmDescription ??\n    (stamp\n      ? `The conversation and its file changes go back to how they were at ${stamp.text}. Messages after that are removed.`\n      : \"The conversation and its file changes go back to this point. Messages after it are removed.\");\n\n  return (\n    <div\n      role=\"group\"\n      aria-label={typeof label === \"string\" ? `Checkpoint: ${label}` : \"Checkpoint\"}\n      data-current={current || undefined}\n      className={cx(\"flex w-full min-w-0 items-center gap-3 text-xs\", className)}\n      {...props}\n    >\n      <span aria-hidden=\"true\" className=\"h-px min-w-4 flex-1 bg-zinc-950/10 dark:bg-white/10\" />\n      <span className=\"flex min-w-0 items-center gap-2\">\n        <BookmarkIcon current={current} />\n        <span className=\"min-w-0 truncate text-zinc-600 dark:text-zinc-400\">{label}</span>\n        {stamp ? (\n          <time dateTime={stamp.iso} className=\"shrink-0 font-mono text-[11px] text-zinc-500 tabular-nums\">\n            {stamp.text}\n          </time>\n        ) : null}\n      </span>\n      {current ? (\n        <span className=\"inline-flex h-7 shrink-0 items-center px-2 text-xs font-medium text-zinc-500\">Current</span>\n      ) : onRestore ? (\n        confirm ? (\n          <Popover\n            open={open}\n            onOpenChange={(next) => {\n              if (busy) return;\n              setOpen(next);\n              if (next) setFailed(false);\n            }}\n          >\n            <PopoverTrigger disabled={disabled} className={action}>\n              <RestoreIcon />\n              Restore\n            </PopoverTrigger>\n            <PopoverContent side=\"top\" sideOffset={6} className=\"w-76 p-4\">\n              <PopoverTitle>{confirmTitle}</PopoverTitle>\n              <PopoverDescription className=\"mt-1\">{description}</PopoverDescription>\n              {failed ? (\n                <p role=\"alert\" className=\"mt-3 rounded-lg border border-red-500/35 bg-red-500/[0.08] px-3 py-2 text-sm text-red-700 dark:text-red-300\">\n                  The checkpoint could not be restored. Try again.\n                </p>\n              ) : null}\n              <div className=\"mt-4 flex justify-end gap-2\">\n                <PopoverClose disabled={busy} render={<Button variant=\"secondary\" size=\"sm\" />}>\n                  Cancel\n                </PopoverClose>\n                <Button size=\"sm\" loading={busy} onClick={restore}>\n                  Restore\n                </Button>\n              </div>\n            </PopoverContent>\n          </Popover>\n        ) : (\n          <button type=\"button\" disabled={disabled} onClick={() => void onRestore()} className={action}>\n            <RestoreIcon />\n            Restore\n          </button>\n        )\n      ) : null}\n      <span aria-hidden=\"true\" className=\"h-px min-w-4 flex-1 bg-zinc-950/10 dark:bg-white/10\" />\n    </div>\n  );\n}\n\nfunction BookmarkIcon({ current }: { current: boolean }) {\n  return (\n    <svg\n      aria-hidden=\"true\"\n      viewBox=\"0 0 16 16\"\n      fill=\"none\"\n      stroke=\"currentColor\"\n      strokeWidth={1.5}\n      strokeLinejoin=\"round\"\n      className={cx(\"size-3.5 shrink-0 transition-colors duration-200 motion-reduce:transition-none\", current ? \"text-zinc-950 dark:text-white\" : \"text-zinc-400 dark:text-zinc-500\")}\n    >\n      <path d=\"M4.5 2.75h7v10.5L8 10.75l-3.5 2.5Z\" className={current ? \"fill-current\" : undefined} />\n    </svg>\n  );\n}\n\nfunction RestoreIcon() {\n  return (\n    <svg aria-hidden=\"true\" viewBox=\"0 0 16 16\" fill=\"none\" stroke=\"currentColor\" strokeWidth={1.5} strokeLinecap=\"round\" strokeLinejoin=\"round\" className=\"size-3.5 shrink-0\">\n      <path d=\"M3 8a5 5 0 1 0 1.5-3.55\" />\n      <path d=\"M3 2.75v2.5h2.5\" />\n    </svg>\n  );\n}\n"
    }
  ],
  "example": {
    "content": "\"use client\";\n\nimport { useState } from \"react\";\nimport { Checkpoint } from \"@/components/shaken/agent/checkpoint\";\n\nexport default function CheckpointExample() {\n  const [restored, setRestored] = useState(false);\n  return (\n    <div className=\"grid w-full max-w-lg gap-4 text-sm\">\n      <p className=\"ml-auto max-w-[80%] rounded-xl bg-zinc-950/[0.04] px-3.5 py-2 text-zinc-950 dark:bg-white/[0.06] dark:text-white\">\n        Rename the users table to accounts and update the queries.\n      </p>\n      <Checkpoint\n        label=\"Before the table rename\"\n        time=\"14:32\"\n        current={restored}\n        onRestore={() => new Promise((resolve) => setTimeout(resolve, 900)).then(() => setRestored(true))}\n      />\n      {restored ? (\n        <button\n          type=\"button\"\n          onClick={() => setRestored(false)}\n          className=\"justify-self-start rounded-md text-xs text-zinc-500 underline decoration-zinc-500/40 underline-offset-4 hover:text-zinc-950 focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-sky-500 dark:hover:text-white\"\n        >\n          Show the example again\n        </button>\n      ) : (\n        <p className=\"leading-relaxed text-zinc-950 dark:text-white\">\n          Renamed the table in a new migration and updated 14 queries across 6 files. The tests pass.\n        </p>\n      )}\n    </div>\n  );\n}\n"
  }
}
