@liyuera/dsh-chrome-browser 0.3.0 → 0.5.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 (100) hide show
  1. package/README.md +238 -12
  2. package/extension/icons/icon-128.png +0 -0
  3. package/extension/icons/icon-16.png +0 -0
  4. package/extension/icons/icon-32.png +0 -0
  5. package/extension/icons/icon-48.png +0 -0
  6. package/extension/manifest.json +12 -5
  7. package/extension/service-worker.js +772 -70
  8. package/lib/activity.d.ts +65 -0
  9. package/lib/activity.d.ts.map +1 -0
  10. package/lib/activity.js +111 -0
  11. package/lib/activity.js.map +1 -0
  12. package/lib/backend.d.ts +235 -11
  13. package/lib/backend.d.ts.map +1 -1
  14. package/lib/backend.js +429 -40
  15. package/lib/backend.js.map +1 -1
  16. package/lib/cdp.d.ts +7 -1
  17. package/lib/cdp.d.ts.map +1 -1
  18. package/lib/cdp.js +17 -1
  19. package/lib/cdp.js.map +1 -1
  20. package/lib/chrome.d.ts +8 -0
  21. package/lib/chrome.d.ts.map +1 -1
  22. package/lib/chrome.js +20 -0
  23. package/lib/chrome.js.map +1 -1
  24. package/lib/client/BrowserActivity.d.ts +22 -0
  25. package/lib/client/BrowserActivity.d.ts.map +1 -0
  26. package/lib/client/BrowserActivity.js +100 -0
  27. package/lib/client/BrowserActivity.js.map +1 -0
  28. package/lib/client/activity.d.ts +27 -0
  29. package/lib/client/activity.d.ts.map +1 -0
  30. package/lib/client/activity.js +57 -0
  31. package/lib/client/activity.js.map +1 -0
  32. package/lib/client/index.d.ts +4 -6
  33. package/lib/client/index.d.ts.map +1 -1
  34. package/lib/client/index.js +13 -19
  35. package/lib/client/index.js.map +1 -1
  36. package/lib/client/tab-catalog.d.ts +11 -1
  37. package/lib/client/tab-catalog.d.ts.map +1 -1
  38. package/lib/client/tab-catalog.js.map +1 -1
  39. package/lib/client/tab-source.d.ts +8 -2
  40. package/lib/client/tab-source.d.ts.map +1 -1
  41. package/lib/client/tab-source.js.map +1 -1
  42. package/lib/client.js +177 -13
  43. package/lib/client.js.map +1 -1
  44. package/lib/console-events.d.ts +32 -0
  45. package/lib/console-events.d.ts.map +1 -0
  46. package/lib/console-events.js +106 -0
  47. package/lib/console-events.js.map +1 -0
  48. package/lib/console-log.d.ts +107 -0
  49. package/lib/console-log.d.ts.map +1 -0
  50. package/lib/console-log.js +158 -0
  51. package/lib/console-log.js.map +1 -0
  52. package/lib/expressions.d.ts +71 -2
  53. package/lib/expressions.d.ts.map +1 -1
  54. package/lib/expressions.js +277 -14
  55. package/lib/expressions.js.map +1 -1
  56. package/lib/extension-package.d.ts +49 -0
  57. package/lib/extension-package.d.ts.map +1 -1
  58. package/lib/extension-package.js +115 -0
  59. package/lib/extension-package.js.map +1 -1
  60. package/lib/help.d.ts +89 -0
  61. package/lib/help.d.ts.map +1 -0
  62. package/lib/help.js +94 -0
  63. package/lib/help.js.map +1 -0
  64. package/lib/index.d.ts +4 -2
  65. package/lib/index.d.ts.map +1 -1
  66. package/lib/index.js +30 -9
  67. package/lib/index.js.map +1 -1
  68. package/lib/presentation.d.ts +130 -0
  69. package/lib/presentation.d.ts.map +1 -0
  70. package/lib/presentation.js +361 -0
  71. package/lib/presentation.js.map +1 -0
  72. package/lib/routes.d.ts +3 -8
  73. package/lib/routes.d.ts.map +1 -1
  74. package/lib/routes.js +24 -109
  75. package/lib/routes.js.map +1 -1
  76. package/lib/skill.d.ts +50 -0
  77. package/lib/skill.d.ts.map +1 -0
  78. package/lib/skill.js +164 -0
  79. package/lib/skill.js.map +1 -0
  80. package/lib/text.d.ts +21 -0
  81. package/lib/text.d.ts.map +1 -1
  82. package/lib/text.js +18 -0
  83. package/lib/text.js.map +1 -1
  84. package/lib/tools.d.ts +22 -4
  85. package/lib/tools.d.ts.map +1 -1
  86. package/lib/tools.js +493 -75
  87. package/lib/tools.js.map +1 -1
  88. package/lib/ws.d.ts +9 -2
  89. package/lib/ws.d.ts.map +1 -1
  90. package/lib/ws.js +49 -19
  91. package/lib/ws.js.map +1 -1
  92. package/package.json +5 -3
  93. package/lib/bindings.d.ts +0 -23
  94. package/lib/bindings.d.ts.map +0 -1
  95. package/lib/bindings.js +0 -49
  96. package/lib/bindings.js.map +0 -1
  97. package/lib/client/TabPicker.d.ts +0 -54
  98. package/lib/client/TabPicker.d.ts.map +0 -1
  99. package/lib/client/TabPicker.js +0 -329
  100. package/lib/client/TabPicker.js.map +0 -1
