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.
Files changed (60) hide show
  1. package/MIT-LICENSE +21 -0
  2. package/README.md +709 -2
  3. package/app/assets/javascripts/context_drop/context_drop.js +8936 -0
  4. package/dist/app/javascript/context_drop/api-client.d.ts +41 -0
  5. package/dist/app/javascript/context_drop/api-client.js +279 -0
  6. package/dist/app/javascript/context_drop/element-picker.d.ts +111 -0
  7. package/dist/app/javascript/context_drop/element-picker.js +1428 -0
  8. package/dist/app/javascript/context_drop/icons.d.ts +32 -0
  9. package/dist/app/javascript/context_drop/icons.js +32 -0
  10. package/dist/app/javascript/context_drop/index.d.ts +7 -0
  11. package/dist/app/javascript/context_drop/index.js +9 -0
  12. package/dist/app/javascript/context_drop/markdown.d.ts +7 -0
  13. package/dist/app/javascript/context_drop/markdown.js +129 -0
  14. package/dist/app/javascript/context_drop/sanitizer.d.ts +38 -0
  15. package/dist/app/javascript/context_drop/sanitizer.js +769 -0
  16. package/dist/app/javascript/context_drop/screenshot.d.ts +21 -0
  17. package/dist/app/javascript/context_drop/screenshot.js +245 -0
  18. package/dist/app/javascript/context_drop/styles.d.ts +1 -0
  19. package/dist/app/javascript/context_drop/styles.js +2015 -0
  20. package/dist/app/javascript/context_drop/types.d.ts +239 -0
  21. package/dist/app/javascript/context_drop/types.js +1 -0
  22. package/dist/app/javascript/context_drop/widget.d.ts +188 -0
  23. package/dist/app/javascript/context_drop/widget.js +3227 -0
  24. package/dist/src/cli.d.ts +3 -0
  25. package/dist/src/cli.js +207 -0
  26. package/dist/src/index.d.ts +5 -0
  27. package/dist/src/index.js +5 -0
  28. package/dist/src/mcp/dispatcher.d.ts +42 -0
  29. package/dist/src/mcp/dispatcher.js +869 -0
  30. package/dist/src/mcp/environment-router.d.ts +38 -0
  31. package/dist/src/mcp/environment-router.js +174 -0
  32. package/dist/src/mcp/index.d.ts +24 -0
  33. package/dist/src/mcp/index.js +75 -0
  34. package/dist/src/mcp/remote-client.d.ts +25 -0
  35. package/dist/src/mcp/remote-client.js +98 -0
  36. package/dist/src/next/index.d.ts +13 -0
  37. package/dist/src/next/index.js +25 -0
  38. package/dist/src/next/server.d.ts +1 -0
  39. package/dist/src/next/server.js +1 -0
  40. package/dist/src/react/index.d.ts +90 -0
  41. package/dist/src/react/index.js +124 -0
  42. package/dist/src/server/handler.d.ts +42 -0
  43. package/dist/src/server/handler.js +677 -0
  44. package/dist/src/server/index.d.ts +8 -0
  45. package/dist/src/server/index.js +8 -0
  46. package/dist/src/server/sanitizer.d.ts +15 -0
  47. package/dist/src/server/sanitizer.js +201 -0
  48. package/dist/src/server/storage/local.d.ts +22 -0
  49. package/dist/src/server/storage/local.js +574 -0
  50. package/dist/src/server/storage/memory.d.ts +5 -0
  51. package/dist/src/server/storage/memory.js +221 -0
  52. package/dist/src/server/storage/postgres.d.ts +27 -0
  53. package/dist/src/server/storage/postgres.js +446 -0
  54. package/dist/src/server/types.d.ts +190 -0
  55. package/dist/src/server/types.js +7 -0
  56. package/dist/src/server/upload-validator.d.ts +16 -0
  57. package/dist/src/server/upload-validator.js +196 -0
  58. package/dist/src/widget/index.d.ts +1 -0
  59. package/dist/src/widget/index.js +1 -0
  60. 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
+ }