gipity 1.1.16 → 1.1.19

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 (59) hide show
  1. package/README.md +58 -75
  2. package/dist/adopt-cwd.js +2 -13
  3. package/dist/api.js +26 -44
  4. package/dist/auth.js +1 -1
  5. package/dist/banner.js +3 -7
  6. package/dist/catalog.js +8 -7
  7. package/dist/commands/add.js +26 -9
  8. package/dist/commands/approval.js +1 -1
  9. package/dist/commands/ask.js +112 -0
  10. package/dist/commands/bug.js +5 -5
  11. package/dist/commands/build.js +10 -35
  12. package/dist/commands/credits.js +3 -3
  13. package/dist/commands/doctor.js +7 -8
  14. package/dist/commands/email.js +6 -56
  15. package/dist/commands/generate.js +4 -4
  16. package/dist/commands/init.js +40 -30
  17. package/dist/commands/key.js +1 -1
  18. package/dist/commands/load.js +2 -12
  19. package/dist/commands/logs.js +2 -2
  20. package/dist/commands/memory.js +5 -17
  21. package/dist/commands/notify.js +1 -1
  22. package/dist/commands/page-eval.js +55 -38
  23. package/dist/commands/page-inspect.js +6 -6
  24. package/dist/commands/page-screenshot.js +51 -54
  25. package/dist/commands/page-test.js +188 -14
  26. package/dist/commands/payments.js +2 -2
  27. package/dist/commands/project.js +66 -15
  28. package/dist/commands/realtime.js +96 -4
  29. package/dist/commands/records.js +4 -6
  30. package/dist/commands/sandbox.js +2 -3
  31. package/dist/commands/skill.js +50 -22
  32. package/dist/commands/status.js +7 -9
  33. package/dist/commands/test.js +2 -2
  34. package/dist/commands/token.js +4 -4
  35. package/dist/commands/workflow.js +45 -8
  36. package/dist/config.js +22 -6
  37. package/dist/flag-aliases.js +75 -18
  38. package/dist/help-skills.js +2 -2
  39. package/dist/hooks/capture-runner.js +5 -3
  40. package/dist/index.js +1616 -1498
  41. package/dist/knowledge.js +24 -21
  42. package/dist/login-flow.js +4 -4
  43. package/dist/net.js +91 -0
  44. package/dist/opencode-setup.js +2 -2
  45. package/dist/page-fixtures.js +3 -3
  46. package/dist/project-setup.js +2 -3
  47. package/dist/prompts.js +1 -1
  48. package/dist/realtime-bench.js +12040 -0
  49. package/dist/relay/agent-token.js +1 -1
  50. package/dist/relay/daemon.js +0 -1
  51. package/dist/relay/setup.js +13 -2
  52. package/dist/setup.js +11 -12
  53. package/dist/sync.js +3 -3
  54. package/dist/utils.js +1 -1
  55. package/package.json +10 -4
  56. package/dist/commands/agent.js +0 -251
  57. package/dist/commands/chat.js +0 -137
  58. package/dist/commands/claude.js +0 -1056
  59. package/dist/commands/plan.js +0 -93
@@ -43,7 +43,7 @@ function printAuthLine(auth) {
43
43
  const who = getAuth()?.email;
44
44
  console.log(auth.established
45
45
  ? `${label('Auth')} ${success('session established')}${who ? muted(` as ${who}`) : ''} ${muted('(what the page renders with it is app-defined)')}`
46
- : `${warning('Auth: session NOT established')}${auth.detail ? ` — ${auth.detail}` : ''} ${muted('(this is the anonymous view)')}`);
46
+ : `${warning('Auth: session NOT established')}${auth.detail ? `: ${auth.detail}` : ''} ${muted('(this is the anonymous view)')}`);
47
47
  }
