demoman 0.7.2 → 0.7.3

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.
@@ -15748,7 +15748,7 @@ Set the \`cycles\` parameter to \`"ref"\` to resolve cyclical schemas with defs.
15748
15748
  });
15749
15749
 
15750
15750
  // ../../packages/scene-schema/dist/document.js
15751
- var CURRENT_SCHEMA_VERSION = 12;
15751
+ var CURRENT_SCHEMA_VERSION = 13;
15752
15752
  var Rect = external_exports.object({
15753
15753
  x: external_exports.number(),
15754
15754
  y: external_exports.number(),
@@ -15997,9 +15997,11 @@ Set the \`cycles\` parameter to \`"ref"\` to resolve cyclical schemas with defs.
15997
15997
  rect: Rect,
15998
15998
  note: external_exports.string().optional(),
15999
15999
  /** Both or neither. Neither means the WHOLE take — the migration rule for
16000
- * every mask written before ranges existed. */
16001
- start: MarkerSchema2.optional(),
16002
- end: MarkerSchema2.optional()
16000
+ * every mask written before ranges existed. In the frames' own time
16001
+ * since v13, as a removed piece is: a redaction follows the frames it
16002
+ * covers through every later cut, gap and hold (audit run 1). */
16003
+ start: SourcePointSchema.optional(),
16004
+ end: SourcePointSchema.optional()
16003
16005
  });
16004
16006
  var Hold = external_exports.object({
16005
16007
  id: external_exports.string().min(1),
@@ -16361,7 +16363,7 @@ Set the \`cycles\` parameter to \`"ref"\` to resolve cyclical schemas with defs.
16361
16363
  });
16362
16364
  }
16363
16365
  }
16364
- if (m.start !== void 0 && m.end !== void 0 && m.start.actionId === m.end.actionId && m.end.offsetMs <= m.start.offsetMs) {
16366
+ if (m.start !== void 0 && m.end !== void 0 && m.start.actionId === m.end.actionId && m.end.sourceOffsetMs <= m.start.sourceOffsetMs) {
16365
16367
  ctx.addIssue({
16366
16368
  code: "custom",
16367
16369
  message: `mask "${m.id}" ends before it starts`,
@@ -15979,7 +15979,7 @@ Set the \`cycles\` parameter to \`"ref"\` to resolve cyclical schemas with defs.
15979
15979
  });
15980
15980
 
15981
15981
  // ../../packages/scene-schema/dist/document.js
15982
- var CURRENT_SCHEMA_VERSION = 12;
15982
+ var CURRENT_SCHEMA_VERSION = 13;
15983
15983
  var Rect = external_exports.object({
15984
15984
  x: external_exports.number(),
15985
15985
  y: external_exports.number(),
@@ -16228,9 +16228,11 @@ Set the \`cycles\` parameter to \`"ref"\` to resolve cyclical schemas with defs.
16228
16228
  rect: Rect,
16229
16229
  note: external_exports.string().optional(),
16230
16230
  /** Both or neither. Neither means the WHOLE take — the migration rule for
16231
- * every mask written before ranges existed. */
16232
- start: MarkerSchema2.optional(),
16233
- end: MarkerSchema2.optional()
16231
+ * every mask written before ranges existed. In the frames' own time
16232
+ * since v13, as a removed piece is: a redaction follows the frames it
16233
+ * covers through every later cut, gap and hold (audit run 1). */
16234
+ start: SourcePointSchema.optional(),
16235
+ end: SourcePointSchema.optional()
16234
16236
  });
16235
16237
  var Hold = external_exports.object({
16236
16238
  id: external_exports.string().min(1),
@@ -16592,7 +16594,7 @@ Set the \`cycles\` parameter to \`"ref"\` to resolve cyclical schemas with defs.
16592
16594
  });
16593
16595
  }
16594
16596
  }
16595
- if (m.start !== void 0 && m.end !== void 0 && m.start.actionId === m.end.actionId && m.end.offsetMs <= m.start.offsetMs) {
16597
+ if (m.start !== void 0 && m.end !== void 0 && m.start.actionId === m.end.actionId && m.end.sourceOffsetMs <= m.start.sourceOffsetMs) {
16596
16598
  ctx.addIssue({
16597
16599
  code: "custom",
16598
16600
  message: `mask "${m.id}" ends before it starts`,
@@ -17331,6 +17333,46 @@ Set the \`cycles\` parameter to \`"ref"\` to resolve cyclical schemas with defs.
17331
17333
  return null;
17332
17334
  return toOutputMs(timeline, sourceMs) + marker.offsetMs;
17333
17335
  }
17336
+ function outputSpanOfSource(timeline, srcStartMs, srcEndMs) {
17337
+ let startMs = Number.POSITIVE_INFINITY;
17338
+ let endMs = Number.NEGATIVE_INFINITY;
17339
+ for (const s of timeline.segments) {
17340
+ const lo = Math.max(srcStartMs, s.srcStartMs);
17341
+ const hi = Math.min(srcEndMs, s.srcEndMs);
17342
+ if (lo > hi)
17343
+ continue;
17344
+ const span = s.srcEndMs - s.srcStartMs;
17345
+ const out = (src, still) => span === 0 ? still : s.outStartMs + (s.outEndMs - s.outStartMs) * (src - s.srcStartMs) / span;
17346
+ startMs = Math.min(startMs, out(lo, s.outStartMs));
17347
+ endMs = Math.max(endMs, out(hi, s.outEndMs));
17348
+ }
17349
+ return startMs <= endMs ? { startMs, endMs } : null;
17350
+ }
17351
+ function resolveMaskRange(args) {
17352
+ const { timeline } = args;
17353
+ const unplaced = [];
17354
+ const srcOf = (p, side, ifNone) => {
17355
+ const marker = args.markerSourceMs.get(p.actionId);
17356
+ if (marker === void 0) {
17357
+ unplaced.push(side);
17358
+ return ifNone;
17359
+ }
17360
+ return marker + p.sourceOffsetMs;
17361
+ };
17362
+ const srcStart = srcOf(args.start, "start", 0);
17363
+ const srcEnd = srcOf(args.end, "end", timeline.sourceDurationMs);
17364
+ const span = outputSpanOfSource(timeline, srcStart, srcEnd);
17365
+ if (span !== null && span.endMs > span.startMs) {
17366
+ return { range: span, unplaced, clamped: null };
17367
+ }
17368
+ const at = span?.startMs ?? clamp(toOutputMs(timeline, srcStart), 0, timeline.outputDurationMs);
17369
+ const note = srcEnd < srcStart ? `mask "${args.id}" ends ${Math.round(srcStart - srcEnd)}ms before it starts in the recording, so it covers nothing` : `mask "${args.id}" covers no frame of the video: every frame between its ends was removed`;
17370
+ return {
17371
+ range: { startMs: at, endMs: at },
17372
+ unplaced,
17373
+ clamped: { id: args.id, kind: "mask", note }
17374
+ };
17375
+ }
17334
17376
  function resolveRange(args) {
17335
17377
  const { timeline } = args;
17336
17378
  const duration3 = timeline.outputDurationMs;
@@ -17926,15 +17968,14 @@ Set the \`cycles\` parameter to \`"ref"\` to resolve cyclical schemas with defs.
17926
17968
  var COMPOSITOR_VERSION = "1.1.0";
17927
17969
 
17928
17970
  // ../../packages/compositor/dist/plan/cosmetics.js
17929
- function planCosmetics(scene, cutSteps, attached) {
17930
- return scene.edits.masks.flatMap((m) => {
17931
- const range = m.start && m.end ? { start: m.start, end: m.end } : null;
17932
- if (range && cutSteps.has(range.start.actionId)) {
17933
- attached.push({ id: m.id, kind: "mask", actionId: range.start.actionId });
17934
- return [];
17935
- }
17936
- return [{ id: m.id, kind: "mask", rect: m.rect, range }];
17937
- });
17971
+ function planCosmetics(scene) {
17972
+ return scene.edits.masks.map((m) => ({
17973
+ id: m.id,
17974
+ kind: "mask",
17975
+ rect: m.rect,
17976
+ // Both or neither, by the schema's refinement. Neither is the whole take.
17977
+ range: m.start && m.end ? { start: m.start, end: m.end } : null
17978
+ }));
17938
17979
  }
17939
17980
 
17940
17981
  // ../../packages/compositor/dist/plan/plan.js
@@ -18007,7 +18048,7 @@ Set the \`cycles\` parameter to \`"ref"\` to resolve cyclical schemas with defs.
18007
18048
  // the author never recorded.
18008
18049
  cursorSegments: planCursorSegments(scene, rectOf),
18009
18050
  cameraIntents: planCameraIntents(scene, cutSteps, attachedToCuts),
18010
- cosmetics: planCosmetics(scene, cutSteps, attachedToCuts),
18051
+ cosmetics: planCosmetics(scene),
18011
18052
  holds: (scene.edits.holds ?? []).flatMap((hold) => {
18012
18053
  if (cutSteps.has(hold.marker.actionId)) {
18013
18054
  attachedToCuts.push({
@@ -19068,9 +19109,8 @@ Set the \`cycles\` parameter to \`"ref"\` to resolve cyclical schemas with defs.
19068
19109
  let range = null;
19069
19110
  let unplaced = [];
19070
19111
  if (binding.range) {
19071
- const resolved = resolveRange({
19112
+ const resolved = resolveMaskRange({
19072
19113
  id: binding.id,
19073
- kind: "mask",
19074
19114
  start: binding.range.start,
19075
19115
  end: binding.range.end,
19076
19116
  timeline,
@@ -19118,6 +19158,10 @@ Set the \`cycles\` parameter to \`"ref"\` to resolve cyclical schemas with defs.
19118
19158
  throw new Error("frame bundle has no keyframes; cannot resolve a frame");
19119
19159
  return keyframe;
19120
19160
  }
19161
+ function keyframesBetween(bundle, fromMs, toMs) {
19162
+ const first = keyframeAt(bundle, fromMs);
19163
+ return bundle.keyframes.filter((k) => k === first || k.sourceTimeMs > fromMs && k.sourceTimeMs <= toMs);
19164
+ }
19121
19165
 
19122
19166
  // ../../packages/compositor/dist/ports/frame-source-images.js
19123
19167
  function createImageFrameSource(bundle, load2) {
@@ -19141,6 +19185,11 @@ Set the \`cycles\` parameter to \`"ref"\` to resolve cyclical schemas with defs.
19141
19185
  const image = await get(keyframe.ref);
19142
19186
  return { ...image, sourceTimeMs: keyframe.sourceTimeMs };
19143
19187
  },
19188
+ warm(fromSourceMs, toSourceMs2) {
19189
+ for (const keyframe of keyframesBetween(bundle, fromSourceMs, toSourceMs2)) {
19190
+ get(keyframe.ref).catch(() => void 0);
19191
+ }
19192
+ },
19144
19193
  describe: () => ({
19145
19194
  keyframes: bundle.keyframes,
19146
19195
  motionSpans: bundle.motionSpans
@@ -46568,6 +46617,11 @@ Set the \`cycles\` parameter to \`"ref"\` to resolve cyclical schemas with defs.
46568
46617
  sourceTimeMs: keyframe.sourceTimeMs
46569
46618
  };
46570
46619
  },
46620
+ warm(fromSourceMs, toSourceMs2) {
46621
+ for (const keyframe of keyframesBetween(bundle, fromSourceMs, toSourceMs2)) {
46622
+ still(keyframe.ref).catch(() => void 0);
46623
+ }
46624
+ },
46571
46625
  describe: () => ({
46572
46626
  keyframes: bundle.keyframes,
46573
46627
  motionSpans: bundle.motionSpans
package/dist/recipe.md CHANGED
@@ -11,12 +11,13 @@ the user; section 7 lists every reason.
11
11
  1. Call `status`. It answers `executor` (`"cli"`), `version`,
12
12
  `browserInstalled`, `browserRunning`, `runnerVersion`, `runPage` (the
13
13
  latest run's report or its progress, or null), `sessions`, `accounts`,
14
- `secretsFile` and `update`.
14
+ `secretsFile`, `expiry` and `update`.
15
15
  `sessions` is `[{site, savedAt, refreshedAt, signInUrl}]`; it and
16
- `display` (the screen headless records as) can be `{unreadable}`: tell the user why. `accounts` and `secretsFile` are the demo
17
- accounts below. The browser starts on the first `snapshot`, `run`
18
- or `export`. Demoman updates itself: say nothing about `update`. When `browserInstalled` is false, the first
19
- `snapshot` or `run` answers `browserMissing`.
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`.
20
21
  2. The browser is signed in wherever the user ran `npx demoman signin <url>`,
