demoman 0.9.2 → 0.9.4

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.
@@ -1638,7 +1638,40 @@
1638
1638
 
1639
1639
  // ../../packages/run-core/dist/url.js
1640
1640
  var PLACEHOLDER = "redacted";
1641
+ var UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
1642
+ function charClass(c) {
1643
+ if (c >= "a" && c <= "z")
1644
+ return "l";
1645
+ if (c >= "A" && c <= "Z")
1646
+ return "u";
1647
+ if (c >= "0" && c <= "9")
1648
+ return "d";
1649
+ return null;
1650
+ }
1651
+ function looksLikeToken(raw) {
1652
+ let segment;
1653
+ try {
1654
+ segment = decodeURIComponent(raw);
1655
+ } catch {
1656
+ segment = raw;
1657
+ }
1658
+ if (!/^[\w.~+=-]{20,}$/.test(segment) || UUID.test(segment))
1659
+ return false;
1660
+ const classes = [...segment].map(charClass).filter((c) => c !== null);
1661
+ let switches = 0;
1662
+ for (let i = 1; i < classes.length; i++) {
1663
+ if (classes[i] !== classes[i - 1])
1664
+ switches++;
1665
+ }
1666
+ return switches * (/[A-Z]/.test(segment) ? 3 : 4) >= segment.length;
1667
+ }
1641
1668
  function scrubUrl(raw) {
1669
+ return scrub(raw, true);
1670
+ }
1671
+ function pageKey(raw) {
1672
+ return scrub(raw, false);
1673
+ }
1674
+ function scrub(raw, path) {
1642
1675
  let url;
1643
1676
  try {
1644
1677
  url = new URL(raw);
@@ -1648,7 +1681,9 @@
1648
1681
  url.username = "";
1649
1682
  url.password = "";
1650
1683
  url.hash = "";
1651
- url.pathname = url.pathname.split("/").map((segment) => scrubSecrets(segment) === segment ? segment : PLACEHOLDER).join("/");
1684
+ if (path) {
1685
+ url.pathname = url.pathname.split("/").map((segment) => looksLikeToken(segment) || scrubSecrets(segment) !== segment ? PLACEHOLDER : segment).join("/");
1686
+ }
1652
1687
  for (const key of Array.from(new Set(url.searchParams.keys()))) {
1653
1688
  url.searchParams.set(key, PLACEHOLDER);
1654
1689
  }
@@ -1666,9 +1701,10 @@
1666
1701
  failureReason: report.failureReason
1667
1702
  };
1668
1703
  if (resolved && report.element !== null) {
1704
+ const href = window.location.href;
1669
1705
  const { anchor } = await captureAnchor(report.element, {
1670
1706
  anchorId: intent.id,
1671
- url: scrubUrl(window.location.href),
1707
+ url: scrubUrl(href),
1672
1708
  // No step index exists yet for a freshly authored anchor;
1673
1709
  // driftPick's own remap capture makes the same choice.
1674
1710
  actionIndex: 0,
@@ -1692,6 +1728,7 @@
1692
1728
  failureReason: null,
1693
1729
  intentResolution,
1694
1730
  pageUrl: null,
1731
+ here: pageKey(href),
1695
1732
  document: documentOf(),
1696
1733
  ...credentialField === void 0 ? {} : { credentialField }
1697
1734
  };
@@ -1711,6 +1748,7 @@
1711
1748
  // frame knows which document just failed to resolve the intent. Scrubbed
1712
1749
  // like every other URL that leaves the page.
1713
1750
  pageUrl: scrubUrl(window.location.href),
1751
+ here: pageKey(window.location.href),
1714
1752
  document: documentOf(),
1715
1753
  // No element to ask: when the caller checks credentials, that is "could
1716
1754
  // not tell", which a typed step hides (launch C spec 3.5).
@@ -1842,8 +1880,10 @@
1842
1880
  fields.push({ target, value });
1843
1881
  }
1844
1882
  const notListed = candidates.length - END_PAGE_MAX_FIELDS;
1883
+ const href = doc.location?.href;
1845
1884
  return {
1846
- url: doc.location?.href ?? "",
1885
+ // Written to `report.json`: scrubbed like every address that is.
1886
+ url: href === void 0 ? "" : scrubUrl(href),
1847
1887
  text,
1848
1888
  fields,
1849
1889
  ...notListed > 0 ? { fieldsNotListed: notListed } : {}
@@ -16208,14 +16208,14 @@ Set the \`cycles\` parameter to \`"ref"\` to resolve cyclical schemas with defs.
16208
16208
  * unchanged, but its MEANING narrows: this now records which frames PLAY,
16209
16209
  * not which the author chose. The editor writes it nowhere — since
16210
16210
  * 2026-09-28 every write the editor makes carries the store's current
16211
- * value (`persist()` in `apps/extension/src/editor/session.ts`). Two
16212
- * writers flip it, both outside the editor: the run page's re-shoot
16213
- * promotion (`promote` in `apps/extension/src/adapters/reshoot.ts`) sets
16214
- * `demo` when a re-shoot finishes complete, and the library card's "Back
16215
- * to your recording" (`backToRecording` in
16216
- * `apps/extension/entrypoints/library/main.ts`) sets `screen`. Neither
16217
- * deletes anything to do it — the recording stays on disk under either
16218
- * mode (`chooseActiveBundle`'s own docblock) — so a re-shoot that turns
16211
+ * value (`persist()` in `apps/studio/pages/src/editor/session.ts`). Two
16212
+ * writers set it, both outside the editor: `assembleAuthored`
16213
+ * (`@demoman/replay-engine`) writes `screen` on every new take, and the
16214
+ * library card's "Back to your recording"
16215
+ * (`apps/studio/pages/entrypoints/library/main.ts`) sets `screen`. Nothing writes `demo` today; it is
16216
+ * read from takes the retired extension re-shot. Neither writer deletes
16217
+ * anything — the recording stays on disk under either mode
16218
+ * (`chooseActiveBundle`'s own docblock) — so a re-shoot that turns
16219
16219
  * out worse than the recording is always reversible by writing this field
16220
16220
  * back.
16221
16221
  */
@@ -16581,7 +16581,7 @@ Set the \`cycles\` parameter to \`"ref"\` to resolve cyclical schemas with defs.
16581
16581
  external_exports.object({ text: external_exports.string().min(1) }).strict(),
16582
16582
  external_exports.object({ treePath: external_exports.string().min(1) }).strict()
16583
16583
  ]);
16584
- var RecordedSchema = external_exports.string().min(1).optional();
16584
+ var RecordedSchema = external_exports.string().min(1).optional().describe("Written by Demoman when the script was derived from a video; pairs the step with the action it came from. Leave it as it is");
16585
16585
  var DragSpotSchema = external_exports.object({ x: external_exports.number().min(0).max(1), y: external_exports.number().min(0).max(1) }).strict();
16586
16586
  var DragFromSchema = external_exports.object({ on: ScriptTargetSchema, at: DragSpotSchema.optional() }).strict();
16587
16587
  var DragToSchema = external_exports.union([
@@ -16603,10 +16603,10 @@ Set the \`cycles\` parameter to \`"ref"\` to resolve cyclical schemas with defs.
16603
16603
  var ScriptStepSchema = external_exports.discriminatedUnion("do", [
16604
16604
  external_exports.object({
16605
16605
  do: external_exports.literal("click"),
16606
- on: ScriptTargetSchema,
16606
+ on: ScriptTargetSchema.describe("The element to click"),
16607
16607
  /** Where in the target's box to click (its centre if absent). */
16608
- at: DragSpotSchema.optional(),
16609
- zoom: ZoomIntentSchema.optional(),
16608
+ at: DragSpotSchema.optional().describe("Where in the element to click, as fractions of its width and height; its centre if absent"),
16609
+ zoom: ZoomIntentSchema.optional().describe("The camera's zoom at this click: `false` for none, or `{ scale }` over 1 and at most 2.5. Absent leaves it to the camera"),
16610
16610
  /**
16611
16611
  * The recorded action this step was derived from (`scriptFromTake` writes
16612
16612
  * it). How the recording layer pairs a run's step with the author's —
@@ -16614,21 +16614,21 @@ Set the \`cycles\` parameter to \`"ref"\` to resolve cyclical schemas with defs.
16614
16614
  * list would go stale the moment it did. Absent on a step the agent wrote.
16615
16615
  */
16616
16616
  recorded: RecordedSchema
16617
- }).strict(),
16617
+ }).strict().describe("Click an element"),
16618
16618
  external_exports.object({
16619
16619
  do: external_exports.literal("type"),
16620
- into: ScriptTargetSchema,
16621
- text: external_exports.string(),
16620
+ into: ScriptTargetSchema.describe("The field to type into"),
16621
+ text: external_exports.string().describe("What to type: a demo value, never a real secret"),
16622
16622
  recorded: RecordedSchema
16623
- }).strict(),
16623
+ }).strict().describe("Type text into a field"),
16624
16624
  external_exports.object({
16625
16625
  do: external_exports.literal("hover"),
16626
- on: ScriptTargetSchema,
16626
+ on: ScriptTargetSchema.describe("The element to rest the pointer on"),
16627
16627
  recorded: RecordedSchema
16628
- }).strict(),
16628
+ }).strict().describe("Rest the pointer on an element"),
16629
16629
  external_exports.object({
16630
16630
  do: external_exports.literal("scrollTo"),
16631
- on: ScriptTargetSchema,
16631
+ on: ScriptTargetSchema.describe("The element to scroll into view"),
16632
16632
  recorded: RecordedSchema,
16633
16633
  /**
16634
16634
  * Where the scroll leaves its element: `top` is the viewport y, in CSS
@@ -16645,28 +16645,34 @@ Set the \`cycles\` parameter to \`"ref"\` to resolve cyclical schemas with defs.
16645
16645
  * only an element asks for. A `top` that would leave the element off
16646
16646
  * screen centres too, and the run reports `scrollLandingOffscreen`.
16647
16647
  */
16648
- landing: external_exports.object({ top: external_exports.number().finite() }).strict().optional()
16649
- }).strict(),
16648
+ landing: external_exports.object({ top: external_exports.number().finite() }).strict().optional().describe("Where the element's top edge stops, in CSS px from the top of the window. Absent centres it")
16649
+ }).strict().describe("Scroll an element into view"),
16650
16650
  external_exports.object({
16651
16651
  do: external_exports.literal("waitFor"),
16652
- on: ScriptTargetSchema,
16653
- until: external_exports.enum(["visible", "hidden"]),
16652
+ on: ScriptTargetSchema.describe("The element to wait for"),
16653
+ until: external_exports.enum(["visible", "hidden"]).describe("Wait until it shows, or until it goes"),
16654
16654
  recorded: RecordedSchema
16655
- }).strict(),
16655
+ }).strict().describe("Wait for an element to show or go"),
16656
16656
  external_exports.object({
16657
16657
  do: external_exports.literal("drag"),
16658
- from: DragFromSchema,
16659
- to: DragToSchema,
16660
- zoom: ZoomIntentSchema.optional(),
16658
+ from: DragFromSchema.describe("Where the drag presses: `{ on, at? }`, an element and a spot in it"),
16659
+ to: DragToSchema.describe("Where it lets go: `{ on, at? }` as `from`, or `{ by: { x, y } }` in CSS px from the start"),
16660
+ zoom: ZoomIntentSchema.optional().describe("The camera's zoom at this drag, as on `click`"),
16661
16661
  recorded: RecordedSchema
16662
- }).strict(),
16662
+ }).strict().describe("Press, move and let go"),
16663
16663
  external_exports.object({
16664
16664
  do: external_exports.literal("press"),
16665
- key: external_exports.enum(PRESS_KEYS),
16665
+ key: external_exports.enum(PRESS_KEYS).describe("The key to press"),
16666
16666
  recorded: RecordedSchema
16667
- }).strict(),
16668
- external_exports.object({ do: external_exports.literal("waitForLoad"), recorded: RecordedSchema }).strict(),
16669
- external_exports.object({ do: external_exports.literal("pause"), ms: external_exports.number().positive() }).strict()
16667
+ }).strict().describe("Press a key"),
16668
+ external_exports.object({
16669
+ do: external_exports.literal("waitForLoad"),
16670
+ recorded: RecordedSchema
16671
+ }).strict().describe("Wait for the page to finish loading"),
16672
+ external_exports.object({
16673
+ do: external_exports.literal("pause"),
16674
+ ms: external_exports.number().positive().describe("How long, in milliseconds")
16675
+ }).strict().describe("Hold still, so the viewer can read. Performs nothing")
16670
16676
  ]);
16671
16677
  var ACTS_ON_THE_PAGE = {
16672
16678
  click: true,
@@ -16724,30 +16730,30 @@ Set the \`cycles\` parameter to \`"ref"\` to resolve cyclical schemas with defs.
16724
16730
  var laterVersion = (a, b) => b > a ? b : a;
16725
16731
  var DemoScriptShape = external_exports.object({
16726
16732
  /** Optional: Demoman sets it (see `minimumScriptVersion`); a lower one is raised. */
16727
- scriptVersion: ScriptVersionSchema.optional(),
16728
- name: external_exports.string().min(1),
16729
- target: external_exports.url(),
16733
+ scriptVersion: ScriptVersionSchema.optional().describe("The format's number. Demoman sets it; leave it out"),
16734
+ name: external_exports.string().min(1).describe("The video's name"),
16735
+ target: external_exports.url().describe("The page the run opens first, http or https"),
16730
16736
  /** Absent means the run's own window size, recorded into the document. */
16731
16737
  viewport: external_exports.object({
16732
16738
  width: external_exports.number().int().positive(),
16733
16739
  height: external_exports.number().int().positive()
16734
- }).optional(),
16740
+ }).optional().describe("The window size in CSS px, `{ width, height }`. Absent: Demoman's own window"),
16735
16741
  /** A phone or tablet to film as (spec 2026-10-10 §3). Absent: the desktop.
16736
16742
  * A device is a viewport, so naming both is refused. */
16737
- device: DeviceIdSchema.optional(),
16743
+ device: DeviceIdSchema.optional().describe("A phone or tablet to record as, instead of a viewport. See Phone and tablet"),
16738
16744
  /** One of the site's accounts in `.demoman/accounts.json` (launch C2).
16739
16745
  * Absent: the site's `default`, else the saved manual session. */
16740
16746
  account: external_exports.string().regex(ACCOUNT_NAME, {
16741
16747
  message: `an account name is ${ACCOUNT_NAME_RULE}`
16742
- }).optional(),
16743
- steps: external_exports.array(ScriptStepSchema).min(1),
16748
+ }).optional().describe("A demo account from `.demoman/accounts.json` to sign in as. Absent: the site's default, else your own saved sign-in"),
16749
+ steps: external_exports.array(ScriptStepSchema).min(1).describe("What the run does, in order. At least one step acts on the page"),
16744
16750
  /** Cut the film's start and end (`ScriptTrimSchema`). Absent: the whole take. */
16745
- trim: ScriptTrimSchema.optional(),
16751
+ trim: ScriptTrimSchema.optional().describe("Cut the video's start and end: `{ start: { ms, step? }, end: { ms, step?, after? } }`. Absent: the whole video"),
16746
16752
  /**
16747
16753
  * The take that steps' `recorded` ids refer to (`scriptFromTake` writes it).
16748
16754
  * Absent on a script nobody derived from a recording.
16749
16755
  */
16750
- recordedFrom: external_exports.string().min(1).optional(),
16756
+ recordedFrom: external_exports.string().min(1).optional().describe("The video a derived script came from. Demoman writes it"),
16751
16757
  /**
16752
16758
  * The frame's dress. Reuses the document's own schemas so there is one
16753
16759
  * vocabulary for branding, cursor and canvas rather than two. Absent means
@@ -16757,9 +16763,10 @@ Set the \`cycles\` parameter to \`"ref"\` to resolve cyclical schemas with defs.
16757
16763
  branding: ScriptBrandingSchema.optional(),
16758
16764
  /**
16759
16765
  * One of the author's brand kits, by the name Settings shows (case and
16760
- * surrounding space ignored). Resolved by the extension at the run's
16761
- * door; a name that is not there is refused (`unknownKit`), never
16762
- * replaced by the default kit (spec 2026-10-08 §3).
16766
+ * surrounding space ignored). Resolved by the runner at the run's
16767
+ * door (`lookForRun`, in `@demoman/run-core`); a name that is not
16768
+ * there is refused (`unknownKit`), never replaced by the default kit
16769
+ * (spec 2026-10-08 §3).
16763
16770
  */
16764
16771
  kit: external_exports.string().trim().min(1).optional(),
16765
16772
  cursor: CursorSchema.optional(),
@@ -16774,7 +16781,7 @@ Set the \`cycles\` parameter to \`"ref"\` to resolve cyclical schemas with defs.
16774
16781
  motion: MotionSchema.optional()
16775
16782
  }).strict().refine((look) => look.branding === void 0 || look.kit === void 0, {
16776
16783
  message: "name a kit or give a branding, not both"
16777
- }).optional()
16784
+ }).optional().describe("The frame's look: `kit` (a brand kit by name) or `branding`, plus `cursor`, `canvas` and `motion`. Absent: your default brand kit")
16778
16785
  });
16779
16786
  var DemoScriptSchema = DemoScriptShape.superRefine((script, ctx) => {
16780
16787
  const bg = script.look?.branding?.background;
@@ -16932,9 +16939,9 @@ Set the \`cycles\` parameter to \`"ref"\` to resolve cyclical schemas with defs.
16932
16939
  verticalMaxScale: 1.15,
16933
16940
  /**
16934
16941
  * CSS px of page kept round a zoomed target on every side, so its edges
16935
- * and the cursor on it are not flush with the frame. The extension's
16936
- * generated zooms fit against the capture viewport with it
16937
- * (`zoomsForClicks`); a `cover` render fits against its own crop with it
16942
+ * and the cursor on it are not flush with the frame. Generated zooms fit
16943
+ * against the capture viewport with it (`zoomsForClicks`,
16944
+ * `@demoman/run-core`); a `cover` render fits against its own crop with it
16938
16945
  * (`solveCamera`'s `fitWindow`).
16939
16946
  */
16940
16947
  fitMarginPx: 24,
@@ -16948,8 +16955,8 @@ Set the \`cycles\` parameter to \`"ref"\` to resolve cyclical schemas with defs.
16948
16955
  */
16949
16956
  actSettleMs: 400,
16950
16957
  /**
16951
- * The push-in and the pull-out at the DEFAULT smoothness — what the
16952
- * extension sizes a fresh zoom's length by (`zoom-defaults.ts`) and the
16958
+ * The push-in and the pull-out at the DEFAULT smoothness — what
16959
+ * `@demoman/run-core` sizes a fresh zoom's length by (`zoom-defaults.ts`) and the
16953
16960
  * editor draws an unauthored end with. A render reads the document's own
16954
16961
  * smoothness through `motionTimings`, so these are the timings of a take
16955
16962
  * that never touched the slider, not of every take.
@@ -26799,7 +26806,7 @@ Set the \`cycles\` parameter to \`"ref"\` to resolve cyclical schemas with defs.
26799
26806
  },
26800
26807
  // Bytes or a reason, never an empty array: a 0-byte file stored as a
26801
26808
  // successful output is a Download button that does nothing, and the
26802
- // render loop, the offscreen host and the editor all read `bytes` as
26809
+ // render loop, the runner's render page and the editor all read `bytes` as
26803
26810
  // "it worked".
26804
26811
  async finish() {
26805
26812
  finished = true;
@@ -26895,7 +26902,11 @@ Set the \`cycles\` parameter to \`"ref"\` to resolve cyclical schemas with defs.
26895
26902
  const blob = await response.blob();
26896
26903
  const bitmap = await createImageBitmap(blob);
26897
26904
  try {
26898
- ctx.drawImage(bitmap, 0, 0, manifest.width, manifest.height);
26905
+ const evened = [0, 1].includes(bitmap.width - manifest.width) && [0, 1].includes(bitmap.height - manifest.height);
26906
+ if (evened)
26907
+ ctx.drawImage(bitmap, 0, 0);
26908
+ else
26909
+ ctx.drawImage(bitmap, 0, 0, manifest.width, manifest.height);
26899
26910
  } finally {
26900
26911
  bitmap.close();
26901
26912
  }
@@ -16337,14 +16337,14 @@ Set the \`cycles\` parameter to \`"ref"\` to resolve cyclical schemas with defs.
16337
16337
  * unchanged, but its MEANING narrows: this now records which frames PLAY,
16338
16338
  * not which the author chose. The editor writes it nowhere — since
16339
16339
  * 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
16340
+ * value (`persist()` in `apps/studio/pages/src/editor/session.ts`). Two
16341
+ * writers set it, both outside the editor: `assembleAuthored`
16342
+ * (`@demoman/replay-engine`) writes `screen` on every new take, and the
16343
+ * library card's "Back to your recording"
16344
+ * (`apps/studio/pages/entrypoints/library/main.ts`) sets `screen`. Nothing writes `demo` today; it is
16345
+ * read from takes the retired extension re-shot. Neither writer deletes
16346
+ * anything — the recording stays on disk under either mode
16347
+ * (`chooseActiveBundle`'s own docblock) — so a re-shoot that turns
16348
16348
  * out worse than the recording is always reversible by writing this field
16349
16349
  * back.
16350
16350
  */
@@ -16757,7 +16757,7 @@ Set the \`cycles\` parameter to \`"ref"\` to resolve cyclical schemas with defs.
16757
16757
  external_exports.object({ text: external_exports.string().min(1) }).strict(),
16758
16758
  external_exports.object({ treePath: external_exports.string().min(1) }).strict()
16759
16759
  ]);
16760
- var RecordedSchema = external_exports.string().min(1).optional();
16760
+ var RecordedSchema = external_exports.string().min(1).optional().describe("Written by Demoman when the script was derived from a video; pairs the step with the action it came from. Leave it as it is");
16761
16761
  var DragSpotSchema = external_exports.object({ x: external_exports.number().min(0).max(1), y: external_exports.number().min(0).max(1) }).strict();
16762
16762
  var DragFromSchema = external_exports.object({ on: ScriptTargetSchema, at: DragSpotSchema.optional() }).strict();
16763
16763
  var DragToSchema = external_exports.union([
@@ -16779,10 +16779,10 @@ Set the \`cycles\` parameter to \`"ref"\` to resolve cyclical schemas with defs.
16779
16779
  var ScriptStepSchema = external_exports.discriminatedUnion("do", [
16780
16780
  external_exports.object({
16781
16781
  do: external_exports.literal("click"),
16782
- on: ScriptTargetSchema,
16782
+ on: ScriptTargetSchema.describe("The element to click"),
16783
16783
  /** Where in the target's box to click (its centre if absent). */
16784
- at: DragSpotSchema.optional(),
16785
- zoom: ZoomIntentSchema.optional(),
16784
+ at: DragSpotSchema.optional().describe("Where in the element to click, as fractions of its width and height; its centre if absent"),
16785
+ zoom: ZoomIntentSchema.optional().describe("The camera's zoom at this click: `false` for none, or `{ scale }` over 1 and at most 2.5. Absent leaves it to the camera"),
16786
16786
  /**
16787
16787
  * The recorded action this step was derived from (`scriptFromTake` writes
16788
16788
  * it). How the recording layer pairs a run's step with the author's —
@@ -16790,21 +16790,21 @@ Set the \`cycles\` parameter to \`"ref"\` to resolve cyclical schemas with defs.
16790
16790
  * list would go stale the moment it did. Absent on a step the agent wrote.
16791
16791
  */
16792
16792
  recorded: RecordedSchema
16793
- }).strict(),
16793
+ }).strict().describe("Click an element"),
16794
16794
  external_exports.object({
16795
16795
  do: external_exports.literal("type"),
16796
- into: ScriptTargetSchema,
16797
- text: external_exports.string(),
16796
+ into: ScriptTargetSchema.describe("The field to type into"),
16797
+ text: external_exports.string().describe("What to type: a demo value, never a real secret"),
16798
16798
  recorded: RecordedSchema
16799
- }).strict(),
16799
+ }).strict().describe("Type text into a field"),
16800
16800
  external_exports.object({
16801
16801
  do: external_exports.literal("hover"),
16802
- on: ScriptTargetSchema,
16802
+ on: ScriptTargetSchema.describe("The element to rest the pointer on"),
16803
16803
  recorded: RecordedSchema
16804
- }).strict(),
16804
+ }).strict().describe("Rest the pointer on an element"),
16805
16805
  external_exports.object({
16806
16806
  do: external_exports.literal("scrollTo"),
16807
- on: ScriptTargetSchema,
16807
+ on: ScriptTargetSchema.describe("The element to scroll into view"),
16808
16808
  recorded: RecordedSchema,
16809
16809
  /**
16810
16810
  * Where the scroll leaves its element: `top` is the viewport y, in CSS
@@ -16821,28 +16821,34 @@ Set the \`cycles\` parameter to \`"ref"\` to resolve cyclical schemas with defs.
16821
16821
  * only an element asks for. A `top` that would leave the element off
16822
16822
  * screen centres too, and the run reports `scrollLandingOffscreen`.
16823
16823
  */
16824
- landing: external_exports.object({ top: external_exports.number().finite() }).strict().optional()
16825
- }).strict(),
16824
+ landing: external_exports.object({ top: external_exports.number().finite() }).strict().optional().describe("Where the element's top edge stops, in CSS px from the top of the window. Absent centres it")
16825
+ }).strict().describe("Scroll an element into view"),
16826
16826
  external_exports.object({
16827
16827
  do: external_exports.literal("waitFor"),
16828
- on: ScriptTargetSchema,
16829
- until: external_exports.enum(["visible", "hidden"]),
16828
+ on: ScriptTargetSchema.describe("The element to wait for"),
16829
+ until: external_exports.enum(["visible", "hidden"]).describe("Wait until it shows, or until it goes"),
16830
16830
  recorded: RecordedSchema
16831
- }).strict(),
16831
+ }).strict().describe("Wait for an element to show or go"),
16832
16832
  external_exports.object({
16833
16833
  do: external_exports.literal("drag"),
16834
- from: DragFromSchema,
16835
- to: DragToSchema,
16836
- zoom: ZoomIntentSchema.optional(),
16834
+ from: DragFromSchema.describe("Where the drag presses: `{ on, at? }`, an element and a spot in it"),
16835
+ to: DragToSchema.describe("Where it lets go: `{ on, at? }` as `from`, or `{ by: { x, y } }` in CSS px from the start"),
16836
+ zoom: ZoomIntentSchema.optional().describe("The camera's zoom at this drag, as on `click`"),
16837
16837
  recorded: RecordedSchema
16838
- }).strict(),
16838
+ }).strict().describe("Press, move and let go"),
16839
16839
  external_exports.object({
16840
16840
  do: external_exports.literal("press"),
16841
- key: external_exports.enum(PRESS_KEYS),
16841
+ key: external_exports.enum(PRESS_KEYS).describe("The key to press"),
16842
16842
  recorded: RecordedSchema
16843
- }).strict(),
16844
- external_exports.object({ do: external_exports.literal("waitForLoad"), recorded: RecordedSchema }).strict(),
16845
- external_exports.object({ do: external_exports.literal("pause"), ms: external_exports.number().positive() }).strict()
16843
+ }).strict().describe("Press a key"),
16844
+ external_exports.object({
16845
+ do: external_exports.literal("waitForLoad"),
16846
+ recorded: RecordedSchema
16847
+ }).strict().describe("Wait for the page to finish loading"),
16848
+ external_exports.object({
16849
+ do: external_exports.literal("pause"),
16850
+ ms: external_exports.number().positive().describe("How long, in milliseconds")
16851
+ }).strict().describe("Hold still, so the viewer can read. Performs nothing")
16846
16852
  ]);
16847
16853
  var ACTS_ON_THE_PAGE = {
16848
16854
  click: true,
@@ -16900,30 +16906,30 @@ Set the \`cycles\` parameter to \`"ref"\` to resolve cyclical schemas with defs.
16900
16906
  var laterVersion = (a, b) => b > a ? b : a;
16901
16907
  var DemoScriptShape = external_exports.object({
16902
16908
  /** Optional: Demoman sets it (see `minimumScriptVersion`); a lower one is raised. */
16903
- scriptVersion: ScriptVersionSchema.optional(),
16904
- name: external_exports.string().min(1),
16905
- target: external_exports.url(),
16909
+ scriptVersion: ScriptVersionSchema.optional().describe("The format's number. Demoman sets it; leave it out"),
16910
+ name: external_exports.string().min(1).describe("The video's name"),
16911
+ target: external_exports.url().describe("The page the run opens first, http or https"),
16906
16912
  /** Absent means the run's own window size, recorded into the document. */
16907
16913
  viewport: external_exports.object({
16908
16914
  width: external_exports.number().int().positive(),
16909
16915
  height: external_exports.number().int().positive()
16910
- }).optional(),
16916
+ }).optional().describe("The window size in CSS px, `{ width, height }`. Absent: Demoman's own window"),
16911
16917
  /** A phone or tablet to film as (spec 2026-10-10 §3). Absent: the desktop.
16912
16918
  * A device is a viewport, so naming both is refused. */
16913
- device: DeviceIdSchema.optional(),
16919
+ device: DeviceIdSchema.optional().describe("A phone or tablet to record as, instead of a viewport. See Phone and tablet"),
16914
16920
  /** One of the site's accounts in `.demoman/accounts.json` (launch C2).
16915
16921
  * Absent: the site's `default`, else the saved manual session. */
16916
16922
  account: external_exports.string().regex(ACCOUNT_NAME, {
16917
16923
  message: `an account name is ${ACCOUNT_NAME_RULE}`
16918
- }).optional(),
16919
- steps: external_exports.array(ScriptStepSchema).min(1),
16924
+ }).optional().describe("A demo account from `.demoman/accounts.json` to sign in as. Absent: the site's default, else your own saved sign-in"),
16925
+ steps: external_exports.array(ScriptStepSchema).min(1).describe("What the run does, in order. At least one step acts on the page"),
16920
16926
  /** Cut the film's start and end (`ScriptTrimSchema`). Absent: the whole take. */
16921
- trim: ScriptTrimSchema.optional(),
16927
+ trim: ScriptTrimSchema.optional().describe("Cut the video's start and end: `{ start: { ms, step? }, end: { ms, step?, after? } }`. Absent: the whole video"),
16922
16928
  /**
16923
16929
  * The take that steps' `recorded` ids refer to (`scriptFromTake` writes it).
16924
16930
  * Absent on a script nobody derived from a recording.
16925
16931
  */
16926
- recordedFrom: external_exports.string().min(1).optional(),
16932
+ recordedFrom: external_exports.string().min(1).optional().describe("The video a derived script came from. Demoman writes it"),
16927
16933
  /**
16928
16934
  * The frame's dress. Reuses the document's own schemas so there is one
16929
16935
  * vocabulary for branding, cursor and canvas rather than two. Absent means
@@ -16933,9 +16939,10 @@ Set the \`cycles\` parameter to \`"ref"\` to resolve cyclical schemas with defs.
16933
16939
  branding: ScriptBrandingSchema.optional(),
16934
16940
  /**
16935
16941
  * One of the author's brand kits, by the name Settings shows (case and
16936
- * surrounding space ignored). Resolved by the extension at the run's
16937
- * door; a name that is not there is refused (`unknownKit`), never
16938
- * replaced by the default kit (spec 2026-10-08 §3).
16942
+ * surrounding space ignored). Resolved by the runner at the run's
16943
+ * door (`lookForRun`, in `@demoman/run-core`); a name that is not
16944
+ * there is refused (`unknownKit`), never replaced by the default kit
16945
+ * (spec 2026-10-08 §3).
16939
16946
  */
16940
16947
  kit: external_exports.string().trim().min(1).optional(),
16941
16948
  cursor: CursorSchema.optional(),
@@ -16950,7 +16957,7 @@ Set the \`cycles\` parameter to \`"ref"\` to resolve cyclical schemas with defs.
16950
16957
  motion: MotionSchema.optional()
16951
16958
  }).strict().refine((look) => look.branding === void 0 || look.kit === void 0, {
16952
16959
  message: "name a kit or give a branding, not both"
16953
- }).optional()
16960
+ }).optional().describe("The frame's look: `kit` (a brand kit by name) or `branding`, plus `cursor`, `canvas` and `motion`. Absent: your default brand kit")
16954
16961
  });
16955
16962
  var DemoScriptSchema = DemoScriptShape.superRefine((script, ctx) => {
16956
16963
  const bg = script.look?.branding?.background;
@@ -17951,9 +17958,9 @@ Set the \`cycles\` parameter to \`"ref"\` to resolve cyclical schemas with defs.
17951
17958
  verticalMaxScale: 1.15,
17952
17959
  /**
17953
17960
  * CSS px of page kept round a zoomed target on every side, so its edges
17954
- * and the cursor on it are not flush with the frame. The extension's
17955
- * generated zooms fit against the capture viewport with it
17956
- * (`zoomsForClicks`); a `cover` render fits against its own crop with it
17961
+ * and the cursor on it are not flush with the frame. Generated zooms fit
17962
+ * against the capture viewport with it (`zoomsForClicks`,
17963
+ * `@demoman/run-core`); a `cover` render fits against its own crop with it
17957
17964
  * (`solveCamera`'s `fitWindow`).
17958
17965
  */
17959
17966
  fitMarginPx: 24,
@@ -17967,8 +17974,8 @@ Set the \`cycles\` parameter to \`"ref"\` to resolve cyclical schemas with defs.
17967
17974
  */
17968
17975
  actSettleMs: 400,
17969
17976
  /**
17970
- * The push-in and the pull-out at the DEFAULT smoothness — what the
17971
- * extension sizes a fresh zoom's length by (`zoom-defaults.ts`) and the
17977
+ * The push-in and the pull-out at the DEFAULT smoothness — what
17978
+ * `@demoman/run-core` sizes a fresh zoom's length by (`zoom-defaults.ts`) and the
17972
17979
  * editor draws an unauthored end with. A render reads the document's own
17973
17980
  * smoothness through `motionTimings`, so these are the timings of a take
17974
17981
  * that never touched the slider, not of every take.
@@ -18342,7 +18349,24 @@ Set the \`cycles\` parameter to \`"ref"\` to resolve cyclical schemas with defs.
18342
18349
  }
18343
18350
  return departures[aimed]?.center ?? landing.center;
18344
18351
  };
18345
- const targetAt = (t) => (cursorAt !== null && !held(t) ? cursorAt(t) : null) ?? aimAt(t);
18352
+ let holding = false;
18353
+ let rest = null;
18354
+ const targetAt = (t) => {
18355
+ if (held(t)) {
18356
+ holding = true;
18357
+ return aimAt(t);
18358
+ }
18359
+ const hand = cursorAt?.(t) ?? null;
18360
+ if (holding) {
18361
+ holding = false;
18362
+ rest = hand;
18363
+ }
18364
+ if (hand !== null && rest !== null && Math.hypot(hand.x - rest.x, hand.y - rest.y) < CURSOR_MOTION_EPSILON_PX) {
18365
+ return aimAt(t);
18366
+ }
18367
+ rest = null;
18368
+ return hand ?? aimAt(t);
18369
+ };
18346
18370
  let x = landing.center;
18347
18371
  let v = { x: 0, y: 0 };
18348
18372
  const centers = [x];
@@ -47261,7 +47285,7 @@ Set the \`cycles\` parameter to \`"ref"\` to resolve cyclical schemas with defs.
47261
47285
  },
47262
47286
  // Bytes or a reason, never an empty array: a 0-byte file stored as a
47263
47287
  // successful output is a Download button that does nothing, and the
47264
- // render loop, the offscreen host and the editor all read `bytes` as
47288
+ // render loop, the runner's render page and the editor all read `bytes` as
47265
47289
  // "it worked".
47266
47290
  async finish() {
47267
47291
  finished = true;