@volter/browser-python 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Volter Browser Substrate 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.

package/README.md

@@ -0,0 +1,14 @@
+# `@volter/browser-python`
+
+The Pyodide execution engine for Browser Substrate. It registers `python`,
+`python3`, `pip`, `pip3`, and `uvicorn` with the shared process host and keeps
+the browser workspace coherent across its worker boundary.
+
+Supported application paths include scripts, `python -c`, hash-resolved
+Micropip installs, static HTTP servers, Flask/WSGI, ASGI HTTP streaming and
+WebSockets, lifecycle events, SQLite file coherence, and routed subprocesses.
+Virtual servers use the same port and sandbox bridge as Node and WALI; they do
+not open a host-machine listener.
+
+Arbitrary Python socket listeners, editable/VCS installs, and direct wheel URLs
+are outside the current scope and fail explicitly.

package/dist/asgi-bridge.d.ts

@@ -0,0 +1,3 @@
+/** Python-side ASGI lifecycle, HTTP, streaming, and WebSocket adapter. */
+export declare const ASGI_BRIDGE: string;
+//# sourceMappingURL=asgi-bridge.d.ts.map

package/dist/asgi-bridge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"asgi-bridge.d.ts","sourceRoot":"","sources":["../src/asgi-bridge.ts"],"names":[],"mappings":"AAAA,0EAA0E;AAC1E,eAAO,MAAM,WAAW,QAgTvB,CAAC"}

package/dist/asgi-bridge.js

