demoman 0.9.3 → 0.9.5

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.
@@ -15416,6 +15416,19 @@ Set the \`cycles\` parameter to \`"ref"\` to resolve cyclical schemas with defs.
15416
15416
  pressMs: external_exports.number().nonnegative(),
15417
15417
  releaseMs: external_exports.number().nonnegative()
15418
15418
  });
15419
+ var PageScreenSchema = external_exports.object({
15420
+ after: external_exports.number().int().min(0),
15421
+ sourceTimeMs: external_exports.number(),
15422
+ ref: external_exports.string(),
15423
+ width: external_exports.number().int().positive(),
15424
+ height: external_exports.number().int().positive(),
15425
+ heldAnimations: external_exports.number().int().min(0),
15426
+ waitedMs: external_exports.number().min(0),
15427
+ unsettled: external_exports.string().optional()
15428
+ }).refine((s) => s.ref !== "" || s.unsettled !== void 0, {
15429
+ message: 'a page screen with no bytes (ref "") must say why in `unsettled`',
15430
+ path: ["unsettled"]
15431
+ });
15419
15432
  var ViewportTransformSchema = external_exports.object({
15420
15433
  sourceTimeMs: external_exports.number().nonnegative(),
15421
15434
  scale: external_exports.number().positive(),
@@ -15541,7 +15554,27 @@ Set the \`cycles\` parameter to \`"ref"\` to resolve cyclical schemas with defs.
15541
15554
  // A native drag's picture could not be drawn in the page (the element
15542
15555
  // the page named for it was gone, or copying it threw). The drag still
15543
15556
  // ran; the film shows the card jump to its drop instead of travelling.
15544
- "dragPictureMissing"
15557
+ "dragPictureMissing",
15558
+ // A step's page had not settled when the cap ran out (requests in
15559
+ // flight, an animation running, the DOM still changing) or showed a
15560
+ // caret it would not hide: the page's own doing. The video is
15561
+ // unaffected; refresh cannot compare that screen. The note names the
15562
+ // step and the conditions.
15563
+ "stepUnsettled",
15564
+ // As `stepUnsettled`, but at least one condition was this machine's:
15565
+ // the first paint never came, the settle probe or the page screen
15566
+ // failed, requests could not be watched. Recording again may change
15567
+ // it, so refresh does (DEM-55); the note names the step and the
15568
+ // conditions, the page's beside the machine's.
15569
+ "stepSettleFailed",
15570
+ // A step's settle left out a request open since more than a request cap
15571
+ // before the step began (a long poll): its own step waited for it. The
15572
+ // screen counts as settled; the note names the step and how many.
15573
+ "requestNotWaited",
15574
+ // A page screen's hold (caret hidden, endless animations held) could not
15575
+ // be undone after the capture: the video after that step may show no
15576
+ // caret and frozen spinners. About the video, so not forgiven.
15577
+ "pageHoldNotReleased"
15545
15578
  ]),
15546
15579
  note: external_exports.string()
15547
15580
  });
@@ -15603,6 +15636,9 @@ Set the \`cycles\` parameter to \`"ref"\` to resolve cyclical schemas with defs.
15603
15636
  // 2026-10-11 carries none, and identity is what they were drawn as.
15604
15637
  // See `ViewportTransformSchema`.
15605
15638
  viewportTransforms: external_exports.array(ViewportTransformSchema).optional(),
15639
+ // Optional, and absent is none: a sampled replay, a capture, and every
15640
+ // bundle written before 2026-11-10 carry none.
15641
+ pageScreens: external_exports.array(PageScreenSchema).optional(),
15606
15642
  markers: external_exports.array(MarkerSchema),
15607
15643
  degradations: external_exports.array(DegradationSchema),
15608
15644
  /**
@@ -16337,14 +16373,14 @@ Set the \`cycles\` parameter to \`"ref"\` to resolve cyclical schemas with defs.
16337
16373
  * unchanged, but its MEANING narrows: this now records which frames PLAY,
16338
16374
  * not which the author chose. The editor writes it nowhere — since
16339
16375
  * 2026-09-28 every write the editor makes carries the store's current
16340
- * value (`persist()` in `apps/extension/src/editor/session.ts`). Two
16341
- * writers flip it, both outside the editor: the run page's re-shoot
16342
- * promotion (`promote` in `apps/extension/src/adapters/reshoot.ts`) sets
16343
- * `demo` when a re-shoot finishes complete, and the library card's "Back
16344
- * to your recording" (`backToRecording` in
16345
- * `apps/extension/entrypoints/library/main.ts`) sets `screen`. Neither
16346
- * deletes anything to do it — the recording stays on disk under either
16347
- * mode (`chooseActiveBundle`'s own docblock) — so a re-shoot that turns
16376
+ * value (`persist()` in `apps/studio/pages/src/editor/session.ts`). Two
16377
+ * writers set it, both outside the editor: `assembleAuthored`
16378
+ * (`@demoman/replay-engine`) writes `screen` on every new take, and the
16379
+ * library card's "Back to your recording"
16380
+ * (`apps/studio/pages/entrypoints/library/main.ts`) sets `screen`. Nothing writes `demo` today; it is
16381
+ * read from takes the retired extension re-shot. Neither writer deletes
16382
+ * anything — the recording stays on disk under either mode
16383
+ * (`chooseActiveBundle`'s own docblock) — so a re-shoot that turns
16348
16384
  * out worse than the recording is always reversible by writing this field
16349
16385
  * back.
16350
16386
  */
@@ -16939,9 +16975,10 @@ Set the \`cycles\` parameter to \`"ref"\` to resolve cyclical schemas with defs.
16939
16975
  branding: ScriptBrandingSchema.optional(),
16940
16976
  /**
16941
16977
  * One of the author's brand kits, by the name Settings shows (case and
16942
- * surrounding space ignored). Resolved by the extension at the run's
16943
- * door; a name that is not there is refused (`unknownKit`), never
16944
- * replaced by the default kit (spec 2026-10-08 §3).
16978
+ * surrounding space ignored). Resolved by the runner at the run's
16979
+ * door (`lookForRun`, in `@demoman/run-core`); a name that is not
16980
+ * there is refused (`unknownKit`), never replaced by the default kit
16981
+ * (spec 2026-10-08 §3).
16945
16982
  */
16946
16983
  kit: external_exports.string().trim().min(1).optional(),
16947
16984
  cursor: CursorSchema.optional(),
@@ -17957,9 +17994,9 @@ Set the \`cycles\` parameter to \`"ref"\` to resolve cyclical schemas with defs.
17957
17994
  verticalMaxScale: 1.15,
17958
17995
  /**
17959
17996
  * CSS px of page kept round a zoomed target on every side, so its edges
17960
- * and the cursor on it are not flush with the frame. The extension's
17961
- * generated zooms fit against the capture viewport with it
17962
- * (`zoomsForClicks`); a `cover` render fits against its own crop with it
17997
+ * and the cursor on it are not flush with the frame. Generated zooms fit
17998
+ * against the capture viewport with it (`zoomsForClicks`,
17999
+ * `@demoman/run-core`); a `cover` render fits against its own crop with it
17963
18000
  * (`solveCamera`'s `fitWindow`).
17964
18001
  */
17965
18002
  fitMarginPx: 24,
@@ -17973,8 +18010,8 @@ Set the \`cycles\` parameter to \`"ref"\` to resolve cyclical schemas with defs.
17973
18010
  */
17974
18011
  actSettleMs: 400,
17975
18012
  /**
17976
- * The push-in and the pull-out at the DEFAULT smoothness — what the
17977
- * extension sizes a fresh zoom's length by (`zoom-defaults.ts`) and the
18013
+ * The push-in and the pull-out at the DEFAULT smoothness — what
18014
+ * `@demoman/run-core` sizes a fresh zoom's length by (`zoom-defaults.ts`) and the
17978
18015
  * editor draws an unauthored end with. A render reads the document's own
17979
18016
  * smoothness through `motionTimings`, so these are the timings of a take
17980
18017
  * that never touched the slider, not of every take.
@@ -47284,7 +47321,7 @@ Set the \`cycles\` parameter to \`"ref"\` to resolve cyclical schemas with defs.
47284
47321
  },
47285
47322
  // Bytes or a reason, never an empty array: a 0-byte file stored as a
47286
47323
  // successful output is a Download button that does nothing, and the
47287
- // render loop, the offscreen host and the editor all read `bytes` as
47324
+ // render loop, the runner's render page and the editor all read `bytes` as
47288
47325
  // "it worked".
47289
47326
  async finish() {
47290
47327
  finished = true;
@@ -48149,55 +48186,6 @@ Set the \`cycles\` parameter to \`"ref"\` to resolve cyclical schemas with defs.
48149
48186
  })
48150
48187
  };
48151
48188
  }
48152
- async function renderScreens(args) {
48153
- const { plan, bundle, scene, target, ports } = args;
48154
- const { logo = null, wallpaper = null } = args;
48155
- const sink = ports.images;
48156
- if (!sink)
48157
- throw new Error("renderScreens needs an image sink");
48158
- const { resolved, presentation, violations } = await composeLikeRender({
48159
- plan,
48160
- bundle,
48161
- scene,
48162
- target,
48163
- ports,
48164
- logo,
48165
- wallpaper
48166
- });
48167
- const { startMs } = resolved.range;
48168
- const screens = screensWithWindows(resolved, presentation, target, scene, bundle, startMs);
48169
- const canvas = ports.surface.create(target.width, target.height);
48170
- const ctx = canvas.getContext("2d");
48171
- for (const [i, m] of screens.moments.entries()) {
48172
- const outputTimeMs = startMs + m.ms;
48173
- const image = await ports.frames.at(toSourceMs(resolved.timeline, outputTimeMs));
48174
- await renderFrame({
48175
- resolved,
48176
- target,
48177
- presentation,
48178
- frames: {
48179
- at: async () => image,
48180
- describe: () => ports.frames.describe()
48181
- },
48182
- ctx,
48183
- outputTimeMs
48184
- });
48185
- await sink.add(canvas, `screen-${i}.png`);
48186
- }
48187
- const files = await sink.finish();
48188
- if (files.length !== screens.moments.length) {
48189
- throw new Error(`${screens.moments.length} screens drawn but the image sink returned ${files.length} files`);
48190
- }
48191
- return {
48192
- screens,
48193
- images: screens.moments.map((m, i) => ({
48194
- step: m.step,
48195
- bytes: files[i].bytes
48196
- })),
48197
- detailViolations: violations,
48198
- unavailableSpans: ports.frames.unavailable?.() ?? []
48199
- };
48200
- }
48201
48189
  function stillSourceMs(bundle, marker) {
48202
48190
  const keyframe = bundle.keyframes.find((k) => k.actionId === marker.actionId);
48203
48191
  return keyframe ? keyframe.sourceTimeMs : marker.sourceTimeMs;
@@ -48584,25 +48572,8 @@ Set the \`cycles\` parameter to \`"ref"\` to resolve cyclical schemas with defs.
48584
48572
  return true;
48585
48573
  });
48586
48574
  }
48587
- function screenImageName(step) {
48588
- return step === null ? "final.png" : `step-${step}.png`;
48589
- }
48590
- async function scaledPng(bytes2, width) {
48591
- const bitmap = await createImageBitmap(new Blob([bytes2]));
48592
- try {
48593
- const canvas = new OffscreenCanvas(width, Math.round(bitmap.height * width / bitmap.width));
48594
- canvas.getContext("2d").drawImage(bitmap, 0, 0, canvas.width, canvas.height);
48595
- const blob = await canvas.convertToBlob({ type: "image/png" });
48596
- return new Uint8Array(await blob.arrayBuffer());
48597
- } finally {
48598
- bitmap.close();
48599
- }
48600
- }
48601
48575
  async function renderOutput(input) {
48602
48576
  const { fileType, target, scene, bundle, frames, onFrame } = input;
48603
- if (input.screensOnly !== void 0 && fileType === "stills") {
48604
- throw new Error("screensOnly applies to an mp4 or gif output, not stills");
48605
- }
48606
48577
  const logoAt = async (at2) => {
48607
48578
  if (input.logo === null)
48608
48579
  return { logo: null, logoWarning: null };
@@ -48766,57 +48737,6 @@ Set the \`cycles\` parameter to \`"ref"\` to resolve cyclical schemas with defs.
48766
48737
  }
48767
48738
  };
48768
48739
  }
48769
- if (input.screensOnly !== void 0) {
48770
- const { width } = input.screensOnly;
48771
- const { logo, logoWarning: logoWarning2 } = await logoAt(target);
48772
- const wallpaper = await wallpaperAt(target);
48773
- let result2;
48774
- try {
48775
- result2 = await renderScreens({
48776
- plan,
48777
- bundle,
48778
- scene,
48779
- target,
48780
- ports: { frames, surface, images: createPngSink() },
48781
- logo,
48782
- wallpaper: wallpaper.image
48783
- });
48784
- } finally {
48785
- release(wallpaper.image, wallpaper.held ?? null);
48786
- }
48787
- const deepest = input.wallpaper?.ok !== true ? 1 : composeForTarget({
48788
- plan,
48789
- bundle,
48790
- scene,
48791
- target
48792
- }).resolved.cameraKeys.reduce((m, k) => Math.max(m, k.scale), 1);
48793
- const files = [];
48794
- for (const image of result2.images) {
48795
- files.push({
48796
- name: screenImageName(image.step),
48797
- bytes: await scaledPng(image.bytes, width)
48798
- });
48799
- }
48800
- return {
48801
- files,
48802
- facts: {
48803
- detailViolations: result2.detailViolations,
48804
- unavailableSpans: [...result2.unavailableSpans, ...reclaimed],
48805
- unplacedStills: [],
48806
- loweredZooms: [],
48807
- logoWarning: logoWarning2,
48808
- wallpaperWarning: wallpaperWarning(target, deepest, wallpaper.failed),
48809
- clampedRanges: [],
48810
- // The target's own size: the screens' windows are measured in it.
48811
- rendered: {
48812
- width: target.width,
48813
- height: target.height,
48814
- fps: target.fps
48815
- },
48816
- screens: result2.screens
48817
- }
48818
- };
48819
- }
48820
48740
  const renderAt = async (at2, maxBytes, saysWidth = false, pass) => {
48821
48741
  const { logo, logoWarning: logoWarning2 } = await logoAt(at2);
48822
48742
  const wallpaper = await wallpaperAt(at2);
@@ -49212,7 +49132,6 @@ Set the \`cycles\` parameter to \`"ref"\` to resolve cyclical schemas with defs.
49212
49132
  },
49213
49133
  ...manifest.stills === void 0 ? {} : { stills: manifest.stills },
49214
49134
  ...manifest.outputTimesMs === void 0 ? {} : { outputTimesMs: manifest.outputTimesMs },
49215
- ...manifest.screensOnly === void 0 ? {} : { screensOnly: manifest.screensOnly },
49216
49135
  onFrame: wholePercent((done, total, width, pass) => width === void 0 ? report?.(done, total) : pass === void 0 ? report?.(done, total, width) : report?.(done, total, width, pass))
49217
49136
  // The decoded image is freed once every output is rendered: the GIF
49218
49137
  // ladder and the MP4 cap re-render inside this call.
package/dist/recipe.md CHANGED
@@ -13,8 +13,8 @@ user; section 7 lists every reason.
13
13
  `secretsFile` are the demo accounts below.
14
14
  2. The browser is signed in only where the user ran `npx demoman signin <url>`
15
15
  (`status.sessions` lists them). A demo account records best. A page
16
- that sends this browser to its sign-in page answers `signedOut` (section
17
- 7) with the exact command in `detail`: give the user that command and
16
+ that sends this browser to its sign-in page answers `signedOut` with
17
+ the exact command in `detail`: give the user that command and
18
18
  spend no run until they say they have run it, unless a demo account can
19
19
  sign in (below). Only demo accounts: never ask for the
20
20
  user's own password, or type it. A sign-in or sign-up demo is not
@@ -41,8 +41,7 @@ user; section 7 lists every reason.
41
41
  `sessionsUnreadable`, when present: the saved sessions could not be read; tell the user.
42
42
 
43
43
  `status.sessions` lists an account's saved session with an `account` (and
44
- `origin`) beside `site`; an entry without one is the site's manual session from
45
- `npx demoman signin <url>`.
44
+ `origin`) beside `site`; one without is a manual `npx demoman signin` session.
46
45
 
47
46
  `status.secretsFile` is `null` (no usable accounts file), `{path, absent:
48
47
  true}` (no secrets file: only `DEMOMAN_SECRET_*` can supply values),
@@ -136,7 +135,7 @@ The file, with one account:
136
135
  once more when a call lands on a sign-in page; `signedIn`
137
136
  (`{account, steps, ms}`) says it did. A second failure answers
138
137
  `signInFailed`. A session that lapses mid-run keeps no video; Demoman has
139
- signed in again: just run again.
138
+ signed in again: run again.
140
139
 
141
140
  ## 2. Look at the page
142
141
 
@@ -148,11 +147,11 @@ targets, leaving the page open. Each entry is
148
147
  translate a name from another tool's accessibility tree: Demoman's roles
149
148
  are not Chrome's.
150
149
  - `landedElsewhere: true` - the app redirected, often to its sign-in page;
151
- `landedUrl` says where. If it is a sign-in page, this browser is not
152
- signed in there: see `session` below and spend no run. If it is not a sign-in page (a
150
+ `landedUrl` says where. If it is a sign-in page,
151
+ see `session` below and spend no run. If it is not a sign-in page (a
153
152
  trailing slash, `https`, a locale prefix), use `landedUrl` as the
154
153
  script's `target`; this snapshot stands.
155
- `landedElsewhere: null` means the page's address could not be read: not an
154
+ `landedElsewhere: null`: the address could not be read; not an
156
155
  all-clear.
157
156
  - `session` - `"saved"`: a session is saved for this site; `"none"`: none
158
157
  is (normal for a public page); `"signedOut"`: the page is a sign-in page,
@@ -163,8 +162,8 @@ targets, leaving the page open. Each entry is
163
162
  `"none"` or `"unchecked"` means the same. Tell the user to run
164
163
  `npx demoman signin <the page to record>`; spend no run. Otherwise on
165
164
  `"unchecked"`, carry on only if `landedUrl` is not a sign-in page.
166
- - `settled: false` - the page was still loading; `settleNote` says what was
167
- outstanding. Snapshot again before concluding something is absent.
165
+ - `settled: false` - the page was still loading; `settleNote` says what
166
+ was left. Snapshot again before concluding something is absent.
168
167
  - `rect` is in page coordinates; `inFirstViewport`: in view before any
169
168
  scroll. `rect: null`: no box yet (a closed FAQ answer), still a valid
170
169
  `waitFor … until: "visible"` target after the step that opens it.
@@ -179,15 +178,14 @@ targets, leaving the page open. Each entry is
179
178
  (name, text, stableId, kind, value) to narrow. `containsNote`: no match.
180
179
  - A snapshot sees only the page as it loads: hidden content in the
181
180
  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"
181
+ cut off after the step that opens it, and copy targets from that answer. A probe acts on the app for real: an "Add item"
183
182
  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
183
  run's stop with that reason says, and probe again.
185
184
 
186
185
  ### Recording a phone demo
187
186
 
188
187
  1. Call `snapshot` with `device` (`"phone"` or `"tablet"`), and
189
- copy targets from that answer only: a phone shows a different page, and a
190
- desktop target is often not on it.
188
+ copy targets from that answer only, never a desktop one.
191
189
  2. `run` a script that names the same `device`.
192
190
  3. Leave `look.canvas` at `auto`, which comes out portrait, or name `9:16`.
193
191
  4. No `hover` steps: tap instead.
@@ -251,7 +249,8 @@ A flow in the repo (.demoman/flows) is rewritten by each run: commit that file w
251
249
  `possibleDuplicate` lists `matches`: use one's `id`, or repeat with
252
250
  `confirmedNew: true` for a different flow. `nameTaken` names the
253
251
  `holder`: use its `id` or another name. The report's `flow`
254
- says what was made.
252
+ says what was made; `flow.otherRepo`: joined another
253
+ repo's flow; tell the user.
255
254
  1. `run(script, flow)`. It answers the run's report, or
256
255
  `{ "outcome": "stillRunning", "id": … }` after about 50 s; then call
257
256
  `report(id)` until the outcome is neither `running` nor `stillRunning`.
@@ -278,10 +277,10 @@ A flow in the repo (.demoman/flows) is rewritten by each run: commit that file w
278
277
  sign-in page. `notStored` with `what: "session"` means the saved
279
278
  session could not be refreshed: name it to the user.
280
279
  - `threw` - a fault in the run; report its `error`.
281
- - Then read `frames.degradations` and `frames.storageRefused`. These are
282
- about the video, not the script (`surfaceMismatch`: the browser handed
283
- back frames of the wrong size; `dragPictureMissing`: a native drag's item
284
- jumps). `notDragged`: a drag changed nothing; `verdict.diverged` lists
280
+ - Then read `frames.degradations` and `frames.storageRefused`, about the
281
+ video (`surfaceMismatch`: wrong-size frames; `dragPictureMissing`: a
282
+ drag's item jumps) or refresh screens (`step*`, `requestNotWaited`), not
283
+ the script. `notDragged`: a drag did nothing; `verdict.diverged` lists
285
284
  it. Name them to the user; spend no run. `clickUnconfirmed` is about a step: a click
286
285
  could not be confirmed to have reached its target, and
287
286
  `frames.unconfirmedClicks` names each such step and says why; check in
@@ -488,12 +487,12 @@ Studio exports go to `~/Downloads`.
488
487
  | `sessionNotLoaded` | `snapshot`, `run`¹ | The browser refused the saved sessions; `detail` says why. Tell the user to run `npx demoman signin` again there. |
489
488
  | `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