21
22
  and nowhere else; `status`'s `sessions` lists those sites. A demo account records best. A page
22
23
  that sends this browser to its sign-in page answers `signedOut` (section
@@ -29,8 +30,8 @@ the user; section 7 lists every reason.
29
30
  hidden on disk and in the report.
30
31
  3. Takes are saved under `<DEMOMAN_HOME, default ~/.demoman>/takes/<id>/`.
31
32
  `takes` lists them, newest first: `id`, `name`, `createdAt`, `mode`,
32
- `actions`. A folder that is not a readable take comes last as
33
- `{ id, unreadable }`, saying why. Demoman keeps no telemetry.
33
+ `actions`; an unreadable folder comes last as `{ id, unreadable }`.
34
+ Demoman keeps no telemetry.
34
35
 
35
36
  ### Behind a login: demo accounts
36
37
 
@@ -70,15 +71,16 @@ its site. Then, in this order:
70
71
  create a demo account and the data the demo needs, with a seed script
71
72
  committed in the app and safe to run twice (`priv/repo/demo_seeds.exs`,
72
73
  `db/seeds/demo.rb`). Generate a random password of 20 or more characters.
73
- Write `DEMOMAN_SECRET_<NAME>=…` to `.demoman/secrets.env`, and add
74
+ Write `DEMOMAN_SECRET_<NAME>=…` and
75
+ `DEMOMAN_SECRET_<NAME>_ORIGIN=<the site's origin>` to
76
+ `.demoman/secrets.env`, and add
74
77
  `.demoman/secrets.env` to `.gitignore` if it is missing. Add the account
75
78
  to `accounts.json`. Tell the user in one line.
76
79
  Then `snapshot` again.
77
80
  3. **Two-factor or a magic link in the way:** add a dev-only "sign in as"
78
81
  route, reachable only in development, and make the account's `signIn` one
79
82
  `goto` to it. Phoenix:
80
- `if Mix.env() == :dev, do: get "/dev/sign-in-as/:email", DevController, :sign_in`.
81
- Rails: `get "/dev/sign_in_as/:email", to: "dev#sign_in" if Rails.env.development?`.
83
+ `if Mix.env() == :dev, do: get "/dev/sign-in-as/:email", DevController, :sign_in`; Rails: the same under `Rails.env.development?`.
82
84
  The action starts a session; nothing else.
83
85
  4. **The database is not clearly local** (a remote `DATABASE_URL`, staging,
84
86
  production): create nothing. Ask the user, or give them
@@ -113,24 +115,22 @@ The file, with one account:
113
115
  ```
114
116
 
115
117
  - Sites are keyed by origin. An account name is lower-case letters,
116
- digits, `-` and `_`, starting with a letter or digit, at most 64
117
- characters: `seller`, `demo-customer`. `signIn` uses the script's steps and targets
118
+ digits, `-` and `_`, at most 64: `seller`. `signIn` uses the script's steps and targets
118
119
  (`type` names its field with `into`; copy targets from a `snapshot` of the
119
120
  login page) plus `goto`, which must be the first step. `checkUrl` is
120
121
  required: a page behind the login, a path on the origin, that a browser
121
- signed in to nothing cannot open (the app redirects it to its sign-in
122
- page, or shows a password form there) and that shows no password field
123
- once signed in. Demoman opens it signed out first and treats where it
124
- lands as the sign-in page. `about` names who the account is and what data
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
125
  it has, so the next agent reuses it.
126
126
  - `{secret:NAME}` goes in a `signIn` step's `text`, `NAME` being
127
127
  `[A-Z0-9_]+`, not ending in `_ORIGIN`. Demoman reads
128
128
  `DEMOMAN_SECRET_NAME` from the environment, else the same line of
129
129
  `.demoman/secrets.env`, which it reads only when git ignores it. A value
130
- is at least 8 characters. An environment value is typed only with
131
- `DEMOMAN_SECRET_NAME_ORIGIN` beside it, naming the account's site; the
132
- user sets both, and you never set or change them. `secrets.env` lines
133
- need no origin. A `{secret:…}` in a demo
130
+ 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
134
  script is refused (`invalidScript`): secrets work only in `signIn`.
135
135
  Environment secrets serve only the accounts.json of the repo Demoman was
136
136
  started in; one reached through `project` reads only its own
@@ -157,10 +157,6 @@ The file, with one account:
157
157
  (`{account, steps, ms}`) in the snapshot or the report says it did. A
158
158
  second failure answers `signInFailed`. A session that lapses mid-run keeps
159
159
  no take; Demoman has signed in again: just run again.
160
- - In CI: `npx demoman signin --account <name>` as a smoke step (`--site
161
- <origin>` when two sites share a name, `--project <dir>` for another
162
- folder), with `DEMOMAN_SECRET_*` from the CI provider's secrets,
163
- each with its `DEMOMAN_SECRET_*_ORIGIN`.
164
160
 
165
161
  ## 2. Look at the page
166
162
 
@@ -169,8 +165,7 @@ and leaves the page open. Each entry is
169
165
  `{ target, kind, text, rect, inFirstViewport }`. Every `target` listed is one
170
166
  a run resolves to exactly that element: Demoman checked it.
171
167
 
172
- `snapshot` may answer `stillRunning` with an `id` after about 50 s, like
173
- `run`: call `report(id)`.
168
+ `snapshot` may answer `stillRunning` too: call `report(id)`.
174
169
 
175
170
  - **Copy a `target` into a step verbatim. Never compose one**, and never
176
171
  translate a name from another tool's accessibility tree: Demoman's roles
@@ -209,11 +204,10 @@ a run resolves to exactly that element: Demoman checked it.
209
204
  for the part you need; with it given, a positive count means narrow it
210
205
  further.
211
206
  - Iframe and shadow-root elements are not listed.
212
- - A snapshot sees only the page as it loads: no steps. Hidden content
213
- already in the page is listed. Content a click creates (a dialog or menu
214
- built when it opens) is not, so a step on it has no target: tell the user
215
- it cannot be scripted yet. Never compose its target. A page the flow
216
- navigates to has its own URL to snapshot.
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.
217
211
 
218
212
  ### Recording a phone demo
219
213
 
@@ -272,19 +266,26 @@ to change and run again.
272
266
  - `unreadable` - a stored take cannot be read; report its `reason`.
273
267
  - `threw` - report its `error`.
274
268
 
275
- **Re-recording an edited take.** `run({ takeId })` runs a take again from its
276
- saved script and its current `scene.json`: the steps' text and targets,
277
- name and look as they are now, the original's pauses, and any step added
278
- since. It is a run: a new take, counted toward the three. Pass `takeId` instead of `script`; both
279
- or neither is `invalidScript`. Refused with `unfilledHoles` when
280
- the take did not keep a value (a redacted field): `derive`, fill, `run`.
281
- Refused with `invalidScript` (`field` `steps.<i>.do`) when a step's verb
282
- was changed by hand: `derive`, check that step, `run` the draft.
283
- Refused with `nothingToRerecord` when no step that acts is left.
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
274
+ verb was changed by hand: `derive`, check it, `run` the draft.
284
275
 
285
276
  ## 4. Run and read
286
277
 
287
- 1. `run(script)`. It answers the run's report, or
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.
284
+ `possibleDuplicate` lists `matches`: use one's `id`, or repeat with
285
+ `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
288
289
  `{ "outcome": "stillRunning", "id": … }` after about 50 s; then call
289
290
  `report(id)` until the outcome is neither `running` nor `stillRunning`.
290
291
  Never `run` again while one is in progress: it is refused
@@ -310,10 +311,9 @@ Refused with `nothingToRerecord` when no step that acts is left.
310
311
  show the way the script asked. `matches` with every
311
312
  `steps[i].candidates` at 1 means the steps are right.
312
313
  - In any outcome, a step whose `textHidden` is set typed into a credential
313
- field (`"credentialField"`) or the page could not say whether it was
314
- (`"credentialUnchecked"`): its text is kept nowhere, and `intent.text` reads `(hidden: typed into a
315
- credential field)`. Re-recording or deriving that take asks for a demo
316
- value. `landing.startedElsewhere` names where the start URL went
314
+ 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
317
  instead; `landing.unchecked`: the page could not be checked for a
318
318
  sign-in page. `notStored` with `what: "session"` means the saved
319
319
  session could not be refreshed: name it to the user.
@@ -328,10 +328,8 @@ Refused with `nothingToRerecord` when no step that acts is left.
328
328
  `frames.unconfirmedClicks` names each such step and says why; check in
329
329
  the video that the step did what it should before saying so.
330
330
  - A re-recording's report carries `rerecord`: `from` (the take), `notes`
331
- (`noSkeleton` or `skeletonUnreadable`: the original's pauses were not
332
- kept; `stepDropped`, with `why` `actionGone` or `neverPerformed`;
333
- `actionAdded`: a `scene.json` step the saved script lacked;
334
- `migrated`: a `sentence`) and `notCarried` (each `removed`, `split`,
331
+ (as `report.skeleton` above, `stepDropped` with `why` `actionGone` or
332
+ `neverPerformed`; `migrated`: a `sentence`) and `notCarried` (each `removed`, `split`,
335
333
  mask, hold, gap or trim the old take had and the new one lacks, and
336
334
  each zoom the editor aimed or ended by hand, `zoom`; every other zoom
337
335
  the new take makes again from its own clicks). Name every
@@ -346,8 +344,7 @@ Refused with `nothingToRerecord` when no step that acts is left.
346
344
  whose `actionId` equals `video.steps[i].actionId`; `steps[k].index` is
347
345
  its 0-based position in your script.
348
346
  - `video` may be `{ "unavailable": … }` (`refused`, `noTake`, `noFrames`,
349
- `checkFailed` with `error`): the check could not look. That is not a
350
- clean bill; say so, and do not retry. Likewise
347
+ `checkFailed` with `error`): not a clean bill; say so, do not retry. Likewise
351
348
  `video.steps[i].unknown` and `video.noCursor: true`.
352
349
  - `recording` is `{ "unavailable": … }` or
353
350
  `{ recordingTakeId, steps[], notInRecording[] }`, comparing the run with
@@ -368,8 +365,7 @@ Refused with `nothingToRerecord` when no step that acts is left.
368
365
  than the target you named.
369
366
 
370
367
  **Stop after three runs**, done or not, then export: every run drives the
371
- user's real app. A take
372
- zooms on every click and starts from the kit named in `look.kit`, else the
368
+ user's real app. A take zooms on every click and starts from the kit named in `look.kit`, else the
373
369
  user's default brand kit; a draft derived from a take keeps that take's
374
370
  branding. The report's `look.branding` says where it came from: `script`,
375
371
  `kit` (you named it; `look.kit.name` says which), `defaultKit`, or
@@ -410,12 +406,12 @@ too.
410
406
  lacks (a logo, motion, a still, an edit). `warnings` holds more:
411
407
  Demoman's own calls (`zooms`, `detailViolations`, a size cap's `steps`,
412
408
  a GIF's widths, `targetCheck`). They are
413
- not the user's to act on: do not pass them on. None is the script's to
414
- fix either.
409
+ not the user's to act on: do not pass them on. None is the script's to fix.
415
410
  `warnings.editedSinceRecorded` lists steps whose `scene.json` no longer
416
411
  matches the frames; the summary says so and names the re-recording
417
- (`run({ takeId })`, or `derive` then `run` when a step's verb changed).
418
- Re-record only on request.
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.
419
415
  `links` holds the export's one-click actions for the user, each present
420
416
  only where it works: `studio`, `file` (the file itself) and `copy` (the
421
417
  file to the clipboard; none for stills). `linksError`, set instead, says
@@ -439,18 +435,15 @@ in another checkout): `attach`, `ask`, `off`, or `{ unreadable, file }`,
439
435
  which is not `off`: tell the user. `off`: only when asked. If the diff
440
436
  changes something a user would see, record that one flow (only the change),
441
437
  push and open the PR, then `attach({ takeId, into: "description" })`, or
442
- `"comment"` on a PR that is not yours. A later `gh pr edit --body` drops the
443
- video. `ask`: offer once; on a no, nothing to see or a failed run (say why),
438
+ `"comment"` on a PR that is not yours. A later `gh pr edit --body` drops the video. `ask`: offer once; on a no, nothing to see or a failed run (say why),
444
439
  the PR says nothing of it. `attach`: with no video, the PR description gets
445
440
  one line, `No demo: <why>`, and so does the user.
446
441
  `attach` takes `maxMB` as `export` does. On `stillRunning`, `report(id)`
447
442
  until the outcome is none of `attaching`, `stillRunning`. On `busy`,
448
- `report(id)` on the export in flight, then `attach` again. On `ghMissing`, `ghOutdated`,
449
- `ghSignedOut`, `notGitHub` or `copyFailed`, call
443
+ `report(id)` on the export in flight, then `attach` again. On `ghMissing`,
444
+ `ghOutdated`, `ghSignedOut`, `notGitHub` or `copyFailed`, call
450
445
  `export({ takeId, maxMB: 9.5 })` and give the user that `file.path` to drag
451
- into the PR, saying why: the browser refuses video over 10 MB on a free
452
- plan. On `uploadRefused`, do as its `detail` says: one more `attach` with
453
- `maxMB: 9.5`, or the file by hand. On `partial` or `unconfirmed`, do not
446
+ into the PR, saying why. On `uploadRefused`, do as its `detail` says. On `partial` or `unconfirmed`, do not
454
447
  post again; tell the user to look at the PR. For the other reasons, follow
455
448
  section 7. An export that did not save comes back as the export's answer.
456
449
 
@@ -464,9 +457,8 @@ outcome, say it with its `error` or `detail`, quoted.
464
457
  When the `studio` tool is listed and there is no `links.studio` (after a
465
458
  run with no export), **offer** it; never open it unasked. `studio({ takeId })`
466
459
  opens a window where the person edits and exports the take.
467
- `{ outcome: "opened", url, takeId?, note? }`: say the window is open and
468
- quote `note` if set; `url` is single-use, never offer it. Studio exports go
469
- to `~/Downloads`.
460
+ `{ outcome: "opened", takeId?, note? }`: say the window is open and
461
+ quote `note` if set. Studio exports go to `~/Downloads`.
470
462
 
471
463
  ## 6. The format
472
464
 
@@ -531,12 +523,11 @@ recorded action each step came from (`recorded`, in `recordedFrom`):
531
523
  `viewport`, not both. A device has no hover, so a `hover` step under one is
532
524
  refused. `look` takes `branding` or `kit`, plus `cursor`, `canvas` and
533
525
  `motion`; absent means the user's default brand kit. `kit` names one of
534
- the user's brand kits, as `snapshot`'s `kits` lists them (case does not
535
- matter); name a kit or give a branding, not both. An unknown key in
536
- `look` is refused and named. A `branding` is the whole of one: `background`, `logo` (or `null`) and `padding`, the
537
- margin around the recording as a fraction of the frame's shorter side
538
- (0 to 0.2). A `padding` left out is 0.08; a missing `background` or
539
- `logo` is refused and named.
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
528
+ `branding` is the whole of one: `background`, `logo` (or `null`) and
529
+ `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.
540
531
  A `canvas` is `{ "aspect": "auto" | "16:9" | "9:16" }`; `auto`, the
541
532
  default, is the recording's own shape plus an even margin.
542
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.
@@ -550,13 +541,13 @@ recorded action each step came from (`recorded`, in `recordedFrom`):
550
541
  | Reason | Where | What it means, and the move |
551
542
  | --- | --- | --- |
552
543
  | `browserMissing` | `snapshot`, `run` (`refusedBeforeRun`), `studio` | Demoman's browser is not installed; `detail` gives the command that installs it. Ask the user to run it, then call again. |
553
- | `sessionUnreadable` | `snapshot`, `run` (`refusedBeforeRun`) | A saved session file or folder could not be read, or others can read it; `detail` names it and the fix (often a `chmod`). Tell the user; it is not the script's. |
544
+ | `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. |
554
545
  | `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. |
555
- | `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` names the account, the step and where it landed. It tried once. Fix the account's steps or the secret, or tell the user; do not run again unchanged. |
556
- | `secretMissing` | `snapshot`, `run` (`refusedBeforeRun`) | A `{secret:NAME}` has no `DEMOMAN_SECRET_NAME` and no line in `.demoman/secrets.env`; `detail` names `NAME` and both places. Through `project`, the environment is not used, and `detail` says so when it holds the name. Write one (section 1), or ask the user. |
546
+ | `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. |
547
+ | `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. |
557
548
  | `secretTooShort` | `snapshot`, `run` (`refusedBeforeRun`) | The secret `NAME` is under 8 characters. Generate a longer one and write it again. |
558
- | `secretUnbound` | `snapshot`, `run` (`refusedBeforeRun`) | `DEMOMAN_SECRET_NAME` is in Demoman's environment with no `DEMOMAN_SECRET_NAME_ORIGIN`, or one that is not an origin; `detail` names the variable and the site. Nothing was typed. Tell the user; never set it yourself. |
559
- | `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 an environment secret's `_ORIGIN` names another site; `detail` names both. Nothing was typed. Check the account's site and `goto`, then tell the user. |
549
+ | `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. |
550
+ | `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. |
560
551
  | `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. |
561
552
  | `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. |
562
553
  | `accountsInvalid` | `snapshot`, `run` (`refusedBeforeRun`) | `.demoman/accounts.json` is malformed or breaks a rule; `detail` names the field and the rule. Fix the file. |
@@ -565,38 +556,46 @@ recorded action each step came from (`recorded`, in `recordedFrom`):
565
556
  | `ghMissing`, `ghOutdated`, `ghSignedOut` | `attach` (`refusedBeforeAttach`) | `gh` is missing, too old or signed out; `detail` gives the fix. Hand the user the file (section 5). |
566
557
  | `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. |
567
558
  | `invalidAttach` | `attach` (`refusedBeforeAttach`) | The call is malformed; `detail` says how. Fix it. |
568
- | `uploadRefused` | `attach` (`notAttached`) | GitHub refused the video and nothing landed. Retry as the Pull requests text says. |
559
+ | `uploadRefused` | `attach` (`notAttached`) | GitHub refused the video. Retry as the Pull requests text says. |
569
560
  | `partial` | `attach` (`notAttached`) | `gh` failed but the video is on the PR; do not post again. |
570
- | `unconfirmed` | `attach` (`notAttached`) | Unknown what landed: the PR shows nothing new, or could not be read back. Do not post again; tell the user to look at it. |
561
+ | `unconfirmed` | `attach` (`notAttached`) | Unknown what landed. Do not post again; tell the user to look at the PR. |
571
562
  | `copyFailed` | `attach` (`notAttached`) | The video could not be copied to post it; nothing was posted. Hand the user the capped export's file. |
572
563
  | `windowDidNotOpen` | `snapshot`; `run` (`refusedBeforeRun`); `studio` | The window would not open; try once more. |
573
564
  | `studioDidNotStart` | `studio` | The Studio did not start; `detail` quotes the end of `~/.demoman/studio.log`. Tell the user, quoting it. |
574
565
  | `alreadyRunning` | `snapshot`, `run`, `derive` | A run, snapshot or export is in progress. Call `report(id)` on it and try again when it settles. |
575
566
  | `busy` | `export` (`refusedBeforeExport`) | The same, for an export: a run or snapshot is in progress. Call `report(id)` on that call first. |
576
- | `browserSilent` | `status`, `takes`, `derive`, `report` | Demoman's browser did not answer within about 50 s (frozen, or still starting). Call `status` once; if it answers this again, tell the user. From `report`, the run may still be going: call `report(id)` again. |
567
+ | `browserSilent` | `status`, `takes`, `derive`, `report` | The browser did not answer within about 50 s. Call `status` once; if it answers this again, tell the user. From `report`, the run may still be going: call `report(id)` again. |
577
568
  | `libraryUnreadable` | `takes`, `studio` | The library could not be read; report it. |
578
- | `libraryUnwritable` | `run` (in `notStored`) | Not a `reason`: a take that cannot be written gives the report a `notStored` entry `{ "what": "take", "error": … }` naming the path, and a null `provenance.takeId`. Nothing was saved; quote the `error`. |
569
+ | `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`. |
579
570
  | `unknownRun` | `report` | This demoman-mcp never issued that id (ids do not survive a restart of the server). |
580
- | `noReport` | `report` | No report for that id: this server keeps only its latest runs and exports (an old one was let go), or the call left none; `detail` says which. Do not run again for it. |
571
+ | `noReport` | `report` | No report for that id: this server keeps only its latest; `detail` says which. Do not run again for it. |
581
572
  | `notAnObject` | `run` | The script is not a JSON object. |
582
573
  | `invalidScript` | `run` | The schema refused the script; `field` names where. |
583
- | `unfilledHoles` | `run` | A derived draft still has holes (section 3); also `run({ takeId })` of a take that did not keep a value. |
574
+ | `unfilledHoles` | `run` | A derived draft still has holes (section 3); also a re-record of a take that did not keep a value. |
575
+ | `videoRequired` | `run` (`refusedBeforeRun`) | No `video` was given. Find one (section 4), or pass `{ new }`. |
576
+ | `possibleDuplicate`, `nameTaken` | `run` (`refusedBeforeRun`) | A similar video exists (`matches`) or the name is taken (`holder`). Section 4. |
577
+ | `videoNotFound` | `run` (`refusedBeforeRun`) | No video has that `id`; call `videos`. |
578
+ | `videoUnreadable`, `videoUnwritable` | `run` (`refusedBeforeRun`), `videos` | The video records could not be read or written; quote `detail`. Nothing was recorded. |
579
+ | `noTag`, `unknownVideo`, `fileNotFound` | `videos` | The file has no Demoman tag; its video is not in this library; no file there. Use `query` instead. |
580
+ | `invalidArgs` | `videos` | `file` with `query`, or not an absolute path. |
581
+ | `versionExpired` | `export` (`refusedBeforeExport`) | The take's frames expired: `run({ video: { id } })`, then export. |
582
+ | `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
583
  | `nothingToRerecord` | `run` (`refusedBeforeRun`) | The take has no step left that acts; tell the user. |
585
584
  | `unknownKit` | `run` (`refusedBeforeRun`) | `look.kit` names no brand kit, or one that cannot be read; `detail` lists the kits there are. Fix the name from `snapshot`'s `kits`, or ask the user. |
586
585
  | `kitsUnreadable` | `run` (`refusedBeforeRun`) | The brand kits file could not be read, so `look.kit` could not be checked; not a wrong name. Quote `detail` to the user; do not change the name. |
587
586
  | `invalidDevice` | `snapshot` | `device` names no phone or tablet Demoman has; `detail` lists the ones it does. Use one of them. |
588
- | `deviceFailed` | `snapshot`, `run` | The browser would not emulate the device, so nothing was listed or recorded; `detail` says which command and why. Not the script's: tell the user; do not run it again. |
587
+ | `deviceFailed` | `snapshot`, `run` | The browser would not emulate the device; nothing was listed or recorded; `detail` says why. Tell the user; do not run it again. |
589
588
  | `nonHttpTarget` | `run`, `snapshot` | The target or url is not `http(s)`, or its host contains `*`. |
590
589
  | `invalidFileType` | `export` (`refusedBeforeExport`) | Not answered here: the schema takes only `mp4`, `gif`, `stills`. |
591
590
  | `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. |
592
591
  | `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
592
  | `noTakeId`, `noFrames` | `export` (`refusedBeforeExport`) | No take id; the take has no frames to render. |
594
- | `takeNotFound`, `takeUnreadable` | `export` (`refusedBeforeExport`), `run` with `takeId` (`refusedBeforeRun`), `studio` (`takeNotFound`: call `takes`) | No such take; the take could not be read (or, for `run`, built into a script). |
593
+ | `takeNotFound`, `takeUnreadable` | `export` (`refusedBeforeExport`), `run` re-record (`refusedBeforeRun`), `studio` (`takeNotFound`: call `takes`) | No such take; the take could not be read (or, for `run`, built into a script). |
595
594
  | `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.at` names the step and `stopped.detail` says where the click went. Not the script's fault: run again (it counts toward the three); tell the user if it repeats. |
597
- | `signedOut` | `run` (`stopped.reason`) | The app sent this browser to its sign-in page: no saved session signs this page in. Nothing was recorded or kept. Give the user the command in `stopped.detail`; run again only after they have run it. As an account there is no command to give: the detail says whether Demoman signed in again; repeat only if it says so. |
598
- | `windowClosed` | `run` (`stopped.reason`) | `--headed` only: Demoman's window was closed before the run finished; the script is fine. Ask the user to leave it open; run once more. During an export it answers `renderFailed`; export again. |
599
- | `pageDidNotLoad` | `snapshot` | The url did not load: the browser showed its own error page. Ask the user whether the app is running at that address; spend no run. |
600
- | `pageSilent` | `snapshot` | The page never answered, or took too long. Call once more, and if it answers this again, the page blocked Demoman's script; tell the user. |
601
- | `pageFaulted` | `snapshot` | The page's own code threw while Demoman walked it; quote `detail`. |
595
+ | `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. |
596
+ | `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 have run it. As an account there is no command: the detail says whether Demoman signed in again; repeat only if it says so. |
597
+ | `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. |
598
+ | `pageDidNotLoad` | `snapshot` | The url did not load. Ask the user whether the app is running at that address; spend no run. |
599
+ | `pageSilent` | `snapshot` | The page never answered. Call once more; if again, the page blocked Demoman's script; tell the user. |
600
+ | `pageFaulted` | `snapshot` | The page's own code threw; quote `detail`. |
602
601
  | `snapshotThrew` | `snapshot` | A fault in the snapshot; quote `detail`. |
@@ -11,11 +11,14 @@ this machine, then render the take to an MP4.
11
11
  1. Call the `recipe` tool and follow it. It is the whole procedure: the
12
12
  script format with examples, how to read each report, and what every
13
13
  refusal means. Do not write a script before reading it.
14
- 2. The browser is signed in only where the user ran `npx demoman signin <url>`
14
+ 2. Every run belongs to a video. Before recording, find it: `videos` with
15
+ `file` (an exported video the repo already has) or else `query`; then
16
+ `run` with `video: { id }`, or `video: { new: "<name>" }` for a new one.
17
+ 3. The browser is signed in only where the user ran `npx demoman signin <url>`
15
18
  or where a demo account in `.demoman/accounts.json` signs it in. On
16
19
  `signedOut`, follow the recipe's "Behind a login: demo accounts": reuse one,
17
20
  or create one on a local development database, else give the user the
18
21
  command from its detail. Only demo accounts; never ask for the user's own
19
22
  password.
20
- 3. When `export` answers `saved`, end on two lines: `summary` as it is, then
23
+ 4. When `export` answers `saved`, end on two lines: `summary` as it is, then
21
24
  its `links` as markdown links on one line, as the recipe's hand-back says.