autokast 0.0.0 → 0.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (79) hide show
  1. package/LICENSE +29 -0
  2. package/README.md +165 -0
  3. package/dist/cli.d.ts +2 -0
  4. package/dist/cli.js +300 -0
  5. package/dist/index.d.ts +4 -0
  6. package/dist/index.js +4 -0
  7. package/dist/inspect.d.ts +26 -0
  8. package/dist/inspect.js +193 -0
  9. package/dist/record/animations.d.ts +7 -0
  10. package/dist/record/animations.js +34 -0
  11. package/dist/record/capture.d.ts +85 -0
  12. package/dist/record/capture.js +202 -0
  13. package/dist/record/cast.d.ts +142 -0
  14. package/dist/record/cast.js +680 -0
  15. package/dist/record/cursor-style.d.ts +33 -0
  16. package/dist/record/cursor-style.js +252 -0
  17. package/dist/record/defaults.d.ts +96 -0
  18. package/dist/record/defaults.js +125 -0
  19. package/dist/record/editor.d.ts +11 -0
  20. package/dist/record/editor.js +48 -0
  21. package/dist/record/frame-pump.d.ts +91 -0
  22. package/dist/record/frame-pump.js +306 -0
  23. package/dist/record/index.d.ts +11 -0
  24. package/dist/record/index.js +287 -0
  25. package/dist/record/motion.d.ts +48 -0
  26. package/dist/record/motion.js +112 -0
  27. package/dist/record/pace.d.ts +69 -0
  28. package/dist/record/pace.js +133 -0
  29. package/dist/record/random.d.ts +12 -0
  30. package/dist/record/random.js +24 -0
  31. package/dist/record/scroll.d.ts +71 -0
  32. package/dist/record/scroll.js +249 -0
  33. package/dist/record/timeline.d.ts +34 -0
  34. package/dist/record/timeline.js +44 -0
  35. package/dist/render/background.d.ts +12 -0
  36. package/dist/render/background.js +209 -0
  37. package/dist/render/browser.d.ts +46 -0
  38. package/dist/render/browser.js +223 -0
  39. package/dist/render/camera.d.ts +119 -0
  40. package/dist/render/camera.js +372 -0
  41. package/dist/render/captions.d.ts +114 -0
  42. package/dist/render/captions.js +254 -0
  43. package/dist/render/color.d.ts +23 -0
  44. package/dist/render/color.js +78 -0
  45. package/dist/render/compositor.d.ts +185 -0
  46. package/dist/render/compositor.js +656 -0
  47. package/dist/render/cursor.d.ts +85 -0
  48. package/dist/render/cursor.js +314 -0
  49. package/dist/render/cursors/shapes.d.ts +34 -0
  50. package/dist/render/cursors/shapes.js +268 -0
  51. package/dist/render/defaults.d.ts +91 -0
  52. package/dist/render/defaults.js +139 -0
  53. package/dist/render/easing.d.ts +13 -0
  54. package/dist/render/easing.js +40 -0
  55. package/dist/render/effects.d.ts +39 -0
  56. package/dist/render/effects.js +91 -0
  57. package/dist/render/encoder.d.ts +52 -0
  58. package/dist/render/encoder.js +226 -0
  59. package/dist/render/index.d.ts +19 -0
  60. package/dist/render/index.js +138 -0
  61. package/dist/render/keycaps.d.ts +67 -0
  62. package/dist/render/keycaps.js +270 -0
  63. package/dist/render/scene.d.ts +59 -0
  64. package/dist/render/scene.js +230 -0
  65. package/dist/render/source.d.ts +21 -0
  66. package/dist/render/source.js +57 -0
  67. package/dist/render/spring.d.ts +11 -0
  68. package/dist/render/spring.js +47 -0
  69. package/dist/render/stage.d.ts +59 -0
  70. package/dist/render/stage.js +91 -0
  71. package/dist/render/timeline.d.ts +70 -0
  72. package/dist/render/timeline.js +157 -0
  73. package/dist/session.d.ts +14 -0
  74. package/dist/session.js +33 -0
  75. package/dist/types.d.ts +708 -0
  76. package/dist/types.js +1 -0
  77. package/package.json +61 -3
  78. package/skills/autokast/SKILL.md +300 -0
  79. package/skills/autokast/reference/jupyterlab.md +100 -0
