playwright-deblock 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,101 @@
+# playwright-deblock
+
+Automatic fix for Playwright `file://` navigation blocks.
+One `require()`, works forever.
+
+## Problem
+
+Restricted Playwright runners block `file://` URLs:
+
+```
+Access to 'file:' URL is blocked. Allowed protocols: http, https, about, data.
+```
+
+## Solution
+
+```bash
+npm install playwright-deblock
+```
+
+```js
+require("playwright-deblock");
+```
+
+Done. Every `page.goto("file://...")` is now automatically served over `http://localhost`.
+
+## Usage
+
+### Auto-patch (recommended)
+
+```js
+// Add this ONE line at the top of your script or test
+require("playwright-deblock");
+
+// Then use file:// like normal — it just works
+const browser = await chromium.launch();
+const page = await browser.newPage();
+await page.goto("file:///home/user/page.html"); // auto-redirected to http://
+```
+
+### Playwright config (global)
+
+```js
+// playwright.config.js
+module.exports = {
+  globalSetup: require.resolve("playwright-deblock/register"),
+};
+```
+
+Or via CLI:
+
+```bash
+npx playwright test --require playwright-deblock/register
+```
+
+### With options
+
+```js
+const deblock = require("playwright-deblock");
+deblock.apply({ strategy: "data", silent: true });
+```
+
+### Manual helper (no monkey-patching)
+
+```js
+const { serveAndGoto, cleanup } = require("playwright-deblock/helper");
+
+test("loads local HTML", async ({ page }) => {
+  await serveAndGoto(page, "/path/to/file.html");
+  await expect(page.locator("h1")).toBeVisible();
+});
+
+test.afterAll(() => cleanup());
+```
+
+## How it works
+
+| Strategy | Protocol | Method |
+|---|---|---|
+| `http` (primary) | `http://` | Starts localhost server, serves the file's directory |
+| `data` (fallback) | `data:` | Inlines CSS/JS/images into a data: URL |
+
+- Original HTML files are **never modified** on disk
+- One server per directory, reused across calls
+- Servers auto-cleanup on process exit
+- Works with `chromium`, `firefox`, `webkit`
+- Works with `playwright` and `playwright-core`
+
+## API
+
+| Export | Description |
+|---|---|
+| `apply(opts?)` | Re-apply patch with options |
+| `cleanup()` | Stop all HTTP servers |
+| `convertUrl(url)` | Convert a file:// URL manually |
+| `serveAndGoto(page, path)` | Navigate without monkey-patching |
+| `buildDataUrl(path)` | Build a data: URL from HTML file |
+| `inlineAssets(path)` | Inline assets into HTML string |
+
+## License
+
+MIT

package/helper.js

@@ -0,0 +1,65 @@
+/**
+ * Manual helper — no monkey-patching, explicit control.
+ *
+ *   const { serveAndGoto, cleanup } = require("playwright-deblock/helper");
+ *
+ *   test("my test", async ({ page }) => {
+ *     await serveAndGoto(page, "/path/to/file.html");
+ *   });
+ *
+ *   test.afterAll(() => cleanup());
+ */
+
+const fs = require("fs");
+const path = require("path");
+const { getServer, stopAll } = require("./lib/server");
+const { buildDataUrl } = require("./lib/inline");
+
+/**
+ * Navigate a Playwright page to a local HTML file via allowed protocol.
+ *
+ * @param {import("playwright").Page} page
+ * @param {string} htmlPath — absolute or relative path to the HTML file
+ * @param {object} [opts]
+ * @param {"auto"|"http"|"data"} [opts.strategy="auto"]
+ * @param {number} [opts.timeout=30000]
+ * @param {string} [opts.waitUntil="networkidle"]
+ * @returns {Promise<string>} the URL used
+ */
+async function serveAndGoto(page, htmlPath, opts = {}) {
+  const {
+    strategy = "auto",
+    timeout = 30000,
+    waitUntil = "networkidle",
+  } = opts;
+
+  const resolved = path.resolve(htmlPath);
+  if (!fs.existsSync(resolved)) {
+    throw new Error(`[playwright-deblock] File not found: ${resolved}`);
+  }
+
+  const rootDir = path.dirname(resolved);
+  const fileName = path.basename(resolved);
+
+  // Try HTTP
+  if (strategy === "http" || strategy === "auto") {
+    try {
+      const { port } = await getServer(rootDir);
+      const url = `http://127.0.0.1:${port}/${fileName}`;
+      await page.goto(url, { waitUntil, timeout });
+      return url;
+    } catch (e) {
+      if (strategy === "http") throw e;
+    }
+  }
+
+  // data: URL
+  const dataUrl = buildDataUrl(resolved);
+  await page.goto(dataUrl, { waitUntil: "load", timeout });
+  return "data:text/html;...";
+}
+
+module.exports = {
+  serveAndGoto,
+  cleanup: stopAll,
+};