@@ -0,0 +1,158 @@
1
+ /**
2
+ * Bounded console capture, one buffer per tab.
3
+ *
4
+ * The bounds are count and bytes, never time: a page that logs in a loop can
5
+ * produce more text in one second than a quiet page produces in an hour, so a
6
+ * retention window cannot bound memory. What bounds it is a fixed number of
7
+ * entries and a fixed text budget per tab, plus a fixed number of captured tabs
8
+ * — together a constant ceiling that does not grow with how long the plugin
9
+ * runs.
10
+ *
11
+ * Nothing here is durable. Entries live in the host process for as long as the
12
+ * tab is captured and are never written to the session log; only what a caller
13
+ * reads back enters a transcript.
14
+ * @module @liyuera/dsh-chrome-browser/console-log
15
+ */
16
+ /** Entries one tab keeps; the oldest are dropped past this. */
17
+ export const MAX_ENTRIES = 200;
18
+ /**
19
+ * Text one tab keeps across all its entries, in UTF-16 code units. V8 stores an
20
+ * all-Latin-1 string one byte per unit and a wider string two, so a tab holds
21
+ * 256 KB of ASCII or 512 KB of CJK — the ceiling is this constant times
22
+ * {@link MAX_TABS}, and it does not depend on how long the plugin runs.
23
+ */
24
+ export const MAX_CHARS = 256 * 1024;
25
+ /** Text one entry keeps; a longer message keeps its head plus a marker. */
26
+ export const MAX_ENTRY_CHARS = 4096;
27
+ /** Tabs captured at once; tracking one more releases the least recently used. */
28
+ export const MAX_TABS = 5;
29
+ /** Marker appended to a message the per-entry cap cut short. */
30
+ const TRUNCATED = '…[truncated]';
31
+ /** Cap one message, keeping its head so an oversized line cannot clear the buffer. */
32
+ export function capMessage(text) {
33
+ return text.length <= MAX_ENTRY_CHARS ? text : `${text.slice(0, MAX_ENTRY_CHARS)}${TRUNCATED}`;
34
+ }
35
+ /**
36
+ * A per-tab console window with fixed memory bounds. Every operation is O(1)
37
+ * amortized: eviction pops from the front, and the retained character count is
38
+ * maintained on append rather than recomputed.
39
+ */
40
+ export class ConsoleLog {
41
+ buffers = new Map();
42
+ clock = 0;
43
+ /** Whether one tab is currently captured. */
44
+ tracks(tabId) {
45
+ return this.buffers.has(tabId);
46
+ }
47
+ /** Captured tab ids, most recently used first. */
48
+ tracked() {
49
+ return [...this.buffers.entries()]
50
+ .sort((left, right) => right[1].used - left[1].used)
51
+ .map(([tabId]) => tabId);
52
+ }
53
+ /**
54
+ * Begin capturing one tab. Idempotent: a tab already captured keeps its
55
+ * window, which matters when a reconnecting bridge re-arms capture. Tracking
56
+ * past {@link MAX_TABS} releases the least recently used tab.
57
+ * @param tabId - the tab to capture.
58
+ * @returns the tab id released to stay within the cap, when one was.
59
+ */
60
+ track(tabId) {
61
+ const existing = this.buffers.get(tabId);
62
+ if (existing !== undefined) {
63
+ existing.used = ++this.clock;
64
+ return undefined;
65
+ }
66
+ let released;
67
+ if (this.buffers.size >= MAX_TABS) {
68
+ const oldest = this.tracked().at(-1);
69
+ if (oldest !== undefined) {
70
+ this.buffers.delete(oldest);
71
+ released = oldest;
72
+ }
73
+ }
74
+ this.buffers.set(tabId, { entries: [], chars: 0, seq: 0, dropped: 0, used: ++this.clock });
75
+ return released;
76
+ }
77
+ /** Stop capturing one tab and drop everything it held. */
78
+ release(tabId) {
79
+ this.buffers.delete(tabId);
80
+ }
81
+ /** Stop capturing every tab. */
82
+ releaseAll() {
83
+ this.buffers.clear();
84
+ }
85
+ /**
86
+ * Record one message on a captured tab. A tab that is not captured is
87
+ * ignored, so a late event from a released tab cannot resurrect its buffer.
88
+ * @param tabId - the tab the message came from.
89
+ * @param entry - level, text and optional call site.
90
+ * @returns whether the entry was retained.
91
+ */
92
+ append(tabId, entry) {
93
+ const buffer = this.buffers.get(tabId);
94
+ if (buffer === undefined)
95
+ return false;
96
+ const text = capMessage(entry.text);
97
+ buffer.entries.push({
98
+ seq: ++buffer.seq,
99
+ at: entry.at ?? Date.now(),
100
+ level: entry.level,
101
+ text,
102
+ ...(entry.source === undefined ? {} : { source: entry.source }),
103
+ });
104
+ buffer.chars += text.length;
105
+ buffer.used = ++this.clock;
106
+ this.evict(buffer);
107
+ return true;
108
+ }
109
+ /**
110
+ * Read the window a caller has not seen yet.
111
+ * @param tabId - the captured tab.
112
+ * @param options - `since` is an exclusive cursor (0 starts at the beginning);
113
+ * `limit` keeps the most recent entries of the matching set.
114
+ * @returns the page, or undefined when the tab is not captured.
115
+ */
116
+ read(tabId, options = {}) {
117
+ const buffer = this.buffers.get(tabId);
118
+ if (buffer === undefined)
119
+ return undefined;
120
+ const since = options.since ?? 0;
121
+ const matching = buffer.entries.filter(entry => entry.seq > since);
122
+ const limit = options.limit ?? MAX_ENTRIES;
123
+ const entries = limit >= matching.length ? matching : matching.slice(-limit);
124
+ return {
125
+ entries,
126
+ retained: buffer.entries.length,
127
+ dropped: buffer.dropped,
128
+ cursor: entries.at(-1)?.seq ?? since,
129
+ };
130
+ }
131
+ /** Drop one tab's entries but keep capturing it; the cursor continues from the newest seq. */
132
+ clear(tabId) {
133
+ const buffer = this.buffers.get(tabId);
134
+ if (buffer === undefined)
135
+ return false;
136
+ buffer.entries = [];
137
+ buffer.chars = 0;
138
+ return true;
139
+ }
140
+ /** Retained text across every captured tab, in code units (observability for tests). */
141
+ get retainedChars() {
142
+ let total = 0;
143
+ for (const buffer of this.buffers.values())
144
+ total += buffer.chars;
145
+ return total;
146
+ }
147
+ /** Drop the oldest entries until both the count and the text budget hold. */
148
+ evict(buffer) {
149
+ while (buffer.entries.length > MAX_ENTRIES || buffer.chars > MAX_CHARS) {
150
+ const dropped = buffer.entries.shift();
151
+ if (dropped === undefined)
152
+ return;
153
+ buffer.chars -= dropped.text.length;
154
+ buffer.dropped += 1;
155
+ }
156
+ }
157
+ }
158
+ //# sourceMappingURL=console-log.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"console-log.js","sourceRoot":"","sources":["../src/console-log.ts"],"names":[],"mappings":"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"}
@@ -4,6 +4,54 @@
4
4
  * serialization and cannot leak page globals into the harness.
