webcanvas-wasm 0.1.0

package/engine/gecko.wasm.zst

@@ -0,0 +1,4 @@
+[diffend] Oversized file quarantined before diffing.
+name: package/engine/gecko.wasm.zst
+size: 34136993 bytes
+sha256: 2565cf3e95c3b53d7aae41fbfaf36dfffbb99c6fefa1171051b2c05ba6f18dee

package/package.json

@@ -0,0 +1,85 @@
+{
+  "name": "webcanvas-wasm",
+  "version": "0.1.0",
+  "description": "A Gecko WebView in WebAssembly, with a small framework-agnostic API and optional React bindings.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ibidathoillah/webcanvas-wasm.git"
+  },
+  "bugs": {
+    "url": "https://github.com/ibidathoillah/webcanvas-wasm/issues"
+  },
+  "homepage": "https://github.com/ibidathoillah/webcanvas-wasm#readme",
+  "type": "module",
+  "main": "./src/gecko/index.js",
+  "types": "./types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./types/index.d.ts",
+      "import": "./src/gecko/index.js"
+    },
+    "./react": {
+      "types": "./types/react.d.ts",
+      "import": "./src/gecko/react.js"
+    },
+    "./vite": {
+      "types": "./types/vite.d.ts",
+      "import": "./src/gecko/vite.js"
+    },
+    "./server": {
+      "types": "./types/server.d.ts",
+      "import": "./src/server.js"
+    },
+    "./engine/*": "./engine/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "src/gecko",
+    "src/server.js",
+    "types",
+    "engine",
+    "README.md"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "start": "node src/server.js",
+    "test": "node --test",
+    "typecheck": "tsc --noEmit",
+    "prepack": "npm run typecheck && npm test"
+  },
+  "dependencies": {
+    "@mercuryworkshop/wisp-js": "^0.4.1"
+  },
+  "peerDependencies": {
+    "react": ">=18"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^26.6.3",
+    "@types/react": "^19.3.0",
+    "jsdom": "^29.1.1",
+    "react": "^19.3.0",
+    "react-dom": "^19.3.0",
+    "typescript": "^7.0.2",
+    "vite": "^7.3.6"
+  },
+  "keywords": [
+    "webview",
+    "webcanvas",
+    "gecko",
+    "firefox",
+    "wasm",
+    "webassembly",
+    "browser-in-a-box",
+    "headless",
+    "react"
+  ],
+  "engines": {
+    "node": ">=20"
+  }
+}

package/src/gecko/index.js

@@ -0,0 +1,10 @@
+/**
+ * Package entry point.
+ *
+ * The library is already plain ESM, so this is a re-export barrel rather than
+ * a build artifact. There is no bundler step between the source in this
+ * repository and the files published to npm.
+ */
+
+export { createGeckoRuntime, normalizeHttpUrl, GeckoEvalError, isGeckoEvalError } from './runtime.js';
+export { createGeckoPage } from './page.js';

package/src/gecko/page.js