package/index.d.ts

@@ -0,0 +1,41 @@
+import type { Page } from "playwright";
+
+interface DeblockOptions {
+  /** Which strategy to use. Default: "auto" (http first, data: fallback) */
+  strategy?: "auto" | "http" | "data";
+  /** Suppress console output. Default: false */
+  silent?: boolean;
+}
+
+interface ServeOptions {
+  /** Which strategy to use. Default: "auto" */
+  strategy?: "auto" | "http" | "data";
+  /** Navigation timeout in ms. Default: 30000 */
+  timeout?: number;
+  /** Playwright waitUntil value. Default: "networkidle" */
+  waitUntil?: "load" | "domcontentloaded" | "networkidle" | "commit";
+}
+
+/** Re-apply the patch with different options */
+export function apply(opts?: DeblockOptions): void;
+
+/** Stop all internal HTTP servers */
+export function cleanup(): void;
+
+/** Number of currently active servers */
+export function serverCount(): number;
+
+/** Convert a file:// URL to an allowed URL */
+export function convertUrl(url: string, opts?: DeblockOptions): Promise<string>;
+
+/** Parse a file:// URL to an absolute file path, or null */
+export function parseFileUrl(url: string): string | null;
+
+/** Read HTML and inline all local CSS/JS/images */
+export function inlineAssets(htmlPath: string): string;
+
+/** Build a data: URL from an HTML file with inlined assets */
+export function buildDataUrl(htmlPath: string): string;
+
+/** Navigate a page to a local HTML file via allowed protocol */
+export function serveAndGoto(page: Page, htmlPath: string, opts?: ServeOptions): Promise<string>;

package/index.js

@@ -0,0 +1,54 @@
+/**
+ * playwright-deblock
+ *
+ * Automatic fix for Playwright file:// navigation blocks.
+ *
+ * Usage:
+ *
+ *   // Option A: Auto-patch (recommended)
+ *   require("playwright-deblock");
+ *   // or:
+ *   require("playwright-deblock/register");
+ *
+ *   // Option B: With options
+ *   const deblock = require("playwright-deblock");
+ *   deblock.apply({ strategy: "http", silent: true });
+ *
+ *   // Option C: Manual helper (no monkey-patching)
+ *   const { serveAndGoto, cleanup } = require("playwright-deblock/helper");
+ *   await serveAndGoto(page, "/path/to/file.html");
+ *
+ * After require(), all page.goto("file://...") calls are automatically
+ * converted to http://127.0.0.1:<port>/... (or data: URL as fallback).
+ */
+
+const { apply } = require("./lib/patch");
+const { stopAll, count } = require("./lib/server");
+const { convertUrl, parseFileUrl } = require("./lib/convert");
+const { inlineAssets, buildDataUrl } = require("./lib/inline");
+
+// Auto-apply on require()
+apply();
+
+module.exports = {
+  /** Re-apply the patch with different options */
+  apply,
+
+  /** Stop all internal HTTP servers */
+  cleanup: stopAll,
+
+  /** Number of active servers */
+  serverCount: count,
+
+  /** Convert a file:// URL to http:// or data: */
+  convertUrl,
+
+  /** Parse a file:// URL to an absolute path */
+  parseFileUrl,
+
+  /** Inline assets into HTML string */
+  inlineAssets,
+
+  /** Build a data: URL from an HTML file */
+  buildDataUrl,
+};

