fluxwright 0.2.1 → 0.2.2

package/MISSING.md

@@ -1,15 +1,22 @@
-# Playwright methods not in Fluxwright (TypeScript)
+# Playwright features not in Fluxwright
 
-The TS binding covers the same small page API as the Rust crate. Missing on purpose:
+The Node binding covers the same page API as the Rust crate. Some Playwright features are planned, and some are out of scope.
 
-- Firefox / WebKit
-- Tracing, HAR, video
-- `page.route` beyond resource-type / URL blocking on the job
-- Storage state import/export
-- `page.emulateMedia`, geolocation, permissions helpers
-- Playwright Test runner, fixtures, expect
-- `locator.filter`, `nth`, `getByLabel`/`getByPlaceholder`/`getByTestId`, shadow-DOM piercing
+## Planned (see [ROADMAP.md](https://github.com/harshit-d3v/fluxwright/blob/main/ROADMAP.md))
+
+- Saved login state: `storageState` import and export
+- `page.route` to fulfill or modify requests (today: blocking by resource type or URL)
+- Emulation: user agent, locale, timezone, geolocation, permissions, `emulateMedia`
+- `locator.screenshot()`
+- `getByLabel`, `getByPlaceholder`, `getByTestId`, `nth`, `filter`
+- Downloads
+- `connectOverCDP`, to use browsers you already run
+- Python bindings
+
+## Out of scope
+
+- Firefox and WebKit
+- Playwright Test: the runner, fixtures and `expect`
+- Tracing, the trace viewer, codegen and video recording
 - Multiple pages per context
-- Download / upload helpers
-- WebSocket / worker APIs
-- `connectOverCDP` (planned as a later `BrowserSource`)
+- WebSocket and worker APIs

package/README.md

@@ -1,8 +1,10 @@
 # fluxwright
 
-In-process **Chromium fleet** for Node. Lease API (fresh context per `newPage`), not Playwright parity.
+Run hundreds of headless Chrome jobs on one machine, with a Playwright-style API. Each `newPage` is a fresh browser context on a pooled Chrome. The engine queues jobs when every slot is busy, restarts browsers before they bloat, and replaces browsers that crash.
 
-Requires a local Chrome/Chromium binary (`FLUXWRIGHT_CHROMIUM`, `CHROME`, `CHROMIUM`, or a standard install path).
+Docs: https://fluxwright.vercel.app
+
+Requires a local Chrome/Chromium binary (`FLUXWRIGHT_CHROMIUM`, `CHROME`, `CHROMIUM`, or a standard install path). For headless jobs, chrome-headless-shell is picked up from `PATH` or Puppeteer's/Playwright's cache and opens pages much faster: `npx @puppeteer/browsers install chrome-headless-shell@stable`.
 
 ## Install
 
@@ -24,11 +26,9 @@ import { chromium } from "fluxwright";
 const browser = await chromium.launch({ maxBrowsers: 4 });
 const page = await browser.newPage();
 await page.goto("https://example.com");
