demoman 0.8.0 → 0.8.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (75) hide show
  1. package/THIRD_PARTY_NOTICES +1 -1
  2. package/dist/demoman.mjs +19646 -13607
  3. package/dist/page/decode-probe-entry.js +23071 -0
  4. package/dist/page/executor-entry.js +102 -17
  5. package/dist/page/mux-entry.js +351 -107
  6. package/dist/page/render-entry.js +1931 -1147
  7. package/dist/recipe.md +248 -292
  8. package/dist/skills/record-demo/SKILL.md +5 -4
  9. package/dist/studio/assets/confirm-dialog-BGEp6bKH.css +1 -0
  10. package/dist/studio/assets/confirm-dialog-F4BR4FU0.js +72 -0
  11. package/dist/studio/assets/editor-63atCcDn.js +4 -0
  12. package/dist/studio/assets/{editor-inline-7e387eed.css → editor-inline-d74caea2.css} +10 -0
  13. package/dist/studio/assets/library-L3IU8F5q.js +1 -0
  14. package/dist/studio/assets/library-inline-3627d15c.css +1426 -0
  15. package/dist/studio/assets/settings-g3t2C3Eo.js +1 -0
  16. package/dist/studio/assets/{settings-inline-ff6d2eee.css → settings-inline-2f59fbb0.css} +12 -0
  17. package/dist/studio/assets/state-eyG4SxVq.js +1 -0
  18. package/dist/studio/assets/topbar-CgsXzkpk.js +1 -0
  19. package/dist/studio/assets/view-DzaxHB2c.js +1 -0
  20. package/dist/studio/editor.html +11 -10
  21. package/dist/studio/library.html +9 -8
  22. package/dist/studio/settings.html +8 -7
  23. package/dist/studio/studio-build.json +3 -3
  24. package/dist/studio/wallpapers/dark-1-landscape.webp +0 -0
  25. package/dist/studio/wallpapers/dark-1-portrait.webp +0 -0
  26. package/dist/studio/wallpapers/dark-1-thumb.webp +0 -0
  27. package/dist/studio/wallpapers/dark-2-landscape.webp +0 -0
  28. package/dist/studio/wallpapers/dark-2-portrait.webp +0 -0
  29. package/dist/studio/wallpapers/dark-2-thumb.webp +0 -0
  30. package/dist/studio/wallpapers/light-1-landscape.webp +0 -0
  31. package/dist/studio/wallpapers/light-1-portrait.webp +0 -0
  32. package/dist/studio/wallpapers/light-1-thumb.webp +0 -0
  33. package/dist/studio/wallpapers/light-2-landscape.webp +0 -0
  34. package/dist/studio/wallpapers/light-2-portrait.webp +0 -0
  35. package/dist/studio/wallpapers/light-2-thumb.webp +0 -0
  36. package/dist/studio/wallpapers/muted-1-landscape.webp +0 -0
  37. package/dist/studio/wallpapers/muted-1-portrait.webp +0 -0
  38. package/dist/studio/wallpapers/muted-1-thumb.webp +0 -0
  39. package/dist/studio/wallpapers/muted-2-landscape.webp +0 -0
  40. package/dist/studio/wallpapers/muted-2-portrait.webp +0 -0
  41. package/dist/studio/wallpapers/muted-2-thumb.webp +0 -0
  42. package/dist/studio/wallpapers/muted-3-landscape.webp +0 -0
  43. package/dist/studio/wallpapers/muted-3-portrait.webp +0 -0
  44. package/dist/studio/wallpapers/muted-3-thumb.webp +0 -0
  45. package/dist/studio/wallpapers/muted-4-landscape.webp +0 -0
  46. package/dist/studio/wallpapers/muted-4-portrait.webp +0 -0
  47. package/dist/studio/wallpapers/muted-4-thumb.webp +0 -0
  48. package/dist/studio/wallpapers/vivid-1-landscape.webp +0 -0
  49. package/dist/studio/wallpapers/vivid-1-portrait.webp +0 -0
  50. package/dist/studio/wallpapers/vivid-1-thumb.webp +0 -0
  51. package/dist/studio/wallpapers/vivid-2-landscape.webp +0 -0
  52. package/dist/studio/wallpapers/vivid-2-portrait.webp +0 -0
  53. package/dist/studio/wallpapers/vivid-2-thumb.webp +0 -0
  54. package/dist/studio/wallpapers/vivid-3-landscape.webp +0 -0
  55. package/dist/studio/wallpapers/vivid-3-portrait.webp +0 -0
  56. package/dist/studio/wallpapers/vivid-3-thumb.webp +0 -0
  57. package/dist/studio/wallpapers/vivid-4-landscape.webp +0 -0
  58. package/dist/studio/wallpapers/vivid-4-portrait.webp +0 -0
  59. package/dist/studio/wallpapers/vivid-4-thumb.webp +0 -0
  60. package/dist/studio/wallpapers/vivid-5-landscape.webp +0 -0
  61. package/dist/studio/wallpapers/vivid-5-portrait.webp +0 -0
  62. package/dist/studio/wallpapers/vivid-5-thumb.webp +0 -0
  63. package/dist/studio/wallpapers/vivid-6-landscape.webp +0 -0
  64. package/dist/studio/wallpapers/vivid-6-portrait.webp +0 -0
  65. package/dist/studio/wallpapers/vivid-6-thumb.webp +0 -0
  66. package/package.json +1 -1
  67. package/dist/studio/assets/confirm-dialog-Bcrw3f1a.js +0 -72
  68. package/dist/studio/assets/confirm-dialog-DSKBZQdV.css +0 -1
  69. package/dist/studio/assets/editor-DUZKtJ2T.js +0 -4
  70. package/dist/studio/assets/library-BPokDo6m.js +0 -1
  71. package/dist/studio/assets/library-inline-216fd6fd.css +0 -659
  72. package/dist/studio/assets/settings-RZj4oUzT.js +0 -1
  73. package/dist/studio/assets/state-tew-ACWl.js +0 -1
  74. package/dist/studio/assets/topbar-sSUyITjl.js +0 -1
  75. package/dist/studio/assets/view-SxAupNyx.js +0 -1
package/dist/recipe.md CHANGED
@@ -1,10 +1,10 @@
1
1
  # Recording a demo with Demoman
2
2
 
3
3
  You write a DemoScript. Demoman runs it in a browser of its own on
4
- this machine and saves the take on disk; `export` renders that take to an
4
+ this machine and saves the video on disk; `export` renders that video to an
5
5
  MP4. Every tool answers JSON. A refusal is an error result carrying
6
- `reason`, a stable identifier to branch on, and `detail`, a sentence to tell
7
- the user; section 7 lists every reason.
6
+ `reason`, a stable identifier to branch on, and `detail`, a sentence for the
7
+ user; section 7 lists every reason.
8
8
 
9
9
  ## 1. Preflight
10
10
 
@@ -14,81 +14,69 @@ the user; section 7 lists every reason.
14
14
  `secretsFile`, `expiry` and `update`.
15
15
  `sessions` is `[{site, savedAt, refreshedAt, signInUrl}]`; it and
16
16
  `display` can be `{unreadable}`: tell the user why. `accounts` and
17
- `secretsFile` are the demo accounts below. The browser starts on the
18
- first `snapshot`, `run` or `export`. Say nothing about `update`. When
19
- `browserInstalled` is false, the first `snapshot` or `run` answers
20
- `browserMissing`.
21
- 2. The browser is signed in wherever the user ran `npx demoman signin <url>`,
22
- and nowhere else; `status`'s `sessions` lists those sites. A demo account records best. A page
17
+ `secretsFile` are the demo accounts below.
18
+ 2. The browser is signed in only where the user ran `npx demoman signin <url>`
19
+ (`status.sessions` lists them). A demo account records best. A page
23
20
  that sends this browser to its sign-in page answers `signedOut` (section
24
21
  7) with the exact command in `detail`: give the user that command and
25
22
  spend no run until they say they have run it, unless a demo account can
26
23
  sign in (below). Only demo accounts: never ask for the
27
- user's own password, and never type it. A sign-in or sign-up demo is not
28
- signing in: when the user asks for one and gives you demo values, start
24
+ user's own password, or type it. A sign-in or sign-up demo is not
25
+ signing in: when the user asks for one and gives demo values, start
29
26
  the script at that form's page and type them; a password field's text is
30
- hidden on disk and in the report.
31
- 3. Takes are saved under `<DEMOMAN_HOME, default ~/.demoman>/takes/<id>/`.
32
- `takes` lists them, newest first: `id`, `name`, `createdAt`, `mode`,
33
- `actions`; an unreadable folder comes last as `{ id, unreadable }`.
34
- Demoman keeps no telemetry.
27
+ hidden on disk and in reports.
28
+ 3. Videos are saved under `<DEMOMAN_HOME, default ~/.demoman>/takes/<id>/`.
29
+ No telemetry.
35
30
 
36
31
  ### Behind a login: demo accounts
37
32
 
38
33
  `status.accounts` is one of:
39
34
 
40
35
  - `{file: null, searchedFrom}`: no `.demoman/accounts.json` was found from