package/lib/convert.js

@@ -0,0 +1,67 @@
+/**
+ * Convert file:// URLs to http:// or data: URLs.
+ */
+
+const fs = require("fs");
+const path = require("path");
+const { getServer } = require("./server");
+const { buildDataUrl } = require("./inline");
+
+/**
+ * Parse a file:// URL to an absolute file path. Returns null if not file://.
+ */
+function parseFileUrl(urlStr) {
+  try {
+    const u = new URL(urlStr);
+    if (u.protocol !== "file:") return null;
+    let fp = decodeURIComponent(u.pathname);
+    // Windows: /C:/path → C:/path
+    if (/^\/[A-Za-z]:\//.test(fp)) fp = fp.slice(1);
+    return path.resolve(fp);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Convert a URL: if it's file://, reroute through localhost or data:.
+ * Non-file URLs pass through unchanged.
+ *
+ * @param {string} url
+ * @param {object} [opts]
+ * @param {"auto"|"http"|"data"} [opts.strategy="auto"]
+ * @param {boolean} [opts.silent=false]
+ * @returns {Promise<string>}
+ */
+async function convertUrl(url, opts = {}) {
+  const { strategy = "auto", silent = false } = opts;
+  const filePath = parseFileUrl(url);
+  if (!filePath) return url;
+
+  if (!fs.existsSync(filePath)) {
+    throw new Error(`[playwright-deblock] File not found: ${filePath} (from ${url})`);
+  }
+
+  const rootDir = path.dirname(filePath);
+  const fileName = path.basename(filePath);
+
+  // HTTP strategy
+  if (strategy === "http" || strategy === "auto") {
+    try {
+      const { port } = await getServer(rootDir);
+      const httpUrl = `http://127.0.0.1:${port}/${fileName}`;
+      if (!silent) console.log(`[playwright-deblock] ${url} → ${httpUrl}`);
+      return httpUrl;
+    } catch (e) {
+      if (strategy === "http") throw e;
+      if (!silent) console.warn(`[playwright-deblock] HTTP failed (${e.message}), using data: URL`);
+    }
+  }
+
+  // data: URL strategy
+  const dataUrl = buildDataUrl(filePath);
+  if (!silent) console.log(`[playwright-deblock] ${url} → data: URL (${(dataUrl.length / 1024).toFixed(1)} KB)`);
+  return dataUrl;
+}
+
+module.exports = { parseFileUrl, convertUrl };

package/lib/inline.js

@@ -0,0 +1,92 @@
+/**
+ * Inline external assets into HTML for data: URL loading.
+ * CSS → <style>, JS → <script>, images → base64 data URIs.
+ */
+
+const fs = require("fs");
+const path = require("path");
+const MIME = require("./mime");
+
+const MAX_IMG_SIZE = 2 * 1024 * 1024; // 2 MB
+
+function _tryRead(filePath, encoding) {
+  try {
+    return encoding ? fs.readFileSync(filePath, encoding) : fs.readFileSync(filePath);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Read an HTML file and inline all local CSS, JS, and images.
+ * Returns the modified HTML string.
+ */
+function inlineAssets(htmlPath) {
+  const dir = path.dirname(path.resolve(htmlPath));
+  let html = fs.readFileSync(htmlPath, "utf-8");
+
+  // Inline <link rel="stylesheet" href="..."> (both attribute orders)
+  const cssPattern =
+    /<link\s+(?=[^>]*rel\s*=\s*["']stylesheet["'])(?=[^>]*href\s*=\s*["']([^"']+)["'])[^>]*\/?>/gi;
+  html = html.replace(cssPattern, (match, href) => {
+    if (/^(https?:|data:|\/\/)/i.test(href)) return match;
+    const css = _tryRead(path.resolve(dir, href), "utf-8");
+    return css !== null ? `<style>/* ${href} */${css}</style>` : match;
+  });
+
+  // Catch remaining link+stylesheet combos the first regex missed
+  html = html.replace(
+    /<link\s+[^>]*href\s*=\s*["']([^"']+)["'][^>]*stylesheet[^>]*\/?>/gi,
+    (match, href) => {
+      if (/^(https?:|data:|\/\/)/i.test(href)) return match;
+      if (match.includes("<style>")) return match; // already inlined
+      const css = _tryRead(path.resolve(dir, href), "utf-8");
+      return css !== null ? `<style>/* ${href} */${css}</style>` : match;
+    }
+  );
+  html = html.replace(
+    /<link\s+[^>]*stylesheet[^>]*href\s*=\s*["']([^"']+)["'][^>]*\/?>/gi,
+    (match, href) => {
+      if (/^(https?:|data:|\/\/)/i.test(href)) return match;
+      if (match.includes("<style>")) return match;
+      const css = _tryRead(path.resolve(dir, href), "utf-8");
+      return css !== null ? `<style>/* ${href} */${css}</style>` : match;
+    }
+  );
+
+  // Inline <script src="..."></script>
+  html = html.replace(
+    /<script\s+[^>]*src\s*=\s*["']([^"']+)["'][^>]*>\s*<\/script>/gi,
+    (match, src) => {
+      if (/^(https?:|data:|\/\/)/i.test(src)) return match;
+      const js = _tryRead(path.resolve(dir, src), "utf-8");
+      return js !== null ? `<script>/* ${src} */${js}</script>` : match;
+    }
+  );
+
+  // Inline images as base64 data URIs
+  html = html.replace(
+    /(<img\s+[^>]*src\s*=\s*["'])([^"']+)(["'][^>]*>)/gi,
+    (match, pre, src, suf) => {
+      if (/^(https?:|data:|about:|\/\/)/i.test(src)) return match;
+      const p = path.resolve(dir, src);
+      const buf = _tryRead(p);
+      if (!buf || buf.length > MAX_IMG_SIZE) return match;
+      const ext = path.extname(p).toLowerCase();
+      const mime = MIME[ext] || "application/octet-stream";
+      return `${pre}data:${mime};base64,${buf.toString("base64")}${suf}`;
+    }
+  );
+
+  return html;
+}
+
+/**
+ * Build a complete data: URL from an HTML file, with assets inlined.
+ */
+function buildDataUrl(htmlPath) {
+  const html = inlineAssets(htmlPath);
+  return `data:text/html;charset=utf-8,${encodeURIComponent(html)}`;
+}
+
+module.exports = { inlineAssets, buildDataUrl };

package/lib/mime.js

@@ -0,0 +1,32 @@
+/** MIME type map for the static file server */
+module.exports = {
+  ".html": "text/html",
+  ".htm": "text/html",
+  ".css": "text/css",
+  ".js": "application/javascript",
+  ".mjs": "application/javascript",
+  ".json": "application/json",
+  ".png": "image/png",
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".gif": "image/gif",
+  ".svg": "image/svg+xml",
+  ".ico": "image/x-icon",
+  ".webp": "image/webp",
+  ".avif": "image/avif",
+  ".woff": "font/woff",
+  ".woff2": "font/woff2",
+  ".ttf": "font/ttf",
+  ".otf": "font/otf",
+  ".eot": "application/vnd.ms-fontobject",
+  ".mp4": "video/mp4",
+  ".webm": "video/webm",
+  ".ogg": "audio/ogg",
+  ".mp3": "audio/mpeg",
+  ".wav": "audio/wav",
+  ".pdf": "application/pdf",
+  ".xml": "application/xml",
+  ".txt": "text/plain",
+  ".wasm": "application/wasm",
+  ".map": "application/json",
+};

package/lib/patch.js

@@ -0,0 +1,128 @@
+/**
+ * Monkey-patch Playwright browser types so every page.goto()
+ * automatically converts file:// URLs.
+ */
+
+const { convertUrl } = require("./convert");
+const { stopAll } = require("./server");
+
+let _opts = {};
+let _patched = new WeakSet();
+
+function _patchPage(page) {
+  if (_patched.has(page)) return;
+  _patched.add(page);
+
+  const origGoto = page.goto.bind(page);
+  page.goto = async function (url, options) {
+    const converted = await convertUrl(url, _opts);
+    return origGoto(converted, options);
+  };
+}
+
+function _patchContext(ctx) {
+  if (_patched.has(ctx)) return;
+  _patched.add(ctx);
+
+  const origNewPage = ctx.newPage.bind(ctx);
+  ctx.newPage = async function (...args) {
+    const page = await origNewPage(...args);
+    _patchPage(page);
+    return page;
+  };
+}
+
+function _patchBrowser(browser) {
+  if (_patched.has(browser)) return;
+  _patched.add(browser);
+
+  const origNewContext = browser.newContext.bind(browser);
+  browser.newContext = async function (...args) {
+    const ctx = await origNewContext(...args);
+    _patchContext(ctx);
+    return ctx;
+  };
+
+  const origNewPage = browser.newPage.bind(browser);
+  browser.newPage = async function (...args) {
+    const page = await origNewPage(...args);
+    _patchPage(page);
+    return page;
+  };
+}
+
+function _patchBrowserType(bt) {
+  if (_patched.has(bt)) return;
+  _patched.add(bt);
+
+  const origLaunch = bt.launch.bind(bt);
+  bt.launch = async function (...args) {
+    const browser = await origLaunch(...args);
+    _patchBrowser(browser);
+    return browser;
+  };
+
+  if (bt.launchPersistentContext) {
+    const origLPC = bt.launchPersistentContext.bind(bt);
+    bt.launchPersistentContext = async function (...args) {
+      const ctx = await origLPC(...args);
+      _patchContext(ctx);
+      return ctx;
+    };
+  }
+
+  if (bt.connect) {
+    const origConnect = bt.connect.bind(bt);
+    bt.connect = async function (...args) {
+      const browser = await origConnect(...args);
+      _patchBrowser(browser);
+      return browser;
+    };
+  }
+
+  if (bt.connectOverCDP) {
+    const origCDP = bt.connectOverCDP.bind(bt);
+    bt.connectOverCDP = async function (...args) {
+      const browser = await origCDP(...args);
+      _patchBrowser(browser);
+      return browser;
+    };
+  }
+}
+
+/**
+ * Apply the deblock patch to Playwright.
+ *
+ * @param {object} [opts]
+ * @param {"auto"|"http"|"data"} [opts.strategy="auto"]
+ * @param {boolean} [opts.silent=false]
+ */
+function apply(opts = {}) {
+  _opts = opts;
+
+  // Try both playwright and playwright-core
+  const modules = [];
+  try { modules.push(require("playwright")); } catch {}
+  try { modules.push(require("playwright-core")); } catch {}
+
+  if (modules.length === 0) {
+    throw new Error(
+      "[playwright-deblock] Neither 'playwright' nor 'playwright-core' found. Install one first."
+    );
+  }
+
+  for (const pw of modules) {
+    for (const name of ["chromium", "firefox", "webkit"]) {
+      if (pw[name]) _patchBrowserType(pw[name]);
+    }
+  }
+
+  // Cleanup on exit
+  process.on("exit", stopAll);
+
+  if (!opts.silent) {
+    console.log("[playwright-deblock] Active — file:// URLs will be auto-redirected");
+  }
+}
+
+module.exports = { apply };

package/lib/server.js

@@ -0,0 +1,88 @@
+/**
+ * Zero-dependency static file server.
+ * One server per root directory, reused across calls.
+ */
+
+const http = require("http");
+const fs = require("fs");
+const path = require("path");
+const MIME = require("./mime");
+
+const _servers = new Map();
+const STARTUP_TIMEOUT = 5000;
+
+function _createHandler(rootDir) {
+  const root = path.resolve(rootDir);
+  return (req, res) => {
+    const urlPath = decodeURIComponent(req.url.split("?")[0]);
+    let fp = path.join(root, urlPath);
+
+    // Block path traversal
+    if (!path.resolve(fp).startsWith(root)) {
+      res.writeHead(403);
+      return res.end("Forbidden");
+    }
+
+    if (fs.existsSync(fp) && fs.statSync(fp).isDirectory()) {
+      fp = path.join(fp, "index.html");
+    }
+
+    if (!fs.existsSync(fp)) {
+      res.writeHead(404);
+      return res.end("Not Found");
+    }
+
+    const ext = path.extname(fp).toLowerCase();
+    const buf = fs.readFileSync(fp);
+    res.writeHead(200, {
+      "Content-Type": MIME[ext] || "application/octet-stream",
+      "Content-Length": buf.length,
+      "Cache-Control": "no-store",
+    });
+    res.end(buf);
+  };
+}
+
+/**
+ * Get or start a static server for the given root directory.
+ * Returns { server, port }.
+ */
+async function getServer(rootDir) {
+  const key = path.resolve(rootDir);
+  if (_servers.has(key)) return _servers.get(key);
+
+  return new Promise((resolve, reject) => {
+    const srv = http.createServer(_createHandler(key));
+    const t = setTimeout(
+      () => reject(new Error(`Server start timeout for ${key}`)),
+      STARTUP_TIMEOUT
+    );
+
+    srv.on("error", (e) => {
+      clearTimeout(t);
+      reject(e);
+    });
+
+    srv.listen(0, "127.0.0.1", () => {
+      clearTimeout(t);
+      const info = { server: srv, port: srv.address().port };
+      _servers.set(key, info);
+      resolve(info);
+    });
+  });
+}
+
+/** Stop all running servers */
+function stopAll() {
+  for (const [, { server }] of _servers) {
+    try { server.close(); } catch {}
+  }
+  _servers.clear();
+}
+
+/** Number of active servers */
+function count() {
+  return _servers.size;
+}
+
+module.exports = { getServer, stopAll, count };

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "playwright-deblock",
+  "version": "1.0.0",
+  "description": "Automatic fix for Playwright file:// navigation blocks. One require(), works forever.",
+  "main": "index.js",
+  "types": "index.d.ts",
+  "exports": {
+    ".": "./index.js",
+    "./register": "./register.js",
+    "./helper": "./helper.js"
+  },
+  "keywords": [
+    "playwright",
+    "file-protocol",
+    "deblock",
+    "localhost",
+    "data-url",
+    "navigation",
+    "fix",
+    "patch",
+    "ci",
+    "sandbox"
+  ],
+  "author": "",
+  "license": "MIT",
+  "peerDependencies": {
+    "playwright": "^1.58.2",
+    "playwright-core": ">=1.20.0"
+  },
+  "peerDependenciesMeta": {
+    "playwright": {
+      "optional": true
+    },
+    "playwright-core": {
+      "optional": true
+    }
+  },
+  "files": [
+    "index.js",
+    "index.d.ts",
+    "register.js",
+    "helper.js",
+    "lib/",
+    "LICENSE",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "node test/run.js"
+  }
+}

package/register.js

@@ -0,0 +1,9 @@
+/**
+ * Side-effect-only import. Just require this file to activate the patch.
+ *
+ *   require("playwright-deblock/register");
+ *
+ * Useful for --require in Playwright config:
+ *   npx playwright test --require playwright-deblock/register
+ */
+require("./index");