48
48
  /** A failed pre-capture script still yields a screenshot - of the page it never
49
49
  * touched. Silence there is the trap: the image looks plausible and the command
@@ -70,7 +70,7 @@ export function augmentSandboxTimeout(message) {
70
70
  return message;
71
71
  return (`${message}\n` +
72
72
  `A pre-capture script was set (--action and/or the --wait-for gate), and its runtime is spent INSIDE ` +
73
- `that same sandbox budget — a script that waits on slow work (a WASM/model download, a network fetch, ` +
73
+ `that same sandbox budget: a script that waits on slow work (a WASM/model download, a network fetch, ` +
74
74
  `a long animation) can exhaust the budget on its own. Keep --action to the interaction itself (a click, ` +
75
75
  `a keypress), let the page do the slow work on load, and absorb that with --wait <ms> or a tighter ` +
76
76
  `--wait-for '<selector>' gate instead.`);
@@ -101,15 +101,16 @@ function dimSuffix(vp) {
101
101
  const dpr = vp.deviceScaleFactor ?? 1;
102
102
  return dpr === 1 ? `${vp.width}x${vp.height}` : `${vp.width}x${vp.height}@${dpr}`;
103
103
  }
104
- /** Default screenshot directory: `<project-root>/screenshots`, falling back
105
- * to `./screenshots` in one-off mode (no linked project). Screenshots are
106
- * part of the project's build history: the dir syncs to Gipity (the server
107
- * also persists captures to VFS `screenshots/` directly — same names, so
108
- * sync reconciles by content hash) but is excluded from every deploy
109
- * server-side. Timestamped filenames make the history browsable. */
110
- function defaultScreenshotDir() {
104
+ /** Default screenshot directory: `<project-root>/tmp/screenshots`, falling
105
+ * back to `./tmp/screenshots` in one-off mode (no linked project). A
106
+ * verification capture is scratch: `tmp/` is the one place that never syncs
107
+ * and never deploys, so a shot of a signed-in, private view can't leak into
108
+ * the project and nothing needs cleaning up afterwards. A capture worth
109
+ * keeping is a deliberate `-o docs/<name>.png` (synced, never deployed).
110
+ * Timestamped filenames keep a run's shots in order. */
111
+ export function defaultScreenshotDir() {
111
112
  const root = getProjectRoot();
112
- return join(root ?? '.', 'screenshots');
113
+ return join(root ?? '.', 'tmp', 'screenshots');
113
114
  }
114
115
  /** `yyyy-mm-dd_hh-mm-ss` per the repo timestamp convention - sorts chronologically,
115
116
  * filesystem-safe. One stamp per invocation; viewport suffixes keep multi-shot
@@ -200,6 +201,16 @@ function appendOption(value, previous = []) {
200
201
  // which swallowed the script and errored with a redirect: when the guess is
201
202
  // unambiguous, making it WORK beats making it a better error.)
202
203
  const ACTION_ALIAS_FLAGS = ['--eval', '--js', '--javascript', '--script', '--code', '--exec'];
204
+ // Same accept-the-reflex-guess pattern for the output file: `--path` and `--out`
205
+ // are what agents type for "save it here" (commander answered `--path` with
206
+ // "Did you mean --auth?", which points nowhere useful). Working hidden aliases
207
+ // for -o/--output.
208
+ const OUTPUT_ALIAS_FLAGS = ['--path', '--out'];
209
+ /** True when `--file` names an image: the caller meant the OUTPUT file, but
210
+ * --file is the pre-capture SCRIPT. Caught before it is read as JavaScript. */
211
+ export function looksLikeImagePath(p) {
212
+ return /\.(png|jpe?g|webp|gif)$/i.test(p);
213
+ }
203
214
  /** A capture is worthless if it fires before the app reaches the state you meant
204
215
  * to photograph, and the only lever used to be a blind millisecond delay — so a
205
216
  * camera/vision app got screenshotted with a guessed duration (`--wait 22000`).
@@ -214,7 +225,7 @@ export function buildWaitForGate(selector, timeoutMs) {
214
225
  `while (Date.now() - __t0 < ${timeoutMs}) { ` +
215
226
  `try { if (document.querySelector(${sel})) return; } catch (e) { throw new Error('wait-for: invalid selector ' + ${sel}); } ` +
216
227
  `await new Promise((r) => setTimeout(r, 100)); } ` +
217
- `throw new Error('wait-for: nothing matched ' + ${sel} + ' within ${timeoutMs}ms — the page never reached that state (raise --wait-timeout, fix the selector, or check the app actually gets there headlessly)'); })();`);
228
+ `throw new Error('wait-for: nothing matched ' + ${sel} + ' within ${timeoutMs}ms: the page never reached that state (raise --wait-timeout, fix the selector, or check the app actually gets there headlessly)'); })();`);
218
229
  }
219
230
  /** Max ms the selector gate may wait. The gate runs inside the capture's sandbox
220
231
  * exec budget (page load + delay + script + settle + render), and 15s is what
@@ -240,7 +251,7 @@ export const pageScreenshotCommand = new Command('screenshot')
240
251
  // the single most common reason to screenshot, and agents routinely read the
241
252
  // help through `--help | head -N` — buried below the timing flags, these two
242
253
  // fell off the bottom and the run proceeded at desktop width.
243
- .option('--device <names>', `Device preset(s): ${Object.keys(DEVICE_PRESETS).join(', ')} (comma-separated or repeat flag). mobile/tablet emulate a real touch device — touch events, mobile user-agent, DPR — so touch-gated mobile UI actually renders.`, appendOption, [])
254
+ .option('--device <names>', `Device preset(s): ${Object.keys(DEVICE_PRESETS).join(', ')} (comma-separated or repeat flag). mobile/tablet emulate a real touch device (touch events, mobile user-agent, DPR) so touch-gated mobile UI actually renders.`, appendOption, [])
244
255
  .option('--viewport <dims>', 'Raw viewport(s): WxH or WxH@dpr (comma-separated or repeat flag), e.g. --viewport 390x844 for a phone-sized window', appendOption, [])
245
256
  // No commander default: a default here would make the value always set, so the
246
257
  // merge below could not tell "caller chose a delay" from "nobody did" — which
@@ -251,12 +262,11 @@ export const pageScreenshotCommand = new Command('screenshot')
251
262
  .option('--action <js>', 'Run JS in the page before capturing - e.g. click a button to enter a state ("document.getElementById(\'play\').click()"). Runs as an async function body, so const/await and app-relative import(\'./...\') work. Runs after the post-load delay, then settles again before the shot. If it throws, the capture still happens and the failure is reported.')
252
263
  .option('--file <path>', 'Read the pre-capture script from a file instead of inline --action (mutually exclusive), or --file - to read it from stdin (pipe a heredoc: --file - <<\'EOF\' ... EOF) with no tmp file. For a multi-step driver - click through a flow, wait for it to render - then capture. Same async-function-body semantics as --action; same --file flag as page eval.')
253
264
  .option('--full', 'Capture the full scrollable page (default: viewport only). Scrolls the page through first so scroll-reveal/fade-in-on-scroll (IntersectionObserver) sections render into the shot instead of capturing blank.')
254
- .option('-o, --output <file>', 'Output path (default .gipity/screenshots/ss-<host>-<timestamp>.png). With several viewports it is a stem: -o tmp/shot.png --device desktop,mobile writes tmp/shot-desktop.png and tmp/shot-mobile.png.')
265
+ .option('-o, --output <file>', 'Output path (default tmp/screenshots/ss-<host>-<timestamp>.png in the project: scratch, never synced or deployed). To keep a capture, write it under docs/ (-o docs/home.png: synced, never deployed). With several viewports it is a stem: -o tmp/shot.png --device desktop,mobile writes tmp/shot-desktop.png and tmp/shot-mobile.png.')
255
266
  .option('--no-reload-between', 'Skip reload between viewports (faster, lower fidelity - only safe for static pages)')
256
- .option('--fake-media', 'Grant a synthetic microphone + camera and auto-accept the getUserMedia prompt, so voice/camera apps render headlessly. The video feed is a built-in test pattern — to capture what the app does with a REAL frame (a hand, a face, an object), use --camera <path> instead.')
257
- .option('--camera <path>', 'Play a local image or video (.png/.jpg/.webp/.mp4/.webm/.y4m/.mjpeg) as the browser\'s WEBCAM feed, then capture — so the shot shows the app reacting to a frame you chose (detected gesture, boxes, labels). Implies --fake-media.')
258
- .option('--auth', 'Capture the page signed in as you (your Gipity account), so UI behind a Sign-in-with-Gipity login is shown. Only works for apps using Sign in with Gipity, hosted on *.gipity.ai. Without this flag the page loads as a genuinely anonymous, signed-out visitor — nothing carries over from earlier --auth runs.')
259
- .option('--ephemeral', 'Skip the project screenshot history: do not persist this capture to Gipity (screenshots/ in the project). Local file is still written.')
267
+ .option('--fake-media', 'Grant a synthetic microphone + camera and auto-accept the getUserMedia prompt, so voice/camera apps render headlessly. The video feed is a built-in test pattern. To capture what the app does with a REAL frame (a hand, a face, an object), use --camera <path> instead.')
268
+ .option('--camera <path>', 'Play a local image or video (.png/.jpg/.webp/.mp4/.webm/.y4m/.mjpeg) as the browser\'s WEBCAM feed, then capture, so the shot shows the app reacting to a frame you chose (detected gesture, boxes, labels). Implies --fake-media.')
269
+ .option('--auth', 'Capture the page signed in as you (your Gipity account), so UI behind a Sign-in-with-Gipity login is shown. Only works for apps using Sign in with Gipity, hosted on *.gipity.ai. Without this flag the page loads as a genuinely anonymous, signed-out visitor: nothing carries over from earlier --auth runs.')
260
270
  .option('--json', 'Output JSON metadata instead of a friendly summary')
261
271
  .addOption(new Option('--post-load-delay <ms>', 'Alias for --wait').hideHelp())
262
272
  // (--eval and the other JS-intent guesses are registered in one place from
@@ -277,7 +287,7 @@ export const pageScreenshotCommand = new Command('screenshot')
277
287
  // so the next call uses it.
278
288
  const aliasFlag = ACTION_ALIAS_FLAGS.find((f) => opts[f.slice(2)] !== undefined);
279
289
  if (aliasFlag) {
280
- console.error(muted(`Note: treating ${aliasFlag} as --action — it runs your JS in the page before the capture. --action is the canonical flag.`));
290
+ console.error(muted(`Note: treating ${aliasFlag} as --action: it runs your JS in the page before the capture. --action is the canonical flag.`));
281
291
  }
282
292
  // The pre-capture script can come inline (--action / its JS-intent aliases) or
283
293
  // from a file/stdin (--file, the same script-passing ergonomics as page eval).
@@ -290,6 +300,9 @@ export const pageScreenshotCommand = new Command('screenshot')
290
300
  throw new Error('Pass either --file <path> or an inline --action script, not both');
291
301
  }
292
302
  let actionScript = inlineAction;
303
+ if (opts.file && looksLikeImagePath(opts.file)) {
304
+ throw new Error(`--file is the pre-capture SCRIPT (JavaScript to run before the shot), not the output image: save the PNG with -o ${opts.file}`);
305
+ }
293
306
  if (opts.file) {
294
307
  try {
295
308
  actionScript = readScriptFile(opts.file);
@@ -310,7 +323,7 @@ export const pageScreenshotCommand = new Command('screenshot')
310
323
  throw new Error('--wait must be a non-negative integer (ms)');
311
324
  }
312
325
  if (postLoadDelayMs > MAX_POST_LOAD_DELAY_MS) {
313
- console.error(warning(`--wait ${postLoadDelayMs}ms exceeds the ${MAX_POST_LOAD_DELAY_MS}ms cap — using ${MAX_POST_LOAD_DELAY_MS}ms. ` +
326
+ console.error(warning(`--wait ${postLoadDelayMs}ms exceeds the ${MAX_POST_LOAD_DELAY_MS}ms cap: using ${MAX_POST_LOAD_DELAY_MS}ms. ` +
314
327
  `Waiting longer is rarely the fix: gate on the state you want with --wait-for '<selector>' instead of guessing a duration.`));
315
328
  postLoadDelayMs = MAX_POST_LOAD_DELAY_MS;
316
329
  }
@@ -320,7 +333,7 @@ export const pageScreenshotCommand = new Command('screenshot')
320
333
  }
321
334
  const waitForTimeoutMs = Math.min(waitForTimeoutRaw, WAIT_FOR_MAX_MS);
322
335
  if (waitForTimeoutRaw > WAIT_FOR_MAX_MS) {
323
- console.error(warning(`--wait-timeout ${waitForTimeoutRaw}ms exceeds the ${WAIT_FOR_MAX_MS}ms the capture's browser budget covers — using ${WAIT_FOR_MAX_MS}ms. ` +
336
+ console.error(warning(`--wait-timeout ${waitForTimeoutRaw}ms exceeds the ${WAIT_FOR_MAX_MS}ms the capture's browser budget covers: using ${WAIT_FOR_MAX_MS}ms. ` +
324
337
  `A state that takes longer than that to appear is not a screenshot problem: watch for it with ` +
325
338
  `\`gipity page eval <url> --wait-for '<selector>' --wait-timeout 30000\` (a wider budget), then capture it.`));
326
339
  }
@@ -342,7 +355,7 @@ export const pageScreenshotCommand = new Command('screenshot')
342
355
  // pair is a mis-invocation worth one precise line, not a range error.
343
356
  if (opts.width !== undefined || opts.height !== undefined) {
344
357
  if (opts.width === undefined || opts.height === undefined) {
345
- pageScreenshotCommand.error('error: --width and --height go together (both in px, equivalent to --viewport WxH) — ' +
358
+ pageScreenshotCommand.error('error: --width and --height go together (both in px, equivalent to --viewport WxH): ' +
346
359
  'or use a preset like --device mobile for a real handset (touch events, mobile user-agent, DPR)');
347
360
  }
348
361
  if (!/^\d+$/.test(String(opts.width)) || !/^\d+$/.test(String(opts.height))) {
@@ -353,7 +366,7 @@ export const pageScreenshotCommand = new Command('screenshot')
353
366
  // renders its desktop variant. Say so once, on the path where the caller
354
367
  // was clearly after a phone.
355
368
  if (parseInt(String(opts.width), 10) <= 500) {
356
- console.error(muted('Tip: --device mobile emulates a real handset (touch events, mobile user-agent, DPR) — a raw viewport only resizes the window.'));
369
+ console.error(muted('Tip: --device mobile emulates a real handset (touch events, mobile user-agent, DPR): a raw viewport only resizes the window.'));
357
370
  }
358
371
  }
359
372
  const customViewports = [
@@ -369,16 +382,12 @@ export const pageScreenshotCommand = new Command('screenshot')
369
382
  // Server defaults to 1280×720 when viewports is omitted - don't send it in
370
383
  // the no-flag case so the filename stays unsuffixed (no viewport segment).
371
384
  const userSpecifiedViewports = customViewports.length > 0;
372
- // Filenames are decided before the request so the server can persist the
373
- // captures to the project VFS under the SAME names the local files get —
374
- // the local screenshots/ dir and the VFS screenshot history stay 1:1 and
375
- // sync reconciles them by content hash instead of duplicating.
376
385
  const slug = slugFromUrl(url);
377
386
  const ts = timestampSlug();
378
387
  const shotName = (vp) => defaultFilename(slug, ts, vp && userSpecifiedViewports ? dimSuffix(vp) : undefined);
379
388
  const names = userSpecifiedViewports ? customViewports.map(shotName) : [shotName()];
380
389
  const projectGuid = getConfig()?.projectGuid;
381
- const save = !opts.ephemeral && projectGuid ? { project_guid: projectGuid, names } : undefined;
390
+ const outputArg = opts.output ?? OUTPUT_ALIAS_FLAGS.map((f) => opts[f.slice(2)]).find(Boolean);
382
391
  // The webcam frame is hosted in the project's public file store for the
383
392
  // browser container to fetch, so it needs a linked project. Validate the
384
393
  // file locally first — a bad file type costs one instant error, not an
@@ -387,7 +396,7 @@ export const pageScreenshotCommand = new Command('screenshot')
387
396
  if (opts.camera) {
388
397
  assertCameraFile(opts.camera);
389
398
  if (!projectGuid)
390
- throw new Error('--camera needs a linked project (the frame is hosted for the browser to fetch) — run `gipity link` first.');
399
+ throw new Error('--camera needs a linked project (the frame is hosted for the browser to fetch): run `gipity link` first.');
391
400
  console.log(muted(`Hosting camera feed ${opts.camera}...`));
392
401
  camera = await uploadCameraFeed(projectGuid, opts.camera);
393
402
  }
@@ -412,7 +421,6 @@ export const pageScreenshotCommand = new Command('screenshot')
412
421
  ...(camera ? { cameraUrl: camera.url } : {}),
413
422
  ...(opts.auth ? { auth: true } : {}),
414
423
  ...(preCapture ? { action: preCapture } : {}),
415
- ...(save ? { save } : {}),
416
424
  };
417
425
  // Load + render across viewports runs server-side and can take many
418
426
  // seconds; animate the wait, then clear so the saved-files summary is the
@@ -439,7 +447,7 @@ export const pageScreenshotCommand = new Command('screenshot')
439
447
  await deleteFixture(projectGuid, camera.guid);
440
448
  }
441
449
  catch (err) {
442
- console.error(warning(`⚠ Could not auto-delete camera feed "${camera.name}" (${camera.guid}) — still hosted at ${camera.url}: ${err.message}`));
450
+ console.error(warning(`⚠ Could not auto-delete camera feed "${camera.name}" (${camera.guid}): still hosted at ${camera.url}: ${err.message}`));
443
451
  }
444
452
  }
445
453
  }
@@ -458,19 +466,19 @@ export const pageScreenshotCommand = new Command('screenshot')
458
466
  const usedStems = new Set();
459
467
  const outputPath = (i) => {
460
468
  if (pngs.length === 1)
461
- return opts.output;
469
+ return outputArg;
462
470
  let suffix = viewportLabels[i] ?? dimSuffix(meta.screenshots[i].viewport);
463
471
  while (usedStems.has(suffix))
464
472
  suffix += `-${i + 1}`;
465
473
  usedStems.add(suffix);
466
- return stemPath(opts.output, suffix);
474
+ return stemPath(outputArg, suffix);
467
475
  };
468
476
  for (let i = 0; i < pngs.length; i++) {
469
- const target = opts.output
477
+ const target = outputArg
470
478
  ? outputPath(i)
471
479
  : join(dir, names[i] ?? shotName(meta.screenshots[i].viewport));
472
480
  // Create the target's parent dir so a `-o` path under a not-yet-existing
473
- // directory (e.g. .gipity/screenshots/home.png) writes cleanly instead of
481
+ // directory (e.g. docs/shots/home.png) writes cleanly instead of
474
482
  // failing with a raw ENOENT and forcing a manual `mkdir -p`.
475
483
  mkdirSync(dirname(target), { recursive: true });
476
484
  writeFileSync(target, pngs[i].buffer);
@@ -501,22 +509,10 @@ export const pageScreenshotCommand = new Command('screenshot')
501
509
  size_bytes: s.screenshotSizeBytes,
502
510
  full_page: meta.full,
503
511
  phase: s.phase,
504
- ...(s.vfs ? { gipity: s.vfs } : {}),
505
512
  })),
506
513
  }));
507
514
  return;
508
515
  }
509
- /** One-line VFS-history status for a screenshot ("saved to Gipity" or why not). */
510
- const printVfsLine = (s) => {
511
- if (!s.vfs)
512
- return;
513
- if ('error' in s.vfs) {
514
- console.log(`${warning('⚠ Gipity save failed:')} ${s.vfs.error} ${muted('(local file is fine)')}`);
515
- }
516
- else {
517
- console.log(`${label('Gipity history')} ${s.vfs.path} ${muted('(synced, not deployed)')}`);
518
- }
519
- };
520
516
  if (meta.screenshots.length === 1) {
521
517
  const s = meta.screenshots[0];
522
518
  console.log(`${brand('Screenshot')} ${bold(url)}`);
@@ -537,7 +533,6 @@ export const pageScreenshotCommand = new Command('screenshot')
537
533
  if (s.width && s.height)
538
534
  console.log(`${label('Screenshot dims')} ${s.width} × ${s.height}`);
539
535
  console.log(`${label('Screenshot file')} ${success(savedFiles[0])}`);
540
- printVfsLine(s);
541
536
  return;
542
537
  }
543
538
  console.log(`${brand('Loading')} ${bold(url)} ${muted(`once → ${meta.screenshots.length} viewports`)}`);
@@ -554,20 +549,21 @@ export const pageScreenshotCommand = new Command('screenshot')
554
549
  for (let i = 0; i < meta.screenshots.length; i++) {
555
550
  const s = meta.screenshots[i];
556
551
  const dims = `${s.viewport.width}×${s.viewport.height}${s.viewport.deviceScaleFactor > 1 ? ` @${s.viewport.deviceScaleFactor}x` : ''}`;
557
- const deviceTag = s.viewport.device ? muted(` — ${s.viewport.device}, touch`) : '';
552
+ const deviceTag = s.viewport.device ? muted(` (${s.viewport.device}, touch)`) : '';
558
553
  console.log(`\n${brand('@ ' + dims)}${deviceTag}`);
559
554
  const sizePart = formatSize(s.screenshotSizeBytes) + (meta.full ? ' (full page)' : '');
560
555
  console.log(`${label('Screenshot size')} ${sizePart}`);
561
556
  if (s.width && s.height)
562
557
  console.log(`${label('Screenshot dims')} ${s.width} × ${s.height}`);
563
558
  console.log(`${label('Screenshot file')} ${success(savedFiles[i])}`);
564
- printVfsLine(s);
565
559
  }
566
560
  }));
