webcanvas-wasm 0.1.0

package/src/gecko/vite.js

@@ -0,0 +1,171 @@
+/**
+ * Vite integration.
+ *
+ * The engine is a real WebAssembly payload, so it cannot be fetched from a CDN
+ * and cannot be inlined. Two things must therefore be true before the engine
+ * will boot, and neither is something a bundler does for you:
+ *
+ * 1. The engine assets must be served. This plugin copies them into the build
+ *    output, and serves them directly in dev.
+ * 2. The document must be cross-origin isolated. Without
+ *    `Cross-Origin-Opener-Policy: same-origin` and
+ *    `Cross-Origin-Embedder-Policy: require-corp` there is no
+ *    `SharedArrayBuffer`, and the engine refuses to start.
+ *
+ * Both are handled here, so the common case is a two-line config.
+ */
+
+import { createReadStream } from 'node:fs';
+import { cp, mkdir, readdir, stat } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { pipeline } from 'node:stream/promises';
+
+/** Where the engine lives relative to this file inside the published package. */
+const DEFAULT_ENGINE_DIR = resolve(dirname(fileURLToPath(import.meta.url)), '..', '..', 'engine');
+
+/** Mount point the runtime defaults to. */
+const DEFAULT_MOUNT = '/engine';
+
+/** Only these are served; nothing else in the engine directory is exposed. */
+const ENGINE_FILES = new Set(['gecko.js', 'gecko.wasm.zst']);
+
+/**
+ * @typedef {import('../../types/vite.js').GeckoVitePluginOptions} GeckoVitePluginOptions
+ * @typedef {import('../../types/vite.js').GeckoVitePlugin} GeckoVitePlugin
+ * @typedef {import('../../types/vite.js').GeckoMiddleware} GeckoMiddleware
+ * @typedef {import('../../types/vite.js').GeckoDevServer} GeckoDevServer
+ */
+
+/**
+ * Serves the engine and sets the cross-origin isolation headers.
+ *
+ * Vite is deliberately not referenced by type here: it is an optional peer, and
+ * a `import('vite')` in a JSDoc annotation would make this file unresolvable
+ * for anyone who installed the package without Vite.
+ *
+ * @param {GeckoVitePluginOptions} [options]
+ * @returns {GeckoVitePlugin}
+ */
+export function geckoWebView(options = {}) {
+  const engineDir = resolve(options.engineDir || DEFAULT_ENGINE_DIR);
+  const mount = options.mount || DEFAULT_MOUNT;
+  const copyOnBuild = options.copyOnBuild !== false;
+  let verified = false;
+
+  return {
+    name: 'webcanvas-wasm',
+
+    async buildStart() {
+      if (verified) return;
+      await assertEnginePresent(engineDir);
+      verified = true;
+    },
+
+    /**
+     * The headers belong on every response, not just the document that boots the
+     * engine: a subresource served without them is what actually breaks
+     * isolation, usually as a worker that fails to start.
+     *
+     * @param {GeckoDevServer} server
+     */
+    async configureServer(server) {
+      // `buildStart` does not run for `vite dev`, so the check is repeated
+      // here. Without it a missing engine shows up as a 404 on the first fetch,
+      // long after the mistake was made.
+      await assertEnginePresent(engineDir);
+
+      /** @type {GeckoMiddleware} */
+      const isolation = (req, res, next) => {
+        void req;
+        setIsolationHeaders(res);
+        next();
+      };
+      server.middlewares.use(isolation);
+
+      /** @type {GeckoMiddleware} */
+      const engineFiles = (req, res, next) => {
+        // Strip the query string, then the leading slash, leaving a bare
+        // filename that can be checked against the allow-list.
+        const name = String(req.url).split('?')[0]?.replace(/^\/+/, '') ?? '';
+        // Only the two known assets are exposed; a miss falls through to the
+        // next handler so a genuine 404 stays a 404.
+        if (!ENGINE_FILES.has(name)) {
+          next();
+          return;
+        }
+        sendEngine(res, join(engineDir, name), name.endsWith('.zst')).catch(next);
+      };
+      server.middlewares.use(`${mount}/`, engineFiles);
+    },
+
+    /**
+     * @param {{ dir?: string }} outputOptions
+     */
+    async writeBundle(outputOptions) {
+      if (!copyOnBuild) return;
+      // `dir` is the resolved output directory; falling back to cwd keeps a
+      // misconfigured build from writing engine files into the source tree.
+      const outDir = resolve(String(outputOptions.dir || 'dist'));
+      const target = join(outDir, mount.replace(/^\/+/, ''));
+      await mkdir(target, { recursive: true });
+      for (const file of ENGINE_FILES) {
+        await cp(join(engineDir, file), join(target, file));
+      }
+    }
+  };
+}
+
+/**
+ * Fail early and clearly. A missing engine otherwise surfaces as a blank canvas
+ * and a console error several seconds after boot, which is hard to trace back.
+ *
+ * @param {string} engineDir
+ */
+async function assertEnginePresent(engineDir) {
+  let available;
+  try {
+    available = await readdir(engineDir);
+  } catch {
+    throw new Error(
+      `webcanvas-wasm: no engine assets in ${engineDir}. Pass \`engineDir\` to point at a ` +
+        'local engine build.'
+    );
+  }
+  const missing = [...ENGINE_FILES].filter(file => !available.includes(file));
+  if (missing.length) {
+    throw new Error(`webcanvas-wasm: engine is missing ${missing.join(', ')} in ${engineDir}`);
+  }
+}
+
+/**
+ * The headers the engine requires.
+ *
+ * @param {{ setHeader(name: string, value: string): void }} res
+ */
+export function setIsolationHeaders(res) {
+  res.setHeader('Cross-Origin-Opener-Policy', 'same-origin');
+  res.setHeader('Cross-Origin-Embedder-Policy', 'require-corp');
+  res.setHeader('Cross-Origin-Resource-Policy', 'same-origin');
+}
+
+/**
+ * Streams the file rather than reading it: the compressed wasm is tens of
+ * megabytes, and holding it in memory per request is how a dev server falls
+ * over when a page reloads in a loop.
+ *
+ * @param {import('node:http').ServerResponse} res
+ * @param {string} file
+ * @param {boolean} compressed
+ */
+async function sendEngine(res, file, compressed) {
+  const info = await stat(file);
+  if (!info.isFile()) throw new Error(`not a file: ${file}`);
+  res.setHeader('Content-Type', compressed ? 'application/wasm' : 'text/javascript');
+  if (compressed) res.setHeader('Content-Encoding', 'zstd');
+  res.setHeader('Content-Length', String(info.size));
+  res.setHeader('Cache-Control', 'no-cache');
+  await pipeline(createReadStream(file), res);
+}
+
+export default geckoWebView;

