npm - @vexralabs/zerodom - Versions diffs - 0.0.1 - Mend

@vexralabs/zerodom 0.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (13) hide show

package/dist/playwright.d.ts ADDED Viewed

@@ -0,0 +1,30 @@
+/** Playwright (Node) middleware adapter. Port of zerodom/playwright_wrapper.py. */
+import type { FrameLike } from "./frames.js";
+import { InteractionGraph } from "./parser.js";
+export declare const SERIALIZE = "() => {\n  const roots = [];\n  const marked = [];\n  const visit = (root) => {\n    for (const el of root.querySelectorAll('*')) {\n      if (el.shadowRoot) { roots.push(el.shadowRoot); visit(el.shadowRoot); }\n      // A stylesheet rule is invisible to a parser reading HTML text, so\n      // input.hidden-class looks clickable and an agent burns a 30s timeout\n      // on it. Only the browser knows; record what it knows.\n      //\n      // NOT contentVisibilityAuto: content-visibility:auto is a rendering\n      // optimisation for offscreen content, not a way to hide it. Counting it\n      // as hidden deletes everything below the fold \u2014 on vercel.com that was\n      // 129 of 177 controls, an agent blinded to most of the page.\n      if (!el.checkVisibility({ visibilityProperty: true })) {\n        el.setAttribute('data-zerodom-hidden', '');\n        marked.push(el);\n      }\n    }\n  };\n  visit(document);\n  const body = document.body;\n  if (!body || !body.getHTML) { for (const el of marked) el.removeAttribute('data-zerodom-hidden'); return null; }\n  try {\n    // Only <body>, never <head>. Scripts routinely append a <div> into head;\n    // Chromium serializes it faithfully, but re-parsing HTML text treats flow\n    // content in head as the implicit start of body \u2014 which relocated 40+ head\n    // elements into europa.eu's body and shifted every nth-of-type index after\n    // them. The title is the one thing worth carrying across.\n    const attrs = (el) => [...el.attributes].map(a => ` ${a.name}=\"${a.value.replace(/\"/g, '&quot;')}\"`).join('');\n    const title = document.title.replace(/&/g, '&amp;').replace(/</g, '&lt;');\n    return '<html' + attrs(document.documentElement) + '><head><title>' + title\n         + '</title></head><body' + attrs(body) + '>'\n         + body.getHTML({ serializableShadowRoots: true, shadowRoots: roots })\n         + '</body></html>';\n  } finally {\n    // The page belongs to the caller; leave it exactly as we found it. This\n    // whole function is synchronous, so nothing else can observe the marks.\n    for (const el of marked) el.removeAttribute('data-zerodom-hidden');\n  }\n}";
+/** Minimal surface this module needs from a Playwright Page. */
+export interface PageLike extends FrameLike {
+    content(): Promise<string>;
+    evaluate<T>(fn: string): Promise<T>;
+    frames(): FrameLike[];
+    mainFrame(): FrameLike;
+    frameLocator(selector: string): unknown;
+    locator(selector: string): unknown;
+}
+/** Page HTML including open shadow roots. */
+export declare function serialize(page: PageLike): Promise<string>;
+/** 1-line Playwright integration: `ZeroDOM.fromPage(page)`. */
+export declare const ZeroDOM: {
+    fromHtml(html: string, url?: string): InteractionGraph;
+    /**
+     * Parse a Playwright page.
+     *
+     * `frames: true` also walks same- and cross-origin iframes, which is the only
+     * way to see inside embedded editors, payment fields and consent gates. Off by
+     * default: it costs a serialize per frame, and on an ad-heavy page most of
+     * those frames are advertising.
+     */
+    fromPage(page: PageLike, options?: {
+        frames?: boolean;
+    }): Promise<InteractionGraph>;
+};

package/dist/playwright.js ADDED Viewed

