# The browser editor

```bash
revealer talk.pres
```

Pointing `revealer` at a `.pres` file (or its folder) serves the deck with
rebuild-on-save and live reload, and layers a WYSIWYG editor on top of it
in the browser. The two workflows mix freely: type in your text editor,
click and drag in the browser — both write to the same file.

**You are always editing the `.pres` source file, never the HTML.** Every
change made in the browser is written to it immediately as a minimal text
edit (a session diffs like hand edits), the deck rebuilds, and the preview
reloads in place, keeping your slide, edit mode and selection. There is no
separate save step.

## The command bar

The chrome is **mode-aware**. In preview (not editing) the deck is untouched —
the only chrome is a small draggable **✏ Edit** pill (with a save-state dot) in
the corner. Press `E` or click it to start editing.

In edit mode a command bar pins to the top of the window and the deck docks
below it. Left to right: the **✏ Edit** toggle, a **slide chip** (`N · title`)
that drops the [slide filmstrip](#slide-selector), then a menubar:

| Menu | Items |
| --- | --- |
| **Insert** | **Media** — import an image or movie into `Media/` and insert it · **Fragments / animation** drawer (`F`). |
| **Slide** | **New slide…** — the [template gallery](#new-slide-templates) · **Slide selector** (`O`). |
| **History** | **Undo** / **Redo** (`Ctrl+Z` / `Ctrl+Shift+Z`) · **Version history** — the [time machine](#save-history). |
| **View** | **Split view** (deck left, panel right, draggable divider) · **Document source** — edit the `.pres` header block (title, author, logos, theme, …) that sits above the first slide, right in the panel. |
| **Export** | **Export HTML** / **PDF** — the final `talk.html` / `talk.pdf` next to the `.pres`. |
| **Help** | The help card. |

The status chip on the right names the `.pres` file being edited and reports
every save. In preview, drag the **✏ Edit** pill by its **⠿** grip to move it
off a slide title.

## Edit mode: selecting and inspecting

Press `E` (or click **✏ Edit**). Hovering names the element under the
cursor; clicking selects it. The **side panel** then shows everything about
the selection:

- with nothing selected, the **whole slide's source**, editable in place;
- a clickable **breadcrumb** (slide ▸ row ▸ column ▸ figure) to reach
  enclosing constructs — no guessing what you clicked; `Escape` also
  selects the parent;
- **parameter fields** — pin x/y/width, media height/width, row height and
  gap, column size, grid gap, fragment index, … — type a value and press
  `Enter`;
- **▲ Up / ▼ Down / 🗑 Delete** to reorder a block among its siblings or
  remove it (`Del` deletes the selection too — `Ctrl+Z` undoes);
- a **format bar** and a collapsible, clickable **command palette** —
  generated from the grammar, so it lists every construct; click an entry to
  drop its ready-to-fill skeleton at the cursor;
- the **source box**: the actual `.pres` lines of the selection, editable
  in place (*Apply source*) — anything the quick fields don't cover.

The panel docks to the side of the deck; **View ▸ Split view** switches to a
split layout with the deck on the left and the panel on the right, divider
draggable. In split view the slide is scaled to fit its space with its
aspect ratio preserved and a gray margin around it, so it is always clear
where the slide ends.

## Direct manipulation

- **Drag handles** move pins and resize media, rows, stacks and column
  splits (with fraction snapping — `2/5` stays `2/5`-shaped).
- The square **grip** drags a whole block into another column or slot.
- **Arrow keys** nudge the selection; `Shift` makes bigger steps.
- **Dropping** an image or movie file onto a column uploads it into
  `Media/` and inserts the matching `!` / `!!` line — same as **＋ Media**.

## Keyboard summary

| Key | Action |
| --- | --- |
| `E` | Toggle edit mode. |
| Click | Select the element under the cursor. |
| `Escape` | Select the enclosing construct (walk up the breadcrumb). |
| Arrow keys | Nudge the selection (`Shift` = bigger steps). |
| `Del` | Delete the selection. |
| `Ctrl+Z` / `Ctrl+Shift+Z` | Undo / redo. |
| `F` | Fragment drawer. |
| `O` | Outline sidebar. |

Shortcuts never fire while you are typing in a field or text box.

## Fragment drawer

`F` (or **Insert ▸ Fragments**) opens a drawer listing the current slide's
fragments — every `+`-flagged element (including `* +` bullets) and `> frag`
block — in reveal order. Drag entries to reorder the sequence; the
`data-fragment-index` flags in the source are rewritten accordingly.

## Slide selector

`O` (or the slide chip in the command bar, or **Slide ▸ Slide selector**) drops
a horizontal **filmstrip** of every slide below the command bar. From there you
can navigate and, per slide, **add**, **duplicate**, **reorder** and **delete**
— whole-slide operations that would be tedious as text edits.

## New-slide templates

Adding a slide — the **＋** on a filmstrip cell, or **Slide ▸ New slide…** —
opens a visual gallery of starter layouts (content, section divider, bulleted
list, two columns, image + caption, comparison, equation, grid, table, vertical
sub-slide and more). Pick one and its `.pres` skeleton is inserted right after
that slide.

(save-history)=

## Save history — the time machine

**History ▸ Version history** opens the save history. While the server runs, every
change to the `.pres` (from the browser *or* from your text editor) is
auto-committed to a shadow git repository inside the deck folder
(`.rv-history/` — invisible to your own git, no setup required):

- **Snapshot…** records a labelled snapshot ("before big rework");
- each entry offers **Diff** (what changed), **Peek** (a read-only preview
  of the deck as it was — the working file is untouched) and **Restore**;
- restoring first snapshots the current state, so nothing is ever lost, and
  **undo keeps working across restores**: `Ctrl+Z` after a restore brings
  you back.

Undo/redo itself is a cursor walking this same history, so it covers
browser edits *and* saves made in your text editor. If the file changed on
disk since the page's last sync, an edit is refused and the page resyncs —
nothing is ever overwritten blindly.

## Build errors

If a save produces a build error, the browser shows the error as an
overlay — with an *open in editor* button (uses `$REVEALER_EDITOR`, VS
Code's `code -g`, or `$EDITOR`) — while the last good version keeps being
served. Fix the line, save, and the deck reloads.

## Included files

Slides pulled in with `> include:` rebuild on save like the main file, but
are **read-only in the editor** — the panel names the file they come from;
open that file (or serve it directly) to edit them.

## Scope and safety

- The server binds to `127.0.0.1` only and serves a separate
  `<name>.dev.html` artifact, deleted on exit; the exported `<name>.html`
  is only written by `revealer build` or **Export ▸ HTML**.
- Every edit is guarded by a checksum of the file it was computed against;
  concurrent hand edits can never be clobbered.
- The editor layer exists only in dev builds — exported decks contain none
  of it.