@@ -0,0 +1,307 @@
+/** Python-side ASGI lifecycle, HTTP, streaming, and WebSocket adapter. */
+export const ASGI_BRIDGE = String.raw `
+import asyncio, base64, json
+from urllib.parse import urlsplit
+
+async def __browser_runtime_start_asgi_lifespan():
+    queue = asyncio.Queue()
+    ready = asyncio.Event()
+    shutdown_ready = asyncio.Event()
+    outcome = {"startup_error": None, "shutdown_error": None, "responded": False, "unsupported": False}
+    lifespan_state = {}
+
+    async def receive():
+        return await queue.get()
+
+    async def send(message):
+        outcome["responded"] = True
+        kind = message.get("type")
+        if kind == "lifespan.startup.complete":
+            ready.set()
+        elif kind == "lifespan.startup.failed":
+            outcome["startup_error"] = str(message.get("message", "ASGI lifespan startup failed"))
+            ready.set()
+        elif kind == "lifespan.shutdown.complete":
+            shutdown_ready.set()
+        elif kind == "lifespan.shutdown.failed":
+            outcome["shutdown_error"] = str(message.get("message", "ASGI lifespan shutdown failed"))
+            shutdown_ready.set()
+
+    async def run():
+        try:
+            await globals()["__browser_runtime_asgi_app"](
+                {"type": "lifespan", "asgi": {"version": "3.0", "spec_version": "2.0"}, "state": lifespan_state},
+                receive,
+                send,
+            )
+        except BaseException as error:
+            if outcome["responded"]:
+                outcome["startup_error"] = str(error)
+            else:
+                outcome["unsupported"] = True
+            ready.set()
+            shutdown_ready.set()
+
+    task = asyncio.create_task(run())
+    globals()["__browser_runtime_asgi_lifespan_task"] = task
+    globals()["__browser_runtime_asgi_lifespan_queue"] = queue
+    globals()["__browser_runtime_asgi_lifespan_outcome"] = outcome
+    globals()["__browser_runtime_asgi_lifespan_shutdown_ready"] = shutdown_ready
+    globals()["__browser_runtime_asgi_lifespan_state"] = lifespan_state
+    await queue.put({"type": "lifespan.startup"})
+    try:
+        await asyncio.wait_for(ready.wait(), timeout=5)
+    except TimeoutError:
+        task.cancel()
+        raise RuntimeError("ASGI lifespan startup timed out")
+    if outcome["startup_error"] is not None:
+        task.cancel()
+        raise RuntimeError(outcome["startup_error"])
+
+async def __browser_runtime_stop_asgi_lifespan():
+    task = globals().get("__browser_runtime_asgi_lifespan_task")
+    queue = globals().get("__browser_runtime_asgi_lifespan_queue")
+    outcome = globals().get("__browser_runtime_asgi_lifespan_outcome", {})
+    shutdown_ready = globals().get("__browser_runtime_asgi_lifespan_shutdown_ready")
+    if task is None or queue is None or shutdown_ready is None or outcome.get("unsupported") or task.done():
+        return
+    await queue.put({"type": "lifespan.shutdown"})
+    try:
+        await asyncio.wait_for(shutdown_ready.wait(), timeout=5)
+    except TimeoutError:
+        task.cancel()
+        raise RuntimeError("ASGI lifespan shutdown timed out")
+    if outcome.get("shutdown_error") is not None:
+        task.cancel()
+        raise RuntimeError(outcome["shutdown_error"])
+    await asyncio.wait_for(task, timeout=5)
+
+__browser_runtime_asgi_sockets = {}
+
+async def __browser_runtime_stop_asgi_websockets():
+    sockets = list(globals()["__browser_runtime_asgi_sockets"].values())
+    if not sockets:
+        return
+    for socket in sockets:
+        await socket["queue"].put({"type": "websocket.disconnect", "code": 1001, "reason": "Server shutdown"})
+    tasks = [socket["task"] for socket in sockets]
+    try:
+        await asyncio.wait_for(asyncio.gather(*tasks, return_exceptions=True), timeout=2)
+    except TimeoutError:
+        for task in tasks:
+            if not task.done():
+                task.cancel()
+
+async def __browser_runtime_open_asgi_websocket(payload_json):
+    payload = json.loads(payload_json)
+    connection_id = int(payload["connectionId"])
+    parsed = urlsplit(payload["path"])
+    protocols = [str(value) for value in payload.get("protocols", [])]
+    queue = asyncio.Queue()
+    state = {"accepted": False, "closed": False}
+
+    async def receive():
+        return await queue.get()
+
+    async def send(message):
+        kind = message.get("type")
+        if kind == "websocket.accept":
+            if state["accepted"] or state["closed"]:
+                raise RuntimeError("ASGI WebSocket accepted more than once")
+            state["accepted"] = True
+            globals()["__browser_runtime_asgi_websocket_callback"](json.dumps({
+                "type": "opened",
+                "connectionId": connection_id,
+                "protocol": str(message.get("subprotocol") or ""),
+            }))
+        elif kind == "websocket.send":
+            if not state["accepted"] or state["closed"]:
+                raise RuntimeError("ASGI WebSocket sent data before accept or after close")
+            if message.get("bytes") is not None:
+                frame = {
+                    "type": "message",
+                    "connectionId": connection_id,
+                    "kind": "binary",
+                    "base64": base64.b64encode(bytes(message["bytes"])).decode("ascii"),
+                }
+            else:
+                frame = {
+                    "type": "message",
+                    "connectionId": connection_id,
+                    "kind": "text",
+                    "text": str(message.get("text", "")),
+                }
+            globals()["__browser_runtime_asgi_websocket_callback"](json.dumps(frame))
+        elif kind == "websocket.close":
+            if state["closed"]:
+                return
+            state["closed"] = True
+            globals()["__browser_runtime_asgi_websocket_callback"](json.dumps({
+                "type": "close",
+                "connectionId": connection_id,
+                "code": int(message.get("code", 1000)),
+                "reason": str(message.get("reason", "")),
+                "clean": True,
+            }))
+
+    async def run():
+        try:
+            scope = {
+                "type": "websocket",
+                "asgi": {"version": "3.0", "spec_version": "2.3"},
+                "scheme": "ws",
+                "path": parsed.path,
+                "raw_path": parsed.path.encode("utf-8"),
+                "query_string": parsed.query.encode("ascii"),
+                "root_path": "",
+                "headers": [],
+                "server": ("localhost", int(globals()["__browser_runtime_asgi_port"])),
+                "client": ("127.0.0.1", 0),
+                "subprotocols": protocols,
+                "state": dict(globals().get("__browser_runtime_asgi_lifespan_state", {})),
+            }
+            await globals()["__browser_runtime_asgi_app"](scope, receive, send)
+        except BaseException as error:
+            globals()["__browser_runtime_asgi_websocket_callback"](json.dumps({
+                "type": "error",
+                "connectionId": connection_id,
+                "error": str(error),
+            }))
+            if not state["closed"]:
+                state["closed"] = True
+                globals()["__browser_runtime_asgi_websocket_callback"](json.dumps({
+                    "type": "close",
+                    "connectionId": connection_id,
+                    "code": 1011,
+                    "reason": "Python ASGI WebSocket failed",
+                    "clean": False,
+                }))
+        finally:
+            if not state["closed"]:
+                state["closed"] = True
+                globals()["__browser_runtime_asgi_websocket_callback"](json.dumps({
+                    "type": "close",
+                    "connectionId": connection_id,
+                    "code": 1000,
+                    "reason": "",
+                    "clean": True,
+                }))
+            globals()["__browser_runtime_asgi_sockets"].pop(connection_id, None)
+
+    task = asyncio.create_task(run())
+    globals()["__browser_runtime_asgi_sockets"][connection_id] = {"queue": queue, "task": task}
+    await queue.put({"type": "websocket.connect"})
+    await asyncio.sleep(0)
+
+async def __browser_runtime_asgi_websocket_event(payload_json):
+    payload = json.loads(payload_json)
+    connection_id = int(payload["connectionId"])
+    socket = globals()["__browser_runtime_asgi_sockets"].get(connection_id)
+    if socket is None:
+        return
+    if payload["type"] == "websocket-message":
+        data = payload["data"]
+        if data["kind"] == "binary":
+            event = {"type": "websocket.receive", "bytes": base64.b64decode(data.get("base64", ""))}
+        else:
+            event = {"type": "websocket.receive", "text": str(data.get("text", ""))}
+    else:
+        event = {
+            "type": "websocket.disconnect",
+            "code": int(payload.get("code", 1000)),
+            "reason": str(payload.get("reason", "")),
+        }
+    await socket["queue"].put(event)
+    await asyncio.sleep(0)
+
+def __browser_runtime_asgi_headers(response_start):
+    response_headers = {}
+    for raw_name, raw_value in response_start.get("headers", []):
+        name = bytes(raw_name).decode("latin-1")
+        value = bytes(raw_value).decode("latin-1")
+        if name in response_headers:
+            existing = response_headers[name]
+            response_headers[name] = existing + [value] if isinstance(existing, list) else [existing, value]
+        else:
+            response_headers[name] = value
+    return response_headers
+
+async def __browser_runtime_handle_asgi(payload_json, streaming=False):
+    payload = json.loads(payload_json)
+    parsed = urlsplit(payload["url"])
+    body = base64.b64decode(payload.get("bodyBase64", ""))
+    request_headers = [
+        (str(name).lower().encode("latin-1"), str(value).encode("latin-1"))
+        for name, value in payload.get("headers", {}).items()
+    ]
+    scope = {
+        "type": "http",
+        "asgi": {"version": "3.0", "spec_version": "2.3"},
+        "http_version": "1.1",
+        "method": payload["method"],
+        "scheme": "http",
+        "path": parsed.path,
+        "raw_path": parsed.path.encode("utf-8"),
+        "query_string": parsed.query.encode("ascii"),
+        "root_path": "",
+        "headers": request_headers,
+        "server": ("localhost", int(globals()["__browser_runtime_asgi_port"])),
+        "client": ("127.0.0.1", 0),
+        "state": dict(globals().get("__browser_runtime_asgi_lifespan_state", {})),
+    }
+    received = False
+    response_start = None
+    response_chunks = []
+    stream_started = False
+
+    def start_stream():
+        nonlocal response_start, stream_started
+        if stream_started:
+            return
+        response_start = response_start or {"status": 500, "headers": []}
+        globals()["__browser_runtime_asgi_stream_callback"](json.dumps({
+            "type": "start",
+            "statusCode": int(response_start["status"]),
+            "statusMessage": "",
+            "headers": __browser_runtime_asgi_headers(response_start),
+        }))
+        stream_started = True
+
+    async def receive():
+        nonlocal received
+        if received:
+            return {"type": "http.disconnect"}
+        received = True
+        return {"type": "http.request", "body": body, "more_body": False}
+
+    async def send(message):
+        nonlocal response_start
+        if message["type"] == "http.response.start":
+            response_start = message
+            if streaming:
+                start_stream()
+        elif message["type"] == "http.response.body":
+            chunk = bytes(message.get("body", b""))
+            if streaming:
+                start_stream()
+                if chunk:
+                    globals()["__browser_runtime_asgi_stream_callback"](json.dumps({
+                        "type": "chunk",
+                        "bodyBase64": base64.b64encode(chunk).decode("ascii"),
+                    }))
+            else:
+                response_chunks.append(chunk)
+
+    await globals()["__browser_runtime_asgi_app"](scope, receive, send)
+    response_start = response_start or {"status": 500, "headers": []}
+    if streaming:
+        start_stream()
+        return "{}"
+    return json.dumps({
+        "statusCode": int(response_start["status"]),
+        "statusMessage": "",
+        "headers": __browser_runtime_asgi_headers(response_start),
+        "bodyBase64": base64.b64encode(b"".join(response_chunks)).decode("ascii"),
+    })
+`;
+//# sourceMappingURL=asgi-bridge.js.map

