@productivemark/snipcss 1.0.0

package/dist/extraction/dom-labeler.js

@@ -0,0 +1,124 @@
+import { randomLetters } from '../utils/helpers.js';
+/**
+ * Labels DOM elements with unique snipcss marker classes.
+ * Replaces the content script's snipcssLabelSubelements function.
+ * Runs entirely via page.evaluate() - no content script needed.
+ */
+export class DomLabeler {
+    /**
+     * Label the target element and all its descendants with unique snipcss classes.
+     * Returns the list of classnames and the HTML.
+     *
+     * Port of snipcssLabelSubelements from sniptools.js
+     */
+    async labelElements(page, selector) {
+        const snipId = randomLetters(4);
+        const result = await page.evaluate(({ selector, snipId }) => {
+            const root = document.querySelector(selector);
+            if (!root) {
+                return {
+                    error: `Element not found: ${selector}`,
+                    allClassnamesArr: [],
+                    allElementOuterHtml: '',
+                    allLabelOuterHtml: '',
+                    rootSelector: selector,
+                    rootClassname: '',
+                };
+            }
+            const allClassnamesArr = [];
+            let idCounter = 0;
+            function labelElement(elem, parentId, level) {
+                if (elem.nodeType !== 1)
+                    return; // Element nodes only
+                const tagName = elem.tagName.toLowerCase();
+                // Skip script/style/noscript
+                if (['script', 'style', 'noscript', 'link', 'meta'].includes(tagName))
+                    return;
+                const currId = idCounter++;
+                const className = `snipcss${snipId}-${level}-${parentId}-${currId}`;
+                elem.classList.add(className);
+                allClassnamesArr.push(className);
+                // Label children recursively
+                const children = elem.children;
+                for (let i = 0; i < children.length; i++) {
+                    labelElement(children[i], currId, level + 1);
+                }
+            }
+            // Label root and all descendants
+            labelElement(root, 0, 0);
+            const rootClassname = allClassnamesArr[0] || '';
+            // Capture HTML after labeling
+            const allElementOuterHtml = root.outerHTML;
+            // Also capture a version with just the labels for Tailwind
+            const allLabelOuterHtml = root.outerHTML;
+            return {
+                allClassnamesArr,
+                allElementOuterHtml,
+                allLabelOuterHtml,
+                rootSelector: selector,
+                rootClassname,
+            };
+        }, { selector, snipId });
+        if ('error' in result && result.error) {
+            throw new Error(result.error);
+        }
+        return result;
+    }
+    /**
+     * Remove all snipcss marker classes from the page DOM.
+     * Called after extraction is complete.
+     */
+    async removeLabels(page) {
+        await page.evaluate(() => {
+            const elements = document.querySelectorAll('[class*="snipcss"]');
+            elements.forEach((elem) => {
+                const classes = [...elem.classList];
+                classes.forEach((cls) => {
+                    if (cls.startsWith('snipcss')) {
+                        elem.classList.remove(cls);
+                    }
+                });
+                // Clean up empty class attributes
+                if (elem.classList.length === 0) {
+                    elem.removeAttribute('class');
+                }
+            });
+        });
+    }
+    /**
+     * Get the outerHTML of an element after labels have been removed.
+     */
+    async getCleanHtml(page, selector) {
+        return await page.evaluate((sel) => {
+            const elem = document.querySelector(sel);
+            if (!elem)
+                return '';
+            // Clone and remove snipcss classes
+            const clone = elem.cloneNode(true);
+            const labeled = clone.querySelectorAll('[class*="snipcss"]');
+            labeled.forEach((el) => {
+                const classes = [...el.classList];
+                classes.forEach((cls) => {
+                    if (cls.startsWith('snipcss')) {
+                        el.classList.remove(cls);
+                    }
+                });
+                if (el.classList.length === 0) {
+                    el.removeAttribute('class');
+                }
+            });
+            // Also clean the root
+            const rootClasses = [...clone.classList];
+            rootClasses.forEach((cls) => {
+                if (cls.startsWith('snipcss')) {
+                    clone.classList.remove(cls);
+                }
+            });
+            if (clone.classList.length === 0) {
+                clone.removeAttribute('class');
+            }
+            return clone.outerHTML;
+        }, selector);
+    }
+}
+//# sourceMappingURL=dom-labeler.js.map

