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,193 @@
1
+ import { execFile } from 'node:child_process';
2
+ import { mkdir, writeFile } from 'node:fs/promises';
3
+ import path from 'node:path';
4
+ import { promisify } from 'node:util';
5
+ import { createCanvas, loadImage } from '@napi-rs/canvas';
6
+ import { outputDuration, renderFrame, toOutputTime } from "./render/index.js";
7
+ import { loadSession } from "./session.js";
8
+ const exec = promisify(execFile);
9
+ const MAX_TILES = 64;
10
+ function seconds(ms) {
11
+ return `${(ms / 1000).toFixed(1)}s`;
12
+ }
13
+ function isCut(session, t) {
14
+ return session.events.some((event) => event.type === 'cut' && t >= event.t && t < event.end);
15
+ }
16
+ function describeEvent(event) {
17
+ switch (event.type) {
18
+ case 'mouseDown':
19
+ return `${event.button === 'left' ? 'click' : `${event.button} click`} at (${Math.round(event.x)}, ${Math.round(event.y)})`;
20
+ case 'zoom': {
21
+ if (!event.focus) {
22
+ return 'zoom out';
23
+ }
24
+ const { x, y, width, height } = event.focus;
25
+ const scale = event.scale ? ` scale ${event.scale}` : '';
26
+ return `zoom to (${Math.round(x)}, ${Math.round(y)}, ${Math.round(width)}x${Math.round(height)})${scale}`;
27
+ }
28
+ case 'cut':
29
+ return `cut ${seconds(event.end - event.t)}`;
30
+ case 'speed':
31
+ return `speed x${event.rate} for ${seconds(event.end - event.t)} of record time`;
32
+ case 'caption':
33
+ return `caption "${event.text}" for ${seconds(event.duration)}`;
34
+ case 'spotlight':
35
+ return `spotlight for ${seconds(event.duration)}`;
36
+ case 'marker':
37
+ return `marker "${event.label}"`;
38
+ case 'url':
39
+ return `${event.typing ? 'type address' : event.show ? 'show address' : 'address'} ${event.url}`;
40
+ case 'key':
41
+ return event.kind === 'shortcut' ? `press ${event.key}` : undefined;
42
+ default:
43
+ return undefined;
44
+ }
45
+ }
46
+ /**
47
+ * Returns a text summary of a session: sizes, capture rate and the timeline in output time.
48
+ */
49
+ export function describeSession(session, options) {
50
+ const { viewport, frames, duration } = session;
51
+ const output = outputDuration(session);
52
+ const fps = duration > 0 ? (frames.length / duration) * 1000 : 0;
53
+ const lines = [
54
+ `Session "${session.name}": ${seconds(duration)} recorded, ${seconds(output)} output`,
55
+ `Viewport ${viewport.width}x${viewport.height} @${session.deviceScaleFactor}x, ${frames.length} frames (${fps.toFixed(0)} per second; a frame that does not change is stored once)`,
56
+ 'Timeline (output time):',
57
+ ];
58
+ const at = (t) => seconds(toOutputTime(session, t)).padStart(7);
59
+ const hasActions = session.events.some((event) => event.type === 'action');
60
+ let typed = '';
61
+ let typedAt = 0;
62
+ const flush = () => {
63
+ if (typed) {
64
+ lines.push(` ${seconds(typedAt).padStart(7)} type ${JSON.stringify(typed)}`);
65
+ typed = '';
66
+ }
67
+ };
68
+ for (const event of session.events) {
69
+ if (hasActions) {
70
+ if (event.type === 'action' && !/^(cut|speed)\(/.test(event.call)) {
71
+ const length = toOutputTime(session, event.end) - toOutputTime(session, event.t);
72
+ lines.push(` ${at(event.t)} ${event.call} (${seconds(length)})`);
73
+ }
74
+ else if (event.type === 'cut' || event.type === 'speed') {
75
+ lines.push(` ${at(event.t)} ${describeEvent(event)}`);
76
+ }
77
+ else if (event.type === 'url' && !event.typing && !event.show) {
78
+ lines.push(` ${at(event.t)} ${describeEvent(event)}`);
79
+ }
80
+ continue;
81
+ }
82
+ if (event.type !== 'cut' && event.type !== 'url' && isCut(session, event.t)) {
83
+ continue;
84
+ }
85
+ if (event.type === 'key' && event.kind === 'text') {
86
+ if (!typed) {
87
+ typedAt = toOutputTime(session, event.t);
88
+ }
89
+ typed += event.key.length === 1 ? event.key : event.key === 'Enter' ? '\n' : '';
90
+ continue;
91
+ }
92
+ const text = describeEvent(event);
93
+ if (text) {
94
+ flush();
95
+ lines.push(` ${at(event.t)} ${text}`);
96
+ }
97
+ }
98
+ flush();
99
+ if (options?.range) {
100
+ lines.push(`Range: ${seconds(options.range.start ?? 0)} to ${seconds(options.range.end ?? output)}`);
101
+ }
102
+ return lines.join('\n');
103
+ }
104
+ async function videoDuration(file) {
105
+ const { stdout } = await exec('ffprobe', [
106
+ '-v',
107
+ 'error',
108
+ '-show_entries',
109
+ 'format=duration',
110
+ '-of',
111
+ 'csv=p=0',
112
+ file,
113
+ ]);
114
+ return Number(stdout.trim()) * 1000;
115
+ }
116
+ async function videoFrame(file, time, width) {
117
+ const { stdout } = await exec('ffmpeg', [
118
+ '-v',
119
+ 'error',
120
+ '-ss',
121
+ (time / 1000).toFixed(3),
122
+ '-i',
123
+ file,
124
+ '-frames:v',
125
+ '1',
126
+ '-vf',
127
+ `scale=${width}:-2`,
128
+ '-f',
129
+ 'image2pipe',
130
+ '-c:v',
131
+ 'png',
132
+ '-',
133
+ ], { encoding: 'buffer', maxBuffer: 64 * 1024 * 1024 });
134
+ return stdout;
135
+ }
136
+ /**
137
+ * Writes a grid of stills with time labels, from a session directory or a video file.
138
+ */
139
+ export async function contactSheet(source, options) {
140
+ const isVideo = /\.(mp4|webm|gif|mov|mkv)$/i.test(source);
141
+ const tileWidth = options.tileWidth ?? 480;
142
+ const columns = options.columns ?? 4;
143
+ let duration;
144
+ let grab;
145
+ if (isVideo) {
146
+ duration = await videoDuration(source);
147
+ grab = (time) => videoFrame(source, time, tileWidth);
148
+ }
149
+ else {
150
+ const session = await loadSession(source);
151
+ duration = outputDuration(session);
152
+ const size = options.render?.size ?? session.render?.size ?? { width: 1920, height: 1080 };
153
+ const tileSize = {
154
+ width: tileWidth,
155
+ height: Math.round((tileWidth * size.height) / size.width / 2) * 2,
156
+ };
157
+ grab = (time) => renderFrame(source, time, { ...options.render, size: tileSize });
158
+ }
159
+ const from = Math.max(0, options.from ?? 0);
160
+ const to = Math.min(duration, options.to ?? duration);
161
+ const every = options.every ?? Math.max(500, Math.ceil((to - from) / 16 / 500) * 500);
162
+ const times = [];
163
+ for (let time = from; time < to && times.length < MAX_TILES; time += every) {
164
+ times.push(time);
165
+ }
166
+ if (times.length === 0) {
167
+ throw new Error(`Nothing to show between ${seconds(from)} and ${seconds(to)}.`);
168
+ }
169
+ const images = [];
170
+ for (const time of times) {
171
+ images.push(await loadImage(await grab(time)));
172
+ }
173
+ const tileHeight = Math.round((tileWidth * images[0].height) / images[0].width);
174
+ const gap = 8;
175
+ const label = 24;
176
+ const rows = Math.ceil(images.length / columns);
177
+ const canvas = createCanvas(columns * tileWidth + (columns + 1) * gap, rows * (tileHeight + label) + (rows + 1) * gap);
178
+ const context = canvas.getContext('2d');
179
+ context.fillStyle = '#111';
180
+ context.fillRect(0, 0, canvas.width, canvas.height);
181
+ context.font = '600 15px Inter, sans-serif';
182
+ context.textBaseline = 'middle';
183
+ context.fillStyle = '#fff';
184
+ images.forEach((image, index) => {
185
+ const x = gap + (index % columns) * (tileWidth + gap);
186
+ const y = gap + Math.floor(index / columns) * (tileHeight + label + gap);
187
+ context.fillText(seconds(times[index]), x + 2, y + label / 2);
188
+ context.drawImage(image, x, y + label, tileWidth, tileHeight);
189
+ });
190
+ await mkdir(path.dirname(path.resolve(options.out)), { recursive: true });
191
+ await writeFile(options.out, canvas.toBuffer('image/png'));
192
+ return { out: options.out, tiles: images.length, every };
193
+ }
@@ -0,0 +1,7 @@
1
+ /**
2
+ * In-page: waits until the finite CSS animations, transitions and Web Animations of the
3
+ * document have finished, at most `timeout` ms. Infinite and paused animations do not count.
4
+ * Returns how many finite animations still run. Playwright serializes this function into
5
+ * the page: it must be self-contained.
6
+ */
7
+ export declare function settleAnimations(timeout: number): Promise<number>;
@@ -0,0 +1,34 @@
1
+ /**
2
+ * In-page: waits until the finite CSS animations, transitions and Web Animations of the
3
+ * document have finished, at most `timeout` ms. Infinite and paused animations do not count.
4
+ * Returns how many finite animations still run. Playwright serializes this function into
5
+ * the page: it must be self-contained.
6
+ */
7
+ export async function settleAnimations(timeout) {
8
+ const deadline = performance.now() + timeout;
9
+ const finite = () => document.getAnimations().filter((animation) => {
10
+ if (animation.playState !== 'running' && !animation.pending) {
11
+ return false;
12
+ }
13
+ const end = animation.effect?.getComputedTiming().endTime;
14
+ return typeof end === 'number' && Number.isFinite(end);
15
+ });
16
+ let running = finite();
17
+ // An animation can start another one when it ends, so look again until none is left.
18
+ while (running.length > 0) {
19
+ const left = deadline - performance.now();
20
+ if (left <= 0) {
21
+ break;
22
+ }
23
+ await Promise.race([
24
+ Promise.all(running.map((animation) => animation.finished.catch(() => { }))),
25
+ new Promise((resolve) => setTimeout(resolve, left)),
26
+ ]);
27
+ await new Promise((resolve) => {
28
+ requestAnimationFrame(resolve);
29
+ setTimeout(resolve, 50);
30
+ });
31
+ running = finite();
32
+ }
33
+ return running.length;
34
+ }
@@ -0,0 +1,85 @@
1
+ import type { BrowserContext, Page } from 'playwright';
2
+ import type { FrameRef, Size } from '../types.ts';
3
+ export declare const FRAMES_DIR = "frames";
4
+ /**
5
+ * Screencast settings. `maxWidth` and `maxHeight` are in device pixels.
6
+ */
7
+ export interface CaptureSettings {
8
+ format: 'jpeg' | 'png';
9
+ quality: number;
10
+ maxWidth: number;
11
+ maxHeight: number;
12
+ }
13
+ /**
14
+ * Reads the pixel size from the header of a JPEG or PNG image.
15
+ */
16
+ export declare function imageSize(data: Uint8Array): Size | undefined;
17
+ /**
18
+ * The frames of a recording, and the capture that makes them.
19
+ */
20
+ export interface Capture {
21
+ readonly frames: FrameRef[];
22
+ readonly frameSize?: Size;
23
+ /**
24
+ * Stops at record time `end` and waits until every frame is on disk.
25
+ */
26
+ stop(end?: number): Promise<FrameRef[]>;
27
+ }
28
+ /**
29
+ * Writes frame images to `<dir>/frames/` without blocking the caller.
30
+ */
31
+ export declare class FrameWriter {
32
+ readonly frames: FrameRef[];
33
+ frameSize?: Size;
34
+ private readonly dir;
35
+ private readonly extension;
36
+ private readonly writes;
37
+ private writeError?;
38
+ constructor(dir: string, format: 'jpeg' | 'png');
39
+ add(data: Buffer, t: number): void;
40
+ flush(): Promise<void>;
41
+ }
42
+ /**
43
+ * Captures screencast frames over CDP as the page paints, in real time.
44
+ * Frame times use the record clock whose epoch origin is given to `start()`.
45
+ */
46
+ export declare class FrameCapture implements Capture {
47
+ private readonly cdp;
48
+ private readonly dir;
49
+ private writer;
50
+ private settings?;
51
+ private origin;
52
+ private end;
53
+ private reachedEnd?;
54
+ private stopped;
55
+ private quietTimer?;
56
+ /**
57
+ * A forced capture makes the screencast send one frame too: that frame, when it comes
58
+ * before this real time, starts no quiet period.
59
+ */
60
+ private ownFrameUntil;
61
+ private constructor();
62
+ static create(context: BrowserContext, page: Page, dir: string): Promise<FrameCapture>;
63
+ get frames(): FrameRef[];
64
+ get frameSize(): Size | undefined;
65
+ /**
66
+ * Starts the screencast. `origin` is the epoch time (ms) of record time 0.
67
+ */
68
+ start(origin: number, settings: CaptureSettings): Promise<void>;
69
+ /**
70
+ * Stops the screencast at record time `end` and waits until every frame is on disk.
71
+ * Frames arrive some time after they are made, more so on a loaded machine: it waits up
72
+ * to `grace` ms for a frame made after `end`, which proves that no earlier frame is late.
73
+ */
74
+ stop(end?: number, grace?: number): Promise<FrameRef[]>;
75
+ /**
76
+ * Writes an image as the frame at record time `t`. Used when the screencast gave no frame.
77
+ */
78
+ addFrame(data: Buffer, t: number): Promise<void>;
79
+ /**
80
+ * Captures the page now and stores it as a frame, at most at record time `end`. The
81
+ * screencast sends frames only on damage and can drop the last one of a change.
82
+ */
83
+ refresh(end?: number): Promise<number | undefined>;
84
+ private onFrame;
85
+ }
@@ -0,0 +1,202 @@
1
+ import { mkdir, writeFile } from 'node:fs/promises';
2
+ import path from 'node:path';
3
+ import { epochNow } from "./timeline.js";
4
+ export const FRAMES_DIR = 'frames';
5
+ /**
6
+ * Quiet time, in ms, after the last screencast frame before a forced capture.
7
+ */
8
+ const QUIET_MS = 200;
9
+ const SOF_MARKERS = new Set([
10
+ 0xc0, 0xc1, 0xc2, 0xc3, 0xc5, 0xc6, 0xc7, 0xc9, 0xca, 0xcb, 0xcd, 0xce, 0xcf,
11
+ ]);
12
+ /**
13
+ * Reads the pixel size from the header of a JPEG or PNG image.
14
+ */
15
+ export function imageSize(data) {
16
+ const view = new DataView(data.buffer, data.byteOffset, data.byteLength);
17
+ if (data[0] === 0x89 && data[1] === 0x50 && data.length >= 24) {
18
+ return { width: view.getUint32(16), height: view.getUint32(20) };
19
+ }
20
+ if (data[0] !== 0xff || data[1] !== 0xd8) {
21
+ return undefined;
22
+ }
23
+ let i = 2;
24
+ while (i + 9 < data.length) {
25
+ if (data[i] !== 0xff) {
26
+ return undefined;
27
+ }
28
+ const marker = data[i + 1];
29
+ if (marker === 0xff) {
30
+ i++;
31
+ continue;
32
+ }
33
+ if (SOF_MARKERS.has(marker)) {
34
+ return { width: view.getUint16(i + 7), height: view.getUint16(i + 5) };
35
+ }
36
+ i += 2 + view.getUint16(i + 2);
37
+ }
38
+ return undefined;
39
+ }
40
+ /**
41
+ * Writes frame images to `<dir>/frames/` without blocking the caller.
42
+ */
43
+ export class FrameWriter {
44
+ frames = [];
45
+ frameSize;
46
+ dir;
47
+ extension;
48
+ writes = new Set();
49
+ writeError;
50
+ constructor(dir, format) {
51
+ this.dir = dir;
52
+ this.extension = format === 'png' ? 'png' : 'jpg';
53
+ }
54
+ add(data, t) {
55
+ if (this.frames.length === 0) {
56
+ this.frameSize = imageSize(data);
57
+ }
58
+ const file = `${FRAMES_DIR}/${String(this.frames.length + 1).padStart(6, '0')}.${this.extension}`;
59
+ this.frames.push({ t, file });
60
+ const write = writeFile(path.join(this.dir, file), data)
61
+ .catch((error) => {
62
+ this.writeError ??= error;
63
+ })
64
+ .finally(() => this.writes.delete(write));
65
+ this.writes.add(write);
66
+ }
67
+ async flush() {
68
+ await Promise.all(this.writes);
69
+ if (this.writeError) {
70
+ throw new Error(`Could not write a frame to "${this.dir}": ${String(this.writeError)}`, {
71
+ cause: this.writeError,
72
+ });
73
+ }
74
+ }
75
+ }
76
+ /**
77
+ * Captures screencast frames over CDP as the page paints, in real time.
78
+ * Frame times use the record clock whose epoch origin is given to `start()`.
79
+ */
80
+ export class FrameCapture {
81
+ cdp;
82
+ dir;
83
+ writer;
84
+ settings;
85
+ origin = 0;
86
+ end = Infinity;
87
+ reachedEnd;
88
+ stopped = false;
89
+ quietTimer;
90
+ /**
91
+ * A forced capture makes the screencast send one frame too: that frame, when it comes
92
+ * before this real time, starts no quiet period.
93
+ */
94
+ ownFrameUntil = 0;
95
+ constructor(cdp, dir) {
96
+ this.cdp = cdp;
97
+ this.dir = dir;
98
+ this.writer = new FrameWriter(dir, 'jpeg');
99
+ }
100
+ static async create(context, page, dir) {
101
+ await mkdir(path.join(dir, FRAMES_DIR), { recursive: true });
102
+ return new FrameCapture(await context.newCDPSession(page), dir);
103
+ }
104
+ get frames() {
105
+ return this.writer.frames;
106
+ }
107
+ get frameSize() {
108
+ return this.writer.frameSize;
109
+ }
110
+ /**
111
+ * Starts the screencast. `origin` is the epoch time (ms) of record time 0.
112
+ */
113
+ async start(origin, settings) {
114
+ this.origin = origin;
115
+ this.settings = settings;
116
+ this.writer = new FrameWriter(this.dir, settings.format);
117
+ this.cdp.on('Page.screencastFrame', this.onFrame);
118
+ await this.cdp.send('Page.startScreencast', {
119
+ format: settings.format,
120
+ quality: settings.quality,
121
+ everyNthFrame: 1,
122
+ maxWidth: settings.maxWidth,
123
+ maxHeight: settings.maxHeight,
124
+ });
125
+ }
126
+ /**
127
+ * Stops the screencast at record time `end` and waits until every frame is on disk.
128
+ * Frames arrive some time after they are made, more so on a loaded machine: it waits up
129
+ * to `grace` ms for a frame made after `end`, which proves that no earlier frame is late.
130
+ */
131
+ async stop(end = Infinity, grace = 300) {
132
+ await this.refresh(end);
133
+ this.end = end;
134
+ if (Number.isFinite(end)) {
135
+ await new Promise((resolve) => {
136
+ this.reachedEnd = resolve;
137
+ setTimeout(resolve, grace);
138
+ });
139
+ }
140
+ this.stopped = true;
141
+ clearTimeout(this.quietTimer);
142
+ this.cdp.off('Page.screencastFrame', this.onFrame);
143
+ await this.cdp.send('Page.stopScreencast').catch(() => { });
144
+ await this.cdp.detach().catch(() => { });
145
+ await this.writer.flush();
146
+ return this.frames;
147
+ }
148
+ /**
149
+ * Writes an image as the frame at record time `t`. Used when the screencast gave no frame.
150
+ */
151
+ async addFrame(data, t) {
152
+ this.writer.add(data, t);
153
+ await this.writer.flush();
154
+ }
155
+ /**
156
+ * Captures the page now and stores it as a frame, at most at record time `end`. The
157
+ * screencast sends frames only on damage and can drop the last one of a change.
158
+ */
159
+ async refresh(end = Infinity) {
160
+ clearTimeout(this.quietTimer);
161
+ if (this.stopped || !this.settings) {
162
+ return undefined;
163
+ }
164
+ const t = Math.min(epochNow() - this.origin, end);
165
+ const { format, quality } = this.settings;
166
+ this.ownFrameUntil = Infinity;
167
+ try {
168
+ const { data } = await this.cdp.send('Page.captureScreenshot', format === 'png' ? { format } : { format, quality });
169
+ if (!this.stopped) {
170
+ this.writer.add(Buffer.from(data, 'base64'), this.frames.length === 0 ? 0 : t);
171
+ }
172
+ }
173
+ catch {
174
+ // The page can be between documents: the next frame shows it.
175
+ }
176
+ if (this.ownFrameUntil === Infinity) {
177
+ this.ownFrameUntil = performance.now() + QUIET_MS;
178
+ }
179
+ return t;
180
+ }
181
+ onFrame = (frame) => {
182
+ this.cdp.send('Page.screencastFrameAck', { sessionId: frame.sessionId }).catch(() => { });
183
+ if (this.stopped) {
184
+ return;
185
+ }
186
+ const stamp = frame.metadata.timestamp;
187
+ const epoch = stamp === undefined ? performance.timeOrigin + performance.now() : stamp * 1000;
188
+ const t = Math.max(0, epoch - this.origin);
189
+ if (t > this.end && this.frames.length > 0) {
190
+ this.reachedEnd?.();
191
+ return;
192
+ }
193
+ // The first frame is the page at the start: it gets t = 0.
194
+ this.writer.add(Buffer.from(frame.data, 'base64'), this.frames.length === 0 ? 0 : t);
195
+ if (performance.now() < this.ownFrameUntil) {
196
+ this.ownFrameUntil = 0;
197
+ return;
198
+ }
199
+ clearTimeout(this.quietTimer);
200
+ this.quietTimer = setTimeout(() => void this.refresh(), QUIET_MS);
201
+ };
202
+ }
@@ -0,0 +1,142 @@
1
+ import type { Locator, Page } from 'playwright';
2
+ import type { CaptionOptions, Cast, ClickOptions, DragOptions, GotoOptions, MoveOptions, ScrollOptions, ScrollToOptions, ShowUrlOptions, Size, SpotlightOptions, Target, TypeOptions, ZoomToOptions } from '../types.ts';
3
+ import type { CursorStyleProbe } from './cursor-style.ts';
4
+ import { type ResolvedOptions } from './defaults.ts';
5
+ import type { Pace } from './pace.ts';
6
+ import type { Timeline } from './timeline.ts';
7
+ /**
8
+ * The Cast call that threw an error, and the record time of the failure.
9
+ */
10
+ export interface CallFailure {
11
+ call: string;
12
+ t: number;
13
+ }
14
+ export interface DirectorContext {
15
+ page: Page;
16
+ options: ResolvedOptions;
17
+ timeline: Timeline;
18
+ pace: Pace;
19
+ cursorStyle: CursorStyleProbe;
20
+ }
21
+ /**
22
+ * Short description of a target, for error messages and the action log.
23
+ */
24
+ export declare function describeTarget(target: Target): string;
25
+ /**
26
+ * The Cast implementation: drives the page with human-like input and logs the timeline.
27
+ */
28
+ export declare class Director implements Cast {
29
+ readonly page: Page;
30
+ readonly viewport: Size;
31
+ /**
32
+ * The last Cast call that succeeded, for error messages.
33
+ */
34
+ lastCall?: string;
35
+ private readonly options;
36
+ private readonly timeline;
37
+ private readonly pace;
38
+ /**
39
+ * Default time limit for Playwright waits, which run in real time.
40
+ */
41
+ private readonly timeout;
42
+ private readonly cursorStyle;
43
+ private readonly motionRandom;
44
+ private readonly typingRandom;
45
+ private readonly failures;
46
+ private position;
47
+ private region?;
48
+ constructor(context: DirectorContext);
49
+ /**
50
+ * The innermost Cast call that threw `error`, if a Cast call threw it.
51
+ */
52
+ failureOf(error: unknown): CallFailure | undefined;
53
+ moveTo(target: Target, options?: MoveOptions): Promise<void>;
54
+ click(target: Target, options?: ClickOptions): Promise<void>;
55
+ dblclick(target: Target, options?: ClickOptions): Promise<void>;
56
+ rightClick(target: Target, options?: ClickOptions): Promise<void>;
57
+ hover(target: Target, options?: MoveOptions & {
58
+ hold?: number;
59
+ }): Promise<void>;
60
+ drag(from: Target, to: Target, options?: DragOptions): Promise<void>;
61
+ select(target: Locator | string, values: string | string[], options?: ClickOptions): Promise<void>;
62
+ scroll(delta: {
63
+ x?: number;
64
+ y?: number;
65
+ }, options?: ScrollOptions): Promise<void>;
66
+ scrollTo(target: Target, options?: ScrollToOptions): Promise<void>;
67
+ type(text: string, options?: TypeOptions): Promise<void>;
68
+ press(keys: string, options?: {
69
+ hold?: number;
70
+ }): Promise<void>;
71
+ zoomTo(target: Target, options?: ZoomToOptions): Promise<void>;
72
+ zoom(level: string | number, options?: Omit<ZoomToOptions, 'scale' | 'level' | 'padding'>): Promise<void>;
73
+ zoomOut(options?: Omit<ZoomToOptions, 'scale' | 'level' | 'padding' | 'follow'>): Promise<void>;
74
+ wait(ms: number): Promise<void>;
75
+ cut<T>(fn: () => Promise<T>): Promise<T>;
76
+ speed<T>(rate: number, fn: () => Promise<T>): Promise<T>;
77
+ private get browserFrame();
78
+ showUrl(options?: ShowUrlOptions): Promise<void>;
79
+ goto(url: string, options?: GotoOptions): Promise<void>;
80
+ caption(text: string, options?: CaptionOptions): Promise<void>;
81
+ spotlight(target: Target, options?: SpotlightOptions): Promise<void>;
82
+ marker(label: string): void;
83
+ /**
84
+ * Runs one Cast call. Remembers the innermost failing call for the error message.
85
+ */
86
+ private step;
87
+ private push;
88
+ private inRegion;
89
+ private locatorOf;
90
+ private resolve;
91
+ private resolveRect;
92
+ /**
93
+ * A point inside `box`: at `position` (fractions of the size), or near the center of the
94
+ * visible part with a small random offset.
95
+ */
96
+ private pointIn;
97
+ /**
98
+ * Waits until the element is visible, scrolls it into view, and returns its bounding box
99
+ * once two reads in a row give the same box.
100
+ */
101
+ private stableBox;
102
+ private clickTarget;
103
+ /**
104
+ * Before the press: moves the cursor again when the element moved after the cursor
105
+ * arrived, then makes sure that the click reaches it. One in-page check covers the usual
106
+ * case; Playwright's trial click, with its waits and error messages, runs only when that
107
+ * check fails, and for elements in a child frame.
108
+ */
109
+ private prepareClick;
110
+ /**
111
+ * Moves the cursor again when the element moved after the cursor arrived.
112
+ * Keeps the same relative position inside the element. Returns the current box.
113
+ */
114
+ private followTarget;
115
+ /**
116
+ * Runs the Playwright actionability checks at the exact cursor point, without clicking.
117
+ */
118
+ private checkActionable;
119
+ private pressButton;
120
+ private mouseDown;
121
+ private mouseUp;
122
+ /**
123
+ * Moves the cursor along a human-like path, sampled every few milliseconds.
124
+ */
125
+ private moveCursor;
126
+ /**
127
+ * Scrolls by wheel events at the cursor, with an ease-in-out over `duration`.
128
+ */
129
+ private wheel;
130
+ /**
131
+ * Brings an element into view. Smooth: wheel steps over each scroll container, outer
132
+ * to inner, with the cursor moved over the container first. Falls back to an instant
133
+ * scroll when the wheel does not reach the element. Returns the last plan when the
134
+ * element is in view after a smooth scroll: it holds the element box.
135
+ */
136
+ private bringIntoView;
137
+ /**
138
+ * After Enter in `auto` indent mode: removes the indentation that the editor added and
139
+ * that `wanted` does not have. Returns how many characters of `wanted` are already there.
140
+ */
141
+ private alignIndent;
142
+ }