package/dist/asgi-bridge.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"asgi-bridge.js","sourceRoot":"","sources":["../src/asgi-bridge.ts"],"names":[],"mappings":"AAAA,0EAA0E;AAC1E,MAAM,CAAC,MAAM,WAAW,GAAG,MAAM,CAAC,GAAG,CAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAgTpC,CAAC"}

package/dist/command.d.ts

@@ -0,0 +1,20 @@
+import type { BrowserFileSystem } from "@volter/browser-runtime/browser-filesystem.js";
+import type { BrowserProcessResult, BrowserProcessRunOptions } from "@volter/browser-runtime/browser-process.js";
+import type { PythonServerAttachment } from "./protocol.js";
+export interface BrowserPythonCommandOptions {
+    cwd?: string;
+    env?: Readonly<Record<string, string>>;
+    server: PythonServerAttachment;
+    onFilesystemCommit?(filesystem: BrowserFileSystem): void | Promise<void>;
+}
+/** Runs CPython/Pyodide in a worker against the shared project and process host. */
+export declare class BrowserPythonCommand {
+    private readonly filesystem;
+    private readonly options;
+    private filesystemCommitTail;
+    constructor(filesystem: BrowserFileSystem, options: BrowserPythonCommandOptions);
+    run: (argv: readonly string[], options?: BrowserProcessRunOptions) => Promise<BrowserProcessResult>;
+    private applyResult;
+    private persistFilesystem;
+}
+//# sourceMappingURL=command.d.ts.map

