@nexum-hub/browser 0.0.3-next.8 → 0.0.4-next.25

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 (50) hide show
  1. package/browser-extension/build.mjs +4 -1
  2. package/browser-extension/connection.js +41 -5
  3. package/browser-extension/dist/development/connection.js +41 -5
  4. package/browser-extension/dist/development/frames.js +11 -0
  5. package/browser-extension/dist/development/manifest.json +2 -2
  6. package/browser-extension/dist/development/page.js +115 -8
  7. package/browser-extension/dist/development/profile.js +1 -1
  8. package/browser-extension/dist/development/router.js +468 -46
  9. package/browser-extension/dist/development/visual.js +145 -88
  10. package/browser-extension/dist/production/connection.js +41 -5
  11. package/browser-extension/dist/production/frames.js +11 -0
  12. package/browser-extension/dist/production/manifest.json +2 -2
  13. package/browser-extension/dist/production/page.js +115 -8
  14. package/browser-extension/dist/production/profile.js +1 -1
  15. package/browser-extension/dist/production/router.js +468 -46
  16. package/browser-extension/dist/production/visual.js +145 -88
  17. package/browser-extension/frames.js +11 -0
  18. package/browser-extension/page.js +115 -8
  19. package/browser-extension/release-info.json +6 -4
  20. package/browser-extension/router.js +468 -46
  21. package/browser-extension/visual.js +145 -88
  22. package/dist/client/index.js +25 -1
  23. package/dist/client/routes.js +5 -1
  24. package/dist/client/types.d.ts +20 -0
  25. package/dist/extension/assets.d.ts +1 -0
  26. package/dist/extension/assets.js +3 -1
  27. package/dist/extension/index.js +6 -6
  28. package/dist/extension/scope.d.ts +3 -1
  29. package/dist/extension/scope.js +19 -3
  30. package/dist/extension/service.d.ts +2 -0
  31. package/dist/extension/service.js +18 -8
  32. package/docs/README.md +6 -8
  33. package/docs/connection.md +1 -1
  34. package/docs/usage.md +51 -6
  35. package/implementation.json +1 -1
  36. package/instructions/README.md +5 -7
  37. package/package.json +5 -4
  38. package/skills/browser-control/SKILL.md +11 -5
  39. package/dist/client/index.js.map +0 -1
  40. package/dist/client/routes.js.map +0 -1
  41. package/dist/client/serialize.js.map +0 -1
  42. package/dist/client/types.js.map +0 -1
  43. package/dist/extension/artifacts.js.map +0 -1
  44. package/dist/extension/assets.js.map +0 -1
  45. package/dist/extension/batch.js.map +0 -1
  46. package/dist/extension/files.js.map +0 -1
  47. package/dist/extension/index.js.map +0 -1
  48. package/dist/extension/protocol.js.map +0 -1
  49. package/dist/extension/scope.js.map +0 -1
  50. package/dist/extension/service.js.map +0 -1
