# MolDraw interactive demos: authoring guide (for people and LLMs)

> Interactive demos show a MolDraw task step by step on a lightweight copy of
> the editor UI. A cursor moves to each control, clicks or types, and a caption
> explains the step. They replace screen-recorded videos: about 10 KB, sharp at
> any size, translatable, searchable, and editable as JSON.

## Files
- Player (one script, no dependencies): https://www.moldraw.com/demos/player.js
- JSON Schema (source of truth for every allowed value): https://www.moldraw.com/demos/schema.json
- Catalog of demos: https://www.moldraw.com/demos/index.json
- Gallery: https://www.moldraw.com/demos/
- Example demo: https://www.moldraw.com/demos/turn-on-grid.json
- Example article: https://www.moldraw.com/blog/how-to-turn-on-the-grid-in-moldraw.html

## Use a demo
On a moldraw.com page:
  <script src="/demos/player.js" defer></script>
  <moldraw-demo src="/demos/turn-on-grid.json"></moldraw-demo>

On another site (iframe; it reports its height with postMessage):
  <iframe src="https://www.moldraw.com/demos/embed.html?demo=turn-on-grid"
    title="MolDraw demo: Turn on the canvas grid" loading="lazy"
    style="width:100%;max-width:980px;height:640px;border:0"></iframe>
  Optional query: &theme=dark  &autoplay=false  &loop=false
  Auto-height: listen for message {type:"moldraw-demo:height", height} and set the iframe height.

Try it yourself: the player's "Try it yourself" button swaps the copy for the
real editor (loaded only on click, about 800 KB) at
  https://www.moldraw.com/embed?bridge=1&learn=1&tour=<id>
which runs a guided tour of the same steps: it rings the real control, shows
the caption, and moves on when the reader does the step. It runs in the course
sandbox, so the reader's own settings and designs are never changed. The same
`?tour=<id>` also works on the full editor (https://www.moldraw.com/?tour=<id>).
Real controls are found by selectors in src/app/tour/DemoTour.tsx (SELECTORS)
or a data-tour="<target>" attribute on the element; add one when a new demo
targets a control the tour cannot find yet.

Attributes of <moldraw-demo>: src, autoplay="false", loop="false", theme="light|dark|auto".
Keyboard: Left/Right arrows move between steps, Space plays or pauses.

## Write a demo
A demo is one JSON file named /demos/<id>.json. Shape:
{
  "$schema": "https://www.moldraw.com/demos/schema.json",
  "id": "kebab-case-id",
  "title": "Short task title",
  "description": "One or two sentences.",
  "article": "https://www.moldraw.com/blog/<article>.html",
  "initial": { ...state },
  "steps": [ { "title": "...", "text": "...", "target": "...", "action": "...", "set": { ...state } } ]
}

How a step plays: the player shows the state BEFORE the step, rings the target,
moves the cursor there, performs the action, then applies `set`, then waits.
So put the result of a click in that click step's `set`.

Device-specific steps: add "device": "desktop" or "touch" when the real UI
differs. Phones and touch tablets use MolDraw's compact layout (for example the
top-bar grid button is desktop-only; phones open Settings with the gear at the
top). The player shows only the steps for the viewer's device, so one demo
covers both.

Actions:
- none: caption only (use target "canvas" with "highlight": false for an overview).
- hover: cursor rests on target and shows its tooltip (or "tooltip").
- click: cursor clicks target, then `set` applies.
- type: types "input" into the command palette search box ("target": "palette.input").
- key: shows keyboard chips from "keys", e.g. ["Ctrl","K"], then `set` applies.

State keys (anything else is rejected): theme light|dark, grid, snap, guides,
arrowSnap, settingsOpen, paletteOpen, paletteQuery, paletteActive,
tool hand|select|erase|bond|ring|text|arrow, structure aspirin|benzene|phenol|ethanol|"",
toast (short status text; set "" to hide).

Targets: see the "target" enum in schema.json. Main ones:
topbar.grid, topbar.theme, topbar.search, toolbar.settings, toolbar.cleanup,
toolbar.undo, toolbar.download, rail.select, rail.bond, rail.ring, rail.arrow,
canvas, canvas.structure, settings.showGrid, settings.snapToGrid,
settings.guides, settings.snapCurvedArrows, settings.close, palette.input,
palette.result.0 (first search result), toast.
Command palette results come from: Show or hide grid, Snap to grid, Open settings,
Switch light or dark theme, Clean up structure, Zoom in, Fit drawing to view,
Download PNG, SVG, PDF.

## Writing rules
- Only describe what MolDraw really does. Check labels in the live editor.
- 4 to 12 steps. Titles under 60 characters, imperative ("Click the grid button").
- Captions: one or two short sentences, plain words, no jargon. **bold** names UI labels.
- Teach one task; show alternative routes (button, Settings, Ctrl+K) as later steps.
- End in a clean state (dialogs closed, toast cleared) so the loop restarts smoothly.
- Validate: node scripts/demos/check.cjs (checks every /demos/*.json against the schema).
- Add the demo to /demos/index.json and, if it has an article, embed it there with
  HowTo structured data that mirrors the step titles.

## Extending the UI copy
The UI copy lives in scripts/demos/player.src.js (SCENE, STYLES, apply()).
To support a new control: add its markup with a data-t="area.name" attribute,
add any new state key to DEFAULT_STATE and apply(), add the target / key to
public/demos/schema.json, then run node scripts/demos/build.cjs.