package/dist/command.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"command.d.ts","sourceRoot":"","sources":["../src/command.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAA6B,MAAM,+CAA+C,CAAC;AAKlH,OAAO,KAAK,EACV,oBAAoB,EACpB,wBAAwB,EACzB,MAAM,4CAA4C,CAAC;AACpD,OAAO,KAAK,EAAoB,sBAAsB,EAAuB,MAAM,eAAe,CAAC;AAUnG,MAAM,WAAW,2BAA2B;IAC1C,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACvC,MAAM,EAAE,sBAAsB,CAAC;IAC/B,kBAAkB,CAAC,CAAC,UAAU,EAAE,iBAAiB,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1E;AAED,oFAAoF;AACpF,qBAAa,oBAAoB;IAI7B,OAAO,CAAC,QAAQ,CAAC,UAAU;IAC3B,OAAO,CAAC,QAAQ,CAAC,OAAO;IAJ1B,OAAO,CAAC,oBAAoB,CAAoC;gBAG7C,UAAU,EAAE,iBAAiB,EAC7B,OAAO,EAAE,2BAA2B;IAGvD,GAAG,GAAU,MAAM,SAAS,MAAM,EAAE,EAAE,UAAS,wBAA6B,KAAG,OAAO,CAAC,oBAAoB,CAAC,CAyF1G;YAEY,WAAW;YAaX,iBAAiB;CAKhC"}

package/dist/command.js