@@ -0,0 +1,306 @@
1
+ import { mkdir } from 'node:fs/promises';
2
+ import path from 'node:path';
3
+ import { FRAMES_DIR, FrameWriter } from "./capture.js";
4
+ import { sleep } from "./timeline.js";
5
+ /**
6
+ * Chromium flags for frame-perfect capture: the page paints only on BeginFrame, and all
7
+ * animation and scrolling runs on the main thread, on the page clock.
8
+ */
9
+ export const FRAME_PERFECT_ARGS = [
10
+ '--enable-begin-frame-control',
11
+ '--run-all-compositor-stages-before-draw',
12
+ '--disable-new-content-rendering-timeout',
13
+ '--disable-threaded-animation',
14
+ '--disable-threaded-scrolling',
15
+ '--disable-checker-imaging',
16
+ '--disable-image-animation-resync',
17
+ ];
18
+ /**
19
+ * Page script for frame-perfect capture. Under the page clock, Chromium can hold idle
20
+ * callbacks after input until the end of the recording: run them on timers, which follow
21
+ * the page clock. The JupyterLab cell toolbar, for example, shows from an idle callback.
22
+ */
23
+ export function idleCallbacksOnTimers() {
24
+ window.requestIdleCallback = (callback) => window.setTimeout(() => {
25
+ const end = performance.now() + 16;
26
+ callback({ didTimeout: false, timeRemaining: () => Math.max(0, end - performance.now()) });
27
+ }, 1);
28
+ window.cancelIdleCallback = (id) => window.clearTimeout(id);
29
+ }
30
+ /**
31
+ * Real-time waits of the pump, in milliseconds.
32
+ */
33
+ const WAIT = {
34
+ /**
35
+ * For input sent just before a frame. Mouse input is acknowledged only after the frame.
36
+ */
37
+ inputSettle: 20,
38
+ /**
39
+ * For the acknowledgement of the previous frame's input, then a short gap, so that the
40
+ * browser can forward follow-up events (a wheel gives a scroll gesture) before the frame.
41
+ */
42
+ ack: 100,
43
+ ackGap: 5,
44
+ /**
45
+ * Before a stuck BeginFrame gets a small step of virtual time.
46
+ */
47
+ watchdog: 100,
48
+ /**
49
+ * For virtual time to advance at all.
50
+ */
51
+ advance: 30_000,
52
+ /**
53
+ * For one frame to finish.
54
+ */
55
+ frame: 30_000,
56
+ };
57
+ /**
58
+ * Virtual time step, in ms, that releases a BeginFrame blocked by a renderer task that
59
+ * waits on the frozen page clock (seen after wheel input).
60
+ */
61
+ const KICK = 1;
62
+ const FREE_RUN_INTERVAL = 1000 / 60;
63
+ /**
64
+ * Drives the page clock for frame-perfect capture. Before the recording, a free-running loop
65
+ * sends frames in real time, so that the page loads and Playwright works. During the
66
+ * recording, each step advances virtual time by one frame, sends the queued input, and
67
+ * captures the frame. Record time is `frame * frameMs`.
68
+ */
69
+ export class FramePump {
70
+ frameMs;
71
+ cdp;
72
+ settings;
73
+ writer;
74
+ frame = -1;
75
+ virtual = 0;
76
+ base = 0;
77
+ baseVirtual = 0;
78
+ running = false;
79
+ freeRunning = false;
80
+ loop = Promise.resolve();
81
+ freeLoop = Promise.resolve();
82
+ capturing = true;
83
+ lastImage;
84
+ end = Infinity;
85
+ inputs = [];
86
+ unsettled = new Set();
87
+ waiters = [];
88
+ error;
89
+ constructor(cdp, dir, settings) {
90
+ this.cdp = cdp;
91
+ this.settings = settings;
92
+ this.frameMs = 1000 / settings.fps;
93
+ this.writer = new FrameWriter(dir, settings.format);
94
+ }
95
+ static async create(context, page, dir, settings) {
96
+ await mkdir(path.join(dir, FRAMES_DIR), { recursive: true });
97
+ return new FramePump(await context.newCDPSession(page), dir, settings);
98
+ }
99
+ get frames() {
100
+ return this.writer.frames;
101
+ }
102
+ get frameSize() {
103
+ return this.writer.frameSize;
104
+ }
105
+ /**
106
+ * Record time in ms: the time of the last frame.
107
+ */
108
+ now() {
109
+ return Math.max(0, this.frame) * this.frameMs;
110
+ }
111
+ /**
112
+ * Sends frames in real time, without the page clock, until `start()`.
113
+ */
114
+ startFreeRun() {
115
+ this.freeRunning = true;
116
+ this.freeLoop = (async () => {
117
+ while (this.freeRunning) {
118
+ const started = performance.now();
119
+ await this.cdp
120
+ .send('HeadlessExperimental.beginFrame', { interval: this.frameMs })
121
+ .catch(() => { });
122
+ await sleep(FREE_RUN_INTERVAL - (performance.now() - started));
123
+ }
124
+ })();
125
+ }
126
+ /**
127
+ * Pauses the page clock and starts the recording. Resolves once frame 0 is captured.
128
+ */
129
+ async start() {
130
+ this.freeRunning = false;
131
+ await this.freeLoop;
132
+ // Page time runs slower than real time: with a lead, server time stamps made during
133
+ // the recording stay in the page's past.
134
+ const { virtualTimeTicksBase } = await this.cdp.send('Emulation.setVirtualTimePolicy', {
135
+ policy: 'pause',
136
+ initialVirtualTime: (Date.now() + this.settings.clockLead) / 1000,
137
+ });
138
+ this.base = virtualTimeTicksBase;
139
+ this.running = true;
140
+ this.loop = this.run().catch((error) => this.fail(error));
141
+ await this.waitFrame(0);
142
+ }
143
+ /**
144
+ * Stops at record time `end`, after the frame in progress, and waits for the writes.
145
+ * The page then gets no more frames.
146
+ */
147
+ async stop(end = Infinity) {
148
+ this.end = end;
149
+ this.running = false;
150
+ this.freeRunning = false;
151
+ await Promise.all([this.loop, this.freeLoop]);
152
+ await this.writer.flush();
153
+ return this.frames;
154
+ }
155
+ /**
156
+ * Resolves once `ms` of page time has passed, rounded to whole frames.
157
+ */
158
+ wait(ms) {
159
+ if (!(ms > 0)) {
160
+ return this.error ? Promise.reject(this.error) : Promise.resolve();
161
+ }
162
+ return this.waitFrame(this.frame + Math.max(1, Math.round(ms / this.frameMs)));
163
+ }
164
+ /**
165
+ * Sends input right before the next frame. `send` gets the record time of that frame.
166
+ * Resolves with that time once the input is sent, without waiting for its acknowledgement.
167
+ */
168
+ input(send) {
169
+ if (this.error) {
170
+ return Promise.reject(this.error);
171
+ }
172
+ return new Promise((resolve) => this.inputs.push({ send, resolve }));
173
+ }
174
+ /**
175
+ * Turns screenshots off (inside cut regions) or on. Without screenshots, page time runs
176
+ * as fast as the page can render.
177
+ */
178
+ capture(on) {
179
+ this.capturing = on;
180
+ }
181
+ waitFrame(frame) {
182
+ if (this.error) {
183
+ return Promise.reject(this.error);
184
+ }
185
+ if (this.frame >= frame) {
186
+ return Promise.resolve();
187
+ }
188
+ return new Promise((resolve, reject) => this.waiters.push({ frame, resolve, reject }));
189
+ }
190
+ fail(error) {
191
+ this.error ??= error;
192
+ this.running = false;
193
+ for (const waiter of this.waiters.splice(0)) {
194
+ waiter.reject(this.error);
195
+ }
196
+ }
197
+ async run() {
198
+ while (this.running) {
199
+ const frame = this.frame + 1;
200
+ if (this.unsettled.size) {
201
+ await Promise.race([Promise.all(this.unsettled), sleep(WAIT.ack)]);
202
+ await sleep(WAIT.ackGap);
203
+ }
204
+ const budget = frame * this.frameMs - this.virtual;
205
+ if (budget > 0.01) {
206
+ await this.advance(budget);
207
+ }
208
+ this.frame = frame;
209
+ const t = this.now();
210
+ await this.sendInputs(t);
211
+ const screenshot = this.capturing
212
+ ? this.settings.format === 'png'
213
+ ? { format: 'png', optimizeForSpeed: true }
214
+ : { format: 'jpeg', quality: this.settings.quality, optimizeForSpeed: true }
215
+ : undefined;
216
+ const result = await this.beginFrame({
217
+ frameTimeTicks: this.base + this.virtual - this.baseVirtual,
218
+ interval: this.frameMs,
219
+ ...(screenshot ? { screenshot } : {}),
220
+ });
221
+ // A screenshot always reports damage: equal bytes mean an unchanged frame, which the
222
+ // renderer gets from the previous stored frame. No image (a new renderer starting after
223
+ // a cross-site navigation) also keeps the previous frame.
224
+ const image = result.screenshotData;
225
+ if (image && image !== this.lastImage && t <= this.end) {
226
+ this.lastImage = image;
227
+ this.writer.add(Buffer.from(image, 'base64'), t);
228
+ }
229
+ this.waiters = this.waiters.filter((waiter) => {
230
+ if (waiter.frame > this.frame) {
231
+ return true;
232
+ }
233
+ waiter.resolve();
234
+ return false;
235
+ });
236
+ // A failed input fails the Cast call that waits, but frames go on for error.png.
237
+ if (this.error) {
238
+ for (const waiter of this.waiters.splice(0)) {
239
+ waiter.reject(this.error);
240
+ }
241
+ }
242
+ }
243
+ }
244
+ async sendInputs(t) {
245
+ const inputs = this.inputs.splice(0);
246
+ if (inputs.length === 0) {
247
+ return;
248
+ }
249
+ const sent = inputs.map(({ send }) => {
250
+ const dispatch = Promise.resolve()
251
+ .then(() => send(t))
252
+ .catch((error) => {
253
+ this.error ??= error;
254
+ })
255
+ .finally(() => this.unsettled.delete(dispatch));
256
+ this.unsettled.add(dispatch);
257
+ return dispatch;
258
+ });
259
+ await Promise.race([Promise.all(sent), sleep(WAIT.inputSettle)]);
260
+ for (const input of inputs) {
261
+ input.resolve(t);
262
+ }
263
+ }
264
+ async advance(budget) {
265
+ let timer;
266
+ const expired = new Promise((resolve, reject) => {
267
+ this.cdp.once('Emulation.virtualTimeBudgetExpired', () => resolve());
268
+ timer = setTimeout(() => reject(new Error(`Page time did not advance within ${WAIT.advance} ms.`)), WAIT.advance);
269
+ });
270
+ try {
271
+ const { virtualTimeTicksBase } = await this.cdp.send('Emulation.setVirtualTimePolicy', {
272
+ policy: 'advance',
273
+ budget,
274
+ });
275
+ if (virtualTimeTicksBase !== this.base) {
276
+ // A new renderer process (cross-site navigation) has its own clock.
277
+ this.base = virtualTimeTicksBase;
278
+ this.baseVirtual = this.virtual;
279
+ }
280
+ await expired;
281
+ }
282
+ finally {
283
+ clearTimeout(timer);
284
+ }
285
+ this.virtual += budget;
286
+ }
287
+ async beginFrame(params) {
288
+ const pending = this.cdp.send('HeadlessExperimental.beginFrame', params);
289
+ let done = false;
290
+ pending.then(() => (done = true), () => (done = true));
291
+ const deadline = performance.now() + WAIT.frame;
292
+ while (!done) {
293
+ await Promise.race([pending, sleep(WAIT.watchdog)]);
294
+ if (done) {
295
+ break;
296
+ }
297
+ if (performance.now() > deadline) {
298
+ throw new Error(`The page did not paint a frame within ${WAIT.frame / 1000} s. A native popup, ` +
299
+ `such as a date or color picker, stops frame-perfect capture: avoid it, or ` +
300
+ `record with capture.mode "realtime".`);
301
+ }
302
+ await this.advance(KICK);
303
+ }
304
+ return pending;
305
+ }
306
+ }
@@ -0,0 +1,11 @@
1
+ import type { Cast, RecordedSession, RecordOptions, ScreencastDefinition, SetupContext } from '../types.ts';
2
+ export declare const ERROR_SCREENSHOT = "error.png";
3
+ /**
4
+ * Records a session: runs `setup` unrecorded, then captures `run`.
5
+ */
6
+ export declare function record(options: RecordOptions, run: (cast: Cast) => Promise<void>, setup?: (context: SetupContext) => Promise<void>): Promise<RecordedSession>;
7
+ /**
8
+ * Records a screencast definition. `overrides` replace fields of the definition; nested
9
+ * objects such as `browser` or `cursor` merge.
10
+ */
11
+ export declare function recordScreencast(definition: ScreencastDefinition, overrides?: Partial<RecordOptions>): Promise<RecordedSession>;
@@ -0,0 +1,287 @@
1
+ import { mkdir, rm } from 'node:fs/promises';
2
+ import path from 'node:path';
3
+ import { chromium } from 'playwright';
4
+ import { render } from "../render/index.js";
5
+ import { saveSession, SESSION_FILE } from "../session.js";
6
+ import { settleAnimations } from "./animations.js";
7
+ import { FRAMES_DIR, FrameCapture } from "./capture.js";
8
+ import { Director } from "./cast.js";
9
+ import { CursorStyleProbe } from "./cursor-style.js";
10
+ import { mergeOptions, resolveOptions } from "./defaults.js";
11
+ import { FRAME_PERFECT_ARGS, FramePump, idleCallbacksOnTimers } from "./frame-pump.js";
12
+ import { FramePerfectPace, RealtimePace } from "./pace.js";
13
+ import { Clock, Timeline } from "./timeline.js";
14
+ export const ERROR_SCREENSHOT = 'error.png';
15
+ const MAX_CAUSE_LINES = 25;
16
+ const SETTLE_TIMEOUT = 2000;
17
+ /**
18
+ * Removes the output of a previous recording. Other files in the directory stay.
19
+ */
20
+ async function prepareSessionDir(dir) {
21
+ await mkdir(dir, { recursive: true });
22
+ await Promise.all([SESSION_FILE, ERROR_SCREENSHOT, FRAMES_DIR].map((name) => rm(path.join(dir, name), { recursive: true, force: true })));
23
+ }
24
+ /**
25
+ * Page script: a press on a native `<select>` focuses it but does not open its list. The
26
+ * browser draws the list outside the page, so the video cannot show it, and in
27
+ * frame-perfect mode the open list stops the capture. `cast.select` chooses the options.
28
+ */
29
+ function noSelectPopups() {
30
+ addEventListener('mousedown', (event) => {
31
+ const target = event.composedPath()[0];
32
+ const select = target instanceof Element ? target.closest('select') : null;
33
+ if (select && !select.multiple && select.size <= 1) {
34
+ event.preventDefault();
35
+ select.focus();
36
+ }
37
+ }, true);
38
+ }
39
+ /**
40
+ * Frame-perfect capture needs BeginFrame control, which only the headless shell has.
41
+ */
42
+ function checkFramePerfect(options) {
43
+ const { headless, channel, args = [], launchOptions = {} } = options.browser;
44
+ const problem = (headless ?? launchOptions.headless) === false
45
+ ? 'a headed browser'
46
+ : (channel ?? launchOptions.channel)
47
+ ? `the browser channel "${channel ?? launchOptions.channel}"`
48
+ : [...args, ...(launchOptions.args ?? [])].includes('--site-per-process')
49
+ ? 'the --site-per-process flag'
50
+ : undefined;
51
+ if (problem) {
52
+ throw new Error(`capture.mode "frame-perfect" needs the headless shell of Chromium (the default ` +
53
+ `headless browser), and cannot use ${problem}. Remove that option, or use ` +
54
+ `capture.mode "realtime".`);
55
+ }
56
+ }
57
+ function launch(options) {
58
+ const { headless, channel, executablePath, args = [], launchOptions = {} } = options.browser;
59
+ const framePerfect = options.capture.mode === 'frame-perfect';
60
+ return chromium.launch({
61
+ ...launchOptions,
62
+ headless: headless ?? launchOptions.headless ?? true,
63
+ channel: channel ?? launchOptions.channel,
64
+ executablePath: executablePath ?? launchOptions.executablePath,
65
+ // Without this flag, the screencast frames have 1x resolution whatever the context scale.
66
+ args: [
67
+ `--force-device-scale-factor=${options.deviceScaleFactor}`,
68
+ ...(framePerfect ? FRAME_PERFECT_ARGS : []),
69
+ ...(launchOptions.args ?? []),
70
+ ...args,
71
+ ],
72
+ });
73
+ }
74
+ function seconds(ms) {
75
+ return `${(ms / 1000).toFixed(2)} s`;
76
+ }
77
+ function round(value) {
78
+ return Math.round(value * 100) / 100;
79
+ }
80
+ /**
81
+ * Rounds every number in a JSON-like value to 0.01, to keep `session.json` small.
82
+ */
83
+ function roundDeep(value) {
84
+ if (typeof value === 'number') {
85
+ return round(value);
86
+ }
87
+ if (Array.isArray(value)) {
88
+ return value.map(roundDeep);
89
+ }
90
+ if (typeof value === 'object' && value !== null) {
91
+ return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, roundDeep(item)]));
92
+ }
93
+ return value;
94
+ }
95
+ function byTime(a, b) {
96
+ return a.t - b.t;
97
+ }
98
+ /**
99
+ * Builds an actionable error: what failed, the page state, and a screenshot of the page.
100
+ */
101
+ async function failure(page, dir, headline, error, context = []) {
102
+ const cause = (error instanceof Error ? error.message : String(error)).split('\n');
103
+ // The first line is a complete summary: the CLI repeats it at the end of its output.
104
+ let summary = `${headline}: ${cause[0].trim().replace(/[.:]?$/, '.')}`;
105
+ if (page) {
106
+ const file = path.join(dir, ERROR_SCREENSHOT);
107
+ try {
108
+ await page.screenshot({ path: file, timeout: 5000 });
109
+ summary += ` Screenshot: ${file}`;
110
+ }
111
+ catch (screenshotError) {
112
+ summary += ` No screenshot: ${String(screenshotError).split('\n')[0]}`;
113
+ }
114
+ }
115
+ if (cause.length > MAX_CAUSE_LINES) {
116
+ const more = cause.length - MAX_CAUSE_LINES;
117
+ cause.splice(MAX_CAUSE_LINES, more, `... ${more} more lines in error.cause`);
118
+ }
119
+ const lines = [
120
+ summary,
121
+ ...(page ? [`Page URL: ${page.url()}`] : []),
122
+ ...context,
123
+ `Cause: ${cause.join('\n')}`,
124
+ ];
125
+ return new Error(lines.join('\n'), { cause: error });
126
+ }
127
+ /**
128
+ * Records a session: runs `setup` unrecorded, then captures `run`.
129
+ */
130
+ export async function record(options, run, setup) {
131
+ const opts = resolveOptions(options);
132
+ const framePerfect = opts.capture.mode === 'frame-perfect';
133
+ if (framePerfect) {
134
+ checkFramePerfect(opts);
135
+ }
136
+ const dir = opts.sessionDir;
137
+ const createdAt = new Date().toISOString();
138
+ await prepareSessionDir(dir);
139
+ const browser = await launch(opts);
140
+ let pump;
141
+ try {
142
+ const context = await browser.newContext({
143
+ ...opts.browser.contextOptions,
144
+ viewport: opts.viewport,
145
+ deviceScaleFactor: opts.deviceScaleFactor,
146
+ ...(opts.colorScheme ? { colorScheme: opts.colorScheme } : {}),
147
+ });
148
+ const cursorStyle = new CursorStyleProbe();
149
+ cursorStyle.pointer = opts.cursor.start;
150
+ await cursorStyle.install(context);
151
+ await context.addInitScript(noSelectPopups);
152
+ if (framePerfect) {
153
+ await context.addInitScript(idleCallbacksOnTimers);
154
+ }
155
+ const page = await context.newPage();
156
+ if (framePerfect) {
157
+ const { fps, clockLead, format, quality } = opts.capture;
158
+ pump = await FramePump.create(context, page, dir, { fps, clockLead, format, quality });
159
+ // With BeginFrame control the page paints only when it gets frames: page loads, rAF
160
+ // and Playwright actions all wait for them.
161
+ pump.startFreeRun();
162
+ }
163
+ if (opts.url) {
164
+ try {
165
+ await page.goto(opts.url);
166
+ }
167
+ catch (error) {
168
+ throw await failure(page, dir, `Could not open ${opts.url} before the recording`, error);
169
+ }
170
+ }
171
+ if (setup) {
172
+ try {
173
+ await setup({ page });
174
+ }
175
+ catch (error) {
176
+ throw await failure(page, dir, 'The setup function failed (before the recording)', error);
177
+ }
178
+ }
179
+ await page.mouse.move(opts.cursor.start.x, opts.cursor.start.y);
180
+ await cursorStyle.refresh(page);
181
+ // Frame 0 must not show a half-finished entrance animation or hover transition.
182
+ await page.evaluate(settleAnimations, SETTLE_TIMEOUT).catch(() => 0);
183
+ const frameSize = {
184
+ width: Math.round(opts.viewport.width * opts.deviceScaleFactor),
185
+ height: Math.round(opts.viewport.height * opts.deviceScaleFactor),
186
+ };
187
+ let capture;
188
+ let pace;
189
+ if (pump) {
190
+ await pump.start();
191
+ capture = pump;
192
+ pace = new FramePerfectPace(pump);
193
+ }
194
+ else {
195
+ const clock = new Clock();
196
+ const screencast = await FrameCapture.create(context, page, dir);
197
+ clock.start();
198
+ await screencast.start(clock.origin, {
199
+ format: opts.capture.format,
200
+ quality: opts.capture.quality,
201
+ maxWidth: frameSize.width,
202
+ maxHeight: frameSize.height,
203
+ });
204
+ capture = screencast;
205
+ pace = new RealtimePace(clock, () => screencast.refresh());
206
+ }
207
+ const timeline = new Timeline(pace);
208
+ timeline.sample(opts.cursor.start, 0);
209
+ timeline.push({ type: 'cursorStyle', t: 0, style: cursorStyle.style });
210
+ cursorStyle.onChange = (style) => timeline.push({ type: 'cursorStyle', t: pace.now(), style });
211
+ let address = page.url();
212
+ timeline.push({ type: 'url', t: 0, url: address });
213
+ page.on('framenavigated', (frame) => {
214
+ if (frame !== page.mainFrame() || frame.url() === address)
215
+ return;
216
+ address = frame.url();
217
+ timeline.push({ type: 'url', t: pace.now(), url: address });
218
+ });
219
+ const director = new Director({ page, options: opts, timeline, pace, cursorStyle });
220
+ let failed;
221
+ try {
222
+ await pace.sleep(opts.pacing.startDelay);
223
+ await run(director);
224
+ await pace.sleep(opts.pacing.endDelay);
225
+ }
226
+ catch (error) {
227
+ const call = director.failureOf(error);
228
+ const headline = call
229
+ ? `${call.call} failed at ${seconds(call.t)} (record time)`
230
+ : `The run function failed at ${seconds(pace.now())} (record time)`;
231
+ const context = [`Partial session up to the failure: ${dir}`];
232
+ if (director.lastCall) {
233
+ context.push(`Last successful call: ${director.lastCall}`);
234
+ }
235
+ // In frame-perfect mode the screenshot needs frames: the capture stops after it.
236
+ failed = await failure(page, dir, headline, error, context);
237
+ }
238
+ const duration = pace.now();
239
+ cursorStyle.onChange = undefined;
240
+ try {
241
+ await capture.stop(duration);
242
+ if (capture.frames.length === 0 && capture instanceof FrameCapture) {
243
+ const { format, quality } = opts.capture;
244
+ const image = await page.screenshot(format === 'png' ? { type: 'png' } : { type: format, quality });
245
+ await capture.addFrame(image, 0);
246
+ }
247
+ }
248
+ catch (error) {
249
+ // A failed run must still save what it captured and report its own error.
250
+ if (!failed) {
251
+ throw error;
252
+ }
253
+ }
254
+ await browser.close();
255
+ const session = {
256
+ version: 1,
257
+ name: opts.name,
258
+ createdAt,
259
+ ...(opts.url ? { url: opts.url } : {}),
260
+ viewport: opts.viewport,
261
+ deviceScaleFactor: opts.deviceScaleFactor,
262
+ frameSize: capture.frameSize ?? frameSize,
263
+ duration: round(duration),
264
+ frames: roundDeep(capture.frames.map((frame) => ({ ...frame, t: Math.min(frame.t, duration) })).sort(byTime)),
265
+ cursor: roundDeep([...timeline.cursor].sort(byTime)),
266
+ events: roundDeep([...timeline.events].sort(byTime)),
267
+ ...(opts.render ? { render: opts.render } : {}),
268
+ };
269
+ await saveSession(dir, session);
270
+ if (failed) {
271
+ throw failed;
272
+ }
273
+ return { dir, session, render: (renderOptions) => render(dir, renderOptions) };
274
+ }
275
+ finally {
276
+ await pump?.stop().catch(() => { });
277
+ await browser.close().catch(() => { });
278
+ }
279
+ }
280
+ /**
281
+ * Records a screencast definition. `overrides` replace fields of the definition; nested
282
+ * objects such as `browser` or `cursor` merge.
283
+ */
284
+ export async function recordScreencast(definition, overrides) {
285
+ const { run, setup, ...options } = definition;
286
+ return record(mergeOptions(options, overrides), run, setup);
287
+ }
@@ -0,0 +1,48 @@
1
+ import type { Point, Size } from '../types.ts';
2
+ import type { Random } from './random.ts';
3
+ /**
4
+ * Settings that shape the duration of a cursor move.
5
+ */
6
+ export interface MoveTiming {
7
+ speed: number;
8
+ minDuration: number;
9
+ maxDuration: number;
10
+ }
11
+ /**
12
+ * A cursor path: maps progress in [0, 1] to a point.
13
+ */
14
+ export type CursorPath = (progress: number) => Point;
15
+ export declare function clamp(value: number, min: number, max: number): number;
16
+ /**
17
+ * Duration of a cursor move in milliseconds (a Fitts-like log law). Zero below one pixel.
18
+ */
19
+ export declare function moveDuration(distance: number, timing: MoveTiming): number;
20
+ /**
21
+ * Position profile of a move: minimum jerk, time-warped so the peak speed comes at about 39%
22
+ * of the move and the deceleration is longer than the acceleration, as in human reaching.
23
+ */
24
+ export declare function moveEase(progress: number): number;
25
+ /**
26
+ * Position profile of a drag: minimum jerk, time-warped so the start is gentle (peak speed
27
+ * at about 56% of the move). A dragged element can then follow the cursor.
28
+ */
29
+ export declare function dragEase(progress: number): number;
30
+ /**
31
+ * Smooth acceleration and deceleration, for scrolling.
32
+ */
33
+ export declare function easeInOutCubic(progress: number): number;
34
+ /**
35
+ * A slightly curved path from `from` to `to`: a cubic Bezier whose control points are offset
36
+ * perpendicular to the straight line by up to `curvature` times the distance. The bend
37
+ * flips side when it would leave `bounds`. The path starts and ends exactly on the points.
38
+ */
39
+ export declare function cursorPath(from: Point, to: Point, curvature: number, random: Random, bounds?: Size): CursorPath;
40
+ /**
41
+ * Delay before typing the next character: the mean delay with random variation,
42
+ * a bit longer after a space, punctuation or a new line.
43
+ */
44
+ export declare function typingDelay(previous: string, delay: number, variance: number, random: Random): number;
45
+ /**
46
+ * Default duration of a smooth scroll over `distance` pixels.
47
+ */
48
+ export declare function scrollDuration(distance: number): number;