@nexum-hub/browser 0.0.0-stage → 0.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (100) hide show
  1. package/README.md +22 -2
  2. package/browser-extension/assets.js +654 -0
  3. package/browser-extension/build.mjs +111 -0
  4. package/browser-extension/clipboard.js +397 -0
  5. package/browser-extension/connection.js +880 -0
  6. package/browser-extension/dist/development/assets.js +654 -0
  7. package/browser-extension/dist/development/clipboard.js +397 -0
  8. package/browser-extension/dist/development/connection.js +880 -0
  9. package/browser-extension/dist/development/errors.js +106 -0
  10. package/browser-extension/dist/development/evaluate.js +160 -0
  11. package/browser-extension/dist/development/frames.js +256 -0
  12. package/browser-extension/dist/development/keyboard.js +167 -0
  13. package/browser-extension/dist/development/manifest.json +35 -0
  14. package/browser-extension/dist/development/native-node.js +85 -0
  15. package/browser-extension/dist/development/page-data.js +497 -0
  16. package/browser-extension/dist/development/page.js +772 -0
  17. package/browser-extension/dist/development/profile.js +2 -0
  18. package/browser-extension/dist/development/router.js +5961 -0
  19. package/browser-extension/dist/development/site-source.js +149 -0
  20. package/browser-extension/dist/development/transport.js +405 -0
  21. package/browser-extension/dist/development/visual.js +976 -0
  22. package/browser-extension/dist/development/worker.js +24 -0
  23. package/browser-extension/dist/production/assets.js +654 -0
  24. package/browser-extension/dist/production/clipboard.js +397 -0
  25. package/browser-extension/dist/production/connection.js +880 -0
  26. package/browser-extension/dist/production/errors.js +106 -0
  27. package/browser-extension/dist/production/evaluate.js +160 -0
  28. package/browser-extension/dist/production/frames.js +256 -0
  29. package/browser-extension/dist/production/keyboard.js +167 -0
  30. package/browser-extension/dist/production/manifest.json +35 -0
  31. package/browser-extension/dist/production/native-node.js +85 -0
  32. package/browser-extension/dist/production/page-data.js +497 -0
  33. package/browser-extension/dist/production/page.js +772 -0
  34. package/browser-extension/dist/production/profile.js +2 -0
  35. package/browser-extension/dist/production/router.js +5961 -0
  36. package/browser-extension/dist/production/site-source.js +149 -0
  37. package/browser-extension/dist/production/transport.js +405 -0
  38. package/browser-extension/dist/production/visual.js +976 -0
  39. package/browser-extension/dist/production/worker.js +24 -0
  40. package/browser-extension/errors.js +106 -0
  41. package/browser-extension/evaluate.js +160 -0
  42. package/browser-extension/frames.js +256 -0
  43. package/browser-extension/keyboard.js +167 -0
  44. package/browser-extension/native-node.js +85 -0
  45. package/browser-extension/page-data.js +497 -0
  46. package/browser-extension/page.js +772 -0
  47. package/browser-extension/release-info.json +21 -0
  48. package/browser-extension/route-manifest.json +807 -0
  49. package/browser-extension/router.js +5961 -0
  50. package/browser-extension/site-source.js +149 -0
  51. package/browser-extension/transport.js +405 -0
  52. package/browser-extension/visual.js +976 -0
  53. package/browser-extension/worker.js +24 -0
  54. package/dist/client/index.d.ts +6 -0
  55. package/dist/client/index.js +894 -0
  56. package/dist/client/index.js.map +1 -0
  57. package/dist/client/routes.d.ts +6 -0
  58. package/dist/client/routes.js +777 -0
  59. package/dist/client/routes.js.map +1 -0
  60. package/dist/client/serialize.d.ts +16 -0
  61. package/dist/client/serialize.js +355 -0
  62. package/dist/client/serialize.js.map +1 -0
  63. package/dist/client/types.d.ts +1342 -0
  64. package/dist/client/types.js +2 -0
  65. package/dist/client/types.js.map +1 -0
  66. package/dist/extension/artifacts.d.ts +60 -0
  67. package/dist/extension/artifacts.js +493 -0
  68. package/dist/extension/artifacts.js.map +1 -0
  69. package/dist/extension/assets.d.ts +10 -0
  70. package/dist/extension/assets.js +90 -0
  71. package/dist/extension/assets.js.map +1 -0
  72. package/dist/extension/batch.d.ts +6 -0
  73. package/dist/extension/batch.js +138 -0
  74. package/dist/extension/batch.js.map +1 -0
  75. package/dist/extension/files.d.ts +16 -0
  76. package/dist/extension/files.js +594 -0
  77. package/dist/extension/files.js.map +1 -0
  78. package/dist/extension/index.d.ts +3 -0
  79. package/dist/extension/index.js +623 -0
  80. package/dist/extension/index.js.map +1 -0
  81. package/dist/extension/protocol.d.ts +81 -0
  82. package/dist/extension/protocol.js +475 -0
  83. package/dist/extension/protocol.js.map +1 -0
  84. package/dist/extension/scope.d.ts +55 -0
  85. package/dist/extension/scope.js +563 -0
  86. package/dist/extension/scope.js.map +1 -0
  87. package/dist/extension/service.d.ts +113 -0
  88. package/dist/extension/service.js +905 -0
  89. package/dist/extension/service.js.map +1 -0
  90. package/docs/README.md +10 -0
  91. package/docs/api.md +1375 -0
  92. package/docs/connection.md +9 -0
  93. package/docs/lifecycle.md +17 -0
  94. package/docs/usage.md +75 -0
  95. package/implementation.json +2352 -0
  96. package/instructions/README.md +8 -0
  97. package/package.json +80 -4
  98. package/scripts/discover.js +12 -0
  99. package/scripts/screenshot.js +9 -0
  100. package/skills/browser-control/SKILL.md +12 -0
