@pi-oxide/piccolo-notebook-wasm

Self-contained WebAssembly build of the Piccolo Lua notebook engine. No external WASM file needed — everything is embedded as a single JS module.

Install

npm install @pi-oxide/piccolo-notebook-wasm

Quick start

import { WasmSession } from '@pi-oxide/piccolo-notebook-wasm';

const session = new WasmSession();

// Run a code cell (returns a Promise because fetch/sleep are handled in WASM)
const result = await session.runCellAsync(`
print("hello from Lua")
return 2 + 2
`, "");

console.log(result.stdout);        // ["hello from Lua"]
console.log(result.result);      // "4"
console.log(result.error);       // null

API

new WasmSession()

Creates a new isolated Lua session.

runCellAsync(code: string, stdin: string): Promise<WasmRunResult>

Executes a cell of Lua code. Async because web.fetch() and web.sleep() are resolved directly inside WASM via wasm-bindgen-futures.

run_cell(code: string, stdin: string): WasmRunResult

Synchronous version. Use this if you know the cell does not perform async I/O.

resume_cell(response: WasmAsyncResponse): WasmRunResult

Resume a yielded cell with an async response (for JS-side handling of storage, clipboard, DOM, or chrome.* APIs).

inspect_globals(): WasmGlobalsSnapshot

Returns all global variables in the current Lua state with their types and values.

load_library(source: string): WasmRunResult

Load a Lua library by executing its source code.

reset(): void

Reset the session, clearing all Lua state.

set_fuel_limit(limit: number): void

Set the execution fuel limit (prevents infinite loops).

Types

interface WasmRunResult {
  stdout: string[];
  stderr: string[];
  result: string | null;
  error: WasmCellError | null;
  commands: any[];
  fuel_exhausted: boolean;
  execution_count: number;
  status: "done" | "async_pending";
  pending_command: WasmAsyncCommand | null;
}

interface WasmAsyncCommand {
  call_id: number;
  action: string;
  params: any;
}

interface WasmGlobalsSnapshot {
  variables: WasmGlobalVariable[];
  execution_count: number;
}

How it works

• The .wasm binary is base64-embedded directly into the JS file — no fetch(), no separate file.
• initSync() runs automatically at module load, so you don't need to call any initialization function.
• web.fetch() and web.sleep() are resolved inside WASM using wasm-bindgen-futures, so they don't yield to JavaScript unless necessary.
• Only storage, clipboard, DOM, and Chrome extension APIs require the JS host to handle the async command and call resume_cell().

License

Proprietary