489
  | `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`. |
490
+ | `secretTooShort` | `snapshot`, `run`¹, `ci` | Secret `NAME` is under 8 characters. Write a longer one; `ci`: give the person `command`. |
492
491
  | `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
492
  | `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
493
  | `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
494
  | `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. |
495
+ | `accountsInvalid` | `snapshot`, `run`¹ | `.demoman/accounts.json` is malformed or breaks a rule; `detail` names it. Fix the file. |
497
496
  | `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
497
  | `invalidProject` | `snapshot`, `run`¹, `attach` | `project` is not an absolute path to a folder. Pass one, or leave it out. |
499
498
  | `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. |
@@ -509,14 +508,14 @@ Studio exports go to `~/Downloads`.
509
508
  | `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
509
  | `libraryUnreadable` | `flows`, `studio` | Unreadable; report it. |
511
510
  | `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`. |
512
- | `unknownRun` | `report` | This demoman-mcp never issued that id (ids do not survive a server restart). |
511
+ | `unknownRun` | `report` | This demoman-mcp never issued that id, or let it go (it keeps the last 50 finished; ids do not survive a restart). |
513
512
  | `noReport` | `report` | No report for that id: this server keeps only its latest; `detail` says which. Do not run again. |
514
513
  | `notAnObject` | `run` | The script is not a JSON object. |
515
514
  | `invalidScript` | `run` | The schema refused the script; `field` names where. |
516
515
  | `unfilledHoles` | `run` | A derived draft still has holes (section 3); also a re-film of a video that did not keep a value. |
517
516
  | `flowRequired` | `run`¹ | No `flow` was given. Find one (section 4), or pass `{ new }`. |
518
517
  | `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). |