@@ -0,0 +1,154 @@
+import { applyProcessFilesystemPatch, createProcessFilesystemPatch, } from "@volter/browser-runtime/browser-process-filesystem.js";
+import { createBrowserFileLockChannel, sharedBrowserFileLockCoordinator, } from "@volter/browser-runtime/browser-file-locks.js";
+import { createBrowserFileCoherenceChannel, sharedBrowserFileCoherenceCoordinator, } from "@volter/browser-runtime/browser-file-coherence.js";
+/** Runs CPython/Pyodide in a worker against the shared project and process host. */
+export class BrowserPythonCommand {
+    filesystem;
+    options;
+    filesystemCommitTail = Promise.resolve();
+    constructor(filesystem, options) {
+        this.filesystem = filesystem;
+        this.options = options;
+    }
+    run = async (argv, options = {}) => {
+        if (options.signal?.aborted)
+            return Promise.resolve({ stdout: "", stderr: "", exitCode: 130 });
+        const stdin = await collectStdin(options);
+        if (options.signal?.aborted)
+            return { stdout: "", stderr: "", exitCode: 130 };
+        const worker = new Worker(new URL("./worker.js", import.meta.url), { type: "module", name: "browser-python" });
+        const channel = new MessageChannel();
+        const releaseServer = this.options.server.attach(channel.port1);
+        const lockOwner = `python:${crypto.randomUUID()}`;
+        const lockChannel = createBrowserFileLockChannel();
+        const releaseFileLocks = sharedBrowserFileLockCoordinator.attach(lockChannel.server, lockOwner);
+        const coherenceChannel = createBrowserFileCoherenceChannel();
+        const releaseFileCoherence = sharedBrowserFileCoherenceCoordinator.attach(coherenceChannel.server, this.filesystem, () => this.persistFilesystem());
+        const before = this.filesystem.toSnapshot();
+        let synchronized = before;
+        let commitQueue = Promise.resolve();
+        let stdout = "";
+        let stderr = "";
+        return new Promise((resolve) => {
+            let finished = false;
+            let abortTimeout;
+            const finish = (result) => {
+                if (finished)
+                    return;
+                finished = true;
+                if (abortTimeout !== undefined)
+                    clearTimeout(abortTimeout);
+                options.signal?.removeEventListener("abort", abort);
+                releaseServer();
+                worker.terminate();
+                releaseFileCoherence();
+                releaseFileLocks();
+                resolve(result);
+            };
+            const abort = () => {
+                worker.postMessage({ type: "shutdown" });
+                abortTimeout = setTimeout(() => finish({ stdout, stderr, exitCode: 130 }), 12_000);
+            };
+            options.signal?.addEventListener("abort", abort, { once: true });
+            worker.onmessage = (event) => {
+                const message = event.data;
+                if (message.type === "stdout") {
+                    stdout += message.chunk;
+                    options.onStdout?.(message.chunk);
+                    return;
+                }
+                if (message.type === "stderr") {
+                    stderr += message.chunk;
+                    options.onStderr?.(message.chunk);
+                    return;
+                }
+                if (!("filesystem" in message))
+                    return;
+                const previous = synchronized;
+                synchronized = message.filesystem;
+                commitQueue = commitQueue.then(() => this.applyResult(previous, message.filesystem));
+                if (message.type === "commit") {
+                    void commitQueue.then(() => worker.postMessage({ type: "commit-ack", commitId: message.commitId }), (cause) => worker.postMessage({
+                        type: "commit-ack",
+                        commitId: message.commitId,
+                        error: cause instanceof Error ? cause.message : String(cause),
+                    }));
+                    return;
+                }
+                if (message.type !== "result")
+                    return;
+                void commitQueue.then(() => {
+                    if (!finished)
+                        finish({
+                            stdout,
+                            stderr: message.error ? `${stderr}${message.error}\n` : stderr,
+                            exitCode: message.exitCode,
+                        });
+                }, (error) => finish({ stdout, stderr: `${stderr}${String(error)}\n`, exitCode: 1 }));
+            };
+            worker.onerror = (event) => finish({ stdout, stderr: `${stderr}${event.message}\n`, exitCode: 1 });
+            const request = {
+                type: "run",
+                argv: [...argv],
+                cwd: options.cwd ?? this.options.cwd ?? "/workspace",
+                env: { ...this.options.env, ...options.env },
+                filesystem: before,
+                stdinBase64: encodeBase64(stdin),
+                serverPort: channel.port2,
+                fileLocks: { channel: lockChannel.client, owner: lockOwner },
+                fileCoherence: coherenceChannel.client,
+            };
+            worker.postMessage(request, [
+                request.serverPort,
+                request.fileLocks.channel.port,
+                request.fileCoherence.port,
+            ]);
+        });
+    };
+    async applyResult(before, after) {
+        const commit = this.filesystemCommitTail.then(async () => {
+            applyProcessFilesystemPatch(this.filesystem, createProcessFilesystemPatch(before, after), before);
+            await this.options.onFilesystemCommit?.(this.filesystem);
+        });
+        this.filesystemCommitTail = commit.catch(() => undefined);
+        await commit;
+    }
+    async persistFilesystem() {
+        const commit = this.filesystemCommitTail.then(() => this.options.onFilesystemCommit?.(this.filesystem));
+        this.filesystemCommitTail = commit.then(() => undefined, () => undefined);
+        await commit;
+    }
+}
+async function collectStdin(options) {
+    const chunks = [];
+    let length = 0;
+    if (options.stdin) {
+        const chunk = new TextEncoder().encode(options.stdin);
+        chunks.push(chunk);
+        length += chunk.byteLength;
+    }
+    if (options.stdinStream) {
+        for await (const source of options.stdinStream) {
+            const chunk = source.slice();
+            length += chunk.byteLength;
+            if (length > 16 * 1024 * 1024)
+                throw new Error("Python stdin exceeds 16 MiB.");
+            chunks.push(chunk);
+        }
+    }
+    const result = new Uint8Array(length);
+    let offset = 0;
+    for (const chunk of chunks) {
+        result.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    return result;
+}
+function encodeBase64(value) {
+    let binary = "";
+    for (let offset = 0; offset < value.byteLength; offset += 0x8000) {
+        binary += String.fromCharCode(...value.subarray(offset, offset + 0x8000));
+    }
+    return btoa(binary);
+}
+//# sourceMappingURL=command.js.map

package/dist/command.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"command.js","sourceRoot":"","sources":["../src/command.ts"],"names":[],"mappings":"AACA,OAAO,EACL,2BAA2B,EAC3B,4BAA4B,GAC7B,MAAM,uDAAuD,CAAC;AAM/D,OAAO,EACL,4BAA4B,EAC5B,gCAAgC,GACjC,MAAM,+CAA+C,CAAC;AACvD,OAAO,EACL,iCAAiC,EACjC,qCAAqC,GACtC,MAAM,mDAAmD,CAAC;AAS3D,oFAAoF;AACpF,MAAM,OAAO,oBAAoB;IAIZ;IACA;IAJX,oBAAoB,GAAkB,OAAO,CAAC,OAAO,EAAE,CAAC;IAEhE,YACmB,UAA6B,EAC7B,OAAoC;QADpC,eAAU,GAAV,UAAU,CAAmB;QAC7B,YAAO,GAAP,OAAO,CAA6B;IACpD,CAAC;IAEJ,GAAG,GAAG,KAAK,EAAE,IAAuB,EAAE,UAAoC,EAAE,EAAiC,EAAE;QAC7G,IAAI,OAAO,CAAC,MAAM,EAAE,OAAO;YAAE,OAAO,OAAO,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,QAAQ,EAAE,GAAG,EAAE,CAAC,CAAC;QAC/F,MAAM,KAAK,GAAG,MAAM,YAAY,CAAC,OAAO,CAAC,CAAC;QAC1C,IAAI,OAAO,CAAC,MAAM,EAAE,OAAO;YAAE,OAAO,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,QAAQ,EAAE,GAAG,EAAE,CAAC;QAC9E,MAAM,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,GAAG,CAAC,aAAa,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,gBAAgB,EAAE,CAAC,CAAC;QAC/G,MAAM,OAAO,GAAG,IAAI,cAAc,EAAE,CAAC;QACrC,MAAM,aAAa,GAAG,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;QAChE,MAAM,SAAS,GAAG,UAAU,MAAM,CAAC,UAAU,EAAE,EAAE,CAAC;QAClD,MAAM,WAAW,GAAG,4BAA4B,EAAE,CAAC;QACnD,MAAM,gBAAgB,GAAG,gCAAgC,CAAC,MAAM,CAAC,WAAW,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;QAChG,MAAM,gBAAgB,GAAG,iCAAiC,EAAE,CAAC;QAC7D,MAAM,oBAAoB,GAAG,qCAAqC,CAAC,MAAM,CACvE,gBAAgB,CAAC,MAAM,EACvB,IAAI,CAAC,UAAU,EACf,GAAG,EAAE,CAAC,IAAI,CAAC,iBAAiB,EAAE,CAC/B,CAAC;QACF,MAAM,MAAM,GAAG,IAAI,CAAC,UAAU,CAAC,UAAU,EAAE,CAAC;QAC5C,IAAI,YAAY,GAAG,MAAM,CAAC;QAC1B,IAAI,WAAW,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC;QACpC,IAAI,MAAM,GAAG,EAAE,CAAC;QAChB,IAAI,MAAM,GAAG,EAAE,CAAC;QAChB,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE;YAC7B,IAAI,QAAQ,GAAG,KAAK,CAAC;YACrB,IAAI,YAAuD,CAAC;YAC5D,MAAM,MAAM,GAAG,CAAC,MAA4B,EAAQ,EAAE;gBACpD,IAAI,QAAQ;oBAAE,OAAO;gBACrB,QAAQ,GAAG,IAAI,CAAC;gBAChB,IAAI,YAAY,KAAK,SAAS;oBAAE,YAAY,CAAC,YAAY,CAAC,CAAC;gBAC3D,OAAO,CAAC,MAAM,EAAE,mBAAmB,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;gBACpD,aAAa,EAAE,CAAC;gBAChB,MAAM,CAAC,SAAS,EAAE,CAAC;gBACnB,oBAAoB,EAAE,CAAC;gBACvB,gBAAgB,EAAE,CAAC;gBACnB,OAAO,CAAC,MAAM,CAAC,CAAC;YAClB,CAAC,CAAC;YACF,MAAM,KAAK,GAAG,GAAS,EAAE;gBACvB,MAAM,CAAC,WAAW,CAAC,EAAE,IAAI,EAAE,UAAU,EAAE,CAAC,CAAC;gBACzC,YAAY,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,GAAG,EAAE,CAAC,EAAE,MAAM,CAAC,CAAC;YACrF,CAAC,CAAC;YACF,OAAO,CAAC,MAAM,EAAE,gBAAgB,CAAC,OAAO,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;YACjE,MAAM,CAAC,SAAS,GAAG,CAAC,KAAwC,EAAQ,EAAE;gBACpE,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,CAAC;gBAC3B,IAAI,OAAO,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;oBAAC,MAAM,IAAI,OAAO,CAAC,KAAK,CAAC;oBAAC,OAAO,CAAC,QAAQ,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;oBAAC,OAAO;gBAAC,CAAC;gBACtG,IAAI,OAAO,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;oBAAC,MAAM,IAAI,OAAO,CAAC,KAAK,CAAC;oBAAC,OAAO,CAAC,QAAQ,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;oBAAC,OAAO;gBAAC,CAAC;gBACtG,IAAI,CAAC,CAAC,YAAY,IAAI,OAAO,CAAC;oBAAE,OAAO;gBACvC,MAAM,QAAQ,GAAG,YAAY,CAAC;gBAC9B,YAAY,GAAG,OAAO,CAAC,UAAU,CAAC;gBAClC,WAAW,GAAG,WAAW,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,WAAW,CAAC,QAAQ,EAAE,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC;gBACrF,IAAI,OAAO,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;oBAC9B,KAAK,WAAW,CAAC,IAAI,CACnB,GAAG,EAAE,CAAC,MAAM,CAAC,WAAW,CAAC,EAAE,IAAI,EAAE,YAAY,EAAE,QAAQ,EAAE,OAAO,CAAC,QAAQ,EAAE,CAAC,EAC5E,CAAC,KAAK,EAAE,EAAE,CAAC,MAAM,CAAC,WAAW,CAAC;wBAC5B,IAAI,EAAE,YAAY;wBAClB,QAAQ,EAAE,OAAO,CAAC,QAAQ;wBAC1B,KAAK,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC;qBAC9D,CAAC,CACH,CAAC;oBACF,OAAO;gBACT,CAAC;gBACD,IAAI,OAAO,CAAC,IAAI,KAAK,QAAQ;oBAAE,OAAO;gBACtC,KAAK,WAAW,CAAC,IAAI,CACnB,GAAG,EAAE;oBACH,IAAI,CAAC,QAAQ;wBAAE,MAAM,CAAC;4BACpB,MAAM;4BACN,MAAM,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,MAAM,GAAG,OAAO,CAAC,KAAK,IAAI,CAAC,CAAC,CAAC,MAAM;4BAC9D,QAAQ,EAAE,OAAO,CAAC,QAAQ;yBAC3B,CAAC,CAAC;gBACL,CAAC,EACD,CAAC,KAAK,EAAE,EAAE,CAAC,MAAM,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,GAAG,MAAM,CAAC,KAAK,CAAC,IAAI,EAAE,QAAQ,EAAE,CAAC,EAAE,CAAC,CAClF,CAAC;YACJ,CAAC,CAAC;YACF,MAAM,CAAC,OAAO,GAAG,CAAC,KAAK,EAAQ,EAAE,CAAC,MAAM,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,GAAG,KAAK,CAAC,OAAO,IAAI,EAAE,QAAQ,EAAE,CAAC,EAAE,CAAC,CAAC;YACzG,MAAM,OAAO,GAAqB;gBAChC,IAAI,EAAE,KAAK;gBACX,IAAI,EAAE,CAAC,GAAG,IAAI,CAAC;gBACf,GAAG,EAAE,OAAO,CAAC,GAAG,IAAI,IAAI,CAAC,OAAO,CAAC,GAAG,IAAI,YAAY;gBACpD,GAAG,EAAE,EAAE,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,GAAG,OAAO,CAAC,GAAG,EAAE;gBAC5C,UAAU,EAAE,MAAM;gBAClB,WAAW,EAAE,YAAY,CAAC,KAAK,CAAC;gBAChC,UAAU,EAAE,OAAO,CAAC,KAAK;gBACzB,SAAS,EAAE,EAAE,OAAO,EAAE,WAAW,CAAC,MAAM,EAAE,KAAK,EAAE,SAAS,EAAE;gBAC5D,aAAa,EAAE,gBAAgB,CAAC,MAAM;aACvC,CAAC;YACF,MAAM,CAAC,WAAW,CAAC,OAAO,EAAE;gBAC1B,OAAO,CAAC,UAAU;gBAClB,OAAO,CAAC,SAAS,CAAC,OAAO,CAAC,IAAI;gBAC9B,OAAO,CAAC,aAAa,CAAC,IAAI;aAC3B,CAAC,CAAC;QACL,CAAC,CAAC,CAAC;IACL,CAAC,CAAC;IAEM,KAAK,CAAC,WAAW,CAAC,MAAiC,EAAE,KAAgC;QAC3F,MAAM,MAAM,GAAG,IAAI,CAAC,oBAAoB,CAAC,IAAI,CAAC,KAAK,IAAI,EAAE;YACvD,2BAA2B,CACzB,IAAI,CAAC,UAAU,EACf,4BAA4B,CAAC,MAAM,EAAE,KAAK,CAAC,EAC3C,MAAM,CACP,CAAC;YACF,MAAM,IAAI,CAAC,OAAO,CAAC,kBAAkB,EAAE,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;QAC3D,CAAC,CAAC,CAAC;QACH,IAAI,CAAC,oBAAoB,GAAG,MAAM,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;QAC1D,MAAM,MAAM,CAAC;IACf,CAAC;IAEO,KAAK,CAAC,iBAAiB;QAC7B,MAAM,MAAM,GAAG,IAAI,CAAC,oBAAoB,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,OAAO,CAAC,kBAAkB,EAAE,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC;QACxG,IAAI,CAAC,oBAAoB,GAAG,MAAM,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,SAAS,EAAE,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;QAC1E,MAAM,MAAM,CAAC;IACf,CAAC;CACF;AAED,KAAK,UAAU,YAAY,CAAC,OAAiC;IAC3D,MAAM,MAAM,GAAiB,EAAE,CAAC;IAChC,IAAI,MAAM,GAAG,CAAC,CAAC;IACf,IAAI,OAAO,CAAC,KAAK,EAAE,CAAC;QAClB,MAAM,KAAK,GAAG,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;QACtD,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACnB,MAAM,IAAI,KAAK,CAAC,UAAU,CAAC;IAC7B,CAAC;IACD,IAAI,OAAO,CAAC,WAAW,EAAE,CAAC;QACxB,IAAI,KAAK,EAAE,MAAM,MAAM,IAAI,OAAO,CAAC,WAAW,EAAE,CAAC;YAC/C,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,EAAE,CAAC;YAC7B,MAAM,IAAI,KAAK,CAAC,UAAU,CAAC;YAC3B,IAAI,MAAM,GAAG,EAAE,GAAG,IAAI,GAAG,IAAI;gBAAE,MAAM,IAAI,KAAK,CAAC,8BAA8B,CAAC,CAAC;YAC/E,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACrB,CAAC;IACH,CAAC;IACD,MAAM,MAAM,GAAG,IAAI,UAAU,CAAC,MAAM,CAAC,CAAC;IACtC,IAAI,MAAM,GAAG,CAAC,CAAC;IACf,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QAAC,MAAM,CAAC,GAAG,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;QAAC,MAAM,IAAI,KAAK,CAAC,UAAU,CAAC;IAAC,CAAC;IACtF,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,SAAS,YAAY,CAAC,KAAiB;IACrC,IAAI,MAAM,GAAG,EAAE,CAAC;IAChB,KAAK,IAAI,MAAM,GAAG,CAAC,EAAE,MAAM,GAAG,KAAK,CAAC,UAAU,EAAE,MAAM,IAAI,MAAM,EAAE,CAAC;QACjE,MAAM,IAAI,MAAM,CAAC,YAAY,CAAC,GAAG,KAAK,CAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,CAAC,CAAC;IAC5E,CAAC;IACD,OAAO,IAAI,CAAC,MAAM,CAAC,CAAC;AACtB,CAAC"}