@@ -0,0 +1,244 @@
+// @ts-check
+
+/**
+ * Page object over a {@link GeckoSession}.
+ *
+ * The session exposes the engine faithfully; the page object exposes the
+ * things a caller actually wants to do to a document. Every method is one
+ * round-trip, so chaining reads the same as the script it replaces.
+ *
+ * @typedef {import('../../types/session.js').GeckoSession} GeckoSession
+ * @typedef {import('../../types/page.js').GeckoPage} GeckoPage
+ * @typedef {import('../../types/session.js').ElementSnapshot} ElementSnapshot
+ * @typedef {import('../../types/session.js').EvaluateOptions} EvaluateOptions
+ * @typedef {import('../../types/session.js').WaitForOptions} WaitForOptions
+ */
+
+/**
+ * Writes a value the way a real user would, rather than by assignment.
+ *
+ * Assigning `el.value` directly is invisible to React and to any other
+ * framework that tracks the last value it set: the DOM node changes but the
+ * component state does not, so the next render reverts it. Calling the native
+ * `value` setter and dispatching `input` makes the change observable, which is
+ * what real typing does.
+ *
+ * The snippets take `(sel, value)` as declared parameters rather than reading
+ * `arguments`: they run as arrows, where `arguments` is a ReferenceError.
+ */
+const FILL = `(sel,value)=>{const el=document.querySelector(sel);if(!el)throw new Error('no match for '+sel);`
+  + `const text=value==null?'':String(value);`
+  + `const proto=el.tagName==='TEXTAREA'?HTMLTextAreaElement.prototype:`
+  + `el.tagName==='SELECT'?HTMLSelectElement.prototype:HTMLInputElement.prototype;`
+  + `const desc=Object.getOwnPropertyDescriptor(proto,'value');`
+  + `if(desc&&desc.set)desc.set.call(el,text);else el.value=text;`
+  + `el.dispatchEvent(new Event('input',{bubbles:true}));`
+  + `el.dispatchEvent(new Event('change',{bubbles:true}));`
+  + `el.focus();return true}`;
+
+/** Types a value one character at a time, for sites that only respond to keys. */
+const TYPE = `(sel,value)=>{const el=document.querySelector(sel);if(!el)throw new Error('no match for '+sel);`
+  + `el.focus();const text=value==null?'':String(value);`
+  + `for(const ch of text){`
+  + `el.dispatchEvent(new KeyboardEvent('keydown',{key:ch,bubbles:true}));`
+  + `el.dispatchEvent(new KeyboardEvent('keypress',{key:ch,bubbles:true}));`
+  + `el.value+=ch;`
+  + `el.dispatchEvent(new InputEvent('input',{bubbles:true,data:ch}));`
+  + `el.dispatchEvent(new KeyboardEvent('keyup',{key:ch,bubbles:true}));}`
+  + `el.dispatchEvent(new Event('change',{bubbles:true}));return true}`;
+
+/**
+ * @param {GeckoSession} session
+ * @returns {GeckoPage}
+ */
+export function createGeckoPage(session) {
+  /**
+   * @template T
+   * @param {string} code
+   * @returns {Promise<T>}
+   */
+  function pageEval(code) {
+    return /** @type {Promise<T>} */ (session.eval(code));
+  }
+
+  /**
+   * @param {string} selector
+   * @returns {Promise<boolean>}
+   */
+  function exists(selector) {
+    return pageEval(`document.querySelector(${JSON.stringify(selector)}) !== null`);
+  }
+
+  /**
+   * @param {string} selector
+   * @returns {Promise<number>}
+   */
+  function count(selector) {
+    return pageEval(`document.querySelectorAll(${JSON.stringify(selector)}).length`);
+  }
+
+  /**
+   * @param {string} selector
+   * @param {string} value
+   * @returns {Promise<boolean>}
+   */
+  function fill(selector, value) {
+    return pageEval(`(${FILL})(${JSON.stringify(selector)},${JSON.stringify(value)})`);
+  }
+
+  /**
+   * @param {string} selector
+   * @param {string} value
+   * @returns {Promise<boolean>}
+   */
+  function type(selector, value) {
+    return pageEval(`(${TYPE})(${JSON.stringify(selector)},${JSON.stringify(value)})`);
+  }
+
+  /**
+   * Scrolls an element into view before clicking, then waits briefly for the
+   * DOM to settle so a follow-up read does not race the click handler.
+   * @param {string} selector
+   * @returns {Promise<boolean>}
+   */
+  async function click(selector) {
+    const ok = await pageEval(
+      `(()=>{const el=document.querySelector(${JSON.stringify(selector)});if(!el)return false;`
+        + `el.scrollIntoView({block:'center'});el.click();return true})()`
+    );
+    if (ok) await settle();
+    return ok;
+  }
+
+  /**
+   * Waits a short beat for the DOM to stop changing.
+   *
+   * There is no reliable "navigation finished" signal for an in-page click, so
+   * this is a deliberate small delay rather than a fake guarantee.
+   */
+  async function settle(ms = 150) {
+    await new Promise(resolve => setTimeout(resolve, ms));
+  }
+
+  /**
+   * @param {string} url
+   * @param {number} [timeoutMs]
+   * @returns {Promise<string>}
+   */
+  function open(url, timeoutMs) {
+    return timeoutMs === undefined ? session.open(url) : session.open(url, timeoutMs);
+  }
+
+  /** @returns {Promise<string>} */
+  function url() {
+    return pageEval('location.href');
+  }
+
+  /** @returns {Promise<string>} */
+  function origin() {
+    return pageEval('location.origin');
+  }
+
+  /** @returns {Promise<string>} */
+  function title() {
+    return pageEval('document.title');
+  }
+
+  /**
+   * @template T
+   * @param {string} code
+   * @param {EvaluateOptions} [evaluateOptions]
+   * @returns {Promise<T>}
+   */
+  function run(code, evaluateOptions) {
+    return evaluateOptions === undefined
+      ? pageEval(code)
+      : /** @type {Promise<T>} */ (session.eval(code, evaluateOptions));
+  }
+
+  /**
+   * @param {string} predicate
+   * @param {WaitForOptions} [waitOptions]
+   * @returns {Promise<boolean>}
+   */
+  function waitFor(predicate, waitOptions) {
+    return waitOptions === undefined ? session.waitFor(predicate) : session.waitFor(predicate, waitOptions);
+  }
+
+  /**
+   * @template [T=ElementSnapshot]
+   * @param {string} selector
+   * @param {WaitForOptions} [waitOptions]
+   * @returns {Promise<T | null>}
+   */
+  async function waitForSelector(selector, waitOptions) {
+    const found = await session.waitFor(
+      `document.querySelector(${JSON.stringify(selector)}) !== null`,
+      waitOptions
+    );
+    return found ? query(selector) : null;
+  }
+
+  /**
+   * @template [T=ElementSnapshot]
+   * @param {string} selector
+   * @returns {Promise<T | null>}
+   */
+  function query(selector) {
+    return session.query(selector);
+  }
+
+  /**
+   * @template [T=ElementSnapshot]
+   * @param {string} selector
+   * @returns {Promise<T[]>}
+   */
+  function queryAll(selector) {
+    return session.queryAll(selector);
+  }
+
+  /**
+   * @param {string} selector
+   * @returns {Promise<string>}
+   */
+  function text(selector) {
+    return session.text(selector);
+  }
+
+  /**
+   * @param {string} name
+   * @param {string} selector
+   * @returns {Promise<string | null>}
+   */
+  function attr(name, selector) {
+    return session.attr(name, selector);
+  }
+
+  /** @returns {string | null} */
+  function reload() {
+    return session.reload();
+  }
+
+  return {
+    session,
+    open,
+    url,
+    origin,
+    title,
+    eval: run,
+    waitFor,
+    waitForSelector,
+    settle,
+    exists,
+    count,
+    query,
+    queryAll,
+    text,
+    attr,
+    fill,
+    type,
+    click,
+    reload
+  };
+
+}