@@ -56,6 +56,9 @@ export async function buildExtensions(
56
56
  for (const [profile, info] of Object.entries(release.profiles)) {
57
57
  if (extensionId(info.key) !== info.extensionId || info.profile !== profile)
58
58
  throw new Error("Invalid fixed plugin identity.");
59
+ const start = profile === "development" ? 29030 : 29040;
60
+ if (info.port !== start || info.portEnd !== start + 9)
61
+ throw new Error("Invalid fixed plugin port range.");
59
62
  const target = path.join(destination, profile);
60
63
  await mkdir(target, { recursive: true });
61
64
  for (const name of files)
@@ -94,7 +97,7 @@ export async function buildExtensions(
94
97
  ],
95
98
  host_permissions: ["http://*/*", "https://*/*"],
96
99
  content_security_policy: {
97
- extension_pages: `script-src 'self'; object-src 'self'; connect-src ws://127.0.0.1:${info.port};`,
100
+ extension_pages: `script-src 'self'; object-src 'self'; connect-src ${Array.from({ length: info.portEnd - info.port + 1 }, (_, i) => `ws://127.0.0.1:${info.port + i}`).join(" ")};`,
98
101
  },
99
102
  },
100
103
  null,
@@ -38,12 +38,17 @@ export function createExtensionConnection({
38
38
  "PROFILE_MISMATCH",
39
39
  "Use a dedicated production or development extension build.",
40
40
  );
41
- const expectedUrl = `ws://127.0.0.1:${profile === "production" ? 43831 : 43832}/nexum-browser/v1`;
41
+ const firstPort = profile === "production" ? 29040 : 29030;
42
+ const allowedUrls = Array.from(
43
+ { length: 10 },
44
+ (_, index) => `ws://127.0.0.1:${firstPort + index}/nexum-browser/v1`,
45
+ );
42
46
  requireValue(
43
- url === undefined || url === expectedUrl,
47
+ url === undefined || allowedUrls.includes(url),
44
48
  "PROFILE_MISMATCH",
45
- "The extension cannot cross its fixed profile endpoint.",
49
+ "The extension cannot connect outside its profile's port range.",
46
50
  );
51
+ const endpoints = url === undefined ? allowedUrls : [url];
47
52
  let started = false,
48
53
  stopped = false,
49
54
  socket,
@@ -52,6 +57,10 @@ export function createExtensionConnection({
52
57
  initialize,
53
58
  reconnectTimer,
54
59
  keepAlive,
60
+ probeTimer,
61
+ preferredUrl,
62
+ socketUrl,
63
+ scanIndex = 0,
55
64
  reconnectAttempt = 0,
56
65
  attemptSequence = 0,
57
66
  lastMessage = 0,
@@ -296,8 +305,11 @@ export function createExtensionConnection({
296
305
  };
297
306
  const disconnected = async (expected) => {
298
307
  if (expected !== socket) return;
308
+ const wasReady = Boolean(ready);
299
309
  socket = undefined;
300
310
  ready = undefined;
311
+ clearTimeout(probeTimer);
312
+ probeTimer = undefined;
301
313
  clearInterval(keepAlive);
302
314
  keepAlive = undefined;
303
315
  status(false);
@@ -314,7 +326,17 @@ export function createExtensionConnection({
314
326
  );
315
327
  inbox.discard();
316
328
  for (const lease of leases.values()) void closeLease(lease).catch(() => {});
317
- if (!stopped) schedule();
329
+ if (!stopped) {
330
+ if (wasReady) {
331
+ scanIndex = 0;
332
+ schedule();
333
+ } else if (++scanIndex < endpoints.length) {
334
+ queueMicrotask(() => void connect().catch(schedule));
335
+ } else {
336
+ scanIndex = 0;
337
+ schedule();
338
+ }
339
+ }
318
340
  };
319
341
  const schedule = () => {
320
342
  if (stopped || reconnectTimer) return;
@@ -491,6 +513,10 @@ export function createExtensionConnection({
491
513
  "The plugin and package use incompatible wire budgets.",
492
514
  );
493
515
  ready = Object.freeze(message);
516
+ preferredUrl = socketUrl;
517
+ scanIndex = 0;
518
+ clearTimeout(probeTimer);
519
+ probeTimer = undefined;
494
520
  router.bind(message);
495
521
  reconnectAttempt = 0;
496
522
  status(true);
@@ -714,8 +740,16 @@ export function createExtensionConnection({
714
740
  // Recheck after initialization. A socket, including one still closing,
715
741
  // remains the current owner until its close handler starts cleanup.
716
742
  if (stopped || socket) return;
717
- const expected = new Socket(expectedUrl);
743
+ const choices = preferredUrl
744
+ ? [preferredUrl, ...endpoints.filter((candidate) => candidate !== preferredUrl)]
745
+ : endpoints;
746
+ socketUrl = choices[scanIndex];
747
+ const expected = new Socket(socketUrl);
718
748
  socket = expected;
749
+ probeTimer = setTimeout(() => {
750
+ if (expected === socket && !ready && expected.readyState !== Socket.CLOSED)
751
+ expected.close();
752
+ }, 3000);
719
753
  expected.binaryType = "arraybuffer";
720
754
  expected.addEventListener("open", () => {
721
755
  if (expected !== socket || stopped) {
@@ -757,6 +791,7 @@ export function createExtensionConnection({
757
791
  });
758
792
  });
759
793
  expected.addEventListener("close", () => {
794
+ if (expected === socket) clearTimeout(probeTimer);
760
795
  void disconnected(expected).catch(() => schedule());
761
796
  });
762
797
  expected.addEventListener("error", () => {
@@ -854,6 +889,7 @@ export function createExtensionConnection({
854
889
  if (stopped) return;
855
890
  stopped = true;
856
891
  clearTimeout(reconnectTimer);
892
+ clearTimeout(probeTimer);
857
893
  clearInterval(keepAlive);
858
894
  for (const remove of listeners.splice(0)) remove();
859
895
  for (const action of actions.values())
@@ -38,12 +38,17 @@ export function createExtensionConnection({
38
38
  "PROFILE_MISMATCH",
39
39
  "Use a dedicated production or development extension build.",
40
40
  );
41
- const expectedUrl = `ws://127.0.0.1:${profile === "production" ? 43831 : 43832}/nexum-browser/v1`;
41
+ const firstPort = profile === "production" ? 29040 : 29030;
42
+ const allowedUrls = Array.from(
43
+ { length: 10 },
44
+ (_, index) => `ws://127.0.0.1:${firstPort + index}/nexum-browser/v1`,
45
+ );
42
46
  requireValue(
43
- url === undefined || url === expectedUrl,
47
+ url === undefined || allowedUrls.includes(url),
44
48
  "PROFILE_MISMATCH",
45
- "The extension cannot cross its fixed profile endpoint.",
49
+ "The extension cannot connect outside its profile's port range.",
46
50
  );
51
+ const endpoints = url === undefined ? allowedUrls : [url];
47
52
  let started = false,
48
53
  stopped = false,
49
54
  socket,
@@ -52,6 +57,10 @@ export function createExtensionConnection({
52
57
  initialize,
53
58
  reconnectTimer,
54
59
  keepAlive,
60
+ probeTimer,
61
+ preferredUrl,
62
+ socketUrl,
63
+ scanIndex = 0,
55
64
  reconnectAttempt = 0,
56
65
  attemptSequence = 0,
57
66
  lastMessage = 0,
@@ -296,8 +305,11 @@ export function createExtensionConnection({
296
305
  };
297
306
  const disconnected = async (expected) => {
298
307
  if (expected !== socket) return;
308
+ const wasReady = Boolean(ready);
299
309
  socket = undefined;
300
310
  ready = undefined;
311
+ clearTimeout(probeTimer);
312
+ probeTimer = undefined;
301
313
  clearInterval(keepAlive);
302
314
  keepAlive = undefined;
303
315
  status(false);
@@ -314,7 +326,17 @@ export function createExtensionConnection({
314
326
  );
315
327
  inbox.discard();
316
328
  for (const lease of leases.values()) void closeLease(lease).catch(() => {});
317
- if (!stopped) schedule();
329
+ if (!stopped) {
330
+ if (wasReady) {
331
+ scanIndex = 0;
332
+ schedule();
333
+ } else if (++scanIndex < endpoints.length) {
334
+ queueMicrotask(() => void connect().catch(schedule));
335
+ } else {
336
+ scanIndex = 0;
337
+ schedule();
338
+ }
339
+ }
318
340
  };
319
341
  const schedule = () => {
320
342
  if (stopped || reconnectTimer) return;
@@ -491,6 +513,10 @@ export function createExtensionConnection({
491
513
  "The plugin and package use incompatible wire budgets.",
492
514
  );
493
515
  ready = Object.freeze(message);
516
+ preferredUrl = socketUrl;
517
+ scanIndex = 0;
518
+ clearTimeout(probeTimer);
519
+ probeTimer = undefined;
494
520
  router.bind(message);
495
521
  reconnectAttempt = 0;
496
522
  status(true);
@@ -714,8 +740,16 @@ export function createExtensionConnection({
714
740
  // Recheck after initialization. A socket, including one still closing,
715
741
  // remains the current owner until its close handler starts cleanup.
716
742
  if (stopped || socket) return;
717
- const expected = new Socket(expectedUrl);
743
+ const choices = preferredUrl
744
+ ? [preferredUrl, ...endpoints.filter((candidate) => candidate !== preferredUrl)]
745
+ : endpoints;
746
+ socketUrl = choices[scanIndex];
747
+ const expected = new Socket(socketUrl);
718
748
  socket = expected;
749
+ probeTimer = setTimeout(() => {
750
+ if (expected === socket && !ready && expected.readyState !== Socket.CLOSED)
751
+ expected.close();
752
+ }, 3000);
719
753
  expected.binaryType = "arraybuffer";
720
754
  expected.addEventListener("open", () => {
721
755
  if (expected !== socket || stopped) {
@@ -757,6 +791,7 @@ export function createExtensionConnection({
757
791
  });
758
792
  });
759
793
  expected.addEventListener("close", () => {
794
+ if (expected === socket) clearTimeout(probeTimer);
760
795
  void disconnected(expected).catch(() => schedule());
761
796
  });
762
797
  expected.addEventListener("error", () => {
@@ -854,6 +889,7 @@ export function createExtensionConnection({
854
889
  if (stopped) return;
855
890
  stopped = true;
856
891
  clearTimeout(reconnectTimer);
892
+ clearTimeout(probeTimer);
857
893
  clearInterval(keepAlive);
858
894
  for (const remove of listeners.splice(0)) remove();
859
895
  for (const action of actions.values())
@@ -150,6 +150,14 @@ export async function framePage(ctx, payload, selectors, execute) {
150
150
  ctx.router.noteFrameParent(ctx, node.node.frameId, frameId);
151
151
  frameId = node.node.frameId;
152
152
  }
153
+ // A frame may be replaced between hit-testing and arming the input
154
+ // receipt. Never transfer the receipt to a different frame by selector.
155
+ if (payload.expectedFrameId)
156
+ requireValue(
157
+ payload.expectedFrameId === frameId,
158
+ "STALE_REF",
159
+ "The input frame changed after its native target was observed.",
160
+ );
153
161
  const input = {
154
162
  ...payload,
155
163
  framePath: [],
@@ -179,6 +187,7 @@ export async function framePage(ctx, payload, selectors, execute) {
179
187
  if (!result.ok)
180
188
  throw new BrowserActionError(result.error.code, result.error.message);
181
189
  if (input.command === "resolve" && result.value?.rect) {
190
+ const framePoint = { ...result.value.point };
182
191
  // scrollIntoView in the resolved descendant can scroll every native ancestor.
183
192
  // Coordinates read during traversal are no longer an observation of this input target.
184
193
  for (const owner of owners) {
@@ -243,6 +252,8 @@ export async function framePage(ctx, payload, selectors, execute) {
243
252
  }
244
253
  result.value.point = point;
245
254
  result.value.rect = mappedRect(result.value.rect, owners);
255
+ result.value.framePoint = framePoint;
256
+ result.value.frameId = frameId;
246
257
  }
247
258
  if (input.command === "elementInfo" && Array.isArray(result.value))
248
259
  for (const entry of result.value)
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "manifest_version": 3,
3
3
  "name": "Nexum browser (development)",
4
- "version": "0.0.3",
4
+ "version": "0.0.4",
5
5
  "key": "MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAtjImAZgqOH69mQAmDly9MLjCACeZs7MmPAegDja+g/LJ71H+NmGSIz6AOEMXT2bzxPtZMnoCIg8HuLgN3pIZlxtUD8p7JqLZFkjY2H9mKRf3zFnkYYuxXMiuGucXzatsyY2cnIZsmzvbU3/5pN8I6qW9gA2gVS7vZyN6IksCMtfivoVu6uFxeHenWAWtm4/CbI7jLX4a/6kW4wnEP5JBzpjXUfQrTlepU6kHQFIiMufVMmuj7/2SlF41ToXw5PyrJOR3jnusf1tKZc6EDkTJM3ueO1DwQnvWyd0b0C9ulVzssSQtY2KK8HZmiG/nXJMQ6OflXP1gmASgfPcE6BMcIQIDAQAB",
6
6
  "minimum_chrome_version": "125",
7
7
  "background": {
@@ -30,6 +30,6 @@
30
30
  "https://*/*"
31
31
  ],
32
32
  "content_security_policy": {
33
- "extension_pages": "script-src 'self'; object-src 'self'; connect-src ws://127.0.0.1:43832;"
33
+ "extension_pages": "script-src 'self'; object-src 'self'; connect-src ws://127.0.0.1:29030 ws://127.0.0.1:29031 ws://127.0.0.1:29032 ws://127.0.0.1:29033 ws://127.0.0.1:29034 ws://127.0.0.1:29035 ws://127.0.0.1:29036 ws://127.0.0.1:29037 ws://127.0.0.1:29038 ws://127.0.0.1:29039;"
34
34
  }
35
35
  }
@@ -18,6 +18,10 @@ export async function pageCommand(input) {
18
18
  state.document !== document ||
19
19
  state.version !== input.pageVersion
20
20
  ) {
21
+ for (const receipt of state?.clickReceipts?.values?.() ?? []) {
22
+ document.removeEventListener(receipt.type, receipt.listener, true);
23
+ clearTimeout(receipt.timer);
24
+ }
21
25
  state = {
22
26
  document,
23
27
  version: input.pageVersion,
@@ -27,6 +31,7 @@ export async function pageCommand(input) {
27
31
  next: 0,
28
32
  refs: new Map(),
29
33
  reverse: new WeakMap(),
34
+ clickReceipts: new Map(),
30
35
  };
31
36
  Object.defineProperty(globalThis, slot, {
32
37
  value: state,
@@ -342,11 +347,15 @@ export async function pageCommand(input) {
342
347
  "INVALID_TARGET",
343
348
  "The current element is not visible and enabled.",
344
349
  );
345
- node.scrollIntoView({
346
- block: "center",
347
- inline: "center",
348
- behavior: "instant",
349
- });
350
+ // The first preflight scrolls the target into view. Later checks must
351
+ // observe the compositor's settled position without requesting another
352
+ // scroll that can move the target after coordinates were captured.
353
+ if (!input.noScroll)
354
+ node.scrollIntoView({
355
+ block: "center",
356
+ inline: "center",
357
+ behavior: "instant",
358
+ });
350
359
  const r = rect(node),
351
360
  position = input.command === "resolve" ? input.position : undefined;
352
361
  const x = position?.x ?? r.width / 2,
@@ -415,6 +424,84 @@ export async function pageCommand(input) {
415
424
  };
416
425
  let value;
417
426
  switch (input.command) {
427
+ case "inputReceipt": {
428
+ check(
429
+ typeof input.token === "string" &&
430
+ input.token.length > 0 &&
431
+ input.token.length <= 128,
432
+ );
433
+ const receipts = (state.clickReceipts ??= new Map());
434
+ const release = (receipt) => {
435
+ if (!receipt) return;
436
+ document.removeEventListener(receipt.type, receipt.listener, true);
437
+ clearTimeout(receipt.timer);
438
+ receipts.delete(input.token);
439
+ };
440
+ if (input.action === "arm") {
441
+ check(!receipts.has(input.token) && receipts.size < 32, "QUEUE_FULL");
442
+ check(
443
+ Number.isFinite(input.x) &&
444
+ Number.isFinite(input.y) &&
445
+ [0, 1, 2].includes(input.button) &&
446
+ Number.isFinite(input.expiresAt) &&
447
+ input.expiresAt > Date.now(),
448
+ );
449
+ const type =
450
+ input.button === 2
451
+ ? "contextmenu"
452
+ : input.button === 1
453
+ ? "auxclick"
454
+ : "click";
455
+ const expected = input.expectedRef
456
+ ? getRef(input.expectedRef)
457
+ : null;
458
+ if (expected) {
459
+ const hit = document.elementFromPoint(input.x, input.y);
460
+ if (hit !== expected && !expected.contains(hit)) {
461
+ value = { armed: false, documentToken: state.token };
462
+ break;
463
+ }
464
+ }
465
+ const receipt = {
466
+ type,
467
+ count: 0,
468
+ expiresAt: input.expiresAt,
469
+ x: input.x,
470
+ y: input.y,
471
+ button: input.button,
472
+ expected,
473
+ };
474
+ receipt.listener = (event) => {
475
+ if (
476
+ event.isTrusted &&
477
+ event.button === input.button &&
478
+ (!receipt.expected ||
479
+ event.composedPath().includes(receipt.expected)) &&
480
+ Math.abs(event.clientX - input.x) <= 6 &&
481
+ Math.abs(event.clientY - input.y) <= 6
482
+ )
483
+ receipt.count++;
484
+ };
485
+ receipt.timer = setTimeout(
486
+ () => release(receipt),
487
+ Math.min(30000, input.expiresAt - Date.now()),
488
+ );
489
+ document.addEventListener(type, receipt.listener, true);
490
+ receipts.set(input.token, receipt);
491
+ value = { armed: true, documentToken: state.token };
492
+ } else if (input.action === "peek" || input.action === "drop") {
493
+ check(
494
+ !input.expectedDocumentToken ||
495
+ input.expectedDocumentToken === state.token,
496
+ "STALE_REF",
497
+ "The receipt belongs to a replaced document.",
498
+ );
499
+ const receipt = receipts.get(input.token);
500
+ value = { observed: receipt?.count ?? 0 };
501
+ if (input.action === "drop") release(receipt);
502
+ } else check(false);
503
+ break;
504
+ }
418
505
  // Core-only native bridge: the caller retains the actual remote Node(s), never serializes them.
419
506
  case "nativeNodes":
420
507
  return input.multiple ? all() : unique();
@@ -610,14 +697,27 @@ export async function pageCommand(input) {
610
697
  const node = unique(false, true),
611
698
  geometry = node && actionGeometry(node, true);
612
699
  value = geometry
613
- ? { ...describe(node), ...geometry, tagName: node.tagName }
700
+ ? {
701
+ ...describe(node),
702
+ ...geometry,
703
+ tagName: node.tagName,
704
+ documentToken: state.token,
705
+ }
614
706
  : null;
615
707
  break;
616
708
  }
617
- case "fill":
618
- setValue(unique(true), input.value ?? input.text);
709
+ case "fill": {
710
+ const node = unique(true),
711
+ expected = input.value ?? input.text;
712
+ setValue(node, expected);
713
+ check(
714
+ (node.isContentEditable ? node.textContent : node.value) === expected,
715
+ "INVALID_TARGET",
716
+ "The input did not retain the requested value.",
717
+ );
619
718
  value = null;
620
719
  break;
720
+ }
621
721
  case "focus":
622
722
  unique(true).focus();
623
723
  value = null;
@@ -652,6 +752,13 @@ export async function pageCommand(input) {
652
752
  node.dispatchEvent(new Event("input", { bubbles: true }));
653
753
  node.dispatchEvent(new Event("change", { bubbles: true }));
654
754
  value = matches.map((o) => o.value);
755
+ const actual = [...node.selectedOptions].map((o) => o.value);
756
+ check(
757
+ actual.length === value.length &&
758
+ actual.every((item) => value.includes(item)),
759
+ "INVALID_TARGET",
760
+ "The select did not retain the requested option values.",
761
+ );
655
762
  break;
656
763
  }
657
764
  case "checked": {
@@ -1,2 +1,2 @@
1
1
  export const profile="development";
2
- export const extensionVersion="0.0.3";
2
+ export const extensionVersion="0.0.4";