demoman 0.2.0-rc.8 → 0.7.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.
@@ -15415,7 +15415,31 @@ Set the \`cycles\` parameter to \`"ref"\` to resolve cyclical schemas with defs.
15415
15415
  });
15416
15416
  var MarkerSchema = external_exports.object({
15417
15417
  actionId: external_exports.string().min(1),
15418
- sourceTimeMs: external_exports.number().nonnegative()
15418
+ sourceTimeMs: external_exports.number().nonnegative(),
15419
+ /**
15420
+ * When the step's act was over: the verb had returned and the page had
15421
+ * stopped reacting to it (the last paint of real motion, capped). The
15422
+ * camera starts no move toward a later zoom before it, plus
15423
+ * `CAMERA_DEFAULTS.actSettleMs`. Absent on every take filmed before
15424
+ * 2026-10-19, on captures, and on steps that do not act: "unknown",
15425
+ * which every reader treats as today's behaviour.
15426
+ */
15427
+ actEndSourceTimeMs: external_exports.number().nonnegative().optional(),
15428
+ /** Time the replay waited before this step so the camera had room to
15429
+ * move unhurried (spec 2026-10-19). Absent when it waited nothing. */
15430
+ roomMs: external_exports.number().nonnegative().optional(),
15431
+ /** The longest single hold within `roomMs` (a settle or the camera's
15432
+ * room, not a wait for the page to go quiet): what the film check may
15433
+ * take for Demoman's pacing inside one still stretch. */
15434
+ roomHeldMs: external_exports.number().nonnegative().optional()
15435
+ }).superRefine((marker, ctx) => {
15436
+ if (marker.actEndSourceTimeMs !== void 0 && marker.actEndSourceTimeMs < marker.sourceTimeMs) {
15437
+ ctx.addIssue({
15438
+ code: external_exports.ZodIssueCode.custom,
15439
+ path: ["actEndSourceTimeMs"],
15440
+ message: `act end ${marker.actEndSourceTimeMs}ms is before the step's marker at ${marker.sourceTimeMs}ms`
15441
+ });
15442
+ }
15419
15443
  });
15420
15444
  var MadeFromStepSchema = external_exports.object({
15421
15445
  actionId: external_exports.string().min(1),
@@ -16614,6 +16638,13 @@ Set the \`cycles\` parameter to \`"ref"\` to resolve cyclical schemas with defs.
16614
16638
  fitMarginPx: 24,
16615
16639
  /** Enter before the marker so the beat has landed by the time the action fires. */
16616
16640
  leadInMs: -350,
16641
+ /**
16642
+ * The settle after an act: how long the result of a step is shown before
16643
+ * the camera may set off toward a later zoom (spec 2026-10-19, "unhurried
16644
+ * beats"). Not `neutral.minPlateauMs`, which also sets pull-outs, the hold
16645
+ * before a push-in and the auto-zoom gap, and which old takes render by.
16646
+ */
16647
+ actSettleMs: 400,
16617
16648
  /**
16618
16649
  * The push-in and the pull-out at the DEFAULT smoothness — what the
16619
16650
  * extension sizes a fresh zoom's length by (`zoom-defaults.ts`) and the
@@ -15517,7 +15517,31 @@ Set the \`cycles\` parameter to \`"ref"\` to resolve cyclical schemas with defs.
15517
15517
  });
15518
15518
  var MarkerSchema = external_exports.object({
15519
15519
  actionId: external_exports.string().min(1),
15520
- sourceTimeMs: external_exports.number().nonnegative()
15520
+ sourceTimeMs: external_exports.number().nonnegative(),
15521
+ /**
15522
+ * When the step's act was over: the verb had returned and the page had
15523
+ * stopped reacting to it (the last paint of real motion, capped). The
15524
+ * camera starts no move toward a later zoom before it, plus
15525
+ * `CAMERA_DEFAULTS.actSettleMs`. Absent on every take filmed before
15526
+ * 2026-10-19, on captures, and on steps that do not act: "unknown",
15527
+ * which every reader treats as today's behaviour.
15528
+ */
15529
+ actEndSourceTimeMs: external_exports.number().nonnegative().optional(),
15530
+ /** Time the replay waited before this step so the camera had room to
15531
+ * move unhurried (spec 2026-10-19). Absent when it waited nothing. */
15532
+ roomMs: external_exports.number().nonnegative().optional(),
15533
+ /** The longest single hold within `roomMs` (a settle or the camera's
15534
+ * room, not a wait for the page to go quiet): what the film check may
15535
+ * take for Demoman's pacing inside one still stretch. */
15536
+ roomHeldMs: external_exports.number().nonnegative().optional()
15537
+ }).superRefine((marker, ctx) => {
15538
+ if (marker.actEndSourceTimeMs !== void 0 && marker.actEndSourceTimeMs < marker.sourceTimeMs) {
15539
+ ctx.addIssue({
15540
+ code: external_exports.ZodIssueCode.custom,
15541
+ path: ["actEndSourceTimeMs"],
15542
+ message: `act end ${marker.actEndSourceTimeMs}ms is before the step's marker at ${marker.sourceTimeMs}ms`
15543
+ });
15544
+ }
15521
15545
  });