package/dist/filesystem.d.ts

@@ -0,0 +1,9 @@
+import type { BrowserFileSystemSnapshot } from "@volter/browser-runtime/browser-filesystem.js";
+import { type PyodideFileSystem } from "./pyodide-runtime.js";
+export declare function restorePythonSnapshot(fs: PyodideFileSystem, value: BrowserFileSystemSnapshot): void;
+export declare function snapshotPythonFilesystem(fs: PyodideFileSystem, original: BrowserFileSystemSnapshot): BrowserFileSystemSnapshot;
+export declare function absolutePythonPath(path: string, cwd: string): string;
+export declare function pythonBasename(path: string): string;
+export declare function encodeBase64(value: Uint8Array): string;
+export declare function decodeBase64(value: string): Uint8Array;
+//# sourceMappingURL=filesystem.d.ts.map

package/dist/filesystem.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"filesystem.d.ts","sourceRoot":"","sources":["../src/filesystem.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,+CAA+C,CAAC;AAE/F,OAAO,EAAoB,KAAK,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAEhF,wBAAgB,qBAAqB,CAAC,EAAE,EAAE,iBAAiB,EAAE,KAAK,EAAE,yBAAyB,GAAG,IAAI,CAkBnG;AAED,wBAAgB,wBAAwB,CAAC,EAAE,EAAE,iBAAiB,EAAE,QAAQ,EAAE,yBAAyB,GAAG,yBAAyB,CAM9H;AAED,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAQpE;AAED,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAkD;AAEtG,wBAAgB,YAAY,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,CAMtD;AAED,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,UAAU,CAGtD"}