-console.log(await page.title());
-await page.click("css-selector");
-await page.fill("input", "value");
-const html = await page.content();
-const png = await page.screenshot(); // Buffer
+console.log(await page.getByRole("heading").textContent()); // "Example Domain"
+console.log(await page.evaluate(() => location.hostname));
+const png = await page.screenshot({ fullPage: true }); // Buffer
 await page.close();
 await browser.close();
 ```
@@ -46,13 +46,23 @@ await browser.close();
 | `page.click(selector)` / `page.fill(selector, value)` | Scrolls into view, waits until enabled, stable, and not covered. Selector: CSS, `text=Foo`, `text="Exact"`, `role=button[name="Save"]` |
 | `page.getByRole(role, { name?, exact? })` / `page.getByText(text, { exact? })` / `page.locator(selector)` | `Locator` with `click()`, `fill(v)`, `waitFor()`, `textContent()`. Implicit ARIA roles and accessible names; hidden elements never match a role |
 | `page.frameLocator(iframeSelector)` | Same locators inside an iframe, same- or cross-origin; nest with `.frameLocator()` |
-| `page.evaluate(expression)` | `Runtime.evaluate`, JSON. A thrown JS error rejects with its message and stack |
+| `page.evaluate(fn, arg?)` / `page.evaluate(expression)` | Runs a function with a JSON-serializable `arg`, or a string expression, in the page. Awaits promises and returns JSON. As in Playwright, the function is sent as source text, so it can't use variables from Node. A thrown JS error rejects with its message and stack |
 | `page.screenshot({ fullPage? })` | PNG `Buffer` |
 | `page.setViewportSize({ width, height })` | CSS-pixel viewport for this page |
 | `page.waitForSelector(selector)` | Waits until visible (Playwright's default state) |
 | `page.close()` / `browser.close()` | Dispose context / shut down |
 
-See `MISSING.md` for Playwright methods that will not be added.
+Close pages when a job is done. A page you forget is cleaned up when Node garbage-collects it, which may be much later.
+
+See `MISSING.md` for Playwright features that are planned or out of scope.
+
+## Develop
+
+```bash
+npm install
+npm run build   # needs Rust
+npm test        # smoke test against a real Chrome
+```
 
 ## License
 

package/addon.d.ts

@@ -2,4 +2,16 @@ export * from './index'
 import { Chromium } from './index'
 /** Playwright-style export: `chromium.launch(...)`. Same as `Chromium.launch`. */
 export const chromium: typeof Chromium
-export default { chromium }
+declare const fluxwright: { chromium: typeof Chromium }
+export default fluxwright
+
+declare module './index' {
+  interface Page {
+    /**
+     * Runs `pageFunction` in the page with `arg` and returns its result, awaiting promises.
+     * As in Playwright, the function is sent as source text: it can use `arg` (JSON-serializable)
+     * but not variables from Node.
+     */
+    evaluate<R, Arg = undefined>(pageFunction: (arg: Arg) => R, arg?: Arg): Promise<Awaited<R>>
+  }
+}

package/addon.js

@@ -1,7 +1,44 @@
 'use strict'
 
+const { Script } = require('node:vm')
+
+// Playwright-style `page.evaluate(fn, arg)`. As in Playwright, the function is sent to the page as
+// source text, so it can use `arg` but not variables from Node. Strings run as expressions.
+function toExpression(pageFunction, arg) {
+  if (typeof pageFunction !== 'function') return pageFunction
+  return `(${functionSource(pageFunction)})(${arg === undefined ? '' : JSON.stringify(arg)})`
+}
+
+// Object and class methods stringify as `name(x) { ... }`, which is not an expression on its own.
+// Like Playwright, turn them into function expressions (this also covers async and generator methods).
+function functionSource(fn) {
+  let source = String(fn)
+  if (!parses(source)) {
+    source = source.startsWith('async ') ? `async function ${source.slice(6)}` : `function ${source}`
+    if (!parses(source)) {
+      throw new TypeError(`evaluate: this function can't be sent to the page: ${String(fn).slice(0, 60)}`)
+    }
+  }
+  return source
+}
+
+// Compiles only, nothing runs. Unlike `new Function`, this also works under
+// `--disallow-code-generation-from-strings`.
+function parses(source) {
+  try {
+    new Script(`(${source})`)
+    return true
+  } catch {
+    return false
+  }
+}
+
 try {
   const native = require('./index.js')
+  const evaluate = native.Page.prototype.evaluate
+  native.Page.prototype.evaluate = async function (pageFunction, arg) {
+    return evaluate.call(this, toExpression(pageFunction, arg))
+  }
   module.exports = native
   module.exports.chromium = native.Chromium
   module.exports.default = module.exports

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "fluxwright",
-  "version": "0.2.1",
-  "description": "In-process Chromium fleet engine (napi-rs). Lease API, not Playwright parity.",
+  "version": "0.2.2",
+  "description": "Run hundreds of headless Chrome jobs on one machine: pooling, queueing, recycling and crash recovery, with a Playwright-style API.",
   "main": "addon.js",
   "types": "addon.d.ts",
   "repository": {
@@ -9,16 +9,20 @@
     "url": "git+https://github.com/harshit-d3v/fluxwright.git",
     "directory": "bindings/node"
   },
-  "homepage": "https://github.com/harshit-d3v/fluxwright#readme",
+  "homepage": "https://fluxwright.vercel.app",
   "bugs": {
     "url": "https://github.com/harshit-d3v/fluxwright/issues"
   },
   "keywords": [
     "chromium",
     "chrome",
-    "cdp",
+    "headless",
+    "playwright",
+    "puppeteer",
     "browser-pool",
-    "automation",
+    "browser-automation",
+    "scraping",
+    "cdp",
     "napi-rs"
   ],
   "author": "Fluxwright contributors",
@@ -37,6 +41,8 @@
   ],
   "scripts": {
     "build": "napi build --platform --release",
+    "test": "node test/smoke.mjs",
+    "test:types": "tsc -p test",
     "build:debug": "napi build --platform",
     "artifacts": "napi artifacts",
     "prepublishOnly": "napi prepublish -t npm --skip-gh-release"
@@ -54,12 +60,14 @@
     "access": "public"
   },
   "devDependencies": {
-    "@napi-rs/cli": "^2.18.4"
+    "@napi-rs/cli": "^2.18.4",
+    "@types/node": "^22.20.4",
+    "typescript": "^5.9.3"
   },
   "optionalDependencies": {
-    "fluxwright-darwin-arm64": "0.2.1",
-    "fluxwright-darwin-x64": "0.2.1",
-    "fluxwright-linux-x64-gnu": "0.2.1",
-    "fluxwright-win32-x64-msvc": "0.2.1"
+    "fluxwright-darwin-arm64": "0.2.2",
+    "fluxwright-darwin-x64": "0.2.2",
+    "fluxwright-linux-x64-gnu": "0.2.2",
+    "fluxwright-win32-x64-msvc": "0.2.2"
   }
 }