package/src/server.js

@@ -0,0 +1,128 @@
+// @ts-check
+import { createServer } from 'node:http';
+import { createReadStream } from 'node:fs';
+import { access, stat } from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+// The Wisp dependency ships no types; it is only used for its routeRequest hook.
+const wispModule = /** @type {{ server: any }} */ (
+  /** @type {any} */ (await import('@mercuryworkshop/wisp-js/server'))
+);
+const wispDefault = wispModule.server;
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const MIME = new Map([
+  ['.html', 'text/html; charset=utf-8'],
+  ['.js', 'text/javascript; charset=utf-8'],
+  ['.css', 'text/css; charset=utf-8'],
+  ['.zst', 'application/zstd'],
+  ['.json', 'application/json; charset=utf-8']
+]);
+
+/**
+ * @param {string} root
+ * @param {string} requestPath
+ * @returns {string | null}
+ */
+function safeFile(root, requestPath) {
+  const relative = requestPath.replace(/^\/+/, '');
+  const resolved = path.resolve(root, relative);
+  return resolved === root || resolved.startsWith(`${root}${path.sep}`) ? resolved : null;
+}
+
+/**
+ * @param {string} [url]
+ * @returns {string}
+ */
+function requestPathname(url = '/') {
+  try { return new URL(url, 'http://localhost').pathname; }
+  catch { return '/'; }
+}
+
+/**
+ * @param {import('node:http').ServerResponse} res
+ * @param {string} file
+ * @param {{ engine?: boolean }} [sendOptions]
+ */
+async function sendFile(res, file, { engine = false } = {}) {
+  try {
+    await access(file);
+    const info = await stat(file);
+    if (!info.isFile()) throw new Error('not a file');
+  } catch {
+    res.writeHead(404).end('Not found');
+    return;
+  }
+  const ext = path.extname(file).toLowerCase();
+  res.setHeader('Content-Type', MIME.get(ext) || 'application/octet-stream');
+  res.setHeader('Content-Length', String((await stat(file)).size));
+  res.setHeader('X-Content-Type-Options', 'nosniff');
+  if (engine) {
+    res.setHeader('Cross-Origin-Resource-Policy', 'same-origin');
+    res.setHeader('Cache-Control', 'public, max-age=86400');
+  }
+  res.writeHead(200);
+  createReadStream(file).pipe(res);
+}
+
+/**
+ * @typedef {object} WebviewServerOptions
+ * @property {string} [publicDir] static root, defaults to the demo directory
+ * @property {string} [libDir] library mount point, defaults to src/gecko
+ * @property {string} [engineDir] engine assets, defaults to engine
+ * @property {{ routeRequest: (req: any, socket: any, head: any) => void }} [wispServer]
+ *
+ * Serves the demo, the library and the engine with the cross-origin isolation
+ * headers the engine requires, and routes `/wisp/` upgrades to Wisp.
+ *
+ * @param {WebviewServerOptions} [options]
+ * @returns {import('node:http').Server}
+ */
+export function createWebviewServer(options = {}) {
+  const publicDir = path.resolve(options.publicDir || path.join(ROOT, 'demo'));
+  const libDir = path.resolve(options.libDir || path.join(ROOT, 'src', 'gecko'));
+  const engineDir = path.resolve(options.engineDir || path.join(ROOT, 'engine'));
+  const wispServer = options.wispServer || wispDefault;
+
+  const server = createServer(
+    /**
+     * @param {import('node:http').IncomingMessage} req
+     * @param {import('node:http').ServerResponse} res
+     */
+    async (req, res) => {
+    res.setHeader('Cross-Origin-Opener-Policy', 'same-origin');
+    res.setHeader('Cross-Origin-Embedder-Policy', 'require-corp');
+    const pathname = requestPathname(req.url);
+    if (pathname.startsWith('/lib/')) {
+      const file = safeFile(libDir, pathname.slice('/lib/'.length));
+      if (!file) return res.writeHead(400).end('Bad path');
+      return sendFile(res, file);
+    }
+    if (pathname.startsWith('/engine/')) {
+      const file = safeFile(engineDir, pathname.slice('/engine/'.length));
+      if (!file) return res.writeHead(400).end('Bad path');
+      return sendFile(res, file, { engine: true });
+    }
+    const relative = pathname === '/' ? 'index.html' : pathname.slice(1);
+    const file = safeFile(publicDir, relative);
+    if (!file) return res.writeHead(400).end('Bad path');
+      return sendFile(res, file);
+    }
+  );
+
+  server.on('upgrade', (req, socket, head) => {
+    if (requestPathname(req.url) === '/wisp/') {
+      wispServer.routeRequest(req, socket, head);
+      return;
+    }
+    socket.destroy();
+  });
+  return server;
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  const host = process.env.HOST || '127.0.0.1';
+  const port = Number(process.env.PORT || 8080);
+  const server = createWebviewServer();
+  server.listen(port, host, () => console.log(`webcanvas-wasm http://${host}:${port}`));
+}