567
561
  // Register the JS-intent guesses as hidden aliases for --action (value-taking,
568
562
  // so they capture the script) — the action folds them into the pre-capture body.
569
563
  for (const f of ACTION_ALIAS_FLAGS)
570
564
  pageScreenshotCommand.addOption(new Option(`${f} <js>`, 'Alias for --action').hideHelp());
565
+ for (const f of OUTPUT_ALIAS_FLAGS)
566
+ pageScreenshotCommand.addOption(new Option(`${f} <file>`, 'Alias for -o/--output').hideHelp());
571
567
  // `screenshot` captures the page AFTER load + settle (+ optional --wait-for gate
572
568
  // and --action). There is no scroll-to-a-position lever (agents reach for
573
569
  // --scroll and get an unknown-option detour) — but `--full` does walk the page
@@ -578,23 +574,24 @@ for (const f of ACTION_ALIAS_FLAGS)
578
574
  // --full + crop covers off-screen regions; `page eval` reads data, no picture.
579
575
  pageScreenshotCommand.addHelpText('after', `
580
576
  Examples:
581
- gipity page screenshot "https://dev.gipity.ai/me/app/"
577
+ gipity page screenshot "https://dev.gipity.ai/me/app/" # -> tmp/screenshots/ (scratch: never synced or deployed)
578
+ gipity page screenshot "https://dev.gipity.ai/me/app/" -o docs/home.png # keep it (docs/ syncs, never deploys)
582
579
  gipity page screenshot "https://dev.gipity.ai/me/app/" --full # whole scrollable page (scroll-reveal sections triggered)
583
580
  gipity page screenshot "https://dev.gipity.ai/me/app/" --device mobile,desktop
584
581
  gipity page screenshot "https://dev.gipity.ai/me/app/" \\
585
582
  --action "document.getElementById('play').click()" # capture an in-game frame
586
583
  # Camera / vision app: play a real frame in as the webcam and shoot once the app
587
- # says it's ready — same --camera / --wait-for flags as 'page eval', no guessed delay:
584
+ # says it's ready: same --camera / --wait-for flags as 'page eval', no guessed delay:
588
585
  gipity page screenshot "https://dev.gipity.ai/me/app/" --camera fist.png \\
589
586
  --wait-for '[data-vision="ready"]'
590
587
 
591
588
  Waiting for the page to reach a state before the shot?
592
589
  --wait-for '<selector>' gates the capture on the app's own signal (deterministic).
593
- Reach for --wait <ms> only when there is nothing to gate on — a guessed duration
590
+ Reach for --wait <ms> only when there is nothing to gate on: a guessed duration
594
591
  either shoots too early or wastes the difference.
595
592
 
596
593
  Capturing a state that needs an interaction (start a game, open a menu, dismiss a modal)?
597
- Use --action to run JS in the page before the shot — it fires after the wait
594
+ Use --action to run JS in the page before the shot: it fires after the wait
598
595
  (and after any --wait-for gate), then settles again so the result has painted. For
599
596
  a multi-step driver (click, wait, click) pipe it as a heredoc with --file - (same
600
597
  as 'page eval') instead of cramming it into one inline string:
@@ -610,6 +607,6 @@ Capturing a state that needs an interaction (start a game, open a menu, dismiss
610
607
  Capturing an off-screen region or reading element data?
611
608
  • --full captures the ENTIRE scrollable page (then crop to the region).
612
609
  • 'gipity page eval <url> "<expr>"' reads any (even off-screen) element's
613
- data/state/rect without a picture — e.g. read the chart's bar values
610
+ data/state/rect without a picture: e.g. read the chart's bar values
614
611
  directly instead of screenshotting the slide.`);