41
- `searchedFrom` upward (`status` reads from the folder this server was
42
- started in and takes no `project`). Create one (below), or pass `project`
43
- on `snapshot` and `run`.
44
- - `{file, invalid, field}`: the file exists and cannot be used; `invalid` is
45
- why and `field` where. Fix it; every snapshot and run from that project
36
+ `searchedFrom` upward (`status` reads from the folder this server
37
+ started in and takes no `project`). Create one (below), or pass `project` on `snapshot`/`run`.
38
+ - `{file, invalid, field}`: the file cannot be used; `invalid` is why and
39
+ `field` where. Fix it; every snapshot and run from that project
46
40
  answers `accountsInvalid` until then.
47
41
  - `{file, sites}`: each site is `{origin, default, accounts}`, each account
48
42
  `{name, about, session}` with `session` `"saved"`, `"none"` or
49
43
  `"changed"` (saved before the account's `checkUrl` or `signIn` was
50
44
  edited). Both are fine: Demoman signs in.
51
- `sessionsUnreadable`, when present, says the saved sessions could not be
52
- read: tell the user.
45
+ `sessionsUnreadable`, when present: the saved sessions could not be read; tell the user.
53
46
 
54
47
  `status.sessions` lists an account's saved session with an `account` (and
55
- its `origin`) beside `site`; an entry without one is the site's manual
56
- session from `npx demoman signin <url>`.
48
+ `origin`) beside `site`; an entry without one is the site's manual session from
49
+ `npx demoman signin <url>`.
57
50
 
58
51
  `status.secretsFile` is `null` (no usable accounts file), `{path, absent:
59
52
  true}` (no secrets file: only `DEMOMAN_SECRET_*` can supply values),
60
53
  `{path, git: "ignored"}` (git ignores it: safe), `{path, git: "notGit"}`