5
5
  * @module @liyuera/dsh-chrome-browser/expressions
6
6
  */
7
+ /**
8
+ * Press expression: dispatch one key on a matched element, or on whatever
9
+ * currently has focus.
10
+ *
11
+ * Synthetic key events do not trigger the browser's own default actions, so
12
+ * `Enter` in a form would type nothing and submit nothing. The expression
13
+ * therefore submits the owning form explicitly and reports that it did, rather
14
+ * than leaving the caller to guess why nothing happened.
15
+ * @param key - the `KeyboardEvent.key` value, e.g. `Enter` or `ArrowDown`.
16
+ * @param selector - element to focus first; omit to press on the focused element.
17
+ * @returns a self-contained expression evaluating to `{ found, pressed, submitted }`.
18
+ */
19
+ export declare function pressExpression(key: string, selector?: string): string;
20
+ /**
21
+ * Select expression: set a `<select>`'s value and fire the events a controlled
22
+ * component listens for, through the prototype setter so frameworks that patch
23
+ * the instance still see the change.
24
+ *
25
+ * A value with no matching option leaves the select unchanged; the result says
26
+ * so and lists what was available instead of reporting a success the page never
27
+ * saw.
28
+ * @param selector - CSS selector for the `<select>`.
29
+ * @param value - the option value to select.
30
+ * @returns a self-contained expression evaluating to the selection outcome.
31
+ */
32
+ export declare function selectExpression(selector: string, value: string): string;
33
+ /** Element conditions `chrome_wait` can wait for. */
34
+ export type WaitState = 'attached' | 'detached' | 'visible' | 'hidden';
35
+ /**
36
+ * Poll expression for one wait condition: does the selector currently satisfy
37
+ * `state`? Resolved fresh on every poll, because the page changes between them.
38
+ * @param selector - CSS selector to test.
39
+ * @param state - the condition to test for.
40
+ * @returns a self-contained expression evaluating to a boolean.
41
+ */
42
+ export declare function waitExpression(selector: string, state: WaitState): string;
43
+ /**
44
+ * Hover expression: dispatch the pointer events a hover-driven menu listens for
45
+ * on the first match.
46
+ *
47
+ * These are synthetic: they reach listeners the page attached, but they do not
48
+ * set the browser's own hover state, so a control revealed purely by a CSS
49
+ * `:hover` rule will not appear. The alternative — real pointer input — is not
50
+ * available on the extension bridge, so both backends behave the same.
51
+ * @param selector - CSS selector to hover.
52
+ * @returns a self-contained expression evaluating to `{ matched, hovered }`.
53
+ */
54
+ export declare function hoverExpression(selector: string): string;
7
55
  /** Live page-facts expression: title, url, visible text, optional HTML. */
