Docs
Reference
Every attribute of the embed element, the five DOM events, the marker attributes, the CLI commands and their exit codes — the detail the task pages link out to.
Element attributes
Every option below works two ways: as data-* on the script tag, or as a bare attribute on <rendemo-demo> if you place the element yourself. data-mode and mode are the same thing.
Three attributes are observed — demo/src, open and user — meaning changing them after mount takes effect. Everything else is read once, at connect.
| Attribute | Values | Notes |
|---|---|---|
| demo · src | demo UUID, or workspace/slug | Required. Reactive — changing it after mount re-resolves: a live iframe’s src is swapped in place, or the still-showing poster is repointed. src is an alias, read only when demo is absent, so an element carrying both is never ambiguous. |
| mode | inline (default) · modal · tour | Read once. tour runs guidance on your own product instead of a replay: no iframe, no poster, no box — see Guide people through your app. guide is a silent alias for tour. |
| open | present / absent | Modal only — the host controls it. Reactive: toggling it after mount opens and closes the modal live. |
| poster | auto (default) · off | Read once. auto shows the demo’s still until the visitor starts it, which is what keeps an unstarted demo to one image. |
| ratio | 16:10 (default) · auto | Read once, except the poster’s load handler re-reads it once the image arrives. Any W:H sets a fixed aspect ratio immediately; auto defers to the poster’s intrinsic size. |
| locale | BCP-47 | Read once, and re-read whenever demo changes — both feed the same iframe-src resolution. Forwarded to the demo as a query param. |
| user | any opaque id | Tour only, optional. Keys progress by this id instead of by browser, and rides on the analytics events. Reactive. Ignored in inline/modal, where re-resolving would reload the iframe. Rendemo never resolves it to anybody; bounded at 64 characters. |
| routes | comma-separated paths | Tour only, optional. The pages this tour may run on at all. Read at mount, re-evaluated on every navigation. Absent means every page carrying the tag. |
| when | once (default) · always | Tour only, optional. always replays a tour the viewer already finished or dismissed, while still resuming a run in progress. An unrecognised value is once. |
DOM events
The element listens for messages from the framed demo (origin- and source-checked) and re-emits the matching ones as DOM CustomEvents. Five names, and only these five — this is the whole contract surface, and it does not grow casually.
| Event | Fires when | detail |
|---|---|---|
| rendemo:ready | The framed demo has finished loading and rendered its first frame. | A passthrough of whatever internal player state accompanied the message. Not a documented contract and can change shape without notice — treat it as a bare signal, not a source of fields to read. |
| rendemo:step | The visitor advances to a new step (once per transition, not per card re-render). | { id, n, total } — n is the 1-based step number the visitor is now on. |
| rendemo:complete | The visitor reaches the end of the demo. | {} — no fields. |
| rendemo:lead | A lead-capture form is submitted, either the in-card capture or the full-screen gate. | { where } — "card" or "gate". Deliberately no field values — no email, no name, nothing the visitor typed. Look the lead up server-side. Never fires for a tour. |
| rendemo:close | Modal only. Close button, backdrop click, or Escape — including Escape pressed inside the framed demo. | {} — no fields. A request to close, not a notification: the element does not close itself, and the host clears open in response. |
Marker attributes
Markers go on elements in your own source and are what a tour anchors to. Both spellings work everywhere, and a page may mix them.
| Attribute | Notes |
|---|---|
data-rd · data-rendemo | "<tour>/<step>" — each half a lowercase slug (letters, digits, hyphens; no leading or trailing hyphen). <tour> is the tour’s slug, chosen at creation and written to the published record verbatim, so committed markers and the published tour agree by construction. |
data-rd-do · data-rendemo-do | Optional. "click" | "type" | "hover" — what completes the step. Omitted means the step waits for an explicit Next. |
data-rd-wait · data-rendemo-wait | Optional. A selector that must exist before the step is reachable — for a precondition visibility cannot express, like a fetch settling. |
Only the marker is read at runtime
The overlay takes a step’sdo and wait from the published plan, never from the DOM. Those two attributes exist so an element states what its step does without a round trip to the studio — hand-editing them changes nothing. Change the step and republish.CLI commands
One dependency-free file, published on npm as rendemo. No install needed — npx rendemo <command>.
| Command | What it does |
|---|---|
check [path] | Verifies every lockfile step resolves to exactly one marker in source. Offline, no auth. The only one CI normally runs — see Keep tours from breaking. |
login | Prints a short code and a URL, you approve in a browser, and the token is stored in a per-user config file outside every checkout. The token is never printed. |
logout | Removes the stored token. |
doctor | Six lines: sign-in, workspace, tours, MCP server, MCP headers, version. Touches nothing and publishes nothing. |
token | Exists for the plugin’s headers helper and nothing else. It prints the literal credential, so do not run it to check whether you are signed in — use doctor. |
Exit codes
These are a CI contract. Nothing else about the output is.
| Code | Meaning |
|---|---|
| 0 | Succeeded. For check: every step resolved to exactly one marker. Can still print warnings — an unknown-flow warning means a tour in source is not described by the lockfile, so nothing about it is being checked. |
| 1 | The thing you asked for did not succeed: tour failures, a sign-in never approved, or a doctor run that found a blocker. |
| 2 | No lockfile found, or it is unreadable or invalid — or the command was invoked wrong. |
yaml
- run: npx rendemo check