demoman 0.8.1 → 0.9.0

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