Guide syntax

A guide is plain text, one step per line, written the way a colleague would explain the flow over your shoulder. Screen Browser turns each line into a browser action, writes the narration and the effects from the quoted sentences, and finds each step's target on the live page.

• Auth guide: the login flow only. Runs first, is never recorded, and uses {USERNAME} and {PASSWORD} placeholders whose values come from the project's encrypted variables.
• Main guide: the walkthrough that becomes the video. Runs after the login gate passes.

Steps

Precise forms for when a step needs them: Click the element with test id "save-button" (data-testid), Click selector #wp-submit (CSS, for ids and name= attributes only).

Rules that keep guides working

• Name things the way a person sees them. Buttons by their text, fields by their label or placeholder, menu items by their words. These survive rebuilds and work on apps nobody has inspected.
• Never use class names a build tool generated (css-1x9f2k, sc-bdVaJa, _1a2b3c). They change on every deploy and the validator refuses them.
• Start with Go to https://… and add a Confirm … line after every navigation or save, so a broken flow stops early and free.
• Keep secrets out. Never type a real password or token; use {VARIABLE}.
• Dismiss first-visit dialogs as optional steps at the top of the guide: If visible, click "Accept".
• Make it repeatable. If a step creates something, name it uniquely or delete it at the end.
• One feature per video, ten to twenty-five steps. Videos are capped at five minutes.

Narration and effects

A quoted sentence on its own line, or [CAPTION "…"], is what the narrator says at that moment and what the caption shows. Put one every one to three steps. Effects are [NAME …] tokens on the line before the step they decorate:

[CAPTION "text"]                      caption and narration
[TOAST "text"]                        small notification bubble
[HIGHLIGHT "text=Save"]               ring around an element; also label=, role=button:Save, name=, placeholder=, testid=, id=
[DIM 0.35]                            darken everything except the highlight
[ZOOM "text=Save" 1.6] / [ZOOM_OUT]   zoom towards an element
[TOOLTIP "text" on="label=Email" placement=bottom]
[ANNOTATION "text=Save|Label"]        a label pinned to an element
[ARROW from="text=A" to="text=B"]
[BLUR "label=Card number"]            blur sensitive content
[CURSOR "text=Save"]                  move the cursor there
[SCROLL_INTO_VIEW "text=Save"]
[STEP_NUMBER 2 of 6]
[CHAPTER "Title" duration_ms=1800]
[HEADLINE "Title" duration_ms=1800 size=lg]
[THEME info]                          overlay colour theme; [THEME] resets
[CONFETTI 1500]
[SPEED 2.0]                           playback speed until [SPEED 1.0]
[FREEZE 1.0]                          hold the frame
[FADE_OUT 600] / [FADE_IN 600]
[PAUSE 0.8]                           pause the narration
[CLEAR_OVERLAYS]

Which effects a plan includes is on the Effects page. Point effects at elements the same human way as steps, never at a generated class name.

How a step finds its element

In order: the text, label, placeholder, role and name you wrote; then what the recorder remembered from an earlier run of this guide; then, when nothing matches, the best fit on the page for what the step means. What it finds is remembered on the guide version, so the next run is repeatable. The run page and the editor show what was learned, and you can pin a target by hand.