package/src/gecko/react.js

@@ -0,0 +1,293 @@
+// @ts-check
+
+/**
+ * React bindings for the Gecko session.
+ *
+ * This is a thin adapter: the engine is owned outside React and merely observed
+ * from inside. No `useEffect` here decides *what* to evaluate — it only wires a
+ * subscription to a session that already knows how to evaluate.
+ *
+ * There is deliberately no JSX, so the package stays consumable from a plain
+ * Vite or Node project without a build step.
+ */
+
+import {
+  createContext,
+  createElement,
+  useCallback,
+  useContext,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+  useSyncExternalStore
+} from 'react';
+
+import { createGeckoRuntime } from './runtime.js';
+import { createGeckoPage } from './page.js';
+
+/**
+ * @typedef {import('../../types/session.js').GeckoSession} GeckoSession
+ * @typedef {import('../../types/session.js').SessionState} SessionState
+ * @typedef {import('../../types/session.js').SessionOptions} SessionOptions
+ * @typedef {import('../../types/page.js').GeckoPage} GeckoPage
+ * @typedef {import('../../types/react.js').GeckoContextValue} GeckoContextValue
+ * @typedef {import('../../types/react.js').GeckoProviderProps} GeckoProviderProps
+ * @typedef {import('../../types/react.js').GeckoRunResult<unknown>} GeckoRunResult
+ * @typedef {import('react').ReactNode} ReactNode
+ * @typedef {{ session: GeckoSession | null, page: GeckoPage | null, cancel: (() => void) | null }} Holder
+ */
+
+/** No session exists outside a provider; make the mistake obvious if ignored. */
+const MISSING = 'useGecko() was called outside a <GeckoProvider>. Wrap the tree in one.';
+
+const GeckoContext = /** @type {import('react').Context<GeckoContextValue | null>} */ (
+  /** @type {unknown} */ (createContext(/** @type {GeckoContextValue | null} */ (null)))
+);
+
+/**
+ * How long a session is kept after its last subscriber goes away.
+ *
+ * The deferral is an optimisation, not a correctness requirement: it lets a
+ * provider that remounts in the same task (fast refresh, a key change) keep the
+ * engine it already paid to boot. Note that React StrictMode's double-invoke
+ * does *not* need this — its cleanup runs before `init()` has produced an
+ * engine, so a synchronous teardown there would be a no-op anyway.
+ */
+const DESTROY_GRACE_MS = 0;
+
+/**
+ * Holds the session between the strict-mode unmount and the remount that
+ * immediately follows it.
+ *
+ * @param {GeckoSession} session
+ * @param {number} [ms]
+ * @returns {() => void} a cancel function
+ */
+function scheduleDestroy(session, ms = DESTROY_GRACE_MS) {
+  const timer = setTimeout(() => session.destroy(), ms);
+  return () => clearTimeout(timer);
+}
+
+/**
+ * Owns one session for the life of the provider.
+ *
+ * The requirement that actually bites is that the engine must not be created
+ * during render: React invokes a render twice in development, so building an
+ * engine there would boot two of them and leak the discarded one. Creation is
+ * therefore deferred to an effect, and the effect has no dependencies so it
+ * runs once for the lifetime of the holder.
+ *
+ * @param {Omit<SessionOptions, 'canvas'> & { canvasRef?: import('react').RefObject<HTMLCanvasElement | null> }} options
+ * @returns {GeckoContextValue}
+ */
+function useGeckoSession(options) {
+  const { canvasRef, ...sessionOptions } = options;
+  const optionsRef = useRef(sessionOptions);
+  optionsRef.current = sessionOptions;
+
+  // A holder rather than a bare session, because the session is created inside
+  // an effect (it needs the canvas) but must outlive a strict-mode cleanup.
+  const [holder] = useState(/** @returns {Holder} */ () => ({
+    session: null,
+    page: null,
+    cancel: null
+  }));
+
+  const [state, setState] = useState(/** @type {SessionState} */ ('idle'));
+  const [error, setError] = useState(/** @type {unknown} */ (null));
+  // Bumped when the engine handle changes. `subscribe` reports `'idle'` first,
+  // which is already the current state, so React would bail out of that render
+  // and the new handle would never reach consumers without this.
+  const [generation, setGeneration] = useState(0);
+
+  useEffect(() => {
+    // A teardown from the previous strict-mode pass is still pending.
+    if (holder.cancel) {
+      holder.cancel();
+      holder.cancel = null;
+    }
+
+    // A destroyed session cannot be revived, so replace it. The engine is
+    // reused on an ordinary remount; the second branch is defensive, since a
+    // fresh root always gets a fresh holder anyway.
+    if (!holder.session || holder.session.state === 'destroyed') {
+      const canvas = canvasRef ? canvasRef.current : null;
+      if (!canvas) return undefined;
+      const session = createGeckoRuntime({ ...optionsRef.current, canvas });
+      holder.session = session;
+      holder.page = createGeckoPage(session);
+      setGeneration(value => value + 1);
+    }
+
+    const session = holder.session;
+    if (!session) return undefined;
+
+    // `subscribe` fires immediately, so the first snapshot is free and no
+    // render can observe a state that is already out of date.
+    const unsubscribe = session.subscribe(setState);
+    let cancelled = false;
+    session.init().then(
+      () => {
+        if (!cancelled) setError(null);
+      },
+      (/** @type {unknown} */ reason) => {
+        if (!cancelled) setError(reason);
+      }
+    );
+
+    return () => {
+      cancelled = true;
+      unsubscribe();
+      // Deferred so a same-task remount can reclaim the engine; a pending
+      // teardown from an earlier cleanup is cancelled at the top instead.
+      if (!holder.cancel) holder.cancel = scheduleDestroy(session);
+    };
+    // The engine is built once on purpose: swapping options later would mean
+    // discarding a live page, which is not a decision a render should make.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+
+  return useMemo(
+    () => ({
+      session: holder.session,
+      page: holder.page,
+      state,
+      error,
+      ready: state === 'ready',
+      // Reading `generation` is what makes the engine handle part of the value.
+      generation
+    }),
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [state, error, generation]
+  );
+}
+
+/**
+ * Provides one Gecko engine to the subtree below it.
+ *
+ * The engine is created on mount and torn down when the last consumer goes
+ * away. Children read it with {@link useGecko}, {@link useGeckoPage},
+ * {@link useGeckoState} or {@link useGeckoValue}.
+ *
+ * @param {GeckoProviderProps} props
+ * @returns {import('react').ReactElement}
+ */
+export function GeckoProvider(props) {
+  const { children, canvasRef, ...options } = props;
+  const ownCanvas = useRef(/** @type {HTMLCanvasElement | null} */ (null));
+
+  // A caller may supply their own canvas; otherwise render one and use it.
+  const resolvedRef = canvasRef || ownCanvas;
+  const value = useGeckoSession({ canvasRef: resolvedRef, ...options });
+
+  const canvas = canvasRef
+    ? null
+    : createElement('canvas', {
+        ref: (/** @type {HTMLCanvasElement | null} */ node) => {
+          ownCanvas.current = node;
+        },
+        style: { display: 'block', width: '100%', height: '100%' }
+      });
+
+  return createElement(GeckoContext.Provider, { value }, canvas, children);
+}
+
+/**
+ * The full context: the session, the page object, and the current state.
+ *
+ * @returns {GeckoContextValue}
+ */
+export function useGecko() {
+  const value = useContext(GeckoContext);
+  if (!value) throw new Error(MISSING);
+  return value;
+}
+
+/**
+ * Just the page object, which is what most components want.
+ *
+ * @returns {GeckoPage | null}
+ */
+export function useGeckoPage() {
+  return useGecko().page;
+}
+
+/**
+ * Just the lifecycle state, for components that only show a spinner.
+ *
+ * @returns {SessionState}
+ */
+export function useGeckoState() {
+  return useGecko().state;
+}
+
+/**
+ * Run an async read against the page and keep the result in state.
+ *
+ * A result is discarded if the inputs change or the component unmounts before
+ * it lands, so a slow evaluation cannot overwrite a newer one. State is *not*
+ * reset when the page navigates, because the previous value is still the best
+ * answer available until the new one arrives.
+ *
+ * @template T
+ * @param {(session: GeckoSession) => Promise<T> | T} run
+ * @param {unknown[]} [deps]
+ * @returns {import('../../types/react.js').GeckoRunResult<T>}
+ */
+export function useGeckoValue(run, deps = []) {
+  const { session, state, generation } = useGecko();
+  const [result, setResult] = useState(/** @type {import('../../types/react.js').GeckoRunResult<T>} */ ({
+    status: 'idle',
+    value: undefined
+  }));
+  // Held in a ref so a caller passing an inline closure does not re-run on
+  // every render; `deps` is the declared dependency list.
+  const runRef = useRef(run);
+  runRef.current = run;
+
+  useEffect(() => {
+    if (!session || state !== 'ready') return undefined;
+    let cancelled = false;
+    setResult(previous => ({ ...previous, status: 'pending' }));
+
+    Promise.resolve()
+      .then(() => runRef.current(session))
+      .then(
+        value => {
+          if (!cancelled) setResult({ status: 'ok', value });
+        },
+        error => {
+          if (!cancelled) setResult(previous => ({ status: 'error', value: previous.value, error }));
+        }
+      );
+
+    return () => {
+      cancelled = true;
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [session, state, generation, ...deps]);
+
+  return result;
+}
+
+/**
+ * Convenience wrapper around {@link useGeckoValue} for a single `eval`.
+ *
+ * @template T
+ * @param {string} code
+ * @param {{ deps?: unknown[]; evaluateOptions?: { timeoutMs?: number } }} [options]
+ * @returns {import('../../types/react.js').GeckoRunResult<T>}
+ */
+export function useGeckoEval(code, options = {}) {
+  const { deps = [], evaluateOptions } = options;
+  const run = useCallback(
+    (/** @type {GeckoSession} */ session) =>
+      /** @type {Promise<T>} */ (session.eval(/** @type {string} */ (code), evaluateOptions)),
+    [code, evaluateOptions]
+  );
+  return useGeckoValue(run, deps);
+}
+
+export { GeckoContext };
+export default GeckoProvider;