@revoengine/cli 1.0.38 → 2.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (47) hide show
  1. package/CHANGELOG.md +33 -0
  2. package/README.md +22 -10
  3. package/dist/src/argument-contract.js +5 -5
  4. package/dist/src/automation-contract.generated.d.ts +6 -30
  5. package/dist/src/automation-contract.generated.js +6 -30
  6. package/dist/src/client.d.ts +2 -2
  7. package/dist/src/client.js +4 -14
  8. package/dist/src/commands/component.js +16 -0
  9. package/dist/src/commands/database-tables.js +1 -1
  10. package/dist/src/commands/emulate.js +67 -74
  11. package/dist/src/commands/terminal-browser-human-input.d.ts +28 -0
  12. package/dist/src/commands/terminal-browser-human-input.js +56 -7
  13. package/dist/src/commands/terminal-browser-live-protocol.d.ts +13 -1
  14. package/dist/src/commands/terminal-browser-live-protocol.js +20 -4
  15. package/dist/src/commands/terminal-browser-live-transport.d.ts +2 -0
  16. package/dist/src/commands/terminal-browser-live-transport.js +21 -4
  17. package/dist/src/commands/terminal-browser-live.d.ts +36 -1
  18. package/dist/src/commands/terminal-browser-live.js +435 -106
  19. package/dist/src/commands/terminal-browser-observation.d.ts +1 -1
  20. package/dist/src/commands/terminal-browser-observation.js +10 -1
  21. package/dist/src/commands/terminal-browser-page-input.d.ts +1 -0
  22. package/dist/src/commands/terminal-browser-page-input.js +20 -0
  23. package/dist/src/commands/terminal-browser-profile-sync.d.ts +5 -1
  24. package/dist/src/commands/terminal-browser-profile-sync.js +13 -2
  25. package/dist/src/commands/terminal-browser-profile-sync.protocol.d.ts +2 -0
  26. package/dist/src/commands/terminal-browser-recording.d.ts +6 -3
  27. package/dist/src/commands/terminal-browser-recording.js +45 -15
  28. package/dist/src/commands/terminal-browser.d.ts +17 -0
  29. package/dist/src/commands/terminal-browser.js +318 -111
  30. package/dist/src/commands/terminal-operational-log.js +2 -1
  31. package/dist/src/commands/terminal-output-buffer.d.ts +2 -0
  32. package/dist/src/commands/terminal-output-buffer.js +6 -0
  33. package/dist/src/commands/terminal-reconnect-grace.d.ts +1 -0
  34. package/dist/src/commands/terminal-reconnect-grace.js +1 -0
  35. package/dist/src/commands/terminal-sandbox.js +22 -6
  36. package/dist/src/commands/terminal.js +136 -40
  37. package/dist/src/endpoint-emulator.d.ts +16 -13
  38. package/dist/src/endpoint-emulator.js +26 -35
  39. package/dist/src/project.js +1 -0
  40. package/dist/src/request-contract.d.ts +2 -0
  41. package/dist/src/request-contract.js +11 -1
  42. package/dist/src/resource-syncs/database-table-sync.d.ts +2 -1
  43. package/dist/src/resource-syncs/database-table-sync.js +60 -23
  44. package/dist/src/sync-omit.js +1 -1
  45. package/dist/src/types.d.ts +0 -3
  46. package/dist/src/ui.js +2 -2
  47. package/package.json +1 -1
@@ -1,8 +1,8 @@
1
1
  import fs from 'node:fs';
2
2
  import path from 'node:path';
3
3
  import { randomUUID } from 'node:crypto';
4
- import { applyPageInteraction, pageHasSecretFocus, releasePageInput } from "./terminal-browser-page-input.js";
5
- import { decryptBrowserHumanInput } from "./terminal-browser-human-input.js";
4
+ import { applyPageInteraction, pageHasSecretFocus, readPageSelection, releasePageInput } from "./terminal-browser-page-input.js";
5
+ import { decryptBrowserHumanInput, decryptBrowserPointer, decryptClipboardRequest, encryptBrowserSelection } from "./terminal-browser-human-input.js";
6
6
  import { BROWSER_LIVE_MAX_FRAME_BYTES, validBrowserLiveControl, safeBrowserLiveState } from "./terminal-browser-live-protocol.js";
7
7
  /** Reads SOF JPEG dimensions without decoding or allocating an image. */
8
8
  export function jpegDimensions(jpeg) {
@@ -33,6 +33,9 @@ export function browserAuthPage(value) {
33
33
  }
34
34
  }
