# Tutorial plan

> **Retired — the subsystem is gone (2026-09-03).** The choreographer
> (`src/choreography/`), the tutorial reader, library and player
> (`src/tutorial/`), the Learn segment and the shipped `.bwx` walkthroughs
> were all deleted: reaching a professional finish on a synthesized
> depiction was more work than the feature was worth. R55's "a document step
> lands in sight" survives on a far smaller derivation — `src/spotlight.rs`
> unions the footprints of the entities a commit's ops name, aims the camera
> at that region and rings it. Kept as the record of what was tried.

> **Partly superseded (2026-08-31, choreographer playbook 7·12).** The
> level catalogue below remains the content plan, but the engine
> prerequisites (the A/B/C machinery) and every KDL/script mechanic are
> gone: a tutorial is a `.bwx` container authored per
> `docs/tutorial-levels.md`, and only three levels were ever built and
> converted (`fixtures/tutorials/`). Level 19's KDL-export beats are dead
> with the format (D13/D14).


The tutorial set for the editor: the full feature surface, grouped into
eighteen multi-step levels ordered by importance. Each level bundles the
gestures that occur together in real work, so the user spends real time
driving the application instead of clicking through one-gesture flash cards.
The target size is 4–7 steps per level and roughly 60–120 seconds of demo per
loop.

More, smaller levels also pay off in testing: every level replays to a golden,
so a broken gesture points at one short level instead of somewhere inside a
long one. When a level below feels overloaded while authoring, split it — the
grouping is logical, not a size constraint.

## Engine prerequisites

The script vocabulary today is `highlight`, `move-to`, `hover`, `click` /
`double-click`, `drag`, `type`, `pause`, `camera`, addressing toolbar tools,
objects (`bN`, `bN:pM`, ports, corners), and grid cells. Three extensions
unlock the full set below; each is noted where a level needs it. A (camera
glide) and B (`command` step) are implemented; C is on `todo.md`. B's limits:
commands needing app machinery — clipboard, undo/redo, export/import, the
pickers — are not scriptable yet, so levels 13–14 stay text-only on those
beats for now.

- **A. Camera glide** — `camera … secs=1.5` interpolating from the current
  view to the framed rect (today `camera` is an instantaneous cut). This is
  how wheel-zoom and drag-pan are demonstrated: the *view* performs the
  motion while the instruction text names the physical gesture. Unlocks
  level 10.
- **B. Command step** — `command "<id>"`, riding the planned command
  registry/palette (todo.md): every overlay action, menu entry, and keyboard
  shortcut resolves to a named command, and the script dispatches the same
  command the palette or chord would. The cue layer highlights the on-screen
  button carrying that command id (or the palette entry) so the demo still
  *points at* the affordance it invokes. One step subsumes what would
  otherwise be separate overlay-target and key-synthesis features. Unlocks
  or improves levels 2, 6, 7, 9, 11–16.
- **C. Scripted file pick** — `pick-file "asset:<name>"`: the rfd dialog call
  sites (icon, new-image, import) route through one picker seam; a scripted
  session shows the stylized dialog card for the step's duration, then
  resolves the pending pick with a named asset compiled into the binary
  (include_bytes registry). The tutorial then genuinely attaches the icon /
  places the image / imports the document — no staging in the initial doc.
  Unlocks levels 17–18.

**Keyboard shortcuts** are not scriptable today because they never pass
through the script's seam: the lowering emits pointer `Event`s plus a typing
channel into `Interaction`, while app shortcuts (undo/redo, copy/paste,
nudge) are consumed straight from egui's raw input in `App::ui`. Prerequisite
B fixes this at the right layer — scripts invoke the *command*, not the
keystroke — and the instruction text names the chord.

**The file-dialog card**: one generic, deliberately stylized "file dialog"
SVG bundled with the app, not per-platform screen grabs. Win/mac/Linux BMPs
triple the maintenance, go stale with every OS release, and still won't match
the user's actual environment (KDE vs GNOME alone) — the honest generic card
with "your platform's file picker opens here" ages better, and the same card
serves live users as the `pick-file` placeholder in every demo.

## Gesture inventory, by importance

Tier 1 — without these the editor is unusable:

1. **Select tool basics** — click to select; drag to move; corner handles to
   resize; Delete on the overlay.
2. **Creating blocks** — New Block, both gestures (press-drag-release, or
   click opposite corners); the name editor opens itself; Escape cancels.
3. **Naming** — double-click any label (title, block type, pin name/type,
   route label, text box) opens its in-place editor.
4. **Routing** — Route tool pin-to-pin; routes find their own path.

Tier 2 — the everyday vocabulary:

5. **Visual affordances** — pointing-hand over editables, route highlight on
   hover, the blue new-pin markers, the green route-start target, ghost
   previews, alignment guides while dragging.
6. **Pins** — add via markers, move along the edge, rename/retype, I/O
   direction, delete.
7. **Route editing** — waypoints, rip-up-and-reroute, labels, route color.
8. **Ports** — click- or drag-to-size on the boundary.
9. **View navigation** — wheel zoom, drag-pan, double-click-to-fit, the
   navigator panel.
10. **Hierarchy** — enter a block, edit inside, go up; navigation history.

Tier 3 — control and scale:

11. **Locking** — freezing a block's interface, and everything that freezes
    with it.
12. **Multi-select** — marquee, group move/delete, pin-group marquee.
13. **Clipboard** — copy/cut/paste of shapes and pin groups.
14. **Undo/redo** — buttons and shortcuts; spans navigation too.
15. **Flips and tags** — mirror a block's pins L/R, flip U/D, tag visibility.

Tier 4 — presentation and interchange:

16. **Object color** — the accent swatch picker on any role-bearing object.
17. **Themes** — gear menu: light/dark mode, six theme families, fonts,
    widget zoom.
18. **Icons, images, backgrounds** — block icons, free images, magnetic
    alignment, backdrop graphics.
19. **Export/import** — SVG/PNG/PDF; the embedded diagram inside
    exported SVG/PNG that round-trips a full editable document.

## The eighteen tutorials

### 1. Your first blocks

- Pick New Block; press-drag-release a block; the name editor opens — type a
  name, Enter.
- Still in New Block: click one corner, click the opposite corner; name this
  one too.
- Escape abandons a half-placed block (text mention).

### 2. Select, move, resize

- Click a block to select it; drag it to a new spot.
- Drag a corner handle to grow it; note the 4-cell minimum width.
- Delete the spare block (overlay Delete — prerequisite B, else text).

### 3. Names and labels

- Double-click a block title; rename it.
- Double-click the block-type slot; give the block a type.
- Drag the title, then the type label, to reposition them within the block.

### 4. Reading the canvas

A hover tour of the affordances — almost entirely `hover` steps, fully
scriptable today:

- Hover a title: the pointing hand says "double-click edits this". Same over
  a pin name and a route.
- Hover a route: it highlights end to end.
- Select a block, hover near an edge: the blue new-pin markers fade in and
  the nearest one grows.
- Hover a pin's stub: the green route-start target grows.
- Drag a block slowly past a neighbor: alignment guides flash as edges and
  centers line up.

### 5. Making wires

- Pick Route; drag from one pin to another — the wire steers around the block
  in the way.
- Make the next route click-click instead of dragging.
- Back in Select: hover a pin until the green target grows, drag a route
  straight from it — no tool switch.
- End that route on a blue new-pin marker: the destination pin is minted as
  part of the route.

### 6. Shaping wires

The rest of the routing story: edit, label, color, delete. If this runs long
while authoring, split labels/color/delete into "Dressing wires".

- Select a route; drag a segment sideways — the waypoint pins it there.
- Rip-up-and-reroute from the overlay to clear the waypoints (B).
- Add a label (B); type its name; drag it along the route.
- Open the route's accent swatch and recolor it (B).
- Delete the route (B).
- Text mention: a block's overlay can rip up and reroute *every* wire on
  that block at once.

### 7. Pins

- Select a block; click a blue marker to add a pin; add another on the
  opposite side.
- Pick Add Pin: every unlocked block shows its markers at once; click one to
  add a pin without selecting the block first.
- Drag a pin along its edge to reposition it.
- Double-click its name to rename; double-click its type to retype.
- Set its direction with the I/O picker (B).
- Delete a pin via the overlay (B).