8
56
  export declare function readPageExpression(includeHtml: boolean): string;
9
57
  /** Viewport dimensions expression (screenshot metadata). */
@@ -11,10 +59,31 @@ export declare function viewportExpression(): string;
11
59
  /** Document readiness poll expression (navigation wait). */
12
60
  export declare function readyStateExpression(): string;
13
61
  /**
14
- * Click expression. Returns the number of elements matched and clicked:
15
- * `all` clicks every match, otherwise only the first.
62
+ * Click expression. Returns one outcome per call: how many elements the
63
+ * selector matched, how many received a dispatched click, and why the rest did
64
+ * not or may not have taken effect. `all` clicks every match, otherwise only
65
+ * the first.
66
+ * @param selector - CSS selector to resolve.
67
+ * @param all - whether to click every match instead of the first.
68
+ * @returns a self-contained expression evaluating to the click outcome.
16
69
  */
17
70
  export declare function clickExpression(selector: string, all: boolean): string;
71
+ /** Elements the interactive inventory considers actionable. */
72
+ export declare const INTERACTIVE_SELECTOR: string;
73
+ /** Elements one inventory returns; a longer page is reported as capped. */
74
+ export declare const INVENTORY_LIMIT = 150;
75
+ /**
76
+ * Interactive-element inventory expression: what a reader can act on, with the
77
+ * selector to act on it, instead of the page's prose. Shares the click probe
78
+ * with {@link clickExpression}, so `covered` here means the same thing it means
79
+ * in a click result.
80
+ *
81
+ * The extension bridge runs the same inventory in
82
+ * `extension/service-worker.js` (`interactiveInventory`), because it cannot
83
+ * import host modules; tests/inventory.spec.ts requires the two to agree.
84
+ * @returns a self-contained expression evaluating to `{ matched, items }`.
85
+ */
86
+ export declare function inventoryExpression(): string;
18
87
  /**
19
88
  * Focus-only expression for typing without replacing existing content: focuses
20
89
  * the matched element and leaves its selection untouched. Returns whether a
@@ -1 +1 @@
1
- {"version":3,"file":"expressions.d.ts","sourceRoot":"","sources":["../src/expressions.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAOH,2EAA2E;AAC3E,wBAAgB,kBAAkB,CAAC,WAAW,EAAE,OAAO,GAAG,MAAM,CAQ/D;AAED,4DAA4D;AAC5D,wBAAgB,kBAAkB,IAAI,MAAM,CAE3C;AAED,4DAA4D;AAC5D,wBAAgB,oBAAoB,IAAI,MAAM,CAE7C;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,OAAO,GAAG,MAAM,CAetE;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAQxD;AAED;;;;GAIG;AACH,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAejE"}
1
+ {"version":3,"file":"expressions.d.ts","sourceRoot":"","sources":["../src/expressions.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AA4BH;;;;;;;;;;;GAWG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAuBtE;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAwBxE;AAED,qDAAqD;AACrD,MAAM,MAAM,SAAS,GAAG,UAAU,GAAG,UAAU,GAAG,SAAS,GAAG,QAAQ,CAAA;AAEtE;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,GAAG,MAAM,CAoBzE;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAsBxD;AAED,2EAA2E;AAC3E,wBAAgB,kBAAkB,CAAC,WAAW,EAAE,OAAO,GAAG,MAAM,CAQ/D;AAED,4DAA4D;AAC5D,wBAAgB,kBAAkB,IAAI,MAAM,CAE3C;AAED,4DAA4D;AAC5D,wBAAgB,oBAAoB,IAAI,MAAM,CAE7C;AA4BD;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,OAAO,GAAG,MAAM,CAkBtE;AAED,+DAA+D;AAC/D,eAAO,MAAM,oBAAoB,QACsF,CAAA;AAEvH,2EAA2E;AAC3E,eAAO,MAAM,eAAe,MAAM,CAAA;AAKlC;;;;;;;;;;GAUG;AACH,wBAAgB,mBAAmB,IAAI,MAAM,CAwD5C;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAQxD;AAED;;;;GAIG;AACH,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAejE"}
@@ -8,6 +8,161 @@
8
8
  function literal(value) {
9
9
  return JSON.stringify(value);
10
10
  }
11
+ /**
12
+ * Legacy `keyCode` values the common keys need: libraries still read them, and
13
+ * a synthesized `KeyboardEvent` carries none by default.
14
+ */
15
+ const KEY_CODES = {
16
+ Enter: 13,
17
+ Escape: 27,
18
+ Tab: 9,
19
+ Backspace: 8,
20
+ Delete: 46,
21
+ ArrowUp: 38,
22
+ ArrowDown: 40,
23
+ ArrowLeft: 37,
24
+ ArrowRight: 39,
25
+ Home: 36,
26
+ End: 35,
27
+ PageUp: 33,
28
+ PageDown: 34,
29
+ ' ': 32,
30
+ };
31
+ /**
32
+ * Press expression: dispatch one key on a matched element, or on whatever
33
+ * currently has focus.
34
+ *
35
+ * Synthetic key events do not trigger the browser's own default actions, so
36
+ * `Enter` in a form would type nothing and submit nothing. The expression
37
+ * therefore submits the owning form explicitly and reports that it did, rather
38
+ * than leaving the caller to guess why nothing happened.
39
+ * @param key - the `KeyboardEvent.key` value, e.g. `Enter` or `ArrowDown`.
40
+ * @param selector - element to focus first; omit to press on the focused element.
41
+ * @returns a self-contained expression evaluating to `{ found, pressed, submitted }`.
42
+ */
43
+ export function pressExpression(key, selector) {
44
+ const target = selector === undefined
45
+ ? 'document.activeElement'
46
+ : `document.querySelector(${literal(selector)})`;
47
+ return `(() => {
48
+ const el = ${target}
49
+ if (el === null) return { found: false, pressed: false, submitted: false }
50
+ const node = el ?? document.body
51
+ if (typeof node.focus === 'function') node.focus()
52
+ const init = { key: ${literal(key)}, bubbles: true, cancelable: true, keyCode: ${KEY_CODES[key] ?? 0} }
53
+ node.dispatchEvent(new KeyboardEvent('keydown', init))
54
+ node.dispatchEvent(new KeyboardEvent('keypress', init))
55
+ node.dispatchEvent(new KeyboardEvent('keyup', init))
56
+ let submitted = false
57
+ if (init.key === 'Enter') {
58
+ const form = node.form ?? (typeof node.closest === 'function' ? node.closest('form') : null)
59
+ if (form !== null && form !== undefined && typeof form.requestSubmit === 'function') {
60
+ form.requestSubmit()
61
+ submitted = true
62
+ }
63
+ }
64
+ return { found: true, pressed: true, submitted }
65
+ })()`;
66
+ }
67
+ /**
68
+ * Select expression: set a `<select>`'s value and fire the events a controlled
69
+ * component listens for, through the prototype setter so frameworks that patch
70
+ * the instance still see the change.
71
+ *
72
+ * A value with no matching option leaves the select unchanged; the result says
73
+ * so and lists what was available instead of reporting a success the page never
74
+ * saw.
75
+ * @param selector - CSS selector for the `<select>`.
76
+ * @param value - the option value to select.
77
+ * @returns a self-contained expression evaluating to the selection outcome.
78
+ */
79
+ export function selectExpression(selector, value) {
80
+ return `(() => {
81
+ const el = document.querySelector(${literal(selector)})
82
+ if (el === null) return { matched: 0, changed: false, value: '', options: [] }
83
+ if (!(el instanceof HTMLSelectElement)) {
84
+ return { matched: 1, changed: false, value: '', options: [], reason: 'not a <select>' }
85
+ }
86
+ const all = Array.from(el.options).map((option) => option.value)
87
+ const options = all.slice(0, 30)
88
+ // Checked BEFORE assigning: assigning a value no option carries sets
89
+ // selectedIndex to -1 and clears the control, so a call that is about to be
90
+ // rejected would still wipe the selection the user had.
91
+ if (all.indexOf(${literal(value)}) === -1) {
92
+ return { matched: 1, changed: false, value: el.value, options }
93
+ }
94
+ const setter = Object.getOwnPropertyDescriptor(HTMLSelectElement.prototype, 'value').set
95
+ setter.call(el, ${literal(value)})
96
+ const changed = el.value === ${literal(value)}
97
+ if (changed) {
98
+ el.dispatchEvent(new Event('input', { bubbles: true }))
99
+ el.dispatchEvent(new Event('change', { bubbles: true }))
100
+ }
101
+ return { matched: 1, changed, value: el.value, options }
102
+ })()`;
103
+ }
104
+ /**
105
+ * Poll expression for one wait condition: does the selector currently satisfy
106
+ * `state`? Resolved fresh on every poll, because the page changes between them.
107
+ * @param selector - CSS selector to test.
108
+ * @param state - the condition to test for.
109
+ * @returns a self-contained expression evaluating to a boolean.
110
+ */
111
+ export function waitExpression(selector, state) {
112
+ const condition = {
113
+ attached: 'attached',
114
+ detached: '!attached',
115
+ visible: 'attached && shown',
116
+ hidden: '!attached || !shown',
117
+ }[state];
118
+ return `(() => {
119
+ const el = document.querySelector(${literal(selector)})
120
+ const attached = el !== null
121
+ let shown = false
122
+ if (attached) {
123
+ const rect = el.getBoundingClientRect()
124
+ if (rect.width > 0 && rect.height > 0) {
125
+ const style = getComputedStyle(el)
126
+ shown = style.visibility !== 'hidden' && style.display !== 'none'
127
+ }
128
+ }
129
+ return ${condition}
130
+ })()`;
131
+ }
132
+ /**
133
+ * Hover expression: dispatch the pointer events a hover-driven menu listens for
134
+ * on the first match.
135
+ *
136
+ * These are synthetic: they reach listeners the page attached, but they do not
137
+ * set the browser's own hover state, so a control revealed purely by a CSS
138
+ * `:hover` rule will not appear. The alternative — real pointer input — is not
139
+ * available on the extension bridge, so both backends behave the same.
140
+ * @param selector - CSS selector to hover.
141
+ * @returns a self-contained expression evaluating to `{ matched, hovered }`.
142
+ */
143
+ export function hoverExpression(selector) {
144
+ return `(() => {
145
+ const el = document.querySelector(${literal(selector)})
146
+ if (el === null) return { matched: 0, hovered: false }
147
+ const rect = el.getBoundingClientRect()
148
+ const init = {
149
+ bubbles: true,
150
+ cancelable: true,
151
+ view: window,
152
+ clientX: rect.left + rect.width / 2,
153
+ clientY: rect.top + rect.height / 2,
154
+ }
155
+ const Pointer = typeof PointerEvent === 'function' ? PointerEvent : MouseEvent
156
+ for (const type of ['pointerover', 'mouseover', 'pointermove', 'mousemove']) {
157
+ el.dispatchEvent(new Pointer(type, init))
158
+ }
159
+ // Enter does not bubble; it is delivered on the target only.
160
+ for (const type of ['pointerenter', 'mouseenter']) {
161
+ el.dispatchEvent(new Pointer(type, { ...init, bubbles: false }))
162
+ }
163
+ return { matched: 1, hovered: true }
164
+ })()`;
165
+ }
11
166
  /** Live page-facts expression: title, url, visible text, optional HTML. */