package/types/engine.d.ts

@@ -0,0 +1,132 @@
+/**
+ * Type declarations for the vendored Gecko WASM engine bundle.
+ *
+ * The bundle (`engine/gecko.js`) is a third-party build artifact, not source we
+ * own, so it ships no types. Everything here was verified by reading the
+ * bundle and by exercising the running engine; see README "Engine artifacts".
+ *
+ * Two behaviours below are load-bearing and were confirmed empirically, so
+ * treat them as contract rather than incidental detail:
+ *
+ *  1. `evalChrome` runs in the *content* window of the currently loaded page,
+ *     NOT in chrome. `Services`, `Cc`, `Ci` and `ChromeUtils` are all
+ *     `undefined` there. `window` and `document` are the real page objects.
+ *  2. `evalChrome` resolves to `''` both when the snippet throws and when no
+ *     page has been loaded yet. Callers cannot tell those apart, which is why
+ *     `types/session.d.ts` wraps it in a discriminated union.
+ */
+
+/** Engine environment knobs that are actually useful to set. */
+export interface KnownGeckoEnv {
+  /** Disable the Wasm JIT tiers. Off by default upstream; required for sites
+   *  with deeply nested scripts, which otherwise fail with "too much recursion". */
+  GECKO_NOWASMJIT?: '0' | '1';
+  /** WebGL2 compositor. Requires the canvas to carry `id="screen"`, and forbids
+   *  the host page from taking a 2D context on the same canvas. */
+  GECKO_GPU?: '0' | '1';
+  GECKO_DARK?: '0' | '1';
+  /** Where the ~13 MB GRE remote package is fetched from. */
+  GECKO_GRE_PROVIDER?: string;
+  GECKO_PROFILE_PROVIDER?: string;
+  GECKO_OPFS_MOUNT?: string;
+  GECKO_SKIP_OPFS?: '0' | '1';
+  GECKO_DISK_CACHE?: string;
+  GECKO_APZ?: '0' | '1';
+  GECKO_STYLO_THREADS?: string;
+  GECKO_COARSE_CLOCK?: '0' | '1';
+  GECKO_IMG_PASSTHROUGH?: '0' | '1';
+  GECKO_WASM_PASSTHROUGH?: '0' | '1';
+  GECKO_GL_PASSTHROUGH?: '0' | '1';
+  GECKO_NO_NURSERY?: '0' | '1';
+  GECKO_NO_COMPACT?: '0' | '1';
+  GECKO_MIRROR?: string;
+  GECKO_CHROME?: string;
+  GECKO_CONTENT_CONSOLE?: '0' | '1';
+  GECKO_B_THRESHOLD?: string;
+}
+
+/**
+ * The engine exposes 426 `GECKO_*` names in total. Most are `GECKO_WJ_*`
+ * SpiderMonkey/Warp debug switches, so the index signature stays open instead
+ * of pretending the known list is exhaustive.
+ */
+export type GeckoEnv = KnownGeckoEnv & Record<string, string | undefined>;
+
+export interface GeckoWasmSource {
+  url: string;
+  /** The shipped artifact is zstd-deflated, so this is true in practice. */
+  compressed: boolean;
+}
+
+export interface GeckoOptions {
+  canvas: HTMLCanvasElement;
+  width?: number;
+  height?: number;
+  profile?: string;
+  wasm: GeckoWasmSource;
+  /** All target-site traffic tunnels through this same-origin WISP endpoint. */
+  wispUrl: string;
+  env?: GeckoEnv;
+  print?: (line: string) => void;
+  printErr?: (line: string) => void;
+  /** `false` skips attaching mouse/keyboard handlers. Defaults to attached. */
+  forwardInput?: boolean;
+  locateFile?: (path: string) => string;
+  fs?: unknown;
+}
+
+/**
+ * A raw command for the engine's serial queue, as accepted by {@link Gecko.run}.
+ *
+ * The opcodes are the bundle's own constant table, written as literals because a
+ * `.d.ts` cannot declare a frozen object:
+ *
+ * ```text
+ * 0 Load   1 Mouse   2 Key   3 Wheel   4 Paint   5 Eval   9 ClipSet
+ * ```
+ *
+ * The runtime above drives the engine through the named methods rather than this
+ * queue; it is declared because `run` is part of the vendored class.
+ */
+export type GeckoCommand =
+  | { op: 0; url: string }
+  | { op: 5; url: string }
+  | { op: 9; url: string }
+  | { op: 4 }
+  | { op: 1; x: number; y: number; button?: number; buttons?: number; clickCount?: number; modifiers?: number }
+  | { op: 2; key?: string; keyCode?: number; charCode?: number; modifiers?: number }
+  | { op: 3; deltaX?: number; deltaY?: number };
+
+export declare class Gecko {
+  constructor(options: GeckoOptions);
+
+  readonly gpu: boolean;
+  readonly running: boolean;
+
+  /** Instantiate the engine, mount GRE files, resolve when READY. */
+  init(): Promise<void>;
+
+  /**
+   * Navigate to an http(s) URL. Deliberately not awaited by callers upstream:
+   * a Gecko navigation can be in flight while its command promise stays
+   * pending, so awaiting it can hang.
+   */
+  load(url: string): Promise<unknown>;
+
+  resize(width: number, height: number): Promise<unknown>;
+
+  /**
+   * Evaluate a snippet in the loaded page's content window and return the
+   * stringified completion value.
+   *
+   * Resolves to `''` on throw and before any page has loaded. Does not await
+   * promises: `fetch(url).then(...)` stringifies to `"[object Promise]"`.
+   */
+  evalChrome(js: string): Promise<string>;
+
+  /** Stops loops and detaches input handlers. The wasm module is not torn down. */
+  destroy(): void;
+
+  /** Enqueue a raw command on the engine's serial command queue. */
+  run(item: GeckoCommand): Promise<unknown>;
+}