### 8. Ports

- Pick Add Port; click to place a boundary port.
- Drag-place a second, wider one — the drag sets width, the height is fixed.
- Wire a port to a block pin with the Route tool.
- Rename it like anything else: double-click.

### 9. Flips and tags

- Select a block; Flip L/R mirrors its pins to the opposite sides (B).
- Flip U/D reverses the vertical order (B).
- Toggle a tag's visibility from the overlay (B).
- Show the same Flip L/R on a boundary port.

### 10. Getting around

Requires prerequisite A; the view performs each motion while the text names
the gesture.

- Camera glides in tight on one block: "scroll to zoom, about the cursor".
- Camera sweeps sideways: "drag empty canvas to pan".
- Double-click empty canvas: the view fits the drawing (scriptable today).
- Open the hierarchy (tree icon); click a block in the tree — the canvas frames
  it, selected. Search jumps by name; the arrows retrace your path (B).

### 11. Inside a block

- Select the block; Enter descends into it (B, or double-click if the block
  is empty enough to make that unambiguous — verify while authoring).
- Add a small child block inside; wire it to a boundary port.
- Go up a level (B); the parent shows the block unchanged from outside.
- Text mention: undo also retraces navigation.

### 12. Locking

Locking is a mode change, not a tweak — it gets its own level. Start with a
finished, wired block.

- Lock the block from its overlay (B).
- Hover where the new-pin markers were: nothing appears — the interface is
  frozen.
- Show the I/O picker and pin Delete are gone; Add Port refuses while a
  locked context holds the boundary.
- Show what still works: move the block, recolor it, rename its title.
- Unlock; the markers return.

### 13. Clipboard and bulk edits

- Marquee two blocks on empty canvas; drag the group to move it rigidly.
- Copy the group and paste it (B); the copy lands selected — drag it aside;
  the text names Ctrl+C / Ctrl+V.
- Marquee just a run of pins: a pin group — copy and paste it onto another
  block's edge (B).
- Delete the group.
- Text mention: shift-marquee extends an existing selection.

### 14. Undo and redo

- Undo the deletion from the previous beat (B; the text names Ctrl+Z) — the
  group returns.
- Redo (B) — gone again. Undo once more to keep it.
- Enter a block, edit inside, go up, then undo: the edit unwinds *and* the
  view returns to where the edit happened.
- Text mention: Ctrl+Z / Ctrl+Shift+Z / Ctrl+Y from the keyboard; arrow keys
  nudge the selection one cell.

### 15. Object color

- Select a block; open its accent swatch (B); pick a color.
- Same picker on a port and an area — every role-bearing object carries
  one.
- Show two blocks in different accents surviving a theme change (segue to
  16).

### 16. Themes and appearance

Gear-menu entries dispatch as commands (B).

- Open the gear menu: Mode — flip dark to light and back.
- Theme submenu: step through two of the six families; accents and canvas
  re-derive, the diagram is untouched.
- Font submenu: switch the canvas font; Zoom submenu: widget size.

### 17. Icons, images, and backgrounds

Requires C: `pick-file` completes the real flow with bundled assets.

- Select a block; press Add Icon (B); the dialog card shows, then
  `pick-file "asset:chip-icon"` attaches a real icon to the block.
- Add Image on the toolbar; drag a frame; same card, then a bundled image
  lands in it.
- Drag the image near a block: it snaps magnetically to alignment features
  (free shapes aren't grid-bound).
- A large, faint image dragged behind the diagram serves as a backdrop —
  place, resize by corner, then select and move blocks over it.

### 18. Sharing your work

- Export menu: SVG, PNG, PDF (B for menu targets, else text).
- The point that deserves its own beat: an exported SVG/PNG *contains the
  diagram* — import the picture (dialog card + `pick-file` on a bundled
  export, C) and a full editable document pastes in at the cursor, not a
  flat image.
- Import a plain image for contrast (C): it lands as just an image.
- Text mention: a block's overlay can export that block as its own top-level
  document.

## Deliberately untutored

Developer-facing tooling (`--author`/`--replay`, `--trace`, the theme and
font editors) and the help menu. Everything user-facing above the fold is
covered by the eighteen.