15522
15546
  var MadeFromStepSchema = external_exports.object({
15523
15547
  actionId: external_exports.string().min(1),
@@ -17271,6 +17295,13 @@ Set the \`cycles\` parameter to \`"ref"\` to resolve cyclical schemas with defs.
17271
17295
  fitMarginPx: 24,
17272
17296
  /** Enter before the marker so the beat has landed by the time the action fires. */
17273
17297
  leadInMs: -350,
17298
+ /**
17299
+ * The settle after an act: how long the result of a step is shown before
17300
+ * the camera may set off toward a later zoom (spec 2026-10-19, "unhurried
17301
+ * beats"). Not `neutral.minPlateauMs`, which also sets pull-outs, the hold
17302
+ * before a push-in and the auto-zoom gap, and which old takes render by.
17303
+ */
17304
+ actSettleMs: 400,
17274
17305
  /**
17275
17306
  * The push-in and the pull-out at the DEFAULT smoothness — what the
17276
17307
  * extension sizes a fresh zoom's length by (`zoom-defaults.ts`) and the
@@ -17336,7 +17367,7 @@ Set the \`cycles\` parameter to \`"ref"\` to resolve cyclical schemas with defs.
17336
17367
  return byAction !== 0 ? byAction : a.offsetMs - b.offsetMs;
17337
17368
  });
17338
17369
  }
17339
- function solveCamera(intents, rectOf, timeline, markerSourceMs, viewport, fitWindow = null, motion = MOTION_DEFAULTS) {
17370
+ function solveCamera(intents, rectOf, timeline, markerSourceMs, viewport, fitWindow = null, motion = MOTION_DEFAULTS, actEnds = /* @__PURE__ */ new Map()) {
17340
17371
  const timings = motionTimings(motion.smoothness);
17341
17372
  const neutral = { x: viewport.width / 2, y: viewport.height / 2 };
17342
17373
  const seeds = [];
@@ -17353,12 +17384,20 @@ Set the \`cycles\` parameter to \`"ref"\` to resolve cyclical schemas with defs.
17353
17384
  const asked = clamp(intent.scale, 1, CAMERA_DEFAULTS.maxScale);
17354
17385
  const requested = Math.max(asked, clamp(intent.requestedScale ?? intent.scale, 1, CAMERA_DEFAULTS.maxScale));
17355
17386
  const scale = fitWindow === null ? asked : clamp(fitScaleFor(rect2, fitWindow), 1, asked);
17387
+ let notBeforeMs = Number.NEGATIVE_INFINITY;
17388
+ for (const [actionId, endMs] of actEnds) {
17389
+ const at = markerSourceMs.get(actionId);
17390
+ if (at === void 0 || at >= sourceMs)
17391
+ continue;
17392
+ notBeforeMs = Math.max(notBeforeMs, toOutputMs(timeline, endMs) + CAMERA_DEFAULTS.actSettleMs);
17393
+ }
17394
+ const transitionMs = outputMs - timings.zoomInMs < notBeforeMs ? Math.max(MIN_PAN_MS, Math.min(timings.zoomInMs, outputMs - notBeforeMs)) : timings.zoomInMs;
17356
17395
  seeds.push({
17357
17396
  id: intent.id,
17358
17397
  outputTimeMs: outputMs,
17359
17398
  center: rectCenter(rect2),
17360
17399
  scale,
17361
- transitionMs: timings.zoomInMs,
17400
+ transitionMs,
17362
17401
  stiffness: timings.stiffness,
17363
17402
  zoom: true,
17364
17403
  authoredEndMs: resolvedEndMs,
@@ -17368,7 +17407,8 @@ Set the \`cycles\` parameter to \`"ref"\` to resolve cyclical schemas with defs.
17368
17407
  to: scale,
17369
17408
  cap: asked < requested ? asked : null
17370
17409
  } : null,
17371
- actionMs
17410
+ actionMs,
17411
+ plannedTransitionMs: timings.zoomInMs
17372
17412
  });
17373
17413
  }
17374
17414
  return insertNeutralKeys([
@@ -17385,7 +17425,8 @@ Set the \`cycles\` parameter to \`"ref"\` to resolve cyclical schemas with defs.
17385
17425
  authoredEndMs: null,
17386
17426
  endUnplaced: false,
17387
17427
  fitted: null,
17388
- actionMs: 0
17428
+ actionMs: 0,
17429
+ plannedTransitionMs: 0
17389
17430
  },
17390
17431
  ...seeds
17391
17432
  ].sort((a, b) => a.outputTimeMs - b.outputTimeMs), timeline.outputDurationMs, timings);
@@ -17452,7 +17493,7 @@ Set the \`cycles\` parameter to \`"ref"\` to resolve cyclical schemas with defs.
17452
17493
  });
17453
17494
  continue;
17454
17495
  }
17455
- const latestMs = next.outputTimeMs - next.transitionMs - neutral.minPlateauMs;
17496
+ const latestMs = next.outputTimeMs - next.plannedTransitionMs - neutral.minPlateauMs;
17456
17497
  if (latestMs < earliestMs) {
17457
17498
  const settledMs = Math.max(seed.outputTimeMs, seed.actionMs) + neutral.minPlateauMs;
17458
17499
  seeds[i + 1] = {
@@ -19013,7 +19054,9 @@ Set the \`cycles\` parameter to \`"ref"\` to resolve cyclical schemas with defs.
19013
19054
  });
19014
19055
  const clampedRanges = trim.clamped ? [trim.clamped] : [];
19015
19056
  const motion = scene?.motion ?? MOTION_DEFAULTS;
19016
- const camera = solveCamera(plan.cameraIntents, rectOf, timeline, markerSourceMs, plan.viewport, cameraFitWindow, motion);
19057
+ const cutIds = new Set(plan.cuts.flatMap((run) => run.actionIds));
19058
+ const actEnds = new Map(bundle.markers.flatMap((m) => m.actEndSourceTimeMs === void 0 || cutIds.has(m.actionId) ? [] : [[m.actionId, m.actEndSourceTimeMs]]));
19059
+ const camera = solveCamera(plan.cameraIntents, rectOf, timeline, markerSourceMs, plan.viewport, cameraFitWindow, motion, actEnds);
19017
19060
  const intentAction = new Map(plan.cameraIntents.map((intent) => [intent.id, intent.actionId]));
19018
19061
  const loweredZooms = [];
19019
19062
  for (const segment of camera.segments) {
package/dist/recipe.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # Recording a demo with Demoman
2
2
 
3
- You write a DemoScript. Demoman runs it in a browser window of its own on
3
+ You write a DemoScript. Demoman runs it in a browser of its own on
4
4
  this machine and saves the take on disk; `export` renders that take 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 to tell
@@ -12,9 +12,9 @@ the user; section 7 lists every reason.
12
12
  `browserInstalled`, `browserRunning`, `runnerVersion`, `runPage` (the
13
13
  latest run's report or its progress, or null), `sessions`, `accounts`,
14
14
  `secretsFile` and `update`.
15
- `sessions` is `[{site, savedAt, refreshedAt, signInUrl}]`, or
16
- `{unreadable}` when they could not be read: tell the user why. `accounts` and `secretsFile` are the demo
17
- accounts below. The browser window opens on the first `snapshot`, `run`
15
+ `sessions` is `[{site, savedAt, refreshedAt, signInUrl}]`; it and
16
+ `display` (the screen headless films 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
18
  or `export`. Demoman updates itself: say nothing about `update`. When `browserInstalled` is false, the first
19
19
  `snapshot` or `run` answers `browserMissing`.
20
20
  2. The browser is signed in wherever the user ran `npx demoman signin <url>`,
@@ -164,8 +164,8 @@ The file, with one account:
164
164
 
165
165
  ## 2. Look at the page
166
166
 
167
- `snapshot(url)` opens `url` in Demoman's window, lists the page's targets,
168
- and leaves the window open. Each entry is
167
+ `snapshot(url)` opens `url` in Demoman's browser, lists the page's targets,
168
+ and leaves the page open. Each entry is
169
169
  `{ target, kind, text, rect, inFirstViewport }`. Every `target` listed is one
170
170
  a run resolves to exactly that element: Demoman checked it.
171
171
 
@@ -200,9 +200,9 @@ a run resolves to exactly that element: Demoman checked it.
200
200
  FAQ answer): still a valid target for `waitFor … until: "visible"` after
201
201
  the step that opens it.
202
202
  - `size` is `{ width, height, from, error }`: the size the page was laid out
203
- at, which a run films too. `from` is `screen` (the screen the window is
204
- on), or `device`. `from: "window"` with an `error`: Demoman could not read the
205
- screen and listed the window's smaller layout; tell the user the `error`.
203
+ at, which a run films too. `from` is `screen` (this machine's screen),
204
+ or `device`. `from: "window"` with an `error`: Demoman could not read the
205
+ screen and listed the browser's smaller layout; tell the user the `error`.
206
206
  - `unresolvable` counts elements left out because no target names them
207
207
  uniquely (two buttons with one label, say). `notExamined` above 0 means the
208
208
  page had more than one answer holds: pass `contains` ("pay", "FAQ") to ask
@@ -353,12 +353,14 @@ Refused with `nothingToRefilm` when no step that acts is left.
353
353
  | Finding | Whose | The move |
354
354
  | --- | --- | --- |
355
355
  | `cutOff`, `outOfFrame` | the script | add a `scrollTo` on that element before the step |
356
- | `atEdge` | the script, if a run remains | as above; otherwise name it |
357
- | `longStill` beyond what a `pause` asked for | Demoman | name it; do not rewrite steps |
358
- | stray arrival, `detour` | Demoman | name it as a bug |
356
+ | `atEdge` | the script, if a run remains | as above; otherwise leave it |
357
+ | `longStill` beyond what a `pause` asked for | Demoman | leave it; do not rewrite steps |
358
+ | stray arrival, `detour` | Demoman | leave it |
359
359
  | drift from the earlier take | the app | report it |
360
360
 
361
- A finding that is Demoman's earns no run.
361
+ A finding that is Demoman's earns no run, and is not passed on: the
362
+ user takes the video as it is or changes it in the studio. A step's
363
+ `roomMs` is Demoman's own pacing, not a stall.
362
364
  4. Tighten a step whose `candidates` is above 1 or whose `strategy` is weaker
363
365
  than the target you named.
364
366
 
@@ -401,29 +403,20 @@ too.
401
403
  is `stills` and the answer carries `folder: { path, files }` instead of
402
404
  `file`: give the user `folder.path`; `warnings.unplacedStills` lists steps
403
405
  that got no still. `summary` is one
404
- sentence: what was saved and every warning. Give it to the user as is;
405
- `warnings` holds the detail.
406
- `warnings.zooms` lists each click whose zoom the video skipped (target
407
- too wide) or lowered (`by: "fit"`, narrowed to fit a 9:16
408
- crop; `by: "cap"`, held to 9:16's 1.15x), with the scale asked for and
409
- the one it got. None of these is the script's to fix.
410
- `warnings.retexts` lists each typed step the video cannot vouch for:
411
- `{ actionId, kind, reason }`. `kind` `notDrawn`: the step's text was
412
- edited in the take and the video shows the old text; `unchecked`: the
413
- frames kept no record of what was typed. `reason` says why and what
414
- films it again.
415
- Neither is the script's to fix: give the user the summary; re-film
416
- (`run({ takeId })`) only on request.
406
+ sentence: what was saved and anything the user asked for that the file
407
+ lacks (a logo, motion, a still, an edit). `warnings` holds more:
408
+ Demoman's own calls (`zooms`, `detailViolations`, a size cap's `steps`,
409
+ a GIF's widths, `retexts` marked `unchecked`, `targetCheck`). They are
410
+ not the user's to act on: do not pass them on. None is the script's to
411
+ fix either.
417
412
  `warnings.editedSinceFilmed` lists steps whose `scene.json` no longer
418
- matches the frames: each entry is `{ actionId, what, was?,
419
- now? }` with `what` one of `text`, `target`, `added`, `removed`, `kind`.
420
- The summary says so and names `run({ takeId })` (`derive` then `run` when
421
- a verb changed: `kind`) and, with `warnings.masks`, that a re-film leaves
422
- the masks behind. Give the user the summary; re-film only on request.
423
- `warnings.targetCheck` is `checked` or `noSkeleton` when nothing is wrong;
424
- `{ unreadable }`: edited targets could not be compared; tell the user.
425
- `warnings.notListed` (`{ error }`): the file is saved but will not show
426
- in the studio's list of exports.
413
+ matches the frames; the summary says so and names the re-film
414
+ (`run({ takeId })`, or `derive` then `run` when a step's verb changed).
415
+ Re-film only on request.
416
+ `links` holds the export's one-click actions for the user, each present
417
+ only where it works: `studio`, `reveal` (Finder) and `copy` (the file to
418
+ the clipboard; none for stills). `linksError`, set instead, says why
419
+ there are none: tell the user in one line.
427
420
  Every export report carries a `summary`, whatever its outcome
428
421
  (`stillRunning`, this server's own answer, does not).
429
422
  3. `renderFailed` - export **once** more; never re-run the script for an
@@ -457,16 +450,19 @@ plan. On `uploadRefused`, do as its `detail` says: one more `attach` with
457
450
  `unconfirmed`, do not post again; tell the user to look at the PR. For the other reasons, follow section 7. An
458
451
  export that did not save comes back as the export's answer.
459
452
 
460
- Hand back: the absolute `file.path` (`folder.path` for stills); the take id; the verdict; the export's
461
- `summary`; every film finding left standing; `look.brandKitError` when set;
462
- `size.error` when set; anything you could not fix; and, for any outcome other than `saved`, that
463
- outcome with its `error` or `detail`, quoted.
453
+ Hand back, on `saved`, two lines and nothing else: the `summary` as it is,
454
+ then the `links` as markdown links on one line, in this order and only
455
+ those present: `[Open in studio](links.studio) · [Reveal in Finder](links.reveal) · [Copy video](links.copy)`
456
+ (`Copy GIF` for a GIF). Add one line only for `look.brandKitError`,
457
+ `size.error`, `linksError`, or something you could not fix. For any other
458
+ outcome, say it with its `error` or `detail`, quoted.
464
459
 
465
- When the `studio` tool is listed, **offer** it after a run or an export;
466
- never open it unasked. `studio({ takeId })` opens a window where the person
467
- edits and exports the take. `{ outcome: "opened", url, takeId?, note? }`:
468
- say the window is open and quote `note` if set; `url` is single-use, never
469
- offer it. Studio exports go to `~/Downloads`.
460
+ When the `studio` tool is listed and there is no `links.studio` (after a
461
+ run with no export), **offer** it; never open it unasked. `studio({ takeId })`
462
+ opens a window where the person edits and exports the take.
463
+ `{ outcome: "opened", url, takeId?, note? }`: say the window is open and
464
+ quote `note` if set; `url` is single-use, never offer it. Studio exports go
465
+ to `~/Downloads`.
470
466
 
471
467
  ## 6. The format
472
468
 
@@ -588,7 +584,7 @@ recorded action each step came from (`recorded`, in `recordedFrom`):
588
584
  | `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). |
589
585
  | `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. |
590
586
  | `signedOut` | `run` (`stopped.reason`) | The app sent this browser to its sign-in page: the saved session expired or does not sign this page in, or none was ever saved. Nothing was filmed and no take 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. |
591
- | `windowClosed` | `run` (`stopped.reason`) | 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. |
587
+ | `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. |
592
588
  | `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. |
593
589
  | `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. |
594
590
  | `pageFaulted` | `snapshot` | The page's own code threw while Demoman walked it; quote `detail`. |
@@ -17,4 +17,5 @@ this machine, then render the take to an MP4.
17
17
  or create one on a local development database, else give the user the
18
18
  command from its detail. Only demo accounts; never ask for the user's own
19
19
  password.
20
- 3. When `export` answers `saved`, give the user `summary` and `file.path`.
20
+ 3. When `export` answers `saved`, end on two lines: `summary` as it is, then
21
+ its `links` as markdown links on one line, as the recipe's hand-back says.