webcanvas-wasm 0.1.0

package/README.md

@@ -0,0 +1,305 @@
+# webcanvas-wasm
+
+<img width="1512" height="843" alt="Screenshot 2026-09-26 at 23 04 42" src="https://github.com/user-attachments/assets/33b0ad01-56a2-48eb-a51f-7f6fab35712a" />
+
+
+
+Minimal standalone Gecko WebView running in WebAssembly.
+
+The engine runs unmodified in a `<canvas>` and exposes a typed session, a page object, optional React bindings, and a Vite plugin. Everything is plain ES modules and shipped as source — there is no build step between the files in this repository and the files a consumer imports.
+
+- one persistent `<canvas>` used by Gecko
+- Gecko WASM boot with `SharedArrayBuffer`
+- same-origin Wisp networking at `/wisp/`
+- COOP/COEP headers required for cross-origin isolation
+- no database, auth, worker, or application-specific code
+
+## Install
+
+The engine artifacts are large, so they are fetched with the package rather than bundled into your build output.
+
+```bash
+npm install webcanvas-wasm
+```
+
+Node.js 20 or newer. The Vite plugin additionally needs the Node version Vite itself supports (`^20.19.0 || >=22.12.0`).
+
+## Run
+
+Requires Node.js 20+ and a modern Chromium-based host browser. `npm start` serves the `demo/` directory through `createWebviewServer()`, so the Wisp endpoint and the isolation headers are already wired.
+
+```bash
+npm install
+npm start
+```
+
+Open:
+
+```text
+http://127.0.0.1:8080
+```
+
+That address is for the *host page*. A remote deployment should use HTTPS so the browser can provide the secure, cross-origin-isolated environment needed by `SharedArrayBuffer`. Note that pages you navigate the WebView to are a separate matter: loopback is not reachable from inside it, see [Networking](#networking).
+
+To listen on another address or port:
+
+```bash
+HOST=0.0.0.0 PORT=8080 npm start
+```
+
+## How it works
+
+```text
+Host browser
+  └─ index.html
+      └─ persistent canvas
+          └─ Gecko JS/WASM
+              └─ same-origin WebSocket /wisp/
+                  └─ target website network
+```
+
+The boot path stops at `Gecko.init()`. It does **not** perform a synthetic `about:blank` navigation as a readiness check. Navigation is dispatched after the engine is ready and is intentionally not awaited by the UI, because a Gecko navigation can already be running even while its command promise remains pending.
+
+## Networking
+
+Gecko does not use the host page's `fetch`. It tunnels all of its HTTP through a [Wisp](https://github.com/MercuryWorkshop/Wisp) server reached at `/wisp/` on the **host page's own origin**, so the engine inherits the host's isolation and cookies rather than being cross-origin by accident.
+
+This is a hard requirement, not a default: without a working `/wisp/` endpoint the engine still boots, but no page will ever load. `createWebviewServer()` sets one up for you. The Vite plugin does **not** — it only serves the two engine files and sets headers, so a Vite app has to provide the endpoint itself (for example with `configureServer` middleware that routes `/wisp/` upgrades to `wisp-js/server`).
+
+Two consequences are worth knowing up front:
+
+- **Loopback is not reachable from inside the WebView.** Wisp refuses to open a stream to a loopback address, as an SSRF guard. `http://127.0.0.1:…`, `http://[::1]:…` and `http://localhost:…` are all refused, while public HTTPS pages load normally. Serving your app from `127.0.0.1` is fine; browsing to it is not.
+- **A refused navigation reports a misleading error.** If the navigation did not take, the engine cannot evaluate afterwards and the next `eval()` fails with `EvalError: call to eval() blocked by CSP` from `@embed-chrome`. That message means "there is no loaded document", not "a content security policy is misconfigured". The engine recovers on the next successful navigation.
+
+## Typed API
+
+`createGeckoRuntime()` returns a `GeckoSession` that closes the failure modes the raw engine leaves open. Types live in `types/`, and type checking is type-only — nothing is emitted, so the app still loads as plain ES modules.
+
+```js
+import { createGeckoRuntime, isGeckoEvalError } from 'webcanvas-wasm';
+
+const session = createGeckoRuntime({ canvas, onLog, onError });
+
+await session.init();                 // resolves once the engine is READY
+await session.open('example.com');    // returns once the new document is scriptable
+
+const title = await session.eval('document.title');
+console.log(title);                   // "Example Domain"
+```
+
+| Call | Returns |
+| --- | --- |
+| `init()` | the live engine instance |
+| `navigate(value)` | normalised URL, dispatch not awaited |
+| `open(value, ms?)` | `Promise<string>`, resolved after the new document has loaded |
+| `reload()` | URL, or `null` if nothing has been navigated |
+| `resize(w?, h?)` | `Promise<void>`, defaults to the host viewport |
+| `state` | `'idle' \| 'booting' \| 'ready' \| 'loading' \| 'destroyed'` |
+| `currentUrl` | `string \| null` |
+| `raw` | underlying engine, or `null` |
+| `eval(code, opts?)` / `evaluate(code, opts?)` | `Promise<T>` |
+| `evalJson(code, guard)` | `Promise<T>`, throws `shape` on a mismatch |
+| `waitFor(predicate, opts?)` | `Promise<boolean>` |
+| `query` / `queryAll` | `Promise<ElementSnapshot \| null>` / `Promise<ElementSnapshot[]>` |
+| `text` / `attr` / `click` | `Promise<string>` / `Promise<string \| null>` / `Promise<boolean>` |
+| `attempt(fn)` | `Promise<EvalResult<T>>` for callers who prefer a union |
+| `destroy()` | stops loops, detaches input |
+
+### Errors are thrown, not returned
+
+The engine's `evalChrome()` returns `''` when a snippet throws, when the snippet legitimately returns nothing, and when no page has been loaded yet. `eval()` wraps the snippet in an envelope so those three cases stay distinguishable, and reports the ones that are failures by throwing `GeckoEvalError`:
+
+```js
+await session.eval('40+2');
+// 42
+
+await session.eval('nope.missing.prop');
+// throws GeckoEvalError { code: 'throw' }
+//   "ReferenceError: nope is not defined\n@embed-chrome line 1 ..."
+```
+
+`code` is a closed union, so a caller can branch on the cause instead of matching message text:
+
+| `code` | Meaning |
+| --- | --- |
+| `'not-ready'` | the engine is not up yet |
+| `'no-page'` | no document has been navigated yet |
+| `'no-result'` | the snippet produced no reply at all |
+| `'throw'` | the snippet itself threw |
+| `'shape'` | `evalJson` guard rejected the value |
+| `'timeout'` | the snippet or a poll ran out of time |
+
+Because it is a real class exported from the entry point, `instanceof` narrows normally:
+
+```js
+import { GeckoEvalError, isGeckoEvalError } from 'webcanvas-wasm';
+
+try {
+  await session.eval('throw new Error("boom")');
+} catch (error) {
+  if (isGeckoEvalError(error) && error.code === 'throw') report(error.message);
+}
+```
+
+### Promises are awaited automatically
+
+The command bridge stringifies its completion value synchronously, so a bare `fetch(...).then(...)` would come back as the string `"[object Promise]"`. `eval()` resolves that first, so the common case needs no ceremony:
+
+```js
+const html = await session.eval('fetch(location.href).then(r => r.text())');
+```
+
+`evalAsync(code, ms?)` is kept as a deprecated alias for call sites that still name it explicitly.
+
+### Scope limits
+
+`eval()` runs in the **content window** of the loaded page, not in chrome. `Services`, `Cc`, `Ci` and `ChromeUtils` are all `undefined` there, so there is no privileged API surface. Full DOM read/write, `location`, first-party `document.cookie`, `localStorage`, `fetch`, XHR, WebSocket and `crypto.subtle` are available. There is no screenshot API and no cookie store, so `query()` returns a plain-data `ElementSnapshot` rather than a live element.
+
+## Page object
+
+`createGeckoPage()` puts the common document operations behind readable names. Every method is one round-trip, so it reads like the script it replaces.
+
+```js
+import { createGeckoPage, createGeckoRuntime } from 'webcanvas-wasm';
+
+const session = createGeckoRuntime({ canvas });
+await session.init();
+const page = createGeckoPage(session);
+
+await page.open('https://example.com/login');
+await page.fill('#email', 'someone@example.com');   // through the native value setter
+await page.click('button[type=submit]');
+await page.waitForSelector('h1');
+```
+
+`fill()` and `type()` write through the prototype `value` accessor and dispatch `input`/`change`, so a framework that tracks the last value it set still notices the edit. `type()` sends real key events one character at a time for sites that only respond to keys. A selector that matches nothing throws rather than reporting a silent success.
+
+## React
+
+Optional, and not part of the core bundle. It needs React 18+ as a peer.
+
+```js
+import { GeckoProvider, useGeckoPage } from 'webcanvas-wasm/react';
+
+<GeckoProvider canvas={canvasRef}>
+  <App />
+</GeckoProvider>;
+```
+
+`useGecko()` returns the session, `useGeckoPage()` a page object over it, `useGeckoEval()` re-runs a snippet when its dependencies change, and `useGeckoState()` / `useGeckoValue()` subscribe to the session state.
+
+## Vite
+
+`webcanvas-wasm/vite` serves the engine during `vite dev` and copies it on `vite build`, so there is no separate asset step to remember.
+
+```js
+// vite.config.js
+import { defineConfig } from 'vite';
+import { geckoWebView } from 'webcanvas-wasm/vite';
+
+export default defineConfig({
+  plugins: [geckoWebView({ engineDir: 'node_modules/webcanvas-wasm/engine' })]
+});
+```
+
+The plugin serves `gecko.js` and `gecko.wasm.zst`, and sets the `COOP`, `COEP` and `CORP` headers the engine needs. It fails loudly when the engine assets are missing. Pass `copyOnBuild: false` to keep the files out of the output.
+
+It does not provide Wisp, so you still need a `/wisp/` endpoint on the dev server or the engine will boot without ever loading a page — see [Networking](#networking).
+
+## Standalone server
+
+`webcanvas-wasm/server` is a Node-only entry point — it imports `node:http`, so it is deliberately absent from the browser entry point.
+
+```js
+import { createWebviewServer } from 'webcanvas-wasm/server';
+
+const app = createWebviewServer({ publicDir: 'demo' });
+await app.listen(8080, '127.0.0.1');
+```
+
+It serves static files, sets the isolation headers, and routes `/wisp/` WebSocket upgrades to the Wisp server that gives the engine its networking.
+
+## Entry points
+
+| Specifier | Contents |
+| --- | --- |
+| `webcanvas-wasm` | `createGeckoRuntime`, `createGeckoPage`, `GeckoEvalError`, `isGeckoEvalError`, `normalizeHttpUrl` |
+| `webcanvas-wasm/react` | `GeckoProvider`, `useGecko`, `useGeckoPage`, `useGeckoEval`, `useGeckoState`, `useGeckoValue`, `GeckoContext` |
+| `webcanvas-wasm/vite` | `geckoWebView`, `setIsolationHeaders` |
+| `webcanvas-wasm/server` | `createWebviewServer` (Node only) |
+| `webcanvas-wasm/engine/*` | the raw engine artifacts |
+
+
+## Files
+
+```text
+engine/gecko.js          Gecko JS runtime
+engine/gecko.wasm.zst    compressed Gecko WASM
+src/gecko/index.js       browser entry point
+src/gecko/runtime.js     typed lifecycle, navigation and evaluation
+src/gecko/page.js        page object over a session
+src/gecko/react.js       optional React bindings
+src/gecko/vite.js        Vite plugin and isolation headers
+src/server.js            static server + COOP/COEP + Wisp (Node only)
+types/                   public type declarations, checked but never emitted
+demo/                    minimal WebView UI
+test/                    unit, integration and consumer typecheck tests
+tsconfig.json            type-only checking, no emit
+```
+
+## Engine artifacts
+
+The engine artifacts in this repository were copied from the existing working Gecko WASM build used for this experiment.
+
+The build is small enough to ship as it is, so it is committed here and no recompilation is needed to run this repository:
+
+```text
+engine/gecko.js          3.9 MiB     Gecko JS runtime
+engine/gecko.wasm.zst    32.6 MiB    compressed Gecko WASM, 132 MiB raw
+                         36.5 MiB    total, downloadable from this repository
+```
+
+SHA-256:
+
+```text
+1af4b1521986aba8fdc4b8b02c8450f4e1f2d2bb283f78bd973c3eb7ece5a813  engine/gecko.js
+2565cf3e95c3b53d7aae41fbfaf36dfffbb99c6fefa1171051b2c05ba6f18dee  engine/gecko.wasm.zst
+```
+
+This repository does not make a new licensing claim over third-party engine artifacts. Preserve and comply with the licenses applicable to the Gecko build and third-party dependencies you use. `@mercuryworkshop/wisp-js` declares AGPL-3.0 in its package metadata.
+
+## Test
+
+```bash
+npm test
+npm run typecheck
+```
+
+The tests verify:
+
+- URL normalization only accepts HTTP(S)
+- Gecko readiness ends at `init()` with no hidden navigation
+- navigation dispatch does not block on a hanging `load()` promise
+- `open()` returns the *new* document, not the one it was leaving behind
+- COOP/COEP and engine resource headers are present
+- only `/wisp/` WebSocket upgrades are routed to Wisp
+- the Vite plugin serves and copies exactly the two engine files
+- `eval()` reports a typed error before any page is loaded, instead of `''`
+- `eval()` unwraps the envelope and preserves strings, numbers, objects and booleans
+- `eval()` awaits a promise-returning snippet instead of stringifying it
+- `eval()` reports a thrown snippet as a `GeckoEvalError` with the real message
+- `eval()` degrades circular values to text rather than reporting a crash
+- `evalJson()` rejects values that do not match the expected shape
+- `waitFor()` polls until the predicate holds
+- `fill()` and `type()` really run, use the native value setter, and fail loudly
+- `query()` returns a snapshot or `null`, and `queryAll()` never returns `null`
+- session `state` transitions across init, navigate, settle and destroy
+- the entry points export exactly what they claim, and a consumer without
+  `allowJs` can still narrow `instanceof` against `GeckoEvalError`
+
+The session and page tests run the real bridge envelope and the real page
+snippets inside a `node:vm` context against a fake engine that reproduces the
+engine's failure modes, so the evaluation logic is covered without booting WASM.
+The engine surface itself was verified separately against a live build in Chrome:
+boot, navigation, `eval`, promise auto-await, `evalJson`, `fill`, `type`,
+`waitForSelector`, `attr`, and the `GeckoEvalError` codes.