@@ -0,0 +1,111 @@
1
+ import { readFile, mkdir, copyFile, writeFile } from "node:fs/promises";
2
+ import { createHash, createPublicKey } from "node:crypto";
3
+ import path from "node:path";
4
+ import { fileURLToPath } from "node:url";
5
+
6
+ export function extensionId(key) {
7
+ const der = createPublicKey({
8
+ key: Buffer.from(key, "base64"),
9
+ format: "der",
10
+ type: "spki",
11
+ }).export({ type: "spki", format: "der" });
12
+ return [...createHash("sha256").update(der).digest().subarray(0, 16)]
13
+ .flatMap((b) => [
14
+ String.fromCharCode(97 + (b >> 4)),
15
+ String.fromCharCode(97 + (b & 15)),
16
+ ])
17
+ .join("");
18
+ }
19
+ export async function buildExtensions(
20
+ destination = path.join(path.dirname(fileURLToPath(import.meta.url)), "dist"),
21
+ ) {
22
+ const source = path.dirname(fileURLToPath(import.meta.url));
23
+ const release = JSON.parse(
24
+ await readFile(path.join(source, "release-info.json"), "utf8"),
25
+ );
26
+ const { routeDefinitions } = await import("./router.js");
27
+ await writeFile(
28
+ path.join(source, "route-manifest.json"),
29
+ JSON.stringify(
30
+ routeDefinitions.map(({ method, needsTab, mutating }) => ({
31
+ method,
32
+ needsTab,
33
+ mutating,
34
+ })),
35
+ null,
36
+ 2,
37
+ ) + "\n",
38
+ );
39
+ const files = [
40
+ "worker.js",
41
+ "router.js",
42
+ "page.js",
43
+ "connection.js",
44
+ "transport.js",
45
+ "errors.js",
46
+ "keyboard.js",
47
+ "native-node.js",
48
+ "clipboard.js",
49
+ "frames.js",
50
+ "evaluate.js",
51
+ "visual.js",
52
+ "page-data.js",
53
+ "assets.js",
54
+ "site-source.js",
55
+ ];
56
+ for (const [profile, info] of Object.entries(release.profiles)) {
57
+ if (extensionId(info.key) !== info.extensionId || info.profile !== profile)
58
+ throw new Error("Invalid fixed plugin identity.");
59
+ const target = path.join(destination, profile);
60
+ await mkdir(target, { recursive: true });
61
+ for (const name of files)
62
+ await copyFile(path.join(source, name), path.join(target, name));
63
+ await writeFile(
64
+ path.join(target, "profile.js"),
65
+ `export const profile=${JSON.stringify(profile)};\nexport const extensionVersion=${JSON.stringify(release.extensionVersion)};\n`,
66
+ );
67
+ await writeFile(
68
+ path.join(target, "manifest.json"),
69
+ JSON.stringify(
70
+ {
71
+ manifest_version: 3,
72
+ name:
73
+ profile === "development"
74
+ ? "Nexum browser (development)"
75
+ : "Nexum browser",
76
+ version: release.extensionVersion,
77
+ key: info.key,
78
+ minimum_chrome_version: "125",
79
+ background: { service_worker: "worker.js", type: "module" },
80
+ action: { default_title: "Nexum browser" },
81
+ permissions: [
82
+ "debugger",
83
+ "tabs",
84
+ "scripting",
85
+ "storage",
86
+ "alarms",
87
+ "downloads",
88
+ "history",
89
+ "tabGroups",
90
+ "bookmarks",
91
+ "clipboardRead",
92
+ "clipboardWrite",
93
+ "webNavigation",
94
+ ],
95
+ host_permissions: ["http://*/*", "https://*/*"],
96
+ content_security_policy: {
97
+ extension_pages: `script-src 'self'; object-src 'self'; connect-src ws://127.0.0.1:${info.port};`,
98
+ },
99
+ },
100
+ null,
101
+ 2,
102
+ ) + "\n",
103
+ );
104
+ }
105
+ return release;
106
+ }
107
+ if (
108
+ process.argv[1] &&
109
+ path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)
110
+ )
111
+ await buildExtensions(process.argv[2]);
@@ -0,0 +1,397 @@
1
+ import { requireValue } from "./errors.js";
2
+
3
+ const maximumBytes = 128 * 1024 * 1024;
4
+ const chunkBytes = 16384;
5
+ const encode = new TextEncoder();
6
+ const decode = new TextDecoder();
7
+
8
+ /** Native browser clipboard API, serialized into this extension's isolated page world. */
9
+ export async function clipboardCommand(input) {
10
+ const check = (
11
+ condition,
12
+ code = "INVALID_ARGUMENT",
13
+ message = "The clipboard request is invalid.",
14
+ ) => {
15
+ if (!condition) throw Object.assign(new Error(message), { code });
16
+ };
17
+ const maximum = 128 * 1024 * 1024;
18
+ try {
19
+ const slot = Symbol.for("nexum.browser.clipboard.v1");
20
+ let state = globalThis[slot];
21
+ if (input.command === "drop") {
22
+ if (
23
+ state?.document === document &&
24
+ state.entries.get(input.token)?.leaseId === input.leaseId
25
+ )
26
+ state.entries.delete(input.token);
27
+ return { ok: true, value: null };
28
+ }
29
+ if (!state || state.document !== document) {
30
+ state = { document, entries: new Map() };
31
+ Object.defineProperty(globalThis, slot, {
32
+ configurable: true,
33
+ value: state,
34
+ });
35
+ }
36
+ const size = () =>
37
+ [...state.entries.values()].reduce(
38
+ (total, entry) => total + entry.size,
39
+ 0,
40
+ );
41
+ let stage = state.entries.get(input.token);
42
+ if (input.command === "read" || input.command === "prepare") {
43
+ check(
44
+ !stage && state.entries.size < 8,
45
+ "QUEUE_FULL",
46
+ "The browser clipboard staging budget is full.",
47
+ );
48
+ const items = [];
49
+ let total = 0;
50
+ if (input.command === "read") {
51
+ check(
52
+ typeof navigator.clipboard?.read === "function",
53
+ "CAPABILITY_NOT_ALLOWED",
54
+ "This browser does not expose native multi-format clipboard reading.",
55
+ );
56
+ const nativeItems = await navigator.clipboard.read();
57
+ check(
58
+ nativeItems.length <= 16,
59
+ "OUTPUT_TOO_LARGE",
60
+ "The clipboard has too many native items.",
61
+ );
62
+ for (const item of nativeItems) {
63
+ if (item.types.length === 0) continue;
64
+ check(
65
+ item.types.length <= 64,
66
+ "OUTPUT_TOO_LARGE",
67
+ "The clipboard item has too many formats.",
68
+ );
69
+ const entries = [];
70
+ for (const mimeType of item.types) {
71
+ const blob = await item.getType(mimeType);
72
+ total += blob.size;
73
+ check(
74
+ total <= maximum,
75
+ "OUTPUT_TOO_LARGE",
76
+ "The clipboard exceeds its byte budget.",
77
+ );
78
+ entries.push({ mimeType, size: blob.size, blob });
79
+ }
80
+ items.push({
81
+ entries,
82
+ presentationStyle: item.presentationStyle ?? "unspecified",
83
+ });
84
+ }
85
+ } else {
86
+ check(
87
+ typeof navigator.clipboard?.write === "function" &&
88
+ typeof ClipboardItem === "function",
89
+ "CAPABILITY_NOT_ALLOWED",
90
+ "This browser does not expose native multi-format clipboard writing.",
91
+ );
92
+ check(
93
+ Array.isArray(input.items) &&
94
+ input.items.length > 0 &&
95
+ input.items.length <= 16,
96
+ );
97
+ for (const item of input.items) {
98
+ check(
99
+ Array.isArray(item.entries) &&
100
+ item.entries.length > 0 &&
101
+ item.entries.length <= 64,
102
+ );
103
+ const seen = new Set(),
104
+ entries = [];
105
+ for (const entry of item.entries) {
106
+ check(
107
+ typeof entry.mimeType === "string" &&
108
+ entry.mimeType.length > 0 &&
109
+ entry.mimeType.length <= 256 &&
110
+ !seen.has(entry.mimeType),
111
+ );
112
+ seen.add(entry.mimeType);
113
+ check(
114
+ Number.isSafeInteger(entry.size) &&
115
+ entry.size >= 0 &&
116
+ entry.size <= maximum,
117
+ );
118
+ total += entry.size;
119
+ check(
120
+ total <= maximum,
121
+ "OUTPUT_TOO_LARGE",
122
+ "The clipboard exceeds its byte budget.",
123
+ );
124
+ entries.push({
125
+ mimeType: entry.mimeType,
126
+ size: entry.size,
127
+ bytes: null,
128
+ written: 0,
129
+ });
130
+ }
131
+ check(
132
+ ["unspecified", "inline", "attachment"].includes(
133
+ item.presentationStyle ?? "unspecified",
134
+ ),
135
+ );
136
+ items.push({
137
+ entries,
138
+ presentationStyle: item.presentationStyle ?? "unspecified",
139
+ });
140
+ }
141
+ }
142
+ check(
143
+ size() + total <= maximum,
144
+ "QUEUE_FULL",
145
+ "The browser clipboard staging byte budget is full.",
146
+ );
147
+ if (input.command === "prepare")
148
+ for (const item of items)
149
+ for (const entry of item.entries)
150
+ entry.bytes = new Uint8Array(entry.size);
151
+ stage = {
152
+ leaseId: input.leaseId,
153
+ pageVersion: input.pageVersion,
154
+ items,
155
+ size: total,
156
+ };
157
+ state.entries.set(input.token, stage);
158
+ return {
159
+ ok: true,
160
+ value: items.map((item) => ({
161
+ presentationStyle: item.presentationStyle,
162
+ entries: item.entries.map(({ mimeType, size }) => ({
163
+ mimeType,
164
+ size,
165
+ })),
166
+ })),
167
+ };
168
+ }
169
+ check(
170
+ stage &&
171
+ stage.leaseId === input.leaseId &&
172
+ stage.pageVersion === input.pageVersion,
173
+ "STALE_REF",
174
+ "The original clipboard staging document is no longer current.",
175
+ );
176
+ if (input.command === "commit") {
177
+ const items = stage.items.map((item) => {
178
+ const formats = Object.create(null);
179
+ for (const entry of item.entries) {
180
+ check(entry.bytes && entry.written === entry.size);
181
+ formats[entry.mimeType] = new Blob([entry.bytes], {
182
+ type: entry.mimeType,
183
+ });
184
+ }
185
+ return new ClipboardItem(formats, {
186
+ presentationStyle: item.presentationStyle,
187
+ });
188
+ });
189
+ await navigator.clipboard.write(items);
190
+ return { ok: true, value: null };
191
+ }
192
+ const entry = stage.items[input.item]?.entries[input.entry];
193
+ check(
194
+ entry &&
195
+ Number.isSafeInteger(input.offset) &&
196
+ input.offset >= 0 &&
197
+ input.offset <= entry.size,
198
+ );
199
+ if (input.command === "chunk") {
200
+ check(
201
+ entry.blob &&
202
+ Number.isSafeInteger(input.length) &&
203
+ input.length >= 0 &&
204
+ input.length <= 16384 &&
205
+ input.offset + input.length <= entry.size,
206
+ );
207
+ const bytes = new Uint8Array(
208
+ await entry.blob
209
+ .slice(input.offset, input.offset + input.length)
210
+ .arrayBuffer(),
211
+ );
212
+ return { ok: true, value: Array.from(bytes) };
213
+ }
214
+ if (input.command === "append") {
215
+ check(
216
+ entry.bytes &&
217
+ entry.written === input.offset &&
218
+ Array.isArray(input.bytes) &&
219
+ input.bytes.length <= 16384 &&
220
+ input.offset + input.bytes.length <= entry.size &&
221
+ input.bytes.every(
222
+ (byte) => Number.isInteger(byte) && byte >= 0 && byte <= 255,
223
+ ),
224
+ );
225
+ entry.bytes.set(input.bytes, input.offset);
226
+ entry.written += input.bytes.length;
227
+ return { ok: true, value: null };
228
+ }
229
+ check(false);
230
+ } catch (cause) {
231
+ return {
232
+ ok: false,
233
+ error: {
234
+ code:
235
+ typeof cause?.code === "string"
236
+ ? cause.code
237
+ : cause?.name === "NotAllowedError"
238
+ ? "PERMISSION_DENIED"
239
+ : "INVALID_ARGUMENT",
240
+ message:
241
+ typeof cause?.code === "string"
242
+ ? cause.message
243
+ : "The browser rejected the native clipboard operation.",
244
+ },
245
+ };
246
+ }
247
+ }
248
+
249
+ function nativeBytes(value) {
250
+ requireValue(value instanceof Uint8Array || value instanceof ArrayBuffer);
251
+ const view =
252
+ value instanceof Uint8Array
253
+ ? new Uint8Array(value.buffer, value.byteOffset, value.byteLength)
254
+ : new Uint8Array(value);
255
+ requireValue(
256
+ view.byteLength <= maximumBytes,
257
+ "OUTPUT_TOO_LARGE",
258
+ "The clipboard entry exceeds its byte budget.",
259
+ );
260
+ const copy = new Uint8Array(view.byteLength);
261
+ copy.set(view);
262
+ return copy;
263
+ }
264
+ function prepared(items) {
265
+ requireValue(Array.isArray(items) && items.length > 0 && items.length <= 16);
266
+ let total = 0;
267
+ return items.map((item) => {
268
+ requireValue(
269
+ Array.isArray(item.entries) &&
270
+ item.entries.length > 0 &&
271
+ item.entries.length <= 64,
272
+ );
273
+ const seen = new Set();
274
+ const entries = item.entries.map((entry) => {
275
+ requireValue(
276
+ typeof entry.mimeType === "string" &&
277
+ /^[\x20-\x7e]{1,256}$/.test(entry.mimeType) &&
278
+ !seen.has(entry.mimeType),
279
+ );
280
+ seen.add(entry.mimeType);
281
+ requireValue((entry.text !== undefined) !== (entry.data !== undefined));
282
+ const data =
283
+ entry.text === undefined
284
+ ? nativeBytes(entry.data)
285
+ : (requireValue(typeof entry.text === "string"),
286
+ encode.encode(entry.text));
287
+ total += data.byteLength;
288
+ requireValue(
289
+ total <= maximumBytes,
290
+ "OUTPUT_TOO_LARGE",
291
+ "The clipboard exceeds its byte budget.",
292
+ );
293
+ return { mimeType: entry.mimeType, data };
294
+ });
295
+ requireValue(
296
+ ["unspecified", "inline", "attachment"].includes(
297
+ item.presentationStyle ?? "unspecified",
298
+ ),
299
+ );
300
+ return {
301
+ entries,
302
+ presentationStyle: item.presentationStyle ?? "unspecified",
303
+ };
304
+ });
305
+ }
306
+ export async function readClipboard(ctx) {
307
+ const token = crypto.randomUUID();
308
+ try {
309
+ const metadata = await ctx.router.clipboardPage(ctx, {
310
+ command: "read",
311
+ token,
312
+ });
313
+ requireValue(Array.isArray(metadata) && metadata.length <= 16);
314
+ let total = 0;
315
+ const result = [];
316
+ for (const [item, descriptor] of metadata.entries()) {
317
+ const entries = [];
318
+ for (const [entry, source] of descriptor.entries.entries()) {
319
+ requireValue(Number.isSafeInteger(source.size) && source.size >= 0);
320
+ total += source.size;
321
+ requireValue(
322
+ total <= maximumBytes,
323
+ "OUTPUT_TOO_LARGE",
324
+ "The clipboard exceeds its byte budget.",
325
+ );
326
+ const data = new Uint8Array(source.size);
327
+ for (let offset = 0; offset < data.length; offset += chunkBytes) {
328
+ const length = Math.min(chunkBytes, data.length - offset),
329
+ bytes = await ctx.router.clipboardPage(ctx, {
330
+ command: "chunk",
331
+ token,
332
+ item,
333
+ entry,
334
+ offset,
335
+ length,
336
+ });
337
+ requireValue(
338
+ Array.isArray(bytes) &&
339
+ bytes.length === length &&
340
+ bytes.every(
341
+ (value) =>
342
+ Number.isInteger(value) && value >= 0 && value <= 255,
343
+ ),
344
+ );
345
+ data.set(bytes, offset);
346
+ }
347
+ entries.push(
348
+ source.mimeType.startsWith("text/")
349
+ ? { mimeType: source.mimeType, text: decode.decode(data) }
350
+ : { mimeType: source.mimeType, data },
351
+ );
352
+ }
353
+ result.push({ presentationStyle: descriptor.presentationStyle, entries });
354
+ }
355
+ return result;
356
+ } finally {
357
+ await ctx.router.clipboardPage(ctx, { command: "drop", token }, true);
358
+ }
359
+ }
360
+ export async function writeClipboard(ctx, input) {
361
+ const items = prepared(input),
362
+ token = crypto.randomUUID();
363
+ try {
364
+ await ctx.router.clipboardPage(ctx, {
365
+ command: "prepare",
366
+ token,
367
+ items: items.map((item) => ({
368
+ presentationStyle: item.presentationStyle,
369
+ entries: item.entries.map(({ mimeType, data }) => ({
370
+ mimeType,
371
+ size: data.byteLength,
372
+ })),
373
+ })),
374
+ });
375
+ for (const [item, descriptor] of items.entries())
376
+ for (const [entry, source] of descriptor.entries.entries())
377
+ for (
378
+ let offset = 0;
379
+ offset < source.data.length;
380
+ offset += chunkBytes
381
+ ) {
382
+ await ctx.router.clipboardPage(ctx, {
383
+ command: "append",
384
+ token,
385
+ item,
386
+ entry,
387
+ offset,
388
+ bytes: Array.from(
389
+ source.data.subarray(offset, offset + chunkBytes),
390
+ ),
391
+ });
392
+ }
393
+ await ctx.router.clipboardPage(ctx, { command: "commit", token });
394
+ } finally {
395
+ await ctx.router.clipboardPage(ctx, { command: "drop", token }, true);
396
+ }
397
+ }