petitpy 0.0.0-stage → 0.8.0

package/LICENSE

@@ -0,0 +1,290 @@
+The MIT License (MIT)
+
+Copyright (c) 2025-2026 Stefane Fermigier
+Copyright (c) 2013-2025 Damien P. George and the MicroPython contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
+
+--------------------------------------------------------------------------------
+
+petitpy builds on MicroPython (https://micropython.org/), whose code is under
+the MIT license above.
+
+The modules heapq, bisect and types (nanopython-lib/heapq.py, bisect.py and
+types.py) are verbatim copies from micropython-lib
+(https://github.com/micropython/micropython-lib, commit 381ac746), which
+derives them from CPython. They are under the Python license below, as
+micropython-lib distributes them.
+
+=============== Python License ===============
+
+A. HISTORY OF THE SOFTWARE
+==========================
+
+Python was created in the early 1990s by Guido van Rossum at Stichting
+Mathematisch Centrum (CWI, see http://www.cwi.nl) in the Netherlands
+as a successor of a language called ABC.  Guido remains Python's
+principal author, although it includes many contributions from others.
+
+In 1995, Guido continued his work on Python at the Corporation for
+National Research Initiatives (CNRI, see http://www.cnri.reston.va.us)
+in Reston, Virginia where he released several versions of the
+software.
+
+In May 2000, Guido and the Python core development team moved to
+BeOpen.com to form the BeOpen PythonLabs team.  In October of the same
+year, the PythonLabs team moved to Digital Creations (now Zope
+Corporation, see http://www.zope.com).  In 2001, the Python Software
+Foundation (PSF, see http://www.python.org/psf/) was formed, a
+non-profit organization created specifically to own Python-related
+Intellectual Property.  Zope Corporation is a sponsoring member of
+the PSF.
+
+All Python releases are Open Source (see http://www.opensource.org for
+the Open Source Definition).  Historically, most, but not all, Python
+releases have also been GPL-compatible; the table below summarizes
+the various releases.
+
+    Release         Derived     Year        Owner       GPL-
+                    from                                compatible? (1)
+
+    0.9.0 thru 1.2              1991-1995   CWI         yes
+    1.3 thru 1.5.2  1.2         1995-1999   CNRI        yes
+    1.6             1.5.2       2000        CNRI        no
+    2.0             1.6         2000        BeOpen.com  no
+    1.6.1           1.6         2001        CNRI        yes (2)
+    2.1             2.0+1.6.1   2001        PSF         no
+    2.0.1           2.0+1.6.1   2001        PSF         yes
+    2.1.1           2.1+2.0.1   2001        PSF         yes
+    2.1.2           2.1.1       2002        PSF         yes
+    2.1.3           2.1.2       2002        PSF         yes
+    2.2 and above   2.1.1       2001-now    PSF         yes
+
+Footnotes:
+
+(1) GPL-compatible doesn't mean that we're distributing Python under
+    the GPL.  All Python licenses, unlike the GPL, let you distribute
+    a modified version without making your changes open source.  The
+    GPL-compatible licenses make it possible to combine Python with
+    other software that is released under the GPL; the others don't.
+
+(2) According to Richard Stallman, 1.6.1 is not GPL-compatible,
+    because its license has a choice of law clause.  According to
+    CNRI, however, Stallman's lawyer has told CNRI's lawyer that 1.6.1
+    is "not incompatible" with the GPL.
+
+Thanks to the many outside volunteers who have worked under Guido's
+direction to make these releases possible.
+
+
+B. TERMS AND CONDITIONS FOR ACCESSING OR OTHERWISE USING PYTHON
+===============================================================
+
+PYTHON SOFTWARE FOUNDATION LICENSE VERSION 2
+--------------------------------------------
+
+1. This LICENSE AGREEMENT is between the Python Software Foundation
+("PSF"), and the Individual or Organization ("Licensee") accessing and
+otherwise using this software ("Python") in source or binary form and
+its associated documentation.
+
+2. Subject to the terms and conditions of this License Agreement, PSF hereby
+grants Licensee a nonexclusive, royalty-free, world-wide license to reproduce,
+analyze, test, perform and/or display publicly, prepare derivative works,
+distribute, and otherwise use Python alone or in any derivative version,
+provided, however, that PSF's License Agreement and PSF's notice of copyright,
+i.e., "Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010,
+2011, 2012, 2013 Python Software Foundation; All Rights Reserved" are retained
+in Python alone or in any derivative version prepared by Licensee.
+
+3. In the event Licensee prepares a derivative work that is based on
+or incorporates Python or any part thereof, and wants to make
+the derivative work available to others as provided herein, then
+Licensee hereby agrees to include in any such work a brief summary of
+the changes made to Python.
+
+4. PSF is making Python available to Licensee on an "AS IS"
+basis.  PSF MAKES NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR
+IMPLIED.  BY WAY OF EXAMPLE, BUT NOT LIMITATION, PSF MAKES NO AND
+DISCLAIMS ANY REPRESENTATION OR WARRANTY OF MERCHANTABILITY OR FITNESS
+FOR ANY PARTICULAR PURPOSE OR THAT THE USE OF PYTHON WILL NOT
+INFRINGE ANY THIRD PARTY RIGHTS.
+
+5. PSF SHALL NOT BE LIABLE TO LICENSEE OR ANY OTHER USERS OF PYTHON
+FOR ANY INCIDENTAL, SPECIAL, OR CONSEQUENTIAL DAMAGES OR LOSS AS
+A RESULT OF MODIFYING, DISTRIBUTING, OR OTHERWISE USING PYTHON,
+OR ANY DERIVATIVE THEREOF, EVEN IF ADVISED OF THE POSSIBILITY THEREOF.
+
+6. This License Agreement will automatically terminate upon a material
+breach of its terms and conditions.
+
+7. Nothing in this License Agreement shall be deemed to create any
+relationship of agency, partnership, or joint venture between PSF and
+Licensee.  This License Agreement does not grant permission to use PSF
+trademarks or trade name in a trademark sense to endorse or promote
+products or services of Licensee, or any third party.
+
+8. By copying, installing or otherwise using Python, Licensee
+agrees to be bound by the terms and conditions of this License
+Agreement.
+
+
+BEOPEN.COM LICENSE AGREEMENT FOR PYTHON 2.0
+-------------------------------------------
+
+BEOPEN PYTHON OPEN SOURCE LICENSE AGREEMENT VERSION 1
+
+1. This LICENSE AGREEMENT is between BeOpen.com ("BeOpen"), having an
+office at 160 Saratoga Avenue, Santa Clara, CA 95051, and the
+Individual or Organization ("Licensee") accessing and otherwise using
+this software in source or binary form and its associated
+documentation ("the Software").
+
+2. Subject to the terms and conditions of this BeOpen Python License
+Agreement, BeOpen hereby grants Licensee a non-exclusive,
+royalty-free, world-wide license to reproduce, analyze, test, perform
+and/or display publicly, prepare derivative works, distribute, and
+otherwise use the Software alone or in any derivative version,
+provided, however, that the BeOpen Python License is retained in the
+Software, alone or in any derivative version prepared by Licensee.
+
+3. BeOpen is making the Software available to Licensee on an "AS IS"
+basis.  BEOPEN MAKES NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR
+IMPLIED.  BY WAY OF EXAMPLE, BUT NOT LIMITATION, BEOPEN MAKES NO AND
+DISCLAIMS ANY REPRESENTATION OR WARRANTY OF MERCHANTABILITY OR FITNESS
+FOR ANY PARTICULAR PURPOSE OR THAT THE USE OF THE SOFTWARE WILL NOT
+INFRINGE ANY THIRD PARTY RIGHTS.
+
+4. BEOPEN SHALL NOT BE LIABLE TO LICENSEE OR ANY OTHER USERS OF THE
+SOFTWARE FOR ANY INCIDENTAL, SPECIAL, OR CONSEQUENTIAL DAMAGES OR LOSS
+AS A RESULT OF USING, MODIFYING OR DISTRIBUTING THE SOFTWARE, OR ANY
+DERIVATIVE THEREOF, EVEN IF ADVISED OF THE POSSIBILITY THEREOF.
+
+5. This License Agreement will automatically terminate upon a material
+breach of its terms and conditions.
+
+6. This License Agreement shall be governed by and interpreted in all
+respects by the law of the State of California, excluding conflict of
+law provisions.  Nothing in this License Agreement shall be deemed to
+create any relationship of agency, partnership, or joint venture
+between BeOpen and Licensee.  This License Agreement does not grant
+permission to use BeOpen trademarks or trade names in a trademark
+sense to endorse or promote products or services of Licensee, or any
+third party.  As an exception, the "BeOpen Python" logos available at
+http://www.pythonlabs.com/logos.html may be used according to the
+permissions granted on that web page.
+
+7. By copying, installing or otherwise using the software, Licensee
+agrees to be bound by the terms and conditions of this License
+Agreement.
+
+
+CNRI LICENSE AGREEMENT FOR PYTHON 1.6.1
+---------------------------------------
+
+1. This LICENSE AGREEMENT is between the Corporation for National
+Research Initiatives, having an office at 1895 Preston White Drive,
+Reston, VA 20191 ("CNRI"), and the Individual or Organization
+("Licensee") accessing and otherwise using Python 1.6.1 software in
+source or binary form and its associated documentation.
+
+2. Subject to the terms and conditions of this License Agreement, CNRI
+hereby grants Licensee a nonexclusive, royalty-free, world-wide
+license to reproduce, analyze, test, perform and/or display publicly,
+prepare derivative works, distribute, and otherwise use Python 1.6.1
+alone or in any derivative version, provided, however, that CNRI's
+License Agreement and CNRI's notice of copyright, i.e., "Copyright (c)
+1995-2001 Corporation for National Research Initiatives; All Rights
+Reserved" are retained in Python 1.6.1 alone or in any derivative
+version prepared by Licensee.  Alternately, in lieu of CNRI's License
+Agreement, Licensee may substitute the following text (omitting the
+quotes): "Python 1.6.1 is made available subject to the terms and
+conditions in CNRI's License Agreement.  This Agreement together with
+Python 1.6.1 may be located on the Internet using the following
+unique, persistent identifier (known as a handle): 1895.22/1013.  This
+Agreement may also be obtained from a proxy server on the Internet
+using the following URL: http://hdl.handle.net/1895.22/1013".
+
+3. In the event Licensee prepares a derivative work that is based on
+or incorporates Python 1.6.1 or any part thereof, and wants to make
+the derivative work available to others as provided herein, then
+Licensee hereby agrees to include in any such work a brief summary of
+the changes made to Python 1.6.1.
+
+4. CNRI is making Python 1.6.1 available to Licensee on an "AS IS"
+basis.  CNRI MAKES NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR
+IMPLIED.  BY WAY OF EXAMPLE, BUT NOT LIMITATION, CNRI MAKES NO AND
+DISCLAIMS ANY REPRESENTATION OR WARRANTY OF MERCHANTABILITY OR FITNESS
+FOR ANY PARTICULAR PURPOSE OR THAT THE USE OF PYTHON 1.6.1 WILL NOT
+INFRINGE ANY THIRD PARTY RIGHTS.
+
+5. CNRI SHALL NOT BE LIABLE TO LICENSEE OR ANY OTHER USERS OF PYTHON
+1.6.1 FOR ANY INCIDENTAL, SPECIAL, OR CONSEQUENTIAL DAMAGES OR LOSS AS
+A RESULT OF MODIFYING, DISTRIBUTING, OR OTHERWISE USING PYTHON 1.6.1,
+OR ANY DERIVATIVE THEREOF, EVEN IF ADVISED OF THE POSSIBILITY THEREOF.
+
+6. This License Agreement will automatically terminate upon a material
+breach of its terms and conditions.
+
+7. This License Agreement shall be governed by the federal
+intellectual property law of the United States, including without
+limitation the federal copyright law, and, to the extent such
+U.S. federal law does not apply, by the law of the Commonwealth of
+Virginia, excluding Virginia's conflict of law provisions.
+Notwithstanding the foregoing, with regard to derivative works based
+on Python 1.6.1 that incorporate non-separable material that was
+previously distributed under the GNU General Public License (GPL), the
+law of the Commonwealth of Virginia shall govern this License
+Agreement only as to issues arising under or with respect to
+Paragraphs 4, 5, and 7 of this License Agreement.  Nothing in this
+License Agreement shall be deemed to create any relationship of
+agency, partnership, or joint venture between CNRI and Licensee.  This
+License Agreement does not grant permission to use CNRI trademarks or
+trade name in a trademark sense to endorse or promote products or
+services of Licensee, or any third party.
+
+8. By clicking on the "ACCEPT" button where indicated, or by copying,
+installing or otherwise using Python 1.6.1, Licensee agrees to be
+bound by the terms and conditions of this License Agreement.
+
+        ACCEPT
+
+
+CWI LICENSE AGREEMENT FOR PYTHON 0.9.0 THROUGH 1.2
+--------------------------------------------------
+
+Copyright (c) 1991 - 1995, Stichting Mathematisch Centrum Amsterdam,
+The Netherlands.  All rights reserved.
+
+Permission to use, copy, modify, and distribute this software and its
+documentation for any purpose and without fee is hereby granted,
+provided that the above copyright notice appear in all copies and that
+both that copyright notice and this permission notice appear in
+supporting documentation, and that the name of Stichting Mathematisch
+Centrum or CWI not be used in advertising or publicity pertaining to
+distribution of the software without specific, written prior
+permission.
+
+STICHTING MATHEMATISCH CENTRUM DISCLAIMS ALL WARRANTIES WITH REGARD TO
+THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
+FITNESS, IN NO EVENT SHALL STICHTING MATHEMATISCH CENTRUM BE LIABLE
+FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT
+OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -1,3 +1,21 @@
-# Temporary Holding Version
+# petitpy
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+petitpy is a small Python runtime for the browser and Node (developed as nanopython): written in Zig, with direct DOM access from Python through the `js` module, building on MicroPython, whose `.mpy` bytecode it shares. The wasm is about 333 KB (164 KB gzipped).
+
+```js
+import { loadPetitpy } from "petitpy";
+
+const py = await loadPetitpy();
+const { stdout, stderr, exitCode } = await py.run('print("hello from", 6 * 7)');
+```
+
+`loadPetitpy()` compiles `petitpy.wasm` once; pass `{ wasm }` (a URL, a `Response`, bytes or a `WebAssembly.Module`) to load it from elsewhere. Each `run(source, options)` gets a fresh instance:
+
+- `stdin`: text for `input()`.
+- `files`: extra files by path; modules under `lib/` are importable.
+- `argv`: `sys.argv[1:]`.
+- `onStdout`, `onStderr`: called per printed line, also after `run()` returns, for programs that keep running through JS callbacks.
+
+From Python, `import js` reaches the page: `js.document.getElementById("out").textContent = "hi"`.
+
+This is an alpha. The language is close to CPython (Unicode strings, `match`, floats, exception chaining) with MicroPython's limits: no arbitrary-precision integers in the browser build, dicts are not insertion-ordered, `upper()`/`lower()` are ASCII-only. See the [differences from CPython](https://petitpy.lab.abilian.com/differences/) and the [playground](https://petitpy.lab.abilian.com/play/demos/playground/).

package/index.d.ts

@@ -0,0 +1,30 @@
+export interface RunOptions {
+  /** Text read by input() and sys.stdin. */
+  stdin?: string;
+  /** Extra files, by path; put importable modules under "lib/". */
+  files?: Record<string, string | Uint8Array>;
+  /** Arguments after the script name (sys.argv[1:]). */
+  argv?: string[];
+  /** Called with each line printed to stdout, including after run() returns. */
+  onStdout?: (line: string) => void;
+  /** Called with each line printed to stderr. */
+  onStderr?: (line: string) => void;
+}
+
+export interface RunResult {
+  stdout: string;
+  stderr: string;
+  exitCode: number;
+  /** The live instance, for programs that keep running through JS callbacks. */
+  instance: WebAssembly.Instance;
+}
+
+export interface Petitpy {
+  module: WebAssembly.Module;
+  run(source: string, options?: RunOptions): Promise<RunResult>;
+}
+
+/** Compile petitpy.wasm once (default: the file shipped next to this module). */
+export function loadPetitpy(options?: {
+  wasm?: URL | string | Response | ArrayBuffer | ArrayBufferView | WebAssembly.Module;
+}): Promise<Petitpy>;

package/index.js

@@ -0,0 +1,72 @@
+// petitpy for the browser and Node: run Python source on the wasm build.
+//
+//   import { loadPetitpy } from "petitpy";
+//   const py = await loadPetitpy();
+//   const { stdout, stderr, exitCode } = await py.run('print("hello")');
+//
+// Each run gets a fresh instance of the compiled module, over a virtual
+// filesystem holding the program at /main.py and any `files` you pass
+// (put modules under "lib/" to import them). The instance stays alive
+// after run() returns, so a program that registers JS callbacks (DOM
+// events, timers through the `js` module) keeps running; their output
+// goes to onStdout / onStderr.
+
+import { WASI, File, Directory, OpenFile, PreopenDirectory, ConsoleStdout } from "@bjorn3/browser_wasi_shim";
+import { makeJsBridge } from "./js-bridge.js";
+import { addFile } from "./wasi-fs.js";
+
+const DEFAULT_WASM = new URL("./petitpy.wasm", import.meta.url);
+
+
+async function compile(wasm) {
+  if (wasm instanceof WebAssembly.Module) return wasm;
+  if (wasm instanceof ArrayBuffer || ArrayBuffer.isView(wasm)) return WebAssembly.compile(wasm);
+  const resp = wasm instanceof Response ? wasm : await fetch(wasm);
+  if (!resp.ok) throw new Error(`petitpy: fetching the wasm failed (${resp.status})`);
+  return WebAssembly.compileStreaming
+    ? WebAssembly.compileStreaming(resp)
+    : WebAssembly.compile(await resp.arrayBuffer());
+}
+
+/**
+ * Compile petitpy.wasm once; `wasm` is a URL, a Response, bytes or a
+ * WebAssembly.Module (default: the file next to this module).
+ */
+export async function loadPetitpy({ wasm = DEFAULT_WASM } = {}) {
+  const module = await compile(wasm);
+  const encoder = new TextEncoder();
+
+  async function run(source, { stdin = "", files = {}, argv = [], onStdout, onStderr } = {}) {
+    let stdout = "";
+    let stderr = "";
+    const fsMap = new Map([["main.py", new File(encoder.encode(source), { readonly: true })]]);
+    for (const [path, content] of Object.entries(files)) {
+      const bytes = typeof content === "string" ? encoder.encode(content) : content;
+      addFile(fsMap, path, new File(bytes, { readonly: true }), Directory);
+    }
+    const fds = [
+      new OpenFile(new File(encoder.encode(stdin), { readonly: true })),
+      ConsoleStdout.lineBuffered((line) => {
+        stdout += line + "\n";
+        onStdout?.(line);
+      }),
+      ConsoleStdout.lineBuffered((line) => {
+        stderr += line + "\n";
+        onStderr?.(line);
+      }),
+      new PreopenDirectory("/", fsMap),
+    ];
+    const wasi = new WASI(["petitpy", "/main.py", ...argv], ["PETITPY_LIB=/lib"], fds, { debug: false });
+    const bridge = makeJsBridge();
+    const instance = await WebAssembly.instantiate(module, {
+      wasi_snapshot_preview1: wasi.wasiImport,
+      env: bridge.imports,
+    });
+    bridge.attachMemory(instance.exports.memory);
+    bridge.attachExports(instance.exports);
+    const exitCode = wasi.start(instance);
+    return { stdout, stderr, exitCode, instance };
+  }
+
+  return { module, run };
+}

package/js-bridge.js

@@ -0,0 +1,197 @@
+// ADR-006 J3 — JS-side bridge.
+//
+// Maintains a handle table mapping wasm-side u32 IDs to JS object references.
+// Provides the imports object that nanopython.wasm expects under the
+// `nanopython_js` namespace alongside the WASI `wasi_snapshot_preview1`
+// imports. The Zig side declares the externs in js_bridge.zig with the
+// default `env` module-name convention; the playground loader merges them
+// into both `env` and `nanopython_js` namespaces so either resolution
+// path works depending on how the compiler emitted the wasm import.
+//
+// Handle 0 is reserved for null / undefined; allocation starts at 1.
+//
+// J4 — `this` binding for method calls. When `js_get_attr` resolves to a
+// function value, we store a {receiver, fn} bound-method record in the
+// handle table rather than the bare function. `js_call` then invokes via
+// `fn.apply(receiver, ...)` so `document.getElementById("x")` (and any
+// other method that depends on `this`) sees the correct receiver. Bare
+// functions (e.g. `js.parseInt`) are still called without a `this`.
+
+export function makeJsBridge() {
+  const handles = new Map();
+  let nextHandle = 1;
+
+  // Pre-populate handle 0 with null/undefined so a fresh `js_get_global`
+  // of a missing property returns 0 -> null (consistent with the Python
+  // proxy's __str__ → "undefined" path).
+  handles.set(0, null);
+
+  function newHandle(value) {
+    // Reuse handle 0 for null/undefined so cleanup doesn't have to
+    // double-track them.
+    if (value === null || value === undefined) return 0;
+    const h = nextHandle++;
+    handles.set(h, value);
+    return h;
+  }
+
+  function newBoundMethod(receiver, fn) {
+    const h = nextHandle++;
+    handles.set(h, { __bound: true, receiver, fn });
+    return h;
+  }
+
+  // Resolve a handle to the underlying JS value. Bound-method records
+  // unwrap to their `fn` — callers that need to invoke with the receiver
+  // (i.e. js_call) inspect the record directly; everywhere else (passing
+  // as argument, set_attr, to_string) the JS-visible value is the fn.
+  function valueOf(handle) {
+    const v = handles.get(handle);
+    if (v && typeof v === "object" && v.__bound === true) return v.fn;
+    return v;
+  }
+
+  function readMemString(memory, ptr, len) {
+    const bytes = new Uint8Array(memory.buffer, ptr, len);
+    return new TextDecoder().decode(bytes);
+  }
+
+  let memory; // bound after WebAssembly.instantiate.
+  let wasmExports; // bound after WebAssembly.instantiate (for export callbacks).
+
+  const imports = {
+    js_get_global(namePtr, nameLen) {
+      const name = readMemString(memory, namePtr, nameLen);
+      return newHandle(globalThis[name]);
+    },
+    js_get_attr(handle, namePtr, nameLen) {
+      const obj = valueOf(handle);
+      if (obj == null) return 0;
+      const name = readMemString(memory, namePtr, nameLen);
+      const v = obj[name];
+      // Functions get remembered with their receiver so `this` is bound
+      // correctly when called. Non-function values use a plain handle.
+      if (typeof v === "function") return newBoundMethod(obj, v);
+      return newHandle(v);
+    },
+    js_set_attr(handle, namePtr, nameLen, valueHandle) {
+      const obj = valueOf(handle);
+      if (obj == null) return;
+      const name = readMemString(memory, namePtr, nameLen);
+      obj[name] = valueOf(valueHandle);
+    },
+    js_call(handle, argsPtr, argsCount) {
+      const entry = handles.get(handle);
+      const argsView = new Uint32Array(memory.buffer, argsPtr, argsCount);
+      const args = Array.from(argsView).map((h) => valueOf(h));
+      if (entry && typeof entry === "object" && entry.__bound === true) {
+        return newHandle(entry.fn.apply(entry.receiver, args));
+      }
+      if (typeof entry !== "function") {
+        throw new Error(`js_call: handle ${handle} is not a function`);
+      }
+      return newHandle(entry(...args));
+    },
+    js_release(handle) {
+      if (handle === 0) return;
+      handles.delete(handle);
+    },
+    js_create_string(ptr, len) {
+      return newHandle(readMemString(memory, ptr, len));
+    },
+    js_create_int(value) {
+      return newHandle(value);
+    },
+    js_to_string_len(handle) {
+      const s = String(valueOf(handle));
+      return new TextEncoder().encode(s).length;
+    },
+    js_to_string(handle, outPtr, outMax) {
+      const s = String(valueOf(handle));
+      const bytes = new TextEncoder().encode(s);
+      const len = Math.min(bytes.length, outMax);
+      new Uint8Array(memory.buffer, outPtr, len).set(bytes.subarray(0, len));
+      return len;
+    },
+    js_to_int(handle) {
+      const v = valueOf(handle);
+      return v | 0;
+    },
+    js_bridge_present() {
+      return 1;
+    },
+    // J5a — Python registered a callable; mint a JS function that, when
+    // called, fires npy_dispatch_callback(id, args_ptr, args_count) back
+    // into wasm. The JS function's argument values are first allocated
+    // as bridge handles, then their handles are spilled into wasm memory
+    // as a u32 array on the wasm stack (via `__npy_alloc_arg_buf` if
+    // available; otherwise we accept a hard limit and use a scratch
+    // region from `npy_dispatch_alloc`/free pair). For the first cut
+    // we use a static scratch slab in wasm memory exposed by the runtime
+    // — but to keep the bridge JS self-contained we instead allocate a
+    // small Uint32Array attached to the wasm linear memory via a fresh
+    // `WebAssembly.Memory.grow`-free strategy: copy into a fixed offset
+    // in the existing memory's data segment that's set aside by the
+    // runtime. For now we cap at 8 args and use a JS-side TypedArray
+    // backed by wasm memory at a runtime-provided scratch ptr. To avoid
+    // the scratch-ptr lookup complexity for the J5a slice we use a
+    // simpler shape: we allocate args by writing into the existing
+    // bridge `handles` map and pass a synthetic ptr=0 with the args
+    // count = 0 when there are no args. With args > 0 we write to a
+    // freshly grown region. To stay simple, J5a supports zero-arg
+    // callbacks (the common `addEventListener("click", py_fn)`
+    // shape) — multi-arg event handlers will land with a Python-side
+    // event marshaler in a follow-up.
+    js_create_callback(callbackId) {
+      const fn = function (...args) {
+        if (!wasmExports || !wasmExports.npy_dispatch_callback) return undefined;
+        // Marshal JS args to bridge handles first.
+        const argHandles = args.map((a) => newHandle(a));
+        let resultHandle;
+        if (argHandles.length === 0) {
+          resultHandle = wasmExports.npy_dispatch_callback(callbackId, 0, 0);
+        } else {
+          // Stage the handle array into wasm linear memory using the
+          // MicroPython GC allocator (`m_malloc` is exported from the
+          // runtime). We don't free — the allocation is a tiny u32[] per
+          // dispatch and the runtime's GC reclaims it; trading a
+          // negligible leak for not having to export m_free here.
+          //
+          // Until this landed, the bridge probed for `malloc`/`free` (not
+          // exported by nanopython) and fell through to dropping args,
+          // which made Promise.then(cb) callbacks appear to never fire —
+          // the dispatch ran but Python's `cb` raised TypeError "missing
+          // 1 required argument" (the resolved value) and the dispatcher's
+          // broad `except Exception` swallowed it.
+          if (wasmExports.m_malloc) {
+            const ptr = wasmExports.m_malloc(argHandles.length * 4);
+            new Uint32Array(memory.buffer, ptr, argHandles.length).set(argHandles);
+            resultHandle = wasmExports.npy_dispatch_callback(callbackId, ptr, argHandles.length);
+          } else if (wasmExports.malloc && wasmExports.free) {
+            const ptr = wasmExports.malloc(argHandles.length * 4);
+            new Uint32Array(memory.buffer, ptr, argHandles.length).set(argHandles);
+            resultHandle = wasmExports.npy_dispatch_callback(callbackId, ptr, argHandles.length);
+            wasmExports.free(ptr);
+          } else {
+            // No allocator available — drop args. The Python callback
+            // receives zero proxies. addEventListener("click", fn) works
+            // (no args needed); event-object access requires an allocator.
+            resultHandle = wasmExports.npy_dispatch_callback(callbackId, 0, 0);
+          }
+        }
+        return valueOf(resultHandle);
+      };
+      return newHandle(fn);
+    },
+  };
+
+  function attachMemory(wasmMemory) {
+    memory = wasmMemory;
+  }
+
+  function attachExports(exports) {
+    wasmExports = exports;
+  }
+
+  return { imports, attachMemory, attachExports, handles };
+}

package/package.json

@@ -1,6 +1,21 @@
 {
   "name": "petitpy",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.8.0",
+  "description": "A small Python runtime for the browser: MicroPython-compatible, written in Zig, 333 KB of wasm with direct DOM access.",
+  "type": "module",
+  "main": "./index.js",
+  "types": "./index.d.ts",
+  "exports": {
+    ".": { "types": "./index.d.ts", "default": "./index.js" },
+    "./petitpy.wasm": "./petitpy.wasm",
+    "./js-bridge.js": "./js-bridge.js"
+  },
+  "files": ["index.js", "index.d.ts", "js-bridge.js", "wasi-fs.js", "petitpy.wasm", "README.md", "LICENSE"],
+  "dependencies": {
+    "@bjorn3/browser_wasi_shim": "^0.4.2"
+  },
+  "keywords": ["python", "micropython", "wasm", "webassembly", "interpreter", "browser"],
+  "license": "MIT AND PSF-2.0",
+  "homepage": "https://petitpy.lab.abilian.com/",
+  "repository": { "type": "git", "url": "https://github.com/abilian/petitpy" }
+}

package/wasi-fs.js

@@ -0,0 +1,17 @@
+// The browser WASI shim keys a directory's entries by name, so "lib/x.py"
+// needs a "lib" Directory holding "x.py"; a flat "lib/x.py" key is never
+// found. `Directory` is the shim's class, passed in so this module works
+// with the shim from a CDN (the pages) or from npm (the package).
+export function addFile(root, path, file, Directory) {
+  const parts = path.split("/").filter(Boolean);
+  let dir = root;
+  for (const name of parts.slice(0, -1)) {
+    let sub = dir.get(name);
+    if (!(sub instanceof Directory)) {
+      sub = new Directory(new Map());
+      dir.set(name, sub);
+    }
+    dir = sub.contents;
+  }
+  dir.set(parts[parts.length - 1], file);
+}