context-drop 0.0.0-stage → 0.2.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.
- package/MIT-LICENSE +21 -0
- package/README.md +709 -2
- package/app/assets/javascripts/context_drop/context_drop.js +8936 -0
- package/dist/app/javascript/context_drop/api-client.d.ts +41 -0
- package/dist/app/javascript/context_drop/api-client.js +279 -0
- package/dist/app/javascript/context_drop/element-picker.d.ts +111 -0
- package/dist/app/javascript/context_drop/element-picker.js +1428 -0
- package/dist/app/javascript/context_drop/icons.d.ts +32 -0
- package/dist/app/javascript/context_drop/icons.js +32 -0
- package/dist/app/javascript/context_drop/index.d.ts +7 -0
- package/dist/app/javascript/context_drop/index.js +9 -0
- package/dist/app/javascript/context_drop/markdown.d.ts +7 -0
- package/dist/app/javascript/context_drop/markdown.js +129 -0
- package/dist/app/javascript/context_drop/sanitizer.d.ts +38 -0
- package/dist/app/javascript/context_drop/sanitizer.js +769 -0
- package/dist/app/javascript/context_drop/screenshot.d.ts +21 -0
- package/dist/app/javascript/context_drop/screenshot.js +245 -0
- package/dist/app/javascript/context_drop/styles.d.ts +1 -0
- package/dist/app/javascript/context_drop/styles.js +2015 -0
- package/dist/app/javascript/context_drop/types.d.ts +239 -0
- package/dist/app/javascript/context_drop/types.js +1 -0
- package/dist/app/javascript/context_drop/widget.d.ts +188 -0
- package/dist/app/javascript/context_drop/widget.js +3227 -0
- package/dist/src/cli.d.ts +3 -0
- package/dist/src/cli.js +207 -0
- package/dist/src/index.d.ts +5 -0
- package/dist/src/index.js +5 -0
- package/dist/src/mcp/dispatcher.d.ts +42 -0
- package/dist/src/mcp/dispatcher.js +869 -0
- package/dist/src/mcp/environment-router.d.ts +38 -0
- package/dist/src/mcp/environment-router.js +174 -0
- package/dist/src/mcp/index.d.ts +24 -0
- package/dist/src/mcp/index.js +75 -0
- package/dist/src/mcp/remote-client.d.ts +25 -0
- package/dist/src/mcp/remote-client.js +98 -0
- package/dist/src/next/index.d.ts +13 -0
- package/dist/src/next/index.js +25 -0
- package/dist/src/next/server.d.ts +1 -0
- package/dist/src/next/server.js +1 -0
- package/dist/src/react/index.d.ts +90 -0
- package/dist/src/react/index.js +124 -0
- package/dist/src/server/handler.d.ts +42 -0
- package/dist/src/server/handler.js +677 -0
- package/dist/src/server/index.d.ts +8 -0
- package/dist/src/server/index.js +8 -0
- package/dist/src/server/sanitizer.d.ts +15 -0
- package/dist/src/server/sanitizer.js +201 -0
- package/dist/src/server/storage/local.d.ts +22 -0
- package/dist/src/server/storage/local.js +574 -0
- package/dist/src/server/storage/memory.d.ts +5 -0
- package/dist/src/server/storage/memory.js +221 -0
- package/dist/src/server/storage/postgres.d.ts +27 -0
- package/dist/src/server/storage/postgres.js +446 -0
- package/dist/src/server/types.d.ts +190 -0
- package/dist/src/server/types.js +7 -0
- package/dist/src/server/upload-validator.d.ts +16 -0
- package/dist/src/server/upload-validator.js +196 -0
- package/dist/src/widget/index.d.ts +1 -0
- package/dist/src/widget/index.js +1 -0
- package/package.json +99 -4
|
@@ -0,0 +1,769 @@
|
|
|
1
|
+
export const MANDATORY_EXCLUDED_SELECTORS = [
|
|
2
|
+
"[data-feedback-ignore]",
|
|
3
|
+
"[data-feedback-sensitive]",
|
|
4
|
+
"input[type='password']",
|
|
5
|
+
"input[type='hidden']",
|
|
6
|
+
"[autocomplete^='cc-']",
|
|
7
|
+
"context-drop-widget",
|
|
8
|
+
"[data-context-drop-ui]"
|
|
9
|
+
];
|
|
10
|
+
export const ALLOWED_HTML_ATTRIBUTES = [
|
|
11
|
+
"id",
|
|
12
|
+
"class",
|
|
13
|
+
"role",
|
|
14
|
+
"name",
|
|
15
|
+
"type",
|
|
16
|
+
"href",
|
|
17
|
+
"title",
|
|
18
|
+
"placeholder",
|
|
19
|
+
"alt",
|
|
20
|
+
"data-testid",
|
|
21
|
+
"data-test",
|
|
22
|
+
"data-cy",
|
|
23
|
+
"data-qa",
|
|
24
|
+
"data-component",
|
|
25
|
+
"data-controller",
|
|
26
|
+
"data-ui",
|
|
27
|
+
"data-turbo-frame"
|
|
28
|
+
];
|
|
29
|
+
const IGNORED_TEXT_TAGS = new Set([
|
|
30
|
+
"SCRIPT",
|
|
31
|
+
"STYLE",
|
|
32
|
+
"NOSCRIPT",
|
|
33
|
+
"TEMPLATE",
|
|
34
|
+
"SVG",
|
|
35
|
+
"PATH",
|
|
36
|
+
"INPUT",
|
|
37
|
+
"TEXTAREA",
|
|
38
|
+
"SELECT"
|
|
39
|
+
]);
|
|
40
|
+
export function buildExcludedSelectorList(customSelectors = []) {
|
|
41
|
+
const combined = new Set(MANDATORY_EXCLUDED_SELECTORS);
|
|
42
|
+
for (const sel of customSelectors) {
|
|
43
|
+
if (typeof sel === "string" && sel.trim().length > 0) {
|
|
44
|
+
combined.add(sel.trim());
|
|
45
|
+
}
|
|
46
|
+
}
|
|
47
|
+
return Array.from(combined);
|
|
48
|
+
}
|
|
49
|
+
function elementMatchesAny(el, selectors) {
|
|
50
|
+
const tagName = (el.tagName || "").toLowerCase();
|
|
51
|
+
if (tagName === "context-drop-widget")
|
|
52
|
+
return true;
|
|
53
|
+
if (el.hasAttribute("data-feedback-ignore") || el.hasAttribute("data-feedback-sensitive")) {
|
|
54
|
+
return true;
|
|
55
|
+
}
|
|
56
|
+
if (el.hasAttribute("data-context-drop-ui")) {
|
|
57
|
+
return true;
|
|
58
|
+
}
|
|
59
|
+
if (tagName === "input") {
|
|
60
|
+
const inputType = (el.getAttribute("type") || "").toLowerCase();
|
|
61
|
+
if (inputType === "password" || inputType === "hidden")
|
|
62
|
+
return true;
|
|
63
|
+
}
|
|
64
|
+
const autocomplete = (el.getAttribute("autocomplete") || "").toLowerCase();
|
|
65
|
+
if (autocomplete.startsWith("cc-"))
|
|
66
|
+
return true;
|
|
67
|
+
if (typeof el.matches === "function") {
|
|
68
|
+
for (const sel of selectors) {
|
|
69
|
+
try {
|
|
70
|
+
if (el.matches(sel))
|
|
71
|
+
return true;
|
|
72
|
+
}
|
|
73
|
+
catch {
|
|
74
|
+
// Ignore invalid custom CSS selector syntax
|
|
75
|
+
}
|
|
76
|
+
}
|
|
77
|
+
}
|
|
78
|
+
return false;
|
|
79
|
+
}
|
|
80
|
+
export function getParentOrHostElement(node) {
|
|
81
|
+
if (!node)
|
|
82
|
+
return null;
|
|
83
|
+
if (node.parentElement) {
|
|
84
|
+
return node.parentElement;
|
|
85
|
+
}
|
|
86
|
+
const rootNode = typeof node.getRootNode === "function" ? node.getRootNode() : null;
|
|
87
|
+
if (rootNode && "host" in rootNode && rootNode.host instanceof Element) {
|
|
88
|
+
return rootNode.host;
|
|
89
|
+
}
|
|
90
|
+
return null;
|
|
91
|
+
}
|
|
92
|
+
export function isElementExcluded(node, customSelectors = []) {
|
|
93
|
+
if (!node)
|
|
94
|
+
return true;
|
|
95
|
+
const selectors = buildExcludedSelectorList(customSelectors);
|
|
96
|
+
let current = node;
|
|
97
|
+
while (current) {
|
|
98
|
+
if (elementMatchesAny(current, selectors)) {
|
|
99
|
+
return true;
|
|
100
|
+
}
|
|
101
|
+
current = getParentOrHostElement(current);
|
|
102
|
+
}
|
|
103
|
+
return false;
|
|
104
|
+
}
|
|
105
|
+
export function isSelectableElement(node, customSelectors = []) {
|
|
106
|
+
if (!node)
|
|
107
|
+
return false;
|
|
108
|
+
const tag = (node.tagName || "").toUpperCase();
|
|
109
|
+
if (!tag || tag === "HTML" || tag === "BODY" || tag === "HEAD" || tag === "SCRIPT" || tag === "STYLE") {
|
|
110
|
+
return false;
|
|
111
|
+
}
|
|
112
|
+
if (typeof node.closest === "function") {
|
|
113
|
+
if (node.closest("context-drop-widget") || node.closest("[data-context-drop-ui]")) {
|
|
114
|
+
return false;
|
|
115
|
+
}
|
|
116
|
+
}
|
|
117
|
+
if (isElementExcluded(node, customSelectors)) {
|
|
118
|
+
return false;
|
|
119
|
+
}
|
|
120
|
+
const rect = typeof node.getBoundingClientRect === "function"
|
|
121
|
+
? node.getBoundingClientRect()
|
|
122
|
+
: { width: 0, height: 0 };
|
|
123
|
+
if ((rect.width ?? 0) <= 0 || (rect.height ?? 0) <= 0) {
|
|
124
|
+
return false;
|
|
125
|
+
}
|
|
126
|
+
return true;
|
|
127
|
+
}
|
|
128
|
+
export function extractSanitizedAttributes(el) {
|
|
129
|
+
const snapshot = {};
|
|
130
|
+
const attrNames = typeof el.getAttributeNames === "function" ? el.getAttributeNames() : [];
|
|
131
|
+
for (const rawName of attrNames) {
|
|
132
|
+
const name = rawName.toLowerCase().trim();
|
|
133
|
+
if (!name || name === "value" || name === "defaultvalue" || name.startsWith("on")) {
|
|
134
|
+
continue;
|
|
135
|
+
}
|
|
136
|
+
if (name === "data-feedback-ignore" || name === "data-feedback-sensitive") {
|
|
137
|
+
continue;
|
|
138
|
+
}
|
|
139
|
+
const isAllowed = ALLOWED_HTML_ATTRIBUTES.includes(name) ||
|
|
140
|
+
(name.startsWith("aria-") && name !== "aria-hidden");
|
|
141
|
+
if (!isAllowed)
|
|
142
|
+
continue;
|
|
143
|
+
const rawVal = el.getAttribute(rawName);
|
|
144
|
+
if (rawVal === null)
|
|
145
|
+
continue;
|
|
146
|
+
const trimmed = rawVal.trim();
|
|
147
|
+
if (name === "href" && /^(javascript|data):/i.test(trimmed)) {
|
|
148
|
+
continue;
|
|
149
|
+
}
|
|
150
|
+
snapshot[name] = trimmed.slice(0, 300);
|
|
151
|
+
}
|
|
152
|
+
return snapshot;
|
|
153
|
+
}
|
|
154
|
+
export function extractSanitizedText(el, customSelectors = []) {
|
|
155
|
+
const tagName = (el.tagName || "").toUpperCase();
|
|
156
|
+
if (IGNORED_TEXT_TAGS.has(tagName)) {
|
|
157
|
+
return null;
|
|
158
|
+
}
|
|
159
|
+
const selectors = buildExcludedSelectorList(customSelectors);
|
|
160
|
+
const parts = [];
|
|
161
|
+
function walk(node) {
|
|
162
|
+
if (node.nodeType === 3) {
|
|
163
|
+
// Node.TEXT_NODE === 3
|
|
164
|
+
const text = node.nodeValue || "";
|
|
165
|
+
if (text.trim().length > 0) {
|
|
166
|
+
parts.push(text.trim());
|
|
167
|
+
}
|
|
168
|
+
return;
|
|
169
|
+
}
|
|
170
|
+
if (node.nodeType === 1) {
|
|
171
|
+
// Node.ELEMENT_NODE === 1
|
|
172
|
+
const childEl = node;
|
|
173
|
+
const childTag = (childEl.tagName || "").toUpperCase();
|
|
174
|
+
if (IGNORED_TEXT_TAGS.has(childTag))
|
|
175
|
+
return;
|
|
176
|
+
if (elementMatchesAny(childEl, selectors))
|
|
177
|
+
return;
|
|
178
|
+
const children = childEl.childNodes || [];
|
|
179
|
+
if (children.length === 0) {
|
|
180
|
+
const directText = childEl.textContent || "";
|
|
181
|
+
if (directText.trim().length > 0) {
|
|
182
|
+
parts.push(directText.trim());
|
|
183
|
+
}
|
|
184
|
+
return;
|
|
185
|
+
}
|
|
186
|
+
for (let i = 0; i < children.length; i += 1) {
|
|
187
|
+
walk(children[i]);
|
|
188
|
+
}
|
|
189
|
+
}
|
|
190
|
+
}
|
|
191
|
+
walk(el);
|
|
192
|
+
const joined = parts.join(" ").replace(/\s+/g, " ").trim();
|
|
193
|
+
if (joined.length === 0)
|
|
194
|
+
return null;
|
|
195
|
+
return joined.slice(0, 500);
|
|
196
|
+
}
|
|
197
|
+
function escapeCssIdentifier(ident) {
|
|
198
|
+
if (typeof CSS !== "undefined" && typeof CSS.escape === "function") {
|
|
199
|
+
return CSS.escape(ident);
|
|
200
|
+
}
|
|
201
|
+
return ident.replace(/([^a-zA-Z0-9_-])/g, "\\$1");
|
|
202
|
+
}
|
|
203
|
+
export function computeSelector(el) {
|
|
204
|
+
const tag = (el.tagName || "div").toLowerCase();
|
|
205
|
+
const id = (el.getAttribute("id") || "").trim();
|
|
206
|
+
if (id) {
|
|
207
|
+
return `#${escapeCssIdentifier(id)}`;
|
|
208
|
+
}
|
|
209
|
+
const testId = el.getAttribute("data-testid") ||
|
|
210
|
+
el.getAttribute("data-test") ||
|
|
211
|
+
el.getAttribute("data-cy") ||
|
|
212
|
+
el.getAttribute("data-qa");
|
|
213
|
+
if (testId && testId.trim()) {
|
|
214
|
+
const attrKey = el.hasAttribute("data-testid")
|
|
215
|
+
? "data-testid"
|
|
216
|
+
: el.hasAttribute("data-test")
|
|
217
|
+
? "data-test"
|
|
218
|
+
: el.hasAttribute("data-cy")
|
|
219
|
+
? "data-cy"
|
|
220
|
+
: "data-qa";
|
|
221
|
+
return `${tag}[${attrKey}="${testId.trim().replace(/"/g, '\\"')}"]`;
|
|
222
|
+
}
|
|
223
|
+
const classAttr = (el.getAttribute("class") || "").trim();
|
|
224
|
+
if (classAttr) {
|
|
225
|
+
const classes = classAttr
|
|
226
|
+
.split(/\s+/)
|
|
227
|
+
.filter((c) => c.length > 0 && !c.startsWith("cd-"))
|
|
228
|
+
.slice(0, 3)
|
|
229
|
+
.map((c) => `.${escapeCssIdentifier(c)}`)
|
|
230
|
+
.join("");
|
|
231
|
+
if (classes) {
|
|
232
|
+
return `${tag}${classes}`;
|
|
233
|
+
}
|
|
234
|
+
}
|
|
235
|
+
return tag;
|
|
236
|
+
}
|
|
237
|
+
export function computeDomPath(el) {
|
|
238
|
+
const segments = [];
|
|
239
|
+
let current = el;
|
|
240
|
+
while (current && segments.length < 15) {
|
|
241
|
+
const tag = (current.tagName || "").toLowerCase();
|
|
242
|
+
if (!tag)
|
|
243
|
+
break;
|
|
244
|
+
let segment = tag;
|
|
245
|
+
const id = (current.getAttribute("id") || "").trim();
|
|
246
|
+
if (id) {
|
|
247
|
+
segment += `#${id}`;
|
|
248
|
+
}
|
|
249
|
+
else {
|
|
250
|
+
const classAttr = (current.getAttribute("class") || "").trim();
|
|
251
|
+
if (classAttr) {
|
|
252
|
+
const firstClasses = classAttr
|
|
253
|
+
.split(/\s+/)
|
|
254
|
+
.filter(Boolean)
|
|
255
|
+
.slice(0, 2)
|
|
256
|
+
.join(".");
|
|
257
|
+
if (firstClasses) {
|
|
258
|
+
segment += `.${firstClasses}`;
|
|
259
|
+
}
|
|
260
|
+
}
|
|
261
|
+
}
|
|
262
|
+
segments.unshift(segment);
|
|
263
|
+
current = getParentOrHostElement(current);
|
|
264
|
+
}
|
|
265
|
+
return segments.join(" > ").slice(0, 1000);
|
|
266
|
+
}
|
|
267
|
+
export function computeBoundingRect(el) {
|
|
268
|
+
const rect = typeof el.getBoundingClientRect === "function"
|
|
269
|
+
? el.getBoundingClientRect()
|
|
270
|
+
: { x: 0, y: 0, width: 0, height: 0 };
|
|
271
|
+
return {
|
|
272
|
+
x: Math.round((rect.x ?? rect.left ?? 0) * 100) / 100,
|
|
273
|
+
y: Math.round((rect.y ?? rect.top ?? 0) * 100) / 100,
|
|
274
|
+
width: Math.round((rect.width ?? 0) * 100) / 100,
|
|
275
|
+
height: Math.round((rect.height ?? 0) * 100) / 100
|
|
276
|
+
};
|
|
277
|
+
}
|
|
278
|
+
export function describeElementCandidate(el, relation, depth, customSelectors = []) {
|
|
279
|
+
const rawText = extractSanitizedText(el, customSelectors);
|
|
280
|
+
const textPreview = rawText
|
|
281
|
+
? rawText.length > 64
|
|
282
|
+
? `${rawText.slice(0, 61)}...`
|
|
283
|
+
: rawText
|
|
284
|
+
: null;
|
|
285
|
+
const smart = describeSmartComponent(el, customSelectors);
|
|
286
|
+
return {
|
|
287
|
+
element: el,
|
|
288
|
+
tagName: (el.tagName || "div").toLowerCase(),
|
|
289
|
+
selector: computeSelector(el),
|
|
290
|
+
domPath: computeDomPath(el),
|
|
291
|
+
textPreview,
|
|
292
|
+
friendlyLabel: smart.label,
|
|
293
|
+
componentKind: smart.kind,
|
|
294
|
+
rect: computeBoundingRect(el),
|
|
295
|
+
relation,
|
|
296
|
+
depth
|
|
297
|
+
};
|
|
298
|
+
}
|
|
299
|
+
const INTERACTIVE_SMART_TAGS = new Set([
|
|
300
|
+
"button",
|
|
301
|
+
"a",
|
|
302
|
+
"input",
|
|
303
|
+
"select",
|
|
304
|
+
"textarea",
|
|
305
|
+
"summary",
|
|
306
|
+
"label"
|
|
307
|
+
]);
|
|
308
|
+
const INTERACTIVE_SMART_ROLES = new Set([
|
|
309
|
+
"button",
|
|
310
|
+
"link",
|
|
311
|
+
"menuitem",
|
|
312
|
+
"tab",
|
|
313
|
+
"switch",
|
|
314
|
+
"checkbox",
|
|
315
|
+
"radio",
|
|
316
|
+
"combobox",
|
|
317
|
+
"option",
|
|
318
|
+
"searchbox",
|
|
319
|
+
"slider"
|
|
320
|
+
]);
|
|
321
|
+
const SEMANTIC_COMPONENT_TAGS = new Set([
|
|
322
|
+
"dialog",
|
|
323
|
+
"article",
|
|
324
|
+
"aside",
|
|
325
|
+
"nav",
|
|
326
|
+
"header",
|
|
327
|
+
"footer",
|
|
328
|
+
"form",
|
|
329
|
+
"tr",
|
|
330
|
+
"li",
|
|
331
|
+
"figure",
|
|
332
|
+
"blockquote",
|
|
333
|
+
"fieldset",
|
|
334
|
+
"details",
|
|
335
|
+
"table",
|
|
336
|
+
"turbo-frame"
|
|
337
|
+
]);
|
|
338
|
+
const SEMANTIC_COMPONENT_ROLES = new Set([
|
|
339
|
+
"dialog",
|
|
340
|
+
"alertdialog",
|
|
341
|
+
"alert",
|
|
342
|
+
"status",
|
|
343
|
+
"banner",
|
|
344
|
+
"navigation",
|
|
345
|
+
"search",
|
|
346
|
+
"region",
|
|
347
|
+
"tabpanel",
|
|
348
|
+
"listitem",
|
|
349
|
+
"row",
|
|
350
|
+
"toolbar",
|
|
351
|
+
"menu",
|
|
352
|
+
"card"
|
|
353
|
+
]);
|
|
354
|
+
const INLINE_LEAF_TAGS = new Set([
|
|
355
|
+
"span",
|
|
356
|
+
"strong",
|
|
357
|
+
"em",
|
|
358
|
+
"b",
|
|
359
|
+
"i",
|
|
360
|
+
"u",
|
|
361
|
+
"small",
|
|
362
|
+
"mark",
|
|
363
|
+
"abbr",
|
|
364
|
+
"time",
|
|
365
|
+
"code",
|
|
366
|
+
"kbd",
|
|
367
|
+
"svg",
|
|
368
|
+
"path",
|
|
369
|
+
"circle",
|
|
370
|
+
"rect",
|
|
371
|
+
"line",
|
|
372
|
+
"polyline",
|
|
373
|
+
"polygon",
|
|
374
|
+
"g",
|
|
375
|
+
"use"
|
|
376
|
+
]);
|
|
377
|
+
const COMPONENT_HINT_PATTERN = /\b(card|panel|modal|drawer|dialog|toast|banner|alert|notice|callout|widget|navbar|topbar|header|sidebar|toolbar|dropdown|popover|menu|tile|pricing|checkout|summary|hero|stat|metric|item|row|badge|pill)\b/i;
|
|
378
|
+
function isInteractiveSmartNode(el) {
|
|
379
|
+
const tag = (el.tagName || "").toLowerCase();
|
|
380
|
+
if (INTERACTIVE_SMART_TAGS.has(tag))
|
|
381
|
+
return true;
|
|
382
|
+
const role = (el.getAttribute("role") || "").trim().toLowerCase();
|
|
383
|
+
return role.length > 0 && INTERACTIVE_SMART_ROLES.has(role);
|
|
384
|
+
}
|
|
385
|
+
function hasComponentBoundarySignal(el) {
|
|
386
|
+
const tag = (el.tagName || "").toLowerCase();
|
|
387
|
+
if (SEMANTIC_COMPONENT_TAGS.has(tag))
|
|
388
|
+
return true;
|
|
389
|
+
const role = (el.getAttribute("role") || "").trim().toLowerCase();
|
|
390
|
+
if (role && SEMANTIC_COMPONENT_ROLES.has(role))
|
|
391
|
+
return true;
|
|
392
|
+
for (const attr of [
|
|
393
|
+
"data-component",
|
|
394
|
+
"data-controller",
|
|
395
|
+
"data-turbo-frame",
|
|
396
|
+
"data-ui",
|
|
397
|
+
"data-testid",
|
|
398
|
+
"data-qa"
|
|
399
|
+
]) {
|
|
400
|
+
const val = (el.getAttribute(attr) || "").trim();
|
|
401
|
+
if (val.length > 0)
|
|
402
|
+
return true;
|
|
403
|
+
}
|
|
404
|
+
const classAndId = `${el.getAttribute("id") || ""} ${el.getAttribute("class") || ""}`;
|
|
405
|
+
return COMPONENT_HINT_PATTERN.test(classAndId);
|
|
406
|
+
}
|
|
407
|
+
function isOversizedPageShell(el) {
|
|
408
|
+
const tag = (el.tagName || "").toLowerCase();
|
|
409
|
+
if (tag === "main" || tag === "body" || tag === "html")
|
|
410
|
+
return true;
|
|
411
|
+
const vw = typeof window !== "undefined" ? window.innerWidth || 1280 : 1280;
|
|
412
|
+
const vh = typeof window !== "undefined" ? window.innerHeight || 800 : 800;
|
|
413
|
+
const rect = computeBoundingRect(el);
|
|
414
|
+
return rect.width >= vw * 0.92 && rect.height >= vh * 0.82;
|
|
415
|
+
}
|
|
416
|
+
function findFirstHeadingText(root, customSelectors = [], maxDepth = 4) {
|
|
417
|
+
const selectors = buildExcludedSelectorList(customSelectors);
|
|
418
|
+
const headingTags = new Set(["H1", "H2", "H3", "H4", "H5", "H6", "LEGEND", "CAPTION", "SUMMARY"]);
|
|
419
|
+
function search(node, depth) {
|
|
420
|
+
if (depth > maxDepth)
|
|
421
|
+
return null;
|
|
422
|
+
const children = node.childNodes || [];
|
|
423
|
+
for (let i = 0; i < children.length; i += 1) {
|
|
424
|
+
const child = children[i];
|
|
425
|
+
if (!child || child.nodeType !== 1)
|
|
426
|
+
continue;
|
|
427
|
+
const childEl = child;
|
|
428
|
+
if (elementMatchesAny(childEl, selectors))
|
|
429
|
+
continue;
|
|
430
|
+
const cTag = (childEl.tagName || "").toUpperCase();
|
|
431
|
+
const cRole = (childEl.getAttribute("role") || "").trim().toLowerCase();
|
|
432
|
+
if (headingTags.has(cTag) || cRole === "heading") {
|
|
433
|
+
const headingText = extractSanitizedText(childEl, customSelectors);
|
|
434
|
+
if (headingText && headingText.length > 0) {
|
|
435
|
+
return headingText;
|
|
436
|
+
}
|
|
437
|
+
}
|
|
438
|
+
const nested = search(childEl, depth + 1);
|
|
439
|
+
if (nested)
|
|
440
|
+
return nested;
|
|
441
|
+
}
|
|
442
|
+
return null;
|
|
443
|
+
}
|
|
444
|
+
return search(root, 1);
|
|
445
|
+
}
|
|
446
|
+
function humanizeIdentifierToken(raw) {
|
|
447
|
+
const cleaned = raw
|
|
448
|
+
.trim()
|
|
449
|
+
.replace(/^(cd|js|app|ui|scenario|section|page)[-_]/i, "")
|
|
450
|
+
.replace(/[-_](btn|button|link|card|panel|section|wrapper|container|box|el|root|view|\d+)$/i, "")
|
|
451
|
+
.replace(/([a-z])([A-Z])/g, "$1 $2")
|
|
452
|
+
.replace(/[-_./]+/g, " ")
|
|
453
|
+
.replace(/\s+/g, " ")
|
|
454
|
+
.trim();
|
|
455
|
+
if (!cleaned || cleaned.length < 2 || /^[0-9a-f]{7,}$/i.test(cleaned)) {
|
|
456
|
+
return null;
|
|
457
|
+
}
|
|
458
|
+
return cleaned
|
|
459
|
+
.split(" ")
|
|
460
|
+
.slice(0, 4)
|
|
461
|
+
.map((word) => word.charAt(0).toUpperCase() + word.slice(1).toLowerCase())
|
|
462
|
+
.join(" ");
|
|
463
|
+
}
|
|
464
|
+
function inferFriendlyComponentKind(el) {
|
|
465
|
+
const tag = (el.tagName || "div").toLowerCase();
|
|
466
|
+
const role = (el.getAttribute("role") || "").trim().toLowerCase();
|
|
467
|
+
const classAndId = `${el.getAttribute("id") || ""} ${el.getAttribute("class") || ""}`.toLowerCase();
|
|
468
|
+
if (tag === "button" || role === "button")
|
|
469
|
+
return "Button";
|
|
470
|
+
if (tag === "a" || role === "link")
|
|
471
|
+
return "Link";
|
|
472
|
+
if (role === "tab")
|
|
473
|
+
return "Tab";
|
|
474
|
+
if (role === "menuitem")
|
|
475
|
+
return "Menu item";
|
|
476
|
+
if (role === "switch")
|
|
477
|
+
return "Toggle";
|
|
478
|
+
if (tag === "select" || role === "combobox")
|
|
479
|
+
return "Dropdown";
|
|
480
|
+
if (tag === "textarea")
|
|
481
|
+
return "Text field";
|
|
482
|
+
if (tag === "input") {
|
|
483
|
+
const type = (el.getAttribute("type") || "text").toLowerCase();
|
|
484
|
+
if (type === "search" || role === "searchbox")
|
|
485
|
+
return "Search box";
|
|
486
|
+
if (type === "checkbox" || role === "checkbox")
|
|
487
|
+
return "Checkbox";
|
|
488
|
+
if (type === "radio" || role === "radio")
|
|
489
|
+
return "Option";
|
|
490
|
+
if (type === "submit" || type === "button")
|
|
491
|
+
return "Button";
|
|
492
|
+
return "Input field";
|
|
493
|
+
}
|
|
494
|
+
if (tag === "label")
|
|
495
|
+
return "Field";
|
|
496
|
+
if (tag === "dialog" || role === "dialog" || role === "alertdialog" || /\b(modal|drawer|dialog)\b/.test(classAndId)) {
|
|
497
|
+
return "Dialog";
|
|
498
|
+
}
|
|
499
|
+
if (role === "alert" || role === "status" || /\b(toast|banner|alert|notice|callout)\b/.test(classAndId)) {
|
|
500
|
+
return "Banner";
|
|
501
|
+
}
|
|
502
|
+
if (tag === "nav" || role === "navigation" || /\b(navbar|topbar|Subnav|breadcrumb)\b/i.test(classAndId)) {
|
|
503
|
+
return "Navigation";
|
|
504
|
+
}
|
|
505
|
+
if (tag === "header" || /\bheader\b/.test(classAndId))
|
|
506
|
+
return "Header";
|
|
507
|
+
if (tag === "footer")
|
|
508
|
+
return "Footer";
|
|
509
|
+
if (tag === "aside" || /\bsidebar\b/.test(classAndId))
|
|
510
|
+
return "Sidebar";
|
|
511
|
+
if (tag === "form")
|
|
512
|
+
return "Form";
|
|
513
|
+
if (tag === "table")
|
|
514
|
+
return "Table";
|
|
515
|
+
if (tag === "tr" || role === "row")
|
|
516
|
+
return "Table row";
|
|
517
|
+
if (tag === "li" || role === "listitem")
|
|
518
|
+
return "Item";
|
|
519
|
+
if (tag === "img" || tag === "figure" || tag === "svg" || tag === "picture")
|
|
520
|
+
return "Image";
|
|
521
|
+
if (/^h[1-6]$/.test(tag) || role === "heading")
|
|
522
|
+
return "Heading";
|
|
523
|
+
if (tag === "article" ||
|
|
524
|
+
tag === "turbo-frame" ||
|
|
525
|
+
/\b(card|panel|tile|pricing|summary|widget|stat|metric|popover|dropdown)\b/.test(classAndId)) {
|
|
526
|
+
return "Card";
|
|
527
|
+
}
|
|
528
|
+
if (tag === "section" || role === "region")
|
|
529
|
+
return "Section";
|
|
530
|
+
return "Page area";
|
|
531
|
+
}
|
|
532
|
+
function truncateCleanPhrase(raw, maxLen = 32) {
|
|
533
|
+
const normalized = raw.replace(/\s+/g, " ").trim();
|
|
534
|
+
if (normalized.length <= maxLen)
|
|
535
|
+
return normalized;
|
|
536
|
+
return `${normalized.slice(0, maxLen - 1).trimEnd()}…`;
|
|
537
|
+
}
|
|
538
|
+
/**
|
|
539
|
+
* Resolves a hovered/clicked DOM leaf into a meaningful, human-recognizable UI component
|
|
540
|
+
* for Production ("smart") mode so non-technical users never wrestle with tiny `<span>`/`<svg>`
|
|
541
|
+
* fragments or overlapping DevTools layer lists.
|
|
542
|
+
*/
|
|
543
|
+
export function resolveSmartComponent(primaryTarget, customSelectors = []) {
|
|
544
|
+
if (!primaryTarget || !isSelectableElement(primaryTarget, customSelectors)) {
|
|
545
|
+
return null;
|
|
546
|
+
}
|
|
547
|
+
// 1. If the user is pointing inside an interactive control (button, link, input, tab, menuitem),
|
|
548
|
+
// snap cleanly to that control rather than an inner <span> or <svg>.
|
|
549
|
+
let cursor = primaryTarget;
|
|
550
|
+
let hops = 0;
|
|
551
|
+
while (cursor && hops < 6) {
|
|
552
|
+
if (isSelectableElement(cursor, customSelectors) && isInteractiveSmartNode(cursor)) {
|
|
553
|
+
return cursor;
|
|
554
|
+
}
|
|
555
|
+
cursor = getParentOrHostElement(cursor);
|
|
556
|
+
hops += 1;
|
|
557
|
+
}
|
|
558
|
+
// 2. Otherwise walk up to the nearest bounded semantic / visual component (Card, Banner, Form,
|
|
559
|
+
// Dialog, Table row, Navigation, Stimulus/Turbo component) without jumping to full-page <main>/<body>.
|
|
560
|
+
cursor = primaryTarget;
|
|
561
|
+
hops = 0;
|
|
562
|
+
let fallbackSection = null;
|
|
563
|
+
while (cursor && hops < 6) {
|
|
564
|
+
if (isSelectableElement(cursor, customSelectors) && !isOversizedPageShell(cursor)) {
|
|
565
|
+
const rect = computeBoundingRect(cursor);
|
|
566
|
+
if (rect.width >= 24 && rect.height >= 18) {
|
|
567
|
+
if (hasComponentBoundarySignal(cursor)) {
|
|
568
|
+
return cursor;
|
|
569
|
+
}
|
|
570
|
+
const tag = (cursor.tagName || "").toLowerCase();
|
|
571
|
+
if (tag === "section" && !fallbackSection) {
|
|
572
|
+
fallbackSection = cursor;
|
|
573
|
+
}
|
|
574
|
+
}
|
|
575
|
+
}
|
|
576
|
+
cursor = getParentOrHostElement(cursor);
|
|
577
|
+
hops += 1;
|
|
578
|
+
}
|
|
579
|
+
if (fallbackSection) {
|
|
580
|
+
return fallbackSection;
|
|
581
|
+
}
|
|
582
|
+
// 3. If the leaf is a bare inline/SVG fragment, step up to its nearest clean block parent.
|
|
583
|
+
const leafTag = (primaryTarget.tagName || "").toLowerCase();
|
|
584
|
+
if (INLINE_LEAF_TAGS.has(leafTag)) {
|
|
585
|
+
let parent = getParentOrHostElement(primaryTarget);
|
|
586
|
+
let step = 0;
|
|
587
|
+
while (parent && step < 4) {
|
|
588
|
+
const pTag = (parent.tagName || "").toLowerCase();
|
|
589
|
+
if (!INLINE_LEAF_TAGS.has(pTag) &&
|
|
590
|
+
isSelectableElement(parent, customSelectors) &&
|
|
591
|
+
!isOversizedPageShell(parent)) {
|
|
592
|
+
return parent;
|
|
593
|
+
}
|
|
594
|
+
parent = getParentOrHostElement(parent);
|
|
595
|
+
step += 1;
|
|
596
|
+
}
|
|
597
|
+
}
|
|
598
|
+
return primaryTarget;
|
|
599
|
+
}
|
|
600
|
+
/**
|
|
601
|
+
* Produces a plain-language, jargon-free label for any DOM element (e.g. `"Upgrade Cluster" button`,
|
|
602
|
+
* `"Order Summary" card`, `"Email Address" input field`) with zero CSS selectors or pixel metrics.
|
|
603
|
+
*/
|
|
604
|
+
export function describeSmartComponent(el, customSelectors = [], originalLeaf) {
|
|
605
|
+
const kind = inferFriendlyComponentKind(el);
|
|
606
|
+
let name = null;
|
|
607
|
+
const ariaLabel = (el.getAttribute("aria-label") || "").trim() ||
|
|
608
|
+
(el.getAttribute("placeholder") || "").trim() ||
|
|
609
|
+
(el.getAttribute("alt") || "").trim() ||
|
|
610
|
+
(el.getAttribute("title") || "").trim();
|
|
611
|
+
if (ariaLabel) {
|
|
612
|
+
name = truncateCleanPhrase(ariaLabel, 30);
|
|
613
|
+
}
|
|
614
|
+
if (!name && isInteractiveSmartNode(el)) {
|
|
615
|
+
const ownText = extractSanitizedText(el, customSelectors);
|
|
616
|
+
if (ownText) {
|
|
617
|
+
name = truncateCleanPhrase(ownText, 28);
|
|
618
|
+
}
|
|
619
|
+
}
|
|
620
|
+
if (!name) {
|
|
621
|
+
const headingText = findFirstHeadingText(el, customSelectors);
|
|
622
|
+
if (headingText) {
|
|
623
|
+
name = truncateCleanPhrase(headingText, 30);
|
|
624
|
+
}
|
|
625
|
+
}
|
|
626
|
+
if (!name) {
|
|
627
|
+
for (const attr of ["data-component", "data-turbo-frame", "data-controller", "id", "name"]) {
|
|
628
|
+
const rawAttr = (el.getAttribute(attr) || "").trim();
|
|
629
|
+
if (rawAttr) {
|
|
630
|
+
const humanized = humanizeIdentifierToken(rawAttr);
|
|
631
|
+
if (humanized) {
|
|
632
|
+
name = truncateCleanPhrase(humanized, 28);
|
|
633
|
+
break;
|
|
634
|
+
}
|
|
635
|
+
}
|
|
636
|
+
}
|
|
637
|
+
}
|
|
638
|
+
if (!name) {
|
|
639
|
+
const snippet = extractSanitizedText(el, customSelectors);
|
|
640
|
+
if (snippet && snippet.length <= 42) {
|
|
641
|
+
name = truncateCleanPhrase(snippet, 28);
|
|
642
|
+
}
|
|
643
|
+
}
|
|
644
|
+
const lowerKind = kind.toLowerCase();
|
|
645
|
+
let label = kind;
|
|
646
|
+
if (name) {
|
|
647
|
+
const nameAlreadyHasKind = name.toLowerCase().endsWith(lowerKind);
|
|
648
|
+
label = nameAlreadyHasKind ? name : `“${name}” ${lowerKind}`;
|
|
649
|
+
}
|
|
650
|
+
return {
|
|
651
|
+
element: el,
|
|
652
|
+
label,
|
|
653
|
+
kind,
|
|
654
|
+
name,
|
|
655
|
+
promotedFromLeaf: Boolean(originalLeaf && originalLeaf !== el)
|
|
656
|
+
};
|
|
657
|
+
}
|
|
658
|
+
export function computeFriendlyComponentLabel(el, customSelectors = []) {
|
|
659
|
+
return describeSmartComponent(el, customSelectors).label;
|
|
660
|
+
}
|
|
661
|
+
export function resolveAncestorChain(el, customSelectors = [], maxDepth = 8) {
|
|
662
|
+
if (!el || !isSelectableElement(el, customSelectors)) {
|
|
663
|
+
return [];
|
|
664
|
+
}
|
|
665
|
+
const chain = [];
|
|
666
|
+
let current = el;
|
|
667
|
+
while (current && chain.length < maxDepth) {
|
|
668
|
+
if (isSelectableElement(current, customSelectors)) {
|
|
669
|
+
chain.unshift(current);
|
|
670
|
+
}
|
|
671
|
+
current = getParentOrHostElement(current);
|
|
672
|
+
}
|
|
673
|
+
return chain;
|
|
674
|
+
}
|
|
675
|
+
function isAncestorOf(possibleAncestor, node) {
|
|
676
|
+
let current = getParentOrHostElement(node);
|
|
677
|
+
while (current) {
|
|
678
|
+
if (current === possibleAncestor)
|
|
679
|
+
return true;
|
|
680
|
+
current = getParentOrHostElement(current);
|
|
681
|
+
}
|
|
682
|
+
return false;
|
|
683
|
+
}
|
|
684
|
+
/**
|
|
685
|
+
* Builds an ordered list of candidate elements for a pointer location so users can
|
|
686
|
+
* disambiguate overlapping sibling layers, deeply nested children, and parent containers.
|
|
687
|
+
*
|
|
688
|
+
* Order:
|
|
689
|
+
* 1. Direct child elements (if the target is a container with immediate selectable children)
|
|
690
|
+
* 2. Primary hovered/clicked target ("target")
|
|
691
|
+
* 3. Overlapping non-ancestor elements at the same screen coordinate ("overlap")
|
|
692
|
+
* 4. DOM ancestors from immediate parent up to top-level layout section ("ancestor")
|
|
693
|
+
*/
|
|
694
|
+
export function resolveCandidateStack(primaryTarget, pointElements = [], customSelectors = [], maxCandidates = 10) {
|
|
695
|
+
const seen = new Set();
|
|
696
|
+
const stack = [];
|
|
697
|
+
const validPrimary = primaryTarget && isSelectableElement(primaryTarget, customSelectors)
|
|
698
|
+
? primaryTarget
|
|
699
|
+
: pointElements.find((candidate) => isSelectableElement(candidate, customSelectors)) || null;
|
|
700
|
+
if (!validPrimary) {
|
|
701
|
+
return [];
|
|
702
|
+
}
|
|
703
|
+
// 1. Primary target at index 0 so default hover/click is the exact element under pointer
|
|
704
|
+
seen.add(validPrimary);
|
|
705
|
+
stack.push(describeElementCandidate(validPrimary, "target", 0, customSelectors));
|
|
706
|
+
// 2. Overlapping non-ancestor elements from elementsFromPoint (e.g., elements behind an overlay or badge)
|
|
707
|
+
for (const ptEl of pointElements) {
|
|
708
|
+
if (stack.length >= maxCandidates)
|
|
709
|
+
break;
|
|
710
|
+
if (seen.has(ptEl))
|
|
711
|
+
continue;
|
|
712
|
+
if (!isSelectableElement(ptEl, customSelectors))
|
|
713
|
+
continue;
|
|
714
|
+
if (!isAncestorOf(ptEl, validPrimary)) {
|
|
715
|
+
seen.add(ptEl);
|
|
716
|
+
stack.push(describeElementCandidate(ptEl, "overlap", stack.length, customSelectors));
|
|
717
|
+
}
|
|
718
|
+
}
|
|
719
|
+
// 3. Direct selectable children of the primary target (when a wrapper intercepts hover)
|
|
720
|
+
const childNodes = validPrimary.children ||
|
|
721
|
+
(validPrimary.childNodes || []);
|
|
722
|
+
for (let i = 0; i < childNodes.length; i += 1) {
|
|
723
|
+
if (stack.length >= maxCandidates)
|
|
724
|
+
break;
|
|
725
|
+
const node = childNodes[i];
|
|
726
|
+
if (node && node.nodeType === 1 && !seen.has(node) && isSelectableElement(node, customSelectors)) {
|
|
727
|
+
seen.add(node);
|
|
728
|
+
stack.push(describeElementCandidate(node, "child", stack.length, customSelectors));
|
|
729
|
+
}
|
|
730
|
+
}
|
|
731
|
+
// 4. Ancestor chain walking up from validPrimary
|
|
732
|
+
let parent = getParentOrHostElement(validPrimary);
|
|
733
|
+
while (parent && stack.length < maxCandidates) {
|
|
734
|
+
if (!seen.has(parent) && isSelectableElement(parent, customSelectors)) {
|
|
735
|
+
seen.add(parent);
|
|
736
|
+
stack.push(describeElementCandidate(parent, "ancestor", stack.length, customSelectors));
|
|
737
|
+
}
|
|
738
|
+
parent = getParentOrHostElement(parent);
|
|
739
|
+
}
|
|
740
|
+
return stack;
|
|
741
|
+
}
|
|
742
|
+
export function captureElementSnapshot(el, customSelectors = [], clientRef, extraMetadata) {
|
|
743
|
+
if (isElementExcluded(el, customSelectors)) {
|
|
744
|
+
return null;
|
|
745
|
+
}
|
|
746
|
+
const boundingRect = computeBoundingRect(el);
|
|
747
|
+
const smart = describeSmartComponent(el, customSelectors);
|
|
748
|
+
const viewport = {
|
|
749
|
+
width: typeof window !== "undefined" ? window.innerWidth || 1024 : 1024,
|
|
750
|
+
height: typeof window !== "undefined" ? window.innerHeight || 768 : 768
|
|
751
|
+
};
|
|
752
|
+
const generatedRef = clientRef || `el_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
|
|
753
|
+
return {
|
|
754
|
+
client_ref: generatedRef,
|
|
755
|
+
tag_name: (el.tagName || "div").toLowerCase(),
|
|
756
|
+
selector: computeSelector(el),
|
|
757
|
+
dom_path: computeDomPath(el),
|
|
758
|
+
text_content: extractSanitizedText(el, customSelectors),
|
|
759
|
+
attributes_snapshot: extractSanitizedAttributes(el),
|
|
760
|
+
bounding_rect: boundingRect,
|
|
761
|
+
viewport: viewport,
|
|
762
|
+
metadata: {
|
|
763
|
+
friendly_label: smart.label,
|
|
764
|
+
component_kind: smart.kind,
|
|
765
|
+
...(extraMetadata || {})
|
|
766
|
+
},
|
|
767
|
+
captured_at: new Date().toISOString()
|
|
768
|
+
};
|
|
769
|
+
}
|