@@ -0,0 +1,130 @@
+/** Playwright (Node) middleware adapter. Port of zerodom/playwright_wrapper.py. */
+import { frameChain, isWorthReading, renumber } from "./frames.js";
+import { ZeroDOMParser } from "./parser.js";
+// `page.content()` serializes light DOM only, so controls inside a shadow root are
+// invisible — and worse, Playwright's CSS engine *pierces* open shadow roots when it
+// clicks, so a light-DOM path like `#host > button` silently matches shadow elements
+// we never knew were there. Chromium's getHTML() emits open roots as
+// `<template shadowrootmode>`, which gives the parser the whole picture.
+//
+// Closed roots stay unreachable by design; no API exposes them. Identical to the
+// Python SERIALIZE string — it's JavaScript either way, evaluated in the page.
+export const SERIALIZE = `() => {
+  const roots = [];
+  const marked = [];
+  const visit = (root) => {
+    for (const el of root.querySelectorAll('*')) {
+      if (el.shadowRoot) { roots.push(el.shadowRoot); visit(el.shadowRoot); }
+      // A stylesheet rule is invisible to a parser reading HTML text, so
+      // input.hidden-class looks clickable and an agent burns a 30s timeout
+      // on it. Only the browser knows; record what it knows.
+      //
+      // NOT contentVisibilityAuto: content-visibility:auto is a rendering
+      // optimisation for offscreen content, not a way to hide it. Counting it
+      // as hidden deletes everything below the fold — on vercel.com that was
+      // 129 of 177 controls, an agent blinded to most of the page.
+      if (!el.checkVisibility({ visibilityProperty: true })) {
+        el.setAttribute('data-zerodom-hidden', '');
+        marked.push(el);
+      }
+    }
+  };
+  visit(document);
+  const body = document.body;
+  if (!body || !body.getHTML) { for (const el of marked) el.removeAttribute('data-zerodom-hidden'); return null; }
+  try {
+    // Only <body>, never <head>. Scripts routinely append a <div> into head;
+    // Chromium serializes it faithfully, but re-parsing HTML text treats flow
+    // content in head as the implicit start of body — which relocated 40+ head
+    // elements into europa.eu's body and shifted every nth-of-type index after
+    // them. The title is the one thing worth carrying across.
+    const attrs = (el) => [...el.attributes].map(a => \` \${a.name}="\${a.value.replace(/"/g, '&quot;')}"\`).join('');
+    const title = document.title.replace(/&/g, '&amp;').replace(/</g, '&lt;');
+    return '<html' + attrs(document.documentElement) + '><head><title>' + title
+         + '</title></head><body' + attrs(body) + '>'
+         + body.getHTML({ serializableShadowRoots: true, shadowRoots: roots })
+         + '</body></html>';
+  } finally {
+    // The page belongs to the caller; leave it exactly as we found it. This
+    // whole function is synchronous, so nothing else can observe the marks.
+    for (const el of marked) el.removeAttribute('data-zerodom-hidden');
+  }
+}`;
+/** Page HTML including open shadow roots. */
+export async function serialize(page) {
+    return (await page.evaluate(SERIALIZE)) ?? (await page.content());
+}
+/** 1-line Playwright integration: `ZeroDOM.fromPage(page)`. */
+export const ZeroDOM = {
+    fromHtml(html, url = "about:blank") {
+        return new ZeroDOMParser(html, url).parse();
+    },
+    /**
+     * Parse a Playwright page.
+     *
+     * `frames: true` also walks same- and cross-origin iframes, which is the only
+     * way to see inside embedded editors, payment fields and consent gates. Off by
+     * default: it costs a serialize per frame, and on an ad-heavy page most of
+     * those frames are advertising.
+     */
+    async fromPage(page, options = {}) {
+        const html = await serialize(page);
+        const graph = new ZeroDOMParser(html, page.url()).parse();
+        return options.frames ? mergeFrames(page, graph) : graph;
+    },
+};
+/**
+ * One frame's nodes, `[]` if not worth reading, `null` if it refused.
+ *
+ * Every failure is swallowed here so `Promise.all` never has to care: one
+ * hostile advertisement must not cost the caller the rest of the page.
+ */
+async function readFrame(frame) {
+    if (!(await isWorthReading(frame)))
+        return [];
+    const chain = await frameChain(frame);
+    if (chain === null)
+        return null;
+    try {
+        const html = await serialize(frame);
+        const sub = new ZeroDOMParser(html, frame.url()).parse();
+        for (const node of sub.nodes) {
+            node.frame = chain;
+            node.frame_url = frame.url();
+        }
+        return sub.nodes;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Append every readable iframe's nodes to the top document's, in frame order.
+ *
+ * Frames are independent documents, so reading them serially just adds up round
+ * trips. `Promise.all` preserves order, which matters: node ids are assigned in
+ * document order and must stay stable between reads.
+ */
+async function mergeFrames(page, graph) {
+    const children = page.frames().filter((f) => f !== page.mainFrame());
+    const results = await Promise.all(children.map((f) => readFrame(f).catch(() => null)));
+    const added = [];
+    let skipped = 0;
+    for (const result of results) {
+        if (result === null)
+            skipped += 1;
+        else
+            added.push(...result);
+    }
+    if (added.length) {
+        graph.nodes = renumber([...graph.nodes, ...added]);
+        graph.metadata.total_interactive_nodes = graph.nodes.length;
+        // A graph that reached into frames is no longer "almost empty because the
+        // content is in an iframe" — that warning would now be misleading.
+        delete graph.metadata.warning;
+    }
+    graph.metadata.frames_read = new Set(added.map((n) => JSON.stringify(n.frame))).size;
+    if (skipped)
+        graph.metadata.frames_skipped = skipped;
+    return graph;
+}

package/package.json ADDED Viewed

@@ -0,0 +1,41 @@
+{
+  "name": "@vexralabs/zerodom",
+  "version": "0.0.1",
+  "description": "DOM-to-Interaction-Graph middleware for AI web agents (TypeScript port)",
+  "license": "Apache-2.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": ["dist"],
+  "keywords": ["dom", "llm", "agent", "playwright", "browser-automation", "tokens", "mcp"],
+  "author": {
+    "name": "Syed Husnain Khalid",
+    "email": "contact@vexralabs.com"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/DevHusnainAi/zerodom.git",
+    "directory": "js"
+  },
+  "homepage": "https://github.com/DevHusnainAi/zerodom/tree/main/js#readme",
+  "bugs": "https://github.com/DevHusnainAi/zerodom/issues",
+  "scripts": {
+    "build": "tsc",
+    "prepare": "tsc",
+    "pretest": "tsc",
+    "test": "node --test --experimental-strip-types test/*.test.ts"
+  },
+  "dependencies": {
+    "linkedom": "^0.18.13"
+  },
+  "devDependencies": {
+    "@types/node": "^22.20.2",
+    "typescript": "^5.9.3"
+  }
+}