35
35
  export class BrowserLiveHandle {
36
+ pointer;
37
+ pointerExpiry;
38
+ pointerStarts = new Map();
36
39
  baseOptions;
37
40
  viewerOptions;
38
41
  get options() { return this.viewerOptions ?? this.baseOptions; }
@@ -44,13 +47,17 @@ export class BrowserLiveHandle {
44
47
  this.baseOptions = { ...options, sessionOwned: true };
45
48
  }
46
49
  attachViewer(options) {
47
- if (!this.sessionOwned || this.closed || ['actorUserId', 'threadId', 'agentTerminalWorkspaceId', 'connectionId', 'browserSessionId']
48
- .some(key => options[key] !== this.baseOptions[key]) || !options.isAuthorized())
50
+ if (!this.sessionOwned || this.closed || ['actorUserId', 'threadId', 'agentTerminalWorkspaceId', 'browserSessionId']
51
+ .some(key => options[key] !== this.baseOptions[key]) || !options.isAuthorized()
52
+ || options.connectionId !== this.baseOptions.connectionId && this.baseOptions.isAuthorized())
49
53
  throw new Error('browser_live_scope_invalid');
50
54
  this.viewerOptions = options;
55
+ this.stateFingerprint = '';
56
+ this.lastStatePoll = 0;
51
57
  }
52
58
  async resumeRecordingIfPublic() {
53
- if (!this.sessionOwned || this.closed || this.mode !== 'observe' || this.recordingMode === 'off')
59
+ if (!this.sessionOwned || this.closed || this.mode !== 'observe' || this.recordingMode === 'off'
60
+ || !this.baseOptions.isAuthorized())
54
61
  return;
55
62
  const page = this.port.active().page;
56
63
  if (browserAuthPage(page.url()) || await pageHasSecretFocus(page))
@@ -63,7 +70,10 @@ export class BrowserLiveHandle {
63
70
  }
64
71
  port;
65
72
  page;
73
+ preview;
66
74
  segment;
75
+ recordingStop;
76
+ pendingCheckpoint;
67
77
  recordingMode = 'off';
68
78
  fps = 15;
69
79
  settingsApplied = false;
@@ -93,15 +103,16 @@ export class BrowserLiveHandle {
93
103
  get mode() { return this.port.control.mode; }
94
104
  get controlEpoch() { return this.port.control.epoch; }
95
105
  get private() { return this.port.control.private; }
96
- assertAuthorized() {
97
- if (this.closed || !this.baseOptions.isAuthorized() || !this.port.authorized())
106
+ assertAuthorized(options = this.options) {
107
+ if (this.closed || this.options !== options || !options.isAuthorized() || !this.port.authorized())
98
108
  throw new Error('browser_live_scope_expired');
99
109
  }
100
110
  async state() {
101
- this.assertAuthorized();
111
+ const options = this.options;
112
+ this.assertAuthorized(options);
102
113
  const state = await this.port.state();
103
- const preferences = this.options.profilePreferences;
104
- const owner = this.options.profileOwner;
114
+ const preferences = options.profilePreferences;
115
+ const owner = options.profileOwner;
105
116
  let profiles = [];
106
117
  if (preferences && owner) {
107
118
  const pending = this.profileChoicesPending || preferences.choicesAsync(owner, { selectedName: state.browserProfile?.persistent ? state.browserProfile.name : undefined });
@@ -118,11 +129,15 @@ export class BrowserLiveHandle {
118
129
  const profile = preferences && owner ? selected?.persistent
119
130
  ? profiles.find(choice => choice.persistent && choice.name === selected.name) || { ...selected, default: false }
120
131
  : profiles[0] : selected;
121
- this.assertAuthorized();
132
+ this.assertAuthorized(options);
122
133
  return { ...state, profile, profiles, private: this.private, frameSequence: this.sequence, recording: { mode: this.recordingMode },
123
134
  settings: { fps: this.fps, ...this.port.active().page.viewportSize() },
124
- recordingState: { status: this.segment ? 'recording' : this.recordingMode === 'off' ? 'off' : 'paused',
125
- elapsedMs: this.elapsedMs + (this.segmentStartedAt === undefined ? 0 : Date.now() - this.segmentStartedAt) } };
135
+ recordingState: this.recordingState() };
136
+ }
137
+ recordingState() {
138
+ return { status: this.segment ? 'recording' : this.recordingMode === 'off' ? 'off' : 'paused',
139
+ elapsedMs: this.elapsedMs + (this.segmentStartedAt === undefined ? 0 : Date.now() - this.segmentStartedAt),
140
+ checkpoint: this.pendingCheckpoint ?? this.baseOptions.recordingCheckpoint?.() };
126
141
  }
127
142
  async start() {
128
143
  this.assertAuthorized();
@@ -141,20 +156,30 @@ export class BrowserLiveHandle {
141
156
  // Website-created popups and model tab switches need no model call to refresh the active stream.
142
157
  if (this.poll)
143
158
  clearInterval(this.poll);
144
- this.poll = setInterval(() => {
159
+ const poll = setInterval(() => {
160
+ if (this.syncing || this.mode === 'blocked')
161
+ return;
162
+ const options = this.options;
145
163
  void this.sync().catch(error => {
164
+ if (this.poll !== poll || this.closed || this.stopped || this.options !== options
165
+ || this.sessionOwned && !this.viewerOptions && !this.baseOptions.isAuthorized())
166
+ return;
167
+ clearInterval(poll);
168
+ this.poll = undefined;
146
169
  const known = ['browser_profile_busy', 'browser_profile_changed', 'browser_profile_corrupt',
147
170
  'browser_profile_keystore_unavailable', 'browser_observation_unavailable', 'browser_observation_stale',
148
171
  'browser_live_scope_expired', 'browser_recording_network_required', 'browser_recording_path_invalid'];
149
172
  const code = error instanceof Error && known.includes(error.message) ? error.message : 'browser_live_capture_failed';
173
+ const epoch = this.controlEpoch;
174
+ this.block();
150
175
  try {
151
- this.options.onFailure?.(code, this.controlEpoch);
176
+ this.options.onFailure?.(code, epoch);
152
177
  }
153
178
  catch { /* Diagnostics cannot bypass the local fence. */ }
154
- this.block();
155
179
  });
156
180
  }, 200);
157
- this.poll.unref();
181
+ this.poll = poll;
182
+ poll.unref();
158
183
  }
159
184
  captureQueue = Promise.resolve();
160
185
  capture(work) {
@@ -166,27 +191,43 @@ export class BrowserLiveHandle {
166
191
  async stopCaptureInner() {
167
192
  this.cancelTrailingFrame();
168
193
  const page = this.page;
169
- const segment = this.segment;
170
194
  this.page = undefined;
171
- this.segment = undefined;
172
195
  this.scroll = undefined;
173
196
  this.generation++;
174
- if (page && !page.isClosed())
175
- await page.screencast.stop().catch(() => undefined);
197
+ if (this.sessionOwned)
198
+ await this.stopPreview();
199
+ await this.finishRecording(page);
200
+ }
201
+ stopEncoder(page) {
202
+ return this.recordingStop ??= page && !page.isClosed()
203
+ ? page.screencast.stop().then(() => true, () => false) : Promise.resolve(false);
204
+ }
205
+ async finishRecording(page, checkpoint = false) {
206
+ const segment = this.segment;
207
+ this.segment = undefined;
208
+ const finalized = (segment || !this.sessionOwned) ? await this.stopEncoder(page) : false;
209
+ this.recordingStop = undefined;
176
210
  if (this.segmentStartedAt !== undefined) {
177
211
  this.elapsedMs += Date.now() - this.segmentStartedAt;
178
212
  this.segmentStartedAt = undefined;
179
213
  }
180
- if (segment) {
181
- const file = fs.lstatSync(segment.path, { throwIfNoEntry: false });
182
- if (file?.isFile() && !file.isSymbolicLink() && file.size > 0 && file.size <= 256 * 1024 * 1024) {
183
- fs.chmodSync(segment.path, 0o600);
184
- if ((this.sessionOwned ? this.baseOptions : this.options).onRecording({ ...segment, size: file.size }) === false)
185
- this.recordingMode = 'off';
186
- }
187
- else if (file && file.size === 0)
188
- fs.unlinkSync(segment.path);
214
+ if (!segment)
215
+ return false;
216
+ const file = fs.lstatSync(segment.path, { throwIfNoEntry: false });
217
+ if (finalized && file?.isFile() && !file.isSymbolicLink() && file.size > 0 && file.size <= 256 * 1024 * 1024) {
218
+ fs.chmodSync(segment.path, 0o600);
219
+ const options = this.sessionOwned ? this.baseOptions : this.options;
220
+ const { authorized, ...recording } = segment;
221
+ if (this.sessionOwned && (!authorized() || !options.isAuthorized()))
222
+ return false;
223
+ const accepted = options.onRecording({ ...recording, size: file.size, ...(checkpoint ? { checkpoint } : {}) }) !== false;
224
+ if (!accepted && !checkpoint)
225
+ this.recordingMode = 'off';
226
+ return accepted;
189
227
  }
228
+ if (file?.isFile() && file.size === 0)
229
+ fs.unlinkSync(segment.path);
230
+ return false;
190
231
  }
191
232
  async pauseRecording(restartPreview = true) {
192
233
  if (!this.segment && this.recordingMode === 'off')
@@ -196,8 +237,8 @@ export class BrowserLiveHandle {
196
237
  if (!restartPreview) {
197
238
  // Navigation routes must not wait for a queued DOM evaluation which itself
198
239
  // waits for navigation. Stop native media first; finalize after the route resumes.
199
- if (this.page && !this.page.isClosed())
200
- await this.page.screencast.stop().catch(() => undefined);
240
+ if (this.segment || !this.sessionOwned)
241
+ await this.stopEncoder(this.page);
201
242
  void this.stopCapture().catch(() => this.block());
202
243
  return;
203
244
  }
@@ -213,17 +254,18 @@ export class BrowserLiveHandle {
213
254
  return this.syncing;
214
255
  }
215
256
  async publishCurrentState(force = false) {
216
- if (!this.options.onState || !['observe', 'human'].includes(this.mode) || !force && Date.now() - this.lastStatePoll < 1000)
257
+ const options = this.options;
258
+ if (!options.onState || !['observe', 'human'].includes(this.mode) || !force && Date.now() - this.lastStatePoll < 1000)
217
259
  return false;
218
260
  this.lastStatePoll = Date.now();
219
261
  const epoch = this.controlEpoch;
220
262
  const mode = this.mode;
221
263
  const state = safeBrowserLiveState(await this.state());
222
- this.assertAuthorized();
223
- if (this.mode !== mode || epoch !== this.controlEpoch)
264
+ if (this.options !== options || this.mode !== mode || epoch !== this.controlEpoch)
224
265
  return false;
266
+ this.assertAuthorized(options);
225
267
  const fingerprint = JSON.stringify({ mode, epoch, tabs: state.tabs, profile: state.profile, private: state.private, focusId: state.focusId, settings: state.settings, recordingState: state.recordingState });
226
- if (fingerprint !== this.stateFingerprint && this.options.onState({ controlEpoch: epoch, mode, state })) {
268
+ if (fingerprint !== this.stateFingerprint && options.onState({ controlEpoch: epoch, mode, state })) {
227
269
  this.stateFingerprint = fingerprint;
228
270
  return true;
229
271
  }
@@ -232,9 +274,30 @@ export class BrowserLiveHandle {
232
274
  async syncInner() {
233
275
  if (this.closed || this.stopped)
234
276
  return;
277
+ if (this.sessionOwned && !this.viewerOptions && !this.baseOptions.isAuthorized()) {
278
+ if (this.page)
279
+ await this.stopCaptureInner();
280
+ if (!this.viewerOptions && !this.baseOptions.isAuthorized() && this.poll) {
281
+ clearInterval(this.poll);
282
+ this.poll = undefined;
283
+ }
284
+ return;
285
+ }
235
286
  this.assertAuthorized();
287
+ if (this.sessionOwned && this.segment && (!this.segment.authorized() || !this.baseOptions.isAuthorized()))
288
+ await this.finishRecording(this.page);
236
289
  const { page, tabId } = this.port.active();
237
- if (page === this.page && !(this.sessionOwned && this.segmentStartedAt !== undefined && Date.now() - this.segmentStartedAt >= 30_000)) {
290
+ if (page === this.page) {
291
+ if (this.sessionOwned) {
292
+ if (this.segmentStartedAt !== undefined && Date.now() - this.segmentStartedAt >= 30_000)
293
+ await this.finishRecording(page);
294
+ if (!this.segment)
295
+ await this.startRecording(page);
296
+ if (this.viewerOptions && !this.preview)
297
+ await this.startPreview(page, tabId, this.generation);
298
+ else if (!this.viewerOptions && this.preview)
299
+ await this.stopPreview();
300
+ }
238
301
  const changed = await this.publishCurrentState();
239
302
  if (changed)
240
303
  await this.refreshFrame();
@@ -256,54 +319,91 @@ export class BrowserLiveHandle {
256
319
  return;
257
320
  const generation = ++this.generation;
258
321
  this.page = page;
259
- let recordingPath;
260
- if (this.recordingMode !== 'off' && !this.private && this.mode !== 'blocked'
261
- && (this.recordingMode === 'local' || this.port.fullNetwork())) {
262
- const directory = this.options.recordingDirectory;
263
- fs.mkdirSync(directory, { recursive: true, mode: 0o700 });
264
- const info = fs.lstatSync(directory);
265
- if (!info.isDirectory() || info.isSymbolicLink() || fs.realpathSync(directory) !== directory)
266
- throw new Error('browser_recording_path_invalid');
267
- fs.chmodSync(directory, 0o700);
268
- const recordingId = randomUUID();
269
- const name = `browser-${recordingId}.webm`;
270
- recordingPath = path.join(directory, name);
271
- fs.closeSync(fs.openSync(recordingPath, 'wx', 0o600));
272
- this.segmentStartedAt = Date.now();
273
- this.segment = { recordingId, name, path: recordingPath, size: 0, mode: this.recordingMode };
322
+ if (this.sessionOwned) {
323
+ await this.startRecording(page);
324
+ if (this.viewerOptions)
325
+ await this.startPreview(page, tabId, generation);
326
+ }
327
+ else {
328
+ const recordingPath = this.prepareRecording();
329
+ await page.screencast.start({ quality: 70, size: page.viewportSize(),
330
+ ...(recordingPath ? { path: recordingPath, fps: this.fps } : {}),
331
+ onFrame: frame => this.previewFrame(frame.data, page, tabId, generation) });
274
332
  }
275
- await page.screencast.start({ quality: 70, size: page.viewportSize(),
276
- ...(recordingPath ? { path: recordingPath, fps: this.fps } : {}),
277
- onFrame: frame => {
278
- if (this.closed || generation !== this.generation || !this.options.isAuthorized() || !this.port.authorized()
279
- || this.port.active().page !== page)
280
- return;
281
- try {
282
- if (this.segment && fs.statSync(this.segment.path).size > 250 * 1024 * 1024) {
283
- void this.pauseRecording().catch(() => this.block());
284
- return;
285
- }
286
- }
287
- catch {
288
- this.block();
289
- return;
290
- }
291
- if (this.sessionOwned && !this.viewerOptions)
292
- return;
293
- if (Date.now() - this.lastFrameAt < this.frameInterval) {
294
- this.scheduleTrailingFrame(page, tabId, generation);
295
- return;
296
- }
297
- this.cancelTrailingFrame();
298
- this.lastFrameAt = Date.now();
299
- try {
300
- this.emitFrame(frame.data, page, tabId);
301
- }
302
- catch { /* A destroyed page/frame is discarded, never replayed. */ }
303
- } });
304
333
  if (!this.sessionOwned || this.viewerOptions)
305
334
  await this.refreshFrame();
306
335
  }
336
+ prepareRecording() {
337
+ if (this.recordingMode === 'off' || this.private || this.mode === 'blocked'
338
+ || this.sessionOwned && !this.baseOptions.isAuthorized()
339
+ || (this.recordingMode !== 'local' && !this.port.fullNetwork()))
340
+ return;
341
+ const directory = this.options.recordingDirectory;
342
+ fs.mkdirSync(directory, { recursive: true, mode: 0o700 });
343
+ const info = fs.lstatSync(directory);
344
+ if (!info.isDirectory() || info.isSymbolicLink() || fs.realpathSync(directory) !== directory)
345
+ throw new Error('browser_recording_path_invalid');
346
+ fs.chmodSync(directory, 0o700);
347
+ const recordingId = randomUUID();
348
+ const name = `browser-${recordingId}.webm`;
349
+ const recordingPath = path.join(directory, name);
350
+ fs.closeSync(fs.openSync(recordingPath, 'wx', 0o600));
351
+ this.segmentStartedAt = Date.now();
352
+ this.segment = { recordingId, name, path: recordingPath, size: 0, mode: this.recordingMode, authorized: this.baseOptions.isAuthorized };
353
+ return recordingPath;
354
+ }
355
+ async startRecording(page) {
356
+ if (this.closed || this.stopped || page.isClosed() || this.port.active().page !== page)
357
+ return;
358
+ this.assertAuthorized();
359
+ if (this.recordingMode === 'off' || this.private || !this.baseOptions.isAuthorized()
360
+ || browserAuthPage(page.url()) || await pageHasSecretFocus(page))
361
+ return;
362
+ if (this.port.active().page !== page)
363
+ return;
364
+ this.assertAuthorized();
365
+ const recordingPath = this.prepareRecording();
366
+ if (recordingPath)
367
+ await page.screencast.start({ quality: 70, size: page.viewportSize(), path: recordingPath, fps: this.fps });
368
+ }
369
+ async startPreview(page, tabId, generation) {
370
+ const session = await page.context().newCDPSession(page);
371
+ this.preview = session;
372
+ session.on('Page.screencastFrame', ({ data, sessionId }) => {
373
+ void session.send('Page.screencastFrameAck', { sessionId }).catch(() => undefined);
374
+ if (this.preview === session && data.length <= Math.ceil(BROWSER_LIVE_MAX_FRAME_BYTES * 4 / 3))
375
+ this.previewFrame(Buffer.from(data, 'base64'), page, tabId, generation);
376
+ });
377
+ const { width, height } = page.viewportSize();
378
+ try {
379
+ await session.send('Page.startScreencast', { format: 'jpeg', quality: 70, maxWidth: width, maxHeight: height });
380
+ }
381
+ catch (error) {
382
+ await this.stopPreview();
383
+ throw error;
384
+ }
385
+ }
386
+ async stopPreview() {
387
+ const session = this.preview;
388
+ this.preview = undefined;
389
+ if (session)
390
+ await session.detach().catch(() => undefined);
391
+ }
392
+ previewFrame(data, page, tabId, generation) {
393
+ if (this.closed || this.mode === 'blocked' || generation !== this.generation || !this.options.isAuthorized() || !this.port.authorized()
394
+ || this.port.active().page !== page || (this.sessionOwned && !this.viewerOptions))
395
+ return;
396
+ if (Date.now() - this.lastFrameAt < this.frameInterval) {
397
+ this.scheduleTrailingFrame(page, tabId, generation);
398
+ return;
399
+ }
400
+ this.cancelTrailingFrame();
401
+ this.lastFrameAt = Date.now();
402
+ try {
403
+ this.emitFrame(data, page, tabId);
404
+ }
405
+ catch { /* Discard destroyed pages and invalid frames. */ }
406
+ }
307
407
  cancelTrailingFrame() {
308
408
  if (this.trailingFrame)
309
409
  clearTimeout(this.trailingFrame);
@@ -397,17 +497,149 @@ export class BrowserLiveHandle {
397
497
  }
398
498
  throw new Error('browser_observation_stale');
399
499
  }
500
+ async stopPointer(commit = false) {
501
+ if (this.pointerExpiry)
502
+ clearTimeout(this.pointerExpiry);
503
+ this.pointerExpiry = undefined;
504
+ const pointer = this.pointer;
505
+ this.pointer = undefined;
506
+ if (pointer) {
507
+ pointer.page.off('framenavigated', pointer.navigation);
508
+ if (!commit)
509
+ await pointer.page.mouse.move(-1, -1).catch(() => undefined);
510
+ await pointer.page.mouse.up({ button: pointer.button }).catch(() => undefined);
511
+ for (const key of pointer.modifiers)
512
+ await pointer.page.keyboard.up(key).catch(() => undefined);
513
+ }
514
+ }
515
+ async pointerInput(frame) {
516
+ const options = this.options;
517
+ this.assertAuthorized(options);
518
+ if (frame.action === 'pointer' && frame.liveSessionId === options.liveSessionId && frame.controlEpoch === this.controlEpoch
519
+ && Number.isSafeInteger(frame.privateInput?.expiresAt) && frame.privateInput.expiresAt <= Date.now()) {
520
+ await this.stopPointer();
521
+ return;
522
+ }
523
+ if (!validBrowserLiveControl(frame) || frame.action !== 'pointer' || frame.liveSessionId !== options.liveSessionId
524
+ || this.sessionOwned && (!this.viewerOptions || !this.viewerOptions.isAuthorized()))
525
+ throw new Error('browser_live_scope_invalid');
526
+ if (frame.controlEpoch !== this.controlEpoch || this.mode !== 'human' || !this.private)
527
+ return;
528
+ const input = decryptBrowserPointer(frame, options, options.identity);
529
+ await this.port.queue(async () => {
530
+ this.assertAuthorized(options);
531
+ if (frame.controlEpoch !== this.controlEpoch || this.mode !== 'human' || !this.private)
532
+ return;
533
+ const { page, tabId } = this.port.active();
534
+ const viewport = page.viewportSize();
535
+ try {
536
+ if (input.phase === 'down') {
537
+ for (const [id, expiresAt] of this.pointerStarts)
538
+ if (expiresAt <= Date.now())
539
+ this.pointerStarts.delete(id);
540
+ if (this.pointerStarts.has(input.gestureId) || this.pointerStarts.size >= 64)
541
+ return;
542
+ this.pointerStarts.set(input.gestureId, frame.privateInput.expiresAt);
543
+ await this.stopPointer();
544
+ this.port.observations.require(input.observationId, page, tabId, true);
545
+ if (!viewport || input.x >= viewport.width || input.y >= viewport.height)
546
+ return;
547
+ const pointer = { id: input.gestureId, page, tabId, url: page.url(), width: viewport.width, height: viewport.height,
548
+ navigation: () => { void this.stopPointer(); },
549
+ epoch: frame.controlEpoch, sequence: 0, button: input.button, modifiers: input.modifiers ?? [] };
550
+ this.pointer = pointer;
551
+ page.on('framenavigated', pointer.navigation);
552
+ for (const key of pointer.modifiers)
553
+ await page.keyboard.down(key);
554
+ await page.mouse.move(input.x, input.y);
555
+ this.assertAuthorized(options);
556
+ if (this.pointer !== pointer || this.controlEpoch !== pointer.epoch || this.mode !== 'human') {
557
+ await releasePageInput(page);
558
+ return;
559
+ }
560
+ await page.mouse.down({ button: pointer.button });
561
+ if (this.pointer !== pointer || this.controlEpoch !== pointer.epoch || this.mode !== 'human') {
562
+ await releasePageInput(page);
563
+ return;
564
+ }
565
+ }
566
+ else {
567
+ const pointer = this.pointer;
568
+ if (!pointer || pointer.id !== input.gestureId || input.sequence <= pointer.sequence)
569
+ return;
570
+ if (input.phase === 'cancel' || pointer.page !== page || pointer.tabId !== tabId || pointer.url !== page.url()
571
+ || viewport?.width !== pointer.width || viewport?.height !== pointer.height
572
+ || input.x >= viewport.width || input.y >= viewport.height) {
573
+ await this.stopPointer();
574
+ return;
575
+ }
576
+ pointer.sequence = input.sequence;
577
+ await page.mouse.move(input.x, input.y);
578
+ if (input.phase === 'up') {
579
+ await this.stopPointer(true);
580
+ return;
581
+ }
582
+ }
583
+ if (this.pointer) {
584
+ if (this.pointerExpiry)
585
+ clearTimeout(this.pointerExpiry);
586
+ this.pointerExpiry = setTimeout(() => { void this.stopPointer(); }, 10_000);
587
+ this.pointerExpiry.unref();
588
+ }
589
+ }
590
+ catch (error) {
591
+ await this.stopPointer();
592
+ if (!(error instanceof Error && error.message === 'browser_observation_stale'))
593
+ throw error;
594
+ }
595
+ }, true);
596
+ }
597
+ async copySelection(frame) {
598
+ const options = this.options;
599
+ this.assertAuthorized(options);
600
+ if (!validBrowserLiveControl(frame) || frame.action !== 'copy_selection' || frame.liveSessionId !== options.liveSessionId
601
+ || this.sessionOwned && (!this.viewerOptions || !this.viewerOptions.isAuthorized()))
602
+ throw new Error('browser_live_scope_invalid');
603
+ if (frame.controlEpoch !== this.controlEpoch || this.mode !== 'human' || !this.private)
604
+ return undefined;
605
+ const request = decryptClipboardRequest(frame, options, options.identity);
606
+ try {
607
+ return await this.port.queue(async () => {
608
+ this.assertAuthorized(options);
609
+ if (this.mode !== 'human' || this.controlEpoch !== frame.controlEpoch || !this.private)
610
+ return undefined;
611
+ const { page, tabId } = this.port.active();
612
+ try {
613
+ this.port.observations.require(request.observationId, page, tabId, true);
614
+ }
615
+ catch {
616
+ return undefined;
617
+ }
618
+ const url = page.url();
619
+ const selected = await readPageSelection(page);
620
+ this.assertAuthorized(options);
621
+ if (!selected || this.mode !== 'human' || this.controlEpoch !== frame.controlEpoch
622
+ || this.port.active().page !== page || page.url() !== url)
623
+ return undefined;
624
+ return encryptBrowserSelection(frame, request.key, selected);
625
+ }, true);
626
+ }
627
+ finally {
628
+ request.key.fill(0);
629
+ }
630
+ }
400
631
  async control(frame) {
632
+ const options = this.options;
401
633
  let humanProfileTransition = false;
402
634
  const ack = (ok, error, state) => ({
403
- type: 'control.result', requestId: frame.requestId, liveSessionId: this.options.liveSessionId,
635
+ type: 'control.result', requestId: frame.requestId, liveSessionId: options.liveSessionId,
404
636
  controlEpoch: this.controlEpoch, mode: this.mode, ok, ...(error ? { error } : {}), ...(state ? { state } : {})
405
637
  });
406
638
  try {
407
- this.assertAuthorized();
639
+ this.assertAuthorized(options);
408
640
  if (this.sessionOwned && (!this.viewerOptions || !this.viewerOptions.isAuthorized()))
409
641
  throw new Error('browser_live_scope_expired');
410
- if (!validBrowserLiveControl(frame) || frame.liveSessionId !== this.options.liveSessionId || this.requests.has(frame.requestId))
642
+ if (!validBrowserLiveControl(frame) || frame.liveSessionId !== options.liveSessionId || this.requests.has(frame.requestId))
411
643
  throw new Error('browser_live_control_invalid');
412
644
  for (const [id, at] of this.requests)
413
645
  if (Date.now() - at > 300000)
@@ -415,69 +647,107 @@ export class BrowserLiveHandle {
415
647
  if (this.requests.size >= 4096)
416
648
  throw new Error('browser_live_reconnect_required');
417
649
  this.requests.set(frame.requestId, Date.now());
418
- const transition = ['takeover', 'release', 'profile', 'select_tab'].includes(frame.action)
650
+ const transition = ['takeover', 'release', 'profile', 'select_tab', 'new_tab', 'close_tab', 'close_session'].includes(frame.action)
419
651
  || frame.action === 'stop' && this.mode !== 'observe';
420
652
  if (transition ? frame.controlEpoch !== this.controlEpoch + 1
421
653
  : frame.action === 'start' ? frame.controlEpoch > this.controlEpoch : frame.controlEpoch !== this.controlEpoch)
422
654
  throw new Error('browser_live_epoch_stale');
423
655
  const priorMode = this.mode;
656
+ if (this.port.control.tabId && ['profile', 'select_tab', 'new_tab', 'close_tab', 'close_session'].includes(frame.action))
657
+ throw new Error('browser_live_tab_scope_required');
424
658
  humanProfileTransition = frame.action === 'profile' && priorMode === 'human';
425
- if (['input', 'profile', 'select_tab', 'settings', 'navigate'].includes(frame.action) && priorMode !== 'human'
659
+ if (['input', 'profile', 'select_tab', 'new_tab', 'close_tab', 'settings', 'navigate'].includes(frame.action) && priorMode !== 'human'
426
660
  || frame.action === 'recording' && priorMode === 'blocked' && frame.recording?.mode !== 'off')
427
661
  throw new Error('browser_live_human_owner_required');
662
+ if (frame.action === 'recording_save') {
663
+ const accepted = this.requestRecordingSave();
664
+ return ack(accepted, accepted ? undefined : 'browser_recording_save_unavailable', { recordingState: this.recordingState() });
665
+ }
428
666
  // Fence every queued model operation immediately, before awaiting the shared session queue.
429
667
  if (transition) {
430
668
  this.port.control.epoch = frame.controlEpoch;
431
669
  this.port.control.mode = 'blocked';
670
+ if (frame.action === 'takeover')
671
+ this.port.control.tabId = frame.tabId;
432
672
  this.port.observations.invalidate();
433
673
  }
434
674
  return await this.port.queue(async () => {
435
- this.assertAuthorized();
675
+ this.assertAuthorized(options);
436
676
  if (frame.action !== 'start' && frame.controlEpoch !== this.controlEpoch)
437
677
  throw new Error('browser_live_epoch_stale');
678
+ if (this.pointer)
679
+ await this.stopPointer();
438
680
  if (frame.action === 'takeover') {
681
+ if (frame.tabId && this.port.active().tabId !== frame.tabId)
682
+ throw new Error('browser_tab_missing');
439
683
  this.port.control.private = frame.private !== false;
440
684
  if (this.private)
441
685
  await this.stopCapture();
442
- for (const page of this.port.pages())
686
+ for (const page of this.controlledPages())
443
687
  await releasePageInput(page);
688
+ this.assertAuthorized(options);
444
689
  this.port.control.mode = 'human';
445
690
  }
446
691
  else if (frame.action === 'release') {
447
- await this.stopCapture();
692
+ if (this.private)
693
+ await this.stopCapture();
694
+ this.assertAuthorized(options);
448
695
  await this.port.release();
696
+ this.assertAuthorized(options);
449
697
  this.port.control.private = false;
698
+ this.port.control.mode = 'observe';
450
699
  }
451
700
  else if (frame.action === 'input') {
452
- const interaction = decryptBrowserHumanInput(frame, this.options, this.options.identity);
701
+ const interaction = decryptBrowserHumanInput(frame, options, options.identity);
453
702
  const { page, tabId } = this.port.active();
454
703
  const observation = this.port.observations.require(interaction.observationId, page, tabId, true);
455
704
  if (this.private || await pageHasSecretFocus(page)) {
456
705
  this.port.control.private = true;
457
706
  await this.stopCapture();
458
707
  }
708
+ this.assertAuthorized(options);
459
709
  await applyPageInteraction(page, interaction, observation, true);
460
710
  this.port.observations.invalidate();
461
711
  }
462
712
  else if (frame.action === 'profile') {
463
713
  this.port.control.private = true;
464
714
  await this.stopCapture();
465
- await this.port.profile(frame.profile, this.options);
715
+ this.assertAuthorized(options);
716
+ await this.port.profile(frame.profile, options);
717
+ this.assertAuthorized(options);
466
718
  this.port.control.mode = 'human';
467
719
  }
468
720
  else if (frame.action === 'select_tab') {
469
721
  await this.stopCapture();
722
+ this.assertAuthorized(options);
470
723
  await this.port.selectTab(frame.tabId);
724
+ this.assertAuthorized(options);
725
+ this.port.control.mode = 'human';
726
+ }
727
+ else if (frame.action === 'new_tab' || frame.action === 'close_tab' || frame.action === 'close_session') {
728
+ await this.stopCapture();
729
+ this.assertAuthorized(options);
730
+ if (frame.action === 'close_session') {
731
+ await this.port.closeSession();
732
+ return { ...ack(true), closed: true };
733
+ }
734
+ if (frame.action === 'close_tab' && await this.port.closeTab(frame.tabId))
735
+ return { ...ack(true), closed: true };
736
+ if (frame.action === 'new_tab')
737
+ await this.port.newTab();
738
+ this.assertAuthorized(options);
471
739
  this.port.control.mode = 'human';
472
740
  }
473
741
  else if (frame.action === 'settings') {
474
742
  await this.stopCapture();
743
+ this.assertAuthorized(options);
475
744
  this.fps = frame.settings.fps;
476
745
  await this.port.active().page.setViewportSize({ width: frame.settings.width, height: frame.settings.height });
477
746
  this.port.observations.invalidate();
478
747
  }
479
748
  else if (frame.action === 'navigate') {
480
749
  await this.stopCapture();
750
+ this.assertAuthorized(options);
481
751
  this.port.observations.invalidate();
482
752
  const page = this.port.active().page;
483
753
  if (frame.navigation === 'back')
@@ -499,10 +769,25 @@ export class BrowserLiveHandle {
499
769
  }
500
770
  if (mode !== 'off' && mode !== 'local' && !this.port.fullNetwork())
501
771
  throw new Error('browser_recording_network_required');
502
- await this.stopCapture();
503
- if (this.recordingMode === 'off' && mode !== 'off')
504
- this.elapsedMs = 0;
505
- this.recordingMode = mode;
772
+ if (this.sessionOwned) {
773
+ await this.capture(async () => {
774
+ this.assertAuthorized(options);
775
+ const page = this.port.active().page;
776
+ await this.finishRecording(this.page);
777
+ this.assertAuthorized(options);
778
+ if (this.recordingMode === 'off' && mode !== 'off')
779
+ this.elapsedMs = 0;
780
+ this.recordingMode = mode;
781
+ if (page === this.page)
782
+ await this.startRecording(page);
783
+ });
784
+ }
785
+ else {
786
+ await this.stopCapture();
787
+ if (this.recordingMode === 'off' && mode !== 'off')
788
+ this.elapsedMs = 0;
789
+ this.recordingMode = mode;
790
+ }
506
791
  }
507
792
  else if (frame.action === 'stop') {
508
793
  if (this.sessionOwned && priorMode === 'observe') {
@@ -528,29 +813,36 @@ export class BrowserLiveHandle {
528
813
  await this.sync();
529
814
  await this.refreshFrame();
530
815
  const state = await this.state();
531
- this.assertAuthorized();
532
- if (frame.action === 'release') {
533
- this.port.control.mode = 'observe';
534
- await this.stopCapture();
535
- await this.sync();
536
- }
537
- return ack(true, undefined, frame.action === 'release' ? await this.state() : state);
816
+ this.assertAuthorized(options);
817
+ if (frame.action === 'release')
818
+ this.port.control.tabId = undefined;
819
+ return ack(true, undefined, state);
538
820
  });
539
821
  }
540
822
  catch (error) {
541
823
  const message = error instanceof Error && /^browser_[a-z_]+$/u.test(error.message) ? error.message : 'browser_live_control_failed';
542
824
  // Geometry may change during native smooth scrolling. This rejected action had no
543
825
  // side effects: refresh its observation without ending the user's control or replaying it.
826
+ if ((frame.action === 'new_tab' || frame.action === 'close_tab') && ['browser_tab_limit', 'browser_tab_missing'].includes(message)) {
827
+ try {
828
+ this.assertAuthorized(options);
829
+ this.port.control.mode = 'human';
830
+ await this.sync();
831
+ await this.refreshFrame(this.controlEpoch);
832
+ return ack(false, message, await this.state());
833
+ }
834
+ catch { /* Keep ordinary authorization failures fenced. */ }
835
+ }
544
836
  if (frame.action === 'recording' && ['browser_recording_private', 'browser_recording_network_required'].includes(message)) {
545
837
  try {
546
- this.assertAuthorized();
838
+ this.assertAuthorized(options);
547
839
  return ack(false, message, await this.state());
548
840
  }
549
841
  catch { /* Keep ordinary authorization failures fenced. */ }
550
842
  }
551
843
  if (humanProfileTransition && ['browser_profile_busy', 'browser_profile_exists', 'browser_profile_name_invalid', 'browser_profile_keystore_unsupported'].includes(message)) {
552
844
  try {
553
- this.assertAuthorized();
845
+ this.assertAuthorized(options);
554
846
  this.port.control.mode = 'human';
555
847
  this.port.control.private = true;
556
848
  await this.sync();
@@ -563,6 +855,7 @@ export class BrowserLiveHandle {
563
855
  }
564
856
  if (['browser_observation_stale', 'browser_focus_changed'].includes(message) && frame.action === 'input' && this.mode === 'human') {
565
857
  try {
858
+ this.assertAuthorized(options);
566
859
  await this.refreshFrame(this.controlEpoch);
567
860
  return ack(false, message, await this.state());
568
861
  }
@@ -571,6 +864,29 @@ export class BrowserLiveHandle {
571
864
  return ack(false, message);
572
865
  }
573
866
  }
867
+ requestRecordingSave() {
868
+ const page = this.port.active().page;
869
+ const segment = this.segment;
870
+ const epoch = this.controlEpoch;
871
+ if (!this.sessionOwned || !this.baseOptions.isAuthorized() || !this.baseOptions.recordingCheckpoint || !segment || page !== this.page
872
+ || this.private || this.mode === 'blocked' || !this.port.fullNetwork()
873
+ || !['storage', 'both'].includes(segment.mode) || this.recordingState().checkpoint?.status === 'saving')
874
+ return false;
875
+ this.pendingCheckpoint = { recordingId: segment.recordingId, status: 'saving' };
876
+ void this.capture(async () => {
877
+ this.assertAuthorized();
878
+ if (!this.baseOptions.isAuthorized() || this.segment !== segment || this.port.active().page !== page || this.controlEpoch !== epoch
879
+ || this.private || !this.port.fullNetwork())
880
+ throw new Error('browser_recording_save_unavailable');
881
+ const queued = await this.finishRecording(page, true);
882
+ this.pendingCheckpoint = queued ? undefined : { recordingId: segment.recordingId, status: 'failed' };
883
+ await this.startRecording(page);
884
+ }).catch(() => {
885
+ if (this.pendingCheckpoint?.recordingId === segment.recordingId)
886
+ this.pendingCheckpoint = { recordingId: segment.recordingId, status: 'failed' };
887
+ });
888
+ return true;
889
+ }
574
890
  block(epoch) {
575
891
  if (this.closed)
576
892
  return;
@@ -582,10 +898,21 @@ export class BrowserLiveHandle {
582
898
  this.port.control.mode = 'blocked';
583
899
  this.port.control.private = true;
584
900
  this.port.observations.invalidate();
901
+ void this.stopPointer();
585
902
  void this.stopCapture().catch(() => undefined);
586
- for (const page of this.port.pages())
903
+ for (const page of this.controlledPages())
587
904
  void releasePageInput(page);
588
905
  }
906
+ controlledPages() {
907
+ if (!this.port.control.tabId)
908
+ return this.port.pages();
909
+ try {
910
+ return [this.port.active().page];
911
+ }
912
+ catch {
913
+ return [];
914
+ }
915
+ }
589
916
  async settled() { await this.captureQueue.catch(() => undefined); }
590
917
  disconnect() {
591
918
  if (this.closed)
@@ -596,6 +923,8 @@ export class BrowserLiveHandle {
596
923
  this.viewerOptions = undefined;
597
924
  this.port.control.connected = false;
598
925
  this.cancelTrailingFrame();
926
+ this.generation++;
927
+ void this.capture(() => this.stopPreview()).catch(() => undefined);
599
928
  if (this.recordingMode === 'off') {
600
929
  if (this.poll)
601
930
  clearInterval(this.poll);
@@ -618,7 +947,7 @@ export class BrowserLiveHandle {
618
947
  if (this.poll)
619
948
  clearInterval(this.poll);
620
949
  void this.stopCapture().catch(() => undefined);
621
- for (const page of this.port.pages())
950
+ for (const page of this.controlledPages())
622
951
  void releasePageInput(page);
623
952
  }
624
953
  }