webcanvas-wasm 0.1.0

package/types/session.d.ts

@@ -0,0 +1,216 @@
+/**
+ * The typed surface this repository exposes over the vendored Gecko engine.
+ *
+ * The raw `Gecko` class is a thin, leaky interface: `evalChrome` collapses every
+ * failure into `''`, and it stringifies its completion value synchronously, so a
+ * promise comes back as `"[object Promise]"`. `GeckoSession` is the ergonomic
+ * layer over that: it awaits promises, reports failures as typed throws, and
+ * exposes a subscription point so a UI framework can observe it.
+ */
+
+import type { Gecko, GeckoEnv } from './engine.js';
+
+export type SessionState = 'idle' | 'booting' | 'ready' | 'loading' | 'destroyed';
+
+/** Why an evaluation failed. Stable across versions, safe to switch on. */
+export type GeckoErrorCode = 'not-ready' | 'no-page' | 'no-result' | 'throw' | 'shape' | 'timeout';
+
+/**
+ * Raised by {@link GeckoSession.eval} and friends.
+ *
+ * Distinct from a plain `Error` so callers can tell a WebView failure from a
+ * bug in their own code.
+ *
+ * The class and its guard are re-exported from the implementation rather than
+ * declared here. A second declaration would be a *different* type with the same
+ * name, which silently breaks `instanceof` narrowing for consumers.
+ */
+export declare class GeckoEvalError extends Error {
+  readonly name: 'GeckoEvalError';
+  readonly code: GeckoErrorCode;
+  constructor(message: string, code: GeckoErrorCode);
+}
+
+export declare function isGeckoEvalError(value: unknown): value is GeckoEvalError;
+
+/**
+ * Normalise a user-supplied address into something the engine can load.
+ *
+ * A bare host is assumed to be https; anything with a non-http scheme is
+ * rejected, because handing `javascript:` to a navigation is how a page would
+ * end up executing in the host document's origin.
+ */
+export declare function normalizeHttpUrl(value: string): string;
+
+/** Create a session. Nothing is loaded until {@link GeckoSession.init}. */
+export declare function createGeckoRuntime(options?: Partial<SessionOptions>): GeckoSession;
+
+/**
+ * Non-throwing result form.
+ *
+ * The ergonomic default is to throw, so this is only needed where a value is
+ * genuinely more convenient than a `try`/`catch` — typically in a render path
+ * that must not unwind.
+ */
+export type EvalResult<T> =
+  | { readonly ok: true; readonly value: T }
+  | { readonly ok: false; readonly error: string };
+
+export type TypeGuard<T> = (value: unknown) => value is T;
+
+export interface EvaluateOptions {
+  /** Applies only to snippets whose value is a promise. */
+  timeoutMs?: number;
+}
+
+export interface WaitForOptions {
+  timeoutMs?: number;
+  intervalMs?: number;
+}
+
+export interface SessionOptions {
+  canvas: HTMLCanvasElement;
+  /** Defaults to `globalThis.window`; injectable for tests. */
+  host?: Window;
+  profile?: string;
+  width?: number;
+  height?: number;
+  env?: GeckoEnv;
+  /** Defaults to `/engine/gecko.js`. */
+  bundleUrl?: string;
+  /** Defaults to `/engine/gecko.wasm.zst`. */
+  wasmUrl?: string;
+  /** Injectable module loader; the default is a dynamic `import()`. */
+  loadModule?: (url: string) => Promise<{ Gecko: typeof Gecko }>;
+  onLog?: (line: string) => void;
+  onError?: (error: unknown) => void;
+}
+
+/** Rectangle reported by `getBoundingClientRect()`. */
+export interface ElementRect {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+
+/**
+ * A plain-data projection of a page element.
+ *
+ * The command bridge is string-based, so a live `Element` cannot cross it
+ * intact. These helpers return a snapshot instead of pretending otherwise.
+ */
+export interface ElementSnapshot {
+  tag: string;
+  id: string | null;
+  className: string | null;
+  text: string;
+  html: string;
+  attrs: Record<string, string>;
+  visible: boolean;
+  rect: ElementRect;
+}
+
+export interface GeckoSession {
+  readonly state: SessionState;
+  /** URL of the most recent navigation, or `null` before the first one. */
+  readonly currentUrl: string | null;
+  /** `true` once the engine is instantiated and past its init handshake. */
+  readonly ready: boolean;
+
+  /**
+   * Instantiate the engine and wait for READY. Does not navigate: the boot path
+   * deliberately performs no hidden `about:blank` load.
+   *
+   * Resolves to the live engine instance, which stays reachable afterwards via
+   * {@link GeckoSession.raw}.
+   */
+  init(): Promise<Gecko>;
+
+  /** Normalise and dispatch a navigation without awaiting its promise. */
+  navigate(value: string): string;
+
+  /**
+   * Navigate and wait until the new document is scriptable.
+   *
+   * Prefer this over {@link GeckoSession.navigate}: navigating only dispatches,
+   * so evaluating immediately afterwards races the load.
+   */
+  open(value: string, timeoutMs?: number): Promise<string>;
+
+  /** Re-navigate to `currentUrl`, or return `null` if there is none. */
+  reload(): string | null;
+
+  resize(width?: number, height?: number): Promise<void>;
+
+  /**
+   * Subscribe to state changes. The listener fires immediately with the current
+   * state, which is what `useSyncExternalStore` expects.
+   *
+   * The listener runs on the engine's own callbacks, so it fires outside any
+   * framework's batching.
+   */
+  subscribe(listener: (state: SessionState) => void): () => void;
+
+  /**
+   * Evaluate a snippet in the loaded page and return its value.
+   *
+   * Throws {@link GeckoEvalError} rather than returning a sentinel, so
+   * `await session.eval('document.title')` just gives the title. A
+   * promise-returning snippet is awaited automatically.
+   */
+  eval<T = unknown>(code: string, options?: EvaluateOptions): Promise<T>;
+
+  /** Explicit alias for {@link GeckoSession.eval}. */
+  evaluate<T = unknown>(code: string, options?: EvaluateOptions): Promise<T>;
+
+  /**
+   * As {@link GeckoSession.eval}, but validates the shape.
+   *
+   * @throws `GeckoEvalError` with code `shape` when the guard rejects.
+   */
+  evalJson<T>(code: string, guard: TypeGuard<T>): Promise<T>;
+
+  /**
+   * Run a call and convert a thrown {@link GeckoEvalError} into a result union.
+   *
+   * @example
+   * const found = await session.attempt(() => session.eval('document.title'));
+   * if (found.ok) render(found.value);
+   */
+  attempt<T>(fn: () => Promise<T> | T): Promise<EvalResult<T>>;
+
+  /**
+   * @deprecated Promises are awaited automatically by `eval`. Kept so existing
+   * call sites keep working.
+   */
+  evalAsync<T = unknown>(code: string, timeoutMs?: number): Promise<T>;
+
+  /** Poll a boolean snippet until it returns true or the timeout elapses. */
+  waitFor(predicate: string, options?: WaitForOptions): Promise<boolean>;
+
+  /** Snapshot the first match, or `null` when nothing matches. */
+  query<T = ElementSnapshot>(selector: string): Promise<T | null>;
+
+  /** Snapshot every match; an empty array when nothing matches. */
+  queryAll<T = ElementSnapshot>(selector: string): Promise<T[]>;
+
+  /** Trimmed `textContent` of the first match, or `''` when nothing matches. */
+  text(selector: string): Promise<string>;
+
+  /** `getAttribute` on the first match, or `null` when absent or unmatched. */
+  attr(name: string, selector: string): Promise<string | null>;
+
+  /** Dispatch a synthetic click on the first match. */
+  click(selector: string): Promise<boolean>;
+
+  /** Stop the engine's loops and detach input handlers. */
+  destroy(): void;
+
+  /**
+   * Escape hatch to the underlying engine, for commands and properties this
+   * wrapper does not model. Null until {@link GeckoSession.init} resolves and
+   * after {@link GeckoSession.destroy}.
+   */
+  readonly raw: Gecko | null;
+}

package/types/vite.d.ts

@@ -0,0 +1,47 @@
+/**
+ * `webcanvas-wasm/vite` — serves the engine and sets the isolation headers.
+ *
+ * The plugin type is declared structurally rather than as `import('vite').Plugin`
+ * so that a non-Vite consumer who merely has this package installed does not need
+ * Vite's own types present.
+ */
+
+export interface GeckoVitePluginOptions {
+  /** Source directory holding the engine assets. Defaults to the bundled engine. */
+  engineDir?: string;
+  /** Public path to serve the engine from. Defaults to `/engine`. */
+  mount?: string;
+  /** Set false to serve the engine yourself instead of copying it on build. */
+  copyOnBuild?: boolean;
+}
+
+export interface GeckoVitePlugin {
+  name: string;
+  buildStart?: () => Promise<void>;
+  configureServer?: (server: GeckoDevServer) => void;
+  writeBundle?: (outputOptions: { dir?: string }) => Promise<void>;
+}
+
+/**
+ * A Connect-style middleware, typed loosely on purpose.
+ *
+ * The real `res` is a `ServerResponse`, which is a Writable stream with dozens
+ * of members. Spelling that out structurally would add nothing for a caller —
+ * Vite supplies the object, nobody constructs one — while making this file
+ * depend on Node's exact stream typings.
+ */
+export type GeckoMiddleware = (req: any, res: any, next: () => void) => void;
+
+export interface GeckoDevServer {
+  middlewares: {
+    use(handler: GeckoMiddleware): void;
+    use(route: string, handler: GeckoMiddleware): void;
+  };
+}
+
+export function geckoWebView(options?: GeckoVitePluginOptions): GeckoVitePlugin;
+
+/** The two headers the engine requires, plus a matching resource policy. */
+export function setIsolationHeaders(res: { setHeader(name: string, value: string): void }): void;
+
+export default geckoWebView;

package/types/wisp.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Minimal declarations for the one dependency that ships no types.
+ *
+ * The server only needs Wisp's request router, so declaring just that keeps
+ * `checkJs` honest without pulling the whole surface in.
+ */
+declare module '@mercuryworkshop/wisp-js/server' {
+  export interface WispRouteServer {
+    routeRequest(
+      request: import('node:http').IncomingMessage,
+      socket: import('node:stream').Duplex,
+      head: Buffer
+    ): void;
+  }
+
+  export const server: WispRouteServer;
+}