518
+ | `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 and the fix). |
520
519
  | `flowNotFound` | `run`¹ | No flow has that `id`; call `flows`. |
521
520
  | `wrongIdKind` | any | Wrong kind of id; see `detail`. |
522
521
  | `flowUnreadable`, `flowUnwritable` | `run`¹, `flows` | The flow records could not be read or written; quote `detail`. Nothing recorded. |
@@ -536,7 +535,7 @@ Studio exports go to `~/Downloads`.
536
535
  | `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
536
  | `noVideoId`, `noFrames` | `export`¹ | No video id; no frames to render. |
538
537
  | `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. |
538
+ | `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. A `detail` naming a closed shadow root: its targets can't be reached; pick one outside. |
540
539
  | `ambiguousAnchor` | `run`² | Several elements matched; name the target more exactly. |
541
540
  | `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
541
  | `pageWentElsewhere`, `unperformableStep` | `run`² | The app left the page unasked (sign-in expired, or a missing `waitForLoad`); or the step asks the impossible. |
@@ -549,7 +548,7 @@ Studio exports go to `~/Downloads`.
549
548
  | `pageFaulted`, `snapshotThrew`, `probeThrew` | `snapshot`, `probe` | The page threw, or a fault; quote `detail`. |
550
549
  | `portFailure` | `probe` | The browser gave way, not the script. Probe once more; quote `detail` if it repeats. |
551
550
  | `notInRepo`, `outsideRepo`, `outputTaken`, `logoUnreadable`, `handSignIn`, `cannotRefilm`, `keepRefused`, `exportFailed`, `repoFlowUnwritable` | `add`, `ci` | `detail`: what was written, the fix. |
552
- | `appInvalid`, `appOriginMismatch`, `appUnknown`, `appHoles`, `appInstallFailed`, `appStartExited`, `appNeverAnswered`, `appServiceFailed`, `appPortTaken`, `appDockerMissing`, `appNowInFuture`, `appNowTooOld`, `appNowNotPinned`, `checkoutFailed`, `noRepoFlow`, `refreshFailed`, `checkThrew`, `alreadySetUp`, `setupPrOpen`, `setupBranchExists`, `noRepoFlows`, `noRelease`, `noDeployment`, `routeRefused`, `githubUnreadable`, `noSetupBranch`, `secretsUnknown`, `secretsUnreadable`, `workflowRefused`, `filesUnreadable`, `setupUnreadable`, `secretRefused`, `actionsRefused`, `actionsUnknown`, `prFailed` | `ci` | `detail`: what was done, the fix. |
551
+ | `checkNeedsPerson`, `appInvalid`, `appOriginMismatch`, `appUnknown`, `appHoles`, `appInstallFailed`, `appStartExited`, `appNeverAnswered`, `appServiceFailed`, `appPortTaken`, `appDockerMissing`, `appNowInFuture`, `appNowTooOld`, `appNowNotPinned`, `checkoutFailed`, `noRepoFlow`, `refreshFailed`, `checkThrew`, `alreadySetUp`, `setupPrOpen`, `setupBranchExists`, `noRepoFlows`, `noRelease`, `noDeployment`, `routeRefused`, `githubUnreadable`, `noSetupBranch`, `secretsUnknown`, `secretsUnreadable`, `workflowRefused`, `filesUnreadable`, `setupUnreadable`, `secretRefused`, `actionsRefused`, `actionsUnknown`, `prFailed` | `ci` | `detail`: what was done, the fix. |
553
552
 
554
553
  ## 8. Repo flows and CI
555
554