# Version history

> Named, saved versions newest first, compared with today, restored after the current version is saved.

Source: https://kwark.space/designSystem/components/version-history

## Usage

### When to use
Wherever a person might want to go back: a character, a scene ("This scene, before"), a research notebook. Versions are named by the person ("Before the table read") or by the moment ("Draft sent to Arjun").

### When not to
- For issued production paperwork. A call sheet uses numbered revisions (Decision 0020) and a locked script uses colours ([Script revision diff](https://kwark.space/designSystem/components/script-revision-diff.md)).
- As an activity feed of every keystroke.

### Anatomy in use
- Header: *Saved versions* and *Newest first*.
- Rows: the name (13px 500), when and who in meta text. The one being compared is pressed and says *Comparing*.
- Compare: *Current* and *Saved version* in two columns.
- Restore: one primary, with the promise underneath.

### Writing
The promise is the point: *Your current version is saved first, so you can return to it.* Never "Are you sure? This cannot be undone", because it can.

**Do:** *Restore this version*, with the line saying the current version is saved first.

**Don't:** A red *Revert* button behind a confirmation dialog.

## Style

### Anatomy

List of full-width buttons, 14px × 10px padding, 1px bottom line, pressed row on 8% accent.

### Tokens

| Token | Light | Dark |
|---|---|---|
| `--k-line` | #e2e8f0 | rgba(255, 255, 255, .1) |
| `--k-text` | #0f172a | #e3e3e3 |
| `--k-text-2` | #5b6779 | #9ca3af |
| `--k-accent` | #98633f | #98633f |
| `--k-raise` | #f1f5f9 | #252525 |

## Code

### React

In the Kwark app: `import CharacterHistory from '@/pages/Understanding/CharacterModule/components/CharacterHistory'`.

```tsx
// Also: EditorModule/components/SceneHistory.tsx ("This scene, before")
<CharacterHistory character={character} onRestore={restore} />
```

| Prop | Type | Notes |
|---|---|---|
| `onRestore` | `(version) => void` | saves the current version first |

### HTML and CSS

Works anywhere with `kwark.css`.

```html
<div class="kw-history">
  <div class="kw-history__label"><span>Saved versions</span><span>Newest first</span></div>
  <div class="kw-history__list">
    <button class="kw-history__item" type="button" aria-pressed="true"><span><strong>Before the table read</strong><small>Today, 18:40 · Mira</small></span><span class="kw-history__now">Comparing</span></button>
    <button class="kw-history__item" type="button" aria-pressed="false"><span><strong>Draft sent to Arjun</strong><small>12 Nov, 09:15 · Mira</small></span></button>
    <button class="kw-history__item" type="button" aria-pressed="false"><span><strong>First full draft</strong><small>2 Nov, 22:03 · Mira</small></span></button>
  </div>
  <div style="display:flex;gap:8px;align-items:center;margin-top:16px"><button class="kw-button kw-button--primary" type="button">Restore this version</button><span class="kw-meta">Your current version is saved first, so you can return to it.</span></div>
</div>
```

## Accessibility

- Rows are toggle buttons (`aria-pressed`) choosing which version to compare.
- After restoring, announce "Restored *Before the table read*. Your previous version is saved as *Before restoring*."

## For agents

### Rules

- **Must** save the current version before restoring another.
- **Never** confirm a restore with a dialog; it is undoable.
- **Always** show who saved a version and when.

### AI readiness test

**Task:** Add scene history to the screenplay's scene menu.

**Give the agent:** Version history, Screenplay page.

**Constraint:** The scene may have been split since.

**A reliable answer:**
- Shows "This scene, before" versions
- Compare current and saved
- Restore saves current first
- Caveat if the scene was split