61
- (not in git, so that could not be checked: tell the user), or `{path, refused}` (it cannot be read; `refused` is why,
54
+ (not in git, so unchecked: tell the user), or `{path, refused}` (unreadable; `refused` is why,
62
55
  as `secretsFileNotIgnored` or `secretsFileInvalid` will be). Never a value.
63
56
 
64
57
  A page behind a login answers `signedOut` and `status` shows no account for
65
- its site. Then, in this order:
58
+ its site. Then, in order:
66
59
 
67
60
  1. **Reuse first.** Read each account's `about` and pick the one that fits
68
- the demo. Name it in the script's `account`, or leave it out for the
69
- site's `default`.
61
+ the demo. Name it in the script's `account`, or omit it for the `default`.
70
62
  2. **The app's repo is open and runs against a local development database:**
71
63
  create a demo account and the data the demo needs, with a seed script
72
64
  committed in the app and safe to run twice (`priv/repo/demo_seeds.exs`,
73
65
  `db/seeds/demo.rb`). Generate a random password of 20 or more characters.
74
66
  Write `DEMOMAN_SECRET_<NAME>=…` and
75
67
  `DEMOMAN_SECRET_<NAME>_ORIGIN=<the site's origin>` to
76
- `.demoman/secrets.env`, and add
77
- `.demoman/secrets.env` to `.gitignore` if it is missing. Add the account
78
- to `accounts.json`. Tell the user in one line.
79
- Then `snapshot` again.
68
+ `.demoman/secrets.env`, and `.gitignore` it if missing. Add the
69
+ account to `accounts.json`, tell the user in a line, `snapshot` again.
80
70
  3. **Two-factor or a magic link in the way:** add a dev-only "sign in as"
81
71
  route, reachable only in development, and make the account's `signIn` one
82
72
  `goto` to it. Phoenix:
83
73
  `if Mix.env() == :dev, do: get "/dev/sign-in-as/:email", DevController, :sign_in`; Rails: the same under `Rails.env.development?`.
84
- The action starts a session; nothing else.
74
+ It starts a session only.
85
75
  4. **The database is not clearly local** (a remote `DATABASE_URL`, staging,
86
76
  production): create nothing. Ask the user, or give them
87
77
  `npx demoman signin <url>`, which signs in by hand in a window: it is the
88
78
  way for a real account, single sign-on and two-factor.
89
79
 
90
- Only demo accounts. Never put the user's own password in `secrets.env`.
91
-
92
80
  The file, with one account:
93
81
 
94
82
  ```jsonc
@@ -118,30 +106,25 @@ The file, with one account:
118
106
  digits, `-` and `_`, at most 64: `seller`. `signIn` uses the script's steps and targets
119
107
  (`type` names its field with `into`; copy targets from a `snapshot` of the
120
108
  login page) plus `goto`, which must be the first step. `checkUrl` is
121
- required: a page behind the login, a path on the origin, that a browser
122
- signed in to nothing cannot open (it redirects to sign-in, or shows a
123
- password form) and that shows no password field once signed in. Demoman
124
- opens it signed out first and treats where it lands as the sign-in page. `about` names who the account is and what data
125
- it has, so the next agent reuses it.
109
+ required: a path on the origin behind the login, which a browser signed
110
+ in to nothing cannot open (it redirects to sign-in, or shows a
111
+ password form) and which shows no password field once signed in. Demoman
112
+ opens it signed out first and treats where it lands as the sign-in page. `about` names who the account is and what data it has.
126
113
  - `{secret:NAME}` goes in a `signIn` step's `text`, `NAME` being
127
114
  `[A-Z0-9_]+`, not ending in `_ORIGIN`. Demoman reads
128
- `DEMOMAN_SECRET_NAME` from the environment, else the same line of
129
- `.demoman/secrets.env`, which it reads only when git ignores it. A value
115
+ `DEMOMAN_SECRET_NAME` from the environment, else `.demoman/secrets.env`
116
+ (only when git ignores it). A value
130
117
  is at least 8 characters, typed only with `DEMOMAN_SECRET_NAME_ORIGIN`
131
- beside it, naming the account's site. In the environment the user sets
132
- both and you never change them; in `secrets.env` you write both.
133
- A `{secret:…}` in a demo
134
- script is refused (`invalidScript`): secrets work only in `signIn`.
135
- Environment secrets serve only the accounts.json of the repo Demoman was
136
- started in; one reached through `project` reads only its own
137
- `.demoman/secrets.env`.
138
- - A script names its account: `"account": "seller"`, which needs
139
- scriptVersion 5 (`"scriptVersion": 5`). `snapshot` takes `account` too. Both take `project`,
140
- an absolute path, to use another checkout's `.demoman/`.
118
+ beside it, naming the account's site. The user sets both in the
119
+ environment and you never change them; in `secrets.env` you write both.
120
+ A `{secret:…}` in a demo script is refused (`invalidScript`).
121
+ Environment secrets serve only the accounts.json of the repo Demoman
122
+ started in; a `project` one reads only its own `.demoman/secrets.env`.
123
+ - A script names its account: `"account": "seller"`; so does `snapshot`. Both take `project`,
124
+ an absolute path, for another checkout's `.demoman/`.
141
125
 
142
126
  ```json
143
127
  {
144
- "scriptVersion": 5,
145
128
  "name": "Seller dashboard",
146
129
  "target": "http://localhost:4000/admin/dashboard",
147
130
  "account": "seller",
@@ -153,68 +136,65 @@ The file, with one account:
153
136
  ```
154
137
 
155
138
  - Demoman signs in by itself: when the account has no saved session, and
156
- once more when a call lands on a sign-in page. `signedIn`
157
- (`{account, steps, ms}`) in the snapshot or the report says it did. A
158
- second failure answers `signInFailed`. A session that lapses mid-run keeps
159
- no take; Demoman has signed in again: just run again.
139
+ once more when a call lands on a sign-in page; `signedIn`
140
+ (`{account, steps, ms}`) says it did. A second failure answers
141
+ `signInFailed`. A session that lapses mid-run keeps no video; Demoman has
142
+ signed in again: just run again.
160
143
 
161
144
  ## 2. Look at the page
162
145
 
163
- `snapshot(url)` opens `url` in Demoman's browser, lists the page's targets,
164
- and leaves the page open. Each entry is
165
- `{ target, kind, text, rect, inFirstViewport }`. Every `target` listed is one
166
- a run resolves to exactly that element: Demoman checked it.
167
-
168
- `snapshot` may answer `stillRunning` too: call `report(id)`.
146
+ `snapshot(url)` opens `url` in Demoman's browser and lists the page's
147
+ targets, leaving the page open. Each entry is
148
+ `{ target, kind, text, value, rect, shown, inFirstViewport }`. Every `target` resolves in a run to that element.
169
149
 
170
150
  - **Copy a `target` into a step verbatim. Never compose one**, and never
171
151
  translate a name from another tool's accessibility tree: Demoman's roles
172
152
  are not Chrome's.
173
153
  - `landedElsewhere: true` - the app redirected, often to its sign-in page;
174
154
  `landedUrl` says where. If it is a sign-in page, this browser is not
175
- signed in there: see `session` below and spend no run. If it is
176
- not a sign-in page (a trailing slash, `https`, a locale prefix), use
177
- `landedUrl` as the script's `target`, and this snapshot as it stands.
155
+ signed in there: see `session` below and spend no run. If it is not a sign-in page (a
156
+ trailing slash, `https`, a locale prefix), use `landedUrl` as the
157
+ script's `target`; this snapshot stands.
178
158
  `landedElsewhere: null` means the page's address could not be read: not an
179
159
  all-clear.
180
160
  - `session` - `"saved"`: a session is saved for this site; `"none"`: none
181
161
  is (normal for a public page); `"signedOut"`: the page is a sign-in page,
182
162
  and `sessionDetail` holds the command to give the user (spend no run, or
183
163
  set up a demo account: section 1);
184
- `"unchecked"`: the page could not be checked, and `sessionDetail` says
185
- why. A sign-in page offering only "Continue with Google" may
186
- not answer `signedOut`: a `landedUrl` that is plainly a sign-in page with
164
+ `"unchecked"`: `sessionDetail` says why. A sign-in page with only "Continue with Google" may
165
+ not answer `signedOut`: a plainly sign-in `landedUrl` with
187
166
  `"none"` or `"unchecked"` means the same. Tell the user to run
188
- `npx demoman signin <the page to record>` and spend no run. On
189
- `"unchecked"` otherwise, carry on only if `landedUrl` is not a sign-in
190
- page.
167
+ `npx demoman signin <the page to record>`; spend no run. Otherwise on
168
+ `"unchecked"`, carry on only if `landedUrl` is not a sign-in page.
191
169
  - `settled: false` - the page was still loading; `settleNote` says what was
192
- outstanding. Snapshot again before you conclude something is absent.
193
- - `rect` is in page coordinates; `inFirstViewport`: shown before any
194
- scroll. `rect: null` means the element has no box yet (a closed
195
- FAQ answer): still a valid target for `waitFor … until: "visible"` after
196
- the step that opens it.
170
+ outstanding. Snapshot again before concluding something is absent.
171
+ - `rect` is in page coordinates; `inFirstViewport`: in view before any
172
+ scroll. `rect: null`: no box yet (a closed FAQ answer), still a valid
173
+ `waitFor … until: "visible"` target after the step that opens it.
174
+ `shown: false`: transparent, hidden or a sliver now; `waitFor` waits.
197
175
  - `size` is `{ width, height, from, error }`: the size the page was laid out
198
- at, which a run records too. `from` is `screen` (this machine's screen),
176
+ at, as a run records. `from` is `screen` (this machine's screen),
199
177
  or `device`. `from: "window"` with an `error`: Demoman could not read the
200
178
  screen and listed the browser's smaller layout; tell the user the `error`.
201
- - `unresolvable` counts elements left out because no target names them
202
- uniquely (two buttons with one label, say). `notExamined` above 0 means the
203
- page had more than one answer holds: pass `contains` ("pay", "FAQ") to ask
204
- for the part you need; with it given, a positive count means narrow it
205
- further.
179
+ - `positional: true`: the target is a `treePath` (shared or no name); snapshot
180
+ again after the page changes. `value`: a field's text, never a password's.
181
+ `unresolvable`: no target reaches it. `notExamined` above 0: pass `contains`
182
+ (name, text, stableId, kind, value) to narrow. `containsNote`: no match.
206
183
  - Iframe and shadow-root elements are not listed.
207
- - A snapshot sees only the page as it loads: hidden content already in the
208
- page is listed; content a click creates (a dialog or menu built when it
209
- opens) is not, so a step on it has no target: tell the user it cannot be
210
- scripted yet. A page the flow navigates to has its own URL to snapshot.
184
+ - A snapshot sees only the page as it loads: hidden content in the
185
+ page is listed; content a click creates (a menu, dialog, results, a new row) is not. To list it, `probe` your script
186
+ cut off after the step that opens it, and copy targets from that answer. A probe acts on the app for real: "Add item" adds one per
187
+ probe and again in the run, so a unique target can turn ambiguous;
188
+ a delete deletes; in the Studio an edit saves into the video. Server data
189
+ carries into the run; browser storage does not (a signed-in site's does). Prefer demo data. `stopped`: a step did not play; fix it as a
190
+ run's stop with that reason says, and probe again.
211
191
 
212
192
  ### Recording a phone demo
213
193
 
214
194
  1. Call `snapshot` with `device` (`"phone"` or `"tablet"`), and
215
195
  copy targets from that answer only: a phone shows a different page, and a
216
196
  desktop target is often not on it.
217
- 2. `run` a script that names the same `device`, at `scriptVersion` 4.
197
+ 2. `run` a script that names the same `device`.
218
198
  3. Leave `look.canvas` at `auto`, which comes out portrait, or name `9:16`.
219
199
  4. No `hover` steps: tap instead.
220
200
 
@@ -225,20 +205,14 @@ a run resolves to exactly that element: Demoman checked it.
225
205
  1. `snapshot` the page the flow starts on.
226
206
  2. Write each step with a `target` copied from that snapshot.
227
207
  3. A step that reveals hidden content (a FAQ answer, a panel) names its
228
- targets from the same snapshot, followed by a `waitFor … until:
229
- "visible"`. A step that navigates: snapshot the new page's URL and put a
230
- `waitForLoad` after the step. A step on content a click creates: see
231
- section 2.
208
+ targets from the same snapshot, then a `waitFor … until: "visible"`. A step that navigates: snapshot the new page's URL and put a `waitForLoad` after it; the step after waits up to 10 s for its own target, so needs no `waitFor`. Content a click creates: section 2.
232
209
  4. `snapshot`'s `kits` lists the user's brand kits by name, the default
233
- marked. Use a name from it in `look.kit` only when the user asked for a
234
- look, and then write `"scriptVersion": 2` - a script that names a kit at
235
- version 1 is refused (`invalidScript`, `field` `scriptVersion`).
236
- `{ "ok": false, "reason": … }` means the kits could not be read: say so,
237
- and name none.
210
+ marked. Use one in `look.kit` only when the user asked for a look.
211
+ `{ "ok": false, "reason": … }`: kits unreadable; say so, name none.
238
212
 
239
- ### From a take made earlier
213
+ ### From a video made earlier
240
214
 
241
- `derive(takeId)` answers `{ report, script }`: the take's steps as a script
215
+ `derive(videoId)` answers `{ report, script }`: the video's steps as a script
242
216
  to change and run again.
243
217
 
244
218
  - `report.outcome: "derived"` - `script` is a draft, with `holes[]` and
@@ -247,74 +221,66 @@ to change and run again.
247
221
 
248
222
  | Hole `reason` | What to do |
249
223
  | --- | --- |
250
- | `scrubbedTarget` | `step` is null: the hole is the start URL. Demoman strips query values and secret-looking path segments from a take; `recorded` shows the page with `redacted` in their place. Set `target` to the real start URL - ask the user if you cannot tell. |
224
+ | `scrubbedTarget` | `step` is null: the hole is the start URL. Demoman strips query values and secret-looking path segments from a video; `recorded` shows `redacted` there. Set `target` to the real start URL - ask the user if unsure. |
251
225
  | `redacted` | Add `"text"` with a **demo** value, never a real credential. |
252
226
  | `unnameable`, `ambiguousAtCapture`, `brokenAtCapture` | Add the target, copied from a `snapshot` of that page. |
253
227
  | `buttonNotScriptable` | Delete `"button"` only if a left click is acceptable - it is a different action. Otherwise tell the user the step cannot be scripted. |
254
228
  | `hostField` | Deleting `"host"` makes the step **replace the whole rich-text editor's contents** on the live app. Ask the user first. |
255
229
 
256
- `notes[]` lists steps the take cut or trimmed; they are kept. A
230
+ `notes[]` lists steps the video cut or trimmed; they are kept. A
257
231
  `landingOffscreen` note names a scroll that will centre its element. **Keep each step's `recorded`, each
258
- scroll's `landing`, and the script's `recordedFrom`**: they are how the
259
- report compares the new run with the take. A step you add has no
260
- `recorded`.
261
- `report.skeleton` is what the merge with the take's saved script said:
232
+ scroll's `landing`, and the script's `recordedFrom`**: the report
233
+ compares the new run with the video by them. A step you add has no `recorded`.
234
+ `report.skeleton` is what merging with the video's saved script said:
262
235
  `noSkeleton` or `skeletonUnreadable` (the original's pauses were not
263
236
  kept), `stepDropped`, `actionAdded` (kept in place), `verbChanged` (the
264
237
  draft takes the verb in `scene.json` - check that step before running).
265
- - `takeNotFound` - no take has that id; call `takes`.
266
- - `unreadable` - a stored take cannot be read; report its `reason`.
238
+ - `videoNotFound` - no video has that id; `flows()` lists them.
239
+ - `unreadable` - a stored video cannot be read; report its `reason`.
267
240
  - `threw` - report its `error`.
268
241
 
269
- **Re-recording an edited take.** `run({ video: { id } })` with no `script`
270
- records the video's current version again from its saved script and current
271
- `scene.json` (steps, name, look, pauses, added steps), as a new version and a
272
- run toward the three. Refused with `unfilledHoles` when the take did not keep
273
- a value: `derive`, fill, `run`. `invalidScript` (`field` `steps.<i>.do`): a
242
+ **Re-filming an edited video.** `run({ flow: { id } })` with no `script`
243
+ re-films the flow's current video from its saved script and current
244
+ `scene.json` (steps, name, look, pauses, added steps), as a new video and a
245
+ run toward the three. Refused with `unfilledHoles` when the video kept no
246
+ value: `derive`, fill, `run`. `invalidScript` (`field` `steps.<i>.do`): a
274
247
  verb was changed by hand: `derive`, check it, `run` the draft.
275
248
 
249
+ A flow in the repo (.demoman/flows) is rewritten by each run: commit that file with the change. To add one, run `npx demoman add <flow> --to <path>` in the repo.
250
+
276
251
  ## 4. Run and read
277
252
 
278
- 0. Name the video first: every run adds a version to one. If the repo
279
- has an exported file of it, `videos({ file:
280
- <absolute path> })`. Else `videos({ query: "<what the flow shows>" })`;
281
- `videos()` lists the repo's. Answers: `{ videos, unreadable, deferred }`;
282
- `file` adds `{ version, current, expired }`. Then `run({ script, video:
283
- { id } })` adds a version; `video: { new: "<name>" }` starts one.
253
+ 0. Name the flow first: every run adds a video to one. If the repo
254
+ has an exported file of it, `flows({ file: <absolute path> })`. Else
255
+ `flows({ query: "<what the flow shows>" })`; `flows()` lists the repo's. Then `run({ script, flow:
256
+ { id } })` adds a video; `flow: { new: "<name>" }` starts one.
284
257
  `possibleDuplicate` lists `matches`: use one's `id`, or repeat with
285
258
  `confirmedNew: true` for a different flow. `nameTaken` names the
286
- `holder`: use its `id` or another name. The report's `videoVersion`
287
- (`id`, `version`, `created`) says what was made.
288
- 1. `run(script, video)`. It answers the run's report, or
259
+ `holder`: use its `id` or another name. The report's `flow`
260
+ says what was made.
261
+ 1. `run(script, flow)`. It answers the run's report, or
289
262
  `{ "outcome": "stillRunning", "id": … }` after about 50 s; then call
290
263
  `report(id)` until the outcome is neither `running` nor `stillRunning`.
291
- Never `run` again while one is in progress: it is refused
292
- (`alreadyRunning`).
293
264
  2. The report's `outcome`:
294
265
  - `refusedBeforeRun` - the door refused before opening anything; `reason`
295
266
  and `field` name what to fix (section 7).
296
267
  - `refused` - the replay policy refused; `refused.routes` names the
297
- user's move. Tell the user; do not work around it.
268
+ user's move. Tell them; do not work around it.
298
269
  - `stopped` - `stopped.at` names the step and `stopped.sentence` says why.
299
270
  A `steps[i].pageUrl` on a sign-in page means the app sent this browser
300
271
  to sign in mid-run: tell the user; do not rewrite targets.
301
- `signedOut` means nothing usable was recorded and no take was kept: give
302
- the user the command in `stopped.detail`; run again only after they
303
- have run it. It is not a script fault.
304
- `signInFailed` names the account, step and landing: fix the account's
305
- file or secret, or tell the user. (A run
306
- that stopped short on the site's recorded sign-in page is relabelled
307
- `signedOut` too; its detail ends "The run itself stopped at script
272
+ (A run stopped short on the site's recorded sign-in page is relabelled
273
+ `signedOut` (section 7); its detail ends "The run itself stopped at script
308
274
  step N: ...".)
309
275
  - `complete` - read `verdict`: `verdict.kind` is `"matches"` or
310
276
  `"diverged"`, and `verdict.diverged[]` lists each step the video does not
311
- show the way the script asked. `matches` with every
312
- `steps[i].candidates` at 1 means the steps are right.
277
+ show as the script asked. `still`, the image after the text, is
278
+ the last frame: the verdict says the actions happened; look at `still` against the brief before you export or run again.
279
+ `endPage`: the end page's `url`, `text` and `fields`.
313
280
  - In any outcome, a step whose `textHidden` is set typed into a credential
314
281
  field (`"credentialField"`, or `"credentialUnchecked"` if the page could
315
- not say): its text is kept nowhere. Re-recording or deriving that take
316
- asks for a demo value. `landing.startedElsewhere` names where the start URL went
317
- instead; `landing.unchecked`: the page could not be checked for a
282
+ not say): its text is kept nowhere. Re-filming or deriving that video
283
+ asks for a demo value. `landing.startedElsewhere` names where the start URL went; `landing.unchecked`: the page could not be checked for a
318
284
  sign-in page. `notStored` with `what: "session"` means the saved
319
285
  session could not be refreshed: name it to the user.
320
286
  - `threw` - a fault in the run; report its `error`.
@@ -322,106 +288,92 @@ verb was changed by hand: `derive`, check it, `run` the draft.
322
288
  about the video, not the script (`surfaceMismatch`: the browser handed
323
289
  back frames of the wrong size; `dragPictureMissing`: a native drag's item
324
290
  jumps). `notDragged`: a drag changed nothing; `verdict.diverged` lists
325
- it. Spend no run on them; name them to the
326
- user. One is about a step: `clickUnconfirmed` means a click
291
+ it. Name them to the user; spend no run. `clickUnconfirmed` is about a step: a click
327
292
  could not be confirmed to have reached its target, and
328
293
  `frames.unconfirmedClicks` names each such step and says why; check in
329
294
  the video that the step did what it should before saying so.
330
- - A re-recording's report carries `rerecord`: `from` (the take), `notes`
295
+ - A re-film's report carries `rerecord`: `from` (the old video), `notes`
331
296
  (as `report.skeleton` above, `stepDropped` with `why` `actionGone` or
332
- `neverPerformed`; `migrated`: a `sentence`) and `notCarried` (each `removed`, `split`,
333
- mask, hold, gap or trim the old take had and the new one lacks, and
334
- each zoom the editor aimed or ended by hand, `zoom`; every other zoom
335
- the new take makes again from its own clicks). Name every
336
- one to the user; a mask not carried may show what the old video hid.
297
+ `neverPerformed`; `migrated`, `trimClampedToStep`, `zoomNotWritten`: a `sentence`) and `notCarried` (each `removed`, `split`,
298
+ mask, hold, gap or trim the old video had and the new one lacks, and
299
+ each zoom added or moved in the editor, `zoom`; others are remade
300
+ from clicks). Name each
301
+ to the user; a mask not carried may show what the old video hid.
337
302
  3. **Read the video.** The report carries `video` and `recording`. Read
338
303
  `video.summary` first (a count per label: `inside`, `atEdge`, `cutOff`,
339
304
  `outOfFrame`, `strayArrival`, `detour`, `longStill`), then
340
305
  `video.steps[i].framing.label`, and `video.journeys[j].arrival` /
341
306
  `video.journeys[j].detour` for the cursor.
342
- - **Which script step a video step is:** `video.steps` lists the take's
307
+ - **Which script step a video step is:** `video.steps` lists the video's
343
308
  actions, and a `pause` makes no action. Find the report's `steps[k]`
344
309
  whose `actionId` equals `video.steps[i].actionId`; `steps[k].index` is
345
310
  its 0-based position in your script.
346
- - `video` may be `{ "unavailable": … }` (`refused`, `noTake`, `noFrames`,
311
+ - `video` may be `{ "unavailable": … }` (`refused`, `noVideo`, `noFrames`,
347
312
  `checkFailed` with `error`): not a clean bill; say so, do not retry. Likewise
348
313
  `video.steps[i].unknown` and `video.noCursor: true`.
349
314
  - `recording` is `{ "unavailable": … }` or
350
- `{ recordingTakeId, steps[], notInRecording[] }`, comparing the run with
351
- the take a derived script came from. `unavailable` is again an answer.
315
+ `{ recordingVideoId, steps[], notInRecording[] }`, comparing the run with
316
+ the video a derived script came from. `unavailable` is again an answer.
352
317
 
353
318
  | Finding | Whose | The move |
354
319
  | --- | --- | --- |
355
320
  | `cutOff`, `outOfFrame` | the script | add a `scrollTo` on that element before the step |
356
321
  | `atEdge` | the script, if a run remains | as above; otherwise leave it |
357
322
  | `longStill` beyond what a `pause` asked for | Demoman | leave it; do not rewrite steps |
323
+ | `opening` long | the script | add `trim.start` |
324
+ | `zoomNotes` | the script | set that click's `zoom` |
325
+ | `trimNotes` | the script | name another step in `trim` |
358
326
  | stray arrival, `detour` | Demoman | leave it |
359
- | drift from the earlier take | the app | report it |
327
+ | drift from the earlier video | the app | report it |
360
328
 
361
- A finding that is Demoman's earns no run, and is not passed on: the
362
- user takes the video as it is or changes it in the Studio. A step's
363
- `roomMs` is Demoman's own pacing, not a stall.
329
+ A finding that is Demoman's earns no run and is not passed on (the
330
+ user can change it in the Studio). A step's `roomMs` is pacing, not a stall.
364
331
  4. Tighten a step whose `candidates` is above 1 or whose `strategy` is weaker
365
332
  than the target you named.
366
333
 
367
334
  **Stop after three runs**, done or not, then export: every run drives the
368
- user's real app. A take zooms on every click and starts from the kit named in `look.kit`, else the
369
- user's default brand kit; a draft derived from a take keeps that take's
370
- branding. The report's `look.branding` says where it came from: `script`,
335
+ user's real app. A video zooms on every click and starts from `look.kit`, else the
336
+ user's default brand kit; a derived draft keeps its video's branding. `look.branding` says where it came from: `script`,
371
337
  `kit` (you named it; `look.kit.name` says which), `defaultKit`, or
372
- `defaults`. A non-null `look.brandKitError` means the default kit could not
373
- be read, and goes into your hand-back. The report's `size` is what the video
374
- was recorded at, read as in section 2; a `size.error` goes into your hand-back
375
- too.
338
+ `defaults`. A non-null `look.brandKitError` (default kit unreadable),
339
+ `look.wallpaperError` (its image) or `size.error` goes into your hand-back;
340
+ `size` is the recorded size (section 2).
376
341
 
377
342
  ## 5. Export and hand back
378
343
 
379
- 1. `export(takeId)` with the accepted run's `provenance.takeId`. It answers
344
+ 1. `export(videoId)` with the accepted run's `provenance.videoId`. It answers
380
345
  the export report, or `stillRunning` with an `id`; then call `report(id)`
381
- until the outcome is none of `exporting`, `stillRunning`. A second export, run
382
- or snapshot while one is in progress is refused (`busy`, `alreadyRunning`).
383
- `fileType` picks the file: `mp4` (the default), `gif` (plays inline in
384
- a GitHub PR or issue), or `stills` (a PNG per step, in a folder). Ask
385
- for a GIF or stills only if the user did. An MP4 follows Settings
346
+ until the outcome is none of `exporting`, `stillRunning`.
347
+ `fileType`, only if asked: `mp4` (the default), `gif`, or `stills`. An MP4 follows Settings
386
348
  (unset: ~1 MB/s); `quality: "full"` is largest.
387
- `export({ takeId, maxMB: 9.5 })` fits GitHub's 10 MB drag-in, or says
388
- it could not (it lowers fps, then size, then quality: the summary says
389
- what it cost).
390
- A GIF is made as wide as the recording backs and fits 10 MB, up to twice
391
- its usual width; `warnings.gifSize` says how wide, its size, and which
392
- wider widths were refused (`limit`: `budget`, too big, or `detail`, too
393
- few pixels); a GIF over 10 MB at its narrowest says so: offer the MP4.
394
- Stills take `stills: { width, zoom }`, both optional. By default each
395
- still is up to 2560 px wide (never wider than the recording) and shows
396
- the whole window. `width` asks for a size in
397
- px (320-3840) or `"native"`, the recording's own size; `zoom: "step"`
398
- frames each step the way the video zooms on it, all the way in. Pass
399
- them only when the user asked for a size or for zoomed stills.
349
+ `export({ videoId, maxMB: 9.5 })` fits GitHub's 10 MB drag-in, or says
350
+ it could not.
351
+ A GIF is as wide as fits 10 MB (`warnings.gifSize` says how wide and
352
+ which widths were refused); one over 10 MB at its narrowest says so: offer the MP4.
353
+ Stills take `stills: { width, zoom }`, both optional; by
354
+ default a still is the whole window, up to 2560 px wide. `width` is px (320-3840) or `"native"`, the video's own size; `zoom` is `"none"` or `"step"`, which frames each step as the video zooms on it, all the way in. Only when asked.
400
355
  2. `saved` - the file is at `file.path`, absolute: in `~/Downloads`, or the
401
- folder the server was started with `--out-dir`. For `stills`, `fileType`
356
+ server's `--out-dir`. For `stills`, `fileType`
402
357
  is `stills` and the answer carries `folder: { path, files }` instead of
403
358
  `file`: give the user `folder.path`; `warnings.unplacedStills` lists steps
404
- that got no still. `summary` is one
405
- sentence: what was saved and anything the user asked for that the file
406
- lacks (a logo, motion, a still, an edit). `warnings` holds more:
407
- Demoman's own calls (`zooms`, `detailViolations`, a size cap's `steps`,
408
- a GIF's widths, `targetCheck`). They are
409
- not the user's to act on: do not pass them on. None is the script's to fix.
359
+ with no still. `summary` is one
360
+ sentence: what was saved and anything asked for that the file lacks (a logo, motion, a still, an edit). `warnings` holds more:
361
+ Demoman's calls (`zooms`, `detailViolations`, a size cap's `steps`,
362
+ a GIF's widths, `targetCheck`): not the user's to act on: do not pass them on. None is the script's.
363
+ Except `wallpaperWarning.sentence` (wallpaper left out: plain
364
+ gradient; or will look soft): quote it.
410
365
  `warnings.editedSinceRecorded` lists steps whose `scene.json` no longer
411
- matches the frames; the summary says so and names the re-recording
412
- (`run({ video: { id } })`, or `derive` then `run` when a verb changed).
413
- Re-record only on request. `warnings.untagged`: the file has no video
414
- tag (`error` says why); not the user's to act on.
415
- `links` holds the export's one-click actions for the user, each present
366
+ matches the frames; the summary names the re-film
367
+ (`run({ flow: { id } })`, or `derive` then `run` when a verb changed).
368
+ Re-record only on request. `warnings.untagged` and `taggedWithoutCommit`: not the user's to act on.
369
+ `links` holds the export's one-click actions, each present
416
370
  only where it works: `studio`, `file` (the file itself) and `copy` (the
417
371
  file to the clipboard; none for stills). `linksError`, set instead, says
418
372
  why there are none: tell the user in one line.
419
- Every export report carries a `summary`, whatever its outcome
420
- (`stillRunning`, this server's own answer, does not).
421
373
  3. `renderFailed` - export **once** more; never re-run the script for an
422
374
  export failure. `saveFailed` - its `error` names the folder and the
423
375
  system's reason (a folder that cannot be written): tell the user;
424
- exporting again will not help until it is fixed. A stills export that
376
+ exporting again will not help until fixed. A stills export that
425
377
  stopped partway carries `partial: { folder, written, notWritten }`; the
426
378
  stills in `written` are whole PNGs.
427
379
  4. `pathUnknown`, `refusedBeforeExport` or `threw` - report it, quoting
@@ -434,41 +386,40 @@ Before opening a PR, read `status.pullRequests` (`project` for
434
386
  another checkout): `attach`, `ask`, `off`, or `{ unreadable, file }`,
435
387
  which is not `off`: tell the user. `off`: only when asked. If the diff
436
388
  changes what a user sees, record that one flow (only the change),
437
- push and open the PR, then `attach({ takeId, into: "description" })`, or
389
+ push, open the PR, then `attach({ videoId, into: "description" })`, or
438
390
  `"comment"` on a PR that is not yours. The video carries its own line; write no other. On `line.notWritten`,
439
- tell the user the video lacks its line, quoting why. A later `gh pr edit --body` drops the video. `ask`: offer once; on a no, nothing to see or a failed run (say why),
391
+ tell the user the video lacks it, quoting why. A later `gh pr edit --body` drops the video. `ask`: offer once; on a no, nothing to see or a failed run (say why),
440
392
  the PR says nothing of it. `attach`: with no video, the PR description gets
441
393
  one line, `No demo: <why>`, and so does the user.
442
- `attach` takes `maxMB` as `export` does. On `stillRunning`, `report(id)`
443
- until the outcome is neither `attaching` nor `stillRunning`. On `busy`,
444
- `report(id)` on the export in flight, then `attach` again. On `ghMissing`,
445
- `ghOutdated`, `ghSignedOut`, `notGitHub` or `copyFailed`, call
446
- `export({ takeId, maxMB: 9.5 })` and give the user its `file.path` to drag
447
- into the PR, saying why. On `uploadRefused`, do as its `detail` says. On `partial` or `unconfirmed`, do not
394
+ `attach` caps at 9.5 MB; `maxMB` sets another. On `stillRunning`, `report(id)`
395
+ until the outcome is not `attaching` or `stillRunning`. On `busy`,
396
+ `report(id)` on the export in flight, then `attach`. On `ghMissing`,
397
+ `ghOutdated`, `ghSignedOut`, `notGitHub`, `prUnreadable` or `copyFailed`, call
398
+ `export({ videoId, maxMB: 9.5 })` and give the user its `file.path` to drag
399
+ into the PR, saying why. On `uploadRefused` or `prNotFound`, do as its `detail` says. On `partial` or `unconfirmed`, do not
448
400
  post again; tell the user to check the PR. Other reasons: section 7. An unsaved export answers as `export` does.
449
401
 
450
402
  Hand back, on `saved`, two lines and nothing else: the `summary` as it is,
451
403
  then the `links` as markdown links on one line, in this order, only
452
- those present: `[Open in Studio](links.studio) · [<file name>](links.file) · [Copy video](links.copy)`
453
- (`Copy GIF` for a GIF). Add one line only for `look.brandKitError`,
454
- `size.error`, `linksError`, or something you could not fix. Any other
404
+ those present: `[Open in Studio](links.studio) · [<file name>](links.file) · [Copy video](links.copy)` (`Copy GIF` for a GIF). Add one line only for `look.brandKitError`,
405
+ `look.wallpaperError`, `size.error`, `linksError`, or something you could not fix. Any other
455
406
  outcome: quote its `error` or `detail`.
456
407
 
457
408
  When the `studio` tool is listed and there is no `links.studio`, **offer**
458
- it; never open it unasked. `studio({ takeId })`
459
- opens a window to edit and export the take.
460
- `{ outcome: "opened", takeId?, note? }`: say the window is open;
461
- quote `note` if set. Studio exports go to `~/Downloads`.
409
+ it; never open it unasked. `studio({ videoId })`
410
+ opens a window to edit and export it.
411
+ `{ outcome: "opened", videoId?, note? }`: say it is open; quote `note` if set.
412
+ Studio exports go to `~/Downloads`.
462
413
 
463
414
  ## 6. The format
464
415
 
465
416
  ```json
466
417
  {
467
- "scriptVersion": 1,
468
418
  "name": "Checkout with a coupon",
469
419
  "target": "https://app.example.com/cart",
470
420
  "steps": [
471
421
  { "do": "waitForLoad" },
422
+ { "do": "scrollTo", "on": { "treePath": "body:1/main:1/section:2/div:1" }, "landing": { "top": 280 } },
472
423
  { "do": "click", "on": { "role": "button", "name": "Apply coupon" } },
473
424
  { "do": "waitFor", "on": { "role": "textbox", "name": "Coupon code" }, "until": "visible" },
474
425
  { "do": "type", "into": { "role": "textbox", "name": "Coupon code" }, "text": "SPRING25" },
@@ -479,124 +430,129 @@ quote `note` if set. Studio exports go to `~/Downloads`.
479
430
  }
480
431
  ```
481
432
 
482
- A derived draft keeps where its scrolls stopped (`landing`) and which
483
- recorded action each step came from (`recorded`, in `recordedFrom`):
484
-
485
433
  ```json
486
- {
487
- "scriptVersion": 1,
488
- "name": "Landing page tour",
489
- "target": "https://app.example.com/",
490
- "steps": [
491
- { "do": "scrollTo", "on": { "treePath": "body:1/main:1/section:2/div:1" }, "landing": { "top": 280 }, "recorded": "a-1" },
492
- { "do": "click", "on": { "role": "link", "name": "Get started" }, "recorded": "a-2" }
493
- ],
494
- "recordedFrom": "take-7f3a"
495
- }
434
+ {"name": "Move a card", "target": "https://app.example.com/board",
435
+ "steps": [{ "do": "drag", "from": { "on": { "text": "Card A" } }, "to": { "on": { "text": "Done" } } }]}
496
436
  ```
497
437
 
498
438
  ```json
499
- {"scriptVersion": 6, "name": "Move a card", "target": "https://app.example.com/board",
500
- "steps": [{ "do": "drag", "from": { "on": { "text": "Card A" } }, "to": { "on": { "text": "Done" } } }]}
439
+ {"name": "Search", "target": "https://app.example.com/",
440
+ "steps": [
441
+ { "do": "type", "into": { "role": "searchbox", "name": "Search" }, "text": "invoices" },
442
+ { "do": "press", "key": "Enter" }
443
+ ]}
501
444
  ```
502
445
 
503
- - `scriptVersion` and `name` are required; a step's verb is `do`.
504
- `scriptVersion` is the highest that applies: `1`; `2` when `look` names
505
- a `kit`; `3` when it carries `motion`; `4` when the script names a
506
- `device`; `5` when it names an `account`; `6` when it has a `drag`.
446
+ - `name` is required; a step's verb is `do`. Leave `scriptVersion` out: Demoman sets it. Keep a derived draft's `recorded` (on steps) and `recordedFrom`.
507
447
  - **Targets** name exactly one strategy: `{ "stableId" }`, `{ "role", "name" }`,
508
448
  `{ "text" }` or `{ "treePath" }`. Two in one target is refused. Copy them
509
449
  from `snapshot` or a derived draft. A `treePath` is a position in the
510
- page: it breaks when the structure changes, and the run stops there.
511
- - **Verbs:** `click`, `type` (replaces the field's contents), `hover`,
512
- `scrollTo`, `waitFor` (`until`: `visible` | `hidden`; visible means it can
513
- be seen, so an element at `opacity: 0` or `visibility: hidden` is hidden),
514
- `waitForLoad`, `pause` (`ms`), and `drag` (`from: { on, at? }`, `to`
450
+ page: it breaks when the structure changes, stopping the run.
451
+ - **Verbs:** `click` (optional `at: { x, y }`, a spot in the box, 0–1, as drag's; absent is the centre), `type` (replaces the field's contents), `hover`,
452
+ `scrollTo`, `waitFor` (`until`: `visible` | `hidden`; `opacity: 0` or
453
+ `visibility: hidden` is hidden),
454
+ `waitForLoad`, `pause` (`ms`), `press` (`key`: `Enter` | `Tab` | `Escape` |
455
+ `Backspace` | `Delete` | `ArrowUp` | `ArrowDown` | `ArrowLeft` | `ArrowRight` |
456
+ `Space`; names no element, goes to whatever holds focus), and `drag` (`from: { on, at? }`, `to`
515
457
  the same or `{ "by": { x, y } }` px; `at` is a spot in the box, 0–1). An unknown key is refused and named.
516
- - `scrollTo` takes an optional `landing: { "top": <px> }`, the viewport y of
517
- the element's top edge when the scroll stops. Absent means centred.
458
+ - `trim`: `{ "start"?: { "ms", "step"? }, "end"?: { "ms", "step"?, "after"? } }`, the video kept before the first and after the last shown step. `step` is 1-based, not a `pause`; `after` is `"zoomOut"` (default) or `"action"`. To end every video right after its last step, give every script `"trim": { "end": { "ms": 0 } }`.
459
+ - A `click` or `drag` takes `zoom`: `false` for none, or `{ "scale": 1.5 }` (over 1, at most 2.5).
460
+ - `scrollTo` takes `landing: { "top": <px> }`, optional: the viewport y of
461
+ the element's top edge once scrolled; absent is centred.
518
462
  - `viewport` absent means the size the user chose: the screen's, which
519
- `snapshot` measured `inFirstViewport` against. Leave `viewport`
520
- out unless the user asked for a size.
463
+ `snapshot` measured `inFirstViewport` against. Leave `viewport` out unless the user asked.
521
464
  - `device` is `"phone"` or `"tablet"`: the page is recorded as a phone (393x852)
522
- or a tablet (820x1180), with touch and an iOS user agent. Name a device or a
523
- `viewport`, not both. A device has no hover, so a `hover` step under one is
465
+ or a tablet (820x1180). Name a device or a
466
+ `viewport`, not both. A device has no hover: a `hover` under one is
524
467
  refused. `look` takes `branding` or `kit`, plus `cursor`, `canvas` and
525
- `motion`; absent means the user's default brand kit. `kit` names one of
526
- `snapshot`'s `kits` (case does not matter); name a kit or give a
527
- branding, not both. An unknown key in `look` is refused and named. A
468
+ `motion`; absent is the user's default brand kit. `kit` names one of
469
+ `snapshot`'s `kits`; not both a kit and a branding. An unknown key in `look` is refused and named. A
528
470
  `branding` is the whole of one: `background`, `logo` (or `null`) and
529
471
  `padding`, the margin as a fraction of the frame's shorter side (0 to
530
- 0.2; left out is 0.08); a missing `background` or `logo` is refused.
472
+ 0.2; left out is 0.12); a missing `background` or `logo` is refused.
473
+ A `background` may be `{ "kind": "wallpaper", "id" }` (`muted-1` to
474
+ `muted-4`, `vivid-1` to `vivid-6`, `light-1`, `light-2`, `dark-1`, `dark-2`;
475
+ another id is refused, naming them) or `{ "kind": "image", "ref": "<path>" }`, a file, absolute or
476
+ relative to the Demoman home; copied into the video. Either takes
477
+ `"blur"`, 0-1 (default 0, sharp).
531
478
  A `canvas` is `{ "aspect": "auto" | "16:9" | "9:16" }`; `auto`, the
532
- default, is the recording's own shape plus an even margin.
533
- A `motion` is how the camera moves, `{ "smoothness": 0-1, "blur": 0-1, "follow": true | false }`; a derived draft carries the take's own, so keep it.
479
+ default, is the source's shape plus an even margin.
480
+ A `motion` is how the camera moves, `{ "smoothness": 0-1, "blur": 0-1, "follow": true | false }`; keep the one a derived draft carries.
534
481
  - Refused at the door: a script whose every step is a `pause`; a `target`
535
482
  that is not `http(s)`; a `click` with a `button`.
536
- - No branching, no loops, no assertions. Add `pause` only where a viewer
537
- must read something.
483
+ - No branching, loops or assertions. Add `pause` only where a viewer must read.
538
484
 
539
485
  ## 7. Every reason
540
486
 
487
+ `probe` can answer any reason `snapshot` can, and `run`'s `refusedBeforeRun` ones.
488
+
541
489
  | Reason | Where | What it means, and the move |
542
490
  | --- | --- | --- |
543
- | `browserMissing` | `snapshot`, `run` (`refusedBeforeRun`), `studio` | Demoman's browser or its libraries are missing; `detail` gives the command. Ask the user to run it, then call again. |
544
- | `unsupportedPlatform` | `snapshot`, `run`, `export` | This machine cannot record (arm64 Linux, or another OS); quote `detail` to the user. |
545
- | `sessionUnreadable` | `snapshot`, `run` (`refusedBeforeRun`) | A saved session file or folder could not be read, or others can read it; `detail` names the fix. Tell the user. |
546
- | `sessionNotLoaded` | `snapshot`, `run` (`refusedBeforeRun`) | The browser refused the saved sessions; `detail` says why. Tell the user to run `npx demoman signin` again for that site. |
547
- | `signInFailed` | `snapshot`, `run` (`refusedBeforeRun`) | Demoman signed in as the account and the page still showed a sign-in page, or a step could not run; `detail` says where. It tried once. Fix the account's steps or the secret, or tell the user; do not run again unchanged. |
548
- | `secretMissing` | `snapshot`, `run` (`refusedBeforeRun`) | A `{secret:NAME}` has no `DEMOMAN_SECRET_NAME` and no line in `.demoman/secrets.env`; `detail` names both. Through `project` the environment is not used. Write one (section 1), or ask the user. |
549
- | `secretTooShort` | `snapshot`, `run` (`refusedBeforeRun`) | The secret `NAME` is under 8 characters. Generate a longer one and write it again. |
550
- | `secretUnbound` | `snapshot`, `run` (`refusedBeforeRun`) | `DEMOMAN_SECRET_NAME` has no `DEMOMAN_SECRET_NAME_ORIGIN` beside it, or one that is not an origin; `detail` names the line and the site. Nothing was typed. Add it to `secrets.env` for an account you made; else tell the user. |
551
- | `secretOffOrigin` | `snapshot`, `run` (`refusedBeforeRun`) | A secret was about to be typed off its site: a sign-in step's page is not the site's origin, or the secret's `_ORIGIN` names another site; `detail` names both. Nothing was typed. Check the account's site and `goto`, then tell the user. |
552
- | `secretsFileNotIgnored` | `snapshot`, `run` (`refusedBeforeRun`) | Git does not ignore `.demoman/secrets.env`, so Demoman did not read it. Add `.demoman/secrets.env` to `.gitignore` (`detail` says the line), or take the file out of git if tracked. |
553
- | `secretsFileInvalid` | `snapshot`, `run` (`refusedBeforeRun`) | A line of `.demoman/secrets.env` is not `DEMOMAN_SECRET_NAME=value`, a comment or blank; `detail` gives the line number. Fix it. |
491
+ | `browserMissing` | `snapshot`, `run` (`refusedBeforeRun`), `studio` | Demoman's browser or libraries are missing; `detail` gives the command. Ask the user to run it, then call again. |
492
+ | `unsupportedPlatform` | `snapshot`, `run`, `export` | This machine cannot record (arm64 Linux, or another OS); quote `detail`. |
493
+ | `sessionUnreadable` | `snapshot`, `run` (`refusedBeforeRun`) | A saved session file or folder could not be read, or is readable by others; `detail` names the fix. Tell the user. |
494
+ | `sessionNotLoaded` | `snapshot`, `run` (`refusedBeforeRun`) | The browser refused the saved sessions; `detail` says why. Tell the user to run `npx demoman signin` again there. |
495
+ | `signInFailed` | `snapshot`, `run` (`refusedBeforeRun`) | Demoman signed in as the account and the page still showed a sign-in page, or a step could not run; `detail` says where. It tried once. Fix the account's steps or secret, or tell the user; do not rerun unchanged. |
496
+ | `secretMissing` | `snapshot`, `run` (`refusedBeforeRun`) | A `{secret:NAME}` has no `DEMOMAN_SECRET_NAME` and no line in `.demoman/secrets.env`; `detail` names both. Through `project` the environment is unused. Write one (section 1), or ask the user. |
497
+ | `secretTooShort` | `snapshot`, `run` (`refusedBeforeRun`) | The secret `NAME` is under 8 characters. Write a longer one. |
498
+ | `secretUnbound` | `snapshot`, `run` (`refusedBeforeRun`) | `DEMOMAN_SECRET_NAME` has no `DEMOMAN_SECRET_NAME_ORIGIN` beside it, or one that is no origin; `detail` names the line and site. Nothing typed. Add it to `secrets.env` for an account you made; else tell the user. |
499
+ | `secretOffOrigin` | `snapshot`, `run` (`refusedBeforeRun`) | A secret was about to be typed off its site: a sign-in step's page is not the site's origin, or the `_ORIGIN` names another site; `detail` names both. Nothing typed. Check the account's site and `goto`, then tell the user. |
500
+ | `secretsFileNotIgnored` | `snapshot`, `run` (`refusedBeforeRun`) | Git does not ignore `.demoman/secrets.env`, so Demoman did not read it. Add it to `.gitignore` (`detail` says the line), or untrack it. |
501
+ | `secretsFileInvalid` | `snapshot`, `run` (`refusedBeforeRun`) | A line of `.demoman/secrets.env` is not `DEMOMAN_SECRET_NAME=value`, a comment or blank; `detail` gives the line. Fix it. |
554
502
  | `accountsInvalid` | `snapshot`, `run` (`refusedBeforeRun`) | `.demoman/accounts.json` is malformed or breaks a rule; `detail` names the field and the rule. Fix the file. |
555
- | `unknownAccount` | `snapshot`, `run` (`refusedBeforeRun`) | The script names an account the site does not have, or names none and the site has no `default`; `detail` lists the site's accounts. Name one, or add it (section 1). |
503
+ | `unknownAccount` | `snapshot`, `run` (`refusedBeforeRun`) | The script names an account the site lacks, or none and the site has no `default`; `detail` lists the accounts. Name one, or add it (section 1). |
556
504
  | `invalidProject` | `snapshot`, `run` (`refusedBeforeRun`), `attach` | `project` is not an absolute path to a folder. Pass one, or leave it out. |
557
- | `ghMissing`, `ghOutdated`, `ghSignedOut` | `attach` (`refusedBeforeAttach`) | `gh` is missing, too old or signed out; `detail` gives the fix. Hand the user the file (section 5). |
558
- | `notGitHub`, `prNotFound`, `prUnreadable` | `attach` (`refusedBeforeAttach`) | Not a GitHub remote; no such PR; the PR could not be read. Nothing was posted: quote `detail` to the user. |
505
+ | `ghMissing`, `ghOutdated`, `ghSignedOut`, `notGitHub`, `prNotFound`, `prUnreadable` | `attach` (`refusedBeforeAttach`) | `gh` is missing, too old or signed out; not a GitHub remote; no such PR, or GitHub did not answer. Nothing posted; do as `detail` says. |
559
506
  | `invalidAttach` | `attach` (`refusedBeforeAttach`) | The call is malformed; `detail` says how. Fix it. |
560
507
  | `uploadRefused` | `attach` (`notAttached`) | GitHub refused the video. Retry as the Pull requests text says. |
561
508
  | `partial` | `attach` (`notAttached`) | `gh` failed but the video is on the PR; do not post again. |
562
509
  | `unconfirmed` | `attach` (`notAttached`) | Unknown what landed. Do not post again; tell the user to look at the PR. |
563
- | `copyFailed` | `attach` (`notAttached`) | The video could not be copied; nothing was posted. Hand the user the capped export's file. |
510
+ | `copyFailed` | `attach` (`notAttached`) | The video could not be copied; nothing posted. Hand the user the capped export's file. |
564
511
  | `windowDidNotOpen` | `snapshot`; `run` (`refusedBeforeRun`); `studio` | The window would not open; try once more. |
565
512
  | `studioDidNotStart` | `studio` | The Studio did not start; `detail` quotes the end of `~/.demoman/studio.log`. Tell the user, quoting it. |
566
- | `alreadyRunning` | `snapshot`, `run`, `derive` | A run, snapshot or export is in progress. Call `report(id)` on it; try again when it settles. |
567
- | `busy` | `export` (`refusedBeforeExport`) | A run or snapshot is in progress. Call `report(id)` on it first. |
568
- | `browserSilent` | `status`, `takes`, `derive`, `report` | The browser did not answer within about 50 s. Call `status` once; if again, tell the user. From `report`, the run may still be going: call `report(id)` again. |
569
- | `libraryUnreadable` | `takes`, `studio` | The library could not be read; report it. |
570
- | `libraryUnwritable` | `run` (in `notStored`) | Not a `reason`: the report has a `notStored` entry `{ "what": "take", "error": … }` and a null `provenance.takeId`. Nothing was saved; quote the `error`. |
513
+ | `alreadyRunning` | `snapshot`, `probe`, `run`, `derive` | A run, probe, snapshot or export is in progress. Call `report(id)` on it; retry when it settles. |
514
+ | `busy` | `export` (`refusedBeforeExport`) | A run, probe or snapshot is in progress. `report(id)` it first. |
515
+ | `browserSilent` | `status`, `flows`, `derive`, `report` | The browser did not answer in about 50 s. Call `status` once; if again, tell the user. From `report` the run may still be going: call `report(id)` again. |
516
+ | `libraryUnreadable` | `flows`, `studio` | Unreadable; report it. |
517
+ | `libraryUnwritable` | `run` (in `notStored`) | Not a `reason`: the report has a `notStored` entry `{ "what": "video", "error": … }` and a null `provenance.videoId`. Nothing saved; quote the `error`. |
571
518
  | `unknownRun` | `report` | This demoman-mcp never issued that id (ids do not survive a server restart). |
572
519
  | `noReport` | `report` | No report for that id: this server keeps only its latest; `detail` says which. Do not run again. |
573
520
  | `notAnObject` | `run` | The script is not a JSON object. |
574
521
  | `invalidScript` | `run` | The schema refused the script; `field` names where. |
575
- | `unfilledHoles` | `run` | A derived draft still has holes (section 3); also a re-record of a take that did not keep a value. |
576
- | `videoRequired` | `run` (`refusedBeforeRun`) | No `video` was given. Find one (section 4), or pass `{ new }`. |
577
- | `possibleDuplicate`, `nameTaken` | `run` (`refusedBeforeRun`) | A similar video exists (`matches`) or the name is taken (`holder`). Section 4. |
578
- | `videoNotFound` | `run` (`refusedBeforeRun`) | No video has that `id`; call `videos`. |
579
- | `videoUnreadable`, `videoUnwritable` | `run` (`refusedBeforeRun`), `videos` | The video records could not be read or written; quote `detail`. Nothing was recorded. |
580
- | `noTag`, `unknownVideo`, `fileNotFound` | `videos` | The file has no Demoman tag; its video is not in this library; no file there. Use `query` instead. |
581
- | `invalidArgs` | `videos` | `file` with `query`, or not an absolute path. |
582
- | `versionExpired` | `export` (`refusedBeforeExport`) | The take's frames expired: `run({ video: { id } })`, then export. |
583
- | `failed` | `status` (`expiry`) | Not a refusal: `expiry` is the last cleanup `{ ranAt, expired, freedBytes, skippedLeased }`. Say nothing unless it is `{ failed }` or `{ unreadable }`: quote it. |
584
- | `nothingToRerecord` | `run` (`refusedBeforeRun`) | The take has no step left that acts; tell the user. |
585
- | `unknownKit` | `run` (`refusedBeforeRun`) | `look.kit` names no brand kit, or one that cannot be read; `detail` lists the kits. Fix the name from `snapshot`'s `kits`, or ask the user. |
586
- | `kitsUnreadable` | `run` (`refusedBeforeRun`) | The brand kits file could not be read, so `look.kit` was not checked. Quote `detail` to the user; do not change the name. |
587
- | `invalidDevice` | `snapshot` | `device` names no phone or tablet Demoman has; `detail` lists those it has. Use one. |
588
- | `deviceFailed` | `snapshot`, `run` | The browser would not emulate the device; nothing was listed or recorded; `detail` says why. Tell the user; do not run again. |
522
+ | `unfilledHoles` | `run` | A derived draft still has holes (section 3); also a re-film of a video that did not keep a value. |
523
+ | `flowRequired` | `run` (`refusedBeforeRun`) | No `flow` was given. Find one (section 4), or pass `{ new }`. |
524
+ | `possibleDuplicate`, `nameTaken` | `run` (`refusedBeforeRun`) | A similar flow exists (`matches`) or the name is taken (`holder`). Section 4. |
525
+ | `repoFlowNameTaken`, `duplicateFlow`, `repoFlowUnreadable` | `run` (`refusedBeforeRun`); the first two also `flows` with `file` | Repo flows: this library has another flow with that name (`detail` gives the `join-flow` command to tell the user); two files in `.demoman/flows` or the old folder before it name one flow (delete one); a file there will not read (`detail` names it; fix or remove it). |
526
+ | `flowNotFound` | `run` (`refusedBeforeRun`) | No flow has that `id`; call `flows`. |
527
+ | `wrongIdKind` | any | Wrong kind of id; see `detail`. |
528
+ | `flowUnreadable`, `flowUnwritable` | `run` (`refusedBeforeRun`), `flows` | The flow records could not be read or written; quote `detail`. Nothing recorded. |
529
+ | `noTag`, `unknownFlow`, `fileNotFound` | `flows` | The file has no Demoman tag; its flow is not in this library; no file there. Use `query` instead. |
530
+ | `invalidArgs` | any | `file` with `query`, not absolute; an old name (`video`, `takeId`): `detail` gives the new. |
531
+ | `videoExpired` | `export` (`refusedBeforeExport`) | The video's frames expired: `run({ flow: { id } })`, then export. |
532
+ | `failed` | `status` (`expiry`) | Not a refusal: `expiry` is the last cleanup. Say nothing unless it is `{ failed }` or `{ unreadable }`: quote it. |
533
+ | `nothingToRerecord` | `run` (`refusedBeforeRun`) | The video has no step left that acts; tell the user. |
534
+ | `unknownKit` | `run` (`refusedBeforeRun`) | `look.kit` names no kit, or an unreadable one; `detail` lists the kits. Fix it from `snapshot`'s `kits`, or ask the user. |
535
+ | `kitsUnreadable` | `run` (`refusedBeforeRun`) | The kits file would not read, so `look.kit` went unchecked. Quote `detail`; keep the name. |
536
+ | `wallpaperUnreadable` | `run` (`refusedBeforeRun`) | The image would not open. Quote `detail`; fix or drop `look.branding`/`look.kit`. |
537
+ | `invalidDevice` | `snapshot` | `device` is no phone or tablet Demoman has; `detail` lists them. |
538
+ | `deviceFailed` | `snapshot`, `run` | The browser would not emulate the device; nothing was listed or recorded. Tell the user `detail`; do not run again. |
589
539
  | `nonHttpTarget` | `run`, `snapshot` | The target or url is not `http(s)`, or its host contains `*`. |
590
540
  | `invalidFileType` | `export` (`refusedBeforeExport`) | Not answered here: the schema takes only `mp4`, `gif`, `stills`. |
591
- | `invalidStillsOptions` | `export` (`refusedBeforeExport`) | `stills` was given for an MP4 or GIF, or holds a width outside 320-3840 (or `"native"`), a zoom other than `"none"` or `"step"`, or another field; `detail` says which. Fix the call. |
541
+ | `invalidStillsOptions` | `export` (`refusedBeforeExport`) | `stills` was given for an MP4 or GIF, or breaks section 5's width or zoom; `detail` says which. Fix the call. |
592
542
  | `invalidQuality`, `invalidMaxMB` | `export` (`refusedBeforeExport`), `attach` | Through these tools, only `quality` or `maxMB` given for a GIF or stills; the schema rejects a bad value first. |
593
- | `noTakeId`, `noFrames` | `export` (`refusedBeforeExport`) | No take id; the take has no frames to render. |
594
- | `takeNotFound`, `takeUnreadable` | `export` (`refusedBeforeExport`), `run` re-record (`refusedBeforeRun`), `studio` (`takeNotFound`: call `takes`) | No such take; it could not be read (or, for `run`, built into a script). |
543
+ | `noVideoId`, `noFrames` | `export` (`refusedBeforeExport`) | No video id; no frames to render. |
544
+ | `videoNotFound`, `videoUnreadable` | `export` (`refusedBeforeExport`), `run` re-film (`refusedBeforeRun`), `studio` (`videoNotFound`: call `flows`) | No such video; it could not be read (or, for `run`, built into a script). |
545
+ | `unresolvedAnchor`, `anchorNotRendered`, `waitTimeout` | `run` (`stopped.reason`) | The target was not there in the 10 s a step waits, or a `waitFor`/`waitForLoad` timed out. Check it against a `snapshot` and the step before; `scrollTo` first in a long list. |
546
+ | `ambiguousAnchor` | `run` (`stopped.reason`) | Several elements matched; name the target more exactly. |
547
+ | `anchorFrameMismatch`, `anchorUnreachable`, `occlusionTimeout` | `run` (`stopped.reason`) | `anchorFrameMismatch`: its frame changed; pick another target. The others are not the script (unmeasurable, or window covered): run again once. |
548
+ | `pageWentElsewhere`, `unperformableStep` | `run` (`stopped.reason`) | The app left the page unasked (sign-in expired, or a missing `waitForLoad`); or the step asks the impossible. |
595
549
  | `dragEndOutOfView`, `dragNoDistance` | `run` (`stopped.reason`) | A drag's end was off screen (a drag cannot scroll), or on its start. Fix the script. |
596
- | `clickNotDelivered` | `run` (`stopped.reason`) | The browser put a click elsewhere than where it was sent; `stopped.detail` says where. Not the script's fault: run again (it counts); tell the user if it repeats. |
597
- | `signedOut` | `run` (`stopped.reason`) | The app sent this browser to its sign-in page. Nothing was kept. Give the user the command in `stopped.detail`; run again only after they ran it. As an account there is no command: the detail says whether Demoman signed in again; repeat only if it says so. |
598
- | `windowClosed` | `run` (`stopped.reason`) | `--headed` only: the window was closed mid-run; the script is fine. Ask the user to leave it open; run once more. In an export it answers `renderFailed`; export again. |
599
- | `pageDidNotLoad` | `snapshot` | The url did not load. Ask the user whether the app is running at that address; spend no run. |
600
- | `pageSilent` | `snapshot` | The page never answered. Call once more; if again, the page blocked Demoman's script; tell the user. |
601
- | `pageFaulted` | `snapshot` | The page's own code threw; quote `detail`. |
602
- | `snapshotThrew` | `snapshot` | A fault in the snapshot; quote `detail`. |
550
+ | `clickNotDelivered` | `run` (`stopped.reason`) | The browser put a click elsewhere than sent; `stopped.detail` says where. Not the script's fault: run again (it counts); tell the user if it repeats. |
551
+ | `signedOut` | `run` (`stopped.reason`) | The app sent this browser to its sign-in page. Nothing kept; not a script fault. Give the user the command in `stopped.detail`; run again only after they ran it. As an account there is no command: the detail says whether Demoman signed in again; repeat only if it does. |
552
+ | `windowClosed` | `run` (`stopped.reason`) | `--headed` only: the window closed mid-run; the script is fine. Ask the user to leave it open; run once more. In an export it answers `renderFailed`; export again. |
553
+ | `pageDidNotLoad` | `snapshot`, `probe` stop | The url did not load. Ask whether the app runs at that address; spend no run. |
554
+ | `pageSilent` | `snapshot` | The page never answered. Call once more; if again, the page blocked Demoman's script: tell the user. |
555
+ | `pageFaulted` | `snapshot` | The page's code threw; quote `detail`. |
556
+ | `snapshotThrew` | `snapshot` | A snapshot fault; quote `detail`. |
557
+ | `probeThrew` | `probe` | A probe fault; quote `detail`. |
558
+ | `portFailure` | `probe` | The browser gave way; not the script's fault. Probe once more; quote `detail` if it repeats. |