12
167
  export function readPageExpression(includeHtml) {
13
168
  const htmlPart = includeHtml
@@ -27,24 +182,132 @@ export function readyStateExpression() {
27
182
  return 'document.readyState';
28
183
  }
29
184
  /**
30
- * Click expression. Returns the number of elements matched and clicked:
31
- * `all` clicks every match, otherwise only the first.
185
+ * Page-side clickability probe, shared with the extension bridge: the same
186
+ * function body exists in `extension/service-worker.js` (`describeTarget`), and
187
+ * the two must stay in step — the bridge cannot import this module.
188
+ *
189
+ * `disabled` is the only state that suppresses the click event outright, so it
190
+ * is the only one the caller refuses to click. The others are reported because
191
+ * a click can be dispatched while a real pointer could never have reached the
192
+ * element, which is exactly the case a caller must not mistake for success.
193
+ */
194
+ const CLICK_PROBE = `const probe = (el) => {
195
+ if (el.disabled === true) return 'disabled'
196
+ const rect = el.getBoundingClientRect()
197
+ if (rect.width === 0 || rect.height === 0) return 'invisible'
198
+ const style = getComputedStyle(el)
199
+ if (style.visibility === 'hidden' || style.display === 'none') return 'invisible'
200
+ const x = rect.left + rect.width / 2
201
+ const y = rect.top + rect.height / 2
202
+ if (x < 0 || y < 0 || x > window.innerWidth || y > window.innerHeight) return 'offscreen'
203
+ const root = el.getRootNode()
204
+ const from = root && typeof root.elementFromPoint === 'function' ? root : document
205
+ const hit = from.elementFromPoint(x, y)
206
+ if (hit === null) return 'offscreen'
207
+ return hit === el || el.contains(hit) ? 'ok' : 'covered'
208
+ }`;
209
+ /**
210
+ * Click expression. Returns one outcome per call: how many elements the
211
+ * selector matched, how many received a dispatched click, and why the rest did
212
+ * not or may not have taken effect. `all` clicks every match, otherwise only
213
+ * the first.
214
+ * @param selector - CSS selector to resolve.
215
+ * @param all - whether to click every match instead of the first.
216
+ * @returns a self-contained expression evaluating to the click outcome.
32
217
  */
33
218
  export function clickExpression(selector, all) {
34
219
  const sel = literal(selector);
35
- return all
36
- ? `(() => {
37
- const els = document.querySelectorAll(${sel});
38
- let n = 0;
39
- for (const el of els) { el.click(); n++ }
40
- return n
41
- })()`
42
- : `(() => {
43
- const el = document.querySelector(${sel});
44
- if (!el) return 0
220
+ const targets = all ? 'Array.from(matched)' : 'matched.length > 0 ? [matched[0]] : []';
221
+ return `(() => {
222
+ ${CLICK_PROBE}
223
+ const matched = document.querySelectorAll(${sel})
224
+ const targets = ${targets}
225
+ const outcome = { matched: matched.length, clicked: 0, disabled: 0, invisible: 0, offscreen: 0, covered: 0, ariaDisabled: 0 }
226
+ for (const el of targets) {
227
+ const state = probe(el)
228
+ if (state === 'disabled') { outcome.disabled++; continue }
229
+ if (state !== 'ok') outcome[state]++
230
+ if (el.getAttribute('aria-disabled') === 'true') outcome.ariaDisabled++
45
231
  el.click()
46
- return 1
47
- })()`;
232
+ outcome.clicked++
233
+ }
234
+ return outcome
235
+ })()`;
236
+ }
237
+ /** Elements the interactive inventory considers actionable. */
238
+ export const INTERACTIVE_SELECTOR = 'a[href],button,input,select,textarea,[role=button],[role=link],'
239
+ + '[role=checkbox],[role=radio],[role=tab],[role=menuitem],[role=switch],[contenteditable=""],[contenteditable=true]';
240
+ /** Elements one inventory returns; a longer page is reported as capped. */
241
+ export const INVENTORY_LIMIT = 150;
242
+ /** Characters one inventory entry's name keeps. */
243
+ const MAX_NAME_CHARS = 80;
244
+ /**
245
+ * Interactive-element inventory expression: what a reader can act on, with the
246
+ * selector to act on it, instead of the page's prose. Shares the click probe
247
+ * with {@link clickExpression}, so `covered` here means the same thing it means
248
+ * in a click result.
249
+ *
250
+ * The extension bridge runs the same inventory in
251
+ * `extension/service-worker.js` (`interactiveInventory`), because it cannot
252
+ * import host modules; tests/inventory.spec.ts requires the two to agree.
253
+ * @returns a self-contained expression evaluating to `{ matched, items }`.
254
+ */
255
+ export function inventoryExpression() {
256
+ return `(() => {
257
+ ${CLICK_PROBE}
258
+ const SELECTOR = ${JSON.stringify(INTERACTIVE_SELECTOR)}
259
+ const LIMIT = ${INVENTORY_LIMIT}
260
+ const MAX_NAME = ${MAX_NAME_CHARS}
261
+ const escape = (value) => (typeof CSS !== 'undefined' && CSS.escape
262
+ ? CSS.escape(value)
263
+ : String(value).replace(/[^a-zA-Z0-9_-]/g, (ch) => '\\\\' + ch))
264
+ const stableSelector = (el) => {
265
+ if (el.id) {
266
+ const byId = '#' + escape(el.id)
267
+ try { if (document.querySelectorAll(byId).length === 1) return byId } catch (error) { /* unusable id */ }
268
+ }
269
+ const parts = []
270
+ let node = el
271
+ for (let depth = 0; node && node.nodeType === 1 && depth < 4; depth++) {
272
+ const tag = node.tagName.toLowerCase()
273
+ const parent = node.parentElement
274
+ if (parent === null) { parts.unshift(tag); break }
275
+ const siblings = Array.from(parent.children).filter((child) => child.tagName === node.tagName)
276
+ parts.unshift(siblings.length > 1 ? tag + ':nth-of-type(' + (siblings.indexOf(node) + 1) + ')' : tag)
277
+ node = parent
278
+ }
279
+ return parts.join(' > ')
280
+ }
281
+ const nameOf = (el) => {
282
+ const raw = el.getAttribute('aria-label')
283
+ || (el.innerText && el.innerText.trim())
284
+ || el.value
285
+ || el.getAttribute('placeholder')
286
+ || el.getAttribute('title')
287
+ || el.getAttribute('name')
288
+ || ''
289
+ return String(raw).replace(/\\s+/g, ' ').trim().slice(0, MAX_NAME)
290
+ }
291
+ const matched = document.querySelectorAll(SELECTOR)
292
+ const items = []
293
+ for (const el of matched) {
294
+ if (items.length >= LIMIT) break
295
+ const rect = el.getBoundingClientRect()
296
+ if (rect.width === 0 || rect.height === 0) continue
297
+ const style = getComputedStyle(el)
298
+ if (style.visibility === 'hidden' || style.display === 'none') continue
299
+ const state = probe(el)
300
+ items.push({
301
+ selector: stableSelector(el),
302
+ role: el.getAttribute('role') || el.tagName.toLowerCase(),
303
+ name: nameOf(el),
304
+ inView: state !== 'offscreen',
305
+ disabled: el.disabled === true || el.getAttribute('aria-disabled') === 'true',
306
+ covered: state === 'covered',
307
+ })
308
+ }
309
+ return { title: document.title, url: location.href, matched: matched.length, items }
310
+ })()`;
48
311
  }
49
312
  /**
50
313
  * Focus-only expression for typing without replacing existing content: focuses
@@ -1 +1 @@
1
- {"version":3,"file":"expressions.js","sourceRoot":"","sources":["../src/expressions.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,8EAA8E;AAC9E,SAAS,OAAO,CAAC,KAAa;IAC5B,OAAO,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAA;AAC9B,CAAC;AAED,2EAA2E;AAC3E,MAAM,UAAU,kBAAkB,CAAC,WAAoB;IACrD,MAAM,QAAQ,GAAG,WAAW;QAC1B,CAAC,CAAC,oEAAoE;QACtE,CAAC,CAAC,IAAI,CAAA;IACR,OAAO;;sEAE6D,QAAQ;OACvE,CAAA;AACP,CAAC;AAED,4DAA4D;AAC5D,MAAM,UAAU,kBAAkB;IAChC,OAAO,4DAA4D,CAAA;AACrE,CAAC;AAED,4DAA4D;AAC5D,MAAM,UAAU,oBAAoB;IAClC,OAAO,qBAAqB,CAAA;AAC9B,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,eAAe,CAAC,QAAgB,EAAE,GAAY;IAC5D,MAAM,GAAG,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAA;IAC7B,OAAO,GAAG;QACR,CAAC,CAAC;8CACwC,GAAG;;;;SAIxC;QACL,CAAC,CAAC;0CACoC,GAAG;;;;SAIpC,CAAA;AACT,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,eAAe,CAAC,QAAgB;IAC9C,MAAM,GAAG,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAA;IAC7B,OAAO;wCAC+B,GAAG;;;;OAIpC,CAAA;AACP,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,wBAAwB,CAAC,QAAgB;IACvD,MAAM,GAAG,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAA;IAC7B,OAAO;wCAC+B,GAAG;;;;;;;;;;;OAWpC,CAAA;AACP,CAAC"}
1
+ {"version":3,"file":"expressions.js","sourceRoot":"","sources":["../src/expressions.ts"],"names":[],"mappings":"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"}
@@ -21,6 +21,55 @@ export declare function crc32(data: Buffer): number;
21
21
  * @returns the absolute extension directory path.
22
22
  */
23
23
  export declare function extensionDir(moduleUrl: string): string;
24
+ /**
25
+ * Version the loaded extension must report to be current.
26
+ *
27
+ * Read from the packaged manifest rather than duplicated as a constant, so the
28
+ * manifest stays the single source of truth. Compared against what the
29
+ * extension reports about itself on connect, which is the only way to tell a
30
+ * stale unpacked extension apart from a current one — Chrome never re-reads
31
+ * those files on its own.
32
+ * @param moduleUrl - `import.meta.url` of the module resolving the folder.
33
+ * @returns the manifest's version, or '' when it cannot be read.
34
+ */
35
+ export declare function extensionVersion(moduleUrl: string): string;
36
+ /**
37
+ * Every file the extension is made of, as sorted relative paths.
38
+ *
39
+ * Sorted so both sides of the version handshake hash the same byte order, and
40
+ * the whole tree rather than a list so a file added to the folder is covered
41
+ * without an edit here. extension/service-worker.js carries the same set; a
42
+ * test keeps the two equal.
43
+ * @param directory - the extension folder.
44
+ * @returns relative paths, `/`-separated and sorted.
45
+ */
46
+ export declare function extensionFiles(directory: string): string[];
47
+ /**
48
+ * Fingerprint of one extension folder, as lowercase hex SHA-256.
49
+ *
50
+ * A stamp rather than a version number someone has to remember to bump, and a
51
+ * stamp rather than a hash the extension computes at runtime: measured on a
52
+ * real browser, `fetch(chrome.runtime.getURL(...))` inside the worker returns
53
+ * the files on DISK, not the copy Chrome loaded, so a runtime self-hash reports
54
+ * the new bytes while the old code is still running and nothing ever looks
55
+ * stale. The worker therefore carries this value as a constant and reports it;
56
+ * the host compares that constant against this function's answer.
57
+ * @param directory - the extension folder.
58
+ * @returns the digest of every file, name and bytes, in sorted order.
59
+ */
60
+ export declare function extensionStampOf(directory: string): string;
61
+ /**
62
+ * The stamp this package's extension files should carry.
63
+ * @param moduleUrl - `import.meta.url` of the module resolving the folder.
64
+ * @returns the digest, or '' when the folder cannot be read.
65
+ */
66
+ export declare function extensionStamp(moduleUrl: string): string;
67
+ /**
68
+ * The stamp actually written into the worker beside this module.
69
+ * @param moduleUrl - `import.meta.url` of the module resolving the folder.
70
+ * @returns the constant's value, or '' when it cannot be read.
71
+ */
72
+ export declare function extensionStampedValue(moduleUrl: string): string;
24
73
  /**
25
74
  * Build an uncompressed zip archive of one directory tree.
26
75
  *
@@ -1 +1 @@
1
- {"version":3,"file":"extension-package.d.ts","sourceRoot":"","sources":["../src/extension-package.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAMH,sEAAsE;AACtE,eAAO,MAAM,kBAAkB,iCAAiC,CAAA;AA8BhE;;;;GAIG;AACH,wBAAgB,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAM1C;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAEtD;AAoBD;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CA0D5D"}
1
+ {"version":3,"file":"extension-package.d.ts","sourceRoot":"","sources":["../src/extension-package.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAOH,sEAAsE;AACtE,eAAO,MAAM,kBAAkB,iCAAiC,CAAA;AA8BhE;;;;GAIG;AACH,wBAAgB,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAM1C;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAEtD;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAW1D;AAED;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,EAAE,CAc1D;AAcD;;;;;;;;;;;;GAYG;AACH,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAQ1D;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAOxD;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAQ/D;AAoBD;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CA0D5D"}