package/dist/extraction/dom-labeler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dom-labeler.js","sourceRoot":"","sources":["../../src/extraction/dom-labeler.ts"],"names":[],"mappings":"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"}

package/dist/extraction/element-discovery.d.ts

@@ -0,0 +1,59 @@
+import { Page } from 'playwright';
+/**
+ * Discovered element with semantic information for agent-driven extraction.
+ */
+export interface DiscoveredElement {
+    /** Numeric label (1, 2, 3...) for referencing in screenshots */
+    label: number;
+    /** Unique CSS selector guaranteed to match exactly one element */
+    selector: string;
+    /** HTML tag name */
+    tag: string;
+    /** Semantic role inferred from tag, ARIA role, class names, and position */
+    semanticType: string;
+    /** Parent chain context (e.g., "inside main > .content") */
+    parentContext: string;
+    /** Bounding box (absolute, accounting for scroll) */
+    rect: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    /** Background color (computed) */
+    backgroundColor: string;
+    /** Number of child elements */
+    childCount: number;
+    /** Text content preview (first 80 chars) */
+    textPreview: string;
+    /** Element's class list */
+    classes: string;
+    /** Element's id */
+    id: string;
+    /** Nesting depth from body */
+    depth: number;
+}
+/**
+ * Discover page segments using the SnipCSS page segmenter approach:
+ * 1. Sample visible elements via grid-point probing (elementFromPoint)
+ * 2. Scroll the page to catch all content including lazy-loaded
+ * 3. Bottom-up merge: consolidate small elements into parent containers
+ * 4. Smart filter: split oversized parents, remove redundant wrappers
+ * 5. Generate unique selectors and enrich with semantic metadata
+ *
+ * Ported from snip-extension/js/page_segmenter.js
+ */
+export declare function discoverElements(page: Page): Promise<DiscoveredElement[]>;
+/**
+ * Inject numbered badge overlay into the page at each element's position.
+ */
+export declare function injectLabelOverlay(page: Page, elements: DiscoveredElement[]): Promise<void>;
+/**
+ * Remove the label overlay from the page.
+ */
+export declare function removeLabelOverlay(page: Page): Promise<void>;
+/**
+ * Format discovered elements as a human-readable legend.
+ */
+export declare function formatElementLegend(elements: DiscoveredElement[]): string;
+//# sourceMappingURL=element-discovery.d.ts.map

package/dist/extraction/element-discovery.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"element-discovery.d.ts","sourceRoot":"","sources":["../../src/extraction/element-discovery.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AAElC;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,gEAAgE;IAChE,KAAK,EAAE,MAAM,CAAC;IACd,kEAAkE;IAClE,QAAQ,EAAE,MAAM,CAAC;IACjB,oBAAoB;IACpB,GAAG,EAAE,MAAM,CAAC;IACZ,4EAA4E;IAC5E,YAAY,EAAE,MAAM,CAAC;IACrB,4DAA4D;IAC5D,aAAa,EAAE,MAAM,CAAC;IACtB,qDAAqD;IACrD,IAAI,EAAE;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IAC9D,kCAAkC;IAClC,eAAe,EAAE,MAAM,CAAC;IACxB,+BAA+B;IAC/B,UAAU,EAAE,MAAM,CAAC;IACnB,4CAA4C;IAC5C,WAAW,EAAE,MAAM,CAAC;IACpB,2BAA2B;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,mBAAmB;IACnB,EAAE,EAAE,MAAM,CAAC;IACX,8BAA8B;IAC9B,KAAK,EAAE,MAAM,CAAC;CACf;AAWD;;;;;;;;;GASG;AACH,wBAAsB,gBAAgB,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAAC,iBAAiB,EAAE,CAAC,CA6W/E;AA2DD;;GAEG;AACH,wBAAsB,kBAAkB,CACtC,IAAI,EAAE,IAAI,EACV,QAAQ,EAAE,iBAAiB,EAAE,GAC5B,OAAO,CAAC,IAAI,CAAC,CAuDf;AAED;;GAEG;AACH,wBAAsB,kBAAkB,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CASlE;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,iBAAiB,EAAE,GAAG,MAAM,CAUzE"}