Lean VIR SDK
============

This SDK contains the JavaScript runtime modules and wasm32-wasip1 interpreter
for the matching lean_vir package revision.

The JavaScript files are ES modules. The generic runtime and host-binding
modules do not import React; js/vir-react-host-bindings.js imports react and
react-dom/client and should only be used by browser React integrations.

Application code should import the entry modules directly under js/:

  js/vir-runtime.js
  js/vir-runtime-node.js
  js/vir-host-bindings.js
  js/vir-react-host-bindings.js

Nested js/runtime/, js/host/, and js/react/ modules are shipped so those entry
modules can resolve relative imports. They remain internal implementation
modules and may change with the matching lean_vir revision.

In a Lake client package, mark JavaScript-callable declarations with
@[vir_export] and startup hooks with @[vir_startup], then build the module
package and matching SDK:

  lake build +MyApp.Runtime:vir
  lake build :virSdk

The module facet creates a descriptor plus ordinary .irpkg members. Serve:

  wasm/vir-upstream.wasm
  wasm/vir-upstream.dev.wasm
  js/vir-runtime.js
  your generated .irpkg-set.json and all of its .irpkg members

wasm/vir-upstream.wasm is the stripped release artifact and is selected by
default. wasm/vir-upstream.dev.wasm is an optimized, unstripped debugging
companion.

Minimal browser usage:

  import { createVirRuntime } from "./js/vir-runtime.js";

  const vir = await createVirRuntime({
    wasmUrl: "./wasm/vir-upstream.wasm",
    irPackageSetUrl: "./MyApp/Runtime.irpkg-set.json",
  });

  vir.runStartupEntries();

Call vir.dispose() when the page or application is torn down.

Set debugWasm: true to load ./wasm/vir-upstream.dev.wasm instead:

  const debugVir = await createVirRuntime({
    wasmUrl: "./wasm/vir-upstream.wasm",
    debugWasm: true,
    irPackageSetUrl: "./MyApp/Runtime.irpkg-set.json",
  });

Browser React root usage:

  import { createVirRuntimeFactory } from "./js/vir-runtime.js";
  import {
    createBrowserHostBindings,
    createHostResourceState,
  } from "./js/vir-host-bindings.js";
  import { createBrowserReactHostBindings } from "./js/vir-react-host-bindings.js";

  const factory = createVirRuntimeFactory({
    wasmUrl: "./wasm/vir-upstream.wasm",
    defaultHostBindings: () => {
      const resources = createHostResourceState();
      return createBrowserHostBindings({
        resources,
        reactHostBindings: createBrowserReactHostBindings(resources),
      });
    },
  });

Check lean-vir-artifact.json before mixing this SDK with generated packages
from another lean_vir revision.