615
612
  //# sourceMappingURL=page-screenshot.js.map
@@ -18,6 +18,104 @@ async function inspectClient(url, waitMs, i) {
18
18
  }
19
19
  const MAX_HOLD_MS = 15_000; // keep each in-page await under the ~20s browser action timeout
20
20
  const MIN_HOLD_MS = 1_000;
21
+ // ── lifecycle actions (--at) ───────────────────────────────────────────────
22
+ // Freeze, hide, or take one client offline partway through the hold window, so
23
+ // an app can test what its peers do when a phone locks (host handoff) instead
24
+ // of only a clean leave. The server applies them in the browser over CDP; the
25
+ // CLI parses and validates the specs and shows the timeline.
26
+ export const LIFECYCLE_ACTIONS = ['freeze', 'wake', 'hide', 'show', 'offline', 'online'];
27
+ /** Sample value recorded for an observe slot the page's JS never got to run
28
+ * (it was frozen, or blocked, when the sample was due). */
29
+ export const PAUSED_SAMPLE = '(paused)';
30
+ /** How late a sample may run before it counts as slept through. */
31
+ export const PAUSE_SLACK_MS = 1500;
32
+ const AT_SYNTAX = '"<label|index>:<action>@<ms>", e.g. --at host:freeze@5000';
33
+ /** Parse the repeatable --at specs into per-client step lists (index-aligned
34
+ * with `labels`, one entry per client). A target matches every client with
35
+ * that label (so `phone:hide@3000` hides every phone), else a 0-based index.
36
+ * Throws a caller-facing error on bad syntax, an unknown client or action, a
37
+ * time outside the hold window, or an impossible sequence (wake without a
38
+ * freeze, ...). The server re-checks the sequence; this is the early error. */
39
+ export function parseAtSpecs(specs, labels, holdMs) {
40
+ const perClient = labels.map(() => []);
41
+ for (const raw of specs) {
42
+ const m = /^\s*([^:@\s]+)\s*:\s*([A-Za-z]+)\s*@\s*(\d+)\s*(?:ms)?\s*$/.exec(raw);
43
+ if (!m)
44
+ throw new Error(`--at "${raw}": expected ${AT_SYNTAX}`);
45
+ const [, target, rawAction, rawMs] = m;
46
+ const action = rawAction.toLowerCase();
47
+ if (!LIFECYCLE_ACTIONS.includes(action)) {
48
+ throw new Error(`--at "${raw}": unknown action "${rawAction}". Use one of: ${LIFECYCLE_ACTIONS.join(', ')}`);
49
+ }
50
+ const atMs = parseInt(rawMs, 10);
51
+ if (atMs >= holdMs) {
52
+ throw new Error(`--at "${raw}": ${atMs}ms is past the end of the ${holdMs}ms --hold window. Actions must happen inside it (raise --hold, max ${MAX_HOLD_MS}ms, or move the action earlier).`);
53
+ }
54
+ let targets = labels.flatMap((l, i) => (l === target ? [i] : []));
55
+ if (targets.length === 0 && /^\d+$/.test(target) && Number(target) < labels.length)
56
+ targets = [Number(target)];
57
+ if (targets.length === 0) {
58
+ throw new Error(`--at "${raw}": no client "${target}". Use a label (${[...new Set(labels)].join(', ')}) or an index 0-${labels.length - 1}.`);
59
+ }
60
+ for (const i of targets)
61
+ perClient[i].push({ atMs, action });
62
+ }
63
+ perClient.forEach((steps, i) => {
64
+ steps.sort((a, b) => a.atMs - b.atMs);
65
+ const err = sequenceError(steps);
66
+ if (err)
67
+ throw new Error(`--at for client ${i} (${labels[i]}): ${err}`);
68
+ });
69
+ return perClient;
70
+ }
71
+ /** First impossible transition in a time-ordered step list, or null. Freeze
72
+ * already hides the page (as a locking phone does), so hide/freeze don't stack. */
73
+ function sequenceError(steps) {
74
+ const on = { frozen: false, hidden: false, offline: false };
75
+ for (const { action, atMs } of steps) {
76
+ const at = `${action}@${atMs}`;
77
+ if (action === 'freeze') {
78
+ if (on.frozen)
79
+ return `${at}: already frozen`;
80
+ if (on.hidden)
81
+ return `${at}: the page is hidden; show it first (freeze hides the page on its own)`;
82
+ on.frozen = true;
83
+ }
84
+ else if (action === 'wake') {
85
+ if (!on.frozen)
86
+ return `${at}: not frozen (wake undoes freeze)`;
87
+ on.frozen = false;
88
+ }
89
+ else if (action === 'hide') {
90
+ if (on.hidden || on.frozen)
91
+ return `${at}: already ${on.frozen ? 'frozen, which hides the page' : 'hidden'}`;
92
+ on.hidden = true;
93
+ }
94
+ else if (action === 'show') {
95
+ if (!on.hidden)
96
+ return `${at}: not hidden (show undoes hide)`;
97
+ on.hidden = false;
98
+ }
99
+ else if (action === 'offline') {
100
+ if (on.offline)
101
+ return `${at}: already offline`;
102
+ on.offline = true;
103
+ }
104
+ else {
105
+ if (!on.offline)
106
+ return `${at}: not offline (online undoes offline)`;
107
+ on.offline = false;
108
+ }
109
+ }
110
+ return null;
111
+ }
112
+ function fmtTimeline(events) {
113
+ return events.map((e) => {
114
+ const when = e.appliedMs === null ? `@${e.atMs}ms` : `+${(e.appliedMs / 1000).toFixed(1)}s`;
115
+ const note = e.error ? clrError(` (failed: ${e.error})`) : e.auto ? muted(' (auto, end of hold)') : '';
116
+ return `${e.action} ${when}${note}`;
117
+ }).join(' → ');
118
+ }
21
119
  /** Splice per-client values into a user string (URL, --action, or --observe).
22
120
  * `{{label}}` → the client's label, `{{i}}` → its 0-based index. Plain string
23
121
  * replace (no regex) so the string's own characters are never treated as
@@ -43,12 +141,12 @@ function unknownTokens(...strings) {
43
141
  function warnUnknownTokens(unknown) {
44
142
  if (unknown.length === 0)
45
143
  return;
46
- console.error(warning(`⚠ Unrecognized placeholder ${unknown.join(', ')} left as-is — only {{i}} (0-based client index) and {{label}} are substituted per client. Set per-client values with --labels and reference them as {{label}}.`));
144
+ console.error(warning(`⚠ Unrecognized placeholder ${unknown.join(', ')} left as-is: only {{i}} (0-based client index) and {{label}} are substituted per client. Set per-client values with --labels and reference them as {{label}}.`));
47
145
  }
48
146
  /** Build the statement-body script one client runs: do the one-time action,
49
147
  * then sample `observe` `samples` times across `holdMs`, stamping in-page
50
148
  * start/end so the caller can confirm the clients overlapped. */