package/dist/filesystem.js

@@ -0,0 +1,96 @@
+import { PYTHON_WORKSPACE } from "./pyodide-runtime.js";
+export function restorePythonSnapshot(fs, value) {
+    clearTree(fs, PYTHON_WORKSPACE);
+    fs.mkdirTree(PYTHON_WORKSPACE);
+    const entries = value.files.slice().sort((left, right) => depth(left.path) - depth(right.path));
+    for (const entry of entries) {
+        if (entry.path !== PYTHON_WORKSPACE && !entry.path.startsWith(`${PYTHON_WORKSPACE}/`))
+            continue;
+        if (entry.type === "directory")
+            fs.mkdirTree(entry.path);
+        else {
+            fs.mkdirTree(entry.path.slice(0, entry.path.lastIndexOf("/")) || "/");
+            fs.writeFile(entry.path, decodeBase64(entry.content ?? ""));
+        }
+    }
+    for (const source of entries) {
+        const entry = source;
+        if (entry.path !== PYTHON_WORKSPACE && !entry.path.startsWith(`${PYTHON_WORKSPACE}/`))
+            continue;
+        if (entry.mode !== undefined)
+            fs.chmod(entry.path, entry.mode);
+        if (entry.mtimeMs !== undefined)
+            fs.utime(entry.path, entry.mtimeMs, entry.mtimeMs);
+    }
+}
+export function snapshotPythonFilesystem(fs, original) {
+    const retained = original.files.filter((entry) => entry.path !== PYTHON_WORKSPACE
+        && !entry.path.startsWith(`${PYTHON_WORKSPACE}/`));
+    const files = [...retained];
+    walk(fs, PYTHON_WORKSPACE, files);
+    return { files };
+}
+export function absolutePythonPath(path, cwd) {
+    const source = path.startsWith("/") ? path : `${cwd}/${path}`;
+    const parts = [];
+    for (const part of source.split("/")) {
+        if (!part || part === ".")
+            continue;
+        if (part === "..")
+            parts.pop();
+        else
+            parts.push(part);
+    }
+    return `/${parts.join("/")}`;
+}
+export function pythonBasename(path) { return path.slice(path.lastIndexOf("/") + 1); }
+export function encodeBase64(value) {
+    let binary = "";
+    for (let offset = 0; offset < value.byteLength; offset += 0x8000) {
+        binary += String.fromCharCode(...value.subarray(offset, offset + 0x8000));
+    }
+    return btoa(binary);
+}
+export function decodeBase64(value) {
+    const binary = atob(value);
+    return Uint8Array.from(binary, (character) => character.charCodeAt(0));
+}
+function walk(fs, path, files) {
+    const stat = fs.stat(path);
+    const metadata = pythonMetadata(stat);
+    files.push({ path, type: "directory", ...metadata });
+    for (const name of fs.readdir(path)) {
+        if (name === "." || name === "..")
+            continue;
+        const child = `${path}/${name}`;
+        const childStat = fs.stat(child);
+        if ((childStat.mode & 0o170000) === 0o040000)
+            walk(fs, child, files);
+        else
+            files.push({ path: child, type: "file", content: encodeBase64(fs.readFile(child)), ...pythonMetadata(childStat) });
+    }
+}
+function clearTree(fs, path) {
+    if (!fs.analyzePath(path).exists)
+        return;
+    for (const name of fs.readdir(path)) {
+        if (name === "." || name === "..")
+            continue;
+        const child = `${path}/${name}`;
+        if ((fs.stat(child).mode & 0o170000) === 0o040000) {
+            clearTree(fs, child);
+            fs.rmdir(child);
+        }
+        else
+            fs.unlink(child);
+    }
+}
+function depth(path) { return path.split("/").length; }
+function pythonMetadata(stat) {
+    const mtimeMs = stat.mtime instanceof Date ? stat.mtime.getTime() : stat.mtime;
+    return {
+        mode: stat.mode & 0o7777,
+        ...(typeof mtimeMs === "number" && Number.isFinite(mtimeMs) ? { mtimeMs } : {}),
+    };
+}
+//# sourceMappingURL=filesystem.js.map