package/types/index.d.ts

@@ -0,0 +1,30 @@
+/**
+ * `webcanvas-wasm` — a Gecko WebView in WebAssembly.
+ *
+ * The engine is a real browser engine compiled to wasm, so a page it loads runs
+ * with genuine Gecko behaviour rather than a DOM shim. This module is the
+ * framework-agnostic core; see `webcanvas-wasm/react` and `webcanvas-wasm/vite`.
+ *
+ * Every value below is declared in this directory rather than re-exported from
+ * the `.js` sources. A consumer without `allowJs` cannot read the sources, so a
+ * re-export would silently degrade to `any` — which, among other things, breaks
+ * `instanceof` narrowing on {@link GeckoEvalError}.
+ */
+
+export { createGeckoRuntime, normalizeHttpUrl, GeckoEvalError, isGeckoEvalError } from './session.js';
+export { createGeckoPage } from './page.js';
+
+export type {
+  GeckoSession,
+  SessionState,
+  SessionOptions,
+  EvaluateOptions,
+  WaitForOptions,
+  EvalResult,
+  GeckoErrorCode,
+  TypeGuard,
+  ElementSnapshot,
+  ElementRect
+} from './session.js';
+
+export type { GeckoPage } from './page.js';

package/types/page.d.ts

@@ -0,0 +1,85 @@
+/**
+ * The page object: task-shaped helpers over a {@link GeckoSession}.
+ *
+ * Each method is a single round-trip to the page, so a call site reads like the
+ * script it replaces.
+ */
+
+import type { ElementSnapshot, GeckoSession } from './session.js';
+
+export interface GeckoPage {
+  /** The session this page drives, for anything not modelled here. */
+  readonly session: GeckoSession;
+
+  /** Navigate and wait until the document is scriptable. */
+  open(url: string, timeoutMs?: number): Promise<string>;
+
+  reload(): string | null;
+
+  url(): Promise<string>;
+  origin(): Promise<string>;
+  title(): Promise<string>;
+
+  /** Evaluate in the page. Throws {@link GeckoEvalError} on failure. */
+  eval<T = unknown>(code: string, options?: { timeoutMs?: number }): Promise<T>;
+
+  /** Poll a boolean snippet until it holds or the timeout elapses. */
+  waitFor(predicate: string, options?: { timeoutMs?: number; intervalMs?: number }): Promise<boolean>;
+
+  /** Poll until a selector matches. Resolves to `null` on timeout. */
+  waitForSelector<T = ElementSnapshot>(
+    selector: string,
+    options?: { timeoutMs?: number; intervalMs?: number }
+  ): Promise<T | null>;
+
+  /**
+   * Brief pause after an action so a follow-up read does not race the handler.
+   *
+   * There is no reliable completion signal for an in-page click, so this is a
+   * deliberate small delay rather than a guarantee.
+   */
+  settle(ms?: number): Promise<void>;
+
+  exists(selector: string): Promise<boolean>;
+  count(selector: string): Promise<number>;
+
+  /** Snapshot the first match, or `null` when nothing matches. */
+  query<T = unknown>(selector: string): Promise<T | null>;
+  queryAll<T = unknown>(selector: string): Promise<T[]>;
+
+  /** Trimmed `textContent` of the first match, or `''` when unmatched. */
+  text(selector: string): Promise<string>;
+
+  /** `getAttribute` on the first match, or `null` when absent or unmatched. */
+  attr(name: string, selector: string): Promise<string | null>;
+
+  /**
+   * Set a form control's value and fire `input` plus `change`.
+   *
+   * Assigning `element.value` directly is invisible to React and to any other
+   * framework that tracks the last value it set, so the component would keep
+   * its own state and revert the change on the next render. This drives the
+   * native setter and dispatches the events real typing produces.
+   *
+   * @throws when the selector matches nothing.
+   */
+  fill(selector: string, value: string): Promise<boolean>;
+
+  /**
+   * Type a value one character at a time, firing key events between edits.
+   *
+   * Use this instead of {@link GeckoPage.fill} for sites that only respond to
+   * real key events, such as search-as-you-type inputs and shortcuts.
+   */
+  type(selector: string, value: string): Promise<boolean>;
+
+  /**
+   * Scroll into view, click, then settle briefly.
+   *
+   * @returns `false` when the selector matched nothing.
+   */
+  click(selector: string): Promise<boolean>;
+}
+
+/** Wrap a session in the task-shaped helper surface. */
+export declare function createGeckoPage(session: GeckoSession): GeckoPage;