51
- function buildHarness(action, observe, label, holdMs, samples) {
149
+ export function buildHarness(action, observe, label, holdMs, samples) {
52
150
  const n = Math.max(2, samples);
53
151
  const interval = Math.max(0, Math.floor(holdMs / (n - 1)));
54
152
  const lines = [
@@ -58,11 +156,17 @@ function buildHarness(action, observe, label, holdMs, samples) {
58
156
  if (action && action.trim()) {
59
157
  lines.push(`try{ ${action} }catch(__e){ return {label:__label,startedAt:__t0,endedAt:Date.now(),samples:[],actionError:String((__e&&__e.message)||__e)}; }`);
60
158
  }
61
- lines.push(`const __s=[];`, `for(let __k=0;__k<${n};__k++){`, ` let __v; try{ __v=(${observe}); }catch(__e){ __v='ObserveError: '+String((__e&&__e.message)||__e); }`, ` __s.push(__v);`, ` if(__k<${n - 1}) await new Promise(function(r){setTimeout(r,${interval});});`, `}`, `return {label:__label,startedAt:__t0,endedAt:Date.now(),samples:__s};`);
159
+ // Samples are due on a fixed schedule from the first one. A page that could
160
+ // not run when a sample was due (frozen by --at, or blocked) records
161
+ // PAUSED_SAMPLE for each slot it reached more than PAUSE_SLACK_MS late,
162
+ // instead of a stale reading taken the moment it resumes. The slack keeps a
163
+ // hidden page's throttled (about 1/s) timers from reading as paused. The
164
+ // last slot always takes a reading.
165
+ lines.push(`const __s=[]; const __ts=Date.now();`, `for(let __k=0;__k<${n};__k++){`, ` const __w=__ts+__k*${interval}-Date.now();`, ` if(__w>0) await new Promise(function(r){setTimeout(r,__w);});`, ` if(__k<${n - 1}&&Date.now()>__ts+__k*${interval}+${PAUSE_SLACK_MS}){ __s.push(${JSON.stringify(PAUSED_SAMPLE)}); continue; }`, ` let __v; try{ __v=(${observe}); }catch(__e){ __v='ObserveError: '+String((__e&&__e.message)||__e); }`, ` __s.push(__v);`, `}`, `return {label:__label,startedAt:__t0,endedAt:Date.now(),samples:__s};`);
62
166
  return lines.join('\n');
63
167
  }
64
168
  /** Kick off and poll one client's eval job, then parse the harness payload. */
65
- async function observeClient(url, expr, i, label, settleMs, holdMs, waitForSelector) {
169
+ async function observeClient(url, expr, i, label, settleMs, holdMs, waitForSelector, lifecycle) {
66
170
  const base = { i, label, samples: [], startedAt: 0, endedAt: 0 };
67
171
  try {
68
172
  const kickoff = await post('/tools/browser/eval', {
@@ -71,6 +175,9 @@ async function observeClient(url, expr, i, label, settleMs, holdMs, waitForSelec
71
175
  waitMs: settleMs,
72
176
  waitForSelector: waitForSelector || undefined,
73
177
  waitForTimeoutMs: waitForSelector ? 5000 : undefined,
178
+ // Timed from the start of the observe window; the server restores
179
+ // anything still applied at the end of the hold so the harness finishes.
180
+ lifecycle: lifecycle?.length ? { steps: lifecycle, untilMs: holdMs } : undefined,
74
181
  });
75
182
  // Server work ≈ nav + settle + the in-page hold; pollEvalResult adds 60s headroom.
76
183
  const d = await pollEvalResult(kickoff.data.evalJobId, settleMs + holdMs);
@@ -88,13 +195,34 @@ async function observeClient(url, expr, i, label, settleMs, holdMs, waitForSelec
88
195
  if (parsed.actionError) {
89
196
  return { ...base, error: `action failed: ${parsed.actionError}` };
90
197
  }
91
- return {
198
+ const startedAt = typeof parsed.startedAt === 'number' ? parsed.startedAt : 0;
199
+ const out = {
92
200
  i,
93
201
  label: typeof parsed.label === 'string' ? parsed.label : label,
94
202
  samples: Array.isArray(parsed.samples) ? parsed.samples : [],
95
- startedAt: typeof parsed.startedAt === 'number' ? parsed.startedAt : 0,
203
+ startedAt,
96
204
  endedAt: typeof parsed.endedAt === 'number' ? parsed.endedAt : 0,
97
205
  };
206
+ if (lifecycle?.length) {
207
+ // A step that silently didn't happen would make "the handoff works" a
208
+ // false positive, so a missing or failed step fails the client.
209
+ const report = d.lifecycle;
210
+ out.lifecycle = (report?.events ?? []).map((e) => ({
211
+ action: e.action,
212
+ atMs: e.atMs,
213
+ appliedMs: typeof e.appliedAt === 'number' && startedAt > 0 ? e.appliedAt - startedAt : null,
214
+ ...(e.auto ? { auto: true } : {}),
215
+ ...(e.error ? { error: e.error } : {}),
216
+ }));
217
+ const failed = out.lifecycle.find((e) => e.error);
218
+ if (!report)
219
+ out.error = 'lifecycle actions were not applied (the server did not report them; it may need updating)';
220
+ else if (report.error)
221
+ out.error = `lifecycle actions failed: ${report.error}`;
222
+ else if (failed)
223
+ out.error = `lifecycle ${failed.action}@${failed.atMs} failed: ${failed.error}`;
224
+ }
225
+ return out;
98
226
  }
99
227
  catch (err) {
100
228
  return { ...base, error: err instanceof Error ? err.message : String(err) };
@@ -111,6 +239,22 @@ function overlapMs(results) {
111
239
  const end = Math.min(...live.map((r) => r.endedAt));
112
240
  return Math.max(0, end - start);
113
241
  }
242
+ /** One explanation for an --observe expression that threw, printed once under
243
+ * the client blocks. The bare `ObserveError: Cannot read properties of null`
244
+ * sample reads like a quirk of the harness, so it got waved off as "the observe
245
+ * context is different" when it was a real selector (or app) bug on the live
246
+ * page. Exported for tests. */
247
+ export function observeErrorHint(results) {
248
+ const thrown = results.flatMap((r) => r.samples)
249
+ .find((v) => typeof v === 'string' && v.startsWith('ObserveError:'));
250
+ if (!thrown)
251
+ return null;
252
+ const nullRead = /of null|of undefined/.test(thrown)
253
+ ? ' "of null" means a querySelector in it matched nothing at that moment: the element is missing, renamed, or not rendered yet.'
254
+ : '';
255
+ return `ObserveError = your --observe expression threw. It runs against the live deployed page, the same DOM \`page eval\` sees, so this is the page's real state, not a harness quirk.${nullRead} ` +
256
+ "Check the selector with `gipity page eval <url> \"!!document.querySelector('<selector>')\"`, or gate the run on it with --wait-for '<selector>'.";
257
+ }
114
258
  function fmtSamples(samples) {
115
259
  if (samples.length === 0)
116
260
  return muted('(no samples)');
@@ -124,7 +268,7 @@ async function runInteractive(url, observe, opts) {
124
268
  if (rawHold > MAX_HOLD_MS) {
125
269
  // Surface the clamp (to stderr, so --json stdout stays clean) instead of
126
270
  // leaving the agent to infer it from the printed "hold Nms" line.
127
- console.error(warning(`--hold ${rawHold}ms exceeds the ${MAX_HOLD_MS}ms per-client cap (each client samples inside one browser eval, bounded by the server's eval budget) — using ${MAX_HOLD_MS}ms. ` +
271
+ console.error(warning(`--hold ${rawHold}ms exceeds the ${MAX_HOLD_MS}ms per-client cap (each client samples inside one browser eval, bounded by the server's eval budget): using ${MAX_HOLD_MS}ms. ` +
128
272
  `Co-launch every role in this one command (put {{label}}/{{i}} in the URL) so all clients overlap for the whole window; a separately-started background client overlaps only the sliver of its window that lines up.`));
129
273
  }
130
274
  const samples = Math.min(30, Math.max(2, parseInt(opts.samples, 10) || 6));
@@ -135,9 +279,13 @@ async function runInteractive(url, observe, opts) {
135
279
  // (a natural guess like {{name}} or {{index}}) so it isn't sent literally to
136
280
  // every client — the silent wrong-behavior trap of identical clients.
137
281
  warnUnknownTokens(unknownTokens(url, opts.action, observe));
282
+ const atSpecs = opts.at ?? [];
283
+ const lifecycle = parseAtSpecs(atSpecs, Array.from({ length: clients }, (_, i) => labelFor(i)), hold);
138
284
  if (!opts.json) {
139
285
  console.log(`${brand('Page test')} ${muted('(interactive)')} ${bold(url)}`);
140
286
  console.log(muted(`${clients} client(s), stagger ${stagger}s, hold ${hold}ms, ${samples} samples each`));
287
+ if (atSpecs.length)
288
+ console.log(muted(`lifecycle (ms into each client's hold): ${atSpecs.map((s) => s.trim()).join(', ')}`));
141
289
  }
142
290
  const runs = [];
143
291
  for (let i = 0; i < clients; i++) {
@@ -150,7 +298,7 @@ async function runInteractive(url, observe, opts) {
150
298
  // and the overlap check still confirms they coexisted.
151
299
  const clientUrl = subst(url, labelFor(i), i);
152
300
  const expr = buildHarness(opts.action ? subst(opts.action, labelFor(i), i) : undefined, subst(observe, labelFor(i), i), labelFor(i), hold, samples);
153
- return observeClient(clientUrl, expr, i, labelFor(i), settle, hold, opts.waitFor);
301
+ return observeClient(clientUrl, expr, i, labelFor(i), settle, hold, opts.waitFor, lifecycle[i]);
154
302
  })());
155
303
  }
156
304
  const results = (await Promise.all(runs)).sort((a, b) => a.i - b.i);
@@ -160,6 +308,7 @@ async function runInteractive(url, observe, opts) {
160
308
  if (opts.json) {
161
309
  console.log(JSON.stringify({
162
310
  url, mode: 'interactive', clients, stagger, hold, samples,
311
+ ...(atSpecs.length ? { at: atSpecs.map((s) => s.trim()) } : {}),
163
312
  overlapMs: ovl, overlapped, results,
164
313
  }));
165
314
  if (errored.length > 0 || (clients > 1 && !overlapped))
@@ -168,24 +317,29 @@ async function runInteractive(url, observe, opts) {
168
317
  }
169
318
  for (const r of results) {
170
319
  console.log(`\n${bold(`=== client ${r.i} (${r.label}) ===`)}`);
320
+ if (r.lifecycle?.length)
321
+ console.log(`${muted('timeline:')} ${fmtTimeline(r.lifecycle)}`);
171
322
  if (r.error) {
172
323
  console.log(clrError(`✗ ${r.error}`));
173
324
  continue;
174
325
  }
175
326
  console.log(`${muted('samples:')} ${fmtSamples(r.samples)}`);
176
327
  }
328
+ const observeHint = observeErrorHint(results);
329
+ if (observeHint)
330
+ console.log(`\n${warning(observeHint)}`);
177
331
  console.log('');
178
332
  if (errored.length > 0) {
179
333
  console.log(clrError(`⚠ ${errored.length} client(s) failed (see above)`));
180
334
  }
181
335
  if (clients < 2) {
182
- console.log(muted('Note: a single client cannot verify cross-client visibility — run with --clients 2+.'));
336
+ console.log(muted('Note: a single client cannot verify cross-client visibility: run with --clients 2+.'));
183
337
  }
184
338
  else if (overlapped) {
185
- console.log(success(`✓ all clients overlapped for ~${(ovl / 1000).toFixed(1)}s — genuine concurrency, so the readings above are trustworthy`));
339
+ console.log(success(`✓ all clients overlapped for ~${(ovl / 1000).toFixed(1)}s: genuine concurrency, so the readings above are trustworthy`));
186
340
  }
187
341
  else {
188
- console.log(clrError('⚠ clients did NOT overlap in time — each ran in isolation, so any shared-state reading here is a FALSE NEGATIVE, not proof the app is broken.'));
342
+ console.log(clrError('⚠ clients did NOT overlap in time: each ran in isolation, so any shared-state reading here is a FALSE NEGATIVE, not proof the app is broken.'));
189
343
  console.log(muted(' Likely causes: --stagger ≥ --hold, or more --clients than free browser slots (they queued). Lower --stagger / raise --hold / fewer --clients and retry.'));
190
344
  }
191
345
  if (errored.length > 0 || (clients > 1 && !overlapped))
@@ -272,13 +426,14 @@ export const pageTestCommand = new Command('test')
272
426
  .option('--hold <ms>', `Interactive: total observe window per client (${MIN_HOLD_MS}-${MAX_HOLD_MS}ms)`, '8000')
273
427
  .option('--samples <k>', 'Interactive: number of observations across the hold window (2-30)', '6')
274
428
  .option('--wait-for <selector>', 'Interactive: wait for this CSS selector before running --action (deterministic readiness gate)')
429
+ .option('--at <spec>', `Interactive: lifecycle action on one client mid-run, "<label|index>:<action>@<ms>" (ms into that client's hold window). Actions: freeze|wake (locked phone: JS stops, socket stays open), hide|show (backgrounded tab), offline|online (network drop). Repeatable; anything still applied at the end of --hold is restored.`, (v, prev = []) => [...prev, v])
275
430
  .option('--json', 'Output as JSON')
276
431
  .addHelpText('after', `
277
432
  Examples:
278
433
  # Passive: load in 3 staggered clients, flag console errors
279
434
  gipity page test "https://dev.gipity.ai/me/app/" --clients 3 --stagger 8
280
435
 
281
- # Per-client URL params: each client joins under a distinct name (Bot0, Bot1, …)
436
+ # Per-client URL params: each client joins under a distinct name (Bot0, Bot1, ...)
282
437
  gipity page test "https://dev.gipity.ai/me/app/?name=Bot{{i}}" --clients 2
283
438
 
284
439
  # Interactive: two concurrent clients each join with a name, then watch the
@@ -290,11 +445,30 @@ Examples:
290
445
 
291
446
  # Asymmetric roles in ONE invocation: {{label}} in the URL routes client 0 to
292
447
  # host and client 1 to join. They overlap in time (verified), so the joiner
293
- # observes the live state the host is driving — no background-process dance.
448
+ # observes the live state the host is driving: no background-process dance.
294
449
  gipity page test "https://dev.gipity.ai/me/app/?test-action={{label}}" --clients 2 \\
295
450
  --labels host,join \\
296
- --observe "document.querySelector('[data-screen]')?.dataset.screen"`)
451
+ --observe "document.querySelector('[data-screen]')?.dataset.screen"
452
+
453
+ # Host handoff: lock the host's phone 5s in (its JS stops, its socket stays
454
+ # open, so nobody sees a leave) and watch who the phones think is host.
455
+ gipity page test "https://dev.gipity.ai/me/app/?role={{label}}" --clients 3 \\
456
+ --labels host,phone,phone --hold 15000 --at host:freeze@5000 --at host:wake@12000 \\
457
+ --observe "window.game?.hostId"
458
+
459
+ freeze: the page's JS stops (timers, rendering, message handlers) and it fires
460
+ visibilitychange (hidden) then freeze, like a phone locking. Its WebSocket stays
461
+ open, so the server sees no leave. On wake the page resumes and Chrome drops that
462
+ socket (close code 1006), so the app's reconnect path runs. Samples due while a
463
+ client was frozen read (paused).
464
+ hide: backgrounded tab (document.hidden, rAF stops, timers throttle to ~1/s); JS
465
+ and the socket keep running.
466
+ offline: navigator.onLine false, new requests fail, and an open WebSocket stalls
467
+ without closing; online delivers the held traffic.`)
297
468
  .action((url, opts) => run('Page test', async () => {
469
+ if (opts.at?.length && !opts.observe) {
470
+ throw new Error('--at needs interactive mode: add --observe "<expr>" to watch what the other clients do while one is frozen, hidden, or offline');
471
+ }
298
472
  if (opts.observe) {
299
473
  await runInteractive(url, opts.observe, opts);
300
474
  }