package/types/react.d.ts

@@ -0,0 +1,102 @@
+/**
+ * `webcanvas-wasm/react` — React bindings.
+ *
+ * The engine lives outside React; these types describe how the component tree
+ * observes it. React is an optional peer dependency, so importing this module
+ * does not pull React into a non-React project.
+ *
+ * The functions are declared here rather than re-exported from the `.js` source
+ * for the same reason as the core entry: a consumer without `allowJs` cannot
+ * read the source, so a re-export would silently become `any`.
+ */
+
+import type { Context, ReactElement, ReactNode, RefObject } from 'react';
+
+import type { GeckoPage } from './page.js';
+import type { GeckoSession, SessionOptions, SessionState } from './session.js';
+
+export interface GeckoContextValue {
+  /** Null until the engine has been created; do not dereference during render. */
+  readonly session: GeckoSession | null;
+  /** Task-shaped helpers, available at the same time as {@link GeckoContextValue.session}. */
+  readonly page: GeckoPage | null;
+  readonly state: SessionState;
+  /** Whatever `init()` rejected with, cleared on a successful boot. */
+  readonly error: unknown;
+  readonly ready: boolean;
+  /**
+   * Changes whenever the engine handle is replaced.
+   *
+   * Include it in a dependency list to re-read a value after a restart.
+   */
+  readonly generation: number;
+}
+
+export interface GeckoProviderProps extends Omit<SessionOptions, 'canvas'> {
+  children?: ReactNode;
+  /**
+   * Use an existing canvas instead of letting the provider render one.
+   *
+   * A canvas supplied this way is *not* rendered, so it must be mounted
+   * somewhere in the tree and visible, otherwise the engine has no surface.
+   */
+  canvasRef?: RefObject<HTMLCanvasElement | null>;
+}
+
+/**
+ * Lifecycle of a value read from the page.
+ *
+ * A read is `'pending'` until it lands and keeps the previous value meanwhile,
+ * so a navigation does not blank the screen.
+ */
+export type GeckoRunResult<T> =
+  | { readonly status: 'idle'; readonly value: undefined }
+  | { readonly status: 'pending'; readonly value: T | undefined }
+  | { readonly status: 'ok'; readonly value: T }
+  | { readonly status: 'error'; readonly value: T | undefined; readonly error: unknown };
+
+/**
+ * Provides one Gecko engine to the subtree below it.
+ *
+ * The engine is created on mount, after React's render phase — creating it
+ * during render would boot two engines, because React renders twice in
+ * development — and torn down when the provider unmounts.
+ */
+export function GeckoProvider(props: GeckoProviderProps): ReactElement;
+
+/** The full context. Throws if used outside a {@link GeckoProvider}. */
+export function useGecko(): GeckoContextValue;
+
+/** The page object, or `null` before the engine exists. */
+export function useGeckoPage(): GeckoPage | null;
+
+/** Just the lifecycle state, for components that only show a spinner. */
+export function useGeckoState(): SessionState;
+
+/**
+ * Run an async read against the page and keep the result in state.
+ *
+ * A result from a superseded run is discarded, so a slow evaluation cannot
+ * overwrite a newer one. `deps` is the dependency list; the callback itself is
+ * held in a ref, so an inline closure does not re-run on every render.
+ */
+export function useGeckoValue<T>(
+  run: (session: GeckoSession) => Promise<T> | T,
+  deps?: unknown[]
+): GeckoRunResult<T>;
+
+/** Convenience wrapper around {@link useGeckoValue} for a single `eval`. */
+export function useGeckoEval<T = unknown>(
+  code: string,
+  options?: { deps?: unknown[]; evaluateOptions?: { timeoutMs?: number } }
+): GeckoRunResult<T>;
+
+/**
+ * The context itself, for consumers writing their own provider.
+ *
+ * It holds `null` outside a provider, which is what lets {@link useGecko} throw
+ * a message naming the problem instead of failing on a null dereference.
+ */
+export const GeckoContext: Context<GeckoContextValue | null>;
+
+export default GeckoProvider;

package/types/server.d.ts

@@ -0,0 +1,20 @@
+/**
+ * `webcanvas-wasm/server` — a small static server for apps that embed the engine.
+ *
+ * Useful for local development and for single-process hosting: it serves the
+ * engine, mounts the library, applies the cross-origin isolation headers and
+ * proxies `/wisp/` upgrades to the Wisp network, all from one `node` process.
+ */
+
+export interface WebviewServerOptions {
+  /** Static root. Defaults to the demo directory shipped with the package. */
+  publicDir?: string;
+  /** Library mount point. Defaults to `src/gecko`. */
+  libDir?: string;
+  /** Engine assets. Defaults to the `engine` directory. */
+  engineDir?: string;
+  /** Wisp request router, usually `server` from `@mercuryworkshop/wisp-js/server`. */
+  wispServer?: { routeRequest(request: unknown, socket: unknown, head: unknown): void };
+}
+
+export function createWebviewServer(options?: WebviewServerOptions): import('node:http').Server;